FSPACE

Spaces forward or backward on a file.


             IV           IV 
   FSPACE(filenum,displacement);

The FPSACE intrinsic allows you to space forward or backward a specified number of records on a KSAM file. The logical record pointer is repositioned by FSPACE in key sequence. The spacing is based on primary key sequence unless an alternate key has been specified in a prior call to FFINDN, FFINDBYKEY, or FREADBYKEY.

PARAMETERS

filenum

integer by value (required) A word identifier supplying the file number of the file on which spacing is to be done.

displacement

integer by value (required)

An integer indicating the number of logical records to be spaced over, relative to the current logical record pointer position. Record sequence for spacing is based on key sequence. A positive value signifies forward spacing, a negative value signifies backward spacing; zero signifies no spacing, but sets a flag so that the next call to FREAD does not move the logical record pointer before reading the record. The maximum positive value is 32767; the maximum negative value is -32768. The sign is optional for positive values.

CONDITION CODES

CCE: Request granted.
CCG: A logical end-of-file indicator was encountered during spacing. The logical record pointer is at the beginning-of-file if displacement was negative, to the end-of-file if displacement was positive.
CCL: Request denied because an error occurred.

SPECIAL CONSIDERATIONS

Split stack calls permitted.

USING FSPACE

If you want to space back a particular number of records in key sequence, you would specify a negative value for the displacement parameter in a call to FSPACE. To space forward, you would use a positive or unsigned integer as the displacement value. In either case, the displacement indicates the number of records to space over.

For example, suppose the following sequence of primary key values:


   ABLE 
   BAKER <---------- (2) pointer after FSPACE(FILNUM,-2); 
   CHARLIE 
   DOG <------------ (1) current record pointer 
   EASY 
   FOX <------------ (3) pointer after FSPACE(FILNUM,4);

Suppose the current record pointer is at the beginning of the record whose primary key contains the value DOG. To position the pointer to the beginning of the record with a primary key value BAKER:


   FSPACE(FILNUM,-2);

To space forward from the beginning of the record with BAKER as the key value to the beginning of the record with FOX as the key value:


   FSPACE(FILNUM,4);

Figure 4-12 File Position with FSPACE shows that the movement of the pointer bears no relation to the physical placement of records in the file.

Figure 4-12 File Position with FSPACE

POINTER POSITION

FSPACE checks a flag to determine whether to advance the pointer before it moves the pointer the specified number of records. If FSPACE follows a call that reads the file (FREAD or FREADBYKEY) then it advances the pointer to the record in key sequence following the record just read. After advancing the pointer, FSPACE positions the pointer as indicated in the call. If, on the other hand, FSPACE follows FPOINT, FFINDBYKEY, or FFINDN, the pointer remains positioned to the record specified in one of these calls until FSPACE is executed.

To illustrate, consider the following calls:


   FREAD <------------- read record, set flag to advance pointer 
   FSPACE(-1) <-------- test flag, advance pointer, then move pointer back 1 record 
   FREAD <------------- reread record just read

SHARED ACCESS

Because FSPACE is a pointer-dependent procedure (see Table 4-2 “Positioning the Pointers”), it is essential to lock the file before the call that determines the original pointer position, then call FSPACE, then call any other procedures that depend on where FSPACE positioned the pointer. When all the pointer-dependent procedures are complete, then unlock the file for other users. To illustrate:


   FLOCK <-------------- lock file 
   FFINDBYKEY <--------- locate a particular key ualue 
   FSPACE <------------- move pointer relative to that key position 
   FREAD <-------------- read the record to which pointer is positioned 
   FUNLOCK <------------ unlock the file