We all know that LMi is fantastic at being able to be configured to manage just about every situation you would require for your applications, right? 

At this point, you say, "Wait, Joe, what do you mean, just about??".  I'm so glad you asked! :)

For those super-unique situations where you want to program LMi to do something special for you, we've created muliple "exit points" in our standard workflow. You can set up LMi to call your program automatically at any of these exit points to greatly increase the level of automation and decrease the manual effort required to fully accomplish your desired change. 

There are five exit points: ADD (adding a brand new object), DLT (deleting an object), CHK (checking out an object), PRM (promoting an object) and when you install an object on your target via Deployment. The first four are accessed via STRLMI, 11: Setup, then 13: User Exits. There is a lot of F1 help text here, and it is also covered in "User Exits" section in the LM(i) Setup and Administration Reference. 

Deployment exits are not covered quite as well (or used quite as often), so the rest of my post will dive deeper there! 

First, to access this exit point, you need to go into your deployment profile. STRLMI, 6:Deployment, 14:Deployment Profiles, 2:Change, 1:Definition. Then page down to the last page where it asks for input to the installation process: 

Here you will see that you have two options, "function at begin" and "function at end". Begin of what? End of what? Before or after the actual installation of the deployed objects into the specified libraries on the specified target! In both cases, Deployment will process the Extract, Send and Receive steps first. If you say "before", it will call your function (a command or a program) before the installation step. This means that your objects are still in the ACMS_nnnn library on the target. If you say after, then deployment first runs the installation step as per normal, getting the objects out of ACMS_nnnn and into the specified target library. After that, it calls your function. 

Ok, now let's talk about your exit program. Like the other four exit points, there is some great sample code in ACMSUSER. It helps to do a filter and just look for object attribute PF-SRC. A really good example is in source file JDESRC, members DVR and DD2. What you'll see in these programs is that the information you need to retrieve is in the deployment job's local data area (*LDA) and read the deployment manifest file. First you extract the set number from the LDA and then you start reading through file RMTSETOBJ3 in ACMSRCTL. This file that has tons of information on each object that was deployed in the set. Once you've found a record that matches the set in the LDA, you can start on your logic. 

One final important part of your logic needs to be how to communicate back to Deployment Manager. If your exit program encountered a problem and you want to stop the entire deployment, the only way to do this is to perform a SNDPGMMSG with MSGTYPE of *ESCAPE.  For example: 
        CHGVAR VAR(&ERRMSG) VALUE('Set' *BCAT &DSTSET *BCAT + 'has a problem. Set processing has stopped.')
        SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA(&ERRMSG)  TOMSGQ(*TOPGMQ) MSGTYPE(*ESCAPE)

How does this affect your deployment set? Whether your exit is before installation or after installation, the set ends up in a status of "STR" (the set has been sent) and "T" (waiting for action on the target). If you look into the deployment log for the set, you'll see that the last entry is "CMP INF" (the installation set had a failure). 

Where does this leave the objects that you've deployed? In both cases, the net result of the failed set is no changes to your target libraries! In the case of the processing before installation, the installation never gets called and the objects remain in the ACMS_nnnn library. In the case of the processing after the installation, the installation put the objects into the target library, but when the exit program fails, Deployment automatically backs them out! Cool! 

One final tip: remember that your exit program has to exist on the target machine. You can put it in any library you wish, as long as you don't put it in ACMSRLIB since this library gets overlayed during an upgrade.