Namespace: Consultingwerk.Util
Class 
DatasetHelper Copy to Clipboard
Parent classes:
Progress.Lang.Object
Consultingwerk.Util.DatasetHelper

Inherits: Progress.Lang.Object

File:DatasetHelper
Syntax:Static methods only, private constructor to disallow
instance creation
Author(s):Mike Fechner / Consultingwerk Ltd.
Created:Tue Jul 14 08:37:47 CEST 2009

Navigate to: Methods | Constructors | Events | Properties



Top Method Summary
Options Name Purpose
+ AddErrorString (handle, character) Adds an ERROR-STRING to a ProDataset Buffer, and sets the ERROR attribute of the BUFFER and the ProDataset
+ AddErrorString (handle, character, character) Adds an ERROR-STRING to a ProDataset Buffer, and sets the ERROR attribute of the BUFFER and the ProDataset
+ AddErrorString (handle, character, character, character) Adds an ERROR-STRING to a ProDataset Buffer, and sets the ERROR attribute of the BUFFER and the ProDataset
+ CHARACTER BufferNames (handle) Returns a list of all buffer names in the ProDataset
+ CHARACTER ChildBuffers (handle) Returns a comma-delimited list of the handles of the child buffers of a ProDataset buffer
+ CHARACTER ChildRelationQueryString (handle) Returns the query string matching a DATA-RELATION field pairs
+ CHARACTER ChildRelationQueryStringWithValues (handle) Returns the query string matching a DATA-RELATION field pairs
+ CopyReadOnlyTables (handle, handle) Copies the read-only tables (no before table) from the source dataset to the target dataset
+ Consultingwerk.RecordIdentifier DatasetErrorRecordIdentifier (handle) Returns the RecordIdentifier identifying the first record in the ProDataset with Errors
+ CHARACTER DatasetErrorStrings (handle) Returns a single CHARACTER string composed of the error-strings of all records (from all tables in the given Dataset instance)
+ DeleteCascade (handle) Deletes the record from the given ProDataset buffer and recursively deletes all child records
+ DeleteDatasetAndBuffers (handle) Deletes a ProDataset object handle and all it's buffers
+ DeleteRestrict (handle) Deletes the record from the given ProDataset buffer only when there is no child record
+ EmptyDataset (handle) Empties a ProDataset
+ HANDLE FindBufferWithField (handle, character, character) Find the first buffer of the list in the given ProDataset that contains a field with the given name
+ HANDLE GetBufferHandles (handle) Returns an Array of the Buffer handles of the given Dataset
+ INTEGER GetBufferIndex (handle, character) Returns the index of the buffer name in the ProDataset
+ HANDLE GetChangesDataset (handle) Builds a dataset containing the changes records from the source dataset.
+ HANDLE GetChildRelation (handle, character) Returns the handle of the child relation of a buffer by name
+ ROWID GetDatasetRowids (handle) Returns an array with the current ROWID's of every ProDataset buffer
+ HANDLE GetDatasetWithCurrentRecord (handle) Creates a Dataset as a copy of another Dataset that only contains the current record in the given ProDataset temp-table buffer
+ HANDLE GetDataSourceQueryHandles (handle) Returns an array of the Query handles of the Data-Sources of the given Dataset
+ HANDLE GetTableHandles (handle) Returns an Array of the Temp-Table handles of the given Dataset
+ LOGICAL GetTrackingChanges (handle) Returns if the Dataset is currently TRACKING-CHANGES
+ LOGICAL HasBuffer (handle, character) Returns if the the passed in ProDataset handle has a buffer with the given name
+ LOGICAL HasChanges (handle) Tests if a ProDataset has changes
+ LOGICAL IsUniqueChildRelation (handle) Returns if the provided data-relation is pointing to an unique child record
+ HANDLE ParentBuffer (handle) Returns the handle of the parent buffer of a ProDataset buffer
+ Consultingwerk.Framework.Collections.RowidDictionary ParentRecordRowids (handle) Returns a RowidDictionary with the ROWID's of the current record as well as the parent and grand-parent ... records based on the ProDataset relations
+ CHARACTER ParentRelationWhereStringWithValues (handle) Returns the where string matching a DATA-RELATION field pairs
+ RejectNonCreateChanges (handle) Rejects all row-changes in the ProDatasets before tables that do not have the row-mod of Adding
+ RepositionDatasetBuffers (handle, rowid[]) Locates the records in all ProDataset buffers based on an Array of ROWID's
+ SetDataSourceQueryHandles (handle, handle[]) Assigns the Query handles of the data-source widgets attached to the ProDataset buffers
+ SetErrorString (handle, character) Sets the ERROR-STRING of a ProDataset Buffer, and the ERROR attribute of the BUFFER and the ProDataset
+ SetTrackingChanges (handle, logical) Sets the tracking changes property of all temp-tables of the passed in dataset
+ SetTrackingChanges (handle, logical, DynamicTempTablesEnum) Sets the tracking changes property of all temp-tables of the passed in dataset
+ ThrowDatasetErrors (handle) Throws Dataset Validation error messsages from the ERROR-STRING attributes of any record

