HP 3000 Manuals

KSAM/3000 Reference Manual

FFINDN 

INTRINSIC NUMBER 301

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)
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, 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.

MPE/iX 5.0 Documentation