C
OEMUTIL Utility

OEMUTIL is a command-line utility that performs various job-related and event-related functions, providing a command-line alternative to performing these same operations from within the Enterprise Manager Console. This allows job and event-related operations to be submitted as batch jobs which can run unattended and later checked for completeness.

This chapter provides information on how to setup and use the OEMUTIL utility. This utility is available in both Enterprise Manager 2.2 and 9i. The following topics are discussed:

• Starting OEMUTIL

• Using OEMUTIL

• OEMUTIL Commands

• OEMUTIL Issues

Starting OEMUTIL

To enable OEMUTIL, set the environment variable ORACLE_OEM_CLIENTTRACE to "true" at the command line.

Windows NT or 2000:

>set ORACLE_OEM_CLIENTTRACE=true 

UNIX:

>setenv ORACLE_OEM_CLIENTTRACE=true 

Using OEMUTIL

OEMUTIL can perform a single function or command (e.g. submit a new Job) or perform multiple commands in succession. For example, you want OEMUTIL to submit job A and B from the job library, and then deregister Event C.

Performing a single command:

To use OEMUTIL to execute a single task, run OEMUTIL at the command line using the following syntax:

> oemapp oemutil <username>/<password>@<oms> <command> <parameters>

where:

• <username> is a valid Enterprise Manager administrator

• <password> is the Enterprise Administrator's password

• <oms> is the name of the machine running the Oracle Management Server

• <command><parameters> is the OEMUTIL command and its associated parameters.

Performing Commands in Succession:

You can use OEMUTIL to execute multiple commands in succession by first creating a single file consisting of the commands you want to execute and run OEMUTIL using the following syntax:

> oemapp oemutil -cmdfile <command file name> 

where:

• -cmdfile is the option that instructs OEMUTIL to accept a single file containing the commands to be executed.

