Class RemoteBizobj

Read-only object reference to the Dabo Application object.  (dApp).

Determines if we are using a table that auto-generates its PKs. (bool)

When True (default), table and column names are enclosed with
quotes during SQL creation in the cursor.  (bool)

Returns the SQL statement automatically generated by the sql manager.

The base Dabo class of the object. Read-only.  (class)

Base key used when saving/restoring preferences  (str)

The friendly title of the cursor, used in messages to the end user. (str)

If this is a child bizobj, this represents the length of time in seconds that a
requery from parent.requeryAllChildren() will be ignored.  (int)

The class the object is based on. Read-only.  (class)

The dConnection object used to connect with the backend database.

Returns the current SQL that will be run, which is one of UserSQL or AutoSQL.

The title of the cursor. Used in resolving DataSource references. (str)

If set, treated as cursor real table name where DataSource
is an alias	for it. This allows coexistence of many business objects
with same data source on single form. (str)

Example:
	class StockBase(dBizobj):
		def initProperties(self):
			self.DataSourceName = "stock"

	class StockHigh(StockBase):
		def initProperties(self):
			self.DataSource = "stock_high"

	class StockLow(StockBase):
		def initProperties(self):
			self.DataSource = "stock_low"

Returns the structure of the cursor in a tuple of 6-tuples.

| 0: field alias (str)
| 1: data type code (str)
| 2: pk field (bool)
| 3: table name (str)
| 4: field name (str)
| 5: field scale (int or None)

This information will try to come from a few places, in order:

1. The explicitly-set DataStructure property
2. The backend table method

A dictionary specifying default values for fields when a new record is added.

The values of the dictionary can be literal (must match the field type), or
they can be a function object which will be called when the new record is added
to the bizobj.

Name of encoding to use for unicode  (str)

In the onNew() method, do we fill in the foreign key field specified by the
LinkField property with the value returned by calling the bizobj's 	getParentPK()
method? (bool)

Returns True if the current record is new and unsaved.

Name of field that is the PK. If multiple fields make up the key,
separate the fields with commas. (str)

Returns the last executed SQL statement.

Name of the field that is the foreign key back to the parent. (str)

Specifies which events to log.  (list of strings)

If the first element is 'All', all events except the following listed events
will be logged.
Event logging is resource-intensive, so in addition to setting this LogEvents
property, you also need to make the following call:

	>>> dabo.eventLogging = True

The name of the object.  (str)

Should new child records be added when a new parent record is added? (bool)

If this bizobj's parent has NewChildOnNew==True, do we create a record here? (bool)

Fields in the cursor to be ignored during updates

Reference to the parent bizobj to this one. (dBizobj)

Name of the field in the parent table that is used to determine child
records. If empty, it is assumed that the parent's PK is used  (str)

Reference to the Preference Management object  (dPref)

Represents a record in the data set. You can address individual
columns by referring to 'self.Record.fieldName' (read-only) (no type)

Do we requery child bizobjs after a save()? (bool)

Do we requery child bizobjs when navigating records? (bool)

Usually, you want to automatically requery children when the parent
RowNumber changes. However, there may be cases when you want to do 
that requery manually at the proper time instead for performance
reasons.

Setting this property to False will keep requeryAllChildren() from
automatically running after RowNumber changes.

When True, the cursor object runs its query immediately. This
is useful for lookup tables or fixed-size (small) tables. (bool)

Specifies whether a child bizobj gets requeried automatically.

When True (the default) moving the record pointer or requerying the
parent bizobj will result in the child bizobj's getting requeried
as well. When False, user code will have to manually call
child.requery() at the appropriate time.

After a requery, do we try to restore the record position to the same PK?

The number of records in the cursor's data set. It will be -1 if the
cursor hasn't run any successful queries yet. (int)

The current position of the record pointer in the result set. (int)

DEPRECATED. Equivalent to UserSQL. (str)

Specifies whether new unchanged records are saved.  (bool; default:False)

When calling the scan() function, this property determines if we
requery any child bizobjs for each row in this bizobj. The default is False,
as this has the potential to cause performance issues.  (bool)

After running a scan, do we attempt to restore the record position to
where it was before the scan (True, default), or do we leave the pointer
at the end of the recordset (False). (bool)

