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"
• "Understanding the Notation Used for the Command Syntax"
• "Requirements for Using the Command Line Interface"
• "Scheduling the Execution of Command Line Interface Scripts"
• "Using the Command Line Interface Commands"
• "Status Codes Returned by the Command Line Interface"

  Note: Before using the command line interface, you should be familiar with the Oracle Change Management Pack concepts and applications described in the previous chapters of this manual.

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:

• Capturing the definitions of a set of database objects each night, using the same baseline specification
• Comparing the definitions of a set of database objects to those of a different schema or database, or a baseline, each night
• Generating scripts during off hours by applying a single plan to each of a set of destination databases, and then executing the script at each destination if the generation completes without error

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

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

Understanding Case-Sensitivity Requirements for the Command Line Interface

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

• Commands, options, and keywords must be specified in lowercase.
• The case of a change plan, baseline, or comparison name specified with the command line interface must exactly match the case of that object's name as it appears in the Change Manager application.
• Database names are not case-sensitive.
• The string that you specify for the -id option's identity argument is case-sensitive.

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:

• If you choose to run the command line interface logged into the Oracle Management Server, you must specify your Oracle Enterprise Manager administrator's name, your administrator password, and the name of the node on which the Oracle Management Server is running.
• If you choose to run the command line interface standalone (without logging into the Oracle Management Server), you must specify the Username, Password, and Service (database) credentials of the user that owns the schema used for your standalone repository.

  Important: Be aware of the following considerations when you use the login command: Before you run a script that contains command line interface commands, you must first issue the login command outside of the script to establish the administrator credentials that are referenced inside the script. For example, if a script includes commands that use the -idfred argument, the ocm login -idfred command must be issued prior to the script being invoked so that credentials for the administrator identified by -idfred can be established before the script is run. To execute the login command on a remote machine, your local machine's display must be appropriately set to allow the login dialog box to display on your local machine. Then you can use the login dialog box to establish the administrator credentials to be used for the command line interface session.

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

• Your decision to run the command line interface connected to the Oracle Management Server or standalone.
• The credentials you specified for the option you selected. When you execute other command line interface commands, specify the same identity string.

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

• The administrator credentials that are specified for that identity.
• Where (in what repository) to store the Change Management Pack objects created during the command line session for that administrator.

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

• The operating system session is terminated.
• The ocm logout command is used to de-establish the administrator credentials for a specific administrator.

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:

• forward

  The forward option executes the script.

• backward

  The backward option executes the recovery script that undoes the changes made by the script. Use this option if the script failed or you do not like the changes made by the script. Using this option is equivalent to selecting the Undo option in Plan Editor or one of the other change applications after executing a script.

• cleanup

  The cleanup option keeps the changes made by the script and removes the temporary data that the recovery script uses to undo changes made by the script. Use this option only after the script has successfully executed in the forward direction. Using this option is equivalent to selecting the Keep option in Plan Editor or one of the other change applications after executing a script. After using this option, you cannot use the backward option.

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:

• cleanup

  When the cleanup option is specified with the -s option and the script executes successfully, the changes made by the script are kept and the temporary data that the recovery script uses to undo changes made by the script is removed.

  The cleanup option only makes sense when the script is executed in the forward direction.

• exit

  When the exit option is specified with the -s option and the script executes successfully, the changes made by the script execution are not kept or undone, which means your script execution results in a pending task. To complete this pending task, you need to specify later whether you want to keep or undo the changes. You can use one of the change applications or issue another execute command to specify whether to keep or undo the changes. See "Viewing and Completing Pending Tasks" for more information on pending tasks and how to complete them.

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:

• undo

  When the undo option is specified with the -e option and errors occur when the script executes, the recovery script executes, undoing the changes made by the script. Using this option is equivalent to selecting the Undo option in Plan Editor or one of the other change applications after executing a script.

  The undo option only makes sense when the script is executed in the forward direction.

• exit

  When the exit option is specified with the -e option and errors occur when the script executes, the changes made by the script execution are not kept or undone, which means your script execution results in a pending task. To complete this pending task, you need to specify later whether you want to keep or undo the changes.

  When an error occurs during script execution, you can use several different approaches for determining the cause of the error, including:

  • Use Table A-2 to look up the meaning of the exit status code returned for the execute command.
  • If you used the -l option with the execute command, look at the logging output that was generated by the execute command.
  • Use Plan Editor or one of the change applications to view the execution log for the script. See "Executing the Script with Plan Editor" for more information on viewing an execution log.

  After determining the cause of the execution error, you can either keep or undo the changes to complete the pending task, or you can make changes to the script or destination database that will allow you to execute the script successfully. See "Dealing with Script Execution Errors" for more information on dealing with script execution errors.

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
0	Operation completed successfully.
1	Syntax error in command line.
2	The Oracle Management Server specified in the login command does not exist or the Oracle Management Server is not running.
3	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.
4	General, catchall error.
5	The baseline specified does not exist.
6	The comparison specified does not exist.
7	The change plan specified does not exist.
8	The script for that plan and database is already executing.
9	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.