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:
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:
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'.
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