Category:Debugger Home: Difference between revisions

Revision as of 22:23, 23 March 2023

This is a master category and page for all things Debugger (Janus/TN3270 Sirius Debugger). It is currently under construction, so it is subject to changes and formatting.

About the Debuggers

The Janus Debugger is a tool designed for developers who create and maintain Janus Web Server applications. With software installed in the Model 204 Online, as well as on a workstation with a browser that can access the Web Server, the Janus Debugger lets you examine in statement by statement detail the SOUL code that the Web Server executes.

The TN3270 Debugger is designed for developers who create and maintain Model 204 3270 and Batch2 applications. With software installed on the Model 204 Online, it uses the same Debugger Client as the Janus Debugger, letting you examine 3270 and Batch2 applications.

An instance of the Debugger Client can be debugging a web application (acting as the Janus Debugger), or it can be debugging a 3270 or Batch2 application (acting as the TN3270 Debugger). At any given time, it may only be debugging one type of application. The title bar of the Debugger Client indicates the application type.

The basic operation

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

Request source code is sent to the Debugger Client deployed on a workstation.
The Debugger Client displays the code, navigable to top and bottom, with search features available.
Program execution is paused, the Debugger awaiting the instructions you provide through the Client GUI.

The feature set

Both Debuggers provide these typical debugging capabilities:

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

In addition, the Debuggers provide:

A compact Graphical User Interface with user configurable buttons and hot keys
Views of the Model 204 audit trail and code executed by daemons
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
Display of Web Server output (Janus Debugger) and screen variables (TN3270 Debugger)
A code line's Model 204 procedure details (subsystem, 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 selected (added to "White List")
Stepping out of a called subroutine, method, or daemon and continuing processing at the statement after the call to the subroutine, method, or daemon
Examination of longstrings, $lists, objects
System class methods that let you insert code in User Language that runs only under the Debuggers

The architecture

The following figure displays the principal components in a Janus Debugger configuration:

The main components in a TN3270 Debugger configuration parallel those in the Janus Debugger configuration, the principal exception being the absence of the web browser:

Per Debugger session for a Janus Web or 3270 or Batch2 application, these components are active in the Online and on the workstation:

Model 204 nucleus hooks (Assembler; not shown above)	Compiler: Capture source lines, before and after dummy string substitution. Note source of line (procedure and file). Evaluator: Can step one statement at a time, and can step over routines and methods. Can stop on breakpoints. Between statements, can get variable, field, and global values, to support display, trace, watch, etc.
Janus Web thread	`Janus Debugger` only.
3270/Batch2 thread	`TN3270 Debugger` only.
Worker threads (Assembler Language, one for each thread being debugged)	For each debugging session, a “worker thread” arbitrates between the thread being debugged and the workstation client. A worker thread does the following: Passes data between the thread being debugged and the Client. Controls the execution of the thread being debugged, at the behest of the Client.
Debugger Client (Windows GUI, written in VB.NET)	The Debugger Client resides on the developer's workstation. It is a proxy server in a `Janus Debugger` session: the browser no longer directly connects to the Web Server, but instead it "sends" to and "receives" from the Client. The Client GUI lets you control the application and view variable values, source code, traces, and for `Janus Debugger` sessions, the web output buffer.
Web browser	`Janus Debugger` only. Any web browser that allows proxy servers.

Versions and builds

Independent of the version of Model 204 being run, the Debugger Client has its own numbered sequence of "builds" that contain new and updated features. From build to build of the Debugger Client, the About box (accessed by the Help menu) provides a searchable list of the principal changes in each of the previous builds of the Debugger Client.

System requirements

The Online Configuration section of this document specifies the requirements for Model 204 product release levels, licenses, and maintenance, as well as Debugger product authorization. In addition are instructions for configuring a Model 204 Online that hosts the Debugger, which include User 0 parameter and TCP port definitions and increases in storage table and work area sizes for both of these:

The worker thread that services a debugging session
The thread on which the program to be debugged is running

Known limitations

The following are known limitations and issues concerning the Janus and TN3270 Debuggers:

You may not use either Debugger for DBCS data.
You may use the Janus Debugger on a Janus Web Legacy Support thread only if you also have a license for the TN3270 Debugger.
No asynchronous daemon or $COMMBG requests may be debugged. They are simply ignored by the Debugger (and they execute normally).
The client requires Windows 7 or higher
Both the Execution Trace tab (output from one trace) and the Web Buffer tab have 5000 line capacities. If the capacity is exceeded, the last 5000 lines are shown.

Check Prerequisites

Ensure you are running Version 7.5 or higher of Model 204. You can verify this by issuing the VIEW VERSION command at the Model 204 command prompt, for example:

VIEW VERSION VERSION 7.9.0A Release of Model 204

Installation and Configuration

This section describes how to install the Janus Debugger, the TN3270 Debugger, or both. Once you complete this installation, you can begin to use either or both products.

This section consists of two subsections of mostly cookbook-style directions. You should first complete the steps in the "Online Configuration" section, then complete the "Workstation Configuration" section.

Most of the steps are to be performed whether you are installing one or both Debugger products, and exceptions are noted.

If you will be using a local editor (Xtend or UltraEdit) with the Debugger, finish the Debugger installation first, then see Using a local editor.

For information about setting up at your site a centralized distribution of updated Debugger Client replacement files, see Providing updated versions of the Debugger Client.

Online Configuration

This section shows how to prepare a Model 204 Online for use of the Janus Debugger, the TN3270 Debugger, or both.

The installation tasks require Model 204 system manager privileges. Also, since you must set at least one User 0 parameter, a cycle of the Model 204 Online will be required.

