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

writevu Statement