$instancemod

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

$instancemod { (InstanceName) }

set | reset  $instancemod

Parameters

InstanceName—component instance name; optional; can be a literal name, string, variable, function, parameter, or indirect reference to a field containing the name. If omitted, the current instance is returned.

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

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 more information, see the newinstance Proc statement); for example, the argument contains incorrect characters.

-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 Application Execute trigger.

The current instance is a form started with run.

Use

Allowed in all components, but not in report components that are self-contained.

Description

$instancemod is an instance-level function that tests the modification status of data in the component instance.

The value of $instancemod is actually the inclusive 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 recognized as modified include such things as:

  • The user entering a retrieve profile in an empty field. (This means that $instancemod can be set to 1 before a retrieve has been performed.)
  • The user changing the value of data that has been retrieved.
  • Modification of a non-database field made by a Proc assignment (=) without the /init switch.
Proc Statements that Change $instancemod and $formmod

Statement

Value of $instancemod and $formmod after statement

Discussion

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 Proc Statements on Instance-Level Proc Functions.

Checking for Modifications

In the following example, a Quit Proc code examines $instancemod 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 Proc code 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 Proc code 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