Skip Headers

Oracle Enterprise Manager Getting Started with Oracle Change Management Pack
Release 9.2.0

Part Number A96679-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

A
Command Line Interface Appendix

Oracle Change Management Pack provides a command line interface that is available on the Windows NT and UNIX operating systems. This appendix provides the following sections that provide more information about the command line interface:

Possible Uses for the Command Line Interface

You can use the Oracle Change Management Pack command line interface to perform various Change Management Pack tasks without accessing the Oracle Change Management Pack applications. Some of the tasks that you can perform using the command line interface include:

Understanding the Notation Used for the Command Syntax

The reference sections that describe each command in the Oracle Change Management Pack's command line interface use the following notation to describe command syntax:

Square brackets [...] denote optional elements.

Braces {...} denote a required element which can be one of two or more options separated by vertical bars |.

Square brackets enclosing options separated by vertical bars indicate an optional element which can be one of two or more options.

Italics denote elements to be substituted by the user, or elements that are further defined in the command description section.

All other characters are keywords and punctuation that should be typed as shown in the command descriptions.

Requirements for Using the Command Line Interface


Important:

Before issuing command line interface commands using the Solaris operating system, make sure that your default directory is the ORACLE_HOME/bin directory (where ORACLE_HOME is the directory in which Oracle Enterprise Manager is installed).

The command line interface on Solaris only recognizes command line interface commands that are issued in the ORACLE_HOME/bin directory. 


When you enter the command line interface commands interactively at the MS-DOS prompt or UNIX prompt, preface each command with the ocm keyword, for example:

ocm command-name

When you use the command line interface, replace command-name with the name of a command line interface command.

When you use the command line interface, do not leave any blank spaces between a command line option and the argument specified for the option. For example, in the following command, the -d, -s, -e, and -id options are followed immediately by their respective arguments, forward, cleanup, undo, and fred:

ocm execute plan15 corporate.world -dforward -scleanup -eundo -idfred


Note:

There is no continuation character for command line interface commands. Therefore, when you enter a command line interface command interactively at the command prompt, enter the entire command before pressing Return.

Similarly, when entering command line interface commands in a script file, do not enter enter a carriage return for a command until you have entered the complete command. 


Understanding Case-Sensitivity Requirements for the Command Line Interface

The command line interface's case-sensitivity requirements are:

Using the Command Line Interface with the Oracle Management Server

You can use the command line interface with or without the Oracle Management Server (OMS). When you execute the login command, a login dialog box is displayed that allows you to specify whether or not to use the Oracle Management Server. See "login command" for more information on the login command.

Scheduling the Execution of Command Line Interface Scripts

With the NT operating system, you can enter the command line interface commands in a .BAT file. You can then parameterize the .BAT file and run it at specified times and/or intervals using operating system facilities. The commands return a status code, which allows flow-of-control within the containing .BAT file. If you are entering the commands in a .BAT file, use the MS-DOS call command to preface calls to the command line interface commands, for example:

call ocm command-name

Similarly, with the UNIX operating system, you can enter the command line interface commands in a script. You can parameterize the script file and run it at specified times and/or intervals using operating system facilities. The commands return a status code, which allows flow-of-control within the containing script file.

Using the Command Line Interface Commands

Table A-1 lists each command line interface command and provides a brief description of the command's function:

Table A-1 Overview of Command Line Interface Commands  
Command  Use of the Command  For More Information 

login 

Establishes the credentials that an administrator will use during a command line interface session. 

See "login command" 

logout 

De-establishes the administrator credentials for the specified administrator. 

See "logout command" 

capture 

Captures a new baseline for an existing baseline specification. 

See "capture command" 

compare 

Compares databases, baselines, or a baseline and a database using an existing comparison specification. 

See "compare command" 

generate 

Generates a script from a change plan. 

See "generate command" 

execute 

Executes a script, undoes changes made by a previously-executed script, or cleans up after the successful execution of a script. 

See "execute command" 

login command

