Chapter 13: Procedure Division - ENTER - INVOKE

13.1 The ENTER Statement

The ENTER statement provides a means of allowing the use of more than one language in the same program.

The ENTER statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

All dialects in this COBOL implementation support this syntax for documentation purposes only. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

Although it is a part of the standard COBOL definition, this feature is explicitly excluded from the X/Open COBOL language definitions and should not be used in an X/Open COBOL conforming source program.

General Format

Syntax Rules

  1. Language-name and routine-name can be any user-defined word or alphanumeric literal.

General Rules

  1. This statement is treated as for documentation purposes only. Access to other languages can be achieved by means of the CALL statement.

13.2 The ENTRY Statement

The ENTRY statement establishes an alternate entry point into a called COBOL program.

General Formats

Format 1

Format 2

Directives

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

Syntax Rules

All Formats
  1. The ENTRY statement cannot be used in a program that is nested within another program.

  2. Literal-1 must be non-numeric and must not be a figurative constant. In some environments, only the first 8 characters are significant.

Format 1
  1. Format 1 must be specified only within program definitions.

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

  3. 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 can be of any class, but the length must be no greater than 8 bytes.

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

All Formats
  1. The content of literal-1 gives the entry-name, a name which identifies an entry point into the program that is an alternative to the default COBOL entry point at the start of the PROCEDURE DIVISION. The program-name given in the PROGRAM-ID paragraph can be considered to identify the default COBOL entry point.

    Note that program files containing executable COBOL code typically have names that are essentially the same as the program-name. When a CALL is made and the program-name or entry-name is not already loaded into memory, program files are located by filename but can appear to be located by program-name. In such circumstances, a CALL that references a program-name may succeed but a CALL that references an entry-name may fail.

    The entry-name is largely equivalent to a program-name and the two are subject to common rules for formation of the name as indicated in the section The Program-ID Paragraph and Nested Source Programs. Literal-1 corresponds to literal-1 of the general format for the PROGRAM-ID paragraph.

  2. When the calling program invokes the called program by a CALL statement naming the entry-name given by literal-1, control is transferred to the next executable statement following the ENTRY statement.

  3. Data items that are declared in the Linkage Section but are not declared in the USING phrase of the ENTRY statement can only be referenced if they have been linked to a data item by executing a SET statement or if the STICKY-LINKAGE Compiler directive is used.

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

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

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

  3. The USING phrase identifies the names of the formal parameters used by the program or for any arguments passed to it. The arguments passed to it are identified in the activating source element by the USING phrase of a CALL statement. The correspondence between the two lists of names is established on a positional basis.

  4. If the argument is passed by content, the called program operates as if the record in the linkage section were allocated by the calling runtime element during the process of initiating the call and as if this record does not occupy the same storage area as the argument in the calling 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 called program as if it were the argument and as if it were passed by reference.

  5. If the argument is passed by reference, the called program operates as if the formal parameter occupies the same storage area as the argument.

  6. If the argument is passed by value, the called program operates as if the record in the linkage section were allocated by the calling runtime element during the process of initiating the call and as if this record does not occupy the same storage area as the argument in the calling 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 called program as if it were the argument and as if it were passed by reference.

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

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

13.3 The EVALUATE Statement

The EVALUATE statement describes a multi-branch, multi-join structure. It can cause multiple conditions to be evaluated. The subsequent action of the runtime element depends on the results of these evaluations.

General Format

Syntax Rules

  1. The operands or the words TRUE and FALSE which appear before the first WHEN phrase of the EVALUATE statement are referred to individually as selection subjects and collectively, for all those specified, as the set of selection subjects.

  2. The operands or the words TRUE, FALSE, and ANY which appear in a WHEN phrase of an EVALUATE statement are referred to individually as selection objects and collectively, for all those specified in a single WHEN phrase, as the set of selection objects.

  3. The words THROUGH and THRU are equivalent.

  4. Two operands connected by a THROUGH phrase must be of the same class. The two operands thus connected constitute a single selection object.

  5. The number of selection objects in each set of selection objects must be equal to the number of selection subjects.

  6. Each selection object in a set of selection objects must correspond to the selection subject having the same ordinal position in the set of selection subjects according to the following rules:

    1. Identifiers, literals, or arithmetic expressions appearing in a selection object must be valid operands for comparison to the corresponding operand in the set of selection subjects. (See the section Relation Condition earlier in this chapter.)

    2. Condition-1, condition-2, or the words TRUE or FALSE appearing as a selection object must correspond to a conditional expression or the words TRUE or FALSE in the set of selection subjects.

    3. The word ANY can correspond to a selection subject of any type.

    4. Where identifiers are permitted, they can reference floating-point data items.

    5. Where numeric literals are permitted, floating-point literals are permitted.

    6. Where identifiers are permitted, they can reference pointer data items.

  7. If partial-expression-1 or partial-expression-2 is specified as a selection object, it must correspond to a selection subject that is an identifier, a literal or an arithmetic expression. Partial-expression-1 and partial-expression-2 must be a sequence of COBOL words which, when following the corresponding selection subject, make the resultant text a valid conditional expression.

