Command Line Options: Display Server

The following command line arguments are enabled when you run the Display Server from a Windows Command Prompt or UNIX terminal window. Options specified using command line arguments override values saved in initialization (e.g. OPTIONS.ini) files.

For command line options for your data source, refer to the RTView Data Sources section of this documentation.

Note: If a command line argument contains a space or a semicolon, then the entire argument must be enclosed in quotes (e.g.: "-sub:$data:my Data").

 

Name

Description

-bg

Set the RTView application to run as a background process. When this option is specified, the GmsLauncher process and run scripts exit immediately after the RTView application is started, rather than continuing to run, thereby reducing the host system process count. However, note that:

• The RTView application output and error messages will not appear in the command/shell window from which it was launched.
• Ctrl-c cannot be used to terminate the application.

Note: This option is only recognized on the command line and is not read from, or saved to, any RTView options (.ini) files.

Example:

-bg

-cellsperexport

Specify to limit the number of table cells included in HTML/Excel exports requested by the Thin Client. This option avoids out-of-memory exceptions and timeouts when exporting tables with many rows. This option is typically used in conjunction with the cellsperpage option, and has the following behavior:

• If the cellsperexport option is not specified, or if a value of less than a 1000 is specified, the Display Server attempts to export all rows for all tables, regardless of the table size.
• If a table contains fewer cells than the cellsperexport setting, the Display Server exports all rows for that table.
• The exported HTM/Excel table starts with the same first row (or near it) that is visible in the Thin Client. That is, if you scroll to row 900 in the Thin Client and perform an HTML/Excel export, the exported table will begin near line 900.

 
• If the rows included in an export to HTML/Excel are limited by the cellsperexport option, the first row in the exported file is the same as the first row currently visible in the Thin Client.
• An export to HTML/Excel requires less CPU and memory than an export to PDF (see cellsperreport), therefore the value of the cellsperexport option is typically larger than the value of the cellsperreport option. For example, if an export to HTML/Excel was performed on a table with 5 columns and 100,000 rows, and the option -cellsperexport:30000 was specified when the Display Server was launched, 6000 rows (30000/5) would be included in an exported HTML/Excel file for that table. If the -cellsperreport:5000 option was specified, an export to PDF would include 1000 rows from the table.

Note: This option is not recognized by the Builder or the Viewer.

Example:

run_displayserver -cellsperpage:10000 -cellsperexport:30000

-cellsperpage

Specify server-side table paging and sorting mode, also referred to as paging mode, for the Thin Client. Paging mode improves the performance of displays containing table objects (obj_table02) with many rows. In paging mode, the Display Server sends a specified maximum number of table data rows at a time to the Thin Client, rather than sending all table data rows at once. This option avoids out-of-memory exceptions, timeouts and sluggish performance that can otherwise occur from processing and transmitting all of the rows at once. This option is typically used in conjunction with the cellsperexport and cellsperreport options.

The page of rows sent from the Display Server to the Thin Client includes all of the rows currently visible in the Thin Client plus additional rows above and/or below the visible rows. If the user scrolls beyond the rows contained in the current page or clicks on a column header to change the sorting order, the Display Server sends another page of rows in response.

The cellsperpage option can also be specified in the DISPLAYSERVER.ini file. See RTView Core® User’s Guide Version 7.4 for more information.

Command line example:

run_displayserver -cellsperpage:NNNN

where NNNN specifies the number of table cells the Display Server includes per page. Typical values for cellsperpage are 10000 to 30000.

 

