MustGather: Collect Troubleshooting Data for Read First/Fix List for TSO/VTAM for z/OS Communications Server

Resolving The Problem

Table Of Contents

Section 1: General Information
Section 2: Common Problems

• Section 2.1: IKT00405I
• Section 2.2: ABEND0AB
• Section 2.3: Hung Address Space

Section 3: Gathering Documentation

Section 1: General Information

TSO/VTAM is a VTAM application program that is included with VTAM. TSO/VTAM allows terminal users to have access to the command processors, terminal monitor programs, and all other TSO facilities while using VTAM as the access method. TSO/E is included as part of the MVS operating system.

The major elements in a TSO/VTAM time-sharing system are the Terminal Control Address Space (TCAS) and VTAM terminal I/O coordinator (VTIOC).

After the system operator issues a START command to start TSO/VTAM time sharing, an address space is created for TCAS as a VTAM application program. When a user attempts to log on to TSO/VTAM time sharing, TCAS accepts the logon request, creates an address space with a unique VTAM application ID for the user, and transfers control of the terminal to the newly created address space. The TSO Application controls the session by use of the TPUT, TGET, TPG, and Terminal Control macros. The data flow protocols are managed by VTIOC.

Back to top

Section 2: Common Problems

This section describes useful hints for analyzing the following TSO/VTAM problems:

1. IKT00405I SCREEN ERASURE CAUSED BY ERROR RECOVERY PROCEDURE
2. ABEND0AB S/0AB
3. HUNG TSO ADDRESS SPACE

Additional information about these types of problems and others can be found in the SNA Diagnosis Volume 1 manual.

Note: If you need to determine the terminal name as known by VTAM, use the following:
D net,TSOUSER,ID=your userid

Back to top

Section 2.1: IKT00405I

IKT00405I is generated whenever an I/O error condition is detected. An I/O error is considered to be a negative response to TPUT/TGET/TPG processing (conversely known as VTAM SEND/RECEIVE). There are many reasons why an I/O error can be generated, from hardware to an incorrect definition. To begin diagnosing:

1. The most common cause of this problem is an incorrect LOGMODE specification. To ensure that the correct LOGMODE has been used to establish the session, first log on to TSO and then display the user's terminal name with the following command:
   
   D net,ID=terminal name,SCOPE=ACT | ALL
   
   From the output, take note of the MODETAB and DLOGMODE names in IST861I and IST934I. If either is not what was expected, then correct the definition errors. If these are correct, then note the 16-character SID value in IST874I or IST635I. Use this value in the next command:
   
   D net,SESSIONS,SID=xxxxxxxxxxxxxxxx
   
   If the LOGMODE name specified in IST933I is not the same as in the previous display, then VTAM could not locate the DLOGMODE table or the LOGMODE name specified on the definition. Correct the table or name error. If the error message still occurs, then continue to the next step.
   
2. Try to isolate when the error occurs (for example, during initialization or at a certain point of execution of a particular application, and so on). Then gather the traces from section 3 of this document ("Gathering Documentation").

Back to top

Section 2.2: ABEND0AB

TSO/VTAM will create an abend s/0AB when an unrecoverable I/O error occurs during the session. Most of these abends do not produce a dump due to the nature of the cause.

A) If you receive an abend0AB without a matching dump, then on the system console there should be a IKT108I or IKT116I for the TSO user. The sense code provided in this message will describe why the session was terminated. In most cases, the user will be able to continue by doing a logon reconnect. Many times this abend will also produce an EREP Report Software LOGREC entry to further describe the abend cause. When this happens, the register 15 return code will indicate which RPL based macro failed as follows:

x'101' or x'103' IKTIMLUx failed for a Receive RPL

x'102' or x'104' IKTOMLUx failed for a Send RPL

x'105' Indicates a Bind/Unbind failure registers 6 and 7 will contain the RPL return code and feedback code.

SNA Programming will have descriptions of the RPLRTNCD and feedback code for each RPL type.

x'201' or x'202' Open ACB failure. Register 8 will contain the Open ACB error flag. Regs 9 and 10 will contain the TSO APPLID name. Refer to SNA Programming for a description of the ACB error flag.

