Useful Data Handler Methods

The Data Handler class contains many useful methods that you can use when needed. Some of the most useful methods are briefly described below.

Tip: You should take the time to review the “Data Handler Class” chapter in the VPME 9.1 Technical Reference manual to learn about all the properties and methods available to you in the Data Handler class.

Tip – Parameters: The Data Handler class methods listed below have parameters that you need to know when you use them. Refer to the method descriptions in the “VPMDataHandler Class Methods” section of the “Data Handler Class” chapter in the VPME 9.1 Technical Reference manual for descriptions of the parameters.

AddRecord

Adds a record to or copies the current record in the current cursor or the cursor with the alias specified in the parameter stcAlias.

DataChanged

Determines if a change has been made to the current record of the cursor open in the current work area or the cursor specified in the parameter stcAlias. Also checks for changes made to any of the cursors specified in the parameter stcAdditionalAliases. For any of the cursors specified in stcAdditionalAliases that use table buffering, determines if there are any modified or deleted records in the cursor. Otherwise, just determines if the current record has been modified.

DeleteFor

Deletes records in the cursor specified by the parameter stcAlias using the expression specified in the parameter stcExpression. If the parameter stcAlias is empty and a cursor is open in the current work area, the records in that cursor are deleted. The deletions are performed using the DELETE FOR command and the TABLEUPDATE function instead of using the DeleteRecord method, which means the records are deleted without the PreDelete/PostDelete code being run, without the data handler’s RI routine being run, and without the Audit Trail functionality being run.

DeleteRecord

Deletes the current record in the cursor specified in the parameter stcAlias. If the parameter stcAlias is empty and a cursor is open in the current work area, the current record in that cursor is deleted.

FieldValidation

Validates the value in the stValue parameter against the validation rule defined in the data dictionary for a field that is specified in the stcDDDName, stcDDTVName, and stcDDFName parameters.

GenerateGUID

Generates and returns a GUID (Globally Unique ID) string of varying length. The length of the GUID string that is returned is specified by the value that is passed in the stnGUIDLength parameter.

GenerateKey

Generates a character or numeric value to be placed in a field. Normally, this method is run to generate a value to be placed in a key field of a new record. The last used key field values are stored in the table SDATADDGK and are accessed using the view SDATA_V!DDGK_V.

IsNew

Determines whether the current record in the current cursor or the cursor with the alias specified in the parameter stcAlias is new (has been created but not yet saved).

IsNew Potential Problem

There are two situations where IsNew cannot identify whether a record is new or is an existing record without the solution described below:

1.  No Buffering: If the record being checked is in a table that is not buffered, IsNew cannot use the GETFLDSTATE() function to determine if a record has been appended.

2.  Buffering & Deleted Records Recycled: If the record being checked is in a table that is buffered and for which deleted records are recycled (recalled), GETFLDSTATE() does not let IsNew differentiate between a recycled record and any other non-appended record. In this case, if the record was not appended, IsNew needs to determine if the record was recycled, but it cannot do that.

nIsNew Solution

The solution for handling these two situations is for you to add a field named nIsNew (numeric, 1.0) to the table to identify new records.

The value of the nIsNew field in a new record is set to 1 by the AddRecord method and reset to 0 in the SaveRecord method. Then, when the IsNew method is run, a record is determined to be new if the nIsNew field contains a value of 1.

Tip: The nIsNew field does not need to be added to tables that are either (a) edited with row or table buffering and do not recycle deleted records or (b) edited through the use of a view or cursoradapter (with views and cursoradapters, buffering is always used and deleted records are not recycled).

LocateFor

Performs a LOCATE with a FOR expression to find a selected record or records.

OpenCursorAdapter

Opens a cursoradapter cursor. The cursoradapter object that is created must be kept in memory (not released) until the cursor is no longer needed. Therefore, the object cannot be released within this method, and will be stored in the array aCursorAdapterObjects.

OpenTable

Opens the table specified in the parameter stcTable.

OpenView

Opens a view after first defining the variables that are used in the WHERE clause (filter) of the view's SELECT statement. Filter variables that are not used in the current situation (not defined in the parameter staFilterVariables) will be set to values that will cause those variables to not filter out any records. This allows a single view to be used in any number of situations that only require the use of a subset of the filter variables.

RefreshCursorAdapter

Runs the CursorRefresh method of a cursoradapter object after first defining the variables that are used in the WHERE clause (filter) of the cursoradapter's SELECT statement. Filter variables that are not used in the current situation (not defined in the parameter staFilterVariables) will be set to values that will cause those variables to not filter out any records. This allows a single cursoradapter to be used in any number of situations that only require the use of a subset of the filter variables.

RequeryView

Performs a REQUERY() on a view cursor after first defining the variables that are used in the WHERE clause (filter) of the view's SELECT statement. Filter variables that are not used in the current situation (not defined in the parameter staFilterVariables) will be set to values that will cause those variables to not filter out any records. This allows a single view to be used in any number of situations that only require the use of a subset of the filter variables.

RestoreRecord

Cancels the changes to the current record in the cursor specified in the parameter stcAlias. If the parameter stcAlias is empty and a cursor is open in the current work area, the changes to the current record in that cursor are cancelled.

SaveRecord

Saves the changes to the current record in the cursor specified in the parameter stcAlias. If the parameter stcAlias is empty and a cursor is open in the current work area, the changes to the current record in that cursor are saved.

SetFilter

Sets or removes a filter on the current cursor or the cursor with the alias specified in the parameter stcAlias. A filter is removed by passing the null string or .F. in the parameter stcFilterExpression.

SetOrder

Sets the master (controlling) tag of the current cursor or the cursor with the alias specified in the parameter stcAlias. If the tag specified in the parameter stcTagName does not exist for a view or cursoradapter cursor the tag will be created if an expression is passed in the parameter stcCreateTagExpression or the tag definition can be found in the SDATADDIT table.

SetRelation

Sets or removes a relation from the current cursor or the cursor with the alias specified in the parameter stcAlias. A relation is removed by passing the null string or .F. in the parameter stcRelationExpression.

More:

Useful Data Handler Properties