Viz Pilot User Guide

Version 8.0 | Published May 30, 2017 ©

Oracle Database

This section describes how to manually configure the Oracle database connection, it contains the following topics:

  • Oracle Database Configuration During Installation

  • Database Setup Options

  • Database Initialization File Configuration

  • Database Registry Settings

  • Database Service Names and SID

  • Database TNS Alias

  • Database Client

Oracle Database Configuration During Installation


The Oracle database needs to be configured in the following places:

  1. For client applications, use the Viz Pilot Configuration Tool, either during the Viz Pilot System Installation , or afterwards. See To configure the database connection.

  2. For the Pilot Data Server, use the installation interface during Pilot Data Server Installation.

  3. For the Media Sequencer, in Director go to Tools > Media Sequencer Configuration > Database Tab.

Workflow Options

Note: For existing installations with Oracle, we recommend that the Media Sequencer connects to Oracle directly.

In Viz Pilot 6.x and earlier, the Media Sequencer connected directly to Oracle for change notifications and to fetch Pilot data.

In Viz Pilot 7.x an alternative setup has been introduced. The Pilot Data Server now exposes all the data needed by the Media Sequencer through its REST interface. It also provides Change Notifications using the Stomp protocol. It is possible to configure the Media Sequencer to connect to the Pilot Data Server instead of the Pilot database.

Note: This setup requires Media Sequencer 4.0 or later.

Database Setup Options

There are several ways to configure the database connection settings. The following sections describe the configuration options for Director and Viz Pilot News. Configurations for Director also apply for Template Wizard and Object Store.

Initialization File

In this case, ContentPilot.ini is used by all the Viz Pilot system components, except Viz Pilot News, which uses registry settings.

Since it is possible to connect to the Viz Pilot database by only using an INI file, the tnsnames.ora file may be omitted.

If the database username and password is changed (default is PILOT/PILOT), they too must be set under the Database section of the ini file. See Database Initialization File Configuration below.

Initialization File and Registry

The combination of an initialization (INI) file and registry settings, allow the use of a TNS alias. This is helpful if the database setup is used by more than one application.

For more information see Database TNS Alias.

Initialization File and Environment Variable

As with the Initialization File and Registry combination, an INI file and an environment variable allows the use of a TNS alias.

However, this could potentially affect the use of Database TNS Alias es for other database clients. If more than one tnsnames.ora file is used, it is recommended that the files are merged when setting the TNS_ADMIN as an environment variable. If this is not desirable, add the TNS_ADMIN to the registry.


Only Viz Pilot News can use database Registry Settings alone.

Database Initialization File Configuration

To set the database properties for the INI file

  1. Start the Initialization File Editor.

  2. Select ContentPilot.ini, and click Open.

  3. Select the Database section and enter the following parameters:

    • login: database login string (PILOT)

    • pwd: database password string (PILOT)

    • utf8: Sets Director encoding for all database communication. Set Y (Yes) to use the recommended and default UTF-8 encoding, or N (No) to use the local Oracle client’s encoding setting.

    • nls_lang: define the NLS_LANG environment variable here.

    • name: database name (either the Database TNS Alias or the SID).
      The SID can be combined with a hostname //<hostname>/<SID>. This is useful because the database host is, in most cases, not the same host as for the client applications.
      When using a tnsnames.ora file, use the TNS name (default: VIZRTDB).

Database Registry Settings

If connection properties are entered during installation, all applications will have their Registry Settings already set for each application.

Database Service Names and SID

A SID is a unique name that uniquely identifies the database instance where as a service name is the Database TNS Alias that is given when users remotely connect to the database. The Service name is recorded in the tnsnames.ora file on the clients and it can be the same as the SID, and it can also be given any other name.

A service name is a feature in which a database can register itself with the listener. If a database is registered with a listener using a service name then the service name can be used as a parameter in the tnsnames.ora file. Otherwise a SID can be used in the tnsnames.ora file.

With Oracle Real Application Clusters (RAC) there will be different service names for each database instance.

Service name specifies one or more names for the database service to which this instance connects. It is possible to specify multiple service names in order to distinguish among different uses of the same database. It is also possible to use service names to identify a single service that is available from two different databases through the use of replication.

So, SID is a unique database system identifier while service name is an alias.

