$instancemod

Return or set the modification status of data in the current component instance.

$instancemod { (InstanceName) }

set | reset  $instancemod

Example: if ($instancemod = 0) ...

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 $instancemod

Value

Meaning
1 In the following cases:
  • At least one field has been modified
  • An occurrence has been added to or removed from the component
0 In the following cases:
  • No field has been modified
  • No occurrences have been added or removed
  • No entities are present 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

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.
ProcScript Statements that Change $instancemod
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

Related Topics