SPC 2011: <Coming Soon>

The Synergy/DE community is filled with companies developing on a broad range of platforms. Some are based in OpenVMS, others are UNIX enthusiasts, and others support Windows, with most offering their solutions on a combination of these platforms. Our community includes companies already deploying the latest Synergy/DE technologies and others running successful businesses with the version they’ve had for many years. Regardless of where your company fits in the Synergy/DE community, SPC 2011 is designed for you.

The SPC has a new format this year, one that offers something for everyone, on every platform, and at every stage of development.
Day 1 is an exhibition of the technologies available in today’s Synergy/DE. A series of high-level presentations will cover all of the topics essential to current software developers, such as user interfaces, data and storage, networking, and development environments. With the broad range of features in Synergy/DE– both old and new – these first-day sessions will help you envision how these features will enrich your applications and improve your productivity.

On Day 2, you’ll delve deeper into these technologies as our highly-skilled and experienced presenters address common, specific development objectives and obstacles – and discuss potential strategies to help you accomplish your goals. These presentations are of a more technical nature and are designed to present you with the examples and “how to’s” that will jumpstart your development initiatives. You’ll also get to witness first-hand how one Synergy/DE customer is successfully using Synergy/DE technologies to advance its application.

Day 3 is your day to get your hands dirty as you try out these technologies for yourself. You’ll choose from a wide variety of hands-on tutorials that will provide you with a deeper understanding of Synergy/DE technologies and an abundance of new skills that you can put to use as soon as you return to the office.

This year’s SPC is guaranteed to provide three of the most productive days of your year, as you gain valuable knowledge and skills you can immediately employ to advance your own applications. Don’t miss this opportunity: Attend SPC 2011 and discover just how far your Synergy application can take you!

http://spc.synergex.com

Unraveling the Mystery behind Installation Issues

The Windows Installer Log Deciphered
By Henry Steinbeck, Windows Installation Engineer

Nobody ever wants to have it happen to them but sometimes problems arise when installing an application. At these times, your best friend will be the Windows Installer log. This log will tell you everything that occurred during the installation, making it the best resource for troubleshooting installation problems. Also, an installation log is an extremely effective means to communicate your installation problem to product support engineers.

However, cracking open the log file in a text editor and scrolling down till you see the culprit seldom proves fruitful. A typical log file can be thousands of lines long with seemingly repetitious entries. What’s more, many reported “errors” are not problems at all.

In this article we’ll go over where to find the installer log, what kind of entries it includes and what they mean. We’ll also discuss a utility that can help you decipher the log file. While information in this article is applicable to any installation that uses the Windows Installer service, I have also included information that is specific to Synergy products throughout.

Let’s get the file

The first step in troubleshooting an installation problem is to locate or create a log file.

Installation packages for Windows Installer 4.0 and higher can be configured to create an installation log file automatically. (To see the Windows Installer version, type “msiexec” at a command prompt.) So, if you are using Vista or a later platform, you’re in luck because Synergy installations already have a log file to examine. The log files are written to the folder defined by the “temp” or “tmp” environment variable. The log file name, beginning with “msi” and ending with “.log”, is randomly generated by Windows Installer. The following command (run from the “temp” directory) will list all installation log files with the most recent file at the bottom of the list:

>dir /od msi*

If an installation has just failed, odds are that the last log file will be of most interest. To make sure the log file is from the product you are having problems installing, search for the “ProductName” property in the log.

With earlier versions of Windows Installer, you can enable logging in a number of ways. On a per machine basis, you can add a registry entry. Or, for a one time shot, you can run the installation from the command line to set logging options. Also, logging can be enabled through group policies under the Windows Installer section.

To enable Windows Installer logging on a per-machine basis, add the following information to the registry:

KEY	HKLM\Software\Policies\Microsoft\Windows\Installer
Value Type	Reg_SZ
Value Name	Logging
Data	voicewarmupx

With this setting enabled, log files will be written to the temp folder in the same manner described above for systems with Windows Installer 4.0.

