HP 3000 Manuals HP 3000 Manuals
FFINDBYKEY
INTRINSIC NUMBER 302
Positions record pointer to record located by a key value.
IV BA IV IV IV
FFINDBYKEY(filenum,keyvalue,keylocation,keylength,relop);
When FFINDBYKEY is executed, the logical record pointer is set to the
beginning of a record located by this intrinsic. The particular key is
defined by the keylocation parameter, The pointer is positioned to the
first record containing a key value that bears the relation specified by
relop to the value specified by keyvalue. A partial key can be specified
by a keylength value less than the defined key length. If, however, the
key type specified at file creation was numeric display or packed
decimal, a type where the sign is stored in the least significant byte,
partial keys cannot be specified.
FFINDBYKEY also positions the chronological pointer.
PARAMETERS
filenum integer by value (required)
A word identifier supplying the file number of the file
to be positioned.
keyvalue byte array (required)
A byte array containing a value that is used to locate
the record at which the pointer is positioned. The key
value in the record must be in the relation specified by
relop to the value in array keyvalue.
keylocation integer by value (required)
The keylocation parameter specifies the relative byte
location of the key being used. Bytes are numbered
starting with 1. If keylocation is zero, then the
primary key is used.
keylength integer by value (required)
This parameter specifies the length of the key in bytes.
If it equals zero, the entire key is used. If less than
the full key length (generic key), then only the length
specified here is used in the comparison with relop.
The keylength parameter must be equal to or less than
the full length of the key when the file was created.
For keys of type numeric display or packed decimal, the
full key length must be used.
relop integer by value (required)
A relational operator that specifies the relation of the
key value in the file to the value specified in
keyvalue. The record to which the file is positioned
will have this relation to keyvalue following execution
of FFINDBYKEY:
0 - equal
1 - greater than
2 - equal to or greater than
When relop is set to 1 or 2, the search is for an
approximate key.
CONDITION CODES
CCE Request granted.
CCG The requested position was beyond the logical
end-of-file or beginning of file.
CCL Request denied because an error occurred. The error
could be a disc input/output error; the relational
operator (relop) could not be satisfied; a keylength
less than the fulllength was specified for a key with
numeric display or packed decimal format; or a key is
not found in the key file when the relational operator
is equal.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FFINDBYKEY
The intrinsic FFINDBYKEY allows you to position the file to a record
containing a particular key value. Usually, you will do this in order to
read in ascending sequence from that particular record. If you simply
want to locate and read a single record, you should use FREADBYKEY.
In Figure 4-2, FFINDBYKEY is used to position the file to the record
containing the lowest value of an 8-byte alternate key in which a
telephone number is stored. After FFINDBYKEY positions the file to this
record, a series of FREAD statements read the records in ascending order
according to the value of the key specified by FFINDBYKEY. (Refer to
shaded portions of the program for the FFINDBYKEY declarations and
statements).
FFINDBYKEY can also be used prior to a call to FREADC in order to
position the chronological pointer to the record located by the specified
key.
USING APPROXIMATE KEYS. In order to find the lowest-valued telephone
number, keyvalue is set to the value "000-0000". The key to be searched
for this value is identified by its position in the record. In this
case, the alternate key containing the telephone number starts in byte
position 21, and keylocation is set to the value 21. The fulllength of
the key is specified in keylength as the value 8. In order to position
to the record whose alternate key value is equal to or greater than
"000-0000", the value of relop is set to 2.
When executed, FFINDBYKEY will locate the record with an 8-byte value
starting in byte 21 that is either equ"000-0000" or is the lowest value
greater "000-0000". Since the value "000-0000" is not a valid telephone
number, the value of relop could be set to 1 indicating the lowest value
greater than "000-0000". An error condition is returned if the value in
keyvalue cannot be located. For this reason, relop should not be set to
0 unless it is expected that the value being sought exists.
USING PARTIAL (GENERIC) KEYS. If the value of keylength is less than the
length of the key at creation, this allows a search for a partial
(generic) key. For example, assume a file with a 20- byte key starting
in byte 2 of each record. This key contains a name entered last name
first. If you want to find and read all records starting with the letter
"R" through the last record in sequence by key, you could assign the
following FFINDBYKEY values:
INTEGER FILNUM;
BYTE ARRAY FILNAME(0:9):="KSAMFILE ";
BYTE ARRAY KEYVALUE(0:4):="R";
INTEGER KEYLENGTH:=1;
INTEGER KEYLOCATION:=2;
INTEGER RELOP:=2;
:
INTRINSIC FOPEN,FCLOSE,FREAD,FWRITE,FFINDBYKEY;
:
FFINDBYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP)
When executed, FFINDBYKEY will position to the first record with a key
value whose first (leftmost) character is the letter "R". A subsequent
series of FREADs will read that record and position to the next record in
sequence by the same key.
SHARED ACCESS. If you use FFINDBYKEY to position the pointer before
calling another procedure to read or update the file in a shared
environment, you must call FLOCK to lock the file before calling
FFINDBYKEY. Then, after performing the read or update operation, you can
unlock the file. If you call FFINDBYKEY and then lock the file before an
operation that depends on the record pointer, another user could move the
pointer between the call to FFINDBYKEY and FLOCK.
____________________________________________________________________
| |
| <<******************************************************>> |
| <<* *>> |
| <<* 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,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>> |
| FEERMSG(ERRORCODE,MESSAGE,LENGTH); <<GET MESSAGE STRING>>|
| PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
| |
| <<*********************************************************>>|
| <<* READ DATA FROM KSAM FILE IN TELEPHONE # SEQUENCE *>>|
| <<*********************************************************>>|
| L2: |
| FFINDBYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP); |
| MOVE MESSAGE:="** LIST IN TELEPHONE NO. SEQUENCE"; |
| PRINT (MESSAGE,-33,0); |
____________________________________________________________________
Figure 4-2. FFINDBYKEY Example
_____________________________________________________________________________
| |
| 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,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; |
| END; |
| PRINT(OUTPUT,-72,0); |
| <<**********************************>> |
| <<* GO BACK TO GET ANOTHER RECORD *>> |
| <<**********************************>> |
| GO TO L3: |
_____________________________________________________________________________
Figure 4-2. FFINDBYKEY Example (continued)