BY-REFERENCE Access to Business Entity FetchData
In SCL-1724 (released in April 2017) we implemented the optional ability to invoke the ServiceInterface:FetchData method with the BY-REFERENCE option for the Dataset parameter.
This allows the consumer to pass it's own ProDataset by reference to the Business Entity. The Business Entity and the Data Access will then for the duration of the call work on the Dataset provided this way. Our tests have shown that when reading large amounts of result data (e.g. 50.000 records) this may improve the execution time by 15 to 20 %. On smaller result sets (100 records) the benefit is usually not measurable.
Business Entities need a new method in order to support the FetchData request BY-REFERENCE. Business Entities will further need to implement the new Interface IFetchDataByReference interface.
New Business Entities generated based on the extended templates will automatically include the new method and implement the interface.
Adding support for BY-REFERENCE FetchData calls to existing Business Entities
The following method needs to be added to the Business Entity:
/*------------------------------------------------------------------------------
Purpose: Fetch data from the Data Access object
Notes:
@param poFetchDataRequest The IFetchDataRequest object with the parameters for this call
@param dsCustomer The customer dataset, intended to by passed BY-REFERENCE
------------------------------------------------------------------------------*/
METHOD PUBLIC FINAL VOID FetchDataByReference (poFetchDataRequest AS Consultingwerk.OERA.IFetchDataRequest,
OUTPUT DATASET dsCustomer):
THIS-OBJECT:FetchData (poFetchDataRequest, DATASET dsCustomer:HANDLE) .
END METHOD.
Please replace the ProDataset name dsCustomer with the name of your actual ProDataset
Further the interface IFetchDataByReference needs to be implemented by the Business Entity:
CLASS Consultingwerk.SmartComponentsDemo.OERA.Sports2000.CustomerBusinessEntity
INHERITS SmartBusinessEntity IMPLEMENTS IFetchDataByReference:
Updating customized Business Entity Designer templates
The Business Entity Designer templates need to be updated like this:
/*------------------------------------------------------------------------
File : &1
Purpose : &6
Syntax :
Description : &7
Author(s) : @USER@
Created : &5
Notes :
----------------------------------------------------------------------*/
ROUTINE-LEVEL ON ERROR UNDO, THROW.
USING &2.* FROM PROPATH .
USING Consultingwerk.SmartFramework.* FROM PROPATH .
USING Consultingwerk.OERA.* FROM PROPATH .
USING Consultingwerk.Util.* FROM PROPATH .
USING Progress.Lang.* FROM PROPATH .
/* Sample Annotations - see http://confluence.consultingwerkcloud.com/wiki/display/SCL/The+Annotation+based+Type+Descriptor
@BusinessEntityView (name="order", isdefault="true", entitytable="eOrder", entityview="eCustomer",
listcolumns="eOrder.OrderNum,eOrder.OrderDate,eOrder.CustNum,eCustomer.Name",
viewercolumns="eOrder.OrderNum,eOrder.OrderDate,eOrder.CustNum,eCustomer.Name,eOrder.OrderStatus") .
@BusinessEntityTable (name="eOrder", mandatoryColumns="ordernum,orderstatus", addOnlyColumns="ordernum", readonlyColumns="ordernum") .
@BusinessEntityTable (name="eCustomer", mandatoryColumns="ordernum,orderstatus", readonly="true") .
*/
@FILEANNOTATION@
CLASS &2.&1
INHERITS BusinessEntity IMPLEMENTS IFetchDataByReference
USE-WIDGET-POOL:
{ &4/&3.i }
/*------------------------------------------------------------------------------
Purpose: Constructor of the &1 class
Notes: Passes the handle of the dataset instance to the base class and
sets the default DataAccessName
------------------------------------------------------------------------------*/
CONSTRUCTOR PUBLIC &1 ():
SUPER (DATASET &3:HANDLE).
THIS-OBJECT:DataAccessName = "&9.&8":U .
END CONSTRUCTOR.
/*------------------------------------------------------------------------------
Purpose: Fetch data from the Data Access object
Notes:
@param poFetchDataRequest The IFetchDataRequest object with the parameters for this call
@param &3 The dataset, intended to by passed BY-REFERENCE
------------------------------------------------------------------------------*/
METHOD PUBLIC FINAL VOID FetchDataByReference (poFetchDataRequest AS Consultingwerk.OERA.IFetchDataRequest,
OUTPUT DATASET &3):
THIS-OBJECT:FetchData (poFetchDataRequest, DATASET &3:HANDLE) .
END METHOD.
/*------------------------------------------------------------------------------
Purpose: Provides a hook to modify data in the ProDataset after Read and
Update operations (i.e. population of aggregated values)
Notes: Invoked during FetchData () and SaveChanges ()
------------------------------------------------------------------------------*/
METHOD OVERRIDE PUBLIC VOID ReceiveData ():
@CALC_FIELDS@
END METHOD.
/*------------------------------------------------------------------------------
Purpose: Provides a hook for high level data validation before Update
operations
Notes: Invoked during SaveChanges (). When the ERROR flag of the ProDataset
is set, the Update operation will be cancelled before writing back
the data to the database using the DataAccess object
------------------------------------------------------------------------------*/
METHOD OVERRIDE PUBLIC VOID ValidateData ():
END METHOD.
END CLASS.