Sather Home Page

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.
Produced with Amaya