WinDeveloper O365 Mailer FREE for 1 Year

WinDeveloper IMF Tune
WinDeveloper IMF Tune

Extracting ExMerge Processing Results

Alexander Zammit

Alexander Zammit Photo

Alexander Zammit has been developing server applications for over 15 years. Most of his works involve Exchange integrated applications, including a FAX server, a mail security product and anti-spam products.

  • Published: Dec 14, 2006
  • Category: ExMerge
  • Votes: 4.3 out of 5 - 6 Votes
Cast your Vote
Poor Excellent

Batch processes often rely on ERRORLEVEL tests to determine whether a call completed execution successfully. However ExMerge does not expose its processing result in this manner. Today we bridge this gap.

We started discussing ExMerge batch process integration in Complete ExMerge Command-Line Control. Here we looked at the benefits of the command-line interface. We saw how to extract the list of mailboxes through lidfde.exe. Finally we configured ExMerge.ini using another command-line tool ExMergeIni.exe.

Today we look at further improving batch process integration. We use ExMerge logs to determine whether an import/export session completed successfully. In this manner we enable an unattended batch process to automatically handle any failures.

ExMerge Processing Summary Log

A batch process running a sequence of operations should ensure that each command is completed successfully. Those accustomed to batch file scripting will immediately think of statements of the type:
IF ERRORLEVEL 1 GOTO END

It is common practice for command-line tools to return 0 when an operation completes successfully. Other return values typically signal failures and other possible outcomes.

The ExMerge executable does not return such information. Applying a direct ERRORLEVEL test won't work. Instead the process status and any errors are reported to a set of log files. The main log file, the one we are interested in, is named ExMerge.log. Additionally ExMerge will also create a log file for each worker thread named ExMerge-(Thread0).log, ExMerge-(Thread1).log and so forth.

As ExMerge goes through its processing, these files record information on each completed step. Most importantly ExMerge.log will also include a summary report. This is recorded at the end of the file and looks like this:

[14:50:57] 78 mailboxes successfully processed. 0 mailboxes were not 
successfully processed. 0 non-fatal errors encountered.

IMPORTANT: This article and the included tool were only verified against the ExMerge build included with the Exchange 2003 Tools. There is a good chance that earlier versions also generate the same summary report. Thus anyone using earlier ExMerge versions should verify this point.

ExMergeLog.exe - Bringing It All Together

ExMergeLog.exe (see references for download link) is a little tool that searches the logs for the summary report. It determines whether any failures were encountered and returns an ERRORLEVEL of 0 or 1:
0 - Success
1 - Failure

Here is the application help information:

ExMergeLog.exe

Let's have a look at the ExMerge.log summary report again:

[14:50:57] 78 mailboxes successfully processed. 0 mailboxes were not 
successfully processed. 0 non-fatal errors encountered.

This includes three pieces of data:
x mailboxes successfully processed
x mailboxes were not successfully processed
x non-fatal errors encountered

If run without any parameters ExMergeLog.exe will look for ExMerge.log in the application directory. Otherwise using the -f parameter the log file path and filename may be explicitly set.

By default ExMergeLog.exe ignores non-fatal errors and returns ERRORLEVEL 1 (failure) in these cases:

  1. If the summary report is not found within the last 1024 bytes of the log file. Note that when ExMerge fails before starting mailbox processing the summary report won't be present.

  2. In case of unexpected problems (access rights, missing log file etc).

  3. If the summary report says '0 mailboxes successfully processed'.

  4. If the summary report does NOT say '0 mailboxes were not successfully processed'.

You can force ExMergeLog.exe to also fail in case of non-fatal errors by specifying the -a parameter.

The script that follows was originally presented in Complete ExMerge Command-Line Control. It now includes log verification through ExMergeLog.exe. Additionally an ERRORLEVEL test was also added for ExMergeIni.exe. Originally ExMergeIni.exe always returned 0. However this was now updated to return 1 in case of failures. ExMergeLog.exe, ExMergeIni.exe and the sample script are included in the download zip (see references).

echo OFF
echo =================
echo = Backup Script =
echo =================
echo -
echo - Base Backup Destination Path: %1
if NOT EXIST %1 ( echo - FAILED: Invalid destination path. 
goto end )

md %1\Exchange
md %1\Exchange\Brick 
md %1\Exchange\logs

C:\Backups\Script\ExMergeIni.exe DataDirectoryName %1\Exchange\Brick 
-f C:\Backups\Script\ExMerge.ini

IF ERRORLEVEL 1 GOTO FAILEXIT

C:\Backups\Script\ExMergeIni.exe LogFileName %1\Exchange\logs\ExMerge.log 
-f C:\Backups\Script\ExMerge.ini

IF ERRORLEVEL 1 GOTO FAILEXIT

echo -
echo ExMerge Starting...

"C:\Program Files\Exchsrvr\bin\ExMerge.exe" -b 
-f C:\Backups\Script\ExMerge.ini

echo ExMerge Ready
echo -

C:\Backups\Script\ExMergeLog.exe -f %1\Exchange\logs\ExMerge.log
IF ERRORLEVEL 1 GOTO FAILEXIT

echo -
echo * * * * * BACKUP SUCCEEDED  * * * * *
echo -
goto end

:FAILEXIT
echo -
echo * * * * * BACKUP FAILED  * * * * *
echo -

:end
pause

Final Tips

ExMergeLog.exe bridges the communication problems between ExMerge and the batch process, allowing us to perform an ERRORLEVEL test. Other generic file parsing tools could have been used instead. However I hope this dedicated tool will simplify your batch process scripts.

References

Meeting the ExMerge Requirements

Complete ExMerge Command-Line Control

ExMerge Download - Tools for Exchange Server 2003

Copyright © 2005 - 2016 All rights reserved. ExchangeInbox.com is not affiliated with Microsoft Corporation