Windows Services 2.8+

Running Omniscope Server as a Windows Service (2.8+)

New documentation: This page relates specifically to Omniscope version 2.8 b313 (end Sept 2012) and later.  If using Omniscope 2.6 or 2.7, or any build of 2.8 up to 312, see the older instructions [2].

Keeping Scheduler and Mobile Web Server running without login/logouts

If installed as a Windows Service, Omniscope Server/Publisher will start when your system starts, without a user account login required. This enables 'always-on' 24/7 services to remain running regardless of user account logins or logout.

Installation on Windows Vista, 7, 8, Server 2008 and  Server 2012

Per-user installation (2.8+)

On typical systems, this is the default option when installing Omniscope.  Omniscope will be installed to the user profile under "C:\Users\[username]\AppData\Local\Visokio Omniscope app", and will not be available to other accounts.  The same user account will be activated, and will also be used to run the service under.

1. Stop the Visokio Enterprise service if previously installed, using the Windows Services dialog (Start > Control Panel" then "System and Security > Administrative Tools > Services).
2. If you are upgrading from 2.8 b312 or earlier, delete "C:\Users\[username]\AppData\Local\Visokio Omniscope app\service\wrapper.conf" (but keep a copy if you have previously customised it).
3. Install Omniscope, customising and ensuring "Per-user" installation is chosen. If available, choose 64-bit.  No need to uninstall.
4. If you copied then deleted wrapper.conf in step 2, restore any advanced customisations to the newly installed file (we recommend using Beyond Compare 3), but you no longer need to customise memory allocation - this is now automatic.
5. Activate: If not already activated, start Omniscope and activate with your Server license key. Note that activation is unaffected by upgrades.
6. Install the service as follows
   • Browse to "Start menu > All programs > Accessories > Command Prompt"
   • Right click and choose "Run as administrator".  Approve any User Account Control dialog that may be shown.
   • Enter:
     cd "C:\Users\[username]\AppData\Local\Visokio Omniscope app\service"
     "Install Visokio Service.bat"
   • Check the command executed successfully.  If not, check you followed the above steps correctly, then get in touch [3].
7. Configure the Windows account for the service to run as:
   • Open Windows Services dialog > "Visokio Enterprise" > Properties > "Log on" tab
   • Select "This account" and enter name and password of the account that the Visokio service is going to run on. 
     This user must be the same account that has been installed and activated.
8. Start the service using the Windows Services dialog.
9. Schedule some tasks:
   • Browse to "Start menu > All programs > Visokio Omniscope" and choose "Scheduler".
   • This will open the scheduler interface where you can add and edits tasks. 
   • You can exit this and tasks will continue to run in the service.
10. Check the Scheduler log and make sure everything is working.
    • Scheduler configuration and logs are located in "C:\Users\[username]\scheduler" folder.
    • Alternatively, in the Scheduler window, click the link to view the log.
11. To uninstall the service:
    • Open command prompt as administrator (as in step 6)
    • Enter:
      cd "C:\Users\[username]\AppData\Local\Visokio Omniscope app\service"
      "Uninstall Visokio Service.bat"

System-wide installation

Follow the steps above.  But in this case, Omniscope is installed to "C:\Program Files (x86)\Visokio Omniscope" or "C:\Program Files\Visokio Omniscope". 

Regardless of installation location, activation is typically per-user.  You must ensure that the service is configured to run as a specific user account, and that same user account must be activated by logging in and entering the key into Omniscope Desktop.

Memory configuration (2.8+)

By default the service uses the same memory limit as the desktop app, which is 1100mb on a 32-bit system or approx. 75% installed memory on a 64-bit PC.

Advanced users can customise this to free up memory for multiple schedulers or to squeeze more RAM out of a server.

To edit the service memory configuration, open wrapper.conf in your Omniscope installation folder typically in "C:\Users\[username]\AppData\Local\Visokio Omniscope app\service" or "c:\ProgramFiles\Visokio Omnisope\service" and edit the line "wrapper.java.maxmemory", specifying a number in MB.  For example:

wrapper.java.maxmemory=1100            (32-bit limit)

or

wrapper.java.maxmemory=6000            (as recommended on an 8gb server running 64-bit)

32-bit vs 64-bit Mode

