matread Statement

The matread statement reads the specified item from the optionally specified file.var, or if not specified, the default file.var, and stores one attribute per element in the dimensioned array.

Syntax

matread array.var from {file.var,} ID.exp {locked statement.block} {then|else statement.block}

Description

This statement can optionally be written matread or read. If mat is omitted, a matrix read can be determined by the definition of the variable, array.var. 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 clauses and specifies the statements to execute if the item is locked when the read is attempted. The locked clause can be used in conjunction with a then or else clause, but not both.

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

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

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

WARNING

Using a matread from a program that is called from dictionary item is not recommended.

 

NOTE

  • 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 functions properly while the last array element remains unreferenced.

Example(s)

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.

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"

See Also

() Reserved Characters, > Relational Operator, Array References, Array Variable, Arrays, begin work Statement, Default File Variables, delete() Function, extract() Function, file Statement, File Variable, ID Expression, locked Clause, mat Statement, matbuild Statement, matparse Statement, matread Statement, matreadu Statement, matwrite Statement, open Statement, read Statement, readv Statement, release Statement, replace() Function, Statement Blocks, Statements and Functions, system() Function, then/else Statement Blocks, u001c User Exit, unlock-group Command, unlock-item Command, write Statement, writev Statement, ritevu Statement