Skip Headers

Oracle® Process Manager and Notification Server Administrator's Guide 10g Release 3 (10.1.3) B15976-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 4 opmnctl Commands

This chapter provides an overview of `opmnctl` commands for Oracle Application Server components managed by OPMN. It features the following topics:

- Section 4.1, "opmnctl"

- Section 4.2, "opmnctl Command Quick Reference"

- Section 4.3, "opmnctl Detailed Command Description"

## 4.1 opmnctl

```opmnctl` is the supported tool for starting and stopping all components in an Oracle Application Server instance, with the exception of the Oracle Enterprise Manager 10g Application Server Control Console (Application Server Control Console). `opmnctl` provides a centralized way to control and monitor Oracle Application Server components from the command line. You can use `opmnctl` to execute control and monitoring commands across multiple Oracle Application Server instances simultaneously.``

`opmnctl` also enables you to perform operations on a specified Oracle Application Server instance in a cluster or all instances in a cluster using an optional parameter called `scope`. You can also use the `scope` option to control an individual Oracle Application Server process.

The `opmnctl` command is located in the following directory locations:

(Linux) `ORACLE_HOME``/opmn/bin/opmnctl`

(Microsoft Windows) `ORACLE_HOME``\opmn\bin\opmnctl`

Note: Oracle Application Server components managed by OPMN should never be started or stopped manually. Do not use command line scripts or utilities from previous versions of Oracle Application Server for starting and stopping Oracle Application Server components. Use the Application Server Control Console and the `opmnctl` command line utility to start or stop Oracle Application Server components.

Note: Oracle recommends starting OPMN as the user that has installed Oracle Application Server.

### 4.1.1 opmnctl Syntax

The following command shows an example of the syntax of the `opmnctl` command:

    opmnctl [verbose] [<scope>] <command> [<options>]

Table 4-1 provides a description about `opmnctl` syntax.

Table 4-1 opmnctl Syntax

Syntax | Description
--- | ---
verbose | Prints detailed execution message, if available.
scope | Specifies where the request is routed. Refer to Section 4.3.1.1, "Scope" for a list of options.
command | Specifies an `opmnctl` command. Refer to Example 4-1 for a list of commands.
options | Specifies options for the command. Refer to Section 4.3.4.1.1, "Options for the Status Command of opmnctl" for a list of options.

## 4.2 opmnctl Command Quick Reference

Example 4-1 lists `opmnctl` commands for quick reference. You can obtain the same output information by executing the `opmnctl help` command.

Example 4-1 opmnctl Commands

    prompt > opmnctl help

      scope      command      options
    _________   __________   __________
                start                         - Start opmn
                startall                      - Start opmn and all managed processes
                stopall                       - Stop opmn and all managed processes
                shutdown                      - Shutdown opmn and all managed processes
    [<scope>]   startproc   [<attr>=<val>..]  - Start opmn managed processes
    [<scope>]   restartproc [<attr>=<val>..]  - Restart opmn managed processes
    [<scope>]   stopproc    [<attr>=<val>..]  - Stop opmn managed processes
    [<scope>]   reload                        - Trigger opmn to reread opmn.xml
    [<scope>]   status      [<options>]       - Get managed process status
    [<scope>]   dmsdump     [<attr>=<val>&..] - Get DMS stats
    [<scope>}   set         [<attr>=<val> ..] - Set opmn log parameters
    [<scope>]   query       [<attr>=<val> ..] - Query opmn log parameters
                ping        [<max_retry>]     - Ping local opmn
                validate    [<filename>]      - Validate the given xml file
                config      [<options>]       - Modify the opmn xml file
                help                          - Print brief usage description
                usage       [<command>]       - Print detailed usage description

## 4.3 opmnctl Detailed Command Description

The following sections contains detailed descriptions of the `opmnctl` commands listed in Example 4-1. The `opmnctl` commands are displayed in the following sections:

- Section 4.3.1, "Command Definitions"

- Section 4.3.2, "Server Control Commands"

- Section 4.3.3, "Process Control Commands"

- Section 4.3.4, "Status Commands"

- Section 4.3.5, "Help Commands"

### 4.3.1 Command Definitions

`opmnctl` features command definitions that enable you to further define the action you would like to execute with OPMN.

This section describes the command definitions available with the `opmnctl` command. It includes the following sections:

- Section 4.3.1.1, "Scope"

- Section 4.3.1.2, "Attributes"

- Section 4.3.1.3, "Verbose"

#### 4.3.1.1 Scope

Syntax: `@instance[:instname[:instname...]]`

`@cluster[:clusname[:clusname...]]`

The `scope` option specifies which Oracle Application Server instances the `opmnctl` command applies to. You can use the scope option for `opmnctl` commands for single or multiple Oracle Application Server instances and clusters.

- `@instance:` If you do not specify a name after `@instance` option, the `opmnctl` command is applied to the local Oracle Application Server instance; local refers to the Oracle Application Server instance or cluster containing the OPMN server handling the request. The default is the local Oracle Application Server instance. If the `@instance` option is followed by Oracle Application Server instance names, the request will be routed to Oracle Application Server instances. To apply the command to one or more Oracle Application Server instances, specify `@instance[:instname[:instname...]]`.

