$instancedb
Return an indication whether data in the current instance has been retrieved from a database.
$instancedb { (
InstanceName)
}
Parameters
Parameter | Data Type | Description |
---|---|---|
InstanceName | String | Name of component instance; optional. If omitted, the current instance is used. |
Return Values
Value |
Meaning |
---|---|
0 |
|
>0 |
An entity in the instance has been retrieved from a database |
""
|
|
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:
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).