3 Install Oracle Clinical Database Components on UNIX

3.1.1 Create the oclsascr User Group for SAS

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. Create a user group named oclsascr by adding it to the /etc/group file.

2. The preferred method for group authentication is that all groups assigned to a user should become the user's default group at login. If this method is acceptable, link the /etc/logingroup file to the /etc/group file.

   • If the /etc/logingroup file does not exist, create it as a symbolic link to the /etc/group file; changes in the /etc/group file automatically reflect in the /etc/logingroup file.

     To create the symbolic link, enter these commands:

     % su root
     # cd /etc
     # ln -s /etc/group /etc/logingroup
     

   • If the /etc/logingroup file already exists with entries, or if it is unacceptable to link it to the /etc/group file, you must change both the contents of /etc/logingroup and /etc/group each time you add a user to the oclsascr group.

3.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. Make a shell for this user. For example, make the default shell:

   /bin/csh

2. Make the opapps account a member of these user groups:

   • oclsascr

   • oinstall

   • dba

   Neither oclsascr nor oinstall group needs to be the primary group for the opapps account.

3.2.1 Change Permissions for Running oraenv Script

With the Bourne shell, you use the Oracle environment-setting script (oraenv) when granting write access to the ORACLE_HOME directory.

However, the oraenv script gives an error if run by a non-Oracle user. To avoid this error:

1. Set the following directory and file permissions:

   drwxrwxr-x  18 oracle    oinstall  1024 Apr 11 19:11 inventory
   drwxrwxr-x   3 oracle    oinstall  1024 Apr 11 18:29 ContentsXML
   -rwxrwxrwx   1 oracle    oinstall   492 Apr 11 13:15 oraclehomeproperties.xml
   

3.2.2 Grant Access to the ORACLE_HOME Directory

Because the Oracle Clinical Installer checks if the ORACLE_HOME directory exists and if it has write access, you must change the access settings for this directory before you install Oracle Clinical.

To grant write access to the ORACLE_HOME directory and its contents:

1. Log in to the server as the oracle user.

2. Find the Oracle environment-setting script to define ORACLE_HOME:

   • For C shell, use coraenv.

   • For Bourne shell, use oraenv.

   These shells are located under your Oracle Database 12c Release 2 (12.1.0.2) installation.

   Note that the oraenv script gives an error if run by a non-Oracle user. To avoid this error, see Section 3.2.1, "Change Permissions for Running oraenv Script".

3. Grant group users modification access to all files in the ORACLE_HOME directory:

   chmod -R g+rw $ORACLE_HOME

   If you receive any warning messages, you can ignore them.

3.2.3 Set Permissions for the Oracle Inventory Directory

To set the permissions for the Oracle Inventory (oraInventory) directory:

1. Log in to the server as the oracle user.

2. Locate the path for the oraInventory directory. The location is defined in the inventory_loc parameter in the /var/opt/oracle/oraInst.loc file.

   For example, suppose you enter:

   more /var/opt/oracle/oraInst.loc

   The system might return the oraInventory location as:

   inventory_loc=/u01/app/oraInventory

3. Give recursive read and write permission for the oraInventory directory to the group:

   chmod -R g+rw /oraInventory_location

   For example:

   chmod -R g+rw /u01/app/oraInventory

   If you receive any warning messages, you can ignore them.

4. Modify protections on the oraInventory directory to ensure that the group you set up as the oinstall group has write access:

   chmod -R g+w oraInventory

   Use oinstall instead of dba because the dba group membership gives you access to databases, which is a security issue. The oinstall group gives you access to the Oracle Inventory.

3.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 12c Release 2 (12.1.0.2); for example:

   root:app/oracle/product/12102/dbname

2. If you are installing in a RAC installation, the names of all RAC nodes where the same product(s) should be installed.

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

   /pharm/home/opapps

4. Owner of Oracle Clinical Server Code must be opapps

5. Location for files oratab, tnsnames; for example:

   • /etc

   • $ORACLE_HOME/network/admin

6. RXC_USER: Choose directory for RXC_USER; Oracle recommends:

   /pharm/home/opapps

