XLogic2: Limit Item Value

Owned by Wolfgang Granzer
Last updated: Aug 31, 2016
10 min read

This example shows the functionality of an item value which is limited to a minimum and maximum boundary. The minimum and maximum value can be defined by the user. Additionally it is possible to define an email address where the user is notified when the input value is outside the upper or lower boundary. The value can also be written to an output item, when the value is inside the defined value range.

The functionality of the example is based on the idea to limit the output for a specific server item. The user has to specify the minimum and maximum value which defines the range in which the input values are accepted. The definition of the example provides additionally two optional parameter. First an output item can be defined, where correct values are forwarded too. Second it is possible to specify an email address, to inform the user about values of the item which are outside the defined range. In the following section the example is solved in a step by step tutorial and every single step is described in detail.

To use this tutorial, please do the following steps in advance:

  • Install the NETx BMS Server. The setup can be found here at our website.
  • Create a new BMS server workspace and integrate some data points that you want to monitor.

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 "LIMIT ITEM VALUE'' 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 can be written on.

Finally, define the following parameters:

  • Parameter_min: defines the minimum value of the range for the input item
  • Parameter_max: defines the maximum value of the range for the input item
  • Parameter_email: defines the e mail address where item values outside the boundaries are reported.

Command flow

The next step to define the command is to add different blocks to define the command flow. In this example the structure can be grouped into three different steps that have to be taken to fulfill all the requirements of the task. First the input value has to be validated, if the numeric input value is "GOOD''. This means that the input item was assigned with a valid item value. The second step is to check, if the specified value is inside a defined value range. The third and last step is the output of the item value. The value can be written on a specified output item or the messages concerning non valid values outside the numeric range can be sent to a email address.

To validate the input three "IF THEN ELSE'' blocks need to be added to the command window and connect them as illustrated in the figure below. Three "IF THEN ELSE'' blocks in combination three "CMD'' blocks are finally used to check and write the output to the defined server item or to write a message to an e-mail address. Please connect the individual blocks as illustrated in the figure below. In the following section the individual blocks and their purpose will be described in detail. All remaining connectors that do not have a link to another block have to be connected to the "CMD END'' block. After the configuration the links of the connectors can be checked over the "Compile'' button.

Check if input value is good

In the first step it has to be checked if the input was assigned with a valid value. For this purpose the first "IF THEN ELSE'' block will be used. For documentation purposes it is possible to add a comment to the block. Via double click on the field "<comment>'' a message box opens, where a comment can be inserted (e.g. Input value good). Via double click on the "<empty>'' field of the "IF THEN ELSE'' block, a new window for the definition of the condition opens. A "Input Item ID'' block and a "IS GOOD'' block have to be inserted to this window. The "ID'' connector of the "Input Item ID'' block has to be connected to the "Item ID'' connector of the "IS GOOD'' block. The  "Output'' connector of the "IS GOOD'' block has to be connected to the "Result'' connector of the "End'' block. Via double click on the "Input Item ID'' block the input "Input_Item_1'' has to be chosen from the drop-down menu. The final condition is illustrated in the figure below. The window can now be closed.

 

 

Check the value range

The check for validating the value range is done in two steps. First the lower limit is checked and afterwards the upper limit. Click on the "<comment>'' field of the second "IF THEN ELSE'' block and add a comment (e.g. value greater min). Double click on the "<empty>'' field of the "IF THEN ELSE'' block. In the opened window a "INPUT ITEM VALUE'', "PARAMETER VALUE'' and a "GREATER OR EQUAL'' block have to be added. The "Output'' connector of the "INPUT ITEM VALUE'' block has to be connected to the "Input 1'' connector of the "GREATER OR EQUAL'' block. The "Output'' connector of the "PARAMETER VALUE'' block has to be connected to the "Input 2'' connector of the "GREATER OR EQUAL'' block. Double click on the "INPUT ITEM VALUE'' block and select "Input_Item_1''. Then double click on the "PARAMETER VALUE'' block and select "Parameter_min''. Finally connect the "Output'' connector of the "GREATER OR EQUAL'' block with the "Result'' connector of the "End'' block. Now the input value is checked for the lower limit as illustrated in the figure below. The next step is to check the input value for the upper limit. The window can now be closed.

 

