# Directives

WRITE RECORD | Write Record

## Format

WRITE RECORD (filespec[,fileopt])contents$

Where:

filespec | Can be a numeric expression indicating the open channel number to use or a string expression containing the pathname or table name (if string is prefixed by the keyword TABLE) of the file to use.
contents$ | String (literal, expression or variable) that contains the contents of the record to write.
fileopt | Supported file options (see File Options):
BSY=stmtref | Traps Error #0: Record/file busy
DOM=stmtref | Duplicate record transfer (taken when record of same primary key already exists)
END=stmtref | End-of-File transfer
ERR=stmtref | Error transfer
IND=num | Record index
KEY=string$ | Record key (See Automatic Padding with KEY=Option)
REC=name$ | Record prefix (REC=VIS(string$) can also be used to define the prefix)
RTY=num | Number of retries (one-second intervals). This overrides the value defined by the 'WT' system parameter.
TIM=num | Maximum time-out (support write operations for TCP channels)
stmtref | Program line number or statement label to which to transfer control

(TABLE support was added in PxPlus 2018.)

## Description

Use the WRITE RECORD directive to add/update a record for a file (logical file number/channel).

If the specific record already exists (indexed, direct or sort files) and you include the DOM=stmtref option, control transfers to the stmtref; otherwise, the specified record is updated.

In keyed files with multiple keys, the WRITE RECORD directive automatically updates all alternate keys. PxPlus supports use of the WRITE RECORD directive with *MEMORY* and ZIP files.

Automatic Padding with KEY=Option

When you use KEY=string$:string$[:string$][...], PxPlus automatically pads key segments. This is valid only if you have keyed files with segmented key definitions. PxPlus right pads the key segment using $00$ (nulls) to the segment's full length. The last segment in a compound key is not padded.

Example:

> keyed "TEST",[1:1:5]+[2:1:6]+[3:1:8]
> read (1,key=A$:B$:C$)

… is the same as:

> read (1,key=pad(A$,5,$00$)+pad(B$,6,$00$)+C$)

Writing to *MEMORY*

A WRITE operation will check the last entry in the key table for the key being added before proceeding to the top of the key chain to determine the new entry point. This dramatically increases the speed of writing additional records in sequential order.

You can use WRITE and/or WRITE RECORD directives to update records in a memory file using an IOList or a string expression. You can add records by index, inserting records at the given index number. PxPlus will not overwrite existing records.

Use the DOM= option when you write to a memory file.

Example:

The following two examples insert a new record at index 3 without overwriting the current record at index 3. The record that was at index 3 is now at index 4, and the number of records in the file has increased by 1.

> 0910 write (14,ind=3)iol=2010
> or
> write record (14,ind=3)"DOGCATPIG"

To update a given record in a memory file, use KEY= with a given key value:

> 0910 write (14,key=KK$,dom=0920)iol=2010
> or
> write record (14,key=KK$)A$

## See Also

WRITE Add/Update Data in File
INSERT Insert New Record in File
UPDATE Update Existing Record in File
Accessing ZIP Files

## Example

0010 open (1)"OLDFIL"
0020 open lock (2)"NEWFIL"
0030 read record (1,end=1000)R$
0040 write record (2)R$
0050 goto 0030
1000 close
1010 end