OS/390

Follow these instructions for OS/390.

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
- Running the EDIT PROC and EDIT QUERY functions
At initiation of an abnormal ending
QMF calls the governor just before it initiates an abnormal ending. The governor can perform the cleanup necessary before the abend processing begins. The actions might be similar to those during the session end.

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. These values are shown in Figure 228.

What happens upon entry to the governor exit routine

QMF calls the governor exit routine by branching to the address of the entry point DSQUnGV1 (TSO), or DSQUnGV3 (CICS).

Branching to the CICS entry point DSQUnGV3

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

Register 1 contains a CICS parameter list suitable for processing by CICS-supplied macros DFHEIENT and DFHEIRET Figure 228shows 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 228. Contents of Register 1 on a call to the governor exit routine
Register 13 contains the address of a standard CICS working storage area as described by CICS DSECT (DFHEISTG).
Register 14 contains the return address.

Because the governor program runs on the same program level as QMF, use caution when using any EXEC CICS commands that change the environment (for example, CICS HANDLE CONDITION). If you need to use the CICS HANDLE CONDITION, use EXEC CICS PUSH and EXEC CICS POP to save and restore them.

Begin the governor program with code similar to that shown below.

Figure 229. Sample code at the start of a governor (for CICS)

DSQUEGV3 TITLE 'QMF GOVERNOR EXIT ROUTINE'
DFHEISTG DSECT
DSQUEGV3 DFHEIENT CODEREG=(12),DATAREG=(13),EIBREG=(10)
         B     FDENTRY              BRANCH AROUND CONSTANTS
*
MODNAME  DC    C'DSQUEGV3'          MODULE NAME
         DC    C' '
         DC    C'&SYSDATE '         DATE OF ASSEMBLY
         DC    C'&SYSTIME '         TIME OF ASSEMBLY
         DS    0H
*
FDENTRY  DS    0H
         L      R01,4(R01)          GET ADDRESS OF DFHCOMMA
         L     XCBPTR,8(R01)        GET ADDRESS OF QMF EXIT CTL BLK
         L     GOVPTR,12(R01)       GET ADDRESS OF QMF GOV  CTL BLK
         USING DXEXCBA,XCBPTR
         USING DXEGOVA,GOVPTR
         LA    WORKPTR,GOVUSERS     GET ADDRESS OF GOVERNOR WORK AREA
         USING WORK,WORKPTR
*

·
·
·

    GOVPTR   EQU   R03              PTR TO DXEGOV CONTROL BLOCK
    XCBPTR   EQU   R02              PTR TO DXEXCB CONTROL BLOCK
    WORKPTR  EQU   R04              PTR TO GOVERNOR SCRATCH PAD AREA

The code in Figure 229 first branches around a block of constants that can serve as eye catchers in a dump of virtual storage. The constants name the entry point and the applicable version of QMF. They also show the date and time that the code was assembled.

The code establishes base registers for the program, DXEXCB, DXEGOV, and a scratchpad area named GOVUSERS. The scratchpad area is preserved by QMF between calls to the governor. A DSECT named WORK describes this scratchpad area in the code for the IBM-supplied governor.

When processing is complete, the governor returns control to QMF using the standard CICS return as specified by the CICS macro DFHEIRET.

Attention: Do not use the command EXEC CICS RETURN. This ends the QMF session without releasing QMF resources.

The governor program ends with code similar to Figure 230.

Figure 230. Endcode for the governor program


·
·
·

*
         XR    R15,R15           ZERO RETURN CODE
         DFHEIRET RCREG=15
*

Branching to the entry point

QMF calls the governor exit routine by branching to the address of the entry point DSQUEGV1 (TSO). Upon entry to the governor exit routine:

Register 1 contains the address of the parameter list.
The parameter list contains two full-word addresses; one for the control block DXEXCBA; the other for the control block DXEGOVA.

Figure 231. Contents of Register 1 on a call to the governor exit routine
Register 13 contains the address of the QMF SAVE area.
Register 14 contains the return address from the call.
Register 15 contains the address of the entry point, which is DSQUEGV1.

After the governor is called, it might begin with code like that shown in Figure 232. The code sample is from the IBM-supplied governor for TSO or native OS/390.

Figure 232. Sample code at the start of a governor (for TSO, ISPF, or native OS/390)

DSQUEGV1 CSECT
         USING *,R15
         B     FDENTRY              BRANCH AROUND CONSTANTS
         DC    C'DSQUEGV1'          MODULE NAME
         DC    C' '
         DC    C'&SYSDATE '         DATE OF ASSEMBLY
         DC    C'&SYSTIME '         TIME OF ASSEMBLY
         DS    0H
*
FDENTRY  STM   R14,R12,12(R13)      SAVE THE REGISTERS
         BALR  R12,0                INITIALIZE BASE REGISTER
         DROP  R15
         LA    R02,MAINSV           CHAIN THE SAVE AREAS
         ST    R02,8(R13)
         ST    R13,MAINSV+4
         LR    R13,R02
*
         L     R01,4(R01)           GET ADDRESS OF DFHCOMMA
         L     XCBPTR,0(R01)        GET ADDRESS OF QMF EXIT CTL BLK
         L     GOVPTR,4(R01)        GET ADDRESS OF QMF GOV CTL BLK
         USING DXEXCBA,XCBPTR
         USING DXEGOVA,GOVPTR
         LA    WORKPTR,GOVUSERS     SCRATCH PAD ADDRESS
         USING WORK,WORKPTR

·
·
·

MAINSV   DS    18F                  SAVE AREA
XCBPTR   EQU   R02                  PTR TO DXEXCBA CONTROL BLOCK
GOVPTR   EQU   R03                  PTR TO DXEGOVA CONTROL BLOCK
WORKPTR  EQU   R04                  PTR TO SCRATCH__PAD AREA

The code in Figure 232 first branches around a block of constants that can serve as eye catchers in a dump of virtual storage. The constants name the entry point and the applicable version of QMF. They also show the date and time that the code was assembled.

After processing a call, the governor returns control to QMF in the standard way; that is, you must use the standard epilog and prolog. In the IBM-supplied governor, the following code does this:

L     R13,4(R13)        RESTORE CALLER'S SAVE AREA ADDRESS
         LM    R14,R12,12(R13)   RESTORE CALLER'S REGISTERS
         XR    R15,R15           ZERO RETURN CODE
         BR    R14               RETURN TO CALLER

Establishing addressability for function calls

Because QMF always branches to an entry point named DSQUnGV1 (TSO), or DSQUnGV3 (CICS) 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 in Figure 233. (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.

Figure 233. Character and numeric values for the GOVFUNCT field of DXEGOVA

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 234 shows an example of some code that identifies branch addresses for the IBM-supplied governor.

Figure 234. Identifying the type of function call and branching to the appropriate address

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

[ Previous Page | Next Page | Contents | Index ]