Boneman's Blog

Software Product Lines

2008-02-14T12:11:00.001-05:00

This is the first of a series of articles on an approach to systems architecture called “Software Product Lines.” To introduce the concept, let’s ignore the word “software” for now and focus on what a product line is in a more general and tangible fashion.

If you are in the market for a laptop and go to Dell’s website, you have a choice of several different base models that can be configured to your specification. Once you select the base model, you can configure things such as the size of RAM, size of the hard drive, type of display, etc. What makes this possible is a hardware architecture of various components that can fit into the same slot – compatible electrically as well as physically. This allows Dell to create and mass produce (or purchase) several standardized components and simply plug them together to create a customized product at a reasonable cost in a short timeframe. When new technologies come out that require changes to the base product, like ATA laptop hard drives, Dell spins up a new product line with that one modification reusing the old technology and components that is still valid, tried, and true. This sounds like a great idea and solid common sense, doesn’t it?

As with anything, there are challenges to this approach. Take for instance a design flaw in one of the more heavily shared components, such as the motherboard, where the power connector solder joints go bad due to heat and constant plugging/unplugging. This one design flaw could end up costing dearly in repair and possibly recall expenses, as a significantly higher number of devices are impacted then if the system was not as modular. It is also significantly more difficult and time consuming up-front to design, build, and test a system that shares components. In a product line, tight adherence to specifications needs to be considered for future compatibility. Take for example the wireless network/Bluetooth riser cards found in many laptops. Let’s assume the bus timings are just a hair off spec, but the current crop of hardware is tolerant of it. Newer technologies coming out six months later may not be tolerant. A non-product line approach would be to make a revision of the entire system – which is required anyway; however, the product line approach requires significant expense to revise and test one or both of the components to assure compatibility.

Software is not very different than hardware when it comes to product lines. Most high-end software packages are heavily customizable so it can integrate into a variety of environments. Microsoft’s SharePoint product is one example, SAP is another. These two products are off-the-shelf packages intended to appeal to a very large market. There was heavy up-front investment by the vendor in design, documentation, interfaces, components, external training and certification programs, and more. But what if your product is very specialized with a small market? Even worse, what if your product is designed for small to medium sized businesses that typically can’t afford or will not have the resources to self-customize such a vast system? To top it all off, certainly, you cannot afford to invest in the amount of up-front work required to build, test, and debug a heavily customizable system given the small size of your target market.

Enter the concept of Software Product Lines. It is important to note that this is an engineering approach to solve a specific business problem. Using the Software Product Line methodology in a business environment that is not controlled or the problem domain of the customer is not well understood will cause you to paint yourself into a corner with no easy or cheap way out. Another salient comment is choosing this approach should not significantly change your development methodology (assuming, of course, that you have adopted a legitimate methodology in the first place). Finally, this approach is NOT a method of implementation, merely a way of thinking from a design perspective of what needs componentized. The decision to use a Service Oriented Architecture to implement a Software Product Line is off-topic – these are two different animals entirely.

Part II of this series will delve into some of these concepts deeper.

Go Steelers Redux

2006-01-22T22:39:00.001-05:00

Not only has it been a long time since my last post, but it has been exactly a year since my last post on my hometown NFL football team, the Pittsburgh Steelers. Sadly, last year we lost the AFC championship. This year we won it against the Denver Bronco's. This means we are off to the Super Bowl against the Seattle Seahawks. Superbowl XL is on February 5th, 2006. In preparation, my blog banner has been updated to "All Steelers, all the time" from the revolving banner of the past.

One of the great things about living in (or coming from) the Pittsburgh area is the friendliness of the people in and around the city. Last year, I blogged a bit about Myron Cope and the "Terrible Towel." One thing I neglected to mention is that all proceeds on the sale of the towel go to the Allegheny Valley School that provides care for children, adults, and seniors with mental retardation and physical disabilities. If you would like to support the Steelers, and the school, please use the above link (instead of the Google AdSense ones) so that the school gets additional credit.

I believe the Steelers have been playing for the 'Bus' - a.k.a. running back Jerome Bettis. The Bus has been a Pittsburgh fixture for years, not only as a dependable player, but as an excellent example of what a celebrity should be like. To illustrate my point, Hines Ward (a teammate and Steelers Wide Receiver) was in tears last year after the AFC Championship loss because he believed the team let Jerome down in his potentially last season. This year is different. Jerome will have the opportunity to play, and in his home city, Detroit. Jerome is active in the community, and is currently raising awareness about Asthma, a disease he is afflicted with, in addition to a program called "The Bus Stops Here," benefiting children from both Pittsburgh and Detroit. Jerome's parents, Gladys and John, have every reason to proud of their son, and the values they instilled in him.

Other team members have had tremendous impact on the Pittsburgh region. I don't want to leave out any players, but Charlie Batch, a backup quarterback, is also famous for not only coming from the Pittsburgh area, but for his contributions to it. There are several other examples of how the team and its players gives back to the community.

I believe much of the reason for the positive impact of the players of the Steelers goes back to the team's ownership and philosophy. The most famous owner is Art Rooney, a.k.a. "The Chief", who bought the franchise in 1933. If any Pittsburgher's have not yet seen the play "The Chief" at the Pittsburgh Public Theatre, you don't know what you missed! This play ran in 2003, 2004, and earlier this month - keep checking for it to return (possibly) next fall at the PPT website. Franco Harris (star player in the 70's) was talking about Art Rooney when he said, "He was always there to help and to give. And this feeling filtered down to the players. I think the Steelers' players give more to their community than any other team in professional sport."

I'm hoping that the Super Bowl in a few weeks does not bring on any additional heart attacks among the fans, but that you watch it with the understanding that many of the athletes on both sides of the ball are using their celebrity status and monies to better their communities. I think we can all learn from this.

To my readers in the Seattle/Redmond area - I didn't mean to leave out the players of your team, I merely am not familiar with their good works. I am, however, familiar with Victor's Celtic Coffee Company, and am currently out of the "Redmond Slough" blend as of this morning. I'd be willing to trade for some of that in exchange for posting Seattle Seahawks charity links and an equivalent amount of coffee from one of our local coffee houses (Coffee Tree Roasters)...

Go Steelers!

Silence is a virtue...

2006-01-22T09:00:00.001-05:00

I was looking for some way of explaining my recent blog silence. As one who likes to use the words of others to explain things that are difficult to explain in my own words, I hit the quote book and encountered this gem by Sally Berger: "You never saw a fish on the wall with its mouth shut." That doesn't really fit, but I found it kinda funny and that will have to do.

In addition to the typical excuse of the holidays, I also recently changed employers. This has the side effect of changing the type of development I do. Keeping with my philosophy that I speak only for myself and not my employer, I will not divulge the name of my current employer. I will also not divulge anything that could be considered something other than generally available developer knowledge. So in reality, the only thing that could possibly change is the type of content.

Most likely I will be delving into topics such as .NET Development, the Compact Framework, and native Windows Mobile (Windows CE) development/debugging. Some of these postings may be about deployment concerns in the Windows Mobile environment. Content suggestions related to this area of development are welcome. I also plan on finishing up a few posts on MSI related subjects I started a while back after some editing and reviewing.

If you have questions regarding MSI of other installer technologies, please keep them coming - many of the privately asked (and answered) questions I have saved as blog post drafts to be completed later, and I will continue to attempt to answer them time permitting.

In the meantime, constant reader, please bear with me while I adapt to my new environment and gather together some new (and old) content.

Writing Clear Code

2005-12-04T17:11:00.003-05:00

This topic is a bit of a divergence from Custom Actions, but useful for some general coding skills. I'm going to highlight the C# language in this post, although you don't need to know C# to benefit from this discussion - I'll cover the essentials in the post. The topic is how to write clear code that makes it easier to defer the understand the intention of the code rather than the behavior of the code. The subject came up about a few months ago in a discussion with a coworker who initially didn't quite agree with me. I'll lay out the argument here as I did with him.