A log file can also be generated by initiating the installation from the command line using the msiexec command. To see the logging options, type “msiexec” at a command prompt. In the dialog that displays, scroll down to find the logging section. While there are a number of options, there is a clever mnemonic device to help you remember, voicewarmupx. The asterisk can be used as a wild card to log all information except for Verbose (v) and Extra debugging (x) options.

May I suggest… For installation logs, I feel more is better—up to a point. I’d recommend getting a verbose log of everything, but skip the extra debugging, by using /lv*.

Here’s an example of how to install Synergy/DE with a log:

msiexec /i 101sde951.msi /lv* c:\temp\sdeinstall.log

I have a few Synergy-specific things to mention here:

For the Synergy/DE installation package, we require that the entire installation run elevated. So, on Vista and higher platforms, if you execute the command above from a regular command prompt, you will get an error message requesting that you invoke the installation with elevated privileges.
If the location specified for the log file is not writable, the installation will fail immediately.
For Synergy/DE Client, the installation depends on having the LICENSE_SERVER property set at the time the installation is executed. To log a client install from the command line, you need to either add the logging option (just before the LICENSE_SERVER property) to the setup.ini or, if using msiexec, add “LICENSE_SERVER=YourServer” to the end of the msiexec command line. For example, in the setup.ini, you can do this:

CmdLine=/lv* c:\temp\sdeinstall.log LICENSE_SERVER=YourServer

Or, from msiexec, you can do this:

msiexec /i synclient.msi /lv* c:\temp\sdeinstall.log LICENSE_SERVER=YourServer

Log file structure

Now that you have found a log file, let’s open it up in your favorite text editor and take a look. Typically you are going to see thousands of lines in a log file. So, let’s get started on figuring out what all these lines really mean.

Entry line header

All entries in the log file, except those pertaining to action status, begin with a header similar to this:

MSI (s) (5C:F8) [12:14:54:078]:

The first set of parentheses, in red, will likely be of most interest. The letter within the parentheses indicates what process generated the event. Multiple processes are initiated while Windows Installer is processing an installation package. However, they all write to the same log file.

Typically, when we talk about server and client model, we are discussing details about distributed applications. However, in regards to Windows Installer, we are referring to separate processes running on the same machine. Each process runs within its own set of memory but can have properties passed from another process. The table below describes each process.

Letter	Type	Description
c	Client	The Client process initiates the installation. Client entries are at the beginning and end of the log. Windows Installer Dialogs are displayed from the Client process. Even if there is no UI during the installation, there will still be some Client initialization and finalization entries.
s	Server	The Server process is called from the Client process. While the Client can pass properties to the Server, all properties are reevaluated during the Server initialization. Server entries generally occur during the time that changes are being made to the system. On Vista and higher systems, the Server process always runs elevated.
n	Nested	Nested installations are a deprecated feature of the Windows Installer. It is not likely you’ll see a nested entry. Nested installations allowed an additional msi package to be installed during the same session as the parent msi package.

The second set of parentheses, in green, indicates the last two (hexadecimal) digits of the process and thread ID.

The information between the square brackets, in blue, is a time stamp to the millisecond.

Actions and return values

Actions are tasks run throughout the installation session. Some actions are standard Windows Installer actions that are defined by the Windows Installer product. Other actions are built by the author of the installation package to do specific things peculiar to the product being installed. Actions authored by the installation engineer are called custom actions.

Custom actions can be scheduled to occur at nearly any time during the installation process. Every custom action has a condition that must evaluate to true before it is run:

MSI (s) (5C:F8) [12:14:42:000]: Skipping action: caTouchVslickSta (condition is false)

When an action is performed you will see a line similar to this:

MSI (s) (5C:F8) [12:13:59:390]: Doing action: caCheckServices

For each action that is run there will be an “Action start” and an “Action ended” entry.