Top Constructor Summary
Options Name Purpose
# DatasetHelper () Protected default constructor.


Method Detail
Top

PUBLIC AddErrorString (handle, character)
Purpose: Adds an ERROR-STRING to a ProDataset Buffer, and sets the ERROR
attribute of the BUFFER and the ProDataset
Notes:

Parameters:
phBuffer HANDLE
The ProDataset Member Buffer
pcErrorString CHARACTER
The Error-String to add
Top

PUBLIC AddErrorString (handle, character, character)
Purpose: Adds an ERROR-STRING to a ProDataset Buffer, and sets the ERROR
attribute of the BUFFER and the ProDataset
Notes:

Parameters:
phBuffer HANDLE
The ProDataset Member Buffer
pcErrorString CHARACTER
The Error-String to add
pcErrorFieldName CHARACTER
The name of the field this error message belongs to
Top

PUBLIC AddErrorString (handle, character, character, character)
Purpose: Adds an ERROR-STRING to a ProDataset Buffer, and sets the ERROR
attribute of the BUFFER and the ProDataset
Notes:

Parameters:
phBuffer HANDLE
The ProDataset Member Buffer
pcErrorString CHARACTER
The Error-String to add
pcErrorFieldName CHARACTER
The name of the field this error message belongs to
pcErrorBufferName CHARACTER
The name of the buffer this error message belongs to
Top

PUBLIC CHARACTER BufferNames (handle)
Purpose: Returns a list of all buffer names in the ProDataset
Notes:

Parameters:
phDataset HANDLE
The handle of the ProDataset
Returns CHARACTER
The comma-delimited list of buffer names
Top

PUBLIC CHARACTER ChildBuffers (handle)
Purpose: Returns a comma-delimited list of the handles of the child buffers
of a ProDataset buffer
Notes:

Parameters:
phBuffer HANDLE
The ProDataset buffer handle to return child buffers from
Returns CHARACTER
The comma-delimited list of the handles of the child buffers
Top

PUBLIC CHARACTER ChildRelationQueryString (handle)
Purpose: Returns the query string matching a DATA-RELATION field pairs
Notes: Uses the parent table field names in the query string

Parameters:
phBuffer HANDLE
The child buffer of the relation
Returns CHARACTER
The query string matching the data-relation criteria
Top

PUBLIC CHARACTER ChildRelationQueryStringWithValues (handle)
Purpose: Returns the query string matching a DATA-RELATION field pairs
Notes: Instead of the parent table field names, the current buffer values are
used

Parameters:
phBuffer HANDLE
The child buffer of the relation
Returns CHARACTER
The query string matching the data-relation criteria
Top

PUBLIC CopyReadOnlyTables (handle, handle)
Purpose: Copies the read-only tables (no before table) from the source dataset
to the target dataset
Notes: Useful in combination with the dataset MERGE-CHANGES method to copy
also rows from tables without a before table form the source to the
target dataset. Those tables are ignored by the MERGE-CHANGES method

Parameters:
phSourceDataset HANDLE
The handle of the source dataset
phTargetDataset HANDLE
The handle of the target dataset
Top