General Rules

  1. The execution of the EVALUATE statement operates as if each selection subject and selection object were evaluated and assigned a numeric or nonnumeric value, a range of numeric or nonnumeric values, or a truth value. These values are determined as follows:

    1. Any selection subject specified by identifier-1, identifier-2, and any selection object specified by identifier-3, identifier-5, without either the NOT or the THROUGH phrases, are assigned the value and class of the data item referenced by the identifier.

    2. Any selection subject specified by literal-1, literal-2, and any selection object specified by literal-3, literal-5, without either the NOT or the THROUGH phrases, are assigned the value and class of the specified literal. If literal-3, literal-5, is the figurative constant ZERO, it is assigned the class of the corresponding selection subject.

    3. Any selection subject in which expression-1, expression-2, is specified as an arithmetic expression and any selection object, without either the NOT or the THROUGH phrases, in which arithmetic-expression-1, arithmetic-expression-3, is specified are assigned a numeric value according to the rules for evaluating an arithmetic expression. (See the section Arithmetic Expressions earlier in this chapter.)

    4. Any selection subject in which expression-1, expression-2 is specified as a conditional expression and any selection object in which condition-1, condition-2, is specified are assigned a truth value according to the rules for evaluating conditional expressions. (See the section Conditional Expressions earlier in this chapter.)

    5. Any selection subject or any selection object specified by the words TRUE or FALSE is assigned a truth value. The truth value "true" is assigned to those items specified with the word TRUE, and the truth value "false" is assigned to those items specified with the word FALSE.

    6. Any selection object specified by the word ANY is not further evaluated.

    7. If the THROUGH phrase is specified for a selection object, without the NOT phrase, the range of values is all values which, when compared to the selection subject, are greater than or equal to the first operand and less than or equal to the second operand according to the rules for comparison. (See the section Relation Condition in this chapter.) If the first operand is greater than the second operand, no values are in the range.

    8. If the NOT phrase is specified for a selection object, the values assigned to that item are all values not equal to the value, or range of values, which would have been assigned to the item had the NOT phrase not been specified.

  2. The execution of the EVALUATE statement then proceeds as if the values assigned to the selection subjects and selection objects were compared to determine if any WHEN phrase satisfies the set of selection subjects. This comparison proceeds as follows:

    1. Each selection object in the set of selection objects for the first WHEN phrase is compared to the selection subject having the same ordinal position in the set of selection subjects.

      1. If the items being compared are assigned numeric or nonnumeric values, or a range of numeric or nonnumeric values, the comparison is satisfied if the value, or one of the range of values, assigned to the selection object is equal to the value assigned to the selection subject according to the rules for comparison. (See the section Relation Condition in this chapter.)
      2. If the items being compared are assigned truth values, the comparison is satisfied if the items are assigned the identical truth value.
      3. If the selection object being compared is specified by the word ANY, the comparison is always satisfied regardless of the value of the selection subject.

    2. If the above comparison is satisfied for every selection object in the set of selection objects being compared, the WHEN phrase containing that set of selection objects is selected as the one satisfying the set of selection subjects.

    3. If the above comparison is not satisfied for one or more selection objects in the set of selection objects being compared, that set of selection objects does not satisfy the set of selection subjects.

    4. This procedure is repeated for subsequent sets of selection objects, in the order of their appearance in the source element, until either a WHEN phrase satisfying the set of selection subjects is selected or until all sets of selection objects are exhausted.

  3. After the comparison operation is completed, execution of the EVALUATE statement proceeds as follows:

    1. If a WHEN phrase is selected, execution continues with the first imperative-statement-1 following the selected WHEN phrase.

    2. If no WHEN phrase is selected and a WHEN OTHER phrase is specified, execution continues with imperative-statement-2.

    3. The scope of execution of the EVALUATE statement is terminated when execution reaches the end of the scope of the selected WHEN phrase or WHEN OTHER phrase or when no WHEN phrase is selected and no WHEN OTHER phrase is specified. (See the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)

  4. If the selection object is specified by partial-expression-1 or partial-expression-2, the corresponding selection subject is considered to be the word TRUE. The selection object is considered to be condition-1 or condition-2 respectively, where condition-1 or condition-2 is the conditional expression resulting from partial expression-1 or partial-expression-2 following the original corresponding selection-subject-1 or selection-subject-2 respectively.

13.4 The EXAMINE Statement

The EXAMINE statement replaces or counts the number of occurrences of a given character in a data item.

General Formats

Format 1

Format 2

Syntax Rules

All Formats
  1. The identifier must be described, explicitly or implicitly, as USAGE IS DISPLAY.

  2. Each literal must consist of a single character. If identifier is a numeric item, the literals must be numeric literals, nonnumeric literals whose value is a single numeric digit, or the figurative constant ZERO. If identifier belongs to any other class, then the literals can be numeric or nonnumeric, or any figurative constant without the word ALL.

General Rules

All Formats
  1. Examination proceeds as follows:

    1. For nonnumeric data items, examination starts at the leftmost character and proceeds to the right. Each character in the data item specified by the identifier is examined in turn.

    2. If a data item referred to by the EXAMINE statement is numeric, it must consist of numeric characters and can possess an operational sign. Examination starts at the leftmost character (excluding the sign) and proceeds to the right. Each character except the sign is examined in turn. Regardless of where the sign is physically located, it is completely ignored by the EXAMINE statement.

  2. The TALLYING option creates an integral count which replaces the value of a spe cial register called TALLY. The count represents the number of:

    1. Characters not equal to literal-1 encountered before the first occurrence of literal-1 when the UNTIL FIRST option is used.

    2. Occurrences of literal-1 when the ALL option is used.

    3. Occurrences of literal-1 prior to encountering a character other than literal-1 when the LEADING option is used.

  3. When either of the REPLACING options is used, the replacement rules are as follows:

    1. When the ALL option is used, then literal-2 is substituted for each occurrence of literal-1.

    2. When the LEADING option is used, the substitution of literal-2 terminates as soon as a character other than literal-1 or when the right-hand boundary of the data item is encountered.

    3. When the FIRST option is used, the first occurrence of literal-1 is replaced by literal-2.

    4. When the UNTIL FIRST option is used, the substitution of literal-2 terminates as soon as literal-1 or the right-hand boundary of the data item is encountered.

13.5 The EXEC(UTE) Statement

The EXEC(UTE) statement is provided as a linkage mechanism to allow control to be passed to non-COBOL subsystems.

General Format

Syntax Rules

  1. Text-data can be any textual data not containing the string END-EXEC.

General Rules

  1. The statement will be compiled as a CALL "text-name" USING text-data-buffer statement (see the section The CALL Statement earlier in this chapter), where text-data-buffer contains all the text-data from the EXEC statement (space compressed) for further parsing by the CALLed program text-name.

    This means that the called subprogram (text-name) will be passed a text string which includes the entire COBOL statement beginning with the EXEC(UTE) verb and ending with the END-EXEC phrase. The called program must parse and then process all of the included information.

    If an identifier-name is included in text-data, then it is the name of the identifier, not the value of the data in the identifier that is passed to the subprogram.

  2. The special case EXEC SQL is normally treated differently by the compiler. If you wish EXEC SQL statements to be treated as described here you must ensure that the Compiler directive NOSQL is explicitly set.

13.6 The EXHIBIT Statement

The EXHIBIT statement causes an (optionally conditional) display of the literals, and/or identifiers (optionally preceded by the identifier name) specified in the statement.