If the Viz Pilot system is running without a tnsnames.ora file all database connection parameters must be specified in the initialization (INI) file. Database configuration can be done during the Viz Pilot System Installation . Reconfiguration can now be done after installation by running the Viz Pilot Configuration Tool.

Note that Viz Pilot News does not use an INI file, hence the database connection parameters need to be applied during installation. These settings can be edited using the Viz Pilot Configuration Tool, or by manually editing registry settings (the latter is not recommended).

  • Local database: <SID>

  • Remote database: <hostname>/<SID>

  • Remote database: <hostname>/Service name

Database TNS Alias

Oracle’s Transparent Network Substrate (TNS) technology provides a network of applications above the existing networks of computers. Although TNS technology can be complex to setup, it is useful when more than one machine connects to a particular database, and makes switching over to another database instance more efficient. Switching can be done manually, or automatically as part of a standby database system.

The TNS technology is configured in a tnsnames.ora file, that can be placed locally, or in a centralized location to manage all of the Viz Pilot system’s database connections. It contains connection information for one or more databases.

In order to make use of TNS, a combination of the Viz Pilot system’s initialization file settings and registry settings are used.

This section contains the following topics:

  • The tnsnames.ora file

  • INI File Settings for TNS alias

  • Registry Settings for TNS alias

  • To set TNS_ADMIN as a local variable

The tnsnames.ora file

The tnsnames.ora file itself contains client side network configuration parameters, and defines incoming database requests. It contains all service names. This file also describes each domain name, with protocol, host, and port information.

A tnsnames.ora file maps TNS names to connect descriptors (usually ADDRESS and CONNECT_DATA). The TNS name usually becomes a shorter and more readable alias for the somewhat cumbersome service name.

Note: A tnsnames.ora file can contain more than one TNS name.

Note that when using an Oracle Instant Client a tnsnames.ora file needs to be created manually. Place the file in a directory with read access. For other Oracle clients, the default tnsnames.ora__file can be found in the Oracle client folder.

Example: C:\Oracle\product\10.1.0\Client_1\NETWORK\ADMIN \

A client needs a connect descriptor in order to connect to an Oracle instance. The tnsnames.ora file can define more than one database so that a backup database can be used in a fail situation. Oracle uses the normal TCP communication between the clients and the database.

  • Local database: <SID>

  • Remote database: \<hostname>\<SID>

  • Remote database: \<hostname>\Service name
    The example below uses two hosts. These settings are needed if the database server is set up with a standard Oracle failover mechanism. When failing over a standby solution (not Data Guard) both servers will for a short period of time be unavailable. To avoid disconnect problems on clients a configuration is needed to make sure clients try to reconnect long enough to get reconnected. This can be accomplished with a connect descriptor as shown below.

Note: Always check with the current Oracle documentation for current recommendations regarding failover setups.

Example of a tnsnames.ora file for a standby failover setup:

# Generated by Oracle configuration tools.
(ADDRESS = (PROTOCOL = TCP)(HOST = SomeHost1)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = SomeHost2)(PORT = 1521))
(RETRIES = 180)
(DELAY = 5)
  • Host: Preferably host, or an IP address

  • Service name: Database service name (e.g.
    The ADDRESS_LIST property lists the server addresses. When a server is in standby mode the database is not open and does not register the service name with the listener. This means that if the client tries to connect to the standby server it will be rejected and try the other server instead.

(ADDRESS = (PROTOCOL = TCP)(HOST = SomeHost1)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = SomeHost2)(PORT = 1521))

The FAILOVER_MODE property tells the Oracle client to fail over the session and ignore any currently open cursors. The sub-parameters say that it will use basic failover (not preconnect) and at failover time will retry 180 times waiting 5 seconds between each retry (15 minutes). This should be enough time for the switch to happen.


IMPORTANT! A failover situation will not be initiated until the user tries to access the database.

INI File Settings for TNS alias

The TNS alias name must be set in the name property under the Database section in the ContentPilot.ini file (see Database Initialization File Configuration).


IMPORTANT! In order for the TNS settings to work for Director, Template Wizard and Object Store, the name key must contain the same TNS name alias as in the tnsnames.ora file (e.g. VIZRTDB).

Registry Settings for TNS alias

