FFINDN

Positions the logical record pointer to relative record number according to key sequence.

 

            IV      DV        IV 

   FFINDN(filenum,number,keylocation)

When FFINDN is executed, it positions the KSAM logical record pointer to the record whose relative record number is specified in the parameter number. Records are numbered from the record with the lowest key value in the key that starts at keylocation in each record. Record numbering starts with zero unless the flagword in the FOPEN ksamparam parameter specifies that record numbering starts with 1, or the FIRSTREC parameter in the >BUILD command is set to 1.

PARAMETERS

filenum

integer by value (required)

A word identifier supplying the file number of the file to be positioned.

number

double by value (required)

Relative record number counting from the first logical record in the file. Record numbers start with zero or one depending on the record numbering scheme specified at file creation; the lowest numbered record applies to the record with the lowest value in the specified key field. A negative record number positions the file pointer to the record with the smallest key value.

keylocation

integer by value (required)

The relative byte location in the record of the key to be used. The first byte is byte 1. If keylocation is set to zero, the primary key is assumed.

CONDITION CODES

CCE: Request granted.
CCG: The requested position was beyond the logical end-of-file.
CCL: Request denied because an error occurred.

SPECIAL CONSIDERATIONS

Split stack calls permitted.

USING FFINDN

When you specify the relative record number, it is important not to confuse this number with the chronological record number, the number of the record as it is stored in the file. To illustrate, assume a file in which records have been stored in chronological order from the beginning of the file (BOF). Each record has a key starting in byte 3 that contains a name. The relative record number is based on the value of this key, not the relative location of the record in the file.

For example:

 

   FFINDN(FILNUM,4D,3)

This call positions the logical record pointer (as shown in Figure 4-3 File Position with FFINDN) to record number 4 of the key at location 3. Note that record number 4 is the fifth record in the sequence of key values:

ABLE: relative record 0D
BAKER: relative record 1D
CHARLIE: relative record 2D
DOG: relative record 3D
EASY: relative record 4D
FOX: relative record 5D

If you want to position the chronological record pointer to the relative record number in chronological sequence from the beginning of the file, you can use the intrinsic FPOINT, discussed later in this section. Chronological order is the order in which records are written. In Figure 4-3 File Position with FFINDN, record number 4 in key order, to which FFINDN positioned the file pointer, is also record number 2 in chronological order.

Figure 4-3 File Position with FFINDN

Note that FFINDN is useful to reset the pointer to an alternate key. For example, when you open the file, the primary key is selected by default. If you want to select another key starting in location 23 and position to the first record in key sequence, you can use the following command:

 

   FFINDN(FILNUM,-1,23)

SHARED ACCESS

If you use FFINDN to position the pointer before calling another procedure that reads or updates the file in a shared environment, you must call FLOCK before calling FFINDN. Then, after performing the read or update operation, you should unlock the file so other users can access it. If you lock the file after calling FFINDN, another user can change the pointer position without your program being aware of it.