ILE COBOL Language Reference

Indexed and Relative Files

WRITE - Format 2 - Indexed and Relative Files
 
>>-WRITE--record-name-1--+--------------------+----------------->
                         '-FROM--identifier-1-'
 
>--+-------------------------------------+---------------------->
   |        (1)                          |
   '-FORMAT------+----+-+-identifier-2-+-'
                 '-IS-' '-literal-1----'
 
>--+-----------------------------------------+------------------>
   |              (1)                        |
   '-NULL-KEY-MAP-------+----+--identifier-8-'
                        '-IS-'
 
>--+-------------------------------------+---------------------->
   |          (1)                        |
   '-NULL-MAP-------+----+--identifier-9-'
                    '-IS-'
 
>--+------------------------------------------+----------------->
   '-INVALID--+-----+--imperative-statement-1-'
              '-KEY-'
 
>--+----------------------------------------------+------------->
   '-NOT INVALID--+-----+--imperative-statement-2-'
                  '-KEY-'
 
>--+-----------+-----------------------------------------------><
   '-END-WRITE-'
 
 

Notes:

  1. IBM Extension

Related Information:

record-name-1

Must be defined in a Data Division FD entry. Record-name-1 may be qualified. It must not be associated with a sort or merge file.

In the case of relative files, only, the number of character positions in record-name-1 must equal the number of character positions in the record being replaced. It must not be associated with a sort or merge file.

FROM
When FROM is specified, the result is the same as:
MOVE identifier-1 TO record-name-1
WRITE record-name-1

After the WRITE statement is executed, the information is still available in identifier-1, even though it may not be in record-name-1. (See INTO/FROM Identifier Phrase.)

identifier-1
Must be an alphanumeric or numeric-edited data item. Data is transferred from this field to the receiving fields.

Record-name-1 and identifier-1 cannot both refer to the same storage area.

Identifier-1 can be the name of an alphanumeric or DBCS function identifier.

Considerations When Writing Indexed Files

Before the WRITE statement is executed, you must set the prime record key (the RECORD KEY data item, as defined in the File-Control entry) to the desired value. When the WRITE statement is processed, the system releases the record.

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

If the DUPLICATES phrase is specified, record key values for a format need not be unique (see RECORD KEY Clause). In this case, the system stores the records so that later sequential access to the records allows retrieval in the order specified in DDS.

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

If records are written to an indexed file of fixed size when it has SEQUENTIAL access, is open for OUTPUT, and blocking is in effect (BLOCK CONTAINS clause is specified), the blocking factor will change to 1 at the point at which a block of records would cause the end-of-file to be reached.

If the ALTERNATE RECORD KEY clause is also specified in the File-Control entry, each alternate record key must be unique, unless the DUPLICATES phrase is specified. If the DUPLICATES phrase is specified, alternate record key values need not be unique.

The number of remaining records in the file at this moment is less than the number of records in a block.

When ACCESS IS SEQUENTIAL is specified in the File-Control entry, records must be released in ascending order of RECORD KEY values.

When ACCESS is RANDOM or ACCESS IS DYNAMIC is specified in the File-Control entry, records may be released in any programmer-specified order. If the FORMAT phrase is not specified on the I-O statement when indexed files are accessed in random access mode, the first format defined is used. When writing to a multiformat logical file, the format must be specified on the WRITE statement.

Considerations When Writing Relative Files

For OUTPUT files, the WRITE statement causes the following actions:

For files opened in I-O mode, either ACCESS IS RANDOM or ACCESS IS DYNAMIC must be specified; the WRITE statement inserts new records into the file. The RELATIVE KEY must contain the desired relative record number for this record before the WRITE statement is issued. When the WRITE statement is executed, this record is placed at the specified relative record number position in the file.

For a physical file that does not allow the DELETE operation on records (for example, using the CRTPF with the ALWDLT(*NO) parameter), the update operation on records must be allowed (that is, CRTPF with the ALWUPD(*YES) parameter).

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

FORMAT Phrase

Required if there is more than one record format for the file.

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, if specified, must be a an alphanumeric data item of 10 characters or less.

