WRITEV Statement

Updates an attribute value in a file item.

Syntax

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

Syntax Elements

char-string An expression that evaluates to the data to be written.

file-var 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 The name of the item to which the data is written.

attr# The number of the attribute where char-string is written.

  • If attr# is a number in the range 1 to the number of attributes in the item, the specified attribute is replaced by the new value.

  • If attr# is greater than the number of attributes in the item, a new attribute is created, with null attributes created as necessary to put the new value in the specified position.

  • If attr# is -1, a new attribute is appended to the item.

  • If attr# is 0, a new attribute is added at the beginning of the item, preceding the existing attributes.

setting-var 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 attribute cannot be written and the ON ERROR clause is taken. For a description of file I/O error codes, refer to 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 WRITEV operation.

statement(s) One or more DataBasic statements, either separated by semicolons, or on separate lines and followed by an END statement. These will be executed if an error occurs.

Operation

If the specified item or attribute is non-existent, a new item or attribute is created.

If the specified file has not been opened prior to executing the WRITEV, or if an attribute number less than -1 is specified, an error message displays and the program terminates.

The WRITEV statement unlocks a previously locked item at the completion of the write operation (cf. WRITEVU 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).

Refer to the topic File Input and Output in the Efficiency Guidelines section for important recommendations about efficiency and the use of WRITEV.

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.

Examples

X1 = "XXX"
WRITEV X1 ON A2, "ABC", 4

Replaces the fourth attribute of item ABC in the file opened and assigned to variable A2 with the string value XXX.

Z=2
Y="THIS IS A TEST"
WRITEV Y ON X, "PROG", Z+3

Replaces attribute 5 of item PROG in the file opened and assigned to variable X with the string value "THIS IS A TEST."

WRITEV "XYZ" ON "A7", 4

Replaces attribute 4 of item A7 in the file most recently opened without a file variable with the string value XYZ.