RUN QUERY represents the beginning of the process. This could mean the user issued a RUN QUERY or RQA QUERY command from QMF. It could also mean that Query Analyzer was invoked from the online ISPF facility or from the edit macro. In the latter two cases, the query is never executed.
This step represents the isolation of the query prior to execution of the analysis phase. If the query is coming from QMF, then all substitution variables will have been replaced. If the query is coming from the online ISPF facility or the edit macro, host variables and substitution variables will be replaced internally by parameter markers (question marks) in this step.
During this step, the query is processed using the EXPLAIN command. The result of this command is that access path information is inserted into a PLAN_TABLE. These PLAN_TABLE entries are read and stored internally in the program, then these entries are deleted from the PLAN_TABLE.
The owner of the PLAN_TABLE into which these entries are inserted is determined by the user's CURRENT SQLID. You can override the CURRENT SQLID. That is, Query Analyzer can SET CURRENT SQLID before running the EXPLAIN to control which PLAN_TABLE will be used. Once CURRENT SQLID is set, all unqualified tables within the query will be qualified by CURRENT SQLID.
From QMF, CURRENT SQLID is obtained from the user's resource group. Use the Governor online facilities to set this field. From the online ISPF facility or from the edit macro, CURRENT SQLID is obtained from the Set Default Parameters panel.
If a PLAN_TABLE does not exist for the user (the CURRENT SQLID), then Query Analyzer will attempt to create one. The database and table space in which the PLAN_TABLE will be created is supplied to Query Analyzer via the resource group definitions if the user is running under QMF, or via the value set on the Set Default Parameters if the user is running from the online ISPF facility. If these variables are left blank, no analysis can be performed.
During this step, access path information is gathered and summarized. In addition, historical query statistics (CPU time and rows fetched) are summarized and made available to the exit routine. All table names found in the plan table output (a maximum of 10) are passed to the exit routine.
Once the access path information is gathered and summarized, the exit routine is called. The exit routine is responsible for setting three variables:
The PANELID variable notifies Query Analyzer which panel, if any, should be displayed to the user after the query is analyzed. Any non-blank value is used as the name of the output panel.
The CANFLG variable notifies Query Analyzer if it should cancel the QMF query. To cancel the query, set CANFLG to CANCEL. Any other value allows the query to continue.
If the exit routine specifies a panel name and has canceled the query, a message will be displayed on the output panel notifying the user that the query has been canceled. If the query was not canceled by the exit routine, then the panel contains a cancellation prompt. If the user responds with a Y, then the CANFLG variable will be set to CANCEL by the output panel in its processing section.
If the query will be canceled (if CANFLG is set to CANCEL after all exit processing finishes), then Query Analyzer cancels the QMF query and notifies the user with a message on the QMF message line.
The AAQARM variable is more of a resource controller than an analysis tool, but it provides more user control over query execution. This field lets the user tell QMF how many rows to fetch before canceling the query. The default value is zero, which means no row limit is set here. If any other value is specified, that value will cause QMF to halt execution after reaching this row limit.
Query Analyzer can display a panel to the user. The exit routine is responsible for notifying Query Analyzer which panel it should display by setting the ISPF variable named PANELID. To hide the analysis from the user, set PANELID to spaces. The sample exit sets PANELID to RAAQMFQA, the sample output panel.
If the PANELID variable is set, then Query Analyzer displays the appropriate panel.
Query Analyzer can cancel a QMF query. This exit routine is responsible for notifying Query Analyzer if the query should be canceled by setting the ISPF named CANFLG to CANCEL. (The sample output panel can also set CANFLG.)