The Visokio service will by default run in the 32/64-bit mode as chosen when first installed.  By default this is 64-bit on a 64-bit PC and 32-bit on a 32-bit PC.  If you are upgrading an older version of Omniscope you will need to replace "wrapper.conf" as detailed above in the installation section, otherwise an old configuration will be used.

To switch between 32-bit and 64-bit, reinstall following the steps above and choosing the right option in the installer, being sure to replace "wrapper.conf" as detailed.

Troubleshooting

First steps

Make sure you're using 2.8 b313 or later and have followed the instructions above carefully.  See also Scheduler troubleshooting [4] and the flowchart PDF in this forum post [5]. 

Service will not install

If you try to install Visokio as a service on Vista, you will get a"OpenSCManager Failed - Access is Denied. (0x5)" error. On Vista, you need to log on as an administrator when you install the service, as detailed in the installation instructions above.

Service will not start

If your service will not start after it has been installed, please check that you have a clean installation of Omniscope with an updated "wrapper.conf" file as detailed above.  

Also make sure the service is configured to run under a user account which has access to the Omniscope installation folder.  Make sure the same account has been activated with your license key, and not another user account.

Repeat the installation steps carefully.  Get in touch on the forums [6] if you still cannot get the service to start.

"Out of memory" errors

If you get out of memory errors (in the scheduler or service log files, in the program folder), please check that you have a clean installation of Omniscope with an updated "wrapper.conf" file as detailed above.  

See above Memory configuration [7] section on how to increase memory and switch to 64-bit Java (if you are using a 64-bit machine).

You need to restart the service for the changes to take effect.

Files on network drives

Scheduler as a service is unable to access files on mapped network drive, because these drive mappings are only available to a desktop user session on Windows.

The way to get around this issue is by using full UNC paths (\\machine name\path) in your DataManager models and source/output paths.

Database drivers not working

See System-wide database driver location settings [8]. 

Scheduler Server task will not execute - Java errors in log

This usually means the "wrapper.conf" is old and applies to an older version of Omniscope.  Please check that you have a clean installation of Omniscope with an updated "wrapper.conf" file as detailed above.  

Administered Desktops

Installing Omniscopes throughout an organisation 

Installation for corporate-administered Windows machines/networks

To install Omniscope in a corporate administered network environment you may either install individually, or deploy (roll out) to multiple terminals from a central location. Once installed, you will then need to activate your installation(s) to increase functionality from the read/query/print-only free Viewer to the authoring Desktop (or Server) Editions. Omniscope licensing is on a per-account, not a per-machine basis. If you install using an Administrator account, you must activate using the User, rather than Administrative account. Installing to all accounts will result in all unactivated accounts having the free Viewer installed...usually a good thing.

Single User Windows installation

Download the full installer files

There is only one installer file for all Omniscope Editions. Download the full installer from here [11]

The full installers which are self-contained (include the latest Java PVM) and do not trigger further downloads.

Installation by an System Administrator

It is advisable for the Administrator to configure the appropriate proxy settings at installation, allowing Omniscope to activate and update itself online. This can be done from Settings > {Application-wide} Advanced > HTTP Proxy Settings. Another alternative is to deploy a plain-text properties file into the Visokio Omniscope program folder in Program Files. See Proxy Settings [12]for more information.

Activation from User account

Installations can be either unactivated Omniscope free Viewers (read/query/print-only of .IOK files), or an activated Omniscope Editions able to publish data sets as .IOM Workgroup or .IOK Professional files. If the user is intending to use only the free Viewer, then Omniscope doesn't need to be activated. However, if the user needs an authoring Edition of Omniscope, then the installation needs to be activated. Activation is by-account. Omniscope should be activated while logged in to the User account, not the Administrator account used for the installation. If another user logs in to a different account on the same machine, they will see the free Viewer only. When upgrading to a newer version, it is best to have all users refresh their activation from Omniscope:

Help > Licensing & Activation > [Refresh]

Multiple or 'Roll-out' installation

Omniscope can be deployed to multiple machines in an administered network environment using either a 3rd party application deployment management suite that will simulate the log-in of an administrator and execution of the offline installer executable, or using the silent installation option detailed below.

Roll-out Installation Options

Silent installation

