AssemblyLine Simulation Mode

AssemblyLines can be debugged without actually exchanging data with connected systems using the AssemblyLine Simulation Mode. When an AssemblyLine has been started in this mode all AssemblyLine Components which potentially could cause changes in the target systems will be skipped.

This implies that the AL executes normally, but Connectors in Update, Delta, Delete and AddOnly Mode do not perform the actual operation.

Note: An AssemblyLine run this way can only approximate what would happen in normal mode; in many cases the very fact that a connected system does not receive any updates in Simulation Mode may cause your business logic to behave differently, negating the usefulness of the simulation.

The simulation state should not to be confused with the state of a component. The component’s state has higher priority than the component’s simulation state.

The component’s state has two values – Enabled or Disabled. If the component is in Enabled state then it will initialize and its simulation state will be checked when the appropriate operation is called. When the state is set to Disabled then no check for the simulation state will be made since no operation will be called, and the component’s initialization will not be called.

Connectors and FCs have another state called Passive. When their state is set to Passive then they only will be initialized. Their operations can be executed only via a user script. When their specific operation is called then the simulation state is checked. There are a number of ways in which an AssemblyLine can be started in Simulation Mode:

From the Configuration Editor:

A checkbox in the Run-mode drop-down menu is available to enable and disable simulation for the AL. You must choose the desired run-mode Run with Options from the drop-down menu and check the checkbox Simulation mode in the pop-up Options dialog box in order to make the AL simulate while running. The default state for this checkbox is unchecked.

Using the Server startup command ibmdisrv:

This command recognizes the the switch –M, and will start the AL with simulation turned on if this switch is provided.

Using the API:

In order to make an AL run in Simulation Mode, you must set the property AssemblyLine.TCB_SIMULATE_MODE to true in the TCB object. This object then should be provided to the startAssemblyLine(String, TaskCallBlock) method. If no property is set then by default its value is considered to be false.

In order to run an AssemblyLine in Simulate Mode, a new configuration is created. It is a child of the AssemblyLine Config. This configuration object contains parameters that configure the connection to an AL that will be used as a Proxy AssemblyLine (ProxyAL). The SimulationConfig object has a method that creates or updates a template of a ProxyAL based on the components’ states of the AssemblyLine that is being simulated. The SimulateConfig object also contains all the hooks defined for Components that are in Scripted simulation state. The name of each hook is the same as the name of the component in Scripted simulation state. It also contains the simulation state for each component.

AssemblyLines to be run in Simulation Mode can be configured in more detail; relevant settings can be configured by selecting AssemblyLine Settings > Simulation Settings in the AssemblyLine Editor window. Simulation Settings window

The configuration of the simulation states for each component is done using the Simulation Settings dialog box. This dialog box configures the ProxyAL to be used by the components which simulation state is set to ProxyAL. When you click Update Proxy AssemblyLine the Config Editor will either create a new ProxyAL in the current project or will update an existing Proxy AssemblyLine. The created or updated ProxyAL is provided as a template and its structure is based on the configuration you have done in the Simulation Settings dialog box. Note that in this process only the name of the Proxy AssemblyLine is taken into account. The Server Name and Config ID are taken into account during the execution of the Simulated AssemblyLine. If there is already an existing AssemblyLine with the name specified in the dialog box, then only new branches will be added and no old branches will be modified or removed. This is because some of them can contain a user-specific configuration. Individual components in the AssemblyLine can be set to one of the following states:

Enabled

This is the equivalent of running this component in the AL in normal mode (that is, the component is executed as it normally would).

Disabled

This is the equivalent of disabling the component (that is, no operations, hooks, or anything else except the initialization is executed for the component).

Simulated

Generally, the statistics for all of the components described below will contain information for the operation that would have completed if the AL was not simulating. Since no critical operation is done during simulation, there is no possible way to predict what would be the result from the execution of a critical operation (success or error), thus the statistics will state that the operation has completed successfully.

