Verzeichnis der WinHex-Script-Befehle

Aktueller Stand dieser Dokumentation nur in Programmhilfe und Benutzerhandbuch.

Ein Großteil der Funktionalität von WinHex kann in automatisierter Weise verwendet werden, z. B. um wiederkehrende Routineaufgaben zu erledigen oder um bestimmte Tätigkeiten an nicht beaufsichtigten Computern im Netz ferngesteuert auszuführen. Die Möglichkeit, andere als die mitgelieferten Beispielscripte auszuführen, ist Besitzern von professionellen und Specialist-Lizenzen vorbehalten. Scripte können vom Start-Center oder von der Kommandozeile aus gestartet werden. Wenn ein Script ausgeführt wird, können Sie die Esc-Taste drücken, um es abzubrechen. Scripte lösen aufgrund ihrer umfangreicheren Möglichkeiten die von früheren Versionen von WinHex bekannten Routinen ab.

WinHex-Scripte sind Textdateien mit der Namensendung ".whs". Sie können mit jedem Texteditor bearbeitet werden und bestehen einfach aus einer Folge von Befehlen. Es wird empfohlen, pro Zeile nur einen Befehl einzugeben, um die Übersichtlichkeit zu wahren. Abhängig vom jeweiligen Befehl müssen dahinter ggf. Parameter angegeben werden. Die meisten Befehle wirken sich auf die Datei oder den Datenträger im aktuell aktiven Editierfenster aus.

Siehe auch: WinHex API

Groß- und Kleinschreibung spielt bei den Scriptbefehlen keine Rolle. Kommentare dürfen überall in einem Script eingefügt werden. Zu ihrer Kenntlichmachung müssen ihnen zwei aufeinanderfolgende Schrägstriche vorangestellt werden. Parameter dürften max. 255 Zeichen lang sein. Where in doubt because hex values, text strings (or even integer numbers) are accepted as parameters, you may use inverted commas (quotation marks) to enforce the interpretation of a parameter as text. Inverted commas are required if a text string or variable name contains one or more space characters, so that all characters between the inverted commas are recognized as constituting one parameter.

Im Folgenden finden Sie Beschreibungen aller gegenwärtig unterstützten Scriptbefehle, incl. Beispiel-Parameter.

Create "D:\My File.txt" 1000
Creates the specified file with an initial file size of 1000 bytes. If the file already exists, it is overwritten.

Open "D:\My File.txt"
Open "D:\*.txt"
Opens the specified file(s).

Open C:
Open D:
Opens the specified logical drive.

Open 80h
Open 81h
Open 9Eh
Opens the specified physical media. Floppy disk numbering starts with 00h, fixed and removable drive numbering with 80h, optical media numbering with 9Eh.

Optionally, you may pass a second parameter with the Open command that defines the edit mode in which to open the file or media ("in-place" or "read-only").

CreateBackup
Creates a backup of the active file in its current state.

CreateBackupEx 0 100000 650 true "F:\My backup.whx"
Creates a backup of the active disk, from sector 0 through sector 1,000,000. The backup file will be split automatically at a size of 650 MB. Compression is enabled ("true"). The output file is specified as the last parameter.
If the backup file should not be split, specify 0 as the third parameter. To disable compression, specify "false". To have the Backup Manager automatically assign a filename and place the file in the folder for backup files, specify "" as the last parameter.

Goto 0x128
Goto MyVariable
Moves the current cursor position to the hexadecimal offset 0x128. Alternatively, an existing variable (up to 8 bytes large) can be interpreted as a numeric value, too.

Move -100
Moves the current cursor position 100 bytes back (decimal).

Write "Test"
Write 0x0D0A
Write MyVariable
Writes the four ASCII characters "Test" or the two hexadecimal values "0D0A" at the current position (in overwrite mode) and moves the current position forward accordingly (i.e. by 4 bytes). Can also write the contents of a variable specified as the parameter.

Insert "Test"
Functions just as the "Write" command, but in insert mode. Must only be used with files.

Read MyVariable 10
Reads the 10 bytes from the current position into a variable named "MyVariable". If this variable does not yet exist, it will be created. Up to 16 different variables allowed. Another way to create a variable is the Assign command.

ReadLn MyVariable
Reads from the current position into a variable named "MyVariable" until the next line break is encountered. If the variable already exists, its size will be adjusted accordingly.

Close
Closes the active window without saving.

CloseAll
Closes all windows without saving.

Save
Saves changes to the file or disk in the active window.

SaveAs "C:\New Name.txt"
Saves the file in the active window under the specified path. Specify "?" as the parameter to let the user specify the destination.

SaveAll
Saves changes in all windows.

Exit
Terminates script execution and ends WinHex.

ExitIfNoFilesOpen
Aborts script execution if no files are already opened in WinHex.

Block 100 200
Block "My Variable 1" "My Variable 2"
Defines the block in the active window to run from offset 100 to offset 200 (decimal). Alternatively, existing variables (each up to 8 bytes large) can be interpreted as numeric values.

Block1 0x100
Defines the block beginning to be at the hexadecimal offset 0x100. A variable is allowed as the parameter as well.

Block2 0x200
Defines the block end to be at the hexadecimal offset 0x200. A variable is allowed as the parameter as well.

Copy
Copies the currently defined block into the clipboard. If no block is defined, it works as known from the Copy command in the Edit menu.

Cut
Cuts the currently defined block from the file and puts it into the clipboard.

Remove
Removes the currently defined block from the file.

