The MATREAD statement reads a file item and assigns each attribute to elements of a dimensioned array.
Format
MATREAD array FROM [filevar,]item-ID [SETTING var] [THEN statements END] [ELSE statements END] |
Parameter(s)
array |
Dimensioned array to be assigned. The array must have been dimensioned with a DIMENSION or COMMON statement before it may be assigned with the MATREAD statement. |
filevar |
File variable to which the file was opened. If filevar is not specified, the default file variable is used, which is the last file opened without a file variable assigned. |
item-ID |
An expression evaluating to the item-ID to be read. If the item is not found, the contents of array remain unchanged. |
SETTING var |
Assigns to var the number of attributes in the file item, regardless of whether this number is greater than the dimensions of the array. |
THEN statements |
Executes statements if the item-ID is found. |
ELSE statements |
Executes statements if the item-ID is not found. |
Description
The MATREAD statement assigns the attributes of a file item to consecutive elements of the specified dimensioned array. The first attribute of the item becomes the first element of array, the second attribute of the item becomes the second element of array, and so on. The array must be named and dimensioned in a DIMENSION or COMMON statement before it is used in this statement.
A MATREAD statement does not set an update lock on the specified record. That is, the record remains available for update to other users. To prevent other users from updating the record until it is released, use a MATREADU statement. See MATREADU Statement for more information.
If the number of attributes in the file item is greater than the dimensions of the array, the remainder of the attributes are placed into the last element of the array, separated by attribute marks (CHAR(254)). If the number of elements in the array is greater than the number of attributes in the item, the extra elements in the array are assigned a null value.
The MATREAD statement performs the same function as using the READ statement to read a dynamic array and then using the MATPARSE statement to assign a dimensioned array to the same elements.
Example
In this application, the file item containing an employee’s statistics is read into the dimensioned array EMP. The EMP array is dimensioned to 100 elements, and the MATREAD statement reads the elements of the array from the employee’s file.
The SETTING clause of the MATREAD statement assigns a variable to the number of attributes in the file item, which is checked to see if it exceeds the dimensions of the array.
DIMENSION EMP(100) ID = "PHONE" MATREAD EMP FROM EMPLOYEES, NAME SETTING NUM ELSE PRINT "CANNOT LOCATE EMPLOYEE" STOP END IF NUM > 100 THEN . . . |
See Also