Creating a z/OS Unix Application launch configuration

A launch configuration is a mechanism for defining and saving different workbench configurations that can be launched separately. You can use launch configurations to launch debug sessions.

1. If you are creating a new launch configuration without using the Remote Systems view Debug action, switch to a workbench perspective that offers the launch/debug/run action set (such as the Debug perspective) and perform one of the following tasks:
   • Select Run > Debug from the workbench menu bar to open the Debug launch configurations dialog box.
   • Click the down arrow next to the workbench toolbar Debug push button and select Debug from the list. This opens the Debug launch configurations dialog box.
   If you are using the Remote Systems view Debug action, the launch configuration is created for you and you do not need to perform this step or the following step.
2. In the Debug launch configurations dialog box, perform one of the following tasks:
   • Select the z/OS UNIX application node and click New.
   • Right-click the z/OS UNIX application node and select New from the pop-up menu.
   • Double-click the z/OS UNIX application node.
3. In the Name field, type a descriptive name for this new launch configuration.
4. Select the Main tab to bring it to the foreground.
5. In the Main tab, specify information for the program that you want debug:
   1. To specify the remote system connection that you want to use for this launch configuration, select an existing connection from the Connection drop-down list or click New to create a new connection.
   2. In the Program name field, type the name of the program that you want to debug or click Browse to browse for the program.
   3. In the Remote Working Directory field, type the remote location in which the program is stored or click Browse to browse for the location.
   4. Optional. If you want the program to stop at the first executable line of the main method when the program is launched in debug mode, select the Automatically stop at the first executable line of main method check box.
6. Select the Arguments tab to bring it to the foreground.
7. In the Program Arguments section, specify any application-specific arguments that you want to pass to the command line.
8. Select the Environment tab to bring it to the foreground. In this tab, you can set the environment variables for your debug session; these settings will only affect your debug session. You might need to set environment variables for a variety of factors, for example, to specify the location of the executable for an application that is required for the debug session. To set environment variables in this tab, perform any of the following tasks:
   • To add an environment variable for the debug session, click New, and then complete the New Environment Variable dialog box with the appropriate values. The new environment variable is added to the list of default environment variables.
   • To select the environment variables to use while debugging, click Select to open the Select Environment Variables dialog box. Select the environment variables that you want the z/OS UNIX application to use while debugging.
   • To edit the name or value of an existing environment variable, select the variable and click Edit.
   • To remove an environment variable for the debug session, select it from the Environment variables to set list, and then click Remove.
   • Select the Append environment to native environment radio button to specify that you want to add the selected environment variables to the native environment.
   • Select the Replace native environment with specified environment radio button to specify that you want to replace the native environment with the selected environment variables.
9. To set the Source Lookup Path to specify where the debugger should find source files when stepping or hitting breakpoints, select the Source tab and perform any of the following tasks:
   • To add a source location, click Add to open the Add Source dialog box. From the selection list, specify the type of source location that you want to add. For example, to add source folders on z/OS UNIX System Services to the source search path, select Remote Folder. All other selections open a dialog box in which you can enter or browse for the source search path location that you want to use.
   • To remove an existing entry, select a source location and click Remove.
   • To set the order of existing entries, select a source location and click Up or Down to alter the placement of the selected location.
     Note: In some cases, changing the placement of a location might not take effect until the next time the z/OS UNIX application is launched.
   • To search for all instances of the source file name in the source search path, select the Search for duplicate source files on the path check box. If you select this check box and the debugger finds multiple instances of the file name, you are prompted to select the correct source file.
   Note: By default, the debugger looks up the remote working directory. If this lookup fails, the debugger reverts to the debug engine for source lookup.
10. In the Advanced tab, perform the following tasks:
    1. Do one of the following:
       • To specify you want to use z/OS Debugger to debug z/OS Unix applications, select IBM® z/OS Debugger from the Engine combination box.
       • To specify that you want to use dbx to debug z/OS UNIX application, select DBX from the Engine combination box.
    2. If you choose to use dbx for debugging, do one of the following to specify where the debug engine resides on the host:
       • Click the Automatically detect the location of the debug engine radio button to specify that you want the location of dbx to be determined automatically.
       • Click the Specify location of the debug engine radio button and in the Location of the debug engine field, type the full path to the dbx debug engine or click Browse to browse for the location. In the Library Search Path section, add the search path that will be used to pick up the libraries that the dbx program requires to run.
11. Select the Common tab to bring it to the foreground. You can perform the following tasks in the Common tab:
    • If you want the launch configuration to be stored locally and available for a single user, ensure that the Local file radio button is selected. If the launch configuration is to be stored as a file in the workspace and shared in a repository for team use, select the Shared file radio button and type a location to save the launch configuration in. Alternatively, you can browse for the location.
    • If you want the launch configuration to be displayed as a favorite debug configuration in the Debug push button favorites menu or the Debug menu Debug History list, select the Debug check box.
    • In the Standard Input and Output section, indicate the location of the Console view input and output.
    • To run the launch configuration in the background, select the Launch in background check box.
12. If all information mandatory to the launch configuration has been provided, the Debug and Apply push buttons are enabled. Click Apply to save the launch configuration, and then do one of the following:
    • Close the dialog box without launching the debug session.
    • Click Debug to launch a debug session using the new launch configuration. If you click Debug, any changes to the launch configuration are saved and a debug session is launched.
    Tip: If you have not yet saved the launch configuration settings and you have made entries in the launch configuration settings that you want to remove or change, click Revert to remove all changes that you have made.
13. If information mandatory to the launch configuration has not been provided or if there are errors in the information that you have provided, messages are displayed at the top of the dialog box to indicate what is missing.
14. If you did not use the dialog box to launch a debug session (for example, you used it instead to create and save a launch configuration), click Close to exit the dialog box when you are finished working in it.