Skip Headers
Distributed Configuration Management Administrator's Guide
10g Release 2 (10.1.2)
B13997-02
  Go To Table Of Contents
Contents
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Index
Index

Previous
Previous
Next
Next
 

A dcmctl Commands

This chapter describes the characteristics of the dcmctl utility, and provides syntax and reference information for each of its commands. It is divided into these sections:

A.1 Notes for Using dcmctl Commands

All dcmctl commands have this syntax:

ORACLE_HOME/dcm/bin/dcmctl command [options]

Before you use the dcmctl utility, be aware of the following:

A.1.1 dcmctl Options

As shown in the syntax description, dcmctl commands may be used with options. An option can be one of following types:

  • Global: These can be used with all commands (see Table A-1).

  • Scope: These options indicate the scope of a command. The scope can be an application, OracleAS Cluster, component, type of component, or Oracle Application Server Instance (see Table A-2).

  • Command-specific: These options apply only to certain commands. Each command description in the following pages includes information about any options the command provides (see Table A-3).

Table A-1 dcmctl Global Options

Option                  Description

–d

Prints the stack trace if an exception occurs when the command is executed. By default, dcmctl executes with this option on. You can change this behavior with the set command.

–l directory

Saves the DCM client error log file log.xml in the named directory.

The directory can be a full path name or a path name relative to the current directory.

Default value: ORACLE_HOME/dcm/logs/dcmctl_logs

–v

Prints the long (verbose) version of state and error messages. Setting verbose to off is recommended when using scripts or using the dcmctl shell, since the brief messages are easier to parse.

By default, dcmctl executes with this option on. You can change this behavior with the set command.

-sort

Sorts the output of list commands by name.

For example:

dcmctl listComponents –sort

By default, this option is set to off. You can make the sorting feature persistent with the set command.


Table A-2 dcmctl Scope Options

Option                             Description

-a app name

Applies the command to the named application app name, or designates the name of an application during initial deployment.

-admin

Applies the command to the DCM daemon. For example:

start –admin
stop –admin

-cl cluster name

Applies the command to the named OracleAS Cluster, cluster name, or designates the name of an OracleAS Cluster during creation.

-co comp name

Applies the command to the named component, comp name, or designates the name of a component during creation

-ct type

Applies the command to components of the named component type.

Component type can be of type: ohs, oc4j, opmn, or jazn.

-i inst name

Applies the command to the named Oracle Application Server Instance, inst name.

-r repository info

Applies the command to the repository name or port specified with repository info.


Table A-3 dcmctl Command-Specific Options

Option              Description

-arch

Specifies an archive name. Use with archive commands.

For example:

dcmctl createArchive -arch myArchive

-c

Creates a comment. Use with archive commands and 'import' and 'export' configuration management commands.

-force

Performs an operation without performing checks or issuing a confirmation. This option should be used judiciously, since in some cases, it can result in lengthy processing, and in others, it can perform a destructive action that might be unrecoverable.

-src

Indicates the source of the archive. Use with archive commands.

For example, to apply an archive to the current Oracle Application Server Instance:

dcmctl applyArchiveTo -src myArchive


A.1.1.1 Notes on OracleAS Cluster, Instance, Component and Component Type Options

The following rules apply to command-specific options. If you do not use options, by default, the command applies to the local Oracle Application Server Instance.

  • If -cl is supplied, the command applies to all Oracle Application Server Instances in the OracleAS Cluster.

  • If -ct is supplied with -cl or -i, then the command applies to the component type within the OracleAS Cluster, or the component type within the Oracle Application Server Instance within the OracleAS Cluster.

  • If -co is supplied with -ct, -cl, -i then the command applies to the component within the OracleAS Cluster, or the component type within the Oracle Application Server Instance within the OracleAS Cluster.

  • If -a is supplied with any of the preceding options, that particular application within the component, component type, Oracle Application Server Instance, or OracleAS Cluster is affected.

A.1.2 Using the dcmctl Shell

You can execute dcmctl commands from within the dcmctl shell. Within the shell, it is not necessary to preface commands with dcmctl (see the following sample session). To start the dcmctl shell, type:

dcmctl shell

Following is a sample shell session in which the shell is started, commands are executed, and the shell is stopped.

Example A-1 dcmctl Shell Session

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

A.2 Types of dcmctl Commands

This section describes types of dcmctl commands and their uses.

Configuration Management: Use these commands to create and manage configuration elements (OracleAS Clusters, Oracle Application Server Instances, components) and the DCM repository.

dcmctl Shell: Use these commands with the dcmctl shell.

Table A-5 dcmctl Shell Commands

Command


!!


echo


exit


quit


shell


setLogLevel





Archive: Use these commands to create archives of configurations.

Application: Use these commands to deploy and manage applications.

dcmctl Properties: Use these commands to administer the dcmctl utility.

Table A-8 dcmctl Properties Commands

Command


getError


getReturnStatus


getState


help


listComponentTypes


set





Manually Managed Oracle Application Server Clusters: Use these commands to work with Manually Managed OracleAS Clusters.

Table A-9 Manually Managed OracleAS Cluster Commands

Command


addOPMNLink


getOPMNPort


listOPMNLinks


removeOPMNLink



Process Management: These commands allow you to start and stop processes within OracleAS Clusters and Oracle Application Server Instances. These commands are deprecated in Oracle Application Server 10g. Use opmnctl to manage processes in Oracle Application Server 10g. See the Oracle Process Manager and Notification Server Administrator's Guide for information on using opmnctl.

Table A-10 Process Management Commands

Command


restart


shutdown


start


stop



A.3 Alphabetical Listing of dcmctl Commands

This section lists all commands alphabetically. The command type, syntax, and description is included for each command.


Note:

All commands are case-insensitive. Capital letters are used in this guide only to increase readability. Many examples show the commands in all lower case.

A.3.1 !!

Repeats the previous command.

Type

Shell

Syntax

!!

Description

Use this command in the dcmctl shell to repeat the previous command.

Example

!!

A.3.2 addOPMNLink

Creates a Manually Managed Oracle Application Server Cluster.

Type

Manually Managed OracleAS Cluster

Syntax

addOPMNLink hostname:port[, hostname:port...]

Description

You can use this command to create a Manually Managed OracleAS Cluster that includes the local Oracle Application Server Instance and the Oracle Application Server Instances specified as arguments.

  • You must run this command in the Oracle home of each Oracle Application Server Instance that is to be a member of the Manually Managed OracleAS Cluster, using the rest of the Oracle Application Server Instances as arguments.

  • All Oracle Application Server Instances must be J2EE and Web Cache Oracle Application Server Instances, and the Oracle Application Server Instances must not be part of an OracleAS File-Based Farm. Otherwise, the command will fail.

  • To change the ONS remote port for an Oracle Application Server Instance in an Manually Managed OracleAS Cluster, you must remove the Oracle Application Server Instance from the Manually Managed OracleAS Cluster using removeOPMNLink, change the remote port, and add it to the Manually Managed OracleAS Cluster again using addOPMNLink. You must repeat the command in every Oracle home.

  • If you create a Manually Managed OracleAS Cluster and then want to add another Oracle Application Server Instance to the Manually Managed OracleAS Cluster, you must run the command again in all Oracle homes (essentially creating a new Manually Managed OracleAS Cluster with the added Oracle Application Server Instance).

Example

HOST1_ORACLE_HOME/dcm/bin/dcmctl getopmnport 
host1:6200
HOST2_ORACLE_HOME/dcm/bin/dcmctl getopmnport
host2:6200
HOST3_ORACLE_HOME/dcm/bin/dcmctl getopmnport 
host3:6200
HOST1_ORACLE_HOME/dcm/bin/dcmctl addopmnlink host2:6200,host3:6200
HOST2_ORACLE_HOME/dcm/bin/dcmctl addopmnlink host1:6200,host3:6200 
HOST3_ORACLE_HOME/dcm/bin/dcmctl addopmnlink host1:6200,host2:6200

A.3.3 applyArchiveTo

Applies an archived configuration to an Oracle Application Server Instance or DCM-Managed OracleAS Cluster.

Type

Archive

Syntax

applyArchiveTo –src archiveName [-cl clusterName | -i instanceName]

Description

