Attach dialog box

Depending on the programming language and platform of the program you are debugging, select the appropriate tab for a description of the controls and control groups. The tabs cover the following categories of programming languages on various platforms:

The controls and control groups are described on separate tabs for each category of programming language on various platforms. Select the appropriate tab from the following:

Compiled tab

Use the Attach dialog box to select and attach to a process or JVM that is already running so it can be debugged.

This tab is used for attaching to compiled language processes running on AIX, Solaris, and Windows. Attaching to an operating system process or to any of the processes of the Debugger itself can cause unpredictable results and should therefore not be done.

Terminating a process for programs written in compiled languages has additional considerations. The following are notes describing how the Debugger handles attached processes on exit.

Controls and control groupings are described below. Group and subgroup names appear in italics, and control names appear in bold.

Select local or remote execution of the program Select one of the following options to define the location in which the process being attached to will be running.
Local If selected, all process execution and debugging takes place on the local system. Local is applicable on Windows, Solaris, and AIX only.
TCP/IP Connection If selected, process execution takes place on a remote system while debugging control and display remain with the local system. If you choose this option, you must have started a debug engine daemon on the remote system using the irmtdbgc command. You must also provide the following information regarding the remote system:
Host This field incorporates a selection list containing the names of remote hosts recently used by the Debugger. Select any remote host name from this list. If the remote host you want to use is not named in the list, type the name of that host into this field.
Port Enter the port number the remote debug engine daemon is listening on. If not specified, port 8000 is assumed.
Specify the dominant language the Debugger will use Select the appropriate programming language from this drop-down list. The default value is C++.
Process path (optional) Enter the process path, if known.

The operating system can determine the process path from the process ID and does not require you to specify this information.

Select the radio button for the method to be used to specifiy the process ID.

Select process from list Enables the Get Process List push button, which opens the Process List dialog box. This secondary dialog displays a list of running processes and their process IDs from which you can make a selection.
Enter process ID If you know the process ID for your process, enter this identifier in this entry field.
Use program profile Check this box if you want to use the breakpoint, monitor, and Application Preferences settings that were associated with your program during your last Debugger session. If you are debugging your program for the first time, the Debugger uses the default Application Preferences settings, with no initially set breakpoints.

Checking this box will also associate and save any changes you make to the monitors and breakpoints with your program when you end your Debugger session.

Note: If you add or delete lines in your source file, recompile it, and then debug the program again with a saved program profile, line breakpoints may no longer match the code they were initially set for because line breakpoint information is saved by line number, not by the content of the line.

The push buttons of the Attach dialog box are described in the following table. Control names appear in bold.

Push buttons
Attach Attaches to the specified process or JVM.
Cancel Closes the Attach dialog and terminates the engine connection, if any.
Help Displays this help panel.

Interpreted tab

Use the Attach dialog box to select and attach to a process or JVM that is already running so it can be debugged.

Restriction: This tab applies to interpreted Java programs only. It does not apply to debugging High Performance Compiled Java programs or OS/390 Java program objects.

Use the Interpreted tab to attach to an already running Java Virtual Machine (JVM). Attaching to a running JVM allows you to debug the interpreted Java program running inside the JVM. When attaching to a JVM, you select the location of execution for the debug engine rather than the location of execution for the program.

Controls and control groupings are described below. Group and subgroup names appear in italics, and control names appear in bold.

Select a method to attach to the JVM
Create a local engine If selected, the debug engine runs on the local system. Also, debugging control and display take place on the local system. Program execution takes place within the JVM running on a host system. This host system can be your local system or a remote system.

If you choose this option, you must also provide the following information regarding the JVM host system:

JVM Host This field incorporates a selection list containing the names of JVM hosts recently used by the Debugger. Select any JVM host name from this list. If the JVM host you want to use is not named in the list, type the name of that host into this field.

If the JVM you want to attach to is running on the local system, the JVM host is "localhost".

