VPMDataHandler Class Methods

The following table lists the class methods. The methods listed include the standard Visual FoxPro class methods that the VPM Enterprise class uses and the VPM Enterprise custom methods. Where appropriate, the Comments column of the table describes a method and provides suggestions for its use.

 

Property & Initial Value

Comments

Standard Methods Used:

 

Destroy

Calls the Cleanup method.

Error

Calls the appropriate method that will handle the error that occurred within the data handler, passing on the parameters that it received.

Init

Calls the methods that set up the data handler environment.

Custom Methods:

 

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.

Parameters:

stcAlias – The alias of the cursor to which the record will be added.

stlCopy – Specifies whether the current record should be copied (.T.) or a new record should be created (.F.).

stcRulesID – Passed on to business rules methods so that code in those methods can run conditionally if necessary. If this method is run for a record being added on a form the contents of the form’s cRulesID property is passed to this method.

stlNoRecycle – Specifies whether a deleted record is recalled (.F.) or a record is appended (.T.).

stlNoDefaultValues – Specifies whether or not the DefaultValues method should be run to fill in default values into the fields of the new record.

stlBlankPKOnCopy – Specifies whether or not the PK field(s) of the copied record are blanked-out.

stlPreSaveDefaults – Specifies whether the add-time default values or pre-save default values are placed in the fields.

stcUpdateAliases – A comma-delimited list of aliases that specifies the additional cursors into which a new or copied record should be created.

stnParentRow – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

stcChildFKFlds – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

stcParentPKFlds – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

stcParentAlias – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

Returns:

.T. – The record was created.

.F. – The record was not created.

AuditTrail_Cancel

Run by the SaveRecord and DeleteRecord methods when the save or delete has not been completed successfully. Removes all of the Audit Trail records from the cursor that was populated by the ReferentialIntegrity_Start method.

AuditTrail_OK

Run by the SaveRecord and DeleteRecord methods when the save or delete has been completed successfully. Saves all of the Audit Trail records in the cursor that was populated by the ReferentialIntegrity_Start method.

AuditTrail_Start

Run by the SaveRecord and DeleteRecord methods to create the cursor to which Audit Trail records are added by the ReferentialIntegrity_Start method.

BypassVariables

Determines the values that will be used to make WHERE clause variables of views and cursoradapters not filter out any records. The “bypass” values that are used are specific to the data source (VFP table, SQL Server database, Oracle database, etc.). This method identifies the data source of the view or cursoradapter identified in the parameters and then calls the BypassVariables_SetProperties method to place the bypass values of the data source into properties.

Parameters:

stcDDTVName – Along with the following parameter identifies the view or cursoradapter for which the bypass values are being determined.

stcDDDName – See above for description.

stlRemoteView – If .T., specifies that the view identified in the other parameters is a remote view.

Required Parameters:

stcDDTVName

stcDDDName

Properties:

cBypassVariables_LastDDD – Used to speed up the process.

cBypassVariables_LastDDTV – Used to speed up the process.

Returns:

.T.

BypassVariables_SetProperties

Determines the values that will be used to make WHERE clause variables not filter out any records. The “bypass” values that are used are specific to the data source (VFP table, SQL Server database, Oracle database, etc.) and are stored in the SDATADDDS (Data Sources) table. The stcDataSource parameter identifies the SDATADDDS record from which the bypass values will be taken and placed in properties.

Parameters:

stcDataSource – PK of Data Sources record that contains bypass values.

Required Parameters:

stcDataSource

Properties:

cBypassVariables_Wildcard – See descriptions of SDATADDDS (Data Sources) fields.

cBypassVariables_Max – See above.

cBypassVariables_Min – See above.

dBypassVariables_Max – See above.

dBypassVariables_Min – See above.

nBypassVariables_Max – See above.

nBypassVariables_Min – See above.

Returns:

.T.

CalculateCheckSum

Calculates a four-character check sum value for the string that is passed to this method. By default it is assumed that the string contains a check sum as the first four characters. Therefore, the check sum calculation starts with the fifth character in the string. The stnStartingPosition parameter can be used to specify an alternate calculation starting position.

Parameters:

stcString – The string on which the calculation is performed.

stnStartingPosition – Specifies the starting position of the calculation.

Required Parameters:

stcString

Returns:

A four-character check sum string.

Cleanup

Called by the Init event if any of the methods called from the Init code return a false value. Called by the Destroy event when the Data Handler object is released. Performs cleanup activities like releasing class libraries, releasing object references, and closing cursors.

Cleanup_CursorAdapterObjects

Called by the Cleanup method to release any remaining cursoradapter objects that are stored in the array aCursorAdapterObjects.

Cleanup_Data

Called by the Cleanup method to close all cursors after reverting unsaved changes.

CloseViewSourceTables

When a view is opened, VFP opens the view’s source table(s). When a view cursor is closed, the source table(s) are left open. This method is used in conjunction with the OpenView method to close the view’s source table(s) when the view cursor is closed.

Parameters:

stlInitialize – When .T., causes the recording of open view source tables to commence. When .F., causes those tables to be closed.

Properties:

aCloseViewSourceTables[<alias>]

lCloseViewSourceTables

nCloseViewSourceTables

Returns:

.T.

CreateErrorRecord

Logs an error in the Errors table.

Determines if the Errors table is nearing the VFP file size limit (see lErrorsTableNearingSizeLimit property).

Parameters:

stnErrorNumber – The error number.

stcErrorMessage – The error message.

stcClassOrProgram – The name of the class or program that contains the code where the error occurred.

stcMethodOrProcedure – The name of the class or procedure that contains the code where the error occurred.

stnSourceLineNumber – The line number of the line of code that caused the error to occur.

stcCode – The line of code that caused the error to occur.

Required Parameters:

stnErrorNumber

stcErrorMessage

stcClassOrProgram

stcMethodOrProcedure

stnSourceLineNumber

stcCode

Returns:

.T. – The record was created.

.F. – The record was not created.

CursorAdapterIdentification

Various processes in VPM require that data dictionary information be retrieved for cursoradapter cursors. This method saves/retrieves the information that identifies the table, view, or cursoradapter whose data dictionary information should be used for a particular cursoradapter cursor.

Parameters:

stcAlias – The alias of the cursoradapter cursor for which the information is saved/retrieved.

stcCAIdentification – The information that is saved is parsed from the string passed in this parameter. If this parameter is empty the information is retrieved. Otherwise the information in this parameter is saved. Format of string in this parameter: <DBC or CursorAdapter Library name>!<Table, View, or CursorAdapter name>

Required Parameters:

stcAlias

Properties:

cCAID_Alias

cCAID_DDD_Name

cCAID_DDTV_Name

Returns:

.T. – The information was saved, or the information was retrieved and loaded into the properties.

.F. – The information was not saved, or the information was not retrieved and the properties contain default (empty) values.

CursorIdentification

Various processes in VPM require that data dictionary information be retrieved for cursors. This method identifies the information necessary to find data dictionary records for a cursor. For cursoradapter cursors this information cannot be determined directly from the cursor itself and is therefore determined through a subsequent call to the CursorAdapterIdentification method.

Parameters:

stcAlias – The alias of the cursor for which the information is retrieved.

Required Parameters:

stcAlias

Properties:

cCursorID_DDD_Name

cCursorID_DDTV_Name

nCursorID_SourceType

Returns:

.T. – The properties were loaded and contain values.

.F. – The properties contain default (empty) values.

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.

Parameters:

