Setlocal - DOS/Command Prompt Reference
[Windows NT/2000/XP and later] Keeps the environment variable settings and the current directory only in batch files (localization of environment changes).
Syntax
setlocal [enableextensions | disableextensions] [enabledelayedexpansion | disabledelayedexpansion]
Options
| enableextensions | disableextensions | If you specify either, enables or disables Command Extensions until next call of Endlocal. ‘enableextensions’ will enable, and ‘disableextensions’ will disable. ‘enableextensions’ can be used even if the Extensions is disabled by Cmd parameter. |
| enabledelayedexpansion | disabledelayedexpansion | [Windows 2000 and later] If you specify either, enables or disables delayed environment variable expansion until next call of Endlocal. ‘enabledelayedexpansion’ will enable, and ‘disabledelayedexpansion’ will disable. For more information, please see the description of ‘!’. |
| (No parameters specified) | If you don't specify above parameters, only begins localization of environment changes. (Localization is also performed when the parameter is specified.) |
You can specify both of ‘either enableextensions or disableextensions’ and ‘either enabledelayedexpansion or disabledelayedexpansion’. For example the syntax ‘setlocal disableextensions enabledelayedexpansion’ is valid and it applies the effects of ‘disableextensions’ and ‘enabledelayedexpansion’ in addition to the effect of ‘setlocal’ (localization).
Details
Setlocal is used to define environment variables or change the current directory, both of which are valid until Endlocal command is called (i.e. localization). By calling Setlocal, changing environment variables by Set or changing the current directory by Chdir/Pushd will be restored to the previous state by Endlocal. (However the state changed by Pushd will not be restored strictly. For details please see Pushd page.)
If Endlocal does not exist, the localization of those state is valid during the batch program execution. When the batch program exits, the state is restored as if Endlocal is called.
You can call Setlocal multiple times, and each of calls perform localization. To end localization, you must call Endlocal a corresponding number of times. (i.e. nesting of localization)
By specifying parameters to Setlocal, you can enable or disable Command Extensions or delayed environment variable expansion temporarily. These changes will be restored by calling Endlocal. Also, the localization is performed even if Setlocal gives parameters, and Endlocal restores those state as well as ending localization.
* You can call ‘setlocal enabledelayedexpansion’ in Extensions-disabled command prompt environment without calling ‘setlocal enableextensions’.
Setlocal returns an exit code (Errorlevel). It returns 0 for successful, and 1 for failure such as invalid parameters. (It returns an exit code regardless of Extensions-enabled or existence of parameters.) However older Windows may not return an exit code, so if you need to consider older Windows, you must treat exit codes carefully. (see Samples.)
Samples
Sample 1 (Batch file)
setlocal set PATH=N:\bin;%PATH% hoge.exe endlocal foo.exe
After entering localization of environment changes, adds ‘N:\bin’ to PATH, and executes ‘hoge.exe’. Then restores environment changes by calling Endlocal and executes ‘foo.exe’. In this case, PATH contains ‘N:\bin’ during executing ‘hoge.exe’, while PATH does not contain ‘N:\bin’ during ‘foo.exe’.
Sample 2 (Batch file)
setlocal enableextensions cd /d "%~dp0" execute.exe
Enables Command Extensions as well as performing localization, changes the current directory to the directory containing the batch file, and executes ‘execute.exe’. As a result, ‘execute.exe’ will be executed with the directory containing the batch file as the current directory, and the current directory will be restored when the batch program exits. Enabling Command Extensions by calling Setlocal with parameter ‘enableextensions’ is necessary for Extensions-disabled environment because the syntaxes ‘cd /d’ and ‘%~dp0’ are Extension syntaxes.
Please see following sample for determining whether Extensions can be enabled.
Sample 3 (Batch file)
find "invalid" 9:\invalid 2> NUL setlocal enableextensions if errorlevel 1 goto no_extensions bar.exe if "%ERRORLEVEL%"=="0" echo Succeeded. else echo Failed. goto last :no_extensions echo Cannot run this program. :last
Executes ‘bar.exe’ with Extensions enabled, and checks bar.exe's exit code. Extensions feature is required to use Errorlevel as an environment variable, so calling Setlocal is necessary for an evaluation with %ERRORLEVEL%.
In the first three lines sets Errorlevel to non-zero value by calling Find with invalid parameter deliberately, and then calls Setlocal. By doing this, (using the fact that Errorlevel is not changed on the environment which Setlocal parameters cannot be used, whereas the Errorlevel will be 0 if the parameter is available and the command succeeds,) you can detect whether to enable Extensions correctly.