Description
Reads a dynamic array row into a matrix, assigning each field to consecutive elements in the matrix.
Syntax
MatRead matrix From [filevar | Cursor cursorvar], key| Then Else statements
Parameters
The MatRead statement has the following parameters.
| Parameter | Description |
|---|---|
| matrix | The designated matrix must have been previously named and dimensioned by either a Dimension or Common statement. The data content of the fields that are read from the specified record will become the data in the designated matrix. Data that is stored in the fields of a record are assigned as elements of the matrix in an ordered manner: the data of the first field in the record is assigned to the first element of the matrix, the data of the second field is assigned to the second element, and so on. MatRead does not assign a value to the 0 (zero) element of the matrix. If the record that is read contains fewer fields than the matrix has elements, the extra elements will be assigned a null value. If the record contains more fields than the matrix has elements, the remaining fields will be assigned to the last element of the matrix as a single string, retaining any outstanding field marks. |
| cursorvar | Contains a cursor variable. Cursor variables are initialized with a Select...By statement, and must be preceded with the key word Cursor. If the file being accessed has had control features added, cursor access will automatically invoke data (domain) conversion during a MatRead operation. |
| filevar | Must refer to a file variable name that has been previously named in an Open statement. If the specified file cannot be accessed, the program aborts with a runtime error message, and the elements of the matrix are left unchanged. |
| key | The record referenced by key will be read from the file identified by filevar or the file accessed using the cursor in cursorvar. |
| Then | The statement(s) following Then are executed if the record can be read successfully. The value of the InMat() function will be set to the number of elements in the matrix that received values in the execution of the MatRead statement. |
| Else | The statement(s) following Else are executed if the record cannot be read. The elements of the matrix are left unchanged. The Status() function indicates the severity of the error, and the system variable @FILE_ERROR contains detail about the nature of the error. |
See also
Dimension, Mat, MatParse, MatUnparse, MatWrite, InMat()
Example
* Reading records into a matrix. /* The CUSTOMER record is read into the CUST matrix. Each field is in one element. */ Open "CUSTOMER" To CUST_FILE Else status = Set_FSError() Return End KEY = "1" Dim CUST(30) MatRead CUST From CUST_FILE, KEY Else status = Set_FSError() End
