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 OS/390.
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 258 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 258 appears in QMF Messages and Codesas:
Column &01 is not in table &02.
The bottom half of Figure 258shows 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 259.
* 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=1QMF 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.
Follow these instructions to use the trace facility on VM.
When you are using procedures involving trace information, ensure that the trace file is allocated before you begin the QMF session. This is true if the file is allocated by the PROFILE EXEC for a user ID. The default file name is DSQDEBUG.
Check with your VM administrator if you are not sure whether the file is allocated automatically before a QMF session. If it is not, issue the following CMS statement before you start QMF for your diagnostic session.
FILEDEF DSQDEBUG PRINTER (LRECL 121 RECFM FA PERM)
If the PROFILE EXEC takes you to QMF immediately after logon and logs you off VM when you terminate the QMF session, insert the preceding FILEDEF statement into the user's PROFILE EXEC file.
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. For more information on choosing trace options, see Getting the right level of detail in your trace output.
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.
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 260 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 260 appears in QMF Messages and Codesas:
Column &01 is not in table &02.
The bottom half of Figure 260shows 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 might have been allocated automatically through your PROFILE EXEC. You might want to 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 actually want to display it.
To allocate (or reallocate) for printing, issue the following statement which defines DSQDEBUG as a print file:
FILEDEF DSQDEBUG PRINTER (LRECL 121 FA PERM)
The allocation contains fixed-length, 121-character records hose 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.
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.
FILEDEF DSQDEBUG DISK DEBUG LIST (PERM RECFM FBA LRECL 81
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.
Follow these instructions to use the trace facility on VSE.
Choose either a CICS temporary storage or transient data queue to store trace data. If the trace data for the user's session does not exceed 32,767 rows, you can use CICS temporary storage or intrapartition transient data queues to contain it. If the trace data exceed 32,767 rows, define in the CICS DCT an extrapartition transient data queue that routes the output to a VSE file or SYSLST.
To define a transient data queue, update the CICS DCT with a 1-byte to 7-byte entry that points to the location that receives your trace data.
Figure 261 shows the definitions for the default queue, a transient data queue named DSQD that is allocated to a SYSLST. The default location is DSQDBUG.
DFHDCT TYPE=EXTRA, QUEUE FOR QMF EXTRA PROCESSING
DESTID=DSQD,
RSL=PUBLIC,
DSCNAME=DSQDBUG
DFHDCT TYPE=SDSCI, DCT ENTRY FOR DEBUG OF QMF
DSCNAME=DSQDBUG,
RECFORM=VARUNB,
BLKSIZE=136,
TYPEFLE=OUTPUT,
CTLCHR=ASA,
DEVADDR=SYSLST,
DEVICE=1403
Use DSQSDBQT parameter if you want to use a temporary storage queue for the trace data when you start QMF. If you want to name the queue something other than DSQD, use the DSQSDBQN parameter.
The trace data queue can be shared by all users in the same CICS partition, because QMF issues CICS ENQ and DEQ commands around single trace entries. Because tracing is an aspect of a user's profile, you can also set the level of trace detail individually for each user with the SET PROFILE command using the TRACE keyword. Records in the trace data identify individual terminal IDs for different QMF sessions on the header line.
To start the trace facility, do one of the following tasks:
SET PROFILE (T=value
where value is ALL or a string that indicates QMF functions and their levels of detail in the trace output.
CONNECT JONES (PA=MYPW
Users who do not have DB2 CONNECT authority can end the current QMF session and begin another to initialize the values.
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 262 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 262 appears in QMF Messages and Codesas:
Column &01 is not in table &02.
The bottom half of Figure 262shows 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
Depending on the number of users and the levels of detail at which their sessions are traced, the data might be very long. Browse the data before you decide to print it.
Use the CICS transaction CEBR to browse a temporary storage queue. For example, to browse a queue named MYTRACE, enter the following command from a cleared CICS screen:
CEBR MYTRACE
If the trace output is less than 32,767 rows, use temporary storage queues to hold the trace data. If the output is more than 32,767 rows, you must use a transient data queue for the trace data.
The default queue for trace data is a transient data queue named DSQD. Trace output routed to this queue goes to the SYSLST, and can be found in the list output of your CICS job. To transfer the data from the CICS LST queue to the SYSLT so you can view it, you must stop CICS. This will allow you to browse or print the SYSLST using VSE POWER, ICCF, or another facility available to you.
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.
[ Previous Page | Next Page | Contents | Index ]