ILE COBOL Language Reference

Statement Operations

COBOL statements perform the following types of operations:

FROM Phrase

Select which topic you want help on:

TO

Select which topic you want help on:

Common Phrases and Concepts

There are several phrases and concepts common to arithmetic and data manipulation statements:

CORRESPONDING Phrase

The CORRESPONDING phrase (CORR) allows ADD, SUBTRACT, and MOVE operations to be performed on elementary data items of the same name if the group items to which they belong are specified.

Both identifiers following the keyword CORRESPONDING must be group items. In this discussion, these identifiers are referred to as identifier-1 and identifier-2.

A pair of data items (subordinate items), one from identifier-1 and one from identifier-2, correspond if the following conditions are true:

When you use the (default) *PRTCORR compiler option or the PRTCORR option of the PROCESS statement, the compiler inserts comment lines in the compiler listing after each statement that contains the CORRESPONDING phrase. These comment lines, which print immediately before the next valid source statement, identify the elementary items that are affected within the groups named.

GIVING Phrase

The data item referenced by the identifier that follows the word GIVING is set to the calculated result of the arithmetic operation.

Because this identifier is not involved in the computation, it may be a numeric edited item.

Giving Phrase - Format
 
           .---------------------------.
           V                           |
>>-GIVING----identifier-1--+---------+-+-----------------------><
                           '-ROUNDED-'
 
 

ROUNDED Phrase

After decimal point alignment, the number of places in the fraction of the result of an arithmetic operation is compared with the number of places provided for the fraction of the resultant identifier.

When the size of the fractional result exceeds the number of places provided for its storage, truncation occurs unless ROUNDED is specified. When ROUNDED is specified, the least significant digit of the resultant identifier is increased by 1 whenever the most significant digit of the excess is greater than or equal to 5. The maximum number of digits that can be accurately rounded is 62.

When the resultant identifier is described by a PICTURE clause containing rightmost Ps, and when the number of places in the calculated result exceeds the number of integer positions specified, rounding or truncation occurs, relative to the rightmost integer position for which storage is allocated.

+-------------------------------IBM Extension--------------------------------+

In a floating-point arithmetic operation, the ROUNDED phrase has no effect; the result of a floating-point operation is always rounded. For more information on floating-point arithmetic expressions, see the ILE COBOL for AS/400 Programmer's Guide.

+----------------------------End of IBM Extension----------------------------+

SIZE ERROR Phrases
SIZE ERROR Phrase - Format
 
>>-+----+--SIZE ERROR--imperative-statement-1------------------><
   '-ON-'
 
 

A size error condition can occur in three different ways:

The size error condition applies only to final results, not to any intermediate results.

If the resultant identifier is defined with USAGE IS BINARY, the largest value that can be contained in it is the maximum value implied by its associated decimal PICTURE character-string.

If the ROUNDED phrase is specified, rounding takes place before size error checking.

When a size error occurs, the subsequent action of the program depends on whether or not the ON SIZE ERROR phrase is specified.

If the ON SIZE ERROR phrase is specified and a size error condition occurs, the value of the resultant identifier affected by the size error is not altered--that is, the error results are not placed in the receiving identifier. Values of other resultant identifiers are not affected, as long as no size error occurred for them. After completion of the execution of the arithmetic operation, the imperative statement in the ON SIZE ERROR phrase is executed. If no explicit transfer of control is executed upon completion of the imperative statement specified in the ON SIZE ERROR phrase, control is transferred to the end of the arithmetic statement and the NOT ON SIZE ERROR phrase, if specified, is ignored.

If the ON SIZE ERROR phrase is not specified and a size error condition exists after the execution of the arithmetic operations specified by an arithmetic statement, the value of the affected resultant identifier is undefined. Values of other resultant identifiers are not affected, as long as no size error occurred for them. After completion of the arithmetic operations, control is transferred to the end of the arithmetic statement and the NOT ON SIZE ERROR phrase, if specified, is ignored.

For ADD CORRESPONDING and SUBTRACT CORRESPONDING statements, if an individual arithmetic operation causes a size error condition, the ON SIZE ERROR imperative statement is not executed until all the individual additions or subtractions have been completed.

NOT ON SIZE ERROR

If the NOT ON SIZE ERROR phrase has been specified and, after execution of an arithmetic operation, a size error condition does not exist, the NOT ON SIZE ERROR phrase is executed.

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

Overlapping Operands

When a sending and a receiving item in any statement share a part or all of their storage areas, yet are not defined by the same data description entry, the result of the execution of such a statement is unpredictable. In addition, the results are unpredictable for some statements in which sending and receiving items are defined by the same data description entry. These cases are addressed in the general rules associated with those statements.

Arithmetic Statements

The arithmetic statements are used for computations. Individual operations are specified by the ADD, SUBTRACT, MULTIPLY, and DIVIDE statements. These operations can be combined symbolically in a formula, using the COMPUTE statement.