- `@cluster:` If you do not specify a name after `@cluster` option, the `opmnctl` command is applied to the local Oracle Application Server cluster. If `@cluster` is followed by a set of 1 or more cluster names, the request will be routed to the all Oracle Application Server instances contained in the specified Oracle Application Server clusters. To apply the command to all Oracle Application Server instances within one or more Oracle Application Server clusters, specify `@cluster[:clusname[:clusname...]]`.

For example, the following command starts OC4J on Oracle Application Server instance named "`myInst2.foo.com`":

    prompt > opmnctl @instance:myInst2.foo.com startproc ias-component=HTTP_Server

See Also: Chapter 5, "Using OPMN"

#### 4.3.1.2 Attributes

syntax: `<attribute>=<value>`

The `opmnctl` attributes enable you to apply process control operations to specific Oracle Application Server components.

For example, the following command starts all Oracle Application Server processes configured for OracleAS Wireless:

    prompt > opmnctl startproc ias-component=wireless

Refer to Chapter 5, "Using OPMN" for additional `opmnctl` command examples.

Table 4-2 lists the attribute names and values that can be used with the `opmnctl` command:

Table 4-2 opmnctl Attribute Names and Values

Attribute Name | Attribute Values
--- | ---
`ias-component` | Value should be the same as the value for the `id` attribute for the `<ias-component>` element in the `opmn.xml` file.
`process-type` | Value should be the same as the value for the `id` attribute for the `<process-type>` element in the `opmn.xml` file.
`process-set` | Value should be the same as the value for the `id` attribute for the `<process-set>` element in the `opmn.xml` file.
`mode` | Value can either be `sync` or `async`. The default value is "`sync`, meaning that this request operates synchronously, and waits for the operation to complete before returning. "`async` indicates that the request returns immediately, while OPMN continues to perform the request until the operation finishes.
`timeout` | This can only be specified in sync mode. The value is in seconds. After this timeout expires, OPMN does not continue to perform the request for `startproc` operations. The request does continue for `restartproc` and `stopproc` operations.
`uniqueid` | This value is assigned by OPMN after starting up. You can use this value when you execute the `opmnctl` `restartproc` and `opmnctl` `stopproc` commands.

See Also: Chapter 5, "Using OPMN"

#### 4.3.1.3 Verbose

Syntax: `opmnctl verbose command`

The `opmnctl` `verbose` option enables you to obtain detailed information about the command you are executing.

For example, the following command outputs the information shown in Example 4-2:

    prompt> opmnctl verbose startproc ias-component=HTTP_Server

Example 4-2 opmnctl verbose output

    HTTP/1.1 200 OK
    Content-Length: 0
    Content-Type: text/html
    Response: Ping succeeded.

    opmnctl: starting opmn managed processes...
    HTTP/1.1 200 OK
    Content-Length: 571
    Content-Type: text/html
    Response: 1 of 1 processes started.

    <response>
    <opmn id="jerichar-sun.us.oracle.com:6200" http-status="200" http-response="1 of 1
     processes started.">
       <ias-instance id="M140801.jerichar-sun.us.oracle.com">
          <ias-component id="HTTP_Server">
             <process-type id="HTTP_Server">
                <process-set id="HTTP_Server">
                   <process id="1954086921" pid="9355" status="Alive" index="1"
                    log="/home/demoas/M140801/opmn/logs/HTTP_Server~1"
                   operation="request" result="success">
                   </process>
                </process-set>
             </process-type>
          </ias-component>
       </ias-instance>
    </opmn>
    </response>

### 4.3.2 Server Control Commands

The `opmnctl start, startall, reload, stopall,` and `shutdown` commands enable you to control the OPMN server.

- Section 4.3.2.1, "Server Control Commands on Microsoft Windows"

- Section 4.3.2.2, "opmnctl start"

- Section 4.3.2.3, "opmnctl startall"

- Section 4.3.2.4, "opmnctl stopall"

- Section 4.3.2.5, "opmnctl shutdown"

- Section 4.3.2.6, "opmnctl reload"

Output is not generated for the successful execution of an `opmnctl` server control command. Refer to Appendix A, "OPMN Troubleshooting" if you receive any error messages during `opmnctl` command execution.

#### 4.3.2.1 Server Control Commands on Microsoft Windows

On the Microsoft Windows operating system, OPMN is installed as a Windows service `(Oracle<OracleHomename>ProcessManager)` and it starts up automatically when you restart your computer. When you start or stop OPMN using Windows Services you start or stop all OPMN-managed components on the local instance.

Use the Application Server Control Console and the `opmnctl` command line utility to start or stop Oracle Application Server components.

#### 4.3.2.2 opmnctl start

Syntax: `opmnctl start`

Use this command to start the OPMN server for a local Oracle Application Server instance without starting OPMN-managed processes.

Execute this command as soon as possible after starting your computer.

Note: OPMN starts up automatically on Microsoft Windows when you start or restart your computer. All OPMN-managed processes are also started.

See Also: Chapter 5, "Using OPMN"

#### 4.3.2.3 opmnctl startall

Syntax: `opmnctl startall [timeout=<``seconds``>]`

Use this command to start OPMN as well as the OPMN managed processes for a local Oracle Application Server instance. The `startall` is equivalent to the `start` command and the `startproc` command without arguments. Oracle recommends using the `start` or `startproc` command.

This command operates synchronously and waits for the operation to complete before returning. To set a timeout for the request, specify the timeout value in seconds.

