The following is a list of functions for communicating with the 010 Editor program when writing a Template or Script.

void AddBookmark(
    int64 pos,
    string name,
    string typename,
    int arraySize=-1,
    int forecolor=cNone,
    int backcolor=0xffffc4,
    int moveWithCursor=false )
Creates a bookmark on the file the current Script or Template is being executed on (not the actual Script or Template). See Using Bookmarks for information on bookmarks and see Running Templates and Scripts for information on controlling which file a Script or Template is run on.

pos indicates the file address where the bookmark will be generated and name gives the name of the bookmark (this name can be empty). typename is a string giving the type of the bookmark to generate and this must be one of the built-in types or a user-defined type. If the type is user-defined and the AddBookmark function is run from a Template, that type must be defined in the current Template. If the type is user-defined and the AddBookmark function is run from a Script, that type must be defined in a Template that has already been run on the file (not in the current Script). Specify an array of variables using the arraySize argument or set arraySize to -1 to just generate a single variable. The text color of the bookmark can be indicated using the forecolor argument and the background color can be specified with the backcolor argument. If the moveWithCursor argument is true, the bookmark will reposition itself to the cursor as the cursor moves around the file.

For example, after loading a ZIP file in 010 Editor (which will cause the 'ZIPTemplate.bt' Template to be run on the file), create a new Script and run the following command on the file:

    AddBookmark( GetCursorPos(), "endmarker", 
        "ZIPENDLOCATOR", cRed );

Here the type "ZIPENDLOCATOR" type is defined in the 'ZIPTemplate.bt' file, not in the Script. The functions GetNumBookmarks, GetBookmarkPos and GetBookmarkName can be used to query existing bookmarks and the RemoveBookmark function can be used to erase bookmarks.

Requires 010 Editor v3.1 or higher.

void Assert( int value, const char msg[] = "" )
Stops execution of the script or template if the value is equal to zero. If execution is stopped, the text message msg will be displayed in the Output tab of the Output Window (note that this is an optional argument). Because conditional statements evaluate to 1 or 0 in C/C++, comparisons can be used in asserts. For example:

    Assert( numRecords > 10, 
      "numRecords should be more than 10." );

Requires 010 Editor v3.1 or higher.

void ClearClipboard()
Removes any data is currently on the Windows clipboard.

Requires 010 Editor v3.1 or higher.

void CopyStringToClipboard( const char str[] )
Sets the operating system clipboard to contain the string passed in the str argument.

Requires 010 Editor v3.1 or higher.

void CopyToClipboard()
Copies the currently selected bytes to the clipboard. See SetSelection to change the selection.

void CutToClipboard()
Copies the currently selected bytes to the clipboard and deletes them from the file. See SetSelection to change the selection.

int DeleteFile( char filename[] )
Deletes the file given by filename from disk. Note that the file should not be open in the editor or the delete will fail. Returns a value less than zero on failure.

void DisableUndo()
Turns off undo support for a file. This function will speed up a script when writing a large number of changes to a file. Undo is automatically turned on after the script is finished. Note that undo is automatically disabled for files created with FileNew. See EnableUndo below.

void DisplayFormatBinary()
void DisplayFormatDecimal()
void DisplayFormatHex()
void DisplayFormatOctal()
Sets the display format of variables in the Inspector to binary, decimal, hexadecimal, or octal. Any variables declared after this function is called will be displayed in the selected format. Note that the format can also be set for one variable using the syntax <format=hex|decimal|octal|binary> after a declaration or typedef (see Declaring Template Variables for more information).

void EnableUndo()
Turns back on Undo support for a file after calling DisableUndo. Undo is automatically turned on after the script is finished.

int Exec( const char program[], const char arguments[], int wait=false )
Executes an external application using the given program and arguments. Returns true if successful or false if an error occurred. If the wait argument is true, this function waits for the external application to finish processing before it returns. Note that the wait argument is only available starting in 010 Editor version 3.1 and also starting in 010 Editor version 3.1, this function can no longer be called in a Template because of security issues.

void Exit( int errorcode )
Ends execution of the current script or template and displays the errorcode in the Output tab of the Output panel. Note that usually the keyword return can be used to accomplish the same task unless execution is inside of a custom function.

