6 Administrative Tasks

Troubleshoot the Installation

The installation script creates a log file on the server. Examine the log file even if the installation reports success. Search the log file for ERROR.

If you cannot resolve the problems, request help from Oracle Support or from the Oracle R Enterprise discussion forum.

Oracle R Enterprise Users

You must create at least one user for Oracle R Enterprise. Follow these steps to create a user for Oracle R Enterprise:

1. Create a User

2. Add any Required GRANTs

grant EXECUTE on rqsys.rqGroupEvalImpl to rquser;

Configure Oracle Wallet (Optional)

Oracle Wallet provides secure storage of user passwords and client certificates. An Oracle Wallet provides a secure way for embedded R scripts to avoid storing passwords in the script.

Follow these steps to configure Oracle Wallet with Oracle R Enterprise:

1. Configure Oracle Wallet and store the username and password. For information, see the discussions of Oracle Wallet in Oracle Database Security Guide.

2. Add the connection string used to create the wallet entry (for example, "mydb112_test") to map to the DB instance connection string in tnsnames.ora (Change the host name to be your database machine name and SID to be the SID of your database.):

   mydb112_test =
         (DESCRIPTION =
            (ADDRESS =
               (PROTOCOL = TCP)
               (HOST = <host_name>)
               (PORT = 1521)
            )
            (CONNECT_DATA = (sid=<SID>))
         )
   

   After you complete the steps, you can just use the connect string to connect to the database:

    ore.connect(conn_string = "mydb112_test", all = TRUE)
   

   For more information about connecting using Oracle Wallet, see the R help for ore.connect().

Start Oracle R Enterprise Client

After you have installed a server and a client, follow these directions to start the client:

• Start Oracle R Enterprise Client on Microsoft Windows

• Start Oracle R Enterprise Client on Linux, Solaris, or AIX

# Load ORE packages and dependencies
# DBI, ROracle, OREbase, MASS, OREstats,
# OREgraphics, OREeda, ORExml, ORE
library(ORE)
 
# Connect to Oracle RDBMS
# Change the connection information below
ore.connect(user = "<USERNAME>",
            sid = "<SID>",
            host = "<HOST>",
            password = "<PASSWORD>",
            port = PORTNUMBER, 
            all = TRUE)

ore.is.connected()

ore.connect(conn_string = "ore_wallet", all = TRUE)

# Load ORE packages and dependencies
# DBI, ROracle, OREbase, MASS, OREstats,
# OREgraphics, OREeda, ORExml, ORE
library(ORE)
 
# Connect to Oracle RDBMS
# Change the connection information below
ore.connect(user = "<USERNAME>",
            sid = "<SID>",
            host = "<HOST>",
            password = "<PASSWORD>",
            port = PORTNUMBER
            all = TRUE)
 

ore.connect(conn_string = "ore_wallet", all = TRUE)

Connect to an Oracle Database

Oracle R Enterprise includes the following R functions that enable transparent access to Oracle Database tables and views:

• ore.connect(user = "", sid = "", host = "localhost", password = "", port = 1521, service_name = NULL, conn_string = NULL,all = FALSE, type = c("ORACLE", "HIVE")) establishes a connection to an Oracle R Enterprise server running on an ORE database.

  The call ore.connect() must precede all other calls to ORE functionality (except ore.is.connected()). There can only be one active ORE connection.

  An ORE session can optionally end with a call to function ore.disconnect(). An ORE session is implicitly terminated when the R session ends.

  To connect to an Oracle Database, specify user, sid, host, password, and port. conn_string is specified if you set up Oracle Wallet as described in Configure Oracle Wallet (Optional).

  Calling ore.connect() when an active ORE connection already exists results in disconnecting the active session prior to starting a new session.

  If ore.is.connected() returns TRUE, an active connection exists.

• ore.attach(schema, pos = 2, warn.conflicts = TRUE) attaches The named ORE schema's R environment to the R search path. When attached to the R search path, the ORE objects can be accessed by directly by name.

  If you don't specify schema, the default schema, the one used to connect to the ORE database, is used.

  By default the ORE database is attached in position 2 in the R search path, immediately after the user's workspace and before all previously attached packages and environment. The pos argument can be used to attach the ORE schema at a different location in the search path, but it cannot be attached at pos = 1.

  If you use the all parameter of ore.connect when you attach to a database, ore.attach is executed automatically.

  Use ore.detach(schema) to detach from schema.

• ore.sync(schema, table, use.keys = TRUE) synchronizes ore.frame objects, representing database tables and views, in the ORE schema environment, on a per schema basis.

  Oracle R Enterprise creates proxy objects in R that correspond to the tables or views in the database schema. These proxy objects contain metadata used by Oracle R Enterprise internally to provide transparency layer functionality.By default, ore.sync() uses the schema given in ore.connect(). The schema argument can be used to select a different schema to which the user has the appropriate access privileges.If table is not specified in an ore.sync function call, all tables and views whose name do not contain $ or begin with SYS_ are selected. Select all tables in a database schema can be expensive and so the recommended practice is to use table to limit the number of tables and views represented in the ORE schema environment.

• ore.ls(schema, all.names = FALSE, pattern) lists all objects in the specified schema with names that match the regular expression pattern. all.names = FALSE lists names that do not start with . (period), such as internal functions or objects.

  ore.ls() returns the objects available in the current ORE schema environment.

