Question & Answer
Question
Are there any troubleshooting guidelines for situations that may arise when installing or customizing IBM Rational Development and Test Environment for System z?
Answer
Configuration and usage for Rational Development and Test Environment for System z is described in the Redbooks and configuration guide that are shipped with the product. Copies of the Redbooks are also available online at (http://www.redbooks.ibm.com/redbooks.nsf/searchsite?SearchView&query=zPDT) and the configuration guide is available on the product support page.
If you experience difficulty with Rational Development and Test Environment, you may find the following tables helpful for problem determination. These instructions assume a working knowledge of the Linux command line environment.
Note: The following troubleshooting tips are organized by the ordered steps that are defined in the installation checklist in the Rational Development and Test Environment for z Systems Installation and Sample Configuration Guide.
Begin by looking at the general troubleshooting tips, then look for your symptom in the particular process that is failing.
General troubleshooting tips
Symptom | Problem Determination |
For any problem after installation of Rational Development and Test Environment for z Systems (creating a devmap, installing z/OS, starting or stopping Rational Development and Test Environment for z Systems, z/OS networking issues, performance issues) | Validate the environment and the installation by running the z1090instcheck command and fixing errors. Do not worry about errors that are related to kernel.core_pattern unless the emulator is terminating abnormally. |
AWScccnnns message that is issued from the Linux terminal that is running Rational Development and Test Environment for z Systems. | Any message beginning with AWS is a zPDT message. Enter the following zPDT command
Where message-number is the 10 character message. This command displays more information about the reason for the message. See 4.1.36, “The msgInfo command” in the zPDT Guide and Reference Redbook. |
Installation of the Rational Development and Test Environment for z Systems
Symptom | Problem Determination | ||||||
Message CRIMA1076E in the install log when you are uninstalling a version of Rational Development and Test Environment for z Systems | Ensure you have performed the following steps to uninstall your release of Rational Development and Test Environment for System z:
If the uninstall still fails, perform the steps defined in the last entry of this table. . |
||||||
When you are attempting to run launchpad.sh or launchpad-console.sh, you get the following error:
|
This issue can happen for several reasons:
|
||||||
When you are attempting to perform an Installation Manager update for Rational Development and Test
Environment for z Systems, or to run launchpad.sh or launchpad-console.sh, you get one of the following errors:
Or
|
Do the following:
|
||||||
You receive any error message when you are uninstalling a previous version of Rational Development and Test Environment for z Systems. |
|
USB Hardware device activation and licensing
Troubleshooting the USB Hardware device activation and licensing
Symptom | Problem Determination |
Neither SecureUpdateUtility or Z1091_token_update does not apply the update file to the USB hardware device. | Do the following:
|
Unit not found message that is issued during the SecureUpdateUtility -u or the z1091_token_update command | This issue can happen for several reasons:
|
When you are starting Rational Development and Test
Environment for z Systems,
(awsstart) you get any of the following messages at the Linux terminal that indicaties a failure to get a license:
|
This issue can happen for several reasons:
|
When you are starting Rational Development and Test Environment for z Systems,
(awsstart) you get the following messages at the Linux terminal that
indicate an expired license
|
A replacement update file must be obtained from the Rational License Key Center when a license expires, and the update file must be applied to the USB hardware device being used. For more information, see “Steps to get the replacement file” in the Rational Development and Test Environment for z Systems Activation Guide (SC27-6630). |
Time cheat errors | Time cheat errors occur when the time stored on the USB hardware device is in the future when compared to the system clock of the Linux system it is plugged into. The USB device stores the latest date of the system clock it sees and will not provide licenses until the Linux system clock matches. Verify that the Linux system clock is correct. Have your system clock set to UTC to avoid errors that are caused by semi-annual time changes. There is no way to inspect the time on the USB key. However, you might wait a short time to see whether the Linux clock catches up to the time stored on the USB key. Do NOT set the Linux clock ahead of the actual time. If you suspect that the time stored on the USB key is in the future, contact IBM support. |
Installing z/OS volume images
Symptom | Problem Determination |
You get the following errors while performing a z1091_ADCD_install
command:
|
For information on possible causes, see the same symptom in "USB Hardware device activation and licensing". Also this can occur if the USB Hardware device, either local or in a product license server, has been updated with a .upw update file instead of a .zip update file. If you are migrating a Rational Development and Test Environment for z Systems instance from version 9 to version 9.1, you must request a new update file from the Rational License Key Center to install the ADCD S1RES1 and SARES1 volumes. |
Defining the Rational Development and Test Environment for z Systems machine characteristics (DEVMAP)
Symptom | Problem Determination |
Unable to run find_io command at create_devmap.pl | The path to the find_io command is not available. Ensure that you run aws_bashrc from the user ID that runs create_devmap.pl and Rational Development and Test Environment for z Systems. This updates the path to the needed files. |
Starting and stopping Rational Development and Test Environment for z Systems
Symptom | Problem Determination |
|
Ensure that you are starting Rational Development and Test Environment for z Systems from the home directory of the user who is created for running Rational Development and Test Environment for z Systems. Ensure that you have run the aws_bashrc command while logged on as that user, and from that user's home directory. |
The following messages occur during startup:
|
This message is seen with many awsckd definitions. The Linux kernel setting SHMMNI, which sets the system-wide maximum number of shared memory segments, is probably too low. The default is 4096. Try increasing this setting by adding kernel.shmmni = 8192 to /etc/sysctl.conf and activate it using the command sysctl -p. |
z/OS Networking issues
Symptom | Problem Determination |
General z/OS networking configuration errors | Do the following:
|
Unable to establish a network tunnel on a 10.x.x.x network. | On a 10.x.x.x network, you can establish the tunnel by configuring the
tunnel to be on a 192.168.1.x address. For example, configure the tunnel device in
the devmap as:
Configure z/OS TCP IP profile as a tunnel IP of
|
Cannot connect to Rational Development and Test Environment for z Systems z/OS using a remote 3270 terminal emulator | Do the following:
|
Cannot ping to a z/OS defined IP address on the Rational Development and Test Environment for z Systems instance | Do the following:
|
Cannot FTP or Telnet to a z/OS defined IP address on the Rational Development and Test Environment for z Systems instance | Do the following:
|
Symptom - z/OS Unicode Services Conversion Information Service failures with messages such as these: Telnet fails with message EZZ6023I, similar to the following:
FTP fails with EZYFT30E. No conversion available, similar to the following:
System Automation fails with message GEO252E BCPii fails with message HWI008I Sample ICONV job EDCICONV fails with message EDC4182 | Install the interim fix described in the technote "z/OS Unicode Services Conversion Information Service failures in Rational Development and Test Environment for System z after December 15, 2015" for each release of Rational Development and Test Environment for System z experiencing these problems. |
Performance
Troubleshooting performance issues
Symptom | Problem Determination |
High volume traffic through an emulated OSA-Express ethernet adapter on Rational Development and Test Environment for z Systems suffers poor throughput. | If newer Linux kernels are installed, you might experience
a drastic slowdown of OSA performance, This slowdown is immediately obvious and is due to Linux attempting to offload various functions into the adapter,
which is not acceptable to the current awsOSA implementation. One or more of the following commands,
intended to disable the Linux offloading of IP functions,
might improve the situation:
You might need to experiment with these commands. These commands must be entered after each Linux boot. If a script is used to start Rational Development and Test Environment for z Systems, such as the runzpdt script shipped with the product, that script can be modified to enter one or more of these commands each time Rational Development and Test Environment for z Systems is started. Effective combinations of these options differ with various Linux levels and with various NIC adapters. This problem was first noticed with Linux kernel level 2.6.36.2 If frames larger than expected are used, an excessive number of frames might be dropped (causing a re-transmission). This may not be noticed unless careful measurements or comparisons are made. This problem might be resolved by including the sysctl parameter that is now recommended:
For more information on zPDT performance and performance problems, see paragraph 2.3.4 “Performance” and 7.5.9 “Performance problems” in the zPDT Guide and Reference Redbook. |
Rational Development and Test Environment for z Systems performs slowly. CPUs reach 100% utilization. | Verify that you are meeting the minimum requirements for both the hardware and the software. See “Rational Development and Test Environment for z Systems prerequisites” and paragraph 2.3.2 “zPDT instances” in zPDT Guide and Reference Redbook |
For additional information about IBM Rational's Development and Test tools for System z, see the Rational System z Development and Testing Hub.
Was this topic helpful?
Document Information
Modified date:
27 October 2020
UID
swg21662343