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

INTOWhen 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:

Only one record description is subordinate to the file description entry, or, All record-names associated with file-name, and the data item referenced by identifier-1, describe a group item, a numeric-edited item, or an elementary alphanumeric item. 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-1Identifier-1 refers to a data item described as a group item, a numeric-edited item, or an elementary alphanumeric item.

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

FORMATThe 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 -2The 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 -4The 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.

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

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

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

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

KEYThe 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-1Data-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-1The 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-2After successful completion of a READ statement with the NOT INVALID KEY phrase, control transfers to the imperative statement associated with the phrase.

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

INDICATORThe 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-4Identifier-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-1When 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.

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

COBOL/400 Language Help

NEXT MODIFIED Phrase

When you specify the NEXT MODIFIED phrase, the record made available is the first record in the subfile that has been modified.

The search for the next modified record begins:

At the beginning of the subfile if: o An I-O operation has been performed for the subfile control record. o The I-O operation cleared, initialized, or displayed the subfile.

For all other cases, with the record following the record that was read by a previous read operation.

The value of the RELATIVE KEY data item is updated to reflect the relative record number of the record made available to the program.

If you specify NEXT MODIFIED and there is no user-modified record in the subfile with a relative record number greater than the relative record number contained in the RELATIVE KEY data item, the AT END condition exists, the file status is set to 12, and the value of the RELATIVE KEY data item is set to the key of the last record in the subfile. Imperative-statement-2, or any applicable USE AFTER ERROR/EXCEPTION procedure, if any, is then executed.

If you do not specify the NEXT MODIFIED phrase, the data record made available is the record in the subfile with a relative record number that corresponds to the value of the RELATIVE KEY data item; and if the RELATIVE KEY data item contains a value other than the relative record number of a record in the subfile, the INVALID KEY condition exists and the execution of the READ statement is unsuccessful.

Random Access of Subfile Records: The NEXT MODIFIED phrase must not be used to randomly access records in a subfile. The INVALID KEY phrase can only be used for random access of subfile records.

Sequential Access of Subfile Records: The NEXT MODIFIED phrase must be specified to access subfile records sequentially. The AT END phrase can only be specified with the NEXT MODIFIED phrase.

FORMAT, identifier-2, or literal-1

If you specify the FORMAT phrase, literal-1 or the contents of identifier-2 must specify a format which is active for the appropriate program device. The READ statement reads a data record of the specified format.

When a format-name is not specified, the format used is the last record format written to the display device that contains input fields, input/output fields, or hidden fields. If no such format exists for the display file, the format used is the record format of the last WRITE operation to the display device.

To ensure correct results, always specify the FORMAT phrase for multiple format files.

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.

If the TERMINAL phrase is omitted for a file that has multiple devices acquired for it, a record is read from the subfile associated with the default program device.

INVALID, KEY, or imperative-statement-1

The INVALID KEY phrase should be specified if the NEXT MODIFIED phrase is not specified and there is no applicable USE procedure specified for the file name.

If the RELATIVE KEY data item contains a value that does not correspond to a relative record number for the subfile at the time of the execution of the READ statement, the INVALID KEY condition exists and the execution of the READ statement is unsuccessful.

Click here for further information about the invalid key condition.

END imperative-statement-3

The AT END phrase serves to explicitly delimit the scope of the READ statement. Specify the AT END phrase when you use the NEXT MODIFIED phrase and no applicable USE procedure is specified for the file name. If the AT END phrase and a USE procedure are both specified for a file, and the AT END condition arises, control transfers to the AT END imperative statement and the USE procedure is not executed.

If you specify NEXT MODIFIED and there is no user-modified record in the subfile, the AT END condition exists, and the READ operation is unsuccessful.

COBOL/400 Language Help

RELEASE Statement

Description

The RELEASE statement transfers records from an input/output area to the initial phase of a sorting operation. You can only use the RELEASE statement within the range of an input procedure associated with a SORT statement.

Within an INPUT PROCEDURE, you must specify at least one RELEASE statement.

When the RELEASE statement is executed, the current contents of record-name-1 are placed in the sort file; that is, made available for the beginning of the sorting operation.

->->---RELEASE record-name-1---*-------------------*----------><- *-FROM identifier-1-*

Format 5 (PIP Data Area)

Description

Format 5 of the ACCEPT statement transfers data from the PIP (Program Initialization Parameters) data area into the identifier.

The move into the identifier takes place according to the rules for the MOVE statement for a group move without the CORRESPONDING phrase.

Format 5 (PIP Data Area) ->->--ACCEPT identifier FROM mnemonic-name--------------------> ->---*-------------------------------------------*-----------> *-*----*-EXCEPTION imperative-statement-1---* *-ON-* ->---*-----------------------------------------------*-------> *-NOT-*----*-EXCEPTION imperative-statement-2---* *-ON-* ->---*------------*------------------------------------------><- *-END-ACCEPT-*

mnemonic-name

Mnemonic-name must be associated with an environment-name of PIP-DATA in the SPECIAL-NAMES paragraph.