Components with `id-matching="true"` will not be started.

Enter the following command for additional detailed information:

    prompt > opmnctl usage startall
    stopall
    start startall startproc

On Microsoft Windows, you can also perform an `opmnctl startall` by starting the `Oracle<OracleHomename>ProcessManager` service in the Windows services control panel. The `Oracle<OracleHomename>ProcessManager` starts automatically when you start or restart your computer.

#### 4.3.2.4 opmnctl stopall

Syntax: `opmnctl stopall`

Use the `opmnctl stopall` command to shut down the OPMN server as well as the OPMN-managed processes for the local Oracle Application Server instance. This request operates synchronously; it waits for the operation to complete before returning.

Shutting down the OPMN server is not necessary during normal operation. Shutting down the OPMN server prevents remote commands to OPMN from executing on the Oracle Application Server instance until OPMN is restarted.

The `opmnctl stopall` command should only be executed prior to shutting down OPMN and your computer. This request first tries to stop all OPMN-managed processes gracefully. Processes which will not stop gracefully will be forcefully shutdown. After stopping all managed processes, the OPMN daemon will shutdown itself.

The `opmnctl stopall` command should only be used when it is necessary to stop the OPMN daemon. Once started, the OPMN daemon should remain up until it is necessary to restart the computer or some other unforeseen administrative event occurs.To stop all OPMN-managed processes without stopping the OPMN daemon, consider using the `opmnctl stopproc` command without any arguments.To restart the OPMN daemon without restarting any OPMN-managed processes, consider using the `opmnctl reload` command. The `opmnctl reload` command is the appropriate command to use when the only goal is to restart the opmn daemon with a new configuration.

Use the `opmnctl stopproc` command if you want to stop all OPMN managed processes.

Use the `opmnctl reload` if you want OPMN to reread its configuration.

Enter one of the following commands to obtain additional information:

    prompt > opmnctl usage stopall

or

    prompt > opmnctl usage shutdown

#### 4.3.2.5 opmnctl shutdown

Syntax: `opmnctl shutdown`

Use the `opmnctl shutdown` command to shut down the OPMN server as well as the OPMN-managed processes for the local Oracle Application Server instance.

The `opmnctl shutdown` command quickly shutdowns the OPMN daemon and OPMN-managed processes for the local Oracle Application Server instance.The `opmnctl shutdown` command is similar to the `opmnctl stopall` command but waits less time before initiating a forceful termination of OPMN-managed processes. After all of the OPMN-managed processes are stopped, the OPMN daemon will shutdown itself.The `opmnctl shutdown` command should only be performed when it is necessary to stop the OPMN daemon. Once started, the OPMN daemon should remain up until it is necessary to restart the computer or some other unforeseen administrative event occurs.To stop all OPMN-managed processes without stopping the OPMN daemon, consider using the `opmnctl stopproc` command without any arguments.To restart the OPMN daemon without restarting any OPMN-managed processes, consider using the `opmnctl reload` command. The `opmnctl reload` command is the appropriate command to use when the objective is to restart the OPMN daemon with a new configuration.

On Microsoft Windows, you can also perform an `opmnctl shutdown` by stopping the `Oracle<OracleHomename>ProcessManager` service in the Windows services control panel.

Use the `opmnctl stopproc` command if you want to stop all OPMN managed processes.

Use the `opmnctl reload` if you want OPMN to reread its configuration.

Enter one of the following commands to obtain additional information:

    prompt > opmnctl usage stopall

or

    prompt > opmnctl usage shutdown

#### 4.3.2.6 opmnctl reload

Syntax: `opmnctl [``scope``] reload`

Use this command to trigger the OPMN to reread its configuration files in the requested scope. This command restarts the OPMN server without restarting any Oracle Application Server processes managed by OPMN. The OPMN server for the Oracle Application Server instance must be up and running.

Note: On Microsoft Windows, you can highlight the `Oracle<OracleHomename>ProcessManager` in the services control panel and select Restart. The restart of the service is not equivalent to an `opmnctl reload`, however. This action is equivalent to an `opmnctl shutdown` followed by an `opmnctl startall`. It is a much slower operation than `opmnctl reload` because it restarts OPMN and all the processes managed by OPMN.

Enter the following command for additional detailed information:

    prompt > opmnctl usage reload

See Also: Section 4.3.1, "Command Definitions"

### 4.3.3 Process Control Commands

The `opmnctl` process control commands enable you to start, stop, or restart single or multiple Oracle Application Server components. You can control an Oracle Application Server component at the `<ias-component>`, `<process-set>`, or `<process-type>` level.

This section describes the process control commands available with `opmnctl`. It includes the following process control commands:

- Section 4.3.3.1, "opmnctl startproc, opmnctl restartproc and opmnctl stopproc"

- Section 4.3.3.2, "Progressive Request Reports"

- Section 4.3.3.3, "Sequential Requests"

- Section 4.3.3.4, "opmnctl config"

- Section 4.3.3.5, "Starting a Specific J2EE Application"

Output is not generated for the successful execution of an `opmnctl` process control command. Refer to Appendix A, "OPMN Troubleshooting" if you receive any error messages during `opmnctl` command execution.

#### 4.3.3.1 opmnctl startproc, opmnctl restartproc and opmnctl stopproc

