Configuration

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

1. For client applications, use the Viz Pilot Configuration Tool either during or after the Viz Pilot System Installation. See Configuring 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

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

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

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's 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 allows the use of a TNS alias. This is useful if the database setup is used by more than one application.

For more information see Database TNS Alias.

Initialization File and Environment Variable

An INI file and an environment variable allows the use of a TNS alias.

However, this could potentially affect the use of aliases for other database clients, see Database TNS Alias. 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.

Registry

Only Viz Pilot News can solely use database Registry Settings.

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 since in most cases the database host is not the same host as for the client applications.
     When using a tnsnames.ora file, use the TNS name (default: VIZRTDB).

The tnsnames.ora file

The tnsnames.ora file contains client side network configuration parameters and defines incoming database requests. The file also contains all service names and 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 is usually a shorter and more legible alias for the somewhat cumbersome service name.

A tnsnames.ora file must be created manually when using an Oracle Instant Client. 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.

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 required 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 briefly be unavailable. To avoid disconnect problems on clients, a configuration is required to ensure that clients attempt to reconnect long enough to succeed in reconnecting. This can be accomplished with a connect descriptor as shown in the code block below.

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

• Host: Preferably host, or an IP address

• Service name: Database service name (for example VIZRTDB.tvchannel.place)
  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.

The FAILOVER_MODE property directs the Oracle client to fail over the session and ignore any currently open cursors. The sub-parameters say that the client must use basic failover (not preconnect) and will retry 180 times waiting 5 seconds between each new attempt (15 minutes) on failover. This should provide enough time for the switch to occur.

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).

Registry Settings for TNS alias

The TNS_ADMIN string in the registry contains the path to the tnsnames.ora file. This allows all of the Viz Pilot system’s clients (Director, Template Wizard, Object Store and Viz Pilot News) to use the tnsnames.ora file, and avoids potential conflict 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, this can be done 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 as described below.

Set TNS_ADMIN as a local variable

Rather than using the Viz Pilot Configuration Tool, 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. See also how best to use the Initialization File and Environment Variable.

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.

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 only use the Runtime Client (if installed).

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 must use.

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