Skip Headers

Oracle9iAS Containers for J2EE User's Guide
Release 2 (9.0.2)

Part Number A95880-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

A
DCM Command-Line Utility (dcmctl)

The Distributed Configuration Management (DCM) utility, dcmctl, provides a command-line alternative to using Oracle Enterprise Manager for some management tasks. The dcmctl tool uses the same distributed architecture and synchronization features as Enterprise Manager Web site, thereby providing identical functionality in a format that is ideal for scripting and automation.

The following sections describe the tasks you can perform using dcmctl:

Overview

The dcmctl utility is located in ORACLE_HOME/dcm/bin/dcmctl.


Note:

The only type of application server instance that you can manage with dcmctl is a J2EE and Web Cache instance type with only Oracle HTTP Server (OHS) and Oracle9iAS Containers for J2EE (OC4J) configured. If Web Cache is configured, it will be ignored by dcmctl.


In order to run dcmctl you must log in to your operating system as the user that installed Oracle9i Application Server. You can run dcmctl from your operating system prompt using the following syntax:

dcmctl command [options]

Table A-1 displays dcmctl help and error information commands.

Table A-1 Help and Error Commands
Command Description

help

View usage information.

getError [err_number | err_name]

View a description of the most recent error that occurred if no parameter is given. If you provide an error number or name, the description for that error is displayed. An example of a valid number is 906007; an example of a valid name is ADMN-906007.

getReturnStatus

Print the current status of the last command executed. The last command must be a command that performs an operation, not a command that returns state. If the last command has a failed or unknown state, the -verbose option will provide more information.

The following sections describe overall information on how to use dcmctl:

About dcmctl Commands and Options

The dcmctl utility supports many commands, which are described in the subsequent sections of this appendix. Commands are a single word and are not case-sensitive. Each dcmctl command supports zero or more options.

Options take the following form:

-option [argument]

Option names have a long and short form, and are not case-sensitive. There are two types of dcmctl options: target and universal.

Target Options

Table A-2 lists the dcmctl target options that define the target on which to apply the given command. Subsequent sections of this appendix describe which target options can be used with each command. On hosts with multiple application server instances, dcmctl determines the target instance as follows:

Universal Options

Table A-3 lists the dcmctl universal options that define command behavior and can be used with all commands.

Table A-3 dcmctl Universal Options  
Option Description

-debug

-d

Print the stack trace if an exception occurs when executing the command

-logdir directory

-l directory

Save the DCM error log file log.xml in the named directory. The directory can be a full pathname or a pathname relative to the current directory. The default directory is ORACLE_HOME/dcm/logs.

-oraclehome directory

-o directory

Set the Oracle home to the named directory. The default is the Oracle home where the dcmctl command resides.

-timeout num_seconds

-t num_seconds

Set the maximum number of seconds to allow for a command to complete. The default is 45 seconds.

-verbose

-v

Print the long version of state and error messages

Using dcmctl in a Clustered Environment

In order to use dcmctl in a clustered environment, you must have a DCM daemon associated with every instance in the cluster. You can do this in one of the following ways:

Passing Parameters to the JVM

You can pass parameters directly to the JVM when executing dcmctl through the ORACLE_DCM_JVM_ARGS environment variable.

For example, to set up a proxy:

ORACLE_DCM_JVM_ARGS="-DhttpProxy.host=yourproxyhost.com 
-DhttpProxy.port=yourproxyport"

Starting and Stopping

Use dcmctl to start, stop, restart, and retrieve the status of application server instances, components, and clusters.

Table A-4 lists the administration commands and their options for starting, stopping, restarting, and retrieving the status of instances, clusters, or components within the instance or cluster.

Table A-4 Administration Commands and Their Options
Command Description

start [[-cl cluster_name] |
[-i instance_name] |
[-co component_name] | [ -ct type]]

Start the processes indicated. The default is to start the local application server instance only. Refer to Table A-2 for information on the scope parameters. Note that you can choose to start all application server instances in the cluster (-cl), the local application server instance (default), a remote application server instance (-i), a single component within the local instance (-co), or a component type (ohs or oc4j) within an instance (-ct). For all options except the -co and -ct options, OPMN and DCM are started if not already executing.

stop [[-cl cluster_name] |
[-i instance_name] |
[-co component_name] | [ -ct type]]

Stop the processes indicated. See the start command for further discussion. This does not stop OPMN and DCM.

restart [[-cl cluster_name] |
[-i instance_name] |
[-co component_name] | [ -ct type]]

Restart the processes indicated. See the start command for further discussion. This will leave OPMN and DCM running.

shutdown

Stops the local application server instance, including its components, OPMN, and DCM. This command is appropriate to run before a system shutdown.

getstate [[-cl cluster_name] | [-i instance_name] |
[-co component_name]]

Return the current status of the processes indicated. This command returns a status of "up" or "down" for the indicated process.

Managing Application Server Instances

Table A-5 describes commands that you can use to display information about application server instances and destory and resynchronize instances.

Table A-5 Listing and Destroying Application Instances
Command Description

listInstances

Return the names of all instances that belong to the farm as the target instance and are not part of a cluster. If the target instance does not belong to a farm, return only the name of the target instance.

whichInstance

Return the name of the target instance.

destroyInstance -i instance_name

Remove all information related to the instance from the DCM repository. This command can be used if an instance was not deinstalled properly using Oracle Universal Installer. Note that the instance name must be supplied for this command.

listComponents [[-i instance_name] | [-cl cluster_name]]

Return a list of component instance names in the application server instance.

resyncInstance [-force]
[-i
instance_name]

