Devoloping DB2 QMF Applications

DB2 Query Management Facility
Developing DB2 QMF Applications

Version 9 Release 1
SC18-9687-00
DB2 Query Management Facility
Developing DB2 QMF Applications

Version 9 Release 1
SC18-9687-00
Note!
Before using this information and the product it supports, be sure to read the general information under Appendix D,
“Notices,” on page 213.
First Edition (March 2007)

This edition applies to IBM DB2 Query Management Facility, a feature of Version 9 Release 1 of IBM DB2 for z/OS,
5635-DB2, and to all subsequent releases and modifications until otherwise indicated in new editions or technical
newsletters. This edition replaces SC18-7651-01.
© Copyright International Business Machines Corporation 1982, 2007. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this information . . . . . . . . . . . . . . . . . . . . . vii
How to use this information . . . . . . . . . . . . . . . . . . . . vii
Conventions for National Language Feature information . . . . . . . . . . vii
Prerequisite and related information . . . . . . . . . . . . . . . . . viii
Prerequisite knowledge . . . . . . . . . . . . . . . . . . . . . viii
Related product information . . . . . . . . . . . . . . . . . . . ix
Support information . . . . . . . . . . . . . . . . . . . . . . . ix
Accessibility features . . . . . . . . . . . . . . . . . . . . . . . ix
How to send your comments . . . . . . . . . . . . . . . . . . . . ix
Chapter 1. QMF application development overview . . . . . . . . . . . 1

What is application development in QMF? . . . . . . . . . . . . . . . 1
How can end users use your application? . . . . . . . . . . . . . . . 1
Interacting primarily with the application . . . . . . . . . . . . . . . 2
Starting the application from a QMF session . . . . . . . . . . . . . 2
What QMF application development tools are available? . . . . . . . . . . 3
QMF procedures . . . . . . . . . . . . . . . . . . . . . . . . 3
QMF callable and command interfaces . . . . . . . . . . . . . . . 4
External formats for QMF objects . . . . . . . . . . . . . . . . . 5
Command synonyms . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 2. Using procedures as applications . . . . . . . . . . . . . 7

Knowing when not to use procedures . . . . . . . . . . . . . . . . . 7
Initial procedures . . . . . . . . . . . . . . . . . . . . . . . . 7
Considerations for writing initial procedures . . . . . . . . . . . . . . 8
Initial procedures and Remote Unit of Work . . . . . . . . . . . . . . 8
Using QMF CONNECT within a procedure . . . . . . . . . . . . . . . 9
Substitution variables in procedures. . . . . . . . . . . . . . . . . . 9
Specifying values on the RUN command . . . . . . . . . . . . . . . 9
Specifying values on the RUN command prompt panel . . . . . . . . . 10
Using REXX variables in procedures with logic . . . . . . . . . . . . . 11
Passing arguments to a procedure with logic . . . . . . . . . . . . . . 11
Using REXX error-handling statements in procedures with logic . . . . . . . 12
Branching to error-handling subroutines . . . . . . . . . . . . . . . 12
Using messages with the REXX EXIT statement . . . . . . . . . . . 12
Calling REXX programs from a procedure with logic . . . . . . . . . . . 14
Calling REXX programs without substitution variables . . . . . . . . . 14
Calling REXX programs that contain substitution variables . . . . . . . . 14
Chapter 3. Using the callable interface for applications . . . . . . . . . 17

What is the callable interface? . . . . . . . . . . . . . . . . . . . 17
Considerations for using the QMF callable interface . . . . . . . . . . . 18
The interface communications area (DSQCOMM) . . . . . . . . . . . . 18
Return codes . . . . . . . . . . . . . . . . . . . . . . . . . 20
Commands for using the callable interface . . . . . . . . . . . . . . . 20
Starting QMF from an application . . . . . . . . . . . . . . . . . . 21
Running your callable interface application . . . . . . . . . . . . . . . 21
Using the callable interface from within QMF . . . . . . . . . . . . . . 22
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . 22
Running callable interface programs under CICS . . . . . . . . . . . . 22
Chapter 4. Using the command interface for applications . . . . . . . . 25

Writing a program that uses the command interface: an example . . . . . . 25
© Copyright IBM Corp. 1982, 2007 iii

Invoking the command interface . . . . . . . . . . . . . . . . . . 26
The END command . . . . . . . . . . . . . . . . . . . . . . . 26
Using variables in the command interface . . . . . . . . . . . . . . . 27
Command interface return codes . . . . . . . . . . . . . . . . . . 27
Return codes 0 through 16 . . . . . . . . . . . . . . . . . . . 27
Return codes of 20 or higher . . . . . . . . . . . . . . . . . . . 28
Chapter 5. ADDRESS QRW: Using the QMF command environment . . . . 29
Chapter 6. Writing QMF applications that use ISPF services . . . . . . . 31

Starting and running QMF from an ISPF application . . . . . . . . . . . 31
Running queries that contain variables . . . . . . . . . . . . . . . . 32
Using QMF to invoke a program that uses ISPF services . . . . . . . . . 32
Using ISPF services from a procedure with logic . . . . . . . . . . . . 32
Using the EDIT command with ISPF . . . . . . . . . . . . . . . . . 33
Using ISPF to debug applications . . . . . . . . . . . . . . . . . . 34
Using the ISPF Log Service . . . . . . . . . . . . . . . . . . . 34
Using the PDF Dialog Test service . . . . . . . . . . . . . . . . . 34
Chapter 7. Writing bilingual applications . . . . . . . . . . . . . . 35

Comparing the English and NLF environments . . . . . . . . . . . . . 35
Environmental similarities . . . . . . . . . . . . . . . . . . . . 35
Environmental differences . . . . . . . . . . . . . . . . . . . . 36
Creating objects for use in bilingual applications. . . . . . . . . . . . . 36
Using the command language variable . . . . . . . . . . . . . . . . 37
Using an initial procedure in a bilingual application . . . . . . . . . . . . 38
Using English commands . . . . . . . . . . . . . . . . . . . . . 38
Multilingual environments . . . . . . . . . . . . . . . . . . . . . 39
Creating translatable applications . . . . . . . . . . . . . . . . . . 39
Chapter 8. Using QMF commands in applications . . . . . . . . . . . 41

CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . 41
How connecting to a new location affects support for long names . . . . . 42
An example . . . . . . . . . . . . . . . . . . . . . . . . . 42
END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
GET GLOBAL (extended syntax) . . . . . . . . . . . . . . . . . . 43
INTERACT . . . . . . . . . . . . . . . . . . . . . . . . . . 44
The session form of INTERACT . . . . . . . . . . . . . . . . . 44
The command form of INTERACT . . . . . . . . . . . . . . . . . 45
MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . 46
SET GLOBAL . . . . . . . . . . . . . . . . . . . . . . . . . 49
SET GLOBAL (extended syntax) . . . . . . . . . . . . . . . . . 49
Guidelines for defining and using global variables . . . . . . . . . . . 50
START . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
General syntax . . . . . . . . . . . . . . . . . . . . . . . . 51
START command keywords . . . . . . . . . . . . . . . . . . . 51
Using command synonyms . . . . . . . . . . . . . . . . . . . . 56
Creating a command synonym . . . . . . . . . . . . . . . . . . 56
RUN QUERY report minisession . . . . . . . . . . . . . . . . . 57
Chapter 9. Exporting and importing objects . . . . . . . . . . . . . 61

What you can do with an exported UNIX file, TSO data set, or CICS data queue 61
Exporting versus saving data . . . . . . . . . . . . . . . . . . . . 62
Exporting data objects and database tables . . . . . . . . . . . . . . 62
Exporting data or tables in QMF format . . . . . . . . . . . . . . . 63
iv Developing QMF Applications

Exporting data or tables in IXF format . . . . . . . . . . . . . . . 67
| Exporting data or tables in XML format . . . . . . . . . . . . . . . 78
Rules and information for exporting and importing data objects and tables 81
Exporting forms, reports, and prompted queries . . . . . . . . . . . . . 82
General format of the exported file. . . . . . . . . . . . . . . . . 83
Exporting a form . . . . . . . . . . . . . . . . . . . . . . . 91
Exporting a standard report . . . . . . . . . . . . . . . . . . . 101
Exporting a report in HTML format . . . . . . . . . . . . . . . . 105
Exporting an across-style report . . . . . . . . . . . . . . . . . 107
Exporting a prompted query. . . . . . . . . . . . . . . . . . . 109
Importing forms and prompted queries . . . . . . . . . . . . . . . . 115
Procedures and SQL queries . . . . . . . . . . . . . . . . . . . 116
Charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Exporting QBE queries . . . . . . . . . . . . . . . . . . . . . 117
Size specifications for externalized QMF objects . . . . . . . . . . . . 117
Storage considerations . . . . . . . . . . . . . . . . . . . . . 118
CICS data queues . . . . . . . . . . . . . . . . . . . . . . 118
| TSO data sets . . . . . . . . . . . . . . . . . . . . . . . . 119
Chapter 10. Debugging your QMF applications . . . . . . . . . . . 121

Debugging your callable interface applications . . . . . . . . . . . . . 121
Using the L option for tracing . . . . . . . . . . . . . . . . . . 121
Using the A option for tracing . . . . . . . . . . . . . . . . . . 121
Turning the tracing off . . . . . . . . . . . . . . . . . . . . . 122
Allocating the QMF trace data output . . . . . . . . . . . . . . . 122
Using tracing with the QMF MESSAGE command . . . . . . . . . . 123
Debugging errors on the START and other QMF commands . . . . . . . . 123
Appendix A. Sample code for callable interface languages . . . . . . . 125

Assembler language interface . . . . . . . . . . . . . . . . . . . 125
Interface communications area mapping for Assembler (DSQCOMMA) 125
Function calls for Assembler language . . . . . . . . . . . . . . . 126
Assembler programming example . . . . . . . . . . . . . . . . 128
DSQCOMM for Assembler . . . . . . . . . . . . . . . . . . . 137
Running your Assembler programs in CICS . . . . . . . . . . . . . 139
Running your Assembler programs in TSO . . . . . . . . . . . . . 140
C language interface . . . . . . . . . . . . . . . . . . . . . . 142
Interface communications area mapping for C language (DSQCOMMC) 142
Function calls for the C language. . . . . . . . . . . . . . . . . 143
C language programming example . . . . . . . . . . . . . . . . 145
DSQCOMM for C . . . . . . . . . . . . . . . . . . . . . . 148
Running your C programs in CICS . . . . . . . . . . . . . . . . 150
Running your C programs in TSO . . . . . . . . . . . . . . . . 151
COBOL language interface . . . . . . . . . . . . . . . . . . . . 153
Interface communications area mapping for COBOL (DSQCOMMB) . . . . 154
Function calls for COBOL . . . . . . . . . . . . . . . . . . . 154
Using ISPF LIBDEF service with COBOL . . . . . . . . . . . . . . 156
COBOL programming example . . . . . . . . . . . . . . . . . 156
DSQCOMM for COBOL . . . . . . . . . . . . . . . . . . . . 158
Considerations for running your COBOL callable interface program . . . . 160
Running your COBOL programs in CICS . . . . . . . . . . . . . . 161
Running your COBOL programs in TSO . . . . . . . . . . . . . . 161
FORTRAN language interface . . . . . . . . . . . . . . . . . . . 164
Interface communications area mapping for FORTRAN (DSQCOMMF) 165
Function calls for FORTRAN . . . . . . . . . . . . . . . . . . 166
FORTRAN programming example . . . . . . . . . . . . . . . . 167
Contents v
DSQCOMM for FORTRAN . . . . . . . . . . . . . . . . . . . 171
Running your FORTRAN programs . . . . . . . . . . . . . . . . 173
PL/I language interface . . . . . . . . . . . . . . . . . . . . . 176
Interface communications area mapping for PL/I (DSQCOMML) . . . . . 177
Function calls for PL/I . . . . . . . . . . . . . . . . . . . . . 178
PL/I programming example . . . . . . . . . . . . . . . . . . . 179
DSQCOMM for PL/I . . . . . . . . . . . . . . . . . . . . . 182
Running your programs under CICS . . . . . . . . . . . . . . . 184
Running your programs under TSO . . . . . . . . . . . . . . . . 185
REXX language interface . . . . . . . . . . . . . . . . . . . . 189
Interface communications variables for REXX . . . . . . . . . . . . 189
Function call for REXX . . . . . . . . . . . . . . . . . . . . 190
REXX programming example . . . . . . . . . . . . . . . . . . 191
Running your REXX programs . . . . . . . . . . . . . . . . . . 192
A REXX example of using an INTERACT loop . . . . . . . . . . . . 193
Appendix B. Product interface macros . . . . . . . . . . . . . . . 195
Appendix C. QMF global variable tables . . . . . . . . . . . . . . 197

Naming conventions for global variables . . . . . . . . . . . . . . . 197
Global variables for profile-related state information . . . . . . . . . . . 198
Global variables for state information not related to the profile . . . . . . . 199
Global variables associated with CICS . . . . . . . . . . . . . . . . 202
Global variables related to a message produced by the most recent command 203
Global variables associated with the Table Editor . . . . . . . . . . . . 203
Global variables that control various displays . . . . . . . . . . . . . 205
Global variables that control how commands and procedures are executed 208
Global variables that store results of CONVERT QUERY . . . . . . . . . 211
Global variables that show RUN QUERY error message information . . . . . 211
Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . 213

Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 214
Glossary of terms and acronyms . . . . . . . . . . . . . . . . . 215
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
vi Developing QMF Applications

About this information
Use this topic to help you understand more about how to use the application
development information provided here. The following subtopics are included:
v “How to use this information”
v “Conventions for National Language Feature information”
v “Prerequisite and related information” on page viii
v “Support information” on page ix
v “Accessibility features” on page ix
v “How to send your comments” on page ix
How to use this information

This information is written for application programmers responsible for developing
applications that make use of QMF™ functions.
Conventions for National Language Feature information

DB2 QMF is available in several different languages, each of which is provided by a
National Language Feature (NLF).
NLFs let users enter QMF commands, view help, and perform QMF tasks in
languages other than English; they are installed as separate features of DB2 QMF.
For more information about installing an NLF, see Installing and Managing DB2
QMF for TSO/CICS.
All tasks described here can be performed for the base QMF product (English
language) and for any NLF. The procedures for both the base and NLF sessions
are the same; however, any special considerations for NLF users are preceded by
the following phrase: “If you are using an NLF”.
Some names of programs or data sets shown in this information have an "n" in
them, indicating that this character of the name can vary. If you are using an NLF,
replace any "n" symbols you see with the one-character national language identifier
(NLID) from Table 1 that matches the language feature that you are using. The table
also shows the names by which QMF recognizes each language.
Table 1. QMF NLFs and their identifying information
Name that QMF
National Language Feature Identifier (NLID) uses for this NLF
English E ENGLISH
Uppercase English U UPPERCASE
Canadian French C FRANCAIS CANADIEN
Danish Q DANSK
French F FRANCAIS
German D DEUTSCH
Italian I ITALIANO
Japanese Kanji K NIHONGO
Korean Hangeul H HANGEUL
© Copyright IBM Corp. 1982, 2007 vii

Table 1. QMF NLFs and their identifying information (continued)

Name that QMF
National Language Feature Identifier (NLID) uses for this NLF
Brazil Portuguese P PORTUGUES
Spanish S ESPANOL
Swedish V SVENSKA
Swiss French Y FRANCAIS (SUISSE)
Swiss German Z DEUTSCH (SCHWEIZ)
The Uppercase English feature uses the English language, but converts all text to
uppercase characters. The uppercase characters allow users working with
Katakana display devices to use the product and get English online help and
messages.
Prerequisite and related information

Before you begin, read the information in this topic regarding other products you
need to know about, how to get service updates and support information,
procedures you need to run, and authorities you need to have before performing
QMF administration tasks.
Prerequisite knowledge
You should be familiar with the components that make up your specific
environment, as well as some concepts and terms, before you begin application
programming for QMF.
Products
To develop applications for QMF, you may need to be familiar with some or all of
the following products, depending on your environment and your business needs:
v The z/OS® operating system.
v DB2®, the database manager for QMF.
v Time Sharing Option (TSO), which is an environment that supports DB2 QMF
and its related products.
v Interactive System Productivity Facility (ISPF), a dialog manager for DB2 QMF.
v Customer Information Control System (CICS®), a general-purpose data
communication and online transaction processing system. CICS provides the
interface between DB2 QMF and z/OS.
v The base Graphical Data Display Manager (GDDM®) product, which is required
to display panels and create charts. You can also use GDDM to provide printing
services from QMF.
v Assembler, C, COBOL, FORTRAN, PL/I or REXX, which you might use to create
callable interface applications for QMF.
v Any language that runs under ISPF, which you will use to create applications that
make use of the QMF command interface.
Publications that explain these products can be found in the IBM Publications
Center at www.ibm.com/shop/publications/order.
viii Developing QMF Applications

Concepts
QMF applications let you work with QMF objects and perform QMF functions from
within an application program written in one of the languages QMF supports. This
information assumes you already know how to write queries and procedures, format
reports, and modify the database.
Related product information

To access information about products related to QMF (such as DB2, CICS, TSO,
GDDM, REXX, and other products), see the IBM Publications Center at
www.ibm.com/shop/publications/order, where you can download or order the
information you need.
Support information
To find service updates and support information (including PTFs, Frequently Asked
Questions (FAQs), technical notes, troubleshooting information, and downloads)
refer to the following Web page:
www.ibm.com/software/data/qmf/support.html
Accessibility features
Accessibility features help a user who has a physical disability, such as restricted
mobility or limited vision, to use a software product successfully. The major
accessibility features in QMF enable users to:
v Use assistive technologies such as screen readers and screen magnifier
software. Consult the assistive technology documentation for specific information
when using it to access z/OS interfaces.
v Customize display attributes such as color, contrast, and font size.
v Operate specific or equivalent features by using only the keyboard. Refer to the
following publications for information about accessing ISPF interfaces:
– z/OS ISPF User’s Guide, Volume 1, SC34-4822
– z/OS TSO/E Primer, SA22-7787
– z/OS TSO/E User’s Guide, SA22-7794
These guides describe how to use ISPF, including the use of keyboard shortcuts
or function keys (PF keys), include the default settings for the PF keys, and
explain how to modify their functions.
How to send your comments

Your feedback is important in helping to provide the most accurate and high-quality
information. If you have any comments about this information, send an e-mail to
comments@us.ibm.com and include the name of the product and the topic along
with your comment.
About this information ix

x Developing QMF Applications
Chapter 1. QMF application development overview
You can use many of the functions of QMF in your own applications. For example,
you can write applications that:
v Run queries or procedures
v Export or import QMF objects and tables
v Display or print reports or charts
v Enable the user to enter or change data in the database
v Enable the user to make global changes to several objects at once
You can also write applications that provide helpful functions to your users in QMF,
such as a user-defined command that prints QMF reports at a remote location, or a
function key that automatically generates a chart of the weekly sales results.
This topic describes the two major types of QMF applications and the application
development tools QMF provides to help you implement your application.
The following topics are covered here:

v “What is application development in QMF?”
v “How can end users use your application?”
v “What QMF application development tools are available?” on page 3
What is application development in QMF?

The word application can have many meanings. In QMF, an application is a
procedure or program that lets you run QMF commands and alter QMF objects
using the QMF EXPORT and IMPORT commands.
Application development refers to the process of creating an application. It includes:

v Understanding the problem that your application needs to solve
v Designing the application
v Writing the code, associated messages, and help panels
Given these definitions, you can begin making the design decisions that affect how
your end users use your application and what QMF application tools you use to
enable your application to interact with QMF.
How can end users use your application?

You might want end users to interact primarily with your application, or you might
want them to use your application as a customized function in QMF.
v If your application is intended for end users who are unfamiliar with QMF, you
probably want them to interact primarily with your application. In fact, you might
not want your end users to know that QMF is active. In this case, your
application uses QMF services, but resides outside of QMF. Your program issues
QMF commands only as needed.
v If your end users are familiar with QMF, you might want your end users to see
your application as an extension or customization of QMF. In this case, you need
to set up your application to run within QMF.
© Copyright IBM Corp. 1982, 2007 1

QMF application development overview
Interacting primarily with the application

Suppose you write an application that uses QMF services. This application provides
the end user with a menu-driven interface, as shown in Figure 1.
J & H Supply Company

Information System
Please select one of the following:
1. Print the monthly sales report
2. Create a new report
3. Modify information in the database
4. End the application
====> 1
Figure 1. An example of an application-defined panel
If the user selects option 1, the application executes a QMF procedure that runs a
query and prints the resulting report.
In the example in Figure 1, your application controls QMF. Your user interacts only
with your user interface and is not aware that QMF is active.
Starting the application from a QMF session

Suppose you write an application that sends a QMF report from one user to
another.
You expect your users to run your application from within the QMF environment.
The users can use the command line to issue a QMF command synonym called
SEND_TO (which you create) or you can assign the application to a function key
that automatically runs your application.
After generating a report, the user can send the report to Smith by entering SEND_TO
SMITH on the QMF command line, as shown in Figure 2 on page 3.
2 Developing QMF Applications

REPORT LINE 1 POS 1 79
NAME DEPT JOB SALARY COMM

--------- ------ ----- ---------- ----------
DANIELS 10 MGR 19260.25 -
JONES 10 MGR 21234.00 -
LU 10 MGR 20010.00 -
MOLINARE 10 MGR 22959.20 -
HANES 15 MGR 20659.80 -
KERMISCH 15 CLERK 12258.50 110.10
NGAN 15 CLERK 12508.20 206.60
ROTHMAN 15 SALES 16502.83 1152.00
JAMES 20 CLERK 13504.60 128.20
PERNAL 20 SALES 18171.25 612.45
SANDERS 20 MGR 18357.50 -
SNEIDER 20 CLERK 14252.75 126.50
ABRAHAMS 38 CLERK 12009.75 236.50
MARENGHI 38 MGR 17506.75 -
1=Help 2= 3=End 4=Print 5=Chart 6=Query
7=Backward 8=Forward 9=Form 10=Left 11=Right 12=
OK, here is your report.
COMMAND ===> SEND_TO SMITH
Figure 2. An example of a user entering a customized QMF command
What QMF application development tools are available?

Regardless of how your end users see your application, you can write applications
using any of the following application development tools:
v QMF procedures
v QMF callable interface
v QMF command interface
v QMF externalized formats
v QMF command synonyms
QMF procedures
QMF procedures are QMF objects that run within QMF and issue QMF commands.
QMF procedures can execute any QMF commands available at your site. QMF
provides two types of procedures: linear procedures and procedures with logic.
v Linear procedures contain only QMF commands and comments. You can use
linear procedures in all environments supported in QMF.
v Procedures with logic combine QMF commands with REXX logic to enable you
to create more powerful programs. You can use procedures with logic in all
environments supported in QMF, except CICS. Procedures with logic can contain
QMF commands and any statement that is valid in a REXX program, including
system commands.
For general information about writing linear procedures or procedures with logic,
see Using DB2 QMF. For specific information about using QMF procedures to write
applications, see Chapter 2, “Using procedures as applications,” on page 7.
Chapter 1. QMF application development overview 3

QMF provides a system initialization procedure that allows you to run commands
and set global variables before the user sees the QMF home panel.
QMF callable and command interfaces

If you choose not to use QMF procedures, you must decide whether your program
will communicate with QMF through the callable interface or the command interface.
Callable interface
You can use the QMF callable interface to create an application invoked outside of
QMF, which starts a QMF session and sends commands to QMF for execution.
The callable interface is available for all environments supported in QMF. It is a

Common Programming Interface for query and is available for the programming
languages shown in Table 2.
Table 2. Callable interface support
CICS TSO Native z/OS batch
Assembler × × ×
C × × ×
COBOL × × ×
FORTRAN × ×
PL/I × × ×
REXX × ×
QMF supports all versions of these programming languages that are supported by
DB2 for z/OS. For details on supported versions, see your DB2 information.
For more information about the callable interface, see Chapter 3, “Using the callable
interface for applications,” on page 17.
Command interface
The QMF command interface allows you to create applications that submit
commands to QMF from an ISPF dialog. QMF communicates with the ISPF dialog
through the ISPF variable pool using this command interface.
The command interface is available only where ISPF is available; it is not available
in CICS.
For more information about the QMF command interface, see Chapter 4, “Using the
command interface for applications,” on page 25.
Differences between the callable and command interfaces

The differences between the callable interface and the command interface are as
follows:
Callable interface:
v Is available for all QMF-supported environments
v Does not require ISPF
v Does not require QMF to be started before you run your application
Command interface:
v Is available in all environments supported in QMF and ISPF

v Requires ISPF to be present and active

v Requires QMF to be started before the application is started
v Provides variables for communication between the ISPF application and QMF
v Requires the programming language to be supported by ISPF
External formats for QMF objects

Your application can export QMF objects outside of the QMF product; for example,
you can export a form to a TSO data set or a CICS data queue. Each object has a
particular format that your application can edit and transfer to another system or
import into QMF.
For more information about the externalized formats of QMF objects, see Chapter 9,
“Exporting and importing objects,” on page 61.
Command synonyms
QMF allows you to specify command synonyms for programs or procedures that
you code. These command synonyms allow end users to use your programs and
procedures just as they would use any QMF command.
For more information about command synonyms, see “Using command synonyms”
on page 56.
Chapter 1. QMF application development overview 5

Chapter 2. Using procedures as applications
You can write applications entirely as procedures. You can create procedures on
your development system and keep them for your personal use or move them to
your production system for public use.
If you are using QMF in the CICS environment, you can use QMF linear
procedures. If you are using QMF in the TSO environment, you can also use REXX
statements and functions in your QMF procedures. REXX functions and procedures
with logic are not available in the CICS environment.
This topic focuses on information you need to know to use QMF procedures to
implement your application. For information about how to create, build, and run a
procedure, see Using DB2 QMF.
Using ISPF services in a QMF procedure requires a few extra steps. For
information about running ISPF commands from a QMF procedure with logic
running under ISPF, see “Using ISPF services from a procedure with logic” on page
32.
The following topics are covered here:

v “Knowing when not to use procedures”
v “Initial procedures”
v “Using QMF CONNECT within a procedure” on page 9
v “Substitution variables in procedures” on page 9
v “Using REXX variables in procedures with logic” on page 11
v “Passing arguments to a procedure with logic” on page 11
v “Using REXX error-handling statements in procedures with logic” on page 12
v “Calling REXX programs from a procedure with logic” on page 14
Knowing when not to use procedures

If you are writing an application that operates on a procedure in QMF temporary
storage, you cannot write your application as a procedure. When you run a
procedure, it becomes the current procedure in QMF temporary storage.
For example, if you write your application as a procedure and code your application
to save the current procedure in QMF temporary storage, the application saves
itself; it is the current procedure in QMF temporary storage while it is running.
Initial procedures
An initial procedure is a procedure that runs immediately after your QMF session
starts. Use the DSQSRUN parameter to specify the name of this procedure. You
can use DSQSRUN:
v With the DSQQMFn command when QMF is started interactively (where n is a
one-character identifier from Table 1 on page vii that reflects the NLF you are
using)
v With the QMF START command when QMF is started through the callable
interface

Using procedures as applications
In TSO, ISPF, and native z/OS batch, applications can also set program parameters
using a REXX program as described by the DSQSCMD parameter of the QMF
START command. Because QMF for CICS does not support REXX, you must
specify all program parameters on the START command using DSQSMODE=I,
which specifies interactive operation, in CICS. The default mode from the callable
interface is B (for batch operation).
For more information about the DSQSRUN parameter, see Installing and Managing
DB2 QMF for TSO/CICS.
Considerations for writing initial procedures

v By default, QMF reruns the initial procedure whenever the user issues the END
command in an interactive session of QMF started by DSQQMFn (where n is the
one-character identifier from Table 1 on page vii that represents the NLF you are
using). The DSQEC_RERUN_IPROC global variable specifies if the initial
procedure is rerun. The default value of this variable is 1 to rerun the procedure;
a setting of 0 prevents the initial procedure from being rerun.
In callable interface programs, the initial procedure is never rerun, so this global
variable does not affect your callable interface programs.
v If you are writing initial procedures to use in an interactive QMF session, avoid
having the home panel be the current panel at the end of the procedure. QMF
will not interactively display a panel at the end of the procedure in this case. If no
severe errors occurred and DSQEC_RERUN_IPROC is set to 1, QMF reruns the
initial procedure without interacting with the user. This results in an uninterruptible
loop that can appear as though QMF is not starting.
To avoid creating an uninterruptible loop, do one of the following:
– Make sure that the current panel at the end of the procedure is not the home
panel.
– Make sure that the procedure contains either a QMF EXIT or an INTERACT
command.
– Set DSQEC_RERUN_IPROC to zero (0).
v When you specify values for substitution variables in initial procedures, the
number of ampersands (&) you must use before the name of the variable can
vary depending on your environment. For example, you can specify DSQSRUN
as:
DSQSRUN=INITPROC(&VAR1 = value)
The number of ampersands that you need to specify with VAR1 depends on
whether QMF is running under CICS, TSO, or native z/OS batch, if ISPF is
present, and if the program starting QMF is written in REXX.
Initial procedures and Remote Unit of Work

The initial procedure must be stored at the system on which you start QMF (the
local system).
If you use the QMF CONNECT command from either your initial procedure or the
command line during an interactive session set up by an initial procedure, you must
code the application to reconnect to your original location before you can code an
END command to invoke your initial procedure again.
If you are still connected to the remote location, you will receive an error.

Using QMF CONNECT within a procedure

The QMF CONNECT command lets you connect to another user ID or to a remote
DB2 database to use remote-unit-of-work support. You can use this command
within a linear procedure or a procedure with logic.
When you write procedures that use the QMF CONNECT command to access
remote databases, be aware of the following:
v If you are connected to a remote database and issue a RUN PROC command,
that procedure and all the objects used in that procedure must be stored at the
remote database.
v All QMF commands in the procedure are run in QMF temporary storage at the
system where QMF is running (the local system). However, all objects used by
these QMF commands (such as queries, procedures, or forms) must be defined
in the database at the current location (the remote system).
For more information about using the QMF CONNECT command and
remote-unit-of-work support, see DB2 QMF Reference.
v Commands that affect the database (SQL statements, QMF queries, or EDIT
TABLE updates) run at the current location.
v If the procedure contains system-specific commands (CICS or TSO), these
commands run at the system where QMF is running (the local system).
If your procedures contain system-specific commands that do not run on the
system where QMF is running, your procedure will not run successfully.
v Any data sets or data queues used in a system-specific command must exist on
the system where QMF is running (the local system).
| v If your site uses TSO and takes advantage of RACF® support for mixed-case
| passwords, ensure that the CASE option of your QMF profile is set to MIXED.
| Otherwise, QMF converts all input to upper case, causing the CONNECT
| command to fail. When CASE=MIXED, ensure that you tell QMF application
| users to enter all input in upper case, because QMF only recognizes commands
| in upper case.
Substitution variables in procedures

You can use QMF substitution variables in linear procedures and procedures with
logic.
A substitution variable is any variable that you can use in a QMF command. A
substitution variable is always preceded by an ampersand (&). You can assign a
value to a substitution variable by setting global variables, by specifying values on
the RUN command, or by specifying values on the RUN command prompt panel.
For information on setting global variables, see “SET GLOBAL” on page 49.
See Using DB2 QMF to learn more about using ampersands with substitution
variables in QMF as well as how to write linear procedures and procedures with
logic.
Specifying values on the RUN command

You can assign a value to a substitution variable using the RUN command.
v In your linear procedure, assign the variable value as follows:
RUN PROC SCHEDULE (&&TYPE=’VACATION’
v In your procedure with logic, assign the value as follows:
Chapter 2. Using procedures as applications 9

"RUN PROC SCHEDULE (&&TYPE=’VACATION’"
The value of &TYPE is available only to the procedure called SCHEDULE.
In this example:
v The variable value VACATION is surrounded by single quotes because the value is
a character string.
v TYPE is preceded by double ampersands (&&) to indicate that the value is being
set on the RUN statement to be passed to the procedure named SCHEDULE. If
the RUN statement specifies &TYPE, the procedure containing this statement
prompts the user for the value.
This value for the substitution variable is active only within the procedure that
defines it. The value is not active in any procedure or module called from the
defining procedure.
If you issue the QMF RUN command from within a PROC or QUERY panel, you do
not need to specify the PROC or QUERY object types. The RUN command
assumes these values when you invoke it from the respective object panels.
Specifying values on the RUN command prompt panel

If you run a query or procedure that contains a substitution variable, and this
variable is not assigned a value by a global variable or on the RUN command, QMF
presents a RUN command prompt panel. You can specify the value for the variable
on this panel.
This value for the substitution variable is active only within the procedure that
defines it. The value is not active in any procedure or module called from the
defining procedure.
For more information about writing linear procedures and procedures with logic, see
Using DB2 QMF.
Prompting for variables in linear procedures

In a linear procedure, QMF scans the procedure for substitution variables and
resolves them before it processes any commands. The user is prompted for all
variables before the procedure runs.
Prompting for variables in procedures with logic

In a procedure with logic, the user is not prompted for variables until REXX
encounters the statement containing the variables. For example, if your procedure
with logic contains three statements that contain variables that QMF must prompt
you for, QMF prompts you three times—once for each statement.
If you want a procedure with logic to prompt you for all the necessary variable
values at one time like a linear procedure does, use a dummy procedure. For
example, suppose that you want to be prompted once for the substitution variables
LASTNAME and DEPT_NUM, which occur on two different lines in your procedure
with logic as shown in Figure 3 on page 11.

/* This procedure runs two queries, displaying the report after each */
/* procedure has run. */
"RUN QUERY REG_QUERY (&&LASTNAME=&LASTNAME";

"INTERACT"
"RUN QUERY REG2_QUERY (&&DEPT_NUM=&DEPT_NUM";
Figure 3. Prompting for variable values in a procedure with logic
Add the following line to the beginning of your procedure with logic, immediately
following the comment lines. (All procedures with logic must begin with at least one
comment line.)
"RUN PROC PROMPT_ME (&LASTNAME, &DEPT_NUM";
In this command, PROMPT_ME is a procedure with logic like the following, which
contains a comment line and no instructions:
/* This procedure is a dummy procedure that provides prompting */
Figure 4 shows the completed procedure with the RUN PROC command for the
PROMPT_ME procedure that prompts for variables:
/* This procedure runs two queries, displaying the report after each */
/* procedure has run */
"RUN PROC PROMPT_ME (&LASTNAME, &DEPT_NUM";

"RUN QUERY REG_QUERY (&&LASTNAME=&LASTNAME";
"INTERACT"
"RUN QUERY REG2_QUERY (&&DEPT_NUM=&DEPT_NUM";
Figure 4. Procedure with logic that prompts for variables
Alternatively, you can use SET GLOBAL to prompt for all the values in your
procedure at the same time, as in the following example:
"SET GLOBAL (LASTNAME=&LASTNAME,DEPTNUM=&DEPT_NUM";
Using REXX variables in procedures with logic

You can use REXX variables in a procedure with logic. The values for these
variables are known only within the procedure in which you defined them. You can:
v Copy a REXX variable to a QMF variable with the SET GLOBAL command
v Copy a global variable to a REXX variable with the GET GLOBAL command
v Use REXX variables in your REXX statements
For more information on REXX variables, see the REXX reference information for
your system in the IBM Publications Center at www.ibm.com/shop/publications/
order. For details on using the GET GLOBAL and SET GLOBAL commands in
procedures with logic, see DB2 QMF Reference.
Passing arguments to a procedure with logic

For procedures with logic, QMF provides an ARG option on the RUN PROC
command. This option lets you pass arguments, or values, to a procedure with
logic.

Use the ARG option when you are running a procedure that contains a REXX
PARSE ARG or ARG statement, as in the example shown in Figure 5:
PROC WILDE.SHOW_ARGS MODIFIED LINE 1
/************************************************************************/
/* This procedure shows you how to use the ’ARG=’ option on the RUN */
/* PROC command. */
/************************************************************************/
parse upper arg query_name form_name
"RUN QUERY" query_name "(FORM="form_name
Figure 5. Passing variable values using the ARG option of the RUN PROC command
The RUN command for this procedure is as follows:

RUN PROC SHOW_ARGS (ARG=(query_name form_name)
In this command, query_name and form_name are REXX variable names that
describe the parameters being passed to the procedure with logic; they contain the
object names for a query and a form, respectively. Using these variable names
allows you to reference the parameters that were passed to the procedure with
logic.
Using REXX error-handling statements in procedures with logic

You can use REXX error handling techniques, such as the REXX SIGNAL
instruction, in a procedure with logic. You can also use QMF commands and
variables with the REXX EXIT instruction to help clarify nonzero return codes.
Branching to error-handling subroutines

The REXX signal on error instruction tells REXX to leave the current line and
branch to a label marked error when a nonzero return code is encountered. This
statement requires two parts:
v Signal on error instruction
After every command, REXX puts the return code of the command in a variable
called rc.
If a command has a nonzero return code, REXX branches to the error label.
Signal on error returns errors from the QMF REXX procedure (ADDRESS QRW)
command environment, but not the REXX callable interface.
v Error label
The signal on error instruction requires that you provide a label that the
procedure can branch to if it encounters a nonzero return code. The label
precedes your error handling code. The return code is in the variable rc. You can
use this variable to branch to another subroutine, or you can use it in your EXIT
instruction, as in the following example:
/* error handling code for a procedure with logic */
error:
exit rc
Using messages with the REXX EXIT statement

You can use the REXX EXIT instruction to exit a procedure with logic. QMF always
issues a message when it finishes running a procedure with logic. If you use the
EXIT instruction, the message you see depends on these factors:

v If the last QMF command encountered an error

v If the return code was zero
Table 3 shows which message you see based on the given conditions.
Table 3. Messages returned from QMF
Return code from
the last QMF Procedure return Examples of messages at the completion
command code of the procedure
0 0 OK, your procedure was run
The return code from your procedure was
0 Nonzero 8
Nonzero 0 The error message provided by QMF
Nonzero Nonzero The error message provided by QMF
A QMF error message takes precedence over the return code message if you have
an incorrect QMF command and a nonzero return code.
If you want to show the error message from the last command and exit with a QMF
return code, use the MESSAGE command and the EXIT DSQ_RETURN_CODE
instruction, as in the example in Figure 6:
..
.
"MESSAGE (TEXT=’"dsq_message_text"’"
exit dsq_return_code
Figure 6. Showing the error message and return code
The variables dsq_message_text and dsq_return_code are QMF-provided REXX

variables. (For a complete listing of these variables, see “REXX language interface”
on page 189.) You can use the MESSAGE command and the dsq_message_text
variable to store and display a message after further processing has occurred, as
shown in Figure 7.
/* Monthly report */
Signal on error
"DISPLAY TABLE JUNE_INFO"
"PRINT REPORT"
Exit(0);
Error: Original_msg = dsq_message_text
/* Saves error message. */
"RUN PROC GENERAL_RECOVERY"
/* This proc generates */
/* new dsq_message_text. */
"MESSAGE (TEXT=’" Original_msg "’"
/* Display original error msg. */
Exit dsq_return_code;
Figure 7. Storing and retrieving messages in a procedure
For more information on the MESSAGE command, see “MESSAGE” on page 46.

Calling REXX programs from a procedure with logic

If you call your REXX callable interface application from a procedure with logic, be
careful about the number of ampersands (&) you specify for the substitution
variables in your application. This is especially true if the program being called
contains a RUN command with substitution variables, as in RUN QUERY WEEKLY_Q
(&&DEPT=58. This topic explains the correct number of ampersands to use in each
situation.
Calling REXX programs without substitution variables

If your REXX program does not contain an embedded RUN command that includes
substitution variables, use one of the following commands to invoke your program:
v The ADDRESS instruction
This instruction establishes a command environment. (For more information on
command environments, see Chapter 5, “ADDRESS QRW: Using the QMF
command environment,” on page 29.) For example, if your program is named
PANDA, and you want to call it from within the TSO environment, the command
is:
ADDRESS TSO "PANDA"
v The CALL instruction
This instruction invokes a program. For example, for the program named PANDA,
the command is:
CALL PANDA
For more information about the syntax of the CALL instruction, see DB2 QMF
Reference.
v A function
You also can call the program PANDA as a function:
answer = PANDA()
For more information on any of these commands, see the REXX reference
information in the IBM Publications Center at www.ibm.com/shop/publications/order.
You might consider removing the substitution variables from the RUN command if
you want to call your programs using one of the REXX invocation calls. In that
case, QMF prompts the user for the variables.
Calling REXX programs that contain substitution variables

If your REXX application contains a QMF RUN command with a substitution
variable, you must invoke it using the following command:
TSO program_name
Whether you are running a procedure with logic or a callable interface program
invoked by a procedure with logic, commands come into QMF the same way. In this
context, the callable interface program becomes a logical extension of the
procedure itself.
For example, consider the following command:

RUN QUERY WEEKLY_Q (&DEPT=58
In a procedure with logic, use two ampersands on the substitution variable to pass
the variable to the query:

"RUN QUERY WEEKLY_Q (&&DEPT=58"
If a substitution variable has only one ampersand, QMF resolves the variable for the
procedure itself and cannot pass the variable to the query.
If you call a REXX callable interface application from a procedure with logic, and
that application contains the command RUN QUERY WEEKLY_Q (&DEPT=58, QMF
resolves the variable just as it would for the calling procedure. Because only one
ampersand is used, the variable is not passed to the query.
To pass variables to QMF from a REXX callable interface application called by a

procedure with logic, you have three choices:
v Use the TSO command to call the application.
When you call the application, QMF does not process any substitution variables it
encounters. In the preceding RUN QUERY command, &DEPT=58 is passed to the
query, where the substitution variable is resolved.
v Treat all substitution variables in your application as though you were using them
in a procedure with logic.
Add an ampersand to every substitution variable so the procedure with logic
does not resolve it.
v Use global variables.
You can define global variables at the start of your application and use them
throughout your QMF session.


Chapter 3. Using the callable interface for applications
This topic presents an overview of the QMF callable interface.
The following topics are covered:

v “What is the callable interface?”
v “Considerations for using the QMF callable interface” on page 18
v “The interface communications area (DSQCOMM)” on page 18
v “Return codes” on page 20
v “Commands for using the callable interface” on page 20
v “Starting QMF from an application” on page 21
v “Running your callable interface application” on page 21
v “Using the callable interface from within QMF” on page 22
v “Error handling” on page 22
v “Running callable interface programs under CICS” on page 22
For specific information about the QMF callable interface for a particular language,
see the information in Appendix A, “Sample code for callable interface languages”
that describes the callable interface for that language:
Assembler “Assembler language interface” on page 125
C Language “C language interface” on page 142
COBOL “COBOL language interface” on page 153
FORTRAN “FORTRAN language interface” on page 164
PL/I “PL/I language interface” on page 176
REXX “REXX language interface” on page 189
What is the callable interface?

Programming languages can use the QMF callable interface to run QMF
commands. The QMF callable interface provides standard interfaces for different
programming languages, and provides common storage and access to program
variables.
When an application program needs to run a QMF command, it must first issue a
call to a QMF-supplied routine to start communication between the program and
QMF. This call is made to the QMF-supplied interface routine. QMF supplies a
routine for each supported language.
The application program can issue one or more QMF commands after the initial
start call. The application program calls the QMF-supplied routine to issue each
QMF command.
After the QMF command finishes processing, QMF supplies a return code that
indicates the status of QMF. The callable interface gathers other information about
the processing of the command and stores this information in variables accessible
to both QMF and the application program. These variables are contained in either a
variable pool or in an interface communications area. When the callable interface
returns control to the calling application program, the application can refer to these
variables but should not alter them.

Using the callable interface for applications
When the application program no longer needs to use QMF, the program issues a
call to terminate communication between the program and QMF. This call is made
to the QMF-supplied routine.
Considerations for using the QMF callable interface

v A call to QMF returns control to the calling application program only after QMF
finishes processing the QMF command.
v QMF is in an inactive state when not processing a call.
v The application program and QMF communicate with return codes and variable
data stored in the variable pool or in the interface communications area.
v All QMF commands must be coded in uppercase English letters.
If you are using a QMF national language feature (NLF), your QMF commands
must be written in the presiding NLF language, and written in (or folded to)
uppercase. You set the presiding language when you start QMF, by providing a
value for the DSQALANG parameter on the START command. This value is
recorded in the DSQEC_NLFCMD_LANG global variable. (For more information
on the DSQALANG parameter, see “START command keywords” on page 51.)
v The maximum length of the passed commands is 2K for REXX programs and
32K for all other languages.
Figure 8 shows how the application passes commands through the callable
interface to QMF.
Figure 8. How an application uses the QMF callable interface to communicate with QMF
The interface communications area (DSQCOMM)

QMF provides an interface communications area for each supported programming
language. This area contains the following information:
v Definitions of return and reason codes
v Definition of the function calls to QMF
The interface communications area defines storage for the interface

communications variables, and the variables stored in this area are accessible to

both QMF and the callable interface application, although only QMF should alter the
values. The application program should view these variables as read-only.
The REXX callable interface uses interface communications variables provided by

QMF rather than using a communications area.
The QMF callable interface communications area is required for all callable
interface calls. Storage for the callable interface communications area is allocated
by the program that is using QMF.
The START command establishes a unique instance or occurrence of a QMF

session. The START command can establish only one QMF session:
v In a TSO address space
v From a single CICS transaction
When running the START command, QMF updates the variables within the interface
communications area.
These variables must never be altered by the application program, with the
following exceptions:
DSQ_COMM_LEVEL
Set DSQ_COMM_LEVEL to the value of DSQ_CURRENT_COMM_LEVEL
to identify the level of DSQCOMM. This does not apply to REXX.
DSQ_INSTANCE_ID
If you call a callable interface program from within QMF, you need to set the
DSQ_INSTANCE_ID to zero (0) on the first call so that QMF resets the
variable to the value set by the initial START command.
All calls that follow the START command must pass the address of the interface
communications area that corresponds to the QMF instance. The application
program is responsible for pointing to the correct interface communications area.
Each supported language has a unique interface communications area that

describes the interface communications area. Application programs must reference
variables by variable name rather than value if they are to be portable, because the
values can be different on other systems. For a description of the interface
communications area for the programming language you are using, see Appendix A,
“Sample code for callable interface languages,” on page 125.
The variables within the interface communications area contain the information in
Table 4.
Table 4. DSQCOMM fields that must not be altered
Information
provided by the
variable Description
Return code Indicates the status of QMF processing after QMF processes a
command.
Instance identifier Identifies the instance of QMF that was started by the START command.
Completion Contains the message ID of the message that QMF displays.
message ID
This field is set at the completion of every QMF command. It contains the
message QMF displays at the end of a command.
Chapter 3. Using the callable interface for applications 19

Table 4. DSQCOMM fields that must not be altered (continued)

Information
provided by the
variable Description
Query message Contains the message ID of the message that is displayed on the query
ID panel upon completion of a RUN QUERY command.
This field is set when an error occurs while a query is running. It contains
the message that QMF displays within the query object at the end of a
command.
START command Contains the name of the parameter in error when the START command
parameter in error fails because of a parameter error.
Cancel indicator Indicates whether the user canceled processing while QMF was running
the command.
Completion Contains the completion message that QMF displays.
message
Query message Contains the query message text of the message that is displayed on the
query panel upon completion of a RUN QUERY command.
For example, if you run a query object with an error, QMF displays a
message describing the error that prevented the query from running. The
query message field then contains this error message text.
Return codes
Return codes are returned after each call to the QMF callable interface. Return
code values are described by the interface communications area provided with
QMF.
If you want your applications to be portable across systems, the applications must
reference the values of these codes by the variable names, because the values can
be different on other systems. (For the names of the return-code variables within
the interface communications area for each programming language, see
Appendix A, “Sample code for callable interface languages,” on page 125.)
Table 5 shows the possible return codes for callable interface conditions.
Table 5. Callable interface return codes
Value Explanation
0 Successful execution
4 QMF session marked for termination by an EXIT or END command
8 Execution failed, but the error did not mark the session for termination
16 Severe error: session marked for termination
Commands for using the callable interface

You can use the callable interface to issue any QMF command that you would use
in a procedure. However, there are three commands that have special syntax for
the callable interface:
v START
v GET GLOBAL
v SET GLOBAL
The START command works only in the callable interface. To use the GET GLOBAL
and SET GLOBAL commands in a callable interface application written in a
language other than REXX, use the extended syntax for these commands. The
extended syntax of the SET GLOBAL command allows you to set global variables
that have values up to 32,768 characters long. For more information on using the
GET GLOBAL and SET GLOBAL commands in a callable interface application, see
“GET GLOBAL (extended syntax)” on page 43 and “SET GLOBAL (extended
syntax)” on page 49.
For information about these and other commands you can use in a callable
interface application, see Chapter 8, “Using QMF commands in applications,” on
page 41. To see examples of the START and SET GLOBAL commands for each
language, see the programming examples for each language:
Assembler “Assembler programming example” on page 128
C Language “C language programming example” on page 145
COBOL “COBOL programming example” on page 156
FORTRAN “FORTRAN programming example” on page 167
PL/I “PL/I programming example” on page 179
REXX “REXX programming example” on page 191
Starting QMF from an application

Before you can run any other command from an application, you must start QMF.
When using the callable interface, you start QMF by issuing the START command
in your application. You can have only one QMF session at a time.
Your application can issue a START command to test whether QMF has already
been started. If QMF has not been previously started, it starts. If QMF was
previously started, the return code is nonzero, and you receive the following
message number and message:
DSQ50719 QMF already active. Secondary session not permitted.
If your START command results in a non-severe error (a return code of 4 or 8),

QMF starts and a session is established. In this case, you must issue a QMF EXIT
command to stop QMF. Inspect the contents of the interface communications area
or the QMF trace data output for the cause of the error.
To pass parameters to QMF, specify the desired command keywords on the START
command. For details about the syntax and keywords used with the START
command, see “START” on page 50.
Running your callable interface application

When you run your callable interface application, you must set up your environment
as though you were going to run QMF interactively.
For specific information about setting up your environment and compiling and
running your callable interface application, see the appropriate coding sample for
your language in Appendix A, “Sample code for callable interface languages,” on
page 125.

Using the callable interface from within QMF
Note to CICS users

You cannot use the callable interface from within QMF while in the CICS
environment.
If you need to modify a QMF object from a user program, you can use the callable
interface from within QMF. For example, you can export or import objects through
the callable interface during an interactive QMF session. You can use the callable
interface from within QMF by using the TSO command to call the application. You
can run any valid QMF command from the application.
You must set the DSQCOMM instance identifier (DSQ_INSTANCE_ID) to zero (0)
before your first call to QMF. QMF determines the current instance and updates
DSQ_INSTANCE_ID for use in subsequent QMF calls.
Error handling
At the completion of every QMF command, the DSQCOMM communications area
contains message text in the dsq_message_text variable and a return code in the
dsq_return_code variable. The return code is assigned one of the following values:
dsq_success Successful completion of the command
dsq_warning Normal completion with warnings
dsq_failure Command did not run correctly
dsq_severe Severe error; QMF session terminated
For a complete list of variables or fields in each DSQCOMM area, see Appendix A,
“Sample code for callable interface languages,” on page 125 and read the
information specific to the programming language you are using.
Running callable interface programs under CICS

To run programs that use the QMF callable interface, install them into CICS using
your normal method of installing CICS programs. The IBM Publications Center at
www.ibm.com/shop/publications/order contains the CICS publications, which provide
more information about CICS applications.
In addition to the normal CICS requirements, the following considerations apply to

all QMF callable interface programs running on CICS:
v Environment
When your program calls the QMF product, your program takes on the same
characteristics as the interactive QMF product; it becomes a very large
conversational program.
QMF is an Assembler-language program that contains CICS commands. It can
be link-edited with other Assembler-language programs or with programs in one
of the supported high-level programming languages. (See “Callable interface” on
page 4 for a list of supported languages.) When you call QMF using a high-level
language, the high-level language program must be link-edited first, and the
resource definition online (RDO) program definition must specify that high-level
language. Each high-level program has specific CICS considerations and

restrictions. The IBM Publications Center at www.ibm.com/shop/publications/order

contains the CICS publications, which provide more information about high-level
language programming in CICS.
In CICS, if you want to override any of the default QMF program parameters, you
must specify the override values as parameters on the START command. For
example, the default mode of operation from the callable interface is batch mode.
To run an interactive QMF session you must issue the START command using
DSQSMODE=I.
v CICS region considerations
The user program containing the QMF interface communications module and the
main QMF module must run in the same region or partition. QMF resources, as
described during QMF installation, must also be allocated to the CICS region or
partition that runs QMF.
v Database
The CICS transaction that invokes your program must be described to DB2. The
IBM Publications Center at www.ibm.com/shop/publications/order contains the
DB2 and CICS publications, where you can find more information about how to
describe programs to DB2.


Chapter 4. Using the command interface for applications
Note to CICS users

The QMF command interface requires ISPF to run, but ISPF does not run in
the CICS environment. Therefore, you need to use the QMF callable interface
for application development under CICS.
The QMF command interface allows you to issue QMF commands from an ISPF
dialog running under QMF. Using this interface, QMF communicates with the dialog
through the ISPF variable pool, as shown in Figure 9.
ISPF
ISPF
Variable
Pool
Application
Program QMF
Figure 9. QMF command interface application interacting with QMF
The following topics explain how to develop applications that make use of the
command interface:
v “Writing a program that uses the command interface: an example”
v “Invoking the command interface” on page 26
v “The END command” on page 26
v “Using variables in the command interface” on page 27
v “Command interface return codes” on page 27
To use the command interface effectively, you need to understand ISPF services
and variable pools. The IBM Publications Center at www.ibm.com/shop/publications/
order contains the ISPF publications, which provide additional information.
Writing a program that uses the command interface: an example

Suppose that you want to use the command interface to display an ISPF panel that
prompts a user to specify a query name, runs the specified query, and displays a
report.
For this scenario, do the following:

1. Write your command interface REXX program. Your program does the following:

Using the command interface for applications
a. Displays the ISPF panel QRYNAME using the DISPLAY services:

ADDRESS ISPEXEC "DISPLAY PANEL(QRYNAME)"
b. Runs a QMF query based on user input from the previous DISPLAY service.
Here, the ISPF variable QNAME contains the name of the QMF query:
ADDRESS ISPEXEC "SELECT PGM(DSQCCI) PARM(RUN QUERY" QNAME ")"
c. Lets the user view the result of the query, using the following command:
ADDRESS ISPEXEC "SELECT PGM(DSQCCI) PARM(INTERACT)"
2. Call your program using the TSO command from the QMF command line. For
example, if your program is named GETINFO, your command looks like the
following:
TSO GETINFO
Invoking the command interface

The command interface is a program named DSQCCI. You can invoke it from a
program through the ISPF SELECT service. To start the command interface, do the
following:
1. Start ISPF.
2. Start QMF using the ISPF SELECT service to call the QMF command interface
(DSQCCI). You can pass QMF commands using the PARM option of the ISPF
SELECT PGM command.
After you start the command interface, you can pass QMF commands you want to
run using the PARM parameter of the ISPF SELECT PGM command, as follows:
SELECT PGM(DSQCCI) PARM(qmf_command)
All QMF commands specified as parameters to the command interface must be in

uppercase, regardless of the QMF profile setting. ISPF does not automatically
convert the commands from lowercase to uppercase; if you specify your QMF
commands in lowercase, QMF will not recognize them.
If you want to use QMF command prompts from your ISPF application, you can
issue the INTERACT command followed by the QMF command for which you need
a prompt to appear, followed by a question mark. For example, to display the RUN
QUERY prompt panel, issue the following command:
SELECT PGM(DSQCCI) PARM(INTERACT RUN QUERY ?)
The SELECT service requires you to use double ampersands on a RUN QUERY
command. This prevents ISPF from interpreting the variable as one of its own.
On the invocation, do not specify the NEWPOOL or NEWAPPL option. Omitting the
NEWPOOL or NEWAPPL options ensures that the command interface can access
your application’s variables. The command interface uses the shared pool to
communicate between QMF and your application.
The END command

The END command terminates the DSQCCI program and returns control to the
calling application when issued while the command interface is running. The QMF
session remains active.

QMF will set the global variable DSQCSESC to mark the session for termination if it
encounters an EXIT command or a severe error during a command interface
invocation. When the program that called DSQCCI ends and returns control to
QMF, the QMF session terminates.
Using variables in the command interface

The STATE command provides the current value for each QMF-provided variable; it
can be used only in the command interface. You can place the QMF variables in
the ISPF variable pool through the VPUT command. Appendix C, “QMF global
variable tables,” on page 197 shows the 8-character command interface names for
the global variables that QMF places into the ISPF variable pool.
Command interface return codes

Return codes for the command interface are the same regardless of the language
of your application. The return code can be positive or zero. A value of zero
indicates successful execution. A positive value indicates that the execution failed or
was abnormal in some way.
Return codes appear in a variable in the user’s exec or CLIST. If you run a REXX
exec, the return code is in the REXX variable called RC; if you run a CLIST, the
return code is in the CLIST variable &LASTCC.
The following example shows an exec that examines a return code. The example
shows how to run a query and test for an error using the REXX variable RC:
ADDRESS ISPEXEC SELECT PGM(DSQCCI) PARM(RUN QUERYA (FORM=FORMA))
Select
When (RC = 0) Then nop
When (RC = 64) Then
Say "You must run QMF with ISPF to use command interface."
When (RC = 100) Then
Say "You need to start QMF before you begin your application"
Otherwise
Say "Unexpected error ("RC") from QMF command interface."
End
You can place code for handling errors in program modules as well as in execs or
CLISTs.
Return codes 0 through 16

Return codes 0 through 16 describe the QMF processing of the command passed
with the command interface. When the command interface returns one of these
codes, it also returns the values of the QMF command message variables in the
application’s ISPF shared pool. The codes are shown in Table 6.
Table 6. Return codes 0 through 16
Value Explanation
0 Successful execution
4 QMF session marked for termination by an EXIT or END command
8 Execution failed, but the error did not cause the session to be marked for
termination
16 Severe error: session marked for termination
Chapter 4. Using the command interface for applications 27

A return code of 4 occurs only on the command that caused the session to be
marked for termination. If the application then attempts to run another command,
QMF returns another return code value to the application.
Return codes of 20 or higher

These codes usually reflect some failure in the command interface (DSQCCI). The
failure has made it impossible to copy a variable into the application’s shared pool.
As a result, the QMF variables might be invalid, or they might not have been set.
The same may be true of the STATE variables if your program uses the STATE
command. (A variable has been set if it has been copied into the application’s
shared pool.)
These return codes usually indicate more serious errors than those in the 0 through
16 range. Some may require the services of the IBM® Support Center.
Table 7 contains explanations of return codes with values of 20 or higher. "Shared

variables" refers to the QMF variables (and the STATE variables, if the current
command is the STATE command).
Some codes indicate that the command was run but the shared variables were not
set. This means that QMF ran the STATE command properly, but the command
interface failed to set the updated shared QMF and STATE variables for the reason
given in the explanation of the error code.
Table 7. Return codes of 20 or more
Value Explanation
20 A user exit routine called the command interface; these calls are always
invalid. The command passed to the command interface was not run. The
shared variables were not set.
24 An error occurred in an ISPF VCOPY command. The command passed to
the command interface was run. The shared variables were not set.
32 An error occurred in an ISPF VREPLACE command. The command passed
to the command interface was run. The shared variables were not set.
36 An error occurred in an ISPF VPUT command. The command passed to the
command interface was run. The shared variables were not set.
40 An error occurred in an ISPF VREPLACE command. This code applies only
to the execution of the STATE command. The command passed to the
command interface was run, but the shared variables were not set.
44 An error occurred in an ISPF VPUT command. This code applies only to the
execution of the STATE command. The QMF variables were set, but the
STATE variables were not.
60 An invalid call was made to the command interface. The command passed
to the command interface was not run. The shared variables were not set.
64 This error is issued when DSQCCI is run and ISPF is not active. For
example, the user could have called DSQCCI without using an ISPF
SELECT PGM command.
100 This error occurs when an application tries to issue a QMF command when
QMF is not active. Start QMF before you begin your application. The
command passed to the command interface was not run. The shared
variables were not set.
104 The anchor was not located. The command passed to the command
interface was not run. The shared variables were set but are not valid.

Chapter 5. ADDRESS QRW: Using the QMF command
environment
Note to CICS users

ADDRESS QRW does not work in the CICS environment.
When QMF is started in TSO, ISPF, or native z/OS, QMF creates a REXX
command environment called QRW. When you are executing a REXX program, you
can set the default command environment to QRW by issuing the REXX ADDRESS
command ADDRESS QRW. With ADDRESS QRW, QMF remains the default command
environment until you issue another ADDRESS command.
You can also direct a single command to be executed by the QRW environment by
issuing the REXX ADDRESS command followed by the QMF command:
ADDRESS QRW qmf_command
In this situation, QMF is the command environment only for the command that
follows the ADDRESS QRW statement.
When you are using a QMF procedure with logic, QRW is the default command
environment.
The following example shows how to use the QMF command environment:
..
.
call dsqcix "START (DSQSMODE=INTERACTIVE"
if dsq_return_code=dsq_severe | dsq_return_code=dsq_failure
then exit dsq_return_code
ADDRESS QRW
"RUN PROC MONDAY_P"
then exit dsq_return_code
"EXIT"
.. then exit dsq_return_code
.
Figure 10. Example of using the QMF command environment

Chapter 6. Writing QMF applications that use ISPF services
You can bypass the QMF panels by writing applications that have their own user
interfaces. You can use either the callable interface or the command interface to
write applications that use ISPF.
Note to CICS users

ISPF does not run in the CICS environment, so ISPF services are not
available under CICS.
This topic outlines considerations for using the callable interface with ISPF. The
following topics are covered:
v “Starting and running QMF from an ISPF application”
v “Running queries that contain variables” on page 32
v “Using QMF to invoke a program that uses ISPF services” on page 32
v “Using ISPF services from a procedure with logic” on page 32
v “Using the EDIT command with ISPF” on page 33
v “Using ISPF to debug applications” on page 34
For general information about using the callable interface, see Chapter 3, “Using the
callable interface for applications,” on page 17. For information on using the
command interface, see Chapter 4, “Using the command interface for applications,”
on page 25.
Starting and running QMF from an ISPF application

When you write a callable interface application that will make use of ISPF, you need
to ensure the following:
v The callable interface application must match the language of your ISPF dialog
For example, if your ISPF dialog is a PL/I program, you must use the QMF
callable interface for PL/I to write your application.
v You must use the correct national language identifier
You must start your ISPF application with an ID of DSQn, where n is a National
Language Feature (NLF) identifier. This application ID prevents QMF from
overriding your ISPF environment, such as the function key settings and labels,
and ensures that the ISPF environment remains intact even after QMF is started.
To begin the application that starts QMF, use a statement like the following:
SELECT PGM(MYPROG) NEWAPPL(DSQn)
The PL/I program MYPROG then starts QMF using the callable interface START
command.
For a list of NLF identifiers, see the description for the DSQALANG keyword in
Table 8 on page 52.
v Use the GET GLOBAL or SET GLOBAL commands in your application instead of
the STATE command to set and retrieve variable values
The GET GLOBAL and SET GLOBAL commands work for all the QMF global
variables; the STATE command works only for variables containing state
information. For more information about STATE variables, see one of the
following topics:

Writing QMF applications that use ISPF services
– “Global variables for profile-related state information” on page 198

– “Global variables for state information not related to the profile” on page 199
Running queries that contain variables

Your applications can run queries that contain variables. You can run these queries
from an application that uses ISPF services in one of three ways:
v Use ISPF file-tailoring services.
With this technique, you represent the query by an ISPF file-tailoring skeleton. In
that skeleton, the portions of the query that can change appear as ISPF dialog
variables. After giving these variables the proper values, your program starts
certain ISPF file-tailoring services. The result is a sequential file containing the
query.
The program can then import the query into QMF temporary storage and have
QMF run it. The required IMPORT and RUN commands can be run through the
callable interface or command interface.
To use this technique, you must know how to define ISPF dialog variables in your
program using the ISPF dialog service. The IBM Publications Center at
www.ibm.com/shop/publications/order contains the ISPF publications, which
provide additional information on how to define dialog variables.
v Use the Program Development Facility (PDF) editor to create QMF objects
You can use the PDF editor with PDF edit macros to design and control data
entry to queries, procedures, forms, and profiles. You can use REXX to write
PDF macros.
v Create a query using an ISPF dialog.
To create a file that contains an SQL query, your program can use ISPF display
services to display a screen and create a file based on input from the user. This
file can then be imported into QMF and run.
Using QMF to invoke a program that uses ISPF services

If you want to start your ISPF program from within QMF, you must call the program
from a linear procedure or a procedure with logic. To call your program, use the
ISPF SELECT PGM service by including the following command in your procedure:
ADDRESS ISPEXEC "SELECT PGM(programname)"
Use the CMD keyword to indicate to ISPF that you are running your program as an
ISPF dialog function. The syntax for this command is:
ADDRESS ISPEXEC "SELECT CMD(cmdname)"
or
ADDRESS ISPEXEC "SELECT CMD(cmdname parameters)"
In this statement, cmdname is the name of your callable interface command.
Using ISPF services from a procedure with logic

You must transfer from the QMF program dialog to an ISPF command dialog to run
ISPF commands from a QMF procedure with logic running under ISPF.
To set the correct ISPF environment and run a program containing your ISPF
commands, use the following ISPF SELECT CMD statement with the CMD
keyword:

ADDRESS ISPEXEC "SELECT CMD(userprogram)"
In this statement, userprogram is the program that contains your ISPF commands.
For example, if the program that contains your ISPF commands is called DIALOG,
include the following command in your procedure with logic:
ADDRESS ISPEXEC "SELECT CMD(DIALOG)"
The IBM Publications Center at www.ibm.com/shop/publications/order contains the

ISPF publications, which provide additional information on ISPF commands and
statements.
You can also use a QMF TSO command to run your program that contains ISPF
commands (for example, TSO DIALOG). In this case, QMF issues the ISPF SELECT
CMD statement for you.
If you are running QMF under ISPF, and your procedure with logic starts a program
requiring ISPF services, your procedure must start this program using the ISPF
SELECT CMD environment. For example, suppose you are running QMF under
ISPF and your procedure with logic issues the DB2 command DSN. Because the
DSN command uses ISPF services, you should use one of the following commands
to issue the DSN command:
ADDRESS ISPEXEC "SELECT CMD(DSN)"
or
ADDRESS ISPEXEC "SELECT CMD(DSNEXEC)"
In the second statement, DSNEXEC is a program that contains the ADDRESS TSO
DSN statement.
Using the EDIT command with ISPF

When you run your QMF application under ISPF, you can edit your QMF SQL query
or procedure using the following commands:
EDIT QUERY
EDIT PROC
If you issue the QMF EDIT command from a PROC or QUERY panel, you do not
need to specify the PROC or QUERY object types. EDIT assumes these values
when you invoke it from their respective panels. By default, the QMF EDIT
command places your procedure or query in a PDF editor session. QMF starts the
PDF editor using the QMF application ID DSQn, where n is the NLF identifier. QMF
also sets the function keys and the location of the command line to match your
QMF application.
To override the default editor, use the EDIT QUERY and EDIT PROC commands as
follows:
EDIT QUERY (E=name
EDIT PROC (E=name
In these statements, name can be either of the following:

v An editor available to you
v The name of a REXX program that specifies an application ID other than the
default (which is DSQn, where n is the national language identifier for the NLF
Chapter 6. Writing QMF applications that use ISPF services 33

you are using). You might want to use an application ID different from the QMF
default application ID if you want to have function keys different from those QMF
provides.
If you are using PDF EDIT options that require PDF PROFILE data set members,
you must create those members. For example, the PDF EDIT RECOVERY option
requires a DSQnEDRT PROFILE data set member (where n is the NLF character
from Table 1 on page vii) that must exist before you use the EDIT command.
For more information about the QMF EDIT command, see DB2 QMF Reference.
Using ISPF to debug applications

The QMF trace facility can help you trace QMF activity at various levels of detail.
For more information on QMF trace functions, see Chapter 10, “Debugging your
QMF applications,” on page 121. You can also use the ISPF Log Service and PDF
Dialog Test service to complement the function that the QMF trace facility provides
to help you more effectively debug applications that make use of ISPF.
Using the ISPF Log Service

You can use the ISPF log service to write a message to the ISPF log file. For
example, in REXX, the ISPF command to write a message to the ISPF log is:
ADDRESS ISPEXEC LOG MSG (message-id)
In this statement, message-id is the identification code for the message that is to be
retrieved from the message library and written to the log.
Using the PDF Dialog Test service

If your site has PDF, you can use the PDF Dialog Test service to log ISPF
application service calls to the ISPF log file. Additionally, you can use the log option
of the PDF Dialog Test service to browse the contents of the log file or data set.
You can also print the log file or data set when you exit ISPF.
The Dialog Test service has many other useful options for debugging your
application. For example, you can perform debugging interactively. You can run all
or portions of your application, examine the results, make changes, and rerun it.
You can also use Dialog Test to:
v Start selection panels, command procedures, and programs
v Display panels
v Add variables and modify variable values
v Run ISPF dialog services
v Add, modify, and delete breakpoint definitions
v Add, modify, and delete function and variable trace definitions
The trace (TRACES) option of the Dialog Test service enables you to create,
change, and delete trace definitions, as well as monitor dialog service calls and
dialog variable usage. During processing, if any of the trace definitions are satisfied,
trace output is written to the ISPF log. You can use the LOG option of Dialog Test
to browse the ISPF log, or you can examine the printed output when you exit ISPF.
For more information about ISPF services in general and Dialog Test in particular,
see the ISPF publications in the IBM Publications Center at www.ibm.com/shop/
publications/order.

Chapter 7. Writing bilingual applications
Many business applications need to run in several different national languages. You
can write one English application and run it in any national language that QMF
supports.
Each national language that QMF supports is called a National Language Feature
(NLF). An NLF provides a user with a QMF session that is tailored to a specific
national language.
QMF provides bilingual support for commands and forms. You can run English QMF
commands and display English forms in any NLF. This topic provides information
about working with QMF in one or more NLF environments. The following topics are
covered:
v “Comparing the English and NLF environments”
v “Creating objects for use in bilingual applications” on page 36
v “Using the command language variable” on page 37
v “Using an initial procedure in a bilingual application” on page 38
v “Using English commands” on page 38
v “Multilingual environments” on page 39
v “Creating translatable applications” on page 39
Comparing the English and NLF environments

When no NLFs are installed, the only available QMF session environment is the
English-language environment. This topic explains the similarities and differences
between the NLF and English-language environments.
Environmental similarities
In many ways, the QMF session environment is the same no matter which NLF is in
operation. The most important similarities are:
v Capabilities
In general, you can do anything in an NLF session that you can do in an
English-language session. You can create objects in temporary storage and save
them in the database, format and print reports, and issue SQL commands. You
can also run Prompted Query, SQL and QBE queries, as well as QMF
procedures. The difference between the English and NLF environments lies not
in what you can do, but in how you need to enter your input and what languages
are displayed.
v SQL and QBE
The verbs, operators, and keywords of the SQL and QBE languages are not
translated.
v Usage codes for forms
These are identical; they are not translated.
v System commands
TSO and CICS commands can still be issued from QMF through QMF’s TSO or
CICS command. These commands are unaffected by translation: enter TSO or
CICS followed by the command to be run, and write the command exactly as you
would if you were running it outside of QMF.

Writing bilingual applications
Environmental differences
Some of the differences between the NLF environment and the English-language
environment are:
v The QMF command language
Every NLF has a complete set of translated QMF verbs and keywords. These
translated verbs and keywords must appear in your QMF commands when you
are operating in the NLF’s language environment. For a given NLF, these words
might be translated. For example, suppose that, in the German NLF, the verb
DISPLAY and the keyword PROC are translated into ANZEIGEN and
PROZEDUR, respectively. During a German NLF session, QMF understands the
command ANZEIGEN PROZEDUR, but does not understand DISPLAY PROC.
Some elements of the QMF language are command synonyms and can be
translated. As a result, each NLF has its own uniquely-named command
synonym table. When the NLF is installed, its command synonym table is
created, and the profile for the NLF indicates the command synonym table name
for that NLF. For more information on creating command synonyms, see
Installing and Managing DB2 QMF for TSO/CICS.
v QMF panels and messages
Every NLF has a complete set of translated QMF messages and panels. Like the
verbs and keywords for QMF commands, these might or might not be translated.
In most cases, they are translated. Within the panels and messages, the fixed
portions of text can be translated. Information that can vary within each panel or
message, such as query names, is not translated.
v Allowable panel input
Many QMF panels requiring user input, such as prompt panels and form panels,
restrict the range of some entries to a small set of keywords, which are
translated. YES and NO responses in English, for example, are JA and NEIN in
German.
v Profile parameter values
In a multilingual environment, users have a separate profile for each available
NLF they can use for a QMF session. For each of these profiles, the parameters
are the same and have the same meanings, but the parameter names are
translated. Certain parameter values are also translated.
For example, in an English profile, the CASE parameter can have the value
UPPER, STRING, or MIXED. In a German profile, the CASE parameter is the
SCHRIFT parameter, and the valid values are GROSS, KETTE, and GEMISCHT.
v Exported and saved form objects
The SAVE, EXPORT, and IMPORT commands let you specify the language in
which you want form objects saved. You can save them in English, or in the
presiding language of your current session. For more information on these
commands, see DB2 QMF Reference.
v Sample tables and queries
IBM supplies translated versions of the English sample tables and queries.
Creating objects for use in bilingual applications

The objects in a bilingual application are like any other QMF object. The key is that
you either create or save them in English. How you do this depends on the specific
object:
Queries You can create prompted and QBE queries in any language

supported by the QMF national language features shown in Table 1

on page vii or you can create SQL queries in English.
Forms Always create forms in the presiding language. Save them by either
using the default language on the SAVE command (ENGLISH) or
with the presiding language.
The global variable DSQEC_FORM_LANG controls which language
is used for the SAVE command. The default value is 1 for English.
A 0 value specifies that the forms are to be saved in the presiding
session language.
Procedures You can create procedures in either English or the presiding
language.
You can translate to English a form that you create and save in an NLF by issuing a
SAVE command. For example, in French, the command to save in English a form
called SEMAINE_F as WEEKLY_F is:
SAUVER FORMAT SEMAINE_F EN WEEKLY_F (LANGUE=ANGLAIS
This converts your NLF form to an English form that you can use in your bilingual
application.
Using the command language variable

To begin using English commands in an NLF session, set the presiding language
variable, DSQEC_NLFCMD_LANG, to English. This variable lets you switch
between English and the presiding language of the NLF session.
For example, suppose that your application is a procedure named WEEKLY_P. The
commands shown in Figure 11 demonstrate how to switch between English and the
presiding NLF language. Following the figure is an explanation of each line.
"GET GLOBAL (CURR_LANG=DSQEC_NLFCMD_LANG" 1

"SET GLOBAL (DSQEC_NLFCMD_LANG=’1’" 2
"RUN PROC WEEKLY_P" 3
"SET GLOBAL (DSQEC_NLFCMD_LANG=CURR_LANG" 4
Figure 11. Switching in a procedure between English and the presiding NLF language
These commands can be part of any valid QMF application, from an initial
procedure to a high-level language program, but they must be in this order. The
commands in the example do the following:
1 This line of the procedure saves the presiding language value into a
variable.
The GET GLOBAL command saves the value for the presiding language in
a variable called CURR_LANG.
2 This line of the procedure sets the presiding language to the language for
which the application was written.
Since the WEEKLY_P application in this example was written using English
commands, the SET GLOBAL command sets the presiding language to
English by setting the DSQEC_NLFCMD_LANG variable to 1.
3 This line of the procedure runs the application.
Chapter 7. Writing bilingual applications 37

After the QMF session is set to English, the application in the example can
be run. User commands must be in English. However, if a user presses a
function key, the underlying command is assumed to be in the presiding
language.
QMF assumes that prompt panels are in the user’s presiding language. For
the EXPORT and IMPORT command prompt panels, the default data set
type, data queue type, or path name is also in the presiding language.
The QMF profile in effect for the session is the user's profile under the NLF
that was set when the application started, not the QMF profile of the
presiding language. For example, suppose a user uses QMF in both
English and German and thus has both English and German QMF profiles.
If the user starts a QMF session under the German NLF, the options in the
German QMF profile are in effect. If the user sets the
DSQEC_NLFCMD_LANG variable to English to run a procedure written
with English commands, the options in the German QMF profile still remain
in effect throughout the session.
4 This line of the procedure returns to the presiding language.
After the application ends, you should reset the command language
variable to its original value as shown in the example.
Using an initial procedure in a bilingual application

If your application starts QMF and runs an initial procedure, QMF runs that
procedure every time the user issues the END command. QMF terminates if this
procedure encounters an error. For example, if the user is running in English and
issues an END command in the presiding language, QMF interprets the command
as an error and terminates.
You can avoid this situation in one of two ways:

v Change the initial procedure to handle bilingual applications.
A bilingual initial procedure includes the commands shown in Figure 12.
"GET GLOBAL (CURR_LANG=DSQEC_NLFCMD_LANG"

"SET
.. GLOBAL (DSQEC_NLFCMD_LANG=0"
.
./*
..
QMF commands in the presiding language */
"SET GLOBAL (DSQEC_NLFCMD_LANG=CURR_LANG"
Figure 12. An initial procedure used in a bilingual application
v Avoid running the initial procedure after the END command.

You can set the variable DSQEC_RERUN_IPROC to 0 so that QMF does not run
the initial procedure when the user issues the END command.
Using English commands

For most QMF commands, you must change the presiding language variable before
you can run the command in English. However, to display a prompt panel or
message in a presiding language, some English commands must run in an NLF
even when the presiding language variable is not set to English.

For example, if you have an interactive application that you want to write in English
and run in an NLF, you must use the MESSAGE command to send the user
customized messages. In addition, you need the INTERACT command to display
the message, as in the example in Figure 13 (which can be run in a French NLF
session):
proceed_text = ’Continue...’
"RUN WEEKLY_Q" /* Use the English RUN command */
"SET GLOBAL (DSQEC_NLFCMD_LANG=0" /* switch back to French */
"MESSAGE (TEXT=’"proceed_text"’" /* message in French */
"INTERACT" /* show the report with message */
Figure 13. Using the MESSAGE and INTERACT commands to display messages
The following commands work in any NLF:

v GET GLOBAL
v INTERACT
v MESSAGE
v SET GLOBAL
v START
Multilingual environments
When one or more NLFs are installed, a multilingual environment is created. With
the proper authorization, you can choose a presiding language for each QMF
session. For example, you can choose English for one session and German for
another, provided the German NLF is installed. Although you cannot switch
languages during a QMF session, you can switch the command language variable.
End the current session and start another to obtain the appropriate language
environment.
Creating translatable applications

You can save time in adapting an application to new languages by using variables
for as many language-sensitive objects as you can. Using variables lets you use the
same program in several NLFs. These variables can include:
v The verbs, object names, and options of a QMF command
v Installation-defined panel names
If you create your own ISPF panels for your application, you need a set of
translated panels for each language under which the application is to be run.
Give these panels unique names and make them available to the application
users. The application can then use variables for the panel names.
v Installation-defined message identifiers
If you create your own ISPF panels, you will also create messages to be issued
by ISPF. These messages panels will have unique IDs and you can use variables
to refer to them. The message text should also be translated into the appropriate
NLF languages. The application can use variables for the message names.
Chapter 7. Writing bilingual applications 39


Chapter 8. Using QMF commands in applications
Any command that is valid on the QMF command line in a particular environment is
valid in an application. However, the following commands are specially designed to
be used in applications:
v “CONNECT”
v “END” on page 42
v “EXIT” on page 43
v “GET GLOBAL (extended syntax)” on page 43
v “INTERACT” on page 44
v “MESSAGE” on page 46
v “SET GLOBAL” on page 49
v “START” on page 50
This topic describes how to use these commands in application programs. All
commands explained here can be used in both callable and command interface
applications with the exception of the START command, which you can use only
with the callable interface. For additional information on any of the commands in
this topic, see DB2 QMF Reference.
“Using command synonyms” on page 56 explains how you can create your own
commands that can perform a variety of functions.
CONNECT
Use the QMF CONNECT command to access data and objects on a remote server.
When you connect to the remote system, this system becomes the current location.
When you write applications, you can issue this command from:
v The callable interface
v The command interface
v Within a procedure (linear or with logic)
Certain aspects of your applications can be affected when you use the QMF
CONNECT command to access a remote server. Be aware of the following
considerations:
v When your application connects to a new location, the QMF profile, command
synonyms, and function keys are re-initialized to the values at the new (current)
location.
v Once QMF starts, the program can issue a QMF CONNECT command to
connect to a remote server. (For a list of valid remote server types, see Installing
and Managing DB2 QMF for TSO/CICS.) Any subsequent QMF commands or
SQL statements that affect database objects are run at the remote server.
v Different types of commands behave differently with remote unit of work. When
your applications use remote unit of work, be aware that all system-specific and
most QMF commands run at the system where QMF is running (the local
system). However, when a QMF command does either of the following, the
commands affect the database at the remote server:
– Sends SQL commands to the database
– Uses or alters QMF objects and data stored in the database

Using QMF commands in applications
| v If your site uses TSO and takes advantage of RACF support for mixed-case
| passwords, ensure that the CASE option of your QMF profile is set to MIXED.
| Otherwise, QMF converts all input to upper case, causing the CONNECT
| command to fail because the case of the password is incorrect. When
| CASE=MIXED, ensure that you tell QMF application users to enter all input in
| upper case, because QMF only recognizes commands in upper case.
How connecting to a new location affects support for long names

When you connect to a new location when starting QMF, support for long names is
dependent on the database limits and QMF object tables that are in effect for the
database that you are connecting to:
v The length of the authorization ID used on the connection must not be longer
than either the authorization ID supported by the database or the authorization ID
supported by the QMF control tables.
v The maximum length of table names is dependent on the maximum length
supported by the database that you are connecting to.
v The maximum length of column names is dependent on the maximum length
supported by the database that you are connecting to.
v The maximum length of QMF object names is dependent on the maximum length
supported by the QMF control tables (18 bytes for QMF Version 7.2 and earlier;
128 bytes for QMF Version 8.1 or later).
An example
Suppose that you are logged onto your local system (SANJOSE) and you want to
write a REXX callable interface program that does the following:
1. Starts a QMF session.
CALL DSQCIX "START"
2. Connects to the remote DB2 database (DALLAS).
CALL DSQCIX "CONNECT TO DALLAS"
3. Runs a procedure with logic (EARNINGS) that queries the remote server for
data, formats the data, and prints the report.
CALL DSQCIX "RUN PROC EARNINGS"
The procedure EARNINGS contains the following logic:
.
.
.
"RUN QUERY EARNQ (FORM=EARNF"
"PRINT
. REPORT"
.
.
4. Ends the QMF session.
CALL DSQCIX "EXIT"
For more information about connecting to a remote location with the QMF
CONNECT command, see DB2 QMF Reference.
END
You can use the END command to set the QMF home panel as the current panel.
For example, if a QMF report is the current QMF panel, issuing the END command
from a callable interface or command interface program sets the QMF home panel
as the current screen. Once the QMF home panel is the current screen, issuing the
END command has no effect on the QMF session.

EXIT
The EXIT command works the same regardless of how the QMF session was
started: it marks all the user’s sessions for termination.
When the EXIT command is entered on the command line, the session in which it is
entered is terminated immediately. Each session begun by the INTERACT
command terminates as the application that started it completes. When the EXIT
command is issued in an application, the session ends when the original QMF
session ends. All interactive sessions begun by the INTERACT command must end
before QMF terminates.
In a callable interface program, it is important to include the QMF EXIT statement

when the application is done using QMF. If you forget to include this command,
your QMF session remains active until you log off, or until your batch job
completes.
When the user or an application issues the EXIT command, QMF sets
DSQAO_TERMINATE to 1 (marked for termination). Only an application running
within QMF can test and use this global variable. If DSQAO_TERMINATE is set to 1
when QMF returns to the main QMF session, QMF immediately terminates and
releases resources.
GET GLOBAL (extended syntax)

You can use the GET GLOBAL command to access QMF global variables in your
application. For languages other than REXX, QMF provides an extended syntax for
the GET GLOBAL command.
GET Global ( Variable definitions
Variable definitions:
number of varnames , varname lengths , varnames ,
value lengths , values , value type
You can use the GET GLOBAL command to copy the value of a QMF global
variable into an application-defined variable for use by the application. The
parameters you specify on the GET GLOBAL command define the application
variable.
number of varnames
The number of variables requested.
varname lengths
A list of lengths for each variable name specified.
The length of the variable name. An 18-character area padded with trailing
blanks is allowed.
varnames
A list of names of the QMF variables.
Chapter 8. Using QMF commands in applications 43

Do not specify trailing blanks in global variable names; QMF deletes trailing
blanks.
value lengths
A list of the lengths of the values of the variables.
The following rules apply to the variable value:
v If the value length you supply is less than that of the value stored in QMF,
QMF truncates on the right and returns a truncated value.
v If the value length you supply is greater than that of the value stored in QMF,
QMF returns a value padded with trailing blanks.
values
A list of variable values.
value type
The data type of the storage area that contains the values; it must be either
character or integer.
INTERACT
You can use the INTERACT command to display the current QMF panel and allow
users to interact with QMF at different points in your application. When the user
issues the END command from a QMF panel, QMF returns control to the
application. When the user issues the EXIT command from a QMF panel, the QMF
session is marked for termination and QMF returns control to the application.
The INTERACT command has two forms: session and command.
The session form of INTERACT

When you issue the INTERACT command, QMF places the user on the current
panel and allows the user to issue QMF commands interactively. The INTERACT
command provides another QMF session within your current session. The
INTERACT command can place the user in either an interactive QMF session or an
interactive GDDM ICU session.
v For an interactive QMF session:
Issue the INTERACT command following a QMF command that would normally
display a QMF panel. In this session, the user can enter any commands that are
valid for interactive QMF.
v For an interactive GDDM ICU session:
Issue the INTERACT command following a command that normally makes QMF
start GDDM ICU and display the ICU panel. In this session, the user can enter
any commands that are valid for the ICU.
A scenario
Figure 14 shows a procedure that requires only one step to produce a report.
/* This procedure prints the weekly sales report. */

"RUN QUERY WEEKLY_SALES_Q (FORM=WEEKLY_SALES_F"
"PRINT REPORT"
Figure 14. A simple procedure without the INTERACT command

QMF displays the REPORT panel containing your formatted data with a message
that says, "OK, your procedure was run."
You might decide to write a procedure that involves several steps. If you want to
see the intermediate results of such a procedure, you must use the INTERACT
command at the points in the procedure where you want to see the results of a
command. For example, to see the intermediate results of a procedure that runs
more than one query, insert an INTERACT command immediately following the first
RUN QUERY command, as shown in Figure 15:
/* This procedure generates a report showing annual sales. */

"INTERACT"
"RUN QUERY YEAR_TOTAL_Q (FORM=YEAR_TOTAL_F"
Figure 15. Using INTERACT in a procedure
When you run this procedure from the home panel, QMF displays the REPORT
panel containing your formatted data. Next, enter the END command from the
REPORT panel. The procedure runs the second query and displays the final report.
If you omit the INTERACT command, QMF displays only the final report without
showing the result of the first query.
Suppressing the display of reports

If you run a query in a QMF callable interface application, QMF displays the
resulting report. However, you can tell QMF not to automatically display the report
by setting the DSQDC_DISPLAY_RPT global variable to zero (0). You can also set
this global variable on the START command by specifying DSQADPAN=0.
This global variable is valid only when the RUN QUERY command is issued from
an application. It does not affect the display of reports when the RUN QUERY
command is issued from the QMF command line.
Ending a session started by the INTERACT command

When the user issues the END command, control returns to the process that issued
the INTERACT command; however, the two sessions are not independent. Anything
done during the INTERACT session remains in effect when the old session
resumes. For example, if the user modifies the current form object in the new
interactive session, the current form object in the old session contains these
modifications when the new session ends.
If you want your application to display the QMF home panel after the user issues an
END command from a QMF object panel (the way interactive QMF does), add the
logic shown in “A REXX example of using an INTERACT loop” on page 193.
The command form of INTERACT

The command interface (DSQCCI) runs QMF commands interactively only when the
command interface application uses the command form of INTERACT and QMF is
running an interactive session (DSQSMODE=I).
The command form of INTERACT has no effect on a command issued through the
callable interface. In the callable interface, the only way to control whether
commands are run interactively is to set DSQSMODE=I on the START command.
For more information about the DSQSMODE keyword, see Table 8 on page 52.

Use the following command syntax to request interactive execution of a designated

command:
INTERACT command
In this statement, command is the command that you want to run interactively.
Various QMF prompt and status panels can appear in this dialog.
For example, the following command displays the command prompt panel for RUN
QUERY command options:
INTERACT RUN QUERY ABC ?
If interactive execution is not allowed, as in a QMF batch session, the command

form of INTERACT has no effect on the command it precedes.
You can check to see if interactive execution is allowed in the current session by
examining a variable named DSQAO_INTERACT; a value of 1 means that
INTERACT is allowed. A batch application does not allow interactive execution. See
“Global variables for state information not related to the profile” on page 199 for
details on the DSQAO_INTERACT variable.
MESSAGE
When you create applications, you often want to send specific messages to your
users about the information displayed for them or the function they should perform
next. You can write your own messages and display them on QMF panels through
the MESSAGE command. In ISPF, you can also choose to have QMF display the
message help for an ISPF error message.
The MESSAGE command syntax is as follows:
Message
number (
Help=helppanel
Stopproc=Yes|NO
Text=value
number (with ISPF only)

number is only valid under ISPF. This parameter is the identification number of
a message definition in an ISPF message library.
HELP
Use this parameter to specify a help panel other than the one defined with the
message normally displayed in this situation. Replace helppanel with the
appropriate panel ID.
You cannot modify a QMF panel to be displayed if its definition is in DSQPNLE.
In ISPF, if you want to create and display your own panel, the panel’s definition
must be in an ISPF panel library. This library must be concatenated to your
ISPPLIB data set. The panel must be a help panel, not a menu or a data-entry
panel.
In ISPF, if you have specified number, helppanel defaults to the help-panel
indicator for the message definition specified by number.

In ISPF, if the message definition specified by number does not reference a

help-panel indicator, then the MESSAGE command does not provide message
help. Instead, the QMF help for the object panel appears on the user’s screen
when the user requests help.
STOPPROC
Use Stopproc to suppress the execution of linear procedures by setting the
procedure termination switch. The following command sets the procedure
termination switch:
Message (Stopproc=Yes
When Stopproc=Yes, the procedure termination switch is on. The default value
is No (off). This switch only affects linear procedures.
While this switch is on, any QMF procedure receiving control ends its execution
immediately. While the switch is off, procedures run normally.
When the switch is off, only a MESSAGE command can turn it back on. When
the switch is on, it stays on until one of the following happens:
v Another QMF command is issued. This can be any QMF command, except a
MESSAGE command with the option to turn the switch on.
v Control returns to the user when the application ends. A user can always
issue online commands that run QMF procedures.
You can check to see whether the procedure termination switch is on by

examining the variable DSQCM_MESSAGE. If the termination option is in
effect, this variable contains the message for the MESSAGE command that
turned on the termination switch.
TEXT
Use the TEXT option to define a message or to override the text in an ISPF
message definition. Replace value with the character string to be used for the
message. A value that contains blank characters must be surrounded with
delimiters. Valid delimiters for a message value are single quotes, parentheses,
and double quotes. When the delimiters are double quotes, the double quotes
are displayed as part of the message. The maximum length for a message
value is 360 single-byte characters; how much of the message can be
displayed is determined by the width of the display device you are using. A
value longer than 78 characters is truncated to contain only the first 78
characters. QMF does not fold the text to uppercase; however, ISPF might fold
the text to uppercase if MESSAGE is issued through the command interface.
If your message contains quotes, you need to double the quotes in the TEXT=
specification.
In ISPF, the default is the long message text of the ISPF message specified by
number, which becomes the generated message. The text is left as it is; no
folding takes place, regardless of the value of the CASE setting in the user’s
QMF profile.
Suppose that you want to write an application using a procedure that runs two
queries and displays two reports. When QMF displays the first report, you want to
display a message that tells users to end the interactive session when they are
ready to continue to the second report. You can write a linear procedure like the
one shown in Figure 16 on page 48, which includes on the REPORT panel a
message defined by the MESSAGE command. To have your message appear on

the REPORT panel, place the MESSAGE command immediately before the
INTERACT command, as shown in Figure 16:
..
.
RUN QUERY WEEKLY_SALES_Q (FORM=WEEKLY_SALES_F
MESSAGE (TEXT=’OK, press END when you are finished viewing this report.’
INTERACT
RUN QUERY YEAR_TOTAL_Q (FORM=YEAR_TOTAL_F
..
.
Figure 16. Example of using the MESSAGE command
If you are using a procedure with logic, you can use a REXX variable in place of
the text string you specify for the MESSAGE command, as shown in Figure 17.
When you use REXX variables, you must use double quotes around the variable
name in the message text string.
oktext = ’OK, press END when you are finished viewing this report.’
"MESSAGE (TEXT=’"oktext"’"
"INTERACT"
"RUN QUERY YEAR_TOTAL_Q (FORM=YEAR_TOTAL_F"
Figure 17. Using REXX variables with the MESSAGE command in a procedure
Example of issuing a message from a QMF REXX procedure
The message shown below spans multiple lines with REXX continuation characters.
(For more information about issuing messages in REXX procedures, see the REXX
documentation in the IBM Publications Center at www.ibm.com/shop/publications/
order.)
/* QMF REXX PROCEDURE */
MSGTEXT="You entered a data value incompatible with "||,
"the column data type; check the data type of the "||,
"column and try again.""MESSAGE(TEXT=("MSGTEXT"))"/*MAXTEXT=360PARANS*/EXIT
Example of issuing a QMF MESSAGE command from a linear QMF procedure
The message shown below spans multiple lines using continuation characters for
linear procedures:
MESSAGE(TEXT=’You entered a data value incompatible with
+the column data type; check the data type of the
+column and try again.’)
Examples of MESSAGE commands with ISPF available
The following are examples of how you can use the MESSAGE command if you are
building an application that makes use of ISPF:
v MESSAGE MSG011X
– The message text is the long message in MSG011X.
– The message help panel is the panel identified (if any) in MSG011X.

– Whether the procedure termination switch is set after QMF processes the
command is determined by the procedure termination switch in MSG011X.
v MESSAGE MSG011X (HELP=PANELX STOPPROC=YES
– The message text is the long message in MSG011X.
– The message help panel is a panel named PANELX.
– The procedure termination switch is turned on, which suppresses the
execution of QMF linear procedures in the application.
SET GLOBAL
You can create your own global variables with the SET GLOBAL command and use
them in QMF commands as substitution variables. You can use your own global
variables, or you can use the ones QMF provides. For a list of the QMF-provided
global variables, see Appendix C, “QMF global variable tables,” on page 197.
To set a global variable for a procedure, do one of the following:

v Set the variable on the SHOW GLOBALS panel.
The variable name can be up to 18 characters long, and the length of the value
can be up to 32,768 characters.
v Use the linear syntax of the SET GLOBAL command in your procedure, on the
command line, or on the SET GLOBAL prompt panel. See DB2 QMF Reference
for more information on the linear syntax for this command.
v Use extended syntax to change the values of variables in a callable interface
application written in a language other than REXX (Assembler, C, COBOL,
FORTRAN, or PL/I).
SET GLOBAL (extended syntax)

The extended syntax of the SET GLOBAL command is used with callable interface
languages other than REXX. The maximum length of a variable name used with the
extended syntax of the SET GLOBAL command is 17 characters. The maximum
length of a variable value is 32,768 characters.
The syntax of the command is as follows:
SET GLOBAL ( Variable definitions
Variable definitions:
number of varnames , varname lengths , varnames ,
number of varnames
The number of variables requested.
varname lengths
A list of lengths for each variable name specified.
The length of the global variable name should be equal to the actual length of
the global name in your program. An 18-character area padded with trailing
blanks is allowed.

varnames
A list of names of the QMF variables.
value lengths
A list of lengths of the values of the variables. If the value length you supply is
less than the length of the value stored in your storage area, the value is
truncated on the right when it is stored in QMF.
QMF uses the value from your program, starting at the address you assign for
the length you assign. If the length is too long, QMF might abend.
values
A list of variable values.
value type
The data type of the storage area that contains the values. It must be either
character or integer.
For examples of how to use the extended syntax of the SET GLOBAL command,
see Appendix A, “Sample code for callable interface languages,” on page 125 for
the sample program for the language you are using.
Guidelines for defining and using global variables

When you are defining and using global variable names, keep the following rules in
mind:
v On the SET GLOBAL command, variable names are not preceded with an
ampersand as they are on the RUN and CONVERT commands.
v If you create a global variable with the same name as a form variable or
aggregation variable, QMF uses the form variable (or aggregation variable) value
in the form rather than the global variable value.
v The QMF form does not recognize global variables with question marks in the
names.
v Global variable names are limited to 17 characters when entered on the
command line and 18 characters when entered through the callable interface.
However, due to limitations of the SET GLOBAL command, you should use
17-character names.
v A global variable name can contain numeric characters, but the first character of
a global variable name cannot be numeric.
v Global variable names cannot begin with DSQ because QMF reserves these
letters for QMF predefined global variables.
v The first character of a global variable name must be an alphabetic character (A
through Z) or one of these special characters:
¢ ! $ ~ { } ? @ # % \
v A global variable name cannot contain blanks or any of the following characters:
* ( ) − + ¬ | : ; " ' < > / . , = &

v QMF strips trailing blanks from global variable names.
START
This topic contains information about the START command syntax and keywords,
including a table of keyword descriptions.

General syntax
When you start QMF through the callable interface, you need to use the START
command. The syntax of the START command depends on which programming
language you are using for your callable interface application; see Appendix A,
“Sample code for callable interface languages,” on page 125 for examples of the
syntax for each programming language.
Only one QMF session can be active at one time. If you want your application to
test whether QMF has already been started, see “Starting QMF from an application”
on page 21.
The following is the general syntax for the START command:
START ( Keyword definitions
Keyword definitions:
number of keywords , keyword lengths , keywords ,
Assembler, C, COBOL, FORTRAN, and PL/I use the following specifications for the
START command:
number of keywords
The number of START command keywords you are using in your START
command.
keyword lengths
The length of each START command keyword specified.
keywords
Names of the START command keywords. See “START command keywords”
for more information.
value lengths
A list that contains the lengths of the values for each START command
keyword.
values
A list of values for the START command keywords specified in this command.
value type
The data type of the value. The data type must be character for the START
command.
START command keywords

You can specify any of the following keywords on the START command:
v DSQADPAN
v DSQALANG
v DSQSBSTG
v DSQSCMD (TSO only)
v DSQSDBCS

v DSQSDBNM
v DSQSDBQN (CICS only)
v DSQSDBQT (CICS only)
v DSQSDBUG
v DSQSIROW
v DSQSMODE
| v DSQSMRFI
v DSQSPILL
v DSQSPLAN (TSO only)
v DSQSPRID (TSO only)
v DSQSRSTG (TSO only)
v DSQSRUN
v DSQSSPQN (CICS only)
v DSQSSUBS (TSO only)
These keywords are described in Table 8.
QMF allows you to specify START command keywords with the following
conventions:
v You can specify any keyword on the START command. In TSO, you can also
specify any keyword in the REXX program named by the DSQSCMD keyword.
Because QMF for CICS does not support REXX, you must specify all keywords
on the START command.
v If your application or the initial procedure (specified by the DSQSRUN keyword)
specifies keywords that are not supported in a particular environment, those
keywords are ignored. This allows you to compile a single program to run in
multiple QMF environments without changing the environment-specific keywords.
v If you do not specify any keywords, QMF uses the values of the START
command keywords as they appear in the program specified by the DSQSCMD
keyword. If you do not use this program, QMF uses the default values of each
keyword shown in Table 8.
For more information about these keywords and how they are affected by
environmental dependencies, see Installing and Managing DB2 QMF for TSO/CICS.
For syntax diagrams of the START command, see DB2 QMF Reference.
Table 8. START command keywords, descriptions, and default values
START command
keywords Description Default value
DSQADPAN Meant for use only with the callable interface, this START command 1 (display report)
parameter sets the DSQDC_DISPLAY_RPT global variable. This
variable controls whether QMF displays the report when a query is
run from within an application program. A value of 1 displays the
report when a query is run. Set the value to 0 to specify that the
report should not be displayed.

Table 8. START command keywords, descriptions, and default values (continued)

START command
DSQALANG Determines the presiding national language for the session you are E (English)
starting. After the national language feature for the language is
installed (see Installing and Managing DB2 QMF for TSO/CICS for
more information), you can specify this parameter in your
applications so that users can enter or specify QMF commands in
that national language. The value for this parameter is a
one-character national language identifier, shown below. If you want
to enter English commands when the presiding language is a
language other than English, you can use QMF bilingual support
(see Chapter 7, “Writing bilingual applications,” on page 35).
C – Canadian French
D – German
E – English
F – French
H – Korean (Hangeul)
I – Italian
K – Japanese (Kanji)
P – Brazilian Portuguese
Q – Danish
S – Spanish
U – Uppercase English
V – Swedish
Y – Swiss French
Z – Swiss German
DSQSBSTG Note to CICS users: DSQSBSTG is always used for CICS; In CICS: 500,000 bytes
DSQSRSTG is never used for CICS.
In TSO: 0 bytes
This keyword provides QMF with a fixed maximum amount of
storage (in bytes) available for report generation. It is a positive
whole number ranging in value from 0 through 99,999,999. If you are
using TSO and set the DSQSBSTG parameter to 0, this parameter is
not used; instead, DSQSRSTG is used, which dynamically allocates
report storage in TSO. If you are using TSO and you specify values
for both DSQSBSTG and DSQSRSTG, QMF ignores the value for
DSQSRSTG.
If you set the DSQSBSTG value to less than the minimum amount of
storage required to produce a report, QMF automatically allocates
the minimum amount of storage required. The minimum amount
required to produce a report depends on your environment.


START command
DSQSCMD Note to CICS users: QMF for CICS does not support REXX; DSQSCMDE
(TSO only) therefore, the DSQSCMD keyword is not supported under CICS. If
you start QMF using the callable interface under CICS and you want
to set the QMF program parameters, you must specify the keywords
on the START command.
This keyword specifies the REXX program that sets the QMF
program parameters.
When QMF receives the START command from a callable interface

application, QMF calls the REXX program specified by this keyword.
This REXX program provides values for the QMF program
parameters unless you have specified their values directly on the
START command. The default program provided with QMF is
DSQSCMDE (which is a program written for the English language). If
you are using an NLF, you can change this default to DSQSCMDn,
where n is the national language identifier (NLID) for the language
you are using. (Table 1 on page vii lists the NLIDs for each
language.)
DSQSDBCS Determines whether QMF allows double-byte characters when the NO
display device does not support the double-byte character set
(DBCS). Values are YES or NO.
You should set the value to YES when you intend to print DBCS data
from a non-DBCS display device or run a QMF batch job that prints
DBCS data. Otherwise, the value should be NO.
DSQSDBNM Specifies the remote server to connect to when starting a QMF NULL
session. A null value means that QMF connects to the default
database (the database it normally connects to without remote unit of
work).
DSQSDBQN Specifies that CICS storage is used for QMF trace data. The name DSQD
(CICS only) must conform to CICS name specifications for the type of CICS
queue specified by DSQSDBQT. For more information about CICS
name specifications, see the appropriate CICS application
programming guide. The IBM Publications Center at
www.ibm.com/shop/publications/order contains the CICS publications.
DSQSDBQT Specifies the type of CICS storage to be used for QMF trace data. TD
(CICS only)
The values are:
TD Uses a CICS transient data queue.
TS Use a CICS auxiliary temporary storage queue. Use caution
when specifying temporary storage, because QMF can
generate a large amount of trace data.


START command
DSQSDBUG Specifies whether product activity is traced during QMF initialization. NONE
The values are:
ALL Specifies the most detailed QMF tracing.
NONE Specifies no QMF tracing.
When you start QMF in batch mode, all messages and commands
are traced (equivalent to an L2 level of tracing) regardless of how
you set DSQSDBUG.
For more information on function-level tracing, see DB2 QMF

Reference or Installing and Managing DB2 QMF for TSO/CICS.
DSQSIROW Indicates the number of rows QMF fetches before displaying the first 100
screen of data for a RUN QUERY, IMPORT DATA, or DISPLAY
command.
DSQSMODE Tells QMF which mode you want to work in. B (batch)
I Specifies interactive mode.
B Specifies batch mode.
When the value of DSQSMODE is B, panel display is inhibited so

that QMF can run as a background job.
| DSQSMRFI Specifies whether the QMF session you are starting will use DB2 NO
| multi-row fetch and insert. DB2 multi-row fetch and insert increases
| performance for many QMF commands (such as DISPLAY TABLE,
| EXPORT DATA or EXPORT TABLE, IMPORT TABLE, PRINT DATA
| or PRINT TABLE, RUN QUERY or RUN PROC (when these
| commands retrieve data), SAVE DATA, DPRE, and BOTTOM or
| FORWARD when navigating reports).
| YES Specifies that QMF will use DB2 multi-row fetch and insert.
| Before you set this parameter to YES, ensure that both the
| database server and requester are DB2 for z/OS Version
| 8.1.5 (New Function Mode) or higher. If you specify
| MR=YES and the server or requester is not DB2 for z/OS
| Version 8.1.5 NFM or higher or the command requires XML
| data to be processed, QMF uses single-row processing.
| Also, when you use a QMF command that references a
| 3-part name, the server referenced in the location qualifier
| of the 3-part name must be DB2 for z/OS NFM Version
| 8.1.5 (or higher) or the command fails.
| NO Specifies that QMF will not take advantage of DB2 multi-row
| fetch and insert capabilities.
DSQSPILL Specifies whether QMF uses a spill file when extra storage for For CICS: NO
reports is needed. Possible values are YES or NO. If you are using
CICS, see the explanation of the DSQSSPQN keyword for how to For TSO: YES
name the temporary storage queue that holds spill data.
DSQSPLAN Specifies the DB2 application plan ID assigned to QMF. QMF910
(TSO only)
DSQSPRID Specifies whether to use the TSO logon ID or the primary database PRIMEID
(TSO only) authorization ID to select the appropriate row from Q.PROFILES and
to qualify Q.ERROR_LOG entries. Allowable values are PRIMEID or
TSOID.


START command
DSQSRSTG Dynamically allocates virtual storage available for reports. You can Zero (0)
(TSO only) use the DSQSBSTG keyword to set a fixed maximum amount of
storage, in which case QMF ignores the DSQSRSTG value.
DSQSRUN Specifies the name of the QMF initial procedure to run after QMF is NULL
started. The initial procedure runs only once with the callable
interface.
In this procedure, you can include commands to set global variables

and profile variables to customize the user’s session.
DSQSSPQN Specifies the name of the CICS temporary storage queue that is DSQSid, where id is the
(CICS only) used for QMF spill data. When the program parameter DSQSPILL CICS terminal ID
has a value of YES, this spill area is used to contain report data.
DSQSSUBS Specifies the ID of the DB2 server your program will use. The DSN
(TSO only) database ID you specify on this keyword must be configured as an
application requester according to the instructions in Installing and
Managing DB2 QMF for TSO/CICS. A full QMF installation on this
server is not necessary.
Using command synonyms

QMF lets you create command synonyms, which are commands that resemble
QMF commands. Command synonyms give you a lot of flexibility, and they are
extremely useful for end users. For example, command synonyms perform the
function of a command or start an application. To enable QMF users to access your
command synonyms, you must enter your command synonyms into one or more
command synonym tables. When a user issues a command synonym, QMF runs a
TSO, RUN, or CICS command that starts the user’s application.
Creating a command synonym

To create a command synonym:
1. Create a descriptive command.
QMF commands follow the verb object format. Every command is a verb (action
word) and many commands also have an object (descriptive noun) following
them. For example, END is a verb-only command, while CONVERT QUERY is
a verb-object command.
You can create command synonyms with verbs that are identical to existing
QMF commands. If you do, you can still use the original QMF command by
preceding it with the command QMF. See DB2 QMF Reference for information on
this command.
For example, suppose your procedure runs a report to see if the weekly sales
figures have been entered. If the data for the current week is missing, the
procedure calls the Table Editor to add the latest information to the table.
Regardless of what you named the procedure, you want the command synonym
to be descriptive for the user. You could choose a verb-object pair like UPDATE
SALES.
If your command synonym needs parameters or options, you can use the
substitution variable &ALL to provide these parameters or options. See Installing
and Managing DB2 QMF for TSO/CICS for more information about this variable.
2. Update the appropriate command synonym table with your new command
synonym.
You need to know the name of the command synonym table you want to use.
The variable DSQAP_SYNONYM_TBL contains the name of the command
synonym table for each user. This variable initializes with the proper value at
startup time, when QMF reads the user's row of the Q.PROFILES table.
Your database administrator has access to the command synonym table. If you
want to create a command synonym for your personal use, you might want to
have a view defined on those tables that lets you add command synonyms.
In the example shown in Figure 18, the Q.COMMAND SYNONYMS table
contains information for the command synonym UPDATE SALES:
ADD Q.COMMAND_SYNONYMS
VERB. . . . . . . . . ( UPDATE )
OBJECT. . . . . . . . ( SALES )
SYNONYM_DEFINITION. . ( RUN PROC WEEKLY_SALES >
REMARKS . . . . . . . ( checks weekly sales figures>
Figure 18. Creating a new command synonym in the Q.COMMAND_SYNONYMS table
After you press the ADD function key, QMF adds this command synonym to
your table.
3. Update your profile, if necessary.
If you added this command synonym to a new table or view, add the name of
the new table or view to your profile.
4. End your QMF session.
QMF does not recognize the changes you made to your command synonym
and profile tables until you start a new QMF session.
RUN QUERY report minisession

When you write applications that produce QMF reports, you can limit users’ access
to QMF by using report minisessions. In a report minisession, QMF limits the
commands that a user can issue while viewing a report. Valid and invalid
commands for a report minisession are explained later in this topic.
A report minisession behaves as a nested session (a session within a session). In

minisessions, your initial QMF session remains intact, but becomes temporarily
unavailable while you are viewing a report. The minisession becomes your current,
active session until you issue the END command (or press the End function key).
When you end a minisession, you either return to the initial QMF session or to the
calling application, depending on how you write the application. The application
cannot continue to issue subsequent commands until the report minisession has
ended.
The QMF global variable DSQDC_DISPLAY_RPT, in effect, determines whether

QMF starts a report minisession. This is because DSQDC_DISPLAY_RPT
determines whether QMF displays a report after running a query (set this variable to
1 to display the report, 0 to suppress display).
When you start QMF using the callable interface:

v The default value for global variable DSQDC_DISPLAY_RPT is 1. (When QMF is

started with DSQQMFn (where "n" is the national language identifier from Table 1
on page vii) – whether interactively or in batch mode – the default value of this
global variable is 0).
v If you run a procedure or an application that runs a query, QMF starts a report
minisession; it is in this minisession that QMF displays the report resulting from
the query.
v If your procedure or application does not run a query, or if you run a query from
the SQL QUERY panel, QMF does not start a report minisession.
If you do not want QMF to start a report minisession, do one of the following:
v Change the value of DSQDC_DISPLAY_RPT to 0.
v Set the DSQADPAN parameter to 0 when you start QMF from the callable
interface.
See “SET GLOBAL” on page 49 for more information about global variables.
From a report minisession, you can issue the following commands and synonyms
for those commands (restrictions shown in parentheses):
v BACKWARD
v BOTTOM
v CANCEL (when pop-up window is active)
v CICS
v DISPLAY REPORT
v DISPLAY CHART
v END
v FORWARD
v GET GLOBAL
v HELP
v INTERACT
v ISPF
v LEFT
v MESSAGE
v PRINT REPORT
v PRINT CHART
v QMF
v RETRIEVE
v RIGHT
v SAVE DATA
v SET PROFILE
v SET GLOBAL
v SHOW REPORT
v SHOW CHART
v SWITCH (when online help is active)
v TOP
v TSO
The following are commands that are not valid in a minisession:

v ADD
v CANCEL
v CHANGE
v CHECK
v CLEAR
v CONNECT
v CONVERT
v DELETE
v DESCRIBE
v DISPLAY (Query, Proc, Profile, Form)
v DRAW
v EDIT
v ENLARGE
v ERASE
v EXIT
v EXPORT
v EXTRACT
v GETQMF
v IMPORT
v INSERT
v INTERACT
v LIST
v NEXT
v PREVIOUS
v PRINT (Query, Proc, Profile, Form)
v REDUCE
v REFRESH
v RESET GLOBAL
v RESET (Query, Proc, Form)
v RUN
v SAVE
v SEARCH
v SHOW
v SORT
v SPECIFY
v START
v SWITCH
QMF returns an error message when you run a CLIST or a procedure that issues a
restricted command.

Chapter 9. Exporting and importing objects
You can write applications that issue QMF EXPORT and IMPORT commands to
place objects outside of the QMF environment. Your applications can export tables
as well as the following QMF objects:
v DATA
v QUERY
v PROC
v FORM
v REPORT
v CHART
| When you export an object, QMF converts the object to an externalized format and
| places it in a UNIX® file (in the case of data or tables only), a TSO data set, or a
| CICS data queue. The externalized format of QMF objects is a powerful element of
| QMF application development. The IMPORT command reads the externalized
format and places the object either in QMF temporary storage or in the database
(depending on how you issue the command).
| You can export data and table objects in either the QMF, IXF, or XML format. Form,
| prompted query, and report objects are exported in encoded format. Charts are
| exported in Graphics Data Format (GDF), a GDDM format.
The following topics explain how to export and import objects:

v “What you can do with an exported UNIX file, TSO data set, or CICS data
queue”
v “Exporting versus saving data” on page 62
v “Exporting data objects and database tables” on page 62
v “Exporting forms, reports, and prompted queries” on page 82
v “Importing forms and prompted queries” on page 115
v “Procedures and SQL queries” on page 116
v “Charts” on page 116
v “Exporting QBE queries” on page 117
v “Size specifications for externalized QMF objects” on page 117
v “Storage considerations” on page 118
| For the syntax of the EXPORT and IMPORT commands as well as restrictions for
| certain data types, see DB2 QMF Reference.
What you can do with an exported UNIX file, TSO data set, or CICS
data queue
The IMPORT and EXPORT commands let you:
v Provide query results to your application
Use the QMF EXPORT command to get data out of the database and into your
application.
v Create objects within your application and use them in QMF

Exporting and importing objects
| You can create an object outside of the QMF environment using the appropriate
| format for the object. When you import into QMF the UNIX file (in the case of
| data or tables only), TSO data set, or CICS data queue containing the object, a
| new QMF object is created.
You cannot import reports and charts into QMF.
v Make QMF objects available to other environments or products.
Caution
Use caution when transferring exported objects between systems with
different CCSIDs or character sets, such as between EBCDIC and ASCII
systems, or between different NLF environments. Transferring the objects
between systems in this way could render them unusable.
If you need to import a prompted or QBE query into a program other than QMF,
you must first use the CONVERT QUERY command to convert the query to an
SQL query that you can export and use in other products. For more information
on the CONVERT command, see DB2 QMF Reference.
You can transfer QMF objects between QMF under TSO, ISPF, or native z/OS
batch and QMF under CICS (using CICS extrapartition transient data queues).
v Save objects and data outside of the database.
For example, in the middle of a program, you can export your data so that an
external program can manipulate it.
v Create bilingual applications
You can create a QMF form in your presiding language and translate it to English
using the LANGUAGE option on the EXPORT command. You can also use the
LANGUAGE option on the IMPORT and EXPORT commands to translate an English
form to your presiding language.
Exporting versus saving data

The difference between the EXPORT DATA and SAVE DATA commands is in where
and how the object is stored. This affects what you can do with the results:
| v Exporting a data object produces a UNIX file, TSO data set, or CICS data queue.
| You can read, modify, or print each item sequentially through QMF application
| programs or other external applications.
v The SAVE DATA command produces a database table. Whatever actions you
perform using saved data must be done through the database.
Exporting data objects and database tables

When you run a query, QMF displays the result in a report. The raw data for the
report is stored in a temporary storage area as a data object. Relational tables and
views stored in the database are referred to as table objects.
You can export data and table objects to storage areas external to QMF. The
exported formats of a table in temporary storage (DATA) and a table stored in the
database (TABLE) are identical. An object exported as data can be imported as a
table, and vice-versa.
| Data and table objects can be exported in QMF format (by specifying
| DATAFORMAT=QMF on the EXPORT command), Integrated Exchange Format (by

| specifying DATAFORMAT=IXF on the EXPORT command), or XML format (by

| specifying DATAFORMAT=XML on the EXPORT command). The QMF format is the
default.
The following topics provide more information on each format:

v “Exporting data or tables in QMF format”
v “Exporting data or tables in IXF format” on page 67
v “Exporting data or tables in XML format” on page 78
| You can create your own tables outside of QMF by using the QMF, IXF, or XML
| format and importing the contents of the UNIX file, TSO data set, or CICS data
| queue that contains the table. Include the required fields and add your own data as
| appropriate. Then import the UNIX file, TSO data set, or CICS data queue into QMF
| as a table object.
For more information and syntax of the EXPORT and IMPORT commands, see
DB2 QMF Reference.
Exporting data or tables in QMF format

The data file that you export using the EXPORT command with the
DATAFORMAT=QMF clause consists of two parts: header records, which describe
the data in the records, and the data records, which contain the data.
Header records
The record length of an external data file is the length of a row of the data, as
described under “Data records” on page 64. The header records that precede the
data records are the same length as the data records. If the header information
exceeds the length of the data record, multiple header records are written. Table 9
shows the information contained in the header records.
Table 9. Header record information
Byte position Information and type
1-8 QMF object format level (8 characters of data).
The object level for QMF Version 8.1 and later is 3.0, so these byte
positions say "REL 3.0" for QMF Version 8.1 and later. Data exported
using QMF Version 8.1 or higher cannot be imported to earlier releases
of QMF.
9-10 Number of header records (halfword signed integer).
11-12 Number of data columns (halfword signed integer).
13-30, 37-54, ... Column name (30 characters of data).
31-32, 55-56, ... Data type (halfword signed integer). Data type codes are shown in
Table 10 on page 64.
33-34, 57-58, ... Column width (halfword signed integer); for most data types this is the
width of the column in bytes, with the following exceptions:
v In DECIMAL columns, the first byte of the halfword represents the
precision, and the second byte represents the scale.
v In GRAPHIC and VARGRAPHIC columns, this value reflects the width
of double-byte characters.
v In FLOAT columns, this value is either 4, indicating single-precision
floating point, or 8, indicating double-precision floating point.
35, 59, ... Nulls allowed: Y if nulls are allowed; N if they are not allowed (1
character of data).
Chapter 9. Exporting and importing objects 63

Table 9. Header record information (continued)

36, 60, ... Unused byte.
Bytes 11-12 indicate the number of columns; this means that the information in
bytes 13 through 36 is repeated for each column in the header. Each column
requires 24 bytes in the header.
The data type codes are shown in Table 10.

Table 10. Data type codes
Code in
hexadecimal Code in decimal Data type Meaning
X'180' 384 DATE Date
X'184' 388 TIME Time
X'188' 392 TIMESTAMP Timestamp
X'1C0' 448 VARCHAR Varying-length
character
X'1C4' 452 CHAR Fixed-length character
X'1D0' 464 VARGRAPHIC Varying-length graphic
X'1D4' 468 GRAPHIC Fixed-length graphic
X'1E0' 480 FLOAT Floating point
X'1E4' 484 DECIMAL Decimal
| X'1EC' 492 BIGINT Big integer
X'1F0' 496 INTEGER Integer
X'1F4' 500 SMALLINT Small integer
| X'38C' 908 VARBINARY Varying-length binary
| X'390' 912 BINARY Fixed-length binary
Date, time, and timestamp data are always exported in ISO format.
Data records
Data records are of fixed-length format and contain the data to be exported. The
maximum allowable length of a data record is 7,000 bytes. The length of a data
record is the sum of the widths of the data types that comprise the record. Use
Table 11 to calculate the widths of each data type.
Table 11. Widths of data records. Calculate the width of a particular data type by adding the
number of bytes in each column.
Null Length
Data type indicator field SO/SI Data
Character 2 Length in header (LIH)
Date 2 LIH
Floating point 2 8
| Big integer 2 LIH
Integer 2 LIH
Small integer 2 LIH

Table 11. Widths of data records (continued). Calculate the width of a particular data type by
adding the number of bytes in each column.
Null Length
Data type indicator field SO/SI Data
Time 2 LIH
Timestamp 2 LIH
Decimal 2 (Precision + 2) // 2
Graphic 2 2 (LIH × 2)
Variable character 2 2 LIH
Variable graphic 2 2 2 (2 × LIH)
| Binary 2 LIH
| Variable binary 2 2 LIH
Note: The LIH is the width given in the header record for that column.
Every data record has two bytes of indicator information, which can have the values
and meanings shown in Table 12:
Table 12. Hex values that show the validity of data records
Value Meaning
X'0000' The column contains valid data.
X'FFFF' or The column contains a null value; any data in the column is meaningless.
X'FFFE'
Interpreting a data object in QMF format

You can calculate the length of the header record when you have the length of the
data records. In this example, each data record is 23 bytes long. Table 9 on page
63 shows that the first 12 bytes contain level and number information. There are 24
bytes for each column of data, and there are three columns. Thus, for this
three-column data object, the header is 84 bytes:
(12 + (24 X 3) = 84).
For example, suppose you export the following data from the Q.STAFF table:
ID NAME COMM
------ --------- ----------
10 SANDERS -
20 PERNAL 612.45
Calculate the widths of each column as shown in Table 13:

Table 13. Calculating column widths
Column width (length in
Column name Data type header) Width of column
ID SMALLINT 2 2+2=4
NAME VARCHAR 9 2 + 2 + 9 = 13
COMM DECIMAL (7,2) 7 (7 + 1)/2 + 2 = 6
Length of data record: 23

Each header record is the same length as the data records: 23 bytes. The 84 bytes
are spread across four 23-byte header records; the last record is padded with
blanks.
Figure 19 shows the header from the report and its hexadecimal representation.
The reversed-type numbers indicate notes following the figure.
R E L 3 . 0 I D
1 D9 C5 D3 40 F1 4B F0 40 0004 0003 C9 C4 40 40 40 40 40 40 40 40 40
1 2 3 4
N N A M E
2 40 40 40 40 40 40 40 01F4 0002 D5 00 D5 C1 D4 C5 40 40 40 40 40 40
5 6 7
Y C O M M
3 40 40 40 40 40 40 40 40 01C0 0009 E8 00 C3 D6 D4 D4 40 40 40 40 40
Y
4 40 40 40 40 40 40 40 40 40 01E4 07 02 E8 00 40 40 40 40 40 40 40
Figure 19. Sample header records for an exported data object in QMF format. 40 is the
hexadecimal code for a blank character.
Figure 20 shows the data from the report and the hexadecimal representation of
that data. For information about what the byte positions mean, see Table 9 on page
63.
10 S A N D E R S
1 00 00 00 0A 00 00 00 07 E2 C1 D5 C4 C5 D9 E2 00 00 FF FF 00 00 00 40 40
8 9 10
20 P E R N A L
2 00 00 00 14 00 00 00 06 D7 C5 D9 D5 C1 D3 00 00 00 00 00 00 61 24 5C
Figure 20. Sample data records for an exported data object in QMF format
| 1 REL 3.0

| Object format level: 3.0
The object format level tells QMF which version of the object format this
object is using. Every time a QMF object format is changed, the level
number is changed; object formats are not changed with every new release.
2 X’0004’
Number of header records: 4
3 X’0003’
Number of data columns: 3
4 X’C9 C4’
Column name: ID
5 X’1F4’
Data type: SMALLINT
6 X’0002’
Column width: 2
7 X’D5’
Nulls allowed: N signifies no
8 X’0A’
Value for the first column of the first data record: 10
9 X’07’
Length of the name in the second column of the first data record: 7
10 X’FFFF’
Indicator information: column contains a null value
Exporting data or tables in IXF format

When you use the EXPORT command to export a DATA or TABLE object using the
DATAFORMAT=IXF option, the data is exported into a TSO data set or CICS data
queue in the Integrated Exchange Format (IXF). QMF supports a subset of IXF,
which is described in this topic.
The data set or data queue containing the exported data or table consists of the
following records:
v Header record (H)
v Table record (T)
v Column records (C)
v Data records (D)
The exported data set or CICS data queue consists of one H record, followed by
one T record. The T record contains a count of how many C records follow the T
record. There is a C record for each column in the table. D records follow C
records. There is a D record for each row in the table. The arrangement of records
looks like Figure 21.
Figure 21. Arrangement of records in an exported data set or CICS data queue (IXF format)
The following topics describe the format of each of these types of records. The
values shown in parentheses appear in the exported output to identify each type of
record.
v “Header record (H)”
v “Table record (T)” on page 68
v “Column records (C)” on page 69
v “Data records (D)” on page 70
v “Column data format” on page 70
v “Format of column data by data type” on page 71
v “Interpreting an object exported in IXF format” on page 75
Header record (H)

A header record (which is mandatory) is the first record in the data set or CICS data
queue. It is a 42-byte record containing character data. The format of the H record
is shown in Table 14:
Table 14. Parts of a header record in an IXF data set or data queue containing an exported
data object or database table
Byte
position Information and type
01 Header record indicator (H).

Table 14. Parts of a header record in an IXF data set or data queue containing an exported
data object or database table (continued)
Byte
02-04 TSO data set or CICS data queue identifier.
05-08 IXF version; the version can be one of the following:
v 0000, which supports data objects that contain short column names (18
characters or less).
v 0001, which supports data objects that contain at least one long column
name (19 characters or more).
09-14 Originating product name (QMF).
| 15-20 Originating product release level (V9R1M0).
21-28 Date the data set or CICS data queue was created, in the form
YYYYMMDD.
29-34 Time the data set or CICS data queue was created, in the form HHMMSS.
35-39 The number of records preceding the first D (Data) record in the data set or
CICS data queue; this is a 5-digit numeric value expressed in character
form.
40 DBCS indicator that tells whether DBCS data is a possibility; Y or N.
41-42 Reserved.
Table record (T)

A table record follows the header record. Each IXF data set or data queue must
have a T record. A table record contains table and data information concerning the
file, data set, or CICS data queue being exported using the QMF EXPORT TABLE
command. However, when exporting a QMF data object that was the result of a
RUN QUERY command, the table record contains a blank owner and name. For
long names, the table name is truncated at 18 characters and the owner name is
truncated at 8 characters.
The format of a T record is shown in Table 15:

Table 15. Parts of a table record in an IXF data set or data queue containing an exported
data object or database table
Byte
01 Table record indicator (T).
02-03 Data name length (18).
04-21 Name of the table from which data is retrieved; left-justified, padded with
blanks to the right.
The entire 18-byte field is blank if the table does not have a name.
22-29 Data name qualifier; name of the owner of the database table from which
the data is retrieved.
The 8-byte field is blank if the table does not have an owner.
30-41 Data source (database).
42 Convention used to describe data: C for columnar data.
43 Data format: C for character (OUTPUTMODE=CHARACTER); M for
machine (OUTPUTMODE=BINARY).

Table 15. Parts of a table record in an IXF data set or data queue containing an exported
data object or database table (continued)
Byte
44 Data location: I for internal.
45-49 Count of column (C) records: a numeric value in character form specifying
the number of C records before the first data (D) record.
50-51 Reserved.
52-81 Blanks.
Column records (C)

In QMF Version 8.1 or higher, the column name field in the column record must be
increased from 18 to 30 characters when a column name longer than 18 characters
exists. When there is a column name longer than 18 characters, the IXF version
number in the header record is set to 0001. If there are no column names longer
than 18 characters, the older IXF format that is compatible with releases of QMF
prior to Version 8.1 is used. In these instances, the IXF version number in the
header record is 0000.
A column record describes the data characteristics of the column. There is a

column record for each column in the table. The format of a column record is
shown in Table 16:
Table 16. Format of a column record in an IXF data set or data queue containing an exported
data object or table
Byte
01 Column record indicator (C).
02–03 Column name length.
04–21 Column name, as obtained from the database or generated by QMF (in
the case where the column did not originally have a name).
The name is left-justified, and padded with blanks to the right if

necessary.
22 or 34 Indicator that tells if nulls are allowed; Y or N.
23 or 35 Column selected indicator (Y).
24 or 36 Key column indicator (Y).
25 or 37 Data class (R).
26–28 or 38-40 Data type (see Table 18 on page 71 for data type codes).
29–33 or 41-45 Code page.
34–38 or 46-50 Reserved.
39–43 or 51-55 Column data length; a numeric value in character form.
| If the data type is DECIMAL, the first 3 bytes represent data precision
| and the next 2 bytes represent the scale. If the data type is BIGINT,
| INTEGER, SMALLINT, DATE, TIME, or TIMESTAMP, this field is blank
| (length is inherent in data type).

Table 16. Format of a column record in an IXF data set or data queue containing an exported
data object or table (continued)
Byte
44–49 or 56-61 Starting position of column data; a value (in character form) reflecting
the offset of the data for a column from the start of the data record.
If the column allows nulls, this field points to the null indicator. If the
column does not allow nulls, it points to the data itself. Whether or not
the column allows nulls, space for the null indicator is always present in
the record. The starting position is based from the first byte that contains
data. Therefore, the first five bytes of the data (D) record are not
included in any consideration for starting position of the actual data.
(The first data position is position 1, not position 0.)
50–79 or 62-91 Column label information, if available (if not available, these byte
positions contain blanks).
80–81 or 92-93 Two bytes of zeros in character form (00).
Data records (D)

There is a data record for each row in the table. Table 17 shows the format of a
data record:
Table 17. Format of a data record in an IXF data set or data queue containing an exported
data object or table
Byte
01 Data record indicator (D).
02–04 Reserved.
05 Blank.
06–end of Row data in binary or character form, depending on whether byte 43 of the
record table record is M (machine) or C (character). Byte 6 represents the start
(position 1) of row data for the first column.
Column data format

Data in D records for n columns is placed side by side, as shown in Figure 22:
Figure 22. Format of column data in D records
For each column, the data consists of a null indicator followed by the data itself. If
nulls are allowed (byte 22 of C record = Y), then bytes 44–49 of each C record
point to the null indicator that precedes the data for that column. If byte 22 = N
(nulls not allowed), then bytes 44–49 point to the data itself. However, in the latter
case, space for the null indicator is left in the data record. The first position in bytes
44–49 is represented by a value of 1, which points to byte 6 of a D record (bytes 1
through 5 are ignored).
The representation of the null indicator depends on what is specified for

OUTPUTMODE: character or binary. OUTPUTMODE is reflected in byte 43 of the T
record: C for character or M for machine (binary). When data format is character,
one byte is used for the null indicator:

v A dash (–) indicates data is null

v A blank indicates data is not null
See Figure 24 on page 77 (which shows character output mode) and Figure 26 on
page 78 (which shows binary output mode) for an illustration of two D records
showing data that is null in one case and not null in the other.
When the data format is binary, two bytes are used for the null indicator:
v X'FFFF' indicates data is null
v X'0000' indicates data is not null
Format of column data by data type

Table 18 shows the length and format of column data in D records for each data
type for both character and binary formats. In the table, IXFCLENG refers to the
contents of bytes 39–43 of a C record (length of column data).
Table 18. Format of IXF column data by data type
Data type Data length information Data length information
code Data type (character format) (binary format)
384 DATE The value in IXFCLENG is not Same as character format.
significant for this data type. The
length (10 bytes) is inherent in
the data type.
The format is:

yyyy-mm-dd
where yyyy represents the year,

mm the month, and dd the day.
yyyy, mm, and dd must be
numeric characters. Leading
zeroes cannot be omitted. The
allowable range for yyyy is
0001–9999; for mm, 01–12. The
dd range depends on the month.
2002-02-28

Table 18. Format of IXF column data by data type (continued)

388 TIME The value in IXFCLENG is not Same as character format.
length (8 bytes) is inherent in the
data type.
The format is:

hh.mm.ss
where hh represents the hour in

24-hour format, mm is minutes,
and ss is seconds. hh, mm, and
ss must all be numeric
characters. Leading zeroes
cannot be omitted. Allowable
ranges are:
v 00 - 23 for hh
v 00 - 59 for mm
v 00 - 59 for ss
The special value 24.00.00 for

midnight is valid. Examples:
10.37.42 is 10:37:42 AM
08.00.00 is 8 AM exactly
23.30.00 is 11:30 PM
392 TIMESTAMP The value in IXFCLENG is not Same as character format.
length (26 bytes) is inherent in
the data type.
The format is:

yyyy-mm-dd-hh.mm.ss.nnnnnn
where yyyy is the year, the first

mm is the month, dd is the day,
hh is hour in 24-hour format, the
second mm is minutes, ss is
seconds, and nnnnnn is
microseconds. Valid ranges for
year, month, day, hour, minutes,
and seconds are the same as
the DATE and TIME data types.
nnnnnn can be 000000–999999.
Examples:
2005-12-31-23.59.59.999999
(the last microsecond
in 2005)
2006-01-01-00.00.00.000000
(the first microsecond
in 2006)
24.00.00.000000 is valid for the

time portion of a timestamp.


448 VARCHAR IXFCLENG is the maximum IXFCLENG is the maximum
length of the character string. length of the character string.
Data length consists of n bytes The data length consists of n
indicated by IXFCLENG bytes indicated by IXFCLENG
preceded by a 5-byte character preceded by a 2-byte binary
count field. (The allowable range count field. (The allowable range
for n is 0-254 and for the count for n is 1-254 and for the count
field it is 0-n.) The number of field it is 0-n). The number of
characters indicated by the count characters indicated by the count
field are valid; the rest are field are valid; the rest are
meaningless. For example, if meaningless. For example, if
IXFCLENG=00010, the data IXFCLENG=00010, the data
format is the following: format is as follows:
00005JONESxxxxx nnJONESxxxxx
In this format, each x is a blank In this format, nn=X’0005’ and

character (X'40'). each x is a blank character
(X'40').
452 CHAR IXFCLENG is the length of the Same as character format.
character string. Data length is
indicated by n bytes of
IXFCLENG. (The allowable
range for n is 1-254). For
example, if IXFCLENG=00005,
the data format is the following:
JONES
In this format, JONES is the

5-byte character string pointed to
by bytes 44-49 of the C record.
456 LONG VARCHAR Same as VARCHAR, except that Same as character format.
the allowable range for n is
0-32767
464 VARGRAPHIC IXFCLENG is the maximum Data length consists of a 2-byte
number of double-byte binary count field followed by
characters (2×n bytes). Data twice the number of bytes
length consists of a 5-byte indicated by IXFCLENG. The
character count field, plus twice allowable range for IXFCLENG is
the number of bytes indicated by 1-127, and for the count field it is
IXFCLENG, plus 2 (for shift 0-IXFCLENG. The number of
characters). The number of 2-byte characters in the count
2-byte characters in the count field are valid. There are no
field are valid plus a shift-out surrounding shift-out and shift-in
(X'0E') immediately preceding characters. The rest can be
the data, and a shift-in (X'0F') meaningless. For example, if
immediately following the data. IXFCLENG = 00008, the data
The rest can be meaningless. format is the following:
(The allowable range for n is nnZZYYXXWWxxxxxxxx
1-127 and for the count field the
allowable range is 0-n.) For
In this format, nn=X'0004' and
example, if IXFCLENG = 00006,
each x is a blank character
the data format is the following:
(X'40').
00003oZZYYXXixxxxxx
In this format, the letter “o” is

shift-out, “i” is shift-in, and each
“x” is a blank character (X'40').


468 GRAPHIC IXFCLENG is the number of Same as character format except
double-byte characters (2*n that there are no surrounding
bytes). Data length is 2*n bytes shift-in and shift-out characters in
plus a shift out (X'0E') the data string. For example, if
immediately preceding the data, IXFCLENG=00005, the data
and a shift-in (X'0F') immediately format is as follows:
following the data. For example, ZZYYXXWWVV
if IXFCLENG=00005, the data
format is the following:
oZZYYXXWWVVi
In this format, the letter “o” is

shift-out and “i” is shift-in.
472 LONG Same as VARGRAPHIC, except Same as character format.
VARGRAPHIC that the allowable range for n is
0-16383.
480 FLOAT The value in IXFCLENG is 8. The value in IXFCLENG is 8.
The length and format of the The length and format of data is
data is inherent in the data type. inherent in the data type.
Data consists of a 23-byte The data consists of an 8-byte

character value arranged as floating-point value.
follows:
v 1 character for sign
v 18 characters for mantissa (17
digits and a decimal point)
v The character E
v 3-character signed exponent
Examples:
-1.2345678901234567E+14
+6.2345678901234567E-01
0.0000000000000000E+00
484 DECIMAL Bytes 39-43 of the C record Bytes 39-43 of the C record
represent the precision P (first 3 represent the precision, or P
bytes) and scale S (next 2 bytes) (first 3 bytes), and scale, or S
of the number. Allowable range (next 2 bytes), of the number.
for P is 0-15. S can be any value The allowable range for P is
less than or equal to P. 0-15. S can be any value less
than or equal to P.
Data is formatted as a P+2-byte
character value (or P+1 bytes if The data consists of a
S=0), right-justified, with the first (P+2)/2-byte decimal value in
byte reserved for a sign, and a packed decimal format. The last
decimal point (position implied by byte indicates the sign of the
S) present only if S is not equal value. For example, if P=005 and
to zero. For example, if P=005 S=00, the data format is as
and S=00, the data format is the follows:
following: X’12345C’
12345
If P=006 and S=02, the data
If P=006 and S=02, the data format is as follows:
format is the following: X’0234510D’
+2345.10
If P=004 and S=03, the data

format is the following:
-8.515


| 492 BIGINT The value in IXFCLENG is not The value in IXFCLENG is not
| significant for this data type. The significant. The length and format
| length and format for data is of data is inherent in the data
| inherent in the data type. Data type. Data consists of a 8-byte
| consists of a 20-byte character binary value.
| value, right-justified, with the first
| character reserved for a sign.
| Examples:
| 0000000000000000033
| +9223372036854775807
| -9223372036854775808
496 INTEGER The value in IXFCLENG is not The value in IXFCLENG is not
significant for this data type. The significant. The length and format
length and format of data is of data is inherent in the data
inherent in the data type. type.
Data consists of an 11-byte The data consists of a 4-byte

character value, right-justified, binary value.
with the first character reserved
for a sign. Examples:
0000000013
+1187642200
-0033588727
500 SMALLINT The value in IXFCLENG is not The value in IXFCLENG is not
significant for this data type. The significant. The length and format
length and format of data is of data is inherent in the data
inherent in the data type. type.
Data consists of a 6-byte Data consists of a 2-byte binary

character value, right-justified, value.
with the first character reserved
for a sign. Examples:
00023
+00763
-21311
| 908 VARBINARY Not applicable Same as VARCHAR, except that:
| v IXFCLENG is the maximum
| length (number of bytes) of
| the binary string.
| v The allowable range for n is
| 0-32704.
| 912 BINARY Not applicable Same as CHAR, except that:
| v IXFCLENG is the length
| (number of bytes) of the
| binary string sequence.
| v The allowable range for n is
| 1-255.
Interpreting an object exported in IXF format

Assume that the table shown in the example in “Interpreting a data object in QMF
format” on page 65 is now exported using the IXF format (with
OUTPUTMODE=CHARACTER). The table to be exported is as follows:
ID NAME COMM
------ --------- ----------
10 SANDERS -
20 PERNAL 612.45

The exported data set or CICS data queue consists of a total of seven records; an
H record, a T record, three C records, and two D records as shown in Figure 23:
HIXF0000QMF V6R1M01998120409560000005N
T18 database CCI00003
C02ID NYNR50000000 000002 00
C04NAME YYNR44800000 00009000008 00
C04COMM YYNR48400000 00702000023 00
D 00010 00007SANDERSxx -
D 00020 00006PERNALxxx 00612.45
Figure 23. A table exported in IXF format with OUTPUTMODE=CHARACTER
Unprintable binary characters are shown as “x” characters. Figure 24 on page 77

gives more detailed information about these records.

Figure 24. Format of sample IXF records (OUTPUTMODE=CHARACTER)
Now suppose that the same table is exported using the IXF format, but with
OUTPUTMODE=BINARY. The exported data set or CICS data queue consists of
seven records which are shown in Figure 25:
HIXF0000QMF V6R1M01998120409565000005N
T18 database CMI00003
C02ID NYNR50000000 000003 00
C04NAME YYNR44800000 00009000005 00
C04COMM YYNR48400000 00702000018 00
D xxxxxxxxSANDERSxxxxxxxx
D xxxxxxxxPERNALxxxxxxxxx
Figure 25. A table exported in IXF format with OUTPUTMODE=BINARY
With the exception of bytes 44 through 49 (starting position of column data), the
information in the H, T, and C records is essentially the same. The data in the D

records, however, differs significantly. Figure 26 contains more information about the
records of the exported data set or CICS data queue.
Figure 26. Format of sample IXF records (OUTPUTMODE=BINARY)
| Exporting data or tables in XML format

| If your data or table contains an XML column, you must use the
| DATAFORMAT=XML clause on the EXPORT DATA or EXPORT TABLE command.
| When you export data or tables in XML format, the data is exported to the UNIX
| file, TSO data set, or CICS data queue that you specify in the command and is
| limited to 32K. (See DB2 QMF Reference for the full syntax of the EXPORT and
| IMPORT commands.)
| QMF uses z/OS XML parse services as well as z/OS Unicode conversion services
| when processing XML data for export or import, so these services must be
| configured and active.
| The data is exported as an XML document in Unicode UTF-8 format with a CCSID
| of 1208. The exported XML data set or CICS data queue consists of the following:

| v Header records (see “Header records”)

| v Records that define the result set (see “Records that define the result set”)
| v Metadata records for each column in the data or table (see “Metadata records”)
| v Data records for each row in the exported data or table (see “Data records” on
| page 80)
| All tags shown in the examples in this topic must be present before you import the
| contents of the file, data set, or CICS data queue containing the XML column data,
| because QMF uses these tags to parse the file. When QMF encounters the
| <extensions> tag at the end of the file, the cursor is closed and the import is
| finished; modifying or deleting this tag will result in an infinite read of the data.
| Header records
| The header records in the exported XML file contain the version of XML used, the
| encoding scheme, and a line that references which style sheet to use to format the
| exported XML document. See “Default style sheet” on page 81 for more information
| about the default style sheet provided with QMF.
| Here is an example of the information that appears within the header lines in an
| exported file:
| <?xml version="1.0" encoding="UTF-8" ?>
| 
| Records that define the result set

| The result set definition contains a namespace definition and a schema definition
| for the QMF schema file that will be used with the XML file. Figure 27 shows the
| records for the result set definition in a sample exported XML file that contains 7
| columns:
|
| <DataSet xmlns="http://www.ibm.com/QMF" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >

| <ResultSet>
| <Metadata>
| <SourceDescription />
| <ColumnsAmount>7</ColumnsAmount>
|
| .....Definitions for each column go here.
|
| </Metadata>
| <Data>
|
| .....Data for each row goes here.
|
| </Data>
| </ResultSet>
| <Extensions />
| </DataSet>
|
|
| Figure 27. Records that define the result set from a query, shown here in an exported XML file
| Metadata records
| The column metadata consists of the number of columns, column names, column
| labels (if applicable), data types, data lengths, whether the data is null, and the
| format. An example of the metadata for a column called "ID" is shown in Figure 28
| on page 80. The exported XML file contains one column-description block for each
| column.
|

| <ColumnDescription id="1">
| <Name>ID</Name>
| <Label>ID</Label>
| <Type>smallint</Type>
| <Width>2</Width>
| <Nullable>false</Nullable>
| <Format>plain</Format>
| </ColumnDescription>
|
|
| Figure 28. Metadata records in an exported XML file
| Data records
| The exported file contains one row-definition block for each row of exported data. A
| <cell> tag identifies each column in the row by number, as shown for the first row of
| the Q.STAFF sample table in Figure 29:
|
| <Row id="0">
| <Cell id="1">10</Cell>
| <Cell id="2">SANDERS</Cell>
| <Cell id="4">MGR</Cell>
| <Cell id="6">99999.99</Cell>
| <Cell id="7" null="1" />
| </Row>
|
|
| Figure 29. How a row of the Q.STAFF sample table appears in an exported XML file
| When you use the DATAFORMAT=XML clause on the EXPORT DATA or EXPORT
| TABLE command and the data contains a column defined with the XML data type,
| QMF wraps the XML data in CDATA tags to prevent the parser from trying to
| process it. Figure 30 shows an example of how XML data appears in an exported
| file.
|
| <Data>
| <Row id="0">
| <Cell id="1">Murphy</Cell>
| <Cell id="2">1234</Cell>
| <Cell id="3"><![CDATA[<?xml version="1.0" encoding="utf-8"?>]]></Cell>
| </Row>
| </Data>
|
|
| Figure 30. How data from XML columns appears in an exported XML file
| How QMF validates the XML

| An XML schema document describes the structure of an XML document and
| defines parameters for the validity of elements and attributes within the XML
| document. A default schema file is provided with QMF as member DSQ1SCEM of
| the QMF samples data set, which is QMF910.SDSQSAPn (where n is a national
| language identifier from Table 1 on page vii). Copy this member to the directory
| where the file containing the XML document is stored and name the schema
| document qmf_data.xsd, which is the name for the default schema document under
| QMF for Workstation and WebSphere®. You can modify the default schema file

| according to your business needs for formatting XML data. If you choose to name
| the schema file something other than qmf_data.xsd or you are using a different
| schema file altogether, be sure to change the name in any files that reference the
| schema document.
| Default style sheet

| QMF provides a default style sheet (named with the default name qmf.xslt) as
| member DSQ1STSH of the QMF samples data set, QMF910.SDSQSAPn (where n
| is a national language identifier from Table 1 on page vii). You can copy this default
| style sheet to the location where the exported file resides, then open the XML
| document to have it formatted to these specifications. If you choose to rename the
| style sheet when you copy it, be sure to change the header in the exported file to
| refer to the new style sheet name. “Header records” on page 79 shows the location
| of the reference line for the style sheet.
Rules and information for exporting and importing data objects and
tables
This topic covers general considerations for importing and exporting data or table
objects.
Allocation of UNIX files, TSO data sets, or CICS data queues

The QMF IMPORT DATA command appears to store the data in the QMF
temporary storage area and display the report on the screen. Actually, only a
| portion of the data is stored and displayed. The UNIX file, TSO data set, or CICS
| data queue remains open and allocated to QMF. QMF reads records when the user
| scrolls through the data.
This connection is maintained until the data object is replaced or reset, or QMF has
| read all the records. At this point, the UNIX file, TSO data set, or CICS data queue
| is closed and is no longer considered allocated to QMF. An application should not
| attempt to delete or alter a UNIX file, TSO data set, or CICS data queue allocated
| to QMF with an IMPORT DATA command. The application needs to either start
using another data source or empty the QMF temporary storage area for the data
object (using a RESET DATA command) before it tries to alter or delete a file, data
set, or data queue it has been reading.
| During the execution of the IMPORT command, QMF does not lock the UNIX file,
| TSO data set or CICS data queue while it is being read. It does not take steps to
prevent the file, data set, or queue from being altered while it is being read. If the
file, data set, or queue is erased or altered in any way before QMF has finished
reading it, the results are unpredictable and can cause a system error.
An incomplete data prompt can occur when there is not enough temporary storage
to retrieve the entire object to be exported.
Export errors
| After QMF imports data from a UNIX file, TSO data set, or CICS data queue, QMF
| displays the report panel and a confirmation message. If the file, data set, or data
queue contains format errors, QMF does not display the Report panel; instead,
QMF displays an error message on the object panel that was current before QMF
processed the IMPORT command. However, if the current object panel was the
Report panel, and QMF finds errors in the imported data, QMF displays the home
panel and an error message.

Support for long names

When one of the column names is longer than 18 characters (as might be the case
with QMF Version 8.1 or later), the size of the column name field in the QMF or IXF
formats must be increased to 30 characters.
QMF format: When you export data or a table in QMF format, the table name and
authorization ID are not included in the exported file. The column name field size
must be increased from 18 to 30 when one of the column names is longer than 18
characters. The object level is "REL 3.0" to indicate the use of long column names
in the QMF DATA object, support for which was added in QMF Version 8.1. Thus,
errors result if you try to import an object from a QMF release earlier than Version
8.1 because the object levels are incompatible.
IXF format: The IXF table record (T record) contains the owner and name of a
table that is being exported using the QMF EXPORT TABLE command. However,
the T record contains a blank owner and name when exporting a QMF data object
that was the result of a RUN QUERY command. For long name support, the table
name is truncated at 18 characters and the owner name is truncated at 8
characters.
The column name field in the C record (column record) must be increased from 18
to 30 characters when there is a column name longer than 18 characters. When
long column names are present, the IXF version number in the H (header) record is
set to 0001. When there are no column names longer than 18 characters, the IXF
version number in the H record is 0000.
Exporting forms, reports, and prompted queries

The form and prompted query objects are exported and imported in an encoded
format that translates an object to a tabular structure. This encoded format helps
you manipulate individual parts of an object more easily. Reports are also exported
in an encoded format; however, they cannot be imported.
When you export an object with the encoded format:

v All table and field numbers are written out as four-digit numbers.
v The table columns are written out in the order in which they normally appear in
the object, except that the column with the maximum length is moved to the right
end of the table record and associated row records.
v Numeric lengths are three digits long (including leading zeroes, if necessary).
v The blank character is used as a delimiter in all records.
v The delimiter is not written following the last character of each record.
v Blanks are written in all reserved fields.
v An E record is the last record written to the output file.
The encoded format of a form, report, or prompted query consists of the following
records:
v Fixed-format records (see “Header records” on page 83)
v Variable-format records, which include the following types of records:
– Data value, or V, records (see “Data value records (V)” on page 85)
– Data table description, or T, records (see “Data table description records (T)”
on page 86)
– Table row, or R, records (see “Table row records (R)” on page 87)
– End-of-object, or E, record (see “End-of-object record (E)” on page 88)

An application data record, denoted by an asterisk (*), can be used by application

programs to store information and comments associated with the object in the
exported data set or data queue. See “Application data record (*)” on page 88 for
details.
In addition to the variable-format records, an exported report can contain the

following records:
v Report line, or L, records (see “Report line records (L)” on page 89)
v Data continuation, or C, records (see “Data continuation records (C)” on page 91)
For specifications of the exported TSO data sets or CICS data queues, see “Size
specifications for externalized QMF objects” on page 117.
General format of the exported file

This topic explains the general format of exported forms, reports, and prompted
queries. For examples and explanations of specific objects, see one of the following
topics:
v “Exporting a form” on page 91
v “Exporting a standard report” on page 101
v “Exporting a prompted query” on page 109
Header records
Most records have a variable format. However, header records have a fixed format,
even though the data set or data queue containing the records can be of variable
format.
These records are used to identify the contents of the exported form, report, or
prompted query. A header record is the first record of the exported data set or data
queue. It describes the characteristics of the object.
A header record contains the information described in Table 19 (an asterisk

indicates that the field is required for import):
Table 19. Header record information
01* Header record indicator (H)
02 Blank
03-05* Product identifier (QMF)
06 Blank
| 07-08 QMF release level in which the form, report, or prompted query was exported; this
| number is 15 for QMF Version 9.1.
09 Blank
10* Type of object:
F for form
R for report
T for prompted query
11 Blank

Table 19. Header record information (continued)

12-13* QMF object level:
01 for report
04 for form
01 for prompted query
The object level denotes a change in an object’s format. Each time an object's format
is changed in a QMF release, its object level is also changed. The object level
increases only when the change in the format could potentially create an error in your
application.
14 Blank
15* Data format of the object ("E" for encoded format used to export form, report and
prompted query objects)
16 Blank
17 Status of the object: E - Contains errors (for form only); W - Contains warning; V -
Valid
18 Blank
19 Whole or partial object indicator (W for whole object)
20 Blank
21 National language in use when the object was exported (E for English; see Table 1 on
page vii for other languages)
22 Blank
23* You can create a form, report, or prompted query outside of QMF in the proper format
and import it into QMF. Code an R in this byte position if you want QMF to replace
the object in temporary storage with the object you are importing.
24 Blank
25-26 Length of control area at the beginning of each record:
01 for form
02 for report
01 for prompted query
27 Blank
28-29 Length of integer length fields specified in V and T records (03)
30 Blank
31-38 Date stamp in the format yy/mm/dd
39 Blank
40-44 Timestamp in the format hh:mm
45 Blank
51 Blank
For specific examples of header records, see one of the following topics:
v For forms: “Interpreting the header record in the exported data set or queue” on
page 94
v For reports: “Interpreting the report header record in the exported data set or
queue” on page 104
v For prompted queries: “Interpreting the header record in the exported data set or
queue” on page 110
Records that comprise the object itself

With the exception of header records, which are fixed-format records, all records
are variable-format records. The types of records comprising the object itself are
listed below, followed in parentheses by the topic to read for more information.

v Data value (see “Data value records (V)”)

v Data table description (see “Data table description records (T)” on page 86)
v Table row (see “Table row records (R)” on page 87)
v End of object (see “End-of-object record (E)” on page 88)
v Application data (see “Application data record (*)” on page 88)
v Report line (see “Report line records (L)” on page 89)
v Data continuation (see “Data continuation records (C)” on page 91)
Variable-format records are accepted on input. Variable-format records have the

general form shown in Figure 31:
Figure 31. General form of variable-format records
The contents of the control area are shown in Table 20:

Table 20. General form of variable-format records
Byte position Description
01 Record identifier (H, V, T, R, E, *, L, C)
02 Blank (sometimes omitted; see specific type
of variable-format record)
The record data area is a variable-length area containing information about that
specific record. Fields in this area are separated by a delimiter (a blank character is
used in the examples in this topic).
Data value records (V): Value records are used to provide a value for a single
field in an object, such as blank lines before the heading in the form. V records
contain:
v A field number unique to the object
v The field’s length
v The field’s value
The control area for V records is shown in Table 21:

Table 21. Control area for V records
01 Value record identifier (V)
02 Blank (used only for reports; omitted for
forms and prompted queries)
The record data area for V records is shown in Table 22:

Table 22. Record data area for V records
01 Blank
02-05 Field number (1001-9999)

Table 22. Record data area for V records (continued)

06 Blank
07-09 Length of the data value (000-999). Can also
be an asterisk (*) followed by two blanks. An
asterisk indicates that the data value is
delimited by the end of the record.
10 Blank
11-end Data
In the record data area for V records:

v Record data area byte positions are offset from the end of the control area, the
length of which is indicated in the header record.
v An omitted data value (an end-of-record or only blanks following the length field)
indicates that the field contains a null value.
v If the length field is zero, the default value for the field is applied and a warning
message is issued.
v If the specified length is different from the actual data that follows, QMF issues a
warning.
Data table description records (T): In the encoded format, most data in an
object appears in tables. These are not relational tables in the database, but rather
a means of grouping information within the encoded format.
Each T record defines one table, and each table corresponds to a particular part of
an object, such as summary calculations in the form. Thus, one exported file can
contain many of these encoded tables.
A T record is always followed by R records. The T record describes the R records

that follow it. If there are no R records following a T record, the table is omitted.
Be sure your application program refers to the contents of tables of an exported

form, report, or prompted query by using the encoding in the T record to correctly
locate the values in the R records. Your application program should not use fixed
offsets to locate information in R records.
The control area for T records is shown in Table 23:

Table 23. Control area for T records
01 Table record identifier (T)
The record data area for T records is shown in Table 24. The byte positions in the
table are offsets following the end of the control area, the length of which is
indicated in the header record.
Table 24. Record data area for T records
01 Blank

Table 24. Record data area for T records (continued)

02-05 Table number (1001-9999)
06 Blank
07-09 The number of rows (R records) in this table.
An asterisk (*) used instead of a numeric
value means that the table consists of all the
R records that follow.
10 Blank
11-13 The number of columns in the record
(000-999)
14 Blank
15-18, 24-27, ... The field number for this column (repeating
field)
19, 28, ... Blank (repeating field)
20-22, 29-31, ... The length of the data values in this column
(repeating field)
Bytes 11-13 (number of columns) indicate how many field number/data value length
pairs follow; this means that the information in bytes 15 through 22 is repeated for
each column.
Keep the following information about T records in mind as you export and import
objects:
v When a form or prompted query is imported, the number of R records must
match the row count specified in bytes 07-09 of the record data area of the T
record. Otherwise, QMF issues a warning.
v When a form or prompted query is imported, the number of columns indicated in
bytes 11-13 must agree with the field number/length pairs in the bytes that follow.
If not, QMF issues a warning.
v The number of field number/length pairs is limited to the number of columns in
the table, and their order is arbitrary.
v Columns with a length of zero (or not included in this table) are set to their
default values when the object in the temporary storage area is updated and a
warning is issued. This is not always true for prompted queries. Where possible,
a default is supplied; otherwise, an error occurs.
v To set a column field to blank, the column must have a positive length in the T
record and a blank value in the R record.
Table row records (R): R records provide a set of values for a single row in an
encoded table. R records contain a list of values arranged in an order described by
the associated T record. An R record matches the description of the positions and
lengths of the data values specified in the T record.
The control area for R records is shown in Table 25:

Table 25. Control area for R records
01 Row record identifier (R)

Table 25. Control area for R records (continued)

Following the control area, the data area for R records consists of a series of
values separated by a delimiter (blank character). The format is as follows:
_value.._value..._value..
In this format, value... represents the data value for this row and column and _ is
the delimiter.
Keep the following information in mind as you work with R records:

v An R record must immediately follow another R record or a T record.
v The number of data values must match the description in the associated T
record.
v A data value length of zero in the associated T record indicates that no value is
to be applied to this row and column of the object; that is, it is set to its default
value. However, the presence of the field in the T record requires that the R
record contain an extra blank for this field (a zero-length value results in one
blank followed by another in the R record).
End-of-object record (E): The E record specifies the end of an exported object. It
is the last record of an exported file, appearing as the character E. For an exported
report, an E record is followed by a blank character to complete its control area. For
a form, the blank is omitted.
Any records following the E record are ignored. If an E record is not included with
the file being imported, QMF assumes that an end-of-file implies the end of the
object.
Application data record (*): Application data records allow application programs
to include their own data, such as comments, associated with a given object in the
external file. Application programs frequently use these records as comment records
to further describe the object in the file. The information following the asterisk is
essentially ignored and has no effect on the input process.
Application data records can appear anywhere in the external file except before the
header (H) record. QMF does not write out application data (*) records upon export.
However, you can use these records in the data set or CICS data queue you
create. They are useful as comment records. The contents of an application data
record are shown in Table 26:
Table 26. Contents of an application data record
01 Application data record identifier (*)
02-end of record Data
Here is an example of an application data record that appears in an exported form:

*This is the form that groups by DEPT.

Report line records (L): Each formatted line in a report is described by an L

record. There is one L record for each line in the report. Like other variable-format
records (V, T, and R), L records consist of a control area followed by a record data
area, as shown in Figure 32. The format of the control area is similar to the other
records; the record data area is composed of a fixed area that precedes the
formatted report line itself. The fixed area provides information about the report line
that follows it.
Figure 32. Format of an L record
The control area for an L record is shown in Table 27:

Table 27. Control area for an L record
01 Value record identifier (L)
02 Continuation indicator. Indicates whether the
current record is continued to a data
continuation record (see “Data continuation
records (C)” on page 91):
v C for continued.
A C record immediately follows an L
record marked with a continuation
character in byte 2 of the control area.
v D for continued with DBCS delimiters SO
and SI inserted at the end of the current
record and the beginning of the data
portion of the next record.
When D is specified for the continuation
indicator in the control area, it means that
the current record is too long to fit into a
single physical record, and that, in the
process of splitting up the record, SO (shift
out) and SI (shift in) characters were
added to the current and next records to
preserve the integrity of any DBCS data
being continued.
v Blank if not continued
The record data area for an L record is shown in Table 28. Bytes 6-13 are line type
attributes. Byte 06 is always 1. Each byte in bytes 7 through 13 indicates the
presence or absence of the corresponding line type attribute in the formatted report
line (1 = attribute present, 0 = attribute absent).
Table 28. Record data area for an L record
01 Blank

Table 28. Record data area for an L record (continued)

02-04 Report part indicator:
110 = Page heading

120 = Page footing
13n = Break heading
(n is break number, 1-6)
15n = Break footing
(n is break number, 1-6)
170 = Column heading
171 = Detail heading
180 = Detail line
181 = Group summary line
190 = Final footing
05 Blank
06 1
07 Data
08 Text
09 Separator
10 Column wrap.
Attributes for column wrap (byte 10) and line

wrap (byte 11) are used to indicate the
continuation of a single logical report line to
multiple physical report lines. The presence
of either attribute in a given L format record
means that the column data or wrapped line
is continued on a following L format record.
11 Line wrap.
Attributes for column wrap (byte 10) and line

wrap (byte 11) are used to indicate the
continuation of a single logical report line to
multiple physical report lines. The presence
of either attribute in a given L format record
means that the column data or wrapped line
is continued on a following L format record.
12 Second data line (across reports only).
Across reports containing percent or

cumulative sum columns can contain two
data lines for each group (also break and
final) summary. The first summary data line
contains the cumulative percent or
cumulative sum values of the column as
computed across each unique “across”
value. The second summary data line
contains the cumulative percent or
cumulative sum values of the column as
computed down each group (in the report or
within a control break). The second data line
(byte 12) line type identifies the second data
line in exported reports of this nature.
13 Reserved
14 Blank

The following is an example of an L record for a break footing line in a report

containing text and data:
L 151 11100000 DEPARTMENT TOTALS 93,659.45
Data continuation records (C): A C record is used to continue a value or set of

values across more than one record. It immediately follows the record being
continued. The format of a C record corresponds to the format of the original record
being continued. QMF uses C records to continue L records only.
The control area for a C record is shown in Table 29:

Table 29. Control area for a C record
01 Value record identifier (C)
02 Continuation indicator. Indicates whether the
current record is continued to another C
record:
v C for continued.
A C record immediately follows an L
record marked with a continuation
character in byte 2 of the control area.
v D for continued with DBCS delimiters SO
and SI inserted at the end of the current
record and the beginning of the data
portion of the next record.
When D is specified for the continuation
indicator in the control area, it means that
the current record is too long to fit into a
single physical record, and that, in the
process of splitting up the record, SO (shift
out) and SI (shift in) characters were
added to the current and next records to
preserve the integrity of any DBCS data
being continued.
v Blank if not continued
The record data area for a C record is shown in Table 30. The byte positions shown
are offset from the end of the control area, the length of which is indicated in the
header record.
Table 30. Record data area for a C record
01 Blank
02-end Value or set of values being continued
Exporting a form
The form object contains all the information specified in all the QMF form panels.
When you export a form, QMF converts to the encoded format any form panels
whose values deviate from the default values. Thus, the following panels are in the
encoded format only if you modified the panel:
v FORM.BREAKn, where n = 1 to 6

v FORM.CALC
v FORM.CONDITIONS
v All variation panels greater than 1 for FORM.DETAIL
Eliminating unused panels from the externalized format helps you save space on
your system.
Creating a default form to see example export results

You can create a default form by running any query that creates an empty report,
such as the query shown in Figure 33:
SELECT JOB
FROM Q.STAFF
WHERE NAME=’NO_NAME’
Figure 33. A query that creates an empty report (for the purposes of viewing the default form)
When QMF displays the report, enter EXPORT FORM TO DEFAULT (including the
QUEUETYPE=xx parameter in CICS).
How the exported form looks

Your data set or CICS data queue named DEFAULT contains the information shown
in Figure 34 on page 93.

H QMF 15 F 04 E V W E R 01 03 98/12/16 22:08
T 1110 001 011 1112 007 1113 040 1114 007 1115 006 1116 005 1117 005 1118 003 1119 008 1120 008
1122 006 1121 050
R CHAR JOB 2 5 C 1 DEFAULT
DEFAULT NO
V 1201 001 0
V 1202 001 2
T 1210 001 003 1212 004 1213 006 1214 055
R 1 CENTER
V 1301 001 2
V 1302 001 0
T 1310 001 003 1312 004 1313 006 1314 055
R 1 CENTER
V 1401 002 NO
V 1402 001 1
V 1403 001 0
T 1410 001 003 1412 004 1413 006 1414 055
R 1 RIGHT
V 1501 001 1
V 1502 003 YES
V 1503 003 YES
V 1504 003 YES
V 1505 003 YES
V 1506 003 YES
V 1507 003 YES
V 1508 003 YES
V 1509 003 YES
V 1510 003 YES
V 1511 004 NONE
V 1512 002 NO
V 1513 007 DEFAULT
V 1514 002 NO
V 1515 004 NONE
V 2790 001 1
V 2791 003 YES
V 2805 003 YES
T 2810 001 003 2812 004 2813 006 2814 055
R 1 LEFT
V 2901 002 NO
V 2902 001 1
V 2904 001 0
V 2906 002 NO
V 2907 002 NO
T 2910 001 003 2912 004 2913 006 2914 055
R 1 LEFT
V 3080 001 1
V 3101 002 NO
V 3102 002 NO
V 3103 001 0
V 3104 001 0
T 3110 001 003 3112 004 3113 006 3114 055
Figure 34. Sample format of an exported form (Part 1 of 2)

R 1 LEFT
V 3201 002 NO
V 3202 001 1
V 3203 001 0
V 3204 001 1T 3210 001 003 3212 004 3213 006 3214 055
R 1 RIGHT
V 3080 001 2
V 3101 002 NO
V 3102 002 NO
V 3103 001 0
V 3104 001 0
T 3110 001 003 3112 004 3113 006 3114 055
R 1 LEFT
V 3201 002 NO
V 3202 001 1
V 3203 001 0
V 3204 001 1
T 3210 001 003 3212 004 3213 006 3214 055
R 1 RIGHT
E
Figure 34. Sample format of an exported form (Part 2 of 2)
You can import your default data set or CICS data queue every time you log on by
issuing the command IMPORT FORM FROM DEFAULT (including the QUEUETYPE=xx
parameter in CICS) in your initial procedure.
Interpreting the header record in the exported data set or queue

The following is an example of a header record for a QMF form:
H QMF 15 F 04 E V W E R 01 03 05/12/16 22:08
Table 31 explains this example.

Table 31. Example of a form header record
Value from
example Description
| H QMF 15 F A QMF form header record for Version 9.1
04 Structure of the form is at object level 4
E Format is encoded (the format used for exported forms, reports, and
prompted queries)
V The exported form does not contain any errors or warnings
W The file contains the entire form
E The national language in use when object was exported is English
R When importing, the object in temporary storage is replaced
01 Length of control area is 1 byte
03 Length of integer length fields is 3 bytes
05/12/16 Date stamp
22:08 Timestamp
When you export a form from a non-English session, you can either export the form
in the current session language or in English. Because of this, the national

language identifier in the H record might not reflect the language of the session
from which you exported the form. See Table 1 on page vii for a list of national
language identifiers.
Interpreting the records that comprise the exported form

Figure 34 on page 93 shows an example of an exported form. The exported form
contains V, T, and R records whose associated codes have special meanings to
help you interpret the exported result. Table 32 explains each field and code in the
exported form.
Field 3080, a V record, acts as a “trigger” for the break panels that follow it. This
record appears once for every break panel in your form. The value of the field
reflects the number of the break panel that the fields following field 3080 describe.
Table 32. Table and field numbers for an exported FORM object
Table or field
number Record type Description Form panel
1110 T Column headings table FORM.COLUMNS
1112 R Column data type; column data type is FORM.COLUMNS
not displayed on the form panels but is
associated with the form in its external
format. The column data type is not
required when a form is imported. If it
is missing during import, QMF provides
default data type information from the
edit codes. (See “Importing a form
object” on page 99 for more
information.)
During export, the column data type

QMF provides is based on the
specified edit code. For edit codes U,
V, M, or invalid edit codes, QMF
specifies the data type keyword
UNKNOWN. Table 33 on page 98
shows the data type keywords that
QMF uses.
1113 R Column heading FORM.COLUMNS
1114 R Column usage code FORM.COLUMNS
1115 R Column indentation FORM.COLUMNS
1116 R Column width FORM.COLUMNS
1117 R Column edit code FORM.COLUMNS
1118 R Column sequence FORM.COLUMNS
1119 R Column heading alignment FORM.COLUMNS
1120 R Column data alignment FORM.COLUMNS
1121 R Column definition FORM.COLUMNS
1122 R Pass nulls on column definition FORM.COLUMNS
1180 T Summary calculations table FORM.CALC
1182 R Calculation identification number FORM.CALC
1183 R Summary calculation expression FORM.CALC
1184 R Summary calculation width FORM.CALC
1185 R Summary calculation edit code FORM.CALC
1186 R Pass nulls on calculation FORM.CALC
1201 V Blank lines before heading FORM.PAGE
1202 V Blank lines after heading FORM.PAGE
1210 T Page heading table FORM.PAGE

Table 32. Table and field numbers for an exported FORM object (continued)
Table or field
1212 R Page heading line number FORM.PAGE
1213 R Page heading alignment FORM.PAGE
1214 R Page heading text FORM.PAGE
1301 V Blank lines before footing FORM.PAGE
1302 V Blank lines after footing FORM.PAGE
1310 T Page foot table FORM.PAGE
1312 R Page footing line number FORM.PAGE
1313 R Page footing alignment FORM.PAGE
1314 R Page footing text FORM.PAGE
1401 V New page for final text FORM.FINAL
1402 V Final summary line number FORM.FINAL
1403 V Blank lines before final text FORM.FINAL
1410 T Final text table FORM.FINAL
1412 R Final text line number FORM.FINAL
1413 R Final text alignment FORM.FINAL
1414 R Final text FORM.FINAL
1501 V Detail line spacing FORM.OPTIONS
1502 V Outlining for break columns FORM.OPTIONS
1503 V Default break text FORM.OPTIONS
1504 V Function name in column heading for FORM.OPTIONS
grouping
1505 V Column-wrapped lines kept on a page FORM.OPTIONS
1506 V Across-summary column FORM.OPTIONS
1507 V Separators for column heading FORM.OPTIONS
1508 V Separators for break summary FORM.OPTIONS
1509 V Separators for across heading FORM.OPTIONS
1510 V Separators for final summary FORM.OPTIONS
1511 V Width of wrapped report lines FORM.OPTIONS
1512 V Page renumbering at breaks FORM.OPTIONS
1513 V Width of break or final text FORM.OPTIONS
1514 V Column re-ordering FORM.OPTION
1515 V Fixed columns FORM.OPTIONS
2790 V Detail variation number FORM.DETAIL
2791 V Detail variation selection FORM.DETAIL
2805 V Include column heading FORM.DETAIL
2810 T Detail heading table FORM.DETAIL
2812 R Detail heading text line FORM.DETAIL
2813 R Detail heading alignment FORM.DETAIL
2814 R Detail heading text FORM.DETAIL
2901 V New page for detail text FORM.DETAIL
2902 V Line number of column data FORM.DETAIL
2904 V Number of lines to skip after detail text FORM.DETAIL
2906 V Repeat detail heading FORM.DETAIL
2907 V Number of detail text lines to keep FORM.DETAIL
together

Table 32. Table and field numbers for an exported FORM object (continued)
Table or field
2910 T Detail text table FORM.DETAIL
2912 R Detail text line number FORM.DETAIL
2913 R Detail text alignment FORM.DETAIL
2914 R Detail text FORM.DETAIL
3080 V Break panel number FORM.BREAKn
3101 V New page for break heading FORM.BREAKn
3102 V Repeat break heading FORM.BREAKn
3103 V Number of lines to skip before break FORM.BREAKn
heading
3104 V Number of lines to skip after break FORM.BREAKn
heading
3110 T Break heading text table FORM.BREAKn
3112 R Break heading line number FORM.BREAKn
3113 R Break heading alignment FORM.BREAKn
3114 R Break heading text FORM.BREAKn
3201 V New page for break text FORM.BREAKn
3202 V Break text summary line FORM.BREAKn
3203 V Number of lines to skip before break FORM.BREAKn
text
3204 V Number of lines to skip after break text FORM.BREAKn
3210 T Break text table FORM.BREAKn
3212 R Break text line FORM.BREAKn
3213 R Break text alignment FORM.BREAKn
3214 R Break text FORM.BREAKn
3310 T Conditions table FORM.CONDITIONS
3312 R Condition identification number FORM.CONDITIONS
3313 R Conditional expression FORM.CONDITIONS
3314 R Pass nulls on conditions panel FORM.CONDITIONS
Table 33 on page 98 shows the data-type keywords QMF generates for the edit
codes specified on the form. In this table, x represents the number of decimal
places to be displayed, where x is an integer from 0 to 99.

Table 33. Data type keywords generated for edit codes specified on the QMF form panels
Edit code specified Data type keyword
C, CW, CT, CDx CHAR
| B, BW, X, XW BINARY
G, GW GRAPHIC
E, D, I, J, K, L, P, EZ, DZ, IZ, JZ, KZ, LZ, PZ, DZC, Dx, Ix, NUMERIC
Jx, Kx, Lx, Px
TDXx DATE
TTXx TIME
TSI TIMEST
M UNKNOWN
U, V UNKNOWN
Invalid edit codes entered UNKNOWN
When you export a form, QMF only exports those variation panels with values that
have been changed from the default. Therefore, the total number of variations in the
external form can be less than that shown in the variation count indicator on the
panel. QMF can alter the individual variation numbers to put the variations back into
a continuous sequence.
Considerations for QMF form objects in applications

When using a QMF form in an application, keep the following in mind:
v Creating a form data set or CICS data queue outside of QMF
If you create a form outside of QMF (not with EXPORT FORM), it is not
necessary to have a complete form object to import it successfully into QMF. You
just need the header (H) record followed by the T and R records of the
COLUMNS table. Default values are applied for the rest of the form when it is
imported.
When you create your own form data set or CICS data queue, it does not have
to be exactly like the data set or queue you get if you use EXPORT FORM. For
example, when QMF exports a form, all data values in a value (V) record are
preceded by a length, whereas you can use an asterisk (*) signifying that the
data value is delimited by the end of the record when you import a form.
QMF keeps the excess lines if an R record count in an imported form is less than
the number of default lines it has already allocated for the associated area in the
default form.
v Checking the object level in the header record
The object level in the header record of a data set or queue containing a form
tells you the level of the format structure at the time the form was generated.
(Object level is indicated in bytes 12 and 13 of the header record as described in
“Header records” on page 83.) You can make sure that your application properly
interprets the contents of the data set or data queue containing the form by
checking that the object level represents the format upon which your application
is based.
v Using application data records
The application data records explained in “Application data record (*)” on page
88 can be useful in your application program. They allow you to include your own
comments within a data set or CICS data queue for a form object. You can place
them anywhere in the data set or CICS data queue following the header record.

When QMF reads such a record, it ignores all data in the record following the *.
The record, therefore, has no effect on the import process.
v Restrictions for using forms in CICS
Because REXX is not available under QMF for CICS, the areas on the QMF form
that rely on REXX do not work if you try to run the form in the CICS environment.
These areas include anything entered on the FORM.CALC panels, the
FORM.CONDITIONS panels, and the Specify Definition window. Therefore,
REXX calculations, conditional row formatting, and column definitions are not
available to QMF for CICS users.
For general information and rules governing the data sets or queues that contain
forms, reports, and prompted queries, see “Importing forms and prompted queries”
on page 115. For specific guidelines to follow when importing a form, see “Importing
a form object.”
Importing a form object

When you import a form, these fields must be in uppercase:
v Record identifier for all records
v The following fields in the header record:
– Product identifier (QMF)
– Type of object (F)
– Format of object (E)
– Action against object (R)
v Data type values (numeric, character, graphic, or unknown data types) in the R
records for the COLUMNS table. If your site supports date/time data types, data
type values DATE, TIME, and TIMEST must also be in uppercase.
v All the form keywords and substitution variables used in the form panels. When a
form is imported, all the input in the form is left intact. If a form keyword is in
lowercase, the error indicator in the form panel is turned on. To correct the error,
the field must be typed over. If the data-type value is not in uppercase, an error
occurs, and the IMPORT ends.
The T record of the COLUMNS table (field number 1110) must immediately follow
the header record, and it must include a numeric count of the number of rows in the
encoded format (an * row count is not allowed).
If the entire COLUMNS table has been read in, unspecified fields are set to their
default values, and the form is displayed.
Variation panels: The variation number field (field number 2790) determines
which variation panel is updated by all the variation panel information that follows
the field. This V record should precede all other V, T, and R records for a given
variation panel.
If a value for a particular variation appears more than once in the encoded format,
the later values replace the original values. The number of variations in the form are
equal to the highest variation number in the form. There is no required order for
variation numbers when importing.
Translated forms: When you import an English-language form into a non-English

session, QMF automatically translates the reserved words in the form (such as
values in the USAGE column in FORM.COLUMNS) into your current session’s
language if the national language identifier in the H record is an E.

Omitting data type, edit code, and width in an imported form: In the
COLUMNS table, data type (field number 1112), edit code (field number 1117), and
width (field number 1116) can optionally be omitted when the following rules are
observed:
v Edit code must be included if data type and width are omitted. Based on the
specified edit code, QMF inserts appropriate defaults for data type and width.
v Data type must be included if edit code and width are omitted. QMF provides
default values for edit code and width.
v Width must be accompanied by either data type or edit code.
Table 34 contains information about values for the field containing the data type of
the column.
Table 34. Values for the field containing the data type of the column
Character string
Data type Code in decimal (database form) Meaning
DATE
384 DATE Date
TIME 388 TIME Time
TIMEST 392 TIMESTAMP Timestamp
NUMERIC 496 INTEGER Integer
500 SMALLINT Small integer
| 492 BIGINT Big integer
484 DECIMAL Decimal
480 FLOAT Floating point
CHAR 448 VARCHAR Varying-length character
452 CHAR Fixed-length character
456 LONG VARCHAR Long varying
character
904 ROWID Row identifier
GRAPHIC Varying-length graphic
464 VARGRAPHIC Fixed-length graphic
468 GRAPHIC Long varying
472 LONG VARGRAPHIC graphic
| BINARY 908 VARBINARY Varying-length binary
| 912 BINARY Fixed-length binary
In addition to the data type values shown in Table 34, there is an UNKNOWN data
type keyword that QMF uses in response to a U, V, or invalid edit code.
Detecting errors during import: If QMF detects an error in the format of the form
file during import, the import function ends with a message describing the error and
its location in the file.
If an error is encountered in the header record and a form already exists in the
temporary storage area, the existing form is displayed. If the form is successfully
imported, QMF displays the form panel.
If an error is encountered after the header record is read, any existing form in the
temporary storage area is discarded, and the home panel is displayed. However, if
the data object exists, QMF generates a default form for the data but does not
display it.

Certain minor errors detected by QMF do not terminate the import. In such cases,
QMF issues a warning message and, where appropriate, applies defaults. Some
examples are:
v V records
– Zero-length fields.
– The specified length field does not match the length of the data actually
supplied.
v T records
– Zero column length.
– The number of columns specified does not match the following field
number/length pairs.
You can respond to errors and warnings as follows:

v Fix one problem at a time.
v Set the TRACE option of the profile to L2 (using the command SET PROFILE
(TRACE=L2) and run the IMPORT FORM command. The L2 tracing option traces
messages and commands at the highest level of detail, allowing you to see all
the message text related to the IMPORT command.
The following command displays the error message for a particular message
number:
HELP message_number
Exporting a standard report

When QMF displays a report, you see the result of interaction between the form
and the data object in temporary storage. A report object does not exist in
temporary storage. When you export a report, QMF is really exporting the
interaction of a form and a data object. A report cannot be saved in the database,
and an exported report cannot be imported back to QMF. However, you can use
exported reports to:
v Extract data from the report and use it in an application
v Modify the appearance of the report for printing or redisplay by the application
This topic explains how to interpret the format of an exported sample report.
A sample report (before export)

Figure 35 on page 102 shows a report with a level 1 break. For an example of an
“across” report, see “Exporting an across-style report” on page 107.
For a list of the field numbers, see “Interpreting the report header record in the
exported data set or queue” on page 104.

J & H SUPPLY COMPANY

AVERAGE SALARIES (DEPTS 10, 15, 20)
REPORT 17
AVERAGE
DEPT JOB SALARY
------ ---------------
10 MGR 20865.86
----------
* 20865.86
15 CLERK 12383.35
MGR 20659.80
SALES 16502.83
----------
* 15482.33
20 CLERK 13878.68
MGR 18357.50
SALES 18171.25
----------
* 16071.53
==========
17473.24
COMPANY NAME
REPORT 17
Figure 35. A tabular QMF report before exporting
How the exported report looks

Figure 36 on page 103 shows the format of the exported report shown in Figure 35.

H QMF 15 R 01 E V W E R 02 03 05/10/14 11:24

V 1001 006 PERIOD
V 1002 003 016
T 1010 003 006 1013 005 1014 006 1015 006 1016 006 1017 006 1012 008
R L 000001 000003 000008 000001 BREAK1
R C 000009 000011 000015 000001 GROUP
R L2 000016 000018 000027 000001 AVERAGE
L 110 10100000 J & H SUPPLY COMPANY
L 110 10100000 AVERAGE SALARIES (DEPTS 10, 15, 20)
L 110 10100000 REPORT 17
L 110 10000000
L 110 10000000
L 170 10000000 AVERAGE
L 170 10000000 DEPT JOB SALARY
L 170 10010000 ------ ----- ----------
L 181 11000000 10 MGR 20865.86
L 151 10010000 ----------
L 151 11100000 * 20865.86
L 151 10000000
L 181 11000000 15 CLERK 12383.35
L 181 11000000 MGR 20659.80
L 181 11000000 SALES 16502.83
L 151 10010000 ----------
L 151 11100000 * 15482.33
L 151 10000000
L 181 11000000 20 CLERK 13878.67
L 181 11000000 MGR 18357.50
L 181 11000000 SALES 18171.25
L 151 10010000 ----------
L 151 11100000 * 16071.52
L 151 10000000
L 190 10010000 ==========
L 190 11000000 17473.24
L 120 10000000
L 120 10000000
L 120 10100000 COMPANY NAME
L 120 10100000 REPORT 17
E
Figure 36. Format of the exported sample report
When exporting a report, QMF writes the full text of the formatted report with
additional information to interpret the contents of the report.
The header record is the first record of the exported file. It is followed by the
appropriate V, T, and R records. If the report is an across-style report, it has another
group of V, T, and R records that follows the first group.
In addition to H, V, T, R, and E records, exported reports also require two additional

types of records:
v Report line, or L, records (see “Report line records (L)” on page 89 for more
information)
v Data continuation, or C, records (see “Data continuation records (C)” on page 91
for more information)
These two records follow the last group of V, T, and R records.
If you want to use only the formatted data of the report in your application, you can
have QMF send print output to a data set or CICS data queue. This data set or
CICS data queue contains only the formatted data without any layout information.

Interpreting the report header record in the exported data set or

queue
The following is an example of a header record for a QMF report:
H QMF 15 R 01 E V W E R 02 03 05/10/14 16:20

Table 35. Example of a header record for a report
Value from
example Description
| H QMF 15 R A QMF report header record for Version 9.1
01 Structure of the report is at object level 1
prompted queries)
V The exported report does not contain any errors or warnings
W The file contains the entire report
E English was the national language in use when the object was exported
R Ignored
02 Length of control area is 2 bytes
05/10/14 Date stamp
16:20 Timestamp
Interpreting the records that comprise the exported report

This topic explains the format of the exported report shown in Figure 36 on page
103.
Table 36 shows the table numbers for T records and field numbers for V records:
Table 36. Table and field numbers for an exported report
Table or field
number Record type Description
1001 V Profile DECIMAL option
1002 V Length of L record control area + fixed area
1010 T Formatted report table
For each formatted data column in the report:

1012 T For all usage codes except OMIT
1013 T Edit code by which data is formatted
1014 T Starting position for field containing formatted data (including indent
area)
1015 T Starting position for field containing formatted data (excluding indent
area)
1016 T Ending position for field containing formatted data
1017 T Number of relative physical report line within logical report line in which
formatted column value appears

When working with table and field numbers in an exported report, note the
following:
v Position 1 of the report line immediately follows the L-record fixed area.
v R records for text lines in each report heading (PAGE or BREAK) or footing
(PAGE, BREAK, or FINAL) are only written up to and including the last line that
contains modifications to the form defaults.
At least one R record is written for each heading or footing even when the fields
for a given heading or footing all have their original values.
v Continuation records are written for the report object when the maximum record
length would otherwise be exceeded.
Exporting a report in HTML format

When you export a report in HTML format, QMF places the necessary HTML tags
before and after the body of your report so that you can place it on a Web server
and display it in an HTML-compliant Web browser. Figure 37 on page 106 illustrates
the HTML coding that QMF places around the report. Each of these tag sets
consists of a start tag and an end tag. The end tags begin with a forward slash (/),
and all tags are enclosed in angle brackets.
For a full description of these tags, see your HTML documentation.

<HTML>
<HEAD>
<TITLE>
Report
</TITLE>
</HEAD>
<BODY>
<PRE>

AVERAGE SALARY (DEPTS 10, 15, 20)
REPORT 17
AVERAGE
DEPT JOB SALARY
---- ----- ---------
10 MGR 20865.86
---------
* 20865.86
15 CLERK 12383.53
MGR 20659.80
SALES 16052.83
---------
* 15482.33
20 CLERK 13878.67
MGR 18357.50
SALES 18171.25
---------
* 16071.52
=========
17473.52
COMPANY NAME
REPORT 17
</PRE>
</BODY>
</HTML>
Figure 37. Sample HTML coding for an exported QMF report
Table 37 briefly explains this HTML coding:

Table 37. HTML tags used in exported HTML reports
Tag set Description
<HTML></HTML> Defines the file as an HTML document.
<HEAD></HEAD> These tags mark the boundaries of the document header.
<TITLE></TITLE> QMF inserts the word "Report" between these tags. Content
between these tags is included in the HTML document title.
Placement of the title is browser- and platform-dependent. These
tags are placed within the header.
<BODY></BODY> These tags follow the header and contain the body of the document.
Report output is placed in the body of the document.

Table 37. HTML tags used in exported HTML reports (continued)

Tag set Description
<PRE></PRE> Content between these tags is displayed as-is. No HTML formatting
is performed between them. QMF places report output between
these tags in the body of the HTML document.
Exporting an across-style report

Figure 38 shows an exported across-style report.

DEPT AVERAGE SALARIES
REPORT 18 (ACROSS REPORT)
<---------------- JOB ----------------->

<- CLERK --> <-- MGR ---> <- SALES --> <- TOTAL -->
AVERAGE AVERAGE AVERAGE AVERAGE
DEPT SALARY SALARY SALARY SALARY
------ ---------- ---------- ---------- ----------
10 20865.86 20865.86
15 12383.35 20659.80 16502.83 15482.33
20 13878.68 18357.50 18171.25 16071.53
38 12482.25 17506.75 17407.15 15457.11
========== ========== ========== ==========
12914.76 19998.21 17372.10 16880.26
COMPANY NAME
REPORT 18
PAGE 1
Figure 38. Sample across-style report. This report uses QMF across-style report functions.
Figure 39 on page 108 shows the encoded format that results from exporting the
across-style report in Figure 38.

H QMF 15 R 01 E V W E R 02 03 05/10/14 16:20
V 1001 006 PERIOD

V 1002 003 016
T 1010 002 006 1013 005 1014 006 1015 006 1016 006 1017 006 1012 008
R L 000001 000003 000008 000001 GROUP
R L2 000003 000005 000014 000001 AVERAGE
V 2001 005 C
V 2002 003 001
V 2003 003 YES
T 2010 004 003 2012 006 2013 006 2014 006
R 000014 000018 000009
R 000029 000031 000023
R 000042 000046 000037
R 000056 000060 000051
L 110 10100000 J & H SUPPLY COMPANY
L 110 10100000 DEPT AVERAGE SALARIES
L 110 10100000 REPORT 18 (ACROSS REPORT)
L 110 10000000
L 110 10000000
L 170 10000000 <---------------- JOB ----------------->
L 170 11000000 <- CLERK --> <-- MGR ---> <- SALES --> <- TOTAL -->
L 170 10000000 AVERAGE AVERAGE AVERAGE AVERAGE
L 170 10000000 DEPT SALARY SALARY SALARY SALARY
L 170 10010000 ------ ---------- ---------- ---------- ----------
L 181 11000000 10 20865.86 20865.86
L 181 11000000 15 12383.35 20659.80 16502.83 15482.33
L 181 11000000 20 13878.68 18357.50 18171.25 16071.53
L 181 11000000 38 12482.25 17506.75 17407.15 15457.11
L 190 10010000 ========== ========== ========== ==========
L 190 11000000 12914.76 19998.21 17372.10 16880.26
ddL 120 10000000
L 120 10000000
L 120 10100000 COMPANY NAME
L 120 10100000 REPORT 18
L 120 10100000 PAGE 1
E
Figure 39. Format of the exported across-style report
Table 36 on page 104 explains field numbers common to both standard reports and
across-style reports. Table 38 explains the additional fields you see in the exported
across-style report.
Table 38. Field numbers for exported across-style report
Field number Record type Description
2001 V Edit code by which across value is formatted
2002 V Number of data lines per across group
2003 V Indicates whether the across summary column exists
2010 T Across report table
For each across value:

2012 T Starting position for formatted across value. (The across value appears
in the column heading lines.)
2013 T Ending position for formatted across value
2014 T Starting position for the set of report columns associated with this
across value, including preceding indent area

For aggregated columns in an across report, fields 1014, 1015, and 1016 describe
the relative starting and ending positions of the field within an across value’s set of
aggregated columns. (Refer to field 2014 in Table 38 on page 108.)
Exporting a prompted query

An exported prompted query object contains the information displayed in the echo
area of the Prompted Query primary panel. A data set or data queue containing an
exported prompted query can either be imported into the QMF temporary storage
area or directly into the database. When you import a prompted query, QMF checks
to see whether the incoming query is consistent with the data in the database. For
example, if the prompted query being imported has columns A, B, and C in table
XYZ, QMF verifies that table XYZ with columns A, B, and C exists in the database.
A sample query (before export)

This topic illustrates an example of an exported prompted query. Figure 40 shows
sample echo text that appears on the Prompted Query primary panel before
exporting.
Tables:
Q.STAFF(A)
Q.ORG(B)
Q.STAFF(C)
Join Tables:
A.DEPT And B.DEPTNUMB
And A.ID And C.ID
Columns:
A.ID
A.DEPT
A.JOB
A.SALARY
DEPTNUMB
C.SALARY
C.SALARY+A.COMM
Row Conditions:
If A.SALARY Is Greater Than 10000
And A.DEPT Is Equal To 84 or 96
Sort:
Descending by C.SALARY+A.COMM
Duplicate Rows:
Keep duplicate rows
Figure 40. Sample prompted query to be exported
How the exported query looks

Figure 41 on page 110 shows the format of the exported prompted query.

H QMF 15 T 01 E V W E R 01 03 98/11/20 17:12

T 1110 003 002 1112 001 1113 050
R A Q.STAFF
R B Q.ORG
R C Q.STAFF
T 1150 002 002 1152 020 1153 020
R A.DEPT B.DEPTNUMB
R A.ID C.ID
T 1210 007 002 1212 001 1213 255
R C A.ID
R C A.DEPT
R C A.JOB
R C A.SALARY
R C B.DEPTNUMB
R C C.SALARY
R C C.SALARY+A.COMM
T 1310 009 003 1312 001 1313 008 1314 255
R 1 C A.SALARY
R 2 IS GT
R 3 10000
R 4 I
R 1 C A.DEPT
R 2 IS EQ
R 3 84
R 3 96
R 4 A
T 1410 001 002 1412 001 1413 255
R D C.SALARY+A.COMM
V 1501 001 K
E
Figure 41. The format of the exported query
Interpreting the header record in the exported data set or queue

Table 39 shows the meaning of the header record in the exported prompted query
shown in Figure 41. For additional information about how to interpret header
records, see “Header records” on page 83.
H QMF 15 T 01 E V W E R 01 03 05/11/20 17:12

Table 39. Example of a prompted query header record
Value from
example Description
| H QMF 15 T A prompted query header record for Version 9.1
01 Structure of the prompted query is at object level 1
prompted queries)
V The exported prompted query does not contain any errors or warnings
W The file contains the entire prompted query
E English was the national language in use when the object was exported
R When importing, the object in temporary storage area will be replaced
01 Length of control area is 1 byte

Table 39. Example of a prompted query header record (continued)

Value from
example Description
05/11/20 Date stamp
17:12 Timestamp
See Figure 41 on page 110 for a complete example of the Prompted Query
encoded format.
Interpreting the records that comprise the exported prompted

query
Table 40 contains prompted query table and field numbers for T records that
describe each table in the prompted query exported format.
Table definitions (field number 1110) are always exported. Join conditions (field
number 1510) are always exported if more than one table is selected.
To import a prompted query file, the file must have an H record followed by the
encoded table's T record. If no tables are specified, an empty query is imported.
Join conditions are not required unless more than one table is selected.
For information about R records, see “Table row records (R)” on page 87.
Table 40. Table and field numbers for an exported prompted query object
Record type Table number Field number Field description
T 1110 - Table definitions table. The T record in this
section of the exported prompted query in
Figure 41 on page 110 identifies this as the
portion containing the table names involved in
the query:
T 1110 003 002 1112 001 1113 050
'003' refers to 3 tables, while '002' refers to 2

field numbers (1112 and 1113). Each T record is
followed by R records and, in this example, the R
records identify the tables involved in the
prompted query join:
R A Q.STAFF
R B Q.ORG
R C Q.STAFF
This portion of the exported file corresponds to

the following part of the prompted query shown in
Figure 40 on page 109:
Tables:
Q.STAFF(A)
Q.ORG(B)
Q.STAFF(C)
1112 Table ID (valid table IDs are A-Z, and #,$,@)

1113 Table name: short length, for Version 7.2 or lower
(50); expanded length, available in Version 8.1 or
higher (280)

Table 40. Table and field numbers for an exported prompted query object (continued)
T 1150 - Join conditions table. The T record in this section
of the exported prompted query in Figure 41 on
page 110 identifies this as the portion containing
the join conditions involved in the query. Each T
record is followed by R records that identify
which tables will be joined and appears as
follows in the exported sample query in Figure 41
on page 110:
T 1150 002 002 1152 020 1153 020
R A.DEPT B.DEPTNUMB
R A.ID C.ID
This portion of the sample exported query

corresponds to the following part of the sample
prompted query shown in Figure 40 on page 109:
Join Tables:
A.DEPT And B.DEPTNUMB
And A.ID And C.ID
1152 Column 1 name:

short length (22)
expanded length (34)
1153 Column 2 name:
short length (22)
T 1210 - Columns table. The T record in this section of the
exported prompted query in Figure 41 on page
110 identifies this as the portion containing the
column names involved in the query. Each T
record is followed by R records that identify the
column names. The section appears as follows in
the exported query:
T 1210 007 002 1212 001 1213 255
R C A.ID
R C A.DEPT
R C A.JOB
R C A.SALARY
R C B.DEPTNUMB
R C C.SALARY
R C C.SALARY+A.COMM
This section of the exported query corresponds

to the following section of the sample query
shown in Figure 40 on page 109:
Columns:
A.ID
A.DEPT
A.JOB
A.SALARY
DEPTNUMB
C.SALARY
C.SALARY+A.COMM
1212 Column type:

v C=column
v E=expression
v S=summary function with expression
v F=summary function with only a column
1213 Column name, expression, or summary function:
short length (255)

T 1310 - Row selection conditions. The T record in this
section of the exported prompted query in
Figure 41 on page 110 identifies this section of
the exported query as the portion containing the
query conditions. Each T record is followed by R
records that characterize each condition. The
section appears as follows in the exported
prompted query:
T 1310 009 003 1312 001 1313 008 1314 255
R 1 C A.SALARY
R 2 IS GT
R 3 10000
R 4 I
R 1 C A.DEPT
R 2 IS EQ
R 3 84
R 3 96
R 4 A

to the following section of the query shown in
Row Conditions:
If A.SALARY Is Greater Than 10000
And A.DEPT Is Equal To 84 or 96
1312 Entry type:

v 1 - left of operator
v 2 - operator
v 3 - right of operator
v 4 - connector
1313 For entry type '1', identifies column type:
v C=column
v E=expression
v S=summary function
v F=summary function (column name only
specified)
For entry type '2', identifies the verb:
v IS for 'is' (default)
v ISN for 'is not'
For entry type '3' (not used)
For entry type '4', identifies a connector:
v O for 'or'
v A for 'and' (default)
1314 For entry type '1' this field is a column name,
expression, or summary function:
short length (255)

For entry type '2', identifies the operator:
v EQ for 'equal to'
v LT for 'less than'
v LE for 'less than or equal to'
v GT for 'greater than'
v GE for 'greater than or equal to'
v BT for 'between'
v SW for 'starting with'
v EW for 'ending with'
v CT for 'containing'
v NL for NULL
For entry type '3', identifies a value
For entry type '4' (not used)
T 1410 - Sort conditions table. The T record in this section
of the exported prompted query in Figure 41 on
page 110 identifies this as the portion containing
the sort conditions for the query. Each T record is
followed by R records that characterize each sort
condition. This section appears as follows in the
exported prompted query:
T 1410 001 002 1412 001 1413 255
R D C.SALARY+A.COMM

to the following section of the sample query in
Sort:
Descending by C.SALARY+A.COMM
1412 Sort direction:

v A for 'ascending'
v D for 'descending'
1413 Column:
short length (255)
V 1501 Duplicate rows treatment:
v K for 'keep'
v D for 'discard'
For example, the following line in the sample

exported prompted query in Figure 41 on page
110 shows that the record length of the value K
is 1 ("001") and that the user who built the query
specified to keep duplicate rows ("K"):
V 1501 001 K

to the following section of the sample query
Duplicate Rows:
Keep duplicate rows
The meaning of values for fields 1313 and 1314 depends on the sequence number
indicated in field number 1312 in the 1310 table.

Ensuring that the exported prompted query has a valid format

If you want to import a prompted query object that your application modified, be
aware of the following:
v When a prompted query file is imported, the incoming records must be in a
specific order following the header (H) record. The order should be:
1. T records for table definitions
2. R records for table names
3. T records for column definitions
4. R records for columns
5. Row condition records (field number 1310) must be in order within each
condition according to the entry type sequence number (field number 1312);
that is, the same order in which row data appears in the Prompted Query
echo area.
The remaining records can be in any order.
v The Table definitions table (T record 1110) must appear before any other tables
or V records.
v The value of row count in the Tables T record must be * or an integer from 0
through 15. A zero value in the row count causes everything in the query to be
ignored, which means that an empty query is imported.
v QMF does not issue warnings for prompted query imports.
v If a second Tables table (table 1110) is specified, QMF issues an error, and the
contents of the table are ignored. Prompted Query does not supply default values
on import.
v If there is a Sort table, there must be a Columns table preceding it.
v QMF accepts duplicate records in the import file. The most recent value for the
record is used.
v All column names must be qualified by the table identifier during import.
v When a prompted query is exported to a pre-allocated data set, the minimum
logical record length (LRECL) allowed is 259 bytes.
v The exported format of a prompted query is the same regardless of the national
language used; the format is language-independent. The language byte in the
header record is ignored during import. You can see the codes used in exporting
a prompted query in “Interpreting the records that comprise the exported
prompted query” on page 111.
Summary functions and expressions are not translated; thus, summary functions
COUNT, AVG, SUM, MIN, and MAX remain unchanged.
Importing forms and prompted queries

When you import a form or prompted query:
v The file can consist of variable-length or fixed-length records. See “Size
specifications for externalized QMF objects” on page 117 for more information.
v The record identifier (H, V, T, R, E, *, L, or C) must be in the first position of
every record.
v The first two bytes are reserved for control information (the control area).
v Every data field (including field numbers, lengths, and values) must be preceded
and followed by one delimiter, with the following exception: the last data field in a
record need not be followed by a delimiter because the end-of-record acts like a
delimiter. (The examples in this information use the blank character as the
delimiter.)

v If QMF encounters a duplicate data value or table while importing, it replaces the
previous value or table. However, duplicates are not allowed where they would
violate the rules for a particular object. For example, the number of columns
provided for a form can’t be changed after the first COLUMNS table has been
processed.
v Table numbers, field numbers, and numeric lengths can contain leading zeroes or
leading blanks. However, trailing blanks (except for the blank delimiter) are not
allowed; fields must be right-justified.
v When * is used instead of a length or count, it must be left-justified and padded
with trailing blanks.
v If the value supplied for a data entry field is shorter than the field, it is padded
with trailing blanks; if it is longer, it is truncated.
v If the record is shorter than its fixed-format length, those fields left unspecified
are assumed to be blank.
Procedures and SQL queries

The format of the TSO data set or CICS data queue representing these objects is
the simplest of all the formats. Each record in the data set or data queue is
essentially an image of a line as it appears on the screen (a fixed-length record of
79 bytes).
Figure 42 shows an example of a simple SQL query:
SQL query
SELECT *
FROM Q.STAFF
Figure 42. A simple SQL query
Figure 43 shows the query in its externalized format:
SELECT *
FROM Q.STAFF
Figure 43. A SQL query in its externalized format
Because of the simplicity of the record format, creating or editing an SQL query or
procedure outside of QMF is very straightforward. An SQL query or procedure
consists of a fixed-length data set or data queue containing 79-byte query or
procedure records. When you import the resulting data set or data queue, your
query or procedure is in the QMF temporary storage area, ready to be run.
Charts
You can export a chart for processing outside of the QMF environment. A chart
cannot be saved as a QMF object in the database or retrieved from the database.
You cannot import charts into QMF.
When you export a chart in QMF, it converts the data from the report to a Graphics
Data Format (GDF). GDF, a GDDM format, is an existing standard for data

interchange. You can print the exported chart data using GDDM utilities, or include
it in documents. See the appropriate GDDM application programming guide for
details about the GDF format. The IBM Publications Center at www.ibm.com/shop/
publications/order contains the GDDM publications for further reference.
You can use an exported chart object just as you would any GDF-formatted data
set. For example, using the Document Composition Facility (DCF), an application
can combine a QMF report (using a printed or exported report) with a QMF chart
(using an exported chart) and send the formatted information to a printer.
Exporting QBE queries

QBE query objects are exported using a format internal to QMF. This format cannot
be altered in any way.
Size specifications for externalized QMF objects

Table 41 contains specifications for both TSO and CICS import and export files.
For CICS, record sizes are indicated in Table 41; however, they are not enforced.
For example, you could import an SQL query from a temporary storage queue with
a record size of 32K and QMF would truncate it to 79 bytes.
Record format is not a factor for CICS temporary storage or transient data queues.
A temporary storage queue holds records without regard to their format. A transient
data queue is defined to a destination control table (DCT) and ignores the record
format.
You must specify a name for your data set or CICS data queue on the EXPORT or
IMPORT command. For more information about names, see DB2 QMF Reference.
Queue names have no default prefix or suffix. CICS temporary storage queue
names are 8 bytes; transient data queue names are 4 bytes.
Table 41. File and data set attributes
Object Record size Record format
Data or table Maximum size: 7,000 bytes Records must be fixed length
(QMF format)
Data or table Maximum size: 32,756 Records must be variable length
(IXF format)
The minimum LRECL for an exported
form that includes defined columns is
161 bytes.
The minimum LRECL that QMF

accepts for an IXF data set or CICS
data queue during import is 49 bytes.
Record size is normally the length of

a row of data in the table being
exported (including space for null
indicators and DBCS delimiters), plus
the length of the IXF D-type record
count field (5 bytes). If the record
size derived from the row length is
less than the length of the longest
IXF header record (81 bytes), then
the record size is set to 81 bytes.

Table 41. File and data set attributes (continued)

Object Record size Record format
| Data or table Maximum size: 32,807 Records must be fixed length
| (XML format)
Prompted Maximum: 7,290 bytes Records must be variable length on
query EXPORT; can be either fixed or
Minimum: 266 bytes on EXPORT; 41 variable on IMPORT.
bytes on IMPORT.
SQL query Must be 79 bytes on EXPORT; must Records must be fixed length on
be fewer than 256 bytes on IMPORT, EXPORT; can be either fixed or
but is truncated to 79 bytes. variable on IMPORT.
QBE query Must be 1,024 bytes Records must be variable length.
An empty QBE query is 828 bytes.

Form Maximum: 7,290 bytes Records must be variable length on
EXPORT; can be either fixed or
Minimum: 161 bytes on EXPORT; 23 variable on IMPORT.
bytes on IMPORT.
Proc Must be 79 bytes on EXPORT; can Records must be fixed length on
be any size on IMPORT, but is EXPORT; can be either fixed or
truncated to 79 bytes. variable on IMPORT.
Report Maximum: 7,290 bytes Records must be variable length.
Minimum: 65 bytes
HTML report Maximum: 32,000 bytes Records must be variable length.
Storage considerations
This topic explains how QMF handles storage when importing and exporting
objects.
CICS data queues

When you export an object to a CICS data queue, keep the following in mind:
v In CICS, both the IMPORT and EXPORT commands require that you specify the
QUEUETYPE option. There is no default.
v When importing an object from a transient data (TD) queue in CICS, you must
specify the correct object type; the queue is emptied once QMF retrieves its
contents. For example, if you specify “Form” when the object type in the transient
data queue is a procedure, QMF issues an error message. However, you cannot
successfully issue the IMPORT command again (even with the correct object
type) using the same queue, because that queue is now empty.
v In CICS, the transient data or temporary storage (TS) queue must contain a
single, completed QMF object before you issue the IMPORT command.
v If you export to a transient data queue, the queue must be open, enabled and
empty before you issue the EXPORT command.
QMF handles CICS transient data queues differently than temporary storage
queues.
v Transient data queues: QMF imports the entire transient data queue prior to
displaying the object on the screen. This means that the contents of the entire

queue must fit into your storage or spill area. It also means that, if the object to
be displayed is large, there may be a delay before QMF displays the object on
the screen.
A CICS intrapartition transient data queue can hold up to 32K rows of data; an
extrapartition transient data queue can be as large as it needs to be to hold the
object.
v Temporary storage queues: By default, QMF reads approximately 100 rows of
temporary storage before displaying them to the user. A temporary storage queue
can hold up to 32K rows of data.
QMF uses the SUSPEND parameter on the IMPORT and EXPORT commands to
let CICS regulate when the command is run.
The SUSPEND parameter on the IMPORT and EXPORT commands determines the
action to be taken if a queue is busy. When the SUSPEND parameter is set to YES,
QMF issues a CICS ENQ (enqueue) for the CICS data queue name. This tells
CICS to wait until the queue is available before writing the QMF object to the
queue, thus ensuring that the QMF transaction does not interfere with any other
jobs being handled by the queue.
When the SUSPEND parameter is set to NO, the EXPORT command is canceled
and a message is returned. The default value of SUSPEND is NO.
| TSO data sets

| You can use global variables to specify the type and size of new TSO data sets that
| will contain exported objects:
| v Use global variable DSQEC_PO to specify the type of partitioned data set to
| create when you export an object to a member of a new data set. The type can
| be your site’s default type, a PDS data set, or a PDSE data set.
| v Use global variable DSQEC_DSALLOC_DIR to specify the number of directory
| blocks when you export a member of a new PDS data set. The default is 20.
| v Use global variable DSQEC_DSALLOC_PRI to specify the primary space
| allocation in tracks. The default is 15 tracks.
| v Use global variable DSQEC_DSALLOC_SEC to specify the secondary space
| allocation in tracks. The default is 105 tracks.
| For more information on these global variables, see “Global variables that control
| how commands and procedures are executed” on page 208.

Chapter 10. Debugging your QMF applications
In addition to error-handling, QMF provides debugging facilities for your programs,
covered in the following topics:
v “Debugging your callable interface applications”
v “Debugging errors on the START and other QMF commands” on page 123
The techniques described in this topic apply to callable interface applications. For
information on ISPF debugging techniques, see Chapter 6, “Writing QMF
applications that use ISPF services,” on page 31.
You can use the REXX trace facility through the REXX trace statement. For more
details on this statement, see the REXX information in the IBM Publications Center
at www.ibm.com/shop/publications/order.
Debugging your callable interface applications

QMF provides two trace options, L and A, and various levels of trace detail for
debugging your applications. Installing and Managing DB2 QMF for TSO/CICS
provides more information about how to use trace options other than L and A to
troubleshoot problems.
Using the L option for tracing

The L option writes messages and commands to an external TSO data set or CICS
data queue.
There are two L options you can choose:

L1 Every QMF message is written to the QMF trace data output.
L2 Every QMF message and command is written to QMF trace data output.
You can set the L option in one of two ways:

v Issue the DISPLAY PROFILE command, and when the PROFILE is displayed,
change the TRACE option to either L1 or L2.
v Issue the command:
SET PROFILE (TRACE=x
In this statement, x is either L1 or L2.
See “Allocating the QMF trace data output” on page 122 and Installing and
Managing DB2 QMF for TSO/CICS for details on how to allocate storage for trace
data.
Using the A option for tracing

The A option allows you to specify a level of tracing for QMF application support
services.
The A option can be A0, A1, or A2. A0 is the default and is interpreted as the signal
for no A-tracing at all. A1 and A2 can then call for increasingly detailed results. This
is the pattern used for the other QMF trace options. (For more information on these
options, see Installing and Managing DB2 QMF for TSO/CICS.)

Debugging your QMF applications
You specify the A option in the same way you specify the L option: through a QMF
SET PROFILE command, or by entering it on the screen after you issue the
DISPLAY PROFILE command. For example, you can enter the following just before
you invoke the application you are debugging:
SET PROFILE (TRACE=L2A1)
When you begin your application, both L2 and A1 tracing are in effect.
To determine the current A option setting, look at the variable

DSQAO_APPL_TRACE. Its value is 0, 1, or 2 for the settings A0, A1, or A2,
respectively. You can use the value of DSQAO_APPL_TRACE to select the kind of
tracing you want in your application, as in the REXX application shown in Figure 44.
/* REXX program to set tracing */

call dsqcix "GET GLOBAL(A_TRACE=DSQAO_APPL_TRACE"
if a_trace > 0 then
do
/* trace code for both A1 and A2 */
..
.
if a_trace = 2 then
do
/* trace code for just A2 */
..
.
end
end
Figure 44. Sample REXX program that sets tracing for application support services
Turning the tracing off

If you need to turn the tracing off for any reason, issue the following command:
SET PROFILE (TRACE=NONE
This discontinues tracing for the rest of the QMF session, but does not affect the
permanent QMF profile.
Allocating the QMF trace data output

You must allocate the QMF trace data output before you invoke QMF if tracing is to
be used. Even so, you might want to reallocate the data set or data queue if the
original allocation does not meet your needs. Installing and Managing DB2 QMF for
TSO/CICS explains trace data allocation in detail.
For examples of how to allocate QMF trace data output for TSO, see the
programming examples for the language you are using:
Assembler “Assembler language interface” on page 125
C Language “C language interface” on page 142
COBOL “COBOL language interface” on page 153
FORTRAN “FORTRAN language interface” on page 164
PL/I “PL/I language interface” on page 176
REXX “REXX language interface” on page 189

Debugging your QMF applications
The commands in the examples in each language-specific topic allocate a

sequential trace data set or data queue that you can examine after your QMF
session is over. The output consists of fixed-length, 80-character records.
For CICS, you can use program parameters DSQSDBQT and DSQSDBQN to
specify where QMF puts your trace data. (For more information about these
program parameters, see “START” on page 50 or Installing and Managing DB2
QMF for TSO/CICS.) Use caution when using CICS temporary storage, because
QMF can produce a large amount of trace data. Because trace data that exceeds
the size of the queue is discarded, CICS temporary storage is recommended only
for trace data from messages or small applications.
Using tracing with the QMF MESSAGE command

You can use the QMF MESSAGE command to do more than display a message
when an application ends. You can also use it to record messages in the QMF trace
data output. To do this, run the application with the L tracing option set to L1 or L2.
(Refer to “Using the L option for tracing” on page 121 for additional information.)
Every message processed through the MESSAGE command is then recorded,
along with other QMF messages (and commands, if L2 is used), in the QMF trace
data output.
By placing MESSAGE commands at strategic points in your program, you can log
useful information in the QMF trace file. You can examine the information either on
a display device or in printed output. For more information about the QMF trace
data output, see “Allocating the QMF trace data output” on page 122 or Installing
and Managing DB2 QMF for TSO/CICS.
The following lines show an example of how to turn tracing on and issue meaningful
messages that will appear in the trace output:
call
. dsqcix "SET PROFILE (TRACE=L2"
.
.
call
. dsqcix "MESSAGE (TEXT=’QUERYA COMPLETED SUCCESSFULLY’"
.
.
call
. dsqcix "MESSAGE (TEXT=’EXECB ENTERED WITH VALUE OF 7’"
.
.
In this example, records containing the messages “QUERYA COMPLETED SUCCESSFULLY”

and “EXECB ENTERED WITH A VALUE OF 7” are written to the QMF trace data output.
Because QMF messages may change from one release to the next, you should not
use the QMF trace data output as input to an application.
Debugging errors on the START and other QMF commands

Depending on its level, the DSQCOMM might contain message text. If the START
command (or any QMF command) fails, this message text is invaluable for
debugging. See DB2 QMF Messages and Codes for information about all QMF
error messages.
Chapter 10. Debugging your QMF applications 123

Appendix A. Sample code for callable interface languages
This topic includes the following subtopics, which explain the application
programming interface for each of the supported callable interface languages:
v “Assembler language interface”
v “C language interface” on page 142
v “COBOL language interface” on page 153
v “FORTRAN language interface” on page 164
v “PL/I language interface” on page 176
v “REXX language interface” on page 189
The sample program shown in each of these topics does the following:
v Starts QMF
v Sets three global variables
v Runs a query called Q1
v Prints the resulting report using form F1
v Ends the QMF session
QMF does not supply query Q1 or form F1; they are just shown for the purposes of
the examples in each topic.
This topic also shows how to assemble (or compile) and link-edit the programs as
well as how to run them using the callable interface. IBM does not provide the
REXX execs, JCL, or CLISTs in these examples, but you can copy them and alter
them to suit your needs.
Assembler language interface

This topic explains the interface communications area for the Assembler language
as well as function calls for writing callable interface programs in Assembler.
Interface communications area mapping for Assembler (DSQCOMMA)

DSQCOMMA provides DSQCOMM mapping for the Assembler language; it is
provided with the product. Table 42 shows the values for DSQCOMMA.
Table 42. Contents of the DSQCOMMA interface communications area
Structure name Data type Description
DSQ_RETURN_CODE DS F Indicates the status of a QMF command
after it runs. Its values are:
DSQ_SUCCESS
Successful execution of the request
DSQ_WARNING
Normal completion with warnings
DSQ_FAILURE
Command did not execute correctly
DSQ_SEVERE
Severe error; QMF session
terminated

Sample code for callable interface languages
Table 42. Contents of the DSQCOMMA interface communications area (continued)

DSQ_INSTANCE_ID DS F Identifier established by QMF during
execution of the START command
DSQ_COMM_LEVEL DS CL12 Identifies the level of the DSQCOMM; in your
application, include instructions that initialize
this variable to the value of
DSQ_CURRENT_COMM_LEVEL before
issuing the QMF START command
DSQ_PRODUCT DS CL2 Identifies the IBM query product in use
(QMF)
DSQ_PRODUCT_RELEASE DS CL2 Release level of QMF in use; values for
supported releases are as follows:
DSQ_QMF_V7R2
QMF Version 7 Release 2
DSQ_QMF_V8R1
| DSQ_QMF_V9R1
| QMF Version 9 Release 1
DSQ_RESERVE1 DS XL28 Reserved for future use
DSQ_MESSAGE_ID DS CL8 Completion message ID
DSQ_Q_MESSAGE_ID DS CL8 Query message ID
DSQ_START_PARM_ DS CL8 Name of the parameter in error when the
ERROR START command failed due to a parameter
error
DSQ_CANCEL_IND DS C Contains one of two values, depending on
whether the user canceled the QMF session
while a QMF command was running:
v DSQ_CANCEL_YES
v DSQ_CANCEL_NO
DSQ_MESSAGE_TEXT DS CL128 Completion message text
DSQ_Q_MESSAGE_TEXT DS CL128 Query message text
Function calls for Assembler language

QMF provides one function call, DSQCIA, for Assembler-language programs. The
function call has two formats:
v Regular syntax (see “DSQCIA”)
v Extended syntax (see “DSQCIA, extended syntax” on page 127)
DSQCIA
This call is for QMF commands that do not require access to application program
variables. Use this call for most QMF commands.
CALL DSQCIA,(DSQCOMM,CMDLTH,CMDSTR),VL
The parameters have the following values:

DSQCOMM
The interface communications area
CMDLTH
Length of the command string (CMDSTR); a FULLWORD parameter
CMDSTR
The QMF command being issued on the function call; an uppercase character
string of the length specified by CMDLTH
VL is the Assembler VARIABLE LIST statement. For more information about this
statement, see the information for your version of Assembler in the IBM Publications
DSQCIA, extended syntax

This extended-syntax format of the DSQCIA function call is for the three QMF
commands that require access to application program variables: START and the
extended formats of GET GLOBAL and SET GLOBAL.
CALL DSQCIA,(DSQCOMM,CMDLTH,CMDSTR,
PNUM,KLTH,KWORD,VLTH,VALUE,VTYPE),VL

DSQCOMM
CMDLTH
Length of the command string (CMDSTR); a FULLWORD parameter
CMDSTR
QMF command to execute; an uppercase character string of the length
specified by CMDLTH
PNUM
Number of command keywords; a FULLWORD parameter
KLTH
Length of each specified keyword; a FULLWORD parameter or array of
FULLWORD parameters
KWORD
QMF keyword or keywords; a character or array of characters whose lengths
are specified by KLTH
VLTH
Length of each value associated with the keyword; a FULLWORD parameter or
array of FULLWORD parameters
VALUE
Value associated with each keyword. Its type is specified in the VTYPE
parameter, and can be a character, array of characters, FULLWORD parameter,
or array of FULLWORD parameters.
VTYPE
Data type of the contents of the VALUE parameter. This is one of two data
types, which are provided in the interface communications area, DSQCOMMA:
v DSQ_VARIABLE_CHAR for character values. If VTYPE is
DSQ_VARIABLE_CHAR, then VALUE is not validated.
v DSQ_VARIABLE_FINT for integer values. If VTYPE is
DSQ_VARIABLE_FINT, then VALUE is validated, and VALUE must be an
integer.
Appendix A. Sample code for callable interface languages 127

All values specified in the VALUE field must have the data type specified in
VTYPE.
VL is the Assembler VARIABLE LIST statement. For more information about this
statement, see the information for your version of Assembler in the IBM Publications
Assembler programming example

You can look at the sample source code listings here or you can access them
online. The sample program is a member of the library QMF910.SDSQSAPn (where
n is a national language identifier from Table 1 on page vii).
The sample programs for the Assembler callable interface perform the following
functions:
v Start QMF
v Set three global variables
v Run a query called Q1
v Print the resulting report using form F1
v End the QMF session
QMF does not supply query Q1 or form F1, but the sample programs use these
objects.
This topic also shows how to assemble, link-edit, and run an Assembler program
using the callable interface. The REXX JCL and CLISTs in these examples are not
provided with QMF, but you can copy them from here, altering them to suit your
needs.
Sample Assembler program for CICS

Figure 45 on page 129 shows program DSQABFAC, which is provided with QMF for
CICS.

TITLE ’Sample HLASM Query Callable Interface’ 00001000

*********************************************************************** 00002000
* * 00003000
* Sample Program: DSQABFAC * 00004000
* Assembler Version of the QMF Callable Interface * 00005000
* * 00006000
*********************************************************************** 00007000
DSQABFAC DFHEIENT CODEREG=(12),DATAREG=(13),EIBREG=(11) 00008000
SPACE 1 00009000
*********************************************************************** 00010000
* Start a query interface session * 00011000
*********************************************************************** 00012000
LA R4,CICOMM ESTABLISH ACCESS TO DSQCOMM 00013000
USING DSQCOMM,R4 00014000
SPACE 1 00015000
MVC DSQ_COMM_LEVEL,DSQ_CURRENT_COMM_LEVEL 00016000
ST R4,QMFP1 Address of DSQCOMMA 00017000
LA R1,STARTQIL Address of START command length 00018000
ST R1,QMFP2 00019000
LA R1,STARTQI Address of START command 00020000
ST R1,QMFP3 00021000
LA R1,1 One Start command parameter 00022000
ST R1,NUMPARMS 00023000
LA R1,NUMPARMS Address of number of parameters 00024000
ST R1,QMFP4 00025000
LA R1,STARTKYL Address of keyword lengths 00026000
ST R1,QMFP5 00027000
LA R1,STARTKY Address of keywords 00028000
ST R1,QMFP6 00029000
LA R1,STARTVL Address of value lengths 00030000
ST R1,QMFP7 00031000
LA R1,STARTV Address of values 00032000
ST R1,QMFP8 00033000
LA R1,DSQ_VARIABLE_CHAR Address of value data type 00034000
ST R1,QMFP9 00035000
OI QMFP9,X’80’ Set end of parameter list 00036000
LA R1,QMFPLIST Address of parameter list 00037000
CALL DSQCIA 00038000
SPACE 1 00039000
Figure 45. DSQABFAC, the sample Assembler program for CICS (Part 1 of 5)

*********************************************************************** 00040000
* Set numeric values into query using SET command * 00041000
*********************************************************************** 00042000
SPACE 1 00043000
LA R1,20 Set values for SET GLOBAL command 00044000
ST R1,VVAL1 00045000
LA R1,40 00046000
ST R1,VVAL2 00047000
LA R1,84 00048000
ST R1,VVAL3 00049000
LA R1,SETGL Addr of SET GLOBAL command length 00050000
ST R1,QMFP2 00051000
LA R1,SETG Address of SET GLOBAL command 00052000
ST R1,QMFP3 00053000
LA R1,3 Three SET GLOBAL variables 00054000
ST R1,NUMPARMS 00055000
LA R1,NUMPARMS Address of number of parameters 00056000
ST R1,QMFP4 00057000
LA R1,VNAME1L Address of variable name lengths 00058000
ST R1,QMFP5 00059000
LA R1,VNAME1 Address of variable names 00060000
ST R1,QMFP6 00061000
LA R1,VVAL1L Address of value lengths 00062000
ST R1,QMFP7 00063000
LA R1,VVAL1 Address of values 00064000
ST R1,QMFP8 00065000
LA R1,DSQ_VARIABLE_FINT Address of value data type 00066000
ST R1,QMFP9 00067000
SPACE 1 00071000

*********************************************************************** 00072000
* Run a query * 00073000
*********************************************************************** 00074000
LA R1,QUERYL Addr of RUN QUERY command length 00075000
ST R1,QMFP2 00076000
LA R1,QUERY Address of RUN QUERY command 00077000
ST R1,QMFP3 00078000
SPACE 1 00082000
*********************************************************************** 00083000
* Print the result of the query * 00084000
*********************************************************************** 00085000
LA R1,REPTL Addr of PRINT REPORT cmd length 00086000
ST R1,QMFP2 00087000
LA R1,REPT Address of PRINT REPORT command 00088000
ST R1,QMFP3 00089000
SPACE 1 00093000
*********************************************************************** 00094000
* End the query interface session * 00095000
*********************************************************************** 00096000
LA R1,ENDQIL Address of EXIT command length 00097000
ST R1,QMFP2 00098000
LA R1,ENDQI Address of EXIT command 00099000
ST R1,QMFP3 00100000
SPACE 1 00104000
*********************************************************************** 00105000
* Return * 00106000
*********************************************************************** 00107000
SPACE 1 00108000
XR R15,R15 ZERO RETURN CODE 00109000
DFHEIRET RCREG=15 00110000

*********************************************************************** 00111000
* Data Areas * 00112000
*********************************************************************** 00113000
SPACE 1 00114000
* Query Interface commands 00115000
SPACE 1 00116000
STARTQI DC C’START’ START FUNCTION 00117000
SETG DC C’SET GLOBAL’ SET GLOBAL FUNCTION 00118000
QUERY DC C’RUN QUERY Q1’ RUN QUERY 00119000
REPT DC C’PRINT REPORT (FORM=F1)’ PRINT REPORT 00120000
ENDQI DC C’EXIT’ END INTERFACE 00121000
SPACE 1 00122000
DS 0F 00123000
STARTQIL DC AL4(L’STARTQI) LENGTH OF START FUNCTION 00124000
SETGL DC AL4(L’SETG) LENGTH OF SET GLOBAL FUNCTION 00125000
QUERYL DC AL4(L’QUERY) LENGTH OF RUN QUERY COMMAND 00126000
REPTL DC AL4(L’REPT) LENGTH OF PRINT REPORT COMMAND 00127000
ENDQIL DC AL4(L’ENDQI) LENGTH OF END INTERFACE COMMAND 00128000
SPACE 1 00129000
* START command keyword 00130000
SPACE 1 00131000
STARTKY DC C’DSQSMODE’ 00132000
STARTV DC C’INTERACTIVE’ 00133000
DS 0F 00134000
STARTKYL DC AL4(L’STARTKY) 00135000
STARTVL DC AL4(L’STARTV) 00136000
SPACE 1 00137000
* SET GLOBAL command variable names 00138000
SPACE 1 00139000
VNAME1 DC C’MYVAR01’ 00140000
VNAME2 DC C’SHORT’ 00141000
VNAME3 DC C’MYVAR03’ 00142000
DS 0F 00143000
VNAME1L DC AL4(L’VNAME1) 00144000
SPACE 1 00147000
* SET GLOBAL command values 00148000
SPACE 1 00149000
VVAL1L DC AL4(L’VVAL1) 00150000
* Callable interface communications definition 00153000
DSQCOMMA 00154000

* Equates for registers 0-15 00155000

R0 EQU 00 00156000
R1 EQU 01 00157000
R2 EQU 02 00158000
R3 EQU 03 00159000
R4 EQU 04 00160000
R5 EQU 05 00161000
R6 EQU 06 00162000
R7 EQU 07 00163000
R8 EQU 08 00164000
R9 EQU 09 00165000
R10 EQU 10 00166000
R11 EQU 11 00167000
R12 EQU 12 00168000
R13 EQU 13 00169000
R14 EQU 14 00170000
R15 EQU 15 00171000
* Local variables located in CICS working storage 00172000
DFHEISTG DSECT 00173000
ORG DFHEIUSR 00174000
NUMPARMS DS F NUMBER OF KEYWORDS 00175000
* QMF SET GLOBAL command values 00176000
VVAL1 DS F 00177000
VVAL2 DS F 00178000
VVAL3 DS F 00179000
* QMF Callable interface parameter list 00180000
QMFPLIST DS 0D 00181000
QMFP1 DS F 00182000
QMFP2 DS F 00183000
QMFP3 DS F 00184000
QMFP4 DS F 00185000
QMFP5 DS F 00186000
QMFP6 DS F 00187000
QMFP7 DS F 00188000
QMFP8 DS F 00189000
QMFP9 DS F 00190000
* Callable interface communications area 00191000
CICOMM DS CL(DSQCOMM_LEN) 00192000
CSECT 00193000
SPACE 1 00194000
END DSQABFAC 00195000
Sample Assembler program for TSO

IBM provides a sample Assembler program for TSO named DSQABFA, as shown in
Figure 46 on page 134.

DSQABFA TITLE ’SAMPLE CALLABLE INTERFACE’

DSQABFA CSECT
***********************************************************************
* *
* Sample Program: DSQABFA *
* Assembler Version of the QMF Callable Interface *
* *
***********************************************************************
SPACE 1
STM R14,R12,12(R13) SAVE ENTRY REGISTERS
BALR R12,0 INITIALIZE BASE REGISTER
USING *,R12
LA R2,SAVEAREA CHAIN SAVE AREAS
ST R2,8(R13)
ST R13,SAVEAREA+4
LR R13,R2 ESTABLISH SAVE AREA
SPACE 1
***********************************************************************
* Start a query interface session *
***********************************************************************
LA R4,CICOMM ESTABLISH ACCESS TO DSQCOMM
USING DSQCOMM,R4
SPACE 1
MVC DSQ_COMM_LEVEL,DSQ_CURRENT_COMM_LEVEL
LA R1,1 1 PARAMETER
ST R1,NUMPARMS
CALL DSQCIA, X
(CICOMM, QI COMMON AREA X
STARTQIL, START COMMAND LENGTH X
STARTQI, START COMMAND X
NUMPARMS, NUMBER OF KEYWORDS X
STARTKYL, KEYWORD LENGTHS X
STARTKY, KEYWORDS X
STARTVL, VALUE LENGTHS X
STARTV, VALUES X
DSQ_VARIABLE_CHAR),VL VALUES ARE CHARACTERS
SPACE 1
Figure 46. DSQABFA, the sample Assembler program for TSO (Part 1 of 4)

***********************************************************************
* Set numeric values into query using SET command *
***********************************************************************
SPACE 1
LA R1,20 SET VALUES TO BE MODIFIED
ST R1,VVAL1
LA R1,40
ST R1,VVAL2
LA R1,84
ST R1,VVAL3
LA R1,3 3 PARAMETERS
ST R1,NUMPARMS
SPACE 1
CALL DSQCIA, X
(CICOMM, X
SETGL, SET GLOBAL COMMAND LENGTH X
SETG, SET GLOBAL COMMAND X
NUMPARMS, NUM OF VARIABLES TO BE SET X
VNAME1L, VARIABLE NAME LENGTHS X
VNAME1, VARIABLE NAMES X
VVAL1L, VALUE LENGTHS X
VVAL1, VALUES X
DSQ_VARIABLE_FINT),VL VALUES ARE INTEGERS
SPACE 1
***********************************************************************
* Run a query *
***********************************************************************
SPACE 1
CALL DSQCIA, X
(CICOMM, X
QUERYL, QUERY COMMAND LENGTH X
QUERY),VL TEXT OF QUERY COMMAND
SPACE 1
***********************************************************************
* Print the result of the query *
***********************************************************************
SPACE 1
CALL DSQCIA,(CICOMM,REPTL,REPT),VL
SPACE 1
***********************************************************************
* End the query interface session *
***********************************************************************
SPACE 1
CALL DSQCIA,(CICOMM,ENDQIL,ENDQI),VL
SPACE 1

***********************************************************************
* Return *
***********************************************************************
SPACE 1
SR R15,R15 SET RETURN CODE
L R13,4(R13)
L R14,12(R13) RESTORE CALLER REGISTERS
LM R0,R12,20(R13)
BR R14
EJECT
***********************************************************************
* Data Areas *
***********************************************************************
SPACE 1
* Query Interface commands
SPACE 1
STARTQI DC C’START’ START FUNCTION
SETG DC C’SET GLOBAL’ SET GLOBAL FUNCTION
QUERY DC C’RUN QUERY Q1’ RUN QUERY
REPT DC C’PRINT REPORT (FORM=F1)’ PRINT REPORT
ENDQI DC C’EXIT’ END INTERFACE
SPACE 1
DS 0F
STARTQIL DC AL4(L’STARTQI) LENGTH OF START FUNCTION
SETGL DC AL4(L’SETG) LENGTH OF SET GLOBAL FUNCTION
QUERYL DC AL4(L’QUERY) LENGTH OF RUN QUERY COMMAND
REPTL DC AL4(L’REPT) LENGTH OF PRINT REPORT COMMAND
ENDQIL DC AL4(L’ENDQI) LENGTH OF END INTERFACE COMMAND
SPACE 1
* START command keyword
SPACE 1
STARTKY DC C’DSQSMODE’
STARTV DC C’INTERACTIVE’
DS 0F
STARTKYL DC AL4(L’STARTKY)
STARTVL DC AL4(L’STARTV)
SPACE 1
* SET GLOBAL command variable names
SPACE 1
VNAME1 DC C’MYVAR01’
VNAME2 DC C’SHORT’
VNAME3 DC C’MYVAR03’
DS 0F
VNAME1L DC AL4(L’VNAME1)
SPACE 1
* SET GLOBAL command values
SPACE 1
VVAL1 DS F
VVAL2 DS F
VVAL3 DS F
VVAL1L DC AL4(L’VVAL1)
SPACE 1
NUMPARMS DS F NUMBER OF KEYWORDS
SPACE 1

* callable interface communications area

SPACE 1
CICOMM DS CL(DSQCOMM_LEN)
SPACE 1
SAVEAREA DS 18F
EJECT
DSQCOMMA
SPACE 1
R0 EQU 00 EQUATES FOR REGISTERS 0-15
R1 EQU 01
R2 EQU 02
R3 EQU 03
R4 EQU 04
R5 EQU 05
R6 EQU 06
R7 EQU 07
R8 EQU 08
R9 EQU 09
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
SPACE 1
END DSQABFA
DSQCOMM for Assembler

This file is provided with QMF as the file DSQCOMMA; it is shown in Figure 47 on
page 138.

MACRO 00001000
DSQCOMMA 00002000
********************************************************************** 00003000
* Callable Interface - variable constants * 00004000
********************************************************************** 00005000
* 00006000
* Communications Level ID 00007000
* 00008000
DSQ_CURRENT_COMM_LEVEL DC CL12’DSQL>001002<’ 00009000
* 00010000
* Query Product IDs 00011000
* 00012000
DSQ_QRW DC C’01’ 00013000
DSQ_QMF DC C’02’ 00014000
DSQ_QM4 DC C’03’ 00015000
* 00016000
* Query Product Release IDs 00017000
* 00018000
DSQ_QRW_V1R2 DC C’01’ 00019000
DSQ_QRW_V1R3 DC C’02’ 00020000
DSQ_QMF_V2R4 DC C’01’ 00021000
DSQ_QMF_V3R1 DC C’02’ 00022000
DSQ_QMF_V3R1M1 DC C’03’ 00023000
DSQ_QMF_V3R2 DC C’04’ 00024000
DSQ_QMF_V3R3 DC C’05’ 00025000
DSQ_QMF_V6R1 DC C’06’ 00026000
DSQ_QM4_V1R1 DC C’01’ 00027000
* 00028000
* Extended parameter data types 00029000
* 00030000
DSQ_VARIABLE_CHAR DC C’CHAR’ 00031000
DSQ_VARIABLE_FINT DC C’FINT’ 00032000
* 00033000
* Return codes 00034000
* 00035000
DSQ_SUCCESS EQU 0 00036000
DSQ_WARNING EQU 4 00037000
DSQ_FAILURE EQU 8 00038000
DSQ_SEVERE EQU 16 00039000
* 00040000
* Instance ID values 00041000
* 00042000
DSQ_CONTINUE EQU 0 00043000
* 00044000
Figure 47. DSQCOMMA, the Assembler interface communications area (Part 1 of 2)

* Cancel indicator 00045000

* 00046000
DSQ_CANCEL_YES EQU C’1’ 00047000
DSQ_CANCEL_NO EQU C’0’ 00048000
* 00049000
* 00050000
DSQ_INTERACTIVE EQU C’1’ 00051000
DSQ_BATCH EQU C’2’ 00052000
* 00053000
DSQ_YES EQU C’1’ 00054000
DSQ_NO EQU C’2’ 00055000
* 00056000
********************************************************************** 00057000
* Callable Interface Communications Area * 00058000
********************************************************************** 00059000
DSQCOMM DSECT 00060000
DSQ_RETURN_CODE DS F FUNCTION RETURN CODE 00061000
DSQ_INSTANCE_ID DS F ID ESTABLISHED IN START CMD 00062000
DSQ_COMM_LEVEL DS CL12 COMMUNICATIONS LEVEL ID 00063000
DSQ_PRODUCT DS CL2 QUERY PRODUCT ID 00064000
DSQ_PRODUCT_RELEASE DS CL2 QUERY PRODUCT RELEASE ID 00065000
DSQ_RESERVE1 DS CL28 RESERVED 00066000
DSQ_MESSAGE_ID DS CL8 COMPLETION MESSAGE ID 00067000
DSQ_Q_MESSAGE_ID DS CL8 QUERY MESSAGE ID 00068000
DSQ_START_PARM_ERROR DS CL8 START PARAMETER IN ERROR 00069000
DSQ_CANCEL_IND DS C CMD CANCEL INDICATOR 00070000
DSQ_MESSAGE_TEXT DS CL128 COMPLETION MESSAGE 00073000
DSQ_Q_MESSAGE_TEXT DS CL128 QUERY MESSAGE 00074000
SPACE 1 00075000
DSQCOMM_LEN EQU *-DSQCOMM LENGTH OF DSQCOMM AREA 00076000
MEND 00077000
Figure 47. DSQCOMMA, the Assembler interface communications area (Part 2 of 2)
Running your Assembler programs in CICS

After you write your program, you need to translate, assemble, and link-edit it
before you can run it. The examples listed in this topic show the steps necessary to
do so. The REXX JCL and CLISTs in these examples are not provided with QMF,
but you can copy them from here, altering them to suit your needs.
When you translate, assemble, and link-edit a program that uses the QMF callable
interface, be aware of the following:
v The interface communications area, DSQCOMMA, must be available to the
assemble step or copied into your program as a DSECT.
v The QMF interface module, DSQCIA, must be made available during the link-edit
step of your program.
The JCL shown in Figure 48 on page 140 is an example of how to use the
CICS-supplied procedure DFHEBTAL. For instructions on how to use this
procedure, see the appropriate CICS information in the IBM Publications Center at
www.ibm.com/shop/publications/order.

//sampasm JOB
// EXEC PROC=DFHEBTAL
//TRN.SYSIN DD *
*ASM XOPTS(CICS translator options .....)
.
Your program or copy of QMF sample DSQABFA
.
/*
//* Provide Access to QMF Communications Macro DSQCOMM
| //ASM.SYSLIB DD DSN=QMF910.SDSQSAPE,DISP=SHR
//* Provide Access to QMF Interface Module
| //LKED.QMFLOAD DD DSN=QMF910.SDSQLOAD,DISP=SHR
//LKED.SYSIN DD *
INCLUDE CICSLOAD(DFHEAI)
INCLUDE CICSLOAD(DFHEAI0)
INCLUDE QMFLOAD(DSQCIA)
ORDER DFHEAI,DFHEAI0
ENTRY sampasm
| MODE AMODE(31) RMODE(31)
NAME sampasm(R)
/*
Figure 48. JCL for running the CICS translator, assembler, and linkage editor
Running your Assembler programs in TSO

You must assemble and link-edit your program before you can run it in TSO. This
topic provides sample jobs that assemble and link-edit your programs; it also
provides sample programs for running your assembled program in TSO either with
or without ISPF.
Assembling and link-editing in TSO

Figure 49 shows a sample job that assembles and link-edits your program. Some
parameters might vary from one QMF installation to the next.
//sampasm JOB
//STEP1 EXEC PROC=ASMHCL
| //C.SYSLIB DD DSN=QMF910.SAMPLIB,DISP=SHR
//C.SYSIN DD *
.
Your program or copy of QMF sample DSQABFA
.
/*
| //L.QMFLOAD DD DSN=QMF910.SDSQLOAD,DISP=SHR
//L.SYSIN DD *
INCLUDE QMFLOAD(DSQCIA)
ENTRY sampasm
NAME sampasm(R)
/*
Figure 49. JCL for running the assembler and linkage editor in TSO
After your program is assembled successfully, you can run it, as explained in one of
the following topics:

v “Running in TSO with ISPF”

v “Running in TSO without ISPF” on page 142
Running in TSO with ISPF

After your program is assembled successfully, you can run it under ISPF by writing
a program similar to the one shown in Figure 50:
PROC 0
CONTROL ASIS
/************************************************************/
/* Specify attribute list for dataset allocations */
/************************************************************/
ATTR PRINTDCB LRECL(133) RECFM(F B A) BLKSIZE(1330)
ATTR DEBUGDCB LRECL(80) RECFM(F B) BLKSIZE(3120)
ATTR UDUMPDCB LRECL(125) RECFM(V B A) BLKSIZE(1632)
ATTR EDITDCB LRECL(79) RECFM(F B A) BLKSIZE(4029)
/************************************************************/
/* Datasets used by TSO */
/************************************************************/
| ALLOC FI(SYSPROC) DA(’QMF910.SDSQCLTE’,’ISR.ISRCLIB’)
| ALLOC FI(SYSEXEC) DA(’QMF910.SDSQEXCE’)
/************************************************************/
/* Datasets used by ISPF */
/************************************************************/
ALLOC FI(ISPLLIB) SHR REUSE +
| DA(’QMF910.SDSQLOAD’,’ADM.GDDMLOAD’,’DSN.DSNEXIT’,’DSN.DSNLOAD’)
ALLOC FI(ISPMLIB) SHR REUSE +
| DA(’QMF910.SDSQMLBE’,’ISR.ISRMLIB’,’ISP.ISPMLIB’)
ALLOC FI(ISPPLIB) SHR REUSE +
| DA(’QMF910.SDSQPLBE’,’ISR.ISRPLIB’,’ISP.ISPPLIB’)
ALLOC FI(ISPSLIB) SHR REUSE +
| DA(’QMF910.SDSQSLBE’,’ISR.ISRSLIB’,’ISP.ISPSLIB’)
ALLOC FI(ISPTLIB) SHR REUSE +
DA(’ISR.ISRTLIB’,’ISP.ISPTLIB’)
/************************************************************/
/* QMF/GDDM Datasets */
/************************************************************/
| ALLOC FI(ADMGGMAP) DA(’QMF910.SDSQMAPE’) SHR REUSE
| ALLOC FI(ADMCFORM) DA(’QMF910.DSQCFORM’) SHR REUSE
| ALLOC FI(DSQUCFRM) DA(’QMF910.DSQUCFRM’) SHR REUSE
ALLOC FI(ADMSYMBL) DA(’ADM.GDDMSYM’) SHR REUSE
ALLOC FI(ADMGDF) DA(’ADM.GDDM.CHARTLIB’) SHR REUSE
ALLOC FI(ADMDEFS) DA(’ADM.GDDM.NICKNAME’) SHR REUSE
/************************************************************/
/* Datasets used by QMF */
/************************************************************/
ALLOC FI(DSQPRINT) SYSOUT(X) USING(PRINTDCB)
ALLOC FI(DSQDEBUG) SYSOUT(X) USING(DEBUGDCB)
ALLOC FI(DSQUDUMP) SYSOUT(X) USING(UDUMPDCB)
ALLOC FI(DSQSPILL) NEW UNIT(SYSDA) SPACE(1,1) TRACKS
ALLOC FI(DSQEDIT) NEW UNIT(SYSDA) USING(EDITDCB)
| ALLOC FI(DSQPNLE) DA(’QMF910.DSQPNLE’) SHR REUSE
/************************************************************/
/* Start your program as the initial ISPF dialog */
/************************************************************/
ISPSTART PGM(sampasm) NEWAPPL(DSQE)
EXIT CODE(4)
Figure 50. CLIST for running your program in TSO under ISPF
The EXIT CODE(4) suppresses the ISPF disposition panel.

Running in TSO without ISPF

After your program is assembled successfully, you can run it in TSO without ISPF
by writing a program similar to the one in Figure 51:
PROC 0
CONTROL ASIS
/************************************************************/
/* Note: QMF, DB2 and GDDM load libraries must be allocated */
/* before executing this CLIST. */
| /* Name of QMF load library is "QMF910.SDSQLOAD". */
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| ALLOC FI(SYSPROC) DA(’QMF910.SDSQCLTE’)
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/* Start your program using TSO CALL command */
/************************************************************/
CALL sampasm
EXIT CODE(0)
Figure 51. CLIST for running your program under TSO without ISPF
C language interface
This topic explains the interface communications area for the C language,
DSQCOMMC, and two C function calls, DSQCICE and DSQCIC.
Interface communications area mapping for C language (DSQCOMMC)

DSQCOMMC provides DSQCOMM mapping for C language and is provided with
QMF. Table 43 on page 143 shows the values for DSQCOMMC.

Table 43. Interface communications area for DSQCOMMC

DSQ_RETURN_CODE signed long integer Indicates the status of a QMF command after it has been
run. Its values are:
DSQ_SUCCESS
DSQ_WARNING
DSQ_FAILURE
Command did not run correctly
DSQ_SEVERE
Severe error; QMF session terminated
DSQ_INSTANCE_ID signed long integer Identifier established by QMF during execution of the
START command
DSQ_COMM_LEVEL character, length 12 Identifies the level of the DSQCOMM; in your application,
include instructions that initialize this variable to the value
of DSQ_CURRENT_COMM_LEVEL before issuing the
QMF START command.
DSQ_PRODUCT character, length 2 Identifies the IBM query product in use (QMF).
DSQ_PRODUCT_RELEASE character, length 2 Release level of QMF in use; values for supported
releases are as follows:
DSQ_QMF_V7R2
DSQ_QMF_V8R1
| DSQ_QMF_V9R1
DSQ_RESERVE1 character, length 28 Reserved for future use
DSQ_MESSAGE_ID character, length 8 Completion message ID
DSQ_Q_MESSAGE_ID character, length 8 Query message ID
DSQ_START_PARM_ERROR character, length 8 Parameter in error when START failed due to a parameter
error
DSQ_CANCEL_IND character, length 1 Contains one of two values, depending on whether the
user canceled while a QMF command was running:
v DSQ_CANCEL_YES
v DSQ_CANCEL_NO
DSQ_RESERVE2 character, length 23 Reserved for future use
DSQ_RESERVE3 character, length Reserved for future use
156
DSQ_MESSAGE_TEXT character, length Completion message text
128
DSQ_Q_MESSAGE_TEXT character, length Query message text
128
Function calls for the C language

QMF provides two function calls for the C language: DSQCIC and DSQCICE.

DSQCIC
variables. Use this call for most QMF commands; its syntax is as follows:
DSQCIC (&DSQCOMM,&CMDLTH,&CMDSTR)

DSQCOMM
CMDLTH
Length of the command string (CMDSTR); a long type parameter
CMDSTR
The QMF command to run, specified as an array of unsigned character type of
the length specified by CMDLTH. The QMF command must be in uppercase.
DSQCICE
This call has an extended syntax for the three QMF commands that require access
to application program variables: START and the extended formats of GET
GLOBAL and SET GLOBAL.
DSQCICE (&DSQCOMM,&CMDLTH,&CMDSTR,
&PNUM,&KLTH,&KWORD,
&VLTH,&VALUE,&VTYPE);

DSQCOMM
The interface communications area.
CMDLTH
Length of the command string (CMDSTR); a long integer parameter.
CMDSTR
QMF command to run. It is an array of unsigned character type. The QMF
command must be in uppercase.
PNUM
Number of command keywords. It is a long integer parameter.
KLTH
Length of each specified keyword (KWORD). It is a long integer parameter or
an array of long integer parameters.
KWORD
QMF keyword or keywords. Each is an unsigned character array.
VLTH
Length of each value associated with the keyword; a long integer parameter or
array of long integer parameters
VALUE
parameter, and can be an unsigned character array, a long integer parameter,
or array of long integer parameters.
VTYPE
types, which are provided in the interface communications area, DSQCOMMC:
v DSQ_VARIABLE_CHAR for unsigned character type
v DSQ_VARIABLE_FINT for long integer

All of the values specified in the VALUE field must have the data type specified
in VTYPE.
The C language interface is similar to the others. There are, however, the following
parameter considerations:
v Command strings and the START, GET, and SET command parameters are all
input character strings. For these, C requires you to pass a storage area that is
terminated with a null value, which must be included in the parameter’s length.
The compile-time length function should be used to obtain the parameter length
that is passed to the QMF interface.
v If the string is not terminated by a null value before reaching the end of the
string, an error is returned by QMF. The null value (X'00') indicates the end of a
character string.
v For C parameters that are output character strings, including values obtained by
the GET command, QMF moves data from QMF storage to the application’s
storage area and sets the null indicator at the end of the string. If the character
string does not fit in the user’s storage area, a warning message is issued and
the data is truncated on the right. A null indicator is always placed at the end of
the data string.
C language programming example

This example shows a sample callable interface program for the IBM C language.
The program shown in Figure 52 on page 146, DSQABFC, is provided with QMF.
You can look at the sample source code listing here or you can access it online.
The sample program is a member of the library QMF910.SDSQSAPn (where n is a
national language identifier from Table 1 on page vii).
The sample program performs the following functions:

v Starts QMF
QMF does not supply query Q1 or form F1, but the sample program uses these
objects.

/******************************************************************/
/* Sample Program: DSQABFC */
/* C Version of the Callable Interface */
/******************************************************************/
/******************************************************************/
/* Include standard and string "C" functions */
/******************************************************************/
#include <string.h>
#include <stdlib.h>
/******************************************************************/
/* Include and declare query interface communications area */
/******************************************************************/
#include <DSQCOMMC.H>
int main()
{
struct dsqcomm communication_area; /* DSQCOMM from include */
/******************************************************************/
/* Query interface command length and commands */
/******************************************************************/
signed long command_length;
static char start_query_interface[] = "START";
static char set_global_variables[] = "SET GLOBAL";
static char run_query[] = "RUN QUERY Q1";
static char print_report[] = "PRINT REPORT (FORM=F1";
static char end_query_interface[] = "EXIT";
/******************************************************************/
/* Query command extension, number of parameters and lengths */
/******************************************************************/
signed long number_of_parameters; /* number of variables */
signed long keyword_lengths[10]; /* lengths of keyword names */
signed long data_lengths[10]; /* lengths of variable data */
Figure 52. DSQABFC, the sample C program (Part 1 of 3)

/******************************************************************/
/* Variable data type constants */
/******************************************************************/
static char char_data_type[] = DSQ_VARIABLE_CHAR;
static char int_data_type[] = DSQ_VARIABLE_FINT;
/******************************************************************/
/* Keyword parameter and value for START command */
/******************************************************************/
static char start_keywords[] = "DSQSMODE";
static char start_keyword_values[] = "INTERACTIVE";
/******************************************************************/
/* Keyword parameter and values for SET command */
/******************************************************************/
#define SIZE_VAL 8
char set_keywords [3][SIZE_VAL]; /* Parameter name array */
signed long set_values[3]; /* Parameter value array */
/******************************************************************/
/* MAIN PROGRAM */
/******************************************************************/
/******************************************************************/
/* Start a Query Interface Session */
/******************************************************************/
strncpy (communication_area.dsq_comm_level,
DSQ_CURRENT_COMM_LEVEL,
sizeof(communication_area.dsq_comm_level));
number_of_parameters = 1;
command_length = sizeof(start_query_interface);
keyword_lengths[0] = sizeof(start_keywords);
data_lengths[0] = sizeof(start_keyword_values);
dsqcice(&communication_area,;
&command_length,;
&start_query_interface[0],
&number_of_parameters,;
&keyword_lengths[0],
&start_keywords[0],
&data_lengths[0],
&start_keyword_values[0],
&char_data_type[0]);

/******************************************************************/
/* Set numeric values into query using SET command */
/******************************************************************/
number_of_parameters = 3;
command_length = sizeof(set_global_variables);
strcpy(set_keywords[0],"MYVAR01");
strcpy(set_keywords[1],"SHORT");
strcpy(set_keywords[2],"MYVAR03");
keyword_lengths[0] = SIZE_VAL;
data_lengths[0] = sizeof(long);
set_values[0] = 20;
set_values[1] = 40;
set_values[2] = 84;
dsqcice(&communication_area,;
&command_length,;
&set_global_variables[0],
&number_of_parameters,;
&keyword_lengths[0],
&set_keywords[0][0],
&data_lengths[0],
&set_values[0],
&int_data_type[0]);
/******************************************************************/
/* Run a Query */
/******************************************************************/
command_length = sizeof(run_query);
dsqcic(&communication_area,&command_length,;
&run_query[0]);
/******************************************************************/
/* Print the results of the query */
/******************************************************************/
command_length = sizeof(print_report);
&print_report[0]);
/******************************************************************/
/* End the query interface session */
/******************************************************************/
command_length = sizeof(end_query_interface);
&end_query_interface[0]);
exit(0);
}
DSQCOMM for C
The include file shown in Figure 53 on page 149, DSQCOMMC, is provided with the
QMF product.

/******************************************************************/
/* C Include for Query Callable Interface */
/******************************************************************/
/* Structure declare for Communications Area */
struct dsqcomm {
long int dsq_return_code; /* Function return code */
long int dsq_instance_id; /* id established in start cmd*/
char dsq_comm_level[12]; /* communications level id */
char dsq_product[2]; /* query product id */
char dsq_product_release[2]; /* query product release */
char dsq_reserve1[28]; /* reserved */
char dsq_message_id[8]; /* completion message ID */
char dsq_q_message_id[8]; /* query message ID */
char dsq_start_parm_error[8]; /* start parameter in error */
char dsq_cancel_ind[1]; /* cmd cancelled indicator */
/* 1 = cancelled, 0 = not cancelled*/
char dsq_reserve2[23]; /* RESERVED AREAS */
char dsq_reserve3[156];
char dsq_message_text[128]; /* Message text */
char dsq_q_message_text[128]; /* Query message text */
} ;
/* RETURN CODES */
#define DSQ_SUCCESS 0
#define DSQ_WARNING 4
#define DSQ_FAILURE 8
#define DSQ_SEVERE 16
/* Communications Level */
#define DSQ_CURRENT_COMM_LEVEL "DSQL>001002<"
/* Query Product Codes */
#define DSQ_QRW "01"

#define DSQ_QMF "02"
#define DSQ_QM3 "03"
/* Query Product Release Levels */
#define DSQ_QRW_V1R2 "01"

#define DSQ_QRW_V1R3 "02"
#define DSQ_QMF_V2R4 "01"
#define DSQ_QMF_V3R1M1 "03"
#define DSQ_QM4_V1R1 "01"
Figure 53. DSQCOMMC, the C-language interface communications area (Part 1 of 2)

/* INSTANCE CODES */
#define DSQ_CONTINUE 0
/* CANCELLED INDICATOR */
#define DSQ_CANCEL_YES "1"

#define DSQ_CANCEL_NO "0"
/* VARIABLE TYPES */
#define DSQ_VARIABLE_CHAR "CHAR"

#define DSQ_VARIABLE_FINT "FINT"
#define DSQ_INTERACTIVE "1"

#define DSQ_BATCH "2"
#define DSQ_YES "1"

#define DSQ_NO "2"
/* Call Interface structure */
/* Calling format for normal call with 3 parameters */

#define dsqcic(parm1, parm2, parm3 )\
dsqcicx( parm1, parm2, parm3)
/* Calling format for call with CMD_EXT area 9 parameters */

#define dsqcice(parm1, parm2, parm3,\
parm4, parm5, parm6, parm7, parm8, parm9 )\
dsqcicx( parm1, parm2, parm3, \
parm4, parm5, parm6, \
parm7, parm8, parm9 )
/* DECLARE OS LINKAGE FORMAT */
#pragma linkage(dsqcicx, OS)
Figure 53. DSQCOMMC, the C-language interface communications area (Part 2 of 2)
Running your C programs in CICS

After writing a program in C, you need to translate, compile, and link-edit it before
you can run it. The examples in this topic show the necessary steps. The REXX
JCL and CLISTs in these examples are not provided with QMF, but you can copy
them from here, altering them to suit your needs.
When you translate, compile, and link-edit a program that uses the QMF callable
interface under CICS, consider the following:
v The interface communications area DSQCOMMC must be available to the
compile step or copied into your program.
v The QMF interface module DSQCICX must be available during the link-edit step
of your program.
v Programs written in C must be link-edited with AMODE=31.
The example in Figure 54 on page 151 uses the CICS-supplied procedure

DFHEBTDL.

//sampleC JOB
// EXEC PROC=DFHEBTDL
//TRN.SYSIN DD *
#pragma XOPTS(CICS translator options .....)
.
Your program or copy of QMF sample DSQABFC
.
/*
//* Provide Access to QMF Communications Macro DSQCOMMC
| //ASM.SYSLIB DD DSN=QMF910.SDSQSAPE,DISP=SHR
//LKED.SYSIN DD *
INCLUDE CICSLOAD(DFHELII)
INCLUDE QMFLOAD(DSQCICX)
ORDER DFHELII
ENTRY sampleC
NAME sampleC(R)
/*
Figure 54. JCL for running the CICS translator, C compiler, and linkage editor
Running your C programs in TSO

This topic provides sample jobs for compiling and link-editing your callable interface
application and sample programs for running your compiled programs either with or
without ISPF.
Compiling and link-editing in TSO

The job shown in Figure 55 compiles and link-edits your callable interface
application using the IBM C compiler for z/OS. For more information on the
compiler, see the IBM C information in the IBM Publications Center at
www.ibm.com/shop/publications/order. Some parameters might vary from one QMF
installation to the next.
//sampleC JOB
//STEP1 EXEC PROC=EDCCL,LPARM=’MAP’
| //COMPILE.SYSLIB DD DSN=QMF910.SAMPLIB,DISP=SHR
//COMPILE.SYSIN DD DATA,DLM=’<>’
.
Your program or copy of QMF sample DSQABFC
.
<>
//* Provide Access to QMF Interface Module DSQCICX
| //LKED.SYSLIB DD DSN=QMF910.SDSQLOAD,DISP=SHR
/*
Figure 55. JCL for running the C compiler and linkage editor in TSO
Running your programs in TSO without ISPF

After your program has been compiled successfully, you can write a CLIST similar
to the one shown in Figure 56 on page 152 to run it:

PROC 0
CONTROL ASIS
/************************************************************/
/* Note: QMF, DB2, GDDM and C load libraries must be */
/* allocated before running this CLIST. */
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| ALLOC FI(ADMSYMBL) DA(’ADM.GDDMSYM’) SHR REUSE
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
CALL sampleC
EXIT CODE(0)
Figure 56. CLIST for running your program in TSO without ISPF
Running your programs in TSO under ISPF

After your program has been compiled successfully, you can write a program similar
to the one in Figure 57 on page 153 to run it:

COBOL language interface
PROC 0
CONTROL ASIS
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
ALLOC FI(SYSPROC) DA(’QMF910.SDSQCLTE’,’ISR.ISRCLIB’)
ALLOC FI(SYSEXEC) DA(’QMF910.SDSQEXCE’)
/************************************************************/
/************************************************************/
| DA(’QMF910.SDSQLOAD’,’ADM.GDDMLOAD’,’DSN.DSNEXIT’,’DSN.DSNLOAD’, +
’EDC.SEDCLINK’,’PLI.SIBMLINK’)
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
ISPSTART PGM(sampleC) NEWAPPL(DSQE)
EXIT CODE(4)
Figure 57. CLIST for running DSQABFC in TSO under ISPF

This topic explains the interface communications area and function calls for writing
callable interface programs in COBOL. It also provides examples of how to compile,
link-edit, and run a COBOL program using the callable interface.

Interface communications area mapping for COBOL (DSQCOMMB)

DSQCOMMB provides DSQCOMM mapping for COBOL and is provided with the
product. Table 44 shows the values for DSQCOMMB.
Table 44. Interface communications area for COBOL (DSQCOMMB)
DSQ-RETURN-CODE PIC 9(8) Indicates the status of a QMF command after it has run.
Its values are:
DSQ-SUCCESS
Successful execution of the request.
DSQ-WARNING
Normal completion with warnings.
DSQ-FAILURE
Command did not run correctly.
DSQ-SEVERE
Severe error; QMF session terminated.
DSQ-INSTANCE-ID PIC 9(8) Identifier established by QMF during execution of the
START command
DSQ-COMM-LEVEL PIC X(12) Identifies the level of the DSQCOMM; in your application,
include instructions that initialize this variable to the value
of DSQ_CURRENT_COMM_LEVEL before issuing the
QMF START command.
DSQ-PRODUCT PIC X(2) Identifies the IBM query product in use (QMF)
DSQ-PRODUCT-RELEASE PIC X(2) Identifies the release level of QMF in use
DSQ-RESERVE1 PIC X(28) Reserved for future use
DSQ-MESSAGE-ID PIC X(8) Completion message ID
DSQ-Q-MESSAGE-ID PIC X(8) Query message ID
DSQ-START-PARM-ERROR PIC X(8) Parameter in error when START failed due to a
parameter error
DSQ-CANCEL-IND PIC X(1) Contains one of two values, depending on whether the
v DSQ-CANCEL-YES
v DSQ-CANCEL-NO
DSQ-MESSAGE-TEXT PIC X(128) Completion message text
DSQ-Q-MESSAGE-TEXT PIC X(128) Query message text
Function calls for COBOL

QMF provides one function call, DSQCIB, for the COBOL language. It is described
in the interface communications area, DSQCOMMB. This function call has two
formats: DSQCIB and DSQCIB (extended format).
DSQCIB
CALL DSQCIB USING DSQCOMM CMDLTH CMDSTR


DSQCOMM
CMDLTH
Length of the command string (CMDSTR). It is an integer parameter.
CMDSTR
QMF command to run. It is an uppercase character string of the length
specified by CMDLTH.
DSQCIB (extended format)

This call has an extended syntax for the three QMF commands that require access
to application program variables: START and the extended formats of GET
GLOBAL and SET GLOBAL.
DSQCIB USING
DSQCOMM CMDLTH CMDSTR
PNUM KLTH KWORD VLTH VALUE VTYPE

DSQCOMM
The interface communications area.
CMDLTH
Length of the command string (CMDSTR). It is an integer parameter.
CMDSTR
QMF command to run. It is an uppercase character string of the length
specified by CMDLTH.
PNUM
Number of command keywords. It is an integer parameter.
KLTH
Length of each specified keyword. It is an integer parameter or an array of
integer parameters.
KWORD
QMF keyword or keywords. Each is a character or array of characters whose
lengths are the same as specified by KLTH. If all the keywords have the same
length, you can use an array of characters.
VLTH
Length of each value associated with the keyword. It is an integer parameter or
an array of integer parameters.
VALUE
parameter, and can be a character, an array of characters, an integer
parameter, or an array of integer parameters.
VTYPE
types, which are provided in the communications area, DSQCOMMB:
v DSQ-VARIABLE-CHAR for character values
v DSQ-VARIABLE-FINT for integer values
in VTYPE.

Using ISPF LIBDEF service with COBOL

If you are using a dynamic call to the QMF interface DSQCIB and you want to use
the LIBDEF function in your QMF application, change your dynamic calls to static
calls. For example, consider the following call identifier statement:
CALL DSQCIB USING ...
You can change this statement to its call literal form as follows:
CALL "DSQCIB" USING ...
COBOL programming example

The program shown in Figure 58 on page 157, DSQABFCO, is provided with the
QMF product.
You can look at the sample source code here or you can access it online. The
sample program is a member of the library QMF910.SDSQSAPn (where n is a
The sample program for the COBOL callable interface performs the following
functions:
v Starts QMF
objects.

****************************************************************
* The following is a VS COBOL II version of the query
* callable interface *** DSQABFCO **.
****************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. DSQABFCO.
DATE-COMPILED.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
*************************
* Copy DSQCOMMB definition - contains query interface variables
*************************
COPY DSQCOMMB.
* Query interface commands

01 STARTQI PIC X(5) VALUE "START".
01 SETG PIC X(10) VALUE "SET GLOBAL".
01 QUERY PIC X(12) VALUE "RUN QUERY Q1".
01 REPT PIC X(22) VALUE "PRINT REPORT (FORM=F1 ".
01 ENDQI PIC X(4) VALUE "EXIT".
* Query command length

01 QICLTH PIC 9(8) USAGE IS COMP-4.
* Number of variables
01 QIPNUM PIC 9(8) USAGE IS COMP-4.
* Keyword variable lengths
01 QIKLTHS.
03 KLTHS PIC 9(8) OCCURS 10 USAGE IS COMP-4.
* Value Lengths
01 QIVLTHS.
03 VLTHS PIC 9(8) OCCURS 10 USAGE IS COMP-4.
* Start Command Keyword
01 SNAMES.
03 SNAME1 PIC X(8) VALUE "DSQSMODE".
* Start Command Keyword Value
01 SVALUES.
03 SVALUE1 PIC X(11) VALUE "INTERACTIVE".
* Set GLOBAL Command Variable Names to set
01 VNAMES.
03 VNAME1 PIC X(7) VALUE "MYVAR01".
03 VNAME2 PIC X(5) VALUE "SHORT".
03 VNAME3 PIC X(7) VALUE "MYVAR03".
* Variable value parameters
01 VVALUES.
03 VVALS PIC 9(8) OCCURS 10 USAGE IS COMP-4.
01 TEMP PIC 9(8) USAGE IS COMP-4.
Figure 58. DSQABFCO, the sample COBOL program (Part 1 of 2)

PROCEDURE DIVISION.
*
* Start a query interface session
MOVE DSQ-CURRENT-COMM-LEVEL TO DSQ-COMM-LEVEL.
MOVE 5 TO QICLTH.
MOVE 8 TO KLTHS(1).
MOVE 11 TO VLTHS(1).
MOVE 1 TO QIPNUM.
CALL DSQCIB USING DSQCOMM, QICLTH, STARTQI,
QIPNUM, QIKLTHS, SNAMES,
QIVLTHS, SVALUES, DSQ-VARIABLE-CHAR.
*
* Set numeric values into query variables using SET GLOBAL command
MOVE 10 TO QICLTH.
MOVE 7 TO KLTHS(1).
MOVE 5 TO KLTHS(2).
MOVE 7 TO KLTHS(3).
MOVE 4 TO VLTHS(1).
MOVE 4 TO VLTHS(2).
MOVE 4 TO VLTHS(3).
MOVE 20 TO VVALS(1).
MOVE 3 TO QIPNUM.
CALL DSQCIB USING DSQCOMM, QICLTH, SETG,
QIPNUM, QIKLTHS, VNAMES,
QIVLTHS, VVALUES, DSQ-VARIABLE-FINT.
*
* Run a Query
MOVE 12 TO QICLTH.
CALL DSQCIB USING DSQCOMM, QICLTH, QUERY.
*
* Print the results of the query
MOVE 22 TO QICLTH.
CALL DSQCIB USING DSQCOMM, QICLTH, REPT.
*
* End the query interface session
MOVE 4 TO QICLTH.
CALL DSQCIB USING DSQCOMM, QICLTH, ENDQI.
STOP RUN.
Figure 58. DSQABFCO, the sample COBOL program (Part 2 of 2)
For CICS, the STOP RUN statement must be changed to a GOBACK statement.
DSQCOMM for COBOL

The include file shown in Figure 59 on page 159 is called DSQCOMMB and is
provided with QMF.

************************************************************* 00001000
* COBOL INCLUDE FOR QUERY CALLABLE INTERFACE 00002000
************************************************************* 00003000
00004000
* STRUCTURE DECLARE FOR COMMUNICATIONS AREA 00005000
00006000
01 DSQCOMM. 00007000
00008000
03 DSQ-RETURN-CODE PIC 9(8) USAGE IS COMP. 00009000
* FUNCTION RETURN CODE * 00010000
03 DSQ-INSTANCE-ID PIC 9(8) USAGE IS COMP. 00011000
* IDENTIFIER FROM START CMD * 00012000
03 DSQ-COMM-LEVEL PIC X(12). 00013000
* COMMUNICATIONS LEVEL * 00014000
03 DSQ-PRODUCT PIC X(2). 00015000
* QUERY PRODUCT ID * 00016000
03 DSQ-PRODUCT-RELEASE PIC X(2). 00017000
* QUERY PRODUCT RELEASE * 00018000
03 DSQ-RESERVE1 PIC X(28). 00019000
* RESERVED AREA * 00020000
03 DSQ-MESSAGE-ID PIC X(8). 00021000
* COMPLETION MESSAGE ID * 00022000
03 DSQ-Q-MESSAGE-ID PIC X(8). 00023000
* QUERY MESSAGE ID * 00024000
03 DSQ-START-PARM-ERROR PIC X(8). 00025000
* START PARAMETER IN ERROR * 00026000
03 DSQ-CANCEL-IND PIC X(1). 00027000
* 1 = COMMAND CANCELLED * 00028000
* 0 = COMMAND NOT CANCELLED * 00029000
03 DSQ-RESERVE2 PIC X(23). 00030000
03 DSQ-RESERVE3 PIC X(156). 00032000
03 DSQ-MESSAGE-TEXT PIC X(128). 00034000
* QMF MESSAGE TEXT * 00035000
03 DSQ-Q-MESSAGE-TEXT PIC X(128). 00036000
* QMF QUERY MESSAGE TEXT * 00037000
* 512 BYTES TOTAL * 00038000
00039000
00040000
* VALUES FOR DSQ-RETURN-CODE 00041000
00042000
01 DSQ-SUCCESS PIC 9(8) USAGE IS COMP VALUE 0. 00043000
01 DSQ-WARNING PIC 9(8) USAGE IS COMP VALUE 4. 00044000
01 DSQ-FAILURE PIC 9(8) USAGE IS COMP VALUE 8. 00045000
01 DSQ-SEVERE PIC 9(8) USAGE IS COMP VALUE 16. 00046000
00047000
* VALUES FOR DSQ-INSTANCE-ID 00048000
00049000
01 DSQ-CONTINUE PIC 9(8) USAGE IS COMP VALUE 0. 00050000
Figure 59. DSQCOMMB, the COBOL communications area (Part 1 of 2)

00051000
* VALUES FOR DSQ-COMM-LEVEL 00052000
00053000
01 DSQ-CURRENT-COMM-LEVEL PIC X(12) VALUE "DSQL>001002<". 00054000
00055000
* VALUES FOR DSQ-PRODUCT 00056000
00057000
01 DSQ-QRW PIC X(2) VALUE "01". 00058000
01 DSQ-QMF PIC X(2) VALUE "02". 00059000
01 DSQ-QM4 PIC X(2) VALUE "03". 00060000
00061000
* VALUES FOR DSQ-PRODUCT-RELEASE 00062000
00063000
01 DSQ-QRW-V1R2 PIC X(2) VALUE "01". 00064000
01 DSQ-QRW-V1R3 PIC X(2) VALUE "02". 00065000
01 DSQ-QMF-V2R4 PIC X(2) VALUE "01". 00066000
01 DSQ-QMF-V3R1M1 PIC X(2) VALUE "03". 00068000
01 DSQ-QM4-V1R1 PIC X(2) VALUE "01". 00072000
00073000
* VALUES FOR DSQ-CANCEL-INDE 00074000
00075000
01 DSQ-CANCEL-YES PIC X(1) VALUE "1". 00076000
01 DSQ-CANCEL-NO PIC X(1) VALUE "0". 00077000
00078000
* VALUES FOR MODE 00079000
00080000
01 DSQ-INTERACTIVE PIC X(1) VALUE "1". 00081000
01 DSQ-BATCH PIC X(1) VALUE "2". 00082000
00083000
* VALUES YES AND NO 00084000
00085000
01 DSQ-YES PIC X(1) VALUE "1". 00086000
01 DSQ-NO PIC X(1) VALUE "2". 00087000
00088000
* CALLABLE INTERFACE PROGRAM NAME 00089000
00090000
01 DSQCIB PIC X(6) VALUE "DSQCIB". 00091000
00092000
* VALUES FOR VARIABLE TYPE ON CALL PARAMETER 00093000
00094000
01 DSQ-VARIABLE-CHAR PIC X(4) VALUE "CHAR". 00095000
01 DSQ-VARIABLE-FINT PIC X(4) VALUE "FINT". 00096000
Figure 59. DSQCOMMB, the COBOL communications area (Part 2 of 2)
Considerations for running your COBOL callable interface program

interface, consider the following:
v The execution environment
QMF is run as an Assembler program in the COBOL environment. Your COBOL
program must call the QMF interface program, DSQCIB, using a COBOL
dynamic call.
v Whether to use quotation marks or apostrophes
You must use either double quotes (") or apostrophes (’) to delimit literals in a
COBOL program. You can specify the delimiter of your choice to the CICS
translation process and the COBOL compiler by specifying QUOTE or APOST. Make
sure the APOST or QUOTE option in effect for the COBOL compiler matches that
of the CICS translator.
The communications area (DSQCOMMB) and the sample COBOL program
(DSQABFCO) as distributed by QMF use quotes to delimit literals. If your site or
program uses apostrophes instead of quotes, change DSQCOMMB or copy the
structure to your program, changing quotes to apostrophes.
v Availability of the communications area (DSQCOMMB)
The communications area DSQCOMMB must be available to the COBOL compile
step or copied into your program as a control structure.
v Availability of the interface module (DSQCIB)
The QMF interface module must be available during the link-edit step of your
program.
Running your COBOL programs in CICS

After you write your program, you need to translate, compile, and link-edit it before
you can run it. The programs listed in this topic show the necessary steps.
The JCL and CLISTs in these examples are not provided with QMF, but you can
copy them from here, altering them to suit your needs.
The example in Figure 60 shows the CICS-supplied procedure DFHEBTVL, which

supports COBOL. See the CICS information in the IBM Publications Center at
www.ibm.com/shop/publications/order for details on how to translate programs for
use in CICS.
//samCOBOL JOB
// EXEC PROC=DFHEBTVL
//TRN.SYSIN DD *
*CBL XOPTS(CICS translator options ...QUOTE COBOL2)
.
Your program or copy of QMF sample DSQABFCO
.
/*
//* Provide Access to QMF Communications Macro DSQCOMMB
| //COB.SYSLIB DD DSN=QMF910.SDSQSAPE,DISP=SHR
//LKED.SYSIN DD *
INCLUDE CICSLOAD(DFHECI)
INCLUDE QMFLOAD(DSQCIB)
ORDER DFHECI
ENTRY samCOBOL
NAME samCOBOL(R)
/*
Figure 60. JCL to run the CICS translator, COBOL compiler, and linkage editor
Running your COBOL programs in TSO

This topic provides sample JCL to run the COBOL compiler and linkage editor and
sample programs for running your compiled programs in TSO either with or without
ISPF.


The job shown in Figure 61 uses the COBOL compiler to compile your callable
interface application. It then link-edits your application. Some parameters might vary
from one QMF installation to the next.
//samCOBOL JOB
//STEP1 EXEC PROC=IGYWCL
| //COBOL.SYSLIB DD DSN=QMF910.SAMPLIB,DISP=SHR
//COBOL.SYSIN DD *
.
Your program or copy of QMF sample DSQABFCO
.
/*
//LKED.SYSIN DD *
INCLUDE QMFLOAD(DSQCIB)
ENTRY samCOBOL
NAME samCOBOL(R)
/*
Figure 61. JCL to run the COBOL compiler and linkage editor

After you successfully compile your program, you can run it with JCL similar to the
example in Figure 62 on page 163:

PROC 0
CONTROL ASIS
/************************************************************/
/* Note: QMF, DB2, GDDM and COBOL load libraries must be */
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| /************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
CALL samCOBOL
EXIT CODE(0)
Figure 62. JCL to run the COBOL compiler and linkage editor in TSO without ISPF
Running your programs in TSO under ISPF

After you successfully compile your program, you can run it by writing a CLIST
similar to the one shown in Figure 63 on page 164:

FORTRAN language interface
PROC 0
CONTROL ASIS
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| /************************************************************/
/************************************************************/
’PRDUCT.COB2LIB’)
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
ISPSTART PGM(samCOBOL) NEWAPPL(DSQE)
EXIT CODE(4)
The EXIT CODE(4) suppresses the display of the ISPF disposition panel.

callable interface programs in FORTRAN. It also provides sample FORTRAN
source code and shows how to compile, link-edit, and run a FORTRAN program
using the callable interface.

Note to CICS users

Because FORTRAN is not available under CICS, the QMF callable interface
for FORTRAN does not work under CICS.
Interface communications area mapping for FORTRAN (DSQCOMMF)

DSQCOMMF provides DSQCOMM mapping for FORTRAN and is provided with the
product. Table 45 shows the information for DSQCOMMF, which you must not alter:
Table 45. Interface communications area for FORTRAN (DSQCOMMF)
DSQ_RETURN_CODE INTEGER Indicates the status of a QMF command after it has
been run. Its values are:
DSQ_SUCCESS
DSQ_WARNING
DSQ_FAILURE
DSQ_SEVERE
DSQ_INSTANCE_ID INTEGER Identifier established by QMF during execution of the
START command
DSQ_COMM_LEVEL CHARACTER(12) Identifies the level of the DSQCOMM; in your
application, include instructions that initialize this
variable to the value of
DSQ_CURRENT_COMM_LEVEL before issuing the
QMF START command.
DSQ_PRODUCT CHARACTER(2) Identifies the IBM query product in use (QMF)
DSQ_PRODUCT_RELEASE CHARACTER(2) Release level of QMF in use; values for supported
DSQ_QMF_V7R2
DSQ_QMF_V8R1
| DSQ_QMF_V9R1
DSQ_RESERVE1 CHARACTER(28) Reserved for future use
DSQ_MESSAGE_ID CHARACTER(8) Completion message ID
DSQ_Q_MESSAGE_ID CHARACTER(8) Query message ID
DSQ_START_PARM_ERROR CHARACTER(8) Parameter in error when START failed due to a
parameter error
DSQ_CANCEL_IND CHARACTER(1) Contains one of two values, depending on whether
the user canceled while a QMF command was
running:
v DSQ_CANCEL_YES
v DSQ_CANCEL_NO

Table 45. Interface communications area for FORTRAN (DSQCOMMF) (continued)

DSQ_MESSAGE_TEXT CHARACTER(128) Completion message text
DSQ_Q_MESSAGE_TEXT CHARACTER(128) Query message text
Function calls for FORTRAN

QMF provides two function calls for the FORTRAN language: DSQCIF and
DSQCIFE. Both calls are described in the communications area (DSQCOMMF).
DSQCIF
RC = DSQCIF(DSQCOMM,
+ CMDLTH,
+ CMDSTR)

DSQCOMM
The communications area
CMDLTH
Length of the command string (CMDSTR); it is an integer parameter
CMDSTR
QMF command to run; it is an uppercase character string of the length specified
by CMDLTH
DSQCIFE
This call has an extended syntax for the three commands that require access to
application program variables: START and the extended formats of GET GLOBAL
and SET GLOBAL.
The syntax for this call is:

RC = DSQCIFE(DSQCOMM,
+ CMDLTH,
+ CMDSTR,
+ PNUM,
+ KLTH,
+ KWORD,
+ VLTH,
+ VALUE,
+ VTYPE)

DSQCOMM
CMDLTH
Length of the command string (CMDSTR); it is an integer parameter
CMDSTR
by CMDLTH

PNUM
Number of command keywords; it is an integer parameter
KLTH
Length of each specified keyword; it is an integer parameter or parameter array
KWORD
QMF keyword or keywords; it is a character or array of characters whose
lengths are the same as specified by KLTH
You can use an array of characters if all of the keywords have the same length.
QMF assumes that the keywords are in contiguous storage and are not
separated by any special delimiters.
VLTH
Length of each value associated with the keyword; it is an integer parameter or
parameter array
VALUE
Value associated with each keyword
Its type is specified in the VTYPE parameter and can be a character, array of
characters, integer parameter, or parameter array. If you have character values,
QMF assumes that the values are in contiguous storage and are not separated
by any special delimiters.
VTYPE
types, which are provided in the communications area, DSQCOMMF:
v DSQ_VARIABLE_CHAR for character values
v DSQ_VARIABLE_FINT for integer values
in VTYPE.
FORTRAN programming example

The program shown in Figure 64 on page 168, DSQABFF, is provided with QMF.
The sample program is a member of the library QMF910.SDSQSAPn (where n is a
The sample program for the FORTRAN callable interface performs the following
functions:
v Starts QMF
objects.

C***********************************************************************
C Sample Program: dsqabff
C FORTRAN Version of Callable Interface
C
C Creation Date: 11/21/89
C
C ENVIRONMENT: API IN FORTRAN
C***********************************************************************
C
C Processing:
C a. Start a Query Manager Session using the Callable Interface.
C
C b. Set Global Query Manager numeric variables.
C
C d. Run a Query Manager query using the Callable Interface.
C
C e. Print a report using the Callable Interface.
C
C f. Exit the Query Manager Session.
C
C Prerequisites: 1. Create the SAMPLE database.
C
C 2. Create a prompted query, Q1, which has a SELECT state
C
C 3. Create a form, F1, that displays data for query Q1.
C
C***********************************************************************
PROGRAM DSQABFF
C***********************************************************************
C Include and declare query interface communications area
C***********************************************************************
INCLUDE (DSQCOMMF)
C**********************************************************************
C Query interface command lengths and commands
C**********************************************************************
INTEGER COMMAND_LENGTH
CHARACTER START_QUERY_INTERFACE*5,
+ SET_GLOBAL_VARIABLES*10,
+ RUN_QUERY*12,
+ PRINT_REPORT*22,
+ END_QUERY_INTERFACE*4
C**********************************************************************
C Query command extension, number of parameters and lengths
C**********************************************************************
INTEGER NUMBER_OF_PARAMETERS,
+ KEYWORD_LENGTHS(10),
+ DATA_LENGTHS(10)
Figure 64. DSQABFF, the sample FORTRAN program (Part 1 of 4)

C**********************************************************************
C Variable data type constants
C**********************************************************************
CHARACTER CHAR_DATA_TYPE*4,
+ INT_DATA_TYPE*4
C**********************************************************************
C Keyword parameter and value for START command
C**********************************************************************
CHARACTER*8 START_KEYWORDS(1)
CHARACTER*11 START_KEYWORD_VALUES(1)
C**********************************************************************
C Keyword parameter and values for SET command
C**********************************************************************
CHARACTER SET_KEYWORDS(19)
CHARACTER SET_KEYWORD_1*7,
+ SET_KEYWORD_2*5,
+ SET_KEYWORD_3*7
EQUIVALENCE (SET_KEYWORDS( 1), SET_KEYWORD_1),

+ (SET_KEYWORDS( 8), SET_KEYWORD_2),
+ (SET_KEYWORDS(13), SET_KEYWORD_3)
CHARACTER SET_VALUES(12)
INTEGER*4 SET_VALUE_1,
+ SET_VALUE_2,
+ SET_VALUE_3
EQUIVALENCE (SET_VALUES(1), SET_VALUE_1),

+ (SET_VALUES(5), SET_VALUE_2),
+ (SET_VALUES(9), SET_VALUE_3)
C***********************************************************************
C Declare command length and return code variables
C***********************************************************************
INTEGER LEN,
+ RC
C***********************************************************************
C Initialization
C***********************************************************************
DATA START_QUERY_INTERFACE /’START’ /

DATA SET_GLOBAL_VARIABLES /’SET GLOBAL’ /
DATA RUN_QUERY /’RUN QUERY Q1’ /
DATA PRINT_REPORT /’PRINT REPORT (FORM=F1)’/
DATA END_QUERY_INTERFACE /’EXIT’ /
DATA CHAR_DATA_TYPE /DSQ_VARIABLE_CHAR /

DATA INT_DATA_TYPE /DSQ_VARIABLE_FINT /

C**********************************************************
C Start Query Session
C**********************************************************
DSQ_COMM_LEVEL = DSQ_CURRENT_COMM_LEVEL
NUMBER_OF_PARAMETERS = 1
COMMAND_LENGTH = LEN(START_QUERY_INTERFACE)
KEYWORD_LENGTHS(1) = LEN(START_KEYWORDS(1))
DATA_LENGTHS(1) = LEN(START_KEYWORD_VALUES(1))
START_KEYWORDS(1) = ’DSQSMODE’
START_KEYWORD_VALUES(1) = ’INTERACTIVE’
+ COMMAND_LENGTH,
+ START_QUERY_INTERFACE,
+ NUMBER_OF_PARAMETERS,
+ KEYWORD_LENGTHS,
+ START_KEYWORDS,
+ DATA_LENGTHS,
+ START_KEYWORD_VALUES,
+ CHAR_DATA_TYPE)
C**********************************************************************
C Set numeric values into query using SET command
C**********************************************************************
NUMBER_OF_PARAMETERS = 3
COMMAND_LENGTH = LEN(SET_GLOBAL_VARIABLES)
SET_KEYWORD_1 = ’MYVAR01’
SET_KEYWORD_2 = ’SHORT’
SET_KEYWORD_3 = ’MYVAR03’
KEYWORD_LENGTHS(1) = LEN(SET_KEYWORD_1)
DATA_LENGTHS(1) = 4
DATA_LENGTHS(2) = 4
DATA_LENGTHS(3) = 4
SET_VALUE_1 = 20
SET_VALUE_2 = 40
SET_VALUE_3 = 84
+ COMMAND_LENGTH,
+ SET_GLOBAL_VARIABLES,
+ NUMBER_OF_PARAMETERS,
+ KEYWORD_LENGTHS,
+ SET_KEYWORDS,
+ DATA_LENGTHS,
+ SET_VALUES,
+ INT_DATA_TYPE)

C**********************************************************************
C Run a query
C**********************************************************************
COMMAND_LENGTH = LEN(RUN_QUERY)
+ COMMAND_LENGTH,
+ RUN_QUERY)
C**********************************************************************
C Print the results of the query
C**********************************************************************
COMMAND_LENGTH = LEN(PRINT_REPORT)
+ COMMAND_LENGTH,
+ PRINT_REPORT)
C**********************************************************************
C End the query interface session
C**********************************************************************
COMMAND_LENGTH = LEN(END_QUERY_INTERFACE)
+ COMMAND_LENGTH,
+ END_QUERY_INTERFACE)
END
DSQCOMM for FORTRAN

The interface communications area for FORTRAN, DSQCOMMF, is provided with
QMF and is shown in Figure 65 on page 172:

C********************************************************************** 00001000
C FORTRAN include file for Callable Interface 00002000
C********************************************************************** 00003000
C Return codes 00004000
INTEGER DSQ_SUCCESS, DSQ_WARNING, DSQ_FAILURE, DSQ_SEVERE 00005000
PARAMETER( 00006000
+ DSQ_SUCCESS = 0, 00007000
+ DSQ_WARNING = 4, 00008000
+ DSQ_FAILURE = 8, 00009000
+ DSQ_SEVERE = 16) 00010000
00011000
C Communications level 00012000
CHARACTER DSQ_CURRENT_COMM_LEVEL*12 00013000
PARAMETER( 00014000
+ DSQ_CURRENT_COMM_LEVEL = ’DSQL>001002<’) 00015000
00016000
C Query product IDs 00017000
CHARACTER DSQ_QRW*2, DSQ_QMF*2, DSQ_QM4*2 00018000
PARAMETER( 00019000
+ DSQ_QRW = ’01’, 00020000
+ DSQ_QMF = ’02’, 00021000
+ DSQ_QM4 = ’03’) 00022000
00023000
C Query product release levels 00024000
CHARACTER DSQ_QRW_V1R2*2, DSQ_QRW_V1R3*2, 00025000
+ DSQ_QMF_V2R4*2, DSQ_QMF_V3R1*2, 00026000
+ DSQ_QMF_V3R1M1*2, DSQ_QMF_V3R2*2, 00027000
+ DSQ_QMF_V3R3*2, DSQ_QMF_V6R1*2, 00028000
+ DSQ_QM4_V1R1*2 00029000
PARAMETER( 00030000
+ DSQ_QRW_V1R2 = ’01’, 00031000
+ DSQ_QRW_V1R3 = ’02’, 00032000
+ DSQ_QMF_V2R4 = ’01’, 00033000
+ DSQ_QMF_V3R1 = ’02’, 00034000
+ DSQ_QMF_V3R1M1 = ’03’, 00035000
+ DSQ_QMF_V3R2 = ’04’, 00036000
+ DSQ_QMF_V3R3 = ’05’, 00037000
+ DSQ_QMF_V6R1 = ’06’, 00038000
+ DSQ_QM4_V1R1 = ’01’) 00039000
00040000
C Host variable types 00041000
CHARACTER DSQ_VARIABLE_CHAR*4, DSQ_VARIABLE_FINT*4 00042000
PARAMETER( 00043000
+ DSQ_VARIABLE_CHAR = ’CHAR’, 00044000
+ DSQ_VARIABLE_FINT = ’FINT’) 00045000
00046000
C Cancel indicator 00047000
CHARACTER DSQ_CANCEL_YES, DSQ_CANCEL_NO 00048000
PARAMETER( 00049000
+ DSQ_CANCEL_YES = ’1’, 00050000
+ DSQ_CANCEL_NO = ’0’) 00051000
00052000
CHARACTER DSQCOMM(512) 00053000
Figure 65. DSQCOMMF, the FORTRAN interface communications area (Part 1 of 2)

INTEGER DSQ_RETURN_CODE, DSQ_INSTANCE_ID 00054000

CHARACTER DSQ_COMM_LEVEL*12, 00055000
+ DSQ_PRODUCT*2, 00056000
+ DSQ_PRODUCT_RELEASE*2, 00057000
+ DSQ_RESERVE1*28, 00058000
+ DSQ_MESSAGE_ID*8, 00059000
+ DSQ_Q_MESSAGE_ID*8, 00060000
+ DSQ_START_PARM_ERROR*8, 00061000
+ DSQ_CANCEL_IND*1, 00062000
+ DSQ_RESERVE2*23, 00063000
+ DSQ_RESERVE3*156, 00064000
+ DSQ_MESSAGE_TEXT*128, 00065000
+ DSQ_Q_MESSAGE_TEXT*128 00066000
00067000
EQUIVALENCE (DSQCOMM( 1), DSQ_RETURN_CODE ), 00068000
+ (DSQCOMM( 5), DSQ_INSTANCE_ID ), 00069000
+ (DSQCOMM( 9), DSQ_COMM_LEVEL ), 00070000
+ (DSQCOMM(21), DSQ_PRODUCT ), 00071000
+ (DSQCOMM(23), DSQ_PRODUCT_RELEASE ), 00072000
+ (DSQCOMM(25), DSQ_RESERVE1 ), 00073000
+ (DSQCOMM(53), DSQ_MESSAGE_ID ), 00074000
+ (DSQCOMM(61), DSQ_Q_MESSAGE_ID ), 00075000
+ (DSQCOMM(69), DSQ_START_PARM_ERROR ), 00076000
+ (DSQCOMM(77), DSQ_CANCEL_IND ), 00077000
+ (DSQCOMM(257), DSQ_MESSAGE_TEXT ), 00080000
+ (DSQCOMM(385), DSQ_Q_MESSAGE_TEXT ) 00081000
00082000
C Callable Interface Normal and Extended Calls 00083000
EXTERNAL DSQCIF 00084000
EXTERNAL DSQCIFE 00085000
Figure 65. DSQCOMMF, the FORTRAN interface communications area (Part 2 of 2)
Running your FORTRAN programs

After you write your program, you need to compile and link-edit it in TSO before you
can run it. The programs listed in this topic show the steps necessary to do so.
Compiling and link-editing your program

The job shown in Figure 66 on page 174 compiles and link-edits your callable
interface application using the FORTRAN compiler for z/OS. Some parameters can
vary from one QMF installation to the next.

//samFORT JOB
//STEP1 EXEC PROC=VSF2CL
| //FORT.SYSLIB DD DSN=QMF910.SAMPLIB,DISP=SHR
//FORT.SYSIN DD *
.
Your program or copy of QMF sample DSQABFF
.
/*
//LKED.SYSIN DD *
INCLUDE QMFLOAD(DSQCIF)
INCLUDE QMFLOAD(DSQCIFE)
ENTRY samFORT
NAME samFORT(R)
/*
Figure 66. JCL for running the FORTRAN compiler and linkage editor

The program shown in Figure 67 on page 175 runs your callable interface
application using the FORTRAN compiler. Some parameters can vary from one
QMF installation to the next.

PROC 0
CONTROL ASIS
/************************************************************/
/* Note: QMF, DB2, GDDM and FORTRAN load libraries must be */
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| /************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
CALL samFORT
EXIT CODE(0)
Figure 67. CLIST for running your program in TSO without ISPF
Running in TSO under ISPF

The CLIST shown in Figure 68 on page 176 runs your callable interface application
using the FORTRAN compiler. Some parameters can vary from one QMF
installation to the next.

PL/I language interface
PROC 0
CONTROL ASIS
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| /************************************************************/
/************************************************************/
’PRDUCT.VSF2LOAD’)
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
ISPSTART PGM(samFORT) NEWAPPL(DSQE)
EXIT CODE(4)
The EXIT CODE(4) suppresses the showing of the ISPF disposition panel.

callable interface programs in PL/I. It also provides a sample PL/I program and also
shows how to compile, link-edit, and run a PL/I program using the callable interface.

Interface communications area mapping for PL/I (DSQCOMML)

DSQCOMML provides DSQCOMM mapping for PL/I and is provided with the
product. Table 46 shows the values for DSQCOMML.
Table 46. Interface communications area for PL/I (DSQCOMML)
DSQ_RETURN_CODE FIXED BIN(31) Indicates the status of a QMF command after it has been
run. Its values are:
DSQ_SUCCESS
DSQ_WARNING
DSQ_FAILURE
DSQ_SEVERE
DSQ_INSTANCE_ID FIXED BIN(31) Identifier established by QMF during execution of the
START command
DSQ_COMM_LEVEL CHAR(12) Identifies the level of the DSQCOMM communications
area; in your application, include instructions that initialize
this variable to the value of
DSQ_CURRENT_COMM_LEVEL before issuing the QMF
START command.
DSQ_PRODUCT CHAR(2) Identifies the IBM query product in use (QMF).
DSQ_PRODUCT_RELEASE CHAR(2) Release level of QMF in use; values for supported
DSQ_QMF_V7R2
DSQ_QMF_V8R1
| DSQ_QMF_V9R1
DSQ_RESERVE1 CHAR(28) Reserved for future use
DSQ_MESSAGE_ID CHAR(8) Completion message ID
DSQ_Q_MESSAGE_ID CHAR(8) Query message ID
DSQ_START_PARM_ERROR CHAR(8) Parameter in error when START failed due to a
parameter error
DSQ_CANCEL_IND CHAR(1) Contains one of two values, depending on whether the
v DSQ_CANCEL_YES
v DSQ_CANCEL_NO
DSQ_MESSAGE_TEXT CHAR(128) Completion message text
DSQ_Q_MESSAGE_TEXT CHAR(128) Query message text

Function calls for PL/I

QMF provides two function calls for PL/I: DSQCIPL and DSQCIPX. Both calls are
described in the communications area (DSQCOMML).
DSQCIPL syntax
CALL DSQCIPL(DSQCOMM,
CMDLTH,
CMDSTR)

DSQCOMM
CMDLTH
Length of the command string (CMDSTR)
CMDSTR
by CMDLTH
DSQCIPX syntax
This call is for the three commands that require access to application program
variables: START and the extended formats of GET GLOBAL and SET GLOBAL.
The syntax for this call is:

CALL DSQCIPX(DSQCOMM,
CMDLTH,
CMDSTR,
PNUM,
KLTH,
KWORD,
VLTH,
VALUE,
VTYPE)

DSQCOMM
CMDLTH
Length of the command string (CMDSTR); it is an integer FIXED BIN(31)
parameter
CMDSTR
by CMDLTH
PNUM
Number of command keywords; it is an integer FIXED BIN(31) parameter
KLTH
Length of each specified keyword; it is an integer FIXED BIN(31) parameter or
parameter array
KWORD
QMF keyword or keywords; each is a character or array of characters whose
lengths are specified by KLTH

You can use an array of characters if all of the keywords have the same length.
QMF assumes that the keywords are in contiguous storage and are not
separated by any special separator characters.
VLTH
Length of each value associated with the keyword; it is an integer FIXED
BIN(31) parameter or parameter array
VALUE
Value associated with each keyword
Its type is specified in the VTYPE parameter and can be a character, array of
characters, integer FIXED BIN(31) parameter, or parameter array. If you have
character values, QMF assumes that the values are in contiguous storage and
are not separated by any special delimiters.
VTYPE
types, which are provided in the DSQCOMML communications area:
v DSQ_VARIABLE_CHAR for character values
v DSQ_VARIABLE_FINT for integer FIXED BIN(31) values
in VTYPE.
PL/I programming example

The sample program shown in Figure 69 on page 180, DSQABFP, is provided with
QMF and uses PL/I.
You can look at the sample source code here or you can access it online. The
sample program is a member of the library QMF910.SDSQSAPn (where n is a
The sample program for the PL/I callable interface performs the following functions:
v Starts QMF
objects.

DSQABFP: PROCEDURE OPTIONS(MAIN REENTRANT) REORDER; 00001000

/********************************************************************/ 00002000
/* Sample Program: DSQABFP */ 00003000
/* PL/I Version of the QMF Callable Interface */ 00004000
/********************************************************************/ 00005000
00006000
/********************************************************************/ 00007000
/* Include and declare query interface communications area */ 00008000
/********************************************************************/ 00009000
%INCLUDE SYSLIB(DSQCOMML); 00010000
00011000
/********************************************************************/ 00012000
/* Builtin function */ 00013000
/********************************************************************/ 00014000
DCL LENGTH BUILTIN; 00015000
00016000
/********************************************************************/ 00017000
/* Query interface command length and commands */ 00018000
/********************************************************************/ 00019000
DCL COMMAND_LENGTH FIXED BIN(31); 00020000
DCL START_QUERY_INTERFACE CHAR(5) INIT(’START’); 00021000
DCL SET_GLOBAL_VARIABLES CHAR(10) INIT(’SET GLOBAL’); 00022000
DCL RUN_QUERY CHAR(12) INIT(’RUN QUERY Q1’); 00023000
DCL PRINT_REPORT CHAR(22) INIT(’PRINT REPORT (FORM=F1)’); 00024000
DCL END_QUERY_INTERFACE CHAR(4) INIT(’EXIT’); 00025000
00026000
/********************************************************************/ 00027000
/* Query command extension, number of parameters and lengths */ 00028000
/********************************************************************/ 00029000
DCL NUMBER_OF_PARAMETERS FIXED BIN(31);/* number of variables */ 00030000
DCL KEYWORD_LENGTHS(10) FIXED BIN(31);/* lengths of keyword names*/ 00031000
DCL DATA_LENGTHS(10) FIXED BIN(31);/* lengths of variable data*/ 00032000
00033000
/********************************************************************/ 00034000
/* Keyword parameter and value for START command */ 00035000
/********************************************************************/ 00036000
DCL START_KEYWORDS CHAR(8) INIT(’DSQSMODE’); 00037000
DCL START_KEYWORD_VALUES CHAR(11) INIT(’INTERACTIVE’); 00038000
00039000
/********************************************************************/ 00040000
/* Keyword parameter and value for SET command */ 00041000
/********************************************************************/ 00042000
DCL 1 SET_KEYWORDS, 00043000
3 SET_KEYWORDS_1 CHAR(7) INIT(’MYVAR01’), 00044000
3 SET_KEYWORDS_2 CHAR(5) INIT(’SHORT’), 00045000
3 SET_KEYWORDS_3 CHAR(7) INIT(’MYVAR03’); 00046000
00047000
DCL 1 SET_VALUES, 00048000
3 SET_VALUES_1 FIXED BIN(31), 00049000
3 SET_VALUES_2 FIXED BIN(31), 00050000
3 SET_VALUES_3 FIXED BIN(31); 00051000
00052000
Figure 69. DSQABFP, the sample PL/I program (Part 1 of 3)

/********************************************************************/ 00053000
/* Main program */ 00054000
/********************************************************************/ 00055000
DSQCOMM = ’’; 00056000
DSQ_COMM_LEVEL = DSQ_CURRENT_COMM_LEVEL; 00057000
00058000
/********************************************************************/ 00059000
/* Start a query interface session */ 00060000
/********************************************************************/ 00061000
NUMBER_OF_PARAMETERS = 1; 00062000
COMMAND_LENGTH = LENGTH(START_QUERY_INTERFACE); 00063000
KEYWORD_LENGTHS(1) = LENGTH(START_KEYWORDS); 00064000
DATA_LENGTHS(1) = LENGTH(START_KEYWORD_VALUES); 00065000
00066000
CALL DSQCIPX(DSQCOMM, 00067000
COMMAND_LENGTH, 00068000
START_QUERY_INTERFACE, 00069000
NUMBER_OF_PARAMETERS, 00070000
KEYWORD_LENGTHS, 00071000
START_KEYWORDS, 00072000
DATA_LENGTHS, 00073000
START_KEYWORD_VALUES, 00074000
DSQ_VARIABLE_CHAR); 00075000
00076000
/********************************************************************/ 00077000
/* Set numeric values into query using SET command */ 00078000
/********************************************************************/ 00079000
NUMBER_OF_PARAMETERS = 3; 00080000
COMMAND_LENGTH = LENGTH(SET_GLOBAL_VARIABLES); 00081000
KEYWORD_LENGTHS(1) = LENGTH(SET_KEYWORDS_1); 00082000
DATA_LENGTHS(1) = 4; 00085000
DATA_LENGTHS(2) = 4; 00086000
DATA_LENGTHS(3) = 4; 00087000
SET_VALUES_1 = 20; 00088000
SET_VALUES_2 = 40; 00089000
SET_VALUES_3 = 84; 00090000
00091000
CALL DSQCIPX(DSQCOMM, 00092000
SET_GLOBAL_VARIABLES, 00094000
NUMBER_OF_PARAMETERS, 00095000
KEYWORD_LENGTHS, 00096000
SET_KEYWORDS, 00097000
DATA_LENGTHS, 00098000
SET_VALUES, 00099000
DSQ_VARIABLE_FINT); 00100000
00101000
/********************************************************************/ 00102000
/* Run a Query */ 00103000
/********************************************************************/ 00104000
COMMAND_LENGTH = LENGTH(RUN_QUERY); 00105000
00106000
CALL DSQCIPL(DSQCOMM, 00107000
RUN_QUERY); 00109000
00110000

/********************************************************************/ 00111000
/* Print the results of the query */ 00112000
/********************************************************************/ 00113000
COMMAND_LENGTH = LENGTH(PRINT_REPORT); 00114000
00115000
PRINT_REPORT); 00118000
00119000
/********************************************************************/ 00120000
/* End the query interface session */ 00121000
/********************************************************************/ 00122000
COMMAND_LENGTH = LENGTH(END_QUERY_INTERFACE); 00123000
00124000
END_QUERY_INTERFACE); 00127000
00128000
END DSQABFP; 00129000
DSQCOMM for PL/I

Figure 70 on page 183 shows the interface communications area for PL/I.

/********************************************************************/ 00001000
/* PL/I include for Query Callable Interface */ 00002000
/********************************************************************/ 00003000
00004000
/* Structure declare for Communications Area */ 00005000
DCL 00006000
1 DSQCOMM, 00007000
3 DSQ_RETURN_CODE FIXED BIN(31), /* function return code */ 00008000
3 DSQ_INSTANCE_ID FIXED BIN(31), /* start ID */ 00009000
3 DSQ_COMM_LEVEL CHAR(12), /* communications level */ 00010000
3 DSQ_PRODUCT CHAR(2), /* query product id */ 00011000
3 DSQ_PRODUCT_RELEASE CHAR(2), /* query product release */ 00012000
3 DSQ_RESERVE1 CHAR(28), /* reserved */ 00013000
3 DSQ_MESSAGE_ID CHAR(8), /* completion message ID */ 00014000
3 DSQ_Q_MESSAGE_ID CHAR(8), /* query message ID */ 00015000
3 DSQ_START_PARM_ERROR CHAR(8), /* start parms in error */ 00016000
3 DSQ_CANCEL_IND CHAR(1), /* cmd cancel indicator */ 00017000
/* 1 = cancelled, 0 = not cancelled*/ 00018000
3 DSQ_MESSAGE_TEXT CHAR(128), /* QMF command message */ 00021000
3 DSQ_Q_MESSAGE_TEXT CHAR(128); /* QMF query message */ 00022000
00023000
/* Return Codes */ 00024000
DCL 00025000
DSQ_SUCCESS FIXED BIN(31) INIT(0) STATIC, 00026000
DSQ_WARNING FIXED BIN(31) INIT(4) STATIC, 00027000
DSQ_FAILURE FIXED BIN(31) INIT(8) STATIC, 00028000
DSQ_SEVERE FIXED BIN(31) INIT(16) STATIC; 00029000
00030000
/* Communications Level */ 00031000
DCL 00032000
DSQ_CURRENT_COMM_LEVEL CHAR(12) INIT(’DSQL>001002<’) STATIC; 00033000
00034000
/* Query Product ID */ 00035000
DCL 00036000
DSQ_QRW CHAR(2) INIT(’01’) STATIC, 00037000
DSQ_QMF CHAR(2) INIT(’02’) STATIC, 00038000
DSQ_QM4 CHAR(2) INIT(’03’) STATIC; 00039000
00040000
Figure 70. DSQCOMML, the PL/I interface communications area (Part 1 of 2)

/* Query Product Release ID */ 00041000

DCL 00042000
DSQ_QRW_V1R2 CHAR(2) INIT(’01’) STATIC, 00043000
DSQ_QRW_V1R3 CHAR(2) INIT(’02’) STATIC, 00044000
DSQ_QMF_V2R4 CHAR(2) INIT(’01’) STATIC, 00045000
DSQ_QMF_V3R1M1 CHAR(2) INIT(’03’) STATIC, 00047000
DSQ_QM4_V1R1 CHAR(2) INIT(’01’) STATIC; 00051000
00052000
/* Cancelled Indicator */ 00053000
DCL 00054000
DSQ_CANCEL_YES CHAR(1) INIT(’1’) STATIC, 00055000
DSQ_CANCEL_NO CHAR(1) INIT(’0’) STATIC; 00056000
00057000
/* Variable Types */ 00058000
DCL 00059000
DSQ_VARIABLE_CHAR CHAR(4) INIT(’CHAR’) STATIC, 00060000
DSQ_VARIABLE_FINT CHAR(4) INIT(’FINT’) STATIC; 00061000
00062000
/* Mode */ 00063000
DCL 00064000
DSQ_INTERACTIVE CHAR(1) INIT(’1’) STATIC, 00065000
DSQ_BATCH CHAR(1) INIT(’2’) STATIC; 00066000
00067000
/* Yes or No */ 00068000
DCL 00069000
DSQ_YES CHAR(1) INIT(’1’) STATIC, 00070000
DSQ_NO CHAR(1) INIT(’2’) STATIC; 00071000
00072000
/* Query Interface Entry Point */ 00073000
DCL 00074000
DSQCIPL ENTRY (*, /* interface block */ 00075000
FIXED BIN(31), /* length of command */ 00076000
CHAR(*)) /* command string */ 00077000
EXTERNAL OPTIONS(ASSEMBLER); 00078000
DCL 00079000
DSQCIPX ENTRY (*, /* interface block */ 00080000
FIXED BIN(31), /* length of command */ 00081000
CHAR(*), /* command string */ 00082000
FIXED BIN(31), /* # of command keywords */ 00083000
*, /* length of keyword */ 00084000
*, /* keyword string */ 00085000
*, /* length of value */ 00086000
*, /* value of keyword */ 00087000
CHAR(4)) /* data type of value */ 00088000
EXTERNAL OPTIONS(ASSEMBLER); 00089000
Figure 70. DSQCOMML, the PL/I interface communications area (Part 2 of 2)
Running your programs under CICS

After writing your program, you need to compile and run it. The examples in this
topic show the necessary steps for CICS.

interface, consider the following:
v The communications area (DSQCOMML) must be available in the compile step
or copied into your program.
v The QMF interface modules DSQCIPL and DSQCIPX must be available during
the link-edit step of your program.
Figure 71 shows an example using the CICS-supplied procedure DFHEBTPL.
//samPLI JOB
// EXEC PROC=DFHEBTPL
//TRN.SYSIN DD *
*PROCESS XOPTS(CICS translator options .....)
.
Your program or copy of QMF sample DSQABFP
.
/*
//* Provide Access to QMF Communications Macro DSQCOMML
| //PLI.SYSLIB DD DSN=QMF910.SDSQSAPE,DISP=SHR
//LKED.SYSIN DD *
INCLUDE CICSLOAD(DFHPL1OI)
INCLUDE CICSLOAD(DFHEPI)
INCLUDE QMFLOAD(DSQCIPL)
INCLUDE QMFLOAD(DSQCIPX)
ORDER DFHPL1OI,DFHEPI
ENTRY sampPLI
NAME sampPLI(R)
/*
Figure 71. JCL for running the CICS translator, PL/I compiler, and linkage editor
Running your programs under TSO

After writing your program, you need to compile and run it. The examples in this
topic show the necessary steps for TSO.

The job shown in Figure 72 on page 186 uses the PL/I compiler to compile your
callable interface application and then link-edits the application. Some parameters
can vary from one QMF installation to the next.

//samPLI JOB
//STEP1 EXEC IEL1CL
//* Provide Access to QMF Communications Macro DSQCOMML
| //PLI.SYSLIB DD DSN=QMF910.SAMPLIB,DISP=SHR
//PLI.SYSIN DD *
.
Your program or copy of QMF sample DSQABFP
.
/*
//LKED.SYSIN DD *
INCLUDE QMFLOAD(DSQCIPL)
INCLUDE QMFLOAD(DSQCIPX)
ENTRY sampPLI
NAME sampPLI(R)
/*
Figure 72. JCL to run the PL/I compiler and linkage editor
Running in TSO without ISPF

After you compile your program for the TSO environment, the CLIST shown in
Figure 73 on page 187 runs your program:

PROC 0
CONTROL ASIS
/************************************************************/
/* Note: QMF, DB2, GDDM and PL/I load libraries must be */
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| /************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
CALL sampPLI
EXIT CODE(0)
Figure 73. CLIST to run your program in TSO without ISPF
Running in TSO under ISPF

After you compile your program for the TSO environment, a CLIST like the one
shown in Figure 74 on page 188 runs your program:

REXX language interface
PROC 0
CONTROL ASIS
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
| /************************************************************/
/************************************************************/
’PLI.PLILINK’,’PLI.SIBMLINK’)
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
/************************************************************/
ISPSTART PGM(sampPLI) NEWAPPL(DSQE)
EXIT CODE(4)

Note to CICS users

Because REXX is not available under QMF for CICS, the QMF callable
interface for REXX does not work under CICS.
REXX is an interpretive language; it does not have to be compiled. However,

programs written using compiled REXX or other compiled languages have better
performance than the same programs written using interpretive REXX. A REXX
compiler is available for REXX programs, but not for procedures with logic.
Under TSO, you can reduce the resources required to use REXX services when
you use procedures with logic and certain QMF form functions (calculations, defined
columns, and conditions) by invoking QMF using the REXX callable interface.
For example, fewer resources are required to perform PRINT REPORT or BOTTOM
on the REPORT panel if the QMF session is initiated using the REXX callable
interface. The reduction of resource consumption can be substantial and is most
noticeable when running QMF under TSO.
The REXX language always operates in a command environment that determines

how and where the command is processed. If you write a REXX program that
issues QMF commands, you can use the QMF command environment through the
ADDRESS QRW command. For more information, see Chapter 5, “ADDRESS
QRW: Using the QMF command environment,” on page 29.
Interface communications variables for REXX

The interface communications variables consist of the REXX variables shown in
Table 47. They are set after the completion of every call and must not be altered by
the calling program.
Table 47. Interface communications variables for REXX
Structure name Description
dsq_return_code Integer that indicates the results of executing a QMF
command. Possible values are:
dsq_success
Successful processing of the request
dsq_warning
dsq_failure
Command did not process correctly
dsq_severe
Severe error forcing the QMF session to end;
additional calls to QMF cannot be made using this
instance ID
The value of dsq_return_code is also placed in the REXX
variable rc.
dsq_instance_id Identifier that is established by QMF during processing of the
START command
dsq_product Query manager product in use; the only valid value is
dsq_qmf

Table 47. Interface communications variables for REXX (continued)

Structure name Description
dsq_product_release Release level of QMF in use; values for supported releases
are as follows:
dsq_qmf_v7r2
dsq_qmf_v8r1
| dsq_qmf_v9r1
dsq_message_id Completion message ID
dsq_q_message_id Query message ID
dsq_start_parm_error Parameter in error when START failed due to a parameter
error
dsq_cancel_ind Command cancel indicator that indicates whether the user
canceled command processing while QMF was running a
command; possible values are:
dsq_cancel_yes
The user canceled the command
dsq_cancel_no
The user did not cancel the command
dsq_message_text Completion message text
dsq_q_message_text Query message text
Function call for REXX

The callable interface is accessed by using normal REXX function calls. QMF
provides an external subroutine called DSQCIX, which is used to run all QMF
commands issued through the callable interface.
The syntax for the DSQCIX function call is as follows:

call DSQCIX cmd parmlist
In the above syntax:

v cmd is a QMF command written as an uppercase character string.
v parmlist is a list of parameter and value pairs, as shown in the following diagram:
( parmname = value
)
The entire command, including the parmlist, should be passed to QMF as a single
REXX variable written as a character string. This string must be enclosed in
quotation marks (' ') or (" "). When using REXX variables as part of the command
string, don’t enclose the argument. For example:
CALL DSQCIX "RUN QUERY NAME (&ECN="REXAUG",CONFIRM=YES)"

parmname
Name of a parameter
value
Value that is to be associated with the parameter name specified by parmname
Here are some examples of function calls:

call DSQCIX "RUN QUERY Q1"
call DSQCIX "PRINT REPORT (FORM=F1"
call DSQCIX "EXIT"
In the parmlist, the same results occur whether the following elements are present
or not:
v Comma (,) between parameters (a space produces the same result).
v Closing parenthesis (which is not required).
v Equal sign (=) between parmname and value (a space produces the same
result).
Each of the following would produce the same results:

call dsqcix "SET GLOBAL (abc=17, def=26"
call dsqcix "SET GLOBAL ( abc=17 def=26"
call dsqcix "SET GLOBAL ( abc=17 , def=26)"
call dsqcix "SET GLOBAL (abc 17 def=26)"
REXX programming example

The program shown in Figure 75 on page 192, DSQABFX, is provided with QMF.
The sample program is a member of the library QMF910.SDSQEXCE.
The sample program for the REXX callable interface performs the following
functions:
v Starts QMF
objects.

/*REXX***************************************************************/
/* Sample Program: DSQABFX */
/* REXX Version of the QMF Callable Interface */
/********************************************************************/
/********************************************************************/
/* Start a query interface session */
/********************************************************************/
call dsqcix "START (DSQSMODE=INTERACTIVE"

say dsq_message_id dsq_message_text
if dsq_return_code = dsq_severe then exit dsq_return_code
/********************************************************************/
/* Set numeric values into query using SET command */
/********************************************************************/
call dsqcix "SET GLOBAL (MYVAR01=20,SHORT=40,MYVAR03=84"

/********************************************************************/
/* Run a Query */
/********************************************************************/
call dsqcix "RUN QUERY Q1"

/********************************************************************/
/* Print the results of the query */
/********************************************************************/
call dsqcix "PRINT REPORT (FORM=F1)"

/********************************************************************/
/* End the query interface session */
/********************************************************************/
call dsqcix "EXIT"

Figure 75. DSQABFX, the sample REXX program
Running your REXX programs

You can run your REXX program in TSO by writing a program similar to the one

/*****************************************************************/
/* Issue TSO Allocates for QMF Product */
/*****************************************************************/
Address TSO
"ATTR PRINTDCB LRECL(133) RECFM(F B A) BLKSIZE(1330)"

"ATTR DEBUGDCB LRECL(80) RECFM(F B) BLKSIZE(3120)"
"ATTR UDUMPDCB LRECL(125) RECFM(V B A) BLKSIZE(1632)"
"ATTR EDITDCB LRECL(79) RECFM(F B A) BLKSIZE(4029)"
"ALLOC FI(SYSPROC) SHR REUSE ",
| "DA(’QMF910.DSQCLSTE,’",
"’DSN.DSNCLIST’)"
"ALLOC FI(SYSEXEC) SHR REUSE ",
| "DA(’QMF910.SDSQEXCE’)"
"ALLOC FI(ISPLLIB) SHR REUSE ",
| "DA(’QMF910.SDSQLOAD,’",
"’ADM.GDDM.GDDMLOAD,’",
"’DSN.DSNLOAD’)"
| "ALLOC FI(DSQPNLE) DA(’QMF910.DSQPNLE’) SHR REUSE"
"ALLOC FI(DSQPRINT) SYSOUT USING(PRINTDCB)"
"ALLOC FI(SYSPRT) SYSOUT(X) LRECL(132) RECFM(FBA) BLKSIZE(132)"
"ALLOC FI(DSQDEBUG) SYSOUT(X) USING(DEBUGDCB)"
"ALLOC FI(DSQUDUMP) SYSOUT(X) USING(UDUMPDCB)"
"ALLOC FI(DSQSPILL) NEW UNIT(SYSDA) SPACE(1,1) TRACKS"
"ALLOC DDNAME(DSQEDIT) UNIT(SYSDA) NEW USING(EDITDCB)"
"ALLOC FI(ADMDEFS) DA(’ADM.GDDM.NICKNAME’) SHR REUSE"
| "ALLOC FI(ADMGGMAP) DA(’QMF910.SDSQMAPE’) SHR REUSE"
| "ALLOC FI(ADMCFORM) DA(’QMF910.DSQCHART’) SHR REUSE"
| "ALLOC FI(DSQUCFRM) DA(’QMF910.DSQUCFRM’) SHR REUSE"
| "ALLOC FI(ADMGDF) DA(’GDDM.ADMGDF’) SHR REUSE"
"ALLOC FI(ADMSYMBL) DA(’ADM.GDDM.GDDMSYM’) SHR REUSE"
/* The beginning of your REXX program ..... */

.
.
.
/* The end of your REXX program ........ */
Figure 76. REXX program to run your application in TSO
A REXX example of using an INTERACT loop

Normally, when your callable interface program issues an INTERACT command and
the user issues the END command, QMF immediately returns control to your
program. However, interactive QMF allows the user to issue the END command to
return to the QMF home panel. Issuing the END command a second time ends the
QMF session.
By adding the logic shown in Figure 77 on page 194 to your program, you can
make the END command in an interactive session (started by the INTERACT
command from a callable interface program) behave similarly to the way END
behaves in interactive QMF.
This program uses dsq_message_id to determine how to proceed. These values

can change from one release to the next.
This program is not distributed with QMF.

/*REXX*************************************************************/
/* Sample Program: Using INTERACT loop */
/******************************************************************/
/******************************************************************/
/* Start an interactive QMF session */
/******************************************************************/
trace error
parms = "START (DSQSMODE=INTERACTIVE"

call dsqcix parms
/******************************************************************/
/* SET GLOBAL to show panel IDs */
/******************************************************************/
call dsqcix "SET GLOBAL (DSQDC_SHOW_PANID=1"
/******************************************************************/
/* Issue message */
/******************************************************************/
call dsqcix "MESSAGE (TEXT=’Ok, You may enter a command.’)"
/******************************************************************/
/* INTERACT loop */
/******************************************************************/
Continue = "yes"
Do while continue = "yes"
call DSQCIX "INTERACT"
Select
When (dsq_return_code = dsq_severe) Then /* Severe Error */
Continue = "no"
When (dsq_message_id = "DSQ21869") Then /* END from HOME panel */
Continue = "no"
When (dsq_message_id = "DSQ90557") Then /* User issued EXIT */
Continue = "no"
Otherwise nop /* OK continue session */
End
End
/******************************************************************/
/* End the session */
/******************************************************************/
if dsq_message_id <> "DSQ90557" then /* EXIT not issued */
call dsqcix "EXIT" /* Issue EXIT */
Figure 77. REXX program that uses an INTERACT loop

Appendix B. Product interface macros
Table 48 lists macros that are provided with QMF as General-Use Programming
Interfaces for customers.
Warning: Do not use any QMF macros as programming interfaces other than those
identified in this topic.
Table 48. Macros that provide interfaces to QMF functions
Purpose Macro names
Product interface macro DSQQMFn
In this program name, n is the one-character

NLF identifier (NLID) from Table 1 on page
vii. For English, this identifier is E.
Callable interface macros v Assembler
– DSQCIA
– DSQCOMMA
v COBOL
– DSQCIB
– DSQCOMMB
v C/C++
– DSQCIC
– DSQCICE
– DSQCOMMC
v FORTRAN
– DSQCIF
– DSQCIFE
– DSQCOMMF
v PL/I
– DSQCIPL
– DSQCIPX
– DSQCOMML
v REXX
– DSQCIX
Command interface macro DSQCCI
QMF governor exit routine interface macros v DXEGOVA
v DXEXCBA
QMF user edit exit routine macro DXEECS

Product interface macros

Appendix C. QMF global variable tables
QMF provides many variables for use in your applications. This topic explains:
v “Naming conventions for global variables”
v “Global variables for profile-related state information” on page 198
v “Global variables for state information not related to the profile” on page 199
v “Global variables associated with CICS” on page 202
v “Global variables related to a message produced by the most recent command”
on page 203
v “Global variables associated with the Table Editor” on page 203
v “Global variables that control various displays” on page 205
v “Global variables that control how commands and procedures are executed” on
page 208
v “Global variables that store results of CONVERT QUERY” on page 211
v “Global variables that show RUN QUERY error message information” on page
211
Naming conventions for global variables

QMF provides a procedure named Q.SYSTEM_INI that allows you to customize
global variables at initialization.
Callable interface users can use global variable names that are 18 characters or
less. Command interface users must use names that are 8 characters or less.
The naming convention for global variables is DSQcc_xxxxxxxxxxxx, where:

cc Can be any one of the following category identifiers:
AP Variables for profile-related state information
AO Variables for other (not profile-related) state information
CM Variables for information about the message produced by the
previous command
CP Variables for information about the Table Editor
DC Variables that control how QMF displays information on the screen
EC Variables that control how QMF executes commands and
procedures
QC Variables whose values are produced by a CONVERT QUERY
option
QM Variables that contain RUN QUERY error message information
QW Variables unique to QMF for Workstation (see Getting Started with
DB2 QMF for Workstation and DB2 QMF for WebSphere for more
information about these variables)
_ An underscore character
xxxxxxxxxxxx
A descriptive name up to 12 characters long

QMF global variables
Global variables for profile-related state information

Table 49 shows the set of global variables that stores information related to the
QMF profile settings. None of these global variables can be modified by the SET
GLOBAL command.
Table 49. Global variables for profile-related state information
Command interface variable
Callable interface variable name name Length Description
DSQAP_CASE DSQAPCAS 01 CASE parameter; values can be:
1 for UPPER
2 for MIXED
3 for STRING
| If your site uses RACF support for

| mixed-case passwords under TSO, set this
| value to 2; otherwise, all input (including
| passwords) is converted to uppercase,
| causing the CONNECT command to fail.
| When you set CASE to MIXED, ensure that
| you enter all input in uppercase, because
| QMF only recognizes commands in
| uppercase.
DSQAP_CONFIRM DSQAPRMP 01 CONFIRM parameter; values can be:
0 for NO
1 for YES
DSQAP_DECIMAL DSQAPDEC 01 DECIMAL parameter; values can be:
1 for PERIOD
2 for COMMA
3 for FRENCH
DSQAP_LENGTH DSQAPLEN 18 LENGTH parameter; its value is that of the
parameter ('1' through '999' or 'CONT').
DSQAP_PFKEY_TABLE DSQAPPFK 31 Name of the function keys table.
DSQAP_PRINTER DSQAPPRT 08 PRINTER parameter; values can be:
v A nickname for a GDDM printer.
v Blanks for the printer associated with
DSQPRINT.
DSQAP_QUERY_LANG DSQAPLNG 01 LANGUAGE parameter; values can be:
1 for SQL
2 for QBE
3 for PROMPTED
DSQAP_QUERY_MODEL DSQAMODP 01 MODEL parameter (value is '1' for relational).
DSQAP_RESOURC_GRP DSQAPGRP 16 RESOURCE GROUP parameter.
DSQAP_SPACE DSQAPSPC 50 SPACE parameter; its value is that of the
parameter.
DSQAP_SYNONYM_TBL DSQAPSYN 31 Name of the synonyms table being used for
the current QMF session.

Table 49. Global variables for profile-related state information (continued)

DSQAP_TRACE DSQAPTRC 18 TRACE parameter; values can be:
ALL (maximum tracing)
NONE (minimum tracing)
You can also specify a series of letters and

numbers that specifies which components are
to be traced at which levels of detail (for
example, A2L2C1). For a list of component
letters as well as more information about the
levels of trace detail, see Installing and
Managing DB2 QMF for TSO/CICS.
DSQAP_WIDTH DSQAPWID 18 WIDTH parameter; its value is that of the
parameter ('22' through '999').
Global variables for state information not related to the profile

Table 50 shows the set of global variables that contain status information or settings
of parameters or flags. None of these global variables can be modified by the SET
GLOBAL command.
Table 50. Global variables for state information not related to the profile
Callable interface variable Command interface variable
name name Length Description
DSQAO_APPL_TRACE DSQATRAC 01 Application trace level; values can be:
0 for level A0
1 for level A1
2 for level A2
DSQAO_ATTENTION DSQCATTN 01 User attention flag.
DSQAO_BATCH DSQABATC 01 Batch or interactive mode; value can be:
1 for an interactive session
2 for a batch-mode session
DSQAO_CONNECT_ID DSQAAUTH 08 The user ID used to connect to the database;
this is the user ID under which work is done.
DSQAO_CONNECT_LOC none 18 The location name of the database to which
you are currently connected; the name is 18
characters (padded to the right with blanks, if
necessary).
DSQAO_CURSOR_OPEN DSQACRSR 01 Database cursor status; values can be:
1 if the cursor is open
2 if the cursor is closed
DSQAO_DB_MANAGER DSQADBMG 01 Database manager. Choose one of the
following values:
1 DB2 for VM and VSE
2 DB2 for z/OS
3 DB2 for Linux®, UNIX, and Windows®
4 DB2 for iSeries™
Appendix C. QMF global variable tables 199

Table 50. Global variables for state information not related to the profile (continued)
DSQAO_DBCS DSQADBCS 01 DBCS support status; values can be:
1 for DBCS support
2 for no DBCS support
DSQAO_FORM_PANEL DSQASUBP 02 Current form panel; values can be:
1 for FORM.MAIN
2 for FORM.COLUMNS
3 for FORM.PAGE
4 for FORM.FINAL
5 for FORM.BREAK1
6 for FORM.BREAK2
7 for FORM.BREAK3
8 for FORM.BREAK4
9 for FORM.BREAK5
10 for FORM.BREAK6
11 for FORM.OPTIONS
12 for FORM.CALC
13 for FORM.DETAIL
14 for FORM.CONDITIONS
A blank value means that the form does not

exist in QMF temporary storage.
DSQAO_INTERACT DSQAIACT 01 Setting of the interact flag; values can be:
0 for no interactive execution
1 when interactive execution is allowed
DSQAO_LOCAL_DB2 none 18 The location name of the local DB2 for z/OS
database. This is the location name for the
subsystem named in the variable
DSQAO_SUBSYS_ID.
In a remote unit of work environment,

DSQ_LOCAL_DB2 is the name of the
application requester. The name is 16
characters (padded to the right with blanks, if
necessary).
DSQAO_LOCATION DSQAITLO 16 Location name of the current object, if any; this
value is applicable only if a three-part name
was used.
DSQAO_NLF_LANG DSQALANG 01 National language of user; for the English
language environment, this is ‘E’.
DSQAO_NUM_FETCHED DSQAROWS 16 Fetched data rows; contains '0' when the DATA
object is empty.
DSQAO_OBJ_NAME DSQAITMN 128 The name of the table (contained in a report),
query, procedure, or form shown on the
currently displayed panel.
If the current panel does not display an object,

or if the displayed object has no name, this
variable contains blanks.

DSQAO_OBJ_OWNER DSQAITMO 128 The owner of the table (contained in a report),
query, procedure, or form shown on the
currently displayed panel.
If the current panel does not display an object,

or if the displayed object has no owner, this
variable contains blanks.
DSQAO_PANEL_TYPE DSQAITEM 01 Type of current panel; values can be:
1 for HOME
2 for QUERY
3 for REPORT
4 for FORM
5 for PROC
6 for PROFILE
7 for CHART
8 for LIST
9 for Table Editor
A for GLOBALS
| DSQAO_QMF_RELEASE DSQAREVN 02 Numeric release number of QMF, which
| appears in header records for exported forms,
| reports, and prompted queries; for QMF Version
| 9.1, this is '15'.
| DSQAO_QMF_VER_RLS DSQAQMF 10 Version and release of QMF. For QMF Version
| 9.1, this is 'QMF V9R1.0'.
DSQAO_QMFADM None 01 QMF administrator authority:
0 Current authorization ID does not
have QMF administrator authority.
1 Current authorization ID has
administrator authority.
DSQAO_QRY_SUBTYPE DSQASUBI 01 Query subtype. Values can be:
1 for a subtype of SQL
2 for a subtype of QBE
3 for a subtype of PROMPTED
Blank means the current panel is not QUERY.

DSQAO_QUERY_MODEL DSQAMODL 01 Model of current query; value can only be '1'
(for relational data model).
DSQAO_SAME_CMD DSQACMDM 01 Values can be:
0 if the two commands aren’t the same
1 if the two commands are the same

DSQAO_SUBSYS_ID none 04 If QMF is running in TSO, this is the ID of the
local DB2 subsystem to which QMF is attached.
If you specify a value for the DSQSSUBS

program parameter in CICS, this global variable
contains that value. This happens because the
parameter is tolerated and the value is not
processed; the value is placed in the global
variable field and nothing is done with it. This
logic permits the same program to be used in
multiple environments.
DSQAO_SYSTEM_ID DSQASYST 01 Current operating system; values can be:
2 TSO under z/OS
3 TSO or native z/OS
5 CICS
DSQAO_TERMINATE DSQCSESC 01 QMF termination flag; values can be:
0 if the session was not marked for
termination
1 if the session was marked for
termination
DSQAO_VARIATION DSQAVARN 02 Form panel variation number; blank means
FORM.DETAIL is not the current panel.
Global variables associated with CICS

Of the variables shown in Table 51, only DSQAP_CICS_PQNAME and
DSQAP_CICS_PQTYPE can be modified by the SET GLOBAL command.
When the queue type is transient data (TD), the maximum length of the
corresponding queue name is 4. For example, if DSQAO_CICS_SQTYPE is TD, the
maximum length of DSQAO_CICS_SQNAME is 4.
Table 51. Global variables associated with the CICS environment
DSQAP_CICS_PQNAME none 08 Names the CICS data queue to contain the
QMF print output.
DSQAP_CICS_PQTYPE none 02 Type of CICS storage used to contain the QMF
print output:
TS Writes the QMF print to a CICS
temporary storage queue on an
auxiliary storage device. This is the
default.
TD Writes the QMF print to a CICS
transient data queue.
DSQAO_CICS_SQNAME none 08 Names the CICS data queue to be used as the
spill file.

Table 51. Global variables associated with the CICS environment (continued)
DSQAO_CICS_SQTYPE none 02 Type of CICS storage used to contain the QMF
spill file:
TS Writes the QMF spill data to a CICS
auxiliary storage device. This is the
default.
TD Writes the QMF spill data to a CICS
transient data queue.
DSQAO_CICS_TQNAME none 08 Names the CICS data queue to contain the
QMF trace data.
DSQAO_CICS_TQTYPE none 02 Type of CICS storage used to contain the QMF
trace data:
TS Writes the QMF trace to a CICS
auxiliary storage device.
TD Writes the QMF trace to a CICS
transient data queue. This is the
default.
Global variables related to a message produced by the most recent

command
Table 52 shows global variables that capture information about the most recent
QMF command that was issued. None of these global variables can be modified by
the SET GLOBAL command.
Table 52. Global variables that capture information about the most recently issued command
DSQCM_MESSAGE DSQCIMSG 80 Message text
DSQCM_MESSAGE_ALL DSQCIMSA 360 Complete message text
DSQCM_MSG_HELP DSQCIMID 08 ID of message help panel
DSQCM_MSG_NUMBER DSQCIMNO 08 Message number
DSQCM_SUB_TXT_nn DSQCIMnn 20 Substitution value nn
DSQCM_SUBST_VARS DSQCIM00 04 Number of substitution variables in the
message
Global variables associated with the Table Editor

Table 53 on page 204 shows global variables associated with the operations of the
Table Editor. All of these global variables can be modified by the SET GLOBAL
command.
If the CONFIRM option of the EDIT TABLE command is NO, the Table Editor
suppresses the display of all confirmation panels. If the CONFIRM option is YES,
the Table Editor determines which categories of confirmation are enabled by
checking the values of the global variables shown in this table.
The Table Editor defaults depend on the SAVE keyword from the EDIT TABLE
command:

v When SAVE=IMMEDIATE, the default for each category is to enable.

v When SAVE=END, the default for the DELETE, MODIFY, and END/CANCEL
categories is to enable; the default for the ADD and CHANGE categories is to
disable.
Table 53. Global variables associated with the Table Editor
DSQCP_TEADD none 01 Displays a confirmation panel after an ADD
subcommand; values can be:
0 Panel is disabled.
1 Panel is enabled.
2 Panel is enabled or disabled
depending on the Table Editor
defaults; this is the default.
DSQCP_TECHG none 01 Displays a confirmation panel after a CHANGE
1 Panel is enabled.
DSQCP_TEEND none 01 Displays a confirmation panel when you issue
an END subcommand or a CANCEL
subcommand to terminate a Table Editor
subsession.
The panel can appear in several variations,

depending on whether or not END or CANCEL
was issued, whether modifications were made
to the database, and whether the screen
contained modified data when END or
CANCEL was issued. Values can be:
1 Panel is enabled.
DSQCP_TEDEL none 01 Displays a confirmation panel after a DELETE
1 Panel is enabled.
DSQCP_TEDFLT none 01 The reserved character used to indicate the
default value for a column in the Table Editor;
initially set to a plus sign (+) character.

Table 53. Global variables associated with the Table Editor (continued)
DSQCP_TEDFLT_DBCS none 04 The reserved DBCS character used to indicate
the default value for a graphic string column in
the Table Editor.
The value must be a four-byte mixed string,

composed of one DBCS character, preceded
by the shift-out character, and followed by the
shift-in character. It is initially set to a DBCS
plus sign (+) character. This global variable is
used only in a DBCS environment.
DSQCP_TEMOD none 01 Displays a confirmation panel when displayed
data is modified and a PREVIOUS, CLEAR,
SHOW CHANGE, SHOW SEARCH,
REFRESH, or NEXT subcommand is issued;
the resulting panel includes the name of the
subcommand as part of the panel text. Values
can be:
1 Panel is enabled.
defaults.
DSQCP_TENULL none 01 The reserved character used to indicate the
null value for a column in the Table Editor;
initially set to a hyphen (-) character.
DSQCP_TENULL_DBCS none 04 The reserved DBCS character used to indicate
the null value (or, in the context of search
criteria, to indicate “ignore”) for a graphic-string
column in the Table Editor.
The value must be a four-byte mixed string

composed of one DBCS character, preceded
by the shift-out character, and followed by the
shift-in character. It is initially set to a DBCS
hyphen (-) character. This global variable is
used only in a DBCS environment.
Global variables that control various displays

Table 54 shows global variables that control the display of certain kinds of
information. All of these global variables can be modified by the SET GLOBAL
command.
Table 54. Global variables that control the display of certain types of information
DSQDC_COST_EST none 01 Controls the display of the database cost
estimate; values can be:
0 Does not display the cost estimate.
1 Displays the cost estimate; this is
the default.

Table 54. Global variables that control the display of certain types of information (continued)
DSQDC_CURRENCY none 18 The currency symbol used when the DC edit
code is specified.
The value can be a string with a length from 1

to 18 bytes. For English, the default is the
euro currency symbol. The default varies for
other languages. In a DBCS environment, this
value can be a mixed string of SBCS and
DBCS characters. The total length of the
mixed string, including the shift-out and
shift-in characters, cannot exceed 18 bytes.
DSQDC_DISPLAY_RPT DSQADPAN 01 Displays a report after RUN QUERY; values
can be:
0 QMF does not display the resulting
report from a RUN query command.
This is the default if QMF is started
interactively with DSQQMFn (where
“n” is a character representing the
national language feature you are
using) or in BATCH mode.
Changing this variable when QMF
is started in BATCH mode will not
cause any QMF screen to display.
For a list of national language
features and their one-character
identifiers, see Installing and
Managing DB2 QMF for TSO/CICS.
1 QMF automatically displays the
report.
This is the default if QMF is started
with the callable interface. This can
be overridden with the DSQADPAN
program parameter on the START
command.
This global variable is for applications only. It

has no effect when the RUN QUERY
command is entered on the command line.

Table 54. Global variables that control the display of certain types of information (continued)
DSQDC_LIST_ORDER none 02 Sets the default sort order for objects in a list
of database objects; values for the first
character can be:
1 The list will use the default order.
2 The list will be sorted by object
owner.

name.
type.
5 The list will be sorted by date
modified.
6 The list will be sorted by date last
used.
Values for the second character can be:

A The list will be sorted in ascending
order.
D The list will be sorted in descending
order.
This variable applies only to objects that are

listed as a result of the LIST command. It
does not apply to lists produced in other
contexts, such as from a Display prompt
panel, and it does not apply to lists of tables.
DSQDC_SCROLL_AMT none 04 Sets the scroll amount for QMF panels;
values can be:
Csr Sets the scroll amount to “cursor”.
Depending on whether you scroll
backward, forward, left, or right,
QMF or column where the cursor is
positioned to the bottom, top, far
left, or far right of the scrollable
area.
Half Sets scroll amount to half the
scrollable area.
Page Sets scroll amount to a full page.
This is the default.
n Sets scroll amount to n number of
lines or columns. You can specify
any number from 1 to 9999 for n.
DSQDC_SHOW_PANID DSQCPDSP 01 Displays panel IDs of QMF panels; values
can be:
0 Suppresses panel identifiers. This is
the default.
1 Displays panel identifiers.

Global variables that control how commands and procedures are

executed
Table 55 shows global variables that control how commands and procedures are
executed. All of these global variables can be modified by the SET GLOBAL
command.
Table 55. Global variables that control how commands and procedures are executed
DSQEC_ALIASES none 31 View for retrieving lists of table and view
aliases when you request a list of tables from
a DB2 for z/OS location, or if the current
server is DB2 for z/OS or DB2 for Linux, UNIX,
and Windows.
DSQEC_CC none 01 Provides the ability to suppress the carriage
control characters in the report output format;
values can be:
0 No carriage control character in
column 1.
1 Carriage control is in effect; the
report will have a carriage control
character in column 1.
DSQEC_COLS_LDB2 none 31 View for retrieving column information for a
table at the current location, if that location is
DB2 for z/OS.
DSQEC_COLS_RDB2 none 31 View for retrieving column information for a
table at a remote DB2 for z/OS location (if it is
not the current location).
DSQEC_COLS_SQL none 31 View for retrieving column information for a
table in a DB2 for VM or VSE database.
DSQEC_DISABLEADM none 01 Suppression of QMF administrator authority.
When the value of this global variable is
changed, the effect is immediate. Possible
values can be:
0 QMF administrator authority is
available (if the authorization ID has
QMF administrator authority).
1 QMF administrator authority is

suppressed (regardless of the
authority of the authorization ID).
The initial default value for this global variable

may be overridden by the QMF installation exit
routine. See Installing and Managing DB2
QMF for TSO/CICS for more information about
this exit routine.
| DSQEC_DSALLOC_DIR None 3 Specifies the number of directory blocks to be
| used when exporting a member of a new PDS
| data set in TSO. The value must be greater
| than zero for PDS data sets.
| If you are using the site default type of data

| set (specified by setting DSQEC_PO to 0) or
| PDSE data sets (specified by setting
| DSQEC_PO to 2), QMF ignores the value of
| this global variable.
| If your site uses sequential data sets, set this

| global variable to zero.

Table 55. Global variables that control how commands and procedures are executed (continued)
| DSQEC_DSALLOC_PRI None 8 QMF allocates data sets in tracks. This global
| variable specifies the primary quantity of tracks
| for the TSO data set that will be used to store
| the results of the QMF EXPORT command.
| Values can be from 1 to the maximum size

| allowed by the storage device and operating
| system. The default value is 15. A value of
| zero is not allowed.
| PS and PDS data sets can have a maximum

| value of 65535 tracks; PDSE data sets can
| have a maximum value of 16777215 tracks.
| DSQEC_DSALLOC_SEC None 8 QMF allocates data sets in tracks. This global
| variable specifies the secondary quantity of
| tracks for the TSO data set that will be used to
| store the results of the QMF EXPORT
| command.
| Values can be from zero to the maximum size

| allowed by the storage device and operating
| system. The default value is 105 tracks.
| PS and PDS data sets can have a maximum

| value of 65535 tracks; PDSE data sets can
| have a maximum value of 16777215 tracks.
DSQEC_FORM_LANG none 01 Establishes the default NLF language in a
saved or exported form; values can be:
0 The form will use the presiding NLF
language.
1 The form will use English; this is the
default.
DSQEC_ISOLATION none 01 Default query isolation level; values can be:
0 Isolation level UR (uncommitted
read).
1 Isolation level CS (cursor stability);
this is the default.
Attention: Setting the value to ’0’ can

introduce non-existent data into a QMF report.
Do not set the value to ’0’ if your QMF reports
must be free of non-existent data.
DSQEC_NLFCMD_LANG none 01 Sets expected NLF language for commands;
values can be:
0 Commands must be in the presiding
NLF language; this is the default.
1 Commands must be in English.

Table 55. Global variables that control how commands and procedures are executed (continued)
| DSQEC_PO None 1 Specifies the type of partitioned (PO) data set
| to create when exporting a QMF object to a
| new TSO data set. Values can be the
| following:
| 0 Allocates a data set of the type listed
| as the default for your site. This type
| is specified in the IGDSMSxx
| member of the SYS1.PARMLIB. This
| is the default value.
| 1 Allocates a PDS data set for the

| exported data.
| 2 Allocates a PDSE data set for the

| exported data.
DSQEC_RERUN_IPROC none 01 Reruns the invocation procedure after the END
command; values can be:
0 Suppresses rerun of the invocation
procedure after the END command.
1 Reruns the invocation procedure
after the END command; this is the
default.
If you start QMF with an invocation procedure,

set this variable to '0'; QMF terminates instead
of rerunning the procedure.
DSQEC_RESET_RPT none 31 Determines whether or not QMF prompts you
when an incomplete DATA object in temporary
storage appears to be affecting performance;
possible values are:
0 Reset Report prompt panel is not
displayed and QMF completes the
running report; this is the default
value.
1 Reset Report prompt panel is
displayed; this panel prompts you to
complete or reset the currently
running report before starting the
new command.
2 Reset Report prompt panel is not
displayed and QMF resets the
currently running report.
DSQEC_SHARE none 31 Specifies the default value for the SHARE
parameter; possible values are:
0 Do not share data with other users.
1 Share data with other users.
DSQEC_TABS_LDB2 none 31 View for retrieving lists of tables and views at
the current server, if it is DB2 for z/OS or DB2
for Linux, UNIX, and Windows.
DSQEC_TABS_RDB2 none 31 View for retrieving lists of tables and views at
remote DB2 subsystems.
DSQEC_TABS_SQL none 31 View for retrieving lists of tables and views for
a DB2 for VM or VSE database.

Global variables that store results of CONVERT QUERY

Table 56 shows global variables that reflect the results of a CONVERT QUERY
command. None of these global variables can be modified by the SET GLOBAL
command.
Table 56. Global variables that reflect the results of a CONVERT QUERY command
Callable Interface Variable Command Interface Variable
Name Name Length Description
DSQQC_LENGTH_nnn DSQCLnnn 05 Length of converted result nnn.
DSQQC_QRY_COUNT DSQCQCNT 03 Number of queries in converted result; value
must always be '1' unless the original query is a
QBE I. or U. query.
DSQQC_QRY_LANG DSQCQLNG 01 Language of converted query; values can be:
1 for SQL
2 for QBE
3 for Prompted
DSQQC_QRY_TYPE DSQCQTYP not specified First word in converted results.
DSQQC_RESULT_nnn DSQCQnnn not specified Converted result nnn.
Global variables that show RUN QUERY error message information

Table 57 shows global variables that store the results of a RUN QUERY command.
None of these global variables can be modified by the SET GLOBAL command.
Table 57. Global variables that store the results of a RUN QUERY command
DSQQM_MESSAGE DSQCIQMG 80 Text of query message.
DSQQM_MESSAGE_ALL DSQCIQMA 360 Complete query message text.
DSQQM_MSG_HELP DSQCIQID 08 ID of message help panel.
DSQQM_MSG_NUMBER DSQCIQNO 08 Message number.
DSQQM_SQL_RC DSQCISQL 16 The SQLCODE from the last command or
query.
DSQQM_SQL_STATE none 05 The SQLSTATE associated with the
SQLCODE in DSQQM_SQL_RC, if
SQLSTATE is returned by the database
manager.
DSQQM_SUB_TXT_nn DSQCIQnn 20 Substitution value nn.
DSQQM_SUBST_VARS DSQCIQ00 04 Number of substitution variables.


Appendix D. Notices
This information was developed for products and services offered in the U.S.A. IBM
may not offer the products, services, or features discussed in this document in other
countries. Consult your local IBM representative for information on the products and
services currently available in your area. Any reference to an IBM product, program,
or service is not intended to state or imply that only that IBM product, program, or
service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However,
it is the user’s responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply to
you.
This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements and/or
changes in the product(s) and/or the program(s) described in this publication at any
time without notice.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue

San Jose, CA 95141-1003
U.S.A.
Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.
The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
Trademarks
The following terms are trademarks of International Business Machines Corporation
in the United States, other countries, or both.
CICS IBM
DB2 iSeries
Distributed Relational Database Architecture OS/390
DRDA QMF
eServer RACF
GDDM WebSphere
z/OS
Intel® is a registered trademark of Intel Corporation or its subsidiaries in the United

States and other countries.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Windows is a trademark of Microsoft® Corporation in the United States, other

countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, and service names may be trademarks or service marks
of others.

Glossary of terms and acronyms
abend. The abnormal termination of a task.
ABENDx. The keyword for an abend problem.
aggregation function. Any of a group of functions that summarizes data in a column. They are requested with these
usage codes on the form panels: AVERAGE, CALC, COUNT, FIRST, LAST, MAXIMUM, MINIMUM, STDEV, SUM,
CSUM, PCT, CPCT, TPCT, TCPCT.
aggregation variable. An aggregation function that is placed in a report using the FORM.BREAK, FORM.CALC,
FORM.DETAIL, or FORM.FINAL panels. Its value appears as part of the break footing, detail block text, or final text
when the report is produced.
alias. In DB2 for z/OS, an alternate name that can be used in SQL statements to refer to a table or view in the same
or a remote DB2 for z/OS subsystem. In QMF, a locally defined name used to access a QMF table or view stored on a
local or remote DB2 for z/OS subsystem.
APAR. Authorized Program Analysis Report.
application. A program written by QMF users that extends the capabilities of QMF without modifying the QMF
program itself. Started from a QMF session by issuing a RUN command for a QMF procedure, a site-defined
command, or a TSO command that invokes a CLIST.
application requester. (1) A facility that accepts a database request from an application process and passes it to an
application server. (2) In DRDA®, the source of a request to a remote relational database management system.
The application requester is the database management system code that handles the QMF end of the distributed
connection. The local DB2 for z/OS subsystem to which QMF attaches is known as the application requester for QMF,
because the DB2 for z/OS application requester is installed within the local database manager. Therefore, an entire
DB2 for z/OS subsystem (including data) is associated with the application requester, but the SQL statements are
processed at the current location.
application server. The target of a request from an application requester. (1) The local or remote database manager
to which the application process is connected. The application server executes at the system containing the desired
data. (2) In DRDA, the target of a request from an application requester. With DB2 for z/OS, the application server is
part of a full DB2 for z/OS subsystem.
With DB2 for VM and VSE, the application server is part of a DB2 for VM and VSE database machine.
application-support command. A QMF command that can be used within an application program to exchange
information between the application program and QMF. These commands include INTERACT, MESSAGE, STATE, and
QMF.
area separator. The barrier that separates the fixed area of a displayed report from the remainder of the report.
argument. An independent variable.
base QMF environment. The English-language environment of QMF, established when QMF is installed. Any other
language environment is established after installation.
batch QMF session. A QMF session running in the background. Begins when a specified QMF procedure is invoked
and ends when the procedure ends. During a background QMF session, no user interaction and panel display
interaction are allowed.
bind. In DRDA, the process by which the SQL statements in an application program are made known to a database
management system over application support protocol (and database support protocol) flows. During a bind, output
from a precompiler or preprocessor is converted to a control structure called a package. In addition, access paths to
the referenced data are selected and some authorization checking is performed. (In DB2 for z/OS, the output may also
be an application plan.)
built-in function. Generic term for scalar function or column function. Can also be “function.”

Glossary
calculation variable. CALCid is a special variable for forms that contains a user-defined calculated value. Each
CALCid is defined on the FORM.CALC panel.
callable interface. A programming interface that provides access to QMF services. An application can access these
services even when the application is running outside of a QMF session. Contrast with command interface.
CICS. Customer Information Control System.
column wrapping. Formatting values in a report so that they occupy several lines within a column. Often used when
a column contains values whose length exceeds the column width.
command interface. An interface for running QMF commands. The QMF commands can only be issued from within
an active QMF session. Contrast with callable interface.
command synonym. The verb or verb/object part of a site-defined command. Users enter this for the command,
followed by whatever other information is needed.
command synonym table. A table each of whose rows describes a site-defined command. Each user can be
assigned one of these tables.
commit. The process that makes a data change permanent. When a commit occurs, data locks are freed, enabling
other applications to reference the just-committed data. See also “rollback”.
concatenation. The combination of two strings into a single string by appending the second to the first.
correlation name. An alias for a table name, specified in the FROM clause of a SELECT query. When concatenated
with a column name, it identifies the table to which the column belongs.
CSECT. Control section.
current location. The application server to which the QMF session is currently connected. Except for
connection-type statements, such as CONNECT (which are handled by the application requester), this server
processes all the SQL statements. When initializing QMF, the current location is indicated by the DSQSDBNM startup
program parameter.
current object. An object in temporary storage currently displayed.
Customer Information Control System (CICS). An IBM licensed program that enables transactions entered at
remote terminals to be processed concurrently by user-written application programs. It includes facilities for building,
using, and maintaining databases.
database administrator. The person who controls the content of and access to a database.
database management system. A system for defining, creating, manipulating, controlling, managing, and using
databases. The database management system also has transaction management and data recovery facilities to
protect data integrity.
database manager. A program used to create and maintain a database and to communicate with programs requiring
access to the database.
database server. In DRDA, the target of a request received from an application server.
date/time default formats. Date and time formats specified by a database manager installation option. They can be
the EUR, ISO, JIS, USA, or LOC (LOCAL) formats.
date/time data. The data in a table column with a DATE, TIME, or TIMESTAMP data type.
DB2 for Linux, UNIX, and Windows. The IBM family of DRDA database products on the UNIX and Intel platforms.
DBCS. Double-byte character set.
DBMS. Database management system.
default form. The form created by QMF when a query is run. The default form is not created if a saved form is run
with the query.

Glossary
destination control table (DCT). In CICS, a table containing a definition for each transient data queue.
detail block text. The text in the body of the report associated with a particular row of data.
detail heading text. The text in the heading of a report. Whether or not headings will be printed is specified in
FORM.DETAIL.
dialog panel. A panel that overlays part of a Prompted Query primary panel and extends the dialog that helps build
a query.
distributed data. Data that is stored in more than one system in a network, and is available to remote users and
application programs.
distributed database. A database that appears to users as a logical whole, locally accessible database, but is
comprised of databases in multiple locations.
distributed relational database. A distributed database where all data is stored according to the relational model.
Distributed Relational Database Architecture™ (DRDA). A connection protocol for distributed relational database
processing that is used by IBM and vendor relational database products.
distributed unit of work. A method of accessing distributed relational data in which users or applications can, within
a single unit of work, submit SQL statements to multiple relational database management systems, but no more than
one RDBMS per SQL statement.
DB2 for z/OS has a limited form of distributed-unit-of-work support called system-directed access, which QMF
supports.
double-byte character. An entity that requires two character bytes.
double-byte character set (DBCS). A set of characters in which each character is represented by two bytes.
Languages such as Japanese, Chinese, and Korean, which contain more symbols that can be represented by 256
code points, require double-byte character sets. Because each character requires two bytes, the typing, display, and
printing of DBCS characters requires hardware and programs that support DBCS.
EBCDIC. Extended Binary-Coded Decimal Interchange Code.
echo area. The part of the Prompted Query primary panel in which a prompted query is built.
EUR (European) format. A format that represents date and time values as follows:
v Date: dd.mm.yyyy
v Time: hh.mm.ss
extended syntax. QMF command syntax that is used by the QMF callable interface; this syntax defines variables
that are stored in the storage area acquired by the callable interface application and shared with QMF.
global variable. A variable that, once set, can be used for an entire QMF session. A global variable can be used in a
procedure, query, or form. Contrast with run-time variable.
Graphical Data Display Manager (GDDM). A group of routines that allows pictures to be defined and displayed
procedurally through function routines that correspond to graphic primitives.
grouped row. A row of data in a QBE target or example table that is summarized either by the G. keyword or a
built-in function.
HTML. Hypertext Markup Language. A standardized markup language for documents displayed on the Internet.
ICU. Interactive Chart Utility.
INCORROUT. The keyword for incorrect output.
initialization program. A program that sets QMF program parameters. This program is specified by the DSQSCMDn
parameter (where “n” is a single character identifying the national language feature you are using) on the START
Glossary of terms and acronyms 217

Glossary
command in the callable interface. The default program is DSQSCMDE (which is an English program that passes
QMF program parameter values). For a list of national language features and their one-character identifiers, see
Installing and Managing DB2 QMF for TSO/CICS.
invocation CLIST or EXEC. A program that starts QMF.
ISO (International Standards Organization) format. A format that represents date and time values as follows:
v Date: yyyy-mm-dd
v Time: hh.mm.ss
ISPF. Interactive System Productivity Facility.
IXF. Integration Exchange Format: A protocol for transferring tabular data among various software products.
JCL. Job control language for OS/390® and z/OS.
JIS (Japanese Industrial Standard) format. A format that represents date and time values as follows:
v Date: yyyy-mm-dd
v Time: hh:mm:ss
keyword parameter. An element of a QMF command consisting of a keyword and an assigned value.
literal. In programming languages, a lexical unit that directly represents a value; a character string whose value is
given by the characters themselves.
linear procedure. Any procedure not beginning with a REXX comment. A linear procedure can contain QMF
commands, comments, blank lines, RUN commands, and substitution variables. See also “procedure with logic.”
linear syntax. QMF command syntax that is entered in one statement of a program or procedure, or that can be
entered on the QMF command line.
local DB2 for z/OS. With DB2 for z/OS, the application requester is part of a DB2 for z/OS subsystem that is running
in the same z/OS system as QMF. Therefore, an entire DB2 for z/OS subsystem (including data) is associated with the
application requester, but the SQL statements are processed at the current location. This subsystem is where the QMF
plan is bound.
location. A specific relational database management system in a distributed relational database system. Each DB2
for z/OS subsystem is considered to be a location.
MSGx. The keyword for a message problem.
NLF. National Language Feature. Any of several optional features available with QMF that lets the user select a
language other than English.
NLS. National Language Support.
package. The control structure produced when the SQL statements in an application program are bound to a
relational database management system. The database management system uses the control structure to process
SQL statements encountered during statement execution.
panel. A particular arrangement of information, grouped together for presentation in a window. A panel can contain
informational text, entry fields, options the user can choose from, or a mixture of these.
parameter. An element of a QMF command. This term is used generically in QMF documentation to reference either
a keyword parameter or a positional parameter.
PERFM. The keyword for a performance problem.
permanent storage. The database where all tables and QMF objects are stored. Contrast with temporary storage.
plan. A form of package where the SQL statements of several programs are collected together during bind to create
a plan.

Glossary
positional parameter. An element of a QMF command that must be placed in a certain position within the
command.
primary panel. The main Prompted Query panel containing your query.
primary QMF session. An interactive session begun from outside QMF. Within this session, other sessions can be
started by using the INTERACT command.
procedure with logic. Any QMF procedure beginning with a REXX comment. In a procedure with logic, you can
perform conditional logic, make calculations, build strings, and pass commands back to the TSO or CICS environment.
See also “linear procedure.”
profile. An object that contains information about the characteristics of the user’s session. A stored profile is a profile
that has been saved in permanent storage. A profile in temporary storage has the name PROFILE. There can be only
one profile for each user.
Prompted Query. A query built in accordance with the user’s responses to a set of dialog panels.
PSW. Program status word.
PTF. Program temporary fix.
QBE (Query-by-Example). A language used to write queries graphically. For more information, see Using DB2 QMF.
QMF administrative authority. At minimum, insert or delete privilege for the Q.PROFILES control table.
QMF administrator. A QMF user with QMF administrative authority.
QMF command. Refers to any command that is part of the QMF language. Does not include site-defined
commands.
QMF session. All interactions between the user and QMF from the time the user invokes QMF until the EXIT
command is issued.
qualifier. (1) When referring to a QMF object, the part of the name that identifies the owner or the location of an
object. (2) When referring to a TSO data set, any part of the name that is separated from the rest of the name by
periods. For example, ‘TCK’, ‘XYZ’, and ‘QUERY’ are all qualifiers in the data set name ‘TCK.XYZ.QUERY’.
RDBMS. Relational database management system.
relational database management system (RDBMS). A system for defining, creating, manipulating, controlling,
managing, and using relational databases.
remote unit of work. (1) The form of SQL distributed processing where the application is on a system different from
the relational database. A single application server services all remote-unit-of-work requests within a single logical unit
of work. (2) A unit of work that allows for the remote preparation and execution of SQL statements.
REXX. Restructured extended executor, a procedural language used by QMF and in applications that you can write
for use with QMF.
rollback. The process that removes uncommitted database changes made by one application or user. When a
rollback occurs, locks are freed and the state of the resource being changed is returned to its state at the last commit,
rollback, or initiation. See also commit.
row operator area. The left-most column of a QBE target or example table.
run-time variable. A variable in a procedure or query whose value is specified by the user when the procedure or
query is run. The value of a run-time variable is only available in the current procedure or query. Contrast with global
variable.
SBCS. Single-byte character set.
scalar. A value in a column or the value of a literal or an expression involving other scalars.

Glossary
scalar function. An operation that produces a single value from another value and is expressed in the form of a
function name followed by a list of arguments enclosed in parentheses.
SNAP dump. A dynamic dump of the contents of one or more storage areas that QMF generates during an abend.
SQL. See Structured Query Language.
SQLCA. Structured Query Language Communication Area.
Structured Query Language (SQL). A standardized language for defining and manipulating data in a relational
database.
subquery. A complete SQL query that appears in a WHERE or HAVING clause of another query (the main query or
a higher-level subquery).
substitution variable. (1) A variable in a procedure or query whose value is specified either by a global variable or
by a run-time variable. (2) A variable in a form whose value is specified by a global variable.
substring. The part of a string whose beginning and length are specified in the SUBSTR function.
System Log (SYSLOG). A data set or file in which job-related information, operational data, descriptions of unusual
occurrences, commands, and messages to and from the operator may be stored.
tabular data. Data in columnar format. The content and the form of the data is specified on FORM.MAIN and
FORM.COLUMNS.
target table. An empty table in which example elements are used to combine columns, combine rows, or include
constant values in a report.
temporary storage. Areas where the QUERY, FORM, PROC, PROFILE, REPORT, DATA, and CHART objects in
current use are stored.
temporary storage queue. In CICS, a temporary storage area used for transfer of objects between QMF and an
application or a system service.
thread. The DB2 for z/OS structure that describes an application’s connection, traces its progress, provides resource
function processing capability, and delimits its accessibility to DB2 resources and services. Most DB2 for z/OS
functions execute under a thread structure.
three-part name. A fully-qualified name of a table or view, consisting of a location name, owner ID, and object name.
When supported by the application server, a three-part name can be used in an SQL statement to retrieve or update
the specified table or view at the specified location.
timestamp. A date, time, and possibly a number of microseconds (a six- or seven-part value).
transient data queue. In CICS, a storage area whose name is defined in the Destination Control Table (DCT), where
objects are stored for subsequent internal or external processing.
TSO. Time Sharing Option.
two-phase commit. A protocol used in distributed unit of work to ensure that participating relational database
management systems commit or roll back a unit of work consistently.
unit of work. (1) A recoverable sequence of operations within an application process. At any time, an application
process is a single unit of work, but the life of an application process may involve many units of work as a result of
commit or rollback operations. (2) In DRDA, a sequence of SQL commands that the database manager treats as a
single entity. The database manager ensures the consistency of data by verifying that either all the data changes
made during a unit of work are performed or none of them are performed.
unnamed column. An empty column added to an example table. Like a target table, it is used to combine columns,
combine rows, or include constant values in a report.
variation. A data formatting definition specified on a FORM.DETAIL panel that can be used to conditionally format a
report or part of a report.

Glossary
WAIT. The keyword for an endless-wait-state problem.
z/OS. An operating system for the IBM eServer™ product line that uses 64-bit real storage.

Glossary

Index
A C language (continued)
DSQCOMM 148
A option for debugging 121
mapping 142
accessibility ix
function calls 143
ADDRESS command 14, 29
interface requirements 145
application
ISPF 151
controlling 1
sample programs 145
implementation methods 3
TSO 151
programming interfaces with QMF 4
CALL instruction 14
QMF
callable interface
controlling 1
application, running 21
implementation methods 3
calling from procedure with logic 14
running under 2
CICS, running under 22
running under QMF 2
COBOL 153
applications 1, 2, 3
command processing information 17
bilingual 36
commands 20
CICS environment 4
communications area 3
command synonym 2
C 148
commands 1
COBOL 158
INTERACT 44
defining 18
overview 41
error handling 22
processing 18
set fields 19
data records 88
debugging applications 121
debugging 121
description 17
developing 1
FORTRAN 164
ISPF requirements 31
GET GLOBAL command 43
procedures 7
ISPF 3
procedures with logic 3
languages 4, 17, 125
types 1
macros 195
ARG statement 11
PL/I 176
arguments 11
program 3
Assembler
return codes 20
CICS 125
REXX
sample program 128
communications variables 189
z/OS 139
description 189
communications area 137
invoking with 7
function calls 126
uses 3
High Level Assembler (HLASM) 125
sample programs 3
language interface 125
Assembler 128
macros 195
C 145
sample program 128
COBOL 156
TSO sample programs 133, 140
START command 3
starting QMF 21
syntax 50
B CDATA tags in exported XML 80
BIGINT data type, exporting 64 cell tags in exported XML 80
bilingual objects 36 chart objects 116
BINARY data type, exporting 64, 65 CICS
break Assembler 4
panel 98 z/OS requirements 139
break panel 95 callable interface 4
COBOL programs 161
CONNECT command 9
C data queue 4
C language IXF format 67
callable interface 142 transient data queues 118
CICS 150 using to transfer QMF objects 62
communications area 142 DB2 interaction 23

CICS (continued) control areas in exported objects (continued)
program start parameter overrides 22 records of report files 85
region 23 T records 86
COBOL current location 41
callable interface 153
CICS 161
communications area 154 D
delimiters 160 data
DSQCOMM 158 D records 70
execution requirements 160 exporting 62
function calls 154 object
ISPF 162 formats 63
macros 195 IXF exported format 67
sample program 156 records, exporting 64, 80
TSO 162 type widths 64
column 69, 70 data set, defining for exports 210
C records 69 data types, export considerations 64, 100
data format 70 database remote connections 9
column description block in exported XML 79 DB2 (IBM DATABASE 2)
command CICS requirements 23
applications 41 DB2 for VM or VSE
bilingual applications 38 remote connections 9
environment 29 DB2 Server for VSE & VM
INTERACT 44 CONNECT command 9
interface 2 debugging applications
description 25 ISPF, using 34
invoking from a program 26 PDF dialog test 34
requirements 4 directory blocks, specifying upon export 208
return codes 27 disabilities, features for users with ix
sample program 25 DSQ1SCEM schema file 80
SELECT service 26 DSQ1STSH style sheet file 81
language variable 37 DSQABFA 133
length 18 DSQABFAC 128
return code 12 DSQADPAN 52
RUN 9 DSQALANG 53
SET GLOBAL 49 DSQCIA 126
system specific 9 DSQCIX subroutine 190
command synonyms DSQCOMM
creating 56 Assembler 137
description 5 C 142, 148
example 2 COBOL 154
NLF table 36 defining 18
table 57 DSQCOMMA 137
comment DSQCOMMC 148
application data records 88, 98 error handling 22
exported formats 98 message text 123
communications area set fields 19
COBOL 154, 158 DSQDC_DISPLAY_RPT global variable 57
defining 18 DSQEC_NLFCMD_LANG variable 37, 209
FORTRAN 171 DSQSBSTG 53
PL/I 182 DSQSCMD 54
Compatibility Mode and multi-row fetch 55 DSQSDBCS 54
CONNECT command DSQSDBNM 54
DB2 Server for VSE & VM 9 DSQSDBQN 54
description 41 DSQSDBQT 54
example 41 DSQSDBUG 55
initial procedures 8 DSQSIROW 55
mixed-case passwords 9, 198 DSQSMODE 55
procedures 9 DSQSMRFI 55
control areas in exported objects 85 DSQSPILL 55
records of form files 85 DSQSPRID 55

DSQSRSTG 56 formats (continued)
DSQSRUN 56 form object 95
DSQSSPQN 56 header record 63, 64
DSQSSUBS 56 import 63
IXF 61, 67
prompted query object 111
E report object 104
edit codes, keywords seen in exports 97 table 62
EDIT command 33 FORTRAN
END command callable interface 164
command interface 26 communications area 165
description 42 DSQABFF 167
interactive session 193 DSQCOMM 171
rerunning initial procedures 8 function calls 166
session types 42 ISPF 174
end-of-object record (E) 88 macros 195
environments 4 sample program 167
EXIT command 43 TSO 173
EXPORT command z/OS 173
DATA 62 function calls
data object 62 C 143
IXF option 67 DSQCIC 143
table object 62 DSQCICE 144
using CICS 118
exporting
charts 116 G
data and tables 62 GDDM (Graphical Data Display Manager) 44
form objects 61 GET GLOBAL command 20, 43
forms 82 global variable
hex codes for data types 64 creating 49
keywords used for edit codes 97 creating variables 49
object size specifications 117 list of 197
object types 61 QMF used through RUW 198
procedures 116 rules for 50
prompted queries 82 setting 49
QBE queries 117 SET GLOBAL command 49
reports 82 Graphics Data Format (GDF) 116
SQL queries 116
storage considerations 118
versus saving 62 H
width calculations for data types 64 header record
Extensible Markup Language (XML) data type fields 83
See XML data type, exporting form object 94
format 63, 64
IXF 67
F length, calculating 65
fetch, multi-row 55 object level 84
form XML exports 79
data formats 63 hex codes for exported data types 100
exporting 82 home panel 8
field numbers 95 HTML report 105
sample header 94
table numbers 95
translating 94, 99 I
form object 63, 82, 92, 94, 95, 97, 98 ICU (Interactive Chart Utility) 44
formats IMPORT command
column data 70 DATA option 81
data, exporting 64 definition 61
encoded errors and warnings during execution of 101
definition 61 using CICS 118
export 63 importing 61
Index 225
importing (continued) MESSAGE command (continued)
form object 99 ISPF panels 46
object level information 84 options 46
prompted query object 115 QMF help panels 46
tables created outside QMF 63 suppressing linear procedure execution 47
incomplete data prompt 81 tracing 123
initial procedures metadata records in exported XML 79
bilingual applications 38 migration information 84
CONNECT command 8 minisession
name, specifying 7 invalid commands 58
storing 8 report 57
writing 7 valid commands 58
INTERACT command mixed-case passwords 198
command form 45 multi-row fetch 55
description 44 multilingual environments 39
session
ending 45
form 44 N
termination 43 New Function Mode and multi-row fetch 55
interact switch (DSQAO_INTERACT) 46 NLF (National Language Feature)
interactive mode defined 35
GDDM ICU 44 language 36
initial procedures 8 language ID 31
QMF 44 multilingual environments 39
ISPF (Interactive System Productivity Facility) panel requirements 36
callable interface 32 session environments 35
IXF
binary 70
character 70 P
examples 75 panel 44
exporting in 67 current 44
long name support 68 interactive 44
OUTPUTMODE=BINARY 77 PARSE ARG statement 11
parse services and exporting XML 78
passwords, mixed-case 9
K PDF 34
keyboard shortcuts ix PDS and PDSE data sets
keywords 51 defining export storage 208, 209
for edit codes, in exported file 97 defining type to QMF 210
START command 51 PL/I
CICS 184
L communications area 177
L option for debugging 121 DSQABFP 179
language DSQCOMM 182
callable interface 4 function calls 178
ID 31 ISPF 186
NLF, specifying 37 macros 195
return codes 22 sample program 179
LAYOUT command 92 TSO 185
linear procedure z/OS 184
STOPPROC option 47 prerequisite DB2 for z/OS knowledge viii
suppressing 47 primary space allocation upon export 209
product interface macros 195
program calls 18
M prompted query
macros, product interface 195 data formats 63
MESSAGE command export format 111
description 46 exporting 82, 109
displaying text 47 field numbers 111
examples 48 import/export file specifications 117

prompted query (continued) RUN command
table numbers 111 embedded substitution variables 14
prompted query object 63, 82, 109, 110, 111 prompt panel 9
PS data sets, defining for export 209 substitution variables 9
RUW (remote unit of work) 9
Q
QBE (Query-By-Example) S
export format 117 SAVE DATA command 62
import/export file specifications 117 schema definition in exported XML file 79, 80
QMF format for exporting data and tables 63 screen readers and magnifiers ix
qmf_data.xsd schema file 80 secondary space allocation upon export 209
SELECT command 25, 32
session environments 35
R SET GLOBAL command
RACF and mixed-case passwords 198 callable interface 20, 49
records prompting for variables 11
application data (*) 88 syntax 49
column (C) 69 signal on error instruction 12
data (D) 70 SQL query object 116
data continuation (C) 91 START command
data value (V) 85 debugging errors 123
fixed format 83 interface communications area 18
formats 64 keywords
header 83 DSQADPAN 52
table description (T) 68 DSQALANG 53
variable format 84 DSQSBSTG 53
remote unit of work DSQSCMD 54
command behavior 41 DSQSDBCS 54
report DSQSDBNM 54
across 104 DSQSDBQN 54
data formats 63 DSQSDBQT 54
displaying text 47 DSQSDBUG 55
export example 101 DSQSIROW 55
export format 104 DSQSMODE 55
export records 103 DSQSMRFI 55
export uses 101 DSQSPILL 55
exported across 107 DSQSPRID 55
exporting 62 DSQSRSTG 56
field numbers 104 DSQSRUN 56
HTML 105 DSQSSPQN 56
line (L) records 89 DSQSSUBS 56
minisession 57 list 51
object 2 QMF startup 21, 50
across 104 syntax 50
export format 104 STATE command 27
field numbers 104 storage
table numbers 104 export considerations 118
panel 2 specifying when exporting 208, 210
records 83 style sheet for exported XML files 81
row data 87 substitution variables 9
sample header 104 assigning values 9
table data 86 global variables, setting 9
table numbers 104 REXX program calls 14
result set records in exported XML 79 syntax 9
return codes synonyms 56
command interface 27, 28
message 12 T
nonzero 12 table
creating outside QMF 67
Index 227
table (continued)
description records (T) 68, 86
exporting 62
form, numbers 95
object
import/export file specifications 117
import/export rules 81
importing 62
processing 62
prompted query, numbers 111
report, numbers 104
row records (R) 87
table record 68
temporary storage 22
modifying 22
queue 119
restrictions 3
trace data output 121, 122
tracing
A option 121
creating trace definitions 34
example 123
ISPF commands 34
L option 121
turning off 122
transient data queue
contrasted with temporary storage queue 118
translatable applications 39
TSO
Assembler callable interface programs 140
Assembler programs 140
C callable interface programs 151
C programs 151
mixed-case passwords on RACF 9
REXX callable interface programs 192
REXX programs 192
V
validation of exported XML file 80
VARBINARY data type, exporting 64, 65
variables
error handling 22
global 9, 197
substitution 9
pool 17
prompting for 10
QMF 27
rc 12
rules 50
setting 9
substitution 9
variation panels 98, 99
X
XML data type, exporting 78

Program Number: 5635-DB2
Printed in USA
SC18-9687-00

Devoloping DB2 QMF Applications

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Devoloping DB2 QMF Applications

Uploaded by

Copyright:

Available Formats

DB2 Query Management Facility

Developing DB2 QMF Applications

Developing DB2 QMF Applications

First Edition (March 2007)

Chapter 1. QMF application development overview . . . . . . . . . . . 1

Chapter 2. Using procedures as applications . . . . . . . . . . . . . 7

Chapter 3. Using the callable interface for applications . . . . . . . . . 17

Chapter 4. Using the command interface for applications . . . . . . . . 25

© Copyright IBM Corp. 1982, 2007 iii

Chapter 5. ADDRESS QRW: Using the QMF command environment . . . . 29

Chapter 6. Writing QMF applications that use ISPF services . . . . . . . 31

Chapter 7. Writing bilingual applications . . . . . . . . . . . . . . 35

Chapter 8. Using QMF commands in applications . . . . . . . . . . . 41

Chapter 9. Exporting and importing objects . . . . . . . . . . . . . 61

iv Developing QMF Applications

Chapter 10. Debugging your QMF applications . . . . . . . . . . . 121

Appendix A. Sample code for callable interface languages . . . . . . . 125

Appendix B. Product interface macros . . . . . . . . . . . . . . . 195

Appendix C. QMF global variable tables . . . . . . . . . . . . . . 197

Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . 213

Glossary of terms and acronyms . . . . . . . . . . . . . . . . . 215

vi Developing QMF Applications

How to use this information

Conventions for National Language Feature information

© Copyright IBM Corp. 1982, 2007 vii

Table 1. QMF NLFs and their identifying information (continued)

Prerequisite and related information

viii Developing QMF Applications

Related product information

How to send your comments

About this information ix

The following topics are covered here:

What is application development in QMF?

Application development refers to the process of creating an application. It includes:

How can end users use your application?

© Copyright IBM Corp. 1982, 2007 1

Interacting primarily with the application

J & H Supply Company

Please select one of the following:

1. Print the monthly sales report

2. Create a new report

3. Modify information in the database

4. End the application

Figure 1. An example of an application-defined panel

Starting the application from a QMF session

2 Developing QMF Applications

REPORT LINE 1 POS 1 79

NAME DEPT JOB SALARY COMM

Figure 2. An example of a user entering a customized QMF command

What QMF application development tools are available?

Chapter 1. QMF application development overview 3

QMF callable and command interfaces

The callable interface is available for all environments supported in QMF. It is a

Differences between the callable and command interfaces

4 Developing QMF Applications

v Requires ISPF to be present and active

External formats for QMF objects

Chapter 1. QMF application development overview 5

The following topics are covered here:

Knowing when not to use procedures

© Copyright IBM Corp. 1982, 2007 7

Considerations for writing initial procedures

Initial procedures and Remote Unit of Work