Oracle 8i | Oracle 9i | Oracle 10g | Oracle 11g | Oracle 12c | Miscellaneous | PL/SQL | SQL | Oracle RAC | Oracle Apps | Linux

Installing Enteprise Manager Command Line Interface (EMCLI) for Cloud Control 12c

Enterprise Manager Cloud Control 12c includes a command line interface (EMCLI) that allows you to script many tasks. This article introduces the basics of the EMCLI utility.

Related articles.

Download EMCLI

From the Cloud Control console, navigate to the "Enterprise Manager Command Line Tools Download" page using the "Setup > Command Line Interface" menu option.

Click on the "Download the EMCLI with Scripting option kit to your workstation." link under the "EMCLI with Scripting option" section.

Once you have the JAR file you can install EMCLI. Remember, this is a client tool, so the location you install it is independent of the location of the management server. You may have a management server running on Linux, but choose to install the EMCLI on your desktop PC running Windows.

Linux Installation

The typical procedure for installing EMCLI on Linux is shown below.

mkdir /home/oracle/emcli
export JAVA_HOME=/usr/java/jdk1.7.0_25
export PATH=$JAVA_HOME/bin:$PATH
java -jar emcliadvancedkit.jar client -install_dir=/home/oracle/emcli
cd /home/oracle/emcli
emcli setup -url=https://ol6-em12cr3.localdomain:7803/em -username=sysman -trustall -autologin
export EMCLI_STATE_DIR=/home/oracle/emcli

Adjust the JAVA_HOME and the install location of EMCLI as required. The "-autologin" flag means that once you've logged in for the first time you will not have to log in again. If you think this is too risky, you can omit it and log in each time you use the tool.

The "-url" parameter should be set to the fully qualified URL of your management server.

Windows Installation

The typical procedure for installing EMCLI on Windows is shown below.

mkdir c:\emcli
set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_25
set PATH=%JAVA_HOME%\bin;%PATH%
java -jar emcliadvancedkit.jar client -install_dir=c:\emcli
cd c:\emcli
emcli setup -url=https://ol6-em12cr3.localdomain:7803/em -username=sysman -trustall -autologin
set EMCLI_STATE_DIR=C:\emcli

Adjust the JAVA_HOME and the install location of EMCLI as required. The "-autologin" flag means that once you've logged in for the first time you will not have to log in again. If you think this is too risky, you can omit it and log in each time you use the tool.

The "-url" parameter should be set to the fully qualified URL of your management server.

Starting EMCLI

Once EMCLI is installed, you can either use interactive mode or standard invocation. To work in interactive mode, simply issue the emcli command with no parameters.

# Linux
cd /home/oracle/emcli
emcli

Rem Windows
cd C:\emcli
emcli

For standard invocation, issue the same command, but include the relevant parameters, or verbs, for the required action.

# Linux
cd /home/oracle/emcli
emcli help

Rem Windows
cd C:\emcli
emcli help

Verb Reference

The list of available commands, or verbs, is available in the Verb Reference documentation.

You can get much of this information from the EMCLI help.

Getting Help

Not surprisingly, the way you get help in EMCLI is to use the help command. Like most commands, it can be called interactively or using standard invocation.

emcli># Interactive
emcli>help()

$ # Standard Invocation
$ emcli help

The basic help command produces a lot of output, with a brief explanation of each verb. An example of the output is shown here.

You can drill down further into the help by specifying the verb of interest.
emcli># Interactive
emcli>help("create_job")

$ # Standard Invocation
$ emcli help create_job

Some of the help pages suggest additional help commands to get more detailed information, or even example parameter files.

Example

Rather than trying to present lots of examples, I'll show you the approach you need to take to figure out how to use specific commands.

First, check the basic help to see if there is a verb that sounds like it could suit your purpose. For example, let's say we need to create a new job. We issue the help command and check the output for anything that looks like it might be related to jobs.

$ emcli help
.
.
.
  Job Verbs
    create_job               -- Create a job
    create_job_from_library  -- Create a job using a library job as a template.

    create_library_job       -- Create a library job
    delete_job               -- Delete the specified job
    delete_library_job       -- Delete a library job
    describe_job             -- Describe a job
    describe_job_type        -- Describe a Job Type
    describe_library_job     -- Describe a library job
    get_job_execution_detail -- Display details of job execution
    get_job_types            -- Lists all Job Types that can be used to create jobs from EMCLI
    get_jobs                 -- Get a list of existing jobs
    retry_job                -- Restart a previously failed job execution
    stop_job                 -- Stop the specified job
    submit_job               -- Submit a job (Deprecated - use create_job)
.
.
.

We can see a verb called create_job, which looks promising, so we drill down into that.

$ emcli help create_job
emcli create_job
     -name=<job_name>
     -type=<job_type>
     -input_file="property_file:<filename>"
Description:
 Create and schedule a job.

Options:
     -name: Optional parameter. The name may be specified in the input file instead.
     -type: Optional parameter. The type may be specified in the input file instead.
     -input_file : Required parameter. <filename> must be provided to load the properties for creating and scheduling the job.

 A template property file for the job_type can be obtained using EMCLI verb "describe_job_type".
 Another job of the same job type could also be used to generate the property file using EMCLI verb "describe_job".
 Please make sure that the property file is accessible to the EMCLI client for reading.