Resynchronize the local configuration information for an instance with what is in the DCM repository. This command can be used if an instance was not able to be updated due to a system failure, and the instance state is not in sync with the DCM repository. The -force option causes an instance to resynchronized with information from the DCM repository regardless of whether the instance state indicates that it requires resynchronization.

Managing Components

Table A-6 describes commands that you can use to manage Oracle HTTP Server and OC4J instances that reside within a J2EE and Web Cache instance type.

Table A-6 Listing or Destroying Instances
Command Description

listComponentTypes

Return a list of supported component types. The current supported component types are ohs and oc4j.

getComponentType -co component_name [-i instance_name ]

Return the type of the component instance.

createComponent -ct type -co component_name

Create a new component instance of the specified type with the specified name. Only the oc4j type is allowed.

removeComponent -co component_name

Remove the specified component from the local instance (and from the cluster if applicable). Only oc4j component instances can be removed.

updateConfig [-ct type [, type]]

Update the DCM repository with configuration changes made by manually editing the component configuration files. The componentType indicates the component type that has been edited (ohs or oc4j). The default is both component types.

Managing Clusters

Table A-7 describes commands that you can use to manage application server clusters.

Table A-7 Managing Clusters
Command Description

createCluster -cl cluster_name

Create a cluster with the indicated name in the farm.

removeCluster -cl cluster_name

Remove the cluster and destroy all information about the cluster in the DCM repository. A cluster must contain zero instances when it is removed.

listInstances [-cl cluster_name]

Return a list of application server instances in the cluster. If no cluster is supplied, list instances that are not in a cluster.

listClusters

Return a list of cluster names in the farm that is associated with this host.

whichCluster [-i instance_name]

Return the name of the cluster that contains the supplied instance.

isClusterable [-i instance_name]

Determine if an application server instance is eligible for clustering. Only J2EE and Web Cache instance types with OHS and OC4J configured are eligible. Note that the -verbose option will describe why an instance is not eligible for clustering.

isCompatible -cl cluster_name [-i instance_name]

Determine if an application server instance is compatible with a cluster, and therefore eligible to join the cluster. Note that the -verbose option will describe why an instance is not compatible with a cluster.

joinCluster -cl cluster_name
[-i
instance_name]

Add the indicated instance to the specified cluster. An instance is stopped after being added to a cluster and you can manually start it.

leaveCluster [-i instance_name]

Remove the indicated instance from the cluster. An instance is stopped after being removed from a cluster and you can manually start it.

updateConfig [-ct type]

Update the DCM repository and other members of the cluster with configuration changes made by manually editing the component configuration files. The componentType indicates the component type that has been edited (ohs or oc4j). The default is both component types.

resyncInstance [-force]
[-i
instance_name]

Resynchronize an application server instance with other instances in the cluster. This command can be used after a synchronization operation failed. For example, if you deployed an application across a cluster, and one instance was not able to deploy the application due to insufficient disk space, you could correct the disk space problem and run this command to redeploy the application across all instances. The -force option causes an instance to resynchronize with information from the DCM repository regardless of whether the instance state indicates that it requires resynchronization.

Deploying Applications

This section describes commands for deploying, redeploying, and undeploying OC4J applications.

On hosts with multiple OC4J instances, dcmctl determines the target OC4J instance as follows:

Saving a Backup

Table A-9 lists commands that you can use to back up your application instance, including clustering information, configuration, and applications deployed.

Table A-9 Backing Up the Application Instance
Command Description

saveInstance
-dir directory_name

Saves the configuration and application information of the current instance to the designated directory. Creates the directory if it does not exist. If it does exit, then the specified directory must be empty. This command can be used to save current configuration settings and installed J2EE applications before making configuration changes. You can then back out of the changes, if necessary, using the restoreInstance command.

restoreInstance
[-dir directory_name]

Restores the configuration and application information from the specified directory for this instance. If no directory is specified, then the instance is restored to the configuration set at install time. This command causes the instance to be shut down. If the instance is a member of a cluster, it is removed from the cluster before the information is restored. RestoreInstance does not effect the configuration of the other members of the cluster.

resetFileTransaction

When using a file-based repository for your application instance, it may leave uncommitted information in the repository if an operation is interrupted (control C). This command blocks all subsequent updates to the repository, cleans up uncommitted data, and reopens the repository for update.

Using the dcmctl Shell

You can execute dcmctl commands from within the dcmctl shell. To start the dcmctl shell, type:

dcmctl shell

The following is a sample session using the dcmctl shell:

dcmctl shell
dcmctl> createcluster testcluster 
dcmctl> joincluster testcluster
dcmctl> createcomponent -ct oc4j -co component1
dcmctl> start -co component1
dcmctl> deployapplication -f /stage/apps/app1.ear -a app1 -co component1
dcmctl> start -cl testcluster
dcmctl> getstate
dcmctl> exit


Note:

You can repeat any command within the dcmctl shell using the !! command.


Executing dcmctl from a Command File

You can execute dcmctl commands from a script file using the following command:

dcmctl shell -f script_file_name

For example, create a file called testFile.cmd containing the following lines:

# this is a comment in a dcmctl command file
echo "creating testcluster"
createcluster testcluster 
echo "joining testcluster"
joincluster testcluster
echo "creating component component1"
createcomponent -ct oc4j -co component1
echo "starting component to deploy application"
start -co component1
echo " deploying application"
deployapplication -f /stage/apps/app1.ear -a app1 -co component1
echo "starting the cluster"
start -cl testcluster
echo "verifying everything started "
getstate
exit

Execute testFile.cmd using the following command:

dcmctl shell -f testFile.cmd


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index