stcAlias – The alias of the cursor for which the determination is made.

stcAdditionalAliases – A comma-delimited list of aliases that specifies the additional cursors to be included in the determination.

Returns:

.T. – A change has been made.

.F. – A change has not been made.

DecryptString

Decrypts the string passed to this method.

Parameters:

stcString – The string to be decrypted.

stcEncryptionCharacter – Specifies an alternate character to be used in the decryption algorithm.

Required Parameters:

stcString

Returns:

A string of the same length as the string that was passed to this method.

DefaultValues

Places default values into fields in the current record of the cursor open in the current work area or the cursor specified in the parameter stcAlias. Default values are determined by running one of the key generation routines or executing the Default code stored for each field in the SDATADDF table. If this method is run for a copied record Default vaules are created only for primary key fields.

Parameters:

stcAlias – The alias of the cursor that contains the record into which the default values are placed.

stlPreSaveDefaults – Specifies whether the add-time default values or pre-save default values are placed in the fields.

stcRulesID – Passed on to the Default code so that parts of the code can run conditionally if necessary. If this method is run for a record being added on a form the contents of the form’s cRulesID property is passed to this method.

stlCopy – Specifies whether or not the default values are being placed in a new record or a copied record.

stlBlankPKOnCopy – Specifies whether or not the PK field(s) of the copied record are blanked-out.

stnParentRow – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

stcChildFKFlds – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

stcParentPKFlds – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

stcParentAlias – Used by VPM forms to fill in FK field value(s) in a child record with the PK field value(s) from the current parent record.

stcNotBlankFields – Used by the SaveRecord method to cause empty required fields to be filled-in with default values when the record is saved.

Returns:

.T. – Default values were placed in the fields.

.F. – Default values were not placed in the fields.

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.

Parameters:

stcAlias – The alias of the cursor that contains the records to be deleted.

stcExpression – The expression used to select the records to be deleted.

Required Parameters:

stcExpression

Returns:

.T. – The records were deleted.

.F. – The records were not deleted.

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.

Parameters:

stcAlias – The alias of the cursor that contains the record to be deleted.

stcRulesID – Passed on to business rules methods so that code in those methods can run conditionally if necessary. If this method is run for a record being deleted on a form the contents of the form’s cRulesID property is passed to this method.

stnGoToRecNo – The record number of the record where the record pointer is positioned after the deletion is completed. If this parameter is not used the record pointer is positioned on the record following the deleted record according to the master tag.

stlNoAuditTrail – Specifies whether or not Audit Trail records are created for the deletion.

stlNoRICall – Specifies whether or not the RI routine is called. If not, both the RI check and the Audit Trail functionality are disabled.

stlNoRICheck – Specifies whether or not RI check is performed.

Properties:

cRIMessage – Contains error information when 2, 5, or 7 value is returned.

Returns:

0 – Deletion completed.

1 – PreDelete method or code in mPreDeleteCode returned .F., deletion aborted.

2 – Failed VPM RI check, deletion aborted.

3 – Delete trigger failed, deletion aborted.

4 – TABLEUPDATE failed, deletion aborted.

5 – Error occurred, deletion aborted.

6 – Transaction failed, deletion aborted.

7 – TABLEUPDATE failed, deletion aborted (ODBC error occurred).

8 – PostDelete method or code in mPostDeleteCode returned .F., deletion aborted.

9 – PreDeletePreTransaction method or code in mPreDeletePreTransactionCode returned .F., deletion aborted

EmptyRequiredFields

Determines if any of the required fields in the current record of the current cursor or the cursor with the alias specified in the parameter stcAlias are empty or contain a null value. Required fields are those that have the Integrity Option set to “On”. This method returns the number of required fields that do not contain a value. Those required fields that do not contain a value are loaded into the array aEmptyRequiredFields.

Parameters:

stcAlias – The alias of the cursor that contains the record for which the check is performed.

stcNotBlankFields – If only specific fields should be checked, a comma-delimited list of fields can be passed in this parameter. If there are fields from more than one cursor in the list, the field names should contain the alias (<alias>.<field name>) so that only those fields in the current alias (stcAlias) will be checked.

stlCheckNoAlias – If one or more of the fields in the stcNotBlankFields list do not contain the alias, this parameter should be used to specify when those fields should be checked.

Properties:

aEmptyRequiredFields[<field name>, <field description>]

Returns:

The number of required fields that do not contain a value (corresponds to number of rows in aEmptyRequiredFields).

EncryptString

Encrypts the string passed to this method.

Parameters:

stcString – The string to be encrypted.

stcEncryptionCharacter – Specifies an alternate character to be used in the encryption algorithm.

Required Parameters:

stcString

Returns:

A string of the same length as the string that was passed to this method.

EvaluateExpression

Selects the alias or work area specified by the parameter stAliasOrWorkArea and then evaluates the expression specified in the parameter stcExpression. If the parameter stAliasOrWorkArea is empty and a cursor is open in the current work area, the expression is evaluated with the current work area still selected.

Parameters:

stAliasOrWorkArea – The alias or work area to be selected before the expression in stcExpression is evaluated.

stcExpression – The expression that is evaluated.

Required Parameters:

stcExpression

Returns:

A value that is the result of the evaluation of the expression.

ExtractFindVariables

Loads the aBypassFindVariables array with the names of the Find variables from the WHERE clause of a SELECT statement and the “bypass” values that will cause those variables to not filter out any records. Called by the OpenView, OpenCursorAdapter, RequeryView, and RefreshCursorAdapter methods.

Note: The BypassVariables method must be run before this method is run.

Parameters:

stcDDTVName – Along with the following parameter identifies the view or cursoradapter for which the aBypassFindVariables array is being loaded.

stcDDDName – See above for description.

stcSelectStatement – The SELECT statement of the view or cursoradapter identified in the other parameters.

Required Parameters:

stcDDTVName

stcDDDName

stcSelectStatement

Properties:

aBypassFindVariables – Contains a row for each Find variable in the WHERE clause of the SELECT statement. Column 1 contains the variable name. Column 2 contains the bypass value.

cExtractFindVariables_LastDDD – Used to speed up the process.

cExtractFindVariables_LastDDTV– Used to speed up the process.

nBypassFindVariables – The number of rows in the aBypassFindVariables array.

Returns:

.T.

ExtractGetVariables

Loads the aBypassGetVariables array with the names of the Get variables from the WHERE clause of a SELECT statement and the “bypass” values that will cause those variables to not filter out any records. Called by the OpenView, OpenCursorAdapter, RequeryView, and RefreshCursorAdapter methods.

Note: The BypassVariables method must be run before this method is run.

Parameters:

stcDDTVName – Along with the following parameter identifies the view or cursoradapter for which the aBypassGetVariables array is being loaded.

stcDDDName – See above for description.

stcSelectStatement – The SELECT statement of the view or cursoradapter identified in the other parameters.

Required Parameters:

stcDDTVName

stcDDDName

stcSelectStatement

Properties:

aBypassGetVariables – Contains a row for each Get variable in the WHERE clause of the SELECT statement. Column 1 contains the variable name. Column 2 contains the bypass value.

cExtractGetVariables_LastDDD – Used to speed up the process.

cExtractGetVariables_LastDDTV– Used to speed up the process.

nBypassGetVariables – The number of rows in the aBypassGetVariables array.

Returns:

.T.

ExtractRIVariables

