COBOL/400 Language Help

Format 5 (TRANSACTION Subfile)

Description
The Format 5 READ statement is used only to read a format that is a subfile record. You cannot use Format 5 for communications devices. If the subfile format of the READ statement is used for a communication device, the READ operation fails.

The AT END phrase can only be specified when the NEXT MODIFIED phrase is specified. The INVALID KEY phrase must not be used when the NEXT MODIFIED phrase is specified.

Format 5 (TRANSACTION Subfile)
 
->->---READ SUBFILE file-name--------------------------------->
 
->---*-------------------*--*--------*----------------------->
    *-*------*-MODIFIED-*  *-RECORD-*
      *-NEXT-*
 
->---*-------------------*----------------------------------->
    *-INTO identifier-1-*
 
->----*--------------------------------*--------------------->
     *-FORMAT-*----*-*-identifier-2-*-*
              *-IS-* *-literal-1----*
 
->----*----------------------------------*------------------->
     *-TERMINAL-*----*-*-identifier-3-*-*
                *-IS-* *-literal-2----*
 
->----*------------------------------------------*----------->
     *-*-INDICATOR--*--*-----*--identifier-4----*
       *-INDICATORS-*  *-IS--*
       *-INDIC------*  *-ARE-*
 
->---*--------------------------------------------*---------->
    *-INVALID---*-----*---imperative-statement-1-*
                *-KEY-*
 
->---*------------------------------------------------*------>
    *-NOT INVALID---*-----*---imperative-statement-2-*
                    *-KEY-*
 
->----*-----------------------------------*------------------>
     *-*----*-END imperative-statement-3-*
       *-AT-*
 
->----*---------------------------------------*-------------->
     *-NOT-*----*-END imperative-statement-4-*
           *-AT-*
 
->---*----------*--------------------------------------------><-
    *-END-READ-*

file-name

File-name must be defined in a Data Division FD entry, and must not name a sort or merge file. If more than one record-description entry is associated with file-name, these records automatically share the same storage area. That is, they are implicitly redefined.

INTO

When you specify the INTO phrase, the current record moves from the input area to the identifier area according to the rules for the MOVE statement without the CORRESPONDING phrase. Any subscripting, indexing, or reference modification associated with the identifier is evaluated after the record has been read and immediately before it is transferred to the identifier. (Click here for information about reference modification.)

You can specify the INTO phrase if:

You cannot specify the INTO phrase when the file contains records of various sizes, as indicated by their record descriptions. The storage area associated with the identifier and the record area associated with the file-name cannot be the same storage area.

identifier-1

Identifier-1 refers to a data item described as a group item, a numeric-edited item, or an elementary alphanumeric item.

NO LOCK

The NO LOCK phrase prevents the READ operation from obtaining record locks on files that you open in I-O (update) mode. A READ statement with this phrase also releases records that have been locked by a previous READ operation.

If you use this phrase for a file that is not open in I-O mode, you receive an error message.

FORMAT

The value specified in the FORMAT phrase contains the name of the record format to use for this I-O operation. The system uses this to specify or select which record format to operate on.

identifier-2 or literal-1

Literal-1 or identifier-2 specifies the name of the record format to be read. If you specify literal-1 it must be nonnumeric, uppercase, and 10 characters or less in length. If you specify identifier-2, it must refer to an alphanumeric data item, 10 characters or less in length. If identifier-2 contains blanks, the READ statement runs as if the FORMAT phrase were omitted.

END imperative-statement-1 or -2

The AT END phrase serves to explicitly delimit the scope of the READ statement. The imperative statement is executed when the AT END condition is detected. Any EXCEPTION/ERROR procedure for the file is not run. If the AT END phrase is not specified, any EXCEPTION/ERROR procedure for the file is run. Return from that procedure is to the next executable statement following the end of the READ statement.

NOT or END imperative-statement-2, -3, or -4

The NOT AT END phrase transfers control to the imperative statement upon successful completion of the READ operation. The imperative statement specifies procedures that will be performed when the AT END condition does not exist.

NEXT

For a dynamic access READ NEXT statement, the file position indicator is positioned to point to the next record in the file. That record is then made available.

This applies to sequential retrieval from disk and database files, with either relative or indexed organization.

If you omit NEXT, a random access read is done.

FIRST

For a dynamic access READ FIRST statement, the file position indicator is positioned to point to the first record in the file. That record is then made available.

This applies to sequential retrieval from a database file with indexed organization.

If you omit FIRST, a random access read is done.

LAST

For a dynamic access READ LAST statement, the file position indicator is positioned to point to the last record in the file. That record is then made available.

This applies to sequential retrieval from a database file with indexed organization.

If you omit LAST, a random access read is done.

PRIOR

For a dynamic access READ PRIOR statement, the file position indicator is positioned to point to the previous existing record in the file. That record is then made available.

This applies to sequential retrieval from a database file with indexed organization.

If you omit PRIOR, a random access read is done.

KEY

The KEY IS phrase may be specified only for indexed files.

The KEY IS phrase is syntax checked only and has no effect on the operation of the READ statement.

data-name-1

Data-name-1 must identify a record key associated with file-name. Data--name-1 may be qualified but it may not be subscripted.

INVALID, KEY, or imperative-statement-1

The INVALID KEY phrase must be specified for files for which there is not an appropriate EXCEPTION/ERROR procedure.

Click here for further information about the invalid key condition.

NOT INVALID, KEY, or imperative-statement-2

After successful completion of a READ statement with the NOT INVALID KEY phrase, control transfers to the imperative statement associated with the phrase.

TERMINAL

The TERMINAL phrase specifies the program device from which the data record is made available. The program device must have been acquired before the READ operation. For a single device file, the TERMINAL phrase can be omitted. The program device is assumed to be that single device. If the TERMINAL phrase is omitted for a READ of a TRANSACTION file that has acquired multiple program devices, the default program device is used.

identifier-3 or literal-2

Literal-2 or identifier-3 specifies the program device name. If you specify literal-2, it must be nonnumeric and 10 characters or less in length. If you specify identifier-3, it must refer to an alphanumeric data item 10 characters or less in length. If identifier-3 contains blanks, the READ statement executes as if the TERMINAL phrase had been omitted.

INDICATOR

The INDICATOR phrase specifies which indicators are to be read. When a data record is read, indicators can be read with it. The indicators can be used to pass information about the data record and how it was entered into the program. INDICATOR, INDICATORS, and INDIC are equivalent.

identifier-4

Identifier-4 must be either an elementary Boolean data item specified without the OCCURS clause, or a group item that has elementary Boolean data items subordinate to it.

NO DATA imperative-statement-1

When you specify the NO DATA phrase, the READ statement will determine whether data is immediately available. If data is available, the data is returned in the record area. If no data is immediately available, imperative-statement-1 is executed. The NO DATA phrase prevents the READ statement from waiting for data to become available.

SUBFILE

When you specify the SUBFILE phrase, it indicates that all formats referenced by the statement are subfiles. When you do not specify SUBFILE in a TRANSACTION I/O statement, it indicates that none of the formats referenced by the statement are subfiles.

When SUBFILE is specified, a RELATIVE KEY data item must be defined for the file. Its value is referenced, and sometimes changed, by the I/O operation.

When SUBFILE is not specified, the RELATIVE KEY data item associated with the file, if specified, is not referenced or changed by the I/O operation.

You can specify the SUBFILE phrase only for display files.


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