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:

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

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