Do we scan the records in reverse order? (Default: False) (bool)

Reference to the cursor that handles SQL Builder information (cursor)

SQL statement to run. If set, the automatic SQL builder will not be used.

A dictionary mapping virtual_field_name to function to call.

The specified function will be called when getFieldVal() is called on
the specified virtual field name.

Occurs when the PrimaryBizobj of the dForm is being navigated.

As the user is rapidly calling dForm.next(), .prior(), etc., RowNavigation
events get raised. Your code should do some quick display updates to indicate
to the user that the record is changing, but the child bizobj's won't be 
requeried until after the navigation has ended.

See also RowNumChanged, which only occurs after the user has settled on a
record and has stopped navigating.

Occurs when the RowNumber of the PrimaryBizobj of the dForm has changed.

Add the passed child bizobj to this bizobj.

Child bizobjs stay in sync with their parent, getting requeried at the 
appropriate times. 

Add a field to the field clause.

Add a table to the sql statement. For 1-M joins, use
the addJoin() method. For M-M joins, use the
createAssociation() method.

Add an expression to the group-by clause.

Add SQL JOIN clause.

:param tbl: the name of the table to join with
:param exp: the join expression
:param joinType: examples: "LEFT", "RIGHT", "INNER", "OUTER"

Add the passed bizobj to this bizobj in a Many-to-Many relationship.

The reference will be stored, and the Parent reference of that bizobj
will be set to this. If mmPkCol is not specified, the KeyField for the mmBizobj
will be used for the relationship.

Add an expression to the order-by clause.

Add a filter expression to the where clause.

Hook method called after the changed records are canceled..

Hook method called after a record is changed.

This hook will be called after a successful save() or delete(). Contrast
with the afterSave() hook which only gets called after a save(), and the
afterDelete() which is only called after a delete().

Hook method called after the child bizobjs are requeried.

This hook is called after the underlying cursor object is created.
The crs argument will contain the reference to the newly-created
cursor.

Hook method called after a record is deleted.

Hook method called after all child records are deleted.

Hook method called after navigating to the next record.

Subclass hook. Called after the object's __init__ has run fully.
Subclasses should place their __init__ code here in this hook, instead of
overriding __init__ directly, to avoid conflicting with base Dabo behavior.

Hook method called after navigating to the last record.

Hook method called after a new record is added.

Use this hook to change field values of newly added records. If
you change field values here, the memento system will catch it and
prompt you to save if needed later on. If you want to change field
values and not trigger the memento system, override onNew() instead.

Hook method called after navigating to the next record.

Hook method called after the record pointer moves.

Hook method called after navigating to the prior record.

Hook method called after the cursor is requeried.

Hook method called after the current record is saved..

Hook method called after all the the changed records are saved..

Hook method called after the parent cursor changes.

Hook method called after a field's value has been set.

Your hook method needs to accept two arguments:

	| -> fld : The name of the changed field.
	| -> row : The RowNumber of the changed field.

If row is None, this is the common case of the change happening
in the current row.

Note that this hook will only fire if the new field value is different
from the old.

Hook method called after the RowNumber property is set.

Appends the rows in the passed dataset to this bizobj's dataset. No checking
is done on the dataset columns to make sure that they are correct for this bizobj;
it is the responsibility of the caller to make sure that they match. If invalid data is
passed, a dException.FieldNotFoundException will be raised.

Diffs are dicts in the format:

{hashval: (DataSource, KeyField, [changes])}

		where 'changes' is a list of dicts; one for each changed row in
		the bizobj. Each row dict has the following key/value pairs:

KeyField: pk value
ColumnName: (origVal, newVal)
Column2Name: (origVal, newVal)
...
		
		The 'diff' dict we receive can have 1 or two keys. One that will always
		be present is the hashval for this bizobj. If this bizobj has related child
		bizobjs, and they have changes, there will be a 'children' key that will
		contain a list of one diff for each child bizobj with changes.

		If this is the primary bizobj called from the web server, the 'primary'
		parameter will be true, meaning that this bizobj will handle transactions.
		

Automatically bind any on*() methods to the associated event.

User code only needs to define the callback, and Dabo will automatically
set up the event binding. This will satisfy lots of common cases where
you want an object or its parent to respond to the object's events.

