MATREADU Statement
Locks an item in a file, then reads the item and assigns each attribute to consecutive elements of a dimensioned array.
Syntax
MATREADU array
Syntax Elements
array The name of a dimensioned array to which the elements of the file item are assigned.
fileVar The name of a variable containing a file reference (assigned via an OPEN statement). If fileVar is not specified, the internal default file variable is used; that is, the file used is that most recently opened without a file variable.
itemId The name of the item from which the data is to be read.
settingVar The name of a 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), settingVar 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 there is no LOCKED clause, MATREADU is suspended until the item becomes unlocked.
-
The THEN clause is executed (and the item is locked) if the read is successful.
-
The ELSE clause is executed (and the item is locked) 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
MATREADU works the same way as the MATREAD statement, except that it locks the item. It should be used when updating an item to prevent it being modified by two or more processes simultaneously.
The item is locked even if the item does not exist on file. Thus, when building a new item it can be locked in the database first before it is ever written away.
If the SETTING clause is used and the read is successful, settingVar is set to the number of attributes in the item assigned to array. For example, if array was dimensioned for 100 elements and the item read in was only 12 attributes long, settingVar would be set to 12.
MultiValue Compatibility
If you call the STATUS function immediately after a MATREADU statement, if a LOCKED clause was specified and has been executed STATUS returns the port number of the process that has locked the item; otherwise STATUS returns zero.
Examples
MATREADU ARR1 FROM X, ITEM3 ELSE GOTO 120
Reads ITEM3 from file X into array ARR1 or, if ITEM3 does not exist, transfers control to statement 120.
MATREADU ARRAY FROM FIL1, "REC" SETTING K LOCKED PRINT... "CANNOT ACCESS" ELSE STOP
Reads item REC from file FIL1 into array ARRAY and sets K to the number of items read in. If REC cannot be read, error message displays and program terminates.