executeWhen Instruction

The executeWhen instruction loads and executes JADE instructions if a Boolean flag value is true.

Syntax

The syntax of the executeWhen instruction is as follows.

executeWhen [not] FlagName;
    optionalStatementList
endExecuteWhen;

The FlagName value is a user‑defined Boolean global constant. The value of FlagName can be set for the node in the JADE initialization file or through code at run time.

Description

The executeWhen instruction enables blocks of code in a method to be:

• Not loaded if the value of a boolean flag value is false

• Executed only when the value of a boolean flag value is true

The value of the boolean flag can be:

• Set when the node starts up from a setting in the JADE initialization file

• Changed through code at run time

You could use the executeWhen instruction to bracket debug instructions that are useful during development but not in production, for example. In the production system, the debug instructions are not loaded when the method is loaded prior to execution; that is, only code to be executed is loaded.

Consider loading the following code fragment.

instruction #1;
executeWhen FlagName;
instruction #2;
endExecuteWhen;
instruction #3;

If the effective value of FlagName for the node is true, the instructions loaded are:

instruction #1;
instruction #2;
instruction #3;

If the effective value of FlagName for the node is false, the instructions loaded are:

instruction #1;
instruction #3;

FlagName is a Boolean global constant that you must have defined

The executeWhen instruction does not examine the true or false value defined when the global constant was created. This value is always ignored by the executeWhen instruction. Instead, the effective value of the global constant is read from the FlagName parameter in the [JadeExecuteFlags] section of the JADE initialization file when the node is initialized (although it can also be changed at run time), as shown in the following example.

[JadeExecuteFlags]
DebugTestFlag=true

If the [JadeExecuteFlags] section does not contain a parameter corresponding to a global constant, the effective value used in an executeWhen instruction is false.

The setExecuteFlagValue method defined in the Node class enables you to change the effective value of the executeWhen flag for the current node, thereby overriding the value set in the FlagName parameter in the [JadeExecuteFlags] section of the JADE initialization file on that node, as shown in the following code fragment.

node.setExecuteFlagValue("FlagName", false);
node.clearMethodCache;

The Node class also provides the getExecuteFlagValue method, which returns the current, effective value of a global constant used in an executeWhen condition for the current node.

The setExecuteFlagValue method dynamically sets the in-memory value of the executeWhen flag for the node on which the method is executed. If the flag needs to be set on another node (for example, the database server), a serverExecution method must be called. Note, however, that the method cache must be flushed so that methods are reloaded with the new flag value in effect.

The value of the flag is not re-evaluated (that is, re-read from the initialization file) after the clearMethodCache method has been called. The current value is applied to each method as it is reloaded from the database.

The parameter values in the [JadeExecuteFlags] section of the JADE initialization file are loaded into memory the first time:

• An executeWhen instruction is encountered while loading a method.

• The Node::getExecuteFlagValue method is called.

• The Node::setExecuteFlagValue method is called.

The values are not read again until the node is restarted.

Example

The following example shows the executeWhen instruction used to conditionally load a debug write instruction for execution.

executeWhen DebugTestFlag;
    write cust.balance;
endExecuteWhen;