MATREAD, MATREADL, MATREADU
Synopsis
MATREAD array FROM filevar,recID [SETTING var] [ON ERROR statements] [[THEN statements] [ELSE statements]] MATREADL array FROM filevar,recID [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]] MATREADU array FROM filevar,recID [SETTING var] [ON ERROR statements] [LOCKED statements] [[THEN statements] [ELSE statements]]
Arguments
| array | Name of an existing dimensioned array that receives the file data. This array must have been dimensioned using the DIM statement. |
| filevar | A local variable used as the file identifier of an open MultiValue file. This variable is set by the OPEN statement. |
| recID | The record ID of the record to be read, specified as either a number or an alphanumeric string of up to 31 characters. Letters in a recID are case-sensitive. For naming conventions, refer to MATWRITE. |
| SETTING var | Optional — When an error occurs, sets the local variable var to the operating system's error return code. Successful completion returns 0; error return codes are platform-specific. The SETTING clause is executed before the ON ERROR, THEN, or ELSE clause. Provided for jBASE compatibility. |
Description
The MATREAD, MATREADL, and MATREADU statements read the specified record into a dimensioned array.
You must use the OPEN statement to open the MultiValue file before issuing any of these statements.
You must use the DIM statement to dimension array before issuing any of these statements. If a record read by MATREAD has more attributes than specified by DIM, the handling of these extra attributes is controlled by the STATIC.DIM option:
-
With $OPTIONS STATIC.DIM (the default in Reality, PICK, Ultimate, POWER95, MVBase, IN2, and R83 emulations) dimensioned arrays are created starting from element #1. When there is a MATREAD of more attributes than the array has dimensions, the extra attributes are appended to the last element, and INMAT returns 0 to indicate the overflow. On legacy platforms, there is no array element 0, and the array usually cannot be re-dimensioned, but Caché does have an element 0 and allows re-dimensioning.
-
With $OPTIONS -STATIC.DIM (the default in Cache, UniVerse, UniData, INFORMATION, PIOpen, UDPICK, D3, and jBASE emulations) dimensioned arrays are created starting from element 0. When there is a MATREAD with more attributes than dimensions, the extra attributes are put into element 0.
A read operation must be able to acquire at least a shared lock on the desired resource. The MATREADL statement acquires a shared lock before performing the read. The MATREADU statement acquires an update (exclusive) lock before performing the read. An optional LOCKED clause is provided that is executed if the desired lock could not be acquired. A MATREAD pauses execution until it can acquire a shared lock on the specified record.
You can optionally specify a LOCKED clause. This clause is executed if MATREADL or MATREADU could not perform a read due to lock contention. The LOCKED clause is optional, but strongly recommended; if no LOCKED clause is specified, program execution waits indefinitely for the conflicting lock to be released.
You can optionally specify an ON ERROR clause, which is executed if array is not a MultiValue dimensioned array. If no ON ERROR clause is present, the ELSE clause is taken, or an <ARRAY DIMENSION> error is issued.
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. MATREAD executes the THEN clause if the read was successful. The THEN clause is executed even when all remaining field identifiers are the null string. MATREAD executes the ELSE clause if the read operation fails.
MATREAD, MATREADL, and MATREADU all read the specified MultiValue file record value into array. If recID refers to a non-existent record, the read operation fails.
This statement cannot be executed from the MVBasic command shell. Attempting to do so results in a MVBasic syntax error.
The various MATREAD statements read from a MultiValue file into a dimensioned array. The various READ statements read from a MultiValue file into a dynamic array.
Examples
The following example illustrates the use of the MATREAD statement:
DIM myarray(6)
OPEN "TEST.FILE" TO myfile
MATREAD myarray FROM myfile,1
PRINT "the number of records read:",INMAT()
PRINT "the record value:",myarray(1)
