F
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

• Starting and Stopping

• Managing Application Server Instances

• Managing Components

• Managing Clusters

• Deploying Applications

• Using the dcmctl Shell

• Executing dcmctl from a Command File

Overview

The dcmctl utility is located in:

(UNIX) ORACLE_HOME/dcm/bin/dcmctl
(Windows) 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 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 F-1 displays dcmctl help and error information commands.

Table F-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

• Using dcmctl in a Clustered Environment

• Passing Parameters to the JVM

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 F-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:

• The target is all instances in the designated cluster with the -cluster or -cl option.

• The target is the instance supplied with the -instance or -i option.

• If a cluster or instance is not supplied, then the target is the instance associated with the -oraclehome universal option.

• If the cluster, instance, or -oraclehome is not supplied, use the instance associated with the Oracle home directory in which the dcmctl executable resides.

Table F-2 dcmctl Target Options  

Option	Description
-application app_name -a app_name	Apply the command to the named application
-cluster cluster_name -cl cluster_name	Apply the command to the named application server cluster
-component comp_name -co comp_name	Apply the command to the named component
-componentType type -ct type	Apply the command to components of the named component type. Component type can be ohs, oc4j, opmn, or jazn.
-instance inst_name -i inst_name	Apply the command to the named application server instance

Universal Options

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

Table F-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:

• Start the Oracle Enterprise Manager Web site on each host that contains an application server instance in your cluster. On each host, log in as the user that installed Oracle9i Application Server and enter the following command in the Oracle home of the primary installation (the primary installation is the first application server or infrastructure installed on the system):

  (UNIX) ORACLE_HOME/bin/emctl start
  (Windows) ORACLE_HOME\bin\emctl start
  

  See Also: "Starting and Stopping the Oracle Enterprise Manager Web Site" for more information on starting the Oracle Enterprise Manager Web site.

• On UNIX, you can start the dcmctl shell in each application server instance in the cluster. On each host that contains instances in the cluster, log in as the user that installed Oracle9i Application Server and execute the following command in the Oracle home directory for each instance in the cluster:

  ORACLE_HOME/dcm/bin/dcmctl shell 
  

  To stop the process, use the following command:

  dcmctl> exit
  

  Note that the dcmctl shell must stay running in the foreground; do not put it in the background.

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

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

Table F-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 F-4 Starting and Stopping 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 F-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, oc4j, or opmn) 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	Stop 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 F-5 describes commands that you can use to display information about application server instances and destroy and resynchronize instances.

Table F-5 Application Server Instance Commands and Their Options  

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 F-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 F-6 Component Commands and Their Options  

Command	Description
listComponentTypes	Return a list of supported component types. The current supported component types are ohs, oc4j, opmn, and jazn.
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, oc4j, opmn, or jazn). The default is both component types.

Managing Clusters

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

Table F-7 Cluster Commands and Their Options  

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 HTTP Server 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, oc4j, or opmn). The default is all 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:

• If an OC4J instance is specified with the -co target option, apply the operation to that OC4J instance within the associated application server instance. The application server instance is determined first by the -oraclehome option, and second by the Oracle home directory in which the dcmctl executable resides. If the application server instance is part of a cluster, apply the operation to all OC4J instances with the specified name within the cluster.

• If the -co target option is not supplied, apply the operation to all OC4J instances within the associated application server instance. The application server instance is determined first by the -oraclehome option, and second by the Oracle home directory in which the dcmctl executable resides. If the application server instance is part of a cluster, apply the operation to all OC4J instances within the cluster.

  Table F-8 Deployment Commands and Their Options  

  Command	Description
  deployApplication -file name -a app_name [-co comp_name] [-rc root_context]	Deploy an application to the current instance using the WAR or EAR file supplied with the -file option. The application name is assigned to the application for administrative purposes. The name used to access the application from the Web is still the name supplied in the EAR file. The -rc option is required if the application is a WAR file. Do not use the -rc option when deploying an EAR file
  redeployApplication -file name -a app_name [-co comp_name] [-rc root_context]	Redeploy an application to the current instance using the WAR or EAR file indicated by the -file option and associate the indicated name as the name of the application for administrative purposes. The -rc option is required if the application is a WAR file. Do not use the -rc option when deploying an EAR file
  undeployApplication -a app_name [-co comp_name]	Undeploy the indicated application.
  listApplications -co comp_name [[-cl cluster_name] | [-i instance_name]]	Return a list of the applications deployed within the indicated OC4J component. Note that this command allows you to specify an instance or cluster that contains the OC4J component.
  validateEarFile -file simple_ear_file	Determine if the supplied EAR file is J2EE compliant. In order to run this command, you must set up your proxy so that Document Type Definitions (DTDs) may be reached on the Web. See Also: "Passing Parameters to the JVM" for more information.

Saving a Backup

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

Table F-9 Backup Commands and Their Options  

Command	Description
saveInstance -dir directory_name	Save the configuration and application information of the current instance to the designated directory. Create 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]	Restore 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