Home > MultiValue Central > Online D3 Reference > BASIC Program > basic.matread

basic.matread

Statement/BASIC Program, Releases: AP and R83

Reads item into dimensioned array.

Syntax

{mat}read{u} array.variable from {file.variable,} id.expression {locked statement.block} {then | else statement.block}

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.

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

See Also

Command Name Type Description
basic.then/else.construct Definition provide program flow change based upon a boolean condition.
basic.matreadu Statement see 'matread'.
basic.dim Statement Declares a dimensioned array.
tcl.unlock-item Verb: Access Clears item locks in specified file.
basic.matwrite Statement Writes dimensioned array to file.
basic.matbuild Statement Converts dimensioned array to dynamic array.
basic.matparse Statement Converts dynamic array to dimensioned array.
basic.id.expression Definition An expression which derives an item-id.
statement.block Definition one or more statements that follow a Pick/BASIC decision-path related token such as, but not limited to, 'then', 'else', 'locked' and 'onerr'.
basic.writev Statement Writes one attribute.
basic.release Statement Releases group/item lock(s).
basic.file.variable Definition Defines file location from previous 'open' statement.
basic.default.files Definition used by any file-access Pick/BASIC statement when a specific file variable is not specified.
basic.array.dimensioned Definition a table where the contents of the elements can be altered (replaced) but the position of each element is fixed.
basic.writevu Statement Writes one attribute, without unlocking.
basic.statements Definition Definition of statements and functions.
basic.write Statement Writes dynamic array to file.
basic.locked Definition Takes 'locked' path when group/item lock encountered.
tcl.unlock-group Verb: Access Clears group locks.
basic.array.references Definition Referencing arrays.

User Comments

What do you think?

Share your experience or ask a question by using the form below.

Login to leave your comments.