MATREAD, MATREADL, MATREADU

The MATREAD statement reads a record from a file, assigning each field to an element of a matrix.

The MATREADL statement is similar to MATREAD but sets a read lock on the record. The MATREADU statement sets an update lock on the record.

Format

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

{LOCKED statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

where

mat	is the matrix into which fields are to be assigned. This matrix must already have been dimensioned.

file.var

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

record.id

evaluates to the key of the record to be read.

statement(s)

are statements to be executed depending on the outcome of the operation.

The LOCKED clause is not valid with the MATREAD statement. At least one of the THEN and ELSE clauses must be present unless the OPTIONAL.THEN.ELSE setting of the $MODE compiler directive is enabled.

The MATREAD statement is equivalent to a READ followed by a MATPARSE.

READ REC FROM file.var, record.id

ON ERROR statement(s)

LOCKED statement(s)

THEN MATPARSE mat FROM REC, @FM

ELSE statement(s)

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.

Each field of the record is assigned to a separate element of mat. If mat is two dimensional, its elements are assigned row by row. The INMAT() function will return the number of elements assigned. Unused elements are set to null strings.

With the default style of matrix, where there are fewer elements in mat than the number of fields in the record, the remaining data is stored in the zero element of mat. In this case, the INMAT() function will return zero.

Pick style matrices do not have a zero element. Any excess data is stored in the final element of the matrix and the INMAT() function returns zero to indicate this condition. See the COMMON and DIMENSION statements for more details.

Example

DIM ITEMS(30)

MATREAD ITEMS FROM ITEM.FILE, "ITEM.LIST" ELSE

ABORT "ITEM.LIST record not found"

END

IF INMAT() THEN DISPLAY INMAT() : " items read"

ELSE ABORT "Too many items"

This program fragment reads a record from a file, assigning fields to elements of matrix ITEMS. If there are more than 30 fields, the program aborts, otherwise it displays the number of items read.