To use this feature, just define a method on<EventName>(), or	if you
want a parent container to respond to the event, make a method in the
parent on<EventName>_<object Name or RegID>().

For example::
	
	class MyButton(dabo.ui.dButton):
		def onHit(self, evt):
			print "Hit!"

	class MyPanel(dabo.ui.dPanel):
		def afterInit(self):
			self.addObject(MyButton, RegID="btn1")

		def onHit_btn1(self, evt):
			print "panel: button hit!"

When the button is pressed, you'll see both 'hit' messages because of
auto event binding.

If you want to bind your events explicitly, you can turn off auto event
binding by calling::

	 dabo.autoBindEvents = False

This feature is inspired by PythonCard.

Hook method called before the changed records are canceled..

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before the child bizobjs are requeried.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before the underlying cursor object is created.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before all child records are deleted.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before navigating to the next record.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Subclass hook. Called before the object is fully instantiated.
Usually, user code should override afterInit() instead, but there may be
cases where you need to set an attribute before the init stage is fully
underway.

Hook method called before navigating to the last record.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before a new record is added.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before navigating to the next record.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before the record pointer moves.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before navigating to the prior record.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before the cursor is requeried.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before the current record is saved..

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before all the changed records are saved..

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Hook method called before the RowNumber property is set.

Subclasses can put in additional code to run, and/or return a non-empty
string to signify that the action should not happen. The contents
of the string will be displayed to the user.

Attempts to begin a transaction at the database level, and returns
True/False depending on its success.

Bind a dEvent to a callback function.

Bind a sequence of [dEvent, callback] lists.

Returns an iterator that moves the bizobj's record pointer from
the first record to the last, and returns a dict of the columns/values
of the record for the current iteration. If you pass 'reversed=True',
the iterator will go in reverse order, from the last record to the first.


Note that the bizobj will remain on the last (or first, if reverse()
is True) record after the iteration is complete unless you call this
with restorePointer=True.

Returns an iterator that moves the bizobj's record pointer from
the first record to the last, and returns the current record number.
If you pass 'reversed=True', the iterator will go in reverse order,
from the last record to the first.

Note that the bizobj will remain on the last (or first, if reverse()
is True) record after the iteration is complete unless you call this
with restorePointer=True.

This controls if a child requery is needed when a parent is requeried.

Cancel all changes to the current record and by default all children.

Two hook methods will be called: beforeCancel() and afterCancel(). The
former, if it returns an error message, will raise an exception and not
continue cancelling the record.

Cancel all changes made in all rows, including by default all children
and all new, unmodified records.

Creates a copy of the current record and adds it to the dataset. The KeyField
is not copied.

Attempts to commit a transaction at the database level, and returns
True/False depending on its success.

Create a many-to-many association. Generally it is better to use the 'addMMBizobj()'
method, but if you want to set this manually, use this instead of defining the JOINs.

:param mmOtherTable: the name of the table for the other half of the MM relation
:param mmOtherPKCol: the name of the PK column in the mmOtherTable
:param assocTable: the name of the table holding the association between the two
:param assocPKColThis: the name of the column in the association table for this PK
:param assocPKColOther: the name of the column in the association table for the other PK 

Create the cursor that this bizobj will be using for data, and optionally store it
in the dictionary for cursors, with the passed value of 'key' as its dict key.
For independent bizobjs, that key will be None. If creating a cursor that will not
be used as a data source for this bizobj, as when creating many-to-many
cursors, pass False for the 'addToCursorCollection' parameter.

Subclasses should override beforeCreateCursor() and/or afterCreateCursor()
instead of overriding this method, if possible. Returning any non-empty value
from beforeCreateCursor() will prevent the rest of this method from
executing.

Returns XML representing the data set. If there are child bizobjs,
the data for the related child records will be nested inside of the
parent record; this nesting can go as many levels deep as there are
child/grandchild/etc. bizobjs.

You must define and create the connection in this method. Otherwise
an error will be raised. Pass the connection information to setConnectionParams();
if you are using a .cnxml file, pass that in the 'cxnfile' parameter; otherwise, use
the various connection setting params to define the connection.
NOTE: You must use a SINGLE-CONNECTION .cnxml file; if multiple connections
are defined, there is no way for the bizobj to know which one you want to use.

Delete the current row of the data set.