JVM Port or Password

Enter the agent password/port number for the JVM you want to attach to. This password/port number is provided when you start the debuggable JVM.

Use a remote engine If selected, the debug engine runs on a remote system while debugging control and display remain with the local system. Program execution takes place within the JVM running on a host system. This host system can be remote to both your local system and the remote system running the debug engine.

If you choose this option, you must have started the debug engine on the remote system with the irmtdbgj command using the JVM_attach_parameters. You must also provide the following information regarding the remote system:

Engine Host This field incorporates a selection list containing the names of remote hosts recently used by the Debugger. Select any remote host name from this list. If the remote host you want to use is not named in the list, type the name of that host into this field.
Port Enter the port number the remote debug engine daemon is listening on. If not specified, port 8000 is assumed.
Use program profile Check this box if you want to use the breakpoint, monitor, and Application Preferences settings that were associated with your program during your last Debugger session. If you are debugging your program for the first time, the Debugger uses the default Application Preferences settings, with no initially set breakpoints.

Checking this box will also associate and save any changes you make to the monitors and breakpoints with your program when you end your Debugger session.

Note: If you add or delete lines in your source file, recompile it, and then debug the program again with a saved program profile, line breakpoints may no longer match the code they were initially set for because line breakpoint information is saved by line number, not by the content of the line.

The push buttons of the Attach dialog box are described in the following table. Control names appear in bold.

Push buttons
Attach Attaches to the specified process or JVM.
Cancel Closes the Attach dialog and terminates the engine connection, if any.
Help Displays this help panel.

ngos400.gif (278 bytes) AS/400 Use the Attach dialog box to attach to an existing job on an AS/400. Jobs on the AS/400 can be one of the following:
  • Interactive jobs, which are enabled to run an application with screen input/output.
  • Batch jobs.
  • Batch immediate (BCI) jobs, which are enabled to run a threaded application. Applications with screen input/output should not be run in a BCI job.
  • JVM jobs.

All types of jobs can be attached to by the Debugger.

When you are attaching to an existing AS/400 job, the behavior of the debug session changes depending on whether or not you select Step Into in this dialog box. For more details, see the description of the Step Into box in this group.

Controls and control groups in this group are used as follows:

TCP/IP name of AS/400 host

Host

Specify the name of the AS/400 host on which you are debugging your applications. You can enter the host name in one of the following formats:

  • An IP address, such as 9.99.99.99
  • A hostname which is defined in your local host table or on a name server to which you link, such as name.name.name.com

Alternatively, you may select the name of the host from the Host field drop down list, which contains debug host names specified in previous debug sessions. Specifying a debug host is mandatory.

Note: To determine the AS/400 TCP/IP address, type GO CFGTCP on an AS/400 command line, and choose menu option 12 = Change local domain and host names. Be careful not to change the local domain name and hostname when you use this option.

Port Number You only need to specify a port if you want to connect to the AS/400 using a port other than the default port. By default, the port number is set to 3001.

Use this field to permanently specify the port used by the AS/400 debug server. Enter a value between 1 and 64,767 that matches the port number specified for the QDBGSVR entry on the AS/400.

Job to debug

In this field, specify the name of the AS/400 job you want to put under debug mode. A fully qualified AS/400 job name has the format job/user/number, where:

  • job is the name of the job as identified to the system, for example, QPADEV0017.
  • user is the user profile under which the job is running, for example, MYUSER.
  • number is the system-assigned job number, for example, 001234.

If the system-assigned job number is known, then specifying it in the format //number will specify a unique job and specification of job and user will not be necessary.

You can use one of the following methods to retrieve a subset list of the jobs available on the AS/400 system. Entries are made in the Job to debug field and the Job List push button is clicked to invoke the Job List dialog box:

  • Entering QPADEV0017// gives you a list of jobs with job name QPADEV0017.
  • Entering /MYUSER/ gives you a list of jobs with user profile MYUSER.
  • Entering //001234 gives you the job assigned this job number.

