DEBUG messages

Telnet-specific debug messages can be turned on or off to diagnose Telnet problems related to client connections, Telnet tasks, or configuration processing. Several types of debug messages are available.

Exception messages indicate that a problem was detected and are issued for connection, task, and configuration processing. Exception level debug is the default level.
Summary messages indicate important status changes and are available for connection processing.
Detail messages are issued when an important event occurs other than an error and are available for connection and task processing.
Trace messages show detail data that is coming into and out of Telnet and are available for connection and configuration processing.

Message generation is controlled with the DEBUG statement. For information about the DEBUG statement, see z/OS Communications Server: IP Configuration Reference.

Connection processing debug options are as follows:

Exception
The DEBUG CONN EXCEPTION statement issues a message at the time of failure that displays the client IP address and port, connection ID, Telnet LU name, detecting module name, unique return code and brief explanation, and additional parameters if relevant. Some messages will be helpful to you and others will be helpful to IBM® service. For message EZZ6035I return code details, see z/OS Communications Server: IP Messages Volume 4 (EZZ, SNM).
The DEBUG CONN EXCEPTION statement causes the CONN DROP message to be issued only for error conditions and inactivity reasons. DEBUG CONN EXCEPTION is the default. If more than one connection is dropped for the same reason within 15 seconds, a single message with LU name MULTIPLE will be issued. For example, if MSG07 is not coded in the DEBUG CONN DETAIL example, the connection will be dropped after the lookup failure. The CONN DROP message will include the return code and indicate that an error caused the connection drop. The following message will be produced whether or not DEBUG was coded because of the error condition.
```
 EZZ6034I TNSERV11 CONN 00000011 LU TCPM1001 CONN DROP  ERR 3012
   IP..PORT: 1.12.13.14..456          EZBTPGLU
```
Summary
The DEBUG CONN SUMMARY statement provides tracking for the status of a connection. A summary message is written when:
- A connection request is accepted by Telnet.
- Connection negotiation is complete.
- A session is established with the host application.
- A session is dropped.
- A connection is dropped.
LU name, Connection ID, and client IP address and port are included in each message. In the example below a user connects to port 23. The connection is negotiated as a TN3270E connection and a session with TSO is established. The session is dropped because of client disconnect (CLNTDISC) and then the connection is dropped because of client disconnect.
```
EZZ6034I TNSERV11 CONN 00000011 LU **N/A**  ACCEPTED      23
  IP..PORT: 1.12.13.14..456
EZZ6034I TNSERV11 CONN 00000011 LU TCPM1001 NEGOTIATED TN3270E
  IP..PORT: 1.12.13.14..456
EZZ6034I TNSERV11 CONN 00000011 LU TCPM1001 IN SESSION TSO0001
  IP..PORT: 1.12.13.14..456
EZZ6034I TNSERV11 CONN 00000011 LU TCPM1001 SESS DROP  CLNTDISC
  IP..PORT: 1.12.13.14..456
EZZ6034I TNSERV11 CONN 00000011 LU TCPM1001 CONN DROP  CLNTDISC
  IP..PORT: 1.12.13.14..456
```
In addition to tracking major state changes and providing key information, the statements can be used for diagnostic purposes. For example, a user might be attempting a connection and something is not working. The ACCEPTED, NEGOTIATED, and IN SESSION messages are major connection milestones. Using the information provided and knowing whether or not these messages are displayed can provide many clues about the connection request. The SESS DROP and CONN DROP messages give a variety of reasons about why the drop occurred.
Detail
You can use the DEBUG CONN DETAIL statement if the DEBUG CONN SUMMARY messages do not provide enough information to solve a problem. In addition to the summary messages, the DEBUG CONN DETAIL statement issues a message at the time of failure that displays the client IP address and port, connection ID, Telnet LU name, detecting module name, unique return code and brief explanation, and additional parameters if relevant. Some messages will be helpful to the system administrator and others will be helpful to IBM service. For message EZZ6035I return code details, see z/OS Communications Server: IP Messages Volume 4 (EZZ, SNM).
In the example below the user specified an application not in the Telnet profile and then disconnected at the client emulator.
```
EZZ6035I TNSERV11 DEBUG DETAIL CONN DETAIL 
  IP..PORT: 1.12.13.14..456
  CONN: 00000011  LU: TCPM1001  MOD: EZBTPGLU
  RCODE: 3012-00  Application name is invalid.
  PARM1: 00000000 PARM2: 00000000 PARM3: 00000000

EZZ6035I TNSERV11 DEBUG DETAIL CONN DETAIL 
  IP..PORT: 1.12.13.14..456
  CONN: 00000011  LU: TCPM1001  MOD: EZBTTRCV
  RCODE: 1001-02  Client disconnected from the connection.
  PARM1: FFFFFFFF PARM2: 00000461 PARM3: 00000000
```
Trace
The DEBUG CONN TRACE statement generates messages that contain data that was sent to and from the client, sent to and from VTAM®, and sent to and from an LU name exit for a single connection. The TRACE option allows you to quickly see why a client is not connecting or why a session hangs. Be careful where you specify DEBUG CONN TRACE. Every connection that maps to the statement generates many messages. DEBUG CONN TRACE should be specified in a PARMSGROUP block that is mapped to only a few connections. Even when DEBUG CONN TRACE is specified in a PARMSGROUP block, it could flood the message console quickly if the connection is very active.
```
EZZ6034I TNSERV11 CONN 00000080 LU **N/A** ACCEPTED
  IP..PORT: 9.14.6.42..36484
EZZ6035I TNSERV11 DEBUG CONN TRACE 
  IP..PORT: 9.14.6.42..36484
  CONN: 00000080  LU:           MOD: TO  CLNT
  <-C- FFFD28
  PARM1: 00000003 PARM2: 00000000 PARM3: 00000000
EZZ6035I TNSERV11 DEBUG CONN TRACE 
  IP..PORT: 9.14.6.42..36484
  CONN: 00000080  LU:           MOD: FRM CLNT
  -C-> FFFB28
  PARM1: 00000003 PARM2: 00000000 PARM3: 00000000
EZZ6035I TNSERV11 DEBUG CONN TRACE 
  IP..PORT: 9.14.6.42..36484
  CONN: 00000080  LU:           MOD: TO  CLNT
  <-C- FFFA2808 02FFF0
  PARM1: 00000007 PARM2: 00000000 PARM3: 00000000
```