• Connectors in AddOnly mode: executed as normal, only the potentially unsafe call to the connector.putEntry() method and the call to the override_add hook are skipped.
• Connectors in Update mode: executed as normal, only the potentially unsafe call to the connector.modEntry() method and the call to the override_modify hook are skipped.
• Connectors in Delete mode: executed as normal, only the potentially unsafe call to the connector.deleteEntry() method and the call to the override_delete hook are skipped.
• Connectors in Delta mode: executed as normal, but because of the fact that this connector relies on calls to the methods described above, it will be simulated when the above methods and hooks are skipped.
• Connectors in Iterator mode with Delta tagging: executed as normally; for these components the change is similar to the Connectors described above, that is, the calls to the potentially unsafe methods of the BTree class (putEntry, modEntry, deleteEntry) are skipped. For the CDDeltaTaskComponent the commit state is overridden to disable commit (“No autocommit”) but committing will still be possible for users that explicitly call the CSDeltaTaskCoponent#commitDeltaState() method.
• Function Components (FCs): execute as normal, but the invocation of “before_functioncall”, “after_functioncall” and “no_reply” hooks as well as the call to the function.perform() method are disabled. The invocation of these hooks is disabled because they are associated with an object that is returned from the perform method which is also disabled. The only thing that will be done is a change to the statistics that will indicate that the FC has successfully executed this operation.

  Also the Input and Output Maps will be executed but the actual entry before the InputMap will be an empty one (this could lead to an exception being thrown, it is better to disable each simple attribute mapping from the InputMap that relies on an attribute returned from the Function Component or to add a check for validity of the retrieved attribute in the advanced attribute Map; alternatively, we can use the NullBehaviour mechanism to override potential errors).

• Connectors in any other mode run as usual.

Proxy

Connectors in this simulation state will start another AL (specified in the Simulation tab) that will override the potentially unsafe execution of the operation. This external AL is shared between all the Components in this simulation mode. It will be executed with different operation which name matches the name of the Component being simulated. See Proxy AssemblyLine workflow.

Scripted

A user-defined script will override the potentially unsafe operation. Each component in this simulation mode has its own hook, unlike the Proxy state where an AL is shared between the components. See Simulation script workflow.

You have the ability to check whether the AL is simulating and also to switch simulation on and off using the following methods:

• boolean AssemblyLine#isSimulating() Used as follows from a hook: task.isSimulating();
• void AssemblyLine#setSimulating(boolean) Used as follows from a hook: task.setSimulating(true);

You have the ability to check the state of each component, and to set it dynamically by using the following methods:

• String AssemblyLineComponent.getSimulatingState() Used as follows from a hook: ConnectorName.getSimulatingState();
• void AssemblyLineComponent.getSimulatingState(String) Used as follows from a hook: ConnectorName.setSimulatingState("Proxy");

Note: Only Connectors and FCs have the full set of simulation states as described above, the remaining components (and Connectors in Server mode) have only Enabled and Disabled states. Security Directory Integrator considers some FCs safe and their default simulation state will be Enabled, that is by default they will not simulate and will execute as usual; these are all FCs that are unable to change a target system since they simply do not connect to any. The list of safe FCs is as follows:

• CBE FC
• JavaToXML FC
• XMLToJava FC
• SDOToXML FC
• XMLToSDO FC
• Parser FC
• MemQueue FC
• JavaToSOAP FC
• SOAPToJava FC
• WrapSOAP FC

Attention: You still can cause changes to underlying datasystems by explicit coding; this is out of scope of the Simulation Mode.

Any remaining FCs not listed here are considered potentially unsafe and their default simulate state will be set to Simulated.

• Proxy AssemblyLine workflow
  In the context of Simulation Mode, the call to a proxy AL works similar to how you would use the AssemblyLine Connector to drive an AL of your choice, however some significant differences are observed.
• Simulation script workflow
  Each component which simulation state is set to Scripted has a Simulation Script (SS) defined in the Simulate tab.

Parent topic:

Debugging features in SDI