Table of Contents

Class BudaDataSet

Namespace
PolarStudio
Assembly
PolarStudio.dll

The BudaDataSet is the Polar Studio way of communicating with the data in the database. It is like a Recordset, but with all features added by Polar Studio

public class BudaDataSet : IDisposable, PolarWeakEventListener
Inheritance
BudaDataSet
Implements
Inherited Members
Extension Methods

Fields

SuppressDeleteCommand

Can be set to True in a script to suppress the actual delete-statement without canceling the delete. For example to support soft-deletes.

public bool SuppressDeleteCommand

Field Value

bool

Properties

AbsolutePosition

This propery gets/set the position of the current record. This position is one based. If there are no records, -1 will be returned.

public long AbsolutePosition { get; set; }

Property Value

long

Application

The Application used to create this DataSet

public BudaApplication Application { get; }

Property Value

BudaApplication

AutomaticallyAddWildCards

When this property is set to True, the user can search in a field for 'john' and the system will then automatically search for '%john%'. Can be convenient but can also slow down performance on large tables.

public bool AutomaticallyAddWildCards { get; set; }

Property Value

bool

AvailableFilters

Returns a list with the available filters

public repFilters AvailableFilters { get; }

Property Value

repFilters

BOF

This property (meaning Begin Of File) returns true if the begin of the file has been reached (before the first record). When True, no record is active, when False, a record is available.

public bool BOF { get; }

Property Value

bool

BaseTableName

The name of the BaseTable in case this table is a query.

public string BaseTableName { get; }

Property Value

string

Caption

Returns the caption of the current Dataset based on the Caption set in the repository.

public string Caption { get; }

Property Value

string

ClearFilterValuesOnRemovingFilter

This property sets the behaviour that when the user removes the filter, all filter-values (for all fields) are also cleared. If this property is False, then only the filter is removed (so all records will be shown), but the individual fields will still have the filter-values as specified by the user.

public bool ClearFilterValuesOnRemovingFilter { get; set; }

Property Value

bool

CustomFilters

CustomFilters are additional Filters (not visible for the user) that are added to the query for this DataSet.

public CustomFilters CustomFilters { get; }

Property Value

CustomFilters

DataConnector

The DataConnector that is used by the Application of this DataSet to communicate with the database.

public DataConnector DataConnector { get; }

Property Value

DataConnector

DateFormat

The DateFormat (as int) used for this dataset.

public DateFormat DateFormat { get; }

Property Value

DateFormat

DateFormatString

The full string used to format dates

public string DateFormatString { get; }

Property Value

string

DateSeparator

The character used to separate elements in the date, coded as int. Values: ''

public DateSeparator DateSeparator { get; }

Property Value

DateSeparator

DecimalCharacterString

Returns the character used for decimals

public string DecimalCharacterString { get; }

Property Value

string

DeleteAllowed

Returns True if the user is allowed to delete the current record.

public bool DeleteAllowed { get; }

Property Value

bool

DeleteAllowedScript

A script-expression returning a boolean indicating if deleting this record is allowed. Initially set with the value defined in the repository but can be overwritten.

public string DeleteAllowedScript { get; set; }

Property Value

string

Dirty

Returns True if any field in the current record has unsaved changes

public bool Dirty { get; }

Property Value

bool

EOF

This property (meaning End Of File) returns true if the end of the file has been reached (after the last record). When True, no record is active, when False, a record is available.

public bool EOF { get; }

Property Value

bool

EditAllowed

Returns True if the user is allowed to edit the current record.

public bool EditAllowed { get; }

Property Value

bool

EditAllowedScript

A script-expression returning a boolean indicating if editing this record is allowed. Initially set with the value defined in the repository but can be overwritten.

public string EditAllowedScript { get; set; }

Property Value

string

Engine

Returns the Engine

public BudaEngine Engine { get; }

Property Value

BudaEngine

Fields

The Fields is a collection of the all fields in this dataset in the order as specified in Polar Studio.

public BudaFields Fields { get; }

Property Value

BudaFields

Filter

This property gets / sets the BaseFilter for the dataset. When setting the property, the dataset is requeried instantly.

public string Filter { get; set; }

Property Value

string

FilterBooleanOperator

Determins how multiple search-criteria in the search-form are handled ("OR" / "AND"). The default behaviour is set to "AND"

