Installing and Configuring the BI Beans Catalog

The BI Beans Catalog enables end users to save and share analyses. Before installing the Catalog, you must ensure that the prerequisites have been met, as described in the section Before You Begin. You can then install and configure the BI Beans Catalog in either of the following two ways:

1. Simple installation - Use this option when you have no specific need to control the default name of the BI Beans Catalog owner or the tablespaces where the schema objects are installed.

2. Advanced installation - Use this option if you wish to have full control over all aspects of the installation, including the ability to specify your own tablespaces, the user name of the Catalog owner, and so on. Oracle Corporation recommends this option for production systems. The installation should be performed by a database administrator.

Before You Begin

• The installation procedures in this topic assume that you have already installed the Oracle9i database for the BI Beans Catalog. You can use either Oracle9i Release 1 or Oracle9i Release 2 for your BI Beans Catalog. Oracle8i is no longer supported.

• You must ensure that Oracle9i client and JDK 1.3.1-b24 (or higher) are installed on your local machine (the machine where JDeveloper and BI Beans are installed). The BI Beans Catalog is certified against JDK 1.3.1-b24, but can also be used with JDK 1.4.

• If you have an existing Catalog, then you must complete the following steps:

  1. If your Catalog is implemented with Oracle8i (8.1.7), then you must upgrade to Oracle9i, either Release 1 or Release 2.

  2. Upgrade the Catalog, as described in the section "Migrating BI Beans Projects from Version 9.0.2 to 9.0.3" in the BI Beans installation guide for release 9.0.3.

     Note: If you are moving the Catalog to a new instance of the database, you must follow the steps in Moving the Catalog to a New Database Instance.

Option 1 - Simple Installation

1. On your local machine, open a command prompt at Oracle_home/bibeans/bin where Oracle_home is the directory where JDeveloper is installed. When you installed BI Beans, you made this directory an Oracle Home.

2. Set the environment variable JDEV_ORACLE_HOME to the Oracle Home directory.

3. Ensure that the environment variable JAVA_HOME is set to the directory where the JDK is installed.

4. Ensure that sqlplus is included in the PATH variable.

5. Run Oracle_home\bibeans\bin\bi_installcatauto.bat on Windows or Oracle_home/bibeans/bin/bi_installcatauto.csh on Unix as follows:

   bi_installcatauto host_name port_id sid

   Where host_name is the name of the host machine, port_id is the port identifier, and sid is the identifier of the database instance. For example :

   bi_installcatauto sun-server 1521 orcl

6. When prompted, enter the password for the user SYSTEM. (If you do not know the password, then ask your DBA.) When you see a warning that the BI Beans Catalog is about to be overwritten, press Y to continue. The script creates a user named BIBCAT, with default tablespace USERS, and temporary tablespace TEMP.

   Note: BIBCAT is an application user, as well as the Catalog schema owner. The user name is case sensitive. Application user names are used when running the BI Beans Catalog Explorer. You should also make note of the user name now, because you will need it later when you are developing applications with JDeveloper.

7. As the script runs, error messages are written to the console. Some error messages occur when database objects that do not exist are dropped; you can ignore such messages. However, if there are other error messages, then review the errors and take appropriate action.
   

Option 2 - Advanced Installation

Follow these steps to install the BI Beans Catalog:

1. Create an Oracle user to own the Catalog schema.

2. Install the Catalog into the schema using the scripts that are provided.

To create an Oracle user that will own the Catalog schema:

Create a database user to own the BI Catalog schema objects and assign the appropriate credentials. You can do this with Oracle Enterprise Manager or you can enter SQL commands (such as those shown below) using SQL*Plus®, iSQL*Plus™, or another editor. SQL*Plus is installed with Oracle9i client.

create user BIBCAT identified by BIBCAT default tablespace USERS temporary tablespace TEMP;
grant resource, connect to BIBCAT;

Note: In this example, BIBCAT is an application user, as well as the Catalog schema owner, and uses the workspaces USERS and TEMP. The user ID is case sensitive. Application user names are used when running the BI Beans Catalog Explorer. You should also make note of the user name now, because you will need it later when you are developing applications with JDeveloper.

To install the Catalog into the schema:

1. (Optional) By default, all objects are installed into the USERS tablespace. If you want to, you can use Oracle Enterprise Manager to create the tablespaces to hold the BI Catalog schema objects, using the names listed in the following table:

   Tablespace	Name
   catalog system	BIBCATSYS
   catalog index	BIBCATIDX
   catalog attributes	BIBCATATT
   catalog clob	BIBCATCLOB

   For the remaining Tablespace names (Type: Permanent; Status: Online; Storage: Automatic Allocation), simply accept the defaults.

2. On the local machine, open a command prompt at Oracle_home/bibeans/bin where Oracle_home is the directory where JDeveloper is installed. When you installed BI Beans, you made this directory an Oracle Home.

3. Set the environment variable JDEV_ORACLE_HOME to the Oracle Home directory.

4. Ensure that the environment variable JAVA_HOME is set to the directory where the JDK is installed.

