$instancedbmod
Return the modification status of database fields in the current component instance.
$instancedbmod { (
InstanceName)
}
Example: selectcase $instancedbmod(vCurrentChild) ...
Parameters
Parameter | Data Type | Description |
---|---|---|
InstanceName | String | Name of component instance; optional. If omitted, the current instance is used. |
Return Values
Value |
Meaning |
---|---|
1
|
Any field in the component instance that is defined as being a database field has been modified. |
0
|
|
""
|
An error occurred. $procerror contains the exact error. |
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 |
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.
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