Take for instance the following code snippet:

string a = "hello";
string b = "hello";
System.Console.WriteLine(a == b);
System.Console.WriteLine((object)a == (object)b);

Lets explore the last two lines. The a == b equivalence operator is working on strings, and by C# rule, two strings are equivalent if they are both null, or if both values are non-null references to string instances that have identical lengths and identical characters in each character position. Translation - two nulls are identical, and any two strings that match, case sensitive, will result in a true expression. In the latter comparison, when we cast both of the strings to objects, we are not comparing the values of the strings, but the objects themselves.

What do you think it will print? The answer is True and True. Why? String literals that are identical within the same assembly refer to the same instance. Translated, 'a' and 'b' are variables that refer to the same underlying object.

Now lets replace the declaration and assignment for string b with:

string b = "he"+"llo";

Now what do you think it will print? The answer is again True and True. Why? Because the Lexical analysis (lexer) in the compiler stripped out the needless additive operator in the literal. The same would have happened if we changed the string to be "hell\u006f" - since '\u006f' is the Unicode escape sequence of the lower-case letter 'o', and this expansion takes place (most likely) prior to the lexer during the transformation phase in the compilation process.

Now lets replace the same line as above with the following two lines:

string b = "he";
b += "llo";

Now what do you think it will print? The answer is now True and False. Why? The strings are equivalent, but since the preprocessing of the source file before the compilation did not identify the strings as being the same literal, they are in different objects. In fact, because a string is immutable (once created cannot be changed), there was the construction of the string "b" during declaration and initial assignment that was later garbage collected when a new instance of "b" was created during the string concatenation.

Now that the necessary background information is understood, can you tell me the intention of the following code snippet?

string a,b;
//code here that assigns and manipulates a and b
...
if (a==b)
    compareOK();
else
    compareBad();

I'm hoping you are going to tell me that you have no clue as to the intent of the programmer. The intent could have been to compare the two strings in a case sensitive manner, ignoring cultural rules (which is what actually is happening in the above snippet). It also could have been to compare object equivalence, just that the programmer forgot to cast the strings to object first. The intention could also have been a case-insensitive comparison. Another possible intent was to compare strings using cultural rules. The intent of the programmer simply is not clear!

Rewriting the comparison line in the above snippet correctly, assuming the actual behavior of the code was the intent should look like this:

if ( String.Compare(a, b, false,
System.Globalization.CultureInfo.InvariantCulture ) == 0 )

This tells me that the intent of the programmer was to compare the two strings in a case sensitive manner, ignoring cultural rules . There is no other possible intent given the above line of code. This is not saying that the code is correct - just that the intent of the code is clear to those lucky enough to read it, and that the developer thought it through.

If I am skimming through some code and see a non-String.Compare() string comparison, I will sprinkle a //BUGBUG: comment above it. Why? The simple string comparison syntax has been a rather common cause of bugs in C# code - much like the C/C++ switch statement. When investigating an issue in a piece of code, I will first look for these BUGBUG's and the TODO's as a starting point - often with better-than-random chance results.

Custom Action Tutorial Part III – What we did in Part II

2005-11-15T09:04:00.001-05:00

This is the third in a series of articles about building Custom Actions. If you are coming in late to the party, check out Part I and Part II first. If I tried to explain what we were doing and why in the last installment of this tutorial, you would be even more lost now than you probably are. This article is an attempt to explain exactly what it was we did in Part II and why. Let’s start by going over each project in our solution.

The HelloWorld project

We needed something to install. This happens to be it. I could have picked notepad.exe or something, but it is nicer to see how Visual Studio could grab project outputs and put them into an MSI fairly easily.

The CustomAction project

This one is really the meat of what we are trying to learn. The other projects are sort of extraneous if you are using a tool other than Visual Studio to build your MSI. Microsoft did a pretty good job of explaining why you may want to use Custom Actions in the first place, so I’m not going to rehash that.

We created a Custom Action DLL. The reason I chose a DLL is because it is the most flexible means of tightly integrating a Custom Action with the installation engine. Additionally, there is not much you cannot do in a Win32 C++ DLL. An executable Custom Action cannot interact with the MSI engine. A VBScript or JScript action does have this capability, but if you are not careful, these are not bulletproof, and usually won't allow you to do much anyway.

We added a "Module Definition File" (.def) file to the project. This .def file is read by the linker and is used (for our purposes, anyway) to prevent mangling of function names (to be technically correct, specify the calling convention to be used). Mangling is entirely normal when a DLL is created without using the extern "c" function declaration – in fact, it is called by the more pleasant name "Decorating" the function names. If you run "Dependency Walker" (depends.exe in the Bin folder of the Platform SDK), and open a DLL in it, the listing of function exports appears. Pick FrameDyD.Dll from the same Bin directory and look at it. You will notice some ? and @ symbols around the names of functions. The .def file allows us to not create these mangled exports – you can verify this by opening the custom action dll we built in our project and see this for yourself. Ultimately, this makes the process less prone to error when entering data in the custom action table of the MSI. When adding the Custom Action via Visual Studio, it will handle the mangling automatically, so for this specific project this was not strictly necessary. If you are adding this DLL using another installation designer, you will thank me for not mangling the function names. Anyway, the .def file must contain the function names of any function you wish to make callable from outside the DLL. In our case, we wanted all four of the functions we added to be callable by the MSI engine, which is why they were added to the DEF file. There are tons of other ways to accomplish this goal

The function signatures we added to the CustomAction.cpp file are based on the requirements of the DLL Custom Action type. We return an unsigned integer (UINT) and accept a single parameter that is the handle to the installation (MSIHANDLE). We must use this handle to interact with the MSI Engine. The UINT return type indicates our status to the MSI engine.

The file "msi.lib" is the link library for the MSI engine. All custom action DLL’s must link to this file in order to call any MSI functions. The instructions in Part I explained an alternate way to inform the linker what to link with. One way is not necessarily better or worse than the other. The functions defined in the header files msi.h and msiquery.h (that we included in the stdafx.h file) all require linking to this library.

We made additional solution configurations to give us a UNICODE project type. While this is not intended to be a primer on UNICODE, all NT kernel OS’s are UNICODE under the hood. Windows 95 through ME are not UNICODE, although they can support some UNICODE extensions with the Unicode Library. For dll's and executables that only will run under Windows NT, 2000, XP, or 2003, the only option you should use is UNICODE. Therefore, if you are targeting only NT based systems, build and use the UNICODE projects. If you are supporting Windows 9x based machines use the non Unicode versions. To make the Unicode transition easier, Microsoft provided the tchar.h header that we include in the stdafx.h file that deals with strings based on compiler settings (actually preprocessor macros), so you may write code that will compile and work as native UNICODE or ANSI based on compiler settings. The TEXT() macro used in the "Hello MSI!" exercise is an example of one such tchar.h macro. Future Custom Action examples presented here will use the tchar.h macros when the compatibility of the Custom Action spans both Windows 9x and NT based platforms. Actions targeting Windows NT based systems will only compile in UNICODE, and will not use the tchar.h macros.

The final thing we added to the CustomAction project was the header include for strsafe.h. This header file describes the safe string functions intended to replace the C/C++ standard library string functions as well as specific Windows string handling implementations. These functions always start with the word "String" followed by the type of count provided as a parameter to the function, either the "Cb" which is a count of bytes, or "Cch" which is a count of characters. Remember that Unicode implementations use 2 bytes per character as opposed to the ANSI 1 byte per character – so the Cb and Cch designations are important. The last important fact about this header is by default it will deprecate the unsafe string handling functions – if you use sprintf(), you will get a compiler warning.

