1
Introducing the Oracle Discoverer EUL Command Line for Java

1.1 Introducing the Oracle Discoverer EUL Command Line for Java

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

• "What is the Oracle Discoverer EUL Command Line for Java?"

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

The Oracle 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 Oracle Discoverer Administrator on a Windows machine

• using the Oracle Discoverer Administrator Command Line Interface on a Windows machine

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

Figure 1-1 Discoverer interfaces to the Discoverer EUL

Text description of the illustration overview.gif

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

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

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

  Note: You do not need to have Oracle Discoverer Administrator 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 (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 Section B.1, "Differences in syntax between Discoverer command line interfaces").

1.4 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 (i.e. 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.5 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 in conjunction 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.6 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 Discoverer Administrator Administration Guide.

1.7 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 Section 1.7.1, "How to type commands directly at a command prompt")

• by running commands stored in command files (for more information, see Section 1.7.2, "How to run commands stored in a command file")

Notes

• Oracle Administrator Command Line Interface commands are not compatible with Discoverer EUL Command Line for Java commands without amendment (for more information, see Section 1.3, "What are the differences between the Oracle Discoverer Administrator Command Line Interface and the Discoverer EUL Command Line for Java?").

• Make sure that the <ORACLE_HOME>/lib directory is registered in the CLASS PATH.

• To see a list of EUL objects in an EUL, export all EUL objects so that you can inspect it. For example:

  java eulbuilder.jar -connect jchan/12345@my_database -export 
  objectlist.xml -all % -wildcard
  

1.7.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 machine.

To type a command directly at a command prompt:

1. Open a command prompt (e.g. a UNIX command prompt).

2. Type a command directly at the command prompt.

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

   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

Text description of the illustration cm_cline.gif

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

1. Create a text file and type the commands into the text file (e.g. import.txt).

2. Open a command prompt (e.g. a UNIX command prompt).

3. 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 Section 1.11, "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:

  java -jar eulbuilder.jar -cmdfile c:\scripts\login.txt -cmdfile 
  c:\scripts\import.txt
  

1.8 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 Section 2.6.43, "-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>.
  

1.9 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 Section 2.6.64, "-wildcard").

How to identify EUL objects using the percent wildcard:

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

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

   java eulbuilder.jar -connect jchan/12345@my_database -delete -business_
   area A% -wildcard 
   

How to identify EUL objects using the underscore wildcard:

1. 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 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.10 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

Notes:

• You can find more examples in Section 2.1, "Discoverer EUL Command Line for Java Reference".

1.11 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.12 Examples of command files

Three example command files are described below:

1. connect.txt contains '-connect jchan/12345@my_database'

2. create.txt contains '-create_eul -log create.log'

3. 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.13 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 Section 2.1, "Discoverer EUL Command Line for Java Reference").