General Format

Syntax Rules

  1. Each identifier specified in the EXHIBIT statement can be any class of data. TALLY and RETURN-CODE are the only special registers that can be used as identifiers.

  2. CHANGED and NAMED can both be omitted.

General Rules

  1. Literals and identifiers displayed by the EXHIBIT statement are separated by a space on the displayed line.

  2. Each literal can be any figurative constant other than ALL.

  3. If the literal is numeric, it must be an unsigned integer.

  4. Each execution of an EXHIBIT NAMED statement displays each identifier or literal specified, with each identifier (including any qualifiers and subscripts) followed by an "=" (equal sign) and its current value. They all appear on a single line in the order in which they appear in the statement.

  5. Each execution of an EXHIBIT CHANGED NAMED statement displays each identifier or literal specified, with each identifier (including any qualifiers and subscripts) followed by an "=" (equal sign) and its current value. They all appear on a single line in the order in which they appear in the statement. However, the display for each identifier (name and value) is conditional on the value of that identifier having changed since the last execution of the current EXHIBIT statement. If one or more of the identifier values have not changed, neither the name nor the value is printed for those identifiers. If none of the identifier values has changed, and no literals are specified, no display takes place (display of a blank line is suppressed).

  6. Each execution of an EXHIBIT CHANGED statement displays the current value of each identifier or literal specified. They all appear on a single line in the order in which they appear in the statement. However, the value display for each identifier is conditional on the value of that identifier having changed since the last execution of the current EXHIBIT statement. If one or more of the identifier values have not changed, the value for those identifiers is not printed; spaces are inserted instead. If none of the identifier values has changed, and no literals are specified, a blank line is displayed (display of a blank line is not suppressed).

  7. Each execution of an EXHIBIT statement with neither the CHANGED nor the NAMED option displays each identifier or literal specified. They all appear on a single line in the order in which they appear in the statement.

13.7 The EXIT Statement

The EXIT statement provides a common end point for a series of procedures.

The EXIT statement can also exit an inline PERFORM, a paragraph or a section.

The EXIT PROGRAM statement marks the logical end of a called program.

You can also return values to activating runtime elements written in any language.

The EXIT METHOD statement marks the logical end of an invoked method.

The EXIT FUNCTION statement marks the logical end of the execution of a function.

General Formats

Format 1

Format 2

Format 3

Format 4

Format 5

Format 6

Syntax Rules

Format 1
  1. The EXIT statement should appear in a sentence by itself.

    This rule is not enforced.

  2. The EXIT sentence should be the only sentence in the paragraph.

    This rule is not enforced.

Format 2
  1. A Format 2 EXIT statement can be used only within an inline PERFORM.

Format 4
  1. If an EXIT PROGRAM statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.

    This rule is not enforced.

  2. There must be no sentence other than the EXIT PROGRAM sentence in the paragraph.

    This rule is not enforced.

  3. Integer-1 may be signed.

  4. GIVING and RETURNING are equivalent.

  5. If the ADDRESS OF clause is not specified, identifier-1 must be no larger than 8 bytes in size.
Format 5
  1. An EXIT METHOD statement may be specified only in a method procedure division.

Format 6
  1. An EXIT FUNCTION statement must be specified only in a function procedure division.

Formats 4, 5 and 6
  1. The EXIT statement must not be specified in a declarative procedure for which the GLOBAL phrase is specified in the associated USE statement.

General Rules

Format 1
  1. An EXIT statement serves only to enable the user to assign a procedure-name to a given point in a procedure division. Such an EXIT statement has no other effect on the compilation or execution .
Format 2
  1. The execution of an EXIT PERFORM statement without a CYCLE phrase causes control to be passed to an implicit CONTINUE statement, immediately following the END-PERFORM associated with the nearest inline PERFORM statement.

  2. The execution of an EXIT PERFORM statement with a CYCLE phrase causes control to be passed to an implicit CONTINUE statement, immediately preceding the END-PERFORM associated with the nearest inline PERFORM statement.

Format 3
  1. The execution of a Format 3 EXIT statement with the PARAGRAPH phrase causes control to pass to an implicit CONTINUE statement immediately following the last statement in the paragraph.

  2. The execution of a Format 3 EXIT statement with the SECTION phrase causes control to pass to an implicit CONTINUE statement immediately following the last statement in the last paragraph in the section.

Format 4
  1. If the EXIT PROGRAM statement is executed in a program which is not under the control of a calling runtime element, the EXIT PROGRAM statement causes execution of the program to continue with the next executable statement.

  2. The execution of an EXIT PROGRAM statement in a called program which does not possess the initial attribute causes execution to continue with the next executable statement following the CALL statement in the calling runtime element. The state of the calling runtime element is not altered and is identical to that which existed at the time it executed the CALL statement except that the contents of data items and the contents of data files shared between the calling and called runtime elements may have been changed. The program state of the called program is not altered except that the ends of the ranges of all PERFORM statements executed by that called program are considered to have been reached.

  3. Besides the actions specified in General Rule 7, the execution of an EXIT PROGRAM statement in a called program which possesses the initial attribute is equivalent to also executing a CANCEL statement referencing that program except that the statement will not free any memory. See the section The CANCEL Statement earlier in this chapter.

  4. An EXIT PROGRAM statement must not be executed while executing a declarative procedure in which the GLOBAL phrase is specified except in a program called while executing that declarative procedure.

  5. Execution of an EXIT PROGRAM statement in a program that is under the control of a calling runtime element, causes a return value to be set in the system area generally available for non-COBOL programs to return a value. This system area is never smaller than 4 bytes in size but may be larger in some environments.

    If the GIVING phrase is not specified and the calling convention specifies updating the RETURN-CODE special-register (see the CALL CONVENTION clause in the earlier section The Special-Names Paragraph) then the object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and with a size determined by the operating environment external to the COBOL system and as if a MOVE statement had been executed with the RETURN-CODE as the sending item and the system area as the receiving item. (See the section Special Registers in the chapter Concepts of the COBOL Language for details of RETURN-CODE.)

    If the GIVING ADDRESS OF phrase is specified, the object program operates as if the system area were declared as a COBOL data item with USAGE POINTER and as if a SET statement had been executed with TO ADDRESS OF identifier-1 as the first operand and the system area as the second operand. The ADDRESS OF phrase may be used to indirectly pass a value that is larger than the system area.

    If the GIVING identifier-1 phrase is specified, identifier-1 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is expected by the calling runtime element. The object program operates as if a MOVE statement had been executed with identifier-1 as the sending item and the system area as the receiving item.

    If the GIVING integer-1 phrase is specified, integer-1 must not be larger than the value that can be held in the system area. The object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and with a size determined by the operating environment external to the COBOL system and as if a MOVE statement had been executed with integer-1 as the sending item and the system area as the receiving item.