Literal-1, if specified, must be an uppercase character-string of 10 characters or less.

If the FORMAT phrase is not specified on the I-O statement when indexed files are accessed in random access mode, the first format defined is used.

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

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

NULL-KEY-MAP IS Phrase

Refer to

the description supplied for this phrase on page NULL-KEY-MAP IS Phrase.

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

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

NULL-MAP IS Phrase

Refer to the description supplied for this phrase on page NULL-MAP IS Phrase.

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

INVALID KEY Phrase

The INVALID KEY phrase must be specified if an explicit or implicit EXCEPTION/ERROR

procedure is not specified for this file.

When an attempt is made to write beyond the externally defined boundaries of the file, WRITE statement execution is unsuccessful and an EXCEPTION/ERROR condition exists.

For Relative files in Random or Dynamic access mode, an INVALID KEY condition exists when RELATIVE KEY specifies a record that already contains data.

For Indexed files in Random or Dynamic access mode, an INVALID KEY condition exists when the value of the key field in the record area equals that of an already existing record and DUPLICATES are not allowed.

For Indexed files in Sequential access mode, an INVALID KEY condition exists when the values of the primary record keys of successive records are not in ascending order.

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

For a file that allows duplicate keys, the INVALID KEY condition exists only if the value of the record key is less than that for the previous record.

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

When the invalid key condition is recognized, WRITE statement execution is unsuccessful, and the contents of the record are unaffected. Program execution proceeds according to the rules described under INVALID KEY Condition.

NOT INVALID KEY Phrase

If the NOT INVALID KEY phrase is specified and a valid key condition exists at the end of the execution of the WRITE statement, control is passed to the imperative statement associated with this phrase.

END-WRITE Phrase

This explicit scope terminator serves to delimit the scope of the WRITE statement. END-WRITE permits a conditional WRITE statement to be nested in another conditional statement. END-WRITE may also be used with an imperative WRITE statement.

For more information, see Delimited Scope Statements.

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

FORMATFILE

WRITE Statement - Format 3 - FORMATFILE
 
>>-WRITE--record-name-1--+--------------------+----------------->
                         '-FROM--identifier-1-'
 
>--+--------------------------------+--------------------------->
   '-FORMAT-+----+-+-identifier-2-+-'
            '-IS-' '-literal-1----'
 
>--+-------------------------------------+---------------------->
   '-+-INDICATOR--+-+-----+-identifier-3-'
     +-INDICATORS-+ +-IS--+
     '-INDIC------' '-ARE-'
 
>--+-----------------------------------------------+------------>
   '-+----+-+-END-OF-PAGE-+-imperative-statement-1-'
     '-AT-' '-EOP---------'
 
>--+---------------------------------------------------+-------->
   '-NOT-+----+-+-END-OF-PAGE-+-imperative-statement-2-'
         '-AT-' '-EOP---------'
 
>--+-----------+-----------------------------------------------><
   '-END-WRITE-'
 
 

FORMAT Phrase

Required if there is more than one record format for the file.

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, if specified, must be an alphanumeric data item of 10 characters or less.

Literal-1, if specified, must be an uppercase character-string of 10 characters or less.

A value of all blanks is treated as though the FORMAT phrase were not specified. If the value is not valid for the file, a FILE STATUS of 9K is returned and a USE procedure is invoked, if applicable for the file.

INDICATORS Phrase

Specifies which indicators are to be written when a data record is read. Indicators can be used to pass information about the data record and how it was entered into the program.

For detailed information on the INDICATORS phrase, refer to the ILE COBOL for AS/400 Programmer's Guide.

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

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

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

TRANSACTION (Nonsubfile)

WRITE - Format 4 - TRANSACTION (Nonsubfile)
 
>>-WRITE--record-name-1--+--------------------+----------------->
                         '-FROM--identifier-1-'
 
>--FORMAT-+----+-+-identifier-2-+------------------------------->
          '-IS-' '-literal-1----'
 
