Testing and Debugging

docs.intersystems.com

Home / Application Development: Creating Productions / Developing Productions / Testing and Debugging

Developing Productions

InterSystems: The power behind what matters

This topic explains the facilities available for testing and debugging productions. The information is also useful for troubleshooting and tuning production software that is already in use at the enterprise. Topics include:

Correcting Production Problem States

If a production is Suspended or Troubled, read this section.

Recovering a Suspended Production

A production acquires the Suspended status when, at the end of the shutdown sequence, some queues still contain synchronous messages. If this is the case, you can start the Suspended production again to permit these messages to be processed.

However, if the problem that originally caused the Suspended status is not resolved, starting a Suspended production can just as easily add more synchronous messages to a queue, without discharging the previous messages and return the production to a Suspended status.

You may stop a Suspended production. InterSystems advises you do so only during initial development and not on a deployed, live installation.

If you find this is the case, you may sometimes need to take more drastic action to fully clean up after a production that goes into the Suspended state. InterSystems IRIS™ provides the CleanProduction() method for this case.

Caution:

Never use this procedure on a live, deployed production. The CleanProduction() method removes all messages from queues and removes all current information about the production. Use this procedure only on a production that is still under development. If a live, deployed production goes into a Suspended state, contact the InterSystems Worldwide Response Center (WRC) for assistance.

If you have exhausted all means to correct the problem and, therefore, are sure that a Suspended production must stop, discarding even synchronous messages that have not yet been delivered, then use the following procedure:

Start the Suspended production from the [Interoperability] > [Production Configuration] page by clicking Start in the ribbon bar; the production status changes to Running.
Now click Stop to verify the problem still exists. If the production stops successfully, there is no need to clean the production; if the production status returns to Suspended, continue with the next step.
Kill the production from a Terminal session as follows:
1. Change to the appropriate namespace:
```
  ZN "EnsSpace"
```
  Where EnsSpace is the name of the production-enabled namespace where the Suspended production runs.
2. Enter the following command:
```
  Do ##class(Ens.Director).CleanProduction()
```
Verify the production status from the [Interoperability] > [Production Configuration] page; the Status of the production should now be Stopped.

Important:

Only run the CleanProduction() method on a production in a Suspended state.

Recovering a Troubled Production

A production acquires a status of Troubled if InterSystems IRIS is stopped but the production did not shut down properly. This can happen if you restarted InterSystems IRIS or rebooted the machine without first stopping the production.

In this case the Recover command appears on the [Interoperability] > [Production Configuration] page. Click Recover to shut down and clean up the troubled instance of the production so that you can run a new instance when you are ready.

Or you may need to use the command line to recover the production. See “Using Ens.Director to Start and Stop a Production,” earlier in this book.

Testing from the Management Portal

You can use the Management Portal to perform several tasks as you develop, test, and debug your productions:

Ability to view and modify system configuration.
Ability to start and stop a production.
Ability to view queues and their contents; messages and their details; adapters and actors and their status; business processes and their status; code and graphical representations of configured items.
Ability to view, sort, and selectively purge Event Log entries.
Ability to suspend (and later resend) messages whose connectivity is temporarily blocked.
Ability to filter and search the message warehouse for specific messages, by category or message content, using a graphical user interface or by entering SQL SELECT commands.
Ability to visually trace message activity using a graphical user interface.
Ability to create and view statistical reports.

Portal features that are most useful for developers are the Monitor Service, which constantly collects runtime data, the Testing Service, which you can use to issue simulated requests into a production that you are developing, and the Event Log, which logs the status messages issued by business hosts. Use these features together to generate test data and study the results.

For information on using the portal, see Managing Productions.

The Management Portal has a Test menu where you can test both business hosts and data transformations. It contains the following items:

Business Hosts — The [Interoperability] > [Testing Service] page allows you to test business processes and business operations.
Data Transformations — This option brings you to another page, where you can select a data transformation and click Test. For details, see the Testing Data Transformations section.

Using the Testing Service