Format 5
  1. The execution of an EXIT METHOD statement causes the executing method to terminate, and control to return to the invoking statement. If a RETURNING phrase is present in the containing method definition, the value in the data item referenced by the RETURNING phrase becomes the result of the method invocation.
Format 6
  1. The execution of an EXIT FUNCTION causes the executing function to terminate, and control to return to hte activating statement. The value in the data item referenced by the RETURNING phrase in the containing function definition becomes the result of the function activation.

13.8 The GOBACK Statement

The GOBACK statement marks the logical end of a called program.

You can also return values to calling runtime elements written in any language or to the operating system environment.

General Format

Syntax Rules

  1. If a GOBACK statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.

    This rule is not enforced, although any statements in the sentence that follow the GOBACK statement will not be executed.

  2. GIVING and RETURNING are equivalent.

  3. If the ADDRESS OF clause is not specified, the data item referenced by identifier-1 must be no larger than 8 bytes in size.

  4. Integer-1 may be signed.

General Rules

  1. If a GOBACK statement is executed in a program which is under the control of a calling runtime element, the object program operates as if executing an EXIT PROGRAM statement that has the same clauses as the GOBACK statement. See the section The EXIT Statement.

  2. If a GOBACK statement without the ADDRESS OF clause is executed in a program which is not under the control of a calling runtime element, the object program operates as if executing a STOP RUN statement that has the same clauses as the GOBACK statement.

  3. If a GOBACK statement with the ADDRESS OF clause is executed in a program which is not under the control of a calling runtime element, the object program operates as if executing a STOP RUN statement except that an arbitrary returned value is set in the system area. The GOBACK statement may result in more compact code than the equivalent EXIT PROGRAM and STOP RUN statement.

  4. A GOBACK statement must not be executed while executing a declarative procedure in which the GLOBAL phrase is specified except in a program called while executing that declarative procedure.

13.9 The GO TO Statement

The GO TO statement causes control to be transferred from one part of the Procedure Division to another.

The option of omitting procedure-name-1 in a Format 1 GO TO statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

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

Although it is a part of the standard COBOL definition, omitting the procedure-name in Format 1 is explicitly excluded from the X/Open COBOL language definitions and should not be used in an X/Open COBOL conforming source program.

General Formats

Format 1

Format 2

Syntax Rules

All Formats
  1. Identifier is the name of a numeric elementary item which is an integer.

  2. When a paragraph is referenced by an ALTER statement, that paragraph can consist only of a paragraph header followed by a Format 1 GO TO statement.
Format 1
  1. A Format 1 GO TO statement, without procedure-name-1, can only appear in a single statement paragraph.

    This restriction is not enforced.

  2. If a Format 1 GO TO statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.
Format 2
  1. In Format 2, at least two procedure-names should be specified.

    A Format 2 statement can be written with only one procedure name.

General Rules

All Formats
  1. If procedure-name-1 is not specified in Format 1, an ALTER statement, referring to this GO TO statement, must be executed prior to the execution of this GO TO statement.

    If an ALTER statement referring to the paragraph containing this GO TO statement has not been executed before this GO TO statement is executed, this GO TO statement is treated like a CONTINUE statement.

Format 1
  1. When a GO TO statement represented by Format 1 is executed, control is transferred to procedure-name-1 or to another procedure-name if the GO TO statement has been modified by an ALTER statement.
Format 2
  1. When a GO TO statement represented by Format 2 is executed, control is transferred to procedure-name-1, procedure-name-2, and so on, depending on the value of the identifier being 1, 2, ..., n. If the value of the identifier is anything other than the positive or unsigned integers 1, 2, ..., n, then no transfer occurs and control passes to the next statement in the normal sequence for execution.

13.10 The IF Statement

The IF statement causes a condition to be evaluated (see the section Conditional Expressions earlier in this chapter). The subsequent action of the runtime element depends on whether the value of the condition is true or false.

General Format

Syntax Rules

  1. Statement-1 and statement-2 represent either an imperative statement or a conditional statement optionally preceded by an imperative statement.

  2. If the END-IF phrase is specified, the NEXT SENTENCE phrase must not be specified.

    NEXT SENTENCE can be specified with END-IF.

    If the NEXT SENTENCE phrase is executed, control will not pass to the next statement following the END-IF, but instead will pass to the statement after the closest following period.

General Rules

  1. The scope of an IF statement can be terminated by any of the following:

    1. An END-IF phrase at the same level of nesting.

    2. A separator period.

    3. If nested, by an ELSE phrase associated with an IF statement at a higher level of nesting.

  2. When an IF statement is executed, the following transfers of control occur:

    1. If the condition is true, statement-1 is executed if specified. If statement-1 contains a procedure branching or conditional statement, control is explicitly transferred in accordance with the rules of that statement. If statement-1 does not contain a procedure branching or conditional statement, the ELSE phrase, if specified, is ignored and control passes to the end of the IF statement.

    2. If the condition is true and the NEXT SENTENCE phrase is specified instead of statement-1, the ELSE phrase, if specified, is ignored and control passes to the next executable sentence.

    3. If the condition is false, statement-1 or its surrogate NEXT SENTENCE is ignored, and statement-2, if specified, is executed. If statement-2 contains a procedure branching or conditional statement, control is explicitly transferred in accordance with the rules of that statement. If statement-2 does not contain a procedure branching or conditional statement, control passes to the end of the IF statement. If the ELSE statement-2 phrase is not specified, statement-1 is ignored and control passes to the end of the IF statement.

    4. If the condition is false, and the ELSE NEXT SENTENCE phrase is specified, statement-1 is ignored, if specified, and control passes to the next executable sentence.

  3. Statement-1 and/or statement-2 can contain an IF statement. In this case the IF statement is said to be nested.

    IF statements within IF statements are considered matched IF, ELSE, and END-IF ordered combinations, proceeding from left to right. Thus, any ELSE encountered is matched with the nearest preceding IF that has not been already matched with an ELSE or has not been implicitly or explicitly terminated. Any END-IF encountered is matched with the nearest preceding IF that has not been implicitly or explicitly terminated.

