WRITE

Write a record to a file

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

WRITE(channel, data_area[, record][, POSITION:pos_spec][, GETRFA:new_rfa]
&    [, RFA:match_rfa]) [[error_list]]

Arguments

channel

The channel on which the file is open. The channel must already have been opened in output, append, or update mode. (n)

data_area

An expression that contains the information to be written. (a)

record

(optional) The ID of the record to write or one of the following options. The record ID is a numeric variable whose value is the ordinal number of the desired record. On Windows and UNIX, record must be passed when writing to a file other than an ISAM or relative file. (non-ISAM only)

^FIRST

Evaluate to the first record currently in the file.

^LAST

Evaluate to the last record currently in the file.

^EOF

Evaluate to the nonexistent record starting at the end of file.

POSITION

(optional) Specifies an absolute position in the file. See POSITION for a complete description. (non-ISAM only)

GETRFA

(optional) Returns the record’s RFA after the WRITE has been performed. See GETRFA for a complete description.

RFA

(optional) Writes the record at the specified RFA. See RFA for a complete description. (non-ISAM only)

error_list

(optional) An I/O error list. If any one of the specified errors occurs as part of the WRITE, control is transferred to the associated label.

Discussion

The WRITE statement outputs a record to a file. If the specified record already exists in the file, it is replaced. On file types other than ISAM, if the record doesn’t exist, it is created.

If you specify a WRITE with no record number to a relative file, the runtime writes the current record.

For ISAM files, the record being modified must be the record most recently retrieved (locked) by a FIND, READ, or READS statement. If it is not locked, a “Record not locked” error ($ERR_NOCURR) occurs. If you try to modify the value of a key that was not defined as modifiable when the ISAM file was created, a “Key not same” error ($ERR_KEYNOT) occurs. If the data area is longer than the defined maximum length of a record in the ISAM file, an “Invalid record size” error ($ERR_IRCSIZ) occurs, and no data is transferred to the file.

You can’t modify the primary key with the WRITE statement in an ISAM file. To modify the primary key or any key that is not modifiable, you must delete the existing record and then STORE the modified record with a new primary key. After the WRITE, any automatic record locks are released for the record. The WRITE appends a record terminator to the data area written.

A WRITE to ^EOF extends the file, and the record just written (the last record in the file) becomes the current record.

On OpenVMS, ^LAST is only supported for ISAM and relative files.

When using RFAs from a file with data compression or variable-length records, you may need to use the GETRFA option to retrieve the potentially new RFA. This isn’t necessary if the file has STATIC RFA defined.

See also

Input and output statement qualifiers

Examples

The following subroutine updates a modification tracking record.

subroutine writerec
    a_datachn                   ,d      ;Channel for data file (modlog file)
    a_seqnum                    ,d      ;Current sequence number
    a_orig_seqnum               ,d      ;Original sequence number
    a_modlog                    ,a      ;Modification record
.define TTCHN           ,1
proc
    if (a_seqnum .eq. a_orig_seqnum) then
      begin
        write(a_datachn, a_modlog, a_seqnum)[key = badkey]
        display(TTCHN, $scr_pos(5,22), "Sequence number ", ^a(a_seqnum), 
  &             " has been updated")
        read(a_datachn, a_modlog, a_seqnum) [key = badkey]    ;Reread for update
      end
    else                         ;Don't let them change the sequence number
      writes(TTCHN, "Sequence number may not be modified")
    return
badkey,
    writes(TTCHN, "Invalid key specified")
    return
endsubroutine                   ;End of subroutine writerec

The following example references a data file that contains item information and uses the item number as the reference code. The reference codes are numerically ordered starting with item number 00001. The example gets an item code number, validates it, reads the appropriate record, updates the information, then writes the updated record back to the file.

subroutine get_item
    a_maxitem           ,d
    a_chn               ,d      ;Channel opened in i:r mode
    a_data              ,a      ;Data area for item record
.define TTCHN           ,1
record
    item                ,a5
    item_num            ,d5
proc
    repeat
      begin
        display(TTCHN, "Item #: ")
        reads(TTCHN, item) [eof=done]
        item_num = item
        if (item_num .gt. a_maxitem .or. item_num .le. 0)
          begin
            display(TTCHN, "Invalid item number", $scr_mov(-1,-80), 
  &                 $scr_clr(line))
            nextloop
          end
        read(a_chn, a_data, item_num) 
        xcall show_item(a_data)
        xcall update_item(a_data)
        write(a_chn, a_data, item_num)
      end
done,
    xreturn
endsubroutine