4 Install Oracle Clinical Database Components on Windows

4.1.1 Create the oclsascr User Group

If you use SAS integrated with Oracle Clinical, you must create the oclsascr user group, which controls access to the files Oracle Clinical generates on the database server for SAS. These include SAS data extract files, which contain patient data.

1. Use Windows Administrative Tools to create a new Global Group in your Domain named oclsascr.

   See the Oracle Database 12.1.0.2 Installation Guide for Windows chapter "Configuring Users, Groups and Environments for Oracle Database" at http://docs.oracle.com/database/121/NTDBI/user_grps.htm#CIHCAABC.

4.1.2 Create the opapps Account and Add It to Groups

Create the opapps operating system account that owns Oracle Clinical. This account also has the privileges to run the parameterized submission (PSUB) service RXCPSDPS and the PSUB Launcher (PSLAUNCH). The opapps home directory on the database server, for example Drive:\opapps, is referred to as OPA_HOME in Oracle Clinical documentation.

1. Create the opapps operating system account.

2. Using Windows administrative tools, assign opapps to the following user groups:

   • ORA_DBA

   • ORA_ASMDBA

   • OCLSASCR

     Note:

     Beginning in Oracle Clinical 5.0, no other accounts need to be added to the oclsascr user group.

4.3.1 Gather Required Information

Have the following information ready to enter in the Installer:

1. Home Details: The ORACLE_HOME location, which is where you installed Oracle Database 12.1.0.2; for example:

   drive:\app\oracle\product\12.1.0.2\dbhome

2. OPA Home: The directory where Oracle Clinical will be installed. Oracle recommends:

   drive:\opapps

3. SAS View: The directory where Oracle Clinical will generate SAS views. Oracle recommends:

   drive:\opapps\sas_view

4. Oracle Wallet location and password. The Installer uses these to create the database Wallet in the location you specify. The database Wallet stores the password for two accounts:

   • The OCPSUB proxy account, which is used for database access for parameterized submission (PSUB) jobs. If your installation includes multiple databases using either replication or RAC, each database needs an OCPSUB account and its credentials are created in this Wallet on the database server during Oracle Clinical database installation.

   • The RXC_DISC_REP account. If you use disconnected replication you must insert credentials for this account manually. See Section 4.6.3, "Set Up Disconnected Replication (Optional)".

     Note:

     If you have already created a Wallet through a previous installation of Oracle Clinical 5.0 or higher, you can continue using it instead of creating a new one by entering the location and password for the existing Wallet.

4.3.2 Install the Oracle Clinical 5.2 Database Server for Windows

1. Log in to the server computer using the opapps account.

2. In the staging area, locate the directory where you downloaded and extracted Oracle Clinical (see Section 1.6, "Download the Software").

3. Run the following file as an administrator:

   Disk1\install\setup.exe

   The Installer opens to the Welcome screen.

   Note:

   See "Use the Silent Installer (Optional)" for instructions for running the Installer as a file with pre-entered parameter values.

   Note:

   Although there is a button for deinstalling products on the Welcome screen, Oracle does not support using the Installer to deinstall Oracle Clinical or Oracle Clinical Remote Data Capture (RDC) Onsite.

4. In the Select a Product to Install page, select OC Server for Windows 5.2.0.0.x.

5. Follow the instructions on the installation screens, providing the information you assembled in Section 4.3.1, "Gather Required Information".

4.3.3 Save the Installation Information

At the end of the installation, the installer screen displays the:

• Location of the OPA_HOME directory

• Location of the OPA_HOME\bin directory

• Name of the code environment

Make note of this information because you need it for several post-installation tasks.

4.3.4 Review the Installation Log Files

1. Review the generated installation log files located at:

   \Oracle\Inventory\logs

   For example:

   C:\Program Files\Oracle\Inventory\logs

Work with Oracle Support, if necessary, to resolve any errors.

4.3.5 Oracle Clinical Database Server Directory Structure for Windows

The Installer creates the following directory structure:

OPA_HOME
      \bin
      \xmltemp
      \oc
         \52
            \bin      (Executables)
            \dcd      (Data Collection Definition)
            \des      (Design)
            \dm       (Data Management)
            \dx       (Data Extract)
            \glib     (Global Library)
            \install  (Install and upgrade scripts)
            \log      (PSUB log files)
            \lr       (Lab Ranges)
            \patch    (Patches to Oracle Clinical)
            \pd       (Procedure Definition)
            \psub     (Parameterized Submission process)
            \release  (Server code release marker)
            \tools    (Miscellaneous tools)
  