The number of cells in a table is equal to the number of rows times the number of columns. For example, if cellsperpage = 10000, and the display contains a table with 5 columns, the Display Server uses a page size of 2000 rows for the table. This means the Display Server sends a maximum of 2000 table rows to the Thin Client at a time. If the table contains 40,000 rows the Display Server sends rows 1 through 2000 to the Thin Client when a user opens the display. If the user then scrolls to the bottom of the table, the Display Server sends rows 38,001 through 40,000 to the Thin Client. Similarly, if the user clicks on a column header to sort by that column, the Display Server sorts the table and sends the first 2000 sorted rows to the Thin Client. After the user scrolls or sorts a table in paging mode, the Thin Client displays '...' in each cell and an hourglass cursor appears over the table while it waits to receive the new page from the Display Server. The cellsperpage option also has the following behavior:

 
• A smaller value for cellsperpage reduces the memory requirements for processing large tables in the Display Server, Application Server, and browser. A larger value makes for smoother scrolling in the Thin Client because it increases the number of rows through which the Thin Client can scroll before it needs to request another page from the server.
• If the cellsperpage option is not specified, or if a value less than a 1000 is specified, paging mode is disabled and the Display Server sends all data rows to the Thin Client for all tables regardless of the table size.
• If a table contains fewer cells than the cellsperpage setting, the Display Server sends all rows for that table.
• Paging mode only affects the behavior of obj_table02 objects, and only in the Thin Client.
• The maxNumberOfHistoryRows property on obj_table02 limits the maximum number of rows that are shown in the table, regardless of the cellsperpage setting.
• After scrolling to a new page, if the user immediately drags the scrollbar again, the table may not react. The user may need to nudge the scrollbar knob or click on the scroll up/down arrows to make the table react.

 
• The Thin Client Export Table to Excel/HTML/PDF feature is not affected by paging mode. Attempts to export a table with many rows may result in timeouts or out-of-memory exceptions in the Display Server or in the Display Servlet. To avoid those errors, see the cellsperexport and cellsperreport Display Server options.
• After the user clicks a column to sort a table, the table vertical scrollbar is reset to the top position.
• The Thin Client ignores the scrollToSelectionFlag property on a table that is in paging mode.
• A table row selection is cleared when a different page of rows is received from the Display Server. If a table is in paging mode, only rows that are on the current page can be selected, even if the table multiSelectFlag property is checked.

-cellsperreport

Specify to limit the number of table cells included in PDF exports requested by the Thin Client. This option avoids out-of-memory exceptions and timeouts when exporting tables with many rows. This option is typically used in conjunction with the cellsperpage option, and has the following behavior:

• If the cellsperexport option is not specified, or if a value of less than a 1000 is specified, the Display Server attempts to export all rows for all tables, regardless of the table size.
• If a table contains fewer cells than the cellsperreport setting, the Display Server exports all rows for that table.
• In an exported PDF file, the scroll position of the Thin Client has no effect on the starting row in the PDF file, nor any effect on the rows that are included in the PDF report.
• An export to PDF requires more CPU and memory than an export to HTML/Excel (see cellsperexport), therefore the value of the cellsperreport option is typically smaller than the value of the cellsperexport option. For example, if an export to HTML/Excel was performed on a table with 5 columns and 100,000 rows, and the option -cellsperexport:30000 was specified when the Display Server was launched, 6000 rows (30000/5) would be included in an exported HTML/Excel file for that table. If the -cellsperreport:5000 option was specified, an export to PDF would include 1000 rows from the table.

Note: This option is not recognized by the Builder or the Viewer.

Example:

run_displayserver -cellsperpage:10000 -cellsperreport:5000

-clearsubs:

Set to false in order to preserve the value of local variables, for which the Use as Substitution option is selected, when navigating to different displays in the same panel. This behavior is consistent with that of the Display Viewer.

By default (or if set to true), the Display Server will reset all local variables to their initial values when navigating to a new display regardless of the variable's value in the current display.

Note: Global variables are not affected by this option.

Example:

run_displayserver -clearsubs:false

-daemon

Run the Display Server as a daemon process.

Example:

run_displayserver -daemon

-dataserver:

(filename) - Read data from Data Server output file instead of directly from data sources. If no file name is specified, default output file (rtvdata.xml) will be used. If necessary, include local directory path or http URL.

Example:

-dataserver:rtvdata.xml

 

//(host:port) - Read data from Data Server via socket instead of directly from data sources. If no host is specified, local host will be used. If no port is specified, default port (3278) will be used.

Example:

-dataserver://remotehost:8723

 

remote:primary,backup1 - Read data from Data Server instead of directly from data sources. Specify primary and backup servers. If no host is specified, local host will be used. If no port is specified, default port (3278) will be used.

Note: Designation of a backup server is optional; one or multiple backup servers can be specified.

