This section describes how to manually configure the Oracle database connection:

• Oracle Database#Oracle Database Configuration During Installation

• Oracle Database#Database Setup Options

• Oracle Database#Database Initialization File Configuration

• Oracle Database#Database Registry Settings

• Oracle Database#Database Service Names and SIDs

• Oracle Database#Database TNS Alias

• Oracle Database#Database Client

Oracle Database Configuration during Installation

Configuration

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

1. For client applications, use the Changing Settings either during or after the Viz Pilot System Installation. See Configuring the database connection.

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

3. For 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 Pilot Data Server exposes all the data needed by 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 Media Sequencer to connect to Pilot Data Server instead of the Pilot database.

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

Database Initialization File Configuration

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

Database Registry Settings

If connection properties are entered during installation, Registry Settings will already be set for each application.

Database Service Names and SIDs

An Oracle System ID (SID) is a name that uniquely identifies the database instance, whereas 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 client.  The same name can be used for both the service name and the SID, or any other name can be used.

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

Different service names are used for each database instance with Oracle Real Application Clusters (RAC).

A 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 between 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.

SID is a unique database system identifier while a 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 Changing Settings.

• 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 network of computers. Although TNS technology can be complex to set up, 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. The file 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 is used.

This section contains the following topics:

• The tnsnames.ora File

• INI File Settings for TNS Alias

• Registry Settings for TNS Alias

• Setting TNS_ADMIN as a Local Variable

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 Changing Settings, see configuring 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.

Setting TNS_ADMIN as a Local Variable

Rather than using the Changing Settings, 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.

Database Client

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

 It is not necessary to install Oracle’s Instant Client if Oracle’s Runtime Client is already installed.

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

Since the Instant Client does not create a tnsnames.ora file, 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.

Using a tnsnames.ora File with Instant Client

1. Open Registry

2. Search for the registry key

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

3. Add the following string value to TNS_ADMIN

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

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

Disabling Instant Client and using Runtime Client

1. Open Registry

2. Search for the registry key

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

Overriding the Default Oracle Client

1. Open Registry

2. Search for the registry key

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

3. Add the following string value ORACLE_HOME:

   • 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 64-bit: %ProgramFiles(x86)%\vizrt\Common\Oracle\oci.dll

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