PUBLIC Consultingwerk.RecordIdentifier DatasetErrorRecordIdentifier (handle)
Purpose: Returns the RecordIdentifier identifying the first record in the
ProDataset with Errors
Notes: Processes the Dataset in the same order as DatasetErrorStrings

Parameters:
phDataset HANDLE
The handle of the dataset to return the error strings from
Returns Consultingwerk.RecordIdentifier
The RecordIdentifier identifying the first record in the ProDataset with errors
Top

PUBLIC CHARACTER DatasetErrorStrings (handle)
Purpose: Returns a single CHARACTER string composed of the error-strings
of all records (from all tables in the given Dataset instance)
Notes:

Parameters:
phDataset HANDLE
The handle of the dataset to return the error strings from
Returns CHARACTER
The string composed of the error-strings of all records
Top

PUBLIC DeleteCascade (handle)
Purpose: Deletes the record from the given ProDataset buffer and recursively
deletes all child records
Notes:

Parameters:
phBuffer HANDLE
The handle of the ProDataset buffer with the record to delete
Top

PUBLIC DeleteDatasetAndBuffers (handle)
Purpose: Deletes a ProDataset object handle and all it's buffers
Notes: Useful, when dynamic buffers have been added to a ProDataset manually
any are not maintained by the ProDataset (like they would be when the
Dataset was created by the CREATE-LIKE method or similar).

Parameters:
phDataset HANDLE
The handle of the ProDataset
Top

PUBLIC DeleteRestrict (handle)
Purpose: Deletes the record from the given ProDataset buffer only when
there is no child record
Notes: Throws an error message, when a child error still exists

Parameters:
phBuffer HANDLE
The handle of the ProDataset buffer with the record to delete
Top

PUBLIC EmptyDataset (handle)
Purpose: Empties a ProDataset
Notes: Assigns Tracking-Changes of all temp-tables to FALSE prior to
emptying the ProDataset and restores the state of Tracking-Changes
afterwards

Parameters:
phDataset HANDLE
The handle of the ProDataset
Top

PUBLIC HANDLE FindBufferWithField (handle, character, character)
Purpose: Find the first buffer of the list in the given ProDataset that
contains a field with the given name
Notes: Returns ? when the field is not available in any buffer

Parameters:
phDataset HANDLE
The handle of the ProDataset
pcBufferNames CHARACTER
The comma delimited list of buffer names of the ProDataset
pcFieldName CHARACTER
The unqualified name of the field to locate
Returns HANDLE
The handle of the first buffer that contains the field
Top

PUBLIC HANDLE GetBufferHandles (handle)
Purpose: Returns an Array of the Buffer handles of the given Dataset
Notes: Returns an uninitialized array and not a runtime error when the dataset
does not contain any buffer

Parameters:
phDataset HANDLE
The handle of the dataset
Returns HANDLE
The Array of Buffer handles
Top

PUBLIC INTEGER GetBufferIndex (handle, character)
Purpose: Returns the index of the buffer name in the ProDataset
Notes: Return ? when the buffer is not a member of the ProDatast

Parameters:
phDataset HANDLE
The handle of the ProDataset
pcBufferName CHARACTER
The name of the buffer to locate
Returns INTEGER
The index of the buffer in the ProDataset buffer's list
Top

PUBLIC HANDLE GetChangesDataset (handle)
Purpose: Builds a dataset containing the changes records from the
source dataset.
Notes: This method returns a dataset, clean up has to be done by the
caller.

Parameters:
phDataset HANDLE
The handle of the original dataset
Returns HANDLE
The handle of a new dataset containing the changes from the original dataset
Top

PUBLIC HANDLE GetChildRelation (handle, character)
Purpose: Returns the handle of the child relation of a buffer by name
Notes:

Parameters:
phParentBuffer HANDLE
The handle to the parent buffer
pcDataRelationName CHARACTER
The name of the data-relation to return
Returns HANDLE
The handle of the data-relation with the matching name
Top

PUBLIC ROWID GetDatasetRowids (handle)
Purpose: Returns an array with the current ROWID's of every ProDataset buffer
Notes: Useful in situations where ProDataset methods such as GET-CHANGES
or MERGE-CHANGES invalidate the current record buffers