Loads the aBypassRIVariables array with the names of the RI variables from the WHERE clause of a SELECT statement and the “bypass” values that will cause those variables to not filter out any records. Called by the OpenView, OpenCursorAdapter, RequeryView, and RefreshCursorAdapter methods.

Note: The BypassVariables method must be run before this method is run.

Parameters:

stcDDTVName – Along with the following parameter identifies the view or cursoradapter for which the aBypassRIVariables array is being loaded.

stcDDDName – See above for description.

stcSelectStatement – The SELECT statement of the view or cursoradapter identified in the other parameters.

Required Parameters:

stcDDTVName

stcDDDName

stcSelectStatement

Properties:

aBypassRIVariables – Contains a row for each RI variable in the WHERE clause of the SELECT statement. Column 1 contains the variable name. Column 2 contains the bypass value.

cExtractRIVariables_LastDDD – Used to speed up the process.

cExtractRIVariables_LastDDTV– Used to speed up the process.

nBypassRIVariables – The number of rows in the aBypassRIVariables array.

Returns:

.T.

FieldChanged

Determines if a change has been made to a particular field in the current record of the cursor open in the current work area or the cursor specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor that contains the field for which the determination is made.

stcField – The name of the field for which the determination is made.

Returns:

.T. – A change has been made.

.F. – A change has not been made.

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.

Parameters:

stcDDDName – Along with the following two parameters identifies the field for which the value in stValue is validated

stcDDTVName – See above for description.

stcDDFName – See above for description.

stValue – The value being validated.

stcRulesID – Passed on to business rules methods so that code in those methods can run conditionally if necessary. If this method is run for a field/control on a form the contents of the control’s cValidRulesID property is passed to this method.

stcRefFilterExpr – The filter expression to be applied to the table that is used to validate the value.

staRefFilterVariables – The filter variables and values to be used with the view that is used to validate the value.

stlRecordLevel – If .T., the field is being validated prior to a record being saved.

Required Parameters:

stcDDDName

stcDDTVName

stcDDFName

stValue

Properties:

cFieldValidationReturnMessage

Returns:

.T. – The value passed the validation check.

0 (zero) – The value failed the validation check.

The value returned by the developer’s code.

FieldValidation_RecordLevel

Called from the SaveRecord method. Calls the FieldValidation method to determine if any of the fields in the current record of the current cursor or the cursor with the alias specified in the parameter stcAlias contain an invalid value. This method returns the number of fields that contain an invalid value. Information about the fields that contain an invalid value is loaded into the array aRecordLevelInvalidFields.

Parameters:

stcAlias – The alias of the cursor that contains the record for which the field values are validated.

stcRulesID – Passed on to business rules methods so that code in those methods can run conditionally if necessary. If this method is run for a record on a form the contents of the form’s cRulesID property is passed to this method.

Properties:

aRecordLevelInvalidFields [<field name>, <field description>, <validation message>]

Returns:

The number of fields that contain an invalid value (corresponds to number of rows in aRecordLevelInvalidFields).

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.

Parameters:

stnGUIDLength – Specifies the length and format of the GUID string that is returned.

Returns: A string in one of the following formats depending on the stnGUIDLength value.

16 or .T. – Binary GUID

Example: ζKj£H?PM?«.ΝΈ ΚΏ

22 – GUID converted to 0-9, A-Z, and non-alpha, non-code page based characters

Example: %J6ZNG6+Y47<)OI@Z\$@N~

23 – GUID converted to 0-9, A-Z, a-z, ‘+’, and ‘-‘

Example: 3aGqeXG8pEHM6fZQqs2QezX

26 – GUID converted to 0-9 and A-V

Example: 769DLA6I4DA16O3ASLPMS0JILV

32 – GUID without ‘-‘, ‘{‘, and ‘}’

Example: A36A4BE68D484D5081AB95CDB 809CABF

36, .F., or non-supported length – GUID with ‘-‘ but without ‘{‘ and ‘}’

Example: A36A4BE6-8D48-4D50-81AB-95CDB809CABF

38 – GUID with ‘-‘, ‘{‘, and ‘}’

Example: {A36A4BE6-8D48-4D50-81AB-95CDB809CABF}

48 – Binary GUID converted to a string of ANSI character values

Example: 22313517707717417907406515110 2008183174119043176

128 – Binary GUID converted to a string of ‘0’s and ‘1’s

Example: 111001100100101101101010101…

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.

Parameters:

stcFieldPK – The string used to find the field’s record in the Generated Key table.

stlGenerateNumeric – The last value generated is stored in a character field in the Generated Key table. However, the value returned by this method does not have to be stored in a character field. If this parameter is .T., the value returned by this method will be numeric, which can be stored in a numeric, integer, float, double, or currency field. Otherwise, the value returned by this method will be of character type, which can be stored in a character or memo field.

stcDDDName – Along with the following two parameters identifies the field for which the key is being generated. If this is the first time a key is being generated for the field, these parameter values are placed in the cDescription field of the SDATADDGK record that is created.

stcDDTVName – See above for description.

stcDDFName – See above for description.

Required Parameters:

stcFieldPK

Returns:

A value to be placed in the field.

.F. – A value for the field cannot be generated.

GenerateKey_Increment

Increments the character value passed to this method by the GenerateKey method and returns that incremented character value.

Parameters:

stcLastUsed – The value that this method is to increment.

Returns:

A character string representing the incremented value.

GetAlias

Returns the alias of the cursor open in the current work area.

Returns:

The alias of the cursor that is open in the current work area or the null string if a cursor is not open in the current work area.

GetDDCK

Retrieves into a view cursor (alias ddck_v_dh) the SDATADDCK (Candidate Keys) records for the table, view, or cursoradapter specified in the parameters.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the records are retrieved.

stcDDTVName – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

Required Parameters:

stcDDDName

stcDDTVName

Returns:

.T. – The view cursor was created.

.F. – The view cursor was not created.

GetDDD

Retrieves into an object the SDATADDD (Databases and CursorAdapter Libraries) record for the database or cursoradapter library specified in the parameters.

Parameters:

stcDDDName – Identifies the database or cursoradapter library for which the record is retrieved.

stcPKValue – The PK value of the record to be retrieved.

Required Parameters:

stcDDDName; or

stcPKValue

Properties:

oDDDRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDF

Retrieves into an object the SDATADDF (Fields) record for the field specified in the parameters.

Parameters:

stcDDDName – Along with the following two parameters identifies the field for which the record is retrieved.

stcDDTVName – See above for description.

stcDDFName – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

stcPKValue – The PK value of the record to be retrieved.

stcParentPKValue – Along with the stcDDFName parameter identifies the field for which the record is retrieved. This parameter (the PK value of an SDATADDTV record) identifies the table, view, or cursoradapter that contains the field identified in the stcDDFName parameter.

Required Parameters:

stcDDDName, stcDDTVName, and stcDDFName; or

stcPKValue; or

stcParentPKValue and stcDDFName

Properties:

oDDFRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDF_All

Retrieves into a view cursor (alias ddfall_v) the SDATADDF (Fields) records for the table, view, or cursoradapter specified in the parameters.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the records are retrieved.

stcDDTVName – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

stcParentPKValue – This parameter (the PK value of an SDATADDTV record) identifies the table, view, or cursoradapter for which the records are retrieved.

Required Parameters:

stcDDDName and stcDDTVName; or

stcParentPKValue

Returns:

.T. – The view cursor was created and contains at least one record.

.F. – The view cursor was not created or does not contain any records.

GetDDFH

