FFINDBYKEY

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 Title not available, 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.

Figure 4-2 FFINDBYKEY Example

 



<<******************************************************>>

<<*                                                    *>>

<<*               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); 

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:

FFINDBYKEY

Technical documentation

» Table of Contents

PARAMETERS

CONDITION CODES

SPECIAL CONSIDERATIONS

USING FFINDBYKEY

USING APPROXIMATE KEYS

USING PARTIAL (GENERIC) KEYS

SHARED ACCESS