B) If you receive a dump for an ABEND0AB, then make a note of the return code contained in register 15. Then load the dump in IPCS. From the main panel, select the ANALYSIS option. From this panel, select the SUMMARY option. The first control block that is formatted is the ASCB. Within the ASCB at offset x'3C' is a pointer to the TSB. Make a note of the ASCB and TSB control block addresses. Press PF3 until you return to the IPCS main panel. From here select the BROWSE option. Using the TSB address, go into the dump. The first word of the TSB contains a flag byte followed by the ASCB address (this is a 24-bit or 3 byte address). If this is correct, then proceed. If not, then check to ensure that correct addresses are being used from the SUMMARY output. Now add x'9C' to the TSB address. The word in this field is a pointer to the TVWA. This control block is typically built on a page boundary (i.e. an address like x'nnnnn000'). Go to this address. In EBCDIC the first 2 words contain the TSO User's APPLID. The next word or offset x'8' contains a ptr to the TVWATIMW control block. If register 15 was x'101' or x'103' then the Receive RPL needs to be examined. To get to this control block, add x'3D8' to the TVWATIMW address. If register 15 was x'102' or x'104' then the Send RPL needs to be examined. To get to this control block, add x'E98' to the TVWATIMW address. In either case, the RPL return code an feedback codes are within the RPL at offset x'D'. Refer to SNA Programming for a description of these codes. In most cases, the RPLRTNCD is x'0800'. If this is true refer to APAR OY05233.

Back to top

Section 2.3: Hung Address Space

This anomaly can also occur during a normal shutdown of TCAS. TCAS's address space will not completely terminate while there are OPEN ACBs for TSO sessions. While waiting on the user to supply a userid/pw, there is an OPEN ACB for the TSOnnnn application. These sessions have *LOGON* jobname. Therefore an FSTOP must be done to cleanup these users.

The "hung/waiting" TSO sessions are likely to wait for the user to Logon with the reconnect option.
TCAS reacts differently to the main two termination options. For SIC, a normal shutdown is requested. TCAS posts the Halt command ECB, and expects that the sessions will terminate normally. TCAS shuts down, which makes further commands unavailable.

For the other option, FSTOP, a forced shutdown is requested. An MVS MEMTERM is executed for all TSO address spaces.

Using the FSTOP option will also cleanup *LOGON* address spaces immediately. The SIC option will wait until the end user presses the enter key. Note: This is performing as designed.

If the hang condition can be recreated, then gather the trace information from section 3 ("Gathering Documentation"). When the hang occurs, take an SVC dump of the user's address space. When complete, contact the IBM Support Center for assistance in reviewing the data. If a recreate is not possible, an SVC dump of the user's address space may provide the information necessary to diagnosis the hang condition. The dump should contain one of the following storage areas:

• CSA, LSQA, PSA, RGN, SQA, SUM, SWA, TRT, LPA
• SDATA=(CSA,LSQA,PSA,RGN,SQA,SUM,SWA,TRT,LPA)

Which amount to the MVS dump command defaults plus RGN or the the user's CURRENT storage.

Back to top

Section 3: Gathering Documentation

Follow these instructions for setting up the traces. An MVS SERVICE AIDS MANUAL will be helpful. Before starting these traces, check SYS1.PARMLIB member TSOKEYxx (where xx is some number, usually 00) for a parameter CONFTXT=NO. If this parameter is not within the TSOKEYxx that was used to initiate TSO, then add the parameter and restart TSO before running the traces. Taking the default for this parameter will result in the VTAM buffer trace removing the RU data and replacing it with this message:
CONFIDENTIAL AND SUPPRESSED

The following commands must be entered from an MVS console:

1. When you start GTF use only trace OPTIONS USRP,SVCP
2. The system will prompt you for which SVC's to trace.
3. Reply to this message SVC=(93,94)
4. The system will prompt you for which USR records to trace.
5. Reply to this message USR=(FEF,FF1,FE2)
6. Then start a VTAM Buffer trace using the terminal name for the ID. The syntax is as follows:
   F net,TRACE,TYPE=BUF,AMOUNT=FULL,ID=terminal name
7. LOGON to TSO.
8. When the user is at the TSO READY prompt, enter MVS console command:
   F net,TRACE,TYPE=TSO,ID=
   where ID is the TSO USERID
9. Re-create the failure.
10. Stop the traces with the following commands:
    F net,NOTRACE,TYPE=BUF,ID=
    F net,NOTRACE,TYPE=TSO,ID=
11. Stop GTF, there is no need to stop the SVC traces.
12. ACFTAP will not format all of the trace record types.

To format the traces, you MUST use IPCS.
Using IPCS from the main panel select commands, then enter:
GTF USR(ALL) SVC(93,94)

Contact the IBM support center for assistance in reviewing the data if necessary.

Back to top