Delete all rows in the data set.

Delete all children associated with the current record without
deleting the current record in this bizobj.

Escape special characters in SQL strings.

Escapes any single quotes that could cause SQL syntax errors. Also
escapes backslashes, since they have special meaning in SQL parsing.
Finally, wraps the value in single quotes.

Execute the sql on the cursor. Dangerous. Use executeSafe instead.

Execute the passed SQL using an auxiliary cursor.

This is considered 'safe', because it won't harm the contents of the
main cursor.

Expire the requery cache so that a subsequent self.Parent.requeryAllChildren()
will fetch records from the backend instead of using the cached records.

If recurse is True, the cache in the child bizobjs will be expired, too.

This is called by the form when a control that is marked for field-
level validation loses focus. It handles communication between the
bizobj methods and the form. When creating Dabo apps, if you want
to add field-level validation rules, you should override fieldValidation()
with your specific code.

This takes a field name, an expression, and an optional operator, and applies that
to the current dataset. The original dataset is preserved; calling removeFilter() will
remove the last filter applied to the bizobj. If the current record is in the filtered
dataset, that record will still be current; if it is filtered out, the current row will
be row 0.
If the operator is specified, it will be used literally in the evaluation instead of the
equals sign, unless it is one of the following strings, which will be interpreted
as indicated:
	
	| eq, equals: =
	| ne, nequals: !=
	| gt: >
	| gte: >=
	| lt: <
	| lte: <=
	| startswith, beginswith: fld.startswith(expr)
	| endswith: fld.endswith(expr)
	| contains: expr in fld

Allows you to filter by any valid Python expression.

Use the field alias names, for example::
    
	biz.filterByExpression('cust_name[0].lower() = 'a')

where cust_name is a field alias name in this record.

Move to the first record of the data set.

Any child bizobjs will be requeried to reflect the new parent record. If
there are no records in the data set, an exception will be raised.

Wrap a date or date-time value in the format
required by the backend.

Wrap up any value(int, long, string, date, date-time, decimal, none)
for use to be in a query.

Return the fully qualified name of the object.

Given a DataSource, finds the ancestor (parent, grandparent, etc.) of
this bizobj that has that DataSource. If no such ancestor exists, returns None.

Returns a list of row numbers for which isChanged() returns True. The
changes may therefore not be in the record itself, but in a dependent child
record. If includeNewUnchanged is True, the presence of a new unsaved
record that has not been modified from its defaults will suffice to mark the
record as changed.

Returns a dictionary of bizobj references and the results of
getRecordStatus() on each changed row. Use to easily inspect 
the current	dirty records in the hierarchy.

Return a reference to the child bizobj with the passed dataSource.

Return a tuple of the child bizobjs.

Get a dict that is keyed on the hash value of this bizobj, with the value
being  a list of record changes. Default behavior is to only consider the
current row; you can change that by passing allRows=True. Each changed
row will be present in the diff, with its PK and any columns whose values
have changed. If there are any related child bizobjs, their diffs will be
added to the dict under the key 'children' so that they can be processed
accordingly.

Get the entire data set encapsulated in a list.

If the optional	'flds' parameter is given, the result set will be filtered
to only include the specified fields. rowStart specifies the starting row
to include, and rows is the number of rows to return.

Gets the structure of the DataSource table. Returns a list
of 3-tuples, where the 3-tuple's elements are:

	| 0: the field name (string)
	| 1: the field type ('I', 'N', 'C', 'M', 'B', 'D', 'T')
	| 2: boolean specifying whether this is a pk field.

Gets the structure of the DataSource table. Returns a list
of 3-tuples, where the 3-tuple's elements are:

	| 0: the field name (string)
	| 1: the field type ('I', 'N', 'C', 'M', 'B', 'D', 'T')
	| 2: boolean specifying whether this is a pk field.

Given a field name, returns its Python type, or None if no
DataStructure information is available.

Returns the field type definitions as set in the cursor.

Returns the current field clause set in the backend.

Returns a tuple of all the field names in the cursor.

Return the value of the specified field in the current or specified row.

Return a dict of the field/value pairs in the current or specified row.

Returns the current from clause set in the backend.

Returns the current group-by clause set in the backend.

Returns the current join clause set in the backend.

Returns the current limit clause set in the backend.

Returns the current limit clause set in the backend.

Returns the current order-by clause set in the backend.

Return the value of the PK field.

Return the parameters to send to the cursor's execute method.

This is the place to define the parameters to be used to modify
the SQL statement used to produce the record set. Normally if you have
known parameters, you would simply call setParams(<param tuple>).
But in cases where the parameter values need to be dynamically calculated,
override this method in your subclass to determine the tuple to return.

Return the value of the parent record on which this bizobj is dependent. Usually this
is the PK of the parent, but can be a non-PK field, if this bizobj's ParentLinkField is
not empty.

Return the value of the parent bizobjs' PK field. Alternatively,
user code can just call self.Parent.getPK().

Returns a dictionary of property name/value pairs.

If a sequence of properties is passed, just those property values
will be returned. Otherwise, all property values will be returned.
The sequence of properties can be a list, tuple, or plain string
positional arguments. For instance, all of the following are
equivilent::

	print self.getProperties("Caption", "FontInfo", "Form")
	print self.getProperties(["Caption", "FontInfo", "Form"])
	t = ("Caption", "FontInfo", "Form")
	print self.getProperties(t)
	print self.getProperties(\*t)

An exception will be raised if any passed property names don't
exist, aren't actual properties, or are not readable (do not have
getter functions).