The login command is used to establish or change administrator credentials for a command line interface session. You must establish administrator credentials for a command line interface session, otherwise the command line interface commands that you issue will fail.

The syntax for the command is:

ocm login -ididentity

The string that you choose for the identity argument is used to uniquely identify you during a command line interface session. The identity string is case-sensitive.

For example, you can specify a login command like this one:

ocm login -idfred

When the login command is executed, a login dialog box displays that prompts you whether you want to use the command line interface logged into the Oracle Management Server, or whether you want to use the command line interface standalone (not logged into the Oracle Management Server). After you choose the mode in which you want to run the command line interface, the dialog box prompts you for the necessary credentials for that option:

The command line interface associates the string that you specified for the identity argument (fred in the example in this section) with:

Because of this association, when you execute other commands that include the same identity argument, the command line interface knows:

The login command sets the credentials in the administrator's environment that are used until one of the following occurs:

logout command

The logout command de-establishes the administrator credentials established with an earlier login command.

The syntax for the command is:

ocm logout -ididentity

For example, the following command ends the command line interface session for the administrator identified as fred:

ocm logout -idfred

See "login command" for more information about the identity argument.

capture command

The capture command captures a new baseline for an existing baseline specification.

The syntax for this command is:

ocm capture [-l] baseline-specification-name -ididentity

The baseline-specification-name must be the name of an existing baseline specification. The baseline-specification-name must exactly match the case of the baseline specification's name as it appears in the Change Manager application. Enclose the baseline-specification-name within double quotation marks if it contains special characters such as backslashes, asterisks, or spaces, for example:

ocm capture "Baseline Specification Name With Spaces" -idfred

The command in this example uses the baseline specification named "Baseline Specification Name With Spaces" to capture a new version of that baseline. The baseline is stored in the repository for the administrator identified as fred. Note that the identity specified with the -id argument was established previously with the login command. See "login command" for more information about the identity argument.

The optional -l option is used to enable logging for the capture command. When logging is enabled, the same messages that would be displayed in Create Baseline during a baseline creation operation are displayed in the DOS window or UNIX window while the capture command is executing. If the -l option is not specified on the command line, no messages are displayed in the DOS window or UNIX window while the capture command is executing.

Baselines cannot be viewed using the command line interface. To view a baseline Change Manager application, select the baseline in the navigator tree, and choose Object->View Baseline.

In some cases, the capture command may return a status code other than success. For example, the output of the command may be a non- success status code if the baseline specification referred to in the capture command does not exist. See Table A-2 for more information on exit status codes that can be returned by the command line interface.

compare command

The compare command compares databases and/or baselines using an existing comparison specification.

The syntax for this command is:

ocm compare [-l] comparison-specification-name -ididentity

Each comparison specification has a series of comparisons associated with it; the compare command creates another comparison in the series. The comparison-specification-name must be the name of an existing comparison specification. The comparison-specification-name must exactly match the case of the comparison specification's name as it appears in the Change Manager application. Enclose the comparison-specification-name within double quotation marks if it contains special characters such as backslashes, asterisks, or spaces, for example:

ocm compare "Comparison Specification Name With Spaces" -idfred

The command in this example uses the comparison specification named "Comparison Specification Name With Spaces" to capture a new version of that comparison. The comparison is stored in the repository for the administrator identified as fred. Note that the identity specified with the -id argument was established previously with the login command. See "login command" for more information about the identity argument.

The optional -l option is used to enable logging for the compare command. When logging is enabled, the same messages that would be displayed in the graphical user interface during a comparison creation operation are displayed in the DOS window or UNIX window while the compare command is executing. If the -l option is not specified on the command line, no messages are displayed in the DOS window or UNIX window while the compare command is executing.

Comparisons cannot be viewed using the command line interface. To view a comparison created using the compare command, select the comparison in Change Manager and choose Object->View Comparison.