Parameters:
phDataset HANDLE
The handle of the ProDataset
Returns ROWID
The variable extent array of ROWID's matching the order of buffers in the ProDataset
Top

PUBLIC HANDLE GetDatasetWithCurrentRecord (handle)
Purpose: Creates a Dataset as a copy of another Dataset that only contains
the current record in the given ProDataset temp-table buffer
Notes: Useful to send individual records of a ProDataset to Business Entity
InvokeMethod or Business Task methods

Parameters:
phBuffer HANDLE
The handle of the ProDataset Buffer that contains the record to be copied
Returns HANDLE
The copy of the ProDataset, the caller is responsible to clean this up when no longer needed
Top

PUBLIC HANDLE GetDataSourceQueryHandles (handle)
Purpose: Returns an array of the Query handles of the Data-Sources of the
given Dataset
Notes: Array may contain invalid ? entries when data sources don't have a
query assigned

Parameters:
phDataset HANDLE
The handle of the ProDataset
Returns HANDLE
The handle array with the handles of the data-source queries
Top

PUBLIC HANDLE GetTableHandles (handle)
Purpose: Returns an Array of the Temp-Table handles of the given Dataset
Notes: Returns an uninitialized array and not a runtime error when the dataset
does not contain any buffer

Parameters:
phDataset HANDLE
The handle of the dataset
Returns HANDLE
The Array of Temp-Table handles
Top

PUBLIC LOGICAL GetTrackingChanges (handle)
Purpose: Returns if the Dataset is currently TRACKING-CHANGES
Notes: Returns the value of the TRACKING-CHANGES attribute of the first
updatable temp-table. When there is not updatable temp-table, FALSE
will be returned

Parameters:
phDataset HANDLE
Handle of the dataset
Returns LOGICAL
Logical value indicating if the Dataset is TRACKING-CHANGES
Top

PUBLIC LOGICAL HasBuffer (handle, character)
Purpose: Returns if the the passed in ProDataset handle has a buffer with the
given name
Notes:

Parameters:
phDataset HANDLE
The handle of the ProDataset
pcBufferName CHARACTER
The name of the Buffer that should exist
Returns LOGICAL
Logical value indicating if the ProDataset has a buffer with the given name
Top

PUBLIC LOGICAL HasChanges (handle)
Purpose: Tests if a ProDataset has changes
Notes: Similar to the System.Data.Dataset.HasChanges attribute

Parameters:
phDataset HANDLE
Handle of the dataset
Returns LOGICAL
Logical value indicating if the ProDataset has change records (before table records)
Top

PUBLIC LOGICAL IsUniqueChildRelation (handle)
Purpose: Returns if the provided data-relation is pointing to an unique
child record
Notes: Returns TRUE for eOrder->eCustomer and FALSE for eOrder->eOrderLine

Parameters:
phRelation HANDLE
The handle of the DATA-RELATION to test
Returns LOGICAL
Logical value indicating if the data-relation is pointing to an unique child record
Top

PUBLIC HANDLE ParentBuffer (handle)
Purpose: Returns the handle of the parent buffer of a ProDataset buffer
Notes:

Parameters:
phBuffer HANDLE
The handle of the ProDataset buffer (child buffer)
Returns HANDLE
The handle of the parent buffer
Top

PUBLIC Consultingwerk.Framework.Collections.RowidDictionary ParentRecordRowids (handle)
Purpose: Returns a RowidDictionary with the ROWID's of the current record as
well as the parent and grand-parent ... records based on the ProDataset
relations
Notes:

Parameters:
phBuffer HANDLE
The handle of the child buffer to return the parent ROWID's for
Returns Consultingwerk.Framework.Collections.RowidDictionary
The RowidDictionary with the ROWID's of the parent records
Top

PUBLIC CHARACTER ParentRelationWhereStringWithValues (handle)
Purpose: Returns the where string matching a DATA-RELATION field pairs
Notes: Instead of the parent table field names, the current buffer values of
the child table are used in the where string

