See Also: Transactions and DDOs, Lock, Unlock, DF_LOCK_TIMEOUT
To maintain data integrity in multi user systems by updating record buffer data for any changes made by other users since the data was first brought into the buffers, and to prevent further changes by other users until an unlock command has been executed. This command is usually not used when working with Data Dictionaries.
Reread [{table} … {table}]
table is the logical name, or filelist number, used to identify the table.
When a reread command is executed, an internal lock command is executed, preventing changes to all tables opened by the program. Then reread updates all active records in the buffers for any changes which may have been made to the database (by other users) since the data was first brought into the buffers by the user of the program, unless tables have been named in the command. If tables have been named, then only the buffers for the named database tables are updated (whether their buffers are active or not).
All database tables opened by the program are locked, and remain so until a following unlock command. The records in the buffers for Database tables vendor and customer are updated for any changes since the disk was last read.
In a database table for which FILE_LOCK_TYPE is set to DF_LOCK_TYPE_NONE, Reread does not refresh the buffer unless Reread is used with an argument naming the table.
Whether you specify tables or not, reread will lock all tables opened by the program except for those opened read_only or alias (see Alias_File). The lock remains in effect until an unlock command is executed.
Reread
In this example, all database tables opened by the program are locked, and all active record buffers are updated.
This command:
Reread animals
is the same as:
Lock
Find eq animals By Recnum
The following program fragment updates a counter (animals.confirmed) in a table in a manner which will not be corrupted by concurrent activities of other users.
Get AnimalName to animals.name
Find ge animals.name
If (Found) Begin
Reread animals
Increment animals.confirmed
Save animals
Unlock
End
The Reread command is required to make sure that the value of animals.confirmed that is incremented is in fact the current value of that field. If the starting value pulled into the buffer had been 102 and other users had raised it to 110, incrementing without a reread would put it back to 103, since it would have started out from 102 (the original value in the buffer).
The interval between reread and unlock is critical. In the example above, there are commands (increment and save) in that interval. Both of these commands must be in that interval, but neither requires keyboard input. It is essential that no command requiring keyboard input be placed in this interval, because all database tables opened by the program are locked, and any delay, or potential for delay, could deprive all other users of use of the affected table(s). As shown above, the lock interval would be a fraction of a second, imperceptible even to other users actively saving to the same database.
The following program fragment will get the next available invoice number from a system table in a manner which cannot be corrupted by concurrent activities of other users who also are getting invoice numbers from the same system table:
Reread SysTable
Increment SysTable.invnum
Saverecord SysTable
Unlock
The invoice number generated from SysTable.invnum is "assigned" to the user who "drew" it. Another user will never get the same number. For this reason, where continuous accountability of invoice numbers is required, the number either should be drawn at the moment the invoice is actually issued, or if drawn prior to that point, must be assigned to a voided invoice in the event the invoice is not issued, rather than simply discarded.
An Unlock command must follow each reread command with as few intervening commands as possible, and no intervening commands which require keyboard input (entry_item, inkey, or input).
Records that have been re-read may be updated without fear of disrupting other users because the table is locked after the reread.
Always reread before you put any changes in the record buffer. If you reread after making a change to a column, the column value on disk will overwrite the changed value, unless the column is an indexed one, in which case an Error Status 82 (Edited record not saved) will be triggered, the buffer will be cleared, and Error Status 25 (Record not found) will be triggered.
If the buffer of an explicitly named table (reread table) is inactive (clear, or recnum set equal to zero), an Error Status 25 (Record not found) will be triggered.
A Reread is not required when you are only creating new records. Other users cannot make changes to records which you have not yet created.
Where two or more locks or rereads are in effect at the same time, the same number of unlocks will be required to unlock the database. You can use the DF_TRAN_COUNT attribute to see how many locks are in effect.
Tables are locked in the order of their numbers in the filelist, and unlocked in the reverse of that order.
You can pass either the table's logical name or table number (in the filelist) to the reread command.