Troubleshooting and Debugging
Visual DataFlex 9.1 Web Applications

A Data Access Worldwide White Paper
by Dennis Piccioni

January 27, 2004
Last Edited: January 30, 2004

This paper will show you:

• How to debug ASP scripting code and Visual DataFlex code in VDF Web Applications.
• Where to find more information than meets the eye if you encounter problems with Web Applications .
• How to deal with common Web Application errors.

• Debugging Techniques

  • Visual DataFlex Web Application Basics

  • Types of Code Debuggers

  • Using DebugHelp

  • Logging Your Own Events to the VDF Web Application Event Log

  • A Debugging Scenario

• Log Files

  • Visual DataFlex Web Application Event Log

  • Windows Event Viewer

• Common Error Messages

  • HTTP Error 404 'File not Found'

  • ASP Error '80004005' Unspecified Error
  • Microsoft VBScript compilation (0x800A03F6)
  • The page cannot be displayed HTTP 500.100 - Internal Server Error - ASP error
• Tips
  • VDF Web Application Debugger Limitations
  • Use Option Explicit to Force Variable Declarations in ASP code
  • Install Microsoft Internet Information Manager on Windows NT Workstation

• Terms

• Additional Resources

Debugging Techniques

Visual DataFlex Web Application Basics

A VDF Web Application consists of 2 areas where coding is done: ASP and VDF. When an ASP page that is part of a VDF Web Application is accessed from a browser, code execution starts on the ASP side. Then, code on the VDF side is called from ASP scripting code.

Here is a brief sample of what happens when a VDF Web Application report is called:

Top of page:  (static HTML)
   print title of report

Middle of page:  (ASP script code)
    call VDF function that runs report
    (VDF report writes the report: a list of customers)

Bottom of page: (static HTML)
    print footer of report

The basic order of code execution is this:

1. An ASP page is accessed in a browser.
2. The ASP page code is executed from top to bottom, just as normal HTML is executed.
3. If script code is encountered, the ASP script code executes, including making calls to VDF functions.
4. The VDF functions execute.
5. The ASP page code execution continues.

ASP script code can do a lot of other things besides making calls to VDF programs, but this is how VDF Web Application code is called and executed.

Types of Code Debuggers

Since a VDF Web Application has 2 areas in which programming code is created, the VDF side and the ASP side, it is important to have the ability to debug code on both sides:

• Visual DataFlex Code

  Visual DataFlex has a Debugger which can debug VDF code, including VDF code in VDF Web Applications.

• ASP Script Code

You should install a script debugger to enable you to debug code on the ASP side. We do not consider this optional for developing Web Applications!

If you have certain Microsoft development tools installed, such as Visual Studio or Visual Studio .Net, you may already have one or more script debuggers installed. The Microsoft Script Debugger is available as a free download from Microsoft. See the Additional Resources section for more information. 

This paper will teach you how to get started using both debuggers, but you should plan to spend time learning both debuggers as expertly as possible. 

Using DebugHelp

An include file named DebugHelp.inc is added to each Web Application’s AppHtml\inc directory. This file allows you to turn on a "trace" mode, which will show all request data submitted to your ASP page by your browser. This is a very useful feature. It lets you see what data is actually being submitted to a server page. Often you will discover that a source of an error is that data being passed back to the server is different to what you expect. Also, this debugging feature is a great learning tool – it shows you how the POST/GET process works.

When trace debugging is enabled, all HTTP request information sent to a server page will be displayed as part of this server’s page HTML output. In other words, you will see the request information in your browser. Here is an example of what that output will look like:

----DEBUG INFORMATION----
content_length = 627
request_method = POST
Customer__Recnum= 1
customer__customer_number= 1
customer__name= Data Access Worldwide
customer__address= 14000 SW 119 Ave
customer__status= Y
customer__city= Miami
customer__state= FL
customer__zip= 331866017
customer__phone_number=
customer__fax_number=
customer__email_address=
customer__credit_limit= 6320
customer__purchases= 10640
customer__balance= 10640
CUSTOMER__COMMENTS= Innovative software company & makers of Visual DataFlex...
ChangedStates=
findnext= >
Index= 1
Querystring =
----END DEBUG INFORMATION----

