1 Introducing the Discoverer EUL Command Line for Java

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

"What is the Oracle BI Discoverer EUL Command Line for Java?"
"What are the differences between the 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"

1.1 What is the Oracle BI Discoverer EUL Command Line for Java?

The Oracle BI 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 Database 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 (Windows, UNIX, Linux). For example, you might want to refresh (or patch) an EUL from a UNIX system.

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 system, as described in this guide
Using Oracle BI Discoverer Administrator on a Windows system
Using the Oracle BI Discoverer Administrator Command Line Interface on a Windows system

Note: To run the Oracle BI Discoverer Administrator Command Line Interface, you must have Oracle BI Discoverer Administrator installed on your system.

Figure 1-1 Discoverer interfaces to the Discoverer EUL

Notes:

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

1.2 What are the differences between the 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 Oracle BI Discoverer Administrator Command Line Interface. If you have commands and scripts written for the Oracle BI Discoverer Administrator Command Line Interface, you can easily convert them to run on the Discoverer EUL Command Line for Java.

The Oracle BI 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 Oracle BI Discoverer Administrator Command Line Interface runs only on Windows.

Note: Oracle BI Discoverer Administrator need not be installed to run the Discoverer EUL Command Line for Java.
Discoverer EUL Command Line for Java commands are prefixed with java -jar eulbuilder.jar.
The Discoverer EUL Command Line for Java contains extra commands (for example, 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").

1.3 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:
```
java -jar eulbuilder.jar -connect jchan/12345@my_database
```
The -import command imports EUL objects into the current EUL from a specified Discoverer EUL export file (that is, a file with an EEX extension). For example, to import EUL objects from the file c:\data\sales.eex:
```
java -jar eulbuilder.jar -connect jchan/12345@my_database
 -import c:\data\sales.eex
```

1.4 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:
```
java -jar eulbuilder.jar -connect jchan/12345@my_database
 -import c:\data\sales.eex -log sales_import_logfile.txt
```
The -item command modifier used with the -delete command specifies which EUL item to remove from an EUL. For example, to delete the item sales.profit:
```
java -jar eulbuilder.jar -connect jchan/12345@my_database -delete
 -item sales.profit
```

1.5 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 Fusion Middleware Administrator's Guide for Oracle Business Intelligence Discoverer.

1.6 How to run a Discoverer EUL Command Line for Java command

Note:

Before running the EUL Command Line for Java commands, run the discenv.sh script. For the location of the script, see "Discoverer file locations" in the Oracle Fusion Middleware Configuration Guide for Oracle Business Intelligence Discoverer.

This ensures that the environment variables (NLS_LANG and ORACLE_HOME) that are required for running the EUL Command-Line for Java command are initialized.

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.
Oracle BI 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 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:
```
java -jar eulbuilder.jar -connect jchan/12345@my_database
 -export objectlist.xml -all % -wildcard
```

1.6.1 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 system.

To type a command directly at a command prompt:

Open a command prompt (for example, 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 1-2):
```
java -jar eulbuilder.jar -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

1.6.2 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 (for example, import.txt).
Open a command prompt (for example, 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:
```
java -jar eulbuilder.jar -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 multiple command files by repeating the -cmdfile command. For example, to run commands stored in the text file login.txt, then commands in import.txt, type:
```
java -jar eulbuilder.jar -cmdfile c:\scripts\login.txt
 -cmdfile c:\scripts\import.txt
```

1.7 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 (that is, 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 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 see the 'Command completed' message on screen. However, you can 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>.
```

1.8 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 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 (that is, 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':

java -jar eulbuilder.jar -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':

java -jar eulbuilder.jar -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%'.

1.9 Examples of commands

Example 1

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

java -jar eulbuilder.jar -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:

java -jar eulbuilder.jar -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:

java -jar eulbuilder.jar -connect eul_owner:appsresp/appspwd -create_eul
 -apps_mode -apps_grant_details apps/apps -user jchan -password 123456

For more examples, see "Discoverer EUL Command Line for Java Reference".

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

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

java -jar eulbuilder.jar -cmdfile connect.txt

Example 2

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

java -jar eulbuilder.jar -cmdfile connect.txt -cmdfile create.txt

Example 3

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

java -jar eulbuilder.jar -cmdfile connect.txt -cmdfile delete.txt

1.12 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").