First-Time Installation

Configuration of the Oracle

Before the connection to WinCC OA can be established, the Oracle database has to be configured correctly..

1. Create an empty file "RDB_config.sql" in the directory <WinCC_OA_InstallationPath>\data\RDBSetup\ora.
2. Copy the data from the "RDB_config_template.sql" file in the same directory into the empty "RDB_config.sql" file.
3. Replace the existing default values of the setup parameters by real values, if required. See Parameters for the Oracle DB Setup.
4. If the "use_java" setup parameter has been set to 'no', the archives are exported via the external DLL interface. The settings described in Exporting archives via an external DLL interface should be carried out.
5. If the "use_java" setup parameter has been set to 'yes', no additional settings are necessary since Java is Oracle standard and is embedded in the Standard and Enterprise Edition.
6. Set the number of database files (parameter "db_files" in the Oracle database), for example, to the value 10000 (db_files = 10000). This guarantees that the maximum number of database files will not be exceeded. The maximum value for the db_files parameter is 65000. Note in addition that you should determine the value once and not change it continuously.
7. Call the batch file (<WinCC_OA_InstallationPath>\data\RDBSetup\ora) using the command line for starting the setup:

   win_install.bat>Batch file for Windows or unix_install.sh>Batch file for Linux

The setup is started by calling the install batch file in the RDB setup directory of the version, and all the necessary settings for the configuration of the connection to the Oracle DB are entered. For security reasons, the passwords are not entered in the "RDB_config.sql" but requested interactive (the input is hidden).

If the RDB_config.sql file name contains an addition, use the addition also when calling the setup of the installation file. Otherwise both files are executed:

Example Windows:

Alternative name: RDB_config_Test.sql

win_install.bat _Test

This also applies to the RDB_config.sql file under Linux.

e.g. unix_install.sh_Test

Note this also when configuring a DRS system.

Note that you may only extend the name but not rename it!

To prevent password expiration, the default profile should be changed. Change the password lifetime as follows:

alter profile default limit password_life_time unlimited;

The batch file calls different SQL scripts depending on the answers given during the installation. If errors occur, the reasons are written into the ARC_LOG table. Parallel, the single installation steps are logged in the "RDB_setup.log" file. The log files are located in the RDB setup directory after the installation.

1. Set the following registry entry (or create if it does not exist):

   KeepAliveTime
   Key:
   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
   Value type: REG_DWORD // Time in milliseconds
   Range: 1 - 0xFFFFFFFF
   Default value: 7.200.000 //two hours

   This value should be set to 180000 (decimal), equals 3 minutes.

2. Perform a computer reboot afterwards.
3. Carry out the Oracle SQL*Net settingsin the tnsnames.ora file:

   Add the line "(ENABLE=BROKEN)" as shown below:

   TESTDB.etm-ag.com =
   (DESCRIPTION =
   (ENABLE=BROKEN)
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = TCP)(HOST = myhost)(PORT = 1521))
   )
   (CONNECT_DATA =
   (SERVICE_NAME = TESTDB)
   )
   )

4. When using Linux, the switching between two Oracle databases can take a relatively long time. To increase the performance the sysctl.conf must be changed. The file is located in /etc/sysctl.conf . The value for the entry net.ipv4.tcp_retries2 must be changed to the value 2. Afterwards the command "sysctl -p" must be called to apply the changes.
5. The following settings of the SQLNET parameters in the SQLNet.ora file can be considered if problems occur due to an instable network. In normal circumstances this parameters should not be used. Client:
   • SQLNET.RECV_TIMEOUT=150 : After an established connection, the oracle client will wait for 150 seconds for data. If the client receives nothing during this period, the connection is canceled.
   • SQLNET.SEND_TIMEOUT=150 : The oracle client does only try to send data during this period. If he isn't able to send, the connection is canceled.
   • SQLNET.OUTBOUND_CONNECT_TIMEOUT=10 : If no oracle net connection can be established during the declared period, the attempt to connect is canceled. The client gets an ORA-12170: TNS:Connect timeout occurred error.
   • TCP.CONNECT_TIMEOUT=20 (no default) : If no TCP connection can be established during the declared period, the attempt to connect is canceled. The client gets the following error: ORA-12170: TNS:Connect timeout occurred

     Without a correct value for this parameter, a client connection attempt could block the database server for the regulated default time.

   Server:
   • SQLNET.INBOUND_CONNECT_TIMEOUT=60 (Default) : If the client isn't able to establish a connection as well as a successful authentification, the database server is going to cancel the connection. The IP address of the client will be logged.

     Furthermore, the following error is dumped in the SQLNET.log file: ORA-12170: TNS:Connect timeout occurred

     The client gets the error ORA-12547: TNS:lost contact or ORA-12637: Packet receive failed

