QMF provides a facility that traces QMF activity during a user's session. Trace output from the facility can help you analyze errors such as incorrect or missing output, performance problems, or loops. This section shows you how to allocate storage for the trace output, how to start the facility and determine the level of tracing detail, and how to view the trace data for diagnosis.
Follow these instructions for using the trace facility on z/OS.
Certain procedures in this book rely on abend information as well as trace information that QMF records in the DSQDEBUG data set.
Trace information is recorded in the DSQDEBUG data set. You can find abend dump information in the DSQUDUMP and SYSUDUMP data sets. Make sure that these data sets are allocated before you begin the QMF session. The data sets are automatically allocated by the LOGON procedure for the user ID under which you intend to operate.
Check with TSO administration if you are not sure whether these data sets are automatically allocated before a QMF session. If they are not, issue the following TSO statements before you invoke QMF for your diagnostic session.
ATTR DEBUG RECFM( F B A) LRECL(121) ATTR DUMP RECFM( F B A) LRECL(125) ALLOC DDNAME(DSQDEBUG) SYSOUT(A) USING(DEBUG) ALLOC DDNAME(DSQUDUMP) SYSOUT(A) USING(DUMP) ALLOC DDNAME(SYSUDUMP) SYSOUT(A)
The trace is recorded in the DSQDEBUG data set. This data set should be allocated in the CICS startup JCL. The trace can be shared between all users in the same CICS address space.
The trace facility writes trace results into the DSQDEBUG data set, which can be printed or displayed. This data set is used for trace purposes only.
With these options, you control what is traced and the level of detail.
Specify a value of ALL on the DSQSDBUG program parameter when you start QMF. This value traces QMF activity at the highest level of detail, including program failures that might occur during QMF initialization.
You need to use a transient data queue to hold the output if it exceeds 32, 767 rows.
During a QMF session, some set of tracing options is always in effect. You can override current trace options in several different ways:
SET PROFILE (T=valuewhere value is ALL or a string that indicates QMF functions and their levels of detail in the trace output.
CONNECT JONES (PA=MYPW
Looking at DSQDEBUG helps you understand the reason for the error.
You can display or print the DSQDEBUG file for analysis.
If you want to trace all QMF functions at the most detailed level, use a value of ALL for the trace.
If you want to trace individual QMF functions, update the TRACE column of Q.PROFILES with a character string that has letters for the QMF functions you want to trace and numbers for the level of detail you want in the trace data for each function. You need to pair each letter with a number:
Only the functions you specify in the character string are traced. The letter for each QMF function is shown in the following list.
For example, to trace message and command logging at the most detailed level, application support services at a medium level, and common services and systems interfaces at the most detailed level, use this command:
SET PROFILE (T=L2A1C2
Use the L1 and L2 trace records to precisely record user activities during a QMF session. A value of L1 writes records for all messages issued by QMF; L2 writes all the L1 records, plus additional records describing the execution of QMF commands. Use the L2 trace code to log each command a user issued and how QMF responded to that command. Figure 118 shows an example of a RUN QUERY command that failed because the user named columns that were not in the table.
-------------------------------------------------------------------- ---------- ****** 93/12/15 20:39 ****** ----------------- USERID: KRIS AUTHORIZATION-ID: KRIS COMMAND TEXT: RUN QUERY -------------------------------------------------------------------- -------------------------------------------------------------------- ---------- ****** 93/12/15 20:39 ****** ----------------- USERID: KRIS AUTHORIZATION-ID: KRIS MESSAGE NUMBER: DSQ12405 MESSAGE TEXT: Column name DATE is not in table STAFF. &O1: DATE &O2: STAFF &O9: -205 --------------------------------------------------------------------
Within the DSQDEBUG data set, the messages appear chronologically. When commands are included, they also appear chronologically and are intermixed with the messages. A message is associated with the command that precedes it in the data set or file.
QMF messages have variables for parts of the message that change, such as a table or column name. You can use the trace data to help a user decipher a message that includes variables. For example, the message shown in Figure 118 appears in DB2 QMF Messages and Codes as:
Column &01 is not in table &02.
The bottom half of Figure 118 shows that the value for &01 in the message is DATE and that the value for &02 is STAFF. Substitute these values into the message to help a user solve the problem.
These variables might also appear in the definition of the help panels associated with the error message. Use the variable values from the trace data together with the help command to reconstruct the message help panel.
Important: Perform a trace at the module level only under IBM Service Level 2 guidance.
You can turn on a trace for certain modules using the SET PROFILE command and the module DSQUTRAC. For example, you can trace the formatter buffer manager without tracing the line manager or the summary manager. The values for module-level tracing are:
To create a module-level trace, list the modules you want traced in the DSQUTRAC module. Then assemble and link-edit the module. After the module is created, you must make it available. You can then run the following command:
SET PROFILE (TRACE F4
DSQDEBUG holds the information recorded by the trace facility. It must be allocated before you start QMF if tracing is to be used. You can allocate the data set to print or display it.
In CICS, depending on the number of users and the levels of detail at which their sessions are traced, the trace data might be very long.
The DSQDEBUG data set might have been allocated automatically through your LOGON profile in a TSO environment. Even so, you can reallocate it if the original allocation does not fill your needs (for example, the original allocation might define DSQDEBUG as a PRINT file when you really want to display it).
To allocate (or reallocate) for printing, issue the following statements, which define DSQDEBUG as a PRINT file:
FREE FILE(DSQDEBUG) ATTR DEBUG RECFM( F B A) LRECL(121) ALLOC DDNAME(DSQDEBUG) SYSOUT(A) USING(DEBUG)
The allocation contains fixed-length, 121-character records whose first byte is an ANSI carriage-control character. The trace information is formatted with 120 characters to the line, not including the ANSI control character.
Reminder: If you allocate output from DSQDEBUG to go to the HOLD queue, to release the output to the OUTPUT queue, you must issue the following TSO command:
FREE DDNAME(DSQDEBUG)
You can also issue the following statements to allocate (or reallocate) DSQDEBUG as a sequential data set that can be displayed using an online editor. The data set consists of fixed-length, 81-character records whose first byte is an ANSI carriage-control character. The trace information is formatted with 80 characters to a line, not including the ANSI control character.
FREE FILE(DSQDEBUG) ATTR DEBUG RECFM( F B A) LRECL(81) ALLOC DDNAME(DSQDEBUG) DSNAME(DEBUG.LIST) NEW KEEP
The trace is recorded in the DSQDEBUG data set. Allocate this data set in the CICS startup JCL.
If you have a warning or a system error during QMF initialization, you must look at the QMF trace data set to understand the reason for the error. In CICS, the trace data set is described as an extra region data set. The trace data set is described in CICS tables by a DCT TYPE=SDSCI command and a DCT TYPE=EXTRA command, as in Figure 119.
* TRACE DATA SET DFHDCT TYPE=SDSCI,DSCNAME=DSQDEBUG, RECFORM=VARBLK, RECSIZE=121, BLKSIZE=6050, TYPEFILE=OUTPUT * * TITLE 'DSQDCT - CICS DESTINATION CONTROL TABLE' * * TRACE DATA SET * DSQD DFHDCT TYPE=EXTRA,DESTID=DSQD,DSCNAME=DSQDEBUG,RSL=1
QMF trace data from all the QMF users in a single CICS region are written to a single trace data set. Each trace entry contains the terminal ID of the user that recorded it.
To look at the trace data set while the CICS region is active, you must close the trace data set using the CICS queue ID DSQD. You can use this ID while using the CICS-supplied transaction CEMT. After the trace data set is closed, you can print or browse it.
While the trace data set is closed, no other records are written by CICS users. In this state, QMF continues to operate without recording trace records. To make the QMF trace available again, you can use the CICS-supplied transaction CEMT to open the trace data set using the CICS queue ID DSQD.
The service level information is displayed:
You can determine the QMF service level using the following procedure:
The resulting trace shows the program with its version, date, and time. The trace can also show an Authorized Program Analysis Report (APAR) number if the module has a Program Temporary Fix (PTF) applied, as in the following trace example:
** DSQFQWRM: ENTERED FROM DSQFMCTL *** V7R2.00 00/01/30 12:00 PNxxxxx
APAR PNxxxxx is the most recent APAR for which service was applied.
After you capture diagnostic details using the trace facility, you might want to turn tracing off, because the storage queue for the trace data can fill up very quickly.
To turn tracing off, issue the following command from within QMF:
SET PROFILE (T=NONE
If you leave tracing on until you end the QMF session, when you start QMF the next time, the tracing is set to NONE by default. The program parameter DSQSDBUG controls this tracing when QMF is started.