However, if an exception is raised from the property getter function,
the exception will get caught and used as the property value in the
returned property dictionary. This allows the property list to be
returned even if some properties can't be evaluated correctly by the
object yet.

Returns a dictionary containing an element for each changed
field in the specified record (or the current record if none is specified).
The field name is the key for each element; the value is a 2-element
tuple, with the first element being the original value, and the second
being the current value.

Returns the SQL statement currently set in the backend.

Occasionally it is useful to be able to run ad-hoc queries against
the database. For these queries, where the results are not meant to
be managed as in regular bizobj/cursor relationships, a temp cursor
will allow you to run those queries, get the results, and then dispose
of the cursor.

If you send no arguments, you'll get a cursor to use how you want, like::

	cur = self.getTempCursor()
	cur.UserSQL = "select count(*) as count from invoices where cust_id = ?"
	cur.requery((883929,))
	invoiceCount = cur.Record.count

But you can also simplify by sending the sql and params in the call::

	cur = self.getTempCursor("select count(*) as count...", (883929,))
	invoiceCount = cur.Record.count

Note that if you send params, the cursor will be requeried even if
the requery arg is False.

Returns the current where clause set in the backend.

Returns the backend's SQL format for creating queries that are based
on matching words in a given column.

Return True if the passed PK value is present in the dataset.

Hook for subclasses. User code should do custom event binding
here, such as::
	
	self.bindEvent(dEvents.GotFocus, self.customGotFocusHandler)
	

Hook for subclasses. User subclasses should set properties
here, such as::
	
	self.Name = "MyTextBox"
	self.BackColor = (192,192,192)
	

Return True if at least one record in the current record set
has been changed.

Return True if data has changed in this bizobj and any children.

Only the current record is checked. Call isAnyChanged() to
check all records.

Returns True/False, depending on whether this bizobj's connection
is remote or not.

Return True if data has changed in the current row
of this bizobj, without any children.

Move to the last record of the data set.

Any child bizobjs will be requeried to reflect the new parent record. If
there are no records in the data set, an exception will be raised.

Search for a value in a field, and optionally move the record pointer to the first
matching record. Returns the True or False, depending on whether the value was found.

If runRequery is True, and the record pointer is moved, all child bizobjs
will be requeried, and the afterPointerMove() hook method will fire.

This is very similar to the seek() method, with two main differences: there
is no concept of a near-match; either the value is found or it isn't; the return
value is a boolean indicating if the match was found, not the matching RowNumber.

Runs a lookup in the specified field for the desired value. If
found, returns the PK for that record. If not found, a new record is
created with the 'field' column populated with 'val', and the new
record's PK is returned. None of this affects the current dataset.

Creates an association in a M-M relationship. If the relationship
already exists, nothing changes. Otherwise, this will ensure that
both values exist in their respective tables, and will create the 
entry in the association table.

Associates the value in the 'other' table of a M-M relationship with the
current record in the bizobj. If that value doesn't exist in the other
table, it is added.