Configuration in WinCC OA

Once the Oracle database has been prepared for a link to WinCC OA, you must now also make the necessary settings in WinCC OA itself. On the one hand, the settings affect the managers used in the project - instead of the Value Archive Manager an RDB Archive Manager is used, which is reflected in the config file entries.

1. Create a WinCC OA project.
2. Open the WinCC OA Console with the project, without starting it.
3. Remove all per default existing Archive Managers from the manager list.
4. Insert a RDB Archive Manager with the option "-num 99" and the start mode "manually" between the Database Manager and the Event Manager. Currently, the only permissible manager number for the -num start-up option of the RDB Archive Manager is 99.

   

• In the [general] section set the following config entries: Activate the use of the relational database for data archiving by specifying the useRDBArchive = 1 config entry and specify which archive should be used by default via the config entry defaultArchive = 97
• Set also the useValueArchive config entry in the [general] section to 1 (see also Creating archives and setting parameters).

Internally the RDB manager uses the archive number 97 by default. In the console, however, the RDB manager is started with -num 99.

Use the config entry defaultArchive=99 when all empty _archive configs should be saved in the Oracle database. Empty archive configs are normally only available in an empty project. If the config entry defaultArchive=99 is used in the config file for HDB-RDB Parallel feature, the ValueArchive_0 must not be used. When the config entry "defaultArchive=99" is used, use ValueArchive_1 or higher for archiving.

• The following config entries have to be specified in the [ValueArchiveRDB]section:

  Parameter in [ValueArchiveRDB] section	Data type	Description
  DbUser = <name>	String	Name of the newly created WinCC OA application or schema user, as specified in the preceding configuration of the Oracle database, e.g. "operator". An application user can be created, if the user should only have the permission to access the Oracle tables.
  Db = <name>	String	Name of the database. This can be detected via the "tnsping" command from the client computer - as indicated in the preceding configuration under Connect Identifier, e.g. "ORAWERK1".
  DbPass = <password>	String	Defines the password, which must be used to access the database.

• Optionally, you can also specify whether to query values in the Oracle database with the aid of the RDB Archive Manager or directly by using special control add-ons.

  Querying via the RDB Archive Manager allows you to use the familiar CTRL commands such as dpGetPeriod().

  If you use the special CTRL add-ons, you must load these for the managers for which you want the RDB specific CTRL commands to be available.

  Optional parameters in the [ui] or [ctrl] sections	Data type	Description
  queryRDBdirect = 1	Bool	Indicates that queries will be direct.
  CtrlDLL = "CtrlRDBArchive" CtrlDLL = "CtrlRDBCompr"	String	Loads the two necessary control add-ons.

1. Start the WinCC OA Project with the RDB manager. Add the database password in the Configuration panel of the RDB archive manager.
   The RDB Archive Manager checks at startup whether the table schema version in the database is correct (Note: The version number of the database schema is not related to the WinCC OA version number). If the following error message is shown, the schema has to be upgraded:

    WCCOArdb (97), 2008.02.13
                           09:14:53.503, SYS, FATAL, 0, , DB Schema is<versionNumber>RDB
                           needs to have the Version<newVersionNumber>, Starting with the
                           wrong version! Upgrade to the required version! WCCOArdb (97), 2008.02.13
                           09:14:55.516, SYS, INFO, 39, Connection lost, Closing all connections to
                           (SYS: 1 Data -num 0 CONN: 1)

   Depending on the current version number of the database schema, one or several upgrade scripts (\data\RDBSetup\ora) have to be executed. Note that you have to specify the version as the first parameter.

   The upgrade script RDB_upgradeTo8.5.sql (\data\RDBSetup\ora\) contains all lower upgrade scripts. This means that if the current version of the Oracle schema is lower than 8.5, this has to be executed first and subsequently the current upgrade.

   The current schema version is 8.22.

   When upgrading from a schema version < 8.5 the parameter reset_cs must be set to "yes" in the RDB_config.sql.

   Under Linux use unix_upgrade instead of win_upgrade .

   Example 1

   If the current database version is less than 8.5, execute under Windows the following commands:

   win_upgrade 8.5

    win_upgrade <currentVersionNumber>

   As of the version 8.6, you only have to execute the current upgrade file.