Syntax: `opmnctl [<``scope``>] startproc [<``attr``>=<``value``>...]`

`opmnctl [<``scope``>] restartproc [<``attr``>=<``value``>...]`

`opmnctl [<``scope``>] stopproc [<``attr``>=<``value``>...]`

Use these commands to start, restart, or stop OPMN-managed processes in the requested scope. The OPMN server for the Oracle Application Server instance must be up and running.

The following attributes and values can be used with the `startproc, stopproc,` and `restartproc` commands:

- `ias-component, process-type,` and`process-set:` The values for these attributes should be the same as the `id` value specified in the `opmn.xml` file. If no attribute is supplied, the command is applied to all OPMN-managed processes other than those that are configured in the `opmn.xml` file with `id-matching="true"`. To execute commands on components configured with `id-matching="true"`, it is necessary to specify the `ias-component` argument.

- `mode`: The `mode` attribute value can be either `sync` or `async`; the default value is `sync`. The `sync` value for mode causes the `opmnctl` command to operate synchronously and wait for the command to be executed completely before a return prompt is displayed. The timeout element can only be specified when the value of mode is `sync`. The value is specified in number of seconds. After the specified timeout expires, the operation is aborted for `startproc` but not for `restartproc` or `stopproc.` `T`he `opmnctl` command prompt returns, the OPMN server continues to perform the `opmnctl` `restartproc` or `stopproc` command request until the operation is finished.

  The `async` value for mode causes the return prompt to be displayed immediately, while the OPMN server continues to perform the `opmnctl` command request until the operation is finished.

- `uniqueid:` This value is assigned by OPMN after starting up. You can use this value when you execute the `restartproc` and `stopproc` commands. You can obtain this value by entering the following command and obtaining the unique number for the Oracle Application Server component in the `uid` column of the generated output:

      prompt > opmnctl status -l

Attribute names other than those listed may be specified for some types of Oracle Application Server processes managed by OPMN. Unique attribute name should be specific to each type of Oracle Application Server process.

Using the `opmnctl startproc, restartproc,` or `stopproc` commands with a specified scope and attributes enables control of specific processes in your enterprise. You can execute the `opmnctl startproc, restartproc,` or `stopproc` commands at the `<ias-component>`, `<process-type>` and the `<process-set>` level.

For example, the following command starts OracleAS Wireless at the `<process-set>` level:

    prompt > opmnctl startproc ias-component=wireless process-type=alert_server process-set=alert_instance_1

The following command restarts OC4J at the `<process-type>` level:

    prompt > opmnctl restartproc ias-component=OC4J process-type=home

The following command stops Oracle HTTP Server at the `<ias-component>` level:

    prompt > opmnctl stopproc ias-component=HTTP_Server

Enter one of the following commands to obtain additional information:

    prompt > opmnctl usage startproc

or

    prompt > opmnctl usage restartproc

or

    prompt > opmnctl usage stopproc

See Also: Section 4.3.1, "Command Definitions" Chapter 5, "Using OPMN"

#### 4.3.3.2 Progressive Request Reports

The `report=true` attribute when used with `startproc`, `restartproc`, or `stopproc` enables OPMN to report back on each part of a request as it completes. For example, if an `opmnctl startproc` request will attempt to start 4 processes, OPMN will report back to the user the result of each process start attempt as soon as it completes. This attribute works on scoped requests in the same way.

For example, the following shows the reports display when a request is issued:

1. `% opmnctl @instance:your_company:ias_stado17_1 startproc report=true opmnctl: starting opmn managed processes..`.

2. `% opmnctl @instance:your_company:ias_stado17_1 startproc report=true opmnctl: starting opmn managed processes...`

   `ias_stado17_1/HTTP_Server/HTTP_Server/HTTP_Server/1,86061,17501: success`

   `ias_stado17_1/ppid/ppid/ppid/1,86063,17503: success`

3. `% opmnctl @instance:your_company:ias_stado17_1 startproc report=true opmnctl: starting opmn managed processes...`

   `ias_stado17_1/HTTP_Server/HTTP_Server/HTTP_Server/1,86061,17501: success`

   `ias_stado17_1/ppid/ppid/ppid/1,86063,17503: success`

   `your_company/HTTP_Server/HTTP_Server/HTTP_Server/1,2452,11833: success`

4. `% opmnctl @instance:your_company:ias_stado17_1 startproc report=true opmnctl: starting opmn managed processes...`

   `ias_stado17_1/HTTP_Server/HTTP_Server/HTTP_Server/1,86061,17501: success`

   `ias_stado17_1/ppid/ppid/ppid/1,86063,17503: success`

   `your_company/HTTP_Server/HTTP_Server/HTTP_Server/1,2452,11833: success`

   `ias_stado17_1/OC4J/home/default_group/1,86062,17502: success`

   `ias_stado17_1: 3 of 3 processes started.`

5. `% opmnctl @instance:your_company:ias_stado17_1 startproc report=true opmnctl: starting opmn managed processes...`

   `ias_stado17_1/HTTP_Server/HTTP_Server/HTTP_Server/1,86061,17501: success`

   `ias_stado17_1/ppid/ppid/ppid/1,86063,17503: success`

   `your_company/HTTP_Server/HTTP_Server/HTTP_Server/1,2452,11833: success`

   `ias_stado17_1/OC4J/home/default_group/1,86062,17502: success`

   `ias_stado17_1: 3 of 3 processes started.`

   `your_company/OC4J/home/default_group/1,2451,11851: failure`

   `failed to start a managed process after the maximum retry limit`

   `Log:/private/oracle/OraHome_1/opmn/logs/OC4J~home~default_group~1 your_company: 1 of 2 processes started.`

