Scripts
Some 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 higher 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.
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 quotation marks to enforce the interpretation of a parameter as text. Quotation marks are required if a text string or variable name contains one or more space characters, so that all characters in between are recognized as constituting one parameter. If the text within quotation marks is the name of a defined variable, the variable will be used as the parameter.
Wherever numerical parameters are expected (integer numbers), the integrated formula parser allows you to use mathematical expressions. Such expressions need to be enclosed in brackets. They must not contain space characters. They may make use of variables that can be interpreted as integer numbers. Supported operations are addition (+), subtraction (-), multiplication (*), integer division (/), modular division (%), bitwise AND (&), bitwise OR (|), and bitwise XOR (^). Valid mathematical expressions are for example (5*2+1), (MyVar1/(MyVar2+4)), or (-MyVar).
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). Specify "?" as the parameter to let the user select the file to open.
Open C:
Open D:
Opens the specified logical drive. Specify ":?" as the parameter to let the user select a logical drive or physical disk to open.
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 WHX backup of the active file in its current state.
CreateBackupEx 0 100000 650 true "F:\My backup.whx"
Creates a WHX 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). Can also write the contents of a variable specified as the parameter. Moves the current position forward by the number of bytes written. When the end of the file is reached, to accomplish that, a null byte is appended. Useful so that further Write commands don't overwrite the last byte written by the previous Write command.
Write2
Identical to Write, but does not append a null byte if the end of the file has been reached. So it is not safe to assume that Write2 always moves the current position forward by the number of bytes written.
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 48 different variables allowed. Other ways to create variables: Assign, GetUserInput.
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 and filename. Specify "?" as the parameter to let the user select the destination.
SaveAll
Saves changes in all windows.
Terminate
Aborts script execution.
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. 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, Binary, HexASCII, IntelHex, MotorolaS, Base64, UUCode, LowerCase, UpperCase, hiberfil, in combinations as known from the Convert menu command.
AESEncrypt "My Password"
Encrypts the active file or disk, or selected block thereof, with the specified key (up to 32 characters long) with AES.
AESDecrypt "My Password"
Decrypts the active file or disk.
Find "John" [MatchCase MatchWord Down Up BlockOnly SaveAllPos Unicode Wildcards]
Find 0x0D0A [Down Up BlockOnly SaveAllPos Wildcards]
Searches in the active window for the name John or the hexadecimal values 0x0D0A, respectively, and stops at the first occurrence. Other parameters are optional. By default, WinHex searches the entire file/disk. The optional parameters work as known from usual WinHex search options.
ReplaceAll "John" "Joan" [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 "Hello World"
IfEqual 0x12345678 MyVariable
IfEqual MyVariable 1000
IfEqual MyVariable MyOtherVariable
IfEqual MyVariable (10*MyOtherVariable)
Compares either two numerical integer values (each of them being a constant value, an integer variable or a mathematical expression) or two variables, ASCII strings, or hexadecimal values at the binary level. Comparing two objects at the binary with a different length always returns False as the result. If equal, the following commands will be executed. If conditions must not be nested.
IfGreater MyVariable "Hello World"
IfGreater 0x12345678 MyVariable
IfGreater MyVariable 1000
IfGreater MyVariable MyOtherVariable
IfGreater MyVariable (10*MyOtherVariable)
Accepts the same parameters as IfEqual. If the first one is greater than the second one, the following commands will be executed. If conditions must not be nested.
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, IfEqual, IfGreater).
{..
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:
{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 aree 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.
InitMFTRecords
Clears unused MFT FILE records on the current logical drive if it is formatted with NTFS, using the currently set initialization settings. Simply does nothing on other file systems. The changes are written immediately to the disk.
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. Other ways to create variables: e.g. Read, GetUserInput, InttoStr. Up to 48 different variables allowed to exist simultaneously.
Release MyVariable
Specifically disposes an existing variable. Mandatory to invoke only when more than 48 variables with different names are to be used during the execution of a script, so that earlier variables that are not needed any more can be destroyed.
SetVarSize MyVariable 1
SetVarSize MyVariable 4
Explicitly sets the allocated memory size of a variable at a given time, in bytes. This can be useful e.g. for variables that hold integer values and that are the result of a calculation, if this value is to be written to a binary file with a fixed-length structure. Without SetVarSize, no assumption must be made about the size of the variable. For instance, the number 300 could be stored in any number of bytes larger than 1. If the new size set by SetVarSize is smaller than the old size, the allocated memory is truncated. If the new size is larger, the allocated memory is expanded. At any rate, the value of the persisting bytes is retained.
GetUserInput MyVariable "Please enter your name:"
Stores the ASCII text or binary data (0x...) specified by the user at script execution time (128 bytes at max.) in a variable named "MyVariable". The user is prompted by the message you provide as the second parameter. If the variable does not yet exist, it will be created. Other ways to create variables: Assign, Read.
GetUserInputI MyIntegerVariable "Please enter your age:"
Works like GetUserInput, but accepts and stores only integer numbers.
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.
IntToStr MyStr MyInt
IntToStr MyStr 12345
Stores the decimal ASCII text representation of the integer number specified as the second parameter in a variable specified as the first parameter.
StrToInt MyInt MyStr
Stores the binary representation of the integer number specified as a decimal ASCII string in the second parameter in a variable specified as the first parameter.
StrCat MyString MyString2
StrCat MyString ".txt"
Appends one string to another. The second parameter may be a variable or a constant string. The first parameter must be a variable. The result will be saved in the variable specified by the first parameter and must not be longer than 255 characters.
GetClusterAlloc MyStr
May be applied to a logical volume. Retrieves a textual description of the current position's allocation, e.g. which file is stored in the current cluster, and saves that description in the specified variable.
GetClusterAllocEx IntVar
May be applied to a logical volume. Retrieves an integer value that indicated whether the cluster at the current position is allocated (1) or not (0), and saves that description in the specified variable.
GetClusterSize IntVar
May be applied to a logical volume. Retrieves the cluster size and saves that value in the specified integer variable.
InterpretImageAsDisk
Treats a raw image, Encase image or evidence file like the original physical disk or partition. Requires a specialist or forensic license.
CalcHash HashType MyVariable
CalcHashEx HashType MyVariable
Calculates a hash as known from the command in the Tools menu and stores it in the specified variable (which will be created if it does not yet exist). The HashType parameter must be one of the following: CS8, CS16, CS32, CS64, CRC16, CRC32, MD5, SHA-1, SHA-256, PSCHF. CalcHashEx in addition displays the hash in a dialog window.
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) or pause. This may accelerates script execution 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 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.