MATWRITEU Statement

Writes a dimensioned array to a file item, leaving a previously locked item locked at the end of the write.

Syntax

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

Syntax Elements

array is the name of the dimensioned array whose elements are to be assigned to a file item.

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 to be assigned.

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

The MATWRITEU statement works exactly like the MATWRITE statement except it does not unlock a previously locked file item when writing to it. MATWRITEU does not actually lock an item. It simply does not unlock an item that is already locked. If the item is not locked, MATWRITEU is identical to MATWRITE.

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

FOR I=1 TO 10
  ITEM(I) = I
NEXT I
MATWRITEU ITEM ON "TJUNK"

Writes 10 attributes with values 1 through 10 to item named TJUNK. If TJUNK was locked before the write, it remains locked afterwards.