When specifying an item name or identifier that contain spaces or special characters, enclose it in double quotes (""). For example, if a folder is called Video Analysis Information, specify the folder name as "Video Analysis Information".

If you include connection details in a command file (for example, -connect username/password@database), you need not include the -connect command after the java -jar eulbuilder.jar section. In other words, if you store connection details in connect.txt, you might use the following command to connect to a database:

java -jar eulbuilder.jar -cmdfile connect.txt

2.3 Rules for using the Discoverer EUL Command Line for Java

When using the Discoverer EUL Command Line for Java, the following rules apply:

If you omit the optional <database> argument when you specify connection information, you connect to the Oracle database installed on your system. Use the optional <database> argument if you have multiple databases installed on your system, or if you are connecting to a database on a different system.

If you do not specify an object name where one is required, Discoverer uses the default object for that database username. For example, if you do not specify an EUL using the -eul modifier, Discoverer uses the default EUL for the current database username. For more information about specifying an EUL, see "-eul".

You can use nearly all commands with both Oracle or non-Oracle databases. There is one exception, the -refresh_summary command. You can only use the -refresh_summary command with Oracle databases (for more information, see "-refresh_summary").

When specifying Discoverer EUL objects, you can use either item names (for example, folder names) or identifiers (unique IDs assigned to EUL objects). For example, if a Discoverer folder is called Sales, and its identifier is SALES_132388, you can specify this folder as an argument to the -refresh_folder command in either of the following ways:

-refresh_folder Sales

-refresh_folder SALES_132388 -identifier

Hint: Where possible, use identifiers rather than item names to specify EUL objects. Using identifiers avoids translation issues and EUL update problems caused by names being changed arbitrarily (for more information, see -identifier).

For more information about Discoverer identifiers, see Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Discoverer.

To access a remote database, you must have the Transparent Network Substrate (TNS) settings for that database stored in the tnsnames.ora file.

For more information about TNS settings, see Oracle Enterprise Manager Administrator's Guide.

To create a command file, create a text file containing one or more Discoverer EUL Command Line for Java commands using a standard text editor. To run the command(s) in the text file, type the following at the command prompt:

java -jar eulbuilder.jar -cmdfile <command file>

If you omit a directory path when you specify <command file>, the default Discoverer EUL Command Line for Java directory is used.

Example 3: To delete three items from an EUL. You store the identifiers of the items you want to delete in a text file called delete.txt. The -identifier command modifier specifies that the EUL items are identified by identifier, rather than item name. Log information is stored in delete08082003.log.

2.5.7 -export

Use this command to export EUL objects to a Discoverer export file (that is, a file with an EEX extension). You can selectively export individual EUL objects (for example, folders, business areas, functions) or entire EULs (using the -all modifier).

The <export file> argument specifies the name of the target EEX file into which you export EUL objects. If a directory path is not specified, the target file is created in the default Discoverer folder. To override the default target directory setting, specify a directory path for the file (for example, c:\data\sales.eex).

Note: The directory path must be an absolute path, not a relative path.

When you export a business area using the -business_area modifier, Discoverer exports only business area definitions and links to the folders in the business area. Discoverer exports the folders and workbooks only when they are specified by name.

When specifying EUL objects, you can use either their Display Name or Identifier.

To maintain data relationships, you must also export linked (or joined) objects.

The EUL export file produced using the export command is in XML format.

Examples

Example 1: To export two business areas named Test BA and Final BA from an EUL named eul51, into a file named export.eex, and write to a log file named export.log, enter:

Example 2: In another example, you want to export four items. You store the names of the items you want to export in a text file called export.txt. The -identifier command modifier specifies that the EUL items are identified by identifier, rather than item name. Log information is stored in export07222001.log. The -audit_info command modifier is also used to store update information.

Note: When identifying EUL objects, you are recommended to use identifiers rather than display names. If you are using display names rather than identifiers to identify EUL objects, specify the owner of the object. For example, to specify a workbook owned by jchan, use jchan.“Workbook one” rather than “Workbook one”. For more information about identifiers, see "-identifier".

Example 3: To grant all administration privileges to users JOE and JCHAN:

Note: To see help on multiple commands, separate commands with a comma.

To see detailed help on all commands:

java -jar eulbuilder.jar -help -all

2.5.10 -import

Use this command to selectively import EUL objects from one or more Discoverer export files (that is, EEX files). Discoverer export files are created using the -export command, and contain EUL objects (for example, folders, business areas, functions, or an entire EUL). For example, if you export a business area using the -export command, you can import the business area from the EEX file created by the export.

