| MATPARSE | Index Level | MATREADU |
| Syntax | {MAT}READ{U} array.variable FROM {file.variable,} id.expression {LOCKED statement.block} {THEN | ELSE statement.block} |
| Category | BASIC |
| Type | Statement |
| 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". 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. |
| Options | |
| See Also | THEN | ELSE statement.block MATREADU DIM unlock-item MATWRITE MATBUILD MATPARSE id.expression statement.block WRITEV RELEASE file.variable default file variables dimensioned array WRITEVU statements & functions WRITE LOCKED unlock-group array references READ u001c MAT SYSTEM list-locks (R83) array.variable DELETE FILE ( ) |
| 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 |
| Warnings |
If the number of attributes read in the item is less than the dimensioned array size, the trailing array elements are assigned a null string value.
If more attributes are present in the item read than elements in the previously dimensioned array, then the last array element contains the extra attributes, with each attribute delimited by an attribute mark. Everything works fine while the last array element remains unreferenced. Repeated executions of {mat}readu statements will NOT implicitly unlock item locks. In this case, using the "release" statement is recommended. |
| Compatibility | D3 7.0 AP R83 |
| MATPARSE | Index Level | MATREADU |