5. Run the installation script (Oracle_home\bibeans\bin\bi_installcatalog.bat on Windows or Oracle_home/bibeans/bin/bi_installcatalog.csh on Unix). The syntax is given below. Note that you can supply either the servicename or the host_name, port_id, and sid.

   Syntax:
   bi_installcatalog <user> <password> [servicename]| [-h <host_name> -po <port_id> -sid <sid>][-j oci8|thin] [-ts system_tablespace] [-ti index_tablespace] [-ta attributes_tablespace1;a_t2;..;a_tn] [-tc clob_tablespace1;c_t2;..;c_tn] [-v(erbose)]

   The following tables describes the parameters:

   Parameter	Description
   user	The user that owns the Catalog schema. See To create an Oracle user that will own the catalog schema.
   password	The password assigned to the Catalog schema user.
   -h	The name of the host machine.
   -po	The port identifier.
   -sid	The identifier of the database instance.
   -j	The JDBC driver to use. Oracle Corporation recommends that you use the thin driver (the value thin ) for the BI Beans Catalog. (oci8 indicates the Oracle JDBC Thick (OCI) driver, which has additional requirements.)
   tablespace parameters	Optional. If no tablespace parameters are specified, then the objects are installed into the user's default tablespace.

   Example 1: In the following example, sun-server is the host name, 1521 is the port identifier, orcl is the identifier of the database instance, and the objects are installed into BIBCAT's default tablespace.

   bi_installcatalog BIBCAT BIBCAT -j thin -h sun-server -po 1521 -sid orcl

   Example 2: This example is identical, except that the tablespaces (BIBCATSYS, BIBCATIDX, BIBCATATT and BIBCATCLOB) are specified.

   bi_installcatalog BIBCAT BIBCAT -j thin -h sun-server -po 1521 -sid orcl -ts BIBCATSYS -ti BIBCATIDX -ta BIBCATATT -tc BIBCATCLOB

Note: If you do choose to use the oci8 driver, then you must ensure that the environment variable JDBC_CLASSPATH is set to the location of classes12.jar and nls_charset12.jar under the Oracle Home directory, as shown in the following examples:

Windows example -- If the Oracle Home directory is d:\oracle9, then you enter the following: JDBC_CLASSPATH=d:\oracle9\jdbc\lib\classes12.jar;d:\oracle9\jdbc\lib\nls_charset12.jar

UNIX example -- If the Oracle Home directory is /usr/oracle, then you enter the following: setenv JDBC_CLASSPATH /usr/oracle/jdbc/lib/classes12.jar:/usr/oracle/jdbc/lib/nls_charset12.jar

6. When you see a warning that your BI Beans Catalog is about to be overwritten, press Y to continue.

7. As the script runs, error messages are written to the console. Some error messages occur when database objects that do not exist are dropped; you can ignore such messages. However, if there are other error messages, then review the errors and take appropriate action.

You are now ready to begin saving business intelligence objects such as crosstabs, graphs, and calculations into the BI Beans Catalog. The tutorial and samples show you how to develop applications that use the Catalog. The Help system and the API Reference also provide extensive information.

Moving the Catalog to a New Database Instance

When you install a new Catalog into an existing schema, your existing Catalog is deleted. To preserve your Catalog objects and users, perform the following steps.

1. Export your data by running the export utility.

2. If you have a synchronized user system, you must perform whatever synchronization steps are needed by your system.

3. Install the Catalog, using the advanced installation.

4. Import your data into the newly-installed Catalog by running the import utility.

To run the import and export utilities:

You can use these command line utilities to export the data from an existing BI Beans Catalog, then import it into a new version of the Catalog.

File Locations

Syntax: bi_export

bi_export -u username [-p password] [-s servicename | [-h hostname -po portnumber -sid sid]] [-j oci8|thin] [-c [jdbc|file|zip|storagemanager class]] [-o ownerfilter] [-a application filter] [-d database filter] [-f folder filter] [-v] [-i initial pathname] [-z zipfile] [-x a|n|u|r] [-lu BI Beans user] ExportFilename [name1 [name2 [...]]]

Example: bi_export

This Windows example shows how to use bi_export to export the entire BI Beans Catalog.

bi_export -u BIBCAT -p BIBCAT -lu BIBCAT -j thin -h test-lap -po 1521 -sid hbr92 -x a catalogdump.xml

Syntax: bi_import

bi_import -u username [-p password] [-s servicename | [-h hostname -po portnumber -sid sid]] [-j oci8|thin] [-c [jdbc|file|zip|storagemanager class]] [-f target folder] [-v] [-i initial pathname] [-z zipfile] [-x a|n|u|r] [-lu BI Beans user] [-b] ImportFilename [name1 [name2 [...]]]

Example: bi_import

This Windows example shows how to use bi_import to import the entire Catalog file, while preserving the access controls (-x a) and all attributes (-b).

bi_import -u BIBCAT -p BIBCAT -lu BIBCAT -j thin -h test-lap -po 1521 -sid hbr92 -x a -b test.xml