The Setup1 Project

Hopefully we are pretty clear on the basics for the first part of this one – an EXE is generated, Visual Studio generates a basic MSI and adds entries in the Feature, Component, File, Shortcut, and other tables to install the HelloWorld exe and the shortcut for it.

When we added the Custom Actions, we did a few things that affected the compiled MSI. Use Orca (which you installed in Part I) to view the generated MSI and follow along - try to remember back to the Custom Action theory presented in Part I:

Added a new Component and File table entry that installs the CustomAction.dll file.

Added four entries to the CustomAction table, referencing the DLL that we installed with the product. Notice the Source column of the CustomAction table is a reference to the key of File table for our Custom Action DLL. The CustomAction table's Target column is the DLL entry point (remember this is nothing more magical than the function names in our .def file). The action name is just a randomly generated GUID. The type column starts its life as a Type 17 which indicates msidbCustomActionTypeDll + msidbCustomActionTypeSourceFile, and to this number is added the following:

Action Type	Decimal Value	Description
Uninstall	1041	= 17 + msidbCustomActionTypeInScript
Install	1041	= 17 + msidbCustomActionTypeInScript
Rollback	1297	= 17 + msidbCustomActionTypeInScript + msidbCustomActionTypeRollback
Commit	1553	= 17 + msidbCustomActionTypeInScript + msidbCustomActionTypeCommit

Looking at the InstallExecuteSequence table, note that all but the uninstall custom action is scheduled before the RegisterUser Standard action, and the uninstall custom action is scheduled before the UnpublishComponents action. Note that these actions are conditionalized on the action state of the component, denoted by the dollar-sign - you can see this clearly in the InstallExecuteSequence table. In a nutshell, this condition will cause the custom actions to run only when the component it is tied to (the Custom Action DLL) is being added or removed from the system.

Visual Studio does not give us a bunch of options when dealing with Custom Actions, so we are pretty much stuck with what they offer – which is the ability to add an additional condition (other than the component install state), stuff what goes into the CustomActionData property fairly easy, and sequence the custom actions relative to each other. You cannot change sequencing of the custom action (like making it occur relative to another standard action other than RegisterUser or UnpublishComponents, embedding the custom action in the binary table, or add immediate custom actions. Other authoring tools offer the ability to be tons more flexible, but we are stuck with these limitations for now.

That concludes Part III of the Custom Action Tutorial. In the next part, we will learn how to debug the Custom Action.

Custom Action Tutorial Part II – Creating the Project

2005-11-03T08:30:00.001-05:00

In Part I we covered the dry material - what custom actions are, and how to use them. In this part of the tutorial, we will configure the development environment and create a baseline project to start from when developing future Custom Actions. Please make sure your system is configured as described in the first part before continuing.

I am providing a download link for the final project described in this part for convenience (see the end of this post for the link), but I recommend first time custom action developers follow the steps so they understand what is going on. For my more experienced readers, please bear with the simplicity here, but review the project settings before downloading or using the template in future parts.

Create a Basic Installation Project

To create our solution, open Visual Studio 2003. We are going to create two projects to start with – one a Win32 Project called "HelloWorld", and a deployment project that will create an MSI to install it. Go to the File->New->Project menu. Select the Visual C++ Projects->Win32->Win32 Project. Call the name of the project "Hello World" and place it into a directory such as C:\Projects\CATutorial. Select Finish in the Wizard dialog. When the IDE initializes, you should see the Solution Explorer window – Right-click on the Solution 'HelloWorld' line at the top of this box and select Add->New Project. Find the Setup and Deployment Projects category and select Setup Project, and select the Setup Project Wizard – you can accept the default name of Setup1. Hit next, and accept the defaults for page 2. On page 3, check the Primary Output from HelloWorld option and hit Finish. When the project opens, select the Users Programs Menu and right-click in the pane to the right. Select Create New Shortcut. Double-click Application Folder and double-click the Primary Output from HelloWorld (Active). Rename the shortcut if you wish.

Now we have both an EXE and an MSI project that installs the EXE plus a shortcut to it. At this point, we can build and test our MSI by right-clicking the Setup1 project and selecting Build. Next, right-click the project and select Install. You will be walked through the standard MSI project dialog sequence – just accept the defaults and finish the install. A shortcut is installed to Program Files in the Start Menu, which will open a window that pretty much does nothing. If you get this far, you are on the right track.

Add a DLL Project

To make a Custom Action DLL, we want to now add a new project – a Win32 Project that is a DLL. Follow the add project instructions for "HelloWorld" above, but call it "CustomAction" and in the Wizard, select the Application Settings and pick DLL for the Application Type. Press Finish. We now need to add some items to this project – please follow this closely.

Right-click on the CustomAction project and select Add->New Item. Find the Module-Definition File (.def) and select it. Call the file CustomAction and press Open. We'll add some content to it in a later step.
Right-click on the CustomAction project and select properties.
In the Configuration dropdown, select All Configurations
Expand the Linker folder, and select input. In the Additional Dependencies edit box, enter msi.lib and hit Apply. NOTE: As an alternate to this and the previous 2 steps, you can use the following directive in the stdafx.h or any other source file to tell the linker to link with msi.lib: #pragma comment(lib, "msi.lib")
In the upper right hand corner of the Property Pages dialog box, click Configuration Manager.
Under the Active Solution Configuration dropdown, select New. Enter the name Release Unicode, select Release from the Copy Settings from dropdown, and leave the checkbox checked. Press OK.
Repeat the previous step, calling the Configuration Debug Unicode and select Debug under the Copy Settings From dropdown. Close the Configuration Manager.
We are now back at the CustomAction property pages. Select Debug Unicode from the Configuration dropdown. Under the General Configuration Properties, find the Character Set setting and select Use Unicode Character Set. Press Apply.
Repeat the previous step for Release Unicode. Press OK to close the CustomAction property pages.
Repeat the previous two steps for the "HelloWorld" project by opening the property pages for the HelloWorld project.
In the CustomAction project, under the "Header Files" folder, double-click the file stdafx.h file to edit it. Under the // TODO: line, add the following lines:
#include <tchar.h>
#include <msi.h>
#include <msiquery.h>
#include <strsafe.h>
It is always a good idea to add versioning information to all the compiler outputs you build, so right-click on the CustomAction project and select Add->Resource. Pick Version from the list by double clicking on it. Edit the information here if you so desire.
In the CustomAction.cpp file, add four functions based on the following template named Install, Commit, Rollback, and Uninstall – function names are case sensitive.
extern "C" UINT __stdcall Install(MSIHANDLE hInstall)
{
return ERROR_SUCCESS;
}
Edit the CustomAction.def file and make it look like this:
LIBRARY CustomAction
EXPORTS
Install
Commit
Rollback
Uninstall

As a final step, we want to add the Custom Action DLL to the setup project. Right-click on Setup1 and select View->Custom Actions. Right-click on Custom Actions in the pane that opens up and select Add Custom Action. Double-click on Application Folder, and then click Add Output. Select CustomAction from the Project dropdown and accept the default Primary Output and Active Configuration settings. Click OK, then click OK on the Select Item in Project dialog. You will notice that four custom actions are added, and in viewing the properties for each of them the EntryPoint corresponds to the function names we created in the CustomAction.cpp file.

At this point, lets right-click on the Setup1 project and build it. You will notice that the file "msi.dll" is detected as a dependency for the Setup1 project – as a matter of fact, it will create a warning during compilation. Right-click on the msi.dll file under dependencies and check the Exclude option. Rebuilding the Setup1 project should now generate no warnings.

If you have not uninstalled the setup project from the earlier test, do so now, and run the Setup1 installation. You should see no difference from the previous time you ran the setup. If you get errors, you may want to download the zip file that contains the projects and steps we have performed up to here, and use WinDiff from the Bin directory of the Platform SDK to see if you can figure out the issue by comparing the directories of my project against yours.

Save your workspace and exit Visual Studio. Create a .zip file of the project directories – if you used my directory structure, you want to compress the "C:\Projects\CATutorial" directory. We will use this as a template for any future C++ custom action tutorials.

Initially, I was going to end this part here, but I thought people would be cursing me, saying that this whole exercise was pointless and no fun! After all this work, we created a Custom Action that did absolutely nothing! Let’s rectify that! Open your solution and replace the Install function in the CustomAction.cpp file with the following code (Don't worry if you don't understand it, we will cover this later):

extern "C" UINT __stdcall Install(MSIHANDLE hInstall)
{
    PMSIHANDLE hRecord = MsiCreateRecord(0);
    MsiRecordSetString(hRecord, 0, TEXT("Hello MSI!"));
    MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER + MB_OK), hRecord);
    return ERROR_SUCCESS;
}