Task processing debug options are as follows:

Exception
The DEBUG TASK EXCEPTION statement issues a message at the time of a failure that displays the task, detecting module name, unique return code and brief explanation, and additional parameters if relevant. Some messages will be helpful to you and others will be helpful to IBM service. For message EZZ6035I return code details, see z/OS Communications Server: IP Messages Volume 4 (EZZ, SNM). DEBUG TASK EXCEPTION is the default for task processing debug.

The following exception message indicates that Telnet failed to join the XCF group because the group already contains the maximum number of members allowed.
```
EZZ6035I TLUNR1   DEBUG TASK   EXCEPTION
TASK: XCF                      MOD: EZBTXXCF              
RCODE: A006-01  Telnet failed to join the XCF group.
PARM1: 0000000C PARM2: 00000004 PARM3: MAX GROUPS OR MEMBERS
```
Detail
The DEBUG TASK DETAIL statement issues a diagnostic message at certain event points that displays the task, detecting module name, unique return code and brief explanation, and additional parameters if relevant. The Detail option shows event milestones for different scenarios, enabling you to see some events of interest other than errors. Some messages will be helpful to the system administrator and others will be helpful to IBM service. For message EZZ6035I return code details, see z/OS Communications Server: IP Messages Volume 4 (EZZ, SNM).

The following detail message indicates that an outstanding receive failed for job TLUNR1 on MVS023.
```
EZZ6035I TLUNR1   DEBUG TASK   DETAIL    
TASK: XCFRECV                MOD: EZBTXRCV              
RCODE: A014-01  LUNS/LUNR receive failed.               
PARM1: 00000000 PARM2: 00000000 PARM3: MVS023   TLUNR1
```

Configuration processing debug options are as follows:

