This example shall implement the functionality of a lock object. This means that the value of an input data point shall only be forwarded to an output data point if the value of another input item (called lock object) is not set to a configured Boolean value. This functionality is shown in the following truth table (suppose the configured value for the lock object is "true"):
| Input data point | Lock object | Output data point |
|---|---|---|
| a | false | a |
| b | false | b |
| ... | false | ... |
| a | true | x |
| b | true | x |
| ... | true | x |
Creating the command
Within the NETx BMS Studio, start the XLogic Editor using the corresponding icon in the toolbar. Then select the entry "New Command ..." from the menu "File". A new dialog opens that is used to define the name of the command as well as its inputs, outputs, and parameters.
Within this dialog, set the name to "Lock" and define the following inputs:
- Input data point: this is the item ID that specifies the input that shall be monitored.
Then, define following outputs:
- Output data point: this is the item ID that specifies the output where the result shall be written.
Finally, define the following parameters:
- Lock object: this parameter of type "ITEM ID" specifies the data point that is used as lock object. The lock object can also be defined as input. However, the difference between an input and a parameter of type "ITEM ID" is that a change of value of an input triggers the execution of command while a change of value of a parameter does not trigger the command.
- Lock value: this parameter of type "BOOL" specifies the value where the value is not forwarded. This parameter is optional.
The dialog with all correct values is shown in the following figure.
Command flow
As next the command flow has to be defined. For the proposed command, an "IF THEN ELSE" condition and a "CMD" block is needed. Drag and drop both blocks from the catalog on the left hand side onto the work sheet. For documentation purpose, it is possible to set a comment to each block. Double click the "<comment>" field within each block and enter a comment (e.g. "Verify lock object" for the condition and "Write output" for the command block).
To define the command flow, the blocks have to be connected to each other. The command flow is defined from left to right -- starting with the "CMD HEADER" block (begin of the command) and ending with the "CMD END" block (end of command). First, connect the "CMD HEADER" block with "PREV" connector of the "IF THEN ELSE" block. Then connect the "THEN NEXT" connector with the "FINISH" connector of the "CMD END" block and the "ELSE NEXT" connector with the "PREV" connector of "CMD" block. Finally, connect the "NEXT" connector of the "CMD" block with the "FINISH" connector of the "CMD END" block. The idea behind this command flow is as follows. After command start, the lock object is verified with the "IF THEN ELSE" condition. If the condition verifies to true (the object is locked), the command shall finish immediately. If the lock object is false, the output is written by calling the "CMD" block. The final command flow is shown in the figure below.
Verifying the lock object
As next the lock object has to be verified. By doing a double click on "IF THEN ELSE" condition, the work sheet of the condition opens. Within this condition, the value of the lock object shall be compared with the lock value that is provided as parameter. First, the value of lock object has to be retrieved. To do so, place a "PARAMETER VALUE" block and an "ITEM VALUE" block on the work sheet and connect the "VALUE" connector of the "PARAMETER VALUE" block with the "ITEM ID" connector of the "ITEM VALUE" block. Then, double click the "<empty>" field of the "PARAMETER VALUE" block and select "Lock object" from the drop down list. In this way, the current value of the data point behind the lock object is retrieved. The "PARAMETER VALUE" block provides the Item ID of the lock object that the use has to be specified via the parameter "Lock object". Using this Item ID as input, the "ITEM VALUE" block gets the current value of lock object i.e. the item behind the lock object.
Afterwards, place another "PARAMETER VALUE" on the work sheet. Double click the "<empty>" field and select "Lock value" as parameter. In this way, this "PARAMETER VALUE" block provides the user-defined lock value that defines when the input shall be forwarded to the output. However, since the "Lock value" parameter is optional, a default value has to set that is used whenever the user does not define a specific lock value. This is done by adding a "BOOL" block. Using a double click on the block, the value "TRUE" has to be selected. Then, the outgoing connector of the "BOOL" block has to linked to incoming connector of the "PARAMETER VALUE" block.
Now place an "EQUALS" block on the workspace and connect the "VALUE" connector of the "ITEM VALUE" block and the "VALUE" connector of the "PARAMETER VALUE(Lock Value)" block with the "INPUT" connectors of the "EQUAL" block. Finally, connect the "Output" connector of the "EQUAL" block with the "RESULT" connector of the "END" block. The final condition is shown in the figure above.
Writing the output
Close the condition and double click the "CMD" block within the command flow. Place an "INPUT ITEM VALUE" block and a "WRITE OUTPUT ITEM" block on the work sheet. Connect the "VALUE" connectors of both blocks with each other. Then double click the "<empty>" field of the "INPUT ITEM VALUE" block and select the "Input data point" input. In addition, double click the "<empty>" field of the "WRITE OUTPUT ITEM" block and select the "Output data point" output. In this way, the current value of the input data point is written to the output data point. The final command definition is shown in the figure below.
Saving the command and using the command within the NETx BMS Server
To provide the command to the \productbmsserver, it has to be compiled. This can be done by clicking the "Save" icon within the toolbar which saves and compiles the current command. In addition, it is possible to change several options of a command. To open the "Options" dialog, the entry "Options ..." within the menu "File" has to be selected (cf. figure \ref{fig:lock_compile}). Within this dialog, basic information about the command can be specified. To make the command visible within the catalog of the \productname\ and to reuse it in other commands, the flag "Add to Catalog" has to be activated. If the option "Auto-Compile" is set, the command is automatically compiled whenever the project is saved.
After having compiled the command successfully, close the XLogic Editor and go back to the NETx BMS Studio. Afterwards, the new command has to be loaded before it can be used. This can be done by restarting the NETx BMs Server or by loading the command manually by selecting the entry "Load logic module" within the "Tools" menu of the NETx BMS Studio. Then, open the "XCommand event definitions" via the menu "Extensions". Add a new definition and enter a name for the command within the first column. The next column can be left empty since all variables shall only be used locally. Within the third column, select "ON\_INPUT". This indicates that the command shall be invoked whenever one of the inputs changes. Then, press the "..." button within the "XCommand" column. A dialog appears where the command can be selected and configured. Select the "Lock" command from the drop down list. Afterwards, specify the different inputs, outputs, and parameters. A possible configuration is shown in th figure below.
After having saved the "XCommand event definition", restart the NETx BMS Server. Note that the item behind the lock object has to be initialized. If the lock object has not the item quality "GOOD", an error will be shown. A possible solution to this problem is described in following section
Improving the command by testing the quality of the lock object
If the command is executed and the item behind the lock object has the quality "UNCERTAIN" or "BAD", an error will occur. The reason is that the "ITEM VALUE" block within the condition does not provide a correct value and thus the "EQUALS" block gets a wrong input. To solve this, another condition has to be added to the command.
Open the XLogic Editor and reopen the "Lock" command via the menu "File". Place a new "IF THEN ELSE" block on the workspace. Connect the "START" connector of the "CMD HEADER" block to the "PREV" connector of the new "IF THEN ELSE" block. Then connect the "THEN NEXT" connector of the new block to the "PREV" connector of the "Verify lock object" block and the "ELSE NEXT" connector of the new block to the "FINISH" connector of the "CMD END" block. The new command flow is shown in the figure above.
Then, open the "Verify quality" condition and place a "PARAMETER VALUE" and a "IS GOOD" block on the work sheet. Select the parameter "Lock object" within the new "PARAMETER VALUE" block. Connect the "VALUE" of the "PARAMETER VALUE" connector to the "Item ID" connector of the "IS GOOD" block and the "Output" connector of the "IS GOOD" block to the "RESULT" connector of the "END" block. In this way, the item quality of the "Lock object" is tested. If the quality is "GOOD", the result of the condition is also true -- otherwise it is false. The final condition is shown in the figure below.
After having finished the new condition, save the project, compile it, restart the \productbmsserver, and test the improvement. Now, the command tests the quality of the lock object and does not invoke any function if the quality is not "GOOD".