13.11 The INITIALIZE Statement

The INITIALIZE statement provides the ability to set selected types of data fields to predetermined values; for example, numeric data to zeros or alphanumeric data to spaces.

General Format

Syntax Rules

  1. Literal-1 and the data item referenced by identifier-2 represent the sending area; the data item referenced by identifier-1 represents the receiving area.

  2. Each category stated in the REPLACING phrase must be a permissible category as a receiving operand in a MOVE statement where the corresponding data item referenced by identifier-2 or literal-1 is used as the sending operand. (See the section The MOVE Statement later in this chapter.)

  3. The same category cannot be repeated in a REPLACING phrase.

  4. The description of the data item referenced by identifier-1 or any items subordinate to identifier-1 can not contain the DEPENDING phrase of the OCCURS clause.

    The data item referenced by identifier-1 cannot be variably located, that is, it cannot follow in the same record description an item containing the DEPENDING phrase of the OCCURS clause unless identifier-1 is subordinate to that item with the OCCURS clause.

    The data item referenced by identifier-1 can be variably located.

  5. An index data item can not appear as an operand of an INITIALIZE statement.

  6. The data description entry for the data item referenced by identifier-1 must not contain a RENAMES clause.

  7. A floating-point data item or literal can be used anywhere a numeric identifier or literal can be specified.

  8. NATIONAL and NATIONAL-EDITED fields can only be initialized with national character values.

General Rules

  1. The key word following the word REPLACING corresponds to a category of data as defined elsewhere in this document. (See the section Concepts Of Classes Of Data in the chapter Concepts of the COBOL Language.)

  2. Whether identifier-1 references an elementary item or a group item, all operations are performed as if a series of MOVE statements had been written, each of which has an elementary item as its receiving field, subject to the following rules:

    If the REPLACING phrase is specified:

    1. If identifier-1 references a group item, any elementary item in the data item referenced by identifier-1 is initialized only if it belongs to the category specified in the REPLACING phrase.

    2. If identifier-1 references an elementary item, that item is initialized only if it belongs to the category specified in the REPLACING phrase.

    This initialization takes place as follows: the data item referenced by identifier-2 or literal-1 acts as the sending operand in an implicit MOVE statement to the identified item.

    All such elementary receiving fields, including all occurrences of table items in the group, are affected; the only exceptions are those fields specified in General Rules 3 and 4.

  3. Index

    and pointer

    data items and elementary FILLER data items are not affected by the execution of an INITIALIZE statement.

  4. Any item that is subordinate to a receiving area identifier and which contains the REDEFINES clause or any item that is subordinate to such an item is excluded from this operation. However, a receiving area identifier can itself have a REDEFINES clause or be subordinate to a data item with a REDEFINES clause.

  5. When the statement is written without the REPLACING phrase, data items of the categories alphabetic, alphanumeric, and alphanumeric edited are set to spaces; data items of the categories numeric

    , external floating-point

    and numeric edited are set to zeros

    ; data items of the categories national and national-edited are set to national-edited spaces.

    In this case, the operation is as if each affected data item is the receiving area an elementary MOVE statement with the indicated source literal (that is, spaces or zeros).

  6. In all cases, the content of the data item referenced by identifier-1 is set to the indicated value in the order (left to right) of the appearance of identifier-1 in the INITIALIZE statement. Within this sequence, where identifier-1 references a group item, affected elementary items are initialized in the sequence of their definition in the group.

  7. If identifier-1 occupies the same storage area as identifier-2, the result of the execution of this statement is undefined, even if they are defined by the same data description entry. (See the section Overlapping Operands earlier in this chapter.)

  8. NATIONAL and NATIONAL-EDITED fields can be initialized with national character values.

13.12 The INSPECT Statement

The INSPECT statement provides the ability to tally (Format 1), replace (Format 2), tally and replace (Format 3) 

or convert (Format 4)

occurrences of single characters or group of characters in a data item.

Examples

  1. Examples of using INSPECT TALLYING, REPLACING, and CONVERTING are provided in the Examples chapter in your Language Reference - Additional Topics.

General Formats

Format 1

Format 2

Format 3

Format 4

Syntax Rules

All Formats
  1. Identifier-1 must reference either a group item or any category of elementary item, described (either implicitly or explicitly) as USAGE IS DISPLAY.

  2. Identifier-3 ... identifier-n must reference

    either a group item or

    an elementary alphabetic, alphanumeric,

    alphanumeric edited, numeric edited

    or numeric item described (either implicitly or explicitly) as USAGE IS DISPLAY.

  3. Each literal must be nonnumeric and can be any figurative constant, except ALL. If literal-1, literal-2 or literal-4 is a figurative constant, it refers to an implicit one character data item.

  4. No more than one BEFORE phrase

    and /;

    or one AFTER phrase can be specified for any one ALL, LEADING, CHARACTERS, FIRST

    or CONVERTING

    phrase.

  5. Literal-1, literal-2, literal-3, literal-4, and literal-5, and the data items referenced by identifier-3, identifier-4, identifier-5, identifier-6, and identifier-7 can be any number of characters in length up to the limit allowed for literals or data items.

  6. All identifiers, except identifier-2 (the TALLYING field), can be external floating-point items. External floating-point items are treated as if redefined as alphanumeric with the INSPECT statement referring to the alphanumeric item.
Formats 1 and 3
  1. Identifier-2 must reference an elementary numeric data item.

Formats 2 and 3
  1. The size of the data referenced by literal-3 or identifier-5 must be equal to the size of the data referenced by literal-1 or identifier-3. When a figurative constant is used as literal-3, the size of the figurative constant is equal to the size of literal-1 or the size of the data item referenced by identifier-3.

  2. When the CHARACTERS phrase is used, literal-3 or the size of the data item referenced by identifier-5 must be one character in length.

    This restriction does not apply to literal-2 or identifier-4.