Note that OPA_HOME refers to the root installation directory of Oracle Clinical, RDC, and TMS, which were formerly known as Oracle Pharmaceutical Applications (OPA). You specify the root installation directory when you install the Oracle Clinical database server. Oracle recommends drive:\opapps.

4.4.1 Limit Permissions on the XMLTEMP Folder

By default, a Windows installation grants read and write privileges to the XMLTEMP database folder to everyone. To reduce security risks, limit permissions on the XMLTEMP folder for all Windows database server installations.

1. Use Windows Explorer to locate the XMLTEMP folder in the OPA_HOME directory.

2. Right-click on the XMLTEMP folder, and then select Properties from the menu.

3. Click the Sharing tab, then click Advanced Sharing.

4. Select the Share this folder check box to enable sharing with other users on your network.

5. Click Permissions.

6. Give Read and Write (Change) permissions to user oracle.

7. Click OK to save your changes and close the Permissions dialog box.

8. Click OK to save your changes and close the Advanced Sharing dialog box.

9. Click Close to close the Properties dialog box.

4.4.2 Review the opa_settings.bat File

On Windows systems, configurations are defined in the opa_settings.bat file. This file contains the commands to set environment variables at startup and execution of the PSUB service.

1. Review the opa_settings.bat file in the following directory:

   Drive:opapps\bin

2. Adjust the default values, if necessary.

   See the Oracle Clinical Administrator's Guide for a list of the settings and for information about changing, adding, and verifying values.

4.5.1 Customize the Installation

Before you install database objects, you may want to modify some of the default SQL scripts used by the Installer.

• Edit the Tablespace Size Scripts: The Installer creates several new tablespaces with default sizes. To create larger databases, you can edit two scripts. The default value is an autoextend of 1MB and an unlimited maximum size.

  To create larger databases in Windows, edit the following scripts:

  OPA_HOME\oc\52\install\opadba2.sql

  OPA_HOME\oc\52\install\rxcdba2.sql

• Edit the User Account Creation Script: The Installer prompts to create accounts in this database. If you select Yes, the Installer runs a script that creates default guest accounts.

  Before running the Installer, edit the rxcdba4.sql script to customize the accounts that get created and their default settings:

  OPA_HOME/oc/52/install/rxcdba4.sql

  See the Oracle Clinical Administrator's Guide for more information about enrolling users.

• Create a Secret Store Directory

  Create a directory that is accessible to the opapps user and different from the Oracle Wallet location.

  Example location: /pharm/home/opapps/sec_store/db_name

  The Installer fails if this directory is not created before running the Installer.

4.5.2 Check for an ORA-29548 Error

1. Log in to the server computer.

2. Set environment variables:

   set p1=database_name
   set p2=52
   opa_setup
   

3. Connect to SQL*Plus as the SYS user:

   sqlplus sys/password
   

4. Run the following command to check for the ORA-29548 error:

   select dbms_java.get_jdk_version() from dual;
   

   If no error appears and the command retrieves the JDK version, skip to Section 4.5.3, "Gather Required Information".

   If you see the following error, continue with the next step to fix it:

   ERROR at line 1:
   ORA-29548: Java system class reported: release of classes.bin in the database
   does not match that of the oracle executable
   

5. To correct the ORA-29548 error, run the following script:

   start update_javavm_db.sql
   

4.5.3 Gather Required Information

Have the following information ready to enter in the Installer.

1. The ORACLE_HOME location, which is where you installed Oracle Database 12.1.0.2; for example:

   Drive:\app\oracle\product\12102

2. OPA Home: the directory where Oracle Clinical will be installed; Oracle recommends:

   /pharm/home/opapps

3. SAS View: the directory where Oracle Clinical will generate SAS views; Oracle recommends:

   • UNIX: $OPA_HOME/sas_view

   • Windows: %OPA_HOME%\sas_view

   Note:

   The upgrade installer does not prompt for this value.

4. Service name for the database to be installed

5. Know if you plan to use either Automatic Storage Management (ASM) or Real Application Clusters (RAC). This affects the Installer behavior for validating tablespaces.