2. Configure the archiving to a relational database by means of RDB standard panels (see Configuration of the RDB Archive Manager and Setting archive group parameters).
3. Execute a conversion of value archive configs to RDB archive configs. The conversion will be executed automatically after starting the "RDB Manager Selection" panel, in case that there are any data points that use the value archive. Confirm the conversion question in the dialog box with "Yes" (see Configuration of the RDB Archive Manager).
4. If the start of the RDB manager was successful, the start mode can be change in the WinCC OA Console from "manually" to "automatically".

Note that some data points for which you have activated the archive config earlier, but you did not assign an archive class explicitly, are automatically archived in the "EVENT" archive group. This applies, for example, to the _UI_X.UserName data points.

Exporting archives via an external DLL interface

If the option "use_java" (see further below) is not activated, the archives are exported via the external DLL PVSSOraExt.dll on Windows or PVSSOraExt.so on Linux. In this case some settings are necessary so that the communication with the external DLL works.

1. The DLL is located in the RDB setup directory under data/RDBSetup/ora. The DLL has to be copied to the Oracle bin directory (Windows) or to the lib directory (Linux) of the Oracle server! (e.g. ”D:\oracle\product\19.3.0.0\Db_1\BIN”). The DLL has to exist on each Oracle server instance at each possible Oracle configuration (RAC, Dataguard etc.). Copy it manually to the directory.
2. The external procedure calls (extproc) have to be configured in the "tnsnames.ora" and "listener.ora" files. Both files are located in the Oracle home directory under network/admin on the server.

   e.g. change in "tnsnames.ora":
   EXTPROC_CONNECTION_DATA =
   (DESCRIPTION =
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC))
   )
   (CONNECT_DATA =
   (SID = PLSExtProc)
   (PRESENTATION = RO)
   )
   )
   e.g. change in "listener.ora":
   SID_LIST_LISTENER_<YOURLISTENERNAME> =
   (SID_LIST =
   (SID_DESC =
   (SID_NAME = PLSExtProc)
   (ORACLE_HOME = <YOUR_ORACLE_HOME>)
   (PROGRAM = extproc)
   (ENVS = "EXTPROC_DLLS = <YOUR_ORACLE_HOME>/PVSSOraExt.so")
   )
   )
   <YOURORACLE_HOME>/PVSSOraExt.so
   Example:
   SID_LIST_LISTENER_19C
   (SID_LIST =
   (SID_DESC =
   (SID_NAME = PLSExtProc)
   (ORACLE_HOME = /u01/app/oracle/product/19.3.0.0/db1)
   (PROGRAM = extproc)
   (ENVS = "EXPROC_DLLS = /u01/app/oracle/product/19.3.0.0/db1/PVSSOraExt.so"
    )
    )
   LISTENER_MCC-DBS1 =
   (DESCRIPTION_LIST =
   (DESCRIPTION =
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = TCP)(HOST = mcc-dbs1vip)(PORT = 1521))
   )
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.41.53)(PORT = 1521))
   )
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.42.53)(PORT = 1521))
   )
   (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC))
   )
   )
   )

3. The required user permissions are not granted using the DLL interface, because they are not needed - unlike using the Java option. In case of a switch from extern procedure calls (extproc) to Java during an upgrade, the needed file permissions for the scheme user are not available. The permissions have to be granted subsequently by a database user. For information about the needed commands see "RDB_privileges" located in <WinCC_OA_installation_directory>\data\RDBSetup\ora).