MATREAD, MATREADL, MATREADU

Top  Previous  Next

 

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 FROM file.var, record.id {ON ERROR statement(s)}

{LOCKED statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

 

where

 

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

 

file.varis the file variable associated with the file.

 

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

 

 

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.

 

 

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)

 

 

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.