Using the /S (capital "S") switch, the installer will run in silent mode. You can remotely execute the following command to install Omniscope without the usual sequence of interactive wizard steps. You may need to configure the installer to run in silent mode on next login.

 Z:/path/to/OmniscopeOfflineInstaller.exe /S

See Silent installation [13] for more information. 

Deployment without using the installer

It is also possible to roll out Omniscope without the installer.  Please contact [3] Visokio for further information.

Terminal Services

Installing Omniscope on remote machines 

Using Omniscope via Terminal services and Remote Desktop

Overview

This page explains how to install Omniscope on a server and use it through Windows Terminal Services (WTS). This page assumes you have a basic understanding of Windows operating system and WTS.

Tested environments

The environment used for validation were set up in the following ways:

• The WTS environment used Remote Desktop Client version 6.0.2448.0, with Windows Server 2000 Service Pack 4 and Windows Server 2003 Standard Edition.

• Client operating systems tested were Windows XP Professional Service Pack 1, Windows XP Professional Service Pack 2, and Windows 2000 Professional Service Pack 4.

• A user account was set up using a Microsoft Active Directory domain user group.

Note: The Anonymous User profile was not tested.

• The user account was set up on the server with a restricted Common User profile, with Read, Read and Execute, and List Folder Contents permissions. These permissions enable the user to operate the computer and save documents; the user cannot install programs or make changes to the system files or settings.

• The server machine was running Microsoft Office XP Professional and Standard with Service Pack 2, Internet Explorer 6.0, Visio versions 2002 and 2003, Netscape Navigator

Installing Omniscope

1. Download and fully-install the latest version by going to www.visokio.com/download [14].

2. Once downloaded, double-click the installer and follow the instructions.
   It is important that you choose "Install for all users" and not "Install for current user"

3. Follow the the rest of the installer instructions and when prompted click Finish to complete the installation.

4. Please note that Omniscope activation is on a per machine, per account basis. This means that each account intending to use Omniscope will need to be activated separately. If concurrent use of the same machine is aniticapted, please see the discussi9on of setting maximum RAM limits per account here [16].

Accessing Omniscope from WTS client

1. Choose Start > Programs > Accessories > Communication > Remote Desktop Connection.

2. In the Remote Desktop Connection dialog box, type the name of the server you want to access in the Computer Name box, or select a server name from the list.

3. Click Connect.

4. Log into the server.

5. Open Omniscope from the Terminal Services-based server.

Basic acceptance tests for Omniscope

Please refer to test scripts [17] for further information.

Removing Omniscope 

1. Choose Start > Settings > Control Panel > Add/Remove Programs.
2. Select Omniscope in the Add/Remove list, and then click Add/Remove.

Troubleshooting

Please contact us [3],or use our support forums.
[6]

Citrix Installation

Installing Omniscope on Citrix

Many do it.... 

Although Omniscope is not officially supported on Citrix, many clients have been deploying Omniscope via Citrix without issues. Omniscope is a standard Windows application, so it should be possible to install and use Omniscope in these environments.

Activation 

Activation on Citrix environment is the same as non-Citrix environment (per account).

Known Issues:

Omniscope won't start (Citrix 4.5)

On Citrix Presentation Server 4.5 for Windows Server 2003 (32- and 64-bit), you may find after installing Omniscope successfully that Omniscope won't start.  You may get an error message indicating "Could not create the Java virtual Machine". This message can be seen when launching using "launch_debug.exe" in the installation folder.

This is due to a problem with Citrix 4.5 for which a hotfix is available.

Please see http://support.citrix.com/article/CTX115868 [18] for the hotfix, which should resolve this issue.

If you are unable to apply the hotfix, you can try reducing the memory allocated to Omniscope [16] to below 580MB, although this will limit Omniscope's capability.

Install Config File

Using the Omniscope installconfig.properties file

Advanced installation options are available 

Omniscope installs an optional installconfig.properties file containing advanced settings.  Normally, you do not need to make any changes to this file.  It is used to customise installations in advanced ways or to add diagnostics or fault-finding settings.

Corporate administrators may wish to use this file to tailor their rollout of Omniscope, for example, to support a centralised Java VM. This file is also used to re-direct Omniscope to use 64-bit Java installs [19], and to specify customised settings [20] to be available to installed Omniscope users. This file may also be used to assist in diagnosing problems starting or using the software (see below).