Objects created by Oracle R Enterprise are identified with the ore prefix. Pick any object returned by ore.ls() and type either class(OBJECTNAME) or class(OBJECTNAME$COLUMN_NAME).

For example,

R> class(NARROW)
[1] "ore.frame"
attr(,"package")
[1] "OREbase"

The prefix ore is applied to the class names. This indicates that the object is an Oracle R Enterprise created object that holds metadata (instead of contents) of the corresponding object in Oracle Database.

Validate Oracle R Enterprise Installation

The purpose of validation is to ensure that you can connect to the database that has now been enabled with Oracle R Enterprise from R and successfully useOracle R Enterprise.

The exact same steps validate a server installation or a client installation.

After you complete the installation, follow these steps to validate it:

1. On the Oracle R Enterprise server, you must set .libPaths() to specify the library trees that R knows about and, hence, uses when looking for packages.

   The R packages are in $ORACLE_HOME/R/library.

   To set .libPaths(), start R and then execute this command on the server only:

   R> .libPaths(<path/to/$ORACLE_HOME/R/library>)
   

   After this command executes, you can start the ORE library.

2. Start R on a client. Load the Oracle R Enterprise Packages:

   R> ORE
   

3. Connect to Oracle Database on the server. The exact command depends the details for the database to which you connect:

   R> ore.connect(user = "rquser", sid = "orcl", host = "localhost", password = "rquser", port = 1521, all = TRUE)
   

   In this command provide the values for user, sid, host, password, and port that are correct for your database. If you did not install the database, you may have to ask the DBA for these values.

   Alternatively if the database is on the same machine, use ore.connect in this way.

   ore.connect("scott", password="tiger", conn_string="", all=TRUE)
   

4. Run several Oracle R Enterprise demos. This command provides a list of available demos:

   R> demo(package = "ORE")
   

   These commands illustrate how to run specific demos:

   # Test the transparency layer
   R> demo("aggregate", package = "ORE")
   
   # Test embedded R:
   R> demo("row_apply", package = "ORE")
   

Control Memory Used by Embedded R

As system administrator, you can control the memory resources between R and other processes running on system. For example, a properly-set minimum memory bound allows R to have enough memory to run in a reasonable amount of time while a properly-set maximum number prevents R from holding too much memory unnecessarily or starving other processes.

This feature limits the amount of R heap memory (vector and cons in R's terminology) that is automatically managed by R's gc mechanism. The C-type memory that may be allocated via call Calloc, Realloc, calloc, and malloc is not controlled by this feature. Such C-type memory is mainly created to hold intermediate or temporary values for completing computation in an R function implemented in C. The C-type memory that may be allocated and released explicitly by function is not controlled by this feature. Under normal circumstances, the amount of such memory is usually of limited size and does not affect memory usage of R significantly.

Oracle R Enterprise 1.3 and 1.3.1 allow a DBA to control R memory usage by specifying minimum vector heap, maximum vector heap, minimum cons cells, and maximum cons cells using the sys.rqconfigset SQL procedure.

Use these commands to set minimum vector heap, maximum vector heap, minimum cons cells, and maximum cons cells

• sys.rqconfigset('MIN_VSIZE', '20M') sets minimum R vector heap memory to 20MB; default is 32MB

• sys.rqconfigset('MAX_VSIZE', '100M') sets maximum R vector heap memory to 100MB,;default is 4GB

• sys.rqconfigset('MIN_NSIZE', '500K') sets minimum number of R cons cells to 500x1024,; default is 1M

• sys.rqconfigset('MAX_NSIZE', '10M')sets maximum number of R cons cells to 10x1024x1024; default is 20M

To set maximum vector heap memory and maximum cons cells to no limits,

exec sys.rqconfigset('MAX_VSIZE', NULL); exec sys.rqconfigset('MAX_NSIZE', NULL)

Upgrade Oracle R Enterprise

You can upgrade from any version of Oracle R Enterprise to the current version by reinstalling the product.

If you installed an earlier version of Oracle R Enterprise, you can upgrade to this release as follows:

• To upgrade the Client, re-install the packages. See Install Client on Microsoft Windows or Install Client on Linux. You do not have to uninstall the client packages before you re-install.

• To upgrade the Server, follow the steps in Install Server. When install.sh detects a previous version of Oracle R Enterprise, it asks if upgrade is needed. Answering No aborts the process; answering Yes starts the upgrade.

  Follow all of the upgrade steps, including the installation of Oracle R Enterprise Client Supporting Packages.

Uninstall Oracle R Enterprise

You uninstall Oracle R Enterprise Client by removing the packages, as described in Uninstall Oracle R Enterprise Client.

You uninstall Oracle R Enterprise Server by running a script, as described in Uninstall Oracle R Enterprise Server.

You uninstall R or Oracle R Distribution as described in Uninstall R.

remove.packages("ORE")
remove.packages("ORExml")
remove.packages("OREeda")
remove.packages("OREgraphics")
remove.packages("OREstats")
remove.packages("OREbase")
remove.packages("ROracle")
remove.packages("DBI")
remove.packages("png")
remove.packages("OREdm")
remove.packages("OREpredict")

$ su # installp -u ORD                    # uninstall all filesets

# installp -u ORD.devel                  # uninstall only ORD.devel
# installp -u ORD.core                   # uninstall only ORD.core