Exception
The DEBUG CONFIG EXCEPTION statement issues a message at the time of a failure that displays the line number, detecting module name, unique return code and brief explanation, and additional parameters if relevant. Some messages will be helpful to you and others will be helpful to IBM service. For message EZZ6035I return code details, see z/OS Communications Server: IP Messages Volume 4 (EZZ, SNM). DEBUG CONFIG EXCEPTION is the default for configuration processing debug.

The following message indicates that the value for scaninterval on line 35 is outside of the acceptable range.
```
EZZ6035I TLUNS1   DEBUG CONFIG EXCEPTION        
LINE:       35               MOD: EZBTMPRP                     
RCODE: 805B-00  Value outside acceptable range for statement.  
PARM1:          PARM2: SCANINTE PARM3:
```

Trace

The DEBUG CONFIG TRACE statement generates a statement message listing all words associated with the statement and a formatted control block message for each Telnet statement. This option can flood the message console if you have a very large configuration file. The CONFIG messages can be limited to a smaller, specified set of statements. If you specify a subset of statements, DEBUG CONFIG messages are issued only from those statements. If a large amount of CONFIG data is required, you can suppress the DEBUG messages by specifying the CTRACE option on the DEBUG statement. With the CTRACE option, the messages will be in the CTRACE but will not flood the console or joblog. CTRACE is the default option.

The sample below shows data sent to the console for profile statement LUGROUP:

DEBUG CONFIG TRACE,LUGROUP CONSOLE

EZZ6035I TNSERV11 DEBUG CONFIG TRACE   
  LINE:       82               MOD: EZBTMPRF   
    LUGRP1 TCPM1094 TCPM1102     
  PARM1: 00000003 PARM2: 00000052 PARM3: LUGROUP                                              
       
EZZ6035I TNSERV11 TNSERV11 DEBUG CONFIG TRACE
  LINE:       82               MOD: EZBTMPRF                    
         E3C5D3C3 00000000 00000058 00005502 |TELC............| 
         00000036 00000000 00000052 00000000 |................| 
         00000000 00000000 00000000 00000000 |................| 
         D3E4C7D9 D7F14040 00000000 00000000 |LUGRP1  ........| 
         00000002 00000000 E3C3D7D4 F1F0F9F4 |........TCPM1094| 
         E3C3D7D4 F1F1F0F2                   |TCPM1102        | 
  PARM1: 00000058 PARM2: 00000036 PARM3: LUGROUP

The DEBUG OFF statement ensures that all debug messages are suppressed , including the exception CONN DROP messages.

The DEBUG CONN parameter can cause flooding of the operator's console. Console flooding concerns can be dealt with in several ways.

Most DEBUG messages are, by default, assigned to routing code 11, the JOBLOG. The DEBUG option JOBLOG can be used for the same effect. However, the master console also receives routing code 11 messages by default. To stop the messages from going to the master console, issue VARY CN(01),DROUT=(11), which drops routing code 11 from the console. Another DEBUG option, CONSOLE, will direct the messages to the master console, routing code 2, and the teleprocessing console, routing code 8. The CTRACE option suppresses messages completely while continuing tracing at the debug level.
If DEBUG messages are being used primarily for problem diagnosis, the VARY TCPIP,tnproc,OBEYFILE command can be used to keep the number of messages low. Start Telnet initially without DEBUG coded. When a problem appears, issue a VARY TCPIP,tnproc,OBEYFILE command for a Telnet profile that includes the DEBUG statement. Only new connections to the new profile will produce messages. After data is obtained, issue another VARY TCPIP,tnproc,OBEYFILE command for a Telnet profile that omits the DEBUG statement.
If the Client Identifier of the client having the problem is known, include DEBUG in a PARMSGROUP statement. Using PARMSMAP, map that group to the client. Debug messages for only that client will be issued.

The VARY TCPIP,tnproc,TELNET,DEBUG,OFF command can be issued to turn off DEBUG for all connections associated with all profiles, including the current profile. It will also turn off TASK and CONFIG DEBUG messages. To turn on DEBUG again, issue a VARY TCPIP,tnproc,OBEYFILE command with the Debug option specified in the Telnet profile. Summary messages for CONN DROP due to errors or time-outs will also be suppressed. Use DEBUG EXCEPTION to retain these messages.