Command Line Utilities

Cpaexec - Execute Project Packages from the Command Line

Combine allows you to deploy code packages from the command line using the cpaexec.exe command line utility. All features and options that are available in the Combine user-interface are also included in this utility. The cpaexec.exe utility is available in the Combine installation directory. To bring up the menu in the image below, change the directory to the Combine installation directory in the command prompt, type "cpaexec" and hit Enter.

Figure 102a:  Figure 102a: The cpaexec command line utility options.

The cpaexec accepts three mandatory flags. All other flags are optional and allow you to control the package execution. The following parameters are mandatory:

/p - package file path and name. For example, /p:"c:\MyPackage\"

/o - file path and name for the package execution results (cre) output file, e.g., /o:"c:\MyOutput.cre".

/e - the name of the environment against which the package will be executed.

Tip: The environment can be taken from a Combine Repository or from MyEnvironments in the Container Manager. To make sure that you enter the environment name correctly, simply copy and paste the environment name as follows: Select the environment in the Container Manager in Combine, press F4 to bring up the Properties Window, select and copy the "Relative Path" property for the environment and use it in the cpaexec.

The rest of the flags in the cpaexec are options and are explained below:

/a - tells Combine to bring back the actual execution plan from all databases and servers and include then in the package results (cre) output file. To enable this option, include the /a flag; otherwise do not include it.

/ch - if CpaExec is running on a machine where Combine is configured to write deployment results to a Change History Repository, then users should specify the /ch flag if they wish to store the package execution results in the repository database. When the /ch flag is not indicated, then Combine will not write the execution outcome to the Change History Repository.

/ev - used to specify the name and value for Environment Variables used in the code package. This flag is used for Environment Variables that appear both in code or are referenced in the Query for Dynamic Containers. This flag can be used multiple times to specify values for multiple Environment Variables. For example, to enter two Environment Variable names and values, use: /ev:"MyVarName=MyValue" /ev:"MyVar1=MyVal1"

/ie - before Combine executes code packages it validates that you do not have any empty scripts (i.e., ones that have no code) in the code package. If there are empty scripts and /ie is not specified, then Combine will abort the package execution. Include this flag to skip the empty files check.

/if - Combine will make sure that all package files are found on the file system before deploying a code package. If any files are missing and this flag is not included, then Combine will abort the deployment. Use this flag to skip the check for missing files.

/is - Combine checks and replaces system variables before script execution. If there are any invalid system variables and this option is not specified then Combine will abort the deployment. Use this flag to ignore invalid system variables.

/oa - using this option you can tell Combine to append a string to the package results (cre) output file name. For example, if /oa:DateTime is specified, Combine will append the string "_YYYYMMDD_HHNNSS" to the output file name. Date will result in appending YYYYMMDD, and Time is for HHNNSS.

/r - this flag tells Combine how to proceed with execution in case any errors occur on one or more databases. The possible values are: ContinueNonErroredOnly - if Combine detects that the execution of a script resulted in errors on same databases after the script was run, Combine will continue to run the rest of the package scripts on all databases except those that encountered errors. StopAll - tells Combine to abort execution after the first error is reported. Combine will finish running the errored script on all its associated databases and then abort the deployment and will not continue to any other scripts. ContinueAll - instructs Combine to continue and deploy the rest of the package after an error occurs, on all target databases (including the errored databases).

/t and /d - before a package is executed Combine tests that all databases are up and running, to ensure proper connectivity. If any databases cannot be connected when this option is set to On (which is the default) then Combine will use the instruction in the /d flag to figure out how to continue: If /d is set to Alive then Combine will only deploy package scripts to databases that passed the connectivity test. However when /d is set to CancelIfAnyFailed then Combine will not start the deployment and will abort. If you want Combine to deploy the code package on all databases regardless of the connectivity test results, set /t to Off so that Combine will skip the connectivity test altogether.

/v - enable verbose and detailed logging in the command line window.

/w - overwrite the package results (cre) output file if a file with the same name and path already exists.

Example for using the cpaexec:
cpaexec /v /p:"c:\Documents and Settings\" /o:"c:\Documents and Settings\Package1.cre" /w /e:"MyEnvironments\Development" /t:Off /r:StopAll /a /ie /if /v /oa:DateTime /w

© 2001-2018 JNetDirect, Inc. All Rights Reserved.