FREADBYKEY

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 Title not available, 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 “Positioning the Pointers” 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>

Figure 4-8 FREADBYKEY Example

 



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

            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

FREADBYKEY

Technical documentation

» Table of Contents

FUNCTIONAL RETURN

PARAMETERS

CONDITION CODES

USING FREADBYKEY

SHARED ACCESS

DUPLICATE KEYS