basic.matread Statement/BASIC Program

basic.matread

Command basic.matread Statement/BASIC Program
Applicable release versions: AP, R83
Category BASIC Program (486)
Description reads the specified item from the optionally specified file.variable, or if not specified, the default file.variable, and stores one attribute per element in the array.

This statement may optionally be written "matread" or "read". If "mat" is omitted, a matrix read can be determined by the definition of the variable, "array.variable". If no "dim" statement appears, it is automatically treated as a "dynamic" array.

The "else" clause is taken when the item is not on file. The "then" condition is taken when the item is read successfully.

The "locked" clause occurs before the "then" and/or "else" clause{s} and specifies the statement{s} to execute if the item is locked when the read is attempted. The "locked" clause may be used in conjunction with a "then" or "else" clause, but not both.

The "matreadu" form tests if the item is already locked and locks the item if it is not. The item lock set by "matreadu" prevents the item from being read using the "{mat}readu" statement or updated by other processes while the lock is set. Note that in R83 implementations, the entire group in which the item was found is locked.

If the "matreadu" form is specified and no "locked" clause is present, the program pauses (and "beeps" continuously) at the locked item until it is available. If a "locked" clause is specified, the statements in the "locked" clause are executed if the item is already locked by another process or the current process at a different level. "system(30)" contains the port.number which has the item locked. For backwards compatibility, "system(0)", in the "locked" clause, also returns the port.number which has the item locked.

The item lock is only released by a "release", "delete", "write", "writev", or "matwrite" statement. Items can be updated without being unlocked by using the "writeu", "writevu", or "matwriteu" statements.

If a binary item is read, system(0) is set to 10. The variable string consists of the hex fid in attribute 1 and the hex frame in attribute 2.

If the array is defined by a "file" statement, the "file.variable" is not used.

See the "then/else construct" for an explanation on the use of "then" and "else" clauses in statements that allow or require them.
Syntax {mat}read{u} array.variable from {file.variable,} id.expression {locked statement.block} {then | else statement.block}
Options
Example
open 'customer' to cust.fv
dim customer.rec(20)
matread customer.rec from cust.fv,item.id

dim a(5)
mat a = "xyz":am":"abc"
matwrite a on "a"

This writes the dimensioned array "a" on the default file, using 
"a" as the item-id. Although there are only five elements in the 
array, each corresponds to two attributes (separated by attribute marks), thus, 
ten total attributes are written.

dim customer.item(20)
matreadu customer.item from cust.fv,item.id locked
 crt item.id:' is locked by port ':system(0)
end then
 crt 'got it'
end else
 crt 'not on file'
end
Purpose
Related basic.then/else.construct
basic.matreadu
basic.dim
tcl.unlock-item
basic.matwrite
basic.matbuild
basic.matparse
basic.id.expression
statement.block
basic.writev
basic.release
basic.file.variable
basic.default.files
basic.array.dimensioned
basic.writevu
basic.statements
basic.write
basic.locked
tcl.unlock-group
basic.array.references
basic.read
ue.001c
basic.mat
basic.system
tcl.list-locks_rp
basic.array.variable
basic.delete.function
basic.file
basic.(
basic.)