MSI (s) (5C:F8) [12:13:59:078]: Doing action: caSetARPINSTALLLOCATION
Action 12:13:59: caSetARPINSTALLLOCATION.
Action start 12:13:59: caSetARPINSTALLLOCATION.
[Between the Action start and Action ended entries, custom actions can write information to the log file while they are running.]
Action ended 12:13:59: caSetARPINSTALLLOCATION. Return value 1

All actions return one of the following values upon completion:

Value	Meaning
0	Action was invoked, but did not run (not necessarily a bad thing; maybe there was nothing for it to do)
1	Action was a success
2	Action was cancelled by user
3	An unrecoverable error has occurred
4	The installation was suspended awaiting a reboot

TIP! To quickly find a failed action in a log, search for “Return value 3”

Error codes

Error codes are listed throughout the log in the following format:

Note: 1: 1402 2: HKEY_LOCAL_MACHINE\SOFTWARE\Synergex\Install 3: 2

In this example, the Windows Installer error code is 1402, which, when we look it up on the Microsoft website, gives us the following message:

Could not open key: [2]. System error [3].

Bookmark it! The link below is Microsoft’s online source for Windows Installer errors:

http://msdn.microsoft.com/en-us/library/aa372835(v=VS.85).aspx

Once we plug the details from the log into the message “shell” from the website, we have:

Could not open key: HKEY_LOCAL_MACHINE\SOFTWARE\Synergex\Install. System error 2.

Looking up System error 2, reveals the message ERROR_FILE_NOT_FOUND, which means the registry key could not be found. Is this error a problem? Well… it depends on the context. Even a successful installation will have numerous error codes returned. Most errors in an installation log are simply informative, rather than indicative of a problem. Determining if an error code is the root cause of the problem can be tricky. In this case, the Synergy/DE product had never been installed on this system before, which means the registry entry was not expected to be there, so in this instance this message doesn’t indicate a problem.

Error messages nearest the point in the log where a problem has been indentified will likely be most relevant, but reserve the possibility that many of the errors you see in the log may not have anything to do with the problem that caused the installation to fail.

Log file layout

The bullets below show the layout of an installation log to show where certain activities are recorded in a typical installation. The information in the parentheses identifies whether the activity is run by the client or server process.

(client) initialization
(client) evaluation of properties
(client) display dialog windows

The dialog windows are used to gather information from the user, such as feature selection and installation location. Often a dialog window with a progress bar is displayed while the server process is running.

(client) initiate server process

The server process is separate from the client process for security reasons. On Vista and higher the server process runs elevated. The server will re-evaluate properties.
The client process does not share the same properties with the server process, except for the ones defined by the SecureCustomProperties property. In the log, when control is passed to the server, you will see a line labeled with “Switching to server:”, followed by a comma-separated list of properties and their values that were passed.

(server) re-evaluate properties
(server) evaluate install state of features and components and files

For each feature and component, the installer service evaluates its status on the system and determines the Action that will be taken. The lines below are typical of the evaluation of a feature and a component.

MSI (s) (5C:AC) [12:13:53:218]: Feature: SDE; Installed: Absent; Request: Local; Action: Local
MSI (s) (5C:AC) [12:13:53:218]: Component: dbr.exe; Installed: Absent; Request: Local; Action: Local; Client State: Unknown

The link below will provide more information from the online version of the Windows Installer documentation:
http://msdn.microsoft.com/en-us/library/aa367858(VS.85).aspx

(server) modify system resources to install and configure application
dump server properties

Server properties are denoted by: Property(S)

dump client properties

Client properties are denoted by: Property(C)
Client properties can have different values than server properties if actions have changed their values.

(server) return control back to client
(client) finalize installation

Here are some common cases which alter the outline above.