Adding DebugHelp to your ASP page

If you created your ASP page using the wizards, the code required to display request information has already been added to your page. If you are creating this code manually you will need to add two lines of code to your ASP page after the <body> HTML tag as follows:

<body>
<% ' DebugMode =1 ' uncomment this for page get/post debug help %>
<!-- #INCLUDE FILE="inc/DebugHelp.inc" -->

Look at the Customer.asp file in the WebAppSample91 sample application for an example of this.

Enabling DebugHelp in your ASP page

To enable the debug help feature you need to set the VbScript variable DebugMode to 1.
Find line of code that reads <% ‘ DebugMode =1….%> and remove the comment. The line would look like the following:

<% DebugMode =1 ' uncomment this for page get/post debug help %>

Using the DebugMode variable for conditional debug code

Additionally, you can use the DebugMode variable to create pockets of conditional debug code within your application. You do this by creating an "If" statement block that tests for DebugMode as follows:

<% If DebugMode>0 then %>
       ....place your debug asp code here
<% end if %>

Here is an example of how this might be used:

<% If DebugMode>0 then %>
Test code start<br>
The current customer record is <%=oCustomer.ddValue("Customer.Recnum") %>
Test code end<br>
<% end if %>

If debug mode is enabled, the following would be displayed in your browser page:

Test code start
The current customer record is 123
Test code end

When debug mode is disabled, you would not see this code.

Once debug mode is enabled, it will remain enabled until the session ends, or until the mode is explicitly turned off. This is very useful. Once debug mode is enabled, all pages that use the DebugHelp.inc will display debug information.

You can and should experiment with debug mode by running the WebAppSample91 application.

Logging Your Own Events to the VDF Web Application Event Log

You can write to the VDF Web Application Event Log from a Web Application using the LogErrorEvent and LogEvent messages. Both of these messages can be called from VDF or ASP code. See the Visual DataFlex Help for more information about these messages.

• LogErrorEvent can be useful for adding custom errors to your application (e.g. log an error someone attempts to login to an application and enters the wrong password).
• LogEvent can be useful for debugging or logging events in your application (to track certain operations, for example).

Example

Function DoRequestSave String sFilename Returns Integer
    Integer iVoid iEventType
    move 5 to iEventType
    Forward Get DoRequestSave sFilename To iVoid
    send LogEvent iEventType "Saving new record"
    Function_Return iVoid
End_Function // DoRequestSave

This example augments the DoRequestSave method a WBO to log a message to the event log whenever a new record is saved.

Example

dim iEventType
iEventType = 5
oOrderWBO.Call "msg_LogEvent", iEventType, "Saving an order"

This example makes logs the message "Saving an order" to the VDF Web Application Event Log using VBScript code in an ASP page.

Example

oOrderWBO.Call "msg_LogErrorEvent", DfErr_Operator, "Attempt to enter an invalid value for Customer City"

This example makes logs the message "Attempt to enter an invalid value for Customer City" to the VDF Web Application Event Log using VBScript code in an ASP page.

When logging error events, you should use the predefined "generic errors" for the event numbers. The generic errors are reserved specifically for this type of use in applications. The generic errors are DfErr_Operator, DfErr_Program, DfErr_Compile and DfErr_Setup. Most likely, you will use the generic errors DfErr_Operator and DfErr_Program most often in your applications.

A Debugging Scenario

To see how to debug a VDF Web Application, and what happens during a VDF Web Application event, let's work through the scenario of saving a customer record in the WebAppSample91 sample application.

To set up this scenario, do the following:

1. Open the Visual DataFlex Studio and open the WebAppSample91 workspace.
2. Open the WebApp Sample application.
3. Debug-run the program.
4. Once the application is running, switch to the browser and click on the Login (for edit rights) page.
5. Login using the username and password provided on the page.
   Logging in here enables saving and deleting of records in this sample application.