Adds association records so that the current record in this bizobj is associated
with every item in listOfValues. Other existing relationships are unaffected.

Removes all associations between the current record and the associated
M-M table.

Removes the association between the current record and the specified value
in the 'other' table of a M-M relationship. If no such association exists,
nothing happens.

Removes the association between the current record and every item in 'listOfValues'
in the 'other' table of a M-M relationship. If no such association exists,
nothing happens.

Given a relationship, returns the values associated with the current
record. 'listOfFields' can be either a single field name, or a list
of fields in the associated table.

Adds and/or removes association records so that the current record in this
bizobj is associated with every item in listOfValues, and none other.

Move to the row with the specified pk value, or raise RowNotFoundException.

Move to the specified row number.

Create a new record and populate it with default values. Default
values are specified in the DefaultValues dictionary.

Move to the next record of the data set.

Any child bizobjs will be requeried to reflect the new parent record. If
there are no records in the data set, an exception will be raised.

Returns the value that was in the specified field when it was last fetched
from the backend. Used to determine if the current value has been modified.

Hook called when the last record has been deleted from the data set.

Called when a new record is added.

Use this hook to add additional default field values, or anything else
you need. If you change field values here, the memento system will not
catch it (the record will not be marked 'dirty'). Use afterNew() if you
instead want the memento system to record the changes.

Hook method called after successfully saving a new record.

Calls the backend's pre-processing routine for improving efficiency
of filter expressions. If the backend does not have this capability,
nothing is done.

Move to the prior record of the data set.

Any child bizobjs will be requeried to reflect the new parent record. If
there are no records in the data set, an exception will be raised.

Send the event to all registered listeners.

If uiEvent is sent, dEvents.Event will be able to parse it for useful
information to send along to the callback. 

Additional arguments, if any, are sent along to the constructor	of the
event. While this feature exists so that UI-lib event handlers can pass
along information (such as the keystroke information in a key event), user
code may pass along additional arguments as well, which	will exist in the
event.EventData dictionary property.

In most cases, user code should call raiseEvent() with
the event class (dEvents.Hit, for example) as the only parameter.

Remove all child bizobjs.

Remove the most recently applied filter.

Remove all applied filters, going back to the original data set.

Removes the specified bizobj from a Many-to-Many relationship. If no such
relationship exists, nothing happens.

Replaces the value of the specified field with the given value
or expression. All records matching the scope are affected; if
no scope is specified, all records are affected.

'valOrExpr' will be treated as a literal value, unless it is prefixed
with an equals sign. All expressions will therefore be a string
beginning with '='. Literals can be of any type.

Requery the data set.

Refreshes the data set with the current values in the database,
given the current state of the filtering parameters.

Requery each child bizobj's data set.

Called to assure that all child bizobjs have had their data sets
refreshed to match the current master row. This will normally happen
automatically when appropriate, but user code may call this as well
if needed.

Note: children will only be requeried if their cache hasn't expired
yet. If you want to force all children to requery at the next opportunity,
you should call self.expireCache() before calling self.requery() or
self.requeryAllChildren().

Attempts to rollback a transaction at the database level, and returns
True/False depending on its success.

Save any changes that have been made in the current row.

If the save is successful, the saveAll() of all child bizobjs will be
called as well if saveTheChildren is True (the default).

Save changes to all rows in the bizobj, and (by default) the children.

Iterate over all records and apply the passed function to each.

Set self.exitScan to True to exit the scan on the next iteration.

If self.ScanRestorePosition is True, the position of the current
record in the recordset is restored after the iteration.

If self.ScanRequeryChildren is True, any child bizobjs will be requeried
for each row in the bizobj. Only use this if you know the size of the data
involved will be small.

You may optionally send reverse=True to scan the records in reverse
order, which you'll want to do if, for example, you are deleting
records in your scan function. If the reverse argument is not sent,
self.ScanReverse will be queried to determine the behavior.

Returns value from 'func' called in the last iteration.

Move the record pointer to each changed row, and call func.

If allCursors is True, all other cursors for different parent records will
be iterated as well.

If includeNewUnchanged is True, new unsaved records that have not been
edited from their default values will be counted as 'changed'.

If you want to end the scan on the next iteration, set self.exitScan=True.