Retrieves into an object the SDATADDFH (Field Help) record for the field specified in the parameters.

Parameters:

stcDDDName – Along with the following two parameters identifies the field for which the record is retrieved.

stcDDTVName – See above for description.

stcDDFName – See above for description.

Required Parameters:

stcDDDName

stcDDTVName

stcDDFName

Properties:

oDDFHRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDFP

Retrieves into an object the SVPMDDFP (Field Picklists) record for the field specified in the parameters.

Parameters:

stcDDDName – Along with the following two parameters identifies the field for which the record is retrieved.

stcDDTVName – See above for description.

stcDDFName – See above for description.

stcID – Identifies the specific Picklist definition whose record is to be retrieved for the field. If empty, the default Picklist definition record is retrieved for the field. The parameter value corresponds to the value in the cID field in the SVPMDDFP record to be retrieved. If a Picklist is being brought up for control, the parameter value also corresponds to the value in the cPicklistID property of the control for which the Picklist is being brought up.

Required Parameters:

stcDDDName

stcDDTVName

stcDDFName

Properties:

oDDFPRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDGK

Retrieves into an object the SDATADDGK (Generated Keys) record for the field specified in the parameters.

Parameters:

stcDDDName – Along with the following two parameters identifies the field for which the record is retrieved.

stcDDTVName – See above for description.

stcDDFName – See above for description.

Required Parameters:

stcDDDName

stcDDTVName

stcDDFName

Properties:

oDDGKRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDIT

Retrieves into an object the SDATADDIT (Index Tags) record for the tag specified in the parameters.

Parameters:

stcDDDName – Along with the following two parameters identifies the tag for which the record is retrieved.

stcDDTVName – See above for description.

stcTag – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

stcPKValue – The PK value of the record to be retrieved.

stcParentPKValue – Along with the stcTag parameter identifies the tag for which the record is retrieved. This parameter (the PK value of an SDATADDTV record) identifies the table, view, or cursoradapter whose tag is identified in the stcTag parameter.

Required Parameters:

stcDDDName, stcDDTVName, and stcTag; or

stcPKValue; or

stcParentPKValue and stcTag

Properties:

oDDITRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDIT_All

Retrieves into a view cursor (alias dditall_v) the SDATADDIT (Index Tags) records for the table, view, or cursoradapter specified in the parameters.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the records are retrieved.

stcDDTVName – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

stcParentPKValue – This parameter (the PK value of an SDATADDTV record) identifies the table, view, or cursoradapter for which the records are retrieved.

Required Parameters:

stcDDDName and stcDDTVName; or

stcParentPKValue

Returns:

.T. – The view cursor was created and contains at least one record.

.F. – The view cursor was not created or does not contain any records.

GetDDIT_PK

Retrieves into an object the SDATADDIT (Index Tags) record for the PK tag of the table, view, or cursoradapter specified in the parameters.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the PK tag record is retrieved.

stcDDTVName – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

stcParentPKValue – This parameter (the PK value of an SDATADDTV record) identifies the table, view, or cursoradapter for which the PK tag record is retrieved.

Required Parameters:

stcDDDName and stcDDTVName; or

stcParentPKValue

Properties:

oDDITRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDIT_TagType

Retrieves into an object the SDATADDIT (Index Tags) record for the type of tag specified in the parameter stnTagType for the table specified in the other parameters.

Parameters:

stcDDDName – Along with the following parameter identifies the table for which the record is retrieved.

stcDDTVName – See above for description.

stcParentPKValue – This parameter (the PK value of an SDATADDTV record) identifies the table for which the record is retrieved.

stnTagType – 1 (Candidate), 2 (VFP Primary), 3 (Unique)

Required Parameters:

stcDDDName, stcDDTVName, and stnTagType; or

stcParentPKValue and stnTagType

Properties:

oDDITRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetDDSI

Retrieves into a view cursor (alias ddsi_v_dh) the SDATADDSI (Set Integrity) records for the field specified in the parameters.

Parameters:

stcDDDName – Along with the following two parameters identifies the field for which the records are retrieved.

stcDDTVName – See above for description.

stcDDFName – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

stcParentPKValue – This parameter (the PK value of an SDATADDF record) identifies the field for which the records are retrieved.

Required Parameters:

stcDDDName, stcDDTVName, and stcDDFName; or

stcParentPKValue

Returns:

.T. – The view cursor was created and contains at least one record.

.F. – The view cursor was not created or does not contain any records.

GetDDTV

Retrieves into an object the SDATADDTV (Tables, Views, and CursorAdapters) record for the table, view, or cursoradapter specified in the parameters.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the record is retrieved.

stcDDTVName – See above for description.

stlFindLocal – If the stcDDDName and stcDDTVName properties identify a remote view and that remote view is not in the data dictionary, this parameter specifies whether or not the data dictionary information for the related local view should be used for the remote view.

stcPKValue – The PK value of the record to be retrieved.

Required Parameters:

stcDDDName and stcDDTVName; or

stcPKValue

Properties:

GetDDTV_cFK_DDD – Used to determine if the object whose reference is stored in the oDDTVRecord property is the object that has been requested. If so, there is no need to retrieve the record again.

GetDDTV_cName – See above.

GetDDTV_cPK – See above.

oDDTVRecord

Returns:

.T. – The object was created.

.F. – The object was not created.

GetFilter

Returns the filter expression that is in use with the current cursor or the cursor with the alias specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor for which the current filter expression is returned.

Returns:

The current filter expression.

GetOrder

Returns the name of the master (controlling) index tag for the current cursor or the cursor with the alias specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor for which the current master tag name is returned.

Returns:

The name of the master (controlling) tag if a tag is in use.

The null string if no tag is in use.

GetRecNo

Returns the record pointer position (record number) of the current cursor or the cursor with the alias specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor for which the current record pointer position is returned.

Returns:

The current record number if the record pointer is not at end-of-file.

The number 0 (zero) if the record pointer is at end-of-file.

GoEOF

Moves the record pointer to end-of-file in the current cursor or the cursor with the alias specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor in which the record pointer is moved.

Returns:

.T.

GoFirst

Moves the record pointer to the first record in the current cursor or the cursor with the alias specified in the parameter stcAlias. The pointer is moved according to the master tag.

Parameters:

stcAlias – The alias of the cursor in which the record pointer is moved.

Returns:

The record number of the selected (first) record.

The number 0 (zero) if no records are in the cursor or the alias specified in the parameter stcAlias not in use.

GoLast

Moves the record pointer to the last record in the current cursor or the cursor with the alias specified in the parameter stcAlias. The pointer is moved according to the master tag.

Parameters:

stcAlias – The alias of the cursor in which the record pointer is moved.

Returns:

The record number of the selected (last) record.

The number 0 (zero) if no records are in the cursor or the alias specified in the parameter stcAlias not in use.

GoNext

Moves the record pointer in the current cursor or the cursor specified in the parameter stcAlias. The pointer is moved according to the master tag.

Parameters:

stcAlias – The alias of the cursor in which the record pointer is moved.

stnRecs – The record pointer is moved the number of records specified in this parameter. If a positive number, the record pointer is moved forward. If a negative number, the record pointer is moved backward. If empty, the record pointer is positioned one record forward.

Returns:

0 – Not EOF() or BOF()

1 – EOF()

2 – BOF()

3 – EOF() and BOF()

GoRecNo

Moves the record pointer to the record specified in the parameter stnRecNo in the current cursor or the cursor with the alias specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor in which the record pointer is moved.