6. Now click on the Customers page.
7. Click on the > button to find the first record in the Customer table.

When the Save button on the Customers page is clicked, code execution begins in the ASP page. So, the first place to see what is happening is in the ASP code:

1. In the Visual DataFlex Studio, select Open Web Markup from the Open Component toolbar combobox and open the Customer.asp file.

2. Search for "Save" in Customer.asp. Stop when you reach this code:

if Request("save")<>"" then

This code checks whether the Save button has been clicked.
We want to stop program execution when this happens.

3. Add a stop statement right after the line of code above. The resulting code should look like this:

if Request("save")<>"" then
    stop
    oCustomer.call "set_pbReportErrors", 0

1. Click on the Save button on the Customer page.

When the application reaches the stop statement, the application will break and start the Script Debugger.
The Script Debugger will display the Customer.asp page and execution will be stopped on the line with the stop statement.

Note: If the Script Debugger does not start, the application never got to this line of code. In this case, you can place a breakpoint on the first line of the ASP page, then step through each line of code to determine what is happening.

4. In the Script Debugger, Step Over lines of code until you reach this line:

err = oCustomer.RequestSave("Customer")

This line calls the RequestSave function in the Visual DataFlex code of the application.
The next step is to stop execution in the VDF code when the call gets to the VDF side of the application.

From the VDF documentation for the RequestSave function, we know that it calls the DoRequestSave event. We will place a breakpoint in this event in the VDF code. This event is not in the local code of most VDF Web Applications, but in the global packages distributed with VDF that are compiled as part of the application. We need to determine where, so we can place the breakpoint.

5. In the Visual DataFlex Studio, search for text in multiple files.
   Type "Function DoRequestSave" into the Text to find form.
   Choose "Global Source" from the "Workspace Zone" comboform.

The search returns RemoteEntryMixin.pkg.

6. In the VDF Debugger, select RemoteEntryMixin.pkg from the source code comboform.
   Search for "Function DoRequestSave". Stop when you reach this code::

Function DoRequestSave String sFileName returns integer

7. Place a breakpoint on the line "Get pbAllowSaveNew to bAllowSaveNew".
   If you are new to the VDF Debugger, click on the blue dot to place the breakpoint. The blue dot should turn red to indicate that the breakpoint is set.

Now we can return to the Script Debugger, where the execution of the ASP code is still stopped at the oCustomer.RequestSave call.

8. In the Script Debugger, Run the program to continue execution.

A message box will pop up telling you the VDF Debugger has encountered a breakpoint.

9. Click Ok on the message box and switch to the VDF Debugger.
   The debugger is stopped at the breakpoint in DoRequestSave in RemoteEntryMixin.pkg.

This tells us the program has properly executed the call from the ASP code to the VDF code.

Another method of checking whether DoRequestSave is called and what is being sent to it is to intercept this function at the WBO code level. This will allow us to place a breakpoint right in the WBO code instead of the global product package code. Intercepting the function at the WBO level could also be used to customize the save process. 

11. Close the browser running the WebAppSample91 application.
    Doing so will also cause the VDF Debugger to close.
    
    In the Visual DataFlex Studio, open the Customer.wo.
    
    To intercept DoRequestSave at the WBO level, add the following code to the code of object oCustomer, right below the end of Function RunCustomerReport:

Function DoRequestSave String sFilename Returns Integer
    Integer iVoid
    Forward Get DoRequestSave sFilename To iVoid
    Function_Return iVoid
End_Function // DoRequestSave

12. Compile and debug-run the program.
    Follow the same steps as above to login, go to the Customers page and find a customer record.

13. In the VDF Debugger, open the Customer.wo file and search for "Function DoRequestSave".
    Once you have found the augmented code we placed in this WBO, place a breakpoint on the line "Forward Get DoRequestSave sFilename To iVoid".

14. Click on the Save button on the Customer page.
    When the Script Debugger stops again at the stop statement, run the program to continue execution.
    
    A message box will pop up telling you the VDF Debugger has encountered a breakpoint.

