READ

Reviewed and updated 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 (X,0) variable, 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 # 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 # 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 # for the operation, eliminating the interdependence on the external record # variable.

Record #'s 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