Command Line Utilities
CpaBuild – Create Code Packages from the Command Line
The CpaBuild command line utility is extremely useful for automating build and deployment processes and is available in the Combine installation directory. Detailed description of this command line utility is available in the file cpabuild.txt in the same directory. Using this command line utility, after getting the latest scripts version from source control (or any other sources) you can build a code package in run-time, assign each package script and folder with their properties (e.g., map a Container to each script, configure script results options, and so on) and then continue to execute the code package using the CpaExec command line utility.
To get help for CpaBuild in the command prompt, type cpabuild and hit enter. Several options are supported in this command line utility and each option has additional help content. For example, to read the help about the method /AddScript, type cpabuild /AddScript and hit enter in the command line.
Note: It is strongly recommended to use the /v option with all calls to this utility to enable the verbose logging in the command prompt.
The following methods are supported in theCpaBuild utility:
/Create – creates a code package. The /t flag indicates whether the package is wrapped (i.e., a single-file package) or unwrapped (multi-file package). Use the /w flag to overwrite an existing code package, and the /s flag (optional) to set each of the package properties and values. If /s is not used and properties are not set, then Combine uses the default property values which are listed in the command line utility.
/AddScript (for wrapped packages) – the /AddScript method is used to load code into a wrapped package. When this method is called, Combine will create a new script instance in the code package. The flag /l tell Combine where to grab the script to insert it into the package. Also, the /n command can be used to name the script entry in the package (if /n is not specified then the script name will be used). If you wish to place scripts under package folders, use the /r option to specify the relative path of the folder in the package. If you are not sure how to use the relative path, open Combine, select a folder, press F4 to bring up the properties window and search for the value of the relative path property.
/AddScript (for unwrapped packages) – when scripts are added to an unwrapped (i.e., multi-file) package, a new file is created on the file system with the content of the loaded file. The flags used here are the same as in the case for wrapped packages – /l tells Combine where to take the content of the script, /n allows you to specify a name for the script entry in the package, and /r lets you indicate the parent folder name in the package where the script will reside.
Note: A new file will be created on the file system every time you use /AddScript with unwrapped packages. If you wish to use existing files and embed them in the project package then you should use the /LinkScript option which maps between the package script to the file on the local file system. This /LinkScript feature can only be used if the script or scripts reside on or under the package folder in the file system.
/AddFolder (for wrapped packages) – the /AddFolder method creates a new folder or subfolder in the code package. The /n flag is used to denote the name of the folder and the /r flag can be used to create subfolders under existing package folders.
/AddFolder (for unwrapped packages) – the /AddFolder creates a new folder or subfolder in the package and also creates the folder on the local file system. The options /n and /r allow you to specify the folder name and relative location in the package and on the file system.
/LinkScript (only applies to unwrapped packages) – the /LinkScript method allows you to reference an existing file on the file system and make the existing file part of the package (in contrast to using /AddScript in which case a new file is created on the file system). This option is extremely useful to reference scripts that were loaded from source control (for example) and placed on the local file system and are getting ready for deployment – you can create a new code package at the parent folder for all scripts and the link all folders and scripts to be included in the code package.
/LinkFolder (only applies to unwrapped packages) – the /LinkFolder, much like /LinkScript, allows you to reference existing folders and scripts under those folders in a code package. If you link a folder to a code package then a folder will be created (if not already there) in the package and will point to the local folder. The /c flag will abort the loading of the folder (and its subfolder and scripts) to the package if scripts with the same name already exist. The flag /r is useful to load subfolders and all their scripts under a given folder into the code package. If /r is not specified then only scripts that reside directly under the folder indicated in the /l flag will be references and included in the package.
Note: As mentioned earlier, in order to reference existing files and folders in a code package using the /LinkScript and /LinkFolder methods, the folders and scripts must reside under the folder where the package is stored.
/DeleteScript and /DeleteFolder (in wrapped packages) – these methods are used to remove scripts and folders (and all scripts under the removed folders) from the code package. The /f flag does not apply and is ignored for wrapped packages. The flag /i denotes the relative path of the removed script of folder. If you are not sure where to find this value, open the code package in Combine, select the script (or folder), press F4 to bring up the properties window and look for the Relative Path property.
/DeleteScript and /DeleteFolder (in unwrapped packages) – these methods are useful to remove scripts and folders from a code package. In unwrapped package, the folders and scripts in the package are actual folders and scripts on the file system. The /i flag denotes the location of each script (or folder) in the package. If you also include the /f flag, then the scripts and folders removed from the package will also be deleted from the local file system.
/UpdatePackage, /UpdateFolder, /UpdateScript – these methods allow you to update the properties values for each item in the code package.
Recommendations and best-practices:
1. Use wrapped packages when possible – they are more intuitive and easier to understand. Wrapped packages are used by many but require some basic understanding of Combine and are recommended for advanced users.
2. If the scripts you wish to deploy are already available on the file system (e.g., after performing Get Latest from your source control client interface), create a code package at (or above) the root folder of all scripts and then use /LinkFolder to recursively include all scripts and folders in the code package. Make sure to set the Container property for the folders and (or) scripts. Then, after loading all the scripts and folders to the package you can easily and immediately deploy it against all the appropriate target databases and servers.
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.
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\Package1.cpa”
/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).
/rd - using this option you can tell Combine to resume the deployment with the given ID. It requires the /rp option to be set. For example, /rd:"6dce2d58-b6c0-4403-988c-3928aaabc7de" /rp:"c:\MyPackage\Package1.cpa"
/rp - the file path and package name to resume the deployment specified by the /rd parameter.
/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\Package1.cpa” /o:”c:\Documents and Settings\Package1.cre” /w /e:”MyEnvironments\Development” /t:Off /r:StopAll /a /ie /if /v /oa:DateTime /w