Dataman
Class DatamanIndex

java.lang.Object
  Dataman.DatamanIndex

public class DatamanIndex
extends java.lang.Object

This implements most of verbs of the Dataman Package. All master data file records are associated with an index. When a key is retrieved, it's associated data record is also retrieved and stored in the master data record array. Almost everything in Dataaman is done by referencing an index.

Field Summary

static int	AFTER Insert the new record after the current one in memory.
static int	BEFORE Insert the new record before the current one in memory.
static int	RDONLY Opens an index and related datafiles in read-only mode.
static int	UPDATE Opens and index an related datafiels in update mode.

Constructor Summary

DatamanIndex(java.lang.String name, int mode)
Define and open an index.

Method Summary

boolean	back() Retrieve the record preceeding the current one.
void	clear() Unlock the current database record.
void	delete() Delete the current database record.
java.lang.String	fileName() Return the name of the current data file.
boolean	forward() Retrieve the record following the current one.
boolean	get_current() Retrieve the record associated with the current key.
boolean	get_first() Retrieve the lowest order key and it's associated data record from the index.
java.lang.String	get_ixname() Return the String name of this index.
DatamanKey	get_key() Returns this index's current key
boolean	get_last() Retrieve the highest order key and it's associated data record from the index.
boolean	get_next() Retrieve the next higher order key and it's associated data record from the index.
boolean	get_prior() Retrieve the next lower order key and it's associated data record from the index.
boolean	get(DatamanField key) Lookup the named key an return it's associated data record.
boolean	get(DatamanKey key) Lookup the named key and return it's associated record.
boolean	get(java.lang.String key) Lookup the named key and return it's associated data record.
void	iclose() Close an open index.
void	include(DatamanField field) Include a new key into an index.
void	include(DatamanIndex idx, DatamanField field) Include a new key into an index.
void	include(DatamanIndex idx, java.lang.String key) Include a new key into an index.
void	include(java.lang.String key) Include a new key into an index.
void	insert(int fmt, int pos) Insert a new record in the databse.
boolean	protect() Lock the current database record.
boolean	remove(DatamanKey key) Remove the specified key from the index.
boolean	remove(java.lang.String key) Remove the specified key from the index.
boolean	restore() Restore the saved state of the index.
void	save() Save the current state of the index.
void	sort(DatamanField key) Add a key to an index.
void	sort(int i) Add a key to an index.
void	sort(java.lang.String key) Add a key to an index.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RDONLY

public static final int RDONLY

Opens an index and related datafiles in read-only mode.

See Also:

Constant Field Values

UPDATE

public static final int UPDATE

Opens and index an related datafiels in update mode.

See Also:

Constant Field Values

BEFORE

public static final int BEFORE

Insert the new record before the current one in memory.

See Also:

Constant Field Values

AFTER

public static final int AFTER

Insert the new record after the current one in memory.

See Also:

Constant Field Values

Constructor Detail

DatamanIndex

public DatamanIndex(java.lang.String name,
                    int mode)

Define and open an index. Name is the name of the index to open and mode is either of the constants DatamanIndex.UPDATE, or DatmanIndex.RDONLY.

Parameters:

name - - the index name to open

mode - - the open mode either RDONLY or UPDATE

Throws:

DatamanRuntimeException

Method Detail

iclose

public void iclose()

Close an open index. Any open index should be closed before it goes out of scope

Throws:

DatamanRuntimeException

get

public boolean get(DatamanKey key)

Lookup the named key and return it's associated record. The key to lookup is typically one returned by a prior call to DatamanIndex.get_key(), which returns the internal representation of the key. Since the index will allow duplicate keys, this will refer to a particular instance.

Parameters:

key - - the key to search for.

Returns:

true if the key was found, false if not.

Throws:

DatamanRuntimeException

get

public boolean get(java.lang.String key)

Lookup the named key and return it's associated data record. If the key is found in the index the associated data record is stored in master datarecord. Since the index may contain duplicate keys the lowest order matching key is retrieved.

Parameters:

key - - the key to search for.

Returns:

true if the key was found, false if not.

Throws:

DatamanRuntimeException

get

public boolean get(DatamanField key)

Lookup the named key an return it's associated data record. The string representation of the data field is used as the key. Since the index may contain duplicate keys the lowest order matching key is retrieved.

Parameters:

key - - the key to search for.

Returns:

true if the key was found, false if not.

Throws:

DatamanRuntimeException

get_next

public boolean get_next()

Retrieve the next higher order key and it's associated data record from the index.

Returns:

true if successful, false if the current key is the highest order in the index.

Throws:

DatamanRuntimeException

get_prior

public boolean get_prior()

Retrieve the next lower order key and it's associated data record from the index.

Returns:

true if successful, false if the current key is the lowest order in the index.

Throws:

DatamanRuntimeException

get_first

public boolean get_first()

Retrieve the lowest order key and it's associated data record from the index.

Returns:

true if successful, false if the index is empty.

Throws:

DatamanRuntimeException

get_last

public boolean get_last()

Retrieve the highest order key and it's associated data record from the index.