EXCEPTION imperative-statement-1

Any imperative statement specified in the ON EXCEPTION phrase is processed if the PIP data area does not exist (the job is not a prestart job).

In the absence of the ON EXCEPTION phrase, a run-time message is issued if the PIP data area does not exist.

EXCEPTION imperative-statement-2 or NOT

Any imperative statement specified in the NOT ON EXCEPTION phrase is processed if the PIP data area exists (the job is a prestart job).

Format 4 (Local Data Area)

Description

Format 4 of the ACCEPT statement transfers data to identifier-1 from the system-defined local data area created for the job.

The move into identifier-1 takes place according to the rules for the MOVE statement for a group move without the CORRESPONDING phrase.

There is only one local data area for each job, and all devices in a job access the same local data area.

Format 4 (Local Data Area) ->->--ACCEPT identifier-1 FROM mnemonic-name------------------>

->---*----------------------*--------------------------------><- *-FOR-*-identifier-2-*-* *-literal------*

identifier-1

Identifier-1 is the receiving data item.

mnemonic-name

Mnemonic-name must be associated with an environment-name of LOCAL-DATA in the SPECIAL-NAMES paragraph.

FOR

When you specify the FOR phrase, it is syntax checked during compilation but treated as a comment during execution.

identifier-2 or literal

The value of literal or identifier-2 indicates the program device associated with the local data area.

If you specify literal, it must be nonnumeric 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.

Format 1 (Data Transfer)

Description

Format 1 of the ACCEPT statement transfers data from an input/output device into the specified identifier. The incoming data is received in USAGE IS DISPLAY format. When you omit the FROM phrase, the ACCEPT statement obtains input from the job input stream for batch jobs, and from the workstation for interactive jobs.

Format 1 is useful for exceptional situations when operator intervention (to supply a given message, code, or exception indicator) is required. The operator must have the appropriate messages with which to reply.

Format 1 (Data Transfer) ->->--ACCEPT identifier --*------------------------------*----------------><- *-FROM-*--mnemonic-name-----*--* *--environment-name--*

identifier

Identifier is the receiving data item.

mnemonic-name

Mnemonic-name must be associated in the SPECIAL-NAMES paragraph with an input/output device: a workstation (REQUESTOR), or a system operator's message queue (CONSOLE or SYSTEM-CONSOLE).

environment-name

Environment-name may be specified in place of mnemonic-name. Valid environment-names are CONSOLE and SYSIN

Format 2 (System Information Transfer)

Description

Format 2 of the ACCEPT statement transfers system information contained in the specified conceptual data items DATE, DAY, or TIME into the identifier. The transfer must follow the rules for the MOVE statement without the CORRESPONDING phrase. Format 2 (System Information Transfer) ->->--ACCEPT identifier FROM--*--DATE---------*----><- *--DAY----------* *--TIME---------*

DATE

DATE has the implicit PICTURE 9(6).

The sequence of data elements (from left to right) is:

2 digits for year of century 2 digits for month of year 2 digits for day of month

Thus 25 December 1991 is expressed as:

911225

The conceptual data items DATE, DAY, and TIME implicitly have USAGE DISPLAY. Since they are conceptual items, they cannot be described in the COBOL program.

DAY

DAY has the implicit PICTURE 9(5).

The sequence of data elements (from left to right) is:

2 digits for year of century 3 digits for day of year

Thus 25 December 1991 is expressed as:

91359

The conceptual data items DATE, DAY, and TIME implicitly have USAGE DISPLAY. Since they are conceptual items, they cannot be described in the COBOL program.

TIME

TIME has the implicit PICTURE 9(8).

The sequence of data elements (from left to right) is:

2 digits for hour of day 2 digits for minute of hour 2 digits for second of minute 2 digits for hundredths of second

Thus 2:41 P.M. is expressed as:

14410000

The conceptual data items DATE, DAY, and TIME implicitly have USAGE DISPLAY. Since they are conceptual items, they cannot be described in the COBOL program.

COMMIT Statement

Description

The COMMIT statement provides a way of synchronizing changes to data base records while preventing other jobs from modifying those records until the COMMIT is performed.

When the COMMIT statement is executed, all changes made to files under commitment control since the previous commitment boundary are made permanent. A commitment boundary is established by the successful execution of a ROLLBACK or COMMIT statement. If no COMMIT or ROLLBACK has been issued in the current job, a commitment boundary is established by the first OPEN of any file under commitment control in the job. Changes are made to all files under commitment control in the job, not just to files under commitment control in the COBOL program that issues the COMMIT statement.

When a COMMIT is executed, all record locks held by the job since the last commitment boundary for files under commitment control are released and the records become available to other jobs.

The COMMIT statement only affects files under commitment control. If a COMMIT is executed and there are no files opened under commitment control, the COMMIT statement has no effect and no commitment boundary is established.

The COMMIT statement does not:

Modify the I-O-FEEDBACK area for any file Change the file position indicator for any file Set a file status value for any file.

->->---COMMIT-----------------------------------><-