When configuration information is stored in the DCM repository, it is recognized as one of the following two types of information:

  • Information that is generic to any Oracle Application Server Instance (cluster-wide information).

  • Information that is specific to a particular Oracle Application Server Instance (instance-specific information). Instance specific information is defined by the various managed components, including: Oracle HTTP Server, OC4J, OPMN, and JAZN and may include such things as host name or port values

When an archive is applied to the same Oracle Application Server Instance from which it was created, both the cluster-wide information and instance-specific information is restored to the Oracle Application Server Instance. When the archive is applied to a DCM-Managed OracleAS Cluster or to a different Oracle Application Server Instance than the one it was created for, only the cluster-wide information is restored, the existing instance-specific information is not changed. See Section 2.2.4.2, "Parameters Excluded from the Common Configuration: Instance-Specfic Parameters".

Example

dcmctl applyarchiveto –src archive1 –i instance1

A.3.4 applyClusterTo

Applies the configuration of a DCM-Managed OracleAS Cluster to another Oracle Application Server Instance or DCM-Managed OracleAS Cluster.

Type

Configuration Management

Syntax

applyClusterTo -src clusterName [-cl clusterName | -i instanceName]

Description

The configuration of the named DCM-Managed OracleAS Cluster (as specified by the -src option) is applied to the named Oracle Application Server Instance or DCM-Managed OracleAS Cluster. The named source DCM-Managed OracleAS Cluster is not affected.

Example

dcmctl applyclusterto –src cluster1 –i instance1

A.3.5 applyInstanceTo

Applies the configuration of the named Oracle Application Server Instance to another Oracle Application Server Instance or DCM-Managed OracleAS Cluster.

Type

Configuration Management

Syntax

applyInstanceTo –src instanceName [-cl clusterName | -i instanceName]

Description

The configuration of the named Oracle Application Server Instance is applied to the named Oracle Application Server Instance or DCM-Managed OracleAS Cluster. If no Oracle Application Server Instance or DCM-Managed OracleAS Cluster is specified, then the configuration of the named Oracle Application Server Instance is applied to the current Oracle Application Server Instance. The named source Oracle Application Server Instance is not affected. The command will fail if the current Oracle Application Server Instance and the named Oracle Application Server Instance are the same (you cannot apply the configuration of an Oracle Application Server Instance to itself).

Example

dcmctl applyinstanceto -src instance1

A.3.6 configRepositorySSL

Specifies the location and password of the keystore used to secure the Oracle Application Server Farm.

Type

Configuration Management

Syntax

configRepositorySSL -keystore pathToKeystore -storepass password

Description

Specifies the location and password of the keystore to use to provide certificate-based security for the farm. This command applies to a distributed File-based repository only. Configuring the keystore does not automatically enable security.

To use certificate-based security, each Oracle Application Server Instance in the Oracle Application Server Farm must have a Java keystore. It can be shared by other Java applications, or it can be a separate keystore specifically for repository administration. After the keystore is set up, use the configRepositorySSL command in each Oracle Application Server Instance in the Oracle Application Server Farm to tell the system which keystore to use.

To enable this security feature, edit the file ORACLE_HOME/dcm/config/dcmCache.xml, in each Oracle Application Server Instance in the Oracle Application Server Farm to set the value of <useSSL> true </useSSL>. You must restart all DCM daemons and clients in the Oracle Application Server Farm for the security change to take effect. The security setting must be consistent across all Oracle Application Server Instances in the Oracle Application Server Farm, or they will not communicate properly.

Example

configRepositorySSL -keystore /OracleHome/security/files -storepass welcome

A.3.7 createArchive

Creates an archive of the named DCM-Managed OracleAS Cluster or Oracle Application Server Instance.

Type

Archive

Syntax

createArchive -arch archiveName [-cl myCluster | -i myInstance] [-comment "myComments"]

Description

An archive is created of the named Oracle Application Server Instance or DCM-Managed OracleAS Cluster. If you don't specify a DCM-Managed OracleAS Cluster or Oracle Application Server Instance, the current Oracle Application Server Instance is archived.

The difference is as follows.Notes for using createArchive with DCM-Managed OracleAS Clusters:

  • Cluster-wide archives, created with createArchive -cl, contain only cluster-specific information and do not contain any information specific to the Oracle Application Server Instance the archive is created on.

  • Instance-specific archives, created with createArchive -i or with no options, contain cluster-specific information, plus any DCM-managed information pertaining to the Oracle Application Server Instance in which createArchive runs.

Example

createArchive -arch myInstance -comment "my favorite configuration"

A.3.8 createCluster

Creates a DCM-Managed OracleAS Cluster.

Type

Configuration Management

Syntax

createCluster -cl cluster_name

Description

A DCM-Managed OracleAS Cluster is created. "DCM-Managed" means that the DCM configuration can be kept in synch and archived by DCM using the metadata repository of the local farm.

Notes for using createCluster:

  • When creating a DCM-Managed OracleAS Cluster with the createCluster command, use only the following characters in the cluster_name argument supplied with the -cl option:

    abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-
    
    
  • You must issue this command in the Oracle home of an Oracle Application Server Instance that belongs to an Oracle Application Server Farm. The DCM-Managed OracleAS Cluster will be created in that farm.

  • The DCM-Managed OracleAS Cluster has no members when created. You can add members using joinCluster.

  • You can create an unlimited number of DCM-Managed OracleAS Clusters.

Example

dcmctl createCluster -cl cluster1

A.3.9 createComponent

Creates an OC4J instance.

Type

Configuration Management

Syntax

createComponent -ct oc4j -co component_name

Description

Creates a new OC4J instance belonging to the local Oracle Application Server Instance. You cannot specify another Oracle Application Server Instance with the -i option; the command operates locally. Note that OC4J is currently the only component type allowed for this command.


Note:

When creating a component with the createComponent command, use only the following characters in the component_name argument supplied with the -co option:
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-

OC4J instance names and J2EE application names should not contain the host name, the Oracle home or IP address of the computer containing the Oracle Application Server installation. In a clustered environment, this applies to the host name, Oracle home, IP address of any Oracle Application Server installation in the DCM-Managed OracleAS Cluster.

For example, if your computer has the host name of abc.com, you should not create a new OC4J instance or J2EE application that consists of or contains abc.com. This rule also applies to the Oracle home directory path or the IP address of the computer.

The reason for this restriction has to do with the clustering, archival, and cloning features of DCM. When archiving or capturing configuration parameters, DCM scans all configuration files for occurrences of the host name, Oracle home and IP address. When it finds occurrences of these values, it replaces the values with symbolic macros and stores them in the DCM Repository.

When DCM applies these configurations to other installations, the occurrences of host name, Oracle home and IP address are replaced with the values for that installation to which the configuration is being applied. Consequently, if OC4J instance names or J2EE application names contain host names, Oracle home names or IP addresses, they are inappropriately substituted when the configuration is applied to other installations.

Example

dcmctl createComponent -ct oc4j -co OC4J_myapps

A.3.10 deployApplication

Deploys a J2EE application.

Type

Application

Syntax

deployApplication -f file -a app_name [-co comp_name] [-enableIIOP] [-rc rootcontext] [-pa parent_name]