7. Oracle Wallet location and password. The Installer uses these to create the database Wallet in the location you specify. If you are upgrading, you can enter the existing location and password.

   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. Its credentials are created in this Wallet by the Installer.

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

3.3.2 Prepare to Install the Oracle Clinical Database Server Software

1. Log in to the database server as the opapps user.

2. Change the primary group of the opapps account to the group that owns the Oracle Inventory:

   Note:

   Make a note of the current group so that you can set it back after the installation.

   newgrp inst_group

   where inst_group is the name of the group that owns the Oracle Inventory. You specified the name during the Oracle Database installation. Typically, this user group is oinstall. See Section 3.1.2, "Create the opapps Account and Add It to Groups".

   This temporary change is necessary so that the Installer can update the Oracle Home.

3. Set the X Window display output to the IP address of your local computer. Use the standard format for IP addresses.

   For example:

   setenv DISPLAY 123.45.67.89

4. Locate the Oracle Clinical software in the directory in the staging area on the database server where you downloaded it; see Section 1.6, "Download the Software".

5. Open the ldflags file at root: app/oracle/product/12.1.0.2/lib and add the following flag:

   -lnnz12

3.3.3 Install the Oracle Clinical Database Server Software

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

2. In the staging area, locate the directory where you downloaded Oracle Clinical (see Section 1.6, "Download the Software") and extract the .zip file if you have not already done so.

3. Navigate to this location:

   server_code_platform\Disk1\install

4. Change protections on all files to 755:

   chmod 755 *

5. Run one of the following commands, depending on whether or nor you are using Oracle Real Application Cluster (RAC):

   • For a non-RAC installation:

     ./runInstaller
     

     Or, if the database server has multiple Oracle Homes, then enter:

     ./runInstaller -invPtrLoc ORACLE_HOME/oraInst.loc
     

     For example:

     ./runInstaller -invPtrLoc /u01/app/oracle/product/121010_qa/oraInst.loc
     

   • For a RAC installation:

     ./runInstaller -local
     

     Or, if the database server has multiple Oracle Homes, then enter:

     ./runInstaller -local -invPtrLoc ORACLE_HOME/oraInst.loc
     

     For example:

     ./runInstaller -invPtrLoc /u01/app/oracle/product/121010_qa/oraInst.loc
     

     This ensures that the installation is performed only on the local node.

   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.

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

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

8. You can review the progress of the installation:

   1. Open another terminal session as the opapps user.

   2. To review the relinking progress, run the following:

      tail -f $OPA_HOME/oc/52/relink_rxc.log

   3. Open the installActionstimestamp.log in the oraInventory/logs directory.

3.3.4 Save the Installation Information

1. Save the following information displayed in the Installer. You need it for several post-installation tasks.

   • Location of the OPA_HOME directory

   • Location of the OPA_HOME/bin directory

   • Name of the code environment

3.3.5 Review the Installation Log Files

1. Review the generated installation log files located at:

   $ORACLE_BASE/oraInventory/logs

   For example:

   /u01/app/oraInventory/logs

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

3.3.6 Oracle Clinical Database Server Directory Structure for UNIX

The Installer creates the following directory structure for an Oracle Clinical database server on UNIX:

OPA_HOME
      /bin
      /xmltemp
      /oc
         /52
            /bin      (Symbolic links to the executables)
            /common   (Common files)
            /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)
            /sec      (Security tools)
            /tools    (Miscellaneous tools)

3.3.7 Remove Group Privileges from this Session

Undo the temporary change you made in Section 3.3.2, "Prepare to Install the Oracle Clinical Database Server Software":

1. To reset the privileges for the opapps account, enter the following command:

   newgrp group

   where group is the name of your original primary group for the opapps account.

3.4.1 Complete the Setup of the opapps Account

1. Create the log directory for opapps in the following location:

   OPA_HOME/log