#### 4.3.3.3 Sequential Requests

By default an OPMN request is run for all affected processes at the same time, unless a dependency dictates a specific ordering. If the attribute `sequential=true` is specified when used with the `startproc`, `restartproc`, or `stopproc` command, then OPMN will only run the request on a single process at a time, waiting for the request to complete on the first before running the request on the second. When the request has finished on one process, it works on the next.

Note that dependencies are still honoured, and take part in the request sequentially as well.

As shown in Figure 4-1, by default OPMN issues jobs for all processes in parallel such that they run at the same time (except when honoring dependencies). For example, with the following command:

    > opmnctl startproc ias-component=OC4J

Figure 4-1 OC4J Processes in Parallel

Description of "Figure 4-1 OC4J Processes in Parallel"

If the sequential attribute is set to true, OPMN will only perform the request upon one process at a time (shown in Figure 4-2).

For example the following command:

    % opmnctl startproc ias-component=OC4J sequential=true

starts all of the OC4J processes sequentially.

Figure 4-2 OC4J Process Sequential Request #1

Description of "Figure 4-2 OC4J Process Sequential Request #1"

OPMN is processing one OC4J process, before moving on the next shown in Figure 4-3.

As shown in Figure 4-3, when the request completes for the first OC4J process, the request starts on the next OC4J process.

Figure 4-3 OC4J Process Sequential Request #2

Description of "Figure 4-3 OC4J Process Sequential Request #2"

As shown in Figure 4-4, all affected OC4J processes have completed the request.

Figure 4-4 OC4J Process Sequential Request #3

Description of "Figure 4-4 OC4J Process Sequential Request #3"

#### 4.3.3.4 opmnctl config

Syntax: `opmnctl config` `<``target``> <``operation``> <``options``>`

The `opmnctl config` command enables you to execute configuration operations on either the `topology` or `port` element of the `opmn.xml` file using the command line. You do not need to access the `opmn.xml` file to perform a `topology` or `port` configuration.

`<target>` = `topology` or `port`

`<operation>` = `update` or `delete`

`<options>` = the use of this parameter is dependent on your selection for the `<target>` and `<operation>` arguments

The `topology` target is used to configure the `discover` element in the `opmn.xml` file. The `discover` element provides a list of discovery service addresses. The local OPMN server will use the discover element to find and connect with remote OPMN servers in the same cluster. You can configure multiple discover elements.The arguments for the `topology` command are:

- `update`: for the `update` parameter, a `discover` attribute with a value is required. The format is `discover=<value>` where the value is the discovery service address.

- `delete`: for the `delete` parameter, a discover attribute is required but no value needs to be supplied.

The following examples show usage of the described arguments and parameters:

- Update the discover attribute in the `opmn.xml` file with the discovery service address of *234.5.6.7.8910:

      > opmnctl config topology update discover="*234.5.6.7:8910"

- Delete the discover attribute in the `opmn.xml` file:

      > opmnctl config topology delete discover

The `port` target is used to configure the port elements in the `opmn.xml` file. The arguments for the `port` command are:

- `ias-component=<id>`: this argument specifies the ias-component in which the port element resides.

- `process-type=<id>`: this argument specifies the process-type in which the port element resides.

- `portid=<id>`: this argument specifies the port ID that needs to updated or deleted.

- `range=<port range>`: optional argument for the update operation. This parameter is invalid for the delete operation.

- `protocol=<port protocol>`: optional argument for the update operation. This is an invalid argument for the delete operation.

The following examples show usage of the described arguments and parameters:

- Update the default Web site port element for the OC4J `ias-component` element, in the `home process-type` using HTTP protocol:

      > opmnctl config port update ias-component=OC4J process-type=home
        portid=default-web-site protocol=http

- Delete the default Web site port element for the OC4J `ias-component` element, in the `home process-type`:

      > opmnctl config port delete ias-component=OC4J process-type=home portid=default-web-site

#### 4.3.3.5 Starting a Specific J2EE Application

You can start or stop your J2EE based application using the `application` attribute. You can use this attribute with the `startproc`, `restartproc`, or `stopproc`, `opmnctl` commands.

For example:

- `prompt > opmnctl startproc application=mailserver`

  Start the application `mailserver` on every process in the local Oracle Application Server instance that has the application `mailserver`.

- `prompt > opmnctl @cluster startproc application=password-manager`

  Start the`password-manager` application on every process in the entire Oracle Application Server cluster that has the `password-manager` application

- `prompt > opmnctl @cluster startproc process-type=home application=web-module`

  Start the application `web-module` on every process in the entire Oracle Application Server cluster that belongs to the`process-type` named `home` and has the application `web-module`.

- `prompt > opmnctl @instance:inst1:inst2:inst3 startproc process-type=home application=web-module`

  Start the application `web-module` on every process in the three named Oracle Application Server instances that belong to the `process-type` named `home` and has the application `web-module`.

### 4.3.4 Status Commands

The `opmnctl` `status` commands enable you to determine the status of OPMN-managed processes.