Format 4
  1. The size of literal-5 or the data item referenced by identifier-7 must be equal to the size of literal-4 or the data item referenced by identifier-6. When a figurative constant is used as literal-5, the size of the figurative constant is equal to the size of literal-4 or the size of the data item referenced by identifier-6.

  2. The same character must not appear more than once either in literal-4 or in the data item referenced by identifier-6.

General Rules

All Formats
  1. For the purpose of determining its length, identifier-1 is treated as if it were a sending data item. (See the section The OCCURS clause in this chapter.)

  2. Inspection (which includes the comparison cycle, the establishment of boundaries for the BEFORE or AFTER phrase, and the mechanism for tallying and/or replacing) begins at the leftmost character position of the data item referenced by identifier-1, regardless of its class, and proceeds from left to right to the rightmost character position as described in General Rules 11, 12 and 13.

  3. For use in the INSPECT statement, the contents of the data item referenced by identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 will be treated as follows:

    1. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as alphanumeric, the INSPECT statement treats the contents of each such identifier as a character-string.

    2. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as alphanumeric edited, numeric edited or unsigned numeric, the data item is inspected as though it had been redefined as alphanumeric (see General Rule 3a.) and the INSPECT statement had been written to reference the redefined data item.

    3. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as signed numeric, the data item is inspected as though it had been moved to an unsigned numeric data item with length equal to the length of the signed item excluding any separate sign position and then the rules in General Rule 3b had been applied. (See the section The MOVE Statement later in this chapter.)

  4. In General Rules 6 through 19, all references to literal-1, literal-2, literal-3, literal-4, and literal-5 apply equally to the contents of the data item referenced by identifier-3, identifier-4, identifier-5, identifier-6, and identifier-7, respectively.

  5. If any identifier is subscripted

    or is a function-identifier

    , the subscript

    or function-identifie

    is evaluated only once as the first operation in the execution of the INSPECT statement.

Format 1
  1. Identifier-1 is a sending data item.

  2. The required words ALL and LEADING are adjectives that apply to each succeeding literal-1 until the next adjective appears.

  3. The contents of the data item referenced by identifier-2 are not initialized by the execution of the INSPECT statement.

  4. The rules for tallying are as follows:

    1. If the ALL phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for each occurrence of literal-1 matched in the contents of the data item referenced by identifier-1.

    2. If the LEADING phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for the first and each subsequent contiguous occurrence of literal-1 matched in the contents of the data item referenced by identifier-1, provided that the leftmost such occurrence is at the point where comparison began in the first comparison cycle in which literal-1 was eligible to participate.

    3. If the CHARACTERS phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for each character matched, in the sense of Format 1 and 2, General Rule 12e, in the contents of the data item referenced by identifier-1.

  5. If identifier-1, identifier-3 or identifier-4 occupies the same storage area as identifier-2, the result of the execution of this statement is undefined, even if they are defined by the same data description entry. (See the section Overlapping Operands earlier in this chapter.)

Formats 1 and 2
  1. During inspection of the contents of the data item referenced by identifier-1, each properly matched occurrence of literal-1 is tallied (Format 1) or replaced by literal-3 (Format 2).

  2. The comparison operation to determine the occurrences of literal-1 to be tallied or to be replaced, occurs as follows:

    1. The operands of the TALLYING or REPLACING phrases are considered in the order they are specified in the INSPECT statement from left to right. The first literal-1 is compared to an equal number of contiguous characters, starting with the leftmost character position in the data item referenced by identifier-1. Literal-1 matches that portion of the contents of the data item referenced by identifier-1 if, and only if, they are equal, character for character, and:

      1. If neither LEADING nor FIRST is specified, or:

      2. If the LEADING adjective applies to literal-1 and literal-1 is a leading occurrence as defined in General Rules 9 and 15, or:

      3. If the FIRST adjective applies to literal-1 and literal-1 is the first occurrence as defined in General Rule 9.

    2. If no match occurs in the comparison of the first literal-1, the comparison is repeated with each successive literal-1, if any, until either a match is found or there is no next successive literal-1. When there is no next successive literal-1, the character position in the data item referenced by identifier-1 immediately to the right of the leftmost character position considered in the last comparison cycle is considered as the leftmost character position, and the comparison cycle begins again with the first literal-1.

    3. Whenever a match occurs, tallying and/or replacing takes place as described in General Rules 9 and 15. The character position in the data item referenced by identifier-1 immediately to the right of the rightmost character position that participated in the match is now considered to be the leftmost character position of the data item referenced by identifier-1, and the comparison cycle starts again with the first literal-1.

    4. The comparison operation continues until the rightmost character position of the data item referenced by identifier-1 has participated in a match or has been considered as the leftmost character position. When this occurs, inspection is terminated.

    5. If the CHARACTERS phrase is specified, an implied one character operand participates in the cycle described in paragraphs 12a through 12d above, except that no comparison to the contents of the data item referenced by identifier-1 takes place. This implied character is considered always to match the leftmost character of the contents of the data item referenced by identifier-1 participating in the current comparison cycle.

  3. The comparison operation defined in General Rule 12 is affected by the BEFORE and AFTER phrases as follows:

    1. If neither the BEFORE nor the AFTER phrase is specified, literal-1 or the implied operand of the CHARACTERS phrase is first eligible to participate in matching at the leftmost character position of identifier-1.

    2. If the BEFORE phrase is specified, the associated literal-1, or the implied operand of the CHARACTERS phrase participates only in those comparison cycles which involve that portion of the contents of the data item referenced by identifier-1 from its leftmost character position up to, but not including, the first occurrence of literal-2, in the contents of the data item referenced by identifier-1.

      The position of this first occurrence is determined before the first cycle of the comparison operation described in General Rule 12 is begun. If, on any comparison cycle, literal-1, or the implied operand of the CHARACTERS phrase is not eligible to participate, it is considered not to match the contents of the data item referenced by identifier-1. If there is no occurrence of literal-2, in the contents of the data item referenced by identifier-1, its associated literal-1, or the implied operand of the CHARACTERS phrase participates in the comparison operation as though the BEFORE phrase had not been specified.

    3. If the AFTER phrase is specified, the associated literal-1, or the implied operand of the CHARACTERS phrase can participate only in those comparison cycles which involve that portion of the contents of the data item referenced by identifier-1 from the character position immediately to the right of the rightmost character position of the first occurrence of literal-2, in the contents of the data item referenced by identifier-1 to the rightmost character position of the data item referenced by identifier-1.

      The position of this first occurrence is determined before the first cycle of the comparison operation described in General Rule 12 is begun. If, on any comparison cycle, literal-1, or the implied operand of the CHARACTERS phrase is not eligible to participate, it is considered not to match the contents of the data item referenced by identifier-1. If there is no occurrence of literal-2, in the contents of the data item referenced by identifier-1, its associated literal-1, or the implied operand of the CHARACTERS phrase is never eligible to participate in the comparison operation.

