Introduction

Sirius Software offers two full-featured debuggers for analysis and maintenance of Model 204 User Language applications. The Janus Debugger is a tool designed for software developers who create and maintain Janus Web Server applications. The Sirius Debugger is designed to debug applications that use a 3270 terminal stream to interact with the user or applications that use a Batch2 stream.

Both debuggers use the same Windows GUI client, so you need to learn only one user interface.

The Janus and Sirius Debuggers provide these typical debugging capabilities:

• Viewing code while running it
• Stepping one statement at a time
• Examining variable values
• Using a separate "watch window" for the display of specified data items
• Setting breakpoints at which execution pauses
• Skipping over selected procedures

In addition, the Debuggers provide an assortment of special features, including:

• A compact Graphical User Interface
• Views of the Model 204 audit trail, code executed by sdaemons, Web Server output-buffer data (Janus Debugger), and screen variables (Sirius Debugger)
• Tracing of statements that modify variables in executed code lines, or tracing until a variable becomes a certain value
• Saving of sets of variables to be watched, which are restorable at any time
• A code line's Model 204 procedure details (file, name, line number, text preceding dummy string substitution)
• Filtering of program code to skip over all but the Model 204 procedure you identify or the procedures you pre-selected (added to "White List")
• Examination of Sirius extensions to User Language (including LongStrings, $lists, Janus SOAP objects)
• System class methods that let you insert code in User Language programs that runs only under the Debuggers
• The ability to integrate powerful source code editors (for example, Xtend®, UltraEdit®) to edit your User Language code
• User-settable buttons and hot keys for customizing the user interface.
• The ability to create macros that run multiple commands and may include Debugger-macro-language variables, functions, and commands

Janus Debugger

The Janus Debugger is designed to debug Janus Web Server applications. With software installed on the Model 204 Online as well as on a workstation with a browser that can access a proxy server, the Debugger lets you examine in statement-by-statement detail the User Language code that the Web Server executes.

When a Janus Web Server is about to run a request on your behalf, and you are running under the Janus Debugger:

1. Server source code is sent to the Debugger Client deployed on a workstation.
2. The code is shown, navigable to top and bottom, with search features available.
3. Execution is paused, awaiting the control of the Debugger.

Although limited to Janus Web Server applications (for example, if a program does a 3270-screen read, the Debugger session terminates), the programs you debug may be, or contain, the following:

• Janus SOAP applications
• Up to 5 levels of sdaemons or transactional sdaemons
• Up to 5 levels of synchronous $COMMBG requests
• Persistent sessions ($WEB_FORM_DONE)

The Sirius Debugger

The Sirius Debugger follows execution of code requested by terminal and Batch2 requests. It does not process HTTP Web Server requests (though it can debug HTTP client applications that use the Janus Sockets HTTP Helper).

When an application is about to run a Model 204 3270-terminal or Batch2 request,

1. Server source code is sent to the Debugger Client deployed on a workstation.
2. The code is shown, navigable to top and bottom, with search features available.
3. Execution is paused, awaiting the control of the Debugger.

Although limited to 3270 or batch stream applications (unless you also license the Janus Debugger), the programs you debug may be, or contain, the following:

• Up to 5 levels of sdaemons or transactional sdaemons
• Up to 5 levels of synchronous $COMMBG requests
• A client of a web service

The GUI

The following image of the Debugger Client (debugging a Janus Web Server program) has numbered labels that point to the principal areas of the Debugger and that are linked to descriptive text below the image:

1 — The tabbed pages

The main display window is used by any of several tabbed pages (the Web Buffer tab is not present for Sirius Debugger sessions; Daemon tabs display dynamically if the program invokes daemons):

• The Audit Trail page primarily displays the Model 204 audit trail lines produced by the Online thread that is being debugged.
• The Source Code page displays the source code lines of the User Language request that is currently being debugged. Here is where most of your interactions with program code take place.
• The Web Buffer page displays a program's web output buffer lines: the lines the Web Server application is preparing (in CCATEMP) to send to the browser at the completion of the request. This page is not present if you are debugging with the Sirius Debugger.
• The Execution Trace page displays the results of whichever of multiple types of tracing options you are invoking. For example, you can trace those statements that are executed from the current position in the program. Or you can display all the statements that modify a particular variable as well as the variable's resulting value. If you elect to have program execution stop when a designated variable's value changes, the changed value and statement responsible are displayed on the Execution Trace page.
• The Proc Selection page lets you select the Model 204 procedure at which the Debugger will stop for debugging, after running normally the program code that precedes the procedure. From this page you can also operate the White List feature, which lets you specify the particular set of procedures to which debugging will be limited. The Debugger will stop to debug only the procedures on the list.

2 — The lower windows

• The Most Recent Audit Trail window displays the last few lines of the Model 204 audit trail.
• The Watch Window box can display the current value of one or more User Language data items (%variables, $list items, Janus SOAP object variables, etc.). It is updated as the program runs, each time execution is paused by the Debugger.

  The text area above the Watch Window labeled Variable or Field lets you add an item to the Watch Window or provide dynamic input to a user-defined macro.

3 — The Status area

The Status area displays messages that describe the state of the Debugger after each operation you invoke.

4 — The page navigation buttons