In some cases, the compare command may return a status code other than success. For example, the output of the command may be a non- success status code if the comparison specification referred to in the compare command does not exist. See Table A-2 for more information on exit status codes that can be returned by the command line interface.

generate command

The generate command generates a script, script summary, and impact report. Generation is the process of applying the change requests in a plan to a destination database, producing a script that will carry out the change requests, a script summary, and an impact report that describes the changes that will be made when the script is executed at the destination database.

The syntax for this command is:

ocm generate [-l] plan destination-database -ididentity

The plan keyword identifies the plan for which you want to generate a script, script summary, and impact report. The destination-database keyword identifies the database at which the generated script will be executed (the generate command does not execute the script; the script can be executed later at the destination database using the execute command).

The plan that you specify for the plan keyword must already exist, and the destination database that you specify for the destination-database keyword must already be specified in that plan. The plan name must exactly match the case of the plan's name as it appears in the Change Manager application. The destination-database name is not case-sensitive, but it must match the name of the destination database as it appears in the Change Manager application.

Enclose the plan name within double quotation marks if it contains special characters such as backslashes, asterisks, or spaces, for example:

ocm generate "Plan Name With Spaces" personnel_db -idfred

The command in this example uses the generates a script, script summary, and impact report from the plan named "Plan Name With Spaces" for the personnel_db database. The script, script summary, and impact report are stored in the repository for the administrator identified as fred. Note that the identity specified with the -id argument was established previously with the login command. See "login command" for more information about the identity argument.

The optional -l option is used to enable logging for the generate command. When logging is enabled, the same messages that would be displayed in the graphical user interface during a script generation operation are displayed in the DOS window or UNIX window while the generate command is executing. If the -l option is not specified on the command line, no messages are displayed in the DOS window or UNIX window while the generate command is executing.

Scripts, script summaries, and impact reports cannot be viewed using the command line interface. To view the script, script summary and impact report generated with the generate command, start the Change Manager application, select the plan, and choose Object->Edit Change Plan. In Plan Editor, expand the tree and the destination database folder, then click the Script subobject. In the detail view, click the Script Summary tab to view the Script Summary page, then click Edit Script to view or edit the script itself. In the detail view, click the Impact Report tab to view the Impact Report page. In Plan Editor's detail view, you can also click the Options tab, then use the Options page to specify a commit interval, schema mapping, and/or a scratch tablespace to use when the script is executed at the destination database. Similarly, you can click the Advanced Options tab, then use the Advanced Options page to specify how modified exemplars should be applied when the script is executed at the destination database.

In some cases, the generate command may return a status code other than success. For example, the output of the command may be a non- success status code if the impact report contains warnings or errors, or if the script cannot be generated. See Table A-2 for more information on exit status codes that can be returned by the command line interface.

execute command

The execute command executes a script, undoes a previously-executed script, or cleans up after the successful execution of a script. The script must be in an appropriate state for the requested operation or the command will fail.

The syntax for this command is:

ocm execute [-l] plan destination-database
       [ [ -d{forward|backward|cleanup} ]
       [ -s{cleanup|exit} ]
       [ -e{undo|exit} ] ]
       -ididentity

The plan keyword identifies the name of the plan for which the script should be executed. The destination-database keyword identifies the database at which you want the script to execute. A script must already be generated for this plan and this destination database, otherwise the execute command will fail. The plan name must exactly match the case of the plan's name as it appears in the Change Manager application. The destination-database name is not case-sensitive, but it must match the name of the destination database as it appears in the Change Manager application. If the plan name contains special characters such as backslashes, asterisks, or spaces, enclose it within double quotation marks.

The optional -l option is used to enable logging for the execute command. When logging is enabled, the same messages that would be displayed in the graphical user interface during a script execution operation are displayed in the DOS window or UNIX window while the execute command is executing. If the -l option is not specified on the command line, no messages are displayed in the DOS window or UNIX window while the execute command is executing.

Note that the identity specified with the -id argument is an identity established previously with the login command. See "login command" for more information about the identity argument.

