The DXEXCBA control block passes to the governor exit routine information about the state of the QMF session upon entry to the governor. The governor combines this information with information on resource limits (contained in DXEGOVA) to determine when the resource limits are exceeded and when to cancel the user's activity.
For example, you can define a resource option that does not allow user JONES to use the EDIT TABLE command. You can then write your governor exit routine so that, if the XCBQRYP field of the DXEXCBA control block indicates an EDIT TABLE command, the governor exit calls the QMF cancellation service to cancel the command.
Table 84 provides the name of each field in the control block, with its data type and purpose. Each data type is listed as it appears in the DS statement that defines the field in the DSECT.
The layout of the control blocks and the information they contain is the same for QMF support in all operating environments. Therefore, some of the information shown in the control blocks might not apply to QMF operating system you are running in.
| Field | Data Type | Purpose |
|---|---|---|
| XCBACTIV | CL1 | Indicates the current type of database activity. Applies
only when rows are being retrieved for the current data object. Does not apply
when rows are retrieved for an IMPORT command. Possible values are:
This field changes whenever the type of database activity changes. You can use the value when the governor receives control asynchronously as the result of a timer. |
| XCBAIACT | CL1 | Tells whether the current command is running interactively:
|
| XCBAUTH | CL8 | Contains the user's SQL authorization ID. |
| XCBCAN | CL1 | Indicates whether the user or the governor requested cancelation of the current command. The field is set to 1 if cancelation is requested. Zero indicates that no cancelation was requested. The value changes at the point at which the cancelation is requested. This field is reset to zero before the function call for the command's termination. |
| XCBCLOC | CL18 | Contains the current location name. |
| XCBCMDL | F | Contains the length of the string containing the command to be run. This is the string addressed by XCBCMDP field. This field changes values when XCBCMDL changes values. |
| XCBCMDP | A | Points to the string containing the command to be run.
This field is reset when QMF validates a command at some point before the
function call for the start of the command.
The field is reset to zeros before the function call when the command completes. If a command synonym is being run, it appears here. |
| XCBCVERB | CL18 | Holds the verb of the current command. This field changes value on the function call for the start of a command. The value does not change between calls. |
| XCBDBMG | CL1 | Identifies the database manager. This value is set to 1 for DB2 for VM or VSE and to 2 for DB2 for OS/390. |
| XCBEMODE | CL1 | Indicates the current mode of the QMF session:
|
| XCBERRET | F | Contains the return code to be used in the default cancelation message. |
| XCBINCI (ISPF only) | CL1 | Tells whether the current command is being run through the command interface. The field is set to 1 if it is, and 2 if it isn't. For more information about the command interface, see the Developing QMF Applications manual. |
| XCBINPRC | CL1 | Tells the governor where a command is being run: 1 indicates it is running in a procedure or LIST command; 0 indicates it is being run another way. |
| XCBKPARM | CL1 | Tells the governor how the DSQSDBCS program parameter is set. The value does not change during a session. Possible values are: 0 for Latin letters; 1 for double-byte character set (DBCS) data. |
| XCBLOGM | CL1 | Indicates if QMF should log a message in the QMF trace data set. Use a value of 1 to log the message, and 0 to not log the message. |
| XCBMGTXT | CL78 | Contains the text for a message. The message can be logged in the QMF trace data, displayed on the screen, or both. |
| XCBMSGNO (ISPF only) | CL8 | Contains the message ID for an ISPF message definition that can be used to log a message in the DSQDEBUG data set, viewed on your screen, or both. |
| XCBNAME | CL8 | Contains the control block name (DXEXCBA). Can serve as an eye catcher in a dump of virtual storage. This value does not change during a session. |
| XCBNLANG | CL1 | Identifies NLFs being used. (For a list of NLIDs used, see Table 1.) Value does not change during a session. |
| XCBPANEL (ISPF only) | CL8 | Contains the panel ID for the message Help panel for a cancelation message. |
| XCBPLAN | CL8 | Contains the application plan ID for QMF. The value does not change during a session. This field does not apply in CICS. |
| XCBQCE | F | Contains the decimal equivalent of the value of the SQLDERRD(4) field in the SQLCA returned from DBMS. The integer part of this decimal appears in the database status ("relative cost estimate") panel. The value is set to zero on the function call when the command finishes running. The field contains zeros if the operation is not a data retrieval query. The query cost estimate is not available from DB2 Parallel Edition V1.2 or DataJoiner v1.2.1. In these environments the value is set to 1. |
| XCBQERR | CL1 | Tells whether a QMF error occurred since the previous function call: 0 indicates no error occurred; 1 indicates an error occurred. |
| XCBQMF | CL10 | Identifies the current release of QMF. This value is QMF V7R2.0, and does not change during a session. |
| XCBQRYP | A | Contains the address of a copy of the query that QMF passes
to the database for execution. The governor inspects the query upon a call
to start database activity (before any data retrieval) and determines whether
to cancel the activity. The address is set to zero either at the beginning
of the session or when the data object is reset or imported to temporary storage.
This field contains information only when data retrieval is requested through one of the following commands; no information is provided for queries on OS/390 DB2 system tables or QMF control tables.
|
| XCBREFR | CL1 | Indicates whether QMF refreshes the screen after returning
from the governor; 1 indicates a refresh; 0 indicates no refresh.
If your governor displays any screen information, set this field to 1. |
| XCBRELN | CL2 | Identifies the QMF release level. For QMF Version 7.2, this is 13. The value does not change during a session. |
| XCBRGRP | CL16 | Contains the name of the user's resource group. This value does not change during a session. |
| XCBROWSF | F | Reflects the number of rows retrieved into the data object.
Initially zero, this field changes value whenever more rows are retrieved.
All data retrieval is counted whether data is retrieved from the database,
sequential files, CICS temporary storage, or CICS transient data queues.
QMF does not reset this field, but the governor can. For example, if your governor exit routine monitors the number of database rows retrieved, you can set this field to zero on the function call for the end of the command that began the data retrieval. |
| XCBSYST | CL1 | Identifies the current operating system. The value does
not change during a session, and is usually set to 3, indicating TSO, or native OS/390 batch.
Possible values are:
|
| XCBTRACE | CL1 | Contains a value for the level of detail at which user
exit activity is traced. Possible values are 0 (least detail), 1, or 2 (most
detail).
At the start of a session, the value of the TRACE field from the user's QMF profile is used here. After that, the value changes only when the user changes the value of the TRACE option. For more information on tracing, see Using the QMF trace facility. |
| XCBUSER | CL8 | Contains the user's TSO logon ID (for TSO), the user parameter on the job statement (for native OS/390 batch). This field is not used in CICS; it contains blanks. |
| XCBUSERS | CL2048 | Scratchpad area in which you can store results you want the governor to save from one call to the next. It is initially set to blanks. QMF does not change this value. |
The structure of the DXEXCBA control block is illustrated below:
********************************************************************** 00001000
* * 00002000
* CONTROL BLOCK NAME: DXEXCBA * 00003000
* * 00004000
* FUNCTION: * 00005000
* * 00006000
* THIS IS THE INTERFACE CONTROL BLOCK BETWEEN QMF AND * 00007000
* EXIT ROUTINES. * 00008000
* * 00009000
* STATUS: VERSION 7 RELEASE 2 LEVEL 0 * 00010000
* * 00011000
* INNER CONTROL BLOCKS: NONE * 00012000
* * 00013000
* CHANGE ACTIVITY: * 00014000
* * 00015000
* * 00016000
********************************************************************** 00017000
* 00018000
DXEXCBA DSECT 00019000
DS 0D 00020000
XCBNAME DS CL8 -- CONTROL BLOCK IDENTIFICATION 00021000
SPACE 00022000
XCBEXCTL DS XL190 -- EXIT CONTROL 00023000
ORG XCBEXCTL 00024000
XCBAUTH DS CL8 ----- AUTHORIZATION ID 00025000
XCBUSER DS CL8 ----- USER ID 00026000
XCBPLAN DS CL8 ----- PLAN ID 00027000
SPACE 00028000
XCBQMF DS CL10 ----- CURRENT VERSION/RELEASE 00029000
SPACE 00030000
XCBRELN DS CL2 ----- QMF RELEASE LEVEL 00031000
SPACE 00032000
XCBTRACE DS CL1 ----- QMF EXIT TRACE LEVEL 00033000
XCBTOFF EQU C'0' -------- NO TRACING 00034000
XCBTPART EQU C'1' -------- PARTIAL TRACING 00035000
XCBTFULL EQU C'2' -------- FULL TRACING 00036000
SPACE 00037000
XCBSYST DS CL1 ----- OPERATING SYSTEM 00038000
XCBSYSTX EQU C'3' -------- MVS/ESA or XA (TSO,APPC, native) 00039000
XCBSYSTV EQU C'4' -------- CMS/VM/ESA 00040000
XCBSYSTY EQU C'5' -------- CICS (OS/390 or VSE) 00041000
SPACE 00042000
XCBPAD10 DS CL4 ----- RESERVED FIELD 00043000
SPACE 00044000
XCBNLANG DS CL1 ----- CURRENT NATIONAL LANGUAGE 00045000
SPACE 00046000
XCBKPARM DS CL1 ----- SETTING OF K PARAMETER 00047000
XCBKPARN EQU C'0' -------- LATIN 00048000
XCBKPARY EQU C'1' -------- DBCS 00049000
SPACE 00050000
XCBDBMG DS CL1 ----- DATA BASE MANAGER 00051000
XCBDBMGS EQU C'1' -------- DB2 FOR VM/VSE 00052000
XCBDBMGD EQU C'2' -------- DB2 FOR OS/390 00053000
XCBDBMGW EQU C'3' -------- WORKSTATION DB2 00054000
SPACE 00055000
XCBEMODE DS CL1 ----- CURRENT EXECUTION MODE 00056000
XCBIACTV EQU C'1' -------- INTERACTIVE MODE 00057000
XCBBATCH EQU C'2' -------- BATCH MODE 00058000
SPACE 00059000
XCBAIACT DS CL1 ----- CURRENT INTERACT MODE 00060000
XCBAIACY EQU C'1' -------- INTERACTIVE EXECUTION 00061000
XCBAIACN EQU C'0' -------- NOT INTERACTIVE EXECUTION 00062000
SPACE 00063000
XCBINCI DS CL1 ----- CURRENT COMMAND INTERFACE STATE 00064000
XCBINCIY EQU C'1' -------- COMMAND INTERFACE ACTIVE 00065000
XCBINCIN EQU C'0' -------- COMMAND INTERFACE NOT ACTIVE 00066000
SPACE 00067000
XCBINPRC DS CL1 ----- PROCEDURE OR LIST CMD EXEC STATE 00068000
XCBPRCY EQU C'1' ------- RUNNING A PROCEDURE OR LIST CMD 00069000
XCBPRCN EQU C'0' ------- NOT RUNNING PROCEDURE OR LIST CMD 00070000
SPACE 00071000
XCBCVERB DS CL18 ----- CURRENT COMMAND VERB 00072000
SPACE 00073000
XCBCAN DS CL1 ----- CANCEL CURRENT COMMAND INDICATOR 00074000
XCBCANN EQU C'0' -------- NO CANCELLATION 00075000
XCBCANY EQU C'1' -------- CANCELLATION IN PROGRESS 00076000
SPACE 00077000
XCBACTIV DS CL1 ----- TYPE OF DATA BASE ACTIVITY 00078000
XCBOPEN EQU C'1' -------- OPEN 00079000
XCBFETCH EQU C'2' -------- FETCH 00080000
XCBPREP EQU C'3' -------- PREPARE 00081000
XCBDESCR EQU C'4' -------- DESCRIBE 00082000
XCBCLOSE EQU C'5' -------- CLOSE 00083000
XCBEXEC EQU C'6' -------- EXECUTE 00084000
XCBEXECI EQU C'7' -------- EXECUTE IMMEDIATE 00085000
XCBPAD20 DS CL9 ----- RESERVED FIELD 00086000
SPACE 00087000
XCBRGRP DS CL16 ----- RESOURCE GROUP NAME 00088000
XCBPAD30 DS CL22 ----- RESERVED FIELD 00089000
SPACE 00900000
XCBCMDP DS A ----- POINTER TO ORIGINAL COMMAND STRING 00091000
* -------- WILL NOT CONTAIN PROMPT VALUES 00092000
SPACE 00093000
XCBCMDL DS F ----- ORIGINAL COMMAND STRING LENGTH 00094000
SPACE 00095000
XCBQCE DS F ----- QUERY COST ESTIMATE VALUE 00096000
SPACE 00097000
XCBROWSF DS F ----- DATA BASE ROWS FETCHED FROM SOURCE 00098000
* -------- SET BY QMF; EXIT MAY RESET 00099000
SPACE 00100000
XCBQERR DS CL1 ----- QMF ERROR INDICATOR 00101000
XCBQERRN EQU C'0' -------- NO QMF ERROR DETECTED 00102000
XCBQERRY EQU C'1' -------- QMF ERROR DETECTED 00103000
XCBCLOC DS CL18 ----- CURRENT LOCATION NAME 00104000
XCBPAD40 DS CL41 ----- RESERVED FIELD 00105000
SPACE 00106000
XCBQRYP DS A ----- POINTER TO SQL QUERY 00107000
* -------- QUERY LENGTH IS FIRST HALFWORD 00108000
SPACE 00109000
XCBUCTL DS XL432 -- USER CONTROL AREA 00110000
ORG XCBUCTL 00111000
XCBERRET DS F ----- EXIT ERROR RETURN CODE 00112000
XCBMGTXT DS CL78 ----- EXIT ERROR MESSAGE TEXT 00113000
XCBMSGNO DS CL8 ----- ISPF MESSAGE NUMBER 00114000
XCBPANEL DS CL8 ----- ISPF MESSAGE HELP PANEL 00115000
XCBLOGM DS CL1 ----- LOG MESSAGE INDICATOR 00116000
XCBLOGMN EQU C'0' -------- QMF SHOULD NOT LOG MESSAGE 00117000
XCBLOGMY EQU C'1' -------- QMF SHOULD LOG MESSAGE 00118000
XCBREFR DS CL1 ----- REFRESH SCREEN INDICATOR 00119000
XCBREFRN EQU C'0' -------- QMF DOES NOT HAVE TO REFRESH SCR 00120000
XCBREFRY EQU C'1' -------- QMF SHOULD REFRESH SCREEN 00121000
XCBPAD50 DS CL28 ----- RESERVED FIELD 00122000
SPACE 00123000
XCBUSERS DS CL2048 -- USER SCRATCH PAD AREA 00124000
XCBPAD60 DS CL48 ----- RESERVED FIELD 00125000