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

 

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 by concatenating elements of mat, inserting a field mark between each element.

 

If the zero element of mat is a null string or unassigned, assembly of the dynamic array terminates after the last non-null element of mat. No trailing null fields will be written for later unassigned elements of mat.

 

If the zero element of mat contains data, all elements of mat are used and the zero element is concatenated as the final field of the record.

 

Pick style matrices do not have a zero element. See the COMMON and DIMENSION statements for more details.

 

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.

 

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)

 

 

Example

 

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

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

END

IF STATUS() = 0 THEN DISPLAY "Lock released"

 

This program fragment writes a record built from elements of matrix ITEMS. If it was locked prior to the MATWRITE, a message is displayed.