6. Location for tablespace datafiles. You can change the default sizes by editing the script before running the Installer; see Section 4.5.1, "Customize the Installation".

7. Location and password for the Wallet created during Oracle Clinical database server installation to store credentials for OCPSUB and RXC_DISC_REP.

8. You will need to enter passwords for the following:

   • SYS

   • SYSTEM

   • RXC_MAA

   • RXC_PD

   • RXC_REP

   • RXC_DISC_REP

   • OPA

   • RXC

   • TMS

   • RXA_DES

   • RXA_LR

   • OCPSUB

   • RXA_WS

   • RDC_MIDTIER_PROXY

     Note:

     When you upgrade a database, the Installer does not prompt for the following passwords. For new installations, it does prompt for the following passwords.

   • RXA_READ

   • RXA_RAND

   • RXA_ACCESS

   • OPS$OPAPPS

     Note:

     For information on changing the passwords for these accounts on a regular basis to avoid expiration, see the Oracle Clinical Administrator's Guide.

9. A database seed number between 1 and 99. Each database in an Oracle Clinical installation (or group of databases that are replicating with each other) must have a unique seed starting number.

10. Database host name and port number

11. Global library code. There can be only one Global Library location. If you have only one database, this value should be the same as the database host name. If you are using Oracle Clinical replication and have multiple databases, enter the host name for the database designated as the Global Library location.

12. Location of the secret store folder you created in Create a Secret Store Directory.

4.5.4 Start Installing the Oracle Clinical Database

1. Log in to the server computer using the opapps account.

2. In the staging area, locate the directory where you downloaded and extracted Oracle Clinical (see Section 1.6, "Download the Software").

3. Run the following file as an administrator:

   Disk1\install\setup.exe

   The Installer opens to the Welcome screen.

   Note:

   See "Use the Silent Installer (Optional)" for instructions for running the Installer as a file with pre-entered parameter values.

   Note:

   Although there is a button for deinstalling products on the Welcome screen, Oracle does not support using the Installer to deinstall Oracle Clinical or Oracle Clinical Remote Data Capture (RDC) Onsite.

4. In the Select a Product to Install page, select OC Database Install 5.2.0.0.x.

5. Follow the instructions on the installation screens, providing the information you assembled in Section 4.5.3, "Gather Required Information".

4.5.5 Review the Installation Log Files

During the installation of an Oracle Health Sciences component, the Oracle Universal Installer generates a log file named installActions.log. Earlier files have a timestamp appended to the name.

1. Review the generated installation log files located at:

   \Oracle\Inventory\logs

   For example:

   C:\Program Files\Oracle\Inventory\logs

4.6.1 Set the Database Time Zone

The Oracle Clinical Remote Data Capture Onsite (RDC Onsite) application uses the dbtimezone value for internal calculations when the Display timestamps in local timezone preference is set.

Oracle recommends setting time zone to a named location rather than a numeric offset so that standard and daylight time adjustments are made automatically.

You can find valid named location strings in the V$TIMEZONE_NAMES view. For example, to find a time zone in the United States, enter the following query:

SELECT distinct tzname
  FROM V$TIMEZONE_NAMES
  WHERE tzname like 'US/%'

To set the time zone in the database:

1. Connect to the database as any user that has ALTER DATABASE privileges.

2. Enter the following command:

   alter database set time_zone='tzname_value';

   For example:

   alter database set time_zone='US/Eastern';

4.6.2 Pin Database Packages

To improve performance, some of Oracle Clinical's packages are pin-able packages. Pinning allocates a stable memory location so that a package cannot be subjected to being swapped out of memory. Oracle Clinical provides the rxcdbinit.sql script to pin the database packages.

To pin the database packages located on a Windows server:

1. Log in to the Windows server computer as an administrator.

2. Set the Windows environment:

   set p1=database

   set p2=52

   opa_setup

   where database is the name of this database instance, and 52 is the alias for the version of Oracle Clinical.

3. Change to the drive where Oracle Clincal is installed. For example:

   cd %RXC_INSTALL%

4. Start an SQL*Plus session, and connect to the database in the RXC account:

   sqlplus rxc/password

5. Run the rxcdbinit.sql script to pin the database packages:

   start rxcdbinit.sql

If you are continuing the installation, note that you perform the next task in this environment.

