Naming the program segment

Use dsqsdcss or dcssname to name the program segment. The suggested program segment name and default value is:

QMF720E

dcssname

The syntax of dcssname is still supported in QMF:

1. This parameter is optional in the PGM form of the ISPSTART command ISPSTART PGM(DSQQMFE) provided that the default DCSS name is used.
2. In the DCSS form of the command ISPSTART DCSS(dcssname), a DCSS name must be specified.
3. If QMF is not running as an ISPF dialog, and DSQQMFE dcssname(B=n1,...) is used to start QMF, the parameter is optional.

DSQSDCSS

You can add DSQSDCSS to the list of parameters to be passed when starting QMF. For example:

DSQSDCSS=QMFNEW

DSQSDCSS supports the callable interface for QMF.

Setting default start values using the REXX program DSQSCMDn

Specify default values for the program parameters with an initialization program. IBM supplies the REXX program DSQSCMDn for this purpose. DSQSCMDn can change the default program parameter values and can execute across environments.

The parameter values you specify when you start QMF override the values set in the REXX program DSQSCMDn. The parameter values you specify when a workstation session is started override the values set in DSQSCMDn.

DSQSCMDn is valid as a start function keyword on the START command when QMF is started from an application program using the callable interface.

You must use the REXX program method if you want to run programs in SAA environments that use the callable interface without changing the programs.

For more information on the START command and the SAA callable interface, see the Using QMF and Developing QMF Applications manuals.

For CMS, QMF calls the REXX program DSQSCMDE to provide values for the program parameters. This IBM-supplied program supplies default values; by adjusting these values, you can tailor the QMF environment for your installation.

Use NULL if you do not want to provide a parameter value in DSQSCMDE.

Program parameters for VM

When a user performs a QMF task that retrieves data from the database, the data is returned in a default report that is stored in virtual storage. This section explains QMF program parameters that help you customize:

• The maximum amount of storage used for report data
• The amount of spill storage used when virtual storage for reports is full
• The number of rows of data retrieved before QMF displays the first screen of the report

DSQSBSTG (adjusting storage for report data)

Parameter name

DSQSBSTG

Short form

B

Valid values

From 0 to 99,999,999 bytes

Default

0 bytes

The value of DSQSBSTG provides QMF with an upper limit (in bytes) on the storage available for report generation. It is a positive whole number ranging in value from 0 through 99, 999, 999. If DSQSBSTG is specified with a nonzero value less than a QMF-determined minimum (15 to 32 KB, depending on the environment), it is increased to that minimum.

When DSQSBSTG has a value of 0, this parameter is not used; instead, DSQSRSTG is used to specify storage. However, if both DSQSBSTG and DSQSRSTG are specified, DSQSBSTG is used.

Choosing the right amount of virtual storage for each user

Each QMF CMS region requires at least 4.5 MB of virtual storage. Additional storage generally provides improved performance since QMF is able to keep more data records in virtual storage.

Performance tradeoffs

Use the DSQSPILL parameter to provide users with a spill file, which is disk storage. If the spill file is full, QMF continues to retrieve data into virtual storage in amounts specified by the DSQSBSTG or DSQSRSTG parameters. The user does not receive any notification if there is insufficient storage, and QMF can still complete report processing. Consider using a governor exit routine to limit rows retrieved from the database, so that less virtual storage is used for queries and reports.

DSQSRSTG (Adjusting reserved storage used for applications)

Parameter name

DSQSRSTG

Short form

R

Valid values

From 0 to 99,999,999 bytes

Default

0

You can use the DSQSBSTG parameter if you want a more explicit specification of your report storage. The value of this parameter is a positive whole number ranging in value from 0 through 99,999, 999, with a default of 0. The value can affect other programs and the generation of reports.

The first time a user generates a report during a session, QMF determines how much storage is available in the QMF address space. The method that is used to arrive at the total storage acquired for QMF reports depends on both DSQSBSTG and DSQSRSTG:

• If DSQSBSTG is not specified, or is specified as 0, QMF subtracts the amount of DSQSRSTG from the total available storage to determine the maximum amount to use for QMF reports. The remaining storage is available for other programs, including CMS commands, REXX, ISPF, and any other non-QMF user requirements.
• If DSQSBSTG is specified, then its value is used to determine how much storage is acquired for QMF reports, and DSQSRSTG is not used.

DSQSRSTG value of 0

You can specify 0 as the value for both DSQSBSTG and DSQSRSTG. In this case, the DSQSRSTG parameter is used and no storage is reserved for other system services. This value is probably adequate for users who never use VM system services, CMS commands, REXX, ISPF or other non-QMF services during QMF sessions. Those users who do use a VM system service or a CMS command and has DSQSTSTG=0 and DSQSBSTG=0, run the risk of failing and causing an abend, because QMF does not reserve any storage for those services. Even the most casual users might unknowingly use a non-QMF program when they issue installation-defined QMF commands. Such commands are performed by QMF applications, which generally make extensive use of such non-QMF programs. Take this into account when selecting values for DSQSRSTG and DSQSBSTG.

