MATWRITE Statement
Writes a dimensioned array to a file item.
Syntax
MATWRITE array
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 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 MATWRITE 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 specified item-id does not exist, a new item is created.
The number of attributes in the item is determined by the size of the array, but null trailing vector elements are not written as null attributes to the item.
If you use MATWRITE with a two-dimensional array (matrix), the attributes are assigned one row at a time, from each column in that row. For example, if you have an array A with three rows and two columns, the attributes in the file item will be assigned as follows:
Attr1 = A(1,1)
Attr2 = A(1,2)
Attr3 = A(2,1)
Attr4 = A(2,2)
Attr5 = A(3,1)
Attr6 = A(3,2)
MATWRITE releases any previously set item lock on the specified item (cf. MATWRITEU 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).
Note
MATWRITE does not issue an error message when dimensioned array elements contain attribute marks.
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
MATWRITE ITEM ON 'AB-123'
Writes the contents of array ITEM to the file previously opened without a file variable as an item with an id of AB-123.
DIM VEC(10) OPEN '', 'TEST' ELSE STOP FOR I=1 TO 10 VEC(I) = I NEXT I MATWRITE VEC ON "VJUNK"
Writes the contents of the vector VEC to an item named VJUNK in the file named TEST. VJUNK now contains 10 attributes whose string values are 1 through 10.
DIM MRX(5,2) OPEN '', 'TEST' ELSE STOP FOR N=1 TO 5 FOR M=1 TO 2 MRX(N,M) = N * M NEXT M NEXT N MATWRITE MRX ON "MJUNK"
Writes the contents of the matrix MRX to an item named MJUNK in the file named TEST. MJUNK now contains 10 attributes whose string values are 1, 2, 2, 4, 3, 6, 4, 8, 5 and 10.