4.6.3 Set Up Disconnected Replication (Optional)

Do the following only if you plan to use disconnected replication.

4.6.4 Consider Implementing Partitioning

1. Partition the Oracle Clinical RESPONSES table, which contains all patient data entered for all studies in an Oracle Clinical installation.

   See the Oracle Clinical Administrator's Guide for more information.

4.7.1 Create Directories and Enter Values in OCL_STATE Local Reference Codelist

1. Create several directories on the PSUB server.

2. Enter paths of the new directories in the OCL_STATE local reference codelist, with a few related values.

   See the "Setting Up Batch Job File Viewing" section of the "Setting Up File and Image Viewing" chapter of the Oracle Clinical Administrator's Guide for more information.

4.7.2 Enable Users to Submit PSUB Jobs

Beginning in Release 5.0, PSUB users no longer need:

• their own OS account

• a user name beginning with OPS$

• their own directory for PSUB outputs

New Users 

To add new users:

1. Use the ocl_add_user.sql script, indicating which new users need to run PSUB jobs.

   See the Oracle Clinical Administrator's Guide for more information.

Existing Users 

If you are upgrading from a pre-5.0 version of Oracle Clinical, to give users who need to run PSUB jobs access to the opapps account:

1. Use the migration script oclupg50migrateusers.sql.

   See the Oracle Clinical Administrator's Guide for more information.

PSUB Administrator User  

You can give a user the role RXC_VWJOBS (new in 5.0) to allow him or her to:

• View all users' jobs

• View the output from those jobs.

• Stop any job.

The following scripts can grant this role to a user:

• ocl_add_user—Use this script for new users.

• ocl_grant_revoke_rxc_vwjobs.sql—Use this script for existing users. (This script can also be used to revoke the role.)

See the Oracle Clinical Administrator's Guide for more information.

4.7.3 Set Up Active Directory

If you are running PSUB on a Windows server that is a primary domain controller running Active Directory:

1. Add the PSUB account (typically opapps) to the domain.

2. Reassign the following domain user privileges to the PSUB account, through the domain controller security policy and the domain security policy:

   • Load and unload device drivers

   • Act as part of operating system

   • Increase Quotas

   • Log on as a Service

   • Replace a process-level token

4.7.4 Start the PSUB Service

The Installer automatically installs the PSUB service on the database server. You must start it using on set of instructions below.

Instructions for stopping PSUB manually are included in the Oracle Clinical Administrator's Guide.

To start the PSUB service manually on Windows:

1. Log in as opapps. (You set up the PSUB service to start as the opapps user, but in Windows you can start the service when logged on as another user.)

2. Set the PSUB service parameters:

   1. In the Start menu, navigate to Administrative Tools, then Services.

   2. From the list of services in the Services dialog box, double-click the name of the database for this service. It is in this form:

      PSUB Service database

   3. Enter values for the Log On parameters:

      database code_environment [verbose | noverbose] value-of-RXC_ROOT wallet_alias

      For example: prod 52 verbose c:\\opapps\\oc\\52 <wallet_alias>

      where prod is the connect string for the database instance to which the PSUB service connects;

      where 52 is the name of the code environment;

      where wallet_alias is the name of the Wallet specified during installation.

      Note:

      If your entry requires a backslash (\), you must enter two (\\). Alternatively, you can enter the path using single forward slashes, for example, c:/OPA_HOME/oc/52.

3. Click Start.

4. Exit from the Services dialog box.

5. Check the PSUB service log file in <RXC_ROOT>\log for any warning or error messages.

4.7.5 Customize the PSUB Service (Optional)

1. Customize the PSUB service as follows:

   • Automatic Startup — By default, the PSUB service does not start automatically when you restart a server computer. However, you can configure the PSUB service to start automatically.

   • Job Numbering — You can change Oracle Clinical's default job numbering algorithm.

For more information about managing and customizing the PSUB service, see the Oracle Clinical Administrator's Guide.

4.7.6 Test the PSUB Installation

To test your PSUB installation:

1. Open Oracle Clinical.

2. Submit a 3GL job such as Batch Validation or a PL/SQL job such as Study Unfreeze.

3. Verify that Oracle Clinical creates the log and output files by clicking on the View log and View output buttons.

If you encounter problems or errors, review the messages in the PSUB log files created in the following directory:

%RXC_ROOT%\log