$instancedb

Return an indication whether data in the current instance has been retrieved from a database.

$instancedb { (InstanceName) }

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 $instancedb
Value

Meaning

0
  • No entities have been retrieved from a database, for example, the user has not retrieved data, only entered it
  • $instancedb has been reset to 0 by a ProcScript statement
  • No entities are present in the component structure.
>0

An entity in the instance has been retrieved from a database
""
  • InstanceName omitted and there is no current instance, for example, in the apStart trigger.
  • InstanceName omitted and current instance is a Form started with run.
  • No instance named InstanceName can be found in the component pool.
  • InstanceName is not correct; that is, the field or variable is not found or the string is not a valid instance name (see newinstance).

Use

Allowed in all component types.

Description

The $instancedb function is used to test whether any occurrence in InstName has been retrieved from a database. The $instancedb function is evaluated as an inclusive OR of all the entity-level flags indicating database origin.

The following statements affect the value of $instancedb:

Statements that change $instancedb
Statement Value of $instancedb Discussion
clear 0  
clear/e 0 If the only entities retrieved are related to the cleared entity.
No change If the only entities retrieved are not related to the cleared entity.
erase 0  
erase/e 0 If the only entities retrieved are related to the erased entity.
No change If the only entities retrieved are not related to the erased entity.
release 0  
release/e 0 If the only entities retrieved are related to the released entity.
No change If the only entities retrieved are not related to the released entity.
release/mod 0  
release/e/mod 0 If the only entities retrieved are related to the released entity.
No change If the only entities retrieved are not related to the released entity.
retrieve 1 Causes the first outermost entity to be retrieved with its related entities. Any unrelated entities are not automatically retrieved. Internally, the entity-level flags for database origin are set. This affects the value that $instancedb becomes when any unrelated entities use ProcScript statements that modify $instancedb.
retrieve/e 1 The specified entity is retrieved with its related entities. Any unrelated entities are not automatically retrieved. Internally, the entity-level flags for database origin are set. This affects the value $instancedb becomes when any unrelated entities use ProcScript statements that modify $instancedb.
store 1  
store/e 1 Internally, the entity-level flags for database origin are set for the entity and related entities stored. This affects the value $instancedb becomes when any unrelated entities use ProcScript statements that reset $instancedb.

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

When an entity that is painted as an up (or foreign) entity has empty writeUp and deleteUp triggers, for the purposes of $instancedb, that entity is not considered to be a DBMS entity. Even if data for the up entity has been retrieved as a result of a retrieve/e, the value of $instancedb is not affected.

Using $instancedb

The following example shows how to use $instancedb to determine the behavior of the Clear action: 

trigger clear
if ( $instancedb > 0 & $componenttype = "P")
   release
   message "Controls released; data available as default for new input"
else
   clear
endif
end; clear

In the example, the first time the Clear action is invoked, the controls on primary key fields are released and retrieved data is marked as being entered by the user. The second time that component is cleared, the data is removed from the instance (but not the database).

Related Topics