WRITEVU Statement

Updates an attribute value in a file item, leaving a previously locked item locked after the write.

Syntax

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

The WRITEVU statement functions the same as the WRITEV statement except that it leaves a previously locked item locked at the end of the write operation.

Note

WRITEVU does not actually lock an item.  It simply does not unlock an item that is already locked.  If the item is not locked, the WRITEVU statement is identical to the WRITEV statement.

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

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

Z=2
A="TESTING PROGRAM A"
WRITEVU A ON FIL2, "PROG", Z+1

Replaces attribute 3 of item PROG in file FIL2 with the string value TESTING PROGRAM A. If PROG was locked before this write, it remains locked afterward.

WRITEVU "ABC" ON "ITEMA", 8

Replaces attribute 8 of ITEMA in the file most recently opened without a file variable with the string value ABC. If ITEMA was already locked, it remains locked after the write.