Kommandozeilenbefehle: Übersicht • Variablen • ERRORLEVEL
Einige wichtige Befehle: dir • chkdsk • cd • md • rd • tree • del • attrib • if • xcopy • robocopy
Die Variable ERRORLEVEL
Jeder Programmierer kann beim Beenden seines Programms einen 8-Bit-Return-Code hinterlassen, deutsch „Beendigungscode“. Das Betriebssystem speichert diesen Code in einer Variable ERRORLEVEL, die von nachfolgenden Programmen ausgewertet werden kann. ERRORLEVEL = 0 bedeutet, dass bei der Befehlsausführung keine Fehler aufgetreten sind, jeder Wert ungleich Null signalisiert einen Fehler. Je höher der Wert, desto schwerer der Fehler. Welcher Befehl welche Fehlercodes melden kann, müssen Sie in Listen nachschlagen.
Auch eine Stapeldatei kann einen Return-Code hinterlassen: mit dem Befehl exit /b Returncode, wobei Returncode zwischen 0 und 255 liegen muss.
Folgende Befehle setzen ERRORLEVEL = 1, wenn ein Fehler aufgetreten ist: CD, CHDIR, COLOR, COPY, DATE, DEL, DIR, ERASE, MD, MKDIR, MOVE, RENAME, TIME, TYPE, VOL.
Folgende Befehle nutzen den ERRORLEVEL nicht und sie verändern den von einem vorangehend ausgeführten Befehl hinterlassenen ERRORLEVEL auch nicht. Zu diesen Befehlen gehören BREAK, COPY, DEL, ECHO, ENDLOCAL, FC, FOR, IF, PAUSE, RD, REM, RMDIR, TITLE.
Mit dem Befehl „IF“ kann die Variable ausgewertet werden. Ein Beispiel:
Der Befehl CD meldet ERRORLEVEL = 0, wenn zum gewünschten Ordner gewechselt werden konnte, sonst =1. Eine Befehlsfolge als Beispiel:
cd \users\klaus
if errorlevel 1 echo Den Ordner \users\klaus gibt es nicht!
if errorlevel 1 goto Abbruch
Falls es den Ordner \users\klaus nicht gibt, wird mit dem Echo-Befehl eine Fehlermeldung auf den Bildschirm ausgegeben und anschließend ein Sprungbefehl zur Sprungmarke „Abbruch“ ausgeführt.
Setzen Sie ERRORLEVEL nicht selbst! set ERRORLEVEL=1 ist nicht ratsam.
Den ERRORLEVEL abfragen
Wie funktioniert die Abfrage des ERRORLEVEL mit IF?
Mit dem Befehl
echo Errorlevel ist %ERRORLEVEL%
kann man sich den Wert von ERRORLEVEL anzeigen lassen.
IF ERRORLEVEL n
bedeutet: IF ERRORLEVEL >= n (größer oder gleich n)
Daraus folgt: Mit der Abfrage IF ERRORLEVEL 1 kann festgestellt werden, ob überhaupt ein Fehler aufgetreten ist, ohne daß alle anderen (möglicherweise gelieferten) Codes abgefragt werden müssen.
Daraus folgt auch: die Abfrage IF ERRORLEVEL 0 ist sinnlos, denn alle Fehlercodes sind >0 oder =0.
Will man einen ganz bestimmten Fehlercode abfragen, geht das so:
if errorlevel 5 if not error level 6 echo Errorlevel ist gleich 5
Will man mehrere Fehlercodes unterscheiden, ist eine Abfrage in absteigender Folge zu empfehlen.
Beispiel: Der Befehl RD kann die Fehlercodes 0, 1, 2, 5, 32 oder 145 liefern. Die Auswertung kann folgendermaßen erfolgen:
if errorlevel 145 echo Ordner ist nicht leer
if errorlevel 32 echo Ordner in Benutzung
if errorlevel 5 echo Zugriff verboten
if errorlevel 2 echo Ordner nicht gefunden
if errorlevel 1 echo Falscher Befehlsparameter
echo Ordner wurde gelöscht
Verknüpfungen von Anweisungen
A und B seien zwei Anweisungen.
| Code | Bedeutung | Beispiel |
|---|---|---|
| A | B | Führe erst A aus, dann B. Standardausgabe von A wird zur Eingabe von B. | dir c: | more |
| A & B | Führe erst A aus, dann B | |
| A && B | Führe A aus. Wenn kein Fehler, führe B aus. | copy text1.txt text2.txt && echo Kopieren erfolgreich! |
| A || B | Führe A aus. Nur wenn Fehler, führe B aus. | rd c:\temp || echo Ordner c:\temp kann nicht gelöscht werden |
Tabelle 1: Kommandos die ERRORLEVEL nicht verändern
| Kommando | Anmerkungen |
|---|---|
| BREAK | |
| ECHO | |
| ENDLOCAL | |
| FOR | Siehe "Exit Code" |
| IF | Siehe "Exit Code" |
| PAUSE | |
| RD, RMDIR | Bei einem Fehler wird nicht ERRORLEVEL geändert, sondern der "Exit Code". |
| REM | |
| SET | SET ohne Parameter lässt ERRORLEVEL unverändert. SET mit Parametern: Siehe Tabelle 3. |
| TITLE |
Tabelle 2: Kommandos die ERRORLEVEL =0 oder =1 setzen, abhängig vom Resultat
| Kommando | Set ERRORLEVEL = 0 wenn | Set ERRORLEVEL = 1 wenn |
|---|---|---|
| CD, CHDIR | Ordner wurde gewechselt | Ordner gibt es nicht oder Zugriff unmöglich |
| COLOR | Farbe wurde geändert | Vordergrund- und Hintergrundfarbe sind identisch |
| COPY | Dateien wurden kopiert | Datei nicht gefunden oder falsche Parameter angegeben |
| DATE | Datum wurde geändert oder kein Datum angegeben | Benutzer hat keine Admin-Rechte |
| DEL | immer = 0 außer: | Parameter fehlen oder sind fehlerhaft |
| DIR | wie COPY | |
| ERASE | wie DEL | |
| MD, MKDIR | Ordner wurde angelegt | Ordner wurde nicht angelegt |
| MOVE | Datei wurde umbenannt bzw. verschoben | Datei nicht gefunden, konnte nicht umbenannt bzw. verschoben werden oder falsche Parameter |
| PUSHD | wie CD | Ordner gibt es nicht oder Zugriff unmöglich oder falscher Parameter |
| REN, RENAME | wie MOVE | falsche Parameter angegeben |
| SETLOCAL | Neue Umgebung wurde erzeugt | Ordner gibt es nicht oder Zugriff unmöglich oder falscher Parameter |
| TIME | Zeit wurde geändert oder keine Zeit angegeben | Benutzer hat keine Admin-Rechte |
| TYPE | wie COPY | |
| VERIFY | OK oder keine Parameter angegeben | falsche Parameter |
| VOL | Das Volume-Label wurde angezeigt | Laufwerk nicht gefunden oder falsche Parameter angegeben |
Tabelle 3: Kommandos die ERRORLEVEL bei einem Fehler setzen, andernfalls den ERRORLEVEL nicht verändern
| Kommando | E | Set ERRORLEVEL auf = wenn |
|---|---|---|
| ASSOC | * | Die Zuordnung der Extension konnte nicht geändert werden. |
| CLS | Bad switch given. | |
| DPATH | * | 1 = Data path could not be established. |
| FTYPE | * | 1 = File type associations could not be changed. |
| GOTO Label | 1 = Label not exist *in a subroutine* (equivalent to: EXIT /B 1). | |
| KEYS | 1 = Bad switch given. | |
| PATH | * | 1 = Path could not be changed. |
| POPD | 1 = Bad switch given. | |
| PROMPT | * | 1 = Prompt could not be changed. |
| SET var | * | 1 = No variable with such name exists. |
| SET var=value | * | 1 = Variable name start with "/" not enclosed in quotes. |
| SET /P | * | 1 = Read an empty line or at end of file. |
| SET /A | * | 1073750988 = Unbalanced parentheses, 1073750989 = Missing operand, 1073750990 = Syntax error, 1073750991 = Invalid number, 1073750992 = Number larger than 32-bits, 1073750993 = Division by zero. |
| SHIFT | 1 = Bad switch given. |
Ein Stern in Spalte „E“ der Tabelle 3 zeigt diejenigen Befehle an, die ihr Verhalten entsprechend dem Status „Erweiterungen“ ändern. Wenn Erweiterungen aktiviert sind (was die Standardeinstellung ist) und diese Befehle in einer Datei mit der Erweiterung .CMD anstelle von .BAT gespeichert werden, setzen diese Befehle ERRORLEVEL = 0, wenn sie ohne Fehler enden, d. h. wenn die in Tabelle 3 beschriebenen Bedingungen nicht erfüllt sind.
Tabelle 4 - Spezialfälle
| Kommando | Set ERRORLEVEL |
|---|---|
| CALL Table1 | Wird einer der Befehle aus Tabelle 1 (außer FOR und IF) aufgerufen: set ERRORLEVEL = 0. |
| CALL subroutine | Wird die Subroutine aufgerufen, bleibt der ERRORLEVEL unverändert; andernfalls (Subroutine existiert nicht): set ERRORLEVEL = 1. |
| EXIT /B, EXIT | Der vorhandene ERRORLEVEL bleibt unverändert. |
| EXIT /B Nummer | Setzt ERRORLEVEL gleich der angegebenen Nummer. |
| EXIT Nummer | Setzt ERRORLEVEL gleich der angegebenen Nummer. |
| START command | Wenn command startet, bleibt ERRORLEVEL unverändert; andernfalls set ERRORLEVEL = 9059. |
| START /WAIT test.bat | Wenn die gestartete Batch endet, set ERRORLEVEL = value vom 'EXIT number' commmand. |
| notExist | Beim Versuch, ein nicht-existierendes Kommando auszuführen, set ERRORLEVEL = 9009. |
| VER | Set ERRORLEVEL = 0. Jedoch die Abfrage VER /? verändert ERRORLEVEL nicht. |
Exit Code
Einige Programme hinterlassen einen Exit Code (Rückgabe-Code), aber keinen ERRORLEVEL.
Bestimmte Befehle und Umleitungsfehler lassen ERRORLEVEL unverändert, geben aber auf andere Weise geben einen Wert zurück, den wir „Exit Code“ nennen wollen. Wenn dieser Exit-Code nicht null ist, kann er mit einem Trick an das ERRORLEVEL weitergegeben werden, indem irgendein Befehl von Tabelle 1 ausgeführt wird. Weitere Einzelheiten zu diesem Thema können Sie im folgenden nachlesen.
Tabelle 5 - Befehle oder Merkmale die den Exit-Code setzen
Feature │ Setze Exit Code auf = wenn
─────────────┼─────────────────────────────────────────────────────────────────────────
command │1 = Befehl existiert nicht (wenn ERRORLEVEL = 9009).
redirection │1 = Datei existiert nicht in "<", Pfad existiert nicht oder Zugriff verboten in ">" ">>".
drive: |1 = Laufwerk existiert nicht.
POPD |1 = Vorher wurde kein PUSHD ausgeführt.
RD │1 = Falscher Parameter, 2 = Ordner nicht gefunden, 5 = Zugriff verboten,
│32 = Ordner in Benutzung, 145 = Ordner ist nicht leer.
FOR /F │1 = Es wurden keine Daten durchsucht.
Beispiel: Testen, ob eine Weiterleitung funktioniert hat
Bei manchen Befehlen ist es wünschenswert, eine Protokolldatei zu erzeugen.
xcopy c:\*.* e:\*.* /s > C:\Dieser_Pfad_existiert_nicht\Protokoll.txt || rem
if errorlevel 1 echo Umleitung ist fehlgeschlagen (weil es den Pfad „C:\Dieser_Pfad_existiert_nicht“ nicht gibt)
In diesem Beispiel wird das rem Kommando benutzt, um den Exit-Code von RD in die Variable ERRORLEVEL zu kopieren.
Anstelle von rem sind auch andere interne Kommandos geeignet, welche den ERRORLEVEL nicht verändern (außer FOR und IF)
Beispiel: Testen, ob es ein Laufwerk gibt
U: || rem
if errorlevel 1 echo Der Wechsel zu Laufwerk U: ist fehlgeschlagen
In diesem Beispiel wird das rem Kommando benutzt, um den Exit-Code des Laufwerkwechsels in die Variable ERRORLEVEL zu kopieren.
Anstelle von rem sind auch andere interne Kommandos geeignet, welche den ERRORLEVEL nicht verändern (außer FOR und IF)
Beispiel: Auswertung des Befehls rd
Der Befehl rd kann die folgenden Exit-Codes zurückmelden:
1 = Bad switch given, 2 = Directory not found, 5 = Access denied, 32 = Directory in use, 145 = Directory not empty.
rd c:\Some\directory 2> NUL || rem
if %errorlevel% equ 0 (
echo Directory deleted
) else if %errorlevel% equ 2 (
echo Directory not found
) else if %errorlevel% equ 5 (
echo Can not access the directory, check rights
) else if %errorlevel% equ 32 (
echo Can not delete current directory
) else if %errorlevel% equ 145 (
echo Directory is not empty, use /S switch
)