>--+------------------------------------+----------------------->
   '-TERMINAL--+----+--+-identifier-3-+-'
               '-IS-'  '-literal-2----'
 
>--+----------------------------------------------+------------->
   '-STARTING--+----+--+------+--+-identifier-4-+-'
               '-AT-'  '-LINE-'  '-literal-3----'
 
>--+--------------------+--------------------------------------->
   '-| Rolling Phrase |-'
 
>--+-------------------------------------+--+-----------+------><
   '-+-INDICATOR--+-+-----+-identifier-8-'  '-END-WRITE-'
     +-INDICATORS-+ +-IS--+
     '-INDIC------' '-ARE-'
 
Rolling Phrase:
 
|--+-BEFORE-+--ROLLING--+-------+--+-identifier-5-+------------->
   '-AFTER--'           +-LINES-+  '-literal-4----'
                        '-LINE--'
 
>--+---------+--+-identifier-6-+--+-UP---+--+-identifier-7-+---->
   +-THROUGH-+  '-literal-5----'  '-DOWN-'  '-literal-6----'
   '-THRU----'
 
>--+-------+----------------------------------------------------|
   +-LINES-+
   '-LINE--'
 
 

FORMAT Phrase

Literal-1 or identifier-2 specifies the name of the record format to be written. Literal-1, if specified, must be nonnumeric, uppercase, and 10 characters or less in length. Identifier-2, if specified, must refer to an alphanumeric data item, 10 characters or less in length. If identifier-2 contains blanks, the WRITE statement is executed as if the FORMAT phrase were omitted.

TERMINAL Phrase

The TERMINAL phrase specifies the program devices to which the output record is to be sent.

The contents of literal-2 or identifier-3 must be the name of a program device previously acquired, either implicitly or explicitly, by the file. Literal-2, if specified, must be nonnumeric and 10 characters or less in length. Identifier-3, if specified, must refer to an alphanumeric data item, 10 characters or less in length. A value of blanks is treated as if the TERMINAL phrase was omitted.

If only a single program device was acquired by the TRANSACTION file, the TERMINAL phrase can be omitted. That program device is always used for the WRITE.

If the TERMINAL phrase is omitted for a WRITE operation to a TRANSACTION file that has acquired multiple program devices, the default program device is used.

STARTING Phrase

The STARTING phrase specifies the starting line number for the record formats that use the variable starting line keyword. This phrase is only valid for display devices.

The actual line number on which a field begins can be determined from the following equation:
Actual-line = Start-line + DDS Start-line - 1

Where:

The write is successful if:

The write is unsuccessful and the program terminates if:

If the value specified for the STARTING phrase is within the screen area, any fields outside of the screen area are ignored.

Literal-3 of the STARTING phrase must be a numeric literal. Identifier-4 must be an elementary numeric item.

To use the STARTING phrase, the DDS record level keyword SLNO(*VAR) must be specified for the format being written. If the record format does not specify this keyword, the STARTING phrase is ignored at execution time.

The DDS keyword CLRL also affects the STARTING phrase. CLRL controls how much of the screen is cleared when the WRITE statement is executed.

For further information on SLNO(*VAR) and CLRL, see the DB2 Universal Database for AS/400 section of the Database and File Systems category in the iSeries Information Center at this Web site - http://www.ibm.com/eserver/iseries/infocenter.

ROLLING Phrase

The ROLLING phrase allows you to move lines displayed on the workstation screen. All or some of the lines on the screen can be rolled up or down. The lines vacated by the rolled lines are cleared, and can have another screen format written into them. This phrase is only valid for display devices.

ROLLING is specified in the WRITE statement that is writing a new format to the workstation screen. You must specify whether the write is before or after the roll, the range of lines you want to roll, how many lines you want to roll these lines, and whether the roll operation is up or down.

After lines are rolled, the fields on these lines retain their DDS display attributes, for example, underlining, but lose their DDS usage attributes, for example, input-capability. Fields on lines that are written and then rolled (BEFORE ROLLING phrase) also lose their usage attributes.

If any part of a format is rolled, the entire format loses its usage attributes. If more than one format exists, only the rolled formats lose their usage attributes.