Format 2
  1. The required words ALL, LEADING and FIRST are adjectives that apply to each succeeding BY phrase until the next adjective appears.

  2. The rules for replacement are as follows:

    1. When the CHARACTERS phrase is specified, each character matched in the sense of Format 1 and 2, General Rule 12e in the contents of the data item referenced by identifier-1, is replaced by literal-3.

    2. When the adjective ALL is specified, each occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3.

    3. When the adjective LEADING is specified, the first and each subsequent contiguous occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3, provided that the leftmost occurrence is at the point where comparison began in the first comparison cycle in which literal-1 was eligible to participate.

    4. When the adjective FIRST is specified, the leftmost occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3.

  3. If identifier-3, identifier-4 or identifier-5 occupies the same storage area as identifier-1, the result of the execution of this statement is undefined, even if they are defined by the same data description entry. (See the section Overlapping Operands earlier in this chapter.)

Format 3
  1. A Format 3 INSPECT statement is interpreted and executed as though two successive INSPECT statements specifying the same identifier-1 had been written with one statement being a Format 1 statement with TALLYING phrases identical to those specified in the Format 3 statement, and the other statement being a Format 2 statement with REPLACING phrases identical to those specified in the Format 3 statement. The General Rules given for matching and counting apply to the Format 1 statement and the General Rules given for matching and replacing apply to the Format 2 statement.

Format 4
  1. A Format 4 INSPECT statement is interpreted and executed as though a Format 2 INSPECT statement specifying the same identifier-1 had been written with a series of ALL phrases, one for each character of literal-4. The effect is as if each of these ALL phrases referenced, as literal-1, a single character of literal-4 and referenced, as literal-3, the corresponding single character of literal-5. Correspondence between the characters of literal-4 and the characters of literal-5 is by ordinal position within the data item.

  2. If identifier-4, identifier-6 or identifier-7 occupies the same storage area as identifier-1, the result of the execution of this statement is undefined, even if they are defined by the same data description entry.

13.13 The INVOKE Statement

The INVOKE statement causes a method to be invoked.

General Format

Syntax Rules

  1. Object-identifier-1 must be an object reference or a class-name.

  2. Identifier-1 must be a four-byte data item.

  3. Literal-1 must be an alphanumeric literal.

  4. Neither literal-1 nor literal-2 may be a figurative constant.

  5. If object-identifier-1 references a universal object reference, neither the BY CONTENT nor BY VALUE phrase can be specified and the BY REFERENCE phrase, if not specified explicitly, is assumed implicitly.

    The BY CONTENT and BY VALUE phrases can be specified.

  6. Identifier-2 must be defined as an alphanumeric data item.

  7. If identifier-2 is specified, object-identifier-1 must be a universal object reference.

    Object-identifier-1 is not required to be a universal object reference.

  8. If the data item referenced by identifier-1 is not a universal object reference, the rules for conformance as specified in Conformance for parameters and returning items apply.

  9. If the data item referenced by identifier-1 is not a universal object reference and a BY CONTENT or BY REFERENCE phrase is specified for an argument, a BY REFERENCE phrase must be specified for the corresponding formal parameter in the procedure division header.

  10. Identifier-3 must reference a data item defined in the file, working-storage,
    object-storage,
    local-storage, or linkage section.

  11. Neither identifier-4, identifier-5, identifier-6, identifier-7, nor identifier-8 can be a function-identifier.

  12. If a BY VALUE phrase is specified for an argument, a BY VALUE phrase must be specified for the corresponding formal parameter in the procedure division header.

  13. Integer-1 may be signed or zero.

  14. GIVING and RETURNING are equivalent.

  15. Identifier-9 must be a data item no more than 8 bytes in size that is defined in the file, working-storage,
    object-storage,
    local-storage, or linkage section.

  16. Identifier-10 must be defined as a data item in the Linkage Section with a level number of 01 or 77.

  17. If the data item referenced by identifier-1 is not a universal object reference, the rules for conformance as specified in Conformance for parameters and returning items shall apply.

  18. Identifier-3 is both a sending and receiving operand.

  19. Identifier-1, identifier-2, identifier-4, identifier-5, identifier-6, identifier-7 and identifier-8 are a sending operands.

  20. Identifier-9 and identifier-10 are receiving operands.

