HP 3000 Manuals HP 3000 Manuals
FREAD
INTRINSIC NUMBER 2
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.
SHARED ACCESS. 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
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 Figure 4-7, 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).
_________________________________________________________________________
| |
| $CONTROL MAIN=JEXAMPL2 |
| <<*********************************************************>> |
| <<* *>> |
| <<* EXAMPLE 2 *>> |
| <<* READ A KSAM FILE SEQUENTIALLY *>> |
| <<* *>> |
| <<*********************************************************>> |
| INTEGER FILNUM; |
| INTEGER ERRORCODE,LENGTH; |
| BYTE ARRAY FILNAME(0:9):="JEXAMFIL "; |
| ARRAY MESSAGE(0:35); |
| ARRAY INPUT(0:39); |
| ARRAY OUTPUT(*)=INPUT; |
| BYTE ARRAY KEYVALUE(0:7:="000-0000"; |
| INTEGER KEYLENGTH"=8; |
| INTEGER KEYLOCATION:21; |
| INTEGER RELOP:2; |
| INTRINSIC FOPEN,FCLOSE,FREAD,FFINDBYKEY,READ,PRINT, |
| FCHECK,FERRMSG,PRINT'FILE'INFO,TERMINATE; |
| <<*************************>> |
| <<* OPEN THE KSAM FILE *>> |
| <<*************************>> |
| FILENUM:=FOPEN(FILNAME,3,200); <<OPEN KSAM FILE |
| FOR EXCLUSIVE READ-ONLY ACCESS>> |
| IF FILNUM=0 |
| THEN BEGIN <<CANNOT OPEN KSAM FILE>> |
| MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; |
| PRINT(MESSAGE,-21,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>>|
| FERRMSG(ERRORCODE,MESSAGE,LENGTH); <<GET MESSAGE STRING>> |
| PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
| MOVE MESSAGE:="LIST IN LAST NAME SEQUENCE"; |
| PRINT(MESSAGE,-26,0); |
| <<**********************************>> |
| <<* READ KSAM IN NAME SEQUENCE *>> |
| <<**********************************>> |
| L1: |
| FREAD(FILNUM,INPUT,-72); <<READ SEQUENTIALLY BY PRIMARY KEY>> |
| IF > |
| THEN GO TO L2; <<GO TO ALTERNATE KEY ORDER>> |
_________________________________________________________________________
Figure 4-7. FREAD Example
__________________________________________________________________________
| |
| IF < |
| THEN BEGIN |
| MOVE MESSAGE:="ERROR OCCURRED WHILE READING INPUT"; |
| PRINT(MESSAGES,-34,0); |
| TERMINATE; |
| END; |
| <<***********************************************>> |
| <<* WRITE THE DATA JUST READ FROM KSAM FILE *>> |
| <<***********************************************>> |
| PRINT(OUTPUT,-72,0); |
| <<***********************************>> |
| <<* GO BACK TO GET ANOTHER RECORD *>> |
| <<***********************************>> |
| GO TO L1; |
| <<*********************************************************>> |
| <<* READ DATA FROM KSAM FILE IN TELEPHONE # SEQUENCE *>> |
| <<*********************************************************>> |
| L2: |
| FFINDNYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP); |
| MOVE MESSAGE:="LIST IN TELEPHONE NO. SEQUENCE"; |
| PRINT(MESSAGE,-30,0); |
| L3: |
| FREAD(FILNUM,INPUT,-72); <<READ SEQUENTIALLY BY ALTERNATE KEY>> |
| IF > |
| THEN BEGIN <<END OF FILE>> |
| FCLOSE(FILNUM,0,0); <<CLOSE THE KSAM FILE>> |
| IF <> THEN |
| BEGIN <<CLOSE UNSUCCESSFUL>> |
| MOVE MESSAGE:"CANNOT CLOSE THE KSAM FILE": |
| PRINT(MESSAGE,-29,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENSTH;<<GET MESSAGE STRING>>|
| PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| END; |
| TERMINATE; |
| END; |
| IF < |
| THEN BEGIN |
| MOVE MESSAGE:="ERROR OCCURRED WHILE READING INPUT"; |
| PRINT(MESSAGE,-34,0); |
| TERMINATE; |
| END; |
__________________________________________________________________________
Figure 4-7. FREAD Example (continued)
______________________________________________________________________
| |
| <<***********************************************>> |
| <<* WRITE THE DATA JUST READ FROM KSAM FILE *>> |
| <<***********************************************>> |
| PRINT(OUTPUT,-72,0); |
| IF <> |
| THEN BEGIN <<ERROR OCCURRED WHILE PRINTING OUTPUT>> |
| MOVE MESSAGE,="ERROR OCCURRED WHILE PRINTING OUTPUT"; |
| PRINT(MESSAGE,-36,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENGTH),<<GET MESSAGE STRING>>|
| PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
| <<************************************>> |
| <<* GO BACK TO GET ANOTHER RECORD *>> |
| <<************************************>> |
| GO TO L3; |
| END; |
| |
| Output from Program Execution: |
| |
| LIST IN LAST NAME SEQUENCE |
| CARDIN RICK 578-7018 11100 WOLFE ROAD CUPERTINO CA. 94053 |
| ECKSTEIN LEO 287-5137 5303 STEVENS SANTA CLARA CA. 95050 |
| HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022 |
| NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087 |
| PASBY LINDA 295-1187 TOWN & CNTRY VILLAGE SAN JOSE CA. 94102 |
| ROBERT GERRY 259-5535 12345 TELEGRAPH BERKELEY CA. 90871 |
| SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053 |
| TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234 |
| WESTER ELDER 287-4598 1256 KINGFISHER SUNNYVALE CA. 43098 |
| WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234 |
| LIST IN TELEPHONE NO. SEQUENCE |
| HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022 |
| ROBERT GERRY 259-5535 12345 TELEGRAPH BERKELEY CA. 90871 |
| WESTER ELDER 267-4598 1256 KINGFISHER SUNNYVALE CA. 43098 |
| ECKSTEIN LEO 287-5137 5303 STEVENS SANTA CLARA CA. 95050 |
| SEELY HENRY 293-4220 1144 LEBERTY EL CERRITO CA. 94053 |
| PASBY LINDA 295-1187 TOWN & CNTRY VILLAGE SAN JOSE CA. 94102 |
| WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234 |
| CARDIN RICK 578-7018 11100 WOLFE CUPERTINO CA. 94O53 |
| NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087 |
| TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234 |
| |
| END OF PROGRAM |
______________________________________________________________________
Figure 4-7. FREAD Example (continued)