CopyIntoNewFile "D:\New File.dat"
CopyIntoNewFile "D:\File +MyVariable+.dat"
Copies the currently defined block into the specified new file, without using the clipboard. If no block is defined, it works as known from the Copy command in the Edit menu. Can copy disk sectors as well as files. The new file will not be automatically opened in another edit window. Allows an unlimited number of "+" concatenations in the parameter. A variable name will be interpreted as an integer if not be larger than 2^24 (~16 Mio.). Useful for loops and file recovery.

Paste
Pastes the current clipboard contents at the current position in a file, without changing the current position.

WriteClipboard
Writes the current clipboard contents at the current position in a file or within disk sectors, without changing the current position, by overwriting the data at the current position.

Convert Param1 Param2
Converts the data in the active file from one format into another one. Valid parameters are ANSI, IBM, EBCDIC, Binary, HexASCII, IntelHex, and MotorolaS, in combinations as known from the conventional Convert menu command.

Encrypt "My Password"
Encrypts the active file or disk, or selected block thereof, with the specified key (up to 16 characters long) using the PC1 algorithm (128 bit).

Decrypt "My Password"
Decrypts the active file or disk.

Find "John" [MatchCase MatchWord Down Up BlockOnly SaveAllPos Unicode Wildcards]
Find 0x1234 [Down Up BlockOnly SaveAllPos Wildcards]
Searches in the active window for the name John or the hexadecimal values 0x1234, respectively, and stops at the first occurrence. Other parameters are opional. By default, WinHex searches the entire file/disk. The optional parameters work as known from usual WinHex search options.

ReplaceAll "Jon" "Don" [MatchCase MatchWord Down Up BlockOnly Unicode Wildcards]
ReplaceAll 0x0A 0x0D0A [Down Up BlockOnly Wildcards]
Replaces all occurrences of either a string or hexadecimal values in the active file with something else. Can only be applied to a disk if in in-place mode.

IfFound
A boolean value that depends on whether or not the last Find or ReplaceAll command was successful. Place commands that shall be executed if something was found after the IfFound command.

IfEqual MyVariable "constant string"
IfEqual 0x12345678 MyVariable
IfEqual MyVariable MyOtherVariable
Compares two variables, ASCII strings, or hexadecimal values at the binary level. Comparing two objects with a different length always returns False as the result. If equal, the following commands will be executed.

IfGreater 0x12345678 MyVariable
IfGreater MyVariable MyOtherVariable
Compares two variables and interprets them as integer values (64-bit signed). Such an integer comparison is not appropriate for comparing strings of different lengths alphabetically. If the first one is greater than the second one, the following commands will be executed.

Else
May occur after IfFound or IfEqual. Place commands that shall be executed if nothing was found or if the compared objects are not equal after the Else command.

EndIf
Ends conditional command execution (after IfFound or IfEqual).

{...
ExitLoop
...}
Exits a loop. A loop is defined by braces. Closing braces may be followed by an integer number in square brackets, which determines the number of loops to execute. This is may also be a variable or the keyword "unlimited" (so the loop can only be terminated with an ExitLoop command). Loops must not be nested.

Example of a loop:
{ Write "Loop" }[10] will write the word "Loop" ten times.

Label ContinueHere
Creates a label named "ContinueHere"

JumpTo ContinueHere
Continues script execution with the command following that label.

NextObj
Switches cyclically to the next open window and makes it the "active" window. E.g. if 3 windows are open, and window #3 is active, NextObj will make #1 the active window.

ForAllObjDo
The following block of script commands (until EndDo occurs) will be applied to all open files and disks.

CopyFile C:\A.dat D:\B.dat
Copies the contents of C:\A.dat into the file D:\B.dat.

MoveFile C:\A.dat D:\B.dat
Moves the file C:\A.dat to D:\B.dat.

DeleteFile C:\A.dat
Surprisingly, deletes C:\A.dat.

InitFreeSpace
InitSlackSpace
Clears free space or slack on the current logical drive, respectively, using the currently set initialization settings. InitSlackSpace switches the drive temporarily to in-place mode, thus saving all pending changes.

Assign MyVariable 12345
Assign MyVariable 0x0D0A
Assign MyVariable "I like WinHex"
Assign MyVariable MyOtherVariable
Stores the specified integer number, binary data, ASCII text, or other variable's contents in a variable named "MyVariable". If this variable does not yet exist, it will be created. Up to 16 different variables allowed. Another way to create a variable is the Read command.

Inc MyVariable
Interprets the variable as an integer (if not larger than 8 bytes) and increments it by one. Useful for loops.

Dec MyVariable
Interprets the variable as an integer (if not larger than 8 bytes) and decrements it by one.

MessageBox "Caution"
Displays a message box with the text "Caution" and offers the user an OK and a Cancel button. Pressing the Cancel button will abort script execution.

ExecuteScript "ScriptName"
Executes another script from within a running script, at the current execution point, e.g. depending on a conditional statement. Calls to other scripts may be nested. When the called script is finished, execution of the original script will be resumed with the next command. This feature can help you structure your scripts more clearly.

Turbo On
Turbo Off
In turbo mode, most screen elements are not updated during script execution and you are not able to abort (e.g. by pressing Esc). This accelerates the script by up to 75% if a lot of simple commands such as Move and NextObj are executed in a loop.

Debug
All the following commands must be confirmed individually by the user.

UseLogFile
Error messages are written into the log file "Scripting.log" in the folder for temporary files. These messages are not shown in a message box that requires user interaction. Useful especially when running scripts on unattended remote computers.

CurrentPos
GetSize
unlimited
are keywords that act as a placeholders and may be used where numeric parameters are required. On script execution, CurrentPos stands for the current offset in the active file or disk window and GetSize for its size in bytes. unlimited actually stands for the number 2,147,483,647.