$instancemod
Return or set the modification status of data in the current component instance.
$instancemod { (
InstanceName)
}
set | reset $instancemod
Example:
if ($instancemod = 0)
...
Parameters
Parameter | Data Type | Description |
---|---|---|
InstanceName | String | Name of component instance; optional. If omitted, the current instance is used. |
Return Values
Value |
Meaning |
---|---|
1
|
In the following cases:
|
0
|
In the following cases:
|
""
|
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
The $instancemod command tests the modification status of data in the component instance. The value of $instancemod is actually an inclusive logical OR of the values of the $occmod function for all the occurrences in the instance.
Events Affecting $instancemod
Events that cause a field to be modified (and $instancemod 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 $instancemod after statement | Comments |
---|---|---|
clear | 0 | |
clear/e | 0 | If the only fields modified are in entities related to the cleared entity. |
No change | If the only fields modified are not in entities related to the cleared entity. | |
creocc | 1 | Entity-level indicators are set for the created occurrence and its related entities. |
erase | 0 | |
erase/e | 0 | If the only fields modified are in entities related to the erased entity. |
No change | If the only fields modified are not in entities related to the erased entity. | |
release | 0 | |
release/e | 0 | If the only fields modified are in entities related to the released entity. |
No change | If the only fields modified are not in entities related to the released entity. | |
release/e/mod | 1 | |
release/mod | 1 | |
remocc | 1 | Entity-level indicators are set only for the entity and its related entities. |
retrieve | 0 | If the only fields that have been modified are in entities related to the retrieved entity. |
No change | If the only fields that have been modified are not in entities related to the retrieved entity. | |
retrieve/e | 0 | If the only 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 fields that have been modified are not in entities related to the retrieved entity. | |
store | 0 | |
store/e | 0 | If the only modified fields are in entities related to the stored entity. |
No change | If the only modified fields are not in entities related to the stored entity. |
For more information, see Effects of ProcScript Statements on Instance-Level ProcScript Functions.
Checking for Modifications
In the following example, the $instancemod is used to determine if any modifications have been made in the component instance. If there have been modifications, the user is asked to confirm before the modifications are lost.
If the user does not want to quit, the ProcScript ends with a status code that prevents the component from ending; that is, the component remains displayed, and the user is able to accept the modifications. If the user does want to quit, the ProcScript ends normally, allowing the component to end.
trigger quit ; test for modifications ; -1 prevents end of edit session if ($instancemod = 0) return 0 else askmess "Please confirm QUIT (Y/N)" if ($status = 1) return 0 else return -1 endif endif end; quit