Implementation – Basic Copy
A basic deployment of a package will usually stage the package files to a warehouse on the target system, them implement them by copying them from the warehouse to the target location. Code Pipeline provides options to support more complex deployment operations.
Pre and Post Exits for Basic Copy
It is possible to start a process before and/or after the basic package implementation copy. It is also possible to start a process before and/or after each file copy. These processes could check space availability in the target location, stop applications or services, or any other function. If the exit process returns an error, the deploy request is failed. See the Start Process Options table for details on the type of exit processes that can be used.
Implementation – Advanced Process
If the deploy requires more control over the implementation (than just a copy), an implementation process can be specified. In this case, the implementation process will get started by the Remote Server at the beginning of the implementation phase. It can retrieve package details, run the file copies, and perform any additional operations. When using this option, no pre/post exits will be run. This option should only be used when one of the other options will not achieve the required results, as it puts the complete deploy package responsibility in the started implementation process. See the Start Process Options table for details on the type of implementation processes that can be used.
Activation Process
Following an implementation, a process may be started to perform additional operations, such as restarting an updated application. The activation process will be started by the Remote Server on the target system. The process may be a program, a batch file or shell script, or a PHP script. See the Start Process Options table for details on the type of activation processes that can be used.
Start Process Options
The Remote Server will start processes during the deploy package phases, based on the definitions for the deploy environment and sub-environment. Processes can be started at the points as listed in the following table, based upon the definitions in M.DV(N).
Start Process Options
Description | Implement | Activate | Pkg-Pre | Pkg-Post | Item-Pre | Item-Post |
|---|---|---|---|---|---|---|
Implementation is X or blank | N | N | N | N | N | N |
Implementation is C, Activation is X or blank | N | N | Y | Y | Y | Y |
Implementation is C, Activation is S | N | Y | Y | Y | Y | Y |
Implementation is S, Activation is X or blank | Y | N | N | N | N | N |
Implementation is S, Activation is S | Y | Y | N | N | N | N |
Important
Pre and Post exists are only run if they are defined in the WRSDPEX extension class for the Deploy Environment or Sub-Environment. If the exits are defined and can be run based on the Start Process Options chart, then the Remote Server will start them.
WRSDPEX
If pre or post exits are to be executed, then the WRSDPEX Extension Class must be defined in M.EC and then used against the Deploy Environment defined in M.DV. The definition is shown in the following figure.
WRSDPEX Extension Class
Name Type Length Description
ITEMPOST CHAR 8 Item Post-Implementation Copy Exit
ITEMPRE CHAR 8 Item Pre-Implementation Copy Exit
PKGPOST CHAR 8 Package Post-Implementation Copy Exit
PKGPRE CHAR 8 Package Pre-Implementation Copy Exit Processes
Processes started by the Remote Server may be programs, batch commands or shell scripts, or PHP scripts. The deploy package and environment details will be passed as command line arguments to the started process. If the process is a pre/post exit, then only a return code is expected to be returned. If the process is for package activation, then the status of the activation should be set by the process.
Process Name
The name of the deploy process to be run is an 8 character name defined in the deploy environment in M.DV. This name is used to locate the command file in the directory specified by the “COMMAND_PATH” value in the Remote Server start up parameters.
On a Windows system, the process name is appended with a “.exe”, then a “.bat”, then a “.php” to locate a file that matches. If a file matches the name, using a case insensitive check, then that file is used to start the deploy process. If no match is found, then the deploy process is failed.
On a Linux or Unix system, a matching file is checked for, then the process name is appended with a “.sh”, then a “.php” to locate a file that matches. Each check is performed once in upper case, and once in lower case. If a file matches the name, then that file is used to start the deploy process. If no match is found, then the deploy process is failed.
Programmatic Considerations
When deciding whether to use a program, batch/shell script, or PHP script, you will need to consider what the process will be doing. By far the best choice for these started processes is a PHP script. Code Pipeline provides a set of PHP functions that can be used in your scripts to communicate directly with the Code Pipeline server and perform other useful operations. There are also a set of logging functions that will ensure that messages generated by the script will be placed in the deploy log and can be viewed from the Code Pipeline Client. PHP is freely available on all platforms supported by Code Pipeline . BMC Support can provide PHP install instructions and the Code Pipeline PHP Scripting package.
In some cases, specialized utility programs will be provided for use as the implementation or activation process.
If you do not have PHP available and do not want to install it, you may use batch commands or shell scripts to perform activation processing. These bat/shell scripts do not have a direct communication interface to the Code Pipeline server, but a command line utility is provided to let the script place entries into the deploy process log that will be picked up by the Remote Server so it can report package status back to the Code Pipeline server. You may also use bat/shell scripts for pre/post exits, as all that is expected from these exits is a return code. Using a bat/shell script for the implementation process is likely not possible, due to the requirement for direct communications with the Code Pipeline server.
PHP Considerations
The best option for deploy processes is to use the Code Pipeline PHP Scripting package. The package contains the PHP function libraries, the Code Pipeline interface utility, and documentation on usage in HTML format. For the latest version of the Code Pipeline PHP Scripting package, contact BMC Customer Solutions.
PHP scripts may be used for the activation processing, implementation processing, and implementation pre/post exits.
PHP Example
The code shown in the following figure is an example of an implementation process using PHP.
Sample Implementation Process Using PHP
<?php
/* * Sample Implementation Script */
require("wzapi.php");
global $wzenv;
/* Initialize Code Pipeline Environment */
WZAPI($argv,NULL,NULL);
WZLogInit("append,info");
WZLogMsg("MSG", "Deploy Implementation Started");
/* Initialize connection to Code Pipeline */
$srid = WZGetArgvValue($argv,"srid");
$rc = WZInit($srid);
if ($rc == -1) { WZLogMsg("ERROR", "Code Pipeline INIT Failed: ".WZLastError() ) ; return(8);
}
/* Get Command Line Arguments */
$dreqid = WZGetArgvValue($argv,"dreqid");
$pkgid = WZGetArgvValue($argv,"pkgid");
$systname = WZGetArgvValue($argv,"systname");
$pkgarray = WZPackageStart($dreqid,$pkgid,$systname);
if (!$pkgarray) { WZLogMsg("ERROR", "Package Start Failed: ".WZLastError() ) ; return(8);
}
/* Process the Deploy Package */
$pk = $pkgarray['PK'];
WZLogArray("INFO","PK Data Group",$pk);
/* Process each Item in the Package */
$FailCount=0;
foreach ($pkgarray['ITEMS'] as $id=>$item) { WZLogArray("INFO","ITEM Data Group",$item); if ($item['status'] != "C") { /* Use Random Number to determine whether we will process this item */ $random = rand(1, 11); if ($random > 5) { /* If random number is greater than 5 then fail the Item */ $rc = WZItemFail($item,"Package ". $item['pkgid'] . " Item ". $item['itemid'] . " Failed - Random Number=" . $random); $FailCount=$FailCount+1; } else { $item['targtype'] = $item['stortype']; $item['targname'] = trim($item['storname']) . $wzenv['sc'] . trim($item['cmpntype']) . $wzenv['sc'] . trim($item['cmpnname']) . ".txt" ; $itemr = WZItemGet($item); if ($itemr) { $rc = WZItemComplete($item); $msgbuf = "Deploy Copy to " . $item['targname'] ." Complete"; WZLogMsg("MSG", $msgbuf); } else { /* ItemGet Failed */ $rc = WZItemFail($item,"Package ". $item['pkgid'] . " Item ". $item['itemid'] . " Failed - WZItemGet RC=" . WZLastRC()); $FailCount=$FailCount+1; } } } }
/* Fail the package if any items failed , otherwise Complete the Package */
if ($FailCount > 0) $rc = WZPackageFail($pk,"Package " .$pkgid . " failed because " . $FailCount . " item(s) failed");
else $rc = WZPackageComplete($pk);
WZLogMsg("MSG", "Deploy Implementation Ended");
WZTerm();
exit(0);
?>Windows Batch Commands
You may use Windows batch commands to perform deploy package activation processing and pre/post exits. You may not use batch commands for deploy implementation processing.
Batch commands have no direct access to the Code Pipeline server, and will need to report the status of the activation by adding entries to the deploy package log file. The WZUDPAP command line utility is used to create the log, add entries to it, and report activation status. Refer to WZUDPAP – Writing to the Log for details.
When using batch commands for activation processing, you will need to make use of the Deploy Monitor feature of the Remote Server. Refer to Deploy Activation Monitor for details.
Windows Batch Command Example
The following figure shows a sample Windows batch command for Package activation.
Windows Batch Command
REM Sample Deploy Activation Command
REM Syntax: “sample.bat DREQID=nnn PKGID=nn SYSTNAME=xxx LOGPATH=lll SRID=sss”
REM Signal that activation has started
wzudpap.exe START %1=%2 %3=%4 %5=%6 %7=%8 %9=%10
REM Do activation stuff here. Set "RC" to return code
wzudpap.exe MSG %1=%2 %3=%4 %5=%6 %7=%8 TEXT="This message added to deploy log"
IF %RC% GTR 0 GOTO :Failed
:Complete
REM Signal that activation has completed
wzudpap.exe END %1=%2 %3=%4 %5=%6 %7=%8
EXIT 0
:Failed
REM Signal that activation has failed
wzudpap.exe FAIL %1=%2 %3=%4 %5=%6 %7=%8 TEXT="Activation error reason"
EXIT %RC%Linux/Unix Shell Scripts
You may use Linux/Unix shell scripts to perform deploy package activation processing and for Pre/Post exit processing. You may not use shell scripts for deploy implementation processing.
Shell scripts have no direct access to the Code Pipeline server, and will need to report the status of the activation by adding entries to the deploy package log file.
Use the wzudpap command line utility to create the log, add entries to it, and report activation status. Refer to WZUDPAP – Writing to the Log for details.
When using shell scripts for activation processing, you will need to make use of the Deploy Monitor feature of the Remote Server. Refer to Deploy Activation Monitor for details.
Shell Script Example
The following figure shows a sample Linux/Unix shell script for package activation.
Linux/Unix shell script
#!/bin/sh
# Sample Deploy Activation Script
# Syntax: “sample.sh DREQID=nnn PKGID=nn SYSTNAME=xxx LOGPATH=lll SRID=sss”
# Signal that activation has started
./wzudpap START $1 $2 $3 $4 $5
# Do activation stuff here. Set "RC" to return code
RC=0
./wzudpap MSG $1 $2 $3 $4 TEXT="This message added to deploy log"
if [ $RC -eq 0 ]
then # Signal that activation has completed ./wzudpap END $1 $2 $3 $4 exit 0
else # Signal that activation has failed ./wzudpap FAIL $1 $2 $3 $4 TEXT="Activation error reason" exit $RC
fi
