The commit function is called to
indicate to the domain that the application wants to commit
instances of classes and associations to non-volatile storage.
This in turn causes NVS::insert to be called
flushing to NVS elements from a list of instances and links that
were queued when modified.
A return value of 0 indicates success.
integer commit( | void); |
The restore function is called by the
architecture during bring-up after a power cycle. The
restore function causes the classes contained
in non-volatile storage to be read from store and written to the
instance collection list.
A return value of 0 indicates success.
integer restore( | integer class); |
Many NVS domain functions return an integer return code. The values that the return code can take are outlined in the following listing:
#define NVS_RETURN_SUCCESS 0 /* All is well. */
#define NVS_ERROR_BAD_OPEN -1 /* Could not open file. */
#define NVS_ERROR_ITEM_LONG -2 /* Data item is too long. */
#define NVS_ERROR_BAD_SEEK -3 /* Could not seek correctly. */
#define NVS_ERROR_BAD_WRITE -4 /* File did not write correctly. */
#define NVS_ERROR_NOT_FOUND -5 /* Did not find searched record. */
#define NVS_ERROR_BAD_READ -6 /* Read incorrect length of data. */
#define NVS_ERROR_NO_ROOM -7 /* Not enough room for insert. */
#define NVS_ERROR_LENGTH -8 /* Length not correct. */
This can be found in the generated
NVS_bridge.h file. A positive value is used
to indicate the length of a buffer.
Function checksum provides a
mathematical redundancy check on the integrity of the contents of
the non-volatile store (NVS). This mathematical algorithm and the
capabilities of the function are supplied by the implementor of the
internals of the NVS module.
checksum provides an integer return code
representing an integrity check on the contents of the NVS.
integer checksum( | integer first, |
integer second); |
The defrag function coalesces deleted
records together and written records together. This allows for
small fragments of free storage to be collected into a single
contiguous free piece of storage. This function will typically
take significant time to run. This time is a function of the
specific non-volatile storage technology.
defrag provides an integer return
code as listed above.
integer defrag( | void); |
delete searches the store for an item
matching the input and deletes it. Deleted items cannot be
retrieved from NVS in future invocations of select
or search. delete
chooses the item to erase based on two combinations of input
arguments. If the delete is called with a key
and a type, then the item in the NVS matching these key and type
arguments is erased. Otherwise, if non-null data is given, the data
and type arguments are used to identify the item to delete. When
found, the item is marked as deleted and will not be readable from
the store.
delete provides an integer return code
as listed above.
integer delete( | integer key, |
| integer length, | |
| string pointer, | |
integer type); |
The format function erases the
non-volatile store (NVS). It is only to be called when it is
desired that a new NVS be cleared and prepared for writing for the
first time.
integer format( | void); |
The initialize function resets the
internal counters of the non-volatile store. (Note that these
internal counters are the responsibility of the implementor of the
internal of NVS and can contain information about the amount of
data being used, etc.) No application/user data is written or
changed in the store. This function is called automatically at
power-up to prepare the store for access.
initialize provides an integer return
code as listed above.
integer initialize( | void); |
The insert function adds items to the
store. There are four input arguments. The first,
key is the lookup key to the item. In the
case of instance data, this key is a unique identifier for the item
being inserted (added to the store). length
is an integer representation of the length of the data byte
sequence pointed to by pointer. type is the
class type (instance or link) in integer form. The data pointed to
by pointer is not modified. If the record
being inserted already exists in the non-volatile store, the
existing record will be updated. A return code provides status on
the insert.
integer insert( | integer key, |
| integer length, | |
| string pointer, | |
integer type); |
next provides a way to cycle through
reading each item from the store one at a time. This
function returns the item currently being pointed to by the cursor
(maintained inside the store). The buffer space available on the
calling side is passed in as the length argument. If sufficient
space is available in the buffer, the next item data will be copied
into the given buffer pointed to by pointer. The length of the
written data is returned as the return value. Also returned are
the values of the key and type. The initialize function resets the
internal cursor to the first item in the store.
integer next( | integer * key, |
| integer length, | |
| integer * pointer, | |
integer * type); |
The select function searches the store
for a specific item with a key and type matching those given as
input arguments. If a record is found that matches, it is copied
into the data buffer pointed to by pointer. The length argument
provides the amount of buffer space available on the calling side.
The actual length of the returned record (if one is returned) is
provided in the return value. The data behind the pointer argument
is modified with the data found in the non-volatile store.
integer select( | integer key, |
| integer length, | |
| string * pointer, | |
integer type); |
The space_available function returns an
integer representing the number of bytes not being used in the
store. This number of bytes will actually hold fewer bytes due to
the overhead of item meta-data (key, type, etc).
integer space_available( | void); |
The space_total function returns the
overall size in bytes of the non-volatile store.
integer space_total( | void); |
The space_used function returns the
number of bytes currently written in the store.
integer space_used( | void); |
The update function searches for a
record in the store the same way that select
does. When (and if) a record is found, the new data of length
length pointed to by pointer is written into the store over the
existing item. Since insert will perform an
update when a record exists, it is more often used than
update. No arguments are modified calling
this function.
update provides an integer return code
as listed above.
integer update( | integer key, |
| integer length, | |
| string pointer, | |
integer type); |
Function version provides an integer
return value indicating the version of the data and/or format
of the non-volatile store (NVS).
This versioning algorithm and the
capabilities of the function are supplied by the implementor of the
internals of the NVS module. Two input arguments are used to
provide flexible utility.
version provides an integer return code
representing the version of the NVS (contents).
integer version( | integer first, |
integer second); |