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. The following topics are discussed:

• Starting OEMUTIL
• Using OEMUTIL
• OEMUTIL Commands

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

  Parameter	Value
  <username>	A valid Enterprise Manager administrator. This is the same account used to logon to the Enterprise Manager Console.
  <password>	The Enterprise Administrator's password
  <oms>	The name of the machine running the Oracle Management Server.

  .

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

Parameter	Value
username	Name of a valid Enterprise Manager user.
password	Corresponding password of Enterprise Manager user
oms	Name of the machine running the Management Server.
jobName	Name to assign to a job.
nodeName	Name of the target node where the job will run. The name must have been previously discovered in the Console. The name should match the discovered node name in the Navigator tree in the console. You may also specify a group name if you'd like to run the job against the multiple nodes in a group. Specify the group using the syntax: groupOwner:groupName|oracle_sysman_group. Example: To specify a group called dbs owned by sysman, use the syntax: SYSMAN:dbs|oracle_sysman_group If you are specifying a group as a command-line parameter to OEMUTIL, then you need to enclose the group name in quotes. For example: "SYSMAN:dbs|oracle_sysman_group"
osCommand	The OS command to run.
osParameters	Any parameters associated with the OS command.

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.

To 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', do the following:

1. Define the job using the Enterprise Manager 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.

Important: The job that is saved in the library must be assigned at least one valid target. However, when submitting this job from the library, the target you provide to the OEMUTIL command will be used.

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

Parameter	Value
username	Name of a valid Enterprise Manager administrator.
password	Enterprise Manager administrator's password.
oms	Name of the machine on which the Management Server is running.
jobName	Name of the job to be submitted. The name should match the name of the job as it is defined in the Job Library. If the job name has space, whitespaces or other special characters, then you will need to use the command file option. Put quotes around the name containing spaces, whitespaces or other special characters. Example: "ORCL backup_job"
ownerName	Name of the owner of the job to be submitted.
targetName	Name of the target against which the job is to be submitted. The target must have been discovered by the Intelligent Agent. The target name must match the name displayed in the Console Navigator tree. The target specified in this parameter will be used when submitting the job. Any targets predefined in the job as it exists in the Job Library will be ignored. To submit the job against multiple targets, define a group that contains these targets, and specify the group name as the target. Specify the group using the syntax: groupOwner:groupName|oracle_sysman_group. Example: To specify a group called "dbs" owned by sysman, use the syntax: SYSMAN:dbs|oracle_sysman_group If you are specifying a group as a command-line parameter to OEMUTIL, then you need to enclose the group name in quotes. Example: "SYSMAN:dbs|oracle_sysman_group"
admin	(optional) Name of the Enterprise Manager Administrator for whom Notify permissions are to be set. This Administrator must have at least View permissions for the job.

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.

Important: The event that is saved in the library must have at least one valid target. However, when registering this event from the library, the target provided to the OEMUTIL command will be used.

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

Parameter	Value
username	Name of a valid Enterprise Manager administrator.
password	Enterprise Manager administrator's password.
oms	Name of the machine on which the Management Server is running.
eventName	Name of the event to be submitted. The name should match the name of the event as it is defined in the Event Library. If the event name has space, whitespaces or other special characters, then you will need to use the command file option. Put quotes around the name containing spaces, whitespaces or other special characters. Example: "Check Tablespace usage"
ownerName	Name of the owner of the event to be submitted.
targetName	Name of the target against which the event is to be registered. The target must have been discovered by the Intelligent Agent. The target name must match the name displayed in the Console Navigator tree. To register the event against against multiple targets, define a group that contains these targets, and specify the group name as the target for this event. Specify the group using the syntax: groupOwner:groupName|oracle_sysman_group. Example: To specify a group called dbs owned by sysman, use the syntax: SYSMAN:dbs|oracle_sysman_group If you are specifying a group as a command-line parameter to OEMUTIL, then you need to enclose the group name in quotes. Example: "SYSMAN:dbs|oracle_sysman_group"
admin	(optional) Name of the Enterprise Manager Administrator for whom Notify permissions are to be set. This Administrator must have at least View permissions for event.

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

Parameter	Value
username	Name of a valid Enterprise Manager administrator.
password	Enterprise Manager administrator's password.
oms	Name of the machine on which the Management Server is running.
eventName	Name of the event to be deregistered. If the event name has space, whitespaces or other special characters, then you will need to use the command file option. Put quotes around the name containing spaces, whitespaces or other special characters. Example: "Check Tablespace usage"
owner	Name of the owner of the event. The owner is the Enterprise Manager Administrator who originally registered the event.
targetName	Name of the target against which the event is to be deregistered. The target must have been discovered by the Intelligent Agent. The target name must match the name displayed in the Console Navigator tree.
targettype	The type of target against which the event is to be deregistered. The valid target types are: oracle_sysman_database (Target is a database) oracle_sysman_node (Target is a node) oracle_sysman_listener (Target is a net listener) oracle_sysman_cmanager (Target is a concurrent manager) oracle_sysman_ops (Target is an Real Application Cluster node) oracle_sysman_webserver (Target is an apache webserver) oracle_sysman_hotstandby (Target is a standby database)

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. Previously submitted jobs and registered events must be subsequently de-registered and 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

Parameter	Value
username	Name of a valid Enterprise Manager administrator.
password	Enterprise Manager administrator's password.
oms	Name of the machine on which the Management Server is running.
EM username	Name of the Enterprise Manager Administrator whose database credentials are to be changed.
targetName	Name of the database target against which credentials are to be changed. If you are changing the DEFAULT database credentials, specify <default> as the targetName. If you use <default>, you might have to place quotes around the entry depending on your platform. For example, "<default>"
user	Name of the database user.
password	Password associated with database user.
role	Role associated with the database user: NORMAL, SYSDBA, SYSOPER The database user role must be specified.

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. 

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