Reviewed and revised July 2020; see History
READ #ch, recvar
reads a record from a random file without locking.
READL #ch, recvar
establishes an exclusive lock on the record before reading if LOKSER enabled. If the lock cannot be granted, the operation either waits or returns error 37, depending on whether the WAIT'RECORD clause was specified on the OPEN statement. To release the lock, you just either use a WRITE or UNLOKR statement.
READ'READ'ONLY #ch, recvar
an unlocked read, with no option to subsequently write.
READ var1{, var2...}
reads individual data fields from the DATA statement pool.
Parameters
ch (Num) [in]
specifies the previously-opened file channel.
recvar (X) [out]
variable to receive the entire record. Typically it is an unformatted MAP1 level variable or structure containing sub fields arranged to match the layout of the data record. See example below. It may also be a Dynamically Sized Variables (X,0), in which case you would subsequently need to copy it to a structure in order to break out the individual fields. See History.
Comments
The record number for the read operation is established by setting the record number variable specified in the OPEN statement. Since the OPEN statement and subsequent READ statements may be widely separated, care must be taken that the record number variable remains in scope. See MX_FLSET for details related to reading from a file within an SBX. See XREAD and XWRITE for variations of READ and WRITE which specify an explicit record number for the operation, eliminating the interdependence on the external record number variable.
Record numbers start at 0 by default, but may be changed (typically to 1) using the FILEBASE statement.
Typically the size of the recvar should match the record size specified in the OPEN statement. However, if not, the READ operation works in the same was as an assignment statement, with the data read from the disk acting as the source expression. Thus if recvar is too small, the data is simply truncated to fit. If recvar is too large, the extra bytes are either left alone, assuming recvar is an unformatted type, i.e. X variable, or set to null, if recvar is a string.
Example
DEFSTRUCT ST_CUS ! 64 byte customer record definition
MAP2 ID,S,6
MAP2 NAME,S,30
MAP2 PHONES(2)
MAP3 OFFICE,S,10
MAP2 CELL,S,10
MAP2 ZONE,B,2
MAP2 BALANCE,F
ENDSTRUCT
MAP1 CUS,ST_CUS ! customer record instance
MAP1 CUSRECNO,F ! record #
OPEN #1, "CUST.DAT", RANDOM'FORCED, 64, CUSRECNO
CUSRECNO = 9 ! rec # 9
READL #1, CUS ! lock and read rec
CUS.BALANCE += 1 ! modify rec
WRITE #1, CUS ! write (and unlock) rec
See Also
History
2020 June, A-Shell 6.5.1684: READ, XREAD and ISAMA GET operations now work with dynamic X (X0) record variables, regardless of whether they are pre-initialized. Previously this only worked if the variable was pre-initialized to the size of the record.
