# Section 8.10.1.5:
$FILE_CURSORS

###### abstract class $FILE_CURSORS

#### Formal Definitions

This abstract class defines a state component which is a set of all instantiations of objects of any class sub-typing from this class in addition to the vdm model types used wherever this class name is used. Note that SAME has to be an instantiated class, not an abstract one.

types
SAME = object_type ;
$FILE_CURSORS = set of object_type
state
multi : $FILE_CURSORS
inv multi_types ==
forall obj in set multi_types & sub_type($FILE_CURSORS,obj)

NOTE | See the important note about vdm state in the notes on vdm-sl usage in this specification.

This abstraction models a cursor which indicates a particular position in a very large storage file. It is defined in order to enable programs to handle large files for which there is insufficient space in computer system memory.

#### size

This feature provides the current size of the associated file.

error | : CARD

##### Formal Signature

size(self : SAME) res : CARD

##### Pre-condition

The pre-condition is vacuously true since the cursor cannot be created unless the file exists (see the cursor feature of the class BIN_FILE for example).

##### Post-condition

The result, in the absence of filing system errors, is the size of the associated file in octets.

This feature returns the size of the associated file. The value provided is the same as that which could be obtaines by enquiring of the file directly.

#### readable

This predicate returns true if and only if the associated file is readable. It provides the same answer as would be provided by a direct enquiry of the associated file.

readable | : BOOL

##### Formal Signature

readable(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the associated file is readable, otherwise false.

#### writable

This predicate returns true if and only if the associated file is writable. It provides the same answer as would be provided by a direct enquiry of the associated file.

writable | : BOOL

##### Formal Signature

writable(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the associated file is writable, otherwise false.

#### at_end

This predicate returns true if and only if the cursor is positioned at the end of the associated file.

at_end | : BOOL

##### Formal Signature

at_end(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the cursor is positioned at the end of the file.

#### position

This routine returns the current position of the cursor in the file in storage units.

position | : CARD

##### Formal Signature

position1(self : SAME) res : CARD

##### Pre-condition

This feature is defined irrespective of pre-condition.

##### Post-condition

post backward(self,position(self)) = 0

This feature provides the numeric value of the position of the cursor in the associated file based on an offset from the first position in the file which is position 0.

#### position

This feature is the writer routine corresponding to the above reader routine, enabling the cursor position in the associated file to be adjusted to the given offset from the beginning.

position | (
| at : CARD
| ) : SAME

##### Formal Signature

position(self : SAME, at : CARD) res : SAME

##### Pre-condition

pre at < size(self)

##### Post-condition

post position(self) = at
and (res = self)

This feature provides the facility to set a new current position of the cursor in the file to be the value given as an offset in storage units (number of octets) from the beginning of the file, returning the modified cursor resulting from this.

#### forward

This feature provides for relative positioning within a file from the current position to a new position count storage units (octets) nearer to the end of the file.

forward | (
| count : CARD
| ) : SAME

##### Formal Signature

forward(self : SAME, count : CARD) res : SAME

##### Pre-condition

pre position(self) + count < size(self)

##### Post-condition

post position(self) = position(self)~ + count
and (res = self)

This feature provides the facility to set a new current position of the cursor in the file to be the value given as an offset in storage units (number of octets) from the current position in the file, returning the modified cursor resulting from this.

#### backward

This feature provides for relative positioning within a file from the current position to a new position count storage units (octets) closer to the beginning of the file.

backward | (
| count : CARD
| ) : SAME

##### Formal Signature

backward(self : SAME, count : CARD) res : SAME

##### Pre-condition

pre position(self) >= count

##### Post-condition

post position(self) = position(self)~ - count
and (res = self)

This feature provides the facility to set a new current position of the cursor in the file to be the value given as an offset in storage units (number of octets) towards the beginning of the file from the current position, returning the modified cursor resulting from this.

#### skip

This feature provides a facility for skipping a given number of stored items (which need not all be of the same storage size). If there are insufficient items remaining in the file then void is returned instead of the modified cursor.

skip | (
| cnt : CARD
| ) : SAME

##### Formal Signature

skip(self : SAME, count : CARD) res : [SAME]

##### Pre-condition

Since the size of the underlying stored items may be variable, the pre-condition cannot guarantee that there will be no problem; any problem has to be detected dynamically during program execution (see post-condition below).

pre count > 0

##### Post-condition

If there are insufficient stored items remaining in the file beyond the current position then the return value is nil, otherwise the modified cursor repositioned as requested.

post (res = nil)
or (position(self) > position(self)~)

This feature provides a facility to move forward by a number of stored items in the file rather than in terms of storage units. Only where storage units are identical in storage size to the stored items will this be equivalent to the forward feature above.

#### error

This predicate may be used to determine whether there has been a problem relating to the file with which this cursor and buffer are associated.

error | : BOOL

##### Formal Signature

error(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature provides an indication whether some error in the program environment has affected the behaviour of the buffer since either creation or the most recent use of the clear feature defined below.

#### error_message

This feature provides a program environment dependent string indicating the nature of any error which may have been detected. Note that the message only refers to the latest error (if any) in an environment-defined manner.

error_message | : STR

##### Formal Signature

error_message(self : SAME) res : STR

##### Pre-condition

pre error(self)

##### Post-condition

post STR.size(res) > 0

This feature provides an indication whether some error in the program environment has affected the behaviour of the buffer since either creation or the most recent prior use of the clear feature defined below.

#### clear

This feature clears any error which may have occurred in the underlying file system in relation to the file which is associated with this cursor and buffer.

clear

##### Formal Signature

clear(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post not error(self)

This feature provides a way of clearing any error which may have occurred in relation to the file with which this cursor and buffer are associated.

| Language Index |  | Library Index |  | Input/Output Index

Comments or enquiries should be made to Keith Hopper . Page last modified: Friday, 3 March 2000. |