When you specify the ROLLING phrase, the following general rules apply.

For more information, see the DB2 Universal Database for AS/400 section of the Database and File Systems category in the iSeries Information Center at this Web site - http://www.ibm.com/eserver/iseries/infocenter.

INDICATORS Phrase

Specifies which indicators are to be used when a data record is written. Indicators can be used to pass information about the data record and how it was entered into the program.

For detailed information on the INDICATORS phrase, refer to Using Indicators with Transaction Files in the ILE COBOL for AS/400 Programmer's Guide.

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

Figure 27 shows an example of rolling. An initial screen format, FMT1 is written on the work station screen. The program processes this screen format and is now ready to write the next screen format, FMT2, to the workstation screen. Part of FMT1 is rolled down 2 lines before FMT2 is written to the workstation screen.

Execution of the following WRITE statement causes part of FMT1 to be rolled down 2 lines, and FMT2 to be written to the workstation screen:

   WRITE SCREENREC FORMAT "FMT2"
    AFTER ROLLING LINES 14 THROUGH 20
    DOWN 2 LINES

When this WRITE statement is executed, the following steps occur:

  1. The contents of lines 14 through 20 are rolled down 2 lines.
    1. The contents of lines 14 through 18 now appear on lines 16 through 20.
    2. The contents of lines 14 and 15 are vacated and cleared.
    3. The contents of lines 19 and 20 are rolled outside the window and disappear.
  2. After the rolling operation takes place, FMT2 is written to the workstation screen.
    1. Part of FMT2 is written to the area vacated by the roll operation.
    2. Part of FMT2 is written over the data left from FMT1.
  3. When the contents of the workstation screen are returned to the program by a READ statement, only the input capable fields of FMT2 are returned.

Figure 27. Example of ROLLING Operation

REQTEXT

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

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

TRANSACTION (Subfile)

WRITE Statement - Format 5 - TRANSACTION (Subfile)
 
>>-WRITE SUBFILE--record-name-1--+--------------------+--------->
                                 '-FROM--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-WRITE-'
 
 

Format 5 can only be used for display

devices. If the subfile form of the WRITE statement is used for any other type of device, the WRITE operation fails and a file status of 90 is set.

If the format is a subfile record and SUBFILE is specified, the RELATIVE KEY clause must be specified on the SELECT clause for the file being written. The record written to the subfile is the record in the subfile identified by the format name that has a relative record number equal to the value of the RELATIVE KEY data item.

INDICATORS Phrase

Specifies which indicators are to be used when a data record is written. Indicators can be used to pass information about the data record and how it was entered into the program.

For detailed information on the INDICATORS phrase, refer to Using Indicators with Transaction Files in the ILE COBOL for AS/400 Programmer's Guide.

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.

TERMINAL Phrase

See Format 4 for general considerations concerning the TERMINAL phrase.

The TERMINAL phrase specifies which program device's subfile is to have a record written to it. If the TERMINAL phrase is specified, literal-2 or identifier-3 must refer to a workstation associated with the TRANSACTION file. If literal-2 or identifier-3 contains a value of blanks, the TERMINAL phrase is treated as if it was not specified. The workstation specified by the TERMINAL phrase must have been acquired, either explicitly or implicitly.

If the TERMINAL phrase is omitted, the subfile used is the subfile associated with the default program device.

INVALID KEY Phrase

The INVALID KEY condition exists if a record is already in the subfile with that record number, or if the relative record number specified is greater than the maximum allowable subfile record number. The INVALID KEY phrase should be specified in the WRITE SUBFILE statement for all files for which an appropriate USE procedure is not specified.

NOT INVALID KEY Phrase

This phrase allows you to specify procedures that will be performed when an invalid key condition does not exist for the statement that is used.

END-WRITE Phrase

This explicit scope terminator serves to delimit the scope of the WRITE statement. END-WRITE permits a conditional WRITE statement to be nested in another conditional statement. END-WRITE may also be used with an imperative WRITE statement.

For more information, see Delimited Scope Statements.

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


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