Returns:

true if successful, false if the index is empty.

Throws:

DatamanRuntimeException

get_current

public boolean get_current()

Retrieve the record associated with the current key. Because a key is not required for each record, and use of the forward an back methods, the current record may not be the one associated with the current key.

Returns:

true if successful, false if the key has been removed.

Throws:

DatamanRuntimeException

forward

public boolean forward()

Retrieve the record following the current one.

Returns:

true if successful, false if the current record is the last in the file.

Throws:

DatamanRuntimeException

back

public boolean back()

Retrieve the record preceeding the current one.

Returns:

true if successful, false if the current record is the first in the file.

Throws:

DatamanRuntimeException

protect

public boolean protect()

Lock the current database record. This function exerts a co-operative lock on the current data record. If the record is already protected it will sleep up to 500 msec before returning, during which the lock may still be exerted.

Returns:

true if the lock was exerted, false if already protected.

Throws:

DatamanRuntimeException

clear

public void clear()

Unlock the current database record. This function removes a co-operative lock on the current data record. It is an unconditional clear; it doesn't matter who exerted the lock, this will remove it.

Throws:

DatamanRuntimeException

delete

public void delete()

Delete the current database record. This has the side-effect of making any key pointing to the record invalid. When any attempt is made to retrieve a key pointing to a deleted record the key is removed from the index. Thus, it is best to explicitly remove all of a record's keys before deleting the record.

Throws:

DatamanRuntimeException

remove

public boolean remove(DatamanKey key)

Remove the specified key from the index. The key to remove is typically one returned by a prior call to DatamanIndex.get_key(), which returns the internal representation of the key. Since the index will allow duplicate keys, this will refer to a particular instance to be removed.

Parameters:

key - - the key to remove from the index.

Returns:

true if the key was removed, false if no matching key was found

Throws:

DatamanRuntimeException

remove

public boolean remove(java.lang.String key)

Remove the specified key from the index. Since the index will allow duplicate keys, this will remove the first matching instance of the key

Parameters:

key - - the key to remove from the index.

Returns:

true if the key was removed, false if no matching key was found

Throws:

DatamanRuntimeException

save

public void save()

Save the current state of the index. This will allow the user to restore to that state later.

Throws:

DatamanRuntimeException

restore

public boolean restore()

Restore the saved state of the index. This will restore the current index to a saved state. This is important because the MFRP doesn't necessarily refer to the record that the current key does, so it behaves quite differently from get_current().

Returns:

true if the state was successfully restored, else false.

Throws:

DatamanRuntimeException

sort

public void sort(java.lang.String key)

Add a key to an index. This method is used only in sort routines. It associates the current work record with the passed in key, and stores that key in the index.

Parameters:

key - - the key to sort into the index.

Throws:

DatamanRuntimeException

sort

public void sort(DatamanField key)

Add a key to an index. This method is used only in sort routines. It associates the current work record with the string representation of the passed in DataField, and stores that key in the index.

Parameters:

key - - the key to sort into the index.

Throws:

DatamanRuntimeException

sort

public void sort(int i)

Add a key to an index. This method is used only in sort routines. It associates the current work record with the string representation of the passed in integer, and stores that key in the index.

Parameters:

i - - the key to sort into the index.

Throws:

DatamanRuntimeException

insert

public void insert(int fmt,
                   int pos)

Insert a new record in the databse. This takes the current record pointed at in this index, and will put a insert record either following or preceeding it into the database. That new (blank) record will become the current one.

Parameters:

fmt - - the record format number of the new record.

pos - - either DatamanIndex.BEFORE or DatamanIndex.AFTER

Throws:

DatamanRuntimeException

include

public void include(DatamanIndex idx,
                    java.lang.String key)

Include a new key into an index. The symantecs of this is a little tricky. This will take the record pointed to in the index that is the argument, associate it with the key, and put the named key into 'this' index.

Parameters:

idx - - the source index.

key - - the new key to include

Throws:

DatamanRuntimeException

include

public void include(DatamanIndex idx,
                    DatamanField field)

Include a new key into an index. The symantecs of this is a little tricky. This will take the record pointed to in the index that is the argument, associate it with the key, and put the named key into 'this' index.

Parameters:

idx - - the source index.

field - - the key to include.

Throws:

DatamanRuntimeException

include

public void include(java.lang.String key)

Include a new key into an index. This will take the current record pointed to in this index, associate it with the key, and put the named key into 'this' index.

Parameters:

key - - the new key to include.

Throws:

DatamanRuntimeException

include

public void include(DatamanField field)

Include a new key into an index. This will take the current record pointed to in this index, associate it with the string representation of the data field, and put this named key into 'this' index.

Parameters:

field - - the new key to include.

Throws:

DatamanRuntimeException

get_ixname

public java.lang.String get_ixname()

Return the String name of this index.

Returns:

String

get_key

public DatamanKey get_key()

Returns this index's current key

Returns:

DatamanKey

fileName

public java.lang.String fileName()

Return the name of the current data file. This returns the name of the data file that contains the current record.

Returns:

String