Please see the program help or the manual for the latest update of this documentation.
Most of the functionality of WinHex can be used in an automated way, e.g. to speed up recurring routine tasks or to perform certain tasks on unattended remote computers. The ability to execute scripts other than the supplied sample scripts is limited to owners of a professional or specialist license. Scripts can be run from the Start Center or the command line. While a script is executed, you may press Esc to abort. Because of their superior possibilities, scripts supersede routines, which were the only method of automation in previous versions of WinHex.
WinHex scripts are text files with the filename extension ".whs". They can be edited using any text editor and simply consist of a sequence of commands. It is recommended to enter one command per line only, for reasons of visual clarity. Depending on the command, you may need to specify parameters next to a command. Most commands affect the file or disk presented in the currently active window.
Also see:
Script commands are case-insensitive. Comments may occur anywhere in a script file and must be preceded by two slashes. Parameters may be 255 characters long at most. 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.
The following is a description of currently supported script commands, including example parameters.
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.
附：一个sample script.whs
// WinHex sample script, demonstrating various script commands.
// Can only be executed by the evaluation version if unchanged.
MessageBox "Attention: all windows will now be closed without prompting."
CloseAll
// Create a file named "abcdefgh.dat" with 123456 bytes in the root directory of drive C:.
// Will overwrite this file in case it already exists.
Create "C:\abcdefgh.dat" 123456
MessageBox "The sample file 'abcdefgh.dat' has been created."
// Write some text at offset 0.
Write "This file was created by a WinHex sample script."
// Write 16 magic hex values at offset 0x100.
Goto 0x100
Write 0x57696E48657820697320677265617421
Move -16
// Now we are back at offset 0x100.
// Open drive C:
Open C:
// To find out whether this drive has a FAT file system, search for
// the string "FAT" in the boot sector. Could also be implemented as
// Goto 0x36
// Read "A three-character variable" 3
// IfEqual "A three-character variable" "FAT"
Block 0 511
Find "FAT" BlockOnly
IfFound
// Search for the directory entry "abcdefghdat". This only works on FAT drives.
MessageBox "Drive C: has a FAT file system. Now looking for the directory entry of 'abcdefgh.dat'."
Find "abcdefghdat"
Else
// Search for the filename "abcdefgh.dat" in Unicode, as stored on NTFS drives.
MessageBox "Drive C: does not have a FAT file system. Now looking for an NTFS entry of 'abcdefgh.dat'."
Find "abcdefgh.dat" Unicode
EndIf
// Now go back to the file.
NextObj
// We know that the only other open window is the file we created,
// since initially all other possibly open windows were closed.
// Convert the file from Binary to HexASCII and back 3 times.
{
Convert Binary HexASCII
Convert HexASCII Binary
}[3]
// Now make drive C: the active window again, to show
// that the directory entry of "abcdefgh.dat" has been
// found.
NextObj
MessageBox "Sample script execution complete. The file has been converted a few times, and its directory entry has hopefully been found in the file system."