Example:

-dataserver:remote:host:8723,host:8080

 

remote:http://host:port/rtvdata,http://host:port/rtvdata_backup1 - Read data from Data Server via servlet instead of directly from data sources. Specify primary and backup servers. The host is web server hosting the servlet. The port is port used by the web server.

Note: Designation of a backup server is optional; one or multiple backup servers can be specified.

Example:

-dataserver:remote:http://host:8723/rtvdata,http://host:8080/rtvdata_backup

 

name=name;connect=primary,backup1 - Specify primary and backup named data server(s). The name is the Name specified when this data server was configured and connect is either host:port or for servlet http://host:port/rtvdata.

Note: Designation of a backup server is optional; one or multiple backup servers can be specified.

Example:

-dataserver:name=MyDataServer;connect=localhost:56789,host:8080

-dataserver:name=London;connect=https://londonServer:8080/rtvdata,http://host:8080/rtvdata_backup

-dsenable:(dskey)

Enable data source(s) for data attachments and defined commands that have been configured to bypass data being redirected through the specified data server(s).

The dskey is the abbreviation for the data source as listed in the Attach to Data and Define Command drop down menus, but in all lower case.

Example:

-dsenable:sql

-exit_on_out_of_memory

Force the Display Server to terminate when an OutOfMemoryException occurs.

This option is intended for use in a HA deployment where a backup server is available, otherwise the process may continue to run in a crippled state and prevent the backup from taking over.

Note: The Display Server is not automatically restarted by this option and must be restarted manually.

Example:

-exit_on_out_of_memory

-imageformat

Specify image format: jpg or png. By default, the Display Server will automatically select the image that results in the fewer number of bytes for each display.

Example:

-imageformat:jpg

-imagequality:

Specify a value between 0 and 100 to control the quality of .jpg images. If the value is 100, the Display Server will output the highest quality image with the lowest compression. If the value is 0, the Display Server will output the lowest quality image using the highest compression. Default is 75.

If the -verbose option is specified at startup, image creation time/size for each display refresh will be shown in the Display Server console output.

Example:

-imagequality:75

Note: The Display Server chooses an image format (.jpg or .png) for each display, depending on which format produces the smallest image size (in bytes). The size of .png images is controlled by the -pngcompress option.

-jmxport:(port number)

The port number to use to expose JMX methods to monitor and manage the Display Server. There is no default port. If not specified, these JMX methods will not be accessible. See RTView Core® User’s Guide Version 7.4 for more information.

Example:

-jmxport:9998

-log4j

Turns on Log4j logging for the RTView application. By default, RTView processes (Builder, Viewer, Data Server, Display Server, or Historian) print log messages to the console. To obtain log files, you redirect the RTView application output and error streams to a log file using Log4j.

After executing this command, the first time-stamped row in the log file appears as follows:

2012-02-02 14:00:54,693 INFO – [rtview] Log4j is being used with sl.log4j.properties as the configuration file.

When Log4j is not in use, the first time-stamped row in the log file appears as follows:

2012-02-03 10:40:31.866 [rtview] Logging redirected for System.out and System.err. Log4j is not in use.

(Note the missing INFO column when Log4j is not in use.)

For example:

run_displayserver –log4j

run_displayserver –log4j –log4jlevel:INFO –showlogcat

To run an RTView application as a background process using the -bg command line argument, use the sl-bg.log4j.properties configuration file (which only outputs to a log file rather than to a console).

-bg (background) example:

run_displayserver –bg –log4j –log4jprops:sl-bg.log4j.properties

Note: The logging method from previous versions of RTView does not use Log4j. This previous method of logging is enabled with -logfile and –logdir and is still supported. Do not use both the previous logging method and Log4j or you receive the following error message:

ERROR: log4j configuration ERROR - com.sl.rtview.useLog4j is set to true but -logfile redirection is in use. Log4j will not be used.

 

-showlogcat - Turns on the Category column in the log file output. When not in use, the Category column is not shown in the log file. When not in use, the Category column is not shown in the log file.

For example:

-showlogcat

 