General Rules

  1. The instance of the program, function or method that executes the INVOKE statement is the activating runtime element.

  2. Object-identifier-1 or

    identifier-1

    identifies an object instance. If object-identifier-1 is specified as a class-name, object-identifier-1 identifies the factory object of that class-name. Literal-1 or the content of the data item referenced by identifier-2 identifies a method of that object that will act upon that object instance:

    1. If the method to be invoked is a COBOL method, literal-1 or the content of the data item referenced by identifier-2 is the name of the method to be invoked as specified in its METHOD-ID paragraph..

    2. If the method to be invoked is not a COBOL method, the rules for the formation of the method-name are dependent upon the domain involved.

  3. The AS phrase enables you to invoke methods on a COBOL data item. If template-1 is specified, it is used as a class template. Creation of templates is a function provided by objects in the supplied Class Library. (See the book OO Programming with Object COBOL for details.)

  4. When an INVOKE statement is executed, the method specified is made available for execution and control is transferred to the invoked method. If the invoked method is a COBOL method, its execution is described in the general rules of The PROCEDURE DIVISION Header; otherwise, the execution is defined by the implementor of the language in which the method is written. After control is returned from the method, control is transferred to the end of the INVOKE statement.

  5. The run unit is not aware of whether an invoked method is a COBOL method or a non-COBOL method until the invoked method has been located, prior to being made available for execution. The form of the method-name cannot be used to determine whether the method is a COBOL method or not.

  6. The process of invoking a method or exiting from an invoked method does not alter the status or positioning of a file associated with any external file connector.

  7. This implementation does not maintain any synchronization between the argumenrts and the linkage section data items. That is the responsibility of the user.

    Note: The COBOL language places no restrictions on the alignment of the addresses of data items, whereas non-COBOL languages typically do make assumptions about addresses and will fail in some way if a misaligned data item is referenced. Alignment can be achieved by one or more of the following actions:

    • modifying group items to include additional filler items

    • ensuring operands in the USING phrase are level 01 or level 77 data items in conjunction with the ALIGN Compiler directive or

    • use of the SYNCHRONIZED clause in conjunction with the IBMCOMP Compiler directive

    If a RETURNING phrase is specified on the INVOKE statement, a non-COBOL method must return a result in the appropriate format.

  8. The sequence of arguments in the USING phrase of the INVOKE statement and the corresponding formal parameters in the USING phrase of the invoked method's Procedure Division header determines the correspondence between arguments and formal parameters. This correspondence is positional and not by name equivalence; the first argument corresponds to the first formal parameter, the second to the second, etc.

    If a parameter is an index-name, no such correspondence is established. Index-names in the invoked method and the invoking runtime element always refer to separate indices.

    The effect of the USING phrase on the activated runtime element is described in the general rules of The PROCEDURE DIVISION Header.

  9. The values of the parameters referenced in the USING phrase of the INVOKE statement are made available to the invoked method at the time the INVOKE statement is executed.

  10. The BY CONTENT, BY REFERENCE and BY VALUE phrases are transitive across the parameters that follow them until another BY CONTENT, BY REFERENCE or BY VALUE phrase is encountered.

    If no BY CONTENT, BY REFERENCE or BY VALUE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

  11. If the BY REFERENCE ADDRESS OF phrase is specified or implied then the method operates as if a data item had been declared with USAGE POINTER and that data item passed BY REFERENCE with a value acquired by a SET data item TO ADDRESS OF identifier-4 statement.

  12. If the BY CONTENT phrase is specified or implied for a parameter, the invoked method cannot change the value of this parameter as referenced in the INVOKE statement's USING phrase, although the invoked method can change the value of the data item referenced by the corresponding data-name in the invoked method's Procedure Division header. The data description of each parameter in the BY CONTENT phrase of the INVOKE 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.

    If the BY CONTENT phrase is specified or implied for a parameter, the object program operates as if an additional data item had been declared and this additional data item used as the parameter in a BY REFERENCE phrase. If identifier-5 is specified then both the implied data description of the additional data item and its contents are identical to that of identifier-5. If literal-3 is specified then the implied data description of the additional item is equivalent to an alphanumeric data item with the same size as literal-3 and with its contents set to the value of literal-3. If LENGTH OF identifier-6 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-6.

  13. If the BY VALUE phrase is specified or implied for a parameter, the invoked method cannot change the value of this parameter as referenced in the INVOKE statement's USING phrase, though the invoked method can change the value of the data item referenced by the corresponding data-name in the invoked method's PROCEDURE DIVISION header. The method operates, conceptually, as if an additional data item had been declared in a system area (typically the stack), available to non-COBOL languages for passing parameters and that this additional data item occupies the same storage area as the data item in the invoked method.

    If identifier-7 is specified and is BINARY, COMP-4, COMP-5 or COMP-X, then the data description of the additional data item is identical to that of identifier-7, except its usage is COMP-5. The contents of the additional data item are identical to the COMP-5 representation of the contents of identifier-7. This conversion and representation facilitates calling non-COBOL programs.

    Otherwise, if identifier-7 is specified then the implied data description of the additional data item and its contents are identical to that of identifier-7.

    If integer-1 is specified, then the data description of the additional item is equivalent to a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage indicated by the value of integer-2, if specified, or the size of the system area otherwise (typically the size of a POINTER on the system).

    If LENGTH OF identifier-8 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-8.

    If the method being invoked is a COBOL method, each parameter in the BY VALUE phrase of the INVOKE statement must have a corresponding parameter declared in the USING phrase of the PROCEDURE DIVISION header that also has the BY VALUE phrase specified or implied.

    The additional data item generated as a result of the INVOKE statement, described above, is related to this corresponding parameter in the invoked method, as follows.

    If the additional data item was subject to conversion from BINARY, COMP-4, COMP-5 or COMP-X to COMP-5, then the data description of the corresponding parameter in the invoked method must be identical to that of the data description of the additional data item with the exception that the corresponding parameter's usage can be any of BINARY, COMP-4, COMP-5 or COMP-X. On entry to the invoked COBOL method, a conversion from the USAGE COMP-5 of the additional data item to the USAGE of the corresponding parameter in the invoked method is performed.

    If the additional data item was not subject to conversion to COMP-5, the data description of each parameter in the invoked method must be the same as the corresponding additional data item. This means there is no conversion or extension or truncation, of the additional data item to match the corresponding parameter in the invoked method.

    If the method being invoked is non-COBOL, the details of when you need to use the BY VALUE phrase are dependent on the domain involved.

  14. If identifier-4 is in the Linkage Section and has a level number other than 01 or 77 or is in the Working-Storage Section, it is equivalent to passing the item BY CONTENT and the address of identifier-4 cannot be modified by the invoked method. If the BY REFERENCE literal-2 phrase is specified or implied then the method processes literal-2 as described for literal-3.

  15. If LENGTH OF identifier-6 is specified then the data description of the argument is PIC S9(9) USAGE BINARY and its content is set to the number of bytes of storage allocated to identifier-6.

  16. If integer-1 is specified then the implied data description of the argument is a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage specified by the value of integer-2, if specified, or 4 bytes otherwise.

  17. If LENGTH OF identifier-8 is specified then the data description of the argument is PIC S9(9) USAGE BINARY and its content is set to the number of bytes of storage allocated to identifier-8.

  18. If identifier-10 is specified, the invoked method must return a value with explicit or implicit USAGE POINTER. The result of the method is assigned to identifier-10 using the rules for the SET statement.

  19. Invoked methods may contain INVOKE statements. An invoked method may execute an INVOKE statement that directly or indirectly invokes the invoking method.

Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.