HP 3000 Manuals

KSAM/3000 Reference Manual

FSPACE 

INTRINSIC NUMBER 5

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

MPE/iX 5.0 Documentation