Parameters:
phBuffer HANDLE
The child buffer of the relation
Returns CHARACTER
The query string matching the data-relation criteria
Top

PUBLIC RejectNonCreateChanges (handle)
Purpose: Rejects all row-changes in the ProDatasets before tables that
do not have the row-mod of Adding
Notes: ROW-UNMODIFIED 0 The row was not modified.
ROW-DELETED 1 The row was deleted.
ROW-MODIFIED 2 The row was modified.
ROW-CREATED 3 The row was created.

Parameters:
phDataset HANDLE
The handle to the dataset
Top

PUBLIC RepositionDatasetBuffers (handle, rowid[])
Purpose: Locates the records in all ProDataset buffers based on an Array
of ROWID's
Notes: The input parameter proRowids can be obtained from the GetDatasetRowids
method

Parameters:
phDataset HANDLE
The handle of the ProDataset
proRowids ROWID
The variable extent array of ROWID's matching the order of buffers in the ProDataset
Top

PUBLIC SetDataSourceQueryHandles (handle, handle[])
Purpose: Assigns the Query handles of the data-source widgets attached to the
ProDataset buffers
Notes: Ignores Cannot assign auto-generated FILL query to user FILL query. (11866)
in which case it seems safe to assign ? to the DATA-SOURCE QUERY attribute

Parameters:
phDataset HANDLE
The handle of the ProDataset
phQueries HANDLE
The array of the query handles to assign to the data-source queries
Top

PUBLIC SetErrorString (handle, character)
Purpose: Sets the ERROR-STRING of a ProDataset Buffer, and the ERROR attribute
of the BUFFER and the ProDataset
Notes:

Parameters:
phBuffer HANDLE
The ProDataset Member Buffer
pcErrorString CHARACTER
The Error-String
Top

PUBLIC SetTrackingChanges (handle, logical)
Purpose: Sets the tracking changes property of all temp-tables of the passed
in dataset
Notes: Tables without a valid BEFORE-BUFFER will not be handled. For static
temp-tables this is typically understood as read-only temp-tables
(and the attempt to enable TRACKING-CHANGES would cause a runtime
error). Dynamic temp-tables that have never been set to
TRACKING-CHANGES = TRUE will never have a valid BEFORE-BUFFER. As
such it's expected that dynamic temp-tables that should be updatable
will be set to TRACKING-CHANGES briefly in their factory method.

Parameters:
phDataset HANDLE
The handle to the Dataset
plTrackingChanges LOGICAL
LOGICAL value indicating if tracking changes should be turned on or off
Top

PUBLIC SetTrackingChanges (handle, logical, DynamicTempTablesEnum)
Purpose: Sets the tracking changes property of all temp-tables of the passed
in dataset
Notes: Tables without a valid BEFORE-BUFFER will not be handled. For static
temp-tables this is typically understood as read-only temp-tables
(and the attempt to enable TRACKING-CHANGES would cause a runtime
error). Dynamic temp-tables that have never been set to
TRACKING-CHANGES = TRUE will never have a valid BEFORE-BUFFER.
The poDynamicTempTables parameter allows to indicate how to handle
dynamic temp-tables

Parameters:
phDataset HANDLE
The handle to the Dataset
plTrackingChanges LOGICAL
LOGICAL value indicating if tracking changes should be turned on or off
poDynamicTempTables Consultingwerk.Util.Enum.DynamicTempTablesEnum
The DynamicTempTablesEnum value indicating how to handle dynamic tmep-tables
Top

PUBLIC ThrowDatasetErrors (handle)
Purpose: Throws Dataset Validation error messsages from the ERROR-STRING
attributes of any record
Notes: Performs no action, when there is no record with an ERROR-STRING in
the ProDataset
SCL-496
Throws: Consultingwerk.Exceptions.DatasetException

Parameters:
phDataset HANDLE
The handle to the Dataset


Constructor Detail
Top

PROTECTED DatasetHelper ()
Purpose: Protected default constructor.
Notes: There's no need to create instances of the helper classes



©2006-2016 Consultingwerk Ltd.         info@consultingwerk.de         http://www.consultingwerk.de       26.08.2016 08:46:19