The [Interoperability] > [Testing Service] page allows you to test a business process or business operation of a running production in the active namespace. You can navigate to the Testing Service from the following locations in the Management Portal:

From the Interoperability menu, click Test.
From the configuration diagram on the [Interoperability] > [Production Configuration] page, click a business process or business operation in the left pane and click Test on the Actions tab.

Now, to use the Testing Service:

Make sure the appropriate production is running. See Managing Productions.
Make sure that testing is enabled for this production. Access the [Interoperability] > [Productions] as usual. With the production selected, select the Testing Enabled check box, click Apply, and then click OK.
In the Management Portal, click Interoperability, click Test and then Business Hosts to display the [Interoperability] > [Testing Service] page.

This page provides options that let you select either a Business Process or Business Operation as the target of your testing.
Select either Business Process or Business Operation as appropriate.
Select the testing target from the drop-down list.
Select the type of message to send. The page displays the following fields:
- Current Production — The name of the currently running production (view-only).
- Target — The business process or business operation that you selected in the previous Testing Service page (view-only).
- Request Type — Select from a list of request messages. Only the request types that are valid for the Target are listed, including subclasses of supported types.
Enter values for the properties of the message that you selected.

If the request message has no properties, none are displayed.

If you are testing a virtual document message, there is a free-form box where you can paste test message content. Below this box you can enter object properties for the message.
Click Invoke to submit the request with the values you entered and view the results.

If time elapses while the Testing Service attempts the request, a Waiting page displays the following view-only information:
- Target — The session ID associated with the request.
- Request Type — The request type of the selected target.
- Session Id — The session ID associated with the request.
- Request Sent — The date and time when the request was sent.
- Response received — The status Waiting and a graphical progress bar, indicating that work is being done.
Finally, the Results page displays any output values from the response generated by your request, including any errors with the full error message text.

You can perform one of the following commands when the test completes:

Click Done to return to the home page.
Click Trace to navigate to the Visual Trace page to visually follow the path of the message through the production.

You can also use the classes and methods in the EnsLib.Testing package. See the EnsLib.Testing.Service entry in the Class Reference for details.

Debugging Production Code

The first step in debugging is to enable tracing as described in Monitoring Productions Productions. If this does not reveal the problem, you can step into the code using the debugger, as follows:

Using Studio, insert the BREAK command where you want to start debugging.
Enable the Foreground setting for the business host that uses the class you want to debug.
Start the production. The job that you marked in Step 2 runs in the foreground in the Terminal.
When that BREAK command is reached, the Terminal enters debug mode and you can step through the code.

For details, see “Command-Line Routine Debugging” in Using ObjectScript.

You can also debug your code in Studio:

With a business service, you still specify that it should be run in the foreground and use a BREAK to get the process ID.
With a business process, you can use Studio to set a breakpoint and then attach to the process to debug using Studio. In contrast, if you use BPL, Studio displays in .INT code.
With a business operation, you can use Studio to set a breakpoint and then attach to the operation process to debug.

For details, see “Using the Studio Debugger” in Using Studio.

Enabling %ETN Logging

The Event Log automatically includes partial information about system-level exceptions (including exceptions in your code). These Event Log entries end as follows by default:

-- logged as '-' number - @' quit arg1/arg2 }'

To get more complete information about such errors:

Set the ^Ens.Debug("LogETN") global node to any value.

This causes InterSystems IRIS to record additional details for system-level exceptions.
Rerun the code that you think caused the exception (for example, resend messages).
Recheck the Event Log, which now contains entries that end as follows:
```
-- logged as '25 Sep 2012' number 15 @' quit arg1/arg2 }'
```
This information refers to an entry in the Application Error Log — specifically it refers to error 15 in the Application Error Log for 25 September 2012.
Then to examine these exceptions, you can either:
- Use the [Home] > [System Logs] > [View Application Error Log] page. To access this page, click System Operation, click System Logs, click Application Error Log, and then click Go.
- Use the ^%ETN routine. For details, see “Other Debugging Tools” in the chapter “Command-line Routine Debugging” in Using ObjectScript.