In the second step the input value has to be checked if it is below the maximum value of the range. Click on the "<comment>'' field of the third "IF THEN ELSE'' block and add a comment (e.g. value lower max). Double click on the "<empty>'' field of the "IF THEN ELSE'' block. In the opened window a "INPUT ITEM VALUE'', a "PARAMETER VALUE'' and a "LESS OR EQUAL'' block have to be added. The "Output'' connector of the "INPUT ITEM VALUE'' block has to be connected to the "Input 1'' connector of the "LESS OR EQUAL'' block. The "Output'' connector of the "PARAMETER VALUE'' block has to be connected to the "Input 2'' connector of the "LESS OR EQUAL'' block. Double click on the "INPUT ITEM VALUE'' block and select "Input_Item_1''. Then double click on the "PARAMETER VALUE'' block and select "Parameter_max''. Finally connect the "Output'' connector of the "LESS OR EQUAL'' block with the "Result'' connector of the "End'' block. After this step the condition should look like in figure \ref{fig:limit_condition_max}. The window can now be closed.

Check if output is set

To write the input item on a server item, it has to be checked if the output item parameter is not optional before the value can be written on the item. For this purpose the fourth "IF THEN ELSE'' block has to be used. Click on the "<comment>'' field of the "IF THEN ELSE'' block and add a comment (e.g. Output item set). Via double click on the "<empty>'' field of the "IF THEN ELSE'' block a window opens to define a new condition. Drag an "ARGUMENT EXISTS'' block into the new window and connect the "EXISTS'' connector with the "Result'' connector of the "End'' block. Double click on the "ARGUMENT EXISTS'' block and select the "Output_Item_1'' from the drop-down menu. The window can now be closed.

 

Writing the output

After the parameter was checked if it is set and is not optional, the current value can be written to the defined output item. For this purpose the "CMD'' block after the fourth "IF THEN ELSE'' block has to be used. Click on the "<comment>'' field of the "CMD'' block and add a comment (e.g. Write input to output value). Double click on the "<empty>'' field of the "CMD'' block to open the window to define the new condition. Drag a "INPUT ITEM VALUE'' and a "WRITE OUTPUT VALUE'' block to the window and connect the "VALUE'' connectors of both blocks with each other. Double click on the "INPUT ITEM VALUE'' block and select "Input_Item_1''. Additionally click on the "WRITE OUTPUT VALUE'' block and select "Output_Item_1''. Now the value can be written to the output if it is inside the defined value range.  The window can now be closed.

 

Check if email address is set

As next, it has to be checked whether an email address was set by the user. The two remaining "IF THEN ELSE'' blocks are used to define one for the upper and one for the lower limit. Click on the "<comment>'' field of the "IF THEN ELSE'' block and add a comment (e.g. Email address set). Double click on the "<empty>'' field of the "IF THEN ELSE'' block to open the windows to define new conditions. Add in both windows an "ARGUMENT EXISTS'' block and connect the "EXISTS'' connector with the "Result'' connector of the "End'' block. Double click on the "ARGUMENT EXISTS'' block and select "Parameter_email'' from the drop-down menu. The window can now be closed.

 

Send email to configured address

 

 

For this purpose the two remaining "CMD'' blocks are used to send a message to the defined email address. Click on the "<comment>'' field of the "CMD'' blocks and add a comment ("Value above max'' and "Value under min''). Double click on the "<empty>'' fields of the "CMD'' blocks and add a "PARAMETER VALUE'' block, two "STRING'' blocks and a "SEND EMAIL TO'' block to the upcoming window. Connect the

"Value'' connector of the "PARAMETER VALUE'' blocks with the "Address'' connector of the "SEND EMAIL TO'' blocks. Double click on the "PARAMETER VALUE'' block and select the "Parameter_email'' from the drop-down menu. Connect now the two "STRING'' blocks to the "Subject'' and "Body'' connectors or the "SEND EMAIL TO'' block. Enter meaningful strings to the two "STRING'' blocks of each window (e.g "Value out of range'', "The input value is too high/low''). To send emails the corresponding settings have to be added to the system configuration of the NETx BMSServer. The configuration of the email system is also described in the documentation of the NETx BMS Server.

Configuring the e mail system

In order to send an e mail, the connection to an SMTP e mail server has to be configured. This is done within the System Parameter within the Server menu of the NETx BMS Studio. At the bottom of the configuration file, the SMTP host (IP address), SMTP port number and the authentication information (TLS, user name , password) have to entered. The following screenshot shows the configuration of the gmail SMTP server.

Saving the command and using the command within the NETx BMS Server

 

To provide the command to the NETx BMS Server, 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. Within this dialog, basic information about the command can be specified. The flag "Add to Catalog'' defines whether the command shall be visible within the catalog of the XLogic Editor. If activated, the command can be reused in other commands. 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 \productbmsstudio. 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 "LIMIT ITEM VALUE'' command from the drop down list. Afterwards, specify the different inputs, outputs, and parameters. A possible configuration is shown in the figure above.

After having saved the "XCommand definition'', restart the NETx BMS Server and test the command.