Extracting ExMerge Processing Results

[LEFT][CODE]http://exchangeinbox.com/article.aspx?i=69&t=4[/CODE]


[B]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.[/B]

[LIST][*][SIZE=2][B][URL="http://exchangeinbox.com/attachment.aspx?i=7"]exmergelog.zip - 57 Kb[/URL][/B][/SIZE][/LIST]


We started discussing ExMerge batch process integration in [URL="http://exchangeinbox.com/article.aspx?i=61"]Complete ExMerge Command-Line Control[/URL]. 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.
[B]ExMerge Processing Summary Log[/B]

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.
[B]IMPORTANT:[/B] This article and the included tool were only verified against the ExMerge build included with the [URL="http://www.microsoft.com/technet/prodtechnol/exchange/downloads/2003/tools.mspx"]Exchange 2003 Tools[/URL]. There is a good chance that earlier versions also generate the same summary report. Thus anyone using earlier ExMerge versions should verify this point.
[B]ExMergeLog.exe - Bringing It All Together[/B]

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:

[IMG]http://exchangeinbox.com/image.aspx?i=158[/IMG]
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:

[LIST=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.[*]In case of unexpected problems (access rights, missing log file etc).[*]If the summary report says '0 mailboxes successfully processed'.[*]If the summary report does NOT say '0 mailboxes were not successfully processed'.[/LIST]
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 [URL="http://exchangeinbox.com/article.aspx?i=61"]Complete ExMerge Command-Line Control[/URL]. 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
[B]Final Tips[/B]

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.
[B]References[/B]

[URL="http://exchangeinbox.com/article.aspx?i=58"]Meeting the ExMerge Requirements[/URL]
[URL="http://exchangeinbox.com/article.aspx?i=61"]Complete ExMerge Command-Line Control[/URL]
[URL="http://www.microsoft.com/technet/prodtechnol/exchange/downloads/2003/tools.mspx"]ExMerge Download - Tools for Exchange Server 2003[/URL]


[/LEFT]