EGL debugger

When you are in the Workbench, the EGL debugger lets you debug EGL code without requiring that you first generate output. These categories are in effect:

If you are working on a batch program that you intend to deploy in a J2EE context, you can use the launch configuration to debug the program in a non-J2EE context. Although your setup is simpler, you need to adjust some values:

A later section describes the interaction of build descriptors and EGL preferences.

Debugger commands

You use the following commands to interact with the EGL debugger:

Add breakpoint

Identifies a line at which processing pauses. When code execution pauses, you can examine variable values as well as the status of files and screens.

Breakpoints are remembered from one debugging session to the next, unless you remove the breakpoint.

You cannot set a breakpoint at a blank line or at a comment line.

Disable breakpoint

Inactivates a breakpoint but does not remove it.

Enable breakpoint

Activates a breakpoint that was previously disabled.

Remove breakpoint

Clears the breakpoint so that processing no longer automatically pauses at the line.

Remove all breakpoints

Clears every breakpoint.

Run

Runs the code until the next breakpoint or until the run unit ends. (In any case the debugger stops at the first statement in the main function.)

Run to line

Runs all statements up to (but not including) the statement on a specified line.

Step into

Runs the next EGL statement and pauses.

The following list indicates what happens if you issue the command step into for a particular statement type:

call

Stops at the first statement of a called program if the called program runs in the EGL debugger. Stops at the next statement in the current program if the called program runs outside of the EGL debugger.

The EGL debugger searches for the receiving program in every project in the workbench.

converse

Waits for user input. That input causes processing to stop at the next running statement, which may be in a validator function.

forward

If the code forwards to a page handler, the debugger waits for user input and stops at the next running statement, which may be in a validator function.

If the code forwards to a program, the debugger stops at the first statement in that program.

function invocation

Stops at the first statement in the function.

sysLib.java and related functions

Stops at the next Java statement, so you can debug the Java code that is made available by the Java access functions.

show, transfer

Stops at the first statement of the program that receives control. The target program is EGL source that runs in the EGL debugger and is not EGL-generated code.

After either a show statement or a transfer statement of the form transfer to a transaction, the EGL debugger switches to the build descriptor for the new program or (if no such build descriptor is in use) prompts the user for a new build descriptor. The new program can have a different set of properties from the program that ran previously.

The EGL debugger searches for the receiving program in every project in the workbench.

Step over

Runs the next EGL statement and pauses, but does not stop within functions that are invoked from the current function.

The following list indicates what happens if you issue the command step over for a particular statement type:

converse

Waits for user input, then skips any validation function (unless a breakpoint is in effect). Stops at the statement that follows the converse statement.

forward

If the code forwards to a page handler, the debugger waits for user input and stops at the next running statement, but not in a validator function, unless a breakpoint is in effect.

If the code forwards to a program, the debugger stops at the first statement in that program.

show, transfer

Stops at the first statement of the program that receives control. The target program is EGL source that runs in the EGL debugger and is not EGL-generated code.

The EGL debugger searches for the receiving program in every project in the workbench.

Step return

Runs the statements needed to return to an invoking program or function; then, pauses at the statement that receives control in that program or function.

An exception is in effect if you issue the command step return in a validator function. In that case, the behavior is identical to that of a step into command, which primarily means that the EGL debugger runs the next statement and pauses.

The EGL debugger treats the following EGL statements as if they were null operators:

sysLib.audit
sysLib.purge
sysLib.startTransaction

You can add a breakpoint at these statements, for example, but a step into command merely continues to the subsequent statement, with no other effect.

Finally, if you issue the command step into or step over for a statement that is the last one running in the function (and if that statement is not return, exit program, or exit stack), processing pauses in the function itself so that you can review variables that are local to the function. To continue the debug session in this case, issue another command.

Use of build descriptors

A build descriptor helps to determine aspects of the debugging environment. The EGL debugger selects the build descriptor in accordance with the following rules:

If you specified a debug build descriptor for your program or page handler, the EGL debugger uses that build descriptor. For details on how to establish the debug build descriptor, see Setting the default build descriptors.
If you did not specify a debug build descriptor, the EGL debugger prompts you to select from a list of your build descriptors or to accept the value None. If you accept the value None, the EGL debugger constructs a build descriptor for use during the debugging session; and a preference determines whether VisualAge Generator compatibility is in effect.
If you specified either None or a build descriptor that lacks some of the required database-connection information, the EGL debugger gets the connection information by reviewing your preferences. For details on how to set those preferences, see Setting preferences for SQL database connections.

If you are debugging a program that is intended for use in a text or batch application in a Java environment, and if that program issues a transfer statement that switches control to a program that is also intended for use in a different run unit in a Java environment, the EGL debugger uses a build descriptor that is assigned to the receiving program. The choice of build descriptor is based on the rules described earlier.

If you are debugging a program that is called by another program, the EGL debugger uses the build descriptor that is assigned to the called program. The choice of build descriptor is based on the rules described above, except that if you do not specify a build descriptor, the debugger does not prompt you for a build descriptor when the called program is invoked; instead, the build descriptor for the calling program remains in use.