Editing the file

The installconfig.properties file contains plain text, editable by Notepad.  It is located within the installation folder, in one of the following locations, depending on your operating system and installation options:

• C:\Users\YourName\AppData\Local\Visokio Omniscope app   (AppData is hidden, so you may need to reveal hidden files first in Explorer options)
• C:\Program Files (x86)\Visokio Omniscope
• C:\Program Files\Visokio Omniscope

Within the file, comments are prefixed with a space and # symbol. See the description of all available properties in the example file, below.  Uncommented properties must have no leading space nor #.

# This is the installation configuration file.
# This is used to configure initial startup of the application.
#
# All properties are optional, and if defined, each line must not contain redundant whitespace
# To enable/disable a property, remove/add the # sign (# means comment)

# This is an optional manually-specified Java VM installation folder.
# It should contain bin\javaw.exe, and should be Java version 5+
# JVM_DIR=C:\Program Files (x86)\Java\jdk1.5.0_14

# This is an optional manually-specified max memory cap for the Java VM, an integer specifying the
# megabytes to allow the JVM.  Must be at least 64.
# If unspecified, 75% of physical RAM will be used as the cap.
# MAX_MEMORY_MB=300

# Optional property specifying additional space-separated JVM options.  Default is blank.
# Example which enables "heap dump on out of memory", which generates files such as 
# "java_pid4972.hprof" in the program folder, for submitting to Visokio for analysis
# (requires Java 1.5.0_07+ or Java 6):
# ADDITIONAL_JVM_ARGS=-XX:+HeapDumpOnOutOfMemoryError

# Optional property which if true causes output to be redirected to
# "Visokio_output_log.txt" in My Documents
# LOG_TO_MY_DOCUMENTS=true

# Optional property which, if true, disables the default heap tuning parameters
# which at time of writing are -Xms64M -XX:MinHeapFreeRatio=20 -XX:MaxHeapFreeRatio=30
# DISABLE_DEFAULT_HEAP_OPTIONS=true

Changing Java used by Omniscope

Omniscope includes its own copy of Java, which has been selected to work correctly with Omniscope, and which means your system does not have any Java-related requirements. 

In rare cases when fault-finding, you may be asked to use a different version of Java. You can specify a specific version of Java to use with Omniscope by editing installconfig.properties file's JVM_DIR property. Uncomment (by removing "#" at the start, and removing any leading spaces) JVM_DIR, and then specify the location of the Java installation folder, such as "C:\Program Files (x86)\Java\jre6".

Adding JVM arguments

For advanced users, Java and Omniscope can be customised using JVM arguments.  The installconfig.properties file's ADDITIONAL_JVM_ARGS property should be uncommented (by removing "#" at the start, and removing any leading spaces), and the arguments added after the "=" sign with spaces between them, as seen in the examples below. 

Increasing the stack size

For example, if you experience a "stack overflow" error, after reporting the error to Visokio, you may be able to resolve the error by increasing your Java stack size, by including the installconfig property, adjusting the 2000 value upwards if necessary:

ADDITIONAL_JVM_ARGS=-Xss2000k 

Specifying Corporate Fonts  

If you are running on Windows go to C:\Windows\Fonts and copy all the fonts you want to make available from Omniscope to another folder such as C:\our_fonts. Now edit the installconfig.properties file as explained above. Add a command line option to specify which fonts are available by uncommenting (removing the space & hash) at the front of the  #ADDITIONAL_JVM_ARGS line and provide the following: -DinstalledFontLocation=c:\our_fonts (case sensitive). Below is an example of how the modified installconfig.properties line would look:

ADDITIONAL_JVM_ARGS=-DinstalledFontLocation=c:\our_fonts

Note:it is important that to copy rather than move your fonts from the C:\Windows\Fonts location. Also note that onlyTrue Type Fonts (with .TTF extension) files can be included.

Heap dump on out-of-memory

To enable this, only when advised, ensure the ADDITIONAL_JVM_ARGS line is uncommented and includes the option "-XX+:HeapDumpOnOutOfMemoryError". For example:

ADDITIONAL_JVM_ARGS=-XX:+HeapDumpOnOutOfMemoryError