Execution logs cannot be viewed using the command line interface. To view the execution log for a script whose changes have been kept or undone with the execute command, start Change Manager, select the plan, and choose Object->Edit Change Plan. In Plan Editor, expand the tree and the destination database folder, then click the Run subobject. In the detail view, view the execution log on the Execution Log page.

Specifying the Direction in Which to Execute the Script

Use the -d option to specify the direction in which the script should be executed or to specify that you want to clean up after the successful execution of the script. The -d options are:

By default, the script is executed in the forward direction (from the start or from the last successfully completed step, as applicable).

Specifying Completion Actions for a Script Execution

The -s and -e options are used to specify completion actions.

Use the -s option to specify the action to be taken if the script executes successfully. The two -s options are:

If you do not use the -s option, the default action is to exit on success.

Use the -e option to specify the action to be taken if errors occur when the script executes. The two -e options are:

If you do not use the -e option, the default action is to exit on error.

Examples of Using the Execute Command

to execute a script in the forward direction, keeping the changes if the execution completes successfully and undoing the changes if the execution fails, you would use a command like the following:

ocm execute plan15 corporate.world -dforward -scleanup -eundo -idfred

To execute a script in the forward direction, undoing the changes if there is an error and exiting on success, you would use a command like the following:

ocm execute plan15 corporate.world -eundo -idfred

The following command executes a script in the forward direction, undoing the changes if there is an error and exiting on success. It also enables logging in the DOS or UNIX window while the execute command is executing:

ocm execute -l plan15 corporate.world -eundo -idfred

To keep the changes made by a script that has already executed successfully in the forward direction and exit on success or error, use a command like the following:

ocm execute plan15 corporate.world -dcleanup -idfred

You can also execute a script in the backward direction, which undoes the changes made a script that has been executed in the forward direction. The backward option works only if the script was previously executed in the forward direction, either to completion or to a point of failure. To do this, exiting on either success or error, use a command like the following:

ocm execute update_plan my_database.world -dbackward -idfred

Enclose the plan name within double quotation marks if it contains special characters such as backslashes, asterisks, or spaces, for example:

ocm execute "Plan Name With Spaces" personnel_db -dforward -scleanup -eundo -idfred

In some cases, the execute command may return a status code other than success. For example, the output of the command may be a non- success status code if the script for a plan and database is already executing when the execute command is issued.

The execute command also fails if the script is in an inappropriate state for the execute command that you specify. For example, if you issue the execute command with the -dcleanup option for a plan, then issue the execute command with the -dbackup option for that plan, the second execute command fails. See Table A-2 for more information on exit status codes that can be returned by the command line interface.

Status Codes Returned by the Command Line Interface

After you execute each command line interface command, the command line interface returns an exit status code for the command that you entered.

Table A-2 shows the meaning of each exit status value that can be returned.

Table A-2 Exit Status Codes Returned by the Command Line Interface  
Exit Status  Description 

Operation completed successfully. 

Syntax error in command line. 

The Oracle Management Server specified in the login command does not exist or the Oracle Management Server is not running. 

There was an error when trying to login to the Oracle Management Server. Make sure that you specify correct credentials for the Oracle Management Server in the login command. 

General, catchall error. 

The baseline specified does not exist. 

The comparison specified does not exist. 

The change plan specified does not exist. 

The script for that plan and database is already executing. 

An error occurred during execution of the script. 

10 

Generation completed. Impact log contains warnings. 

11 

Generation completed. Impact log contains errors. 

12 

Generation failed. No script generated. 

13 

A problem occurred with the target database. For example, it does not exist. 

14 

Preferred credentials are not defined for the target database. Use the Oracle Enterprise Manager console to set preferred credentials for the database, then retry the operation. 

15 

You must use the login command to specify credentials for the Oracle Management Server before you can issue other command line interface commands. 

To obtain more information about an error or warning status code returned after a generate or execute command, use the Change Management Pack graphical user interface to view the impact log or execution log.


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

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

Master Index

Feedback