15. Click Ok on the message box and switch to the VDF Debugger.
    The debugger is stopped at the breakpoint in DoRequestSave in Customer.wo.

Log Files

There are 2 logs you should always check for more information when you are troubleshooting Web Applications.

1. Visual DataFlex Web Application Event Log

This log contains application-specific error messages.

To view the VDF Web Application Event Log, follow these steps:

1. In the VDF Web Application Administrator, expand the TreeView of web applications and select the application in question.

2. Expand the tree for the application and select the Event Log.

Tip: You may see a lot of "Session Started" and "Session Closed" entries in the Event Log. If you do not want to log each of these events, and instead only want to log error messages from your web application, do the following:

1. Right-click on your application and select Properties.

2. Uncheck the "Log all Access to the Web Application" checkbox.
   This will stop all events from being logged, but will still log errors.

3. Make sure the Maximum log entries is set to 0 for unlimited entries. 

2. Windows Event Viewer

This log contains error messages that are not specific to any particular Web Application, but are more systemic to Visual DataFlex Web Applications, such as invalid registration codes. Here you will also see error messages about other applications that may affect VDF Web Application Server, such as Internet Information Server errors.

To view the Windows Event Viewer's Application Log, select 

1. Start > Control Panel > Administrative Tools > Event Viewer.

2. Select Application in the TreeView.

You can also launch the Windows Event Viewer from the VDF Web Application Administrator's Tools menu.

Common Error Messages

Here are steps to analyzing and solving some of the most common Web Application errors. Please also see the Additional Resources section.

•  HTTP Error 404 'File not Found'

  This error means that the browser could not show the requested page. The error is also often 'Page not Found' or 'Object not Found', but as long as the error code is 404, the cause is the same. This error code is returned from the server that is supposed to serve the page, rather than the browser itself. The the most 'typical' reason why you might see this error when working with VDF Web Application Server is that the file you are trying to access (usually default.asp) is not listed as a default document for the virtual directory.

  To resolve this, do the following:

  • Verify that you are actually accessing the right document (check the URL).
  • Verify that the correct default documents are set up for the virtual directory (see default document section for details).

• ASP Error '80004005' Unspecified Error

error '80004005'
Unspecified error
/VirtualDirectoryName/global.asa, line 15

This error can occur for any number of reasons. There are a number of ways of obtaining more meaningful information when this error occurs.

1. Check the Windows Event Viewer.
2. Check the event log for the VDF Web Application in question.
3. Make sure there is a program filled in (and it is the correct program) for the Web Application in the VDF Web Application Administrator.

1. Open the VDF Web Application Administrator
2. Expand the TreeView of applications and select the application in question
3. Right-click and choose Properties
4. Make sure the correct program is entered into the Filename window
5. While here, also make sure that the Disable Web Application checkbox is not checked

4. Debug-Run the Application

• There might be an error message or other Windows popup dialog that may be hidden when running the application in normal mode using the VDF Web Application Server. When running in debug mode, you will see these types of things.
• You may be able to stop the Application's execution in the debugger and see where the program is "stuck". 

• Microsoft VBScript compilation (0x800A03F6)

  Microsoft VBScript compilation (0x800A03F6)
  'End' expected
  /packing/inc/DebugHelp.inc, line 14

  You will sometimes encounter this error pointing to one of the include files provided with VDF (typically DebugHelp.inc). Most likely this is caused by some other scripting error in your ASP code, such as a missing 'end if', and the error is only 'caught' in the include file. Your best bet for debugging this problem is usually to double-check the last area of ASP code you worked on.

Tips