public string FilterBooleanOperator { get; set; }

Property Value

string

FilterOn

This property determines if the Filter (the user's search) is switched on or off. If you set this property to False, all records will be shown. If you set it to True (even if it was already set to True) the filters will be applied and the DataSet will be requeried.

public bool FilterOn { get; set; }

Property Value

bool

FollowedRelationship

Returns the name of the FollowedRelationship if a ParentDataSet was specified when opening this dataset

public string FollowedRelationship { get; }

Property Value

string

ForeignKeysUpdated

This property can be set to True, to force an update of the underlying recordset from script.

public bool ForeignKeysUpdated { get; set; }

Property Value

bool

Form

The form that has opened this dataset as underlying dataset

public Form Form { get; }

Property Value

Form

GUID

A GUID for this instance dataset as is used for the locking mechanism.

public string GUID { get; }

Property Value

string

GroupIdentifier

Returns the current GroupIdentifier. Use SetOrderSettings to change.

public string GroupIdentifier { get; }

Property Value

string

HasUserInterface

A boolean that is set to True if this dataset is directly bound to a form

public bool HasUserInterface { get; }

Property Value

bool

Identifier

Returns the Identifier of the current record.

public string Identifier { get; }

Property Value

string

InitialRecordToActivate

Returns the initial RecordID that was activated on opening the dataset.

public object InitialRecordToActivate { get; }

Property Value

object

InsertAllowed

Returns True if the user is allowed to insert new records in this dataset.

public bool InsertAllowed { get; set; }

Property Value

bool

InsertAllowedScript

A script-expression returning a boolean indicating if inserting a new record is allowed. Initially set with the value defined in the repository but can be overwritten.

public string InsertAllowedScript { get; set; }

Property Value

string

this[object]

Returns the field for the given Index (either name of index number)

public BudaField this[object pIndex] { get; }

Parameters

pIndex object

Name or index number (one-based)

Property Value

BudaField

The found field or nothing

KeepRecordsVisible

This property sets the behaviour to keep edited records visible. When a user opens a form with a certain filter and then edits one of the records, the situation may occur that this record does not apply to the filter anymore. This feature helps to keep the record in the list anyway, also after a requery. The issue can be that with (very) large tables, the database-queries can become slow, due to the OR-condition that is added. For that reason, you may turn of this feature for some tables if wanted.

public bool KeepRecordsVisible { get; set; }

Property Value

bool

KeepRecordsVisibleRecordCount

When using KeepRecordsVisible, this property set the max number of records that is additionally kept visible.

public int KeepRecordsVisibleRecordCount { get; set; }

Property Value

int

NoRecordsShownBecauseNoFilterApplied

A boolean that is set to true if a filter is required but not set.

public bool NoRecordsShownBecauseNoFilterApplied { get; }

Property Value

bool

OnUpdateEventsRunning

Returns True while running OnUpdateEvents

public bool OnUpdateEventsRunning { get; }

Property Value

bool

ParentIdentifier

Returns the Identifier of the Parent (if a ParentDataSet was specified when opening this DataSet)

public string ParentIdentifier { get; }

Property Value

string

ParentIsRealParent

Returns True if a ParentDataSet was specified when opening this dataset and this dataset contains related records (childs). When going to a Foreign Key, Returns False.

public bool ParentIsRealParent { get; }

Property Value

bool

ParentRecordEditAllowed

A boolean indicating if the ParentTable was allowed to edit if a ParentDataSet was specified when opening this dataset.

public bool ParentRecordEditAllowed { get; }

Property Value

bool

ParentRecordID

The RecordID of the ParentTable if a ParentDataSet was specified when opening this dataset.

public object ParentRecordID { get; }

Property Value

object

ParentTableName

The name of the ParentTable if a ParentDataSet was specified when opening this dataset.

public string ParentTableName { get; }

Property Value

string

PreGroupingOrder

Returns the current PreGroupingOrder. Use SetOrderSettings to change.

public string PreGroupingOrder { get; }

Property Value

string

PredefinedFilter

This property gets / sets the name of the Predefined filter. After changing this property you must apply it by setting property 'FilterOn' to 'True'

public string PredefinedFilter { get; set; }

Property Value

string

PrimaryKeyFieldName

Returns the bare name of the PrimaryKey in this dataset, like 'MyTableID'

public string PrimaryKeyFieldName { get; }

Property Value

string

RecordCount

Returns the number of records in this DataSet

public long RecordCount { get; }

Property Value

long

RecordDeleted

A boolean indicating this record has been soft-deleted.

public bool RecordDeleted { get; }

Property Value

bool

RecordID

This property Gets / Sets the RecordID for the active record. When setting the value, the requested Record will be activated (if possible). For a new record (during insert), the RecordID returns NULL, however when the OnUpdate script of a new record is fired, it will return the RecordID of the just inserted new record in the database.

public object RecordID { get; set; }

Property Value

object

RecordIsPrivate

Returns True if the user is in a group that is tied

public bool RecordIsPrivate { get; }

Property Value

bool

RecordMode

Returns the RecordMode. This can be one of the following values: 'None', 'New', 'Normal', 'EditInProgress', 'Deleted'

public string RecordMode { get; }

Property Value

string

RecordSource

Returns the RecordSource (SQL) that was used to query the records in the database.

public string RecordSource { get; }

Property Value

string

Recordset

This property gives you direct access to the underlying RecordSet. However, the use of this property is not recommended

public Recordset Recordset { get; }

Property Value

Recordset

RelatedTables

Returns all 'incomming' Relationships for related tables ('Related Items Lists') To get the 'outgoing' Relationships, you must access the Field.Relationship - property

public repRelationships RelatedTables { get; }

Property Value

repRelationships

RemoveFilterIfNoRecordsFound

This property sets the behaviour that a user filter is removed if it was applied and no records were found.

public bool RemoveFilterIfNoRecordsFound { get; set; }

Property Value

bool

RequireFilter

When a filter is required, no records will be shown when no filter is set. This can be useful for large tables to increase performance and to prevent each time showing the user the same first 50 records of a 100 million records table.

public bool RequireFilter { get; set; }

Property Value

bool

Session

Returns the Session of the user for the current DataSet

public BudaSession Session { get; }

Property Value

BudaSession

Settings

The Settings property gives access to the repository regarding this Table.

public repTable Settings { get; }

Property Value

repTable

ShowDeletedRecords

A boolean that can be set to true to show records that are SoftDeleted. Changing this value causes a requery.

public bool ShowDeletedRecords { get; set; }

Property Value

bool

SoftDeleteDateTimeField

Returns the Field in which the deletion date-time is stored for soft deletes.

public BudaField SoftDeleteDateTimeField { get; }

Property Value

BudaField

SoftDeleteField

Returns the Field that is used to register soft deletes.

public BudaField SoftDeleteField { get; }

Property Value

BudaField

SoftDeletes

A boolean indicating this table is configured to use SoftDeletes

public bool SoftDeletes { get; }

Property Value

bool

SuppressErrorMessages

This property suppresses form-bound dataset to send messages to the user.

public bool SuppressErrorMessages { get; set; }

Property Value

bool

TableID

The internal TableID that matches the ID in the repository

public int TableID { get; }

Property Value

int

TableName

The name of the table or query this dataset is based on. Equals the name in Polar Studio.

public string TableName { get; }

Property Value

string

TableOrder

Returns the current TableOrder. Use SetOrderSettings to change.

public string TableOrder { get; }

Property Value

string

Tag

The Tag is available for scripted use and can be filled with any text.

public string Tag { get; set; }

Property Value

string

ThousandsCharacterString

Returns the character used for thousands-separation, like in 1.048.576

public string ThousandsCharacterString { get; }

Property Value

string

TimeFormat

The TimeFormat (as int) used for this dataset

public TimeFormat TimeFormat { get; }

Property Value

TimeFormat

TimeFormatString

The full string used to format times

public string TimeFormatString { get; }

Property Value

string

TimeZone

This property sets/gets the TimeZone for the current dataset.

public PolarTimeZone TimeZone { get; set; }

Property Value

PolarTimeZone

Variables

The Variables can be used to store custom information in the BudaDataset

public Dictionary Variables { get; }

Property Value

Dictionary

ViewAllowed

Returns if the user is allowed to view the current record. Would normally be True, because otherwise the record should have been filtered out from the recordset.

public bool ViewAllowed { get; }

Property Value

bool

WFcurrentStateTransition

This property is only set during a state-transition. It then returns the repStateTransition object of the state transition that is taking place.

public repStateTransition WFcurrentStateTransition { get; }

Property Value

repStateTransition

WFenabled

Returns True if this table uses workflow (WF)

public bool WFenabled { get; }

Property Value

bool

WFhistoryFieldName

Returns the name of the memo field that is used to store the history of state transitions (if applicable)

public string WFhistoryFieldName { get; }

Property Value

string

WFinitialStateTransition

Returns the Initial StateTransition that is to be carried out for new records (the Initialize)

public repStateTransition WFinitialStateTransition { get; }

Property Value

repStateTransition

WFlastStateTransitionFieldName

Returns the name of the date/time field that is used to store the date/time of the last state transition (if applicable)

public string WFlastStateTransitionFieldName { get; }

Property Value

string

WFmessage

This property is only set during a state-transition. It then returns the message entered by the user for carrying out this state transition (the confirmation of the state transition must be set to also ask a message).

public string WFmessage { get; }

Property Value

string

WFstateFieldName

Returns the name of the field that is used to store the workflow status (or and empty string if no workflow is used)

public string WFstateFieldName { get; }

Property Value

string

Methods

Abandon()

This method is used to abandon the DataSet. This means it will not be used for some time and closes the underlying recordset and frees resources. It can be 'reactivated' by calling the Continue method.

public void Abandon()

AddNew()

This method creates a new record in the DataSet. If this fails, an error-message will be returned. You need to Update the record to actually create-and-store it in the database.

public string AddNew()

Returns

string

An error message if applicable.

CancelUpdate(bool)

This method cancels an update or new record and reverts to the last record.

public void CancelUpdate(bool pSuppressReleaseRecordLock = false)

Parameters

pSuppressReleaseRecordLock bool

If False, then the lock on the record will also be released. If True, the lock on the record will be maintained.

Continue(object)

To Continue working with a DataSet. Will requery if the dataset was abandoned.

public string Continue(object pGotoRecordID = null)

Parameters

pGotoRecordID object

The recordID to activate. If not specified it will continue on the last active record.

Returns

string

Delete(bool, bool)

This method deletes the current record from both the DataBase and the DataSet. If you are deleting multiple records, you must perform a MoveNext to move to the next record that is to be deleted.

public string Delete(bool pSuppressRequery = false, bool pSuppressCheckSharingViolation = false)

Parameters

pSuppressRequery bool

In script, you can set pSuppressRequery to True for increased performance (for example when looping through a temporary dataset and deleting the records).

pSuppressCheckSharingViolation bool

To suppress checks if this record has been changed in the meanwhile.

Returns

string

An error message if applicable

Destruct(bool)

To destruct the Dataset and free resources.

public void Destruct(bool pCalledFromFinalize = false)

Parameters

pCalledFromFinalize bool

Dispose()

Destructor

public void Dispose()

DoStateTransition(string, string, bool, bool, bool)

This method performs the requested state transition. If this method is called in an OnUpdate event or in a StateTransition-event (on this very dataset), then this StateTransition is 'remembered' and executed after the current action has completed. The state transition will be carried out in the same transaction, so if it fails the whole action (including the initial Update or the initial StateTransition) will be rolled back.

public string DoStateTransition(string pRequestedStateTransitionName, string pAdditionalMessage = "", bool pSuppressRequery = false, bool pSuppressValidityCheck = false, bool pSuppressCheckSharingViolation = false)

Parameters

pRequestedStateTransitionName string

The name of the state transition to execute

pAdditionalMessage string

An additional message, just like the user could have typed in.

pSuppressRequery bool

A boolean to suppress requery. This may speed up scripted use.

pSuppressValidityCheck bool

Pass this parameter as True if the state transition has to be performed regardless any permissions. Howerver, if the statetransition calls an OnExecute script and this script returns an error message, then the whole transaction will be rolled back. This parameter is required to set to True when performing System StateTransitions.

pSuppressCheckSharingViolation bool

To suppress checks if this record has been changed in the meanwhile.

Returns

string

~BudaDataSet()

Destructor

protected ~BudaDataSet()

GetContext()

This method returns the context to use for running scripts.

public Context GetContext()

Returns

Context

Keep()

This method is meant for keeping changes in unsuccessful updates. This way the user can still see the unsaved edits, while the database still contains the original values. Is used internally in Polar Studio.

public void Keep()

KeepRecordVisible()

This method can be called to make sure a record is kept visible (if the feature KeepRecordsVisible is switched on)

public void KeepRecordVisible()

KillRecordSet()

This is a light version of Abandon, in which only the recordset is killed, but all other data is kept. This frees resources.

public void KillRecordSet()

LocalUpdate()

This method performs some FieldChange events without writing data to the database. For example, after changing a value of a foreign key, a call to UpdateFields will cause related fields to be cleared/populated. Also the OnFieldChange-events will be fired If this method fails, an ErrorMessage will be returned

public string LocalUpdate()

Returns

string

Locate(long)

This method tries to locate the record with the given pRecordID. It returns True if successful.

public bool Locate(long pRecordID)

Parameters

pRecordID long

The ID of the record to locate (int or long)

Returns

bool

True if found.

MoveFirst()

This method navigates to the first record. If there are no records, both Bof and Eof are true.

public void MoveFirst()

MoveLast()

This method navigates to the last record. If there are no records, both Bof and Eof are true.

public void MoveLast()

MoveNext()

This method navigates to the next record. Use the property Eof (end of file) to test if the last record has been passed.

public void MoveNext()

MovePrevious()

This method navigates to the previous record. Use the property Bof (begin of file) to test if the first record has been passed.

public void MovePrevious()

RecordChangedByOthers(ref bool)

This method returns True if this record has been changed in the database since it was read the last time.

public bool RecordChangedByOthers(ref bool pRequeryRecommended)

Parameters

pRequeryRecommended bool

the ByRef pRequeryRecommended will RETURN True if a foreign key has been changed. A requery is needed to display the correct new value...

Returns

bool

Boolean indicating the record was changed (false if equal)

RelatedItemsRecordSet(string)

Returns a new Recordset with the related items for a given RelationshipName

public Recordset RelatedItemsRecordSet(string pRelationshipName)

Parameters

pRelationshipName string

The name of the relationship

Returns

Recordset

A new Recordset

Release()

This method is releases a record kept in memory (see Keep)

public void Release()

ReleaseAll()

This method releases all records kept in memory (see Keep)

public void ReleaseAll()

Requery(bool)

To Requery the DataSet to match changed data in the DataBase

public string Requery(bool pSuppressRelocateRecord = false)

Parameters

pSuppressRelocateRecord bool

Pass True to move to the beginning of the list of records instead of re-locating the last active record.

Returns

string

An error message if applicable.

Restored(ref bool)

This method restores the remembered changes a user made to a record. Returns True if successful.

public bool Restored(ref bool pRequeryRecommended)

Parameters

pRequeryRecommended bool

This ByRef parameter is set to True if the system recommends a Requery.

Returns

bool

Resync()

This method forces the actual data in the database to be re-read.

public void Resync()

SetOrderSettings(string, string, string)

This method sets TableOrders in raw format. It also requeries the dataset.

public void SetOrderSettings(string pTableOrder, string pGroupIdentifier, string pPreGroupingOrder)

Parameters

pTableOrder string

A SQL OrderBy clause to set the order of the table

pGroupIdentifier string

A SQL expression for the Group Identifier

pPreGroupingOrder string

A SQL OrderBy clause that is put before the GroupIdentifier is determined

Update(bool, bool)

This method stores the current record in the database (only if Dirty). It this fails, an errorMessage will be returned.

public string Update(bool pSuppressRequery = false, bool pSuppressCheckSharingViolation = false)

Parameters

pSuppressRequery bool

In script, you can set pSuppressRequery to True if you are not interested in the updated record (for example when looping through a temporary dataset and updating records). This will increase performance.

pSuppressCheckSharingViolation bool

Pass as True if not interested in preserving changes by others and just to force an update of this record.

Returns

string

An error message if applicable

WFAllowedStateTransitions()

This method returns the state transitions that the user is allowed to do given the current record.

public repStateTransitions WFAllowedStateTransitions()

Returns

repStateTransitions

A list of state transitions that are allowed.

WFstate(int)

Returns the state (as repState object) of the current record.

public repState WFstate(int pUnknownStateBehaviour = 0)

Parameters

pUnknownStateBehaviour int

With this parameter, the behaviour can be set if a value in the database was found in the State-field that does not match a state in the repository: use 0=Standard (use behaviour defined in the setting of the project); 1=Return DummyObject; -1=Return Nothing

Returns

repState

The state of the current record.