Script Debugger Walkthrough (XSISDK)

This walkthrough demonstrates the use of script debugging techniques, including the use of an external debugger to find and fix bugs in your Jscript code.

Note: The external script debugger requires the use of a third party software, in this case Visual Studio .Net 2003 (http://msdn.microsoft.com/vstudio/productinfo/). Other script debuggers have different user interfaces but will function is a similar fashion. Unfortunately there are no script debuggers available on Linux capable of debugging an XSI script.

Note: The examples in this walkthrough use JScript, but very similar approach would also be true for vbscript.

Table of contents

Part 1 - Fixing Syntax Errors

As a typical scenario a self-installed plug-in is created, containing a single command, "DebuggerDemo". This is the initial script, which contains no errors but does nothing.

function XSILoadPlugin( in_reg )
{
	in_reg.Author = "Softimage";
	in_reg.Name = "DebuggerDemoPlugin";
	in_reg.RegisterCommand("DebuggerDemo","DebuggerDemo");
	return true;
}

function DebuggerDemo_Init( ctxt )
{
	var oCmd;
	oCmd = ctxt.Source;
	oCmd.ReturnValue = true;

	return true;
}

function DebuggerDemo_Execute(  )
{
	return true;
}

The problem arises when some buggy code is added to the custom command implementation. You have created a configuration file called "C:\importoptions.txt" and you wish to read its contents using the FileSystemObject (which is an built-in object for JScript and VBScript usage).

This code initially contains several errors.

function DebuggerDemo_Execute(  )
{
	var strFile = "C:\importoptions.txt ;

	var oFSO = new ActiveXObject( "Scripting.FileSystemObject" );	
	var oFile = oFSO.OpenFile( strFile ) ;	

	return true;
}

As soon as this file is saved XSI complains in the script history window about a syntax error:

//ERROR : Unterminated string constant - 
[line 20 in C:\users\askowron\Softimage\XSI_5.0\Application\Plugins\DebuggerDemo.js]
//ERROR : 2262 - This plug-in could not be loaded:
//<path: C:\users\askowron\Softimage\XSI_5.0\Application\Plugins\DebuggerDemo.js>

Any syntax error will also appear in the Plug-in Manager once the "Update All" button is pressed.

Image:SyntaxErrorInPluginManager.jpg

On Windows the text between the [] characters is a hyperlink, so when you click on it the following line is highlighted. (On Linux you can right click on the line to find an "Edit" option which does the same thing). This points us to the line with the syntax error:

var strFile = "C:\importoptions.txt ;

Usually syntax errors are very easy to track down and fix because XSI is able to detect them as soon as the file is saved. In this case there was just missing a " character.

var strFile = "C:\importoptions.txt" ;

Once this fix is made and the file is saved the Plug-in will load without complaint. But it still contains bugs!

Part 2 - First Runtime Error

Now that there are no syntax errors XSI thinks the Plug-in is working. However scripts often contain bugs that don't appear until they are actually executed. In this case the way to execute our code is to call the DebuggerDemo() command, which can be done by the Plug-in Manager, as shown:

Image:InvokeCommand.jpg

This results in a script error, which lists the following important information in the script history window:

//ERROR : Object doesn't support this property or method - 
[line 23 in C:\users\askowron\Softimage\XSI_5.0\Application\Plugins\DebuggerDemo.js]
//ERROR : 2006-CUST-DebuggerDemo - Unexpected failure.

We find that this line refers to:

var oFile = oFSO.OpenFile( strFile ) ;	

The error message is clearly saying that OpenFile is not a method of the File System Object. By referring back to the JScript documentation (e.g. Script56.chm or online (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/jsorifilesystemobjectmethods.asp)) you realise that the real method name is "OpenTextFile".

So the fix is to change the method name and resave the file:

var oFile = oFSO.OpenTextFile( strFile ) ;

This fixes one of the bugs, but unfortunately this fix will just unearth a more tricky bug.

Part 3 - Second Runtime Error

When the DebuggerDemo command is invoked again you find that XSI complains about the same line number, but with a new error message.

//ERROR : File not found - [line 23 in C:\users\askowron\Softimage\XSI_5.0\Application\Plugins\DebuggerDemo.js]
//ERROR : 2006-CUST-DebuggerDemo - Unexpected failure.

At first glance the error message seems to be extremely useful. You check on your harddrive but find that C:\importoptions.txt really does exist. It opens fine in a text editor so it isn't corrupt or having some permission problems. Now you start scratching your head and feeling perplexed. Everything looks correct to you but it just doesn't work!

So now is time to start using a script debugger. Script debugging is off by default, but it can be enabled by right clicking on the script editor window and selecting the menu item shown below:

Image:EnableScriptDebugger.jpg

Note: If the debugger was already enabled the text would have said "Disable External Script Debugger".

Now you invoke the command again. A new window appears when the offending line of code is executed:

Image:JustInTime.jpg

The contents of this window will vary according to what debugger applications are installed and whether they are already running. In this case you actually have two possible script debugger programs installed: Microsoft Script Editor 6.0 and Microsoft Visual Studio .Net 2003. (If no debugger was installed this dialog would not appear at all and debugging would not be possible.) You could use either program in a similar fashion, but you choose Microsoft Visual Studio .Net 2003.

Click OK on this dialog:

Image:AttachToProcess.jpg

Visual Studio now appears, showing the same error message that XSI displayed, and highlighting the offending line of code.

Image:Debugger.jpg

You click on Break to start debugging.

Now that the script is loaded in Visual Studio there is a wealth of debugging services available. One of the most useful windows is the "Locals" Window which shows the values of all the variables.

Image:DebugLocalWindow.jpg

Looking at this it is clear that the slash character is missing from the filename, so that rather than C:\importoptions.txt, your script is accidentally trying to open C:importoptions.txt. It is at this point that you remember that "\" is a special character in JScript, so that in fact "\\" is the correct way to specify a single slash.

So the required fix is not on the line with the script error, but earlier in the script:

var strFile = "C:\\importoptions.txt" ;

You try to add this fix in Visual Studio, but it complains with an error "Cannot currently modify this text in the editor. It is read-only". You also notice that the filename of the script is not DebuggerDemo.js, but "NSID", followed by some random looking characters. Visual Studio is able to debug the script, but not directly edit the original script file. However now that you know what the error is you can go back to XSI to make the fix directly.

You find that XSI is currently frozen because of the script debugging session. You need to finish the command execution in order to return to XSI.

If you hit "F5" to continue execution Visual Studio will just show the error message again and remain stuck at line 23. You need to force the script past that bad line, so you move the cursor to the beginning of the next code line ("return true") and right click to show this context menu:

Image:SetNextStatement.jpg

The Set Next Statement option moves the script past the bad line so you can continue its execution and return to XSI.

An alternative to moving the script execution point is to completely detach the debugger:

Image:DebugDetachAll.jpg

Doing this will return you to the Just-In-Time debugger dialog (shown earlier). This time you should pick Cancel to return to XSI.

Once you return to XSI you can add the extra slash and have the satisfaction that all your code finally works.

Part 4 - Logic Error

The previous code was able to open a text file, but you would need to go further to do something with the file. Suppose your file "C:\importoptions.txt" is a very simple file format that just lists various options on separate lines. In your testing it contains just these two lines:

importmaterials
fastimport

You add some next code to read the file contents and look for the "fastimport" option.

function DebuggerDemo_Execute(  )
{
	var strFile = "C:\\importoptions.txt" ;

	var oFSO = new ActiveXObject( "Scripting.FileSystemObject" );	

	var oFile = oFSO.OpenTextFile( strFile ) ;	
			
	strFileContent = oFile.ReadAll() ;
	arrayFileLines = strFileContent.split( "\n" ) ;
	
	for ( var i = 0 ; i < arrayFileLines.length ; i++ )
	{
		if ( arrayFileLines[i] = "fastimport" )
			logmessage( "Found fastimport" ) ;
	}
	
	return true;
}


When you run the command you see the following output:

//INFO : Found fastimport
//INFO : Found fastimport
DebuggerDemo();

How could your code find the fastimport option more than once! There is obviously a bug, but what is it?

In the previous cases XSI was giving you a clear error message, but now your code is running without any error messages. But it is doing the wrong thing! So there is an error in the logic of the script itself. Because there is no script error XSI does not automatically go to the script debugger.

To solve a logic error you need to force the code to go into the debugger. You add the line "debugger" to your script. (Note: the equivalent in vbscript is "stop").

When you invoke the command again it puts you back into the debugger:

Image:DebuggerStatement.jpg

Now you can start stepping through the code, examining variables and trying to understand your program.

You step into the for loop and use the QuickWatch window to look at the contents of the Array.

Image:DebugQuickWatch.jpg

It contains exactly the content of the file so everything seems good.

You proceed to the end of the function, then choose to look again at the variable contents:

Image:DebugQuickWatch2.jpg

You see that the array has changed its contents! That is not expected, the code is trying to read that array, not change it. This type of unexpected effect gives you the extra information you need to realise the cause of the bug. It suddenly dawns on you that this line:

if ( arrayFileLines[i] = "fastimport" )

should be doing a JScript comparison, not assignment. So the correct code should be:

if ( arrayFileLines[i] == "fastimport" )

You hit F5 to continue the script execution. Unlike the runtime error scenarios you don't need to detach or use the "Set Next Statement" feature - XSI can just continue the script execution until the command is finished.

You make the fix in XSI and further testing shows that the bug is now fixed. Now that everything is working well you remove the "debugger" statement from the code so that it doesn't launch the debugger anymore when executed.


This page was last modified 07:57, 31 Aug 2007.
This page has been accessed 16575 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy