FPOINT

Sets the chronological (and logical) record pointer for a KSAM file.

 

                 IV     DV 

     FPOINT(filenum,recnum);

The FPOINT intrinsic sets the chronological record pointer for a KSAM disc file. The file may contain either fixed-length or variable-length records. When the next FREADC request is issued for this file, the record to which FPOINT positioned the pointer is read. Note that this intrinsic positions the logical record pointer as well as the chronological pointer.

PARAMETERS

filenum

integer by value (required)

A word identifier supplying the file number of the file on which the pointer is to be set.

recnum

double by value (required)

A positive double integer representing the record number of a fixedlength file or the word pointer to a variable-length file. Word numbering always starts with word 0, whereas record numbering starts with 0 or 1 depending on how the file was created. In either case, the number is in terms of the chronological (consecutive) order in which the data file records were written. It has no relation to the logical record pointer that is based on key values.

CONDITION CODES

CCE

Request granted.

CCG

Request denied. The chronological record pointer position is unchanged. Positioning was requested at a point beyond the physical end-of-file.

CCL

Request denied. The chronological record pointer position is unchanged because of one of the following:

Invalid filenum parameter.
recnum parameter specified a record marked for deletion.
A key value for specified record not found in key file.

SPECIAL CONSIDERATIONS

Split stack calls permitted.

USING FPOINT

The FPOINT intrinsic is generally used prior to an FREADC intrinsic in order to read a record without reference to the key file. FPOINT sets the chronological record pointer to the position in the file specified by recnum. A subsequent FREADC reads the record (or portion of a record) to which the pointer is positioned. It then sets the pointer to the next record that was written to the file in chronological order,

For example, in order to read the 39th record written to the file identified by FILENUM:

 

   FPOINT(FILNUM,39D); <---------------------set pointer

   FREADC(FILNUM,BUFFER,COUNT); <------------read record

Following execution of FREADC, the contents of the 39th record are transferred to the array BUFFER and the chronological pointer remains positioned at record 39. A flag is set so that the next call to FREADC moves the pointer forward to the beginning of record 40, the next record in chronological order.

Note that the combination of FPOINT followed by an FREADC intrinsic is identical in effect to the FREADDIR intrinsic that positions to a chronological record number and then reads that record. The FGETINFO intrinsic can be used to recover the chronological record number of the record most recently accessed. (Refer to FGETINFO and FREADDIR for more information on accessing records by chronological record number.)

Since the FPOINT intrinsic positions the logical pointer as well as the chronological pointer, it can be used prior to an FUPDATE or FREAD intrinsic to identify the record to be updated or read. FPOINT sets the logical record pointer to a key in the key file that points to the record it located by record number. The key is by default the primary key for that record, though an alternate key is used if such a key was selected by a prior call to FFINDBYKEY or FREADBYKEY.

SHARED ACCESS

When you use FPOINT to position the chronological pointer in a shared access environment, you must lock the file with a call to FLOCK before calling FPOINT. You should leave the file locked until you have completed any calls that read or update the file in chronological sequence, and then call FUNLOCK to unlock the file for the other users. This insures that the pointer is not moved by other users between the pointer-independent procedure FPOINT and any subsequent pointer-dependent procedure. (Refer to Table 4-2 “Positioning the Pointers” for a list of the pointer-independent and pointer-dependent procedures.)