1 Introducing the Oracle Business Intelligence Discoverer EUL Command Line for Java

This chapter introduces the OracleBI Discoverer EUL Command Line for Java, and contains the following topics:

"What is the OracleBI Discoverer EUL Command Line for Java?"
"What are the differences between the OracleBI Discoverer Administrator Command Line Interface and the Discoverer EUL Command Line for Java?"
"What is a Discoverer EUL Command Line for Java command?"
"What is a Discoverer EUL Command Line for Java command modifier?"
"What privileges do you require to use the Discoverer EUL Command Line for Java?"
"How to run a Discoverer EUL Command Line for Java command"
"About troubleshooting the Discoverer EUL Command Line for Java"
"About using wildcards to identify EUL objects"
"Examples of commands"
"What is a command file?"
"Examples of command files"
"List of Discoverer EUL Command Line for Java commands"

What is the OracleBI Discoverer EUL Command Line for Java?

The OracleBI Discoverer EUL Command Line for Java is a set of text based commands that enable you to create and manipulate Discoverer EULs.

Note: You use Heterogeneous Services to connect to non-Oracle databases, although the EUL is stored in the Oracle database. For more information about using non-Oracle databases, see Oracle Heterogeneous Connectivity Administrator's Guide.

The Discoverer EUL Command Line for Java runs in a Java environment, which means that you can run it from any Java-compatible platform (e.g. Windows, UNIX, Linux). For example, you might want to refresh (or patch) an EUL from a UNIX machine.

The figure below shows three different ways in which you can manipulate Discoverer EULs:

using the Discoverer EUL Command Line for Java on either a Windows, UNIX, or Linux machine, as described in this guide
using OracleBI Discoverer Administrator on a Windows machine
using the OracleBI Discoverer Administrator Command Line Interface on a Windows machine

Note: To run the OracleBI Discoverer Administrator Command Line Interface, you must have OracleBI Discoverer Administrator installed on your machine.

Figure 1-1 Discoverer interfaces to the Discoverer EUL

Description of "Figure 1-1 Discoverer interfaces to the Discoverer EUL"

Notes:

Discoverer EUL files have an EEX extension (e.g. Sales_eul.eex)
For a list of Discoverer EUL Command Line for Java commands, see "List of Discoverer EUL Command Line for Java commands".

What are the differences between the OracleBI Discoverer Administrator Command Line Interface and the Discoverer EUL Command Line for Java?

Much of the Discoverer EUL Command Line for Java is compatible with the OracleBI Discoverer Administrator Command Line Interface. If you have commands and scripts written for the OracleBI Discoverer Administrator Command Line Interface, you can easily convert them to run on the Discoverer EUL Command Line for Java.

The OracleBI Discoverer Administrator Command Line Interface and the Discoverer EUL Command Line for Java differ as follows:

The Discoverer EUL Command Line for Java runs on multiple platforms. The OracleBI Discoverer Administrator Command Line Interface runs only on Windows.

Note: You do not need to have OracleBI Discoverer Administrator installed to run the Discoverer EUL Command Line for Java.
Discoverer EUL Command Line for Java commands are prefixed with eulapi.
The Discoverer EUL Command Line for Java contains extra commands (e.g. to grant and revoke database privileges, you can use the commands -grant_privilege and -revoke_privilege commands).
Some commands have minor differences in syntax (for more information, see "Differences in syntax between Discoverer command line interfaces").

What is a Discoverer EUL Command Line for Java command?

A Discoverer EUL Command Line for Java command is an instruction that manipulates a Discoverer EUL in some way. For example:

the -connect command connects to a database using the username, password, and database specified. For example, to connect to database my_database as user jchan:
```
eulapi -connect jchan/12345@my_database
```
The -import command imports EUL objects into the current EUL from a specified Discoverer EUL export file (i.e. a file with an EEX extension). For example, to import EUL objects from the file c:\data\sales.eex:
```
eulapi -connect jchan/12345@my_database -import c:\data\sales.eex
```

What is a Discoverer EUL Command Line for Java command modifier?

A Discoverer EUL Command Line for Java command modifier is an instruction that qualifies or refines a command. For example:

The -log command modifier creates a log file to store processing information during the execution of a command. For example, to import EUL objects from the file c:\data\sales.eex and store log data in sales_import_logfile.txt:
```
eulapi -connect jchan/12345@my_database -import c:\data\sales.eex -log sales_import_logfile.txt
```
The -item command modifier used in conjunction with the -delete command specifies which EUL item to remove from an EUL. For example, to delete the item sales.profit:
```
eulapi -connect jchan/12345@my_database -delete -item sales.profit
```

What privileges do you require to use the Discoverer EUL Command Line for Java?

To use the Discoverer EUL Command Line for Java, the database username that you use to connect to a database must have the following database privileges:

CREATE SESSION
CREATE TABLE
CREATE VIEW
CREATE SEQUENCE
CREATE PROCEDURE

The database username also requires a default tablespace, and a quota set on the default tablespace. For more information about granting privileges, see Oracle Business Intelligence Discoverer Administration Guide.

How to run a Discoverer EUL Command Line for Java command

You can run the Discoverer EUL Command Line for Java in two ways:

by entering commands directly at a command prompt (for more information, see "How to type commands directly at a command prompt")
by running commands stored in command files (for more information, see "How to run commands stored in a command file")

Notes

The eulapi script is located in <ORACLE_HOME>/bin.
Make sure that the <ORACLE_HOME>/lib directory is registered in the CLASS PATH.
OracleBI Discoverer Administrator Command Line Interface commands are not compatible with Discoverer EUL Command Line for Java commands without amendment (for more information, see "What are the differences between the OracleBI Discoverer Administrator Command Line Interface and the Discoverer EUL Command Line for Java?").
To see a list of EUL objects in an EUL, export all EUL objects so that you can inspect it. For example:
```
eulapi -connect jchan/12345@my_database -export objectlist.xml -all % -wildcard
```

How to type commands directly at a command prompt

You might type commands directly at a command prompt when you want to patch an EUL from a UNIX machine.

To type a command directly at a command prompt:

Open a command prompt (e.g. a UNIX command prompt).
Type a command directly at the command prompt.

For example, to refresh folders called Sales1 and Sales2, type the following (see figure below):

eulapi -connect jchan/12345@my_database -refresh_folder Sales1 -refresh_folder Sales2

Figure 1-2 Using the Discoverer EUL Command Line for Java from a UNIX command prompt

Description of "Figure 1-2 Using the Discoverer EUL Command Line for Java from a UNIX command prompt"

How to run commands stored in a command file

You might run commands stored in a command file when you want to perform a regular EUL update.

To run commands stored in a command file:

Create a text file and type the commands into the text file (e.g. import.txt).
Open a command prompt (e.g. a UNIX command prompt).
Type the -cmdfile command at the command prompt followed by the name of a command file.

For example, to run commands stored in import.txt, type the following:

eulapi -connect jchan/12345@my_database -cmdfile import.txt

For more information about command files, see "What is a command file?".

Notes

You can also run more than one command file by repeating the -cmdfile command. For example, to run commands stored in the text file login.txt, then commands in import.txt, type:
```
eulapi -cmdfile c:\scripts\login.txt -cmdfile c:\scripts\import.txt
```

About troubleshooting the Discoverer EUL Command Line for Java

The Discoverer EUL Command Line for Java provides a log facility. Use the log facility to test commands without changing data (i.e. for impact analysis) and troubleshoot problems as follows:

Testing commands without changing data.

To test commands without changing data, use the -log <log file name> -log_only modifiers. For example:

-log <log file name> -log_only

These modifiers produce a log file showing whether problems occurred during command execution without changing the data. For more information, see "-log_only".

Troubleshooting problems.

To troubleshoot problems, use the -log <log file name> modifier to store command processing information.

For example, after running a command you will see a 'Command completed' message, which means that Discoverer processing is complete. To verify that the operation was carried out successfully, check the log file created using the -log modifier.

For example, if you attempt to delete a folder called 'Store 4' that is used in a summary folder, you will see the 'Command completed' message on screen. However, you will find details in the log file specifying why the command could not be executed, similar to the following:

java EulCommandLine -connect jchan/12345@my_database -delete -folder Store 4 -log
Started <date and time>...
Deleting folder Store 4...
Element Store 4 cannot be deleted because it is used in a summary 
Completed <date and time>.

About using wildcards to identify EUL objects