Arithmetic Statement Operands

The data description of operands in an arithmetic statement need not be the same. Throughout the calculation, the compiler performs any necessary data conversion and decimal point alignment.

Related Information:

Size of Operands

The maximum size of each operand is 18 decimal digits.

+-------------------------------IBM Extension--------------------------------+

The maximum size of a zoned decimal or an internal decimal operand is 63 decimal digits.

+----------------------------End of IBM Extension----------------------------+

From each operand, you can determine the number of decimal digits in the composite of operands. The composite of operands is a hypothetical data item resulting from aligning the operands at the decimal point and then superimposing them on one another.

For example, assume that each item is defined as follows in the Data Division:

A  PICTURE 9(7)V9(5).
B  PICTURE 9(11)V99.
C  PICTURE 9(12)V9(3).

If the following statement is executed, the composite of operands consists of 17 decimal digits:

ADD A B TO C

It has the following implicit description:

Composite-of-Operands PICTURE 9(12)V9(5).

If the composite of operands is 18 digits or less, enough places are carried so that no significant digits are lost during execution.

+-------------------------------IBM Extension--------------------------------+

When the (default) compiler option *NOEXTEND or the PROCESS statement option NOEXTEND is specified, the composite of operands can have a maximum length of 30 decimal digits.

The composite of operands can have a maximum length of 31 decimal digits when the arithmetic mode compiler option *EXTEND31 or PROCESS statement option EXTEND31 is specified.

The composite of operands can have a maximum length of 63 decimal digits when the arithmetic mode compiler option *EXTEND63 or PROCESS statement option EXTEND63 is specified.

Note:
If the composite of operands exceeds the specified maximum, significant digits may be lost during execution.

+----------------------------End of IBM Extension----------------------------+

The following table shows the maximum number of decimal digits that are allowed for the composite of operands in arithmetic statements.

Compiler Option/Process Statement Maximum Length of Composite (decimal digits)
*NOEXTEND/NOEXTEND

18

+-------------------------------IBM Extension--------------------------------+

30

+----------------------------End of IBM Extension----------------------------+


*EXTEND31/EXTEND31

18

+-------------------------------IBM Extension--------------------------------+

31

+----------------------------End of IBM Extension----------------------------+


*EXTEND63/EXTEND63

+-------------------------------IBM Extension--------------------------------+

63

+----------------------------End of IBM Extension----------------------------+

The following list shows how the composite of operands is determined for arithmetic statements:

Statement
Determination of the Composite of Operands

ADD
Superimposing all operands in a given statement (except those following the word GIVING)

COMPUTE
Restriction does not apply

DIVIDE
Superimposing all receiving data items, except the REMAINDER data item

MULTIPLY
Superimposing all receiving data items

SUBTRACT
Superimposing all operands in a given statement (except those following the word GIVING)

In all arithmetic statements, it is important to define data with enough digits and decimal places to ensure the desired accuracy in the final result. For more information on arithmetic precision, see Appendix B, Intermediate Results and Arithmetic Precision.

Multiple Results

When an arithmetic statement has multiple results, execution conceptually proceeds as follows:

For example, executing the following statement:

ADD A, B, C, TO C, D(C), E.

is equivalent to executing the following series of statements:

ADD A, B, C GIVING TEMP.
ADD TEMP TO C.
ADD TEMP TO D(C).
ADD TEMP TO E.

In the above example, TEMP is a compiler-supplied temporary result field. When the addition operation for D(C) is performed, the subscript C contains the new value of C.

Note:
Intermediate results generated during the execution of arithmetic statements are system-specific and can affect program portability. Use of the individual arithmetic statements ADD, SUBTRACT, MULTIPLY, and DIVIDE, rather than COMPUTE, reduces the risk of getting inconsistent results.

Data Manipulation Statements

The following COBOL statements move and inspect data:

ACCEPT, INITIALIZE, INSPECT, MOVE, READ, RELEASE, RETURN, REWRITE, SET, STRING, UNSTRING, and WRITE.

+-------------------------------IBM Extension--------------------------------+

XML PARSE, XML GENERATE.

+----------------------------End of IBM Extension----------------------------+

Input-Output Statements

COBOL input-output statements transfer data to and from files stored on external media, and also control low-volume data that is obtained from or sent to an input/output device.

In COBOL, the unit of file data made available to the program is a record, and you need only be concerned with such records. Provision is automatically made for such operations as the movement of data into buffers and/or internal storage, validity checking, error correction (where feasible), blocking and deblocking, and volume switching procedures.

The description of the file in the Environment Division and Data Division governs which input-output statements are allowed in the Procedure Division.

See Appendix F, File Structure Support Summary and Status Key Values for a file structure support summary.

Discussions in the following section use the terms volume and reel. The term volume refers to all non-unit-record input-output devices. The term reel applies only to tape devices. Treatment of direct access devices in the sequential access mode is logically equivalent to the treatment of tape devices.