stnRecNo – The record number where the record pointer should be positioned. If 0 (zero), the record pointer is moved to end-of-file.

Required Parameters:

stnRecNo

Returns:

.T. – The record pointer was moved to the desired record.

.F. – The record pointer was not moved to the desired record.

IdentifyCallingApplication

Identifies the application from which this object was instantiated by setting the value of the nCalledFrom property. Called by the InitializeProperties method when the data handler object is instantiated.

Properties:

nCalledFrom – If 1, data handler object was instantiated from within VPM Enterprise or a VPM Enterprise application. Otherwise, property will be set to 2.

Returns:

.T.

InitializeProperties

Initializes selected properties. Called by the Init event when the data handler object is instantiated.

InstantiateBusinessRulesObject

Instantiates the Business Rules object. Called by the Init event when the data handler object is instantiated.

Returns:

.T. – The business rules object was instantiated.

.F. – The business rules object was not instantiated.

IsBOF

Determines whether or not the record pointer has been attempted to be moved above the first record in the current cursor or the cursor with the alias specified in the parameter stcAlias. When this happens, the record pointer remains on the first record and this method returns .T..

Parameters:

stcAlias – The alias of the cursor for which the determination is made.

Returns:

.T. – BOF() returned .T.

.F. – BOF() returned .F.

IsEOF

Determines whether or not the record pointer is at end-of-file for the current cursor or the cursor with the alias specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor for which the determination is made.

Returns:

.T. – The record pointer is at end-of-file.

.F. – The record pointer is not at end-of-file.

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).

Parameters:

stcAlias – The alias of the cursor for which the determination is made.

stlAndEmpty – If .T., the determination is made as to whether the record is new and no changes have been made to the new record.

Properties:

lIsNew_Recycled – Set to .T. if the record is new and recycled.

Returns:

.T. – The record is new but changed (stlAndEmpty = .F.) or is new and unchanged (stlAndEmpty = .T. or .F.).

.F. – The record is new but changed (stlAndEmpty = .T.) or is not new (stlAndEmpty = .T. or .F.).

IsUsed

Determines whether or not a cursor is open in the current work area, or whether or not the cursor with the alias specified in the parameter stcAlias is open.

Parameters:

stcAlias – The alias of the cursor for which the determination is made.

Returns:

.T. – A cursor is open in the current work area (if stcAlias is empty) or a specific cursor is open in any work area (if alias is specified in stcAlias).

.F. – A cursor is not open in the current work area (if stcAlias is empty) or a specific cursor is not open in any work area (if alias is specified in stcAlias).

LocateFor

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

Parameters:

stcAlias – The alias of the cursor in which the LOCATE is performed.

stcLocateExpr – The expression used to find the record(s).

stlUseCurrentTag – If .F. (the default), and the master tag does not have a FOR expression, performs the LOCATE without a tag in use to speed up the LOCATE.

stlContinue – If .T., performs a CONTINUE after the initial LOCATE. If the CONTINUE is successful (a record is found), the record number of that record is placed in the property nContinueRec and the record pointer is moved back to the initially located record. This parameter can be used to determine if more than one record matches the search criteria.

Properties:

nContinueRec – Contains a record number if CONTINUE was successful, 0 (zero) otherwise.

Returns:

.T. – A record was found.

.F. – A record was not found.

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.

Parameters:

stcClassName – The CursorAdapter class name from which the cursoradapter object is instantiated.

stcModule – The name of the VCX file or program that contains the class specified in stcClassName (can include path).

stcInApplication – The name of the VFP application (EXE or APP) containing the VCX file specified in stcModule (extension must be included).

staFilterVariables – The reference to an array that contains the definition of filter variables that will be set before the cursor is created, causing records to be excluded from the cursor. If empty (null, blank, zero, .F., or no parameter), no filter variables are defined. Otherwise, a reference to a two-dimensional array that defines the variables used in the WHERE clause of the cursoradapter’s SELECT statement. Prior to the cursor being created the variables listed in the array are defined using the name from column 1 and the value from column 2.

stcAlias – Used to override the Alias property value of the cursoradapter object.

stlNoData – Passed to the cursoradapter object’s CursorFill method.

stcCAIdentification – Identifies the table, view, or cursoradapter whose information in the data dictionary should be used for the cursoradapter cursor being created. The table, view, or cursoradapter is identified as a string formatted as: <DBC or CursorAdapter Library name>!<Table, View, or CursorAdapter name>. If this parameter is not passed, the cursoradapter itself is assumed to be in the data dictionary and is identified as stcModule+’!’+stcClassName. See the CursorAdapterIdentification method for more information.

stlNoCursorSchema – If .T., .F. is passed to the cursoradapter object’s CursorFill method.

stOptions – Passed to the cursoradapter object’s CursorFill method.

stSource – Passed to the cursoradapter object’s CursorFill method.

stParameter1 through stParameter10 – The parameters are passed to the Init event of the cursoradapter object when the object is instantiated.

Required Parameters:

stcClassName

Properties:

aCursorAdapterObjects[<alias>, <object reference>]

Returns:

.T. – The cursor was created.

.F. – The cursor was not created.

OpenDatabase

Opens the database specified in the parameter stcDatabase. If stcDatabase is empty, all of the databases listed in the SDATADDD table are opened.

Parameters:

stcDatabase – The name of the database to be opened.

Returns:

.T. – The database was opened.

.F. – The database was not opened.

OpenTable

Opens the table specified in the parameter stcTable.

Parameters:

stcTable – The name of the table to open. The path and/or extension can be included. If empty (null, blank, .F., or no parameter), a SELECT 0 is issued (an unused work area is selected).

stcAlias – The alias to be assigned to the cursor when the table is opened. If empty (null, blank, .F., or no parameter), the alias will be the same as the table name.

stlAgain – Determines whether or not the AGAIN clause is included in the USE command that is used to open the table. If empty (null, blank, .F., or no parameter), the AGAIN clause is not included. Otherwise, the AGAIN clause is included.

stlExclusive – Determines whether or not the EXCLUSIVE clause is included in the USE command that is used to open the table. If empty (null, blank, .F., or no parameter), the EXCLUSIVE clause is not included. Otherwise, the EXCLUSIVE clause is included.

stlNoUpdate – Determines whether or not the NOUPDATE clause is included in the USE command that is used to open the table. If empty (null, blank, .F., or no parameter), the NOUPDATE clause is not included. Otherwise, the NOUPDATE clause is included.

Returns:

.T. – The table was opened.

.F. – The table was not opened.

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.

Parameters:

stcView – The name of the view to open.

stcDBC – The name of the database that contains the view to open. The path and/or extension can be included.

staFilterVariables – The reference to an array that contains the definition of view filter variables that will be set before the view cursor is created, causing records to be excluded from the cursor. If empty (null, blank, zero, .F., or no parameter), no filter variables are defined. Otherwise, a reference to a two-dimensional array that defines the variables used in the WHERE clause of the view’s SELECT statement. Prior to the view being opened the variables listed in the array are defined using the name from column 1 and the value from column 2.

stcAlias – The alias to be assigned to the cursor when the view is opened. If empty (null, blank, .F., or no parameter), the alias will be the same as the view name.

stlAdmin – Determines whether or not the ADMIN clause is included in the USE command that is used to open the view. If empty (null, blank, .F., or no parameter), the ADMIN clause is not included. Otherwise, the ADMIN clause is included.

