Skip Headers
Oracle® Database Installation Guide
10g Release 1 (10.1) for hp OpenVMS Alpha
Part No. B13681-01
  Go To Table Of Contents
Go To Index


E Installing, Configuring, and Running EMAgent

This appendix describes Enterprise Manager Agent (EMAgent) for Oracle Database 10g release 1 ( It includes information about the following topics:

E.1 Introduction to EM Framework

This release of EMAgent is different from the previous releases of Oracle Intelligent Agent in terms of architecture and implementation. EMAgent is part of the Enterprise Manager Framework. The DBConsole and Application Control components are not supported on Oracle Database 10g for OpenVMS. To use EMAgent that is shipped with the Oracle Database bundle for hp OpenVMS Alpha, it is necessary to install the Oracle Management Server (OMS) component of Grid Control Enterprise Manager on a UNIX-based or Microsoft Windows-based computer. EMAgent running on OpenVMS will register with and function in coordination with the OMS.

EMAgent version shipped with Oracle Database 10g will not work with Enterprise Manager used with previous releases.

EMAgent is implemented in C, Java, and Perl. Unlike earlier versions, TCL scripts are no longer used. These are replaced by Perl scripts. Perl version 5.6 is included in Oracle Database Server Kit. Oracle Universal Installer automatically installs Perl. It is not required to install a separate Perl kit. Note that this kit includes Oracle-specific DBD or DBI, and is therefore, the only supported Perl kit for use with Oracle Database. The logical PERL_ROOT will be defined to the physical path ORA_ROOT:[PERL] as a job level logical. To avoid potential conflict with Perl from any other kit, including any future versions supplied by Oracle, it is recommended not to convert this logical to a GROUP or SYSTEM logical.

The Job model supported in previous releases is still available in this release in a similar, but not identical, fashion. Jobs can be submitted, their status can be monitored, and their output checked. The Event model, as it existed in earlier versions, is no longer available. Instead, what is available is Targets. Refer to Section E.5, "Supported Targets and Jobs" for more information.

See Also:

For more details, refer to the readme_vms_10gr1.txt file shipped with the Oracle Database Server Kit. The information in this file supercedes the information in this appendix

E.2 Installation Requirements

EMAgent has been implemented to run in a batch queue. It is necessary to specify the name of a batch queue either prior to or after installation. You must define a logical ORA_BATCH_QUEUE_hostname (a Process or Job logical is sufficient) to the name of the batch queue to be used for running EMAgent. In addition to running in the batch queue, EMAgent also submits a number of other tasks, typically related to actions required on other Oracle installations on the same host.

The hostname part of the logical should be the same as the value of the TCPIP$INET_HOST logical. The batch queue specified should run at the same priority level as all other general purpose processes on the system, typically 4.

For example, a typical batch queue recommended is as follows:


EMAgent internally spawns a number of subprocesses and detached processes to run a majority of its tasks. The type of actions performed in these processes ranges widely from running simple DCL commands to running Java applications. It is imperative that the account used to install and run EMAgent not modify the typical OpenVMS session environment in any way that would alter the expected output of normal DCL commands. The file of the account used to start or stop the agent should not have any such redefinitions. If the redefinitions are required for any reason, then it is recommended that they be disabled in the batch mode, because EMAgent runs in the batch mode.

E.3 Installation and Configuration

When you initially run Oracle Universal Installer, it instantiates certain files under the ORA_ROOT:[SYSMAN.EMD] and ORA_ROOT:[SYSMAN.CONFIG] directories. These are the Targets files and the Properties files. However, these cannot be used directly. EMAgent is configured correctly when DBCA is run. The configuration files are created under a separate directory structure (ORA_ROOT:[Hostname_SID.SYSMAN...]). Because the DB Console is not supported on OpenVMS, it is necessary to make certain manual changes to the configuration file or files before starting EMAgent.

Manual Changes Required Before Attempting to Start EMAgent

You must manually change the following properties in the ORA_ROOT:[Hostname_SID.SYSMAN.CONFIG] file before starting EMAgent.


    This property is required to allow EMAgent to upload data to a central Grid Control EM Repository. When EMAgent starts, it registers its targets and other host configuration information with the Oracle Management Server (OMS) so that they are displayed on the Grid Control EM Console. It is then possible to manage the targets from the EM Console. A sample REPOSITORY_URL property is as follows:

  2. agentTZRegion

    This property indicates the time zone in which EMAgent is running. To update this property in the file, run the following command:

    $ emctl config agent updateTZ

    A sample agentTZRegion property for Pacific Standard Time is as follows:


E.4 Management and Maintenance

This section describes the procedures to manage and maintain EMAgent.

E.4.1 Startup, Shutdown, and Status

Perform the following steps to start, shut down, or view the status of EMAgent:

  • After the manual configuration is complete, run the following command to start EMAgent:

    $ emctl start agent
  • To shut down EMAgent, run the following command:

    $ emctl stop agent
  • To query the status of EMAgent at any time, run the following command:

    $ emctl status agent


EMAgent is the only mechanism of communication between the Oracle Management Server and targets or applications running on the host. Therefore, it is not possible to start up or shut down EMAgent from the EM Console.

E.4.2 Troubleshooting and Maintenance

Perform the following tasks to manage or troubleshoot EMAgent:

E.4.2.1 EMAgent Fails to Start

If EMAgent fails to start, check the following files for typical error messages:

Batch Job Log File

EMAgent is submitted as a batch job into the agent batch queue whenever it is started. Each time EMAgent starts, a fresh batch log file is created, which is available at ORA_ROOT:[SYSMAN.LOG]start_agent_host.log. Refer to the latest version of this log file. If it is readable (not locked by a running EMAgent process), look through the file to see if there are any failure messages. Typical errors would be Failure to launch the EMAgent because of some issues with related shared libraries.

EMAgent Log and Trace Files

If there are no errors in ORA_ROOT:[SYSMAN.LOG]start_agent_host.log, look at the emagent.trc and emagent.log files. These are located in the ora_root:[host_sid.sysman.log] directory. A common error is Address already in use, when the port number on which EMAgent is listening is being used by some other application.

E.4.2.2 Extended File Specification (EFS) Characteristics

EMAgent requires an extended file-specifications environment to handle files with multiple dots in their names, long file names, and so on. The default Oracle environment (after running does not provide this environment. Internally, EMAgent tools set up this extended environment when started, and reset the environment back to the original when completed. In a normal run, it is not necessary for an EMAgent administrator to require this environment for interactive use. However, in certain situations, when there are failures due to interruption in the host system, or due to lack of resources, it may be required to manually manipulate certain files, which in turn, would need the EFS environment.

There are two scripts included with EMAgent kit that provides the EFS environment:


    Sets the EFS environment that includes extended parsing, extended file names, and so on.


    Resets the environment back to normal, that is, traditional parsing, standard file names, and so on.

For convenience, two DCL symbols have been created to set and reset the EFS environment. Symbol EMDEFS sets the EFS environment, and symbol NOEMDEFS resets the EFS environment.

E.4.2.3 TMP Directory

EMAgent run time creates a number of temporary files during processing. All temporary files are created in a directory linked to the logical ORA_AGENT_TMP. This logical is automatically defined to the physical path, ORA_ROOT:[], when setting up the Oracle environment.

It is possible that certain temporary files may not get cleaned out due to interruptions, failures, and so on. It is recommended that this directory content be monitored on a periodic basis and cleaned out if it has files that are more than three hours old.

E.4.2.4 Monitoring the Batch Queue

As mentioned in Section E.2, "Installation Requirements", EMAgent runs as a batch job in a batch queue. EMAgent also submits a number of jobs to the batch queue for tasks related to monitoring, start up, shut down, and so on, of databases, listeners, and so on, running in other Oracle installations. There is a possibility that broken environments in these installations could cause these submitted jobs to stop responding. It is recommended that the batch queue be periodically monitored for any long-pending jobs (any job of more than three hours is long-pending) and such jobs be deleted.

E.4.2.5 Disk Space on EMAgent Install Area

There are two agent parameters listed in the properties file related to disk space:

  • UploadMaxDiskUsedPct

  • UploadMaxDiskUsedPctFloor

Ensure that the agent parameters are set correctly at the required level. When the value of max disk pct used exceeds, uploads will stop and all subsequent updates from EMAgent to the Oracle Management Server also will stop. At this time, while querying EMAgent status would show it as up and running, the line reporting Last Successful Upload would show a time stamp that would remain the same over a longer period. Comparing this with the value of the UploadInterval parameter in the file would reflect the correct status of uploads.

E.4.2.6 Resetting EMAgent Environment

You can shut down EMAgent that is already running, and reconfigure it to point to a different Oracle Management Server. To reset EMAgent environment, it is recommended to perform the following tasks:

  1. Delete the ora_root:[host_sid.sysman.emd]lastupld.xml;* file.

  2. Delete all files in the ora_root:[host_id.sysman.emd.upload] directory.

  3. Delete all files in the ora_root:[host_id.sysman.emd.state] directory.

  4. Delete all files in the ora_root:[host_id.sysman.emd.collection] directory.

  5. Delete all files in the ora_root:[host_id.sysman.emd.recv] directory.

  6. Rename or delete EMAgent log and trace files:


E.5 Supported Targets and Jobs

The following targets and jobs are supported by EMAgent.


EMAgent supports the following targets:

When EMAgent is started, EMAgent reads the targets.xml file in the EMSTATE directory, and registers those targets with the Oracle Management Server. The status of each of the targets is reflected under the Targets tab of the EM Console. EMAgent monitors the registered targets on a periodic basis and uploads the status of the targets to the Oracle Management Server, which is reflected on the EM Console. In addition, a set of predefined metrics are also collected for each target and uploaded to the Oracle Management Server. Default thresholds are defined for each predefined metric on the Oracle Management Server. When a threshold is reached, an alert is generated and displayed on the console. This mechanism of automatic target monitoring replaces the Events model of earlier releases. For more information about targets, refer to Oracle® Enterprise Manager Concepts 10g release 1 (10.1).


The following jobs are supported by EMAgent:

E.6 Known Limitations

EMAgent has the following known limitations:

  1. Jobs will always indicate a successful completion status, as long as the agent has been able to create a detached process and run the command specified for the job. The status of job completion is not a reflection of the completion status of the job command. If the command fails for some reason, then the job itself will not be indicated as a failure, but the output of the job needs to be checked to verify if the command has succeeded or not.

  2. The metric browser does not support all metrics. All metrices in the host metrics area are not applicable to Oracle Database. For more details, refer to the readme_vms_10gr1.txt file shipped with the Oracle Database Server Kit.