• <command file name> is the name of the ASCII file containing the various commands you want to execute. The commands in the file will be executed in the order they are listed. The result of each command execution will be displayed sent to standard output. If one command in the sequence fails, then the failure is displayed and OEMUTIL proceeds to execute the next command in sequence.

  The command file may contain any number of commands. Each command must be on a separate line along with its corresponding arguments. Command arguments may be quoted if they have white space or special characters in them such as job and event names. Characters can be "escaped" by using the backslash character ('\'). For example, to insert a literal quote, use \" . A command file may look something like the following example.

Example C-1 Sample Command File

  omsCredentials sysman/sysman@myomsmachine 
  submitJob fileListing SYSMAN:dbs|oracle_sysman_group ls "-l" 
  submitJobFromLibrary backupJob sysman mypc.us.oracle.com 
  deregisterEvent spaceEvent sysman o817.mypc1 

OEMUTIL Commands

The following section summarizes all commands and associated parameters for OEMUTIL.

omsCredentials

The omsCredentials command specifies the credentials to use when logging into the Oracle Management Server. Logging in to the Management Server is required before any other command can be run. All subsequent commands in the command file will use these same credentials until the next omsCredentials command is encountered. There can be multiple omsCredentials commands in a single command file, allowing you to use a one batch command file to perform operations using any number of Management Servers.

Syntax

If you are going to use a batch command file with OEMUTIL, then the omsCredentials command is required and must be the first command in the command file.

If you are issuing commands directly to OEMUTIL (not providing a batch file), then the omsCredentials command is not required.

omsCredentials <username>/<password>@<oms> 

where:

Table C-1 omsCredentials Command Parameters

Example:

omsCredentials sysman/sysman@dlsun966 

submitJob

The submitJob command allows you to submit a new job against node(s). The job will be submitted with a schedule set to "Immediate".

Syntax

If running OEMUTIL with this single command, the syntax is:

oemapp oemutil <username>/<password>@<oms> submitJob <jobName> <nodeName> 
<osCommand> <osParameters>

If specifying this command in a command file, the syntax is:

submitJob <jobName> <nodeName> <osCommand> <osParameters>

Table C-2 submitJob Command Parameters

groupOwner:groupName|oracle_sysman_group. 

SYSMAN:dbs|oracle_sysman_group 

Success indicated by OEMUTIL means the job has been successfully submitted to the Management Server. Use the Enterprise Manager Console to monitor the actual status of the job.

You can also submit jobs that use different schedules such as 'on day of week' or 'on day of month' or jobs that run against other target types such as 'databases' or 'http servers', but the procedure is less direct:

1. Define the job using the Console.

2. Save the job to the Job Library.

3. Using OEMUTIL,submit the job from the library via the submitJobFromLibrary command. See the next section for information on the submitJobFromLibrary command.

submitJobFromLibrary

The submitJobFromLibrary command allows you to submit a job that is defined in the Job Library. The submitted job uses the properties of the job as it is defined in the Job Library (tasks, parameters, schedule, permissions, etc) except for job targets. The job target needs to be specified as a parameter to this command.

Syntax

If running OEMUTIL with this single command, the syntax is:

oemapp oemutil <username>/<password>@<oms>  submitJobFromLibrary  <jobName> 
<ownerName> <targetName> <admin to be notified>

If specifying this command in a command file, the syntax is:

submitJobFromLibrary <jobName> <ownerName> <targetName> <admin to be notified> 

Table C-3 submitJobFromLibrary Command Parameters

groupOwner:groupName|oracle_sysman_group.  

                                                                         
SYSMAN:dbs|oracle_sysman_group  

"SYSMAN:dbs|oracle_sysman_group" 

Success indicated by OEMUTIL means the job has been successfully submitted to the Management Server. Use the Console to monitor the actual status of the job.

registerEventFromLibrary

The registerEventFromLibrary command allows you to register an Event that is defined in the Event Library.

Syntax

If running OEMUTIL with this single command, the syntax is:

oemapp oemutil <username>/<password>@<oms> registerEventFromLibrary  <eventName> 
<ownerName> <targetName> <admin to be notified>

If specifying this command in a command file, the syntax is:

registerEventFromLibrary  <eventName> <ownerName> <targetName> <admin to be notified>

Table C-4 registerEventFromLibrary Command Parameters

                                                                         
groupOwner:groupName|oracle_sysman_group.  

SYSMAN:dbs|oracle_sysman_group  

Success in using this command means the event has been sent to the Management Server for registration. To confirm that the event has been registered with the Intelligent Agent, use the Enterprise Manager Console to verify that the status of the event is "Registered".

deregisterEvent

The deregisterEvent command allows you to deregister an Event.

Syntax

If running OEMUTIL with this single command, the syntax is:

oemapp oemutil <username>/<password>@<oms>  deregisterEvent <eventName>  <owner>  
<targetName>  <targettype>

If specifying this command in a command file, the syntax is:

deregisterEvent <eventName> <owner> <targetName> <targettype> 

Table C-5 deregisterEvent Command Parameters

changeCredentials

The changeCredentials command allows you to change preferred credentials for database targets in the Enterprise Manager repository.

This command does not apply to any other target type. It also does not change the credentials in the databases themselves, nor does it update the credentials in jobs and events that have already been submitted. Jobs already submitted and registered events must be subsequently de-registered/re-registered in order for them to get the new credentials.

Syntax

If running OEMUTIL with this single command, the syntax is:

oemapp oemutil <username>/<password>@<oms> changeCredentials  <EM username> 
<targetName> <user> <password> <role>

If specifying this command in a command file, the syntax is:

changeCredentials  <EM username> <targetName> <user> <password> <role> 

Table C-6 changeCredentials Command Parameters

OEMUTIL Issues

• For any command, if the target node name does not match the name displayed in the Console Navigator, you will receive the following error:

  oracle.sysman.emSDK.client.omsClient.BadAttributeException: VD-3: Some of the targets specified have been removed or do not have agents.

• The job used in the submitJobFromLibrary command must have at least one valid target when it is saved in the Job Library. Otherwise, an exception will occur.

• The event used in the registerEventFromLibrary command must have at least one valid target when it is saved in the Event Library. Otherwise, an exception will occur.

• If you specify an invalid database target using the changeCredentials command, the command will appear to succeed, but will have no effect.