When you use the Discoverer EUL Command Line for Java, you can use wildcards to specify groups of EUL objects that you want to manipulate. Wildcards are special characters that you use to substitute other characters. For example, you might want to import OLAP functions with names that begin with 'BI_'.

There are two wildcards that you can use:

a percent sign (%) matches zero (i.e. none) or more characters
an underscore (_) matches exactly one character

You can use wildcards when you:

delete EUL objects
export EUL objects
import EUL objects
refresh folders, business areas, and summary folders
grant and revoke privileges for workbooks and business areas

You can use wildcards with item names or identifiers. When you use wildcards, you append the command with the -wildcard modifier (for more information, see "-wildcard").

How to identify EUL objects using the percent wildcard:

Use the percent sign (%) followed by the -wildcard modifier.

For example, to delete all business areas with display names that begin with 'A':

eulapi -connect jchan/12345@my_database -delete -business_area A% -wildcard

How to identify EUL objects using the underscore wildcard:

Use the underscore (_) followed by the -wildcard modifier.

For example, to delete all business areas with an identifier 'A', followed by any character, followed by 'C':

eulapi -connect jchan/12345@my_database -delete -business_area A_C -identifier -wildcard

Notes:

You can combine percent wildcard characters with underscore wildcard characters.
If you omit the -wildcard modifier, the percent sign (%) or underscore (_) characters are interpreted as literal characters. In other words, the command '-delete -business_area A%' attempts to delete a business area called 'A%'.

Examples of commands

Example 1

To delete the Sales folder and Sum1 summary from the Sales EUL, use the following command:

eulapi -connect jchan/12345@my_database -delete -folder Sales -summary Sum1 -eul Sales

Example 2

To refresh the Sales1 and Sales2 folders, use the following command:

eulapi -connect jchan/12345@my_database -refresh_folder Sales1 -refresh_folder Sales2

Example 3

To create an Applications Mode EUL in the database under user jchan and grant access using the Applications username and password apps/apps, use the following command:

eulapi -connect eul_owner:appsresp/appspwd -create_eul -apps_mode -apps_grant_details apps/apps -user jchan -password 123456

Notes:

You can find more examples in "Discoverer EUL Command Line for Java Reference".

What is a command file?

Command files are text files that contain one or more Discoverer EUL Command Line for Java commands. You use command files to run commands automatically without having to type them manually at a command prompt. If you are familiar with MS-DOS or UNIX, command files work in a similar way to MS-DOS batch files and UNIX script files.

Notes:

The commands in a command file are treated as though they were entered directly at the command prompt.
Carriage returns embedded in a command file are ignored.
A command file can in turn invoke other command files.

Examples of command files

Three example command files are described below:

connect.txt contains '-connect jchan/12345@my_database'
create.txt contains '-create_eul -log create.log'
delete.txt contains '-delete_eul -log delete.log'

You can use these command files in different combinations as shown in the following examples:

Example 1

To connect to a database:

eulapi -cmdfile connect.txt

Example 2

To connect to a database, create an EUL, and store processing information in a log file:

eulapi -cmdfile connect.txt -cmdfile create.txt

Example 3

To connect to a database, delete an EUL, and store processing information in a log file:

eulapi -cmdfile connect.txt -cmdfile delete.txt

List of Discoverer EUL Command Line for Java commands

The table below lists the Discoverer EUL Command Line for Java commands

Command:	Use to:
-asm <modifiers>	Automate summary management ASM
-cmdfile <command file>	Run commands stored in a command file
-connect <username>/<password> [@<database]	Connect to an EUL
-create_eul <modifiers>	Create an EUL
-delete <modifiers>	Delete an EUL object
-delete_eul <modifiers>	Delete an EUL
-export <export file> <modifiers>	Export EUL object
-grant_privilege <modifiers>	Grant Discoverer privileges to a database user
-help [command name(s)] [-all]	Display online help
-import <import file(s)> <modifiers>	Import EUL objects
-load <business area> <modifiers>	Load a business area
-refresh_business_area <business area(s)> <modifiers>	Refresh a business area
-refresh_folder <folder name(s)> <modifiers>	Refresh a folder
-refresh_summary <summary name(s)> <modifiers>	Refresh a summary folder
-revoke_privilege <modifiers>	Remove Discoverer privileges from a database user

Note: Detailed information about command modifiers is contained in the command reference section (for more information, see "Discoverer EUL Command Line for Java Reference").