When you rebuild the project and install it, you will see a "Hello MSI!" message when the Install Custom action runs.

You can download the Visual Studio 2003 Project Template from here (Special thanks to Aaron Stebner for hosting this for me). The next installment in this series will explain what we did (and why we did it)!

Custom Action Tutorial Part I – Custom Action Types and Sequences

2005-10-27T00:28:00.001-04:00

This is the first part of a multi-part series on Custom Actions in the MSI world. The articles are designed to be read in order, as each one will build from knowledge gained in the previous ones. To give you a short roadmap, the series will start with some dry and boring theory, and the subsequent articles will start us down a path of writing Custom Actions in unmanaged C++, C#, and script.

Custom Actions are used when the power of the Windows Installer engine's Standard Actions are not enough to accomplish a given installation task. For instance, installing or controlling a service is trivial using MSI Standard Actions, but creating a virtual directory in IIS is not. To create that virtual directory, you will need to write a custom action. Other examples of installation tasks that require Custom Actions can be found here.

Before beginning, I'd like to make sure you have the proper environment to work under. I'm going to use Microsoft's Visual Studio 2003 as the environment of choice for this series. The writing level is intended to be a walkthrough for someone who may be academically familiar with C/C++. I am going to handwave much of the Win32 enumerated types and definitions - the reader who is completely unfamiliar with these topics can find additional resources in books, the MSDN library, or around the web.

This part covers some necessary background on the different Custom Action types and Custom Action scheduling. Mostly this is dry and boring theoretical stuff, but essential to understand. Hopefully, I summarized it fairly well and won't cause anyone to drift off to sleep during their lunch hour.

Setting up your environment

For this first part, you only need the Platform SDK and a free MSI editor called Orca (distributed with the Platform SDK) installed. Future parts will require the following setup, so prepare yourself by setting this up. The development environment should be set up as follows: Install Visual Studio 2003, the current MSDN Library, and the most current Platform SDK. The Platform SDK contains new and updated header files and link libraries to support the latest OS platforms, components, and service packs. The installation of the Platform SDK installs a shortcut Microsoft Platform SDK in the Program Files menu. Open this and find the option to register the platform SDK directories with Visual Studio and run it. Finally, in the installation directory for the SDK, there is a directory "bin" and inside this you will find orca.msi. I recommend installing Orca, as my instructions are based on this. You may also substitute the MSI editor of your choice, just be aware of the differences.

Let's get started

We are going to use Orca to investigate the Orca.msi file. So, find the Orca.msi file, right-click on it, and select Edit With Orca, and play along.

The Two "categories" of Custom Actions

There are only two major categories of custom actions. The category of a custom action is indicated by a number in the type column of the CustomAction table (You should be finding this table in Orca as you read along). This number is actually a bitmask - for folks new to programming, if you looked at the number in binary form, the presence of a 1 or 0 in a particular location is how all the flags and options are interpreted by the MSI engine. I will give the hex (or Hexidecimal) representations of these flags throughout (all hex digits begin with a 0x to indicate they are hex). You can use the Windows "calc" program in the scientific view to enter the hex and convert it to binary to see which flag toggles which bit. Using hex (or even binary) is perhaps the best way to reverse engineer the decimal value from the table into the flags it represents. The two major categories of custom actions are:

Deferred - This is a modifier of (in hex) 0x400 or 0x4000 in the Type column of the CustomAction table, which corresponds to what MSDN calls (and you do not need to understand what these are yet) msidbCustomActionTypeInScript or msidbCustomActionTypeTSAware, respectively. What is important is Deferred actions are actions that modify the state of the system in some way. There are also some notable restrictions on deferred actions - you cannot change the value of a property, you can only read the value of a single property, and you cannot interact with the MSI tables. These can only be sequenced between the InstallInitialize and InstallFinalize actions in the Sequence table, lest you encounter the dreaded 2762 error "Cannot write script record. Transaction not started." error. You will find out the reasons behind this error later in this article. Additionally, there are options to specify a special kind of deferred action of "Rollback" or "Commit." These will also be covered later in this article.
Immediate - This is a modifier of zero in the Type column of the CustomAction table - in other words it is any entry in the Type column that does not contain the bitmasks described in the Deferred section above. Immediate actions are used for UI tasks, evaluating the state of the system, or preparing data or the system itself for later modification from a Deferred action. Immediate actions should never modify the state of the system.

The Orca.msi I am looking at has two different custom action types - 0x23 and 0x33. Neither of these numbers has the 0x400 or 0x4000 bits set, so this must mean they are Immediate Actions.

The Type column of the CustomAction table

Custom Actions have a Type - this is the base number (or bitmask) that gets entered in the Type column. This Type column tells the MSI engine both what they do and how to interpret the Source and Target columns of the CustomAction table. The major Types are:

Action	Hex Code	Description / Notes
Call a DLL function	0x01, 0x11	The DLL function that is called must be specifically written for the MSI engine.
Run an EXE	0x02, 0x12, 0x22, 0x32	Any EXE will run. By default, if the EXE returns a code other than zero, the action will fail. There is a flag available to turn off this behavior.
Abort the Installation	0x13	Aborts installation and displays a Formatted message from the target column.
Set a directory	0x23	Uses formatted text from the Target column to set a Directory.
Set a property	0x33	Uses formatted text from the Target column to set a Property.
Run some Jscript	0x05,0x15,0x25,0x35	Bear in mind the normally present WScript object is not available in these scripts.
Run some VBScript	0x06,0x16,0x26,0x36	Bear in mind the normally present WScript object is not available in these scripts.
Run a nested installation	0x07, 0x17, 0x27	Nested installations are evil. Don't do it. Use a setup launcher or AppSearch to enforce setup order.

Hopefully you see the pattern here - all the EXE actions contain 0x2, all the JScript ones contain a 0x5, etc.

The Source Column of the CustomAction Table

The second hex digit from the right in the CustomAction Type column tells us how to interpret the Source column. This is a bit more of a stretch then above, but you should see the trend:

Hex Code	Description / Notes
0x00	The Source column is a key into the Binary Table, where the the file needed to run this action is stored.
0x10	The file needed for this action is installed as part of this installation, the Source column is the key into the File table. This fact places restrictions on where this type of action can be placed in the installation sequence. In the case of the nested installation, the Source column points to the msi path inside this msi's source tree. For the abort action, the source column is ignored.
0x20	Source column is the key into the Directory table for setting the directory or indicating the EXE's working directory,Source column is the ProductCode for the nested installations,Source is null for the VBScript and Jscript actions. Note that you cannot return anything other than a success code with actions of this type. Actual script is stored in the Target column of the CustomAction table.
0x30	Source is the Property name where the value of the property will be set by the set property action, Source column contains the script code for script actions, or for the EXE action the Source column is the property that contains the path of the EXE to run.

