# Directives

WRITE | Add/Update Data in File

## Formats

1. | Write: | WRITE (filespec[,fileopt])varlist
2. | Write Lock: | WRITE LOCK (filespec[,fileopt])varlist

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.
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 where the name of the variable (rather than its contents) defines the prefix. (REC=VIS(name$) can also be used where the contents of the name$ variable defines the prefix.) For information on using the REC= option, see Prefixing Variables in an IOList via REC=.
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
varlist | Comma-separated list of variables, literals, mnemonics, IOL= options, and/or location functions '@(...)'.

(TABLE support was added in PxPlus 2018.)

## Description

Use the WRITE directive to add/update a record to a file (logical file number/channel). PxPlus also supports use of the WRITE directive with *MEMORY* (a memory-resident file or queue of records).

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:

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

## Format 1

Write

WRITE (filespec[,fileopt])varlist

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.

Example:

> 0410 write (1,err=1000,dom=1200)A,B,Z9$

An IND=index clause is mandatory if you are writing to an indexed file:

> 0810 let I=0
> 0820 open (8)"PVX_INDX"
> 0830 read (8)iol=110,err=0950
> 0840 let I=I+1 ! This reserves an empty record at index 0
> 0850 call "SOMETHING",iol=0110,err=950
> 0900 write (8,ind=I,err=9000)iol=0110
> 0910 goto 0830

The KEY=string$ is mandatory if you are writing to a Keyed file with an external key or to a DIRECT or SORT file:

> 0710 open (7)"PVX_SORT"
> 0720 read (6)CUST$,NAME$,*,*,*,*,*,*,*,*,*,err=0750
> 0730 write (7,key=CUST$)

No KEY= option is allowed if you are writing to a Keyed file whose primary key is composed of data fields embedded in the record data.

#### Note:
When writing to a file without an external key and the 'BX' system parameter is On, the KEY= option will be ignored.

In Keyed files with multiple keys, the WRITE directive will automatically update all alternate keys.

Example:

Alternate keys 0 [1:1:6] and 1 [2:1:10] are updated as follows:

> keyed "PVX_KEYD",[1:1:6],[2:1:10],,256
> 0210 open (2)"PVX_KEYD"
> 0220 read (6)CUST$,NAME$,*,*,*,*,*,START_DT$,CRED_LIM,TERMS,END_DT$,err=0250
> 0230 write (2)iol=0100

PxPlus uses the variables in the variable list either in delimited form or in accordance with any format specified (with headers, etc.). The contents of these fields are used to generate the actual data record. Numeric data converted during a WRITE directive does not use the 'DP' (Decimal Point Symbol) or 'TH' (Thousands Separator) system parameters for European decimal settings.

The list of variables can refer to an IOList (using IOL=iolref) as above. The iolref can be the line number or statement label of the line containing the IOList, or it can be a string containing a compiled IOList. If you omit the list of variables from the WRITE directive, PxPlus uses the IOL specified (if any) on your OPEN statement for the file.

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

Example:

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

## Format 2

Write Lock

WRITE (filespec[,fileopt])varlist

Use the WRITE LOCK format to ensure that once the file has been written to, it remains locked:

> 9010 write lock (9,err=2000)iol=0110

When you use the LOCK option, PxPlus does not release an extracted record. It maintains the extraction to prevent potential timing problems and maintain counters and totals in batch processing, sparing you the need to re-extract:

> 9010 write lock (9,key=K$)

#### Note:
If a serial file is not locked before you write to it, an Error #13: File access mode invalid will occur on the WRITE directive. Use OPEN LOCK for your serial file to prevent this error from occurring on the WRITE.

Example:

> serial "PVX_SER",,256
> 0510 open lock (5)"PVX_SER"
> 0520 read (6)CUST$,NAME$,ADDR1$,ADDR2$,CITY$,PROV$,POSTAL$,START_DT$,CREDLIM,
> 0520:TERMS,END_DT$,err=0550
> 0530 write (5)iol=0090
> 0540 goto 0520
> 0550 stop

## See Also

INSERT Insert New Record in File
UPDATE Update Existing Record in File
WRITE RECORD Write Record
OPEN Open a File for Processing
RCD( ) Return Next Record
'XI' Extract Ignore
*MEMORY* Create and Use Memory File