This section describes the command options available with the `opmnctl` command. It includes the following sections:

- Section 4.3.4.1, "opmnctl status"

- Section 4.3.4.2, "opmnctl dmsdump"

- Section 4.3.4.3, "opmnctl ping"

- Section 4.3.4.4, "opmnctl set"

- Section 4.3.4.5, "opmnctl query"

See Also: Section 4.3.1.1, "Scope" Section 4.3.1.2, "Attributes" Section 4.3.4.1.1, "Options for the Status Command of opmnctl" Section 4.3.4.1.2, "opmnctl status -port" Section 4.3.4.1.3, "opmnctl status -app"

#### 4.3.4.1 opmnctl status

Syntax: `opmnctl [`<`scope`>`] status [<``options``>]`

The `status` command enables you to obtain information on the Oracle Application Server processes managed by OPMN.

The output is a text table. Each row in the table represents one Oracle Application Server process.

You can customize the status command in the following ways:

- Supply a scope to obtain status of processes running on other Oracle Application Server instances

- Change the information displayed about each Oracle Application Server process

- Remove the table headers from the output

- Change the field separator

- Change the record separator

- Change the width of individual columns

- Change the justification of the data in an individual column

Enter the `opmnctl usage status` command to obtain full details on how to use the status command.

Example 4-3 shows the output after entering the `opmnctl status` command for the `AppSrv1` instance on host `comp1` for the domain `yourcompany.com`:

Example 4-3 opmctl Status Output

    prompt > opmnctl status

    Processes in Instance: AppSrv1.comp1.yourcompany.com
    --------------------+----------------------+--------+---------
    ias-component       | process-type         |    pid | status
    --------------------+----------------------+--------+---------
    OC4J                | OC4J_Demos           |    N/A | Down
    OC4J                | home                 |  29268 | Init
    HTTP_Server         | HTTP_Server          |  29099 | Alive

You can use the `opmnctl status` command with `<scope>` to obtain additional detailed information. For example, the following command gives you the status of every process of every component of every OracleAS Instance in an entire cluster:

    prompt > opmnctl @cluster status

See Also: Section 4.3.1.1, "Scope"

##### 4.3.4.1.1 Options for the Status Command of opmnctl

The following are the options you can specify for the `<options>` parameter:

- `-l`: Use this option to obtain the `uniqueid` `(uid)` value and other specific process parameter information.

      prompt > opmnctl status -l

  For example, the following command outputs the information shown in Example 4-4:

  Example 4-4 opmnctl status -l output

      Processes in Instance: j2eeuser.yourcompany.com
      -------------+------------+------+-------+---------+-------+---------+--------
      ias-component|process-type|pid   |status |uid      |memused|uptime   | ports
      -------------+------------+------+-------+---------+-------+---------+--------
      -OC4J        | home       | 5611 | Alive |632225812|105008 |17:55:58 |jms:3701, rmi: 3201,ajp:3000

  The `uid` information enables you to stop or restart an individual Oracle Application Server process.

  For example, the following command stops the `home` `process-type`:

      prompt > opmnctl stopproc uniqueid=632225812

- `-fsep <string>`: Use this option to assign a field separator value for your `opmnctl status` output. The default value is |.

- `-rsep <string>`: Use this option to assign a record separator value for your `opmnctl status` output. The default value is \n.

- `-noheaders`: Use this option if you do not want a header displayed after you run the `opmnctl status` command.

- -`fmt <fmtlist>`: This is a single string containing one or more statistic identifiers connected together where each identifier has the following format: `<statname>[<width>{<justification>].` The default value is: `%cmp18%prt18%pid5R%sta8.`

  Table 4-3 lists the format string syntax for the `<fmtlist>` option:

Table 4-3 Format String Syntax

Format String Syntax | Description
--- | ---
`<statname>` | This must be one of the following: `clu`: Oracle Application Server cluster name `ins`: Oracle Application Server instance name `cmp`: Oracle Application Server component ID `prt`: `process-type` ID `prs`: `process-set` ID `idx`: index of process in `process-set` `pid`: operating system process ID `uid`: OPMN `uniqueid` `typ`: name for this kind of process `sta`: process status `stm`: start time (ms) `utm`: up time (ms) `cpu`: cpu time (ms) `mem`: memory used (in KB) `por`: port list
`<width>` | Specifies the size for the field. Output shorter than this value receives padding according to the specified <justification>. Output longer than this value is truncated, and terminated with '~'. Default: width of each datum.
`<justification>` | Specifies the justification for the field. This enables you to justify output when it is less than the width. It is `L`, `R`, or `C` (left, right, or center justification). Default: `L`

For example, the following command displays the output shown in Example 4-5:

    prompt> opmnctl status -noheaders -fsep @ -fmt %cmp%prt%pid%sta

Example 4-5 opmnctl status -noheaders output

    OC4J@home@N/A@Down
    HTTP_Server@HTTP_Server@13926@Alive

See Also: Section 4.3.1, "Command Definitions"

Enter the following command for additional detailed information:

    prompt > opmnctl usage status

##### 4.3.4.1.2 opmnctl status -port

The `opmnctl status -port` command enables you to display the request connect string used to connect to the OPMN daemon. For example, the command:

    prompt > opmnctl status -port

displays:

    123.your_company.com:6200

