10 Keys to Command Shell Scripting

Shell scripts are plain-text files that a command shell interprets as a series of commands to be executed in sequence. Shell scripts have a long history: The Command.com shell in MSDOS has supported simple batch-file scripting since the early 1980s. Released with Windows NT in 1993, the text-based Cmd.exe command shell supports a script language similar to the batch language in Command.com. Despite its age, Cmd.exe shell scripting is still a useful tool in the IT professional's arsenal. For example, a simple shell script with a For command can transform a command that works with only one computer or username at a time on the command line into a command that can step through a text file and execute the command for each line in the file. Because shell scripts are plain-text files that contain a series of commands, they are easy to create, modify, and understand. However, these scripts' simplicity can also be a liability. A carelessly written shell script can cause potentially serious problems. I've seen shell scripts that make incorrect assumptions about the underlying OS or environment that, at best, prevent them from working correctly, or at worst, wreak havoc on an unsuspecting system. To help you avoid such problems, I've written the following set of 10 guidelines for creating more robust scripts that can work correctly in various environments.

1. Use Environment Variables When Possible
When you use a variable in a script, you enclose the variable's name between percent signs (%), and when the shell script runs, the percent signs and the text between them will be replaced with the variable's data. Using variables makes the script's code more generic—it has a better chance of running successfully on different computers. For example, you should never "hard-code" the Windows installation directory name in a shell script. Instead, you should use the SystemRoot variable, which will always point to theWindows installation directory. So, the command

Echo %SystemRoot% 

will display the contents of SystemRoot (i.e., the Windows installation directory).

In several cases, I've seen shell scripts that used C:WINDOWS to refer to the Windows installation directory. If Windows isn't installed in C:WINDOWS (e.g.,Windows 2000 and earlier are installed in WINNT), the script won't work properly. Environment variables make life easier for programmers and script writers.

To see a list of environment variables, type the Set command at a command prompt. Some variables don't appear in the list generated by the Set command because they're dynamically generated by Cmd.exe. Table 1 shows a list of these variables. As with other environment variables, enclose these variables between percent signs. For example, the following line in a script will display the current date and time:

Echo %DATE% %TIME% 

2. Don't Expect Legacy Command.com Batch Files to Work in Cmd.exe
If you're accustomed to writing batch files for the MS-DOS or Windows 9x/Me platforms, be aware that some batch-file commands you're used to don't exist in the newest versions of Windows. The Choice and Deltree commands are the two most common examples. Review your old batch files to make sure they work correctly in a Cmd.exe window. Table 2 shows some suggested replacements for Choice and Deltree. Most of these replacements have a different-syntax than the commands they're replacing, so you'll need to modify your scripts accordingly.

3. Use the .cmd Extension for Cmd.exe Shell Scripts
Command.com batch files require the .bat file extension. Cmd.exe can also use the .bat extension, but in Cmd.exe's more powerful scripting language, many commands aren't compatible with Command.com. Thus, a .bat file that you design to work with Cmd.exe might fail if a user tries to execute it in Command.com (e.g., in Windows 98). One way to avoid this potential problem is to use .cmd as a shell script extension. Because Command.com doesn't recognize the .cmd extension, it simply won't execute a batch file if the filename ends with .cmd.

4. Make Sure the Executables You Want Are Available
If your script relies on programs that aren't a part of the standard OS installation, you must make sure that any such programs are available. You should also document these dependencies in your scripts. One way to ensure executables are available is to put them in the same directory as the script. Then you can run them by using the syntax

"%  ~dp0exename"   ... 

where exename is the name of the executable you want to run. The %~dp0 syntax returns the drive, path, and filename of the current script without quotes. Enclosing the entire string in quotes ensures that the script will still work even if the filename or the directory the script is in contains quotes.