-log4jprops - Specify the .properties file to use to format the Log4j log file. By default, sl.log4j.properties is used. Use this to provide a different property file name. The .properties file is searched for inside a .jar/.war file, then searched for in the current directory, and lastly searched for in the %RTV_HOME%/lib directory. The filename can have a path preceding it. For example, C:\mydir\my.log4j.properties.

For example:

-log4jprops:mylogfile.properties

 

-log4jlevel - Specify the Log4j Level. INFO is used by default. Valid values are:

FATAL: Indicates a severe error that likely causes the application to abort.

ERROR: Indicates an event that might not cause the application to abort.

WARN: Indicates a potentially harmful event.

DEBUG: Indicates detailed informational about events for debugging the application.

INFO: Indicates informational messages about the progress of the application at coarse-grained level.

For example:

-log4jlevel:INFO

-logdir

Specify to prefix the log file name that is set in the -logfile option to the directory name in which the log file is stored. If the -logfile option is not specified, this option is ignored.

Note: This option is only recognized on the command line and is not read from, or saved to, any RTView options (.ini) files.

Example:

-logdir:ABCcompany

-logfile

Specify the redirection of output and error messages to a file. The RTView application output and error message streams are redirected to the specified file. The file is created if it does not exist. If the file does exist, its previous contents are cleared.

Note: This option is only recognized on the command line and is not read from, or saved to, any RTView options (.ini) files.

Example:

-logfile:DisplayServer.log
-max_images_in_cache

Sets the maximum number of images to cache. Default is no limit.

Images used on display objects are stored in a cache to avoid reloading them on each display refresh. If an application uses many different large images, or if the image names change dynamically (e.g. because the image name property of an object is attached to a function) the image cache may use excessive memory. In such cases this option can be used to limit the cache's size to the most recently used images.

Note: Images loaded from RTView's Symbol Library (com/sl/gmsjmodels/symlib/*) are not counted toward the max_images_in_cache limit.

If max_images_in_cache is not specified or if a value of zero or less is specified, then no limit is set on the number of cached images.

Example:
-max_images_in_cache:100

-passclientlogin

Pass RTView login information into all data sources that have the Use Client Credentials option enabled.

Note: Some data sources do not support this feature. For information on Application Options for your data source, refer to the Data Sources section of this documentation.

Example:

-passclientlogin

-pngcompress

Specify a value between 1 and 9 to control the quality of .png images. If the value is 1, the Display Server will output the highest quality image with the lowest compression. If the value is 9, the Display Server will output the lowest quality image using the highest compression. Default is 9. A value of 3 is a good compromise between speed and quality.

If the -verbose option is specified at startup, image creation time/size for each display refresh will be shown in the Display Server console output.

Example:

-pngcompress:3

Note: The Display Server chooses an image format (.jpg or .png) for each display, depending on which format produces the smallest image size (in bytes). The size of .jpg images is controlled by the -imagequality option.

-processName

Specify to identify applications running as background processes. This option tags a unique identifier onto RTView server instances, enabling you to differentiate between multiple instances of those RTView applications. This option allows you to stop a particular instance without eliminating the other instances. If no process name is specified, the RTView application name is used as the process name.

For example,

run_builder-processName:XX

adds the following JVM option to the Java call:

-DPROCESS_NAME=XX

Where XX is the value you specified for the -processName argument.

Note: Values with spaces cannot be used for this option on Unix.

Example:

-processName:XX

-resizemode:(mode)

Globally controls object layout when a display window is resized. It is also possible to set a specific Resize Mode for each particular display (.rtv) file using the Background Properties dialog.

In the Display Builder, the selected Resize Mode is only applied to drill down windows. The main window of the Display Builder is always in Crop mode.

All three resize modes support zooming the display (right-click -> zoom). In both Scale and Layout modes if the window is resized while the display is zoomed, then the resize will further zoom the display.

Values:

crop - When the window is resized, the display stays the same size. If the window is bigger than the display, empty space will show around the display. If the window is smaller than the display, scrollbars will be added. The window is not forced to maintain its aspect ratio. This is the default for the Thin Client.

scale - When the window is resized, the display and all of the objects in it are scaled to fit the available space. The window is forced to maintain its aspect ratio. This is the default for the Display Builder and Display Viewer Application.

layout - When the window is resized, the display is resized to fit the available space. The objects in the display are positioned according to their anchor and dock properties. The window is not forced to maintain its aspect ratio.

Objects that are not docked or anchored will move relative to their offset from the top left corner of the display. For example, if the object is centered on the display, the object will move 50% of the resize amount. If the object is centered at 3/4 of the display, it will move 75% of the resize amount.

Example:

-resizemode:layout

-standby:warm

Run a backup Display Server without the overhead of maintaining the Alert and Cache data sources.

The following actions will be delayed until the backup server has become the primary:

• Loading definition files (i.e. Global, Alert, Cache)
• Preloading display files specified in initialization (.ini) files or on the command line

Note: Although the -standby:warm option reduces overhead because data sources do not provide data until a failover, it is important to note that Alert and Cache data definitions will not start collecting data until the first client connects. Therefore, any previous alert state or cached data from the primary server will not be available to the backup.

Example:

-standby:warm

-stylesheet:(filename)

Specify style sheet(s) to apply to all displays in your applications.

Note: Style sheets are applied at startup. If you edit a style sheet, then you need to restart.

Example:

-stylesheet:rtv_darkstyles.rts

When multiple style sheet (.rts) files are applied, they are processed in the order specified. Therefore if the same property is specified in multiple style sheets, the value in the last style sheet applied (e.g. stylesheet3.rts) will take precedence.

Example:

-stylesheet:stylesheet1.rts,stylesheet2.rts,stylesheet3.rts.

-sub:(substring:subvalue)

Add a substitution string/value pair. Multiple substitution pairs can be specified on the command line.

Note: Substitution strings cannot contain the following:

: | . tab space , ; = < > ' " & / \ { } [ ] ( )

If your substitution value contains single quotes, you must escape them using a /.

Example:

-sub:$1:myValue

-sub:$filter:Plant=/'SanFrancisco/'

-substracelim:(number of characters)

For requests from the Thin Client, limits the total number of characters for substitution name:value that the verbose output includes when listing substitutions. This argument prevents the Display Server log file from quickly filling with requests that have very long substitution strings. If no value is specified, the default, 1000, is used. A value of 0 specifies that no limit is applied to the substitutions listed by -verbose (as in previous releases). For example, the following limits the total number of characters for substitution

run_displayserver -xmlonly -verbose -substracelim:200

In the Display Server console, the messages indicate that the list of substitutions is truncated, for example:

2012-04-23 15:17:30.649 request:

get_image_map, name=test1 subs=$currentDisplay: test1.rtv

$celldata:0 col1:0;1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24;25;26;27;28;29;30;31;32;33;34;35;36;37;38;39;40;41;42;43;44;45;46;47;48;49;50;51;52;53;54;5 <truncated, 77666 more chars> panel=1c32a24bc56547cfb1d5d69fa60b4298, tid=20

Example:

-substracelim:200

-timezone

Set the default timezone for interpreting and displaying dates. Include a Java timezone ID or a custom ID, such as "GMT-8:00". Unrecognized IDs will be treated as GMT. See Timezone ID Values for more information.

If you run the RTView Builder with a valid timezone parameter and then save Application Options, the timezone information will be persisted.

To prevent the persisted timezone value from being used, pass "none" as the timezone ID.

Example:

-timezone:US/Eastern

-timezone:none

-u(milliseconds)

Set update rate in milliseconds. Default is 2000.

Example:

-u5000 (updates every 5 seconds)

-version

Prints the RTView application version information and exits immediately.

Example:

run_displayserver -version

Options Enabled with Alerts

In addition to the General Options, the following command line arguments are enabled with the Alert data source. See Alerts and Audit Alert Action for more information.

 

Name

Description

-actionauditdb:(database)

Specifies name of a database connection, as defined on the SQL tab, in which to store Audit Alert Action information.

Example:

-actionauditdb:ALERTBD

-actionaudittable:(table)

Specifies name of the table in the Alert Action Audit Database in which to store the Audit Alert Action information.

Example:

-actionaudittable:ACTION_AUDIT_TABLE

-alertcleartime:(number of seconds)

Specifies the rate, in seconds, to remove cleared alerts.

Example:

-alertcleartime:3

-alertds:alertdef:(filename)

Adds an alert definition file. Cannot specify substitutions. To specify substitutions, use the Application Options dialog.

Example:

-alertds:alertdef:myalerts.rtv

-alertds:enabled:(true or false)

Enables/disables all alerts in the active alert definition files.

Example:

-alertds:enabled:false

-alertds:history:(size of table)

Sets the number of rows that are stored in the AlertTable.

Example:

-alertds:history:1000

-alertinitdelay:(number of seconds)

Specifies the duration, in seconds, to wait after startup to begin executing alerts.

Example:

-alertinitdelay:5

-cleansettingstable:(true or false)

If true, delete entries from the Alert Settings Table for alert names that are not defined in RTView.

Note: This is done at startup after alert configuration files are processed and all of the alerts are loaded.

Example:

-cleansettingstable:true

-enableactionaudit:(true or false)

If true and configured, alert actions will be stored to the specified database table.

Example:

-enableactionaudit:true

-exitOnPersistInitFailed

Specifies what occurs when alert persistence is enabled but cannot be initialized due to a database problem or configuration issue. When false (the default setting), RTView initializes the alerts with persistence disabled. This is consistent with the behavior in releases previous to RTView 6.6.0 and Enterprise Monitor 2.2.0. When true, RTView exits after the persistence initialization has failed without initializing the alerts.

Example:

-exitOnPersistInitFailed:true

-ignorelutforcount:(true or false)

If true, the AlertTable Count column increments for an alert when new data is received even if the Last Update Time has not changed. This can cause invalid Counts for alerts attached to caches.

If false or not specified, the AlertTable Count column increments for an alert only if the Last Update Time has also updated. This is the default behavior.

Example:

-ignorelutforcount:true

-lutupdatesnewdata:(true or false)

Enables\disables updates to the AlertTable when New Data Only is selected and to the Alert Persistence database when the only columns that contain changes for that row are Last Update Time and Count.

By default, the Last Update Time and Count columns are not tracked by the Row Update Time column. To track the updates of the two columns in the Row Update Time column, use the -lutupdatesnewdata command line option. See Attach to Alert Data Dialog and Viewing Alerts for more information.

Example:

-lutupdatesnewdata:true

-multipleindexdelim:(string)

For alerts with multiple index columns, create a unique alert index by concatenating all of the index column values. Value can be any string, except the following:

• comma (,)
• semi-colon (;), or
• empty string.

Default is tilde (~).

Example:

-multipleindexdelim:~

-persistInitDelayTime:(number of seconds)

Specify the amount of time, in seconds, to delay a backup Data Server from reading the alert persistence database during a failover. The default is 5 seconds. Increase the amount of time if the persistence database is slow or if you expect a large number of alerts to change on each update period. Otherwise, there might not be enough time for the failing Data Server to write all the alerts to the database before the backup server reads them.

Note: Even with high availability configurations, there are cases in which some alerts might not be persisted. For example:

• The persistence database fails. In this case, alerts cannot be written to, or read from, the database. If a failover occurs while the database is down, the backup server will not be able to read persisted alerts from the database. This will also happen if persistence is configured to use a Persistence Data Server to access the database, and the Persistence Data Server is down during failover.
• The Alert Server is terminated in a non-orderly shutdown. Alerts are written out once per update period and once during orderly termination. If there is a non-orderly shutdown, some alerts might not be written to the database.

In cases where alerts are not persisted, the new primary Data Server generates new alerts if the data is still in an alert state. The new primary Data Server might also re-use ID's that were used by the failed Data Server.

Example:

-persistInitDelayTime:10

-purgepersistedalerts

Clears all alerts for the alert engine from the Alert Persistence database on startup and no persisted alerts will be loaded.

Note: If you are persisting alerts for more than one alert engine in the same database, alerts for other alert engines will not be removed.

-printssawarnings:(true or false)

If false, the Self Service Alerts warnings about extra unmapped thresholds will be suppressed.

Note: This option only applies to Self Service Alerts.

Example:

-printssawarnings:false