5 Using the EDQ Command Line Interface

This chapter describes how to use the EDQ command line interface.

This chapter includes the following sections:

The EDQ command line interface, jmxtools.jar, provides access to a number of EDQ facilities.

5.1 Running the Command Line Interface

The EDQ command line interface is distributed as a self contained .jar file in the tools directory, and is executed by the following command line invocation:

java -jar jmxtools.jar commandname arguments

The commands and arguments are described in the following section.

5.2 Understanding the Commands and Arguments

The command line interface can run a number of commands and provides functionality including:

  • Running jobs

  • Listing and dropping orphaned results tables

  • Showing user session logs

  • Shutting down real-time jobs

  • Checking the EDQ version number

The following sections provide a full guide to the commands, arguments and options available.

5.2.1 runjob

The runjob command runs a named job in the same way as if running the job using the Director UI. The runjob command takes the following arguments:

Argument Use

-job job_name

Specifies the name of the job to run.

-project project_name

Specifies the name of the project that contains the job .

-u user_name

Specifies the user name to use to connect to the EDQ server. The user must have permission to run jobs and must have permission to the project containing the job.

-p password

Specifies the connecting user's password. If the -p option is not set, EDQ will prompt the user for the password.

-nolockwait

Indicates that if any of the resources used by the job are locked, the job should not wait for them to become available. Instead, it should terminate with a failure code and return control to the command line. The -nolockwait argument takes no extra values.

-nowait

Indicates that the command line should not wait for the job to complete. The -nowait argument takes no extra values.

server:port

Specifies the server and port of the JMX (management) interface.

5.2.2 runopsjob

The runopsjob command runs a named job in the same way as if running the job using the Server Console user interface. This provides additional functionality to the runjob command, specifically the use of Run Labels and Run Profiles. Run Labels may be used to store results separately from other runs of the same job. Run Profiles may be used to override externalized configuration settings at runtime.

The runopsjob command takes the following arguments:

Argument Use

-job job_name

Specifies the name of the job to run.

-project project_name

Specifies the name of the project that contains the job

-u user_name

Specifies the user name to use to connect to the EDQ server. The user must have permission to run jobs and must have permission to the project containing the job.

-p password

Specifies the connecting user's password. If the -p option is not set, EDQ will prompt the user for the password.

-nolockwait

Indicates that if any of the resources used by the job are locked, the job should not wait for them to become available. Instead, it should terminate with a failure code and return control to the command line. The -nolockwait argument takes no extra values.

-nowait

Indicates that the command line should not wait for the job to complete. The -nowait argument takes no extra values.

-runlabel run_label_name

Specifies the name of the run label under which you wish to store staged output results. Note that this will override any run label that is specified in a run profile or by -D runlabel = run_label_name.

-props run_profile_name

Specifies the full path to a run profile properties file containing override settings for externalized configuration options in the job.

-D externalized_option=value

Allows you to override specific externalized options for the job individually. The syntax for the externalized options and values is the same as used in run profile properties files. Note that characters will be interpreted by the command line, so some characters will need to be escaped according to the shell conventions of your environment. Also note that any individually specified externalized option settings will override any settings for the same option if these are specified in a run profile used in the same run.

server:port

Specifies the server and port of the JMX (management) interface.

5.2.3 droporphans

The droporphans command is used to remove any orphaned results tables that may be created when processes are terminated unexpectedly. It should not be run when any jobs or processes are running on the EDQ server.

The droporphans command takes the following arguments:

Option Use

-u user name

Specifies the user name to use to connect to the EDQ server. The user must have permission to cancel jobs and must have permission to the project containing the job.

-p password

Specifies the connecting user's password. If the -p option is not set, EDQ will prompt the user for the password.

server:port

Specifies the server and port of the JMX (management) interface.

5.2.4 listorphans

The listorphans command is used to identify any orphaned results tables. The listorphans command takes the same arguments as the droporphans command.

5.2.5 scriptorphans

The scriptorphans command creates a list of SQL commands for dropping orphaned results tables. This is useful if you want to review exactly which commands will run on the Results database when you drop tables, or if you want to drop the tables yourself manually.

5.2.6 list

The list command lists all the available commands.

5.2.7 showlogs

The showlogs command starts a small graphical user interface application that allows user session logs to be retrieved.

5.2.8 shutdown

The shutdown command shuts down all real-time jobs. These are jobs that are running from real-time record providers (web services or Java Message Service).

The shutdown command takes the following arguments:

Option Use

-u user name

Specifies the user name to use to connect to the EDQ server. The user must have permission to cancel jobs and must have permission to the project containing the job.

-p password

Specifies the connecting user's password. If the -p option is not set, EDQ will prompt the user for the password.

-nowait

Indicates that the command line should not wait for the job to complete. The -nowait argument takes no extra values.

server:port

Specifies the server and port of the JMX (management) interface.

5.2.9 version

The version command is used to identify the version of the currently installed instance of EDQ.

Enter the following at the command line:

java -jar jmxtools.jar version

The version number is returned.

5.3 Reviewing Examples

This section lists several possible invocations of the command line interface:

5.3.1 Listing All the Available Commands

The following invocation of the command line interface lists all of the available commands:

java -jar jmxtools.jar -list

The output is as follows:

Available launch names:   
<Job tools>  
runjob Run named job    
shutdown Shutdown realtime jobs 
runopsjob Run named job in operations mode      

<Logging>    
showlogs Show session logs      

<Database Tools>     
listorphans List orphaned results tables        
droporphans Drop orphaned results tables        
scriptorphans Create script for dropping orphaned results tables        

<System Information> 
version Display version number of tools

5.3.2 Listing the Available Parameters for a Command

If the command line interface is invoked by specifying a command without the corresponding parameters, it outputs detailed help for the command. For example, to get detailed help on the runjob command, invoke the command line interface as follows:

java -jar jmxtools.jar runjob

The output is as follows:

Usage: runjob -job jobname -project project [-u user] [-p pw] [-nowait] [-nolockwait] [-sslprops props | -ssltrust store] server:port

5.3.3 Running a Named Job

This example illustrates how to run a named job in a named project on a specific EDQ instance (as specified by machine name and port).

To run a job called ”rulecheck” in a project called ”Audit” on the local machine with a JMX server on port 8090 using a user named "dnadmin" , the command is as follows:

java -jar jmxtools.jar runjob -job rulecheck -project audit -u dnadmin localhost:8090

The application prompts the user to enter the password for the dnadmin user.

5.3.4 Running a Named Job in Operations Mode

This example illustrates how to run a named job in 'operations mode' in a Windows environment. In operations mode, there is access to the Run Label and Run Profile capabilities so that the configuration of the job can be specified dynamically, and so that the results of the job can be stored by Run Label.

To run a job called "profiling" in a project called "MDM" on a server called "prod01", with a run label of "Nov2011" and a run profile file called File1.properties, with a JMX server on port 8090, the command is as follows:

java -jar jmxtools.jar runopsjob -job profiling -project MDM -runlabel Nov2011 -props c:\ProgramData\Oracle\"Enterprise Data Quality\oedq_local_home\File1.properties" -u dnadmin prod01:8090