When you import multiple files, Discoverer automatically resolves references between the files. For example, you can export the Emp folder in fileA.eex and the Dept folder in fileB.eex. If Emp and Dept are joined, the join information is in both files, but neither file contains the information for both folders. If you import both files, the join is recreated when the second file is processed.

Example 2: In another example, you want to import four files. You store the names of the files you want to import in a text file called import.txt. This file also contains the -import command. Log information is stored in import07222003.log.

To maximize Discoverer performance, it is recommended that you use the -auto_summaries command modifier to automatically create summary folders. For more information, see "-auto_summaries".

Use the -source modifier to specify the source of the data (default is the current database server). If you are loading data from an EUL Gateway, the source name must exactly match the EUL Gateway name.

Use the -eul modifier to specify an EUL into which to load the objects (default is the Discoverer manager's own EUL). If you specify an EUL, you must have access privileges to the named EUL in order for the operation to succeed.

When doing a bulk load from an Oracle database (Enterprise Edition release 9.2.0.7 and later), constraints on views are also considered when Discoverer creates joins.

Examples

Example 1: To bulk load into an EUL named eul51 from an Oracle Designer source on the current connection, creating a new business area named Test BA, enter:

Example 1: To refresh two business areas named Test BA and Final BA that reside in an EUL named eul_a, from an Oracle Designer source on the current connection owned by user Bob, and summarize information in a log file named refba.log, enter:

2.5.13 -refresh_folder

Use this command to refresh one or more Discoverer folders. When you refresh folders, the metadata for the folder is updated. For example, if a new database column has been added to a table, the EUL is updated with details of the new column.

2.6 Discoverer EUL Command Line for Java command modifier reference

This section contains detailed reference information about optional command modifiers available in the Discoverer EUL Command Line for Java. Command modifiers are used to refine or qualify Discoverer EUL Command Line for Java commands. Note the following:

2.6.12 -asm_space, -asm_tablespace

Use these command modifiers to override space and tablespace values set in the ASM policy and uses space and tablespace constraints that you specify. The following are valid combinations of tablespace and space values:

2.6.14 -auto_gen_name

Use this command modifier to set the Auto Generate name property, of all secondary elements to Yes, for all folders imported. For example, you might export a business area called Performance to an EEX file. If you then import the Performance business area from the EEX file at a later date, Discoverer sets the Auto Generate name property of all secondary elements to Yes, irrespective of the value that exists in exported file. For more information about secondary elements and the Auto generate name property, see the Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Discoverer.

2.6.15 -auto_refresh

Use this command modifier to automatically get up-to-date metadata from the database for all folders imported. For example, you might export a business area called Performance to an EEX file. If you then import the Performance business area from the EEX file at a later date, Discoverer retrieves up-to-date metadata from the data dictionary.

2.6.16 -auto_summaries

Use this command modifier to automatically create summary folders during a bulk load using Discoverer's powerful Automated Summary Management (ASM) facility. Summary folders contain data that has been queried and processed so that it can be reused. This modifier enables you to improve Discoverer's performance and minimize response times for Discoverer end-users.

For more information about summary folders and ASM, see Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Discoverer.

2.6.17 -auto_upgrade

Use command modifier to enable Discoverer to automatically upgrade an EUL when you connect to an EUL. For example, you might have upgrade when a new version of Discoverer is installed. If you do not use the -auto_upgrade modifier when an upgrade is required, the connect fails and an error message is displayed.

Hint: To remove a folder from an EUL completely, use '-delete -folder' (for more information, see "-folder").

2.6.19 -business_area

Use this command modifier to specify a business area for export or deletion.

Note: Only the definition of the business area is exported or deleted, not the objects (for example, folders, items, item classes) contained within it. To export or delete a business area and the objects contained within it, use -business_area_and_contents.

2.6.24 -character_set_encoding

Use this command modifier to specify the character set in which command files are saved (for example, EUC, Shift_JIS, UTF-8). For example, a command file created on Solaris with a Japanese locale is encoded in the default Java character set (that is, EUC). However, on Windows, Japanese characters are usually encoded in Shift_JIS or UTF-8, which means that you must specify a character set so that Java can interpret commands correctly.

You must specify this modifier at the command prompt immediately following the -cmdfile command. In other words, you cannot include the -character_set_encoding command modifier inside the command file itself.

If you reference an object prefixed with a parent object name, you must also reference the parent object name using its identifier. For example, to delete the item Region.City, you must use identifiers for both objects, as follows:

-delete -item REGION_01.CITY_01 -identifier

Examples

Example 1: To delete the item Video Analysis Information.Store Name using identifiers, enter:

2.6.42 -keep_format_properties

Use this command modifier to keep existing format properties (for example, display names, descriptions) on import. If you do not use this command modifier, you update existing format properties with the display names and descriptions in the import file (that is, the EEX file).

2.6.43 -log

This modifier enables you to specify a name for the log file that stores command status messages. After each command is executed, Discoverer writes a status message indicating whether the command was successful. You can use -log with the optional -log_only command modifier.

If the file specified by <log file name> exists, the existing log file is overwritten.

If the file specified by <log file name> does not exist, a new file is created.

2.6.44 -log_only

Use this command modifier to perform impact analysis by simulating a command and generating a log, without changing live data. Using this command modifier enables you to check for errors and exceptions before changing data.

2.6.50 -private

Use this command modifier to specify that public access is not granted to a newly created EUL. In other words, only the EUL owner can access the newly created EUL. If omitted, public access is granted to the newly created EUL.

2.6.51 -privilege

Use this command modifier to specify the privileges to grant (or revoke) to (or from) database users. For more information about granting and revoking privileges, see "-grant_privilege" and "-revoke_privilege".

Use 'administration' to enable the user or role to log in to Discoverer Administrator. Note that to allow the user to access the features in Discoverer Administrator, you must select individual Administration privileges (for example, create_summaries, collect_qpp).

Use 'user_edition' to enable the user or role to log in to Discoverer Desktop and Discoverer Plus. Note that to allow the user to access the features in Discoverer Desktop and Discoverer Plus, you must select individual Desktop/Plus privileges (for example, drill out, schedule_workbook).

Use 'format_business_area' to enable the user or role to edit formatting information (for example, folders, summary folders, joins) in an existing business area to which they have access.

Use 'create_edit_business_area' to enable the user or role to create and modify business areas, folders, summary folders, joins, calculations, conditions, hierarchies and item classes.

Use 'create_summaries' to enable the user or role to create summary folders. This privilege also requires database resource privileges.

Use 'set_privilege' to enable the user to maintain and modify user privileges.

Note: You cannot grant this privilege to a role.

Use 'manage_scheduled_workbooks' to enable the user or role to monitor and maintain scheduled workbooks.

Use 'create_edit_query' to enable the user or role to create new worksheets (queries) and modify existing ones. Without this privilege, the user can only open and run existing workbooks and worksheets.

Use 'collect_qpp' to collect performance statistics when the user opens workbooks and worksheets.

Use 'item_drill' to enable the user or role to drill down into worksheet data.

Use 'drill_out' to enable the user or role to launch another application to see related information by drilling on an item in a worksheet.

Use 'grant_workbook' to enable the user or role to grant access to their workbooks so that other users can access them.

Use 'schedule_workbook' to enable the user to schedule a workbook to run at a later time or at regular intervals (that is, daily, weekly, monthly).

Note: You cannot grant this privilege to a role.

Use 'save_workbook_database' to enable the user or role to save the workbooks in the database.

Use 'all_admin_privs' to enable the user or role to the following privileges:

administration

format_business_area

create_edit_business_area

create_summaries

set_privilege

manage_scheduled_workbooks

Use 'all_user_privs' to enable the user or role to the following privileges:

user_edition

create_edit_query

collect_qpp

item_drill

drill_out

grant_workbook

schedule_workbook

save_workbook_database

2.6.52 -remove_prefix

Use this command modifier to specify that item names do not include the column name prefix when they are generated from their respective column names during a bulk load.

2.6.62 -source

Use gateway name to specify the name of an Oracle Designer object or other gateway.

The gateway name must exactly match the gateway name displayed in the Load Wizard. In the case of Oracle Designer, specify "Designer 6i - <workarea name>" (if you are using a version of Oracle Designer earlier than Oracle Designer 6i, simply specify "Oracle Designer repository").

If you do not specify a gateway using -source, Discoverer uses the online dictionary.

2.6.63 -summary

Use this command modifier to specify a summary for export or deletion.

2.6.69 -xml_workbooks

This command modifier (used with the -export command) forces all workbooks to be exported in XML format and binary large object (BLOB) format. Exporting workbooks in XML format enables you to view the definition of exported workbooks in a text editor or XML browser.