Setting preferences for the EGL debugger

The EGL debugger has two main pages of preferences: the first contains general preferences, and the second contains a list of programs or services to debug in generated code (Java™ or COBOL). An additional page is available if you have set the EGL DLI Developer capability.

The only preferences used for debugging Rich UI applications are as follows:

Stop at first line of a program
Set systemType to DEBUG
In the Debug behavior mapping dialog box, the settings in the Service Reference tab

For further details on Rich UI, see "Rich UI debugging."

General preferences

To set general preferences for the EGL debugger, follow these steps:

From the main menu, click Window > Preferences.
In the Preferences window, expand EGL in the tree and then click Debug. The EGL debugger preferences are displayed.
If you want the debugger to treat the first line of a run unit or program as a breakpoint, select one or more of the following options for Suspend execution:
- Stop at the first line of the initial run unit. The first executed line might be in a library referenced from elsewhere in the run unit.
- Stop at the first line of called programs.
- Stop at the first line of transferred-to programs.
An additional preference specifies whether the debugger continues without stopping, in the following case:
- One of the previous preferences indicates that your debugging session will stop when the debugger reaches a part in an EGLAR file.
- The debugger reaches that part, and the EGLAR file does not include the EGL source code.
The preference is Avoid stopping in a part if its source code is unavailable (automatically step through). When the debugger reaches the part, the response is based on the preference setting:
- The presence of a check means that the debugging session continues without stopping.
- The absence of a check means that the debugging session stops at the part, and you can review variable values.
Regardless of the preference setting, you cannot see the logic in the source code for the part, nor can you step into the logic.
To make changes to your code as you debug, select Enable hotswapping.
By default, EGL searches first for a called program by name and then, more slowly, by alias. If you do not call programs by alias and want to disable the slower process, clear Allow a program to be called by its alias.
By default, EGL displays a prompt if the debugger seeks a program when more than one program of the same name is available. The prompt lists programs found in the EGL build path, followed by programs found in the workspace.
If you want the debugger always to access the first-found program in the EGL build path, select Avoid a prompt for same-named programs by accessing the first one found in the EGL build path.

In a given project, same-named programs in different packages always are considered to be equally "first found." For example, if the debugger is seeking the Program01 program in a project, you receive a prompt if both pkg1.Program01 and pkg2.Program01 are available. The preference setting has no effect.
Select the Called programs release resources by default upon return checkbox if you want to release resources from a called program as soon as that program ends, rather than when the run unit ends.
Select Set systemType to DEBUG to cause the value of sysVar.systemType to be DEBUG rather than the value of the system build descriptor option.
Type the initial values for sysVar.terminalID, sysVar.sessionID, and sysVar.userID. If you do not specify values, each value defaults to your user ID on Windows 2000, NT, XP, and Linux.
In the Remote User and Remote Password fields, type the user ID and password to be used for remote calls while debugging.
The user ID and password that are used for remote calls while debugging are separate from the user ID and password that are used to access a SQL database.
In the EGL debugger port field, type the port number for the EGL debugger. The default is 8345. For more information, see “EGL debugger port” in this topic.
In the VSE remote VSAM codepage field, specify the code page used to translate the data that is sent to or retrieved from a VSAM file that resides on a VSE system.
Select the type of character encoding to use when processing data during a debugging session in the Character encoding field. The default is the local system's file encoding. For more information, see “Character encoding options for the EGL debugger.”
To require that a user ID and password be specified for remote calls to CICS® or to an SQL database while debugging, select Prompt for user ID and password when needed. This user ID and password are separate from those that are used to access the SQL database itself. For more information, see “SQL database access” in this topic.
If you saved your SQL database user ID and password during a debug session, you can clear them by clicking the Clear button with the Clear all saved SQL prompt information label.
If you saved your remote call user ID and password during a debug session, you can clear them by clicking the Clear button with the Clear all saved remote call prompt information label.
To cause the EGL Debugger to prompt you in all cases where a prompt is possible (including cases for which you earlier indicated that you no longer want to see a prompt), click the Clear button with the Clear all 'do not show again' dialog settings label.
To specify external Java classes for use when the debugger runs, modify the class path. You might need extra classes, for example, to support WebSphere® MQ message queues, JDBC drivers, or Java access functions.
The class path additions are not visible to the WebSphere Application Server test environment, but you can add to that environment's classpath by working on the Environment tab of the server configuration.

Use the buttons to the right of the Class Path Order section.
- To add a project, JAR file, directory, or variable, click the appropriate button: Add Project, Add JARs, Add Directory, or Add Variable.
- To remove an entry, select it and click Remove.
- To move an entry in a list of two or more entries, select the entry and click Move Up or Move Down.
To restore the default settings, click Restore Defaults.
To save your changes, click Apply or, if you are finished setting preferences, click OK.

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:

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

The user ID and password that are used to access an SQL database are separate from the user ID and password that are used to make remote calls while debugging. To set the user ID and password for remote calls while debugging, see the earlier instructions for setting preferences in the debugger.

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 the earlier instructions for setting preferences in 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, you must edit the server configuration:

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

Debug behavior mapping

When you debug an application that calls a program or a service, or debug a UI program or a web transaction, the debugger can execute either the EGL source code or the generated code for the called program or service. By default, the debugger uses the EGL source code. To use the generated code, add an entry to the "Debug behavior mapping" table.

Add entries as follows:

From the main menu, click Window > Preferences.
In the Preferences window, expand EGL in the tree, expand Debug, and click Debug Behavior Mapping.
For calls to programs, or for UI programs or web transactions, click the Called Programs tab. For each row of the table, specify the following fields:
Mapping mode
Select one of the following values:
source
If you want to specify an EGL source file for the program. Because source is the default, you only need to specify behavior mapping for source mode when you want to provide additional information. You might choose this option in the following example situations:
You want to specify a package for the file name, such as myPackage.myFile

The call statement specifies an alias and you want to provide the actual file name
generated
If you want to debug the generated Java or COBOL code for the specified program. You might choose this option in the following example situations:
You do not have the EGL source file in your workspace

The source file is large and runs slowly in the debugger
Call target

The name of the program that is called from the program that you are debugging. You can use an asterisk (*) at the end of the target name as a wildcard.

Part mapping

The fully qualified name of the source file that you want the debugger to use when the program in Call target is called. Complete this field only when you set the Mapping mode to source. Do not use an asterisk in this field.
For calls to services, click the Service References tab. For each row of the table, specify the following fields:
Mapping mode
Select one of the following values:
source
If you want to specify an EGL source file for the service. Because source is the default, you only need to specify behavior mapping for source mode when you want to provide additional information. You might choose this option in the following example situations:
You want to specify a package for the service name, such as services.myService

The service call specifies an alias and you want to provide the actual file name
generated
If you want to debug the generated Java or COBOL code for the service. You might choose this option in the following example situations:
You do not have the EGL source file for the service in your workspace

The source file is large and runs slowly in the debugger
Service binding key

The name of the binding key in the deployment descriptor for the service that you are calling.

Part mapping field

The fully qualified name of the service that you want the debugger to run when the service in Service binding key is called. Complete this field only when you set the Mapping mode to Source. Do not use an asterisk in this field.