This function is special in that it can be used to return an ERRORLEVEL code to a batch file (see Command Line Parameters for more information). The last errorcode that was passed to an Exit function, either from a script or a template, will be returned as the global ERRORLEVEL when 010 Editor exits.

void ExpandAll()
Recursively opens all tree nodes in the Template Results panel. Variables that have the attribute '<open=suppress>' set will not be opened. See Template Results for more information.

Requires 010 Editor v3.2 or higher.

void ExportCSV( const char filename[] )
Writes the contents of the Template Results panel to a file in a comma-delimited format which can be opened in other programs such as Excel. The file is saved to the given filename and the ExpandAll function can be called first to ensure all variables are included in the export. Alternately, the FPrintf function can be used to output individual variables.

Requires 010 Editor v3.2 or higher.

void FileClose()
Closes the current file. No file will be active after this function is called and use the FileSelect function to activate another file.

int FileCount()
Returns the number of existing file handles. See FileSelect to set the current file.

int FileExists( const char filename[] )
Returns true if the given file name exists on disk, or false if it does not.

int FileNew()
Creates a new file in the editor and returns the index of the created file (see GetFileNum). If this function is run from a script, the created file becomes the current file. If this function is run from a template, the current file does not change (use the FPrintf function to write data to the returned file handle). Note that when new files are created, the undo buffer is turned off by default, but will be turned on as soon as the script finishes.

int FileOpen( const char filename[], int runTemplate=false )
Opens the file specified by the file name into the editor. If runTemplate is true and a Template is associated with that file (see Template Options), the Template will be run on the file. Returns a value less than zero if the file could not be loaded. Note that the runTemplate argument is only available starting in 010 Editor version 3.1.

int FileSave()
int FileSave( const char filename[] )
int FileSave( const wchar_t filename[] )
Saves the current file to the given file name. The file name can be either an ASCII string or a wide string. If FileSave is called with no parameters, the file is saved to the current file name. See GetFileName or GetFileNameW to retrieve the name of the current file. Returns a value less than zero on error.

void FileSelect( int index )
Only one file can be active at a time and all of the Read/Write operations occur on that file. Use FileSelect to select a different file to be the current file. The files are numbered from 0 up to FileCount()-1. See GetFileNum to get the index of the current file.

char[] GetArg( int index )
wchar_t[] GetArgW( int index )
Returns an argument passed to a script or a template from the command line. The GetArg function returns an ASCII string and the GetArgW function returns a wide string. The index parameter must be a number between 0 and GetNumArgs()-1. If index is an invalid number an empty string is returned. See the GetNumArgs function or the -script or -template parameter for more information on passing command line arguments.

Requires 010 Editor v3.2 or higher.

string GetBookmarkName( int index )
Returns a string which contains the name of a bookmark. index controls which bookmark name is returned and the value of index should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). See AddBookmark for information on creating bookmarks.

Requires 010 Editor v3.1 or higher.

int64 GetBookmarkPos( int index )
Returns the starting address of a bookmark and the bookmark returned is specified using the index argument. index should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). See AddBookmark for information on creating bookmarks.

Requires 010 Editor v3.1 or higher.

int GetBytesPerLine()
Returns the number of bytes displayed per line in the current Hex Editor Window. This value is by default 16, but may change depending upon the current settings in the View Menu.

string GetClipboardString()
If the operating system clipboard currently contains a string, this string will be returned by the GetClipboardString function. If the data on the clipboard cannot be converted to a string, an empty string will be returned.

Requires 010 Editor v3.1 or higher.

string GetCurrentTime()
Returns a string representing the current time in the format "hh:mm:ss" (note this is using the 24-hour clock).

Requires 010 Editor v3.1 or higher.

string GetCurrentDate()
Returns a string representing the current date in the format "MM/dd/yyyy".

Requires 010 Editor v3.1 or higher.

string GetCurrentDateTime()
Returns a string representing the current date and time in the format "MM/dd/yyyy hh:mm:ss" (note this is using the 24-hour clock). Functions such as StringToTimeT or StringToOleTime can be used to convert this string to a date format.

