$instancedbmod

Return the modification status of database fields in the current component instance.

$instancedbmod { (InstanceName) }

Example: selectcase $instancedbmod(vCurrentChild) ...

Parameters

Parameters
Parameter Data Type Description
InstanceName String Name of component instance; optional. If omitted, the current instance is used.

Return Values

Values returned in $instancedbmod
Value

Meaning

1

Any field in the component instance that is defined as being a database field has been modified.
0
  • No modifications have been made to database fields.
  • No entities are specified in the component structure.
"" An error occurred. $procerror contains the exact error.

 

Values of $procerror Commonly Returned Following this Function
Value  Error constant Meaning
-57 <UACTERR_NO_INSTANCE> The named instance cannot be found in the component pool.
-1101 <UPROCERR_FIELD> An incorrect field name was provided; either the field name is not valid syntactically or the field is not available in the component.
-1105 <UPROCERR_INSTANCE> The instance name provided is not valid. For example, the argument contains incorrect characters. For more information, see newinstance.
-1304 <UPROCERR_UNKNOWN_CONTEXT> Function not allowed, unknown context. The InstanceName argument was omitted and one of the following occurred:

There is no current instance, for example, in the apStart trigger.

The current instance is a form started with run.

Use

Allowed in all component types, except self-contained Reports.

Description

$instancedbmod is an instance-level function that tests whether any database field in the specified instance has been modified. Non-database do not affect $instancedbmod.

(You could consider $instancedbmod to be the inclusive OR of the values of the $fieldmod function for all database fields in the instance. )

Events Affecting $instancedbmod

Events that cause a field to be modified (and $instancedbmod set to 1) include:

  • The user enters a retrieve profile in an empty field.
  • The user changes the value of data that has been retrieved.
  • A non-database field is assigned a new value in ProcScript without the /init switch.
Statements that Change $instancedbmod (and $formdbmod)
Statement Value of $instancedbmod Remarks
clear 0  
clear/e 0 If the only database fields modified are in entities related to the cleared entity.
No change If the only database fields modified are not in entities related to the cleared entity.
erase 0  
erase/e 0 If the only database fields modified are in entities related to the erased entity.
No change If the only database fields modified are not in entities related to the erased entity.
release/e/mod 1 The modification status is set only for the specified entity and related entities. Consequently, ProcScript statements that reset the modification status for unrelated entities do not cause $instancedbmod to be set to 0. (Remember that $instancedbmod is evaluated as an inclusive OR for all entities in the instance.)
release/mod 1  
remocc 1 If the removed occurrence is in the database. Entity-level indicators are set only for the entity and its related entities.
No change If the removed occurrence was added by the user and has not been stored.
retrieve 0 If the only database fields that have been modified are in entities related to the retrieved entity.
No change If the only database fields that have been modified are not in entities related to the retrieved entity.
retrieve/e 0 If the only database fields that have been modified are in inner entities related to the retrieved entity or in the retrieved entity itself.
No change If the only database fields that have been modified are not in entities related to the retrieved entity.
store 0  
store/e 0 If the only modified database fields are in entities related to the stored entity.
No change If the only modified database fields are not in entities related to the stored entity.

For more information, see Effects of ProcScript Statements on Instance-Level ProcScript Functions.

Exit Application Menu Item

The following example is for an "Exit Application" menu item or command button of a parent component which may have any number of child component. The module enables central checking of the modification status of all child forms. Without this module, each child form with unsaved data would produce a dialog box when the parent form is exited. The module also generates a list of unsaved instances to enable one-click saving of all the forms. 

variables
   string vUnsaved
   string vChildren
   string vCurrent_child
endvariables

vUnsaved = ""
vChildren= ""
vCurrent_child = ""

; list all the children of the current form
vChildren = $instancechildren
message "%%vChildren%%%"
while (vChildren != "")
   getitem vCurrent_child, vChildren, 1
   delitem vChildren, 1
   selectcase $instancedbmod(vCurrent_child )
      case 0
      ; The child"s data is stored in the database
      ; Insert some code to shut the form
      case 1
         putitem vUnsaved, -1, vCurrent_child 
   endselectcase
endwhile

; Check if the parent form is saved
if ($instancedbmod != 0)
   putitem vUnsaved, -1, $instancename
endif

; are any items unsaved?
if (vUnsaved !="")
   askmess "Data has not been saved on components:%%^%\
   %%vUnsaved%%% %%^Do you wish to exit?"
   if ($status = 0)
      return -1
   else
      apexit
   endif
else
   apexit
endif

Related Topics