In the preceding command:

  • file is the name of the WAR or EAR file to deploy

  • app_name is the name of the application specified by the user in original deployment

  • comp_name is the name of the OC4J instance to which the application will be deployed. The default is the home instance.

  • enable IIOP enables the Internet Inter-Orb Protocol

  • rootcontext is the base path used in the URL to access the web module (for example, http://hostname:port/context root). Applies to deployment of WAR files only.

  • parent_name is the parent application name. The parent application contains common classes used by child applications.

Description

The J2EE application is deployed to the specified Oracle Application Server Instance.

The deployApplication command does the following:

  1. Copies the WAR or EAR file from the specified location to the server.

  2. Expands the WAR or EAR file into the runtime directories.

  3. Changes the context root in the OHS configuration file, the mount points in the oc4j.conf file, and the server.xml file as necessary.

  4. Persists all files into the DCM repository.

  5. (If multiple nodes) Copies files from the local node to the remote node(s), and invokes the remote node processing.

Example

To deploy an application to the home OC4J instance:

dcmctl deployApplication -f app1.ear -a app1

To deploy an application to the OC4J_my_apps instance:

dcmctl deployApplication -f app1.ear -a app1 -co OC4J_myapps

To deploy a WAR file to the home OC4J instance:

dcmctl deployApplication -f app2.war -a app1 -rc /myiAS/myWebapps

A.3.11 destroyInstance

Removes an Oracle Application Server Instance from the DCM Metadata Repository.


Note:

This command is intended for use only with specific guidance from Oracle support, because its effects are irreversible (that is, the Oracle Application Server Instance is unrecoverable). The Oracle Universal Installer uses this command in its deinstallation routine to remove all DCM data associated with the named Oracle Application Server Instance from the Metadata Repository.

Type

Configuration Management

Syntax

destroyInstance -i instance_name

Description

Removes all information related to the specified Oracle Application Server Instance from the DCM repository. The need for this command arises when an Oracle Application Server Instance is removed using operating system commands on files or directories, and the repository information about the Oracle Application Server Instance remains. This may cause problems in subsequent installation attempts. The destroyInstance command clears the repository of all vestiges of an Oracle Application Server Instance that was removed precipitously.

If the command is executed in the Oracle Application Server Instance being destroyed, the dcm.conf file, targets.xml file, and the repository directory will be cleaned up. If it is executed remotely, you should check to ensure that the instance-related information has been removed, and, if not, remove it manually.

Example

dcmctl destroyInstance -i instance1

A.3.12 echo

Displays the specified string to standard output.

Type

Shell

Syntax

echo

Description

Used in a dcmctl command script to display a specified string to standard output.

Example

echo "this is a comment"

A.3.13 exit

Exits a dcmctl shell client.

Type

Shell

Syntax

exit

Description

Exits a dcmctl shell client. This command is only applicable to the shell; it does not affect the dcmctl daemon.

Example

exit

A.3.14 exportArchive

Exports the named archive from the repository to a JAR file.

Type

Archive

Syntax

exportArchive -arch archiveName -f myFile [-comment myComments]

Description

See "Exporting and Importing Archives".

Example

dcmctl exportArchive –arch archive1 –f /exports/testConfig  -comment "this is an export of archive1"

A.3.15 exportRepository

Copies the named file-based repository to the specified location.

Type

Configuration Management

Syntax

exportRepository -f myFile [-force]

Description

Copies the file-based repository information to the location specified. Use the -force option to overwrite an existing file. If you do not use the -force option and the named file exists, an exception is thrown.

Note for using exportRepository:

  • Typically, when you use the exportRepository command, you also use the importRepository command on another Oracle Application Server Instance. Before executing the importRepository command, stop all DCM daemons in the Oracle Application Server Instances that are part of the Oracle Application Server Farm in which you run importRepository. Use the following command in each Oracle Application Server Instance in the Oracle Application Server Farm to stop the DCM daemon:

    ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon
    

Example

This example assumes two Oracle Application Server Instances: instance1 and instance2. To relocate the file-based repository host from instance1 to instance2, perform the following steps:

On instance1, the original file-based repository host issue these commands:

ORACLE HOME/dcm/bin> dcmctl exportrepository -f /export/repository_save_file
ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon

If there are more than two Oracle Application Server Instances, stop the daemon on all of the other Oracle Application Server Instances.

On instance2, issue these commands:

ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon
ORACLE HOME/dcm/bin> dcmctl importrepository -f /export/repository_save_file

On instance1, issue this command:

ORACLE HOME/dcm/bin> dcmctl repositoryrelocated

After the repositoryRelocated command completes, start the dcm daemons, as follows:

On instance1 issue this command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

When this command completes, on instance2, issue the command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

If there are more than two Oracle Application Server Instances, on all of the other Oracle Application Server Instances issue the command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

A.3.16 fileCleanUp

Purges outdated records found in the file-based repository.

Type

Configuration Management

Syntax

fileCleanUp dump | clean [-force]

Description

Purges outdated records from the file-based repository. The data tables in a file-based repository are limited in size, and should be purged periodically to make room for new transactions. DCM operations may fail when the tables become full. You must stop the DCM daemon (opmnctl stopproc ias-component=dcm-daemon) before you execute the fileCleanUp clean command.

Backing up the ORACLE_HOME/dcm/repository directory is recommended before using fileCleanUp.

Example

To list the contents of the repository tables:

dcmctl fileCleanUp dump 

To purge the outdated records from the repository:

dcmctl fileCleanUp clean 

A.3.17 getComponentType

Returns the type of the component in the local Oracle Application Server Instance or specified Oracle Application Server Instance.

Type

Configuration Management

Syntax

getComponentType [-i instance_name] -co component_name

Description

Returns the type of the component to standard output. By default, it returns the type of the component in the local Oracle Application Server Instance. You can use the -i option to specify a different Oracle Application Server Instance.

Example

To obtain the type of the home component in the local Oracle Application Server Instance:

dcmctl getComponentType -co home

OC4J

To obtain the type of the OC4J_SECURITY component in instance1:

dcmctl getComponentType -co OC4J_SECURITY -i instance1
OC4J

A.3.18 getError

Displays descriptions of errors.

Type

dcmctl Properties

Syntax

getError [error_number | error_name]

Description

Displays error descriptions. If you issue this command with no arguments, it displays the error message from the most recent DCM error that occurred. If the debug option is set to on, the stack trace is printed, if there was one. If you provide an error number or error name, it displays the message for that error.

Example

To view the description of the error that occurred most recently:

dcmctl getError

You can use the following commands to print the messages for ADMN-906025:

dcmctl getError 906025
dcmctl getError ADMN-906025

A.3.19 getOPMNPort

Returns the hostname and Oracle Notification Service remote port.

Type

Manually Managed OracleAS Cluster

Syntax

getOPMNPort

Description

This command returns the hostname and the ONS remote port for the local Oracle Application Server Instance. It retrieves this information from the ons.conf file.

Example

dcmctl getopmnport
myhost.example.com:6200

A.3.20 getRepositoryId

Returns the repository ID of an OracleAS File-Based Farm repository.

Type

Configuration Management

Syntax

getRepositoryId

Description

Returns the repository identifier of the OracleAS File-Based Farm to which the Oracle Application Server Instance belongs. If the Oracle Application Server Instance is a standalone Oracle Application Server Instance, this command returns the repository identifier for the Oracle Application Server Instance. If the standalone Oracle Application Server Instance is to be used to establish a new distributed File-based repository, then use the returned repository identifier to initialize the repository host with joinFarm and the -r option.

Example

dcmctl getRepositoryId

A.3.21 getReturnStatus

Returns the status of the last dcmctl command.

Type

dcmctl Properties

Syntax

getReturnStatus

Description

This command displays the status of the last dcmctl command that performed an asynchronous operation (as opposed to a command that returned information). This command is intended to be used to get the status of a previous command that timed out. You can issue the getReturnStatus command repeatedly until it reports that the previous command has finished.

For synchronous operations, use the getError command to retrieve more information on the last failed command.

Example

In this example, the start command times out and the getReturnStatus command is used to check for status:

dcmctl getReturnStatus

ADMN-906005

The specified command, "start", is being executed asynchronously. The maximum wait time of, 120 seconds, has been reached. This operation will continue to execute to completion. Use the "getReturnStatus" command to determine if/when the operation completes successfully.

A.3.22 getState

Returns the state of the components in the indicated scope. The getState command only displays the state of the following components: OC4J, Oracle HTTP Server, and JAZN.

Type

Configuration Management

Syntax

getState [-i instance_name] [-cl cluster_name] [-co component_name]

Description

Without any arguments, this command returns the state of all components in the local Oracle Application Server Instance. The state includes the following indicators:

  • Up Status — indicates whether a component is running

  • In Sync Status — indicates whether the component's configuration is synchronized with the configuration in the DCM repository

You can use arguments with the command to narrow the scope of the command by Oracle Application Server Instance, DCM-Managed OracleAS Cluster, or component.

If you execute the getState command with verbose option set to off, the output (which is intended to facilitate parsing for scripting purposes) appears in the form:

x:y:z

where:

  • x is the number of components running

  • y is the number of components in the process of starting or stopping

  • z is the total number of components

Example

To get the state of the local Oracle Application Server Instance:

dcmctl getState

To get the state of the component HTTP_Server:

dcmctl getState -co HTTP_Server

To get the state of a managed OracleAS Cluster:

dcmctl getState -cl cluster1

A.3.23 help

Returns a listing of dcmctl commands or help for a specific command.

Type

dcmctl Properties

Syntax

help [commandName]

Description

Returns a listing of dcmctl commands. If a command name is specified after the help command, description and syntax information on that command is returned.

Example

To list all commands:

dcmctl help

To get help for the createComponent command:

dcmctl help createcomponent

A.3.24 importArchive

Imports an archive file to the current repository.

Type

Archive

Syntax

importArchive [-arch archiveName] -f myFile [-comment "myComments"]

Description

Imports the named archive file from the file system to the current repository. Use -arch to change the name and -comment to change the comment during the import.

Example

dcmctl importArchive -arch Archive1 -f /exports/testConfig  -comment "this is an import"

A.3.25 importRepository

Moves an OracleAS File-Based Farm repository from one Oracle Application Server Instance to another.

Type

Configuration Management

Syntax

importRepository -f file_name [-force]

Description

Moves a OracleAS File-Based Farm repository from one Oracle Application Server Instance to another, based on a saved file from the exportRepository command. The repository may be restored to any Oracle Application Server Instance in the farm. If the current Oracle Application Server Instance is not hosting a repository, dcmctl prompts for confirmation of the action, unless the -force option is used.

If the repository has been moved, and the former repository host is still a member of the farm, then the repositoryRelocated command must be run in the former repositoryhost Oracle Application Server Instance to notify it that it is no longer the host.

Note for using importRepository:

  • Before executing importRepository, stop all DCM daemons in the Oracle Application Server Instances that are part of the OracleAS File-Based Farm in which you are running importRepository. Use the following command in each Oracle Application Server Instance in the Oracle Application Server Farm to stop the DCM daemon:

    ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon
    

Example

This example assumes two Oracle Application Server Instances: instance1 and instance2. To relocate the OracleAS File-Based Farm repository host from instance1 to instance2, perform the following steps:

On instance1, the original OracleAS File-Based Farm repository host, issue these commands:

ORACLE HOME/dcm/bin> dcmctl exportrepository -f /export/repository_save_file
ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon

If there are more than two Oracle Application Server Instances, issue the opmnctl stopproc command on all of the other Oracle Application Server Instances.

On instance2, issue these commands to stop the DCM daemon, and then import the saved repository:

ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon
ORACLE HOME/dcm/bin> dcmctl importrepository -f /export/repository_save_file

On instance1, issue this command:

ORACLE HOME/dcm/bin> dcmctl repositoryrelocated

After the repositoryrelocated command completes, sequentially, start the DCM daemons, as follows:

On instance1, issue this command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

When this command completes, on instance2, issue this command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

If there are more that two Oracle Application Server Instances, on all of the other Oracle Application Server Instances issue this command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

A.3.26 isClusterable

Identifies whether an Oracle Application Server Instance can become a member of a DCM-Managed OracleAS Cluster.

Note for using DCM-Managed OracleAS Clusters:

  • Oracle Application Server supports heterogeneous Oracle Application Server Instances as part of the same farm. For example, an Oracle Application Server Instance running on Solaris operating system, an Oracle Application Server Instance running on a Linux system, and an Oracle Application Server Instance running on a Windows system can reside in the same farm. Oracle Application Server Instances that you want to join to a DCM-Managed OracleAS Cluster must be of the same installation type and version and be installed on a like operating system. For example, Solaris and Linux systems may be clustered.

Type

Configuration Management

Syntax

isClusterable [-i instance_name | -arch archive_name]

Description

Identifies whether an Oracle Application Server Instance is eligible to become a member of a DCM-Managed OracleAS Cluster. By default, this command uses the local Oracle Application Server Instance. You can use the -i option to specify a different Oracle Application Server Instance. In order for an Oracle Application Server Instance to be eligible, all components in the Oracle Application Server Instance must be clusterable.

If the Oracle Application Server Instance is ineligible, and the verbose option is on, the reason is included with the false answer returned by the command.

Example

dcmctl isClusterable

A.3.27 isCompatible

Identifies whether an Oracle Application Server Instance is compatible with other members of an DCM-Managed OracleAS Cluster.

Type

Configuration Management

Syntax

isCompatible -cl cluster_name [-i instance_name | -arch archive_name]

Description

Identifies whether an Oracle Application Server Instance is compatible with other members of an DCM-Managed OracleAS Cluster. By default, this command uses the local Oracle Application Server Instance. You can use the -i option to specify a different Oracle Application Server Instance. An Oracle Application Server Instance is compatible if it has the same components configured and is of the same version.

Example

dcmctl isCompatible -cl cluster1

A.3.28 joinCluster

Adds an Oracle Application Server Instance to the named DCM-Managed OracleAS Cluster.

Notes for using DCM-Managed OracleAS Clusters:

  • Oracle Application Server supports heterogeneous Oracle Application Server Instances as part of the same farm. For example, an Oracle Application Server Instance running on Solaris operating system, an Oracle Application Server Instance running on a Linux system, and an Oracle Application Server Instance running on a Windows system can reside in the same farm. Oracle Application Server Instances that you want to be part of a OracleAS Cluster must be of the same installation type and version, and be installed on a like operating system. For example, Solaris and Linux systems may be clustered.

  • If you are using Oracle Enterprise Manager 10g Application Server Control Console, then after issuing joinCluster command, you must stop and then start Oracle Enterprise Manager 10g Application Server Control Console using the commands:

    emctl stop iasconsole
    emctl start iasconsole
    

Type

Configuration Management

Syntax

joinCluster -cl cluster_name [-i instance_name]

Description

Adds an Oracle Application Server Instance to the DCM-Managed OracleAS Cluster specified with the -cl option. By default, this command uses the local Oracle Application Server Instance. You can specify a different Oracle Application Server Instance with the -i option. The Oracle Application Server Instance must be a member of the same Oracle Application Server Farm as the DCM-Managed OracleAS Cluster. There is no limit to the number of Oracle Application Server Instances you can add to a DCM-Managed OracleAS Cluster. An Oracle Application Server Instance is stopped after being added to an DCM-Managed OracleAS Cluster, so you must manually start it.

Example

To add the local Oracle Application Server Instance to cluster1 and restart it:

dcmctl joinCluster -cl cluster1
opmnctl @cluster startproc

To add instance1 to cluster1 and restart it:

dcmctl joinCluster -cl cluster1 -i instance1
opmnctl @instance startproc

A.3.29 joinFarm

Associates an Oracle Application Server Instance with an OracleAS Database-based Farm or an OracleAS File-Based Farm.

Notes for using Oracle Application Server Farms and the joinFarm command:

  • Oracle Application Server supports heterogeneous Oracle Application Server Instances as part of the same farm. For example, an Oracle Application Server Instance running on Solaris operating system, an Oracle Application Server Instance running on a Linux system, and an Oracle Application Server Instance running on a Windows system can reside in the same farm.

  • If you are using Oracle Enterprise Manager 10g Application Server Control Console, then after issuing joinFarm command, you must stop and then start Oracle Enterprise Manager 10g Application Server Control Console using the commands:

    emctl stop iasconsole
    emctl start iasconsole
    
    

Note:

When an Oracle Application Server Instance joins a farm, all archives for the Oracle Application Server Instance are removed. If you want to preserve the archives on the Oracle Application Server Instance that is joining the farm, export each of the archives with the exportArchive command prior to using the joinfarm command.

Type

Configuration Management

Syntax

joinFarm [-r repository_ID]

Description

With the -r option and a repository ID, it associates an Oracle Application Server Instance with the named OracleAS File-Based Farm repository. The repository ID is a hostname and port.

If the Oracle Application Server Instance was originally associated with a OracleAS Database-based Farm, using Infrastructure database information, you can issue this command without arguments to reassociate the Oracle Application Server Instance with the original database.

You can obtain the repository ID by issuing the getRepositoryId command on any Oracle Application Server Instance that is a member of the OracleAS File-Based Farm associated with the repository.

Example

To reassociate the Oracle Application Server Instance with a OracleAS Database-Based Farm:

dcmctl joinFarm

To associate the Oracle Application Server Instance with a OracleAS File-Based Farm:

dcmctl joinFarm -r myhost.mycompany.com:1899

A.3.30 leaveCluster

Removes an Oracle Application Server Instance from an DCM-Managed OracleAS Cluster.

Type

Configuration Management

Syntax

leaveCluster [-i instance_name]

Description

Removes an Oracle Application Server Instance from its DCM-Managed OracleAS Cluster. By default, this command uses the local Oracle Application Server Instance. You can specify a different Oracle Application Server Instance with the -i option. The Oracle Application Server Instance being removed is stopped, so you must restart it after using this command.

Notes for using leaveCluster:

  • A middle tier instance that leaves a cluster must be re-registered with OracleAS Single Sign-On. The registration process gives the instance a new encryption key for communicating with the OracleAS Single Sign-On server, and updates the instance's URL. Before you invoke the registration utility, you must set the ORACLE_HOME environment variable.

    The registration utility is available in ORACLE_HOME/sso/bin. Its syntax and required parameters are:

    ssoreg.sh or ssoreg.bat

    -oracle_home_path oracleHome

    -site_name siteName (the host name and port of the partner application)

    -config_mod_osso TRUE

    -mod_osso_url modOSSOURL (the URL used to access the partner application)

    For additional information, see the Oracle Application Server Single Sign-On Administrator's Guide.

  • If you are using Oracle Enterprise Manager 10g Application Server Control Console, then after issuing the dcmctl leaveCluster command, you must stop and then start Oracle Enterprise Manager 10g Application Server Control Console using the commands:

    emctl stop iasconsole
    emctl start iasconsole
    
    

Example

To remove the local Oracle Application Server Instance from the DCM-Managed OracleAS Cluster:

dcmctl leaveCluster

To remove instance1 from its DCM-Managed OracleAS Cluster:

dcmctl leaveCluster -i instance1

A.3.31 leaveFarm

Removes an Oracle Application Server Instance from a farm.

Type

Configuration Management

Syntax

leaveFarm

Description

Removes an Oracle Application Server Instance from a farm. This command affects only the relationship between DCM and a repository, and has no impact on other components. Specific implications for this command on the repository and other components are as follows:

  • Only the metadata for the DCM-managed configuration is moved from the centralized DCM repository to a local Oracle Application Server Instance.

  • The Oracle Application Server Instance is removed from the repository, but it is not removed from the Oracle Internet Directory. Therefore, if you have a complete Infrastructure installation (the Metadata Repository and Identity Management), the leaveFarm command removes the Oracle Application Server Instance the Metadata Repository, but it remains in Identity Management. To remove the Oracle Application Server Instance entirely, see Section 2.2.14, "Removing an Instance From the Infrastructure After Executing the leaveFarm Command".

  • When an Oracle Application Server Instance is removed from a farm, any associated archives are deleted from the centralized repository. For this reason, it is a good idea to issue the createArchive command immediately after issuing the leaveFarm command. This creates a new baseline archive for the Oracle Application Server Instance.

  • The leaveFarm command does not remove connections to the infrastructure database for other components, such as Oracle Application Server Single Sign-On or JAZN.

Note for using leaveFarm:

  • Using Oracle Enterprise Manager 10g Application Server Control Console, after issuing the dcmctl leaveFarm command, you must stop and then start Oracle Enterprise Manager 10g Application Server Control Console using the commands:

    emctl stop iasconsole
    emctl start iasconsole
    

Example

To remove an Oracle Application Server Instance from the farm:

dcmctl leaveFarm

A.3.32 listApplications

Lists the applications deployed in an OC4J instance within a farm, DCM-Managed OracleAS Cluster, Oracle Application Server Instance, or archive.

Type

Application

Syntax

listApplications [-farm] [-cl cluster_name] [-i instance_name] [-arch archive_name] [-co component_name] [-sort on | off] [pattern]

Description

List the applications deployed in the specified domain. The default is the home OC4J instance in the local Oracle Application Server Instance.

When using the dcmctl shell, you can limit the output with the pattern option, which enables you to list only the applications with names matching the pattern. Specify the pattern using the wildcard character * as a leading, trailing or embedded character (or in combination) in the string you want to match, or by itself to specify all. For example, *string, string*, st*ing, *trin*, *tr*ng and * are all valid uses of the wildcard to specify a pattern.


Note:

If the asterisk character is part of the string you want to match, you must prepend it with the escape character \ (backward slash).

Example

To list the applications in the home OC4J instance in the local application server instance:

dcmctl listApplications
1
Application:    ADFBC
Component Name: home
Component Type: OC4J
Cluster:        cluster1

2
Application:    ADFBCManager
Component Name: home
Component Type: OC4J
Cluster:        cluster1

3
Application:    IsWebCacheWorking
Component Name: home
Component Type: OC4J
Cluster:        cluster1

To list the applications in myInstance:

dcmctl listApplications -i myInstance
1
Application:    ADFBC
Component Name: home
Component Type: OC4J
Instance:       myInstance

2
Application:    ADFBCManager
Component Name: home
Component Type: OC4J
Instance:       myInstance

3
Application:    IsWebCacheWorking
Component Name: home
Component Type: OC4J
Instance:       myInstance

To list only the ADFBC applications when applications ADFBC, ADFBCManager and IsWebCacheWorking are present, the command and its resulting output would be:

dcmctl shell
dcmctl> listApplications A*
1
Application:    ADFBC
Component Name: home
Component Type: OC4J
Cluster:        cluster1

2
Application:    ADFBCManager
Component Name: home
Component Type: OC4J
Cluster:        cluster1

A.3.33 listArchives

Returns a list of archive names.

Type

Archive

Syntax

listArchives [–arch archive_name][-sort on| off]

Description

Returns a list of automatically generated archives (in ascending order by timestamp), followed by a list of user generated archives (in ascending order by archive name). If the -arch (archive name) option is used, only the named archive is listed.

Example

To list information about archives:

dcmctl listArchives
****** AUTO GENERATED ARCHIVES ******
1
Name:         dcm.autoarchive_138.2.142.2121ff7a1e.fcb87f2e6d.-7ffe
Source:       instance: my-sun.us.oracle.com 
Version:      10.1.2.0.0 
Comments:     Automatic archival prior to deployment of application IsWebCacheWkng 
Created:      2004-08-24 12:34:24.972 
Clusterable:  true

2
Name:         dcm.autoarchive_138.2.142.21212d3205.fcb882fb5b.-7fff
Source:       instance: my-sun.us.oracle.com
Version:      10.1.2.0.0
Comments:     Automatic archival prior to hand-editing of configuration files OC4J OHS opmn jazn 
Created:      2004-08-24 12:35:59.168
Clusterable:  true


****** USER GENERATED ARCHIVES ******
1
Name:         initial_archive_my-sun.us.oracle.com
Source:       instance: my-sun.us.oracle.com
Version:      10.1.2.0.0
Comments:     The initial archive after joining the farm for my-sun.us.oracle.com
Created:      2004-08-24 14:01:54.158
Clusterable:  true

A.3.34 listClusters

Lists the DCM-Managed OracleAS Clusters in the local Oracle Application Server Farm.

Type

Configuration Management

Syntax

listClusters

Description

This command lists the DCM-Managed OracleAS Clusters in the Oracle Application Server Farm that is associated with the local Oracle Application Server Instance.

When using the dcmctl shell, you can limit the output with the pattern option, which enables you to list only the DCM-Managed OracleAS Clusters whose names match the pattern. Specify the pattern using the wildcard character * as a leading, trailing or embedded character (or in combination) in the string you want to match, or by itself to specify all. For example, *string, string*, st*ing, *trin*, *tr*ng and * are all valid uses of the wildcard to specify a pattern.


Note:

If the asterisk character is part of the string you want to match, you must prepend it with the escape character \ (backward slash).

Example

To list DCM-Managed OracleAS Clusters in the local farm, which contains cluster1 and cluster2:

dcmctl listClusters
1  cluster2
2  cluster1

To list the DCM-Managed OracleAS Clusters whose name ends in 1:

dcmctl shell
dcmctl> listClusters *1
1  cluster1

A.3.35 listComponents

Lists components within the named scope.

Type

Configuration Management

Syntax

listComponents [-i instance_name] [-cl cluster_name] [-farm] [-arch archive_name] [pattern] [-sort on | off]

Description

Returns a list of the components in the specified scope. Without arguments, this command returns a list of components in the local Oracle Application Server Instance.

When using the dcmctl shell, you can limit the output with the pattern option, which enables you to list only the components whose names match the pattern. Specify the pattern using the wildcard character * as a leading, trailing or embedded character (or in combination) in the string you want to match, or by itself to specify all. For example, *string, string*, st*ing, *trin*, *tr*ng and * are all valid uses of the wildcard to specify a pattern.


Note:

If the asterisk character is part of the string you want to match, you must prepend it with the escape character \ (backward slash).

The listcomponents command may display components that OPMN manages. Use the opmnctl command to manage, start, stop, and restart these components.

Example

To list the components in the local Oracle Application Server Instance:

dcmctl listComponents
1
Component Name: home
Component Type: OC4J
Cluster:        cluster1

2
Component Name: HTTP_Server
Component Type: HTTP_Server
Cluster:        cluster1

To list only the components whose name contains the underscore character:

dcmctl shell
dcmctl> listcomponents *_*
1
Component Name: HTTP_Server
Component Type: HTTP_Server
Cluster:        cluster1

A.3.36 listComponentTypes

Lists supported component types.

Type

dcmctl Properties

Syntax

listComponentTypes

Description

Lists the component types that DCM supports.

Example

dcmctl listComponentTypes

A.3.37 listInstances

Lists the Oracle Application Server Instances in a Oracle Application Server Farm or DCM-Managed OracleAS Cluster.

Type

Configuration Management

Syntax

listInstances [-cl cluster_name] [pattern] [-farm]

Description

With no options, this command lists the Oracle Application Server Instances that belong to the same Oracle Application Server Farm as the local Oracle Application Server Instance, but are not part of an DCM-Managed OracleAS Cluster. If you use the -cl option, it lists only the Oracle Application Server Instances that are part of the specified DCM-Managed OracleAS Cluster. If you use the -farm option, it lists all Oracle Application Server Instances in the farm, identifying DCM-Managed OracleAS Cluster membership (if any) for each.

When using the dcmctl shell, you can limit the output with the pattern option, which enables you to list only the Oracle Application Server Instances whose names match the pattern. Specify the pattern using the wildcard character * as a leading, trailing or embedded character (or in combination) in the string you want to match, or by itself to specify all. For example, *string, string*, st*ing, *trin*, *tr*ng and * are all valid uses of the wildcard to specify a pattern.


Note:

If the asterisk character is part of the string you want to match, you must prepend it with the escape character \ (backward slash).

Example

Assume an Oracle Application Server Farm that includes five Oracle Application Server Instances. Two belong to the UNIX DCM-Managed OracleAS Cluster cluster1, two belong to the Windows DCM-Managed OracleAS Cluster cluster2, and one is a non-clustered Windows Oracle Application Server Instance.

To list all non-clustered Oracle Application Server Instances in the Oracle Application Server Farm associated with the local Oracle Application Server Instance:

dcmctl listInstances
1
Instance name: 10gTwo.my-pc.us.oracle.com
Cluster:
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\10gHome2

To list the Oracle Application Server Instances in cluster1:

dcmctl listInstances -cl cluster1 
1
Instance name: 1012AS01.my-sun.us.oracle.com
Cluster:       cluster1
Hostname:      my-sun.us.oracle.com
Oracle Home:   /private2/1012AS01

2
Instance name: AS1012.my-sun.us.oracle.com
Cluster:       cluster1
Hostname:      my-sun.us.oracle.com
Oracle Home:   /private2/1012AS

To list the Oracle Application Server Instances in cluster 2:

dcmctl listInstances -cl cluster2
1
Instance name: M28.my-pc.us.oracle.com
Cluster:       cluster2
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\M28Home

2
Instance name: 10gOne.my-pc.us.oracle.com
Cluster:       cluster2
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\10gHome1

To list all Oracle Application Server Instances in the farm:

dcmctl listInstances -farm
1
Instance name: 10gTwo.my-pc.us.oracle.com
Cluster:        
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\10gHome2

2
Instance name: M28.my-pc.us.oracle.com
Cluster:       cluster2
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\M28Home

3
Instance name: 10gOne.my-pc.us.oracle.com
Cluster:       cluster2
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\10gHome1

4
Instance name: 1012AS01.my-sun.us.oracle.com
Cluster:       cluster1
Hostname:      my-sun.us.oracle.com
Oracle Home:   /private2/1012AS01

5
Instance name: AS1012.my-sun.us.oracle.com
Cluster:       cluster1
Hostname:      my-sun.us.oracle.com
Oracle Home:   /private2/1012AS

To list Oracle Application Server Instances within the Oracle Application Server Farm whose name contains pc:

dcmctl shell
dcmctl> listinstances -farm *pc*
1
Instance name: 10gTwo.my-pc.us.oracle.com
Cluster:        
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\10gHome2

2
Instance name: M28.my-pc.us.oracle.com
Cluster:       cluster2
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\M28Home

3
Instance name: 10gOne.my-pc.us.oracle.com
Cluster:       cluster2
Hostname:      my-pc.us.oracle.com
Oracle Home:   C:\10gHome1

A.3.38 listOPMNLinks

Lists the Oracle Application Server Instances that are in a Manually Managed OracleAS Cluster with the local Oracle Application Server Instance.

Type

Manually Managed OracleAS Cluster

Syntax

listOPMNlinks

Description

This command lists all Oracle Application Server Instances that are in a Manually Managed OracleAS Cluster with the local Oracle Application Server Instance. These Oracle Application Server Instances could have been added to the Manually Managed OracleAS Cluster using the addOPMNLink command.

Example

dcmctl listopmnlinks
host1:6200
host2:6200

A.3.39 quit

Ends a dcmctl shell client session.

Type

Shell

Syntax

quit

Description

Ends a dcmctl shell client session. This command is only applicable to the shell; it does not affect the dcmctl daemon.

Example

quit

A.3.40 redeployApplication

Redeploys a J2EE application.

Type

Application

Syntax

redeployApplication -f file -a app_name [-co comp_name] [-enableIIOP] [-rc rootcontext]

In the preceding command:

  • file is the name of the WAR or EAR file to deploy

  • app_name is the name of the application specified by the user in original deployment

  • comp_name is the name of the OC4J instance to which the application will be deployed. The default is the home instance.

  • enableIIOP enables the Internet Inter-Orb Protocol

  • rootcontext is the base path used in the URL to access the web module (for example, http://hostname:port/context root). Applies to deployment of WAR files only.

Description

This command redeploys a J2EE application (WAR or EAR file) to the local Oracle Application Server Instance.

Example

To redeploy app1.ear to the home OC4J instance:

dcmctl redeployApplication -f app1.ear -a app1

To redeploy app1.ear to the OC4J_myapps instance:

dcmctl redeployApplication -f app1.ear -a app1 -co OC4J_myapps

To redeploy app2.war to the home OC4J instance:

dcmctl redeployApplication -f app2.war -a app1 -rc /myiAS/myWebapps

A.3.41 removeArchive

Removes one or more archive files.

Type

Archive

Syntax

removeArchive -arch [archive_name] [pattern]

Description

Removes the specified archive files from the DCM repository.

When using the dcmctl shell, you can specify multiple archives to remove with the pattern option, which removes all archives with names matching the pattern. Specify the pattern using the wildcard character * as a leading, trailing or embedded character (or in combination) in the string you want to match, or by itself to specify all. For example, *string, string*, st*ing, *trin*, *tr*ng and * are all valid uses of the wildcard to specify a pattern.


Note:

If the asterisk character is part of the string you want to match, you must prepend it with the escape character \ (backward slash).

Example

To remove archive3:

dcmctl removeArchive -arch archive3

To remove all archives whose name begins with init*:

dcmctl shell
dcmctl> removeArchive init*

A.3.42 removeCluster

Removes one or more DCM-Managed OracleAS Clusters from the farm.

Type

Configuration Management

Syntax

removeCluster -cl [cluster_name] [pattern]

Description

Removes the specified DCM-Managed OracleAS Cluster from its farm, or all DCM-Managed OracleAS Clusters whose name matches the pattern string. The DCM-Managed OracleAS Cluster must contain no Oracle Application Server Instances when it is removed. This command destroys all information about the DCM-Managed OracleAS Cluster in the DCM repository.

When using the dcmctl shell, you can specify multiple DCM-Managed OracleAS Clusters to remove with the pattern option, which removes all DCM-Managed OracleAS Clusters with names matching the pattern. Specify the pattern using the wildcard character * as a leading, trailing or embedded character (or in combination) in the string you want to match, or by itself to specify all. For example, *string, string*, st*ing, *trin*, *tr*ng and * are all valid uses of the wildcard to specify a pattern.


Note:

If the asterisk character is part of the string you want to match, you must prepend it with the escape character \ (backward slash).

Example

To remove cluster1 from a Oracle Application Server Farm containing cluster1, cluster2 and cluster3:

dcmctl removeCluster -cl cluster1

To remove all DCM-Managed OracleAS Clusters from a Oracle Application Server Farm containing cluster1, cluster2, cluster3:

dcmctl shell
dcmctl> removeCluster -cl *

A.3.43 removeComponent

Destroys one or more OC4J instances.

Type

Configuration Management

Syntax

removeComponent -co [component_name] [pattern]

Description

Destroy the named OC4J instance, or all OC4J instances in the local Oracle Application Server Instance whose name matches the pattern string. Note that OC4J is the only component type allowed for this command. You cannot remove an OC4J instance that was created by the installation process (such as OC4J_SECURITY).

When using the dcmctl shell, you can specify multiple components to remove with the pattern option, which removes all components with names matching the pattern. Specify the pattern using the wildcard character * as a leading, trailing or embedded character (or in combination) in the string you want to match, or by itself to specify all. For example, *string, string*, st*ing, *trin*, *tr*ng and * are all valid uses of the wildcard to specify a pattern.


Note:

If the asterisk character is part of the string you want to match, you must prepend it with the escape character \ (backward slash).

Example

To destroy the instance OC4J_myapps:

dcmctl removeComponent -co OC4J_myapps

To destroy all OC4J instances whose names begin with my:

dcmctl shell
dcmctl> removeComponent -co my*

A.3.44 removeOPMNLink

Removes Oracle Application Server Instances from a Manually Managed OracleAS Cluster.

Type

Manually Managed OracleAS Cluster

Syntax

removeOPMNLink hostname:port[, hostname:port...]

Description

Removes one or more Oracle Application Server Instances from a Manually Managed OracleAS Cluster. You must run this command in the Oracle home of each Oracle Application Server Instance in the Manually Managed OracleAS Cluster.

Example

This example shows a Manually Managed OracleAS Cluster with three Oracle Application Server Instances on host1, host2, and host3. The command removes the host2 Oracle Application Server Instance.

HOST2_ORACLE_HOME/dcm/bin/dcmctl listopmnlinks
host1:6200
host2:6200
host3:6200
HOST1_ORACLE_HOME/dcm/bin/dcmctl removeopmnlink host2:6200
HOST2_ORACLE_HOME/dcm/bin/dcmctl removeopmnlink host2:6200
HOST3_ORACLE_HOME/dcm/bin/dcmctl removeopmnlink host2:6200

A.3.45 repositoryRelocated

Notifies an Oracle Application Server Instance that it is no longer hosting a repository.


Note:

Usually, you use the repositoryRelocated command after an associated exportRepository and importRepository. Before running importRepository and repositoryRelocated, stop all DCM daemons in the Oracle Application Server Instances that are part of the Oracle Application Server Farm in which you run repositoryRelocated.

Use the following command in each Oracle Application Server Instance in the Oracle Application Server Farm to stop the DCM daemon:

ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon

Type

Configuration Management

Syntax

repositoryRelocated

Description

Notifies an Oracle Application Server Instance that the repository it formerly hosted has been imported to another Oracle Application Server Instance. This command is issued in the Oracle Application Server Instance that formerly hosted the repository.

This command is used in conjunction with the importRepository command. An Oracle Application Server Farm can only be associated with one repository at a time. When the repository is imported to a new Oracle Application Server Instance of the Oracle Application Server Farm, the old Oracle Application Server Instance must be notified, with the repositoryRelocated command, that it is no longer the repository host.

Example

This example assumes two Oracle Application Server Instances: instance1 and instance2.

To relocate the file-based repository host from instance1 to instance2, perform the following steps:

On instance1, the original file-based repository host, issue these commands:

ORACLE HOME/dcm/bin> dcmctl exportrepository -f /export/repository_save_file
ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon

If there are more than two Oracle Application Server Instances, stop the daemon on all of the other Oracle Application Server Instances.

On instance2, issue these commands:

ORACLE HOME/opmn/bin> opmnctl stopproc ias-component=dcm-daemon
ORACLE HOME/dcm/bin> dcmctl importrepository -f /export/repository_save_file

On instance1, issue this command:

ORACLE HOME/dcm/bin> dcmctl repositoryrelocated

After the repositoryrelocated command completes, start the DCM daemons as follows:

On instance1, issue this command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

When the command completes, on instance2, issue this command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

If there are more that two Oracle Application Server Instances, on all of the other Oracle Application Server Instances issue this command:

ORACLE HOME/opmn/bin> opmnctl startproc ias-component=dcm-daemon

A.3.46 resetDCMCachePort

Updates the port used by the DCM cache for Oracle Application Server Instance discovery in DCM-Managed OracleAS Clusters that are managed using a file-based repository.

Type

Configuration Management

Syntax

resetDCMCachePort [new_port_number] [-r]

Description

Changes the port value used by the DCM cache in DCM-Managed OracleAS Clusters in an OracleAS File-Based Farm. To find the current host and port, issue the command without arguments, as follows:

dcmctl resetDCMCachePort

To update the port associated with the current Oracle Application Server Instance, issue the command with the new port number, as follows:

dcmctl resetDCMCachePort 12345

If the port value is changed on the Oracle Application Server Instance that is hosting the repository, other Oracle Application Server Instances in the OracleAS File-Based Farm may not be able to locate the repository. If this occurs, issue the following command in the Oracle Application Server Instance that cannot locate the repository:

dcmctl resetDCMCachePort -r 12345

In the preceding command, 12345 is the port number set at the repository host.

Example

To find the current host and port:

dcmctl resetDCMCachePort

To update the port associated with the current Oracle Application Server Instance:

dcmctl resetDCMCachePort 12345

To notify an Oracle Application Server Instance of the location of the repository:

dcmctl resetDCMCachePort -r 12345

A.3.47 resetFileTransaction

Resets a file-based repository to its pre-transaction state after an interrupted operation.

Type

Configuration Management

Syntax

resetFileTransaction

Description

Resets a file-based repository. If an operation on a File-based repository is interrupted with control-c, uncommitted information may be left in the repository. This command blocks all subsequent updates to the repository, cleans up uncommitted data, and reopens the repository for update.

Example

dcmctl resetfiletransaction

A.3.48 resetHostInformation

Updates IP address or hostname information.

Type

Configuration Management

Syntax

resetHostInformation [-r repository_hostname]

Description

If the IP address or hostname information has changed for an Oracle Application Server Instance in the farm, this command updates the repository and the ons.conf file with the new information. This command is used in the local Oracle Application Server Instance. If the host information changes for the repository host of an OracleAS File-Based Farm, it is best to have all Oracle Application Server Instances running, so that all Oracle Application Server Instances can locate the repository.

For Oracle Application Server Instances that were not running during the change, it may be necessary to update the repository host information directly. Use the -r option and the name of the repository host to do this.

Example

resethostinformation

A.3.49 restart

This command is deprecated in Oracle Application Server 10g. Use opmnctl to manage processes in Oracle Application Server 10g. See the Oracle Process Manager and Notification Server Administrator's Guide for information on using opmnctl.

A.3.50 restoreInstance

This command is deprecated in Oracle Application Server 10g. Use archiving commands to save and restore instances in Oracle Application Server 10g. To move configuration between Oracle Application Server Instances in a farm, use the applyClusterTo and applyInstanceTo commands. To move configuration between farms, use the exportArchive and importArchive commands.

A.3.51 resyncInstance

Resynchronizes Oracle Application Server Instance configuration files with the DCM repository.

Type

Configuration Management

Syntax

resyncInstance [-force]|[-i instance_name]

Description

Resynchronizes the Oracle Application Server Instance configuration files with the contents of the DCM repository. This command takes all data from the repository that is not yet propagated and writes it out to the configuration files for the specified Oracle Application Server Instance. It updates the Oracle HTTP Server, OC4J, and OPMN configuration files, as well as the targets.xml file. It may also deploy or undeploy applications and add or remove components, as required. This could involve lengthy processing; use this command judiciously.

This command operates on the local Oracle Application Server Instance, unless you specify a different Oracle Application Server Instance with the -i option.

By default, the command only updates the configuration files for components whose In Sync Status is false (see getState). You can use the -force option to force it to update all configuration information.

Example

To resynchronize instance1 with the contents of the DCM repository:

dcmctl resyncinstance -i instance1

To force all files in the local Oracle Application Server Instance to be updated with that is in the DCM repository:

dcmctl resyncinstance -force

A.3.52 saveInstance

This command is deprecated in Oracle Application Server 10g. Use createArchive to save an instance's configuration.

A.3.53 set

Sets dcmctl options, timeout value, sorting preference, and number of versions for automatically archived Oracle Application Server Instances.

Type

dcmctl Properties

Syntax

dcmctl set [-v off | on] [-d off | on] [-t timeout_value] [-arch number_of_auto_archive_versions] [-sort on]

Description

Sets properties of the dcmctl utility. The set command enables you to set the -verbose and -debug flags on a persistent basis, and the default time out value to be set on a persistent basis. You can also specify the number of versions to be automatically archived, and whether to sort the output of list commands.

When set is run without any arguments, it displays the current settings.

Example

To turn verbose and debug off, and set the timeout value to 200:

dcmctl set -v off -d off -t 200

To view current settings:

dcmctl set
Verbose:  true
Sort:  false
Debug:  true
Default Timeout:  120
Auto Archive Count:  10

To set name sorting of 'list' command output on:

set -sort on

To automatically archive 45 versions of an Oracle Application Server Instance:

set -arch 45

To turn off automatic archiving:

set -arch 0

A.3.54 setLogLevel

Sets the logging level.

Type

Shell

Syntax

Level [-admin] [error] [notification] [debug] [trace]

Description

Sets the logging level for the dcmctl client shell, or for the daemon (with the -admin option).

Example

To set the DCM daemon logging level:

setloglevel -admin notification

To set the dcmctl shell log level:

setloglevel notification

A.3.55 shell

Starts the dcmctl shell.

Type

Shell

Description

Starts the dcmctl shell, and, optionally, executes the commands in a named file.

Syntax

dcmctl shell [-f file_name]

Example

To start the shell:

dcmctl shell

To start the shell and execute the commands in the file myDCMCommands:

dcmctl shell -f myDCMCommands

A.3.56 shutdown

This command is deprecated in Oracle Application Server 10g. Use opmnctl to manage processes in Oracle Application Server 10g. See the Oracle Process Manager and Notification Server Administrator's Guide for information on using opmnctl.

A.3.57 start

This command is deprecated in Oracle Application Server 10g. Use opmnctl to manage processes in Oracle Application Server 10g. See the Oracle Process Manager and Notification Server Administrator's Guide for information on using opmnctl.

A.3.58 stop

This command is deprecated in Oracle Application Server 10g. Use opmnctl to manage processes in Oracle Application Server 10g. See the Oracle Process Manager and Notification Server Administrator's Guide for information on using opmnctl.

A.3.59 updateConfig

Updates the repository with information from local configuration files.

The purpose of the updateConfig operation is to take the configuration that is currently stored in the local file system and place it into the DCM repository. This is a coarse grained operation with minimal validation of the content of the configuration file.

The dcmctl updateConfig command should be used in limited and controlled situations. It is recommended that when changing DCM-managed configuration for Oracle HTTP Server, OC4J, OC4J applications, OPMN, or JAZN that you use the Application Server Control Console. If you use the Application Server Control Console, then you do not need to use updateConfig.

If you need to manually edit configuration files for a component, you must use updateConfig to place these changes into the DCM repository. If you make manual changes and you do not run updateConfig the changes will be overwritten the next time that the configuration is resynchronized.


Caution:

Do not run updateConfig concurrently with any other dcmctl commands or while performing Application Server Control Console configuration operations across multiple Oracle Application Server Instances in a Oracle Application Server Farm or DCM-Managed OracleAS Cluster.

Type

Configuration Management

Syntax

updateConfig [-ct component_type [, component_type...]] [-force]

Description

Updates the DCM repository with the information in local configuration files.

To do this, DCM obtains all configuration documents from the OHS, OC4J, OPMN and JAZN plug-ins and copies them to the repository. The updated documents are given back to the plug-ins and each plug-in decides whether or not to notify the respective component.

With no arguments, this command updates all DCM managed components, configuration files, as well as the targets.xml file. It does not cause all applications to be redeployed, but if an EAR or an expanded EAR file was changed manually since the last deployment, it will redeploy the application.

You can specify which component's configuration files to update with the -ct option.

Valid component types are:

ohs: Oracle HTTP Server

oc4j: Oracle Application Server Containers for J2EE

opmn: Oracle Process Manager and Notification Server

jazn: Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider

When you make manual configuration file changes in conjunction with the updateConfig command, use this approach:

  1. Verify that the Oracle Application Server Instance has the most current configuration from the DCM repository. Issue the resyncInstance command to resync the configuration.

  2. Create an explicit archive for the Oracle Application Server Instance or the OracleAS Cluster using createArchive.

  3. Ensure that there are no other administrative operations taking place in the Oracle Application Server Farm that may alter the configuration while you are making the manual change to the configuration. This includes Oracle Enterprise Manager 10g Application Server Control Console changes, deployments, or other dcmctl shell or dcmctl commands running in the farm.

  4. Make the manual configuration file change and test the change, if possible.

  5. Execute dcmctl updateConfig to place the updated configuration files into the DCM repository.

If safety precautions outlined in step 3 are not followed, there is a risk that conflicting changes will be placed in the repository. This could leave the configuration stored in the repository in a non-functional state, and could require a restore from the archive created in step 2. If you restore from the archive, you will need to restart at step 1.

Example

To register all configuration files with the Distributed Configuration Management repository and restart the Oracle HTTP Server:

ORACLE_HOME/dcm/bin> dcmctl updateConfig
ORACLE_HOME/opmn/bin> opmnctl restartproc ias-component=HTTP_Server

If you have just updated only an Oracle HTTP Server configuration file, you can register the change with the Distributed Configuration Management repository and restart Oracle HTTP Server as follows:

dcmctl updateConfig -ct ohs
ORACLE_HOME/opmn/bin> opmnctl restartproc ias-component=HTTP_Server

A.3.60 undeployApplication

Undeploys applications.

Type

Application

Syntax

undeployApplication -a application_name -co instance_name

Description

Undeploys the named application in the named OC4J instance.

Example

To undeploy the application testApp in the home OC4J instance:

undeployApplication -a testApp -co home

A.3.61 validateEarFile

Checks an EAR file for J2EE compliance.

Type

Application

Syntax

validateEarFile -f file [-noproxy]

Description

Examines the named EAR file and lists characteristics that are not compliant with the J2EE specification.

You may need to set up a proxy to enable access to DTDs on the Web. You can pass a parameter to the JVM using the ORACLE_DCM_JVM_ARGS environment variable to specify the proxy host and port.

Example

To validate the Pet Store EAR file:

dcmctl validateEarFile -f petstore.ear
Warning: J2EE/DTD validation errors were foundADMN-906001
{0}   Base Exception:   oracle.ias.sysmgmt.deployment.j2ee.exception.J2eeDeploymentException:Cannot get xml document by parsing /var/tmp/jar50152.tmp: Invalid element 'servlet' in content of 'web-app',   expected elements '[servlet-mapping, session-config, mime-mapping, welcome-file-list,   error-page, taglib, resource-ref, security-constraint, login-config, security-role, env-entry,   ejb-ref]'.

A.3.62 whichCluster

Returns the DCM-Managed OracleAS Cluster name for the named Oracle Application Server Instance.

Type

Configuration Management

Syntax

whichCluster [-i instance_name]

Description

Returns the name of the DCM-Managed OracleAS Cluster that contains the named Oracle Application Server Instance. If no Oracle Application Server Instance is specified, returns the name of the DCM-Managed OracleAS Cluster that contains the local Oracle Application Server Instance.

Example

dcmctl whichCluster

A.3.63 whichFarm

Identifies the type and location of the farm.

Type

Configuration Management

Syntax

dcmctl whichFarm

Description

Returns Oracle Application Server Farm name, host Oracle Application Server Instance, host name, and repository type, and SSL usage. If the repository is hosted by a third-party database, the hosting Oracle Application Server Instance name and host name are not available.

Example

dcmctl whichFarm
Farm Name: .private2.1012AS.dcm.repository
Host Instance: AS1012.my-sun.us.oracle.com
Host Name: my-sun.us.oracle.com
Repository Type: Distributed File-based (host)
SSL In Use: false

A.3.64 whichInstance

Returns the Oracle Application Server Instance name.

Type

Configuration Management

Syntax

whichInstance

Description

Returns the name of the local Oracle Application Server Instance.

Example

dcmctl whichInstance
1012AS01.my-sun.us.oracle.com