2 OPMN: Overview

2.8.1.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 reboot 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.

2.8.1.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.

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

2.8.1.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.

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 reboot your computer.

2.8.1.4 opmnctl stopall and opmnctl shutdown

Syntax: opmnctl stopall, opmnctl shutdown

Use either of these commands 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.

The opmnctl stopall or the opmnctl shutdown command should only be executed prior to shutting down OPMN and your computer.

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.

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

2.8.1.5 opmnctl reload

Syntax: opmnctl [scope] reload

Use this command to trigger the OPMN to re-read 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.

Enter the following command for additional detailed information.

prompt > opmnctl usage reload

2.8.2.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.

• 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. The 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 the 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

2.8.3.1 Scope

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

               @cluster[:clusname]

               @farm

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, clusters and farms.

• @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...]].

• @farm: To apply the command query to all Oracle Application Server instances in the Oracle Application Server farm.

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

2.8.3.2 Attributes

syntax: <attribute>=<value>

The opmnctl attributes enable you to apply process control operations to specific Oracle Application Server components. If no attributes are specified, all OPMN-managed processes are started, stopped, or restarted.

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

prompt > opmnctl startproc ias-component=wireless

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

Table 2-2 lists the attribute names and values that OPMN can use this command:

2.8.3.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 2-3.

> opmnctl verbose startproc ias-component=HTTP_Server

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>

2.8.3.4 Options

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

• -l: Use this option to obtain the uniqueid (uid) value.

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

  prompt > opmnctl status -l
  
  

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

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 2-3 lists the format string syntax for the <fmtlist> option:

For example, the following command displays the output shown in Example 2-5.

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

OC4J@home@N/A@Down
dcm-daemon@dcm-daemon@13875@Alive
LogLoader@logloaderd@9800@Alive 
HTTP_Server@HTTP_Server@13926@Alive

Enter the following command for additional detailed information.

prompt > opmnctl usage status

2.8.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 2-6 shows the output after entering the opmnctl status command for the AppSrv1 instance on host comp1 for the domain yourcompany.com:

prompt > opmnctl status

Processes in Instance: AppSrv1.comp1.yourcompany.com
ias-component       | process-type         |    pid | status
--------------------------------------------------------------
WebCache            | WebCacheAdmin        |  29121 | Alive
WebCache            | WebCache             |  29120 | Alive
OC4J                | OC4J_Demos           |    N/A | Down
OC4J                | home                 |  29268 | Init
dcm-daemon          | dcm-daemon           |  29113 | Alive
LogLoader           | logloader            |    N/A | Down
HTTP_Server         | HTTP_Server          |  29099 | Alive

opmnctl @farm status

2.8.4.2 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

2.8.5.1 opmnctl help

Syntax: opmnctl help

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

Example 2-7 shows the output from the opmnctl help command.

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
            ping        [<max_retry>]     - Ping local opmn
            validate    [<filename>]      - Validate the given xml file
            help                          - Print brief usage description
            usage       [<command>]       - Print detailed usage description

2.8.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

• help

For example, enter the following command to receive the output shown in Example 2-8.

prompt > opmnctl usage stopall

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
reboot 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.

2.8.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. No output is generated for successful opmn.xml file validation.