The Target column of the CustomAction table

The Target column is dependent on the major type of the CustomAction, reading the MSDN Summary List of All Custom Action Types will explain this column in more appropriate detail. Looking back to the Orca.msi file - the actions listed translate to the following:

0x23 - Set the directory listed in the Source column to the Formatted Text in the Target column.
0x33 - Set the property listed in the Source column to the Formatted Text in the Target column.

How and When is a Custom Action run?
Now that we know a Custom Action is either Immediate or Deferred, and can be or do just about anything, we need to answer the question "How does a Custom Action get fired off?" Entering a Custom Action into the CustomAction table really only makes it available to be called - so just adding a line in the CustomAction table effectively does nothing. There are three methods of firing off a Custom Action:

In the sequence tables. This is probably the most common way of running a custom action, and the focal point of our discussion for the remainder of this article series.
In the ControlEvent tables. Essentially this is the method to launch a Custom Action in response to a UI event such as a button click. On Windows Server 2003 or better, custom actions run this way cannot send messages with MsiProcessMessage() calls, however Session.Message() calls from the automation interface work just fine (technically, prior to Windows Server 2003 neither message API officially works). Obviously, the installation must be running in full UI mode to fire these off. The Custom Action type launched by this method must be an Immediate type - remember we should never alter system state in the UI phase. I'm not going to cover how to run an Immediate Action from a dialog here using ControlEvent, perhaps in a later article.
By a call to Session.DoAction() or MsiDoAction(). This is a way of calling one Custom Action from another. Although this won't make sense until it is explained later on, you can not call a Deferred Custom Action in this manner unless it is called while the "installation script" is being written - but it should be OK to call it from a custom action scheduled between InstallInitialize and InstallFinalize. More on the "installation script" concept later.

The Sequence tables

Before we can discuss the primary way Custom Actions are launched, you need a better understanding on how MSI sequences work. We will get into this in more detail later in this article so I am handwaving some important details here for the sake of getting a basic understanding.

The typical installation is kicked off by double-clicking the MSI. This causes the installation engine to begin processing the InstallUISequence table (The processing of this table is skipped entirely if the UI mode is set to "basic" or "no UI" - both Full and Reduced UI modes actually do process this table). There are other sequences such as the AdminUISequence and AdvtUISequence that all follow the same logic for administrative and advertised installations. Hopefully you still have Orca open, so look at the tables as I describe them and follow along - sort the table by ascending sequence number.

The InstallUISequence table is processed in the order identified by the Sequence column (starting at sequence number 1), executing each action listed(Standard, Custom, and Dialog), as long as the Condition column for that action evaluates to true or is null (empty). The negative values in this table are "jumped" to on termination of the setup based on the result code of the installation. Once the "ExecuteAction" action is encountered, the InstallExecuteSequence is run. When the InstallExecuteSequence is complete, control will return to process the remaining UISequence table or it will jump to the corresponding negatively numbered sequence based on the result code of the installation process. Every action in the *UISequence tables are run in the currently logged on user's process for security reasons, and this is known throughout MSDN's documentation as the "client" portion of the installation.

The InstallExecuteSequence is where things get interesting, and differs based on platform.

On Windows NT based systems, this table is evaluated and run in a separate process from that of the User Interface. See my earlier article on Properties for information as to what is passed from the "client" (UI portion) to the "server" or "service" portion of the installation. To recap, the admin user has two processes owned by him/her, one is the UI sequence processing, and the second is the Execute sequence processing. The non admin user installing with elevated privlidges can have three processes - the same two as above, plus a third process, owned by the System, which executes the deferred
msidbCustomActionTypeNoImpersonate actions.
On Windows 9x based systems, both the *UISequence and *ExecuteSequence and all actions contained therein are run in the same process.

Actions in the *ExecuteSequence should only use UI interactions that use the Session.Message() or MsiProcessMessage() API's and not reference the Dialog table or contain UI's (such as MessageBoxes, status bars, shell progress indicators, dialogs from 3rd party libraries, etc.) in order to respect the UILevel wishes of the user.

Now or Later

Let's continue the discussion by distinguishing the Immediate vs. Deferred custom action categories a bit more. An immediate action is one that is "run" or "executed" immediately when the action is encountered in the sequence. A Deferred action is one that, when encountered in one of the Sequence Tables, is written to a sequential "installation script" with some metadata - you can think of this as a "To-Do list". Wherever you see the words "script" or "written to the script" in MSDN documentation, this is what I am referring to. More on deferred actions and scripts later - let's get the Immediate Custom Actions out of the way first.

