WRITE Statement

Write a variable, as a dynamic array, to a file item.

Syntax

WRITE char-string [ON || TO] {file-var,}item-id {SETTING setting-var} {ON ERROR statement(s)}

Syntax Elements

char-string is a field of characters comprising the data to be written, expressed as a literal enclosed in quotes, variable, or dynamic array.

file-var is the name of a variable containing a file reference (assigned via an OPEN statement). If file-var is not specified, the internal default file variable is used; that is, the file used is that most recently opened without a file variable.

item-id is the name of the item to which the data is written.

setting-var is the name of a variable that is set to a value corresponding to a file I/O error code by the SETTING clause if the item cannot be written to and the ON ERROR clause is taken. The file I/O error codes are described in File I/O and IPC Error Codes. If the ON ERROR clause is not taken, setting-var is set to 0.

ON ERROR operates the same as an ELSE clause.

Note

It is recommended that you always include an ON ERROR clause. If you do not and an error occurs at run time, your program will abort. This is particularly important if the file has a PRE-WRITE trigger that may cancel the WRITE operation.

statement(s) is a sequence of one or more valid DataBasic statements, either separated by semicolons or contained on separate lines and followed by an END statement. These will be executed if an error occurs.

Operation

If the item-id does not exist, a new item is created.

If a file is update protected and security codes do not match, an error message is displayed and control transfers to the debugger.

Note

The WRITE statement does not delete trailing attribute marks before filing an item.  If you wish to delete trailing attribute marks, use the TRIM function

The WRITE statement unlocks a previously locked item at the completion of the write operation (cf. WRITEU statement). Note, however, that if you write to an item that has been locked multiple times, the lock is not released until it has been unlocked the same number of times (this behaviour can be changed for compatibility with other MutliValue systems).

Caution

When calling this statement, you need to be aware of the effects of any file triggers that might run as a consequence. See File Triggers for more information.

Example

B=ITEMXX
A<1,1>=DATE()
A<1,2>=TIME()
A<2>=NAME.FIELD
.
.
.
WRITE A ON FN1,B

Replaces the current contents of item ITEMXX in the file opened and assigned to variable FN1 with the dynamic array A.