Requires 010 Editor v3.1 or higher.

int64 GetCursorPos()
Returns the address of the cursor in the file.

char[] GetFileName()
Returns a string representing the file name of the current file including the path.

wchar_t[] GetFileNameW()
Returns a wide string which contains the file name of the current file including the path.

Requires 010 Editor v3.2 or higher.

int GetFileNum()
Each open file is assigned a index from 0 up to FileCount()-1. This function returns the index of the current file. Use the FileSelect function to make another file the active file.

int GetNumArgs()
Returns the number of arguments that were passed to this script or template from the command line. The individual arguments can be accessed using the GetArg and GetArgW functions. For more information on how to pass arguments see the -script and -template command line parameters.

Requires 010 Editor v3.2 or higher.

int GetNumBookmarks()
Returns the number of bookmarks set for the file that the current Script or Template is being run on (see Running Templates and Scripts for more information on choosing which file to run a Template or Script on). See the AddBookmark function for information on creating bookmarks.

Requires 010 Editor v3.1 or higher.

int GetReadOnly()
Returns true if the file is marked as read-only, or false if the file can be modified.

int64 GetSelSize()
Returns the number of bytes that have been selected. Returns 0 if no selection is made.

int64 GetSelStart()
Returns the start address of the selection. Use GetSelSize to determine if a selection has been made.