Records are scanned in arbitrary order. Any exception raised by calling
func() will be passed	up to the caller.

Iterate over the specified rows and apply the passed function to each.

Set self.exitScan to True to exit the scan on the next iteration.

Search for a value in a field, and move the record pointer to the match.

Used for searching of the bizobj's cursor for a particular value in a
particular field. Can be optionally case-sensitive.

If 'near' is True, and no exact match is found in the cursor, the cursor's
record pointer will be placed at the record whose value in that field
is closest to the desired value without being greater than the requested
value.

If runRequery is True, and the record pointer is moved, all child bizobjs
will be requeried, and the afterPointerMove() hook method will fire.

If sort is True (the default), then we seek to the first matching value
without sorting first. 

If incremental is True (default is False), then we only compare the first
characters up until the length of val.

Returns the RowNumber of the found record, or -1 if no match found.

If this is a child bizobj, its record set is dependent on its parent's
current PK value. This will add the appropriate WHERE clause to
filter the child records. If the parent is a new, unsaved record, or if
there is no parent record, there cannot be any child records saved yet,
so an empty query is built.

Normally connections are established before bizobj creation, but
for those cases where connections are created later, use this method to
establish the connection used by the bizobj.

Lets dependent child bizobjs update to the current parent
record.

Explicitly set the field clause. Replaces any existing field settings.

Set the value of the specified field in the current or specified row.

Allows you to set the value for multiple fields with one call by passing a dict
containing the field names as keys, and the new values as values.

Explicitly set the from clause. Replaces any existing from settings.

Explicitly set the group-by clause. Replaces any existing group-by settings.

Explicitly set the join clauses. Replaces any existing join settings.

Explicitly set the limit clause. Replaces any existing limit settings.

Explicitly set the limit clause. Replaces any existing limit settings.

Explicitly set the order-by clause. Replaces any existing order-by settings.

Set the query parameters for the cursor.

Accepts a tuple that will be merged with the sql statement using the
cursor's standard method for merging.

Accepts and sets the foreign key value linking to the
parent table for all records.

Sets a group of properties on the object all at once.

You have the following options for sending the properties:
	
	1) Property/Value pair dictionary
	2) Keyword arguments
	3) Both

The following examples all do the same thing::

	self.setProperties(FontBold=True, ForeColor="Red")
	self.setProperties({"FontBold": True, "ForeColor": "Red"})
	self.setProperties({"FontBold": True}, ForeColor="Red")

Sets a group of properties on the object all at once. This
is different from the regular setProperties() method because
it only accepts a dict containing prop:value pairs, and it
assumes that the value is always a string. It will convert
the value to the correct type for the property, and then set
the property to that converted value. If the value needs to be evaluated
in a specific namespace, pass that as the 'context' parameter.

Set the SQL query that will be executed upon requery().

This allows you to manually override the sql executed by the cursor. If no
sql is passed, the SQL will get set to the value returned by getSQL().

Allows you to set the value for multiple fields with one call by passing a dict
containing the field names as keys, and the new values as values.

Explicitly set the where clause. Replaces any existing where settings.

Sort the rows based on values in a specified column.

Called when the data is to be sorted on a particular column
in a particular order. All the checking on the parameters is done
in the cursor.

The web backend uses '~~' as the name enclosure character. Convert that
to the correct character for the actual backend.

Store data info to the cache for the next time the same bizobj
is needed.

Remove a previously registered event binding.

Removes all registrations that exist for the given binding for this
object. If event is None, all bindings for the passed function are
removed. If function is None, all bindings for the passed event are
removed. If both event and function are None, all event bindings are
removed.

This is the method to override if you need field-level validation
to your app. It will receive the field name and the new value; you can
then apply your business rules to determine if the new value is
valid. If not, return a string describing the problem. Any non-empty
return value from this method will prevent the control's value
from being changed.

Hook for subclass business rule validation code.

This is the method that you should customize in your subclasses
to create checks on the data entered by the user to be sure that it
conforms to your business rules. Your validation code should return
an error message that describes the reason why the data is not
valid; this message will be propagated back up to the UI where it can
be displayed to the user so that they can correct the problem.

Example::

	if not myNonEmptyField:
		return "MyField must not be blank"

It is assumed that we are on the correct record for testing before
this method is called.