This information can be used by a remote tool that is seeking to access OPMN. For example, in a J2EE Server and Process Management installation type, the request port information can be used in conjunction with the `admin_client.jar` utility to perform a deployment to an OC4J instance within the scope of the identified OPMN instance.

This `opmnctl status -port` command is a convenient shortcut that replaces the need to look inside of the `opmn.xml` file to determine the request access port.

##### 4.3.4.1.3 opmnctl status -app

The `opmnctl status -app` command displays information for applications (`module-ids`) that are managed by OPMN.For example, after entering the following command:

    > opmnctl status -app

you will see the following output:

    application type: OC4J
    -----+-----------+---------+---------+----------+-------
    pid  | name      | state   | rtid    | routable | parent
    -----+-----------+---------+---------+----------+-------
    2816 | system    | started | g_rt_id | true     |
    2816 | default   | started | g_rt_id | true     |system
    2816 | bc4j      | stopped | g_rt_id | false    |
    2816 | ascontrol | started | g_rt_id | true     |

Only applications that are reported by live processes show up in the `opmnctl status -app` output.

The information that is reported using the `opmnctl status -app` command varies for each `module-id`. A separate table is created for each `module-id`. Data that is not available with a process is shown as empty or as `N/A` in the process table.

You can use the command options specified in Section 4.3.4.1, "opmnctl status" with the `opmnctl status -app` command.

#### 4.3.4.2 opmnctl dmsdump

Syntax: `opmnctl [`<`scope`>`] dmsdump [<attr>=<value>``[&<attr>=<val>...]]`

The `opmnctl dmsdump` command enables you to print the Oracle Dynamic Monitoring Service (DMS) statistics for OPMN. You can obtain a printout of process control operations for specific Oracle Application Server components. If no attributes are specified, performance data for all OPMN-managed processes for your Oracle Application Server components are printed out.

DMS enables you to monitor a specific performance metric, a set of performance metrics, or all performance metrics. Options allow you to specify a reporting interval to report the requested metrics.

Multiple `<attr>=<value>` pairs must be separated by an `&`. For example, the following `opmnctl` command:

    prompt > opmnctl dmsdump "table=opmn_ons&format=xml"

will output the set of statistics that are gathered for ONS. The output includes the ports that ONS listens on and the number of notifications that ONS has processed. The output is in `.xml` format rather than text. If you want to review the output in text format do not include `&format=xml` on the command line.

For more information about DMS performance metric attributes and values refer to the Oracle Application Server Performance Guide.

#### 4.3.4.3 opmnctl ping

Syntax: `opmnctl ping` [<`max_retry`>]

The `opmnctl ping` command enables you to contact the local OPMN server to verify operation. <`max_retry`> specifies the maximum number of retry times. If <`max_retry`> is specified, the local OPMN is pinged every one second, until the command execution succeeds or <`max_retry`> is reached.

For example, the following command,

    prompt > opmnctl ping 10

designates pinging of OPMN 10 times until the ping command succeeds

#### 4.3.4.4 opmnctl set

Syntax: `opmnctl [<``scope``>] set [<``attr``>=<``value``> ...]`

The `opmnctl set` command sets the logging configuration for OPMN.

The `scope` defines where the `opmnctl set` request will be routed. If none or only `@instance` is specified, the request will be routed to the local Oracle Application Server instance only. If `@instance` is followed by specified instance names, the request will be routed to the specified Oracle Application Server instances.

If `@cluster` is specified, the request will be routed to all instances in the cluster.

An attribute name must be specified along with an attribute value. The following attribute names are required by OPMN for this command:

- `target`: the value for `target` can be either `log` or `debug`, which refer to the `opmn.log` or the `opmn.dbg`, respectively. Refer to Section A.2.1, "OPMN log Files" for more information.

  Note: Enable usage of the `opmn.dbg` file only after conferring with Oracle Support. The `opmn.dbg` file is used by Oracle Support to debug and diagnose OPMN issues. Messages that are contained in the `opmn.dbg` file are typically not readily comprehensible to the user.

- `comp`: specifies the OPMN internal components and subcomponents

##### 4.3.4.4.1 The `comp` Attribute

The value for the `comp` attribute can be either `ons` or `pm`. Additionally, the attribute value can be a specific set of sub-components for either the ons or `pm` attributes.

The following values for `comp` specify the OPMN internal components and subcomponents:

- `internal:`specifies the common internal information for OPMN

- `ons`:specifies the ONS component information for OPMN

- `pm`: specifies the PM component information for OPMN

Both the ons and `pm` components consist of subcomponents which may be specified using the `component[subcomponents]` syntax where component can be either ons or `pm`. If both ons and `pm` are specified together they must be separated by a semicolon in the `opmn.xml` file. If subcomponents are listed, the listed items must be separated by a comma.

Table 4-4 ONS Component Codes

ONS element | Definition
--- | ---
all | all subcomponents
local | local information
listener | listener information
discover | discover (server or multicast) information
servers | remote servers currently up and connected to the cluster
topology | current cluster wide server connection topology
server | remote server connection information
client | client connection information
connect | generic connection information
subscribe | client subscription information
message | notification receiving and processing information
deliver | notification delivery information
special | special notification processing
internal | internal resource information
secure | SSL operation information
workers | worker threads

Table 4-5 PM Component Codes

