Scripts

WinHex & X-Ways

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.