The TNS_ADMIN string in the registry holds the path to the tnsnames.ora file. This allows all of the Viz Pilot system’s clients (that is, Director, Template Wizard, Object Store and Viz Pilot News) to use the tnsnames.ora file, and avoids potential conflicts with other applications using a local environment variable.

  • If you do not have any conflicting database connections there is no need to configure the TNS path. The standard environment variable TNS_ADMIN is the recommended option (this is the standard Oracle setup).

  • If you need to set a new/custom path, in cases where you are dependent on connections to two different databases, it can be added in the General tab of the Viz Pilot Configuration Tool, see To configure the database connection. This path is then added to registry and will only be used by the Viz Pilot components.
    An alternative option is To set TNS_ADMIN as a local variable, which is described below.

To set TNS_ADMIN as a local variable

An alternative to using the Viz Pilot Configuration Tool is to add a local Windows environment variable called TNS_ADMIN, with the same value as the config tool option. The difference is that the config tool will only affect the Viz Pilot system, while the environment variable will affect all applications on the machine using an Oracle client. Also see how to make best use of the Initialization File and Environment Variable.


Database Client

The Oracle Instant Client can be selected as one of the components to add when installing the Viz Pilot system. In this case, a separate installation of an Oracle client is not needed, and the database configuration for Viz Pilot News can be done during the installation. However this Oracle Instant Client is only recommended for use with Viz Pilot News, but not Director.

If Oracle’s Runtime Client is already installed, it is not necessary to install Oracle’s Instant Client.

Note: If Viz Pilot News is embedded in a Java-based newsroom system it is recommended to use Oracle’s Runtime Client.

By default all of the Viz Pilot system’s applications will use the Instant Client found under “...\vizrt\Common\Oracle”, so no registry entries are needed unless it is desirable to disable the use of the Instant Client and use a full Runtime Client.

Note: Media Sequencer must use the Oracle 11g Runtime Client.

The Instant Client does not create a tnsnames.ora file so a file must be created if it is to be used. In order to use a tnsnames.ora file, a registry entry or a system environment variable, called TNS_ADMIN, must be entered.

To use a tnsnames.ora file with Instant Client

  1. Open Registry

  2. Search for the registry key

    • Windows 32-bit: HKEY_LOCAL_MACHINE\SOFTWARE\\[vizrt]\viz|content pilot x.y

    • Windows 64-bit: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\\[vizrt]\viz|content pilot x.y

  3. Add the following string value to TNS_ADMIN

    • Windows 32-bit: %ProgramFiles%\vizrt\Common\Oracle

    • Windows 64-bit: %ProgramFiles(x86)%\vizrt\Common\Oracle

    • This sets the path to the location of the tnsnames.ora file.

To disable Instant Client and use Runtime Client

  1. Open Registry

  2. Search for the registry key

    • Windows 32-bit: HKEY_LOCAL_MACHINE\SOFTWARE\\[vizrt]\viz|content pilot x.y

    • Windows 64-bit: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\\[vizrt]\viz|content pilot x.y

  3. Add the integer value IGNORE_IC with 1 as parameter.

    • If set to 1 the application will ignore the Instant Client (if installed) and just use the Runtime Client (if installed).

To override the default Oracle client

  1. Open Registry

  2. Search for the registry key

    • Windows 32-bit: HKEY_LOCAL_MACHINE\SOFTWARE\\[vizrt]\ viz|content pilot x.y

    • Windows 64-bit: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ [vizrt]\viz|content pilot x.y

  3. Add the following string value ORACLE_HOME:

    • Windows 32-bit: %ProgramFiles%\vizrt\Common\Oracle

    • Windows 64-bit: %ProgramFiles(x86)%\vizrt\Common\Oracle

    • ORACLE_HOME will be added as an environment variable, and the Oracle client this path points to will be used.

  4. Add the following string value OCIDLL:

    • Windows 32-bit: %ProgramFiles%\vizrt\Common\Oracle\oci.dll

    • Windows 64-bit: %ProgramFiles(x86)%\vizrt\Common\Oracle\oci.dll

    • The OCIDLL string can be used to specify which library the application will use.

      IMPORTANT! An override should only be set if the Viz Pilot system requires a different version of the Oracle client than other programs residing on the same machine.