During a major upgrade, the previous version of an installed product is first removed. There will be a large number of entries associated with the removal of the product. When the uninstallation completes, a list of properties is written to the log file. These major upgrade “uninstall” properties will be denoted by: Property(N). At this time all Synergy products, even patch releases, perform a major upgrade on systems where a previous version is already installed.
Installations and uninstallations can be performed with no User Interface, in quiet mode. In this case no client activities occur, except initializing and finalizing activities.
Naturally, if you are looking at the log, it’s probably because there was a problem. If the installation had already begun modifying system resources before encountering the failure, then it’s going to have to undo all those changes. The steps where the installation is undoing changes are labeled with “Rollback”. Since Rollbacks occur just after a failure, sometimes you can search for where the rollback lines begin to get close to the source of the failure. “RollbackCleanup” lines occur upon successful completion so expect to see these lines in a log file that successfully completed the installation.

wilogutl.exe

Wilogutl.exe assists in the analysis of a Windows Installer log. It has a lot of nice features that make it easier to examine a log, but it is not critical. I find wilogutl is helpful when you are first learning your way around Windows Installer logs. Once you know what to look for, any text editor will do.

The Wilogutl application is available as part of Microsoft Windows SDK. By default it’s installed to “C:\Program Files\Microsoft SDKs\Windows\[version number]\Bin\WiLogUtl.exe" The following link will take to you to the Microsoft webpage where the latest version of the SDK can be downloaded.
Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1

Features of this tool:

Presents possible solutions to errors

Your mileage may vary on how helpful these recommendations are.

Error code table

The application will list Windows Installer error messages. This table is static and may not be up to date. If you cannot find an error number, check the online source for Windows Installer error codes.

Color coded html output of log file

The application has an option to open a web browser with the log color coded by context and buttons to navigate between errors.

Simple UI to organize information from log file

From the main UI, windows can be opened which show:

Properties table with a tab for each context
Feature and component states
System Policies pertaining to installation

More information on log files

Wilogutl has a nice document, “How to Read a Log File”, which contains more information about Windows Installer log files.

Resources for additional information

Richard Macdonald’s Web Log “How to Interpret Windows Installer Logs” – This article has a link to an annotated msi log file that provides additional information.
Microsoft white paper “Windows Installer: Benefits and Implementation for System Administrators” – Go to the troubleshooting section for more information about installation log files. This is an old white paper and while some aspects of Windows Installer have changed the content on troubleshooting is still relevant.
msi.chm – This is the documentation for Windows Installer from Microsoft, this file is included in the Windows SDK or the online version of the documentation can be found here. For troubleshooting, most likely you’ll be looking up error codes here.
Windows Installer article on Wikipedia.org – The table listing Windows Installer versions and the operating system they’re included with is handy.
Christian Muggli blog article “MSI Understanding the Windows Installer Logs“- Yet another article on understanding Windows Installer log files.

Synergy/DE Tech Tip

Calling a destructor from outside a shared image on OpenVMS

Question:

I am trying to code a custom destructor, but when I run my application and the destructor is called, my application hangs. The Task Manager shows a dbs.exe that is taking 100% of the CPU.

Answer:

In any object-oriented language, if you are going to use a custom destructor, it must never throw an untrapped error. The destructor is called as part of the runtime cleanup, so if you're not using error trapping to ensure it doesn't run into an error, it can cause the runtime to enter an infinite loop.

The easiest way to accomplish this is to put the destructor in a TRY-CATCH block. For example,

namespace tryCatch
  public class myClass
    method ~myDestructMethod
      proc
          try
            close 0
          catch (e, @exception)
            nop
          endtry
    mreturn
    endmethod
  endclass
endnamespace

Quiz

Synergy/DE pros, see if you can answer this question!

What is the output of the following program?

main
record
	x, int, 49
proc
	open(1,o,"TT:")
	using x select
	(x < 50),			writes(1,"a")
	(< 49),			writes(1,"b")
	(%decml('0') thru %decml('9')),	writes(1,"c")
	(),				writes(1,"d")
	endusing
end

a. "a"
b. "b"
c. "c"
d. "d"
e. nothing

Click to find out the answer

Platform News

Read a selection of recent articles from around the web

General

Mozilla sets Firefox 4 release for Tuesday

Windows

Unix