MATWRITE

MATWRITE, MATWRITEU

Top  Previous  Next

 

The MATWRITE statement builds a record from successive elements of a matrix and writes this to a file.

 

The MATWRITEU statement is similar but preserves any lock on the record being written.

 

 

Format

 

MATWRITE mat {ENCODING name} TO file.var, record.id {ON ERROR statement(s)}

 

where

 

matis the matrix from which data is to be taken.

 

file.varis the file variable associated with the file. This may not be a data collection file.

 

record.idevaluates to the key of the record to be written.

 

statement(s)are statements to be executed depending on the outcome of the operation.

 

 

The MATWRITE statement constructs a dynamic array from the elements of mat, writing this dynamic array to the file opened as file.var with the given record.id.

 

A MATWRITE statement is equivalent to a MATBUILD followed by a WRITE.

 

MATBUILD REC FROM mat

WRITE REC TO file.var, record.id ON ERROR statement(s)

 

The way in which the dynamic array is constructed differs depending on the matrix style.

 

For a default style matrix, MATWRITE constructs the dynamic array by concatenating elements of mat, inserting a field mark between each element. If the zero element is null or unassigned, trailing null elements are ignored. If the zero element is not null, trailing null matrix elements are included and followed by a field mark and the content of the zero element.

 

For a Pick style matrix, MATWRITE constructs the dynamic array by concatenating elements of mat, inserting a field mark between each element. Trailing null elements are ignored. Pick style matrices do not have a zero element. See the COMMON and DIMENSION statements for more details.

 

In either style, use of the INMAT() function immediately after MATWRITE will return the index value of the final element included. If the zero element of a default style matrix was non-null, INMAT() will return zero.

 

The optional ENCODING element to this statement sets the character encoding to be used, overriding any encoding set in the VOC F-type record or when the file was opened. This is relevant only to directory files and is ignored for other file types.

 

If the ON ERROR clause is taken, the STATUS() function can be used to determine the cause of the error. Otherwise, for the MATWRITE statement, the STATUS() function returns 0 if the record was locked by this process prior to the MATWRITE or ER$NLK if it was not locked. The STATUS() function value is undefined after a successful MATWRITEU statement.

 

 

Use of a THEN/ELSE Clause

 

For compatibility with the way in which triggers operate in some other multivalue products, the MATWRITE statement has an optional THEN/ELSE clause. Because this would otherwise lead to a syntactic ambiguity, compilation of programs that use this clause requires the WRITE.DELETE.THEN.ELSE option of the $MODE compiler directive to be enabled. Once this is done, the optional THEN/ELSE clauses can be included in their usual position, after the ON ERROR clause.

 

When a MATWRITE statement has a THEN/ELSE clause, a failure returned from a trigger function, typically as a result of a pre-write data validation error, will cause the ELSE clause to be executed instead of the ON ERROR clause.

 

 

Example

 

MATWRITE ITEMS TO ITEM.FILE, "ITEM.LIST" ON ERROR

  ABORT "Error " : STATUS() : " writing item list"

END

IF STATUS() = 0 THEN DISPLAY "Data saved"

 

This program fragment writes a record built from elements of matrix ITEMS. If the MATWRITE is successful, a message is displayed.