Command shell overview

Command shell overview

The command shell is a separate software program that provides direct communication between the user and the operating system. The non-graphical command shell user interface provides the environment in which you run character-based applications and utilities. The command shell executes programs and displays their output on the screen by using individual characters similar to the MS-DOS command interpreter Command.com. The Windows XP command shell uses the command interpreter Cmd.exe, which loads applications and directs the flow of information between applications, to translate user input into a form that the operating system understands.

You can use the command shell to create and edit batch files (also called scripts) to automate routine tasks. For example, you can use scripts to automate the management of user accounts or nightly backups. You can also use the Windows Script Host, CScript.exe, to run more sophisticated scripts in the command shell. You can perform operations more efficiently by using batch files than you can by using the user interface. Batch files accept all commands that are available at the command line. For more information about batch files and scripting, see Using batch files.

Using batch files

With batch files, which are also called batch programs or scripts, you can simplify routine or repetitive tasks. A batch file is an unformatted text file that contains one or more commands and has a .bat or .cmd file name extension. When you type the file name at the command prompt, Cmd.exe runs the commands sequentially as they appear in the file.

You can include any command in a batch file. Certain commands, such as for, goto, and if, enable you to do conditional processing of the commands in the batch file. For example, the if command carries out a command based on the results of a condition. Other commands allow you to control input and output and call other batch files.

The standard error codes that most applications return are 0 if no error occurred and 1 (or higher value) if an error occurred. Please refer to your application help documentation to determine the meaning of specific error codes.

For more information about batch file operations, see the following topics:

• Using batch parameters
• Using filters
• Using command redirection operators

For more information about commands that you can use in batch files, click a command:

• Call
• Echo
• Endlocal
• For
• Goto
• If
• Pause
• Rem
• Setlocal
• Shift

You can customize the command prompt window for easier viewing and to increase control over how you run programs. For more information about customizing the command prompt window, see To configure the command prompt.

Using command syntax

Syntax appears in the order in which you must type a command and any parameters that follow it. The following example of the xcopy command illustrates a variety of syntax text formats:

xcopy Source [Destination] [/w] [/p] [/c] [/v] [/q] [/f] [/l] [/g] [/d[:mm-dd-yyyy]] [/u] [/i] [/s [/e]] [/t] [/k] [/r] [/h] [{/a|/m}] [/n] [/o] [/x] [/exclude:file1[+[file2]][+[file3]] [{/y|/-y}] [/z]

The following table explains how to interpret the different text formats.

Formatting legend

Format	Meaning
Italic	Information that the user must supply
Bold	Elements that the user must type exactly as shown
Ellipsis (...)	Parameter that can be repeated several times in a command line
Between brackets ([])	Optional items
Between braces ({}); choices separated by pipe (|). Example: {even|odd}	Set of choices from which the user must choose only one
Courier font	Code or program output

Using multiple commands and conditional processing symbols

You can run multiple commands from a single command line or script using conditional processing symbols. When you run multiple commands with conditional processing symbols, the commands to the right of the conditional processing symbol act based upon the results of the command to the left of the conditional processing symbol. For example, you might want to run a command only if the previous command fails. Or, you might want to run a command only if the previous command is successful.

You can use the special characters listed in the following table to pass multiple commands.

Character	Syntax	Definition
& [...]	command1 & command2	Use to separate multiple commands on one command line. Cmd.exe runs the first command, and then the second command.
&& [...]	command1 && command2	Use to run the command following && only if the command preceding the symbol is successful. Cmd.exe runs the first command, and then runs the second command only if the first command completed successfully.
|| [...]	command1 || command2	Use to run the command following || only if the command preceding || fails. Cmd.exe runs the first command, and then runs the second command only if the first command did not complete successfully (receives an error code greater than zero).
( ) [...]	(command1 & command2)	Use to group or nest multiple commands.
; or ,	command1 parameter1;parameter2	Use to separate command parameters.

Notes

• The ampersand (&), pipe (|), and parentheses ( ) are special characters that must be preceded by the escape character (^) or quotation marks when you pass them as arguments.
• If a command completes an operation successfully, it returns an exit code of zero (0) or no exit code. For more information about exit codes.

Nesting command shells

You can nest command shells within Cmd.exe by opening a new instance of Cmd.exe at the command prompt. By default, each instance of Cmd.exe inherits the environment of its parent Cmd.exe application. By nesting instances of Cmd.exe, you can make changes to the local environment without affecting the parent application of Cmd.exe. This allows you to preserve the original environment of Cmd.exe and return to it after you terminate the nested command shell. The changes you make in the nested command shell are not saved.

To nest a command shell, at the command prompt, type:

cmd

A message similar to the following appears:

Microsoft (R) Windows XP (TM)
(C) Copyright 1985-2001 Microsoft Corp.

To close the nested command shell, type exit.

You can localize changes even further in an instance of Cmd.exe (or in a script) by using the setlocal and endlocal commands. Setlocal creates a local scope and endlocal terminates the local scope. Any changes made within the setlocal and endlocal scope are discarded, thereby leaving the original environment unchanged. You can nest these two commands to a maximum of 32 levels. For more information about the setlocal and endlocal commands, see Setlocal and Endlocal.

Using environment variables with Cmd.exe

The Cmd.exe command-shell environment is defined by variables that determine the behavior of the command shell and the operating system. You can define the behavior of the command-shell environment or the entire operating system environment by using two types of environment variables, system and local. System environment variables define the behavior of the global operating system environment. Local environment variables define the behavior of the environment of the current instance of Cmd.exe.

System environment variables are preset in the operating system and available to all Windows XP processes. Only users with administrative privileges can change system variables. These variables are most commonly used in logon scripts.

Local environment variables are only available when the user for whom they were created is logged on to the computer. Local variables set in the HKEY_CURRENT_USER hive are valid only for the current user, but define the behavior of the global operating system environment.

The following list describes the various types of variables in descending order of precedence:

1. Built-in system variables
2. System variables found in the HKEY_LOCAL_MACHINE hive
3. Local variables found in the HKEY_CURRENT_USER hive
4. All environment variables and paths set in the Autoexec.bat file
5. All environment variables and paths set in a logon script (if present)
6. Variables used interactively in a script or batch file

In the command shell, each instance of Cmd.exe inherits the environment of its parent application. Therefore, you can change the variables in the new Cmd.exe environment without affecting the environment of the parent application.

The following table lists the system and local environment variables for Windows XP.

Variable	Type	Description
%ALLUSERSPROFILE%	Local	Returns the location of the All Users Profile.
%APPDATA%	Local	Returns the location where applications store data by default.
%CD%	Local	Returns the current directory string.
%CMDCMDLINE%	Local	Returns the exact command line used to start the current Cmd.exe.
%CMDEXTVERSION%	System	Returns the version number of the current Command Processor Extensions.
%COMPUTERNAME%	System	Returns the name of the computer.
%COMSPEC%	System	Returns the exact path to the command shell executable.
%DATE%	System	Returns the current date. Uses the same format as the date /t command. Generated by Cmd.exe. For more information about the date command, see Date.
%ERRORLEVEL%	System	Returns the error code of the most recently used command. A non zero value usually indicates an error.
%HOMEDRIVE%	System	Returns which local workstation drive letter is connected to the user's home directory. Set based on the value of the home directory. The user's home directory is specified in Local Users and Groups.
%HOMEPATH%	System	Returns the full path of the user's home directory. Set based on the value of the home directory. The user's home directory is specified in Local Users and Groups.
%HOMESHARE%	System	Returns the network path to the user's shared home directory. Set based on the value of the home directory. The user's home directory is specified in Local Users and Groups.
%LOGONSEVER%	Local	Returns the name of the domain controller that validated the current logon session.
%NUMBER_OF_PROCESSORS%	System	Specifies the number of processors installed on the computer.
%OS%	System	Returns the operating system name. Windows 2000 displays the operating system as Windows_NT.
%PATH%	System	Specifies the search path for executable files.
%PATHEXT%	System	Returns a list of the file extensions that the operating system considers to be executable.
%PROCESSOR_ARCHITECTURE%	System	Returns the chip architecture of the processor. Values: x86, IA64.
%PROCESSOR_IDENTFIER%	System	Returns a description of the processor.
%PROCESSOR_LEVEL%	System	Returns the model number of the processor installed on the computer.
%PROCESSOR_REVISION%	System	Returns the revision number of the processor.
%PROMPT%	Local	Returns the command prompt settings for the current interpreter. Generated by Cmd.exe.
%RANDOM%	System	Returns a random decimal number between 0 and 32767. Generated by Cmd.exe.
%SYSTEMDRIVE%	System	Returns the drive containing the Windows XP root directory (that is, the system root).
%SYSTEMROOT%	System	Returns the location of the Windows XP root directory.
%TEMP% and %TMP%	System and User	Returns the default temporary directories that are used by applications available to users who are currently logged on. Some applications require TEMP and others require TMP.
%TIME%	System	Returns the current time. Uses the same format as the time /t command. Generated by Cmd.exe. For more information about the time command, see Time.
%USERDOMAIN%	Local	Returns the name of the domain that contains the user's account.
%USERNAME%	Local	Returns the name of the user who is currently logged on.
%USERPROFILE%	Local	Returns the location of the profile for the current user.
%WINDIR%	System	Returns the location of the operating system directory.

Setting environment variables

Use the set command to create, change, delete, or display environment variables. The set command alters variables in the current shell environment only.

To view a variable, at a command prompt, type:

set VariableName

To add a variable, at a command prompt, type:

set variablename=value

To delete a variable, at a command prompt, type:

set VariableName=

You can use most characters as variable values, including white space. If you use the special characters <, >, |, &, or ^, you must precede them with the escape character (^) or quotation marks. If you use quotation marks, they are included as part of the value because everything following the equal sign is taken as the value. Consider the following examples:

• To create the variable value new&name, type:

set varname=new^&name

• To create the variable value "new&name", type:

set varname="new&name"

• If you type set varname=new&name at the command prompt, an error message similar to the following appears:

"'name' is not recognized as an internal or external command, operable program or batch file."

Variable names are not case-sensitive. However, set displays the variable exactly as you typed it. You can combine uppercase and lowercase letters in your variable names to make your code more readable (for example, UserName).

Notes

• The maximum individual environment variable size is 8192bytes.
• The maximum total environment variable size for all variables, which includes variable names and the equal sign, is 65,536KB.

Substituting environment variable values

To enable the substitution of variable values at the command line or in scripts, enclose the variable name in percent signs (that is, %variablename%). By using percent signs, you ensure that Cmd.exe references the variable values instead of making a literal comparison. After you define variable values for a variable name, enclose the variable name in percent signs. Cmd.exe searches for all instances of the variable name and replaces it with the defined variable value. For example, if you create a script that contains different values (for example, user names) and you want to define the USERNAME environment variable for each user with these values, you can write one script using the variable USERNAME enclosed in percent signs. When you run this script, Cmd.exe replaces %USERNAME% with the variable values, which eliminates the need to perform this task manually for each user. Variable substitution is not recursive. Cmd.exe checks variables once. For more information about variable substitution.