Command-Line Users: Verify Correct Exit Code Handling

Overview

Important: Unless a command-line script explicitly returns DataVeil’s exit code, an external caller may receive a successful script exit code even when DataVeil reports an error.

DataVeil returns a non-zero exit code to indicate warnings and errors.

However, if that non-zero exit code is not explicitly returned by the script, the script may return zero to its caller.

As a result, the caller of the script (such as a scheduler, parent script or automation tool) may incorrectly interpret a failed DataVeil run as successful.

This article explains how to ensure that Windows batch files, PowerShell scripts and Linux shell scripts correctly return the exit code produced by DataVeil.

When this matters

This matters when the DataVeil script is being checked externally.

For example, if an automation tool runs a .bat, .ps1, or .sh file and expects the script exit code to indicate success or failure, then the script must pass back the DataVeil exit code.

If all error handling is fully self-contained inside the script, and no outside process checks the script result, then this issue may not affect you if the exit code is saved or used immediately after DataVeil completes. However, it is still good practice to explicitly return the DataVeil exit code from the script correctly.

The recommended pattern

The recommended pattern is:

  1. Run DataVeil.
  2. Immediately save the DataVeil exit code.
  3. Display any messages or perform any related actions.
  4. Exit the script using the saved DataVeil exit code.

Step 2 is necessary if the script executes any further commands after DataVeil completes, because a subsequent command may replace the DataVeil exit code.

Step 4 is necessary if an external caller uses the script’s exit code to determine the result of the DataVeil run.

Windows batch files

In a Windows .bat file, the exit code from the previous command is available as %ERRORLEVEL%.

 

The recommended approach is to save it immediately after running DataVeil:

set "RC=%ERRORLEVEL%"

 

After displaying messages or performing any required cleanup, the batch file should finish with:

exit /b %RC%

For example:

java -Xms512m -Xmx4g ^
 "-Djava.library.path=drivers" ^
 -cp "DvWorker.jar;drivers\*" ^
 com.dataveil.dvworker.DvWorker ^
 --project="T:\DvWorker\projects\proj1.dvp"
 
set "RC=%ERRORLEVEL%"
 
if "%RC%"=="0" (
  echo DataVeil completed successfully. No warnings and no errors.
) else if "%RC%"=="1" (
  echo DataVeil completed OK but there were warnings. Check the DataVeil log.
) else if "%RC%"=="2" (
  echo DataVeil encountered errors or the start failed. Check the DataVeil log.
) else (
  echo Unexpected exit code = %RC%, probably a problem with the command or the environment.
)
 
exit /b %RC%

 

The final line is what returns the DataVeil completion code, saved immediately upon completion of DataVeil, to any external caller.

Without this, the batch file may return 0 to its caller even though DataVeil returned a non-zero exit code. This is because the batch file would report only its own successful completion rather than DataVeil’s actual exit code.

PowerShell scripts

In PowerShell, the exit code from an external program is available in $LASTEXITCODE. Save it immediately after running DataVeil and return it to any external caller as the last line of the script.

For example:

& java -Xms512m -Xmx4g `
 "-Djava.library.path=drivers" `
 -cp "DvWorker.jar;drivers\*" `
 com.dataveil.dvworker.DvWorker `
 --project="T:\DvWorker\projects\proj1.dvp"
 
$rc = $LASTEXITCODE
 
if ($rc -eq 0) {
  Write-Host "DataVeil completed successfully. No warnings and no errors."
} elseif ($rc -eq 1) {
  Write-Host "DataVeil completed OK but there were warnings. Check the DataVeil log."
} elseif ($rc -eq 2) {
  Write-Host "DataVeil encountered errors or the start failed. Check the DataVeil log."
} else {
  Write-Host "Unexpected exit code = $rc, probably a problem with the command or the environment."
}
 
exit $rc

 

Linux and Unix shell scripts

In Linux and Unix shell scripts, the exit code from the previous command is available in $?. Save it immediately after running DataVeil and return it to any external caller as the last line of the script.

For example:

java -Xms512m -Xmx4g \
 -cp "DvWorker.jar:drivers/*" \
 com.dataveil.dvworker.DvWorker \
 --project="/home/test/Documents/DataVeil/projects/kona.dvp"
 
rc=$?
 
if [ "$rc" -eq 0 ]; then
  echo "DataVeil completed successfully. No warnings and no errors."
elif [ "$rc" -eq 1 ]; then
  echo "DataVeil completed OK but there were warnings. Check the DataVeil log."
elif [ "$rc" -eq 2 ]; then
  echo "DataVeil encountered errors or the start failed. Check the DataVeil log."
else
  echo "Unexpected exit code = $rc, probably a problem with the command or the environment."
fi
 
exit "$rc"