11.3.2 Details of a Dashboard Viewer window layout file

This subsection discusses how to create a Dashboard Viewer window layout file, shows the specification format, and explains details of the definition. It also discusses the handling of data when dashboard-display data is displayed with Dashboard Viewer.

Organization of this subsection
(1) How to create the file
(2) Specification format
(3) Details of the definition
(4) Handling of types by Dashboard Viewer

(1) How to create the file

The name of a Dashboard Viewer window layout file is window-name.xml. You can specify for window-name any desired name consisting of 1 to 16 single-byte alphanumeric characters.

We recommend that you use the sample file provided during installation to create each Dashboard Viewer window layout file. Copy the following sample file and then edit the copy:

installation-directory\samples\httppacket\web\containers\uCSDPAF_Server\layout\dashboard.xml

Store the created Dashboard Viewer window layout file in the following directory:

installation-directory\psb\CC\web\containers\uCSDPAF_Server\layout\#

#
The user must create the layout directory.

The following notes apply to creating a Dashboard Viewer window layout file.

(2) Specification format

The following shows an example of the specification format for a Dashboard Viewer window layout file.

<dashboardDisplay>
 <connectionSetting>
   <serverName>localhost</serverName>
   <portNo>20421</portNo>
 </connectionSetting>
 <widgetGroup>
   <widget>
     <kind>table</kind>
     <dataSetting>
       <interval>5000</interval>
       <data1>
         <dataName>InprocessAPTest/OutputAdaptor1/outputer</dataName>
         <filter>
           <columnName>SUBTIME</columnName>
           <condition>ge</condition>
           <value>100</value>
         </filter>
       </data1>
     </dataSetting>
     <dataDisplay>
       <threshold>
         <columnName>SUBTIME</columnName>
         <condition>ge</condition>
         <value>5000</value>
       </threshold>
     </dataDisplay>
   </widget>
 </widgetGroup>
</dashboardDisplay>

(3) Details of the definition

dashboardDisplay tag (all definition information)
Defines the entire interface for a dashboard window.
connectionSetting tag (definition of the connection-target server)
Defines information about the connection-target server.
serverName tag
Specifies the name of the connection-target SDP server, as 0 to 255 single-byte alphanumeric characters. The default is the null character. When the null character is specified, no connection with a server will be established.
portNo tag
Specifies the port number of the connection-target SDP server, as a single-byte integer in the range from 0 to 65535. The default is the null character. When the null character is specified, no connection with a server will be established.
widgetGroup tag (definitions of widgets)
Defines the widgets.
widget tag (definition of a widget)
Defines a widget.
kind tag
Specifies the type of widget to be displayed. The default value is table. The permitted values are as follows:
  • bar
    Vertical bar graph
  • circle
    Pie chart
  • x-y
    Scatter chart
  • trend
    Broken line graph
  • table
    Table