Note: You must use a different build descriptor for the caller and the called program if one of those programs (but not both) takes advantage of VisualAge Generator compatibility. The generation-time status of VisualAge compatibility is determined by the value of build descriptor option VAGCompatibility.

A build descriptor or resource association part that you use for debugging code may be different from the one that you use for generating code.

SQL-database access

To determine the user ID and password to use for accessing an SQL database, the EGL debugger considers the following sources in order until the information is found or every source is considered:

The build descriptor used at debug time; specifically, the build descriptor options sqlID and sqlPassword.
The SQL preferences page, as described in Setting preferences for SQL database connections; at that page, you also specify other connection information.
An interactive dialog that is displayed at connection time. Such a dialog is displayed only if you select the checkbox Prompt for SQL user ID and password when needed.

call statement

As noted earlier, the EGL debugger responds to a transfer or show statement by interpreting EGL source code. The EGL debugger responds to a call statement, however, by reviewing the linkage options part specified in the build descriptor, if any. If the referenced linkage options part includes a callLink element for the call, the result is as follows:

If the callLink property remoteComType is set to DEBUG, the EGL debugger interprets EGL source code. The debugger finds the source by referencing the callLink properties package and location.
If the callLink property remoteComType is not set to DEBUG, the debugger invokes EGL-generated code and uses the information in the linkage options part as if the debugger were running an EGL-generated Java program.

In the absence of linkage information, the EGL debugger responds to a call statement by interpreting EGL source code. Linkage information is unavailable in these cases:

No build descriptor is used; or
A build descriptor is used, but no linkage options part is specified in that build descriptor; or
A linkage options part is specified in the build descriptor, but the referenced part does not have a callLink element that references the called program.

If the debugger runs EGL source code, you can run statements in that program by issuing the step into command from the caller. If the debugger calls generated code, however, the debugger runs the entire program; the step into command works like the step over command.

System type used at debug time

A value for system type is available in sysVar.systemType. Also, a second value is available in sysLib.getVAGSysType if you requested development-time compatibility with VisualAge Generator).

The value in sysLib.systemType is the same as the value of the build descriptor option system, except that the value is DEBUG in either of two cases:

You select the preference Set systemType to DEBUG, as mentioned in Setting preferences for the EGL debugger; or
You specified NONE as the build descriptor to use during the debugging session, regardless of the value of that preference.

The system function sysLib.getVAGSysType returns the VisualAge Generator equivalent of the value in sysLib.systemType; for details, see the table in sysLib.getVAGSysType.

EGL debugger port

The EGL debugger uses a port to establish communication with the Eclipse workbench. The default port number is 8345. If another application is using that port or if that port is blocked by a firewall, set a different value as described in Setting preferences for the EGL debugger.

If a value other than 8345 is specified as the EGL debugger port and if an EGL program will be debugged on the J2EE server, edit the server configuration:

Go to the Environment tab, System Properties section
Click Add
For Name, type com.ibm.debug.egl.port
For Value, type the port number

Recommendations

As you prepare to work with the EGL debugger, consider these recommendations (most of which assume that sysVar.systemType is set to DEBUG when you are debugging the code):

If you are retrieving a date from a database but expect the runtime code to retrieve that date in a format other than the ISO format, write a function to convert the date, but invoke the function only when the system type is DEBUG. The ISO format is yyyy-mm-dd, which is the only one available to the debugger.
To specify external Java classes for use when the debugger runs, modify the class path, as described in Setting preferences for the EGL debugger. You might need extra classes, for example, to support MQSeries, JDBC drivers, or Java access functions.
When you are debugging a page-handler function that was invoked by JSF (rather than by another EGL function), use Run to leave the function rather than Step Over, Step Into, or Step Return. Using any of the three Step commands takes you to the generated Java code of the page handler, which is not useful when you are debugging EGL. If you use one of the Step commands, use Run to leave the generated Java code and display the Web page in a browser.
If you are using the SQL option WITH HOLD (or the EGL equivalent), you need to know that the option WITH HOLD is unavailable for EGL-generated Java or in the EGL debugger. You may be able to work around the limitation, in part by placing commit statements inside a conditional statement that is invoked only at run time, as in the following example:
```
  if (systemType not debug)
    sysLib.commit();
  end
```

If EGL programs are debugged on the J2EE server or by an EGL Listener, the server or EGL Listener must be configured to indicate the number for the EGL debugger port:

To configure a J2EE server, edit the server configuration--
1. Go to the Environment tab, System Properties section
2. Click Add
3. For Name, type com.ibm.debug.egl.port
4. For Value, type the new port number
To configure an EGL Listener, edit the EGL Listener launch configuration--
1. Go to the Arguments tab
2. In the VM Arguments field, type this:
```
  -Dcom.ibm.debug.egl.port=portNumber
```
  portNumber
  
  The new port number