Immediate actions have a method of assuring they will only be executed a set number of times - this is perhaps the most confusing page of documentation in the MSDN library. The Custom Action Type msidbCustomActionTypeFirstSequence will cause the action to not run in the Execute sequence if it already ran in the User Interface sequence. The msidbCustomActionTypeOncePerProcess flag is similar to the msidbCustomActionTypeFirstSequence flag, with the exception that it will run an action again in the Execute sequence if the Execute Sequence is being run in a different process than the User Interface process (In English - it will run in both sequences on NT machines, and only once on 9x based machines). The msidbCustomActionTypeClientRepeat flag means if you run the MSI in silent mode (and therefore don't have the UI sequence table processed) , the Custom Action wouldn't execute, but if you ran it in full UI mode it would execute. The lack of any of these flags causes the action to be run always. Remember that Immediate Actions should not modify the state of the system in any way. Deferred actions cannot have the properties described in this paragraph.

Deferred Actions are "recorded" in what is called the "installation script" before anything is actually run/executed. The script is created in the *ExecuteSequence when the InstallInitialize action is encountered, therefore deferred actions can only be sequenced after this action. The only time an item is written to the script is if the Condition is true at the time it is to be written to the script (as indicated in the Condition column of the Sequence table). In reality, there are two scripts being generated, the "installation script" and the "rollback script". I'm going to treat it as if there is only one script for simplified understanding.

Deferred Actions and the script

Think of this example: The MSI Engine is going through each of the actions in the InstallExecuteSequence in order of the sequence numbers, when - blammo - it hits the InstallInitialize action. At this point, it creates a data structure known as the "script" and starts recording all actions that meet the condition specified in the Condition column and are marked as msidbCustomActionTypeInScript along with some magical metadata (In other words it only records deferred actions in the script). If an immediate action with a proper condition (that also is compliant with the multiple execution flag setting) is encountered, it runs immediately. Otherwise, it keeps adding stuff to the script until it hits an InstallExecute, InstallExecuteAgain, or InstallFinalize action is encountered. Ignoring InstallExecute and InstallExecuteAgain for now, when InstallFinalize is encountered, it completes writing to the script and seals it from further additions. Then it begins processing the script by executing the actions, top down. The details of how the list is processed and the effect of InstallExecute and InstallExecuteAgain is covered in a bit.

So, what exactly is this magical metadata mentioned above? We already know that the condition column was evaluated before the decision was made to write the action to the "script" - if the condition was false, the task was not written. As near as I can figure, this metadata holds three major things:

The value of a property that having the same name as the CustomAction - the so-called CustomActionData property you have undoubtably heard so much about. Additionally, the ProductCode and UserSID properties are available in a Deferred action.
How to Run it flags (derived from the Type column of the CustomAction table)

The type of action (DLL, EXE, Script, etc.) and the path to the CustomAction code.
Impersonation type - The flag msidbCustomActionTypeNoImpersonate will cause the action to run in the system context vs. the otherwise usual currently logged-on user context. The exception to this rule is a server with Terminal Services which normally runs actions in the system context unless the msidbCustomActionTypeTSAware flag is set (flag valid on Windows 2003 Terminal Server only).
msidbCustomActionTypeAsync indicates that once the action is kicked off there is no need for the MSI engine to wait for it to complete before executing the next action. However, the MSI engine does want to know the return code, and as such will wait around at the end of the sequence until it finally returns if the action takes that long. All actions are synchronous unless this flag is set. Only EXE type custom actions can also combine the msidbCustomActionTypeContinue flag so that the installation can exit even while the Custom Action EXE is still running asynchronously.
msidbCustomActionTypeContinue indicates that the exit code of the custom action is ignored - therefore the sequence will progress even if the return code indicates failure.

When to run it flags indicates three possible things (again derived from the Type column of the CustomAction table). As briefly mentioned earlier there are actually two different scripts written - Commit and Rollback actions are both written to a separate "Rollback Script", but ignore this for now.

"Normal Deferred" assuming nothing has failed and the list is being processed top to bottom - msidbCustomActionTypeTSAware or msidbCustomActionTypeInScript
options without msidbCustomActionTypeRollback or msidbCustomActionTypeCommit flags
"Commit" - Run after the entire (sealed) script is processed once successfully (After InstallFinalize is encountered and the complete script has been processed once successfully). Actions in this category have themsidbCustomActionTypeTSAware or msidbCustomActionTypeInScript combined with msidbCustomActionTypeCommit flags in the Type column. This is only written if Rollback is not disabled - more on this later..
"Rollback" - if another deferred action failed, this will be run. This is only written for the msidbCustomActionTypeTSAware or msidbCustomActionTypeInScript
when combined with msidbCustomActionTypeRollback actions, and only if Rollback is not disabled - more on this later..

How the Script is Processed

To recap, we have a "script" containing deferred actions along with some metadata that we started collecting when InstallInitialize was encountered in the sequence. We can potentially start processing the list before it is completely written (assuming a InstallExecute or InstallExecuteAgain was encountered prior to InstallFinalize in the sequence tables).

Processing always begins top-down, and there are up to three "phases" in the script processing based on the "when to run it" metadata described above.

First, only "normal deferred" actions are processed. Each deferred action is executed only once - if an InstallExecute or InstallExecuteAgain action was encountered in the sequence tables causing a portion of the script to be executed prior to the script being completely written, "normal deferred" actions already executed are skipped.

If an error is thrown during the execution of a "normal deferred" action, the processing of the list reverses and starts moving backwards from where it currently is processing, executing the "On Rollback" actions in the list. Rollback can be "turned off" at a system level, if this is the case, Rollback actions will not be written to the script, and will not be executed.

Assuming all "normal deferred" actions are successful, processing of the script begins executing at the top again, this time executing the "On Commit" actions. Retuening a failure from a Commit Custom Action will cause any previously written Rollback actions to be executed. Because this causes some interesting and practically impossible to test scenarios, it is important to write solid Commit actions that do not fail or also specify the msidbCustomActionTypeContinue flag in the CustomAction table. Rollback can be "turned off" at a system level, if this is the case, Commit actions will also not be written to the script, and will not be executed.

Dealing with Rollback and Commit

If you are familiar with database concepts, Windows Installer is transactional. In other words, a failure to install a MSI package should leave the system in the exact state it was prior to beginning the installation. As such, Rollback and Commit actions are a part of the lexicon of Windows Installer, and understanding this when writing a Custom Action is essential. Also essential is understanding that Rollback can be disabled on a system level, thus, Rollback and Commit actions are not executed.

To adhere to the Windows Installer "Best Practices," all changes that are made to a system are in a "deferred" action - as an example, the "InstallFiles" standard action is actually a deferred action under the hood. Although not apparent in this manner (nor is apparrant by looking at the Sequence tables), the InstallFiles "normal deferred" action creates a backup of all the files it replaces if Rollback is enabled. This way, if an error occurs, all the replaced files can be restored to their previous state if an error occurs in a later deferred action through the Rollback process. The Commit actions are only run after all the "normal deferred" actions are run successfully - and the MSI engine uses the Commit action to delete the Rollback files.

Because of their nature, Rollback and Commit actions cannot be asynchronous.

A "normal deferred" Custom Action should only save rollback information if the RollbackDisabled property is not set. If it is set, Rollback and Commit actions will not be run, and this will cause your saved rollback data to remain after the installation is completed. You will need to pass this data into your "normal deferred" CustomActionData property in order to check if you should save rollback information.

Other Considerations

Inside a CustomAction, you may need to evaluate if a patch or repair is occurring. Since deferred CustomActions do not have the ability to check properties (other than the few properties mentioned earlier), you need to use an Immediate action to check (and pass on to the deferred action via CustomActionData) the value(s) of REINSTALL, PATCH, and/or MsiPatchRemovalList properties. For more details, see the Windows Installer Team Blog's comments on the subject or Heath Stewart's post.

To determine if you should save Rollback information in your deferred action, you will need to do the same technique as above to pass the value of the RollbackDisabled property. Other properties of interest for deferred CustomActions (depending on what they do) is ALLUSERS, and possibly UILevel.

To handle user requests to cancel the installation in any custom action, make sure that you check the return value from MsiProcessMessage() (or Session.Message()) calls to handle the IDCANCEL return value. I will be showing examples of handling progress messages in future posts on this topic. In the meantime check out the Windows Installer Team blog entry on the subject.

Another tricky concept is scheduling a reboot, if required, from a deferred Custom Action. Normally, you can't! To work around this oversight you have several options. The one I use is creating a file on the filesystem that the user running the installation can have delete access to. This is where the ProductCode and UserSID properties available to a CustomAction come in handy. Find the temp directory of the user using their SID and write a file with the name "ProductCode_rebootme" there. In an immediate action scheduled after InstallFinalize, check for the existance of this file and if present, delete it and call MsiSetMode() to indicate a reboot is required.

MSDN provides a few pointers on security here and here. In my opinion, it is extremely difficult to author a "data secure" MSI. If you need to pass internally sensitive data to a deferred custom action, use encryption on the CustomActionData in addition to adding sensitive properities (and the name of the deferred custom action) to the MsiHiddenProperties and using the msidbCustomActionTypeHideTarget CustomAction type flag. It is possible to digitally sign an installer package and its cabinet files. It is trivial to circumvent these measures if someone wanted to - and in a typical administrative installation, the msi signing is removed anyway. Think about data security in an MSI as glass in a jewelry store - it only keeps the honest people honest.

If a Custom Action needs to use disk space (to install a database, for example), you need to author (or modify at run time) the ReserveCost table. This is keyed on the installation state of a component.

The use of COM in a CustomAction is fine - when a dll-based Custom Action runs, it is created on its own thread. There is some conflicting documentation on this, however. MSDN claims CoInitialize is called in a per-machine installation and is not called in a per-user installation. A post here (scroll through to the comments) indicates that CoInitialize and/or its brethren CoInitializeEx is not called on this thread. I like MSDN's advice to not quit if it is determined the thread is already COM initialized.

Terminal Server is special. Throughout this article I have mentioned the *TSAware flags. In a per-machine installation on a Terminal Server, actions not marked with this flag are run as LocalSystem, where on a non-terminal server system they will normally impersonate the calling user.

The way patching and upgrading is handled, and its effect on Custom Actions, is the subject of a future article in this series.

The Ten Cent Summary

Custom Actions can be very powerful, and can be run in a variety of different ways and at a variety of times. The important things to remember when deciding on how to design them are:

Immediate actions are normally used to "set up" deferred actions (by stuffing CustomActionData) or to simply evaluate the state of a machine. Immediate actions are NEVER to be used to alter the state of a machine.
Deferred actions come in three different flavors, and where you have one, you should have all of them - the "normal deferred", rollback, and commit. The "normal deferred" should save undo information on the system somewhere if rollback is enabled. The rollback action will use this undo information to restore the initial state of the machine. The commit actions will clean up the rollback's undo information. Deferred actions can only be included in the execute sequences between InstallInitialize and InstallFinalize.
Rollback only occurs if an error is encountered while processing deferred actions (including Commit actions) between InstallInitialize and InstallFinalize in the *Execute sequences.
Because the conditions of deferred actions (including commit and rollback actions) are evaluated at the time the script is written, the same condition should be used for the sister actions.
Actions should be written to run correctly regardless of the UI mode and respect the wishes of the user when it comes to UI levels.
Never use a nested installation custom action type.
Understand the flags and options for scheduling and running actions as presented above.

Part II of this series will cover writing our first Custom Action in C++!

InstallScript and Enumerators

2005-10-04T21:12:00.002-04:00

I was helping a coworker out today trying to figure out why a simple VB Script using WMI could not be "ported" to InstallShield's InstallScript. The reason turned out to be that InstallScript does not support handling enumerators - In VBScript, you can enumerate a collection using the "For Each" construct. In JScript, you have the Enumerator object. In InstallScript - sadly - you have nothing.

I started thinking that I may be able to create a DLL to handle this. I then thought that someone else likely has done the same. My Google-foo came in handy and I found a post by __EDITED___ that covers the topic quite well. I was able to easily compile his C++ code into a DLL and use it immediately.

UPDATE: Turns out that the link previously referenced above was pretty much a blatent copy of code previously submitted to Installsite.org. Thank you to the commenter for pointing this out.

In the deleted link above, the poster was complaining about certain InstallShield limitations. I agree with most of the comments in his post - InstallShield's help system is at least second-rate. The InstallShield books by Baker are nice to have around, but not everyone has this luxury.

I disagree with his comments that MSI is "limited." It certainly is not the "holy grail" of installation technology - and I doubt that this can even exist. MSI technology is extremely extensible, but this comes at a cost of understanding the design patterns inherent in it - which are vastly different than the "other" installation technologies. I know I mentioned this before, but using MSI technology could practically eliminate vendor dependence and ease the switch between authoring tools.

Unfortunately, the documentation for MSI technology is equally as poor as InstallShield's. Rumor has it (plus the Amazon ratings) that Phil Wilson's book on the subject is pretty good - if Brian will ever let me borrow his copy I can give it an official review. I will attempt to help out with this by (finally) publishing my series on Custom Actions over the next several weeks.

Avoiding Disaster

2005-09-25T10:38:00.001-04:00

This post is a bit off the usual technical topic - I will be talking about the duo of hurricanes, impact on the victims, emergency response, pre/post emergency evacuation of large populated areas, your individual family emergency plan, and how to help. Although I am not currently active, I was a volunteer paramedic and firefighter, serving poor and middle-class neighborhoods for several years, so I do have some background in this area - but far from an expert on the subject. To my loyal readers, I have some technical content in the queue for later...

Impact on People

It looks like Hurricane Rita was not as devastating as was feared. Katrina, however, was a nightmare. Ignoring the evacuation problems, lets look at the issues someone who evacuated early will encounter:

Money. If you used a local bank, forget about getting cash from an ATM machine. As the banks were knocked offline, so was the ability of their patrons to access their money. Perhaps some distributed systems can be used in the future to alleviate this issue. In the meantime, I'd start depositing a good portion of my money in a nationwide bank or split assets between two banks housed on opposite coasts. Fortunately, lenders are claiming they are not going to report victims to the credit breuraus. Also fortunately, any cash you had in a banking institution should eventually be available.
Housing. I'd venture to say this is perhaps the worst - you come back to a slab where your house once stood. Jewelry, important documents, photos of your great-grandparents, etc. are now all gone. Even worse is the potential backups of this information stored at the bank or a family member's house are gone, too. Is insurance going to cover any part of the replaceable damaged items?
Job. Unless you work in construction, it could be a while before you can get your old job back. Hopefully, the owners of the damaged or destroyed companies will be able to rebuild at all. Without money, housing, or a job - I can't imagine surviving too well in today's society outside a log cabin house in the forest.
Attitude. While there are several personality types out there, the two I am looking at are the "society owes me" and "I'd never take a handout" type of people. Both of these extreme personality types will require a make-over. If the "society owes me" folks continue with this attitude (or possibly get it more ingrained), they will never recover - assistance programs will decrease as time goes on. The "never take a handout" folks will not be able to recover until they do get some external assistance. Unless you are in that log cabin house in the woods, you live in a society, and participation is a two way street. This reminds me about a old and now not-so-funny anecdote about a man stuck on his roof during a flood. Three rescue boats floated past and the man refused the assistance saying "God will save me." Eventually he drowns, goes to heaven, and asks God why he wasn't saved. God's response - "I sent three boats..."
Fixed income. These folks are the ones who tear at my heart-strings the most. In the previous paragraph I stated that "assistance programs will decrease as time goes on." These people are retired, and can't possibly rebuild their home, get a well-paying job (either because of age/health related issues or the fact that no company will hire them), or rely on long-term financial assistance. It would be nice to see a specific charity set up to help these people long-term who will soon be forgotten. Please leave a comment if you know of one.
Social Structure. Coming back from complete devastation, it is likely a significant portion of what used to be society is no longer there. Neighbors, friends, church members, etc. could have either died or given up on their old lives. The remaining social structure will be slow to recover and ineffective. Small communal groups will likely form inside the shattered society, and their establishment should be encouraged. I see faith-based church groups as the foundation of these mini-communes, as many of these organizations typically group together people of different skills to repair an elderly member's house in "normal times". These groups of people can utilize each member to their best potential to serve the needs of the group. This was the old "American Western Frontier" mentality, which is exactly what is needed in these areas today.

The other subset of people, who did not evacuate prior to the devastation have all the above issues, plus some others:

Mental scaring. I couldn't imagine being stuck in an attic with a gallon of water and a stale loaf of bread for a week - not knowing if I would eventually get rescued or not. Witnessing looting, fighting, and gunfire would put a damper on my ability to trust society when I do rebuild. Seeing bodies stacked on the sidewalk - unthinkable.
Mental boost. The word "news" was formed from the first letters of "North East West South". I have been thinking that the "N" now stands for "Negative". I have heard many stories about positive things occurring in the aftermath, but stories without images have a way of being forgotten - images of people shooting at rescue choppers don't. I'm sure that many (but hopefully most) people in the midst of this disaster had positive interactions with others of their own species.

There is also an impact on the part of society that was not affected at all by the hurricanes.

"How can I help" - I'm sure at least everyone in America has tossed at least a quarter in a fireman's boot for the relief effort. Unfortunately, this is not a very personal way of dealing with it. If this is as far as you have gone in the relief effort, shame on you. The money is needed later. Early on, the need was/is for water, housing, clothing, food, toiletries, sanitization supplies, ice, etc. The most effective assistance was immediate and non-financial. A local radio show got corporate and individual sponsors to get trucks full of various goods (from a specific list, donated by listeners) and convoy it to the affected areas. This was immediate assistance of exactly what was needed. Listening to the stories of the volunteers drivers in this effort brought me to tears - literally.
"I'm not helping those looters" - I can't believe I actually heard this one (while dropping off a donation of goods for the convoy...). Repeat after me - "Not everyone in this world is evil". Taking it one step further, that attitude is not going to help society become less evil.

Emergency Response

Without getting overly technical, the response to any emergency is the same. It requires knowledge (as early as possible in the emergency) such as:

Where is the emergency? In cases of mass casualty incidents, where is the worst emergency so we can attack that first.
What is the emergency? Each response team has a different one (the engineers' emergency was to plug up the levees, as an example), but all efforts are focused on saving lives first.
What are my resources? This is people (rescue workers), equipment (trucks, boats, choppers), and supplies (water, medications, etc) - just to name a few.
Access. How close can I get to the scene? Can I get other, possibly more critical, resources in later? Can I get victims out?
Mitigation. If there is a chemical spill, do I have to worry about keeping it out of the creek? For a fire, we would want to protect the building housing the explosive materials more than other surrounding buildings. How do we stop an already bad situation from getting worse?

This is where the concept of disaster planning comes in. Every area has one. In Pennsylvania, we have a bunch of coal mines, so dealing with fires, subsidence, and rescue is in our plans, and it may not be in your community's plan. To create the plan, you take a risk analysis of different disaster types, and attempt to answer all the questions posed above for the highest risks in advance.

For example, if there is a poly-methyl-bad-stuff chemical manufacturing plant, we would know, in advance, of where to go, what to do, and who to call. This is easy. Keeping it up to date is hard. When a parking lot next to the plant gets converted to an office building, you have additional concerns of more victims and less access. Was the plan reviewed and updated with this new development? Usually, the answer is no.

Planning for disaster response on a large scale - like an entire city - is impossible. You just can't answer questions like the above in advance. For things like this, we rely on a list of resources. In my community's plan, we have several phone numbers for school bus and public transportation companies, heavy equipment companies, etc. If we need a drilling rig on Christmas Eve, we should be able to get one. Are these numbers and resources kept up to date? Likely - no. In a mass disaster situation, you do not have the resources to hunt down the current foreman of "Bob the Builder, Inc" to get a bulldozer to prevent one tragedy when there are 100 other tragedies going on at the same time.

This is where you, as an individual or business owner, can help. Contact your local fire department, and let them know what resources you have available, where they are located, and how to contact you or others that also have access to them. Notify them when this changes. There were cases where I wish I had an ATV or a snowmobile I can get quickly where it was rather difficult to get access or equipment to it. Ask what you can do in the event of an emergency to help out. Volunteer as a fund raiser or associate member of the fire and/or rescue squads to make sure these items are kept up to date and you and your community are protected. You don't have to go into a burning building to help save a life. Remember, after an incident starts, it is too late for planning.

Mass Evacuation

The infrastructure of all cities makes a mass evacuation impossible. Roads are designed (and in Pittsburgh, especially poorly) to manage the traffic of under 10% of the population using a major roadway on a daily basis. There is no way to manage this or mitigate it. Mass evacuations of cities will never go well. If you do have to evacuate, understand why you are evacuating - for a flood, if you can't get out, seek the highest natural ground or a flotation device. Have emergency packs where you keep items like water, non-email-based Spam, first aid products, sanitizers, blankets, maps, camping gear, and medical information/contact information tags for your family that they can wear, put in their pocket, or tape to their arms. You can grab this kit and go. Don't try to move that plasma TV to the attic and barricade the house from looters. Most people will try to get this stuff together before they leave. The earlier you leave the better.

Head for any area that is safe where you think other people won't think of to go. Going to the next major city where friends and relatives are is the first thing people think of. You can get to the friends and relatives later - for now get out of the danger zone and go where the route will be less crowded.

For businesses with large vehicles (trucks, buses, etc.) - make sure you know what to do before you get out in a mass evacuation. Where do you fit in the evacuation plan? Ask this ahead of time - you can be given a specific location to go to to pick up people and route to take when an evacuation is called. You are more likely to get assistance if you run out of gas if you are hauling maximum vehicle capacity of random people, than a car with one or two people full of useless stuff.

Your Family Emergency Plan

As a small kid in an amusement park, there was nothing more thrilling than being old enough where your parents let you go off on your own. Typically, you met at different times throughout the day at the same location so they knew everything was OK. But before you were old enough, I am sure your parents gave instructions as to what to do if you were separated - meet at the Merry-Go-Round, find an employee or security guard, etc. How many people have a plan if their house catches on fire? For something like Katrina? An earthquake?

There are plenty of sites that will help you create one. I'll leave it up to your Google-foo to find them. Here are some ideas to start you off:

Sinking Titanic, Flooding, injured by a large explosion, etc. - Lets say the worst has happened. You are with your family now - but you may get separated. If not by the incident itself, rescue workers will need to separate people based on the criticality of the injury. Make sure everyone has ID - this could be as simple as putting a drivers license or credit card in everyone's pocket, diaper, whatever. Better yet is a Sharpie marker or something indelible where you can write directly on the skin - name, DOB, SSN, important medical information, and a few phone numbers of people you know. Trust me - in this situation scrawling "Diabetic" on someone's forehead is a REALLY good idea. Remember - you may get separated from your ID, clothing, medical bracelet, etc - and in the worst case, you may not be able to communicate. Make sure everything a rescuer could need is available, not only to medically assist, but to reunite you.
Grabbing on to others. Same goes for tying a bunch of people together. In a water emergency, you may lessen the chances of both for survival. There are several techniques you can use, if you are in flood prone areas or like to boat, this is something you should research. I like the "The Worst-Case Scenario" series of books - they are humorous to an extent, but contain real and practical information. They are great coffee table type books to have around and page through, as an added bonus.
Have a series of phone numbers handy, and on your kids at all times - not just in an emergency. Have not only the numbers of the local relatives, but the long-distance ones too. Explain that you are to call as many of these people as you can with your location to make reuniting easier. Cell phone numbers, although nice, are useless in a mass emergency.

Helping Out

Before donating, see if your company, like mine does, matches donations - then pick the best one from the list. Organizations that rate charities such as Charity Navigator are helpful. Remember that there is always overhead with these organizations, so try to get the most bang for the buck with your donation. Even better is to call a few local church groups and see if they are tied into a group in the affected areas with specific needs. Go out and buy these needs, and ship them down there. This way, 100% of your donation is being utilized.

My heart goes out to all the victims of this disaster, and to the families who lost loved ones. God bless them, and protect them.

Trouble ahead for time computations?

2005-07-31T22:50:00.002-04:00

I was just reading an article about the new U.S. Energy Bill that intends to extend Daylight Savings Time an additional month (starting in 2007). I wonder what the impact of this is on the Computer Science front. There has not been any chatter on my normally read blogs, but perhaps there will be soon. I have no facts to back up my theory here, but lets play along with my conspiracy theory and possibly learn something about static and dynamic linking of DLLs.

Think about this from the Microsoft C/C++ developer perspective: the date functions are implemented in the C standard library, MSVCRT.DLL (or its post VC6 brethren MSVC*.dll). Lets assume (although I am guessing) that the "rules" for the current daylight savings time are implemented in this same DLL (NOTE: Please see comments). One of these functions is called mktime(). Let me quote from MSDN:

When specifying a tm structure time, set the tm_isdst field to 0 to indicate that standard time is in effect, or to a value greater than 0 to indicate that daylight savings time is in effect, or to a value less than zero to have the C run-time library code compute whether standard time or daylight savings time is in effect. (The C run-time library assumes the United States's rules for implementing the calculation of Daylight Saving Time).

So if we developers assumed that the runtime would take care of conversions for us, and we statically linked to the library, we may have to recompile against a newer link library (with the revised code) for our applications to continue working if this change actually happens. On the other hand, had the developer dynamically linked to this DLL and not copied the pre-dst-updated MSVCRT.DLL to the application folder or application current directory (Remember that in Windows Server 2003 and possibly Windows XP the rules have changed), the DLL can be updated once in the system32 directory (perhaps through Windows Update) and our preexisting applications will be none the wiser and work just fine with the change.

This is more food for thought on the debate of static vs. dynamic linking that could help sway some developers into a different line of thought - I prefer dynamic linking, but in some cases for some applications I do not practice what I preach. For the installation folks, please read the previous link (and the comments - good stuff there on merge modules) - this is why you need to be sure that you are following proper version replacement and marking shared DLL's as shared - otherwise you can cause grief for other applications or your own.

[UPDATE: 10/4/2005 - fix formatting and errant character]