=== BatchDebug.exe === ist ein Tool zum Debuggen von Batch-Dateien für den Kommando-Interpreter "cmd.exe" unter Windows. === Übersicht === - kontrollierte Ausführung zeilenweise oder bis BreakPoint - bedingte BreakPoints mit IF-Abfragen in Batch-Syntax - Anzeige aller und Variablen - Setzen von Variablen zur Laufzeit - Ausführung zusätzlicher Anweisungen zur Laufzeit - Unterbrechung bei nicht explizit erlaubten ErrorLevel-Änderungen oder Ausgaben auf StdErr - Anzeige des System-Hilfe-Textes zu Batch-Kommandos (kontext-sensitiv) === (Quick-)Start === - Laden eines Batch durch "File open" oder Drag-and-Drop - Setzen der Start-Umgebung im ->Settings-Menü und/oder im ->Settings-Dialog (F10) - Ausführen: zeilenweise mit F8, ganz mit F9, bis Cursor mit F4 - Breakpoint setzen mit F5, Eigenschaften mit Ctrl-F5 - Reset mit Ctrl-F2 === Hinweise === - Der für Kommentare gern genutzte "::" kann in JEDEM Batch merkwürdige Fehler erzeugen, insbesondere innerhalb von Klammern. Solche Fehler werden im für den Debugger instrumentierten Batch noch wahrscheinlicher. Bei unerwarteten Syntaxfehlern dies bitte überprüfen und ggf "::" durch "REM" ersetzen (Automatismus in ->Settings einschaltbar) - BatchDebug arbeitet zeilenorientiert. Enthält eine Zeile mehrere ErrorLevel-Fehler, so wird nur der letzte gemeldet. Produziert eine Zeile mehrere StdErr-Ausgaben, so werden sie als EIN Fehler-Text gemeldet. === Noch nicht realisiert === - Aufruf des Testobjektes von einem anderen Batch oder exe ("Master") - Syntax-Highlighting === Unbedingte Voraussetzungen === - Die Ausführung im Debugger erfolgt mit "enabledelayedexpansion" und "enableextensions". Diese Schalter dürfen vom Testobjekt nicht ausgeschaltet werden. - Die System-Variable "ErrorLevel" darf vom Testobjekt nicht per SET-Anweisung beschrieben werden - Parameter mit einer schliessenden runden Klammer müssen in Anführungszeichen übergeben werden - Im SourceCode explizit enthaltene Dateinamen dürfen keine runden Klammern enthalten === Weitere Voraussetzungen === - Variablen sollten keine Schlüsselwörter als Inhalt haben, z.B. SET Var=REM - Das Testobjekt sollte keinen selbst-modifizierenden Code enthalten: - insbesondere in Anweisungen FOR,SHIFT,CALL,GOTO,Klammern,SETLOCAL,ENDLOCAL - und innerhalb des FOR-tokens: Es wird dann nur eine Laufvariable angelegt === Grenzen === - nach SHIFT werden maximal 9 Parameter angezeigt === Abweichungen === - Unter "ECHO ON" kann die Anzeige der Befehle vom Betrieb ohne Debugger abweichen: - "CALL", "GOTO" und "FOR" werden nicht angezeigt - zusätzliche "&"-Zeichen - zusätzliche Leerzeilen und "(...)" - fehlende Befehle hinter "&", "||" ... - von mehrzeiligen Fehlermeldungen wird im Cmd-Fenster nur die letzte Zeile angezeigt - %~d0 und %~p0 enthalten (in der Regel) nicht den korrekten Wert, siehe ->%0-Problem - in Breakpoint-Bedingungen: - %* enthält nicht die korrekten Werte (einen zusätzlichen Wert als ersten) - in Zusatz-Aktionen: - CALL-intern, GOTO, SHIFT nicht sinnvoll ausführbar - in BreakPoint-Bedingungen und Zusatz-Aktionen: kann nur auf den aktuellen Wert von x (also !x!) zugegriffen werden, nicht auf %x%. Beide Schreibweisen sind aber erlaubt. - nicht-paarige SETLOCAL/ENDLOCAL-Befehle erzeugen eine StdErr-Fehlermeldung === Bekannte Probleme === - vorübergehendes Nicht-reagieren auf Click in Navigations-Leiste === Tips === - da die Extensions "bat" und "cmd" mit dem Befehlsinterpreter verknüpft sind kann BatchDebug nicht per DoppelClick auf ein Batch gestartet werden. In der Entwicklungsphase kann aber eine andere Extension (z.B. "cmdebug") vergeben und mit BatchDebug verknüpft werden. === Beschreibung aller Funktionen === --- Edit --- 1. Text-Änderungen müssen über einen externen Editor vorgenommen werden, Aufruf per F3. Dazu muss ein Editor von Hand in die BatchDebug.ini eingetragen werden, z.B. die Zeile Editor="c:\Programme\ultraedit\UEDIT32.EXE" %n -l%z Der geänderte Quelltext wird automatisch geladen, Zeilen-Eigenschaften möglichst erhalten. 2. Per "Ignore Line" können einzelne Zeilen komplett von der Ausführung ausgenommen werden 3. Per "No Debug Line" können einzelne Zeilen vom Debugging ausgenommen werden, sie werden ausgeführt aber nicht für BreakPoints instrumentiert. Notwenig evtl für mehrzeilige Blöcke mit Filter, z.B. "(Line1 NewLine Line2) | more" 4. Per "Echo Line" kann lokal für eine einzelne Zeile das Echo eingeschaltet werden --- Navigation im Quelltext --- 1. Am rechten Rand befindet sich die Navigations-Liste. Sie enthält - alle Label - alle for-Schleifen - manuell hinzugefügten Textzeilen (über Source-Kontextmenü) - Zeilen, die den per ->.Ini-Datei definierten SuchString enthalten 2. Während der Ausführung wechselt die Anzeige zum ->LogFile --- %0-Problem --- Quelltext wird für die Kommunikation mit dem Debugger instrumentiert (erweitert). Es gibt zwei Varianten (auszuwählen in ->Settings) mit Vor- und Nachteilen: 1) Die instrumentierte Datei wird in einem temporären Verzeichnis erstellt und ausgeführt. + %0 ergibt einen falschen Wert - die Quelldatei bleibt unter ihrem Original-Pfad und Namen editierbar. 2) Die instrumentierte Datei wird mit Original-Pfad und -Name erstellt und ausgeführt. + %0 ergibt den richtigen Wert - die Quelldatei wird nach .org kopiert und ist dort editierbar. --- Settings --- Start-Umgebung der zu startenden Konsole ( 1-3 per F10 und Dialog, 4-8 per Schalter im Menü "Settings", 9 per Kontextmenü ->Navigation ). Diese Daten können während der Ausführung des Batch nicht geändert werden. 1. Start-Verzeichnis 2. Parameter wie man sie auch in der Kommandozeile übergibt, evtl in "". Werden auch oben in der Icon-Leiste angezeigt und können dort geändert werden 3. Startup-Kommando, das bei jedem Start als Intro ausgeführt wird 4. Settings->Format Ansi : Batch-Dateien werden von Windows im OEM-Format erwartet. Aktivieren, falls Source im Ansi-Format vorliegt 5. Settings->Enable Break : aktivieren, um ein lang laufendes Batch zwischen zwei Zeilen unterbrechen zu können 6. Settings->:: to REM : aktivieren, um alle "::" in "REM" umzuwandeln (nicht in Source, nur für Debugger) 7. Settings->Stop on Error: deaktivieren, um global (statt individuell pro Zeile, siehe ->Fehler) den Stop bei Fehlern abzuschalten 8. Settings->Enable %0 : siehe ->%0-Problem 9. Events für das ->LogFile (über Kontextmenü ->Navigation) --- BreakPoints --- BreakPoints können auch während der Ausführung (bei Unterbrechungen) geändert werden 1. Setzen/Löschen per Click auf roten Kreis oder nach Rechts-Click auf Source-Zeile 2. Eigenschaften ändern per DoppelClick auf roten Kreis oder Zeilen-Kontextmenü - Count : Anzahl der Durchläufe dieser Zeile bis zum Stop, Standard ist 1 - Condition: Bedingung für Count, bitte in Batch-Syntax angeben (ohne "IF"), z.B. - (IF) EXIST - (IF) DEFINED - (IF) == - (IF) EQU --- ECHO ON/OFF --- 1. Das globale ECHO der Batch-Zeilen vor Ausführung kann online an- und ausgeschaltet werden 2. Das entsprechende Icon dient als Status-Anzeige UND als Button für Zustandswechsel (F12) 3. Das ECHO bei Ausführung im Debugger ist nicht absolut identisch mit dem ohne Debugger, siehe ->Abweichungen 4. ECHO kann auch zeilenspezifisch eingeschaltet werden, siehe ->Edit --- globale Variablen --- 1. Werden beim Laden automatisch ermittelt, ggf. löschen oder hinzufügen (vor Ausführung) 2. Darstellung der Werte normalerweise (F11) mit "." für Leerzeichen 3. Darstellung der Namen normalerweise (Shift-F11) OHNE Prozentzeichen ( Var statt %Var% ) 4. Werte können jederzeit geändert werden (DoppelClick), Setzen "ErrorLevel" auf 0 auch per Ctrl-E 5. Nutzung von Variableninhalten als Vorgabe von Dateinamen für ->Tracking --- Ausführung --- 1. Die Ausführung wird gestartet und fortgesetzt per Icon-Click oder ->HotKey F4, F7, F8 oder F9 2. Die Navigationsliste wechselt auf die Event-Ansicht 3. Bei Ausführung im Debugger ist die Variable "BatchDebug" definiert (=Versionsnummer) 4. In der Statuszeile wird die CALL-Tiefe, Klammerungstiefe, SETLOCAL-Tiefe und der ECHO-Status angezeigt 5. Settings, Event-Auswahl und einige Zeilen-Eigenschaften können nicht mehr geändert werden 6. Die Ausführung wird per Reset (Ctrl-F2) beendet --- lokale Variablen --- 1. Das sind Parameter wie %1 und FOR-Variablen wie %%s 2. Werte können NICHT geändert werden 3. Nutzung von Variableninhalten als Vorgabe von Dateinamen für ->Tracking --- Fehler --- 1. Fehler sind ->ErrorLevel <> 0 UND Text-Ausgaben auf ->StdErr 2. Fehler werden im LogFile registriert und es wird (normalerweise) gestoppt --- ErrorLevel --- 1. Für erwartete Fehler kann das automatische Stoppen für einzelne Zeilen verhindert werden. Dazu bitte den maximal erlaubten ErrorLevel setzen (RechtsClick auf die den Fehler erzeugende Zeile oder maximal erlaubten Wert einfach eintippen) 2. Damit ein weiterhin anstehender ErrorLevel nicht in der folgenden Zeile sofort zum nächsten Break führt kann mit negativen Werten der ErrorLevel nach Registrierung gelöscht werden --- StdErr --- 1. Für den Debugger sind StdErr-Ausgaben unabhängig vom ErrorLevel obwohl sie in dder Regel gleichzeitig kommen 2. Es gibt aber (Fehler-)Meldungen, die den ErrorLevel NICHT setzen 3. Für erwartete StdErr-Meldungen: erlauben per RechtsClick auf die Zeile oder Taste "T" --- LogFile --- 1. Es wird ein LogFile für ->Fehler, Batch-Ereignisse und manuelle Eingaben angelegt, Dateiname .log 2. Batch-Ereignisse sind Befehle, die vor Ausführung im Kontext-Menü fürs Logging aktiviert werden können, z.B. interner Call und -Return, externer Call und -Return, hinzugefügte Befehle. Das Logging aller Zeilennummern (mit Zeitstempel) ist zeitaufwändig und sollte in der Regel ausgeschaltet sein 3. Log-Zeilen können manuell im Debugger per Kontext-Menü eingefügt werden 4. Log-Zeilen können im Batch-Ablauf eingefügt werden - per Batch-Befehl ECHO Text>>%_dbgLog% - per Batch-Befehl CALL :_dbgLog Text (mit automatischer Einrückung gemäß Call-Ebene) --- Tracking --- 1. Batch-Programme haben oft den Zweck, Dateien zu lesen oder zu schreiben. Diese Dateien können online angezeigt werden 2. Als Vorgabe für den Dateinamen kann der Inhalt von Variablen dienen (Rechts-Click), sonst Ctrl-T --- DelayedExpansion --- 1. Bei verzögerter Auswertung kann eine globale Variable mit zwei Werten gleichzeitig existieren 2. !var! wird unter "globale Variablen" angezeigt und kann geändert werden 3. %var% wird unter "lokale Variablen" angezeigt und kann nicht geändert werden --- zusätzliche Befehle --- 1. Es können bei jeder Programm-Unterbrechung einmalige Zusatz-Befehle eingegeben werden (Ctrl-A) 2. Die Befehle "CALL", "GOTO" und "EXIT" sind hier nicht sinnvoll möglich --- Hilfe --- 1. Anzeige dieser Datei (F1) 2. Hilfe zum ersten Befehl der aktuellen Zeile (Ctrl-F1), "SET" falls dies kein Batch-Befehl ist 3. Hilfe zu einem einzugebenden Befehl (Shift-F1) --- BatchDebug.ini --- Einige Programm-Einstellungen können nur hier vorgenommen werden: - TmpPath : Verzeichnis für temporäre Dateien des Debuggers - Editor : Aufrufzeile für externen Editor, %n für Dateiname, %z für Cursorzeile - ScrollBar : 0 für immer verborgenen ScrollBar - StartUp : Default-Startup-Befehl --- .ini --- Einige Source-Einstellungen können nur hier vorgenommen werden: - NaviString: Zeilen, die diesen String enthalten werden automatisch in die Navigations-Leiste aufgenommen === HOTKEY-Liste === F1 Help BatchDebug -Shift Help Command (Dialog) -Ctrl Help Command (current line) -Alt About F2 Reset Debugger -Ctrl " F3 Call Editor F4 Run until current Line -Ctrl Run until current Line, ignore BreakPoints F5 BreakPoint on/off -Ctrl BreakPoint properties -Shift Show next special line (BreakPoint, ErrorLevel, Ignore, ...) F6 Ignore Line F7 Execute current line, skip CALL (if possible) F8 Execute current line F9 Execute until eof or BreakPoint F10 Set Start-Dir, -Parameters and -Command F11,# Line Numbers in Source on/off -Shift visible Blanks in Sets on/off -Ctrl Percent in Sets on/off F12 ECHO ON/OFF 0..9,- ignore ->ErrorLevel for current line T ignore ->StdErr for current line Ctrl-A Add Command Ctrl-E Reset ErrorLevel Ctrl-L Add Text to ->LogFile Ctrl-O File-Open Ctrl-P Edit Parameters Ctrl-Q Close file Ctrl-T Add File for ->Tracking Ctrl-X Exit Debugger Escape Help-Exit, TrackFile-Exit Return Set Cursor in Source-Window Ctrl-Num+/- Source Textsize === Kontakt === aktuelle Version: https://www.dropbox.com/sh/tut0pkkpqh6c46w/AAA0TAWjEgfpsX9ufsg3pSlRa?dl=0 eMail: mailto:denkDirNix@mail.de