Caché MultiValue Basic Reference
MATREAD, MATREADL, MATREADU
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Reads data from a MultiValue file to a dimensioned array.
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:
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. The statements argument can be the NULL placeholder keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line; there must be a line break between the LOCKED keyword and the first line.
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. The statements argument can be the NULL placeholder keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line; there must be a line break between the ON ERROR keyword and the first line.
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. The statements argument can be the NULL keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line and cannot follow a THEN, ELSE, or END keyword on that line.
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.
Note:
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)
See Also