PM element | Definition
--- | ---
all | all subcomponents
requests | HTTP (user) requests
remote | remote HTTP requests
scheduler | scheduler thread and resource information
monitor | monitor thread information
workers | worker threads
process | managed processes
depend | dependency processing
rmd | RMD directives
fos | service failover information
internal | internal resources
schedjobs | periodic scheduled jobs
procjobs | for each process scheduled jobs
fos | service failover processing
dms | DMS processing
modules | `process module` information. Only modules which call the `modLog()` (or `modDebug` for the debug log) function will yield output. A specific module or list of modules may be specified with modules(`module-ids`). `module-ids` can be specified with a colon seperated list of `module-ids` to be displayed: modules (`module1-id:module2-id`). `module-ids` that do not match a configured and enabled module are not processed.

Each subcomponent for ons and `pm` may be prefaced with the negation character, !, which deselects the subcomponent. By using `all` with negated sub-components, specific subcomponents can be easily eliminated from the display.

Components and subcomponents are set or negated in the order in which they are encountered. Therefore:

    ons[all,!topology]

will yield all ons subcomponents excluding topology, while:

    ons[!topology,all]

will yield all ons subcomponents including topology.

#### 4.3.4.5 opmnctl query

Syntax: `opmnctl [<scope>] query [<attr>=<value> ...]`

The `opmnctl query` command enables you to query the logging configuration for OPMN.

The attribute name of `target` must be specified along with an attribute value. The value for `target` can be either `log` or `debug`, which refer to the `opmn.log` file or the `opmn.dbg` file, respectively. Refer to Section A.2.1, "OPMN log Files" for more information.

### 4.3.5 Help Commands

The `opmnctl help` commands enable you to obtain additional information regarding OPMN.

This section describes the help command options available with the `opmnctl` command. It includes the following sections:

- Section 4.3.5.1, "opmnctl help"

- Section 4.3.5.2, "opmnctl usage"

- Section 4.3.5.3, "opmnctl validate"

#### 4.3.5.1 opmnctl help

Syntax: `opmnctl help`

Use this command to print a short syntax description of `opmnctl` commands.

Example 4-6 shows the output from the `opmnctl help` command.

Example 4-6 opmnctl help Output

    prompt > opmnctl help

    usage: /ORACLE_HOME/bin/opmnctl [verbose] [<scope>] <command> [<options>]

    verbose: print detailed execution message if available

    Permitted <scope>/<command>/<options> combinations are:

      scope      command      options
    _________   __________   __________
                start                         - Start opmn
                startall                      - Start opmn & all managed processes
                stopall                       - Stop opmn & all managed processes
                shutdown                      - Shutdown opmn & all managed processes
    [<scope>]   startproc   [<attr>=<val>..]  - Start opmn managed processes
    [<scope>]   restartproc [<attr>=<val>..]  - Restart opmn managed processes
    [<scope>]   stopproc    [<attr>=<val>..]  - Stop opmn managed processes
    [<scope>]   reload                        - Trigger opmn to reread opmn.xml
    [<scope>]   status      [<options>]       - Get managed process status
    [<scope>]   dmsdump     [<attr>=<val>&..] - Get DMS stats
    [<scope>}   set         [<attr>=<val> ..] - Set opmn log parameters
    [<scope>]   query       [<attr>=<val> ..] - Query opmn log parameters
                ping        [<max_retry>]     - Ping local opmn
                validate    [<filename>]      - Validate the given xml file
                config      [<options>]       - Modify the opmn xml file
                help                          - Print brief usage description
                usage       [<command>]       - Print detailed usage description

#### 4.3.5.2 opmnctl usage

Syntax: `opmnctl usage [<``command``>]`

The `usage` command displays help for all `opmnctl` commands, or only for the specified command.

The command can be one or more of the following:

- `start`

- `startall`

- `startproc`

- `stopall`

- `stopproc`

- `restartproc`

- `reload`

- `shutdown`

- `ping`

- `status`

- `dmsdump`

- `config`

- `help`

For example, enter the following command to receive the output shown in Example 4-7:

    prompt > opmnctl usage stopall

Example 4-7 opmnctl usage stopall output

    opmnctl stopall

    Stop opmn daemon and opmn managed processes for local ias instance.

    This request first tries to stop all opmn managed processes gracefully.
    Processes which will not stop gracefully will be forcefully shutdown.  After
    stopping all managed processes, the opmn daemon will shutdown itself.

    This request should only be performed when it is necessary to stop the opmn
    daemon.  Once started, the opmn daemon should remain up until it is necessary to
    restart the computer or some other rare administrative event occurs.

    To stop all opmn managed processes without stopping the opmn daemon, consider
    using the stopproc command without any arguments.

    To restart the opmn daemon without restarting any managed processes, consider
    using the the reload command.  The reload command is the appropriate command to
    use when the only goal is to restart the opmn daemon with a new configuration.

    This request operates synchronously and will wait for the operation to complete
    before returning.

#### 4.3.5.3 opmnctl validate

Syntax: `opmnctl validate` [<`filename`>]

The `opmnctl validate` command validates the XML syntax of the `opmn.xml` file. The default `ORACLE_HOME``/opmn/conf/opmn.xml` is validated if the filename parameter is not specified. The <`filename`> can be specified by either the relative or absolute path.

Only one file can be validated at a time.