string GetTempDirectory()
Returns a string representing the current temporary directory set using the Memory Options dialog. The temp directory will contain a slash as the last character (e.g. "C:\temp\").

Requires 010 Editor v3.1 or higher.

double InputFloat(
    const char title[],
    const char caption[],
    const char defaultValue[] )
Opens up a dialog with a single edit box. The title displays in the title bar of the dialog and the caption displays above the edit box. The defaultValue specifies the starting value in the edit box. This function returns the floating-point value of the number entered in the edit box. If an invalid number is entered or Cancel is pressed, the constant BAD_VALUE is returned.

int InputNumber(
    const char title[],
    const char caption[],
    const char defaultValue[] )
Similar to InputFloat except an integer is returned instead of a float value. If an invalid number is entered or Cancel is pressed, the constant BAD_VALUE is returned.

char[] InputOpenFileName(
    char title[],
    char filter[]="All files (*.*),
    char filename[]="" )
Shows a standard file open dialog box with the caption title. The filter controls which file masks are available in the File Type drop-down list. Specify filters as an array of strings separated by the '|' character (the file masks should be inside brackets). The filename gives the default file name of the file to open and may just contain a directory to start the dialog in that directory. Only a single file may be selected with the file dialog box. The returned value is the full chosen file name, or an empty string if cancel was pressed.

TOpenFileNames InputOpenFileNames(
    char title[],
    char filter[]="All files (*.*)",
    char filename[]="" )
Similar to InputOpenFileName except that multiple files may be selected. The results are returned in a structure TOpenFileNames that contains a count variable indicating the number of opened files (zero if cancel was pressed), and an array of file variables which each have a filename variable indicating the selected file. For example:

    int i;
    TOpenFileNames f = InputOpenFileNames( 
        "Open File Test", 
        "C Files|*.c;*.cpp|All Files|*.*" );
    for( i = 0; i < f.count; i++ )
        Printf( "%s\n", f.file[i].filename );

will print out all file names selected.

char[] InputSaveFileName(
    char title[],
    char filter[]="All files (*.*)",
    char filename[]="",
    char extension[]="" )
Uses a standard file save dialog box to select a file name suitable to use when saving a file. The user will be asked to overwrite a file if it already exists on disk. The title, filter and filename arguments are similar to the InputOpenFileName function. If no extension is given for the file name, a period and the extension argument will automatically be appended to the file name. The return value is the full chosen file name, or an empty string if cancel was pressed.

char[] InputString(
    const char title[],
    const char caption[],
    const char defaultValue[] )
Similar to InputFloat except that the string value of the edit box is returned instead of a float value. If Cancel is pressed, an empty string is returned.

wstring InputWString(
    const char title[],
    const char caption[],
    const wstring defaultValue )
Displays a dialog for the user to enter a wide string (unicode string). See the InputFloat function for an explanation of the different arguments. If Cancel is pressed, an empty string is returned.

Requires 010 Editor v3.1 or higher.

int InsertFile( const char filename[], int64 position )
Inserts all of the bytes in the file given by filename into the current file starting at position. A negative number is returned if the file cannot be inserted.

int IsEditorFocused()
Returns true if a Editor Window is currently focused. This function is useful if you want to build a script that controls the cursor of the Editor Window and only want the cursor to move when the window is focused.

int IsModified()
Returns true if any changes have been made to the file, or false otherwise.

int IsNoUIMode()
Returns true if 010 Editor is currently in -noui mode, or false otherwise. See Command Line Parameters for more information on -noui mode.

Requires 010 Editor v3.2 or higher.

int MessageBox( int mask, const char title[], const char format[] [, argument, ... ] )
Displays a message box to the user with a number of buttons to press. The buttons displayed depend upon an OR mask of four values. The Ok, Cancel, Yes, or No buttons can be displayed by using the constants idOk, idCancel, idYes, or idNo respectively (note that not all possible combinations are supported). The title is display in the title bar of the message box. The message to display is obtained using a syntax similar to printf (see Printf below). The return value is one of the constants idOk, idCancel, idYes, or idNo depending upon which button was pressed. For example, to display a message box with Yes and No buttons use:

 if( MessageBox( idYes | idNo, 
    "Script", 
    "Save changes to '%s'?", 
    GetFileName() ) 
      == idYes )
  . . .

void OutputPaneClear()
The Output Pane refers to the area where text from the Printf function is displayed (located in the Output tab of the Output Window). When this function is called, all previous output in the Output Pane is cleared.

Requires 010 Editor v3.1 or higher.

int OutputPaneSave( const char filename[] )
Saves all text in the Output tab of the Output Window to a file on disk. The filename argument gives the name of the target output file. This function returns 0 if the file was successfully written or a negative number if the file could not be written.

Requires 010 Editor v3.1 or higher.

void OutputPaneCopy()
Copies the text in the Output tab of the Output Window to the operating system clipboard.

Requires 010 Editor v3.1 or higher.

void PasteFromClipboard()
Inserts any bytes in the clipboard into the file starting at the current cursor position. If a selection has been made, the selected bytes will be deleted before the bytes are inserted.

int Printf( const char format[] [, argument, ... ] )
Similar to the standard C printf function. Accepts a format specifier and a series of arguments. The results of the Printf are displayed in the Output tab of the Output Window. The following codes can be used to specify different data types:

• %d, %i - signed integer
• %u - unsigned integer
• %x, %X - hex integer
• %o - octal integer
• %c - character
• %s - string
• %f, %e, %g - float
• %lf - double
• %Ld - signed int64
• %Lu - unsigned int64
• %Lx, %LX - hex int64

Width, precision, and justification characters are also supported (e.g. "%5.2lf", or "%-15s"). The newline character can be specified with '\n'. Consult documentation on the standard C printf function for more information.

int64 ProcessGetHeapLocalAddress( int index )
Each memory heap in a process is assigned a position in the current file. This function returns the starting local file address for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

wchar_t[] ProcessGetHeapModule( int index )
Returns the name of the module to which the given memory heap belongs. The module name is returned as a wide string and index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap or if the given heap is not associated with a module, an empty string is returned. For more information on heaps and modules see Editing Processes.

Requires 010 Editor v3.2 or higher.

int ProcessGetHeapSize( int index )
Returns the size in number of bytes for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned.

Requires 010 Editor v3.2 or higher.

int64 ProcessGetHeapStartAddress( int index )
Returns the starting address in memory for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned.

Requires 010 Editor v3.2 or higher.

int ProcessGetNumHeaps()
Returns the number of memory heaps for the current process. If the current file is not a process, 0 is returned. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

int64 ProcessHeapToLocalAddress( int64 memoryAddress )
Each heap in a process has two addresses: a memory address where the data actually exists in computer memory and a local file address where the data is located for editing in 010 Editor. Given an address memoryAddress in system memory, this function returns the equivalent address in the local file. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

int64 ProcessLocalToHeapAddress( int64 localAddress )
Each heap in a process has two addresses: a memory address where the data actually exists in computer memory and a local file address where the data is located for editing in 010 Editor. Given an address localAddress in the local file, this function returns the equivalent address in system memory. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

void RemoveBookmark( int index )
Removes a bookmark from the current file. The index argument specifies which bookmark to remove and its value should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). For information on creating bookmarks see AddBookmark.