widgetSetting tag (definition of panel for the widget)
Defines information about the panel for the widget.
title tag
Specifies a title for the widget, as a string of 0 to 32 characters. The default is the null character.
border tag (definition of a border for the widget)
Defines a border for the widget.
Color tag
Specifies a color (RGB color) for the widget's border. The default value is 192,192,192 (gray).
bg tag (definition of a background for the widget)
Defines a background for the widget.
When table is specified in the kind tag under the widget tag, no background color or background image will be displayed.
Color1 tag
Specifies a background color (RGB color) for the widget. The default value is 255,255,255 (white).
bgImage tag
Specifies the URL of an image file that is to be displayed as the background for the widget, as 0 to 255 single-byte alphanumeric characters beginning with http://. The default is the null character.
You can specify an image file that is in GIF or JPG format. If the specified file contains animation, the operation is not guaranteed. If the size of the widget differs from the size of the image, the image is displayed centered in the widget; the image is not enlarged or reduced.
When the null character is specified or if the specified image cannot be displayed, the background color is set.
dataSetting tag (definition of data settings for the widget)
Defines information about setting the data for the widget.
interval tag
Specifies the interval to be used as Dashboard Viewer's display refresh interval and as Dashboard Viewer's data acquisition interval (the interval for acquiring data from Dashboard Server), as a single-byte integer in the range from 1 to 60000 (representing milliseconds). The default value is 3000.
Note that immediately after a startup or re-connection, it might take about twice as much time as the specified refresh interval before data is displayed.
data1 to data5 tags (definition of series of data items)
Defines the data to be displayed. For each data series, a maximum of 1,024 data items can be retained. If the number of data items in a series exceeds 1,024, the excess items are discarded sequentially beginning with the first data item that arrived at Dashboard Server.
When the value of the kind tag under the widget tag is bar, circle, or table, any values in data2 through data5 tags are not used.
legendName tag
Specifies the name that is to be displayed as this data's legend, as a string of 0 to 30 characters. The default is the null character.
When the value of the kind tag under the widget tag is bar, circle, or table, any specified legend name is not displayed.
dataName tag
Specifies the connection name of the data that is to be obtained from Dashboard Server, as 0 to 255 single-byte alphanumeric characters. The default is the null character.
When the null character is specified, a data connection is not used. If the specified connection name is not found, an error occurs.
When the specified connection name is not found or connection fails after Dashboard Viewer has started, the connection status icon changes to the connection-failed icon.
column1 to column2 tags
Specifies the columns to be displayed in the data obtained from Dashboard Server, as 0 to 255 single-byte alphanumeric characters. The default is the null character.
The values depend on the value of the kind tag under the widget tag:
  • bar
    Specify the abscissa (ID) in the column1 tag and the ordinate (value) in the column2 tag.
  • circle
    Specify a sector (ID) in the column1 tag and the size of the sector (value) in the column2 tag.
  • x-y
    Specify the abscissa (value of x-axis) in the column1 tag and the ordinate (value of y-axis) in the column2 tag.
  • trend
    Specify the abscissa (time) in the column1 tag and the ordinate (value) in the column2 tag.
  • table
    No values are used.
When the value of the kind tag is bar, circle, x-y, or trend and the null character is specified in the column1 or column2 tag, data is not displayed.
If any data has been acquired since Dashboard Viewer started, but the data does not contain a specified column, the KFSP46954-E error message is displayed. If the data type is not correct, the KFSP46955-E error message is displayed.
color tag
When the value of the kind tag under the widget tag is x-y or trend, specifies a color (RGB color) to be used to display the data. The default value is 0,0,0 (black).
filter tag (filter definition)
Defines information about a filter for the acquired data. You can set only one filter for each data.
columnName tag
Specifies the name of the column whose data is to be filtered, as 0 to 255 single-byte alphanumeric characters. The default is the null character.
The data that does not satisfy the filter condition defined in the condition tag is hidden. If the null character is specified, no data is hidden.
If any data has been acquired since Dashboard Viewer started, but the data does not contain the specified column, the KFSP46954-E error message is displayed. If the data type is not correct, the KFSP46955-E error message is displayed.
condition tag
Specifies the relationship between the column value and the value specified in the value tag. The default value is eq.
The permitted values depend on the data type of the value in the column specified in the columnName tag, as described below:
  • When a string-type (STRING) column is specified in the columnName tag
    The permitted values are eq (=) and ne (!=).
  • When an integer-type (BYTE, SHORT, INT, or LONG) column is specified in the columnName tag
    The permitted values are lt (>), gt (<), le (>=), ge (<=), eq (=), and ne (!=).
If any data has been acquired since Dashboard Viewer started, but the value specified for the condition is invalid, the KFSP46961-E error message is displayed.
value tag
Specifies the value to be compared.
The permitted value depends on the data type of the value in the column specified in the columnName tag, as described below:
  • When a string-type (STRING) column is specified in the columnName tag
    Specify 0 to 255 single-byte alphanumeric characters.
  • When an integer-type (BYTE, SHORT, INT, or LONG) column is specified in the columnName tag
    Specify a 32-bit integer-type value, in the range from -2147483648 to 2147483647.
If any data has been acquired since Dashboard Viewer started, but the value specified for the condition is invalid, the KFSP46961-E error message is displayed.
A value must be specified in the value tag.
dataDisplay tag (definition of data display)
Defines information about how data is displayed in the widget.
threshold tag (definition of threshold)
Defines a threshold value for the data that is to be displayed.
columnName tag
Specifies the column name for which a threshold is to be specified, as 0 to 255 single-byte alphanumeric characters. The default is the null character.
When the value of the kind tag under the widget tag is table, all characters in the row that satisfies the specified threshold value are displayed in red. If the null character is specified, display highlighting is disabled.
If any data has been acquired since Dashboard Viewer started, but the table data to be displayed does not contain the specified column, the KFSP46954-E error message is displayed. If the data type is not correct, the KFSP46955-E error message is displayed.
condition tag
Specifies the relationship between the column value and the value specified in the value tag. The default value is eq.
The permitted values depend on the data type of the value in the column specified in the columnName tag, as described below:
  • When a string-type (STRING) column is specified in the columnName tag
    The permitted values are eq (=) and ne (!=).
  • When an integer-type (BYTE, SHORT, INT, or LONG) column is specified in the columnName tag
    The permitted values are lt (>), gt (<), le (>=), ge (<=), eq (=), and ne (!=).
