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.
About this task
The IMS Isolation profile contains the following pieces of information:
- The private region and transactions details to be configured by the debugger. The private region options are stored only in the Eclipse workspace, and are used to configure transactions and start the private region before you debug or run code coverage.
- The filters to trigger the debugger and other debugger configuration options. The filters to trigger the debugger are stored in sequential data set called an EQAUOPTS file, just as a non-CICS profile.
Note: IMS Isolation profiles are only available in IBM® Developer for z/OS® Enterprise Edition.
Procedure
- Open the z/OS Debugger Profiles view.
-
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.
- 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.
- If z/OS Debugger is started with
- 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 withNOTEST
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
, theNOPROMPT
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.
- 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.