MATREAD Statement

Reads a file item and assigns each attribute to consecutive elements of a dimensioned array.

Syntax

MATREAD arrayFROM {file-var,}item-id{SETTING setting-var} {LOCKED statement(s)}[THEN statement(s) | ELSE statement(s)]

Syntax Elements

array The name of a dimensioned array to which the elements of the file item are assigned.

file-var 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 The name of the item from which the data is to be read.

setting-var The name of the variable to which the smaller of the number of attributes in the item and the number of elements in the array is assigned if the read is successful.

If the read is not successful (the ELSE clause is taken), setting-var is assigned a file I/O error code. The file I/O error codes are described in File I/O and IPC Error Codes.

statement(s) A sequence of one or more valid DataBasic statements, either separated by semicolons, or contained on separate lines and followed by an END statement.

  • The LOCKED clause (if any) is executed if the item is locked by another process. Use SYSTEM(43) to obtain the number of the port that has locked the item.

    If a LOCKED clause is present, the statement sets a lock on the item (that is, it functions like MATREADU).

  • The THEN clause is executed if the read is successful.

  • The ELSE clause is executed if the item does not exist.

A THEN or an ELSE clause, or both, must be included.

Note

This behaviour can be changed with the NO.IO.ERR compatibility option.

Operation

setting-var is set to the number of attributes in the item, or number of elements in the array if the item has more attributes than the array has elements. Trailing, null attributes in the file item are therefore counted provided they are assigned to separate elements of the array.

If the number of attributes in the item is less than the dimensioned size of the array, the remaining elements are assigned null values. If it is greater than the size of the array, the remainder of the item is assigned to the last dimensioned array element.

If you use MATREAD with a two-dimensional array (matrix), the attributes are assigned one row at a time, to each column in that row. For example, if you have an array A with three rows and two columns, if you assign an item with eight attributes to that array, they will be assigned as follows:

A(1,1) = Attr1
A(1,2) = Attr2
A(2,1) = Attr3
A(2,2) = Attr4
A(3,1) = Attr5
A(3,2) = Attr6AMAttr7AMAttr8

Example 1

MATREAD ITEM FROM F1,'AB-123' ELSE STOP

Reads item 'AB-123' from file F1 into array ITEM.  If AB-123 does not exist, the program terminates.

Example 2

DIM ITEM(20)
OPEN 'LOG' TO F1 ELSE STOP
MATREAD ITEM FROM F1, 'TEST' SETTING K ELSE STOP

Reads the item named TEST from the data file LOG and assigns the string value of each attribute to consecutive elements of array ITEM. K is set to the number of attributes read in.

Example 3

Item 'IT' in file 'FL':

001 FIRST
002 SECOND
003 THIRD
004 FOURTH

Program:

DIM VAR(6)
OPEN 'FL' TO F1 ELSE STOP
MATREAD VAR FROM F1,'IT' ELSE STOP

Reads the item 'IT' from file 'FL' and assigns each attribute to consecutive elements of array VAR. On completion, VAR contains the following:

VAR(1)=FIRST
VAR(2)=SECOND
VAR(3)=THIRD
VAR(4)=FOURTH
VAR(5)= (null)
VAR(6)= (null)

Example 4

Item 'IT' in file 'FL' contains the following:

001 FIRST
002 SECOND
003 THIRD
004 FOURTH
005 FIFTH
006 SIXTH
007 SEVENTH
008 EIGHTH

Program:

DIM VAR(6)
OPEN 'FL' TO F1 ELSE STOP
MATREAD VAR FROM F1,'IT' ELSE STOP

Reads the item 'IT' from file 'FL' and assigns each attribute to consecutive elements of array VAR. On completion, VAR contains the following:

VAR(1)=FIRST
VAR(2)=SECOND
VAR(3)=THIRD
VAR(4)=FOURTH
VAR(5)=FIFTH
VAR(6)=SIXTHAMSEVENTHAMEIGHTH

Example 5

Item 'IT' in file 'FL' contains the following:

001 FIRST
002 SECOND
003 THIRD
004 FOURTH
005 FIFTH
006 SIXTH
007 SEVENTH
008 EIGHTH

Program:

DIM VAR(2,3)
OPEN 'FL' TO F1 ELSE STOP
MATREAD VAR FROM F1,'IT' ELSE STOP

Reads the item 'IT' from file 'FL' and assigns each attribute to consecutive elements of matrix VAR. On completion, VAR contains the following:

VAR(1,1)=FIRST
VAR(1,2)=SECOND
VAR(1,3)=THIRD
VAR(2,1)=FOURTH
VAR(2,2)=FIFTH
VAR(2,3)=SIXTHAMSEVENTHAMEIGHTH