If the value specified for the condition is invalid, the KFSP46961-E error message is displayed.
value tag
Specifies the value to be compared.
The permitted value depends on the type of value in the column specified in the columnName tag, as described below:
  • When a string-type (STRING) column is specified in the columnName tag
    Specify 0 to 255 single-byte alphanumeric characters.
  • When an integer-type (BYTE, SHORT, INT, or LONG) column is specified in the columnName tag
    Specify a 32-bit integer-type value, in the range from -2147483648 to 2147483647.
If the value specified for the condition is invalid, the KFSP46961-E error message is displayed.
A value must be specified in the value tag.
xAxis tag (definition of x-axis)
Defines the x-axis settings.
max tag
When the value of the kind tag under the widget tag is x-y, specifies the maximum value for the data to be plotted in the x-axis direction, expressed as the null character or a 32-bit integer-type value in the range from -2147483648 to 2147483647. The default is the null character.
If the specified maximum value (max tag value) is equal to or less than the specified minimum value (min tag value), the KFSP46961-E error message is displayed.
If the null character is specified for the maximum value, the scale is changed automatically.
If the value of the kind tag under the widget tag is not x-y, any specified maximum value is not set for the x-axis.
min tag
When the value of the kind tag under the widget tag is x-y, specifies the minimum value for the data to be plotted in the x-axis direction, expressed as the null character or a 32-bit integer-type value in the range from -2147483648 to 2147483647. The default is the null character.
If the specified maximum value (max tag value) is equal to or less than the specified minimum value (min tag value), the KFSP46961-E error message is displayed.
If the null character is specified for the minimum value, the scale is changed automatically.
If the value of the kind tag under the widget tag is not x-y, any specified minimum value is not set for the x-axis.
yAxis tag (definition of y-axis)
Defines the y-axis settings.
max tag
When the value of the kind tag under the widget tag is x-y or trend, specifies the maximum value for the data to be plotted in the y-axis direction, expressed as the null character or a 32-bit integer-type value in the range from -2147483648 to 2147483647. The default is the null character.
If the specified maximum value (max tag value) is equal to or less than the specified minimum value (min tag value), the KFSP46961-E error message is displayed.
If the null character is specified for the maximum value, the scale is changed automatically.
If the value of the kind tag under the widget tag is neither x-y nor trend, any specified maximum value is not set for the y-axis.
min tag
When the value of the kind tag under the widget tag is x-y or trend, specifies the minimum value for the data to be plotted in the y-axis direction, expressed as the null character or a 32-bit integer-type value in the range from -2147483648 to 2147483647. The default is the null character.
If the specified maximum value (max tag value) is equal to or less than the specified minimum value (min tag value), the KFSP46961-E error message is displayed.
If the null character is specified for the minimum value, the scale is changed automatically.
If the value of the kind tag under the widget tag is neither x-y nor trend, any specified minimum value is not set for the y-axis.
xTimeRange tag (definition of time axis)
Defines settings for the x-axis (time axis).
range tag
When the value of the kind tag under the widget tag is trend, specifies the amount of time to be plotted on the x-axis for the displayed data, expressed as a single-byte integer in the range from 1 to 86400 (representing seconds). The specified range of time must fit within a single window. The default value is 300.
If the value of the kind tag under the widget tag is not trend, any specified time is not set for the x-axis.
SliderFlag tag
When the value of the kind tag under the widget tag is trend, specifies whether or not a slider is to be displayed for the time axis (x-axis). The default value is OFF.
The permitted values (in single-byte upper-case letters) are as follows:
  • ON
    Displays a slider.
  • OFF
    Does not display a slider.