Small value for DSQSBSTG or large value for DSQSRSTG

Requesting minimal storage for report processing can adversely affect performance when a user is handling a report. If enough storage is not available for the corresponding DATA object, QMF must use a spill file for excess rows of DATA. The input/output operations required for the spill file usually degrade performance.

DSQSPILL (acquiring extra storage)

Parameter name

DSQSPILL

Short form

L

Valid values

YES or NO

Default

YES

Because large amounts of report data in storage might affect the operation of other CMS transactions, QMF lets you allocate a spill file, which is extra storage used when a user's storage is full.

You can reset the DSQSPILL parameter to NO to deactivate the spill file:

DSQQMFn L=NO

Data is written to the spill file until:

• You use the RESET DATA command to reset the data object
• You replace the data object by running another query
• Your query has finished and the data object is complete
• Storage you defined for the spill file is full.

Allocating a spill file for CMS users

You can allocate a spill file through a FILEDEF statement:

FILEDEF DSQSPILL DISK DSQSPILL DATA T (LRECL 4096 RECFM F PERM'

The statement:

• Allocates the spill file to the T disk. The T disk can be a temporary disk. The spill file cannot be allocated to a disk that is used in the CMS shared file system (SFS).
• Specifies the DSQSPILL file with fixed-length records, one record for each block. Records must always be unblocked (a block is the size of a VM page: 4,096 bytes).

Estimating the space required for a spill file

To accommodate QMF's storage requirements, ensure the CMS DASD storage is large enough to hold the individual spill files for all concurrent QMF users, in addition to any other transaction requirements for auxiliary temporary storage.

Use the following procedure to calculate the amount of space required for an individual spill file. Enlarge CMS virtual storage according to how many individual spill files you will need to accommodate all concurrent users of QMF.

1. Calculate the width (W) of one row of the largest table that can appear in the data object by adding field widths in bytes.
   • All rows of an individual table are the same width, regardless of the data each row contains. A row cannot be wider than 32,768 bytes.
   • Defined columns do not get written to the spill file.
2. If W is 4,096 or less, calculate the number of rows per page (R) using R = 4096/W, and round the result down to the next lowest integer.

   When W is 4,096 or less, QMF fits as many rows as it can into a page, without spanning pages.

3. If W is greater than 4,096, calculate the number of pages per row (P), using P = W/4096, and round up to the next highest integer.

   When W is greater than 4,096, QMF uses the minimum number of pages to hold a row, spanning pages regardless of column boundaries. Each row begins at the start of a page.

4. Calculate the number of pages required for the spill file, according to the value of W:
   • If W is 4,096 or less, calculate the number of pages required for the spill file by dividing the number of rows in the table by R.
   • If W is greater than 4,096, calculate the number of pages required for the spill file by multiplying the number of rows in the table by P.

Using a spill file in a noninteractive QMF session

A spill file is most useful for improving performance in an interactive QMF session, when the DSQSMODE parameter is set to I. If you are running QMF noninteractively (the DSQSMODE parameter is set to B), using a spill file can also improve performance when multiple passes of the data are required to produce the report. A spill file might also be necessary to complete the data object, as when a RUN QUERY command is followed by a SAVE DATA command.

Multiple passes of the data are required when:

• You need to print several reports with different formats for the same data.
• You use PCT, CPCT, TCPCT, or TPCT edit codes with the report.
• You print a report that requires QMF to split the pages, because the report is wider than the print width.

QMF Reference explains each of the QMF forms used to format reports and provides examples of how to use the forms.

Solving some spill file problems

If you are not using conditional formatting or column definitions (which use REXX and have additional performance considerations), the performance you observe is the result of accessing data in the database.

If you have enough storage available to QMF after your data is retrieved the first time, QMF will not need to reaccess the database to obtain rows a second time.

Part of the processing time is devoted to writing the data to DSQSPILL so that it can be fetched later.

Performance is affected by several factors:

• The value of DSQSIROW (initial number of rows to fetch). This primarily affects the initial display of the report only.
• Whether you perform a task that requires multiple passes of the data. (Certain usage codes, such as PCT, require that all the data be read before the first report screen displayed.) This primarily affects the initial display of the report only.
• The amount of memory required to hold one row of data.
• Whether or not if data is fetched from the database the second time when multiple passes are required (not all data fits in memory and DSQSPILL), or from memory and DSQSPILL, or just from virtual memory.
• Whether you are scrolling backward or forward. Successive FORWARD commands usually perform best. BACKWARD commands might require starting over at the start of the answer set. This depends on the amount of memory, how far back you want to scroll, and the complexity of the report.

  For very large answer sets with little memory and insufficient DSQSPILL allocation, the entire answer set could be read from row 1 to the new current row, every time the BACKWARD command is used.

The best performance is attained when there is sufficient memory to hold all data and DSQSPILL is not used.

If you can get the complete answer set into virtual memory before the first display (DSQSIROW is large), the database locks will be released. You will be able to scroll around the displayed report faster. This also slows the display of the first report screen. Releasing the locks could also improve performance for other users.

DSQSIROW (controlling the number of report rows retrieved for display)

Parameter name

DSQSIROW

Short form

F

Valid values

Any number from 0 through 99,999,999

Default

Minimum of 100 rows retrieved prior to the first report screen

Use DSQSIROW to specify the maximum number of rows QMF retrieves into the data object before displaying the first screen of the report to the user. DSQSIROW applies only to the initial load of a new data object, created by:

• Executing queries that use SQL SELECT statements
• Displaying a database table with the QMF DISPLAY command

To determine the proper value for this parameter, use step 1 of the algorithm in Estimating the space required for a spill file to estimate the size of a block of rows for the largest table a user is likely to query. A block is the number of rows that fit into one 4,096-byte buffer.

After every block of rows is retrieved, QMF compares the total number of retrieved rows to the value of DSQSIROW to determine whether to display the first screen of data. For example, suppose a block in your installation is 62 rows long, and you set DSQSIROW to 50. QMF retrieves 62 rows of data and, upon comparing 62 to 50, stops retrieving rows and displays the first screen of data.

Some report formatting options, such as percent (%) usage codes and ACROSS reports, require that all the data be retrieved before QMF displays the first screen. QMF ignores the DSQSIROW value in these situations. See the QMF Reference manual for more information about these formatting options.

Performance with small DSQSIROW values

If you use too small a value for DSQSIROW, QMF might not be able to complete the data object before the first screen of data is displayed. An incomplete data object causes share locks on the data, which can prevent other users from updating the data. DB2 maintains an EDM pool to service its requesters. While a data object is incomplete, the requester contends with all other requesters for EDM resources.

Many users might be affected if a QMF control table or a part of the system catalog is locked. You can release the locks in one of the following ways:

• Use the BOTTOM command to retrieve the remaining rows into the data object, then release the locks.
• Use the RESET DATA command to release these locks and clear the data object, whether or not all requested rows were retrieved.
• Use any SAVE command (for example, SAVE DATA or SAVE FORM) to retrieve and save the remaining rows into the data object, then release the locks.

To get the best performance in a noninteractive session (when the DSQSMODE parameter is set to B), use a value of 0 for DSQSIROW unless you want to minimize the number of open read locks while QMF is retrieving or formatting data.

Do not use DSQSIROW to limit the number of rows that QMF displays on the screen. Although you can specify a small value, QMF retrieves enough rows to fill the screen display in an interactive session.

Performance with large DSQSIROW values

If you use too large a value for DSQSIROW, QMF might take a long time to display the first screen of data. If you set DSQSIROW higher than you set the DSQSBSTG parameter, QMF might display a message indicating that there is insufficient storage available to satisfy the user's request.

When storage for the region is full, QMF stops retrieving rows or terminates when storage is full.

DSQSDBUG (setting the level of trace detail)

Parameter name

DSQSDBUG

Short form

T

Valid values

ALL or NONE

Default

NONE (no trace data)

Use DSQSDBUG to specify the level of detail at which you want to trace QMF activity. If you specify NONE, no trace is performed unless you load a profile with a saved value of ALL. If you specify ALL, ALL overrides the profile values and remains at ALL.

The tracing you set with this parameter is effective until the user issues a SET PROFILE (TRACE=value command to change it, or, in the case of NONE, until the profile is loaded.

Set DSQSDBUG to ALL when you want to trace QMF activity at the highest level of detail, including program initialization errors and other errors that might occur before the user's profile is established:

DSQQMFn T=ALL
QMFn T=ALL

When you set DSQSDBUG to NONE, the level of detail in the trace output depends on whether the QMF session is running interactively or noninteractively:

• In either an interactive or a noninteractive session, only system error tracing is done during initialization, before the user's profile is established. The only way to turn off this initial tracing is to not allocate or define storage for the trace data.
• In a noninteractive session, all messages and commands are traced at the most detailed level.

After QMF starts, you can turn tracing off by using the command SET PROFILE (TRACE=NONE. You can also set more specific levels of trace detail using this command, by replacing NONE with various values that represent different QMF functions. See Using the QMF trace facility for more information.