Testing for Success

Whenever you use a script to change computer or user settings, the script should report on the change operation's success or failure. Three common tests that determine whether a command performed successfully are the ERRORLEVEL test, the string-search test, and the follow-up query test.

ERRORLEVEL test. Many tools and utilities use the ERRORLEVEL environment variable to return a number (0 or 1) that indicates whether a command performed successfully (0) or failed (1). The following sample code executes the Copy command, then uses an If command to test for the ERRORLEVEL value to determine whether the file was successfully copied:

Copy C:testfile.txt  C:testfile2.txtIf ERRORLEVEL 0  If not ERRORLEVEL 1  Echo File copy success   & Goto :lastEcho File copy failure:last

A simpler way to display the success or failure of an attempted operation based on the ERRORLEVEL value is to use double ampersand (&&) symbols or double pipe (||) symbols. The following sample copy operation uses && symbols to determine whether the Copy command succeeded:

Copy C:testfile.txt  C:testfile2.txt && Echo  File copy success &  Goto :lastEcho File copy failure:last

To determine whether the Copy command failed, use || symbols:

Copy C:testfile.txt  C:testfile2.txt || Echo  File copy failed &  Goto :lastEcho File copy success:last

One downside of using the ERRORLEVEL test is that it doesn't work with some commands. For example, consider the following code:

Ping Server1 && Echo Server1  ping success & Goto :lastEcho Server1 ping failure:last

If Server1 is an invalid server name, the command returns a correct failure message. However, if Server1 is a valid server name but Server1 is offline, the Ping command returns a misleading success message; that is, the Ping command "succeeded" although the node was offline.

String-search test. A second way to test for a command's success is to embed the command inside a For command, capture the output of the embedded command (in this example, the Ping command), and use the Find command to search the output for a success message. The following example looks for the string Reply to determine whether the Ping command succeeded:

For /F "tokens=1" %%i in  ('Ping -n 1 Server1^ | Find  "Reply"') Do Echo Server1  is on & Goto :lastEcho Server1 is off:last

Follow-up query test. A third way to test for the success or failure of a command operation is to run the command (in this case, run TScmd to modify the Terminal Services settings), then immediately test for the set value. WTSSetUserInfo uses the follow-up query method for three reasons. First, the TScmd tool doesn't work correctly with the ERRORLEVEL method. Second, although the search-string test works with the TScmd tool, it doesn't return the exact setting values that you need for WTSSetUserInfo.bat. Remember that at the end of the change operation you need to have the before and after settings in the spreadsheet. Third, the follow-up query method fits the strategy of capturing the settings before and after the script changes them. The before-and-after technique puts all the data in one spreadsheet so that you can easily verify that the settings are correct and identify problems such as incorrect server paths or failed changes.