The Top, Bottom, Search, and Search Next buttons provide navigation on the currently active tab. You can rearrange the order of the buttons and can even replace them with different functionality.

5 — The program execution buttons

Like the page navigation buttons, the order and functionality of these buttons is user-configurable.

• The Run, Step Next, and Step Over buttons advance the Source Code page execution position by running one or more "executable" User Language statements.
• The End Norun button skips the execution of the current program in the Source Code page, just as if you had ended the code with END NORUN instead of END.

6 — The tracing buttons

• The Trace button lets you trace from the current program point to the end of the program, displaying a list of all executed statements.
• The Trace Changes button lets you trace all statements that modify a variable you specify, also displaying the value that was assigned to the variable.
• The Run To Change button stops program execution as soon as the variable you specify is modified.

7 — The value displaying buttons

• The Add Watch button adds the item you specify (in the Variable or Field box) to the Watch Window.
• The Value button displays in a separate window the value of the item in the Variable or Field box.

8 — The menu bar

The Debugger Client has multiple menus; many of the menu options duplicate the actions of default Client buttons and keyboard shortcuts, and most menu options are associated with Client commands.

Configurability

In addition to a configuration file you edit at the time of product installation to provide Online and workstation TCP port numbers, the Debugger Client has a number of configuration options that are dynamically settable from the File > Preferences menu:

• Execution Options

  These items control optional points at which the Debugger might pause program execution for user input.

• Web Browser Options

  If Internet Explorer is the browser you are using with the Janus Debugger, you can enable a Debugger Client feature that automatically specifies and maintains the definition of the Debugger Client as Internet Explorer's proxy server. The proxy takes over when the Client is started, and its settings are removed when the Client is closed.

• Display Options

  The first of these options lets you limit the number of items displayed when you view the entire contents of a $list or StringList object. The second option lets you trim leading and trailing blanks from text you copy to a separate display window.

• Web Server Selection

  At any time, you can selectively deactivate or reactivate debugging for browser requests sent to any Janus Web Server defined to the Debugger Client.

After some experience using the Debugger, you have further customization options:

• You can create alternative mappings of the functions of the Client's buttons and hot keys.
• You can use the Client's macro language to create a script to automate an often-repeated series of operations.

Tracing options

The Debugger provides several options for tracing the effects of your program execution. You run part or all of your program, and the Debugger collects tracing data in a separate page, the Execution Trace tab.

The simplest form of tracing starts from the current execution point and notes which lines were executed. You click the Trace button below the main window, the program executes, and a list of the statements executed is displayed in the Execution Trace tab.

Clicking the Trace Changes button invokes tracing that lists all statements that modify a selected variable and specifies the new value that was assigned to the variable:

You can also have the Debugger stop program execution whenever the value of a variable changes. Once you click the Run to Change button, the statement that modifies the specified variable, as well as the new variable value, are shown in the Execution Trace tab.

Finally, a variation of the Run To Change feature lets you continue program execution unless or until a selected variable's value becomes equal to a value you specify. This lets you verify whether a variable ever becomes a certain value.

An XML example

Applications using Janus SOAP XML document objects (XmlDocs) are becoming increasingly common due to the prominence of Web Services. The Janus and Sirius Debuggers make it easy to display the contents of your XML document objects, and thus let you examine an XmlDoc as it is being built by your application code.

Ordinarily in the Janus SOAP XML API, you can inspect the contents of an XmlDoc only if it is serialized by an XML document serializing method like Serial, WebSend, Xml, or Print. As a result, if you want to know the contents of an XmlDoc sometime before the code contains a statement that serializes the XmlDoc, you have to intervene. If you were editing your own code by hand, you might simply insert Print method statements to view the contents. The Debugger provides a solution that avoids any modification of your code.

Say you are debugging request code in which a statement like the following is executed:

%x:loadxml('<a>Hello<b>moe</b><c>larry</c></a>')

Instead of directing the Debugger to display the value of %x — the way you display the value of other variables in the GUI — you specify the value %x:serial. When you click the Value button, the Debugger Client displays in a separate window the result of the XmlDoc Serial method applied to the object variable %x:

For your convenience, the Debugger formats the return value with carriage-return/line-feed character sequences and three-blank character sequences for the indent of nested elements. The XML documents you are building or receiving (say, via an HTTP Helper Web Services client application) are readily visualized, thus easier to debug.

Object expansion

With version 7.1 or higher of the Sirius Mods, you can display for a given object variable the names and values of the Variables (public and private) defined for its class.

This feature is supported for Janus SOAP system classes and for user-defined classes. For any class, the display does not include class methods (Functions, Subroutines, Properties, or Constructors).

For example, for an object variable whose value you are watching in the Debugger Watch Window, you simply right-click the variable and the Debugger enables an Expand Object option (as shown to the right):

If the current object variable value is other than Not-null, the Expand Object option is not enabled.

Once you select the Expand Object option, a Value window opens, displaying the names and current values of the Variables in the class (as shown below):

Requirements

Both the Janus Debugger and the Sirius Debugger support Model 204 V5R1 and higher on the MVS, VM, and VSE operating systems.

Version 6.8 or higher of the Sirius Mods is required.

The Debugger Client application runs only on Windows workstations. The Janus Debugger requires a web browser that supports proxy servers.