stlExclusive – Determines whether or not the EXCLUSIVE clause is included in the USE command that is used to open the view. If empty (null, blank, .F., or no parameter), the EXCLUSIVE clause is not included. Otherwise, the EXCLUSIVE clause is included.

stlNoData – Determines whether or not the NODATA clause is included in the USE command that is used to open the view. If empty (null, blank, .F., or no parameter), the NODATA clause is not included. Otherwise, the NODATA clause is included.

stlNoRequery – Determines whether or not the NOREQUERY clause is included in the USE command that is used to open the view. If empty (null, blank, .F., or no parameter), the NOREQUERY clause is not included. Otherwise, the NOREQUERY clause is included.

stlNoUpdate – Determines whether or not the NOUPDATE clause is included in the USE command that is used to open the view. If empty (null, blank, .F., or no parameter), the NOUPDATE clause is not included. Otherwise, the NOUPDATE clause is included.

stlOnline – Determines whether or not the ONLINE clause is included in the USE command that is used to open the view. If empty (null, blank, .F., or no parameter), the ONLINE clause is not included. Otherwise, the ONLINE clause is included.

Required Parameters:

stcView

stcDBC

Returns:

.T. – The cursor was created.

.F. – The cursor was not created.

ReferentialIntegrity_Cancel

Called by the DeleteRecord, SaveRecord, and ReferentialIntegrity_Start methods when a deletion or save cannot be completed. Closes the cursors that were created by the ReferentialIntegrity_Start method.

ReferentialIntegrity_ CandidateKeyCheck

Called by the ReferentialIntegrity_Start method to perform the duplicate candidate key check.

ReferentialIntegrity_FKs

Loads the array whose reference is passed to this method with information about all of the FKs in tables, views, and cursoradapters that are related to the table, view, or cursoradapter specified in the parameters stcDDDName and stcDDTVName. Each element in the array contains an object reference for a DDFFKS_V view record (using the SCATTER NAME command). The array is loaded with FKs from views first and then tables and cursoradapters so that the updating of related views will occur before the updating of related tables and cursoradapters in the ReferentialIntegrity_Start method. This is done so that the updating of a related table will not need to be attempted if the table has already been updated through a view.

Parameters:

staFKFields

stcDDDName

stcDDTVName

Required Parameters:

staFKFields

stcDDTVName

Returns:

The number of rows created in the array.

ReferentialIntegrity_OK

Called by the DeleteRecord and SaveRecord methods when the ReferentialIntegrity_Start method returns zero (all checks were passed). Closes the cursors that were created by the ReferentialIntegrity_Start method and adds records to the Audit Trail table.

ReferentialIntegrity_Start

Called by the DeleteRecord and SaveRecord methods. Performs the following functions:

Performs the RI check (applies the update and delete rules) for a record that has been added, changed, or deleted.

Performs the blank PK check for new records and records whose PK field(s) were changed.

Performs the duplicate PK check for new records and records whose PK field(s) were changed.

Performs the duplicate candidate key for new records and records whose candidate key field(s) were changed.

Loads a cursor with the information from which Audit Trail records will be created.

Parameters:

stcMode – Identifies the mode, or status, of the record for which this method is being run. The record status is either “Delete”, “New”, or “Change”.

stlNoRICheck – If .T., causes the RI check to be bypassed.

stlNoAuditTrail – If .T., prevents Audit Trail records from being created.

Required Parameters:

stcMode

Properties:

aRelated – An array that keeps track of the related tables, views, and cursoradapters that have been opened when performing the RI check.

cRIMessage – Contains information to be displayed in an error message when the save or deletion cannot be completed.

nRelated – Contains the number of rows in the aRelated array.

Returns:

0 – Passed all checks.

1 – Failed the duplicate PK check.

2 – Failed the RI check.

3 – PK is null or blank.

20 – Failed the duplicate candidate key check.

ReferentialIntegrity_StringToValue

Called by the ReferentialIntegrity_Start method to convert a character string into a value of the type specified in the parameter stcValueType.

Parameters:

stcString – The character string to be converted.

stcValueType – The type of value to be returned (C – character, N – numeric, Y – currency, T – datetime, D – date, L – logical).

Required Parameters:

stcString

stcValueType

Returns:

The converted string value.

ReferentialIntegrity_ValueToString

Called by the ReferentialIntegrity_Start method to convert a value of any type into a character string.

Parameters:

stValue – The value to be converted.

Returns:

The converted string value.

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.

Parameters:

stcAlias – The alias of the cursoradapter cursor that will be refreshed.

staFilterVariables – The reference to an array that contains the definition of filter variables that will be set before the CursorRefresh method is run, causing records to be excluded from the cursor. If empty (null, blank, zero, .F., or no parameter), no filter variables are defined. Otherwise, a reference to a two-dimensional array that defines the variables used in the WHERE clause of the cursoradapter’s SELECT statement. Prior to the CursorRefresh method being run the variables listed in the array are defined using the name from column 1 and the value from column 2.

Returns:

.T. – The cursor was repopulated successfully.

.F. – The cursor was not repopulated successfully.

RegisterDLLFunctions

Registers Dynamic-Link Library (DLL) functions. Called by the Init event when the data handler object is instantiated.

ReleaseClassLib

Releases the class libraries that were loaded in the SetClassLib method. Run from the Cleanup method when the data handler object is released.

ReleaseCursorAdapterObject

Releases the cursoradapter object for the cursor with the alias specified in the parameter stcAlias. The object that is released is stored in the array aCursorAdapterObjects by the OpenCursorAdapter method.

Parameters:

stcAlias – The alias of the cursor for which the object is to be released.

Required Parameters:

stcAlias

Returns:

.T.

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.

Parameters:

stcAlias – The alias of the view cursor for which a REQUERY() will be performed.

staFilterVariables – The reference to an array that contains the definition of view filter variables that will be set before the REQUERY() is performed, causing records to be excluded from the cursor. If empty (null, blank, zero, .F., or no parameter), no filter variables are defined. Otherwise, a reference to a two-dimensional array that defines the variables used in the WHERE clause of the view’s SELECT statement. Prior to the REQUERY() being performed the variables listed in the array are defined using the name from column 1 and the value from column 2.

Returns:

.T. – Data was retrieved successfully.

.F. – Data was not retrieved.

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.

Parameters:

stcAlias – The alias of the cursor in which the changes will be cancelled.

stlRestoreAll – If .T., the changes to all modified records in the cursor are cancelled.

stcAdditionalAliases – Changes will also be cancelled in the cursors that are specified in this comma-delimited list of aliases. For any of the cursors specified in this list that use table buffering, changes will be cancelled for each modified record. Otherwise, just the changes in the current record are cancelled.

stcRulesID – Passed on to business rules methods so that code in those methods can run conditionally if necessary. If this method is run for a record on a form the contents of the form’s cRulesID property is passed to this method.

Returns:

.T.

RetrieveFromProperty_DDTV

Retrieves table, view, or cursoradapter information that has been saved to properties by the SaveToProperty_DDTV method. The retrieved information is then saved to the properties listed below.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the information is retrieved.

stcDDTVName – See above for description.

Required Parameters:

stcDDTVName

Properties:

nRetrieveFromProperty_RecycleRecs

cRetrieveFromProperty_PostAddCode

cRetrieveFromProperty_PreAddCode

cRetrieveFromProperty_PostCopyCode

cRetrieveFromProperty_PreCopyCode

cRetrieveFromProperty_PostDeleteCode