The Online configuration tasks are listed below.

&&Functions

&&Function	Description
&&amDaemon	Returns a 1 if a Daemon tab contains the currently active code. Otherwise, the returned number is 0.
&&arg	Serves as a placeholder for a command argument within a macro (if used outside of a macro, an error is issued).
&&assertFailureCount	Returns a count of the number of times that the result of an assert command is a Failure.
&&assertStatus	Returns a string that contains a summary of the counts of assert command results.
&&assertSuccessCount	Returns a count of the number of times that the result of an assert macro command is a Success.
&&blackOrWhiteList	Tests whether the Debugger is filtering the procedures you are going to debug, and if so, whether a Black List or White List is being used.
&&buildNumber	Returns the number of the build of the Client from which the function is called.
&&concatenate	Concatenate and return the function's arguments.
&&currentPacFile	Returns the URL of the Proxy Auto Config (PAC) file in use, or it returns empty if no PAC file is in use.
&&currentRunningMacro	Returns the full file-system path to the macro within which it is called. If not called from within a macro, the function returns a null string.
&&currentTitle	Returns the current title of the Client main window.
&&exists	Tests if a macro variable is defined.
&&fileExists	Returns 1 if the file identified by fileSpec exists, 0 if not.
&&getMainSearchInputArea	Returns the value specified in the search input area on the Client main window.
&&getScope	Returns the scope of the specified routine from the SOUL call stack, -1 if routine not found or we are not executing a program.
&&globalAssertFailureCount	Same as &&assertFailureCount except its scope is the entire Client session.
&&globalAssertStatus	Same as &&assertStatus except its scope is the entire Client session.
&&globalAssertSuccessCount	Same as &&assertSuccessCount except its scope is the entire Client session.
&&ieMode function	Returns the current setting of the Client's IE Mode preference.
&&index	Returns the 1-based position of the needle argument within the haystack argument, or it returns 0 if the needle value is not found within the haystack value.
&&isWatched	Determines whether its argument is a variable that is currently specified in the Watch Window. If it is, &&isWatched returns 1<; if not, it returns 0.
&&isWindowOpen	Returns 1 if the window whose title is passed is open, 0 otherwise
&&length	Returns the length in characters of its string argument.
&&logFile	Returns the absolute Windows file path of the client log file (the log.txt file).
&&numberOfBreakpoints	Returns the number of breakpoints that are set in the current request, irrespective of the current executing position in the request.
&&numberOfLevels	Returns the number of code levels being debugged. The main program is one level, and each active daemon adds another level.
&&numberWatched	Returns the number of items that are currently being watched in the Watch Window.
&&originalTitle	Returns the default value of the title of the Client main window.
&&preference	Returns the value of the specified Client preference setting.
&&procName	Returns the name of the procedure that is being executed.
&&prompt	Pauses a macro while you supply an argument value for a command that is specified within the macro, then continues running the macro using the supplied value for the command.
&&quote	Returns its argument enclosed in double quotes.
&&scriptFolder	Returns the value of <scriptFolder> from debuggerConfig.xml.
&&searchResult	Returns the line number of the line that contained the found string, if the last Client search operation successfully found something.
&&searchSuccess	Returns 1 (True) if the last Client search operation (invoked by button or command) successfully found something. If the last search found nothing, or if there was no prior search, &&searchSuccess returns 0 (False).
&&selectedTab	Returns the label of the Client main window tab that is currently active. Or, it returns a null string () if no tab is active
&&stateFileFolder	Returns the location of all "state" files such as the log and saved preferences and window positions.
&&statusMessage	Returns the most recent Client status message.
&&substring	Return a substring of the target string argument.
&&sum	Returns the sum of the function arguments.
&&verifyMatch	Returns the 1-based position (in string) of the first character in string that is also in the characters in charSet.
&&verifyNoMatch	Returns the 1-based position (in string) of the first character in string that is not in the characters in charSet. If no character in string is not in charSet, returns 0.
&&windowStatus	Returns 1 if the named window is open, 0 otherwise.

Subcategories

This category has the following 3 subcategories, out of 3 total.

&

&&Functions

D

Pages in category "Debugger Home"

The following 114 pages are in this category, out of 114 total.

A

B

C

D

E

F

File menu options

G

H

I

M

O

Opening an external window

P

R

S

T

U

V

W

@@ Line 114: / Line 114: @@
 ==== Known limitations  ====
 The following are known limitations and issues concerning the Janus and TN3270 Debuggers:
-*You may not use either Debugger for '''''DBCS data'''''.
+*You may not use either Debugger for '''DBCS data'''.
-*You may use the Janus Debugger on a '''''Janus Web Legacy Support''''' thread only if you also have a license for the TN3270 Debugger.
+*You may use the Janus Debugger on a '''Janus Web Legacy Support''' thread only if you also have a license for the TN3270 Debugger.
-*No '''''asynchronous daemon or $COMMBG requests''''' may be debugged. They are simply ignored by the Debugger (and they execute normally).
+*No '''asynchronous daemon or $COMMBG requests''' may be debugged. They are simply ignored by the Debugger (and they execute normally).
-*The client requires '''''Windows 7 or higher'''''.
+*The client requires '''Windows 7 or higher'''
-*Both the Execution Trace tab (output from one trace) and the Web Buffer tab have '''''5000 line capacities'''''. If the capacity is exceeded, the last 5000 lines are shown.
+*Both the Execution Trace tab (output from one trace) and the Web Buffer tab have '''5000 line capacities'''. If the capacity is exceeded, the last 5000 lines are shown.
 === Check Prerequisites ===