2. Define the environment variables for the opapps user:

   1. Open the .cshrc file. This file is located in the home directory after you log in as the opapps user. You can use the following command to view the hidden .cshrc file:

      ls -arlt

   2. Add the following lines to the .cshrc file:

      set path=( $path ORACLE_HOME/bin ORACLE_HOME/lib )

      setenv RXC_LOG OPA_HOME/log

      source OPA_HOME/bin/copa_setup_alias

      where:

      ORACLE_HOME is the directory where you installed Oracle Database 12c Release 2 (12.1.0.2).

      OPA_HOME is the directory where you installed Oracle Clinical database server.

   3. Source the .cshrc file when you finish editing it:

      source .cshrc

3.4.2 Limit Permissions on the XMLTEMP Folder

To reduce security risks, you should limit permissions on the XMLTEMP folder for all database server installations.

1. Log in as opapps.

2. Go to the OPA_HOME directory.

3. Enter:

   chmod 777 <XMLTEMP>

3.4.3 Review the opa_settings File

The Installer creates the opa_setting file and enters all necessary entries and default values for the Oracle Clinical environment.

1. Review the opa_settings file in the following directory:

   OPA_HOME/bin

2. Adjust the default values for the Oracle Clinical environment., if necessary.

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

3.4.4 Check for Oracle Clinical Databases on a UNIX Server

As part of the implementation of the PDR hyperlinks on superscripts, a new script post-processes DCI Form Version templates to insert hyperlink placeholders. This process can fail with error ORA-27369, when a database post-install step has not been completed. For example, for a database on HP-UX, refer to https://docs.oracle.com/cd/B28359_01/install.111/b32072/post_inst_task.htm#BJFEHEGG. You can also refer to My Oracle Support Article ID 391820.1, Scheduled Job Running Shell.

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

3.5.2 Check for an ORA-29548 Error

1. Log in to the UNIX server computer as the opapps user.

2. Set the UNIX environment:

   opa_setup database_name code_environment

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

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

   root: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:

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

3.5.4 Start Installing the Oracle Clinical Database

3.5.5 Remove Group Privileges from this Session

Recall that before you started this installation on UNIX, you changed the primary group of the opapps account to the group that owns the Oracle Inventory (see Section 3.5.4, "Start Installing the Oracle Clinical Database"). This temporary change was necessary so that the Installer could update the Oracle Inventory.

1. To reset the privileges for the opapps account, enter the following command:

   newgrp group

   where group is the name of your original primary group for the opapps account.

3.5.6 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_BASE/oraInventory/logs

   For example:

   /u01/app/oraInventory/logs

3.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';

3.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 UNIX server:

1. Log in to the UNIX server computer as the opapps user.

2. Set the UNIX environment:

   opa_setup database_name code_environment

3. Change to the RXC_INSTALL directory:

   cd $RXC_INSTALL

4. Connect to SQL*Plus as the rxc user:

   sqlplus rxc/password

5. Run the rxcdbinit.sql script:

   start rxcdbinit.sql

   The script pins the database packages and exits upon completion.

   Note:

   You must rerun this script each time you restart the database. Consider creating an entry in the database startup script that runs rxcdbinit.sql automatically.

3.6.3 Set Up Disconnected Replication (Optional)

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

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

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

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

3.7.3 Enable opapps to Use the at Command

To use the at command to schedule jobs on behalf of another user, the owner's user account must be listed in the at.allow file. The owner is opapps.

To edit the at.allow file:

1. Change to the appropriate directory location depending on your operating system and open the at.allow file:

   • Oracle Linux x86-64: /etc/at.allow

   • Oracle Solaris SPARC: /usr/lib/cron/at.allow

   • HP Itanium: /usr/lib/cron/at.allow

2. Add the following line to the at.allow file:

   opapps

3.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 on UNIX:

1. Log in as the opapps user. By default, the opapps uses the C shell.

2. Set up the environment:

   opa_setup <database_name> <code_environment>
   

   For example, where prod is the database name:

   opa_setup prod 52

3. Go to the PSUB location:

   cd $RXC_PSUB

4. Start the PSUB service:

   start_psub database_name code_environment wallet_alias

   For PSUB, wallet_alias is the same as the database name. For example:

   start_psub prod 52 prod

   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. By default it is the same as the database name.

5. If there are any errors, check the following log files in the $RXC_CENTRAL_LOG directory:

   • rxcpsd_instance_environment_1.log

   • rxcpsd_instance_environment_2.log

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

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