Requires 010 Editor v3.1 or higher.

int RenameFile( const char originalname[], const char newname[] )
Renames a file on disk from originalname to newname. Note that the file should not be open in the editor when it is renamed. A negative number if returned if the rename fails.

void RequiresVersion( int majorVer, int minorVer=0, int revision=0 )
Indicates what version of 010 Editor is required to execute the current script or template. The execution of the script or template will stop if the current version of 010 Editor is less than the version number given by the majorVer, minorVer, and reversion parameters. For example, with 010 Editor version '3.0.2', the '3' is the major version, '0' is the minor version, and '2' is the revision number. Use this function to ensure that other people that are running your scripts or templates are using the proper version of 010 Editor.

void RunTemplate( const char filename[] )
This function can be called in a Script to execute a Template on the current file. The filename argument indicates which Template file to run and the filename can either be a full file path, or can be just the name of the file and 010 Editor will attempt to locate the Template using the same rules as locating Include files. For example, 'RunTemplate( "ZIPTemplate.bt" );' will attempt to locate the "ZIPTemplate.bt" file and execute it on the current file. If the Template cannot be located or if there is an error executing the Template, program execution will be stopped.

Requires 010 Editor v3.1 or higher.

void SetBackColor( int color )
void SetColor( int forecolor, int backcolor )
void SetForeColor( int color )
These functions are used when writing a Template to apply color to different variables. All variables defined after calling one of these functions will be displayed in the given color. SetForeColor sets the foreground (text) color, and SetBackColor sets the background color. Use SetColor to set both the foreground and background color at the same time. A color is an integer made up of 3 hex bytes specifying the blue, green, and red components of the color. The following constants are defined and may be used when setting colors:

• cBlack - 0x000000
• cRed - 0x0000ff
• cDkRed - 0x000080
• cLtRed - 0x8080ff
• cGreen - 0x00ff00
• cDkGreen - 0x008000
• cLtGreen - 0x80ff80
• cBlue - 0xff0000
• cDkBlue - 0x800000
• cLtBlue - 0xff8080
• cPurple - 0xff00ff
• cDkPurple - 0x800080
• cLtPurple - 0xffe0ff
• cAqua - 0xffff00
• cDkAqua - 0x808000
• cLtAqua - 0xffffe0
• cYellow - 0x00ffff
• cDkYellow - 0x008080
• cLtYellow - 0x80ffff
• cDkGray - 0x404040
• cGray - 0x808080,
• cSilver - 0xc0c0c0,
• cLtGray - 0xe0e0e0
• cWhite - 0xffffff
• cNone - 0xffffffff

The cNone constant indicates that no color should be applied.

void SetCursorPos( int64 pos )
Sets the cursor position in the current file to pos. A flashing caret will visually indicate the cursor position in the file.

int SetReadOnly( int readonly )
Sets the read-only status of the current file to true or false. A negative number is returned if the read-only status could not be changed.

void SetSelection( int64 start, int64 size )
Selects size bytes from the file starting at the address start. The selected bytes will appear blue in the main window.

void Sleep( int milliseconds )
Halts program execution for the given number of milliseconds. For example, 'Sleep(2000);' would cause a pause of two seconds.

Requires 010 Editor v3.1 or higher.

void Terminate( int force=true )
Exits out of the script and then shuts down 010 Editor. If force is true, all open files will be closed and any unsaved modifications will be lost. If force is false and files are modified, the user will be asked if they want to save the files and optionally given a chance to cancel the shut down procedure.

void Warning( const char format[] [, argument, ... ] )
Similar to the Printf function except the resulting string is displayed in the Status Bar of the application and is highlighted orange. This is useful to display an error that occurs in a Template.