Visual Explain (QQQVEXPL) API


  Required Parameter Group:


  Threadsafe: Conditional; see Usage Notes.

The Visual Explain (QQQVEXPL) API is used to create a query graph that graphically displays the execution of an SQL statement. You can use this tool to see information about both static and dynamic SQL statements. QQQVEXPL supports the following types of SQL statements:

You can use this tool to better understand where the highest costs of your queries are taking place. You can improve query performance by:

You also can use the QQQVEXPL API to:

Input to the Visual Explain (QQQVEXPL) API is two structures. One contains the information the Visual Explain consolidator needs to uniquely identify which query within the database monitor table is to be explained. The other contains the name of the database monitor table. The database monitor table is a table that contains the records resulting from an execution of the STRDBMON command. Output from the Visual Explain (QQQVEXPL) API is a pointer to a stream of data located in user domain storage. This data contains the information necessary to create a pictorial view of how the specified query was implemented. It is up to the user to clean up the user domain storage. Also, output is a structure that contains an error return code, the number of entries in the output data, and the entry number of the Final Select ICON. To create the picture, the user starts with the entry of the Final Select ICON and works back to the beginning ICONs.

The format for the output records (or array entries) can be found in Output Format. Each record has a unique I CON number associated with it. The unique ICON number associates the records to a particular ICON. That is, all records with the same unique ICON number are associated with one specific ICON. For example, if the Final Select ICON has a unique ICON number of 12, then all records with a unique ICON number of 12 contain information about the Final Select ICON. The record immediately following the Final Select record is the record that tells the user how many ICONs (called child ICONs) are branched off the Final Select ICON. This record will have a record type of 11, which means it contains the number of child ICONs. The unique ICON number will match the unique ICON number of the Final Select ICON. Therefore, we know this record is telling us how many child ICONs there are for the Final Select ICON. The next records will contain the ICON number of the child ICONs. There will be one record for each child ICON and they will have a record type of 12 (unique ICON number of the child ICON). The user can find the record that corresponds to the child ICON by searching for the record that has a record type of 10 (new ICON) and a unique ICON number that matches the ICON number of the child ICON. Once the record of the child ICON is found, the process starts over again. All the records associated with that ICON (that is, that have the same unique ICON number) are read and processed. Any child ICONs are put on a stack or queue to be processed next. To see the list of possible record types, see Record Types.

The heart of the picture that is generated is the ICONs. In general, each ICON represents an operation performed during the execution of the query. It is up to the user to create and design the ICONs to be used. The connection between the output data and the user's ICONs is the label of the ICON that is returned within the new ICON record (record type of 10). The user is expected to match the non-translated label that is returned to the label that corresponds to the specific ICON. The non-translated ICON label is returned in the character output field. The translated ICON label is returned in the column heading field. For a list of ICON labels, see ICON Labels. For a detailed description of the operation represented by each ICON, see the Database performance and query optimization topic collection.


Authorities and Locks

Library Authority
*EXECUTE
Table Authority
*OBJOPR, *READ

Required Parameter Group

Pointer to the qualified query
INPUT; CHAR(*)

A pointer to a variable length structure that is used to determine the query to be explained. The structure contains two variables:


Pointer to qualified monitor table
INPUT; CHAR(*)

A pointer to a CHAR(72) structure containing the name of the database monitor table and other optional variables. The structure contains nine variables:


Pointer to output data
I/O; PTR(SPP)

A pointer to data that can be viewed as a set of records or multiple entries within an array. This data is used to determine the pictorial representation of the query. The user can retrieve the data in any manner. One suggested method is to view the returned data as a set of records and use the SET RESULTS SETS command within an SQL procedure to retrieve the output data. To see the format of the output data, see Output Format. Once finished, it is up to the user to deallocate or destroy the space containing the output data.

Pointer to output return code
I/O; CHAR(*)

Pointer to a CHAR(32) structure that contains the following output information:


Usage Notes

This function is threadsafe, but not thread-enabled. Database monitor data is collected in the threaded process.


Output Format

The format for each record (or each array entry) in the output data is as follows:


ICON Labels

To determine which ICON should be shown, look at the non-translated ICON label that is returned in the character output field. Compare this text string to the text string associated with the user-generated ICONs. The ICON labels that may be returned are shown below. For a detailed description of the operation represented by the ICON, see Database performance and query optimization.


Context Types

BINARY(4) A context is a group of values used for a special purpose.


Format Types

BINARY(4) The formatting value is used to format or highlight similar output data. For example, all header lines within the data attribute output will have a format value associated with them. This allows the user the option to identify and format all these particular header lines in the same manner.


Record Types

Generally, record types with a value less than 100 are used to construct the picture. For example, they determine which ICONs are connected together. Record types with a value greater than 1000 are data attributes (information associated with a particular ICON). For a detailed description of the data attributes, see Database Performance and Query Optimization.


Error Codes

Possible error codes returned from the Visual Explain consolidator are:



API introduced: V5R1

[ Back to top | Database and File APIs | APIs by category ]