Combine supportBack to main support page
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.
Figure 102a: The cpaexec command line utility options.
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.