read statement

The read statement reads an item as a dynamic array and stores the item as a string. Each attribute is automatically an element of the dynamic array variable and can be referenced with the appropriate intrinsic functions.


read{u} dyn.array from {file.var,} ID.exp{locked statement{s}}
[then|else statement.block]


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.

If file.var is not specified, the default file variable is used.

The else clause is taken when the item is not on file. The then clause 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 readu is attempted. The locked clause can be used in conjunction with a then or else clause.
Note: For locks on FSI files: If the locked clause is not present, you can specify the amount of time a process waits to attempt another read of a locked item. You can do this by creating the updLockTimeout registry string value in the HKEY_LOCAL_MACHINE/SOFTWARE/RocketSoftware/D3/CurrentVersion/D3FSI/ registry key. If this value is not explicitly specified, the default locked item read retry timeout is 500 milliseconds.

The readu form tests if the item is already locked and locks the item if it is not. The item lock set by readu prevents the item from being read using the readu statement or updated by other processes while the lock is set.

If the readu 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(0) contains the port number that has the item locked. For backwards compatibility, system(0) in the locked clause also returns the port number that has the item locked.

The item lock is only released by a release, delete, or write statement. Items can be updated without being unlocked by using the writeu 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.

Note: If an item is read with a read statement and later updated with a write statement, it is possible that another process could read the same item and update it. The readu statement performs a lock to avoid this situation.


This example opens the customer file and prompts the operator for the customer’s item-ID. If the read is successful, the customer name in attribute 1 displays.

open ’customer’ to customer.file else stop 201, ’customer’
item = ’’
crt ’enter customer-ID ’:
input item-ID
read item from customer.file,item-ID else stop 202,item-ID
print ’the customer name is ’:item<1>

This example uses the file statement to bind the customer file to this program. It prompts for the item-ID, reads the item, and prints the name. The file statement allows dictionary-type references to the read data item.

file customer
crt ’enter customer ID ’:
input item-ID
read customer from item-ID else stop 202,item-ID
print ’the customer name is ’:customer(name)

See also

locked clause