cRetrieveFromProperty_PostDeletePostTransaction Code

cRetrieveFromProperty_PreDeleteCode

cRetrieveFromProperty_PreDeletePreTransaction Code

cRetrieveFromProperty_PostRestoreCode

cRetrieveFromProperty_PreRestoreCode

cRetrieveFromProperty_PostSaveCode

cRetrieveFromProperty_PostSavePostTransaction Code

cRetrieveFromProperty_PreSaveCode

cRetrieveFromProperty_PreSavePreTransaction Code

cRetrieveFromProperty_CursorDescription

Returns:

.T. – The information was retrieved and placed in the properties listed above.

.F. – The information was not retrieved.

RetrieveFromProperty_PK

Retrieves a PK value for an entity (database, cursoradapter library, table, view, cursoradapter, or field) from the property that holds the PK value from the entity’s record in the SDATADDD, SDATADDTV, or SDATADDF table, respectively. The retrieved PK value is then saved to the property cRetrieveFromProperty_PK. For more information, see the SaveToProperty_PK method.

Parameters:

stcDDDName – Along with the following two parameters identifies the entity for which the PK value is retrieved.

stcDDTVName– See above for description.

stcDDFName– See above for description.

Required Parameters:

stcDDTVName if stcDDFName contains a value.

Properties:

cRetrieveFromProperty_PK

Returns:

.T. – The PK value was retrieved and placed into the property cRetrieveFromProperty_PK .

.F. – The PK value was not retrieved.

RetrieveFromProperty_ RequiredFields

Retrieves a string containing a comma-delimited list of required fields for a table, view, or cursoradapter from the property that holds the string. The retrieved string is then saved to the property cRetrieveFromProperty_RequiredFields. For more information, see the SaveToProperty_RequiredFields method.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the string is retrieved.

stcDDTVName– See above for description.

Required Parameters:

stcDDTVName

Properties:

cRetrieveFromProperty_RequiredFields

Returns:

.T. – The string was retrieved and placed into the cRetrieveFromProperty_RequiredFields property.

.F. – The string was not retrieved.

RetrieveFromProperty_ ValidateFields

Retrieves a string containing a comma-delimited list of fields to be validated for a table, view, or cursoradapter from the property that holds the string. The retrieved string is then saved to the property cRetrieveFromProperty_ValidateFields. For more information, see the SaveToProperty_ValidateFields method.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the string is retrieved.

stcDDTVName– See above for description.

Required Parameters:

stcDDTVName

Properties:

cRetrieveFromProperty_ValidateFields

Returns:

.T. – The string was retrieved and placed into the cRetrieveFromProperty_ValidateFields property.

.F. – The string was not retrieved.

Reverse

Changes the current tag order from ASCENDING to DESCENDING and vice versa in the current cursor or the cursor specified in the parameter stcAlias.

Parameters:

stcAlias – The alias of the cursor in which the order will be reversed.

Returns:

.T. – The order was reversed.

.F. – The order was not reversed.

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.

Parameters:

stcAlias – The alias of the cursor in which the changes will be saved.

stlSaveAll – If .T., the changes to all modified records in the cursor are saved. Table buffering must be in use on the cursor for this parameter to be used.

stcAdditionalAliases – Changes will also be saved in the cursors that are specified in this comma-delimited list of aliases. For any of the cursors specified in this list that use table buffering, changes will be saved for each modified record. Otherwise, just the changes in the current record are saved.

stcRulesID – Passed on to business rules methods so that code in those methods can run conditionally if necessary. If this method is run for a record on a form the contents of the form’s cRulesID property is passed to this method.

stlNoNewAuditTrail – Specifies whether or not Audit Trail records are created when a new record is saved.

stlNoChangeAuditTrail – Specifies whether or not Audit Trail records are created when a modified record is saved.

stlNoRICall – Specifies whether or not the RI routine is called. If not, the RI check, Audit Trail functionality, duplicate PK check, and blank PK check are all disabled.

stcNotBlankFields – This parameter is passed on to the EmptyRequiredFields method when the save is performed. See the description of that method for a definition of this parameter.

stlNoRecordLevelValidation – Specifies whether or not the record-level field validation will be performed.

Properties:

cRIMessage – Contains error information when 2, 4, 7, 9, 15, 16, 18, or 22 is returned.

Returns:

0 – Save completed.

1 – Failed duplicate primary key check, save aborted.

2 – Failed VPM RI check, save aborted.

3 – Primary key field has null or blank value, save aborted.

4 – TABLEUPDATE failed, save aborted (unknown error).

5 – DefaultValues method returned .F., save aborted.

6 – PreSave method or code in mPreSaveCode returned .F., save aborted.

7 – EmptyRequiredFields method found at least one required field that does not contain a value, save aborted.

8 – Transaction failed, save aborted.

9 – Error occurred, save aborted.

10 – TABLEUPDATE failed, save aborted (record is in use by another user).

11 – TABLEUPDATE failed, save aborted (insert trigger failed).

12 – TABLEUPDATE failed, save aborted (update trigger failed).

13 – TABLEUPDATE failed, save aborted (delete trigger failed).

14 – TABLEUPDATE failed, save aborted (field doesn’t accept null values).

15 – TABLEUPDATE failed, save aborted (field rule was violated).

16 – TABLEUPDATE failed, save aborted (row rule was violated).

17 – TABLEUPDATE failed, save aborted (uniqueness of an index was violated).

18 – TABLEUPDATE failed, save aborted (ODBC error occurred).

19 – PostSave method or code in mPostSaveCode returned .F., save aborted.

20 – Failed duplicate candidate key check, save aborted.

21 – PreSavePreTransaction method or code in mPreSavePreTransactionCode returned .F., save aborted.

22 – FieldValidation_RecordLevel method found at least one field that contains an invalid value, save aborted.

SaveToProperty_DDTV

Creates properties that hold information from a table, view, or cursoradapter’s SDATADDTV record. This is done so that when retrieving information for a table, view, or cursoradapter whose information has already been retrieved once, the information can simply be retrieved from the properties instead of having to get it from the SDATADDTV table again.

Parameters:

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the information is retrieved and then saved to properties.

stcDDTVName – See above for description.

Required Parameters:

stcDDTVName

Properties:

Property names are derived from the parameter values.

Returns:

.T. – The properties were created.

.F. – The properties were not created.

SaveToProperty_PK

Creates a property for an entity (database, cursoradapter library, table, view, cursoradapter, or field) that will hold the PK value of the entity’s record in the SDATADDD, SDATADDTV, or SDATADDF table, respectively. This is done so that when retrieving a record for a field from the SDATADDF table, for example, the FK to the SDATADDTV table that is needed will be known (in a property) and will not have to be retrieved from a record in the SDATADDTV table again.

Parameters:

stcPropertyValue – The PK value to be saved.

stcDDDName – Along with the following two parameters identifies the entity for which the PK value is saved to a property.

stcDDTVName– See above for description.

stcDDFName– See above for description.

Required Parameters:

stcDDTVName if stcDDFName contains a value.

Properties:

Property name is derived from the parameter values.

Returns:

.T. – The property was created.

.F. – The property was not created.

SaveToProperty_RequiredFields

Creates a property that will hold a string containing a comma-delimited list of required fields for a table, view, or cursoradapter. This is done so that when retrieving the list of fields for a table, view, or cursoradapter whose fields list has already been determined, the fields list can simply be retrieved from the property instead of having to get the information from the SDATADDF table again.

Parameters:

stcPropertyValue – The fields list string to be saved.

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the string is saved to a property.

stcDDTVName– See above for description.

Required Parameters:

stcDDTVName

Properties:

Property name is derived from the parameter values.

Returns:

.T. – The property was created.

.F. – The property was not created.

SaveToProperty_ValidateFields

Creates a property that will hold a string containing a comma-delimited list of fields to be validated for a table, view, or cursoradapter. This is done so that when retrieving the list of fields for a table, view, or cursoradapter whose fields list has already been determined, the fields list can simply be retrieved from the property instead of having to get the information from the SDATADDF table again.

Parameters:

stcPropertyValue – The fields list string to be saved.

stcDDDName – Along with the following parameter identifies the table, view, or cursoradapter for which the string is saved to a property.

stcDDTVName– See above for description.

Required Parameters:

stcDDTVName

Properties:

Property name is derived from the parameter values.

Returns:

.T. – The property was created.

.F. – The property was not created.

SelectAlias

Selects the alias specified in the parameter stcAlias. If stcAlias is empty and a cursor is open in the current work area, that work area remains selected.

Parameters:

stcAlias – The alias of the cursor to be selected.

Returns:

.T. – The specified alias (work area) was selected.

.F. – The specified alias (work area) was not selected.

SelectWorkArea

Selects the work area specified in the parameter stnWorkArea. If stnWorkArea is zero or non-numeric an unused work area is selected.

Parameters:

stnWorkArea – The number of the work area to be selected.

Returns:

.T.

SetClassLib

Loads the class libraries from which objects are instantiated. Run from the Init event when the data handler object is instantiated.

SetEnvironment

Sets the environment for the data handler object. Run from the Init event when the data handler object is instantiated.

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.

Parameters:

stcAlias – The alias of the cursor to which the filter is set.

stcFilterExpression – The filter expression to be set on the cursor.

stGoTo – Determines where the record pointer should be positioned after the filter expression is set on the cursor. The value can be of logical, character, or numeric type.

Logical – If .T., causes the record pointer to be positioned on the first record according to the master tag. If .F., causes the record pointer to remain on the same record.

Character – If empty, causes the record pointer to remain on the same record. Otherwise, contains a LOCATE expression that is used to find a particular record.

Numeric – Contains a record number that specifies where the record pointer should be positioned. A value of zero will cause the record pointer to be positioned at end-of-file.

stlAddToExisting – Specifies whether the filter expression is added on to (.T.) or replaces (.F., the default) any existing filter that is currently set on the cursor.

Returns:

.T. – The filter was successfully set or removed.

.F. – The filter was not successfully set or removed.

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.

Parameters:

stcAlias – The alias of the cursor to which the order is set.

stcTagName – The name of the tag to select as the master tag.

stlAscending – Specifies whether or not the ASCENDING clause is included in the SET ORDER command.

stlDescending – Specifies whether or not the DESCENDING clause is included in the SET ORDER command.

stcCreateTagExpression – For a view or cursoradapter cursor for which the stcTagName tag does not exist, specifies the index expression to be used in the creation of that tag.

stcForExpression – If a tag is created because the stcCreateTagExpression parameter contains an expression, specifies the For expression that is applied when the tag is created.

Returns:

.T. – The tag was created and/or the order was set.

.F. – The tag was not created and/or the order was not set.

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.

Parameters:

stcAlias – The alias of the cursor from which a relation is set.

stcRelationExpression – The expression used to relate the stcAlias and stcIntoAlias cursors.

stcIntoAlias – The alias of the cursor into which a relation is set.

Returns:

.T. – The relation was successfully set or removed.

.F. – The relation was not successfully set or removed.

Traverse

Called by the GoNext method to optimize record navigation.

UpdateAliases_LoadArrays

When a new record is created in a child cursor the values from the PK fields of the current record in the parent cursor are placed into the FK fields of the new child record. This method loads the arrays aUpdateAliases_PKFields and aUpdateAliases_FKFields for the parent and child cursors (aliases) identified in the parameters. Each element of the aUpdateAliases_FKFields array will contain a comma-delimited list of child cursor FK field(s) that map to a comma-delimited list of parent cursor PK field(s) stored in the corresponding element of the aUpdateAliases_PKFields array. These arrays are then used to facilitate the movement of field values from the parent record to the child record.

Parameters:

stcAlias –The alias of the parent cursor. If empty, the parent cursor is the cursor open in the current workarea.

stcUpdateAliases – A comma-delimited list of child aliases.

Required Parameters:

stcUpdateAliases

Properties:

aUpdateAliases_FKFields – Contains a comma-delimited list of FK fields in each child cursor.

aUpdateAliases_PKFields – Contains a comma-delimited list of PK fields in the parent cursor.

cUpdateAliases_SaveParentDDDName – Used to speed up the process.

cUpdateAliases_SaveParentDDTVName – Used to speed up the process.

cUpdateAliases_SaveUpdateAliases – Used to speed up the process.

cUpdateAliases_SaveValidAliases – Used to speed up the process.

Returns:

A comma-delimited list of the child aliases that have rows in the array aUpdateAliases_FKFields.

UpdateDDFH

Updates the Field Help text in the SDATADDFH record for the field that is specified in the stcDDDName, stcDDTVName, and stcDDFName parameters.

Parameters:

stcDDDName – Along with the following two parameters identifies the field for which the text is updated.

stcDDTVName – See above for description.

stcDDFName – See above for description.

stcUpdateText – The text to be stored in the SDATADDFH record.

Required Parameters:

stcDDDName

stcDDTVName

stcDDFName

Returns:

.T. – The record was updated.

.F. – The record was not updated.

UpdateFor

Updates records in the cursor specified by the parameter stcAlias using the UPDATE command. If the parameter stcAlias is empty and a cursor is open in the current work area, the records in that cursor are updated. The updates are performed using the UPDATE command and the TABLEUPDATE function instead of using REPLACEs and the SaveRecord method, which means the records are updated without the PreSave/PostSave code being run, without the data handler’s RI routine being run, and without the Audit Trail functionality being run.

Parameters:

stcAlias –The alias of the cursor that contains the records to be updated.

staSet – The reference to a three-dimensional array that contains the information used to build the SET clause of the UPDATE command, which defines how the records are updated. The columns in the array should contain the following: Column 1 – field name, Column 2 – the value to be placed in the field or the expression to be evaluated and result placed in the field, Column 3 – “V” (if column 2 contains a value) or “E” (if column 2 contains an expression).

stcWhereExpression – The expression used in the WHERE clause of the UPDATE command.

Required Parameters:

staSet

Returns:

.T. – The records were updated.

.F. – The records were not updated.

UserValidation

Validates the User ID and optional password that are passed to this method.

Parameters:

stcUserID – Specifies the User ID to be validated.

stcPassword – Specifies the password of the user to be validated.

stlSaveToProperty – Specifies whether or not the User ID should be saved to the cUserID property. The value in the cUserID property is placed in Error records and Audit Trail records when created.

stlPasswordRequired – Specifies whether or not the password must be validated. If not, just the User ID will be validated.

Required Parameters:

stcUserID

Returns:

0 – Validation check was successful.

1 – Empty User ID and password, validation failed.

2 – Empty User ID, validation failed.

3 – Empty password, validation failed.

4 – UserLogin_V view could not be opened, validation failed.

5 – User ID not found, validation failed.

6 – Invalid data in User record, validation failed.

7 – Invalid password, validation failed.

 

More:

Form Classes