This will cause a heap dump (*.hprof file) to be written to the install folder should you experience an out of memory situation. When this occurs, deliver this file to Visokio for diagnosis if you believe the error to be unwarranted. More information... [21]

Disable Free trial

You can disable free trial prompts on start-up and from the Help menu by following the steps below. If you are in a corporate environment it is recommended that you install Omniscope for all users, rather than for each individual user, otherwise you will need to carry the steps below by modifying each user account's installconfig.properties. 

Find this line in installconfig.properties 
#ADDITIONAL_JVM_ARGS=-XX:+HeapDumpOnOutOfMemoryError

Replace with the following line:
ADDITIONAL_JVM_ARGS=-DdisableFreeTrial=true

If you have ADDITIONAL_JVM_ARGS property already enabled, add to the end 
" -DdisableFreeTrial=true" 

Disable automatic update check

Find this line in installconfig.properties 
#ADDITIONAL_JVM_ARGS=-XX:+HeapDumpOnOutOfMemoryError

Replace with the following line:
ADDITIONAL_JVM_ARGS=-DCHECK_UPDATES_AUTOMATICALLY=false

If you have ADDITIONAL_JVM_ARGS property already enabled, add to the end 
" -DCHECK_UPDATES_AUTOMATICALLY=false"

Further information

See also:

• Generating a class load log [22] 
• Customising Omniscope memory allocation [16].
• System-wide database driver location settings [8]

Database driver locations

System-wide database driver location settings

Setting locations available to all users

When you first use a database connection, depending on the type of database, Omniscope may prompt you to download and locate the database JDBC driver. Omniscope tracks this location, so you don't need to enter it again.

However, if there are more than one user account running Omniscope on the same machine, then when running as a different user account, these settings won't be available and you or other users on the same machine will be prompted again on first use. This may be inconvenient if configuring a system for multiple user accounts, and can prevent a 'headless' Scheduler Server running as a Windows Service from working.

Configuring JDBC driver locations for all users (2.8 b1056+)

In the desktop application

Use this approach if you have multiple users launching Omniscope Desktop on the same system, and/or wish to push out a configuration centrally to many PCs.

1. Open configuration file: [path to Omniscope installation]\installconfig.properties [23].  You may need to run your text editor as Administrator.
   
   
2. Add/uncomment the ADDITIONAL_JVM_ARGS line so it looks like this:
   ADDITIONAL_JVM_ARGS=-DpropName="propValue" -Dprop2Name="prop2Value" -Dprop3Name="prop3Value"
   (etc. - see properties, below)
   
   For example:
   ADDITIONAL_JVM_ARGS=-DOracleThinDriverSearch_jarFile="C:\Oracle\product\11.2.0\Db_1\jdbc\lib\ojdbc5.jar"

In the Windows Service 

Use this approach if you're using the Windows Service to run the Omniscope Scheduler/Mobile Web Server without a logon session.

1. Open configuration file: [path to Omniscope installation]\service\wrapper.conf [9].  You may need to run your text editor as Administrator.
2. Find the "wrapper.java.additional.n" section, and add additional lines like this:
   wrapper.java.additional.2=-DpropName="propValue"
   wrapper.java.additional.3=-Dprop2Name="prop2Value"
   wrapper.java.additional.4=-Dprop3Name="prop3Value"
   (etc. - see properties, below)
   
   For example:
   wrapper.java.additional.2=-DOracleThinDriverSearch_jarFile="C:\Oracle\product\11.2.0\Db_1\jdbc\lib\ojdbc5.jar"
   
   

Properties

Class Load Logs

Generating a Class Load Log

1. Install Omniscope 2.2-pre b71 or later.
2. Edit C:\Program Files\Visokio Omniscope\installconfig.properties.(documented fully here [23])
3. Edit/Add the following properties (ensure that these properties do not appear elsewhere in the file unless they are preceded by "#"):
   
   ADDITIONAL_JVM_ARGS=-verbose:class -DtickLogEvery=500
   LOG_TO_MY_DOCUMENTS=true
   
4. Start Omniscope
5. Close Omniscope (and/or dismiss any dialogs, and close any console windows that may remain open)
6. Email the file Visokio_output_log.txt (saved in your My Documents folder) to support AT Visokio.com
7. Remove the changes you made in step 3