| Procedure Division - ACCEPT - DIVIDE |
| Procedure Division - MERGE - OPEN | |
The ENTER statement provides a means of allowing the use of more than one
language in the same pr
ogram.
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
- Language-name and routine-name can be any user-defined word or
alphanumeric literal.
General Rules
- This statement is treated as for documentation purposes only. Access to
other languages can be achieved by means of the CALL statement.
The ENTRY statement establishes an alternate entry point into a called
COBOL program.
General Formats
Format 1
Format 2
Directives
- 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.
- STICKY-LINKAGE - controls whether addressability to Linkage Section
items is maintained between calls to different entry points in the same
program.
- LITLINK - controls the number of significant characters in an
entry-name when .obj files are generated.
Syntax Rules
All Formats
- The ENTRY statement cannot be used in a program that is nested within
another program.
- Literal-1 must be non-numeric and must not be a figurative constant. In
some environments, only the first 8 characters are significant.
- The USING phrase is necessary only if the object program, the called
program, is being invoked by another program, the calling program, that
passes parameters. If the calling program is COBOL, parameters are passed if
the called program is invoked by the CALL statement
or the CHAIN statement
and that statement includes a USING phrase. If the calling program is
not COBOL then see the documentation for that language to determine if
parameters are passed.
- The USING phrase of the ENTRY statement is equivalent to the USING
phrase of the PROCEDURE DIVISION header and the two are subject to common
syntax rules as indicated in the section The PROCEDURE DIVISION
Header. All the data-names, integers, and typedef-names in the general
format of the ENTRY statement correspond to data-names, integers, and
typedef-names in the PROCEDURE DIVISION header. Format 2 of the ENTRY
statement corresponds to Format 2 of the PROCEDURE DIVISION header.
- Format 1 shall only be used within program definitions. Format 2 shall
only be used within call prototypes (when the PROGRAM-ID clause has the
EXTERNAL phrase specified).
General Rules
All Formats
- 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.
- 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.
- The USING phrase of the ENTRY statement is equivalent to the USING
phrase of the PROCEDURE DIVISION header and the two are subject to common
general rules as indicated in the section The PROCEDURE DIVISION Header.
All the data-names, integers, and typedef-names in the general format of the
ENTRY statement correspond to data-names, integers, and typedef-names in the
PROCEDURE DIVISION header. Format 2 of the ENTRY statement corresponds to
Format 2 of the PROCEDURE DIVISION header.
- 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.
The EVALUATE statement describes a m
ulti-branch, m
ulti-join structure. It can cause mu
ltiple conditions to be evaluated. The subsequent action of the object
program depends on the results of these
evaluations.
General Format
Syntax Rules
- 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.
- 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.
- The words THROUGH and THRU are equivalent.
- Two operands connected by a THROUGH phrase must be of the same class.
The two operands thus connected constitute a single selection object.
- The number of selection objects in each set of selection objects must be
equal to the number of selection subjects.
- 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:
- 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.)
- 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.
- The word ANY can correspond to a selection subject of any type.
-
Where identifiers are
permitted, they can reference floating-point data items.
-
Where numeric literals are
permitted, floating-point literals are permitted.
-
Where identifiers are
permitted, they can reference pointer data items.
-
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
- 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:
- 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.
- 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.
- 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.)
- 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.)
- 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.
- Any selection object specified by the word ANY is not further
evaluated.
- 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.
- 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.
- 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:
- 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.
- 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.)
- If the items being compared are assigned truth values, the
comparison is satisfied if the items are assigned the identical truth
value.
- 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.
- 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.
- 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.
- This procedure is repeated for subsequent sets of selection objects,
in the order of their appearance in the source program, until either a
WHEN phrase satisfying the set of selection subjects is selected or until
all sets of selection objects are exhausted.
- After the comparison operation is completed, execution of the EVALUATE
statement proceeds as follows:
- If a WHEN phrase is selected, execution continues with the first
imperative-statement-1 following the selected WHEN phrase.
- If no WHEN phrase is selected and a WHEN OTHER phrase is specified,
execution continues with imperative-statement-2.
- 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.)
-
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.
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
- The identifier must be described, explicitly or implicitly, as USAGE IS
DISPLAY.
- 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
- Examination proceeds as follows:
- 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.
- 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.
- The T
ALLYING option creates an integral count which replaces the value of a
spe
cial register called TAL
LY. The count represents the number of:
- Characters not equal to literal-1 encountered before the first
occurrence of literal-1 when the UNTIL FIRST option is used.
- Occurrences of literal-1 when the ALL option is used.
- Occurrences of literal-1 prior to encountering a character other than
literal-1 when the LEADING option is used.
- When either of the REPLACING options is used, the replacement rules are
as follows:
- When the ALL option is used, then literal-2 is substituted for each
occurrence of literal-1.
- 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.
- When the FIRST option is used, the first occurrence of literal-1 is
replaced by literal-2.
- 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.
The
EXEC(UTE) statement is provided as a linkage mechanism to allow control
to be passed to non-COBOL subsystems.
General Format
Syntax Rules
- Text-data can be any textual data not containing the string END-EXEC.
General Rules
- 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.
- 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.
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
- 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.
- CHANGED and NAMED can both be omitted.
General Rules
- Literals and identifiers displayed by the EXHIBIT statement are
separated by a space on the displayed line.
- Each literal can be any figurative constant other than ALL.
- If the literal is numeric, it must be an unsigned integer.
- 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.
- 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).
- 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).
- 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.
The EXIT statement provides a common en
d 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
calling programs written in any language.
General Formats
Format 1
Format 2
Format 3
Format 4
Syntax Rules
Format 1
- The EXIT statement should appear in a sentence by itself.
This rule is not enforced.
- The EXIT sentence should be the only sentence in the paragraph.
This rule is not enforced.
Format 2
- A Format 2 EXIT statement can be used only within an inline PERFORM.
Format 4
- 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.
- There must be no sentence other than the EXIT PROGRAM sentence in the
paragraph.
This rule is not enforced.
-
Integer-1 may be signed.
-
GIVING and RETURNING are
equivalent.
-
If the ADDRESS OF clause is not
specified, identifier-1 must be no larger than 8 bytes in size.
General Rules
Format 1
- An EXIT statement serves only to enable the user to assign a
procedure-name to a given point in a program. Such an EXIT statement has no
other effect on the compilation or execution of the program.
Format 2
-
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.
-
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
-
The execution of a Format 3
EXIT statement with the PARAGRAPH phrase causes control to pass to an
implicit CONTINUE statement immediately preceding:
- The next paragraph or section header, whichever comes first.
- The end of the source program if no paragraph or section header
appears between this EXIT statement and the end of the source program.
-
The execution of a Format 3
EXIT statement with the SECTION phrase causes control to pass to an implicit
CONTINUE statement immediately preceding:
- The next section header.
- Or immediately before the end of the source program if no section
header appears between this EXIT statement and the end of the source
program.
Format 4
-
If the EXIT PROGRAM statement
is executed in a program which is not under the control of a calling
program, the EXIT PROGRAM statement causes execution of the program to
continue with the next executable statement.
-
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 program. The program state of
the calling program 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
program 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.
-
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.
-
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.
-
Execution of an EXIT PROGRAM
statement in a program that is under the control of a calling program,
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
program. 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.
The GOBACK statement marks the logical end of a called program.
You can also return values to
calling programs written in any language or to the operating system
environment.
General Format
Syntax Rules
- 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.
-
GIVING and RETURNING are
equivalent.
-
If the ADDRESS OF clause is not
specified, the data item referenced by identifier-1 must be no larger than 8
bytes in size.
- Integer-1 may be signed.
General Rules
- If a GOBACK statement is executed in a program which is under the
control of a calling program, the object program operates as if executing an
EXIT PROGRAM statement that has the same clauses as the GOBABCK statement.
See the section The EXIT Statement.
- If a GOBACK statement without the ADDRESS OF clause is executed in a
program which is not under the control of a calling program, the object
program operates as if executing a STOP RUN statement that has the same
clauses as the GOBACK statement.
- If a GOBACK statement with the ADDRESS OF clause is executed in a
program which is not under the control of a calling program, 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.
- 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.
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
- Identifier is the name of a numeric elementary item which is an integer.
- 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
- A Format 1 GO TO statement, without procedure-name-1, can only appear in
a single statement paragraph.
This restriction is not
enforced.
- 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
- 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
- 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
- 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
- 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.
The IF statement causes a condition to be evaluated (see the section Conditional
Expressions earlier in this chapter). The subsequent action of the object
program depends on whether the value of the condition is true or false.
General Format
Syntax Rules
- Statement-1 and statement-2 represent either an imperative statement or
a conditional statement optionally preceded by an imperative statement.
-
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
- The scope of an IF statement can be terminated by any of the following:
-
An END-IF phrase at the same
level of nesting.
- A separator period.
- If nested, by an ELSE phrase associated with an IF statement at a
higher level of nesting.
- When an IF statement is executed, the following transfers of control
occur:
- 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.
- 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.
- 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.
- 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.
- 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.
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
- 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.
- 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.)
- The same category cannot be repeated in a REPLACING phrase.
- 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.
- An index data item can not appear as an operand of an INITIALIZE
statement.
- The data description entry for the data item referenced by identifier-1
must not contain a RENAMES clause.
-
A floating-point data item or
literal can be used anywhere a numeric identifier or literal can be
specified.
-
NATIONAL and NATIONAL-EDITED
fields can only be initialized with national character values.
General Rules
- 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.)
- 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:
- 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.
- 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.
- Index
and pointer
data items and elementary FILLER data items are not affected by the
execution of an INITIALIZE statement.
- 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.
- 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).
- 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.
- 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.)
-
NATIONAL and NATIONAL-EDITED
fields can be initialized with national character values.
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
- 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
- Identifier-1 must reference either a group item or any category of
elementary item, described (either implicitly or explicitly) as USAGE IS
DISPLAY.
- 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.
- 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.
- No more than one
BEFORE phrase
and /;
or one
AFTER phrase can
be specified for any one ALL, LEADING,
CHARACTERS, FIRST
or CONVERTING
phrase.
- 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
- Identifier-2 must reference an elementary numeric data item.
Formats 2 and 3
- 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.
- 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
-
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.
-
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
-
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.)
- 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.
- 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:
- 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.
- 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.
- 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.)
- 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.
- 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
-
Identifier-1 is a sending data
item.
- The required words ALL and LEADING are adjectives that apply to each
succeeding literal-1 until the next adjective appears.
- The contents of the data item referenced by identifier-2 are not
initialized by the execution of the INSPECT statement.
- The rules for tallying are as follows:
- 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.
- 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.
- 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.
- 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
- 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).
- The comparison operation to determine the occurrences of literal-1 to be
tallied or to be replaced, occurs as follows:
- 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:
- If neither LEADING nor FIRST is specified, or:
- If the LEADING adjective applies to literal-1 and literal-1 is a
leading occurrence as defined in General Rules 9 and 15, or:
- If the FIRST adjective applies to literal-1 and literal-1 is the
first occurrence as defined in General Rule 9.
- 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.
- 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.
- 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.
- 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.
- The comparison operation defined in General Rule 12 is affected by the
BEFORE and AFTER phrases as follows:
- 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.
- 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.
- 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
- The required words ALL, LEADING and FIRST are adjectives that apply to
each succeeding BY phrase until the next adjective appears.
- The rules for replacement are as follows:
- 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.
- 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.
- 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.
- 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.
- 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
- 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
-
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.
-
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.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Procedure Division - ACCEPT - DIVIDE |
| Procedure Division - MERGE - OPEN | |