Creating a debug profile for an IMS application using IMS Isolation with an Eclipse IDE

You can create and activate an IMS Isolation profile to isolate the debug session from other users by starting the debugger in a private IMS region. Only one private region can be started and one IMS Isolation or non-CICS profile can be active at a time.

1. Open the z/OS Debugger Profiles view.
2. To create an IMS Isolation profile, open the Debug Profile Editor in one of the following ways:
   • Click the Create IMS Isolation Profile icon () in the view toolbar.
   • Right-click in the view and select Create IMS Isolation Profile.
3. In the Debug Profile Editor, Specify appropriate values. To navigate to a field, you can also use the quick outline.

   Show/Hide Hints

   Click this link to show or hide descriptions for sections.

   Profile name

   Specify a profile name. A name is automatically generated when you create a new profile. You can use this name or specify a different one, but the name must be unique.

   Optional: Description

   Specify a description for the profile. The description is stored locally and visible in the z/OS Debugger Profiles view to help you identify a profile.

   Connection

   Select the Remote System Explorer z/OS connection where the profile is active. If no connection is available, click New to create a new z/OS connection.

   Location

   Specify the location of the profile.

   • If you are connecting to a Remote System Explorer z/OS connection that supports the Debug Profile Service API, the location name is automatically retrieved from the API and cannot be modified.
   • If you are connecting to a Remote System Explorer z/OS connection that does not support the Debug Profile Service API or Debug Profile Service is not running, you must specify the name of the EQAUOPTS file where the IMS Isolation profile is stored. This field is prefilled with the IBM shipped default EQAUOPTS file, but the file might have been changed by your system programmer. Confirm with the system programmer about the correct value.

   ADFz Common Components Server Port

   Specify the port number where the ADFz Common Components server is running. Ensure that your system programmer installed and configured the IMS transaction isolation extension for the ADFz Common Components server, and the IMS Isolation API is enabled.

   Note: This field is disabled if Debug Profile Service can be used to access IMS Transaction Isolation Facility.

   Default Encoding

   Select the encoding to communicate with the ADFz Common Components server. The default option is Cp037.

   Note: This field is disabled if Debug Profile Service can be used to access IMS Transaction Isolation Facility.

   IMS Isolation Configuration

   IMS System ID

   Select an IMS system ID from the list retrieved from the host. You must select a system ID to add transactions.

   Region Name

   Specify the region name for the private region. This option can be specified only if Debug Profile Service is running on the selected RSE connection with z/OS Debugger 16.0.0 or later, or the ADFzCC server is used with z/OS Debugger 15.0.3 or later, with the PTF for APAR PH41774 applied. Otherwise, it defaults to @&USER, where &USER is replaced with the user ID that is authenticated via Remote System Explorer when you register the transaction, start the private region, or activate the profile.

   Job Class

   Specify a character to be used as the job class for the isolated region. Valid characters are A-Z, 0-9. Leave the field blank to use the default job class. This field is only enabled when IMS Isolation support is provided via Debug Profile Service.

   Transactions

   At least one transaction must be added and selected for registration in the IMS Isolation profile. Checked transactions are registered for debugging with the IMS Transaction Isolation Facility. Use the following buttons to update the transaction table:

   Add

   Open the Transaction dialog where you can select one or more transactions to add to the profile. If you are using Debug Profile Service, specify a filter and press Enter or click Refresh to retrieve a list of transactions before selection.

   Note: You need to specify the exact transaction name or use the wildcard (*) to get a list of transactions that match the pattern.

   Remove

   Remove selected transactions from the table.

   Set Pattern

   Open the Modify Routing Pattern window to specify the following transaction routing pattern information:

   Message

   The pattern matching message text. The maximum length is 32 bytes.

   Range Start

   Specify at which index that message text matching should begin. The maximum length is 32767.

   Range Length

   Specify the pattern length to search for during message text matching. The maximum length is 32767.

   Case sensitive

   Indicate that the pattern matching message text is case sensitive.

   Message is hexadecimal

   Indicate that the pattern matching message text is in hexadecimal.

   Start/Stop Region

   Depending on the status of the private region of the selected transaction, clicking this button either starts or stops the region associated with the transaction.

   Refresh

   Connect to the IMS Transaction Isolation Facility and refresh the transaction information in the table.

   STEPLIB

   Use the entry field to add a user library to the list of libraries that will be added to the STEPLIB in the JES job that creates the private region. The following buttons can be used to update the list:

   Add

   Add the library in the entry field to the list.

   Browse

   Find the library that you want to add with Remote System Explorer.

   Remove

   Remove the selected libraries from the list.

   Move up

   Move the selected libraries up in the list.

   Move down

   Move the selected libraries down in the list.

   Filters

   Load Module or DLL/Program or C Function

   Specify at least one to a maximum of eight load module or DLL and program or C function pairs. Double-click or press Enter in the table to add or modify an item.

   Note: Avoid using only the wildcard (*) for both load module or DLL and program or C function in the same pair unless you want to debug all applications.

   Optional: Debugger Options

   Test level

   Select TEST or NOTEST from the list of TEST runtime options.

   TEST

   Use this option to give z/OS Debugger control according to the specified options.

   • If z/OS Debugger is started with CEETEST, PLITEST, or __ctest(), the options in the debug profile are used.
   • If z/OS Debugger is started by using CALL CEETEST or an equivalent entry, you cannot debug higher-level non-Language Environment® programs or intercept non-Language Environment events that occur in higher-level programs after you return from the program that started z/OS Debugger.

   NOTEST

   Use this option so that z/OS Debugger is not started at program initialization. However, you can still start z/OS Debugger with CEETEST, PLITEST, or the __ctest() function. In this case, the suboptions specified with NOTEST are used when z/OS Debugger is started.

   Error level

   Select ALL, ERROR or NONE from the list of TEST runtime suboptions.

   ALL

   Specifies that the following occurrences cause z/OS Debugger to gain control, regardless of whether a breakpoint is defined for that condition.

   • An attention interrupt
   • An ABEND of a program
   • Any program or Language Environment condition of Severity 1 and above

   ERROR

   Specifies that only the following conditions cause z/OS Debugger to gain control without a user-defined breakpoint:

   • For C and C++: an attention interrupt, program termination, a predefined Language Environment condition of Severity 2 or above, any C and C++ condition other than SIGUSR1, SIGUSR2, SIGINT, or SIGTERM.
   • For COBOL: an attention interrupt, program termination, a predefined Language Environment condition of Severity 2 or above.
   • For PL/I: an attention interrupt, program termination, a predefined Language Environment condition of Severity 2 or above.

   NONE

   Specifies that z/OS Debugger gains control from a condition only when a breakpoint is defined for that condition.

   Prompt level

   Select PROMPT or NOPROMPT from the list of TEST runtime suboptions.

   PROMPT

   Indicates that you want z/OS Debugger to start immediately after Language Environment initialization. Commands are read from the preferences file and then any designated primary commands file. If neither file exists, commands are read from your terminal or workstation.

   NOPROMPT

   Indicates that you do not want z/OS Debugger to start immediately after Language Environment initialization. Instead, your application begins running.

   If you specify the NOPROMPT suboption, you cannot debug higher-level non-Language Environment programs or intercept non-Language Environment events that occur in higher-level programs after you return from the program that started z/OS Debugger.

   When z/OS Debugger is running without the Language Environment runtime started by using EQANMDBG, the NOPROMPT option is ignored; PROMPT is always in effect.

   Commands data set

   Specify a valid fully qualified data set name that contains the initial debugger commands to run when the debug session starts, or click Browse to select a data set. A valid VADSCPnnnnn entry is also accepted.

   Note: Not all commands are permitted in remote debug sessions. You might see errors in the Debug Console view if such commands are included in the commands data set.

   Preferences data set

   Specify a valid fully qualified data set name that contains debugger commands that customize your debug session, or click Browse to select a data set.

   Note: Not all commands are permitted in remote debug sessions. You might see errors in the Debug Console view if such commands are included in the preferences data set.

   EQAOPTS file

   Specify the name of the data set containing the EQAOPTS commands for your debug session, or click Browse to select a file.

   Language Environment options

   Specify any additional Language Environment (LE) options that your program might need. You can change any Language Environment option that your site allows you to override except the STACK option. This option is not available for non-CICS® profiles.

   Optional: Advanced Connection Options

   Specify these options to connect to a client other than the current one, such as for headless code coverage or to send a debug session to another user’s client.

   Connect with specific client information

   Select this option to force the debug profile to use connection information that you specify. Specify either an IP and port, or a user ID.

   IP

   Specify the IP name or address to connect with when the debug or code coverage session is triggered.

   Port

   Specify the TCP/IP port that the debug daemon or headless code coverage collector is listening for incoming sessions.

   User ID

   Use this option when Debug Manager is running, and you want to send a debug session to another user’s client. That user must be signed into Remote System Explorer.

4. Click the Save without Activating icon () to save the profile without activation, or the Save and Activate for Debug icon () or the Save and Activate for Compiled Code Coverage icon () in the editor toolbar to save and activate the profile on the remote connection.
   Optionally, press M1+S^a to save without activating, M1+D^a to save and activate for debug, or press M1+M2+C^a to save and activate for code coverage.

   1. M1 is the COMMAND key on macOS, and the Ctrl key on most other platforms. M2 is the SHIFT key.