If the value of the kind tag under the widget tag is not trend, the slider display setting for the time axis (x-axis) is disabled.
tableProperties tag (table definition)
Defines settings for a table.
columnHeaderList tag (definition of column headers)
When the value of the kind tag under the widget tag is table, defines information about the column headers that are to be displayed.
column tag
Defines information about a column that is to be displayed.
If more than 16 column tags are specified, the KFSP46966-E error message is displayed.
actualName tag
Specifies the name of the column whose data is to be displayed, as 0 to 255 single-byte alphanumeric characters; this must be a column contained in the received data. The default is the null character.
When the null character is specified, data is not sorted.
If any data has been acquired since Dashboard Viewer started, but the data does not contain the specified column, the KFSP46954-E error message is displayed.
displayName tag
Specifies the name to be displayed for this column in the column header, as a string of 0 to 32 characters. The default is the null character.
legend tag (legend definition)
Defines information about a legend.
displayFlag tag
Specifies whether or not a legend is to be displayed on the right side of a chart. The default value is OFF.
The permitted values (in single-byte upper-case letters) are as follows:
  • ON
    Displays a legend.
  • OFF
    Does not display a legend.
The content of the legend that will be displayed depends on the value of the kind tag under the widget tag:
  • bar
    Displays a list of the names that are displayed on the abscissa.
  • circle
    Displays a list of the names that are assigned to the sectors in the pie chart.
  • x-y
    Displays the value specified in the legendName tag for each of the data1 through data5 tags.
  • trend
    Displays the value specified in the legendName tag for each of the data1 through data5 tags.
  • table
    Does not display a legend, even when ON is specified.
width tag
Specifies the width of the legend area in pixels, as a single-byte integer in the range from 1 to 2048; or, specifies the width of the legend area as a single-byte integer in the range from 1 to 100 followed by the percent sign (%). A value specified using single-byte integers and % is treated as the ratio of the legend's width to the widget's width. If the legend cannot be displayed based on the specified value, the legend is resized so that it is displayable.
jumpToURL tag (definition of URL change)
Defines information about a URL change.
URL tag
Specifies a destination URL, as 0 to 128 single-byte alphanumeric characters beginning with http://. The default is the null character.
If the null character is specified, no URL change will be performed.
parameter1 tag
Specifies the name of argument 1 in the information contained in the selected data that is to be passed to the destination URL, as 0 to 16 single-byte alphanumeric characters. The default is the null character.
If the null character is specified, no information will be passed to the destination URL.
value1 tag
Specifies the value set in argument 1 in the information contained in the selected data that is to be passed to the destination URL, as 0 to 16 single-byte alphanumeric characters. The default is the null character.
The permitted values (the value that can be passed to the destination URL) depends on the value of the kind tag under the widget tag:
  • bar
    Specifies the value of ID (abscissa).
  • circle
    Specifies the value of ID (abscissa).
  • x-y
    Specifies the value of legend.
  • trend
    Specifies the value of legend.
  • table
    Specifies the values of column1 through column16.
When table is specified in the kind tag under the widget and any data has been acquired since Dashboard Viewer started, but the value of [n] in column[n] is greater than the actual number of columns to be displayed, the KFSP46961-E error message is displayed. If the type of column [n] is not a character string, the KFSP46955-E error message is displayed.

(4) Handling of types by Dashboard Viewer

When Dashboard Viewer is used to display dashboard-display data, Dashboard Viewer handles the types of the dashboard-display data as shown in the table below.

No.Type that can be specified in the dashboard output connector definitionHandling of type by Dashboard ViewerValue range
1BYTEInteger-231 to (231)-1
2SHORT
3INT
4LONGInteger-253 to 253 #1
5FLOATDouble-precision real number#21.79769313486231​ x (10308) to -1.79769313486231​ x (10308)
6DOUBLE
7BIG_DECIMALCharacter string type0 to 1,024 characters#3
8STRING
9DATETime type#4Maximum#1: 1970-01-01 at 00:00:0.000
Minimum#1: 9999-12-31 at 23:59:59.999
10TIME
11TIMESTAMP
#1
If a received value is less than the minimum value, it is replaced with the minimum value. If a received value is greater than the maximum value, it is replaced with the maximum value.
#2
The value range complies with IEEE 754. Rounding of values does not occur between the dashboard output connector and Dashboard Viewer.
#3
If a received character string is longer than the maximum length, it is truncated at the maximum length. A double-byte character is treated as a single character.
#4
The following shows the display format for the TIMESTAMP type:

YYYY-MM-DD hh:mm:ss.SSS

YYYY: Year

MM: Month

DD: Day

hh: Hour

mm: Minute

ss: Second

SSS: Millisecond