HP 3000 Manuals HP 3000 Manuals
FREADBYKEY
INTRINSIC NUMBER 304
Reads a logical record randomly from a KSAM file to the user's data
stack.
I IV LA IV BA IV
lgth:=FREADBYKEY(filenum,target,tcount,keyvalue,keylocation);
FREADBYKEY reads a logical record selected by key value. The record to
be read must have the same value as keyvalue in the bytes that start at
keylocation. Following execution, the logical record pointer is still
positioned to the record in the file located through the value of the key
at keylocation.
FUNCTIONAL RETURN
The FREADBYKEY intrinsic returns a positive integer value to lgth showing
the length of the information transferred. If the tcount parameter in
the FREADBYKEY 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 randomly.
target logical array (required)
An array to which the record is to be transferred. It
should be large enough to hold all the information read.
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 negative, it signifies the
length in bytes; if zero, no transfer takes place.
If tcount is less than the size of the record, only the
first tcount words are read from the record. If tcount
is larger than the physical record size, transfer is
limited to the length of the physical record.
keyvalue byte array (required)
A byte array containing the value that will determine
which record is read. The first record found with this
identical value in the key identified by keylocation is
the record read.
keylocation integer by value (required)
The relative byte location in the record of the key
whose value determines which record is read. The first
byte is numbered 1; if a value of zero is specified, the
primary key is used.
CONDITION CODES
CCE The information specified was read.
CCG The logical end-of-data or beginning-of-data was
encountered during the read.
CCL The information was not read because an error occured,
such as an input/output error, or the key could not be
located.
USING FREADBYKEY
The intrinsic FREADBYKEY allows you to locate and read a single record
according to a specified key value, Like FFINDBYKEY, it defines the key
that is to be used for determining record sequence and, following
execution, remains positioned at the same record. Unlike FFINDBYKEY,
FREADBYKEY cannot specify a key length different from the full length of
the key at creation, nor can it search for approximate key values.
In the example in Figure 4-8, the keylocation and keyvalue values are
read from the standard input device. As each is read, it is printed to
test the read. The first set of values read into the word array INFOW
is:
01 ROBERT GERRY
\/\------------/
| |
%%keylocation%% %%keyvalue%%
The first two ASCII characters contain the keylocation; the characters
starting in byte 2 contain the keyvalue to be found at the specified
keylocation. Since keylocation is an integer parameter, the first two
bytes of the byte array INFO (equivalenced to the word array INFOW) must
be converted to a binary value. This is done with the statement:
KEYLOCATION:=BINARY(INFO,2);
The value to be used for keyvalue is contained in the byte array INFO
starting in the third byte (byte 2 numbered from byte 0). In the
declarations at the beginning of the program, the byte array KEYVALUE is
equivalenced to the portion of the byte array INFO that starts in byte 2.
The intrinsic FREADBYKEY can be called with the following statement:
FREADBYKEY(FILNUM,INPUT,-72,KEYVALUE,KEYLOCATION);
This locates and reads the first record with the value ROBERT GERRY in
the key located starting in byte 1 of the record. The program prints
this record and then returns to get the next pair of values input for
keyvalue and keylocation. When there are no more values in the input
file, the KSAM file is closed and the program terminates.
SHARED ACCESS. If you use FREADBYKEY to position the pointer for
subsequent calls that read or update the specified record, you should
lock the file with a call to FLOCK before calling FREADBYKEY. Then, after
calling the read or update procedure, you should unlock the file so other
users can access it. Locking the file before calling FREADBYKEY insures
that other users do not change the position of the pointer between the
call to FREADBYKEY and any subsequent procedure that depends on the
pointer position. (Refer to Table 4-2 for a list of the pointerpendent
procedures and also those that set the pointer.)
To illustrate, the following sequence of calls makes sure that the
correct record is updated:
FLOCK to lock the file
FREADBYKEY to position the pointer
FUPDATE to modify the record to which the pointer points
FUNLOCK to unlock the file for other users
DUPLICATE KEYS. FREADBYKEY always positions to the first key in a chain
of duplicate keys. If you want to read or update the remaining keys in a
duplicate key chain, you should use FREAD. For example, to update all the
records with a particular key, use the following code sequence:
FREADBYKEY to locate 1st key in chain of duplicates
FUPDATE update that record
---> FREAD read next sequential record
| <test if this is correct key value>
| FUPDATE update record
---- <return to read next record>
______________________________________________________________________
| |
| $CONTROL MAIN=JEXAMPL3 |
| <<*********************************************************>> |
| <<* *>> |
| <<* EXAMPLE 3 *>> |
| <<* READ A KSAM FILE RANDOMLY *>> |
| <<* *>> |
| <<*********************************************************>> |
| INTEGER FILNUM; |
| INTEGER ERRORCODE,LENGTH; |
| BYTE ARRAY FILNAME(0:9):="JEXAMFIL "; |
| ARRAY MESSAGE(0:35); |
| ARRAY INPUT(0:39); |
| ARRAY OUTPUT(*)=INPUT; |
| BYTE ARRAY INFO(0:35); |
| ARRAY INFOW(*)=INFO |
| BYTE ARRAY KEYVALUE(*)INFO(2); |
| INTEGER KEYLOCATION; |
| INTRINNSIC FOPEN,FCLOSE,FREAD,FREADBYKEY,READ,PRINT, |
| FCHECK,FERRMSG,BINARY,TERMINATE; |
| <<*********************************************************>> |
| <<* OPEN THE KSAM FILE *>> |
| <<*********************************************************>> |
| FILNUM:=FOPEN(FILNAME,3); <<OPEN THE KSAM FILE>> |
| 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>>|
| PRINTIMESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
| <<*********************************************************>> |
| <<* READ IN KEYVALUE AND KEYLOCATION INFOMATION *>> |
| <<*********************************************************>> |
| L1: |
| READ(INFOW,-36); |
| IF > |
| THEN BEGIN |
| FCLOSE(FILNUM,0,0); <<CLOSE THE KSAM FILE>> |
| IF <> THEN |
| BEGIN |
| MOVE MESSAGE:="CANNOT CLOSE THE KSAM FILE" |
| PRINT (MESSAGE,-26,0); |
______________________________________________________________________
Figure 4-8. FREADBYKEY Example
____________________________________________________________________________
| |
| FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> |
| FERRMSG(ERRORCODES;MESSAGE,LENGTH);<<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; |
| PRINT(INFOW,-36,0); <<TEST READ>> |
| KEYLOCATION;=BINARY(INFO,2); <<CONVERT FROM ASCII TO BINARY>> |
| <<*****************************************************>> |
| <<* READ KSAM ACCORDING TO KEYVALUE AND KEYLOCATION *>> |
| <<*****************************************************>> |
| FREADBYKEY(FILNUM,INPUT,-72,KEYVALUE,KEYLOCATION); |
| IF <> |
| THEN BEGIN <<ERROR OCCURRED IN FREADDBYKEY>> |
| MOVE MESSAGE:="ERROR OCCURRED IN FREADBYKEY"; |
| PRINT(MESSAGE,-28,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<GET MESSAGE STRING>> |
| PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| GO TO L1; |
| END; |
| <<************************************************>> |
| <<* WRITE THE DATA JUST READ FROM KSAM FILE *>> |
| <<************************************************>> |
| PRINT(OUTPUT,-72,0); |
| <<***********************************>> |
| <<* GO BACK TO GET ANOTHER RECORD *>> |
| <<***********************************>> |
| GO TO L1; |
| END; |
| |
| Output from Program Execution: |
| |
| 01ROBERT GERRY |
| ROBERT GERRY 259-5535 12345 TELEGRAPH AVE. BERKELEY CA. 90871 |
| 21287-5137 |
| ECKSTEIN LEO 287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050 |
| |
| END OF PROGRAM |
____________________________________________________________________________
Figure 4-8. FREADBYKEY Example (continued)