5. Use Double Quotes Correctly
Double quotes (") seem to be a common source of confusion for shell-script writers. Quotes are simply a way of identifying command-line arguments that contain spaces. For example, although it might look correct, the command line

dir C:Program Files 

gives the Dir command two arguments: C:Program and Files. To indicate that you intend C:Program Files to be a single argument (including the space), enclose it in double quotes:

dir "C:Program Files" 

The quotation marks aren't part of the directory name. They tell the Dir command that the text between them is one argument.

Shell scripts also support command-line arguments. To access a script's command-line arguments, use the notation %n (where n is a number 0 through 9). This notation is called a replaceable parameter (or simply a parameter). For example, the script will replace the %1 parameter with the first command-line argument, %2 with the second argument, and so forth. In addition to %1 through %9, %0 is replaced with the script's name, and %* is replaced with the script's entire command line (not including the script name). I mention command-line arguments here because when Cmd.exe replaces the %1 through %9 parameters with the corresponding command-line arguments, it leaves the double quotes if they're in the argument. This fact leads to a simple observation: A script parameter will always be contained in double quotes if it contains spaces. The following simple rules are based on this observation, and if you follow them carefully, you'll virtually eliminate quoting problems from your shell scripts.

If {%1}=={} Goto :HELP 

The exception to this rule is when you use the syntax %~n to remove a parameter's quotes (which I explain in the next rule).

Set DATAFILE=%  ~1 

will copy the script's first parameter ( without quotes) into the variable DATAFILE. The exception to this rule is if you're creating quoted text that will be passed to another command.

Set TARGET=% ~2Copy %1 "%TARGET%" 

The first of these lines copies the script's second argument into the TARGET variable, removing the quotes. The second line is syntactically valid because the %1 parameter is already enclosed in quotes if it contains spaces, and the TARGET variable needs quotes because it might contain spaces.

6. Use the Setlocal and Endlocal Commands
The Setlocal command copies all environment variables, and Endlocal restores all variables to the values they had before the script started. Endlocal also deletes any variables the script created. Using both these commands makes a script more self-contained and ensures that a script "cleans up after itself" by restoring environment variables to their original values and deleting variables the script created.

Also, you can use the Setlocal Enableextensions command to make sure that command extensions are enabled. Command extensions are enhancements to a group of Cmd.exe internal commands (e.g., If, For, Call) that provide expanded capabilities beyond the Command.com commands that have the same names. Command extensions are enabled by default, but in the rare cases in which command extensions are disabled, the Setlocal Enableextensions command ensures that command extensions are enabled. To see more information about command extensions, type Cmd /? at a command prompt.

7. Use the Escape Character When Needed
Cmd.exe uses the caret (^) as an escape character that bypasses the normal meanings of reserved shell characters. For example, the ampersand (&) is the command separator—it lets you put multiple commands on one line. If you intend to use the & literally, you must "escape" its normal meaning by prefacing it with the ^. So in the line

Echo The ^& character is the command separator

the ^ causes the shell to bypass the normal interpretation of the character that follows. You need to escape the characters ( ) < > ^ & and |. You don't need to escape these characters if they occur inside a quoted string.

8. Don't Use the Exit Command Without the /b Option
Without the /b option, the Exit command closes the current shell. If someone starts a Cmd.exe session and executes a script that contains the Exit command, the current shell will abruptly close. The Exit /b command closes the current script without terminating the current shell. For more information about the Exit command, type the command Exit /? at a command prompt.

9. Watch Out for If Errorlevel
The If Errorlevel command tests the exit code of the last command that was executed. Scripts can test a program's exit code and behave accordingly. For example, consider the following script code:

MyprogramIf Errorlevel 1 Goto :ERROR 

In these lines, the Goto command will execute if Myprogram.exe returns an exit code greater than or equal to 1. In other words, "If Errorlevel n" doesn't mean "if the last exit code is exactly n;" it really means, "if the last exit code is at least n." Because of this behavior, make sure to test exit codes in descending order (highest to lowest). To test for a specific exit code, use the ERRORLEVEL dynamic variable instead of If Errorlevel. Note that the If Errorlevel command is different from the ERRORLEVEL variable listed in Table 1. The If Errorlevel command is backward compatible with Command.com's If Errorlevel command; the ERRORLEVEL variable is only available in Cmd.exe.

10. Be Aware of Start's Quirks
The Start command starts a program or a command in a new console window. However, if you try to start a program from a directory that contains spaces (or if the program's name contains spaces), the Start command won't behave as you might expect. For example, the following command

Start "C:Program FilesMicrosoft   OfficeOffice11Winword.exe" 

doesn't start Microsoft Word, as you might expect. Instead, the Start command will open a new Cmd.exe session with the quoted string as the title of the console window. This behavior occurs because the Start command uses the first quoted string on its command line as a console window title.

To work around this quirk, use a pair of quotes to specify a blank title, then follow the title with the program you want to run. The corrected Start command will look like this:

Start "" "C:Program FilesMicrosoft   OfficeOffice11Winword.exe" 

Avoid Potential Problems
Cmd.exe shell scripts are widely used. With these guidelines under your belt, you can write more robust shell scripts and avoid common problems.