• VDF Web Application Debugger Limitations

  The Visual DataFlex Web Application Server Debugger is a separate program from the Visual DataFlex Web Application Server, which runs on a Windows Server as a Service. As a result of this, the following are not supported:

  • Debugging with Process Pooling

    When you enable Process Pooling in a VDF Web Application, the Application will run using Process Pooling in the VDF Web Application Server, which supports process pooling, but not in the VDF Debugger, which does not support process pooling. You can still debug your application if Process Pooling is enabled, it just won't run in the Debugger as a Process Pooled session.

  • Remote Debugging

  The Visual DataFlex Debugger only supports debugging applications locally on the same machine. Remote debugging is not supported with either Windows or Web applications. However, you can run the application on your machine and connect to a database on a separate machine. This is probably the most common configuration for Windows applications. This involves setting the various paths in the workspace file so that it points to the remote machine. Often this is accomplished by using relative pathing and referencing the .exe file and the workspace located on a separate machine.

• Use Option Explicit to Force Variable Declarations in ASP code

  By default, variables in VBScript do not need to be declared. This can easily cause problems that go undetected during development, for example, an accidental change of a variable name will not be trapped as an error.

  The option explicit statement causes declaration of errors for undeclared variables. We highly recommend always using this option.

  Example:

  option explicit
  dim Error
  iError = oCustomerWBO.RequestSave "Customer"

  In this example, the last line would generate a VBScript error message, because the declared variable Error does not match the used variable iError:

Microsoft VBScript runtime error '800a01f4'
Variable is undefined: 'iError'
/VirtualDirectoryName/FileName.asp, line ###

• Install Microsoft Internet Information Manager on Windows NT Workstation
  
  If you are running Windows NT Workstation, the Microsoft Internet Information Manager is not installed. This is an excellent tool that you should install. To install this tool, check the following options during the Windows NT 4 Option Pack Installation (or reinstallation):
  • Leave all the default options as they are.
  • In addition, check the following:
    • "Personal Web Server" > click on "Show Subcomponents" and check "Internet Service Manager".
    • "Microsoft Management Console"

Terms

Here are some brief explanations of terms that are important when working with Visual DataFlex Web Applications. You are expected to be familiar with some of the terms that are not explained here (i.e. HTML, URL).

• Active Server Pages (ASP)

Software technology by Microsoft that allows execution of HTML code with embedded scripting.

• Internet Information Server (IIS)

HTTP server software by Microsoft, which allows, among other things, execution of ASP pages. The minimum IIS version requirement for Visual DataFlex Web Application Server is 4.0.

• Default Documents

Any virtual directory used by IIS can have a set of HTML and/or ASP pages listed as default documents. This means that, when the URL of the virtual directory is typed into the browser's location bar without specifying a page in the virtual directory, the server automatically looks for any default documents specified and displays the first default document found in the browser.

For example, when launching the WebAppSample91 sample application, you typically access the URL http://localhost/DAW.Examples.Web.WebAppSample91, but http://localhost/DAW.Examples.Web.WebAppSample91/default.asp is actually loaded in your browser.

Here is how to configure default documents for a virtual directory:

1. Start > Control Panel > Administrative Tools > Internet Information Services
2. Expand Servers + the Server name your application is hosted on + Web Sites + Default Web Site
3. Select the virtual directory for your application
4. Right-click and select Properties
5. Choose the Documents tab
6. Make sure that "Enable Default Document" is checked
7. Make sure that the correct default documents are listed

• Virtual Directory

A Virtual Directory maps a physical folder on a disk drive (the ASP/HTML folder of a Web Application) with a URL. It provides for an access method to a Web Application on a Web Server.

For example, the virtual directory for the WebAppSample91 sample application is DAW.Examples.Web.WebAppSample91. The physical folder for this virtual directory is C:\Program Files\Visual DataFlex 9.1\Examples\Web\WebAppSample91\AppHtml.

When accessing it on the local machine (the machine you are currently working on), the Web Server is usually be accessed via http://localhost. The combination of the server name and the virtual directory name results in the URL to your application: http://localhost/DAW.Examples.Web.WebAppSample91.

• Web Business Object (WBO)

This is the most common programming component on the VDF code side of a WebApp. A WebApp is usually made up of one or more WBOs, each of which contains a set of DataDictionaries, methods and child objects.

Additional Resources