You can also specify an abbreviated job name. The following formats are supported:

*, *ALL, blank All occurrences are found.
abc* All occurrences starting with the character string abc are found.
abc Only exact matches of the character string abc are found.

The following examples illustrate how to use these formats. Entries are made in the Job to debug field and the Job List push button is clicked to invoke the Job List dialog box:

  • Entering QPADEV0017/*ALL/ gives you a list of all the jobs in QPADEV0017.
  • Entering // or leaving the Job to debug field blank gives you a list of all the jobs on the system.
  • Entering /G*/ gives you a list of all the jobs that are owned by user IDs that start with a G.
  • Entering G*/*/* gives you a list of all the jobs owned by anyone in a job that starts with a G.

If a wild card indicates a user ID that owns a single job, then specifying the wild card in this field will cause that job to be used. However, using wild cards to indicate multiple jobs is useful only to filter the list of jobs when the Job List push button is selected. When you select the Attach push button, exactly one job must be indicated or an error dialog is displayed.

Job List Click Job List to invoke the Job List dialog box. From the jobs listed in this dialog box, select the job you are going to debug.
Specify the name of the program to debug When attaching to an existing job on an AS/400, specifying the program name is optional but has the following conveniences:
  • The program will be added as an entry to the Programs pane. If this dialog's Step Into box is also checked, the Debugger will stop at the first debuggable statement which runs in the job you specified.
  • The debug session will terminate automatically when the program has run to completion. If the program name is not specified, the debug session must be terminated manually.

You can enter the program name using one of the following formats:

  • Library/program -- The Debugger searches the specified library for the program. If it does not find the program in the specified library, an error message is displayed.
  • *LIBL/program -- The Debugger searches all of the libraries in the library list for the job specified in the Job to debug entry field of the Load Program dialog box until it finds the first match for the specified program name. If it does not find the program in the library list, an error message is displayed.
  • *CURLIB/program -- The Debugger uses the current library for the job specified in the Job to debug entry field of the Load Program dialog box to locate the program. If you do not have a library designed as the current library, it searches QGPL instead. If it does not find the program, an error message is displayed.
  • Program -- When only the program name is specified, the search path used is the same as that used for *LIBL/program.
  • Class name.

To locate a Java class that resides on IFS, you can map the IFS network drive to your workstation, and click Browse to select the class on the mapped network drive in the Open dialog box.

Use program profile Check this box if you want to use the breakpoint, monitor, and Application Preferences settings that were associated with your program during your last Debugger session. If you are debugging your program for the first time, the Debugger uses the default Application Preferences settings, with no initially set breakpoints.

Checking this box will also associate and save any changes you make to the monitors and breakpoints with your program when you end your Debugger session.

Attention: If you add or delete lines in your source file, recompile it, and then debug the program again with a saved program profile, line breakpoints may no longer match the code they were initially set for because line breakpoint information is saved by line number, not by the content of the line.

Debug Java Select this check box if you wish to attach to an existing JVM job on the AS/400.
Debugger Settings Click Debugger Settings to open the Debugger Settings dialog box. The Debugger Settings dialog box allows you to specify Debugger options, such as source path.
Step Into

If you select the Step Into check box, you will be asked to start your AS/400 application after clicking the Attach push button.

If you do not select the Step Into check box, you will be able to view the source, add new programs or classes for debugging, and set breakpoints after clicking the Attach push button. If you click the Run push button in the main Debugger window, a message will prompt you to start your AS/400 application. At this point, you will need to invoke the application on the AS/400 if is not already running. Once the application is running, click the message dialog's OK button. The application will stop at the first breakpoint in the code.

The push buttons of the Attach dialog box are described in the following table. Control names appear in bold.

Push buttons
Attach Attaches to the specified job.
Cancel Closes the Attach dialog without attaching to any jobs.
Help Displays this help panel.