VSE

Follow these instructions for VSE

Points at which QMF calls the governor

Function calls to the governor exit routine either precede or follow a specific type of QMF activity. For example, QMF passes control to the governor exit before and after running a command.

When it calls the governor, QMF always branches to an entry point named DSQUnGVx. Therefore, you cannot use the entry point to determine the type of exit. Use instead the control-block field GOVFUNCT. Its value is a positive integer that identifies the type of exit.

• At the beginning and end of a QMF session

  QMF calls the governor exit routine during initialization for a QMF session, after the governor exit routine is loaded into the user's virtual storage. The governor initializes itself for the session using the resource control information contained in rows passed from QMF's query of Q.RESOURCE_VIEW.

• After a new connection is made to the database

  When a user issues the CONNECT command, the Q.PROFILES table and the resource control table are re-initialized. The governor is called because the resource control values might have changed if a different CONNECT ID was used. All unfinished database operations are completed before the connection is made.

  Although the governor exit routine cannot cancel a connection to the database, you can write statements in your own routine that cancel the user's session on the next activity, if the resource information passed to the governor indicates that the user is not allowed to use QMF.

• Before and after running a command

  QMF calls the governor before and after running all commands. There can be several calls for the start of commands before a call for the completion of a command. For example, a RUN PROC command results in two "start command" calls and two "end command" calls when there is a RUN QUERY command embedded in the procedure.

• Before database activity starts and when it ends

  QMF calls the governor just before it begins a variety of database operations, such as PREPARE, OPEN, and FETCH; QMF also calls the governor upon completing any database activity.

  When QMF retrieves data, it fits the maximum number of rows possible into a buffer that has a minimum size of 4K. QMF calls the governor once upon retrieving the first row into the buffer and once upon either filling the buffer or reaching the end of the table, whichever comes first.

  QMF also calls the governor when SQL, QBE, or prompted queries are submitted using RUN QUERY, or when QMF is running queries started by a command. For example, a SAVE DATA command might result in DELETE, CREATE, and INSERT queries. The governor is called before and after each of these operations. If there is an incomplete data object when a command is entered, there might be governor calls for database activity while the data object is being completed. See Solving performance problems for more information on handling problems associated with completing the data object.

  The following QMF commands always force database activity:

  • DISPLAY table commands
  • The EDIT TABLE command for the Table Editor
  • The ERASE command for a table
  • The EXPORT TABLE command
  • The IMPORT command to a table
  • The PRINT command for a table or view
  • The RUN command for queries
  • The SAVE DATA command (which forces an implicit CREATE TABLE query)
  • Scrolling commands that result in fetching data when a report is being displayed
  • Data retrieval operations (fetch operations)
• Before and after the user makes a choice

  At various points in a session, QMF waits for users to make decisions. The time QMF spends waiting is known as think time.

  QMF calls the governor before performing an operation that leads to think time, such as displaying a panel for a user-entered selection. As soon as the user enters a response and ends the period of think time, QMF calls the governor.

  Any of the following activities lead to think time:

  • Displaying a QMF panel between running commands
  • Displaying help panels
  • Displaying confirmation prompt panels; for example, when the user is about to erase something by issuing the SAVE command that replaces the object
  • Displaying command prompt panels; for example, when the user enters DISPLAY ?
  • Displaying the LIST prompt panel
  • Displaying ICU and EXTRACT panels
  • Displaying the GDDM interactive chart utility panels for QMF charting functions

For the IBM-supplied governor exit routine, QMF uses the GOVFUNCT field of the DXEGOVA control block to pass information about the type of function call. Each type of function call has a specific value for the GOVFUNCT field.

What happens upon entry to the governor exit routine

QMF calls the governor exit routine by branching to the address of the entry point DSQUnGV3.

Entry to the governor exit routine follows the standard CICS linkage conventions:

• Register 1 contains a CICS parameter list suitable for processing by CICS-supplied macros DFHEIENT and DFHEIRET. Figure 238 shows the contents of Register 1 on a call to the governor.

  DFHEIBLK is the address of the CICS communications area. DFHCOMMA contains two pointers, one to the DXEXCBA control block and the other to the DXEGOVA control block.

  Figure 238. Contents of Register 1 on a call to the governor exit routine on VSE

  
• Register 13 contains the address of a standard CICS working storage area as described by CICS DSECT (DFHEISTG).
• Register 14 contains the return address.

Establishing addressability for function calls

Because QMF always branches to an entry point named DSQUnGV3 when it calls the governor, you cannot use these entry points to determine the type of function call; instead, use the GOVFUNCT field of the DXEGOVA control block.

In the IBM-supplied governor exit routine, GOVFUNCT contains a character value that identifies the type of function call. This character value, in turn, equates to a 1-byte binary integer from 1 to 10. For example, on a function call for the start of a QMF session, the value of GOVFUNCT is GOVINIT, which equates to a numeric value of X'1'.

Both character and numeric values for each type of function call are shown below. (If you need more information about the activity that occurs at each function call, see Points at which QMF calls the governor.) GOVABEND is not called when running in CICS.

GOVINIT  EQU   1             -------- INITIALIZATION OF SESSION
GOVTERM  EQU   2             -------- TERMINATION OF SESSION
GOVSCMD  EQU   3             -------- START COMMAND
GOVECMD  EQU   4             -------- END COMMAND
GOVCONN  EQU   5             -------- CONNECT COMMAND
GOVSDBAS EQU   6             -------- START DATA BASE
GOVEDBAS EQU   7             -------- END DATA BASE
GOVSACTV EQU   8             -------- SUSPEND QMF ACTIVITY
GOVRACTV EQU   9             -------- RESUME QMF ACTIVITY
GOVABEND EQU   10            -------- QMF ABEND OPERATION

To improve performance in your own exit routine, you can follow the convention the IBM-supplied governor uses, and equate the values of GOVFUNCT with binary numbers by using a branch table. QMF uses the branch table to find the addresses to branch to for each type of function call.

Figure 240 shows an example of some code that identifies branch addresses for the IBM-supplied governor.

XR    R07,R07               ZERO REGISTER 7
         IC    R07,GOVFUNCT          IDENTIFY EXIT TYPE
         SLL   R07,2                 DETERMINE BRANCH TABLE OFFSET
         LA    R15,FUNBTAB(R07)      GET BRANCH TABLE ADDRESS
         L     R15,0(R15)            GET BRANCHING ADDRESS
         BALR  R14,R15               BRANCH TO THE APPROPRIATE CODE
            . . .
            . . .
            . . .
            . . .
FUNBTAB  DS    0F
         DC    A(BYPASS)          VALUE "0"  - UNUSED
         DC    A(INIT)            VALUE "1"  - QMF INITIALIZATION
            . . .
            . . .
            . . .
         DC    A(SUSPEND)         VALUE "10" - QMF ABEND IN PROCESS