Sample:
 Create and schedule a job with name MYJOB1 and of job type MyJobType1 with property file present at location /tmp/myjob1_prop.txt
     emcli create_job -name=MYJOB1 -job_type=MyJobType1 -input_file="property_file:/tmp/myjob1_prop.txt"

$

The help tells us to use the describe_job_type verb to get a template property file.

$ emcli describe_job_type -type=RMANScript

# Description: (Optional) The user specified name of the job
name=

# Description: (Optional) The job type for this job
type=RMANScript

# Description: (Optional) The user specified description of the job
description=

# Description: The job owner. The job owner is the user who creates the job.
# Default: the logged in user
# The job owner information displayed here is for documentation only and user is not expected to change it.
owner=

# Description: (Optional) The kind of job
# Legal Values: active, library
kind=


# Fill in the target list before submitting.
# For Example:
#     target_list=MyTarget:oracle_database
target_list=<target_name>:<target_type>


# Credential Usage: defaultDBCred
# Description:
cred.defaultDBCred.<target_name>:<target_type>=

# Credential Usage: defaultHostCred
# Description:
cred.defaultHostCred.<target_name>:<target_type>=

# Description: (Required) Enter RMAN commands or a fully qualified script name on the remote hosts, for example, "@script.rcv"
variable.rman_perl_script=


# Description: (Optional) Notify the job owner when a selected state occurs
# Allowed Values:  SCHEDULED, RUNNING, ACTION_REQUIRED, SUSPENDED, SUCCEEDED, PROBLEMS
notification=

$
We can now create property file using the template and fill in the values. In this case I created the property file with the name "/tmp/property_file.txt" and the following contents.
# Description: (Optional) The user specified name of the job
name=test_emcli_job_1

# Description: (Optional) The job type for this job
type=RMANScript

# Description: (Optional) The user specified description of the job
description=A test job created using EMCLI

# Description: The job owner. The job owner is the user who creates the job.
# Default: the logged in user
# The job owner information displayed here is for documentation only and user is not expected to change it.
owner=sysman

# Description: (Optional) The kind of job
# Legal Values: active, library
kind=active


# Fill in the target list before submitting.
# For Example:
#     target_list=MyTarget:oracle_database
target_list=db12c:oracle_database


# Credential Usage: defaultDBCred
# Description:
#cred.defaultDBCred.<target_name>:<target_type>=

# Credential Usage: defaultHostCred
# Description:
#cred.defaultHostCred.<target_name>:<target_type>=

# Description: (Required) Enter RMAN commands or a fully qualified script name on the remote hosts, for example, "@script.rcv"
variable.rman_perl_script=<<MULTILINEVALUE
run {
recover copy of database with tag 'MYDB_INCR_BACKUP' until time 'SYSDATE-7';
backup incremental level 1 for recover of copy with tag 'MYDB_INCR_BACKUP' database;
backup device type disk tag 'MYDB_INCR_BACKUP' archivelog all not backed up delete all input;
delete noprompt obsolete device type disk;
}
MULTILINEVALUE

# Description: (Optional) Notify the job owner when a selected state occurs
# Allowed Values:  SCHEDULED, RUNNING, ACTION_REQUIRED, SUSPENDED, SUCCEEDED, PROBLEMS
notification=SUCCEEDED,PROBLEMS

With the property file in place we can run the create_job command as follows.

$ emcli create_job -input_file="property_file:/tmp/property_file.txt"
Creation of job "TEST_EMCLI_JOB_1" was successful.

$

We can remove the job with the following command.

$ emcli delete_job -name=test_emcli_job_1
Job "TEST_EMCLI_JOB_1" deleted successfully

$

The job is scheduled for an immediate run. If you want to schedule a repeated task, you have the following parameter available that can be added to the propery file.

schedule.frequency=
schedule.startTime=
schedule.endTime=
schedule.gracePeriod=
schedule.months=
schedule.days=
schedule.interval=
schedule.timezone.type=
schedule.timezone.targetIndex=
schedule.timezone.zoneOffset=
schedule.timezone.region=

If we wanted to schedule the previous backup job to run every day at 8:00 PM, we might add the following to the propery file before creating the job using it.

schedule.frequency=REPEAT_BY_DAYS
schedule.startTime=2013-08-31 20:00:00
schedule.interval=1
schedule.timezone.type=TIMEZONE_REGION_SPECIFIED
schedule.timezone.targetIndex=1
schedule.timezone.region=Europe/London

To remove a job with a regular schedule, we must first delete all scheduled runs, then delete the job.

$ emcli stop_job -name=test_emcli_job_1
Job "TEST_EMCLI_JOB_1" stopped successfully

$ emcli delete_job -name=test_emcli_job_1
Job "TEST_EMCLI_JOB_1" deleted successfully

$

This type of approach, coupled with the documentation should allow you to quickly figure out any available command.

For more information see:

Hope this helps. Regards Tim...

Back to the Top.