GEAS::DataObject
================

General Notes:
--------------
Each business object is presented as an instance of the GEAS::DataObject
class. This class includes methods to access the business class definition,
fields in the business class, and methods in the business class.


Parents:
--------
None


Attributes:
-----------

Name       : objectID
Type       : ObjectReference
Description: 

Name       : classname
Type       : string
Description: 

Name       : allfields
Type       : fieldlist
Description: 


Methods:
--------

Name:
    ofclass

Synopsis:
    boolean ofclass( in string classname )

Description:
    Determins if an object is an instance of a particular class. (ie, the
object is of that class, or derived from the class.

Arguments:
    classname : The name of the class to test.

Result:
    TRUE if it is, and FALSE if not.

Exceptions:
    ServerError

Example:

See Also:


Name:
    getLookupFieldOptions

Synopsis:
    LookupOptions getLookupFieldOptions( in string fieldname )

Description:
    Get an array containing one LookupOption instance for each possible
option for the lookup field. (In practise, this calls the method provided by
the Connection class, and if you do not already have a DataObject instance,
the simplest option is to call that directly.)

Arguments:
    fieldname : The lookup field to examine

Result:
    An array of LookupOption instances.

Exceptions:
    UnknownField
    NotLookupField
    Interrupted
    ServerError
    Locked
    TransactionNotInProgress

Example:

lst = obj.getLookupFieldOptions( "fieldname" );
for o in lst:
    print o.value

See Also:
    setLookupField
    Connection.getLookupFieldOptions()


Name:
    setLookupField

Synopsis:
    void setLookupField( in LookupOption setting )

Description:
    Perform the appropriate options (as described in the LookupOption
structure) to make the appropriate lookup field contain the desired data.
Ideally, an appropriate item from the arrary returned by the
getLookupFieldOptions() method would be used, avoiding the need for an
application developer to manually create the structure.

Arguments:
    setting - A structure describing the operations required to change a
              particular lookup field to a certain value.

Result:

Exceptions:
    UnknownField
    NotWriteable
    ServerError
    Interrupted,Locked
    TransactionNotInProgress

Example:

lst = obj.getLookupFieldOptions( "fieldname" );
obj.setLookupFieldOption( lst[3] ) # select the 4th entry

See Also:
    getLookupFieldOptions()
    Connection.getLookupFieldOptions()


Name:
    getField

Synopsis:
    string         getField    ( in string fieldname                       )

Description:
    Get the contents of a specific field, including basic data, lookup and
calculated fields, but not list, lookup, or method fields. (TODO: method
fields with 0 arguments will be automatically called and the result
returned.) Note that non-text fields (integers, dates, floating point, etc)
are still represented as ASCII strings, and the client is repsonsible for
any required conversion.

Arguments:
    fieldname - The name of the field to read

Result:
    A string containing the contents of the field.

Exceptions:
    UnknownField
    NotReadable
    ServerError
    Interrupted
    NullField
    NotDataField
    Locked
    TransactionNotInProgress

Example:

See Also:


Name:
    setField

Synopsis:
    void setField( in string fieldname , in string value )

Description:
    This sets a basic data field (and no other type). Note that non-text
fields (integers, dates, floating point, etc) are still represented as ASCII
strings.

Arguments:
    fieldname - the name of the field to set
    value     - A string containing the data to place in the field

Result:

Exceptions:

Example:

See Also:


Name:
    getReference

Synopsis:
    DataObject getReference( in string fieldname )

Description:
    Retrieve the object 'pointed to' by a reference field, using the rules
defined in the GCD file.

Arguments:
    fieldname - The fieldname 'containing' the object

Result:
    A reference to the appropriate object. This may be the CORBA NIL object
reference, if no object is found.

Exceptions:
    UnknownField
    NotReferenceField
    ServerError
    Interrupted
    Locked
    TransactionNotInProgress

Example:

See Also:


Name:
    getList

Synopsis:
    ObjectList getList( in string fieldname )

Description:
    Retrieve an array of the objects 'pointed to' by a list field, using the
rules defined in the GCD file.

Arguments:
    fieldname - The fieldname 'containing' the set of objects

Result:
    A reference to an ObjectList instance, containing references to all
appropriate objects. The list may have no elements, if there were no
matching objects.

Exceptions:
    UnknownField
    NotReferenceField
    ServerError
    Interrupted
    Locked
    TransactionNotInProgress

Example:

See Also:


Name:
    insert

Synopsis:
    void insert( in string fieldname , in DataObject obj )

Description:
    Adjust an object so that it will appear to be in a particular list field
in the container object. Note that if many different rules share a common
data field, this function may have unintended side effects. The object will
be inserted at an indeterminate position.

Arguments:
    fieldname - The name of the field that provides the list
    obj       - The object to insert in the list

Result:
    None

Exceptions:
    UnknownField
    NotListField
    WrongClass
    Interrupted
    NotWriteable
    ServerError
    Locked
    TransactionNotInProgress

Example:
    container.insert( "fieldname" , obj_to_add_to_list )

See Also:
    Adjust an object so that it will appear to be in a particular list field
in the container object. Note that if many different rules share a common
data field, this function may have unintended side effects. The object will
be inserted at an indeterminate position.


Name:
    setReference

Synopsis:
    void setReference( in string fieldname , in DataObject obj )

Description:
    Adjust an object so that it will appear to be in a particular reference
field in the container object. Note that if many different rules share a
common data field, this function may have unintended side effects.

A possible problem exists in some situations:

1) Container A has a reference to Object B, based on a field in B
2) the setReference() method is used to place Object C 'in' that field
3) The field in Object B is unchanged, and any reverse reference will still
   be in place.

Arguments:
    fieldname - The name of the field that provides the list
    obj       - The object to insert in the list

Result:
    None

Exceptions:
    UnknownField
    NotReferenceField
    WrongClass
    Interrupted
    NotWriteable
    ServerError
    Locked
    TransactionNotInProgress

Example:

See Also:


Name:
    flush

Synopsis:
    oneway void flush();

Description:
    No longer required.

Arguments:
Result:
Exceptions:
Example:
See Also:


Name:
    delete

Synopsis:
    void delete()

Description:
    Remove an object from the database. If any clients still retain a
reference to this object, they may still attempt operations on it, which
will always fail.

Arguments:
    None

Result:
    None

Exceptions:
    Interrupted
    ServerError
    Locked
    TransactionNotInProgress

Example:

See Also:


Name:
    callMethod

Synopsis:
    string callMethod( in string methodname , in Arguments args )

Description:
    Execute a method on the object server, associated with a particular
instance of a class.

Arguments:
    methodname : The name of the method to execute
    args       : An array containing the arguments to the method

Result:
    A string returned from the method. (Optionally an empty string, which
    is not the same as a NULL.)

Exceptions:
    ArgumentCount
    UnknownMethod
    InvalidArgument
    MethodError
    NullField
    ServerError
    Locked
    TransactionNotInProgress

Example:

See Also:

