Converting Documents For Use With IRCMD

The irgui.exe command line application is used to convert Windows Client documents into IRCMD Input Text File Format. This saves time and effort in producing the correct syntax for IRCMD usage. The document types that can be converted include;

  • Analysts,
  • Configurations,
  • Database Collections,
  • Database Summaries and
  • Thresholds.

The conversion process produces a text file with a .pcmd suffix that can then be run via the IRCMD utility. The irgui.exe command can be run from either a command line or it can be incorporated into a batch script.

Command Line Syntax

> irgui.exe -ircmd {<dirname> | <filename>} [-type <doctype>[, <doctype>]] -o <dirname> [-l <logfilename>] [-R]

The document conversion facility makes use of the following command line options:

Where:

-ircmd <dirname> | <filename>

Directory name and/or file name of the document(s) to be converted to IRCMD format.

-type <doctype>[,<doctype>]

Document type for -ircmd to convert. This can be one or more of; All, Threshold, Analyst, Configuration, DbCollect, DbInfo, DbSummary.

The default is All.

-o <dirname>

Directory name for -ircmd generated .pcmd files. This directory must already exist prior to running the command.

-l <logfilename>

Logfile name for -ircmd. The default is irgui_results.txt in the <Prognosis_Home>\User Interface folder.

-R

Optional. Only valid with a directory name. Include recursively all documents from the directory name specified.

Example:

C:\Prognosis\User Interface\irgui -ircmd Knowledge\IISAlerts.thr -o OutputFiles

Example Usage

An example of using the irgui.exe is to automate the deployment and auditing of Thresholds and Analysts on multiple servers, after having first created them in the Windows Client.

Both 'ircmd' and 'irgui -ircmd' can be called from a script, therefore making custom automated solutions easy to build. In addition, 'irgui -ircmd' runs locally and does not need to attach to a server.

Example:

An example of calling 'irgui -ircmd' from a script is as follows:

In the '<Prognosis_Home>\User Interface' folder create a .BAT file containing:

> mkdir out
> irgui -ircmd "Knowledge" -o OutputFiles -R
> echo %ERRORLEVEL%

Run the BAT file. This will convert all documents recursively in the 'Knowledge' folder and write the generated .pcmd files to a folder called 'out'. If there are documents with duplicate names within the document tree structure they will be renamed using '_1', '_2', etc in the output file.

After running this command, any file generation errors can be checked by opening the irgui_results.txt log file in a text editor.

ircmd can now be used to run the generated .pcmd files.

Because the 'irgui -ircmd' option runs offline, it will fail if run on a Windows Client that has never successfully connected to any Prognosis Server.

When irgui -ircmd is called from a batch script, it will return zero on success and non-zero on failure. This allows batch scripts to easily check for errors by scanning the program exit code, for example via the ERRORLEVEL environment variable. For further details of any errors encountered, the calling script can inspect the logfile (irgui -l option) which defaults to the file irgui_results.txt in the <Prognosis_Home>\User Interface folder.

Also irgui.exe has a different 'synchronizing' behavior when run directly (either from the command prompt or from the Windows Client) versus being run from a .BAT file. When run directly from a command line or the Windows Client, control is returned to the caller immediately. It is not possible to check the irgui exit code when control is returned because it has not exited yet. The only way to tell when it has finished is to see if the process is still alive or by inspecting the irgui_results.txt file (the last line should read 'irgui -ircmd completed successfully'). When run from a .BAT file, irgui does not return to the calling script until it has finished; the calling script can then check the irgui exit code and the irgui_results.txt log file to check for any errors.

Provide feedback on this article