Related Information

Common Processing Facilities

There are several common processing facilities that apply to more than one input-output statement. The common processing facilities provided are:

Status Key

If the FILE STATUS clause is specified in the FILE-CONTROL entry, a value is placed in the specified status key (the 2-character data item named in the FILE STATUS clause) during execution of any request on that file; the value

indicates the status of that request. The value is placed in the status key before execution of any EXCEPTION/ERROR declarative or INVALID KEY/AT END phrase associated with the request.

The first character of the status key is known as status key 1 (high order digit); the second character is known as status key 2 (low order digit). The combinations of possible values and their meanings are shown in Table 49.

INVALID KEY Condition

The invalid key condition can occur during execution of a START, READ, WRITE, REWRITE, or DELETE statement.

(For details of the causes for the condition, see the appropriate statement in Procedure Division Statements.) When an invalid key condition occurs, the input-output statement that caused the condition is unsuccessful. When the invalid key condition exists after an input-output operation, the following actions are taken:

  1. If there is an applicable file status clause (but not an applicable USE procedure), the file status is updated, and control returns to the program.
  2. Control will be transferred to the imperative statement of an INVALID KEY phrase, if specified.
  3. If an explicit or implicit EXCEPTION/ERROR procedure is specified for the file, the procedure runs; if no such procedure is specified, the results are unpredictable.
  4. In the absence of a file status clause, USE procedure, or INVALID KEY phrase to handle the error, a run-time message is issued, giving you the option to end or return to the program.

When the invalid key condition does not exist after an input-output operation, the INVALID KEY phrase is ignored, if specified, and the following actions are taken:

  1. If an exception condition that is not an invalid key condition exists, control is transferred according to the rules of the USE statement following the running of any USE AFTER EXCEPTION procedure.
  2. If no exception condition exists, control is transferred to the end of the input-output statement or the imperative statement specified in the NOT INVALID KEY phrase, if it is specified.

For more information about error handling and the role of the INVALID KEY phrase, see the chapter on exception and error handling in the ILE COBOL for AS/400 Programmer's Guide.

INTO/FROM Identifier Phrase

This phrase is valid for READ, RETURN, RELEASE, REWRITE, and WRITE statements. The identifier specified must be the name of an entry in the

Working-Storage, Local-Storage or the Linkage Sections, or of a record description for another previously opened file. Record-name, identifier must not refer to the same storage area.

INTO/FROM Identifier Phrase - Format
 
>>-+-+-READ---+--file-name-1--+--------+--+--------------------+-+-><
   | '-RETURN-'               '-RECORD-'  '-INTO--identifier-1-' |
   '-+-RELEASE-+--record-name-1--+--------------------+----------'
     +-REWRITE-+                 '-FROM--identifier-1-'
     '-WRITE---'
 
 

The result of the execution of a READ or RETURN statement with the INTO phrase is equivalent to the application of the following rules in the order specified:

  1. The execution of the same READ or RETURN statement without the INTO phrase.
  2. The current record is moved from the record area to identifier-1 according to the rules for the MOVE statement without the CORRESPONDING phrase. The size of the current record is determined by rules specified in the RECORD clause. If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied MOVE statement does not occur if the execution of the READ or RETURN statement was unsuccessful. Any subscripting or reference modification associated with identifier-1 is evaluated after the record has been read or returned and immediately before it is moved to the data item. The record is available both in the record area and in identifier-1.

The result of the execution of a RELEASE, REWRITE, or WRITE statement with the FROM phrase is equivalent to the execution of the following statements in the order specified:

  1. The statement
    MOVE identifier-1 TO record-name-1
    

    according to the rules specified for the MOVE statement.

  2. The same RELEASE, REWRITE, or WRITE statement without the FROM phrase.

After the execution of the RELEASE, REWRITE or WRITE statement is complete, the information in identifier-1 is available, but the information in record-name-1 is not available, except as specified by the SAME RECORD AREA clause.

File Position Indicator

The file position indicator is a conceptual entity used in this document to facilitate exact specification of the next record to be accessed within a given file during certain sequences of input-output operations. The concept of a file position indicator has no meaning for a file opened in the output or extend mode. The setting of the file position indicator is affected only by the OPEN, READ, RETURN, ROLLBACK and START statements as follows:

The concept of the file position indicator has no meaning for files with an access mode of random or for TRANSACTION files.

+-------------------------------IBM Extension--------------------------------+

DB-FORMAT-NAME Special Register

After the execution of an input/output statement, for a FORMATFILE or DATABASE file, the DB-FORMAT-NAME special register is modified according to the following rules:

You may specify the DB-FORMAT-NAME special register in a function whenever an alphanumeric argument is allowed.

+----------------------------End of IBM Extension----------------------------+

Procedure Branching Statements

Statements, sentences, and paragraphs in the Procedure Division are executed sequentially, except when a procedure-branching statement (listed below) is used.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]