 |
» |
|
|
|
|  | |
Reads a logical record in key sequence from a KSAM file to the user's stack. I IV LA IV
lgth:=FREAD(filenum,target,tcount);
|
FREAD reads a logical record in sequential order by key value. The primary key determines key sequence unless a prior call to FFINDN (or FFINDBYKEY or FREADBYKEY) has specified an alternate key. If the file is opened without KSAM access (FOPEN aoptions bit 3=1), then FREAD reads the data file as if it were not a KSAM file. The record read by FREAD depends on the current position of the logical record pointer. FUNCTIONAL RETURN | |
The FREAD intrinsic returns a positive integer value to lgth showing the length of the information transferred. If the tcount parameter in the FREAD call is positive, the positive value returned represents a word count; if the tcount parameter is negative, the positive value returned represents a byte count. PARAMETERS | |
- filenum
integer by value (required) A word identifier supplying the file number of the file to be read. - target
logical array (required)An array to which the record is to be transferred. This array should be large enough to hold all of the information to be transferred. - tcount
integer by value (required) An integer specifying the number of words or bytes to be transferred. If this value is positive, it signifies the length in words; if it is negative, it signifies the length in bytes; if it is zero, no transfer occurs. If tcount is less than the size of the record, only the first tcount words or bytes are read from the record. If tcount is larger than the size of the physical record, transfer is limited to the length of the physical record.
CONDITION CODES | |
- CCE
The information was read. - CCG
The logical end-of-data was encountered during reading. - CCL
The information was not read because an error occurred.
SPECIAL CONSIDERATIONS | |
Split stack calls permitted. USING FREAD | |
The FREAD intrinsic reads the record at which the logical record pointer is currently positioned. When a file is opened, this pointer is positioned to the beginning of the first record in primary key sequence. That is, it is positioned to the record containing the lowest value in those bytes containing the primary key. Following each FREAD , the record pointer remains positioned at the record just read. Any subsequent FREAD call positions the pointer to the next sequential record in ascending key sequence. Also, if an FREAD call is followed by an FUPDATE and another FREAD, the pointer is advanced before the second FREAD. A key other than the primary key can be selected as the basis of the sequential read by executing FFINDN, FFINDBYKEY, or FREADBYKEY before executing the FREAD intrinsic. When the logical end-of-data is encountered during reading, the CCG condition code is returned to your process. The end-of-data occurs when the last logical record of the file is passed . Note that the last logical record of a KSAM file is the record containing the maximum key value in the key on which the key sequence is based. In order to be sure that you are reading the record you want, you should call either FLOCK or FCONTROL with control code 7 before calling FREAD. FLOCK prevents other users from changing or deleting the record until the file is unlocked with FUNLOCK. FCONTROL with control code 7 clears the data and key block buffers so that the record must be read directly from the file, and also transfers the latest control information from the file to the extra data segment. Because the logical pointer is part of this control information, you can be sure that is is set correctly by calling FCONTROL with code 7. FCONTROL uses less overhead than FLOCK, but it cannot prevent other users from modifying the record you want to read while you are calling FCONTROL. FLOCK, on the other hand, fully protects the information to be read from changes by other users but requires more time. Because FREAD is a pointer-dependent procedure, you must call one of the procedures that position the pointer before calling FREAD. When you are reading the file in sequential key order, it is important to lock the file before calling the procedure that positions the pointer, and to leave it locked while you are reading the file. This insures that the pointer is not moved by another user between the call that positions the pointer and FREAD or between sequential FREAD calls. (Refer to Table 4-2 “Positioning the Pointers” for a list of the pointer-independent and pointer-dependent procedures.) For example, the following sequence of calls guarantees that you will read the file in sequential order starting with a specified key:
FLOCK
FFINDBYKEY <----------------------------sets logical pointer
FREAD loop <------------------read records in key sequence
FUNLOCK
|
Note that FREAD advances the record pointer only if it is followed by another FREAD (or an
FUPDATE followed by another FREAD). A single call to FREAD leaves the pointer at the record just read; a subsequent call to FREAD causes the pointer to be positioned to the next record in key sequence. This permits sequential reading of the file without calling a pointer-independent procedure before each FREAD. Also, in order to allow sequential updates, the pointer is advanced for each FREAD in an FUPDATE/FREAD sequence with no other intervening calls (see FUPDATE discussion). In the example in Title not available, FREAD is used first to read the KSAM file in sequence by primary key. When the end of data is reached, the program uses FFINDBYKEY to specify an alternate key and FREAD then reads the file in sequence by that altemate key. When the end of data is reached again, the file is closed. (Note that this program is opened for exclusive access so that locking is not necessary). |
Printable version
