Vous êtes sur la page 1sur 430

DB2 Universal Database for OS/390 and z/OS 

Command Reference
Version 7

SC26-9934-01
DB2 Universal Database for OS/390 and z/OS 

Command Reference
Version 7

SC26-9934-01
Note
Before using this information and the product it supports, be sure to read the
general information under “Notices” on page 357.

Second Edition, Softcopy Only (August 2001)


This edition applies to Version 7 of IBM DATABASE 2 Universal Database Server for OS/390 and z/OS (DB2 for
OS/390 and z/OS), 5675-DB2, and to any subsequent releases until otherwise indicated in new editions. Make sure
you are using the correct edition for the level of the product.
This softcopy version is based on the printed edition of the book and includes the changes indicated in the printed
version by vertical bars. Additional changes made to this softcopy version of the book since the hardcopy book was
published are indicated by the hash (#) symbol in the left-hand margin. Editorial changes that have no technical
significance are not noted.
This and other books in the DB2 for OS/390 and z/OS library are periodically updated with technical changes. These
updates are made available to licensees of the product on CD-ROM and on the Web (currently at
www.ibm.com/software/data/db2/os390/library.html). Check these resources to ensure that you are using the most
current information.
© Copyright International Business Machines Corporation 1983, 2001. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this book . . . . . . . . . . . . . . . . . . . . . . . . xv
Who should read this book . . . . . . . . . . . . . . . . . . . . xv
Conventions and terminology used in this book . . . . . . . . . . . . . xv
Naming conventions . . . . . . . . . . . . . . . . . . . . . . xv
Product terminology and citations . . . . . . . . . . . . . . . . xviii
How to read the syntax diagrams . . . . . . . . . . . . . . . . . xix
Prerequisite and related information . . . . . . . . . . . . . . . . . xx
How to send your comments. . . . . . . . . . . . . . . . . . . . xxi

Summary of changes to this book . . . . . . . . . . . . . . . . xxiii

Chapter 1. Privileges, authorization IDs, and the bind process . . . . . . 1


Privileges and authorization IDs . . . . . . . . . . . . . . . . . . . 1
The bind process . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2. Commands . . . . . . . . . . . . . . . . . . . . . . 3
DB2 command parsing . . . . . . . . . . . . . . . . . . . . . . 3
Parts of a DB2 command . . . . . . . . . . . . . . . . . . . . 3
Characters with special meanings . . . . . . . . . . . . . . . . . 4
Examples of Keyword Entry . . . . . . . . . . . . . . . . . . . 5
Scope of commands . . . . . . . . . . . . . . . . . . . . . . . 5
Output from DB2 commands . . . . . . . . . . . . . . . . . . . . 6
Issuing commands from IFI . . . . . . . . . . . . . . . . . . . . . 6
DSN subcommand parsing . . . . . . . . . . . . . . . . . . . . . 7
Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . 7
Description of commands . . . . . . . . . . . . . . . . . . . . . 7
The DSN command and its subcommands . . . . . . . . . . . . . . 7
DB2 commands . . . . . . . . . . . . . . . . . . . . . . . . 8
IMS commands. . . . . . . . . . . . . . . . . . . . . . . . 10
CICS attachment facility commands . . . . . . . . . . . . . . . . 10
MVS IRLM commands . . . . . . . . . . . . . . . . . . . . . 11
TSO CLISTs . . . . . . . . . . . . . . . . . . . . . . . . . 11
-ALTER BUFFERPOOL (DB2) . . . . . . . . . . . . . . . . . . . 12
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 12
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 12
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 12
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . . 16
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 18
-ALTER GROUPBUFFERPOOL (DB2) . . . . . . . . . . . . . . . . 19
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 19
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 19
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 19
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . . 21
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 22
-ALTER UTILITY (DB2) . . . . . . . . . . . . . . . . . . . . . . 23
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 23
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 23
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 23
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 25
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 25

© Copyright IBM Corp. 1983, 2001 iii


-ARCHIVE LOG (DB2) . . . . . . . . . . . . . . . . . . . . . . 26
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 26
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 26
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 27
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . . 29
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 30
BIND PACKAGE (DSN). . . . . . . . . . . . . . . . . . . . . . 32
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 32
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 32
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 36
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 36
BIND PLAN (DSN) . . . . . . . . . . . . . . . . . . . . . . . 38
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 38
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 38
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 41
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Options of BIND and REBIND for PLAN, PACKAGE, and TRIGGER PACKAGE 44
-CANCEL THREAD (DB2) . . . . . . . . . . . . . . . . . . . . . 77
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 77
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 77
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 77
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . . 78
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 81
/CHANGE (IMS) . . . . . . . . . . . . . . . . . . . . . . . . 82
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 82
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 82
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 82
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 82
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 83
DCLGEN (DECLARATIONS GENERATOR) (DSN) . . . . . . . . . . . . 84
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 84
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 84
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 85
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . . 88
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 90
/DISPLAY (IMS) . . . . . . . . . . . . . . . . . . . . . . . . 92
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 92
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 92
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 92
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 94
-DISPLAY ARCHIVE (DB2) . . . . . . . . . . . . . . . . . . . . 95
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 95
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 95
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 95
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 95
-DISPLAY BUFFERPOOL (DB2) . . . . . . . . . . . . . . . . . . 97
Environment . . . . . . . . . . . . . . . . . . . . . . . . . 97

iv Command Reference
Authorization. . . . . . . . . . . . . . . . . . . . . . . . . 97
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 97
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 103
-DISPLAY DATABASE (DB2) . . . . . . . . . . . . . . . . . . . 106
Environment . . . . . . . . . . . . . . . . . . . . . . . . 106
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 106
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 108
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 112
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 115
| -DISPLAY DDF (DB2) . . . . . . . . . . . . . . . . . . . . . . 119
| Environment . . . . . . . . . . . . . . . . . . . . . . . . 119
| Authorization . . . . . . . . . . . . . . . . . . . . . . . . 119
| Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 119
| Option descriptions . . . . . . . . . . . . . . . . . . . . . . 119
| Output . . . . . . . . . . . . . . . . . . . . . . . . . . 119
| Examples . . . . . . . . . . . . . . . . . . . . . . . . . 120
-DISPLAY FUNCTION SPECIFIC (DB2) . . . . . . . . . . . . . . . 121
Environment . . . . . . . . . . . . . . . . . . . . . . . . 121
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 121
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 121
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 122
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 123
-DISPLAY GROUP (DB2) . . . . . . . . . . . . . . . . . . . . 125
Environment . . . . . . . . . . . . . . . . . . . . . . . . 125
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 125
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 125
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 125
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 127
-DISPLAY GROUPBUFFERPOOL (DB2) . . . . . . . . . . . . . . . 129
Environment . . . . . . . . . . . . . . . . . . . . . . . . 129
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 129
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 130
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 136
-DISPLAY LOCATION (DB2) . . . . . . . . . . . . . . . . . . . 143
Environment . . . . . . . . . . . . . . . . . . . . . . . . 143
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 143
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 143
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 144
-DISPLAY LOG (DB2) . . . . . . . . . . . . . . . . . . . . . . 146
Environment . . . . . . . . . . . . . . . . . . . . . . . . 146
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 146
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 146
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 146

Contents v
-DISPLAY PROCEDURE (DB2) . . . . . . . . . . . . . . . . . . 148
Environment . . . . . . . . . . . . . . . . . . . . . . . . 148
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 148
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 148
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 150
-DISPLAY RLIMIT (DB2) . . . . . . . . . . . . . . . . . . . . . 152
Environment . . . . . . . . . . . . . . . . . . . . . . . . 152
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 152
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 152
-DISPLAY THREAD (DB2) . . . . . . . . . . . . . . . . . . . . 153
Environment . . . . . . . . . . . . . . . . . . . . . . . . 153
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 153
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 154
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 157
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 160
-DISPLAY TRACE (DB2) . . . . . . . . . . . . . . . . . . . . . 165
Environment . . . . . . . . . . . . . . . . . . . . . . . . 165
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 165
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 166
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 169
-DISPLAY UTILITY (DB2) . . . . . . . . . . . . . . . . . . . . 171
Environment . . . . . . . . . . . . . . . . . . . . . . . . 171
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 171
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 171
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 172
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 173
DSN (TSO) . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Environment . . . . . . . . . . . . . . . . . . . . . . . . 175
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 175
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 175
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 176
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 177
DSNC (CICS attachment facility) . . . . . . . . . . . . . . . . . . 178
Environment . . . . . . . . . . . . . . . . . . . . . . . . 178
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 178
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 178
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 178
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 178
DSNC DISCONNECT (CICS attachment facility) . . . . . . . . . . . . 179
Environment . . . . . . . . . . . . . . . . . . . . . . . . 179
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 179
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Option description . . . . . . . . . . . . . . . . . . . . . . 179
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 179
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 179
DSNC DISPLAY (CICS attachment facility) . . . . . . . . . . . . . . 180

vi Command Reference
Environment . . . . . . . . . . . . . . . . . . . . . . . . 180
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 180
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 180
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 181
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 182
DSNC MODIFY (CICS attachment facility) . . . . . . . . . . . . . . 184
Environment . . . . . . . . . . . . . . . . . . . . . . . . 184
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 184
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 184
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 185
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 185
DSNC STOP (CICS attachment facility) . . . . . . . . . . . . . . . 186
Environment . . . . . . . . . . . . . . . . . . . . . . . . 186
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 186
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 186
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 186
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 186
DSNC STRT (CICS attachment facility) . . . . . . . . . . . . . . . 187
Environment . . . . . . . . . . . . . . . . . . . . . . . . 187
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 187
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 187
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 187
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 187
DSNH (TSO CLIST) . . . . . . . . . . . . . . . . . . . . . . 189
Environment . . . . . . . . . . . . . . . . . . . . . . . . 189
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 189
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Summary of DSNH CLIST parameters . . . . . . . . . . . . . . . 190
General parameter descriptions . . . . . . . . . . . . . . . . . 193
DSNH/DSN subcommand summary . . . . . . . . . . . . . . . . 207
DSNH CLIST/BIND PLAN subcommand comparison . . . . . . . . . 207
DSNH CLIST/BIND PACKAGE subcommand comparison . . . . . . . . 210
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 213
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 214
END (DSN). . . . . . . . . . . . . . . . . . . . . . . . . . 217
Environment . . . . . . . . . . . . . . . . . . . . . . . . 217
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 217
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 217
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 217
FREE PACKAGE (DSN) . . . . . . . . . . . . . . . . . . . . . 218
Environment . . . . . . . . . . . . . . . . . . . . . . . . 218
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 218
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 219
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 219
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 220
FREE PLAN (DSN) . . . . . . . . . . . . . . . . . . . . . . . 221
Environment . . . . . . . . . . . . . . . . . . . . . . . . 221
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 221
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Contents vii
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 221
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 222
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 222
MODIFY irlmproc,ABEND (MVS IRLM) . . . . . . . . . . . . . . . 223
Environment . . . . . . . . . . . . . . . . . . . . . . . . 223
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 223
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 223
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 223
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 223
| MODIFY irlmproc,DIAG (MVS IRLM) . . . . . . . . . . . . . . . . 225
Environment . . . . . . . . . . . . . . . . . . . . . . . . 225
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 225
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 225
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 226
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 226
| MODIFY irlmproc,PURGE (MVS IRLM) . . . . . . . . . . . . . . . 227
| Environment . . . . . . . . . . . . . . . . . . . . . . . . 227
| Authorization . . . . . . . . . . . . . . . . . . . . . . . . 227
| Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 227
| Option descriptions . . . . . . . . . . . . . . . . . . . . . . 227
| Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 227
| Example . . . . . . . . . . . . . . . . . . . . . . . . . . 227
MODIFY irlmproc,SET (MVS IRLM) . . . . . . . . . . . . . . . . . 228
Environment . . . . . . . . . . . . . . . . . . . . . . . . 228
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 228
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 228
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 229
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 230
MODIFY irlmproc,STATUS (MVS IRLM) . . . . . . . . . . . . . . . 232
Environment . . . . . . . . . . . . . . . . . . . . . . . . 232
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 232
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 232
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 233
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 233
-MODIFY TRACE (DB2) . . . . . . . . . . . . . . . . . . . . . 238
Environment . . . . . . . . . . . . . . . . . . . . . . . . 238
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 238
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 238
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 239
REBIND PACKAGE (DSN) . . . . . . . . . . . . . . . . . . . . 240
Environment . . . . . . . . . . . . . . . . . . . . . . . . 240
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 240
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 243
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 243
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 243
REBIND PLAN (DSN) . . . . . . . . . . . . . . . . . . . . . . 244
Environment . . . . . . . . . . . . . . . . . . . . . . . . 244
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 244
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 247

viii Command Reference


Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 247
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 247
REBIND TRIGGER PACKAGE (DSN) . . . . . . . . . . . . . . . . 248
Environment . . . . . . . . . . . . . . . . . . . . . . . . 248
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 248
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 249
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 250
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 250
-RECOVER BSDS (DB2). . . . . . . . . . . . . . . . . . . . . 251
Environment . . . . . . . . . . . . . . . . . . . . . . . . 251
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 251
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 251
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 251
-RECOVER INDOUBT (DB2) . . . . . . . . . . . . . . . . . . . 252
Environment . . . . . . . . . . . . . . . . . . . . . . . . 252
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 252
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 252
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 254
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 254
-RECOVER POSTPONED (DB2). . . . . . . . . . . . . . . . . . 255
Environment . . . . . . . . . . . . . . . . . . . . . . . . 255
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 255
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 255
| Option descriptions . . . . . . . . . . . . . . . . . . . . . . 255
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 255
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 256
-RESET GENERICLU (DB2) . . . . . . . . . . . . . . . . . . . 257
Environment . . . . . . . . . . . . . . . . . . . . . . . . 257
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 257
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 257
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 257
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 258
-RESET INDOUBT (DB2) . . . . . . . . . . . . . . . . . . . . 259
Environment . . . . . . . . . . . . . . . . . . . . . . . . 259
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 259
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 260
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 261
RUN (DSN). . . . . . . . . . . . . . . . . . . . . . . . . . 262
Environment . . . . . . . . . . . . . . . . . . . . . . . . 262
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 262
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 262
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 264
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 264
-SET ARCHIVE (DB2) . . . . . . . . . . . . . . . . . . . . . . 265
Environment . . . . . . . . . . . . . . . . . . . . . . . . 265
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 265
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Contents ix
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 265
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 266
Output . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 266
| -SET SYSPARM (DB2) . . . . . . . . . . . . . . . . . . . . . 268
| Environment . . . . . . . . . . . . . . . . . . . . . . . . 268
| Authorization . . . . . . . . . . . . . . . . . . . . . . . . 268
| Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 268
| Option descriptions . . . . . . . . . . . . . . . . . . . . . . 268
| Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 268
| Examples . . . . . . . . . . . . . . . . . . . . . . . . . 268
-SET LOG (DB2). . . . . . . . . . . . . . . . . . . . . . . . 270
Environment . . . . . . . . . . . . . . . . . . . . . . . . 270
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 270
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 270
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 271
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 271
SPUFI (DSN) . . . . . . . . . . . . . . . . . . . . . . . . . 273
Environment . . . . . . . . . . . . . . . . . . . . . . . . 273
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 273
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 273
/SSR (IMS) . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Environment . . . . . . . . . . . . . . . . . . . . . . . . 274
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 274
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Option description . . . . . . . . . . . . . . . . . . . . . . 274
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 274
/START (IMS) . . . . . . . . . . . . . . . . . . . . . . . . . 275
Environment . . . . . . . . . . . . . . . . . . . . . . . . 275
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 275
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 275
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 275
-START DATABASE (DB2) . . . . . . . . . . . . . . . . . . . . 276
Environment . . . . . . . . . . . . . . . . . . . . . . . . 276
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 276
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 277
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 280
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 282
-START DB2 (DB2) . . . . . . . . . . . . . . . . . . . . . . . 283
Environment . . . . . . . . . . . . . . . . . . . . . . . . 283
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 283
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 283
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 284
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 285
-START DDF (DB2). . . . . . . . . . . . . . . . . . . . . . . 286
Environment . . . . . . . . . . . . . . . . . . . . . . . . 286
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 286
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 286
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 286
-START FUNCTION SPECIFIC (DB2) . . . . . . . . . . . . . . . . 287

x Command Reference
Environment . . . . . . . . . . . . . . . . . . . . . . . . 287
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 287
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 288
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 288
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 289
START irlmproc (MVS IRLM) . . . . . . . . . . . . . . . . . . . 290
Environment . . . . . . . . . . . . . . . . . . . . . . . . 290
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 290
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 290
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 293
-START PROCEDURE (DB2) . . . . . . . . . . . . . . . . . . . 294
Environment . . . . . . . . . . . . . . . . . . . . . . . . 294
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 294
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 295
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 295
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 296
-START RLIMIT (DB2). . . . . . . . . . . . . . . . . . . . . . 297
Environment . . . . . . . . . . . . . . . . . . . . . . . . 297
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 297
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Option description . . . . . . . . . . . . . . . . . . . . . . 297
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 298
-START TRACE (DB2) . . . . . . . . . . . . . . . . . . . . . 299
Environment . . . . . . . . . . . . . . . . . . . . . . . . 299
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 299
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 300
The destination block . . . . . . . . . . . . . . . . . . . . . 301
The constraint block . . . . . . . . . . . . . . . . . . . . . 302
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 307
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 308
/STOP (IMS) . . . . . . . . . . . . . . . . . . . . . . . . . 309
Environment . . . . . . . . . . . . . . . . . . . . . . . . 309
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 309
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 309
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 309
-STOP DATABASE (DB2) . . . . . . . . . . . . . . . . . . . . 310
Environment . . . . . . . . . . . . . . . . . . . . . . . . 310
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 310
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 311
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 313
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 315
-STOP DB2 (DB2) . . . . . . . . . . . . . . . . . . . . . . . 316
Environment . . . . . . . . . . . . . . . . . . . . . . . . 316
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 316
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 316
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 317
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 317
-STOP DDF (DB2) . . . . . . . . . . . . . . . . . . . . . . . 318
Environment . . . . . . . . . . . . . . . . . . . . . . . . 318

Contents xi
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 318
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 318
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 319
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 320
-STOP FUNCTION SPECIFIC . . . . . . . . . . . . . . . . . . . 321
Environment . . . . . . . . . . . . . . . . . . . . . . . . 321
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 321
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 322
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 322
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 323
STOP irlmproc (MVS IRLM). . . . . . . . . . . . . . . . . . . . 324
Environment . . . . . . . . . . . . . . . . . . . . . . . . 324
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 324
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Option description . . . . . . . . . . . . . . . . . . . . . . 324
Usage note . . . . . . . . . . . . . . . . . . . . . . . . . 324
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 324
-STOP PROCEDURE (DB2) . . . . . . . . . . . . . . . . . . . 326
Environment . . . . . . . . . . . . . . . . . . . . . . . . 326
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 326
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 327
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 328
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 328
-STOP RLIMIT (DB2) . . . . . . . . . . . . . . . . . . . . . . 329
Environment . . . . . . . . . . . . . . . . . . . . . . . . 329
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 329
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 329
-STOP TRACE (DB2) . . . . . . . . . . . . . . . . . . . . . . 330
Environment . . . . . . . . . . . . . . . . . . . . . . . . 330
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 330
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 331
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 334
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 334
-TERM UTILITY (DB2) . . . . . . . . . . . . . . . . . . . . . 335
Environment . . . . . . . . . . . . . . . . . . . . . . . . 335
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 335
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 335
Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 336
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 337
/TRACE (IMS). . . . . . . . . . . . . . . . . . . . . . . . . 338
Environment . . . . . . . . . . . . . . . . . . . . . . . . 338
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 338
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 338
Examples . . . . . . . . . . . . . . . . . . . . . . . . . 338
TRACE CT (MVS IRLM) . . . . . . . . . . . . . . . . . . . . . 340
Environment . . . . . . . . . . . . . . . . . . . . . . . . 340
Authorization . . . . . . . . . . . . . . . . . . . . . . . . 340
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Option descriptions . . . . . . . . . . . . . . . . . . . . . . 340

xii Command Reference


Usage notes . . . . . . . . . . . . . . . . . . . . . . . . 341

| Appendix A. Directory of subsystem parameters . . . . . . . . . . . 343


| Editing the subsystem parameters and DSNHDECP values . . . . . . . . 343
| Directory of subsystem parameters and DSNHDECP values. . . . . . . . 343

Appendix B. How to use the DB2 library . . . . . . . . . . . . . . 349

Appendix C. How to obtain DB2 information . . . . . . . . . . . . 351


DB2 on the Web . . . . . . . . . . . . . . . . . . . . . . . . 351
DB2 publications . . . . . . . . . . . . . . . . . . . . . . . . 351
BookManager format . . . . . . . . . . . . . . . . . . . . . 351
PDF format . . . . . . . . . . . . . . . . . . . . . . . . . 351
# CD-ROMs and DVD . . . . . . . . . . . . . . . . . . . . . 351
DB2 education . . . . . . . . . . . . . . . . . . . . . . . . 352
How to order the DB2 library . . . . . . . . . . . . . . . . . . . 352
Subscription through the Publication Notification System (PNS) . . . . . . 352

Appendix D. Summary of changes to DB2 for OS/390 and z/OS Version 7 353
Enhancements for managing data . . . . . . . . . . . . . . . . . 353
Enhancements for reliability, scalability, and availability. . . . . . . . . . 353
Easier development and integration of e-business applications . . . . . . . 354
Improved connectivity . . . . . . . . . . . . . . . . . . . . . . 355
Features of DB2 for OS/390 and z/OS . . . . . . . . . . . . . . . . 356
Migration considerations . . . . . . . . . . . . . . . . . . . . . 356

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Programming interface information . . . . . . . . . . . . . . . . . 358
Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 359

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 379

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Contents xiii
xiv Command Reference
About this book
This is a reference book that lists numerous commands that system administrators,
database administrators, and application programmers use. The commands are in
alphabetical order for quick retrieval.

Important
In this version of DB2® for OS/390® and z/OS, some utility functions are
available as optional products. You must separately order and purchase a
license to such utilities, and discussion of those utility functions in this
publication is not intended to otherwise imply that you have a license to them.

Who should read this book


This book presents reference information for people involved in system
administration, database administration, and operation. It presents detailed
information on commands, including syntax, option descriptions, and examples for
each command.

Conventions and terminology used in this book


Naming conventions that are unique to DB2 commands are discussed in “Naming
conventions”. Terminology is discussed in “Product terminology and citations” on
page xviii.

Naming conventions
When a parameter refers to an object created by SQL statements (for example,
tables, table spaces, and indexes), SQL syntactical naming conventions are
followed.

This section describes naming conventions unique to commands. Characters are


classified as letters, digits, or special characters.
v A letter is any one of the uppercase characters A through Z (plus the three
characters reserved as alphabetic extenders for national languages, #, @, and $
in the United States).
v A digit is any one of the characters 0 through 9.
v A special character is any character other than a letter or a digit.
See Chapter 2 of DB2 SQL Reference for an additional explanation of long
identifiers, short identifiers, and location identifiers.
authorization-id
A short identifier of 1 to 8 letters, digits, or the underscore that identifies a set of
privileges. An authorization ID must begin with a letter.
collection-id
An SQL long identifier of 1 to 18 letters, digits, or the underscore that identifies
a collection of packages; therefore, a collection ID is a qualifier for a package
ID. A collection ID must begin with a letter.
A collection ID should not begin with DSN; this can sometimes conflict with
DB2-provided collection IDs. If a collection ID beginning with DSN is specified,
DB2 issues a warning message.

© Copyright IBM Corp. 1983, 2001 xv


connection-name
An identifier of 1 to 8 characters that identifies an address space connection to
DB2. A connection identifier is one of the following:
v For DSN processes running in TSO foreground, the connection name “TSO”
is used.
v For DSN processes running in TSO batch, the connection name BATCH is
used.
v For the call attachment facility (CAF), the connection name DB2CALL is
used.
v For the Recoverable Resource Manager Services attachment facility
(RRSAF), the connection name RRSAF is used.
v For IMS and CICS processes, the connection name is the system
identification name.

See Part 4 (Volume 1) of DB2 Administration Guide for more information about
connection names.
correlation-id
An identifier of 1 to 12 characters that identifies a process within an address
space connection. A correlation ID must begin with a letter.
A correlation ID can be one of the following:
v For DSN processes running in TSO foreground, the correlation ID is the TSO
logon identifier.
v For DSN processes running in TSO batch, the correlation ID is the job name.
v For CAF processes, the correlation ID is the TSO logon identifier.
v For RRSAF processes, the correlation ID is the value specified during
signon.
v For IMS processes, the correlation ID is pst#.psbname.
v For CICS processes, the correlation ID is
identifier.thread_number.transaction_identifier.

See Part 4 (Volume 1) of DB2 Administration Guide for more information about
correlation IDs.
data-set-name
An identifier of 1 to 44 characters that identifies a data set.
dbrm-member-name
An identifier of 1 to 8 letters or digits that identifies a member of a partitioned
data set. (MVS requires this naming convention.)
A DBRM member name should not begin with DSN; this can sometimes conflict
with DB2-provided DBRM member names. If a DBRM member name beginning
with DSN is specified, DB2 issues a warning message.
dbrm-pds-name
An identifier of 1 to 44 characters that identifies a partitioned data set.
ddname
An identifier of 1 to 8 characters that designates the name of a DD statement.
hexadecimal-constant
A sequence of digits or any of the letters from A to F (uppercase or lowercase).

xvi Command Reference


hexadecimal-string
An X followed by a sequence of characters that begins and ends with an
apostrophe. The characters between the string delimiters must be a
hexadecimal number.
ip address (or Internet address)
A 4 byte value that uniquely identifies a TCP/IP host within the TCP/IP network.
IP addresses are usually displayed in a format called dotted decimal, where
each byte of the IP address is displayed in decimal format with a period
delimiting each number.
location-name
A location identifier of 1 to 16 letters (but excluding the alphabetic extenders),
digits or the underscore that identifies an instance of a data base management
system. A location name must begin with a letter.
luname
An SQL short identifier of 1 to 8 characters that identifies a logical unit name.
An luname must begin with a letter.
luwid
A fully qualified LU network name and an LUW instance number.
The LU network name consists of an optional 8 character network ID, a period,
and an 8 character network LU name. If you indicate no network ID, no period
is required. The LUW instance number consists of 12 hex characters that
uniquely identify the unit of work.
member-name
An identifier of 1 to 8 characters that identifies either a member of a partitioned
data set (MVS requires this naming convention) or a member of a data sharing
group.
A name for a member of a partitioned data set should not begin with DSN; this
can sometimes conflict with DB2-provided member names. If a name beginning
with DSN is specified, DB2 issues a warning message.
package-id
An SQL short identifier of 1 to 8 letters, digits, or underscores that identifies a
package. For packages created under DB2, a package ID is the name of the
program whose precompilation produced the package’s DBRM. A package ID
must begin with a letter. (MVS requires this naming convention.)
A package ID should not begin with DSN; this can sometimes conflict with
DB2-provided package IDs. If a package ID beginning with DSN is specified,
DB2 issues a warning message.
package-name
A name given to the object created during the bind process of a single package.
A package name consists of a location name, a collection ID, and a package ID
separated by periods. An additional attribute, a version ID, allows for multiple
versions of a package to have the same name.
plan-name
An SQL short identifier of 1 to 8 letters, digits or underscores that identifies an
application plan. A plan name must begin with a letter.
A plan name should not begin with DSN; this can sometimes conflict with
DB2-provided plan names. If a plan name beginning with DSN is specified, DB2
issues a warning message.

About this book xvii


qualifier-name
An SQL short identifier of 1 to 8 letters, digits, or the underscore that identifies
the implicit qualifier for unqualified table names, views, indexes, and aliases.
string
A sequence of characters that begins and ends with an apostrophe.
subsystem-name
An identifier that specifies the DB2 subsystem as it is known to MVS.
table-name
A qualified or unqualified name that designates a table. A table name can
contain one or two parts, depending upon its qualification. The first part is the
authorization ID that designates the owner of the table; the second part is an
SQL long identifier. A period must separate each of the parts.
table-space-name
A short identifier that designates a table space of an identified database. If a
database is not identified, a table space name specifies a table space of
database DSNDB04.
utility-id
An identifier of 1 to 16 characters that uniquely identifies a utility process within
DB2. A utility ID must begin with a letter, and the identifier can contain periods.
| version-id
| An SQL identifier of 1 to 64 lowercase alphabetic letters, uppercase alphabetic
| letters, digits, underscores, at signs (@), number signs (#), dollar signs ($),
| dashes and periods that is assigned to a package when the package is created.
| The version ID that is assigned is taken from the version ID associated with the
| program being bound. Version IDs are specified for programs as a parameter of
| the DB2 precompile.

Product terminology and citations


In this book, DB2 Universal Database™ Server for OS/390 and z/OS is referred to
as "DB2 for OS/390 and z/OS." In cases where the context makes the meaning
clear, DB2 for OS/390 and z/OS is referred to as "DB2." When this book refers to
other books in this library, a short title is used. (For example, "See DB2 SQL
Reference" is a citation to IBM® DATABASE 2™ Universal Database Server for
OS/390 and z/OS SQL Reference.)

When referring to a DB2 product other than DB2 for OS/390 and z/OS, this book
uses the product’s full name to avoid ambiguity.

The following terms are used as indicated:


DB2 Represents either the DB2 licensed program or a particular DB2
subsystem.
C and C language
Represent the C programming language.
CICS® Represents CICS/ESA® and CICS Transaction Server for OS/390.
IMS™ Represents IMS or IMS/ESA®.
MVS Represents the MVS element of OS/390.
OS/390
Represents the OS/390 or z/OS operating system.

xviii Command Reference


RACF®
Represents the functions that are provided by the RACF component of the
SecureWay® Security Server for OS/390 or by the RACF component of the
OS/390 Security Server.

How to read the syntax diagrams


The following rules apply to the syntax diagrams used in this book:
v Read the syntax diagrams from left to right, from top to bottom, following the path
of the line.
The ─── symbol indicates the beginning of a statement.
The ─── symbol indicates that the statement syntax is continued on the next
line.
The ─── symbol indicates that a statement is continued from the previous line.
The ─── symbol indicates the end of a statement.
v Required items appear on the horizontal line (the main path).

 required_item 

v Optional items appear below the main path.

 required_item 
optional_item

If an optional item appears above the main path, that item has no effect on the
execution of the statement and is used only for readability.

optional_item
 required_item 

v If you can choose from two or more items, they appear vertically, in a stack.
If you must choose one of the items, one item of the stack appears on the main
path.

 required_item required_choice1 
required_choice2

If choosing one of the items is optional, the entire stack appears below the main
path.

 required_item 
optional_choice1
optional_choice2

If one of the items is the default, it appears above the main path and the
remaining choices are shown below.

About this book xix


default_choice
 required_item 
optional_choice
optional_choice

v An arrow returning to the left, above the main line, indicates an item that can be
repeated.

 required_item  repeatable_item 

If the repeat arrow contains a comma, you must separate repeated items with a
comma.

 required_item  repeatable_item 

A repeat arrow above a stack indicates that you can repeat the items in the
stack.
v Keywords appear in uppercase (for example, FROM). They must be spelled exactly
as shown. Variables appear in all lowercase letters (for example, column-name).
They represent user-supplied names or values.
v If punctuation marks, parentheses, arithmetic operators, or other such symbols
are shown, you must enter them as part of the syntax.

Prerequisite and related information


This book is intended to serve as a reference for people who understand system
administration, database administration, or application programming in the DB2
environment. You should have some knowledge of:
v CICS, IMS, or TSO
v MVS Job Control Language (JCL)
v Structured Query Language (SQL)

xx Command Reference
How to send your comments
Your feedback helps IBM to provide quality information. Please send any comments
that you have about this book or other DB2 for OS/390 and z/OS documentation.
You can use any of the following methods to provide comments:
v Send your comments by e-mail to db2pubs@vnet.ibm.com and include the name
of the product, the version number of the product, and the number of the book. If
you are commenting on specific text, please list the location of the text (for
example, a chapter and section title, page number, or a help topic title).
v Send your comments from the Web. Visit the Web site at:

http://www.ibm.com/software/db2os390

The Web site has a feedback page that you can use to send comments.
v Complete the readers’ comment form at the back of the book and return it by
mail, by fax (800-426-7773 for the United States and Canada), or by giving it to
an IBM representative.

About this book xxi


xxii Command Reference
Summary of changes to this book
| The principal changes to this book are as follows:
| v Chapter 2. Commands introduces the following new commands:
| – “-SET SYSPARM (DB2)” on page 268
| – “-DISPLAY DDF (DB2)” on page 119
| – “MODIFY irlmproc,PURGE (MVS IRLM)” on page 227.
| v New options are available for the following commands:
| – “-CANCEL THREAD (DB2)” on page 77
| - NOBACKOUT
| – “-DISPLAY THREAD (DB2)” on page 153
| - RRSURID
| – “DSN (TSO)” on page 175
| - GROUP
| – “MODIFY irlmproc,DIAG (MVS IRLM)” on page 225
| - PLOCK
| - ALL
| - NONE
| – “-RECOVER POSTPONED (DB2)” on page 255
| - CANCEL
| – “-SET LOG (DB2)” on page 270
| - SUSPEND
| - RESUME
| - CHKTIME
| – “-START DB2 (DB2)” on page 283
| - LIGHT

| For information about the changes to the Version 7 product, see “Appendix D.
| Summary of changes to DB2 for OS/390 and z/OS Version 7” on page 353.

© Copyright IBM Corp. 1983, 2001 xxiii


xxiv Command Reference
Chapter 1. Privileges, authorization IDs, and the bind process
Thic chapter contains information about the privileges and authorization IDs that are
required to issue various commands and a summary of the bind process.

Privileges and authorization IDs


The issuer of a command can be an individual user. It can also be a program
running in batch mode or an IMS or CICS transaction. We use the term process to
represent any or all of those.

A process is represented to DB2 by a set of identifiers (IDs). What the process can
do with DB2 is determined by privileges and authorities that can be held by its
identifiers. We use “the privilege set of a process” to mean the entire set of
privileges and authorities that can be used by the process in a specific situation.

There are three types of identifiers: primary authorization IDs, secondary


authorization IDs, and SQL IDs.
v Generally it is the primary authorization ID that identifies a specific process. For
example, in the process initiated through the TSO attachment facility, the primary
authorization ID is identical to the TSO logon ID. A trace record identifies the
process by that ID.
v Secondary authorization IDs, which are optional, can hold additional privileges
available to the process. A secondary authorization ID is often a Resource
Access Control Facility group ID. For example, a process can belong to a RACF®
group that holds the LOAD privilege on a particular database. Any member of the
group can run the LOAD utility to load table spaces in the database.
DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.
v An SQL authorization ID (SQL ID) holds the privileges exercised when issuing
certain dynamic SQL statements. This ID plays little part in the commands
described in this book.

Within DB2, a process can be represented by a primary authorization ID and


possibly one or more secondary IDs. For detailed instructions on how to associate a
process with one or more IDs, and how to grant privileges to those IDs, see Part 3
(Volume 1) of DB2 Administration Guide.

A privilege or authority is granted to, or revoked from, an identifier by executing an


SQL GRANT or REVOKE statement. For the complete syntax of those statements,
see Chapter 5 of DB2 SQL Reference.

The bind process


The bind process establishes a relationship between an application program and its
relational data. This step is necessary before you can execute your program.
Currently, DB2 allows you two basic ways of binding a program: to a package, or
directly to an application plan. If your application uses DRDA access to distribute
data, then you must use packages.

During the precompilation process, the DB2 precompiler produces both modified
source code and a database request module (DBRM) for each application program.

© Copyright IBM Corp. 1983, 2001 1


The modified source code must be compiled and link-edited before the application
program can be run. DBRMs must be bound to a plan or package.

When determining the maximum size of a plan, you must consider several physical
limitations, including the time required to bind the plan, the size of the EDM pool,
and fragmentation. There are no restrictions to the number of DBRMs that can be
included in a plan. However, packages provide a more flexible method for handling
large numbers of DBRMs within a plan. As a general rule, it is suggested that the
EDM pool be at least 10 times the size of the largest DBD or plan, whichever is
greater. For further information, see Part 2 of DB2 Installation Guide.

The BIND PACKAGE subcommand allows you to bind DBRMs individually. It gives
you the ability to test different versions of an application without extensive
rebinding. Package binding is also the only method for binding applications at
remote sites.

Even when they are bound into packages, all programs must be designated in an
application plan. BIND PLAN establishes the relationship between DB2 and all
DBRMs or packages in that plan. Plans can specify explicitly named DBRMs,
packages, collections of packages, or a combination of these elements. The plan
contains information about the designated DBRMs or packages and about the data
the application program intends to use. It is stored in the DB2 catalog.

In addition to building packages and plans, the bind process:


v Validates the SQL statements using the DB2 catalog. During the bind
process, DB2 checks your SQL statements for valid table, view, and column
names. Because the bind process occurs as a separate step before program
execution, errors are detected and can be corrected before the program is
executed.
v Verifies that the process binding the program is authorized to perform the
data accessing operations requested by your program’s SQL statements.
When you issue BIND, you can specify an authorization ID as the owner of the
plan or package. The owner can be any one of the authorization IDs of the
process performing the bind. The bind process determines whether the owner of
the plan or package is authorized to access the data the program requests.
v Selects the access paths needed to access the DB2 data your program
wants to process. In selecting an access path, DB2 considers indexes, table
sizes, and other factors. DB2 considers all indexes available to access the data
and decides which ones (if any) to use when selecting a path to the data.

BIND PLAN and BIND PACKAGE can be accomplished using DB2I panels, the
DSNH CLIST, or the DSN subcommands BIND PLAN and BIND PACKAGE. For a
detailed explanation of binding with DSNH CLIST, see Chapter 2. Commands. A
complete description of the bind process can be found in Part 5 of DB2 Application
Programming and SQL Guide. Further information on BIND can be found in “BIND
PACKAGE (DSN)” on page 32 and in “BIND PLAN (DSN)” on page 38. Information
about specific options for BIND PLAN and BIND PACKAGE can be found in
“Options of BIND and REBIND for PLAN, PACKAGE, and TRIGGER PACKAGE” on
page 44.

2 Command Reference
Chapter 2. Commands
This chapter contains syntax diagrams, semantic descriptions, rules, and usage
examples of commands, organized alphabetically by command name.

The tables at the beginning of this chapter summarize the commands that follow.
Each table lists commands of one type, describes their functions, and refers to the
page on which a complete description begins.

DB2 command parsing


DB2 commands follow a pattern like this:

Recognition character
Command
Primary keyword
Value

-DISPLAY DATABASE(J64DBASE),SPACENAM(PROJ32)
Value
Keyword
Separators

Parts of a DB2 command


The parts of a command are:
v Recognition character. It is shown as a hyphen throughout this book, with the
following exceptions:
– If the command is issued from an MVS console, the recognition character
must be the command prefix.
In DB2 Version 7, the command prefix can be up to eight characters. The
default is '-DSN1'. However, the majority of examples in this book assume that
the command prefix has been defined as a hyphen (-). Examples involving
members of a data sharing group demonstrate the use of multi-character
command prefixes, such as -DB1G.
Inserting a space between the command prefix and the command is optional.
For example, you can use either one of the following formats:
-DB1GDIS THREAD(*)
-DB1G DIS THREAD(*)
Using a space makes it easier for users to identify the command, especially
when the command prefix has multiple characters.

The command prefix can be defined at installation time. For more information,
see Part 2 of DB2 Installation Guide.
– If the command is issued from an IMS terminal, the recognition character
must be the command recognition character (CRC). The command recognition
character is defined in the IMS SSM PROCLIB member. For more information,
see IMS Customization Guide.
– If the command is issued from a CICS terminal or under the DSN command
processor, the recognition character must be a hyphen.
v Command name. Command names have abbreviations, which are provided in
the command descriptions in this chapter.

© Copyright IBM Corp. 1983, 2001 3


v Operands. These are combinations of keywords and parameters that can be
specified for the command.
– Keywords can be required or optional. They must be entered exactly as
shown in the descriptions of the commands.
– A keyword can have zero or more parameters. A parameter list, if present,
must be enclosed in parentheses.
– Separators. These can be one or more blanks or commas. An open
parenthesis marks the beginning of a parameter list; no separator is needed.
Optionally, an equal sign can be used to separate a single parameter from its
keyword without using parentheses.

Characters with special meanings


The following characters have special meaning for the syntax of DB2 commands:
A blank is a separator.
Multiple blanks are equivalent to a single blank, except in strings enclosed
between apostrophes.
, A comma is a separator.
' An apostrophe is the usual SQL string constant delimiter, and marks the
beginning or end of a string constant in SQL. (In COBOL programs only, the
QUOTESQL precompiler option allows you to choose the quotation mark as
the SQL string delimiter; the apostrophe is then the SQL escape character.)
Letters not in string constants are changed to uppercase. Two successive
apostrophes in a string constant are changed to one apostrophe. Blanks,
commas, equal signs, and parentheses in string constants are treated as
literal characters, and are not recognized as separators.
There is an exception to the rule about changing letters to uppercase. If the
CODED CHARACTER SET install option is set to 930 or 5026 during
installation, the letters are not folded to uppercase, whether in an SQL
string constant or not.
" A quotation mark is the SQL escape character, and marks the beginning or
end of an SQL delimited identifier. (In COBOL programs only, the
QUOTESQL precompiler option allows you to choose the apostrophe as the
SQL escape character; the double quotation mark is then the SQL string
delimiter.)
Within a string delimited by quotation marks, two successive quotation
marks are changed to one. Other rules are the same as for SQL string
constants.
= An equal sign separates a single parameter from a keyword. Thus, an equal
sign is used as a separator for keywords that have only one parameter. An
equal sign can be used for keywords with multiple parameters when only
one member of the parameter list is specified.
( An open parenthesis marks the beginning of a parameter list.
) A close parenthesis marks the end of a parameter list.
: A colon means an inclusive range. For example, (A:D) means the same as
(A,B,C,D); (1:5) means (1,2,3,4,5). The colon can be used this way only in
commands where this operation is specifically permitted.
* An asterisk means any of the following usages:

4 Command Reference
* A single asterisk as a keyword_value indicates all. For example:
-DISPLAY UTILITY (*)
*keyword_value
An asterisk as the first character of a keyword_value indicates that
a match for the value will be satisfied when all characters following
the * are the same. For example: (*BCD)
keyword*value
An intermediate asterisk indicates that a match for the value will be
satisfied when all characters preceding and all characters following
the asterisk are the same. For example: (ABC*EFG)
keyword_value*
An asterisk as the final character of a keyword_value indicates that
a match will for the value will be satisfied when all characters
preceding the asterisk are the same. For example: (ABC*)
*keyword*_value*
Asterisks used as the first, intermediate and final characters in a
string are also valid. For example: (*BCD*FGH*)

For example, DISPLAY UTILITY (*) displays the status of all utilities;
DISPLAY UTILITY (R2*) displays the status of all utilities whose identifiers
begin with R2.

The asterisk pattern-matching character is available to all DB2 commands,


but not all DB2 commands support an asterisk. The asterisk can be used
this way only in commands in which the operation is specifically permitted.
NO (two-character string) negates the keyword that follows.
A negated keyword means the opposite of the keyword itself, and is often
used to override a keyword default. In keywords that have no opposite
meaning, the initial characters NO can be merely part of the keyword itself;
for example, in NODE.

Examples of Keyword Entry


The following are general examples of valid keywords and parameters:
v MODE (FORCE)
v MODE=FORCE
v MODE (NOFORCE) (keyword negation)
v MODE=NOFORCE (keyword negation)
v DATABASE(name1 name2 . . . namen) ACCESS(RO)
v SPACENAM (name1,name2) ACCESS(RO)
v ACCESS (RO),SPACENAM=name
v Combinations of the above

Do not use more than one parameter after an equal sign, or an error condition will
occur.

Scope of commands
In a data sharing environment, the scope of a command is the breadth of its impact:
Member
Many commands used in a data sharing environment have member scope
because they affect only the DB2 for which they are issued. For example, a

Chapter 2. Commands 5
DISPLAY THREAD command displays only those threads that exist for the
member identified by the command prefix.
Group Other commands have group scope because they affect an object in such a
way that affects all members of the group. For example, a STOP
DATABASE command issued from any member of the group stops that
database for all members of the group.

The commands that have group scope are:

ALTER GROUPBUFFERPOOL (DB2) FREE PACKAGE (DSN)


BIND PACKAGE (DSN) FREE PLAN (DSN)
BIND PLAN (DSN) MODIFY irlmproc,DIAG,DELAY (MVS IRLM)
DCLGEN (DSN) REBIND PACKAGE (DSN)
DISPLAY DATABASE (DB2) REBIND PLAN (DSN)
DISPLAY GROUP (DB2) REBIND TRIGGER PACKAGE (DSN)
DISPLAY GROUPBUFFERPOOL (DB2) START DATABASE (DB2)
DISPLAY UTILITY (DB2) STOP DATABASE (DB2)

These commands have either group or member scope, depending on what option
you specify with them:
ARCHIVE LOG (DB2)

MODIFY irlmproc,STATUS (MVS IRLM)

TERM UTILITY (DB2)

All other commands have member scope. The description of each command
includes its scope. For more details on data sharing, see DB2 Data Sharing:
Planning and Administration.

Output from DB2 commands


The amount of output that you receive from a DB2 command is always less than
256 KB. The following factors determine the maximum amount of output you can
receive:
v The amount of storage available to your DB2 subsystem or to an individual
command.
v The environment from which you issue the DB2 command.
For example, if you issue a DB2 command from an IMS console, you can receive
no more than 32 KB of output.
v For DISPLAY DATABASE, the value of the LIMIT parameter.
v For DISPLAY THREAD, the number of lines of output.
DISPLAY THREAD does not display more than 254 lines of output.

Issuing commands from IFI


Consider using IFI to let your programs issue commands to DB2. This method
returns information about the success or failure of the command to your program. If
the command issues a non-zero return code, the information returned to your
program includes diagnostic information about the command processed.

6 Command Reference
For more information about submitting DB2 commands through IFI, see Appendix E
(Volume 2) of DB2 Administration Guide.

DSN subcommand parsing


The parsing of DSN subcommands conforms to standard TSO command parsing
conventions. For information about TSO command parsing, see OS/390 TSO/E
Programming Services.

To continue a subcommand on the next line while using the DSN processor, type
either a hyphen (-) or a plus sign (+) at the end of the current line. If you use a plus
sign, precede it by at least one blank character to prevent the concatenation of
character strings from line to line. Using a plus sign causes TSO/E to delete leading
delimiters (blanks, commas, tabs, and comments) on the continuation line, and will
reduce the overall size of the command.

Abbreviations
The names of the DSN command and its subcommands cannot be abbreviated. For
compatibility with prior releases of DB2, abbreviations for some keywords are
allowed. Recommendation: To avoid potential problems, avoid abbreviating
keywords.

Description of commands
The commands are divided into these categories:
v The DSN command and its subcommands
v DB2 commands
v IMS commands
v CICS attachment facility commands
v MVS IRLM commands
v TSO CLISTs

The DSN command and its subcommands


Environment: DSN is the DB2 command processor and executes as a TSO
command processor. All of its subcommands, except SPUFI, run under DSN in
either the foreground or background, and all, except END, also run under DB2
Interactive (DB2I). SPUFI runs only in the foreground under ISPF.
Table 1. DSN command and subcommands
DSN command
or Refer
Subcommand Function to page
BIND Builds an application package or plan 32, 38
DB2 Execute a DB2 command Table 2 on page 8
commands
DCLGEN (DECLARATIONS GENERATOR) Produces 84
declarations for tables or views
DSN Starts a DSN session 175
END Ends the DSN session 217
FREE Deletes an application package or plan 218, 221
REBIND Updates an application package or plan 240, 244

Chapter 2. Commands 7
Table 1. DSN command and subcommands (continued)
DSN command
or Refer
Subcommand Function to page
REBIND Updates an application trigger package 248
TRIGGER
PACKAGE
RUN Executes an application program 262
SPUFI Executes the SQL Processor Using File Input 273
* A comment 175

DB2 commands
Environment: The command START DB2 can be issued only from an MVS
console. All other DB2 commands can be issued from:
v An MVS console or MVS application program
v A DSN session
v A DB2I panel
v An IMS terminal
v A CICS terminal
v An application program, using the DB2 instrumentation facility interface (IFI)

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Extended MCS Consoles: The extended MCS console feature of MVS lets an
MVS system have more than 99 consoles. Because DB2 supports extended MCS
consoles, messages returned from a DB2 command are routed to the extended
MCS console that issued the command. For more information on extended MCS
consoles, see Part 4 (Volume 1) of DB2 Administration Guide, and OS/390 MVS
Planning: Operations.
Table 2. DB2 commands
Refer
DB2 command Function to page
-ALTER BUFFERPOOL Alters attributes for the buffer pools 12
-ALTER Alters attributes for the group buffer pools 19
GROUPBUFFERPOOL
-ALTER UTILITY Alters parameter values of the REORG utility 23
-ARCHIVE LOG Enables a site to close a current active log and 26
open the next available log data set
-CANCEL THREAD Cancels processing for specific local or distributed 77
threads
-DISPLAY ARCHIVE Displays information about archive log processing 95
-DISPLAY BUFFERPOOL Displays information about the buffer pools 97
-DISPLAY DATABASE Displays status information about DB2 databases 106
-DISPLAY FUNCTION Displays statistics about external user-defined 121
SPECIFIC functions
-DISPLAY GROUP Displays information about the data sharing group 125
to which a DB2 subsystem belongs

8 Command Reference
Table 2. DB2 commands (continued)
Refer
DB2 command Function to page
-DISPLAY Displays status information about DB2 group buffer 129
GROUPBUFFERPOOL pools
-DISPLAY LOCATION Displays status information about distributed 143
threads
-DISPLAY LOG Displays log information and status of the offload 146
task
-DISPLAY Displays status information about stored 148
PROCEDURE procedures
-DISPLAY RLIMIT Displays status information about the resource limit 152
facility (governor)
-DISPLAY THREAD Displays information about DB2 threads 153
-DISPLAY TRACE Displays information about DB2 traces 165
-DISPLAY UTILITY Displays status information about a DB2 utility 171
-MODIFY TRACE Changes the IFCIDs (trace events) associated with 238
a particular active trace
-RECOVER BSDS Reestablishes dual bootstrap data sets 251
-RECOVER INDOUBT Recovers threads left indoubt 252
-RECOVER Completes back-out processing for units of 255
POSTPONED recovery left incomplete during an earlier restart
-RESET GENERICLU Purges information stored by VTAM in the coupling 257
facility
-RESET INDOUBT Purges information displayed in the indoubt thread 259
report generated by the -DISPLAY THREAD
command
-SET ARCHIVE Controls the allocation of tape units and the 265
deallocation time of the tape units for archive log
processing
-SET LOG Modifies the checkpoint frequency 270
| -SET SYSPARM Changes subsystem parameters online 268
-START DATABASE Makes the specified database available for use 276
-START DB2 Initializes the DB2 subsystem (can be issued only 283
from an MVS console)
-START DDF Starts the distributed data facility 286
-START FUNCTION Activates an external function that is stopped 287
SPECIFIC
-START PROCEDURE Activates the definition of stopped or cached stored 294
procedures
-START RLIMIT Starts the resource limit facility (governor) 297
-START TRACE Initiates DB2 trace activity 299
-STOP DATABASE Makes specified databases unavailable for 310
applications
-STOP DB2 Stops the DB2 subsystem 316
-STOP DDF Stops the distributed data facility 318

Chapter 2. Commands 9
Table 2. DB2 commands (continued)
Refer
DB2 command Function to page
-STOP FUNCTION Stops the acceptance of SQL statements for 321
SPECIFIC specified functions
-STOP PROCEDURE Stops the acceptance of SQL CALL statements for 326
stored procedures
-STOP RLIMIT Stops the resource limit facility (governor) 329
-STOP TRACE Stops trace activity 330
-TERM UTILITY Terminates execution of a utility 335

Completion Messages: Message DSN9022I indicates the normal end of DB2


command processing; DSN9023I indicates the abnormal end of DB2 command
processing.

IMS commands
Environment: Each IMS command can be issued from an IMS terminal.
Table 3. IMS commands
Refer
IMS command Function to page
/CHANGE Resets an indoubt recovery unit 82
/DISPLAY Displays the status of the connection between IMS 92
and the specified subsystem (DB2), or displays the
outstanding recovery units associated with the
specified subsystem (DB2)
/SSR Allows the IMS operator to enter an external 274
subsystem (DB2) command
/START Makes available the connection between IMS and 275
the specified external subsystem (DB2)
/STOP Prevents application programs from accessing the 309
external subsystem’s (DB2’s) resources
/TRACE Allows users to direct and control IMS tracing 338
activities

CICS attachment facility commands


Environment: Each CICS attachment facility command can be issued from a CICS
terminal.
Table 4. CICS attachment facility commands
CICS
attachment Refer
facility commands Function to page
DSNC Allows you to enter DB2 commands from CICS 178
DSNC DISCONNECT Disconnects threads 179
DSNC DISPLAY Displays information on CICS transactions 180

10 Command Reference
Table 4. CICS attachment facility commands (continued)
CICS
attachment Refer
facility commands Function to page
DSNC MODIFY Modifies the ERRDEST entry in the resource 184
control table (RCT), or modifies the maximum
active thread value associated with a given
transaction or group name
DSNC STOP Stops the CICS attachment facility 186
DSNC STRT Starts the CICS attachment facility 187

MVS IRLM commands


Environment: Each MVS IRLM command can be issued from an MVS console.
Table 5. MVS commands affecting the IRLM
Refer
MVS command Function to page
MODIFY irlmproc, Abends IRLM 223
ABEND
MODIFY irlmproc, Initiates diagnostic dumps for IRLM subsystems 225
DIAG,DELAY
| MODIFY irlmproc, Releases IRLM locks 227
| PURGE
MODIFY irlmproc, Dynamically sets the maximum CSA or the number 228
SET of trace buffers allowed for IRLM
MODIFY irlmproc, Displays IRLM status 232
STATUS
START irlmproc Starts an IRLM component with an 290
installation-supplied procedure
STOP irlmproc Shuts down IRLM normally 324
TRACE CT Starts, stops, or modifies IRLM tracing 340

TSO CLISTs
Table 6. TSO CLISTs
Refer
CLIST Function to page
DSNH Prepares a program for execution, and executes it 189
if it runs under TSO. Runs under TSO in
foreground or background.
DSNU Generates JCL to execute DB2 utility jobs. Can be
executed directly or by using DB2I. For details on
this command procedure, see DB2 Utility Guide
and Reference.

Chapter 2. Commands 11
-ALTER BUFFERPOOL (DB2)

-ALTER BUFFERPOOL (DB2)


The DB2 command ALTER BUFFERPOOL alters attributes for active or inactive
buffer pools. Altered values are remembered until altered again.

Abbreviation: -ALT BPOOL

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS® terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v SYSOPR authority
v SYSCTRL authority
v SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

 ALTER BUFFERPOOL ( bpname ) 


VPSIZE(integer) VPTYPE ( PRIMARY )
DATASPACE

 
HPSIZE(integer) VPSEQT(integer) VPPSEQT(integer) VPXPSEQT(integer)

 
HPSEQT(integer) DWQT(integer) VDWQT(integer1,integer2) CASTOUT( YES )
NO

 
PGSTEAL ( LRU )
FIFO

Option descriptions
(bpname)
Names the buffer pool to alter.
v 4-KB page buffer pools are named BP0, BP1, ..., BP49.
v 8-KB page buffer pools are named BP8K0, BP8K1, ..., BP8K9.
v 16-KB page buffer pools are named BP16K0, BP16K1, ..., BP16K9.
v 32-KB page buffer pools are named BP32K, BP32K1, ..., BP32K9.
VPSIZE (integer)
Changes the virtual buffer pool size.

12 Command Reference
-ALTER BUFFERPOOL (DB2)
integer specifies the number of buffers to allocate to the active virtual buffer
pool.
integer can range from 0 to 400000 for 4-KB page buffer pools other than BP0.
For BP0, the minimum value is 56. For 8-KB page buffer pools, the range is
from 0 to 200000. For 16-KB page buffer pools, the range is from 0 to 100000.
For 32-KB page buffer pools, the range is from 0 to 50000.
DB2 limits the total VPSIZE for all buffer pools to 1.6 GB. However, the amount
of available real and virtual storage can further limit the amount of buffer pool
storage DB2 can acquire.
If you specify VPSIZE as 0 for an active buffer pool (other than BP0), DB2
quiesces all current database access and update activities for that buffer pool
and then deletes the buffer pool. Subsequent attempts to use table spaces or
indexes that are assigned to that buffer pool fail.
VPTYPE
Specifies the type of virtual buffer pool to be allocated. Changes to the VPTYPE
value apply after DB2 reallocates the buffer pools.
If the specified virtual pool is currently allocated, VPTYPE and VPSIZE are
mutually exclusive. In order to change both the type and size specifications,
follow the procedure in 16.
When DB2 is installed, the default is VPTYPE (PRIMARY). However, when you
issue the ALTER BUFFERPOOL command, you must explicitly specify either
PRIMARY or DATASPACE when the VPTYPE option is used.
# (PRIMARY)
The virtual buffer pool is to be allocated in the DB2 database services
address space.
# (DATASPACE)
The virtual buffer pool is to be allocated in one or more DB2-associated
data spaces.
HPSIZE (integer)
Changes the hiperpool size. If the buffer pool is active at the time the command
is issued, the hiperpool is created, expanded, contracted, or deleted depending
on the new HPSIZE value.
integer specifies the number of buffers for a hiperpool. For 4-KB-page
hiperpools, the acceptable values range from 0 to 2097152. For 8-KB-page
hiperpools, the range is from 0 to 1048576. For 16-KB-page hiperpools, the
range is from 0 to 524288. For 32-KB-page hiperpools, the range is from 0 to
262144.
DB2 limits the total HPSIZE for all buffer pools to 8 GB. However, the amount
of available expanded or real storage can further limit the amount of buffer pool
storage DB2 can acquire. A value of 0 can be specified for all buffer pools.
VPSEQT (integer)
Changes the sequential steal threshold for the virtual buffer pool.
integer specifies the sequential steal threshold for the virtual buffer pool. It is
expressed as a percentage of the total virtual buffer pool size, and valid values
range from 0 to 100. This threshold affects the allocation of buffers in the virtual
buffer pool to page read requests that are part of a sequential access pattern.
This includes pages being prefetched. If the number of buffers containing
sequentially accessed pages exceeds the threshold, a sequential request

Chapter 2. Commands 13
-ALTER BUFFERPOOL (DB2)
attempts to reuse one of those buffers rather than a buffer containing a
non-sequentially accessed page. The initial default value is 80.
When VPSEQT=0, sequentially accessed pages are not kept in the virtual
buffer pool after being released by the accessing agent. Also, prefetch is
disabled.
When VPSEQT=100, DB2 does not prefer reusing sequential buffers over using
non-sequential buffers.
VPPSEQT (integer)
Changes the parallel sequential threshold for the virtual buffer pool. This
threshold determines how much of the virtual buffer pool is used for parallel
processing operations.
integer specifies the parallel sequential threshold for the virtual buffer pool. It is
expressed as a percentage of the sequential steal threshold, and valid values
range from 0 to 100. The initial default value is 50.
When VPPSEQT=0, parallel processing operations are disabled.
VPXPSEQT (integer)
Changes the assisting parallel sequential threshold for the virtual buffer pool.
This threshold determines the portion of the virtual buffer pool that is used for
processing queries that originate on other members of the data sharing group. It
is valid and effective only when DB2 is on a data sharing mode; it is ignored
when DB2 is not on a data sharing mode.
integer specifies the assisting parallel sequential threshold for the virtual buffer
pool. It is expressed as a percentage of the parallel sequential threshold
(VPPSEQT). Whenever the sequential steal threshold or the parallel sequential
threshold is altered, it directly affects the portion of buffer resources dedicated
to “assistant” parallel operations. The valid values range from 0 to 100. The
initial default value is 0.
When VPXPSEQT=0, this bufferpool cannot be used to assist another DB2 with
parallel processing.
HPSEQT (integer)
Changes the hiperpool sequential steal threshold.
integer specifies the sequential steal threshold for the hiperpool. It is expressed
as a percentage of the total hiperpool size, and valid values range from 0 to
100. This threshold affects the allocation of hiperpool buffers when casting out
sequentially accessed pages from the virtual pool. If the number of buffers in
the hiperpool containing sequentially accessed pages exceeds the threshold,
the buffer allocation for a sequentially accessed page attempts to reuse one of
these buffers rather than a buffer containing a non-sequentially accessed page.
The initial default is 80.
When HPSEQT=0, sequentially accessed pages are not cast out to the
hiperpool.
When HPSEQT=100, DB2 does not prefer reusing sequential buffers over using
non-sequential buffers.
DWQT (integer)
Changes the buffer pool’s deferred write threshold.
integer specifies the deferred write threshold for the virtual buffer pool. It is
expressed as a percentage of the total virtual buffer pool size, and valid values
range from 0 to 90. This threshold determines when deferred writes begin,

14 Command Reference
-ALTER BUFFERPOOL (DB2)
based on the number of unavailable (non-stealable) buffers. When the count of
non-stealable buffers exceeds the threshold, deferred writes begin. The initial
default value is 50.
VDWQT (integer1,integer2)
integer1 specifies the vertical deferred write threshold for the virtual buffer pool.
It is expressed as a percentage of the total virtual buffer pool size, and valid
values range from 0 to 90.
This threshold determines when deferred writes begin, based on the number of
updated pages for a given data set. Deferred writes begin for that data set
when the count of updated buffers for a data set exceeds the threshold. This
threshold can be overridden for page sets accessed by DB2 utilities and must
be less than or equal to the value specified for the DWQT option.
The default value is 10. A value of 0 indicates that the deferred write of 32
pages begins when the updated buffer count for the data set reaches 40.
integer2 specifies the vertical deferred write threshold for the virtual buffer pool.
It is expressed as an absolute number of buffers. You can use integer2 when
you want a relatively low threshold value for a large virtual pool, but integer1
cannot provide a fine enough granularity between integer1 values of 0 and 1.
integer2 only applies when integer1 is 0; DB2 ignores a value specified for
integer2 if the value specified for integer1 is non-zero. integer2 can range from
0 to 9999. The default value is 0.
If integer1 is 0 and integer2 is a non-zero value, DB2 uses the value specified
for integer2 to determine the threshold. If both values are 0, then the integer1
value of 0 is used as the threshold.
CASTOUT
Changes the CASTOUT attribute of the hiperspaces used to back the hiperpool.
When DB2 is installed, the default is CASTOUT (YES) for all hiperpools.
However, when you issue the ALTER BUFFERPOOL command, you must
explicitly specify either YES or NO when the CASTOUT option is used.
(YES)
Allows MVS to discard data cached in the hiperpool when a shortage of
expanded storage arises. When data is discarded, hiperspace backing
expanded storage pages is released.
(NO)
Directs MVS to assign a high priority to keeping the data cached in the
hiperpool. Because this could severely limit the availability of expanded
storage to other processes on the system, specify CASTOUT(NO) only for
buffer pools associated with databases for which response time is critical.
PGSTEAL
Specifies the page stealing algorithm DB2 uses for the virtual buffer pool.
When DB2 is installed, the default is PGSTEAL (LRU). However, when you
issue the ALTER BUFFERPOOL command, you must explicitly specify either
LRU or FIFO when the PGSTEAL option is used.
# (LRU)
Specifies the virtual buffer pool buffers should be managed using the least
recently used (LRU) algorithm.
# (FIFO)
Specifies the virtual buffer pool buffers should be managed using the first in
first out (FIFO) algorithm.

Chapter 2. Commands 15
-ALTER BUFFERPOOL (DB2)
Usage notes
The following sections contain additional information about how to use the ALTER
BUFFERPOOL command.

Changing several buffer pool attributes: A failure in modifying one buffer pool
attribute has no effect on other modifications requested in the same command.

Insufficient virtual storage: If insufficient virtual storage is detected while


expanding a virtual buffer pool or while creating or expanding a hiperpool, DB2
issues an error message, and the process terminates, leaving the virtual buffer pool
or hiperpool with a smaller size than was requested. Similarly, DB2 issues an error
message if it is unable to create a hiperspace.

Contracting an active virtual buffer pool: If you use ALTER BUFFERPOOL to


contract the size of an active virtual buffer pool, DB2 contracts the pool by marking
active buffers as ″to be deleted,″ which means they are not reusable to satisfy other
page requests. However, the virtual storage might not be freed immediately. A
system administrator can determine the status of the buffer pool by issuing the
DISPLAY BUFFERPOOL command.

Deleting an active buffer pool: If you use ALTER BUFFERPOOL to delete an


active buffer pool (by specifying 0 for VPSIZE), DB2 issues a message to indicate
that it is ready to explicitly delete this buffer pool. Once DB2 accepts the delete
buffer pool request, the buffer pool is marked as ″delete pending″. All current
access to the buffer pool is quiesced, later access attempts fail with an error
message, and all open page sets that refer to the buffer pool are closed.

Altering hiperpool attributes: If you use ALTER BUFFERPOOL to alter the


CASTOUT attribute of an already active hiperpool, DB2 marks the hiperpool as
temporarily unavailable, so transactions are executed using the buffer pool without
its backing hiperpool. The hiperspaces backing the hiperpool are deleted and
re-created with the new CASTOUT attribute. All pages that were cached in the
hiperpool are purged before the hiperpool is activated again.

When DB2 is restarted, if a hiperpool could not be created, DB2 issues a warning
message indicating the reason. Under this condition, DB2 comes up with only the
virtual bufferpool created. Use ALTER BUFFERPOOL to set the HPSIZE value to 0
to avoid any further messages.

Altering attributes stored in the BSDS: The virtual bufferpool and hiperpool
attributes that are stored in the BSDS cannot be changed off line.

Altering the VPTYPE for a virtual buffer pool: If the virtual pool is currently
allocated and you change the VPTYPE attribute, the VPTYPE specification
becomes effective only at the next allocation of the virtual buffer pool. To alter the
VPTYPE attribute for a buffer pool and have it take effect, use the following
procedure:
1. Issue the ALTER BUFFERPOOL command, specifying a new value for
VPTYPE. If the virtual pool is currently allocated, the new specification takes
effect the next time the buffer pool is allocated. If the buffer pool is currently
allocated, proceed to step 2.
2. If the target buffer pool is not BP0:
a. Issue the following command to deallocate the buffer pool:
-ALTER BUFFERPOOL(bpname) VPSIZE(0)

16 Command Reference
-ALTER BUFFERPOOL (DB2)
b. Issue the following command to redefine the buffer pool with the new type
and new size:
-ALTER BUFFERPOOL(bpname) VPSIZE(newsize) VPTYPE(newtype)
3. If the target buffer pool is BP0:
a. Issue the following command to specify the new type:
-ALTER BUFFERPOOL(0) VPTYPE(newtype)
b. Deallocate BP0 by either issuing the STOP DATABASE command to stop all
table spaces and indexes that are using BP0, or stop DB2.
c. Depending on the action taken in step 3b, issue START DATABASE
commands to start the stopped table spaces and indexes, or restart DB2.
d. Optionally, issue the following command to specify the new size.
-ALTER BUFFERPOOL(BP0) VPSIZE(newsize)

If you skip this step, the previous size is used.

| Converting an active buffer pool to use a data space:When you convert buffer
| pool 0 (BP0) to use a data space, use either one of the following procedures.

| Procedure 1
| 1. Issue ALTER BUFFERPOOL(0) VPTYPE(DATASPACE)
| 2. Issue STOP DB2
| 3. Issue START DB2

| Procedure 2 (requires SYSADM authority)


| 1. Issue ALTER BUFFERPOOL(0) VPTYPE(DATASPACE)
| 2. Stop all databases that are using BP0 (or stop all databases)
| 3. Stop DDF
| 4. Stop the Resource Access Limit Facility
| 5. Stop all work databases that are using BP0
| 6. Stop DSNDB06
| 7. Stop DSNDB01
| 8. Start all datasets starting with step 7 back to step 2

| When you convert buffer pools other than BP0, use the following procedure.
| 1. Issue ALTER BUFFERPOOL(x) VPSIZE(0)
| 2. Let all datasets in the buffer pool stop
| 3. Issue ALTER BUFFERPOOL(x) VPTYPE(DATASPACE) VPSIZE(newsize)

Relating VPPSEQT and VPXSEQT: The Table 7 on page 18 explains how the two
parallel sequential thresholds, VPPSEQT for parallel sequential and VPXPSEQT for
assisting parallel sequential threshold, are related. VPXPSEQT is a percentage of
VPPSEQT, which is itself a portion of VPSEQT. Multiply VPXPSEQT by VPPSEQT
to obtain the total amount of the virtual buffer pool that can be used to assist
another DB2 with parallel processing. In addition, VPPSEQT is affected by changing
VPSIZE and VPSEQT; therefore, VPXPSEQT is also affected by VPSIZE and
VPSEQT. For more information on the relationships of the various thresholds and
possible configurations, see Chapter 6 of DB2 Data Sharing: Planning and
Administration.

Chapter 2. Commands 17
-ALTER BUFFERPOOL (DB2)
Table 7. Relationship between VPPSEQT and VPXPSEQT
the percentage of the
virtual buffer pool available
to assist Sysplex query
If VPPSEQT is ... and VPXPSEQT is ... parallelism is...
50 50 25
50 100 50
100 50 50
anything 0 0
0 anything 0

Examples
Example 1: Set the virtual buffer pool and hiperpool for BP0 to 1000 and 10000
buffers, respectively.
-ALTER BUFFERPOOL(BP0) VPSIZE(1000) HPSIZE(10000)

Example 2: Set the sequential steal threshold of the virtual buffer pool for BP0 to
75 percent of the virtual pool size, while disabling caching of sequentially accessed
pages in the hiperpool.
-ALTER BUFFERPOOL(BP0) VPSEQT(75) HPSEQT(0)

Example 3: Set the hiperpool size for BP4 to 10000 buffers and explicitly specify
that cached data in the hiperpool for BP4 can be discarded.
-ALTER BUFFERPOOL(BP4) HPSIZE(10000) CASTOUT(YES)

Example 4: Delete BP1. Be very careful when using this option because when you
specify a 0 size for an active buffer pool, DB2 quiesces all current database access
and fails all subsequent page set open requests.
-ALTER BUFFERPOOL(BP1) VPSIZE(0)

18 Command Reference
-ALTER GROUPBUFFERPOOL (DB2)

-ALTER GROUPBUFFERPOOL (DB2)


The DB2 command ALTER GROUPBUFFERPOOL alters attributes of group buffer
pools.

Abbreviation: -ALT GBPOOL

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Group

Authorization
To execute this command, the privilege set of the process must include one of the
following authorities:
v SYSOPR authority
v SYSCTRL authority
v SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

 ALTER GROUPBUFFERPOOL ( gbpname ) 


structure-name GBPCACHE( YES )
NO

 
AUTOREC( YES ) RATIO(ratio) CLASST(integer) GBPOOLT(integer)
NO

 
GBPCHKPT(integer)

Option descriptions
(gbpname)
Names the DB2 group buffer pool.
v 4-KB group buffer pools are named GBP0, GBP1, ... , GBP49.
v 8-KB group buffer pools are named GBP8K0, GBP8K1, ... , GBP8K9.
v 16-KB group buffer pools are named GBP16K0, GBP16K1, ... , GBP16K9.
v 32-KB group buffer pools are named GBP32K, GBP32K1, ... , GBP32K9.
(structure-name)
Names the backing coupling facility structure for the group buffer pool. The
coupling facility structure name has the following format:
groupname_gbpname

Chapter 2. Commands 19
-ALTER GROUPBUFFERPOOL (DB2)
where groupname is the DB2 data sharing group name and the underscore (_)
separates groupname and gbpname.
GBPCACHE
Specifies whether gbpname is to be used for both caching data and
cross-invalidation, or just for cross-invalidation.
(YES)
gbpname is used for caching data and cross-invalidation.
Any “no data caching” attribute that is specified at either the page set or
group buffer pool level takes precedence over a caching specification. For
more information, see Table 8.
Table 8. Precedence of a no-data-caching specification
Group buffer pool Attribute that takes
specification Page set specification precedence
GBPCACHE(NO) GBPCACHE CHANGED GBPCACHE(NO)
GBPCACHE ALL
GBPCACHE(YES) GBPCACHE NONE GBPCACHE NONE

(NO)
Indicates that gbpname is used only for cross-invalidation. This group buffer
pool contains no data entries. The GBPCACHE option of table spaces or
index spaces that use this group buffer pool is ignored.
AUTOREC
Specifies whether automatic recovery by DB2 takes place when a structure
failure occurs or when the connectivity of all members of the group to the group
buffer pool is lost.
(YES)
Indicates that DB2 is to automatically recover page sets and partitions that
have a status of group buffer pool RECOVER pending (GRECP) and that
have pages on the logical page list.
(NO)
Disables automatic recovery. Enter a START DATABASE command to
recover page sets and partitions that have a status of GRECP or that have
pages on the logical page list.
RATIO (ratio)
Changes the desired ratio in the group buffer pool of the number of directory
entries to the number of data pages; that is, how many directory entries there
are for each data page.
ratio can be a decimal number from 1.0 to 255, inclusive. Any digits after the
first decimal place are ignored; for example, 5.67 is treated as 5.6. In numbers
greater than 25, any digits after the decimal point are ignored; for example,
25.98 is treated as 25. The default is 5.
The actual number of directory entries and data pages that are allocated
depends on the size of the coupling facility structure, which is specified in the
coupling facility policy definitions.
CLASST (integer)
Changes the threshold at which class castout is started. It is expressed as a
percentage of the size of the number of data entries; integer can range from 0
to 90. The default is 10.

20 Command Reference
-ALTER GROUPBUFFERPOOL (DB2)
As an example, CLASST(5) starts class castout when the number of pages in
that class equals 5% of the group buffer pool page capacity.
GBPOOLT (integer)
Changes the threshold at which data in the group buffer pool is cast out to disk.
It is expressed as a percentage of the number of data entries; integer can
range from 0 to 90. The default is 50.
As an example, GBPOOLT(55) casts out data if the number of pages in the
group buffer pool equals 55% of the group buffer pool page capacity.
GBPCHKPT (integer)
Changes the time interval, in minutes, between successive checkpoints of the
group buffer pool. integer can range from 1 to 999999. Unless a value is
explicitly specified for the GBPCHKPT option, the default value is 8 minutes.
The more frequently checkpoints are taken, the less time it takes to recover the
group buffer pool if the coupling facility fails.

Usage notes
Defaults: Issuing the command does not change any option that is not explicitly
specified; the default is to leave the value unchanged. When the command is first
issued for a group buffer pool or a structure, the option defaults are as follows:

Option Value
GBPCACHE YES
RATIO 5
CLASST 10 (%)
GBPOOLT 50 (%)
GBPCHKPT 8 (minutes)

When new values take effect: When you issue the ALTER GROUPBUFFERPOOL
command, some option specifications become effective only at the next allocation of
the group buffer pool. Refer to Table 9 for more information.
Table 9. Changing group buffer pool attributes
Applicable if
Keyword New value takes effect GBPCACHE(NO)?
1
GBPCACHE at next allocation N/A
AUTOREC immediately No
2 3
RATIO at next allocation No
3
CLASST immediately No
3
GBPOOLT immediately No
3
GBPCHKPT immediately No

Chapter 2. Commands 21
-ALTER GROUPBUFFERPOOL (DB2)

Notes:
1. You can use the MVS command SETXCF START,REBUILD to have the change take
effect if the group buffer pool is not duplexed. If the group buffer pool is duplexed and
you want to change to GBPCACHE(NO), first go back to simplex mode and rebuild.
GBPCACHE(NO) is not allowed for duplexed group buffer pools.
2. You can use the MVS command SETXCF START,REBUILD to have the change take
effect if the group buffer pool is not duplexed. If the group buffer pool is duplexed, first go
back to simplex mode and rebuild; then optionally go back to duplex mode. If a group
buffer pool is duplexed, both instances of that duplexed group buffer pool use the same
RATIO value.
3. DB2 issues message DSNB761 when you specify this option for a GBPCACHE(NO)
group buffer pool. These settings only take effect after the GBPCACHE attribute has
been changed to YES.

Examples
Example 1: For group buffer pool 0, change the ratio of directory entries to data
pages to 1 directory entry for every data page. The RATIO specification becomes
effective at the next allocation of the group buffer pool.
-DB1G ALTER GROUPBUFFERPOOL (GBP0) RATIO(1)

Example 2: For group buffer pool 2, change the class castout threshold to 5% and
the group buffer pool castout threshold to 30%. The new values take effect
immediately.
-DB1G ALTER GROUPBUFFERPOOL (GBP2) CLASST(5) GBPOOLT(30)

Example 3: Assume that the DB2 group name is DSNCAT. For group buffer pool 3,
change the class castout threshold to 5%. The new value takes effect immediately.
Because the group name is DSNCAT, the coupling facility structure name is
DSNCAT_GBP3. Also, in the event of a structure failure, the AUTOREC(YES)
option enables DB2 to automatically recover the page sets and partitions that are in
a GRECP status or that have pages on the logical page list.
-DB1G ALTER GROUPBUFFERPOOL (DSNCAT_GBP3) CLASST(5) AUTOREC(YES)

Example 4: For group buffer pool 32K, change the GBP checkpoint frequency to 5
minutes. The new value takes effect immediately. Here, with AUTOREC(NO)
specified, you are in effect taking control of the recovery process rather than DB2 in
the event of a structure failure. You might choose to do this to determine what
pagesets or partitions are in a GRECP status or that have pages on the logical
page list and before entering the START DATABASE command to enable DB2 to
recover the data with the options you specify.
-DB1G ALTER GROUPBUFFERPOOL (GBP32K) GBPCHKPT(5) AUTOREC(NO)

22 Command Reference
-ALTER UTILITY (DB2)

-ALTER UTILITY (DB2)


The DB2 command ALTER UTILITY changes the values of certain parameters of an
execution of the REORG utility that uses SHRLEVEL REFERENCE or CHANGE.
Specifically, this command changes the values of DEADLINE, MAXRO, LONGLOG,
and DELAY. For more information about those parameters and the REORG utility,
see DB2 Utility Guide and Reference.

REORG can be altered only from the DB2 on which it is running.

Abbreviation: -ALT UTIL

Environment
This command can be issued from an MVS console, a DSN session, a DB2I panel
(DB2 COMMANDS), an IMS or a CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the primary or some secondary authorization ID of the
process must be the ID that originally submitted the utility job, or the privilege set of
the process must include one of the following authorities:
v DBMAINT, DBCTRL, or DBADM authority
v SYSOPR, SYSCTRL, or SYSADM authority
DB2 commands that are issued from an MVS console are not associated with any
secondary authorization IDs.

For users with DBMAINT, DBCTRL, or DBADM authority, the command takes effect
only when a user has sufficient authority over each object that the utility job
accesses.

Syntax

 ALTER UTILITY ( utility-id ) REORG 


DEADLINE( NONE )
timestamp

 
MAXRO( integer ) LONGLOG( CONTINUE ) DELAY( integer )
DEFER TERM
DRAIN

Option descriptions
(utility-id)
Is the utility identifier, or the UID parameter, used when creating the utility job
step.
This job must execute REORG with SHRLEVEL CHANGE or SHRLEVEL
REFERENCE.

Chapter 2. Commands 23
-ALTER UTILITY (DB2)
If utility-id was created by the DSNU CLIST by default, it has the form
tso-userid.control-file-name. For the control file name that is associated with
each utility, see DB2 Utility Guide and Reference.
If utility-id was created by default by the EXEC statement that executed
DSNUTLIB, then this token has the form userid.jobname.
DEADLINE
Specifies the deadline by which the user wants the switch phase of
reorganization to start. If DB2 estimates that the switch phase will not start by
the deadline, DB2 terminates reorganization. The default is the most recently
specified value of DEADLINE.
The pre-switch processing might continue until after the deadline.
(NONE)
Specifies that there is no deadline for the read-only iteration of log
processing.
(timestamp)
Specifies the deadline by which the user wants the switch phase to start
processing. This deadline must not have been reached when ALTER
UTILITY executes. For more information on the format for specifying a
timestamp, see the discussion of data types in DB2 SQL Reference.
MAXRO
Specifies the maximum amount of time that is tolerated for the last iteration of
log processing during reorganization. During that iteration, applications have
read-only access.
The actual execution time of the last iteration can exceed the value specified for
MAXRO.
(integer)
Is the number of seconds. The default is the most recently specified value
of MAXRO.
(DEFER)
Specifies that the log phase is deferred indefinitely.
LONGLOG
Specifies the action that DB2 performs (after sending the LONGLOG message
to the console) if the number of log records that are processed during the next
iteration is not sufficiently lower than the number of log records that were
processed during the previous iterations. The default is the most recently
specified value of LONGLOG.
(CONTINUE)
Specifies that DB2 continues performing reorganization.
(TERM)
Specifies that DB2 terminates reorganization after the delay.
(DRAIN)
Specifies that DB2 drains the write claim class after the delay. The number
of log records, and thus the estimated time, for a future iteration of log
processing will be 0.
DELAY integer
Specifies a lower bound for the interval between the time when REORG sends
the LONGLOG message to the console and the time when REORG performs
the action specified by the LONGLOG parameter.

24 Command Reference
-ALTER UTILITY (DB2)
integer is the number of seconds. The value must be nonnegative. The default
is the most recently specified value of DELAY.

Usage note
REORG can be altered only from the DB2 subsystem on which it is running.

Example
The following example alters the execution of the REORG utility for the utility job
step whose utility identifier is REORGEMP:
-ALTER UTILITY (REORGEMP) REORG MAXRO(240) LONGLOG DRAIN

In this example:
v MAXRO(240) changes the maximum tolerable time for the last iteration of log
processing to 240 seconds (4 minutes).
v LONGLOG DRAIN changes the action that DB2 performs (if reorganization’s
reading of the log is not catching up to applications’ writing of the log quickly
enough) to draining of the write claim class.
v DELAY was not specified and therefore, the example does not change the
existing delay between sending of the LONGLOG message to the console and
performing the action specified by LONGLOG.
v DEADLINE was not specified and the example does not change the existing
deadline (if any) of the last iteration of log processing.

Chapter 2. Commands 25
-ARCHIVE LOG (DB2)

-ARCHIVE LOG (DB2)


When issued without any options, the DB2 command ARCHIVE LOG performs the
following functions:
v Truncates the current active log data sets
v Starts an asynchronous task to offload the data sets
v Archives previous active log data sets not yet archived
v Returns control to the user (immediately)
In a data sharing environment, you can truncate and archive the logs for an
individual member or for all members in the group.

When specified with the option MODE(QUIESCE), the ARCHIVE LOG command
attempts to quiesce (suspend) all DB2 user update activity on the DB2 active log
prior to the offload process. Once a system-wide point of consistency is reached
(that is, when all currently active update users have reached a commit point), the
active log is immediately truncated, and the offload process is initiated. The
resulting point of consistency is captured in the current active log before it is
offloaded. In a data sharing environment, you can create a system-wide point of
consistency only for the entire group.

For further information regarding the ARCHIVE LOG command, see Part 4 (Volume
1) of DB2 Administration Guide.

Abbreviation: -ARC LOG

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

The ARCHIVE LOG command can also be issued from the MVS subsystem
interface (SSI) to enable automated scheduling systems and other programs to
execute the command via supervisor call instruction (SVC) 34.

Data sharing scope: Group or member, depending on whether you specify


MODE(QUIESCE), or on which SCOPE option you choose

Authorization
To execute this command, the privilege set of this process must include one of the
following:
v ARCHIVE privilege
v Installation SYSOPR authority
v SYSCTRL authority
v SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

26 Command Reference
-ARCHIVE LOG (DB2)
Syntax

SCOPE(MEMBER)
 ARCHIVE LOG 
SCOPE(GROUP)
MODE(QUIESCE)
TIME(nnn) NO
WAIT( )
YES
CANCEL OFFLOAD

Option descriptions
SCOPE
Specifies whether the command applies to the entire data sharing group or to a
single member only. The SCOPE option is valid only in a data sharing
environment; the option is ignored in a non-data-sharing environment. SCOPE
cannot be specified if MODE(QUIESCE) is specified; the two keywords are
mutually exclusive.
(MEMBER)
Initiates offload processing only for the member from which the command is
issued. User update activity is not suspended. If that member, or the entire
group, is already archiving, the command fails. This is the default, except
when MODE(QUIESCE) is specified.
(GROUP)
Initiates offload processing for every member of the DB2 group. User
update activity is not suspended. If any member of the group, or the entire
group, is already archiving, the command fails.
MODE(QUIESCE)
Halts all new update activity by the DB2 subsystem for a specified period of
time and attempts to bring all existing users to a point of consistency after a
commit or rollback. When a point of consistency is reached and captured in the
current active log data set, the current active log data set is truncated, and
another log data set in the inventory becomes current. offload processing then
begins with the oldest active log data set and ends with the active log data set
that was truncated.
In a data sharing environment, before archiving logs of any member, the option
quiesces all active members of a data sharing group. The option also ensures
that each inactive member had successfully quiesced its update activity and
resolved any indoubt units of recovery (URs) before the inactive subsystem
completed normal termination. If any DB2 is in a failed state, fails during
quiesce processing, or is stopped with outstanding URs, the ARCHIVE LOG
command fails, and the remaining active members allow update activity to
proceed.
If there are no indoubt URs left on all quiesced members, active or inactive, the
archive operation can continue for active members in the group. Thus, you can
archive logs of a data sharing group normally without forcing all members to be
active. The current logs of inactive members are truncated and offloaded after
they start up.

Chapter 2. Commands 27
-ARCHIVE LOG (DB2)
If a system-wide point of consistency cannot be reached during the quiesce
period, which is a length of time you can control, execution of the ARCHIVE
LOG command fails and an error message is issued. In a data sharing
environment, the maximum time period applies for the whole group, and if any
DB2 cannot quiesce within the time allowed, the command fails.
If you do not use the TIME option to specify the quiesce time period, the default
is the value specified in the field QUIESCE PERIOD of installation panel
DSNTIPA.
If there is no update activity on DB2 data when the command ARCHIVE LOG
MODE(QUIESCE) is issued, the active log is truncated and offloaded
immediately.
TIME(nnn)
Specifies the maximum length of time, in seconds, in which the DB2
subsystem is allowed to attempt a full system quiesce.
The default is the period specified in the field QUIESCE PERIOD of
installation panel DSNTIPA. See Part 2 of DB2 Installation Guide for more
information on this field.
nnn can range from 001 to 999 seconds. You must allocate an appropriate
time period for the quiesce processing or the following events can occur:
v The quiesce processing can expire before a full quiesce is accomplished.
v An unnecessary DB2 lock contention can be imposed.
v A time-out can occur.

This option is valid only when used in conjunction with the option
MODE(QUIESCE).
WAIT
Specifies whether the DB2 subsystem should wait until the quiesce
processing has completed before returning control to the invoking console
or program, or return control when the quiesce processing begins.
This option is valid only when used in conjunction with the option
MODE(QUIESCE).
(YES)
Specifies that the quiesce processing must complete before returning
control to the invoking console or program.
If WAIT(YES) is used, quiesce processing is synchronous to the user;
that is, additional DB2 commands can be issued, but they are not
processed by the DB2 command processor until the ARCHIVE LOG
command is complete.
(NO)
Specifies that control must be returned to the invoking program when
the quiesce processing begins.
If WAIT(NO) is used, quiesce processing is asynchronous to the user;
that is, you can enter additional DB2 commands once the ARCHIVE
LOG command returns control to you.
CANCEL OFFLOAD
Cancels any offloading currently in progress and restarts the offload process,
beginning with the oldest active log data set that has not been offloaded and
proceeding through all active log data sets that need offloading. Any suspended
offload operations are restarted.

28 Command Reference
-ARCHIVE LOG (DB2)
Usage notes
Remote site recovery: The ARCHIVE LOG command is very useful when
performing a DB2 backup in preparation for a remote site recovery. For example,
the command allows the DB2 subsystem to quiesce all users after a commit point,
and capture the resulting point of consistency in the current active log before the
archive is taken. Therefore, when the archive log is used with the most current
image copy (during an offsite recovery), the number of data inconsistencies will be
minimized. See Part 4 (Volume 1) of DB2 Administration Guide for additional
information on backup and recovery.

Simultaneous executions: The ARCHIVE LOG command cannot be executed if


another ARCHIVE LOG command is in progress. Instead, error message DSNJ318I
is issued and the command fails. This is true in both data sharing and
non-data-sharing environments. For example in a data sharing environment, the
command fails if the data sharing member, or group to which it belongs, is already
archiving.

Available active log space: ARCHIVE LOG cannot be used when the current
active log is the last available active log data set because of the following reasons:
v All available active log space would be used.
v The DB2 subsystem would halt processing until an offload is complete.

Executing -ARCHIVE LOG while STOP DB2 is in progress: ARCHIVE LOG


without the option MODE(QUIESCE) is permitted when STOP DB2
MODE(QUIESCE) is in progress. However, if an attempt is made to execute the
ARCHIVE LOG command when a STOP DB2 MODE(FORCE) is in progress, error
message DSNJ315I is issued and the ARCHIVE LOG command is not processed.

ARCHIVE LOG with the option MODE(QUIESCE) is not allowed when a STOP DB2
MODE(FORCE) or STOP DB2 MODE(QUIESCE) is in progress. If an attempt is
made to execute the ARCHIVE LOG command under these circumstances, error
message DSNJ315I or DSNJ316I is issued.

If the system was not fully quiesced (as determined by the number of users which
could not be quiesced), error message DSNJ317I is issued and ARCHIVE LOG
command processing is terminated. The current active log data set is not truncated
and switched to the next available active log data set and the archive log is not
created.

Canceling log offloads: It is possible for the offload of an active log to be


suspended when something goes wrong with the offload process, such as a
problem with allocation or tape mounting. Issuing ARCHIVE LOG CANCEL
OFFLOAD interrupts the offload process and restarts the offload. The command
causes an abnormal termination of the offload task, which can result in a dump. We
recommend using ARCHIVE LOG CANCEL OFFLOAD only if the offload task no
longer seems to be functioning or if you want to restart a previous offload attempt
that failed.

Demand on DB2 resources: Using the option MODE(QUIESCE) during prime time
or during a period in which time is critical causes a significant disruption in the
availability of DB2 for all users of DB2 resources.

Interaction with -DISPLAY THREAD: By issuing message DSNV400I, the


command DISPLAY THREAD indicates that an ARCHIVE LOG MODE(QUIESCE)
command is active.

Chapter 2. Commands 29
-ARCHIVE LOG (DB2)
Quiescing members of a data sharing group: It is not possible to quiesce a
single member of a data sharing group. When MODE(QUIESCE) is specified,
SCOPE(GROUP) is assumed.

| Executing -ARCHIVE LOG while logging is suspended: While logging is


| suspended by SET LOG SUSPEND, do not use ARCHIVE LOG unless CANCEL
| OFFLOAD is specified. If logging is suspended, issue SET LOG RESUME to
| resume logging before issuing ARCHIVE LOG.

Examples
Example 1: Truncate the current active log data sets and initiate an asynchronous
job to offload the truncated data sets. No quiesce processing occurs.
-ARCHIVE LOG

Example 2: Initiate a quiesce period. If all DB2 update activity is stopped within this
period, truncate the current active log data set and switch to the next available
active log data set. Let the value in the field QUIESCE PERIOD of installation panel
DSNTIPA determine the length of the quiesce period. The MODE(QUIESCE)
processing is asynchronous.

If the DB2 subsystem can successfully block all update activity before the quiesce
period ends, it proceeds to the next processing step. If the quiesce time period is
insufficient to successfully quiesce the DB2 subsystem, the active log data sets are
not truncated and the archive does not occur.
-ARCHIVE LOG MODE(QUIESCE)

Example 3: Initiate a quiesce period. If all DB2 update activity is stopped within this
period, truncate the current active log data set and switch to the next available
active log data set. The maximum length of the quiesce processing period is seven
minutes (420 seconds) and the processing is synchronous for the entire seven
minutes.

If the DB2 subsystem can successfully block all update activity before the quiesce
period ends, it proceeds to the next processing step. If the quiesce time period is
insufficient to successfully quiesce the DB2 subsystem, the active log data sets are
not truncated and the archive does not occur.
-ARCHIVE LOG MODE(QUIESCE) WAIT(YES) TIME(420)

Example 4: In a data sharing environment, initiate a quiesce period for all members
of the data sharing group. If all DB2 update activity is stopped within this period,
truncate the current active log data set and switch to the next available active log
data set. Specify a quiesce time period of 10 minutes (600 seconds) to override the
value in the field QUIESCE PERIOD of installation panel DSNTIPA for member
DB1G. If the update activity has not quiesced after the 10 minute quiesce period,
the command fails and new update activity is allowed to proceed.
-DB1G ARCHIVE LOG MODE(QUIESCE) TIME(600)

Example 5: In a data sharing environment, truncate the active log data sets for
group member DB2G and initiate an asynchronous job to offload the truncated data
sets, without any quiesce processing. In this example, SCOPE(MEMBER) is used
by default.
-DB2G ARCHIVE LOG

30 Command Reference
-ARCHIVE LOG (DB2)
Example 6: In a data sharing environment, truncate the data sets for all members
of the data sharing group and initiate an asynchronous job to offload the truncated
data sets, without any quiesce processing.
-DB2G ARCHIVE LOG SCOPE(GROUP)

Chapter 2. Commands 31
BIND PACKAGE (DSN)

BIND PACKAGE (DSN)


The DSN subcommand BIND PACKAGE builds an application package. DB2
records the description of the package in the catalog tables and saves the prepared
package in the directory. For more information on using BIND PACKAGE, see Part
5 of DB2 Application Programming and SQL Guide.

Environment
You can use BIND PACKAGE from DB2I, or from a DSN session under TSO that
runs in either the foreground or background.

Data sharing scope: Group

Authorization
The package owner must have authorization to execute all statements embedded in
the package for BIND PACKAGE to build a package without producing error
messages. (The SYSADM authority includes this authorization.) For
VALIDATE(BIND), DB2 verifies the authorization at bind time. For VALIDATE(RUN),
DB2 verifies the authorization initially at bind time, but if the authorization check
fails, DB2 rechecks it at run time.

The authorization required to add a new package or a new version of an existing


package depends on the value of field BIND NEW PACKAGE on installation panel
DSNTIPP. The default value is BINDADD.

Table 10 on page 33 summarizes the authorization required to run BIND PACKAGE,


depending on the bind options you specify, and in the case of the ADD option, the
value of field BIND NEW PACKAGE.

32 Command Reference
BIND PACKAGE (DSN)
Table 10. Summary of privileges needed for BIND PACKAGE options
Bind option Installation panel field Authorization required to run BIND
BIND NEW PACKAGE PACKAGE
ADD, using the default owner or BINDADD The primary authorization ID (default
primary authorization ID owner) must have one of the following
to add a new package or new version
of an existing package to a collection:
v The BINDADD system privilege and
either the CREATE IN privilege or
PACKADM authority on the
collection or on all collections
v SYSADM or SYSCTRL authority
BIND The primary authorization ID (default
owner) must have one of the following
to add a new package or a new
version of an existing package to a
collection:
v The BINDADD system privilege and
either the CREATE IN privilege or
PACKADM authority on the
collection or on all collections
v SYSADM or SYSCTRL authority
v PACKADM authority on the
collection or on all collections
v The BIND package privilege (can
only add a new version of an
existing package)
ADD, specifying an OWNER other BINDADD If the binder does not have SYSADM
than the primary authorization ID (1) or SYSCTRL authority, the
authorization ID of the OWNER must
have one of the following to add a
new package or new version of an
existing package to a collection:
v The BINDADD system privilege and
either the CREATE IN privilege or
PACKADM authority on the
collection or on all collections
v SYSADM or SYSCTRL authority
BIND If the binder does not have SYSADM
or SYSCTRL authority, the
authorization ID of the OWNER must
have one of the following to add a
new package or new version of an
existing package to a collection:
v The BINDADD system privilege and
either the CREATE IN privilege or
PACKADM authority on the
collection or on all collections
v SYSADM or SYSCTRL authority
v PACKADM authority on the
collection or on all collections
v The BIND package privilege (can
only add a new version of an
existing package)

Chapter 2. Commands 33
BIND PACKAGE (DSN)
Table 10. Summary of privileges needed for BIND PACKAGE options (continued)
Bind option Installation panel field Authorization required to run BIND
BIND NEW PACKAGE PACKAGE
REPLACE, using the default owner or BINDADD or BIND Primary authorization ID must have
primary authorization ID one of the following:
v Ownership of the package
v BIND privilege on the package
v PACKADM authority on the
collection or on all collections
v SYSADM or SYSCTRL authority
REPLACE, specifying an OWNER BINDADD or BIND If the binder does not have SYSADM
other than the primary authorization ID or SYSCTRL authority, the
(1)
authorization ID of the OWNER must
have one of the following:
v BIND privilege on the package
v PACKADM authority on the
collection or on all collections
v SYSADM or SYSCTRL authority
COPY BINDADD or BIND The primary or secondary
authorization ID of the binder or
OWNER must have one of the
following on the package being
copied:
v Ownership of the package
v COPY privilege on the package
v BINDAGENT privilege from the
owner of the package
v PACKADM authority on the
collection or on all collections
v SYSADM or SYSCTRL authority

Notes:
1. If any of the authorization IDs of the process has the SYSADM authority or
SYSCTRL authority, OWNER authorization-id can be any value. If any of the
authorization IDs has the BINDAGENT privilege granted from the owner, then
authorization-id can specify the grantor as OWNER. Otherwise, the OWNER
authorization-id must be one of the primary or secondary authorization IDs of
the binder.

For additional information on the required authorization to execute BIND PACKAGE


see Part 5 (Volume 2) of DB2 Administration Guide.

34 Command Reference
BIND PACKAGE (DSN)
Syntax

 BIND PACKAGE ( collection-id ) 


location-name. OWNER(authorization-id)

 enable-block 
QUALIFIER(qualifier-name)

 MEMBER(dbrm-member-name) 
LIBRARY(dbrm-pds-name)
COPY(collection-id.package-id)
COPYVER(version-id) COMPOSITE
OPTIONS( COMMAND )

 
DEFER(PREPARE) ACTION (REPLACE)
NODEFER(PREPARE) REPLVER(version-id)
(ADD)

 
YES DBPROTOCOL ( DRDA ) 1
CURRENTDATA( NO ) PRIVATE DEGREE( ANY )

 
DYNAMICRULES( RUN ) ENCODING( ASCII ) NO
BIND EBCDIC EXPLAIN( YES )
DEFINEBIND UNICODE
DEFINERUN ccsid
INVOKEBIND
INVOKERUN

 
I IMMEDWRITE( NO ) ISOLATION( RR )
FLAG( W ) PH1 RS
E YES CS
C UR
NC

NOREOPT(VARS)
 
NO REOPT(VARS)
KEEPDYNAMIC( YES )
 
OPTHINT ( ’hint-id’ ) , RELEASE( COMMIT )
DEALLOCATE
PATH(  schema-name )
USER

 
NOPACKAGE RUN
SQLERROR( CONTINUE ) VALIDATE( BIND )

Chapter 2. Commands 35
BIND PACKAGE (DSN)

enable-block:

 
ENABLE(*)
,

ENABLE (  BATCH ) 
DISABLE DLIBATCH ,
DB2CALL
CICS DLIBATCH(  connection-name )
IMS ,
IMSBMP
IMSMPP CICS(  applid )
REMOTE ,
RRSAF
IMSBMP(  imsid )
,

IMSMPP(  imsid )
,

REMOTE(  location-name )
<luname>

Option descriptions
For descriptions of the options shown in the syntax diagram, see “Options of BIND
and REBIND for PLAN, PACKAGE, and TRIGGER PACKAGE” on page 44.

Examples
Example 1: Replace version APRIL_VERSION of package TEST.DSN8BC71 at
local location USIBMSTODB22 with another version of the package. The new
version (or it could be the same) is in the DBRM DSN8BC71. If the DBRM contains
no version ID, the version ID of the package defaults to the empty string. The
package runs only from the TSO BATCH environment, and from the CICS
environment if the connection ID is CON1. The name PRODUCTN qualifies all
unqualified table, view, alias and index names.
BIND PACKAGE (USIBMSTODB22.TEST) -
MEMBER (DSN8BC71) -
ACTION (REPLACE) REPLVER (APRIL_VERSION) -
QUALIFIER (PRODUCTN) -
ENABLE (BATCH, CICS) CICS (CON1)

Example 2: UR isolation acquires almost no locks. It is fast and causes little


contention, but it reads uncommitted data. Do not use ISOLATION(UR) unless you
are sure that your applications and end users can accept the logically inconsistent
data that can occur, such as in the case of this example.

Assume that a supervisor routinely executes SQL statements using SPUFI to check
the status of parts as they go through the assembly process and to update a table
with the results of her inspection. She does not need to know the exact status of
the parts; a small margin of error is acceptable.

36 Command Reference
BIND PACKAGE (DSN)
The supervisor queries the status of the parts from a production table called
ASSEMBLY-STATUS and makes the updates in a non-production table called
REPORTS. She uses the SPUFI option AUTOCOMMIT NO and has the habit of
leaving data on the screen while she performs other tasks.

If the supervisor executes a version of SPUFI that is bound with ISOLATION(UR),


the query for the status of the parts executes without acquiring locks using UR
isolation level and the update executes using CS isolation level. Thus, the query
does not inadvertently hold locks in the production table interfering with the
production jobs, and the supervisor has data good enough for her purposes.

The SPUFI application is bound as follows:


BIND PACKAGE(DSNESPUR) -
COPY(DSNESPCS.DSNESM68) -
ACTION(ADD) -
ISOLATION(UR)

Chapter 2. Commands 37
BIND PLAN (DSN)

BIND PLAN (DSN)


The DSN subcommand BIND PLAN builds an application plan. All DB2 programs
require an application plan to allocate DB2 resources and support SQL requests
made at run time. For more information on using BIND PLAN, see Part 5 of DB2
Application Programming and SQL Guide.

Environment
You can use BIND PLAN through DB2I, or from a DSN session under TSO that
runs in either the foreground or background.

Data sharing scope: Group

Authorization
The plan owner must have authorization to execute all SQL statements embedded
in the plan1 for BIND PLAN to build a plan without producing error messages. (The
SYSADM authority includes this authorization.) For VALIDATE(BIND), DB2 verifies
the authorization at bind time. For VALIDATE(RUN), DB2 verifies the authorization
initially at bind time, but if the authorization check fails, DB2 rechecks it at run time.

Table 11 explains the authorization required to run BIND PLAN, depending on the
options specified.
Table 11. Summary of privileges needed for BIND PLAN options
Option Authorization required to run BIND PLAN
ADD, using the Primary authorization ID (default owner) must have one of the
default owner or following:
primary v BINDADD privilege
authorization ID v SYSADM or SYSCTRL authority
ADD, specifying an If the binder does not have SYSADM or SYSCTRL authority, the
OWNER other than authorization ID of the new OWNER must have one of the following:
the primary v BINDADD privilege
authorization ID v SYSADM or SYSCTRL authority

Specifying the OWNER: If any of the authorization IDs of the process


has the SYSADM authority or SYSCTRL authority, OWNER
authorization-id can be any value. If any of the authorization IDs has
the BINDAGENT privilege granted from the owner, then authorization-id
can specify the grantor as OWNER. Otherwise, OWNER
authorization-id must be one of the primary or secondary authorization
IDs of the binder.
REPLACE, using Primary authorization ID of the process must have one of the following:
the default owner or v Ownership of the plan
primary v BIND privilege on the plan
authorization ID v SYSADM or SYSCTRL authority

1. This excludes statements included in DBRMs that are bound to packages included in the package list of the plan.

38 Command Reference
BIND PLAN (DSN)
Table 11. Summary of privileges needed for BIND PLAN options (continued)
Option Authorization required to run BIND PLAN
REPLACE, If the binder does not have SYSADM or SYSCTRL authority, the
specifying an authorization ID of the OWNER must have one of the following:
OWNER other than v Ownership of the plan
the primary v BIND privilege on the plan
authorization ID v SYSADM or SYSCTRL authority

Specifying the OWNER: If any of the authorization IDs of the process


has the SYSADM authority or SYSCTRL authority, OWNER
authorization-id can be any value. If any of the authorization IDs has
the BINDAGENT privilege granted from the owner, then authorization-id
can specify the grantor as OWNER. Otherwise, OWNER
authorization-id must be one of the primary or secondary authorization
IDs of the binder.
PKLIST, specifying Authorization ID of the process must include one of the following:
individual packages v EXECUTE authority on each package specified in the PKLIST
v PACKADM authority on specific collections that contain the packages
or on all collections
v SYSADM authority
PKLIST, specifying Authorization ID of the process must include one of the following:
(*), indicating all v EXECUTE authority on collection-id.*
packages in the v PACKADM authority on specific collections that contain the packages
collection or on all collections
v SYSADM authority

For additional information on the required authorization to execute BIND PLAN see
Part 5 (Volume 2) of DB2 Administration Guide.

Chapter 2. Commands 39
BIND PLAN (DSN)
Syntax

 BIND 
PLAN(plan-name) OWNER(authorization-id) QUALIFIER(qualifier-name)

NODEFER(PREPARE)
 enable-block member-block 
DEFER(PREPARE) USE
ACQUIRE( ALLOCATE )
 
( REPLACE ) CACHESIZE(decimal-value)
RETAIN
ACTION (ADD)

 
YES CURRENTSERVER(location-name) DBPROTOCOL ( DRDA )
CURRENTDATA( NO ) PRIVATE

 
1 EXPLICIT RUN
DEGREE( ANY ) DISCONNECT( AUTOMATIC ) DYNAMICRULES( BIND )
CONDITIONAL

 
ENCODING( ASCII ) NO I
EBCDIC EXPLAIN( YES ) FLAG( W )
UNICODE E
ccsid C

 
IMMEDWRITE( NO ) ISOLATION( RR ) NO
PH1 RS KEEPDYNAMIC( YES )
YES CS
UR

NOREOPT(VARS)
 
REOPT(VARS) OPTHINT ( ’hint-id’ ) ,

PATH(  schema-name )
USER
 
COMMIT DB2 RUN
RELEASE( DEALLOCATE ) SQLRULES( STD ) VALIDATE( BIND )

40 Command Reference
BIND PLAN (DSN)

enable-block:

 
ENABLE(*)
, ,

ENABLE (  BATCH ) 
DISABLE DLIBATCH ,
DB2CALL
CICS DLIBATCH(  connection-name )
IMS ,
IMSBMP
IMSMPP CICS(  applid )
RRSAF ,

IMSBMP(  imsid )
,

IMSMPP(  imsid )

member-block:

  MEMBER(  dbrm-member-name ) 
,

LIBRARY(  dbrm-pds-name )
,

PKLIST(  collection-id .package-id )


location-name. * .*
*.

Option descriptions
For descriptions of the options shown in the syntax diagram, see “Options of BIND
and REBIND for PLAN, PACKAGE, and TRIGGER PACKAGE” on page 44.

Examples
Example 1: This subcommand creates a new plan called IMSONLY. The SQL
statements for the plan are in the DBRM member DSN8BC71. An ISOLATION level
of cursor stability (CS) provides maximum concurrency when you run the plan, and
protects database values only while the program uses them. DEPTM92 owns the
plan, but PRODUCTN qualifies any unqualified table, view, index, and alias names
referenced in the DBRM.

A cache size of 0 indicates that users will not run the plan repeatedly. Caching the
names of users authorized to run the plan helps only when the same user runs the

Chapter 2. Commands 41
BIND PLAN (DSN)
plan repeatedly while it is in the EDM pool. Since this is not the case with this plan,
there is no need to reserve space in the EDM pool for a cache that the plan does
not use.

The option ENABLE(IMS) runs the plan only from an IMS environment (DLI Batch,
BMP and MPP). If you attempt to run the plan from another environment, such as
TSO Batch, the plan allocation fails.
BIND PLAN(IMSONLY) -
MEMBER(DSN8BC71) -
ACTION(ADD) -
ISOLATION(CS) -
OWNER(DEPTM92) -
QUALIFIER(PRODUCTN) -
CACHESIZE -
ENABLE(IMS)

Example 2: If the DBRM of plan IMSONLY in example 1 contains both embedded


and dynamic SQL statements and you want to allow other users to run the plan,
you must grant the EXECUTE privilege on plan IMSONLY to those users’
authorization IDs. However, because the EXECUTE privilege on a plan is sufficient
authority to run embedded SQL statements in a DBRM but is not sufficient authority
to run dynamic SQL statements, you must also do one of the following:
v Use the SQL GRANT statement to grant the necessary privileges on the objects
(tables, views, aliases, and indexes) referenced in the dynamic SQL statements
to the users’ authorization IDs, or
v BIND the plan IMSONLY with the option DYNAMICRULES(BIND) as follows:
BIND PLAN(IMSONLY) -
MEMBER(DSN8BC71) -
ACTION(ADD) -
ISOLATION(CS) -
OWNER(DEPTM92) -
QUALIFIER(PRODUCTN) -
CACHESIZE(0) -
ENABLE(IMS) -
DYNAMICRULES(BIND)

To allow other users having only the EXECUTE privilege on a plan to run both the
embedded and dynamic SQL statements, you must bind that plan with the option
DYNAMICRULES(BIND). When DYNAMICRULES(BIND) is in effect for plan
IMSONLY:
v A single authorization ID, the authorization ID for DEPTM92, is used for
authorization checking of both the embedded and dynamic SQL statements in the
DBRM.
v PRODUCTN is the implicit qualifier of unqualified object names referenced in
both the embedded and dynamic SQL statements in the DBRM.

Example 3: This subcommand creates a new plan called CICSONLY. The plan
specifies an ISOLATION level of cursor stability (CS). DEPTM12 owns the plan, but
TESTSYS qualifies any unqualified table, view, index, and alias names referenced
in the DBRM. A cache size of 0 indicates that users will not run the plan repeatedly.

The option ENABLE(CICS) CICS(CON1) runs the plan only from CICS VTAM®
node CON1 which is specified in the APPLID parameter of the CICS SIT table. If
you attempt to run the plan from another environment or from another CICS VTAM
note, the run attempt fails.

42 Command Reference
BIND PLAN (DSN)
BIND PLAN(CICSONLY) -
MEMBER(DSN8BC71) -
ACTION(ADD) -
ISOLATION(CS) -
OWNER(DEPTM12) -
QUALIFIER(TESTSYS) -
CACHESIZE(0) -
ENABLE(CICS) CICS(CON1)

Chapter 2. Commands 43
BIND PLAN (DSN)

Options of BIND and REBIND for PLAN, PACKAGE, and TRIGGER


PACKAGE
This section lists the options you can use for binding or rebinding plans and
packages. Some of them are common for both bind and rebind and both plans and
packages.

Defaults: The default for an option is the value used if you omit the entire option.
A default of plan value for BIND PACKAGE means that the default is the same
as the value determined during the bind or rebind of the plan to which the
package is appended at run time.
A default of existing value for REBIND PLAN or REBIND PACKAGE means that
the default is the value that was determined during the previous bind or rebind
of the plan or package you are rebinding.

For all other cases, the option descriptions note the specific defaults, which DB2
assigns at bind time. If a specific default value exists, that value is underlined.

Catalog records: The DB2 catalog records information about plans and packages,
chiefly in the tables SYSIBM.SYSPLAN and SYSIBM.SYSPACKAGE. The
descriptions of where the options record information omit the constant qualifier,
SYSIBM, of those table names.

ACQUIRE (USE) On: BIND and REBIND PLAN


(ALLOCATE)

Determines whether to acquire resources for DBRMs specified in the MEMBER list
when the application first accesses them or when the plan is allocated. Local or
remote packages associated with the plan acquire their resources when the
application first accesses them.
(USE)
Acquires table space locks only when the application program bound to the plan
first uses them.
(ALLOCATE)
Acquires all table space locks when the plan is allocated. The value has no
effect on dynamic SQL statements, which always use ACQUIRE(USE).
If you use ACQUIRE(ALLOCATE), you must also use
RELEASE(DEALLOCATE). ACQUIRE(ALLOCATE) can increase the plan size,
because additional items become resident in the plan.

Defaults:

Process
Default value
BIND PLAN
USE
BIND PACKAGE
N/A
REBIND PLAN
existing value
REBIND PACKAGE
N/A

44 Command Reference
BIND PLAN (DSN)
There is no ACQUIRE option for packages. A package always acquires resources
when it first uses them, as if you specified ACQUIRE(USE). See Part 5 (Volume 2)
of DB2 Administration Guide.

Catalog record: Column ACQUIRE of table SYSPLAN.

For more information about:


v How the option affects locking and concurrency, see Part 5 (Volume 2) of DB2
Administration Guide or Part 4 of DB2 Application Programming and SQL Guide.
v How the option improves the performance of selective partition locking, see Part
5 (Volume 2) of DB2 Administration Guide or Part 4 of DB2 Application
Programming and SQL Guide.
v Estimating the size of a plan, see Part 2 of DB2 Administration Guide.

ACTION (REPLACE) On: BIND PLAN and


(REPLACE) RPLVER (BIND PACKAGE only) PACKAGE
(REPLACE) RETAIN (BIND PLAN only)
(ADD)

Determines whether the object (plan or package) replaces an existing object with
the same name or is new.
(REPLACE)
The object replaces an existing one with the same identifier, and a new entry
replaces the old one in the catalog table SYSPLAN or SYSPACKAGE. If no
object with the given identifier already exists, the bind process creates the new
object and a new entry.
The authorization ID designated explicitly or implicitly by the option OWNER
becomes the owner of the new object. If that authorization ID is not the
previous owner, all grants of privileges for the object that the previous owner
issued change to name the new owner as the grantor.
If the bind fails, the old object and its entry remain.
For BIND PACKAGE: You cannot use REPLACE with a remote package bound
with either of the options ENABLE or DISABLE. The attempt causes the bind to
fail.
REPLVER(version-id) (For BIND PACKAGE only)
Replaces a specific version of the package, identified by version-id. If the
package with the specified version-id does not exist, the bind fails.
The default for version-id comes from the DBRM if you use the MEMBER
option on BIND, or from the COPYVER option if you use the COPY option.
RETAIN (For BIND PLAN only)
Preserves EXECUTE privileges when you replace the plan. If ownership of
the plan changes, the new owner grants the privileges BIND and EXECUTE
to the previous owner.
RETAIN is not the default. If you do not specify RETAIN, everyone but the
plan owner loses the EXECUTE privilege (but not the BIND privilege). If
plan ownership changes, the new owner grants the BIND privilege to the
previous owner.
(ADD)
Adds a new object, but does not replace an existing one. If the object name

Chapter 2. Commands 45
BIND PLAN (DSN)
already exists in the catalog, the bind fails. If the bind fails for any reason, the
bind process does not produce a new package or plan and makes no entry in
the catalog.

Replacing a version of a package (REPLVER): This section describes the effect


of ACTION(REPLACE) REPLVER in four situations. Here, DBRM1 is the member
name and A and B represent the names of two versions of the package. Suppose
you bind version A with this command:
BIND PACKAGE(COLL1) MEMBER(DBRM1) ACTION(REPLACE) REPLVER(B)
v If neither DBRM1, version A, nor version B exist in the DB2 catalog, the
command fails because version B is not in the catalog. No new package is
added.
v If DBRM1 and version B, but not version A, exist in the DB2 catalog, then version
A replaces version B. As a result, version A exists in the catalog, and version B
no longer exists in the catalog.
v If DBRM1 and version A exist in the catalog, but not version B, the command
fails because version B is not in the catalog. Version A continues to exist.
v If DBRM1 and both versions A and B exist in the catalog, the command fails
because version A already exists.

Defaults:

Process
Default value
BIND PLAN
REPLACE
BIND PACKAGE
REPLACE
REBIND PLAN
N/A
REBIND PACKAGE
N/A

Catalog record: Tables SYSPLAN or SYSPACKAGE.

CACHESIZE (value of field PLAN AUTH CACHE) On: BIND and REBIND PLAN
(decimal-value)

Determines the size (in bytes) of the authorization cache acquired in the EDM pool
for the plan. At run time, the authorization cache stores user IDs authorized to run.
Consulting the cache can avoid a catalog lookup for checking authorization to run
the plan.
decimal-value
The size of the cache can range from 0 to 4096. Nonzero values that are not
multiples of 256 round to the next highest multiple of 256. CACHESIZE(0)
specifies creating no cache when the plan runs.

Defaults:

Process
Default value
BIND PLAN
Value of field PLAN AUTH CACHE on installation panel DSNTIPP, which
has a default of 0

46 Command Reference
BIND PLAN (DSN)
BIND PACKAGE
N/A
REBIND PLAN
Existing value
REBIND PACKAGE
N/A

Catalog record: Column CACHESIZE of table SYSPLAN.

For additional information on determining an optimal cache size, see Part 5 of DB2
Application Programming and SQL Guide.

COPY (collection-id.package-id) On: BIND PACKAGE


(collection-id.package-id) COPYVER

Determines that you are copying an existing package and names that package.
Copying the package recalculates the access paths in the copy.

To create a remote copy, this option copies SQL statements from a package at your
local server. Therefore, you must hold the COPY privilege or its equivalent at the
local server.
collection-id
The name of the collection that contains the package to copy, as listed in
column COLLID of catalog table SYSPACKAGE.
package-id
The name of the package to copy, as listed in column NAME of catalog table
SYSPACKAGE.
COPYVER(version-id)
Determines the version of the package to copy. The default for version-id is the
empty string.

Restrictions:
v collection-id.package-id must identify a package on the local server.
v You cannot copy to a package in the same collection. If you make the copy on
the local server, collection-id. on the COPY option must not name the collection
used on the PACKAGE option.

Defaults:

Process
Default value
BIND PLAN
N/A
BIND PACKAGE
None
REBIND PLAN
N/A
REBIND PACKAGE
N/A

COPY has no default. If you do not use COPY, you must use MEMBER. You cannot
use both options.

Chapter 2. Commands 47
BIND PLAN (DSN)
The option values of the package copied (except the values of ENABLE, DISABLE,
OWNER, and QUALIFIER) become the defaults for binding the new package. You
can override a default by choosing a new value for an option on the BIND
PACKAGE command.

Copy packages to remote servers: To copy and bind packages from DB2 Version
7 to some other server that does not support all the new BIND options in Version 7,
use the new OPTIONS(COMMAND) option on BIND PACKAGE COPY. Any options
you do not explicitly specify on the BIND PACKAGE subcommand are set to the
server’s defaults. Using this option can prevent bind errors when you bind and copy
packages to servers other than DB2 Version 7.

Catalog record: Column COPY of table SYSPACKAGE.

CURRENTDATA (YES) On: BIND and REBIND PLAN and


(NO) PACKAGE, REBIND TRIGGER
PACKAGE

Determines whether to require data currency for read-only and ambiguous cursors
when the isolation level of cursor stability is in effect. It also determines whether
block fetching can be used for distributed, ambiguous cursors.

For more information about updating the current row of a cursor, block fetching, and
data currency, see Part 4 of DB2 Application Programming and SQL Guide.
(YES) Specifies that currency is required for read-only and ambiguous cursors.
DB2 acquires page or row locks to ensure data currency. Block fetching for
distributed, ambiguous cursors is inhibited.
(NO) Specifies that currency is not required for read-only and ambiguous cursors.
Block fetching for distributed, ambiguous cursors is allowed.
If your application attempts to dynamically prepare and execute a DELETE
WHERE CURRENT OF statement against an ambiguous cursor, after that
cursor is opened, use of CURRENTDATA(NO) is not recommended. You
receive a negative SQLCODE if your application attempts a DELETE
WHERE CURRENT OF statement for any of the following cursors:
v A cursor that is using block fetching
v A cursor that is using query parallelism
v A cursor that is positioned on a row that is modified by this or another
application process

Restriction for remote rebinds: You cannot use CURRENTDATA when rebinding
a package at a remote server. To change the value of CURRENTDATA, you can:
v Issue BIND REPLACE, remotely or locally.
v Free the package and issue BIND ADD, remotely or locally.
v Rebind the package locally at the location where the package resides.

Defaults:

Process
Default value
BIND PLAN
YES
BIND PACKAGE
YES

48 Command Reference
BIND PLAN (DSN)
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

Catalog record: Column DEFERPREP of table SYSPACKAGE and column


EXPREDICATE of table SYSPLAN.

CURRENTSERVER (location-name) On: BIND and REBIND PLAN

Determines the location to connect to before running the plan. The column
CURRENTSERVER in catalog table SYSPLAN records the value of location-name.
The special register CURRENT SERVER also receives that value at the server
when the plan is allocated. When the plan runs, the requester implicitly uses a type
1 CONNECT statement to that location.

You should use CURRENTSERVER to cause a local application to use data from a
remote server without changing the application. Avoid using CURRENTSERVER
with applications that contain explicit CONNECT statements. The implicit type 1
CONNECT statement that is used by CURRENTSERVER causes any explicit
CONNECT statement issued in the application to be type 1, even if the application
was precompiled with the default type 2.
location-name
The name of the location to connect to. The catalog table SYSIBM.LOCATIONS
must contain this name. If the table does not exist, if the table does not contain
the DBMS, or if there are no packages at that location, warning messages
occur.

SQL return codes: CURRENTSERVER causes DB2 to execute a type 1


CONNECT statement. DB2 does not display or report to the application program
any warnings that this CONNECT returns. To display the warnings, use explicit
CONNECT statements rather than the CURRENTSERVER bind option.

Defaults:

Process
Default value
BIND PLAN
Local DBMS (regardless of the name of the local location)
BIND PACKAGE
N/A
REBIND PLAN
Existing value
REBIND PACKAGE
N/A

Catalog record: Column CURRENTSERVER of table SYSPLAN.

DBPROTOCOL (DRDA) On: BIND and REBIND PLAN and


(PRIVATE) PACKAGE

Specifies which protocol to use when connecting to a remote site that is identified
by a three-part name statement.

Chapter 2. Commands 49
BIND PLAN (DSN)
For DRDA, a package must be bound to each remote site that is referenced by a
three-part name statement. Specify DRDA® to inform DB2 that the three-part name
statements in the plan or package are to be converted to DRDA protocol.

If you specify an option on the BIND PACKAGE command, DB2 uses that remote
access method for the package statements, regardless of the BIND PLAN option.
For remote bind, the default is the system default at the remote site.

If you specify an option on the BIND PLAN statement, that information is stored in
table SYSPLAN.
(DRDA)
DBPROTOCOL DRDA is passed on BIND PACKAGE, BIND PLAN, REBIND
PACKAGE, or REBIND PLAN invocation.
(PRIVATE)
DBPROTOCOL PRIVATE is passed on BIND PACKAGE, BIND PLAN, REBIND
PACKAGE, or REBIND PLAN invocation.

Defaults:

Process
Default value
BIND PLAN
DRDA
BIND PACKAGE
System default
REBIND PLAN
Value that was specified the last time the plan was bound
REBIND PACKAGE
Value that was specified the last time the package was bound

Catalog record: Column DBPROTOCOL of tables SYSPACKAGE and SYSPLAN.

DEFER(PREPARE) On: BIND and REBIND PLAN and


NODEFER(PREPARE) PACKAGE

Determines whether to defer preparation for dynamic SQL statements that refer to
remote objects, or to prepare them immediately. If you defer preparation, the
dynamic statement prepares when DB2 first encounters a statement of the type
EXECUTE, OPEN, or DESCRIBE that refers to the dynamic statement.

For BIND and REBIND PACKAGE, if neither option is specified, and


NOREOPT(VARS) applies:
v For local bind the package inherits the plan’s option at runtime.
v For remote bind the default is NODEFER(PREPARE) at the remote DB2 server.

If neither DEFER nor NODEFER is specified and REOPT(VARS) applies,


DEFER(PREPARE) is the default value.

You cannot use both DEFER(PREPARE) and NODEFER(PREPARE). In addition,


you cannot use both NODEFER(PREPARE) and REOPT(VARS).
NODEFER(PREPARE)
Does not defer preparation.
DEFER(PREPARE)
Defers preparation.

50 Command Reference
BIND PLAN (DSN)
DEFER(PREPARE) and distributed processing: To improve performance,
consider using DEFER(PREPARE) when binding dynamic or static SQL for DB2
private protocol access and when binding dynamic SQL for DRDA access. Specify
the bind option DEFER(PREPARE) instead of NODEFER(PREPARE). DB2 does
not prepare the dynamic SQL statement until that statement executes. This reduces
network traffic, which improves the performance of the dynamic SQL statement.

To defer the preparation of an SQL statement in an application, bind or rebind the


application with the option DEFER(PREPARE). This defers PREPARE messages for
SQL statements that refer to a remote object until either:
v The statement executes
v The application requests a description of the results of the statement

If you choose to defer PREPARE statements, after the EXECUTE or DESCRIBE


statement, you should code your application to handle any SQL error codes or
SQLSTATEs that the PREPARE statement might return. You can defer PREPARE
statements only if you specify the bind option DEFER(PREPARE).

Defaults:

Process
Default value
BIND PLAN
NODEFER
BIND PACKAGE
Plan value
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

Catalog record: Column DEFERPREP of table SYSPLAN and column


DEFERPREPARE of table SYSPACKAGE.

DEGREE (1) On: BIND and REBIND PLAN and


(ANY) PACKAGE

Determines whether to attempt to run a query using parallel processing to maximize


performance.

For plans, the value of DEGREE applies only to the DBRMs bound directly to the
plan (named in the MEMBER option on BIND PLAN), and has no affect on PKLIST
names. The value has no effect on dynamic SQL statements, which use the value
of the special register CURRENT DEGREE. The value of the special register can
be changed by executing the SET CURRENT DEGREE statement.
(1) Prohibits parallel processing.
(ANY) Allows parallel processing.

Limitations: If you bind plans or packages using DEGREE=ANY, the space


required in the EDM pool could increase by 50%–70%.

Defaults:

Process
Default value

Chapter 2. Commands 51
BIND PLAN (DSN)
BIND PLAN
1
BIND PACKAGE
1
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

Catalog record: Column DEGREE of tables SYSPACKAGE and SYSPLAN.

DISCONNECT (EXPLICIT) On: BIND and REBIND PLAN


(AUTOMATIC)
(CONDITIONAL)

Determines which remote connections to destroy during commit operations. The


option applies to any application process that uses the plan and has remote
connections of any type. Regardless of the value of this option, a commit operation
destroys all connections in the release pending state. You can put a connection in
the release pending state using the SQL statement RELEASE.
(EXPLICIT)
Destroy only connections in the release pending state. This value allows you
maximum flexibility for controlling remote connections.
(AUTOMATIC)
Destroy all remote connections.
(CONDITIONAL)
Destroy all remote connections unless an open cursor defined as WITH HOLD
is associated with the connection.

Defaults:

Process
Default value
BIND PLAN
EXPLICIT
BIND PACKAGE
N/A
REBIND PLAN
Existing value
REBIND PACKAGE
N/A

Catalog record: Column DISCONNECT of table SYSPLAN.

DYNAMICRULES (RUN) On: BIND and REBIND


(BIND) PLAN and PACKAGE
(DEFINEBIND) (BIND and REBIND PACKAGE only)
(DEFINERUN) (BIND and REBIND PACKAGE only)
(INVOKEBIND) (BIND and REBIND PACKAGE only)
(INVOKERUN) (BIND and REBIND PACKAGE only)

Determines what values apply at run time for the following dynamic SQL attributes:
v The authorization ID that is used to check authorization
v The qualifier that is used for unqualified objects
v The source for application programming options that DB2 uses to parse and
semantically verify dynamic SQL statements

52 Command Reference
BIND PLAN (DSN)
v Whether dynamic SQL statements can include GRANT, REVOKE, ALTER,
CREATE, DROP, and RENAME statements

In addition to the DYNAMICRULES value, the run-time environment of a package


controls how dynamic SQL statements behave at run time. The two possible
run-time environments are:
v The package runs as part of a stand-alone program
v The package runs as a stored procedure or user-defined function package, or
runs under a stored procedure or user-defined function

The combination of the DYNAMICRULES value and the run-time environment


determine the values for the dynamic SQL attributes. That set of attribute values is
called the dynamic SQL statement behavior. The four behaviors are:
v Run behavior
v Bind behavior
v Define behavior
v Invoke behavior

The following DYNAMICRULES option descriptions include a description of the


dynamic SQL statement behavior for each run-time environment. This information is
summarized in Table 12 on page 55.
(RUN) Processes dynamic SQL statements using the standard attribute values for
dynamic SQL statements, which are collectively called run behavior:
v DB2 uses the authorization ID of the application process and the SQL
authorization ID (the value of the CURRENT SQLID special register) for
authorization checking of dynamic SQL statements.
v DB2 uses the authorization ID of the application process and the SQL
authorization ID (the value of the CURRENT SQLID special register) as
the implicit qualifier of table, view, index, and alias names.
v Dynamic SQL statements use the values of application programming
options that were specified during installation. The installation option USE
FOR DYNAMICRULES has no effect.
v GRANT, REVOKE, CREATE, ALTER, DROP, and RENAME statements
can be executed dynamically.
(BIND)
Processes dynamic SQL statements using the following attribute values,
which are collectively called bind behavior:
v DB2 uses the authorization ID of the plan or package for authorization
checking of dynamic SQL statements.
v Unqualified table, view, index, and alias names in dynamic SQL
statements are implicitly qualified with value of the bind option
QUALIFIER; if you do not specify QUALIFIER, DB2 uses the
authorization ID of the plan or package owner as the implicit qualifier.
v The attribute values that are described in “Common attribute values for
bind, define, and invoke behaviors” on page 55.
The values of the authorization ID and the qualifier for unqualified objects
are the same as those that are used for embedded or static SQL
statements.
(DEFINEBIND)
Processes dynamic SQL statements using one of two behaviors, define
behavior or bind behavior.

Chapter 2. Commands 53
BIND PLAN (DSN)
When the package is run as or runs under a stored procedure or
user-defined function package, DB2 processes dynamic SQL statements
using define behavior, which consists of the following attribute values:
v DB2 uses the authorization ID of the user-defined function or stored
procedure owner for authorization checking of dynamic SQL statements
in the application package.
v The default qualifier for unqualified objects is the user-defined function or
stored procedure owner.
v The attribute values that are described in “Common attribute values for
bind, define, and invoke behaviors” on page 55.

When the package is run as a stand-alone program, DB2 processes


dynamic SQL statements using bind behavior, which is described in 53.
(DEFINERUN)
Processes dynamic SQL statements using one of two behaviors, define
behavior or run behavior.
When the package is run as or runs under a stored procedure or
user-defined function package, dynamic SQL statements have define
behavior, which is described in 53.
When the package is run as a stand-alone program, DB2 processes
dynamic SQL statements using run behavior, which is described in 53.
(INVOKEBIND)
Processes dynamic SQL statements using one of two behaviors, invoke
behavior or bind behavior.
When the package is run as or runs under a stored procedure or
user-defined function package, DB2 processes dynamic SQL statements
using invoke behavior, which consists of the following attribute values:
v DB2 uses the authorization ID of the user-defined function or stored
procedure invoker for authorization checking of dynamic SQL statements
in the application package.
If the invoker is the primary authorization ID of the process or the
CURRENT SQLID value, secondary authorization IDs are also checked if
they are needed for the required authorization. Otherwise, only one ID,
the ID of the invoker, is checked for the required authorization.
v The default qualifier for unqualified objects is the user-defined function or
stored procedure invoker.
v The attribute values that are described in “Common attribute values for
bind, define, and invoke behaviors” on page 55.

When the package is run as a stand-alone program, DB2 processes


dynamic SQL statements using bind behavior, which is described in 53.
(INVOKERUN)
Processes dynamic SQL statements using one of two behaviors, invoke
behavior or run behavior.
When the package is run as or runs under a stored procedure or
user-defined function package, DB2 processes dynamic SQL statements
using invoke behavior, which is described in 54.
When the package is run as a stand-alone program, DB2 processes
dynamic SQL statements using run behavior, which is described in 53.

54 Command Reference
BIND PLAN (DSN)
Common attribute values for bind, define, and invoke behavior: The following
attribute values apply to dynamic SQL statements in plans or packages that have
bind, define, or invoke behavior:
v You can execute the statement SET CURRENT SQLID in a package or plan that
is bound with any DYNAMICRULES value. However, DB2 does not use the value
of CURRENT SQLID as the authorization ID for dynamic SQL statements.
DB2 always uses the value of CURRENT SQLID as the qualifier for the
EXPLAIN output PLAN_TABLE.
v If the value of installation option USE FOR DYNAMICRULES is YES, DB2 uses
the application programming default values that were specified during installation
to parse and semantically verify dynamic SQL statements. If the value of USE for
DYNAMICRULES is NO, DB2 uses the precompiler options to parse and
semantically verify dynamic SQL statements. For a list of the application
programming defaults that the USE FOR DYNAMICRULES option affects, see
Part 5 of DB2 Application Programming and SQL Guide.
v GRANT, REVOKE, CREATE, ALTER, DROP, and RENAME statements cannot
be executed dynamically.

Remote DB2 servers: For a package that uses DRDA access, DB2 sends the
DYNAMICRULES option to the DB2 server at bind time.

For a plan or package that uses DB2 private protocol access, DB2 sends a
DYNAMICRULES value of BIND or RUN to the server at run time, using the
following rules:
v If the DYNAMICRULES value with which the package is bound is BIND,
DEFINEBIND, or INVOKEBIND, DB2 sends a value of BIND to the server.
v If the DYNAMICRULES value with which the package is bound is RUN,
DEFINERUN, or INVOKERUN, DB2 sends a value of RUN to the server.

Table 12 summarizes the dynamic SQL statement attribute values for each
behavior. For more information about the dynamic SQL attributes that are affected
by the DYNAMICRULES option, see Part 5 of DB2 Application Programming and
SQL Guide.
Table 12. Definitions of dynamic SQL statement behaviors
Value for dynamic SQL attributes
Dynamic SQL attribute Bind behavior Run behavior Define behavior Invoke behavior
Authorization ID Package OWNER Current SQLID User-defined Authorization ID of
function or stored invoker
procedure owner
Default qualifier for Bind OWNER or Current SQLID User-defined Authorization ID of
unqualified objects QUALIFIER value function or stored invoker
procedure owner
CURRENT SQLID Initialized to Primary Initialized to Primary Initialized to Primary Initialized to Primary
authid. SET SQLID authid. SET SQLID authid. SET SQLID authid. SET SQLID
is allowed. is allowed. is allowed. is allowed.
Source for application As determined by Install panel As determined by As determined by
programming options the DSNHDECP DSNHDECP the DSNHDECP the DSNHDECP
parameter application defaults parameter parameter
DYNRULS DYNRULS DYNRULS
Can execute GRANT, No Yes No No
REVOKE, CREATE,
ALTER, DROP, RENAME?

Chapter 2. Commands 55
BIND PLAN (DSN)
Defaults:

Process
Default value
BIND PLAN
RUN
BIND PACKAGE
Plan value
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

The default for a package on a remote server is RUN.

Catalog record: Column DYNAMICRULES of tables SYSPACKAGE and


SYSPLAN.

ENABLE DISABLE (*) On: BIND and REBIND


(BATCH) PLAN and PACKAGE
(CICS)
(CICS) CICS(applid, ...)
(DB2CALL)
(DLIBATCH)
(DLIBATCH) DLIBATCH(connection-name, ...)
(IMS)
(IMSBMP)
(IMSBMP) IMSBMP(imsid, ...)
(IMSMPP)
(IMSMPP) IMSMPP(imsid, ...)
(REMOTE) (BIND and REBIND PACKAGE only)
(REMOTE) REMOTE (location-name,..., < luname>,...)
(RRSAF)

Determines which connections can use the plan or package. You cannot use both
DISABLE and ENABLE. For packages, DISABLE and ENABLE are valid only for
local bind operations.
ENABLE
Lists the system connection types that can use the plan or package. Connection
types not listed cannot use it.
DISABLE
Lists the system connection types that cannot use the plan or package.
Connection types not listed can use it.

With some connection types you can list connection IDs to identify specific
connections of the type to disable or enable.
If you list connection IDs as disabled, any connections not listed for the same
connection type are enabled.
If you list connection IDs as enabled, any connections not listed for the same
connection type are disabled.

A connection ID is valid only after the keyword that names its corresponding
connection type.

Connection types:
(*) Specifies all valid connection types. Use only with ENABLE.

56 Command Reference
BIND PLAN (DSN)
(BATCH)
Indicates that all TSO connections are either enabled or disabled for the plan or
package.
(CICS)
Identifies the CICS connection. All CICS VTAM node names specified in the
CICS SIT table are either enabled or disabled for the plan or package.
(CICS) CICS(applid, ...)
Identifies the CICS VTAM node name specified in the APPLID parameter of the
CICS SIT table. The CICS VTAM node identified by applid is either enabled or
disabled for the plan or package.
(DB2CALL)
Indicates that the call attachment facility (CAF) connection is either enabled or
disabled for the plan or package.
(DLIBATCH)
Identifies the Data Language I (DL/I) Batch Support Facility connection. All
connection identifiers from the DDITV02 data set or the job name in the JCL
that the DL/I batch support system needs to have are either enabled or disabled
for the plan or package.
(DLIBATCH) DLIBATCH(connection-name, ...)
Specifies the connection identifier as from the DDITV02 data set or the job
name in the JCL that the DL/I batch support system needs to have. The DL/I
batch connection identified by connection-name is either enabled or disabled for
the plan or package.
(IMS)
Specifies that all Information Management System (IMS) connections,
DLIBATCH, IMSBMP, and IMSMPP are either enabled or disabled for the plan
or package.
(IMSBMP)
Specifies the IMS connection for the Batch Message Program (BMP) region. All
IMS BMP connections identified by the value of IMSID on the CTL parameter
EXEC are either enabled or disabled for the plan or package.
(IMSBMP) IMSBMP(imsid, ...)
Specifies the value of IMSID on the CTL parameter EXEC. The IMS BMP
connection identified by imsid is either enabled or disabled for the plan or
package.
(IMSMPP)
Specifies the IMS connection for the Message Processing Program (MPP) and
IMS Fast Path (IFP) regions. All IMS MPP connections identified by the value of
the IMSID on the CTL parameter EXEC. are either enabled or disabled for the
plan or package.
(IMSMPP) IMSMPP(imsid, ...)
Specifies the value of IMSID on the CTL parameter EXEC. The IMS MPP
connection identified by imsid is either enabled or disabled for the plan or
package.
(REMOTE)
Indicates that all remote connections are either enabled or disabled for the plan
or package.
(REMOTE) REMOTE (location-name,...,< luname>,...) (PACKAGE only)
Specifies that the remote connections identified by the following are either
enabled or disabled for the package:

Chapter 2. Commands 57
BIND PLAN (DSN)
location-name
Specifies the location name of a requesting DBMS that is a DB2 for
OS/390 and z/OS subsystem.
< luname>
Specifies the logical unit name, as defined to VTAM at the server location,
of a requesting DBMS that is not a DB2 for OS/390 and z/OS subsystem.
You must bracket a logical unit name with the less than (<) and the greater
than (>) characters to differentiate it from a location name.
(RRSAF)
Indicates that the RRS attachment facility connection is either enabled or
disabled for the plan or package.

Performance hint: Whenever the plan or package is allocated, DB2 must check
the connection type and connection name with the list of enabled or disabled
connections. For best performance, keep the list short.

Plans that disable a system: If a plan disables a system, then no packages


appended to that plan can run from that system, regardless of the
ENABLE/DISABLE options. However, if the same packages are appended to other
plans that enable the system, those packages can run from that system under
those plans.

Defaults:

Process
Default value
BIND PLAN
ENABLE(*)
BIND PACKAGE
ENABLE(*)
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

Catalog record: Table SYSPKSYSTEM for packages and table SYSPLSYSTEM for
plans.
|| ENCODING (ASCII) On: BIND and REBIND PLAN and
| (EBCDIC) PACKAGE
| (UNICODE)
| (ccsid)
|
Specifies the application encoding for all host variables static statements in the plan
# or package. EBCDIC is the only valid option for a plan or package that was
# precompiled on DB2 Version 6 or earlier.

Defaults: The default package application encoding scheme is not inherited from
the plan application encoding option. The default for a package that is bound on a
remote DB2 for OS/390 is the system default application encoding scheme at the
remote server.

Process
Default value

58 Command Reference
BIND PLAN (DSN)
BIND PLAN
The system default application encoding scheme that was specified at
installation time.
BIND PACKAGE
The system default application encoding scheme that was specified at
installation time.
REBIND PLAN
The value that was specified the last time that the plan or package was
bound.
REBIND PACKAGE
The value that was specified the last time that the plan or package was
bound.

Product-sensitive Programming Interface

EXPLAIN (NO) On: BIND and REBIND PLAN and


(YES) PACKAGE, REBIND TRIGGER
PACKAGE

Obtains information about how SQL statements in the package, or in the member
list of the plan, are to execute, and then inserts that information into the table
owner.PLAN_TABLE, where owner is the authorization ID of the owner of the plan
or package. This option does not obtain information for statements that access
remote objects.

PLAN_TABLE must be a table; it cannot be a view, alias, or synonym. It should


exist before the bind process begins.

The EXPLAIN option also populates two optional tables, if they exist:
DSN_STATEMNT_TABLE and DSN_FUNCTION_TABLE.

DSN_STATEMNT_TABLE contains DB2’s estimate of the processing cost for an


SQL statement. See Part 6 of DB2 Application Programming and SQL Guide for
more information.

DSN_FUNCTION_TABLE contains information about function resolution. See Part 3


of DB2 Application Programming and SQL Guide for more information.

You can get EXPLAIN output for a statement that is embedded in a program that is
bound with EXPLAIN(NO) by embedding the SQL statement EXPLAIN in the
program. Otherwise, the value of the EXPLAIN option applies to all explainable SQL
statements in the program, and to the fullselect portion of any DECLARE CURSOR
statements.

In all inserts to owner.PLAN_TABLE, the value of QUERYNO is the statement


number that the precompiler assigned and placed in the DBRM.

For a description of the tables populated by the EXPLAIN option, see information
about the EXPLAIN statement in Chapter 5 of DB2 SQL Reference.

For automatic rebind: EXPLAIN(YES) is in effect if you bind the plan or package
with EXPLAIN(YES) and if the value of field EXPLAIN PROCESSING on installation
panel DSNTIPO is YES. If EXPLAIN(YES) and VALIDATE(BIND) are in effect and
PLAN_TABLE is not correct, the automatic rebind fails.
(NO) Provides no EXPLAIN information.
(YES) Inserts information in the tables populated by EXPLAIN. If

Chapter 2. Commands 59
BIND PLAN (DSN)
owner.PLAN_TABLE does not exist at bind time, the value of the option
VALIDATE determines the success of the bind operation.
v If the value is BIND, the bind fails.
v If the value is RUN, DB2 checks to see if the table exists again at run
time. If it still does not exist, the plan or package cannot run. If it does
exist, DB2 inserts information in PLAN_TABLE before the plan or
package runs.

If neither or both of the optional tables DSN_FUNCTION_TABLE or


DSN_STATEMNT_TABLE exist, or if they are defined incorrectly, the bind
does not fail.

Invalidation resulting from an unsuccessful rebind: An unsuccessful rebind


generating a return code of greater than 4 invalidates the rebind object and rolls
back all changes to the object, leaving it as it was before the rebind attempt.
However, if the rebind fails because of either the REBIND option EXPLAIN or the
SQL statement EXPLAIN (that is, the PLAN_TABLE does not exist or was created
incorrectly), DB2 rolls back all changes to the object but does not invalidate the
object.

Defaults:

Process
Default value
BIND PLAN
NO
BIND PACKAGE
NO
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

Catalog record: Column EXPLAIN of table SYSPACKAGE and column EXPLAN of


SYSPLAN.
End of Product-sensitive Programming Interface

FLAG (I) On: BIND and REBIND PLAN and


(W) PACKAGE, REBIND TRIGGER
(E) PACKAGE
(C)

Determines what messages to display.


(I) All informational, warning, error, and completion messages
(W) Only warning, error, and completion messages
(E) Only error and completion messages
(C) Only completion messages

Rebinding multiple plans or packages: When your REBIND command contains


an asterisk (*) and affects many plans or packages, FLAG(E) is recommended to
avoid running out of message storage.

Defaults:

60 Command Reference
BIND PLAN (DSN)

Process
Default value
BIND PLAN
I
BIND PACKAGE
I
REBIND PLAN
I
REBIND PACKAGE
I

IMMEDWRITE (NO) On: BIND and REBIND PLAN and


(PH1) PACKAGE
(YES)

Tells whether immediate writes will be done for updates made to group buffer pool
dependent pagesets or partitions. This option is only applicable for data sharing
environments. Table 13 shows the implied hierarchy of this option. The
IMMEDWRITE option values are as follows:
(NO) Specifies that normal write activity is done. Updated pages that are group
buffer pool dependent are written at or before phase two of commit or at the
end of abort for transactions that have rolled back.
(PH1) Specifies that updated pages that are group buffer pool dependent are
written at or before phase one of commit. If the transaction subsequently
rolls back, the pages will be updated again during the rollback process, and
they will be written again at the end of abort.
(YES) Specifies that updated pages that are group buffer pool dependent are
immediately written as soon as the buffer update completes. Updated
pages are written immediately even if the buffer is updated during forward
progress or during rollback of a transaction. Specifying this option may
impact performance.
Table 13. The implied hierarchy of the IMMEDWRITE option
IMMEDWRITE IMMEDWRI
bind option subsystem parameter Value at run time
NO NO NO
NO PH1 PH1
NO YES YES
PH1 NO PH1
PH1 PH1 PH1
PH1 YES YES
YES NO YES
YES PH1 YES
YES YES YES

Performance hints: You can use IMMEDWRITE(PH1) and IMMEDWRITE(YES) for


situations where a transaction spawns another transaction that can run on another
DB2 member and that depends on uncommitted updates that were made by the
originating transaction.

Specify IMMEDWRITE(PH1) to cause group buffer pool dependent pages to be


written at or before phase 1 of commit.

Chapter 2. Commands 61
BIND PLAN (DSN)
Specify IMMEDWRITE(YES) to cause the originating transaction to immediately
write its updated GBP-dependent buffers (instead of waiting until the end of commit
or rollback), which will ensure that the dependent transaction always gets the same
results regardless of whether it runs on the same member or a different member as
the originating transaction. IMMEDWRITE(YES) should be used with caution
because of its potential impact to performance. The impact will be more significant
for plans and packages that do many buffer updates to GBP-dependent pages, and
not as noticeable for plans or packages that perform few buffer updates to
GBP-dependent pages. The following options can be considered as alternatives to
using IMMEDWRITE(YES):
v Always run the dependent transaction on the same DB2 member as the
originating transaction.
v Run the dependent transaction with ISOLATION(RR).
v Wait until the completion of phase two of commit before spawning the dependent
transaction.
v CURRENTDATA(YES) or ISOLATION(RS) can be used to solve the problem only
if the originating transaction updates columns that are not in the WHERE clause
of the dependent transaction.

Defaults:

Process
Default value
BIND PLAN
NO
BIND PACKAGE
NO
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default for a package on a remote DB2 server is IMMEDWRITE(NO).

ISOLATION (RR) On: BIND and REBIND PLAN and


(RS) PACKAGE, REBIND TRIGGER
(CS) PACKAGE
(UR)
(NC)

Determines how far to isolate an application from the effects of other running
applications. For more information on isolation levels, see Improving Concurrency in
Part 5 (Volume 2) of DB2 Administration Guide.
(RR) Repeatable read. Ensures that:
v Your application does not read a row that another process has changed
until that process releases that row.
v Other processes do not change a row that your application reads until
your application commits or terminates.
(RS) Read stability. Ensures that:
v Your application does not read a row that another process has changed
until that process releases that row.
v Other processes do not change a row that satisfies the application’s
search condition until your application commits or terminates. It does

62 Command Reference
BIND PLAN (DSN)
allow other application processes to insert a row, or to change a row that
did not originally satisfy the search condition.

If the server does not support RS, it uses RR.


(CS) Cursor stability. Ensures, like repeatable read, that your application does
not read a row that another process changes until that process releases
that row. Unlike repeatable read, cursor stability does not prevent other
applications from changing rows that your application reads before your
program commits or terminates.
(UR) Uncommitted read. Unlike repeatable read and cursor stability, does not
ensure anything. With the exception of LOB data, uncommitted read avoids
acquiring locks on data and allows:
v Other processes change any row your application reads during the unit
of work.
v Your application read any row that another process has changed, even if
the process has not committed the row.

You can use this option only with a read-only operation: SELECT, SELECT
INTO, or FETCH using a read-only cursor. If you specify ISOLATION(UR)
for any other operation, DB2 uses ISOLATION(CS) for that operation.
(NC) No commit. Used on packages that are bound to certain servers other than
DB2 for OS/390 and z/OS. DB2 for OS/390 and z/OS does not support NC.
If the server does not support this isolation level, it uses UR.

For more information about how the ISOLATION option affects locking and
concurrency, including how DB2 resolves conflicts by using the most restrictive
value when the values specified in the plan and package differ, see Part 4 of DB2
Application Programming and SQL Guide.

Defaults:

Process
Default value
BIND PLAN
RR
BIND PACKAGE
Plan value
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default for binding a package to a remote server is RR.

For REBIND PACKAGE, you cannot change ISOLATION from a specified value to a
default of the plan value by using REBIND PACKAGE. To do that, you must use
BIND PACKAGE ACTION(REPLACE).

Catalog record: Column ISOLATION of tables SYSPACKAGE and SYSPLAN.

KEEPDYNAMIC (NO) On: BIND and REBIND PLAN and


(YES) PACKAGE

Determines whether DB2 keeps dynamic SQL statements after commit points.

Chapter 2. Commands 63
BIND PLAN (DSN)
(NO) Specifies that DB2 does not keep dynamic SQL statements after commit
points.
(YES) Specifies that DB2 keeps dynamic SQL statements after commit points.

If you specify KEEPDYNAMIC(YES), the application does not need to prepare an


SQL statement after every commit point. DB2 keeps the dynamic SQL statement
until one of the following occurs:
v The application process ends
v A rollback operation occurs.
v The application executes an explicit PREPARE statement with the same
statement identifier.

If you specify KEEPDYNAMIC(YES), and the prepared statement cache is active,


DB2 keeps a copy of the prepared statement in the cache. If the prepared
statement cache is not active, DB2 keeps only the SQL statement string past a
commit point. DB2 then implicitly prepares the SQL statement if the application
executes an OPEN, EXECUTE, or DESCRIBE operation for that statement.

If you specify KEEPDYNAMIC(YES), you must not specify REOPT(VARS).


KEEPDYNAMIC(YES) and REOPT(VARS) are mutually exclusive.

Performance hint: KEEPDYNAMIC(YES) results in improved performance if your


DRDA client application uses a cursor defined WITH HOLD. DB2 automatically
closes a held cursor when there are no more rows to retrieve, which eliminates an
extra network message.

Defaults:

Process
Default value
BIND PLAN
NO
BIND PACKAGE
NO
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default for a package on a remote DB2 server is KEEPDYNAMIC(NO).

Catalog record: Column KEEPDYNAMIC of table SYSPLAN and SYSPACKAGE.

LIBRARY (dbrm-pds-name) On: BIND PLAN, BIND PACKAGE


(dbrm-pds-name, ...) (BIND PLAN only)

Determines what partitioned data sets (libraries) to search for the DBRMs listed in
the MEMBER option. The libraries must be cataloged.

The bind process searches for the libraries in the order that you list them. If the
libraries do not contain some DBRM listed in the MEMBER option, and if a JCL
statement exists for DBRMLIB DD, then the process searches for the member
among the libraries that the JCL statement describes.

dbrm-pds-name is the data set name of a library.

64 Command Reference
BIND PLAN (DSN)
For BIND PACKAGE, you can specify only one library to search.

For BIND PLAN, you can specify one or more libraries to search.

Defaults:

Process
Default value
BIND PLAN
None
BIND PACKAGE
None
REBIND PLAN
N/A
REBIND PACKAGE
N/A

The default is to search only the libraries described by the DD statement for
DBRMLIB.

MEMBER (dbrm-member-name) On: BIND PLAN, BIND


(dbrm-member-name, ...) (BIND PLAN only) PACKAGE

Determines what database request modules (DBRMs) to include in the plan or


package.
dbrm-member-name
Specifies the name of a library member that contains a DBRM. You can name
the partitioned data set, of which a DBRM is a member, either in the LIBRARY
option or in the JCL statement for DBRMLIB DD.
For BIND PACKAGE only, the name becomes the package name. Names
beginning with DSN are reserved; you receive a warning message if you use
one.

For BIND PACKAGE, you can use only one member. If you do not use MEMBER,
you must use COPY. You cannot use both options.

For BIND PLAN, you can list many members. DB2 sorts the member list in
alphabetical order. If you do not use MEMBER, you must use PKLIST.

Defaults:

Process
Default value
BIND PLAN
None
BIND PACKAGE
None
REBIND PLAN
N/A
REBIND PACKAGE
N/A

Catalog record: Column NAME of table SYSPACKAGE for BIND PACKAGE, or the
table SYSDBRM for BIND PLAN.

Chapter 2. Commands 65
BIND PLAN (DSN)
OPTHINT ('hint-id') On: BIND and REBIND PLAN and
PACKAGE

Controls whether query optimization hints are used for static SQL.
('hint-id')
A character string of up to eight characters in length, which is used by the
optimizer when searching the PLAN_TABLE for rows to use as input to the
optimizer. The delimiters can only be single quotation marks (').
If 'hint-id' contains all blank characters, DB2 does not use optimization hints
for static SQL statements.

DB2 uses optimization hints only when optimization hints are enabled for your
system. To enable optimization hints, specify YES in the OPTIMIZATION HINTS
field of installation panel DSNTIP4.

For more information about using the OPTHINT option, see Part 5 (Volume 2) of
DB2 Administration Guide.

Restriction: The PACKAGE does not inherit from the PLAN.

Defaults:

Process
Default value
BIND PLAN
All blanks, use normal optimization
BIND PACKAGE
All blanks, use normal optimization
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default for a package on a remote server is all blanks.

Catalog record: Column OPTHINT of tables SYSPLAN and SYSPACKAGE.

OPTIONS(COMPOSITE) On: BIND PACKAGE COPY


OPTIONS(COMMAND)

Specifies which bind options to use for the new package.


COMPOSITE
The options for the new package are what you specify on the BIND
PACKAGE COPY subcommand. Options that you do not specify are the
option values taken from the SYSPACKAGE catalog table row that
describes the source package to be copied.
COMMAND
The options for the new package are what you specify on the BIND
PACKAGE COPY subcommand. Options that you do not specify are
determined as follows:
v For a local copy, the DB2-defined BIND PACKAGE options defaults are
used.

66 Command Reference
BIND PLAN (DSN)
v For a remote copy, the server-defined BIND PACKAGE options defaults
are used at the server. You must use the OPTIONS(COMMAND) when
copying to a downlevel server. A down-level server is any server that is
not DB2 Version 7.

Defaults:

Process
Default value
BIND PACKAGE COPY
OPTIONS(COMPOSITE)

OWNER (authorization-id) On: BIND and REBIND PLAN and


PACKAGE

Determines the authorization ID of the owner of the object (plan or package). The
owner must have the privileges required to execute the SQL statements contained
in the object.

If ownership changes, all grants for privileges on the object that the previous owner
issued change to name the new owner as the grantor. The new owner has the
privileges BIND and EXECUTE on the object and grants them to the previous
owner.

You can bind or rebind only the objects for which the authorization ID has bind
privileges. If you do not specify an authorization ID, the process rebinds only the
objects for which the primary ID has bind privileges.

For remote BIND or REBIND PACKAGE only, the value of OWNER is subject to
translation when sent to the remote system.

Defaults:

Process
Default value
BIND PLAN
Primary ID
BIND PACKAGE
Primary ID
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default owner is the primary authorization ID of the agent that runs the bind
process.

Catalog record: Column OWNER of table SYSPACKAGE, column GRANTOR of


table SYSPACKAUTH, and column CREATOR of table SYSPLAN.

PACKAGE (location-name.collection-id.package-id.(version-id)) On: BIND and REBIND


(*) (REBIND PACKAGE only) PACKAGE

Determines what package or packages to bind or rebind.

You cannot use the BIND PACKAGE subcommand to:


v Bind a package with the same name as an existing trigger package

Chapter 2. Commands 67
BIND PLAN (DSN)
v Copy a trigger package

The following options identify the location, collection, package name, and version of
the package. You can identify a location and collection. For BIND, the DBRM
supplies the package ID and version ID if you use the option MEMBER, or those
IDs come from the option COPY. For REBIND, you must identify a package name,
and you can also supply a version ID.
location-name
The location of the DBMS where the package binds or rebinds and where the
description of the package resides. The location name must be defined in
catalog table SYSIBM.LOCATIONS. If that table does not exist or if the DBMS
is not in it, you receive an error message.
The default is the local DBMS.
collection-id or *
Specifies the collection to contain the package to bind, or that already contains
the package to rebind. There is no default.
For REBIND, you can use an asterisk (*) to rebind all local packages with the
specified package-id in all the collections for which you have bind privileges.
package-id or * (For REBIND only)
Specifies the name of the package to rebind, as listed in column NAME of
catalog table SYSPACKAGE. There is no default.
You can use an asterisk (*) to rebind all local packages in collection-id for which
you have bind privileges.
version-id or * (For REBIND only)
Specifies the version of the package to rebind, as listed in column VERSION of
catalog table SYSPACKAGE.
You can use an asterisk (*) to rebind all local versions of the specified
package-id in collection-id for which you have bind privileges.
Using simply () rebinds the version of the package that is identified by the
empty string.
If you omit version-id, the default depends on the how you specify package-id. If
you use * for package-id, then version-id defaults to *. If you explicitly provide a
value for package-id, then version-id defaults to the empty string version.
DBRMs created in releases of DB2 before Version 2 Release 3 use a version-id
of the empty string by default.
(*) (For REBIND only)
Rebinds all local DB2 packages for which the applicable authorization ID has
the BIND privilege. Specifying (*) is the same as specifying the package name
as (*.*.(*)) or (*.*). The applicable authorization ID is:
v The value of OWNER, if you use that option
v The primary authorization ID of the process running the bind, if you do not
use the option OWNER

Catalog record: Columns COLLID, NAME, and VERSION of table SYSPACKAGE.

For more information about:


v How to define a location name in SYSIBM.LOCATIONS, see Part 3 of DB2
Administration Guide.

68 Command Reference
BIND PLAN (DSN)
v Which packages are bound depending on how you specify collections, packages,
and versions on the REBIND PACKAGE command, see Part 4 of DB2
Application Programming and SQL Guide.

PATH (schema-name) On: BIND and REBIND PLAN and


(USER) PACKAGE
(schema-name,USER, ...)

Determines the SQL path that DB2 uses to resolve unqualified user-defined distinct
types, functions, and stored procedure names (in CALL statements).

For the PATH option, consider the following guidelines when you specify a
schema-name:
v The specified schema names are not folded to uppercase by DB2. This behavior
is different than that for schema names in SQL statements, which are folded to
uppercase before being stored in the catalog. If you do not specify these
nondelimited schema names in upper case, DB2 cannot find a match in the
catalog for those schema names.
v You can specify delimited identifiers in both mixed and uppercase characters.

The PATH keyword is mutually exclusive with the PATHDEFAULT keyword. Do not
specify both keywords in the same REBIND command.
(schema-name)
Identifies a schema.
DB2 does not validate that the specified schema actually exists at
precompile or at bind time.
You do not need to explicitly specify the SYSIBM, SYSFUN, and SYSPROC
schemas; DB2 implicitly assumes that these schemas are at the beginning
of the SQL path. DB2 adds these schemas in the order listed above. If you
do not specify the SYSIBM, SYSFUN, and SYSPROC schemas, they are
not included in the 254-byte length.
(schema-name, ...)
Identifies a list of schemas. The same schema name should not appear
more than once in the SQL path.
The number of schemas you can specify is limited by the length of the
resulting SQL path, which cannot exceed 254 bytes. To calculate the length
of the resulting SQL path:
1. Take the length of each schema.
2. Add 2 for delimiters around each schema-name in the list.
3. Add 1 for each comma after each schema. Do not add 1 for the last
schema.
USER Represents a maximum 8-byte schema-name. At bind time, DB2 includes
this 8-byte length in the total length of the list of schema names specified
for the PATH bind option. The maximum length for a list of schema names,
including comma separators, delimiters, and the 8-byte USER value, is 254
bytes. If you exceed this limit, DB2 generates an error message at bind
time.
At run time, DB2 substitutes the run-time value of the USER special
register, which contains the primary authorization ID of the run-time
process, for the schema-name in the position of USER in the PATH
schema-name list.

Chapter 2. Commands 69
BIND PLAN (DSN)
If you specify USER in a list of schema names, do not use delimiters
around the USER keyword.

For more information about schema names, ordinary identifiers, and delimited
identifiers, see Chapter 2 of DB2 SQL Reference.

Defaults:

Process
Default value
BIND PLAN
"SYSIBM", "SYSFUN", "SYSPROC", plan qualifier 2
BIND PACKAGE
2
"SYSIBM", "SYSFUN", "SYSPROC", package qualifier
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

PATHDEFAULT On: REBIND PLAN and


PACKAGE

Resets the PATH for a package or plan to "SYSIBM", "SYSFUN", "SYSPROC",


plan-qualifier/package-qualifier.

The PATHDEFAULT keyword is mutually exclusive with the PATH keyword. Do not
specify both keywords in the same REBIND command.

Defaults:

Process
Default value
REBIND PLAN
None
REBIND PACKAGE
None

PKLIST (location-name.collection-id.package-id, ...) PKLIST only On: BIND and REBIND


NOPKLIST PLAN

PKLIST determines what packages to include in the package list for the plan. The
order in which you list packages with partial identifiers determines the search order
at run time and can affect performance.

NOPKLIST is used with REBIND PLAN only. NOPKLIST determines that the plan
rebinds without a package list. If a package list already exists, then NOPKLIST
deletes it.
location-name or *
Names the location of the DBMS where the package resides, or defers that
choice until run time. Use either a particular location name or an asterisk (*), or
omit this part of the identifier. The default is the local DBMS.

2. Although this is the default value, it is not stored in the catalog. Instead, the catalog value is blank.

70 Command Reference
BIND PLAN (DSN)
If you use a particular location name, then that DBMS should be defined in
catalog table SYSIBM.LOCATIONS. If that table does not exist or if the
DBMS is not in it, you receive warning messages.
If you use an asterisk, at run time the location comes from the special
register CURRENT SERVER. DB2 checks privileges to use the SQL
statements in the package at that location.
collection-id or *
Names the collection that contains the package or defers that choice until run
time. Use either a particular collection ID or an asterisk (*). There is no default.
If you use an asterisk, then DB2 checks the privileges to use the SQL
statements embedded in the package run time. At that time also, DB2
determines the collection ID as follows:
v If the value in the special register CURRENT PACKAGESET is not blank,
then that value is the collection ID.
v If the value of CURRENT PACKAGESET is blank, then DB2 skips the entry
unless it is the last entry in the package list. If it is the last or only entry, an
error message occurs.
package-id or *
Names a particular package or specifies, by the asterisk, all packages in the
collection. Because you cannot specify a version-id for the packages included in
the package list, all versions are effectively included.

Defaults:

Process
Default value
BIND PLAN
None
BIND PACKAGE
N/A
REBIND PLAN
Existing value
REBIND PACKAGE
N/A
PKLIST has no default; if you do not use PKLIST, you must use MEMBER.

The default for NOPKLIST is to use the package list specified in the PKLIST option,
if any, during the current or previous bind or rebind.

Catalog record: Table SYSPACKLIST.

For more information about:


v How the order of search for packages affects performance, see Part 5 of DB2
Application Programming and SQL Guide.
v How to define a location name in SYSIBM.LOCATIONS, see Part 3 of DB2
Administration Guide.
v The TSO/E restriction that limits the maximum number of packages specified in
the PKLIST, see OS/390 TSO/E Programming Services.

PLAN (plan-name) On: BIND and REBIND PLAN


(*) (REBIND PLAN only)

Determines what plan or plans to bind or rebind.

Chapter 2. Commands 71
BIND PLAN (DSN)
(plan-name)
Specifies the name of the application plan.
For REBIND only, the value of column NAME in the catalog table SYSPLAN;
you can use a list of plan names.
The default is to perform all bind functions, including error diagnostics, without
producing an application plan and without inserting rows into PLAN_TABLE for
the option EXPLAIN.
(*) (For REBIND only)
Rebinds all plans for which the applicable authorization ID has the BIND
privilege. The applicable ID is:
v The value of OWNER, if you use that option
v The authorization ID of the process running the bind, if you do not use the
option OWNER

Catalog record: Column NAME of table SYSPLAN.

QUALIFIER (qualifier-name) On: BIND and REBIND PLAN and


PACKAGE

Determines the implicit qualifier for unqualified names of tables, views, indexes, and
aliases contained in the plan or package.
(qualifier-name)
Specifies the value of the implicit qualifier. This value is not subject to
translation when sent to a remote system for BIND or REBIND PACKAGE.

Defaults:

Process
Default value
BIND PLAN
Owner ID
BIND PACKAGE
Owner ID
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default is the owner’s authorization ID, whether you use the OWNER option or
its default.

Catalog record: Column QUALIFIER of tables SYSPACKAGE and SYSPLAN.

RELEASE (COMMIT) On: BIND and REBIND PLAN and


(DEALLOCATE) PACKAGE, REBIND TRIGGER
PACKAGE

Determines when to release resources that a program uses, either at each commit
point or when the program terminates.
(COMMIT)
Releases resources at each commit point.
(DEALLOCATE)
Releases resources only when the program terminates.

72 Command Reference
BIND PLAN (DSN)
The value has no effect on dynamic SQL statements, which always use
RELEASE(COMMIT), with one exception: When you use
RELEASE(DEALLOCATE) and KEEPDYNAMIC(YES), and your subsystem is
installed with YES for field CACHE DYNAMIC SQL on installation panel
DSNTIP4, the RELEASE(DEALLOCATE) option is honored for dynamic
SELECT, INSERT, UPDATE and DELETE statements.
Locks that are acquired for dynamic statements are held until one of the
following events occurs:
v The application process ends (deallocation).
v The application issues a PREPARE statement with the same statement
identifier. (Locks are released at the next commit point.)
v The statement is removed from the cache because it has not been used.
(Locks are released at the next commit point.)
v An object that the statement is dependent on is dropped or altered, or a
privilege that the statement needs is revoked. (Locks are released at the next
commit point.)

RELEASE(DEALLOCATE ) can increase the package or plan size, because


additional items become resident in the package or plan.

For more information about how the RELEASE option affects locking and
concurrency, see Part 5 (Volume 2) of DB2 Administration Guide or Part 5 of DB2
Application Programming and SQL Guide.

Defaults:

Process
Default value
BIND PLAN
COMMIT
BIND PACKAGE
Plan value
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default for a package that is bound at a remote server is COMMIT.

Catalog record: Column RELEASE of tables SYSPACKAGE and SYSPLAN.

NOREOPT(VARS) On: BIND and REBIND PLAN and


REOPT(VARS) PACKAGE

Specifies whether to have DB2 determine an access path at run time using values
for host variables, parameter markers, and special registers.
NOREOPT(VARS)
Does not determine an access path at run time.
REOPT(VARS)
Re-determines the access path at run time.

Usage notes:
v You cannot use both REOPT(VARS) and NOREOPT(VARS).
v You cannot use both REOPT(VARS) and KEEPDYNAMIC(YES).

Chapter 2. Commands 73
BIND PLAN (DSN)
v You cannot use both REOPT(VARS) and NODEFER(PREPARE).

Defaults:

Process
Default value
BIND PLAN
NOREOPT
BIND PACKAGE
NOREOPT
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value
The default for a package on a remote DB2 server is NOREOPT(VARS).

Catalog record: Column REOPT of table SYSPLAN and SYSPACKAGE.

SQLERROR (NOPACKAGE) On: BIND PACKAGE only


(CONTINUE)

Determines whether to create a package if SQL errors occur.


(NOPACKAGE)
Creates no package if an error occurs.
(CONTINUE)
Creates a package, even if errors occur when binding SQL statements. The
statements in error cannot execute. Any attempt to execute them at run time
causes errors.

Defaults:

Process
Default value
BIND PLAN
N/A
BIND PACKAGE
NOPACKAGE
REBIND PLAN
N/A
REBIND PACKAGE
N/A

Because you cannot use the option SQLERROR for REBIND PACKAGE, the value
for the previous package remains in effect when you rebind that package. If you
rebind a package that uses SQLERROR(CONTINUE), those SQL statements found
in error at bind time do not rebind.

Catalog record: Column SQLERROR of table SYSPACKAGE.

SQLRULES (DB2) On: BIND and REBIND PLAN


(STD)

Determines whether you can execute a type 2 CONNECT statement to an existing


SQL connection, according to DB2 rules. Alternatively, the statement causes an
error, according to the ANSI/ISO SQL standard of 1992. This option applies to any

74 Command Reference
BIND PLAN (DSN)
application process that uses the plan and executes type 2 CONNECT statements.
It has no effect on type 1 CONNECT statements or the rules for DB2 private
protocol access.
(DB2) No error occurs if CONNECT identifies an existing SQL connection. If X is
an existing SQL connection, CONNECT TO X makes X the current
connection. If X is already the current connection, CONNECT TO X has no
effect on the state of any connections.
(STD) An error occurs if CONNECT identifies an existing SQL connection.
Therefore, if X is a dormant SQL connection, you must use the SQL
statement SET CONNECTION to make X the current connection.

For local operations, the value of SQLRULES is used for the initial value of the SQL
special register CURRENT RULES.

Defaults:

Process
Default value
BIND PLAN
DB2
BIND PACKAGE
N/A
REBIND PLAN
Existing value
REBIND PACKAGE
N/A

Catalog record: Column SQLRULES of table SYSPLAN.

VALIDATE (RUN) On: BIND and REBIND PLAN and


(BIND) PACKAGE

Determines whether to recheck, at run time, errors of the type "OBJECT NOT
FOUND" and "NOT AUTHORIZED" found during bind or rebind. The option has no
effect if all objects and needed privileges exist.
(RUN) Indicated that if not all objects or privileges exist at bind time, the process
issues warning messages, but the bind succeeds. DB2 checks existence
and authorization again at run time for SQL statements that failed those
checks during bind. The checks use the authorization ID of the plan or
package owner.
(BIND)
Indicates that if not all objects or needed privileges exist at bind time, the
process issues error messages, and does not bind or rebind the plan or
package, except that:
For BIND PACKAGE only, if you use the option
SQLERROR(CONTINUE), the bind succeeds but the SQL statements in
it that have errors cannot execute.

Defaults:

Process
Default value
BIND PLAN
RUN

Chapter 2. Commands 75
BIND PLAN (DSN)
BIND PACKAGE
RUN
REBIND PLAN
Existing value
REBIND PACKAGE
Existing value

Catalog record: Column VALIDATE of tables SYSPACKAGE and SYSPLAN.

76 Command Reference
-CANCEL THREAD (DB2)

-CANCEL THREAD (DB2)


The DB2 command CANCEL THREAD cancels processing for specific local or
distributed threads.

Abbreviation: -CAN THD

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or a CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the privilege set of this process must include one of the
following:
v SYSOPR authority
v SYSCTRL authority
v SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

 CANCEL THREAD(token) 
DDF THREAD( luwid ) DUMP NOBACKOUT
token

Option descriptions
THREAD (token)
Identifies a specific thread, either distributed or not, whose processing you want
to cancel. DB2 assigns a token to each thread that is unique for that DB2
subsystem, but not necessarily unique across subsystems.
The token is a one- to six-digit decimal number. It can be determined from the
DB2 command DISPLAY THREAD or from an IFI READS call for IFCID 0147 or
0148. The token can also appear after the equal sign in DB2 messages that
display an LUWID.
DDF THREAD(luwid)
Identifies distributed threads for which you want to cancel processing. luwid is a
logical unit of work identifier (LUWID), consisting of:
v A fully qualified LU network name, which consists of:
– A one- to eight-character network ID
– A period
– A one- to eight-character network LU name
v An LUW instance number, which consists of 12 hexadecimal characters that
uniquely identify the unit of work

Chapter 2. Commands 77
-CANCEL THREAD (DB2)
If you enter three fields separated by periods, DB2 assumes that you are
entering an LUWID.

You might have two or more distributed threads with the same LUWID. All
distributed threads with the same LUWID are canceled.

The LUWID can be determined from the DB2 DISPLAY THREAD command and
other DB2 messages.
DUMP
Provides a dump for diagnostic purposes.
| NOBACKOUT
| Specifies that DB2 will not attempt to back out the data during transaction
| rollback processing. Cancelling the thread with NOBACKOUT leaves objects in
| an inconsistent state. Do not issue this command with NOBACKOUT unless
| you have a plan to resolve the data inconsistency.
| Multiple NOBACKOUT requests are allowed. However, if the thread is active
| and the request is accepted, subsequent requests are ignored. You can choose
| to issue a subsequent request if a request fails (as indicated by message
| DSNI032I). Objects that the thread modifies are recovered (backed out). If back
| out processing fails, the objects are marked REFRESH PENDING (REFP) and
| either RECOVER PEINDING (RECP) or REBUILD PENDING (RBDP or
| PSRBD) in the database exception table. Resolve the REFP status of the object
| by running the RECOVER utility to recover the object to a prior point in time or
| by running LOAD REPLACE on the object.

Usage notes
Canceling distributed threads: Canceling a distributed thread can cause the
thread to enter the indoubt state. Message DSNL450I is issued if the CANCEL
command causes the DDF thread to be converted from active to indoubt. DB2
releases the resources that the thread holds when the indoubt state is resolved by
automatic indoubt resolution with the coordinator, or by resolution with the
command RECOVER INDOUBT.

If a thread that is specified in the command is part of a global transaction, the


command is executed against all threads in the global transaction. See Chapter 5 of
the DB2 Administration Guide, for an explanation of global transactions.

The CANCEL command schedules a thread to be terminated in DB2. To terminate,


the thread must be processing within DB2. If the thread does not terminate, it could
be:
v Processing outside of DB2, possibly in the application. If that is the case, the
thread does not terminate until the application makes a request to DB2. Use the
MVS Cancel command to terminate the application immediately.
v Hung up in VTAM. Use VTAM commands to cause VTAM to return processing to
DB2, which will terminate the thread. See topic below for details.

| Canceling local threads: The CANCEL command schedules a thread to


| termintate. Threads that are not in DB2 terminate immediately.

Using VTAM commands to cancel SNA distributed threads: If the CANCEL


command does not terminate a distributed thread, it is possible that it is hung up in
VTAM. Use the VTAM VARY NET,TERM command to cancel the thread’s VTAM

78 Command Reference
-CANCEL THREAD (DB2)
sessions. To do this, you need to know the VTAM session IDs (SIDs) that
correspond to the thread. Take the following steps:
1. Issue the DB2 command DISPLAY THREAD(*) LUWID(nnnn) DETAIL. (The
value of nnnn is the token or LUWID provided by CANCEL DDF THREAD.)
This gives you the VTAM session IDs that must be canceled. Sessions are
identified by the column header SESSID as shown in the following DISPLAY
THREAD output:
-DIS THD(*) LUWID(123) DETAIL
DSNV401I - DISPLAY THREAD REPORT FOLLOWS:
DSNV402I - ACTIVE THREADS:
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH TR * 5 BKH2C SYSADM BKH2 000D 123
V444-DB2NET.LUND0.9F6D9F459E92=123 ACCESSING DATA AT
V446-SAN JOSE:LUND1
V447--LOCATION SESSID A ST TIME
V448--SAN JOSE 00D3590EA1E89701 S1 9332108460302
V448--SAN JOSE 00D3590EA1E89822 V R1 9332108460431
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

The V indicates the thread is processing in VTAM.


2. Record positions 3 through 16 of SESSID for the threads to be canceled. (In the
DISPLAY THREAD output above, the values are D3590EA1E89701 and
D3590EA1E89822.)
3. Issue the VTAM command DISPLAY NET to display the VTAM session IDs. The
ones you want to cancel match the SESSIDs in positions 3 through 16 and the
corresponding session IDs are in bold. The following is an output example of
this command:

D NET,ID=LUND0,SCOPE=ACT

IST097I DISPLAY ACCEPTED


IST075I NAME = LUND0, TYPE = APPL
IST486I STATUS= ACTIV, DESIRED STATE= ACTIV
IST171I ACTIVE SESSIONS = 0000000005, SESSION REQUESTS = 0000000000
IST206I SESSIONS:
IST634I NAME STATUS SID SEND RECV VR TP NETID
IST635I LUND1 ACTIV-S D24B171032B76E65 0051 0043 0 0 NET2
IST635I LUND1 ACTIV-S D24B171032B32545 0051 0043 0 0 NET2
IST635I LUND1 ACTIV-R D2D3590EA1E89701 0022 0031 0 0 NET2
IST635I LUND1 ACTIV-R D2D3590EA1E89802 0022 0031 0 0 NET2
IST635I LUND1 ACTIV-R D2D3590EA1E89822 0022 0031 0 0 NET2
IST314I END

4. Issue the VTAM command VARY NET,TERM for each of the VTAM SIDs
associated with the DB2 thread. In this case, it might be necessary to cancel
only the session ID that DISPLAY THREAD shows to be processing in VTAM
(D2D3590EA1E89822).

For more information about VTAM commands, see VTAM for MVS/ESA Operation.

| Using TCP/IP Commands to Cancel TCP/IP Distributed Threads: If the CANCEL


| command does not terminate a distributed thread, it is possible that it is hung up in
| TCP/IP. Use the TCP/IP DROP command to cancel the thread’s connection ID. To
| do this, you need to first determine the TCP/IP connection ID that corresponds to
| the thread. Depending on whether the thread is a DB2 requester or server thread,
| take the following steps:
| v Terminating TCP/IP connection for a requester thread:

Chapter 2. Commands 79
-CANCEL THREAD (DB2)
| 1. Issue the DB2 command DISPLAY THREAD(*) LUWID(nnnn) DETAIL. (The
| value of nnnn is the token or LUWID provided by CANCEL THREAD.)
| Find the IP address and local port for the connection to the partner, as shown
| in the following DISPLAY THREAD output:
| #display thread(*) detail
|
| DSNV401I # DISPLAY THREAD REPORT FOLLOWS -
| DSNV402I # ACTIVE THREADS -
| NAME ST A REQ ID AUTHID PLAN ASID TOKEN
| TEST0001 TR 4 CTHDCORID001 SYSADM DONSQL1 0027 19
| V444-USIBMSY.SYEC715B.B4FA989AF056=19 ACCESSING DATA AT
| V446-STL714A:9.112.114.102:446
| V447--LOCATION SESSID A ST TIME
| V448--STL714A 1028:446 S2 0032608521413
| DISPLAY ACTIVE REPORT COMPLETE
| DSN9022I # DSNVDT '-DIS THD' NORMAL COMPLETION

| In this case, the partner’s IP address and port is 9.112.114.102 446, and the
| local port is 1028.
| 2. Determine the associated TCP/IP connection ID:
| d tcpip,,netstat,conn,ipaddr=9.112.114.102
|
| EZZ2500I NETSTAT CS V2R10 TCPIP 534
| USER ID CONN LOCAL SOCKET FOREIGN SOCKET STATE
| V71BDIST 0000049D 9.112.114.103..1028 9.112.114.102..446 ESTBLSH
| 1 OF 1 RECORDS DISPLAYED
| 3. Terminate the connection:
| v tcpip,,drop,conn=0000049d
|
| EZZ0060I PROCESSING COMMAND: VARY TCPIP,,DROP,
| CONN=0000049D
| EZZ0053I COMMAND VARY DROP COMPLETED SUCCESSFULLY
| v Terminating TCP/IP connection for a server thread::
| 1. Issue the DB2 command DISPLAY THREAD(*) LUWID(nnnn) DETAIL. (The
| value of nnnn is the token or LUWID provided by CANCEL THREAD.)
| Find the IP address and local port for the connection to the partner, as shown
| in the following DISPLAY THREAD output:
| !display thread(*) detail
|
| DSNV401I ! DISPLAY THREAD REPORT FOLLOWS -
| DSNV402I ! ACTIVE THREADS -
| NAME ST A REQ ID AUTHID PLAN ASID TOKEN
| TEST0001 RA * 2 CTHDCORID001 SYSADM DONSQL1 002D 11
| V445-USIBMSY.SYEC715B.B4FA9BB94FA7=11 ACCESSING DATA FOR
| 9.112.114.103
| V447--LOCATION SESSID A ST TIME
| V448--9.112.114.103 446:1029 W R2 0032609061159
| DISPLAY ACTIVE REPORT COMPLETE
| DSN9022I ! DSNVDT '-DIS THD' NORMAL COMPLETION

| In this case, the partner’s IP address is 9.112.114.103 and the local port is
| 1029.
| 2. Determine the associated TCP/IP connection ID:
| d tcpip,,netstat,conn,ipaddr=9.112.114.103
|
| EZZ2500I NETSTAT CS V2R8 TCPIP 126
| USER ID CONN LOCAL SOCKET FOREIGN SOCKET STATE
| V61ADIST 0000048E 9.112.114.102..446 9.112.114.103..1029 ESTABLS
| 1 OF 1 RECORDS DISPLAYED

80 Command Reference
-CANCEL THREAD (DB2)
| Find the entry where the foreign socket shows the partner’s IP address and
| port (9.112.114.103 1029) and note the CONN.
| 3. Terminate the connection:
| v tcpip,,drop,conn=0000048e
|
| EZZ0060I PROCESSING COMMAND: VARY TCPIP,,DROP,
| CONN=0000048E
| EZZ0053I COMMAND VARY DROP COMPLETED SUCCESSFULLY

| Examples
Example 1: To cancel a non-distributed thread whose token you found through
-DISPLAY THREAD and to produce a diagnostic dump, issue:
-CANCEL THREAD (123) DUMP

Example 2: To cancel a distributed thread whose LUWID you found through


-DISPLAY THREAD, issue:
-CANCEL DDF THREAD (LUDALLAS.DB2SQL1.3042512B6425)

Assume that the output from -DISPLAY THREAD shows that the thread-ID and
token associated with this LUWID is 45162. You can also cancel this thread by
issuing:
-CANCEL DDF THREAD (45162)

or
-CANCEL THREAD (45162)

As in the first example, specifying DUMP with any of the commands shown in this
example causes a diagnostic dump to be produced.

Chapter 2. Commands 81
/CHANGE (IMS)

/CHANGE (IMS)
The IMS command /CHANGE resets an indoubt unit of recovery as identified by the
OASN keyword of the /DISPLAY command. That command deletes the item from
the standpoint of IMS, but it does not communicate to DB2.

Abbreviation: /CHA

Environment
This command can be issued only from an IMS terminal.

Data sharing scope: Member

Authorization
This command requires an appropriate level of IMS authority, as described in IMS
Administration Guide: System.

Syntax

 /CHANGE SUBSYS subsystem-name RESET 


SUBSYS ALL
SUBSYS subsystem-name OASN schedule-number

Option descriptions
SUBSYS
Deletes IMS recovery elements from one or more subsystems.
One of the following subparameters must be coded:
subsystem-name, ...
Specifies one or more subsystems from which recovery elements will be
deleted.
ALL
Deletes IMS recovery elements from all subsystems.
subsystem-name OASN schedule-number, ...
Deletes one or more origin application schedule numbers from one
subsystem, specified by subsystem-name.
schedule-number can be a list of up to 32768 origin application schedule
numbers. The numbers are displayed using the OASN parameter of the
/DISPLAY command.
RESET
Deletes the indoubt recovery unit. The recovery unit represents an incomplete
unit of work assigned to an external subsystem as the result of an application
request.

Usage note
The preceding description of the /CHANGE command is a partial description only.
For a complete description, see IMS Command Reference.

82 Command Reference
/CHANGE (IMS)
Examples
Example 1: Reset all indoubt recovery units for subsystem DB2.
/CHA SUBSYS DB2 RESET

Example 2: Reset all indoubt recovery units for all subsystems.


/CHA SUBSYS ALL RESET

Example 3: Reset indoubt recovery units identified by OASN numbers 99, 685, and
2920 for subsystem DB2.
/CHA SUBSYS DB2 OASN 99 685 2920 RESET

Chapter 2. Commands 83
DCLGEN (DSN)

DCLGEN (DECLARATIONS GENERATOR) (DSN)


The declarations generator (DCLGEN) produces an SQL DECLARE TABLE
statement and a COBOL, PL/I, or C data declaration for a table or view named in
the catalog.

For further information regarding the DCLGEN command and uses for its output,
see Part 2 of DB2 Application Programming and SQL Guide.

Environment
The declarations generator is executed by the DSN subcommand DCLGEN. That
subcommand can be issued from a DSN session, running in either foreground or
background mode, or it can be issued through DB2I.

Data sharing scope: Group

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v SELECT privilege on the table or view
v Ownership of the table or view
v DBADM authority on the database containing the table
v SYSADM authority
v SYSCTRL authority (catalog tables only)

Syntax

 DCLGEN TABLE( table-name ) 


view-name OWNER(owner-name) AT(location-name)

 LIBRARY(library name ) 
(member-name) /password ADD
ACTION( REPLACE )

 
COBOL NAMES(prefix) STRUCTURE(structure-name) APOST
LANGUAGE( PLI ) QUOTE
C
COB2
IBMCOB
CPP

 
NO DBCSSYMBOL( G ) YES NO
LABEL YES N DBCSDELIM( NO ) COLSUFFIX( YES )

 
NO
INDVAR( YES )

84 Command Reference
DCLGEN (DSN)
Option descriptions
TABLE
Specifies what table or view for which to generate a declaration. table-name or
view-name is the qualified or unqualified name of the table or view.
The name must follow the following rules:
v If the name is a single-byte or mixed string and contains special characters
other than underscores (_), it must be enclosed between apostrophes ('). If
the language is COBOL, single-byte underscores in the name are translated
into hyphens (-) by DCLGEN. Double-byte character set (DBCS) names need
not be enclosed in apostrophes.
v If the name contains single-byte apostrophes, each one must be doubled ('').
(Some host languages do not permit apostrophes in variable names.)

A table or view name that contains a period and is not enclosed by apostrophes
is a qualified table name. The characters to the left of the period constitute the
table owner, and those to the right of the period constitute the table name. Any
table name enclosed in apostrophes is an unqualified table name. To
understand how DCLGEN determines the table name qualifier, see the
description of the OWNER option, which follows.
OWNER(owner-name)
Specifies a qualifier for the table name. owner-name is the qualifier for the table
name.
If you specify a qualified table name for the TABLE(table-name) option, and you
also specify OWNER(owner-name), the qualifier portion of table-name
supersedes owner-name as the table name qualifier. If you specify an
unqualified table name for the TABLE(table-name) option, and you do not
specify OWNER(owner-name), the SQL authorization ID is the table name
qualifier.
DCLGEN supports the use of underscore (_) as a valid character in the
owner-name keyword parameter.
The following table illustrates the decision process for determining the DCLGEN
table name qualifier.

Table name OWNER(owner-name) OWNER(owner-name)


specified not specified
TABLE(table-name) table-name qualifier table-name qualifier
qualified
TABLE(table-name) owner-name SQL authorization ID
unqualified

AT(location-name)
Identifies the location of the table or view name specified in TABLE
(table-name). location-name, which can consist of 1 to 16 characters, uniquely
identifies an instance of a table or view in a network.
If you specify AT, location-name is used as the prefix for the table name, and
table-name or table-view must be a qualified name.
DCLGEN supports the use of underscore (_) as a valid character in the
location-name keyword parameter.

Chapter 2. Commands 85
DCLGEN (DSN)
LIBRARY(library-name(member-name)/password)
Specifies the data set into which the declarations go. This data set must already
exist and be accessible to the declarations generator. It can be either sequential
or partitioned.
If the library name is not enclosed within apostrophes, DCLGEN constructs the
following full data set name:
user-prefix.library-name.language.(member-name)

where:
user-prefix
The user prefix of the primary authorization ID of the transaction.
language
The value of the LANGUAGE option: COBOL, COB2, PLI, or C;
(member-name)
Optional; if not used, the output goes to a sequential data set.

password is optional.
ACTION
Indicates whether to add or replace the data set.
(ADD)
Adds the data set as a new member, if it does not already exist.
The default is ACTION(ADD).
(REPLACE)
Replaces an existing member or data set with the new one. If the output is
to a partitioned data set, and no member exists with the given name, one is
added.
LANGUAGE
Specifies the language of the generated declaration.
Possible languages are:
v (COBOL), for OS/VS COBOL
v (COB2), for other COBOL languages
v (PLI), for PL/I
v (C), for C/370
v (IBMCOB), for IBM COBOL
v (CPP), for C⁺⁺
NAMES(prefix)
Allows field names to be formed in the declaration.
Avoid possible name conflicts between DCLGEN output and the source
program. If a conflict occurs, use NAMES or STRUCTURE, or manually edit the
generated declaration or source program.
prefix can contain double-byte characters.
The field names consist of prefix concatenated with a number from one to three
digits in length. prefix can have up to 28 characters. If prefix is a single-byte or
mixed string and the first character is not alphabetic, it must be enclosed in
apostrophes. For example, if prefix is ABCDE, the field names will be ABCDE1,
ABCDE2, and so on, up to a maximum of ABCDE999. Special characters can
be used, but use caution to avoid possible name conflicts.

86 Command Reference
DCLGEN (DSN)
For COBOL and PL/I, if the prefix is a DBCS string, the field name will be the
DBCS prefix concatenated with the DBCS representation of the number. For
example, if prefix is <D1D2D3> (where “<” and “>” represent shift-out and
shift-in characters, respectively, and D1D2D3 represent double-byte characters),
generated field names will be <D1D2D3.1>, <D1D2D3.2>, and so on. The
period (.) represents X’42’.
The column names in the table are taken as default names for the fields in the
output.
STRUCTURE(structure-name)
Specifies the generated data structure.
structure-name can have up to 31 characters. If structure-name is a single-byte
or mixed string and the first character is not alphabetic, it must be enclosed in
apostrophes. Special characters can be used, but use caution to avoid possible
name conflicts.
structure-name can contain double-byte characters.
For SQL output, the name is the same as the table or view name. If the host
language is C, the default structure name is the prefix DCL concatenated with
the table name. If the host language is COBOL or PL/I and the table name is a
single-byte or mixed string, the default structure name is also the prefix DCL
concatenated with the table name. If the host language is COBOL or PL/I and
the table name is a DBCS string, the default structure name is the prefix
<.D.C.L> concatenated with the table or view name. “<” and “>” represent
shift-out and shift-in characters, respectively. You must guard against possible
conflicts with names in the source program. DCLGEN allows the specified
structure name to be the same as the table or view name, but will issue a
warning message.
APOST or QUOTE
Specifies the string delimiter character used in the host language. This option is
effective only for COBOL programs.
APOST specifies the apostrophe (') as the host language string delimiter; the
SQL delimiter is the quotation mark (").
QUOTE specifies the quotation mark (") as the host language delimiter; the
SQL delimiter is the apostrophe (').
If neither APOST nor QUOTE is specified, the default is either APOST or
QUOTE for COBOL, depending on what was specified on DB2 installation panel
DSNTIPF.
The string delimiter delimits strings in host language statements. The SQL
escape character delimits table and column names in the SQL DECLARE
TABLE statement produced by DCLGEN. It is possible, by a choice made
during DB2 installation, to make both delimiters the quotation mark or both the
apostrophe.
LABEL
Indicates whether to include column labels in the output as comments. (Column
labels can be assigned by the LABEL ON statement.)
NO
Omits the column labels.
YES
Includes the column labels.

Chapter 2. Commands 87
DCLGEN (DSN)
DBCSSYMBOL
Specifies the symbol used to denote a graphic data type in a COBOL PICTURE
clause.
(G)
Graphic data is denoted using G.
(N)
Graphic data is denoted using N.
DBCSDELIM
Specifies whether the DBCS table and column names in the generated
DECLARE table statement will be delimited.
(YES)
DBCS table and column names will be delimited in the DCLGEN table
declaration.
(NO)
DBCS table and column names will not be delimited in the DCLGEN table
declaration.
COLSUFFIX
Determines whether to form field names by attaching the column name to the
prefix given by the NAMES option.
(NO)
The column name is not used as a suffix, and field names are controlled by
the option NAMES, as in Version 3.
(YES)
If NAMES is specified, DCLGEN forms field names by adding column
names as a suffix to the value of NAMES. For example, if the prefix given
by NAMES is “NEW” and the column name is EMPNO, then the field name
is “NEWEMPNO”.
If NAMES is not specified, DCLGEN issues a warning message and uses
the column names as the field names, as in Version 3.
INDVAR
Determines whether to create an indicator variable array for the host variable
structure.
(NO)
DCLGEN does not create an indicator variable array.
(YES)
DCLGEN creates an indicator array for the host variable structure. The
array name is the table name with a prefix of “I” (or DBCS letter “<I>” if the
table name is double-byte).

Usage notes
Parsing of the DCLGEN command conforms to standard TSO parsing conventions.
For information about TSO command parsing, see the OS/390 TSO/E Programming
Services.

The DECLARE statement: The DECLARE statement generated by DCLGEN will


define all columns created with a data type of VARCHAR or LONG VARCHAR as
VARCHAR. Columns created with a data type of VARGRAPHIC or LONG
VARGRAPHIC will be defined as VARGRAPHIC.

88 Command Reference
DCLGEN (DSN)
Comments: The output for all host languages includes comments. The leading
comment block echoes the DCLGEN subcommand that requested the declarations.
The trailing comment block indicates the number of variables declared.

Using the output: To include the DCLGEN output in an application program, use
the SQL INCLUDE statement. The same member name specified in the DCLGEN
LIBRARY parameter is specified on the INCLUDE statement.

Prompts: Online TSO will prompt for missing or incorrectly specified options.

Editing the output: It is expected that the output of DCLGEN will not meet every
need. You can freely edit the output before including it in a program. For example,
you might want to change a variable name, or include SQL escape characters.

You can edit the output to add WITH DEFAULT to NOT NULL for columns that do
not allow null values. If you edit the output, you must provide a default value.

If your column names contain embedded blanks, they will also be reflected in the
host variable declarations, and you will have to remove, or translate, any blank
characters to some other value.

C: DCLGEN support of the C language is unique in the following ways:


v DCLGEN does not fold the STRUCTURE, NAMES, or TABLE values to
uppercase.
v For any DB2 column that has the data type CHAR(n), where n > 1, DCLGEN
generates the corresponding host variable as CHAR(n + 1) to avoid the DB2
warning. For n = 1, the corresponding host variable is CHAR.

COBOL and binary integers: DB2 uses the full size of binary integers. It can place
larger values than allowed in the specified number of digits in the COBOL
declaration, which can result in truncated values.

For small integers that can exceed 9999, use S9(5). For large integers that can
exceed 999,999,999, use S9(10) COMP-3 to obtain the decimal data type. If
COBOL is used for integers that exceed the COBOL PICTURE, specify the column
as decimal to ensure that the data types match and perform well.

COBOL and the underscore character: Because COBOL does not allow the use
of the underscore character, DCLGEN translates any underscore characters in the
table’s column names into hyphens (-) for use in the generated structure.

COBOL and DBCS: OS/VS COBOL does not support DBCS, but later versions of
COBOL (VS COBOL II and COBOL/370) do. Although DB2 accepts values outside
of the range from X’41’ to X’FE’, in COBOL data definition statements, both bytes of
each double-byte character in data names must be within this range. Data names
must also contain at least one DBCS character that does not have X’42’ as its first
byte.

Data declarations for arrays of indicator variables: If DCLGEN creates an array


of indicator variables, data declarations have the following form:
Language
Data declaration
C short int Itable-name[n];
COBOL
01 Itable-name PIC S9(4) USAGE COMP OCCURS n TIMES.

Chapter 2. Commands 89
DCLGEN (DSN)
PL/I DCL Itable-name(n) BIN FIXED (15);

where n is the number of columns in the table.

Examples
Example 1: This example shows the use of the DCLGEN. The statement
DCLGEN TABLE(VEMPL) -
LIBRARY('prefix.SRCLIB.DATA(DSN8MPEM)') -
LANGUAGE(PLI) -
APOST

produces the following statements in prefix.SRCLIB.DATA(DSN8MPEM):

/*********************************************************************/
/* DCLGEN TABLE(VEMPL) - */
/* LIBRARY('prefix.SRCLIB.DATA(DSN8MPEM)') - */
/* LANGUAGE(PLI) - */
/* APOST */
/* ... IS THE DCLGEN COMMAND THAT MADE THE FOLLOWING STATEMENTS */
/*********************************************************************/
EXEC SQL DECLARE VEMPL TABLE
( EMPNO CHAR(6) NOT NULL,
FIRSTNME VARCHAR(12) NOT NULL,
MIDINIT CHAR(1) NOT NULL,
LASTNAME VARCHAR(15) NOT NULL,
WORKDEPT CHAR(3) NOT NULL
) ;
/*********************************************************************/
/* PLI DECLARATION FOR TABLE VEMPL */
/*********************************************************************/
DCL 1 DCLVEMPL,
5 EMPNO CHAR(6),
5 FIRSTNME CHAR(12) VAR,
5 MIDINIT CHAR(1),
5 LASTNAME CHAR(15) VAR,
5 WORKDEPT CHAR(3);
/*********************************************************************/
/* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 5 */
/*********************************************************************/

Example 2: This example shows the use of NAMES and STRUCTURE. The
statement
DCLGEN TABLE(VEMPL) -
LIBRARY('prefix.SRCLIB.DATA(DSN8MPEM)') -
LANGUAGE(PLI) -
NAMES(FIELD) -
STRUCTURE(EMPRECORD) -
APOST

produces the following statements in prefix.SRCLIB.DATA(DSN8MPEM):

90 Command Reference
DCLGEN (DSN)
/*********************************************************************/
/* DCLGEN TABLE(VEMPL) - */
/* LIBRARY('prefix.SRCLIB.DATA(DSN8MPEM)') - */
/* LANGUAGE(PLI) - */
/* NAMES(FIELD) - */
/* STRUCTURE(EMPRECORD) - */
/* APOST */
/* ... IS THE DCLGEN COMMAND THAT MADE THE FOLLOWING STATEMENTS */
/*********************************************************************/
EXEC SQL DECLARE VEMPL TABLE
( EMPNO CHAR(6) NOT NULL,
FIRSTNME VARCHAR(12) NOT NULL,
MIDINIT CHAR(1) NOT NULL,
LASTNAME VARCHAR(15) NOT NULL,
WORKDEPT CHAR(3) NOT NULL
) ;
/*********************************************************************/
/* PLI DECLARATION FOR TABLE VEMPL */
/*********************************************************************/
DCL 1 EMPRECORD,
5 FIELD1 CHAR(6),
5 FIELD2 CHAR(12) VAR,
5 FIELD3 CHAR(1),
5 FIELD4 CHAR(15) VAR,
5 FIELD5 CHAR(3);
/*********************************************************************/
/* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 5 */
/*********************************************************************/

Chapter 2. Commands 91
/DISPLAY (IMS)

/DISPLAY (IMS)
The IMS command /DISPLAY displays the status of the connection between IMS
and an external subsystem (as well as all application programs communicating with
the external subsystem), or the outstanding recovery units associated with the
subsystem.

Environment
This command can be issued only from an IMS terminal.

Data sharing scope: Member

Authorization
This command requires an appropriate level of IMS authority, as described in the
IMS Administration Guide: System.

Syntax

 /DISPLAY SUBSYS  subsystem-name 


SUBSYS ALL
,

OASNSUBSYS  subsystem-name
OASN SUBSYS ALL

Option descriptions
One of the following options is required:
SUBSYS
Identifies the subsystems to display information about.
subsystem-name, ...
Specifies one or more subsystems. See “Output” on page 93 for a
description of possible subsystem status.
ALL
Displays information about all subsystems.
OASN SUBSYS
Displays the outstanding recovery units (origin application schedule numbers, or
OASN) associated with the external subsystems. The OASN is assigned by IMS
when it schedules an application into a dependent region. That, coupled with
the IMS ID, becomes the recovery token for units of work distributed to other
subsystems.
subsystem-name, ...
Specifies one or more subsystems to display information about.
ALL
Displays the outstanding recovery units associated with all external
subsystems.

92 Command Reference
/DISPLAY (IMS)
Output
The command recognition character (CRC) is displayed for each external
subsystem. Subsystem status is one of the following:
CONNECTED
An IMS control region or dependent region has successfully connected to
the external subsystem. At this point, the two systems can begin a normal
dialog.
NOT CONNECTED
The external subsystem is in an idle state. That is, either it has not been
the object of the /START SUBSYS command, or the external subsystem
initialization exit routine indicated not to connect.
CONNECT IN PROGRESS
The connection process for the specified subsystem is in progress.
STOPPED
The specified subsystem has been stopped with the /STOP SUBSYS
command. All region connections to the specified external subsystem have
been terminated.
STOP IN PROGRESS
The /STOP SUBSYS command is in progress. Before it completes
successfully, all active connections to the specified subsystem from all IMS
regions must be quiesced.
INVALID SUBSYSTEM NAME = subsystem-name
The indicated subsystem name has not been defined to the IMS subsystem
PROCLIB member. Add the subsystem definition to the subsystem member
and issue the /START SUBSYS command.
SUBSYSTEM subsystem-name NOT DEFINED BUT RECOVERY OUTSTANDING
The indicated subsystem name has not been defined to IMS in the external
subsystem PROCLIB member, but IMS still has outstanding recovery
elements from a previous execution when the name was known. To resolve
the recovery element problem, either add the indicated subsystem definition
to the external subsystem PROCLIB member and then issue the /START
SUBSYS command, or issue the /DISPLAY OASN SUBSYS command to
determine the identification of the OASNs and then manually resolve the
recovery elements by issuing the /CHANGE SUBSYS RESET command.
TERM IN PROGRESS
An internal termination of the subsystem is underway. This type of
termination was instigated by IMS abnormal condition processing, an
external subsystem exit, or the external subsystem.

A thread between an IMS dependent region and an external subsystem is created


when an application program in the region establishes a connection to the external
subsystem. The status of threads to an external subsystem is listed under the
status of the subsystem. The absence of a list of threads under a connected
subsystem indicates that no threads to the specified subsystem have been
established.

Thread status can be:


CONNECTED(CONN)
An IMS control region or dependent region has successfully connected to
the external subsystem.

Chapter 2. Commands 93
/DISPLAY (IMS)
ACTIVE
An IMS application program has established communication with an
external subsystem.

The absence of a PSB name for a thread indicates that a connection to the external
subsystem exists, but an application program is not currently occupying the region.
The presence or absence of an LTERM name indicates whether a region is
message-driven.

The preceding description of the /DISPLAY command is a partial description only.


For a complete description, see IMS Command Reference.

Example
Display the status of connections between IMS and all subsystems.
/DISPLAY SUBSYSTEM ALL
SUBSYS CRC REGID PROGRAM LTERM STATUS
SSTR ? CONN
1 DDLTLM17 PTERM01 CONN,ACTIVE
2 DDLTLM06 PTERM02 CONN
*85202/065933*

94 Command Reference
-DISPLAY ARCHIVE (DB2)

-DISPLAY ARCHIVE (DB2)


The DB2 command DISPLAY ARCHIVE displays input archive log information.

Abbreviation: -DIS ARC

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v ARCHIVE or DISPLAY system privilege
v SYSOPR, SYSCTRL, or SYSADM authority
DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

 DISPLAY ARCHIVE 

Usage note
Data sharing members: Although the command ARCHIVE LOG SCOPE(GROUP)
or ARCHIVE LOG MODE(QUIESCE) initiates archive processing for all members of
a data sharing group, the command DISPLAY ARCHIVE shows information only for
the member for which it is issued. To display input archive log information for all
members of a data sharing group, enter the command to each member.

Example
Display tape unit information about input archive logs.
-DISPLAY ARCHIVE
DSNJ322I - DISPLAY ARCHIVE REPORT FOLLOWS-
COUNT TIME
(TAPE UNITS) (MIN,SEC)
DSNZPARM 2 0,00
CURRENT 2 5,30
===============================
ADDR STATUS CORR-ID VOLSER DATASET_NAME
290 AVAIL ***** TAPE1 DSNCAT.ARCHLOG1.A0000033
294 PREM ***** TAPE3 DSNCAT.ARCHLOG1.A0000035
293 BUSY RECOVER2 TAPE2 DSNCAT.ARCHLOG1.A0000034
END OF DISPLAY ARCHIVE REPORT.
DSN9022I - DSNJC001 '-DISPLAY ARCHIVE' NORMAL COMPLETION

This example report shows:


v The subsystem parameter values for MAX RTU (COUNT) and DEALLC PERIOD
TIME as recorded in the DSNZPxxx load module

Chapter 2. Commands 95
-DISPLAY ARCHIVE (DB2)
v Current specifications for the COUNT and TIME parameters
v Availability status of allocated dedicated tape units
v Volume and data set names associated with all busy tape units

96 Command Reference
-DISPLAY BUFFERPOOL (DB2)

-DISPLAY BUFFERPOOL (DB2)


The DB2 command DISPLAY BUFFERPOOL displays the current status for one or
more active or inactive buffer pools.

Abbreviation: -DIS BPOOL

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v DISPLAY system privilege
v SYSOPR, SYSCTRL, or SYSADM authority
DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

( ACTIVE )
 DISPLAY BUFFERPOOL 
( * ) INTERVAL ACTIVE
, DETAIL( ) LIST( )
* *
(  bpname )

ACTIVE
 ( ) 
LSTATS * *
,

DBNAME (  database-name )
name1:name2
name*
 
* GBPDEP( YES ) CASTOWNR( YES )
, NO NO

SPACENAM(  space-name )
name1:name2
name*

Option descriptions
(ACTIVE)
Displays the current buffer pool status for all active buffer pools.
(*) Displays the current buffer pool status for all active or inactive buffer pools.

Chapter 2. Commands 97
-DISPLAY BUFFERPOOL (DB2)
(bpname)
Names the buffer pool for which current status is to be displayed.
v 4-KB page buffer pools are named BP0, BP1, ..., BP49.
v 8-KB page buffer pools are named BP8K0, BP8K1, ..., BP8K9.
v 16-KB page buffer pools are named BP16K0, BP16K1, ..., BP16K9.
v 32-KB page buffer pools are named BP32K, BP32K1, ..., BP32K9.
DETAIL
Produces a detail report for one or more buffer pools. If DETAIL is not specified,
a summary report is produced.
(INTERVAL)
Requests statistics accumulated since the last incremental display, or since
the buffer pool was first activated if there was no previous incremental
display.
(*) Requests statistics accumulated since the buffer pool was first activated.
LIST
Lists the open index spaces and table spaces associated with the buffer pools
included in the report. Basic information is provided for no-data-sharing systems
while more detail is provided if data-sharing is active.
(ACTIVE)
Restricts the list of open index spaces and table spaces to those that are
currently in use.
(*) Requests a list of all open index spaces and table spaces, whether
currently in use or not.
LSTATS
Lists data set statistics for the open index spaces and table spaces associated
with the buffer pools included in the report. The statistics displayed are
incremental since the last time they were displayed.
(ACTIVE)
Restricts the list statistics to those data sets that are currently in use.
The default is ACTIVE when LIST is not specified or if LIST is specified
with no parameter. If LIST is specified with a parameter and LSTATS has
no parameter, then the parameter specified for LIST is used for LSTATS.
(*) Includes statistics for all open index spaces and table spaces, whether
currently in use or not.
DBNAME
Specifies which databases are included in the LIST display and the LSTATS
display. If you specify DBNAME without LIST, LIST(ACTIVE) is assumed.
ABBREVIATION: DBN
(database-name, ...)
Identifies one or more databases to be included in the LIST and
LSTATS displays. database-name can have any of the forms in the
following list. In the list, name1 and name2 represent strings of from
one to eight characters. name represents a string of from one to eight
characters.
Form Displays the status of...
name1
The database name1

98 Command Reference
-DISPLAY BUFFERPOOL (DB2)
name1:name2
All databases with names from name1 to name2 in a sorted list
of database names.
name* All databases whose names begin with the string name
(*) Displays information on all databases that match the LIST specification.
This is the default.
SPACENAM
Specifies which table spaces or index spaces within the specified databases to
include in the LIST display and the LSTATS display. If you use SPACENAM
without DBNAME, DBNAME(*) is assumed.
ABBREVIATION: SPACE
(*) Displays information about all table spaces and index spaces of the
specified databases. This is the default.
(space-name, ...)
Identifies one or more spaces to be included in the LIST and LSTATS
displays. You can write space-name like database-name to designate:
v The name of a single table space or index space
v A range of names
v A partial name followed by a pattern character
GBPDEP
Indicates whether to restrict the list of data sets to those that are
group-buffer-pool-dependent. This option is not valid if this is a non-data sharing
DB2.
(YES)
Restricts the list of page sets to those that are ″group buffer pool
dependent″ (GBP-dependent). An index space or table space is
GBP-dependent if either of these conditions are true:
v There is inter-DB2 R/W interest in it.
v There are changed pages from it in the group buffer pool that have not
yet been written to disk.
(NO)
Restricts the list of page sets to those that are non-group buffer pool
dependent.
CASTOWNR
Indicates whether to restrict the list of data sets to those for which this DB2
member is the castout owner. This option is not valid if this is a non-data
sharing DB2.
(YES)
Restricts the list of page sets for which this DB2 member is the castout
owner.
(NO)
Restricts the list of page sets for which this DB2 member is not the castout
owner.

Output
You can request a summary report or a detail report.

Chapter 2. Commands 99
-DISPLAY BUFFERPOOL (DB2)
Summary report
A summary report contains the following information, as seen in “Example 1” on
page 103:

Identification:
BUFFERPOOL NAME
Buffer pool external name (BP0, BP1, ..., BP49, or BP32K, BP32K1, ...,
BP32K9).
BUFFERPOOL ID
Buffer pool internal identifier (0-49, 80-89, 100-109, 120-129).
USE COUNT
Number of open table spaces or index spaces that reference this buffer
pool. (Inactive pools have a zero use count.)
VIRTUAL BUFFERPOOL SIZE
User-specified virtual buffer pool size
BUFFERS ALLOCATED
Number of allocated buffers in an active virtual buffer pool.
TO BE DELETED
Number of buffers to be deleted in an active virtual buffer pool (because of
pool contraction).
IN-USE/UPDATED
Number of currently active (not stealable) buffers in the virtual buffer pool.

Hiperpool Values:
HIPERPOOL SIZE
User-specified hiperpool size.
CASTOUT
Hiperpool CASTOUT attribute.
ALLOCATED
Number of allocated buffers in an active hiperpool.
TO BE DELETED
Number of buffers to be deleted in an active hiperpool (because of pool
contraction).
BACKED BY ES
Number of hiperpool buffers backed by expanded storage.

Thresholds:
VP SEQUENTIAL
Sequential steal threshold for the virtual buffer pool.
HP SEQUENTIAL
Sequential steal threshold for the hiperpool.
DEFERRED WRITE
Deferred write threshold for the virtual buffer pool.
VERTICAL DEFERRED WRT
Vertical deferred write threshold for the virtual buffer pool.
PARALLEL SEQUENTIAL
Parallel sequential threshold for the virtual buffer pool.

100 Command Reference


-DISPLAY BUFFERPOOL (DB2)
ASSISTING PARALLEL SEQT
Assisting parallel sequential threshold for the virtual buffer pool.

Names of hiperspaces allocated to the hiperpool: A hiperspace name consists


of 3 parts, with a total length of 8 characters. A hiperspace name always starts with
an indicator of ’@’ followed by:
1. The buffer pool’s internal ID (two characters, using Hex)
2. A sequence number about hiperspace allocation (one character)
3. The DB2 subsystem name (four characters)

Detail report
A detail report includes all summary report information and additional buffer pool
related statistics. You can request cumulative statistics (accumulated since DB2
startup) or incremental statistics (accumulated since the last incremental display). A
sample report appears in “Example 2” on page 103. The statistics in a detail report
are grouped in the following categories:

Getpage information (message DSNB411I):


RANDOM GETPAGE
Non-sequential getpage requests
SYNC READ I/O(R)
Synchronous read I/O operations for non-sequential getpage
SEQ. GETPAGE
Sequential getpage requests
SYNC READ I/O(S)
Synchronous read I/O operations for sequential getpage
DMTH HIT
Number of times data management threshold reached

Sequential prefetch statistics (message DSNB412I):


REQUESTS
Sequential prefetch requests
PREFETCH I/O
Sequential prefetch read I/O operations
PAGES READ
Number of pages read with sequential prefetch

List prefetch statistics (message DSNB413I):


REQUESTS
List prefetch requests
PREFETCH I/O
List prefetch read I/O operations
PAGES READ
Number of pages read due to list prefetch

Dynamic prefetch statistics (message DSNB414I):


REQUESTS
Dynamic prefetch requests
PREFETCH I/O
Dynamic prefetch read I/O operations

Chapter 2. Commands 101


-DISPLAY BUFFERPOOL (DB2)
PAGES READ
Number of pages read with dynamic prefetch

Disabled prefetch statistics (message DSNB415I):


NO BUFFER
Prefetch disabled - no buffer
NO READ ENGINE
Prefetch disabled - no read processor

Page update statistics (message DSNB420I):


SYS PAGE UPDATES
System page updates
SYS PAGES WRITTEN
System pages written
ASYNC WRITE I/O
Asynchronous write I/O operations
SYNC WRITE I/O
Synchronous write I/O operations

Page write statistics (message DSNB421I):


DWT HIT
Number of times deferred write threshold reached
VERTICAL DWT HIT
Number of times vertical deferred write threshold reached
NO WRITE ENGINE
Number of times write processor not available for I/O operations

Hiperpool activity (not using the Asynchronous Data Mover Facility):


(message DSNB430I)
SYNC HP READS
Number of times that a requested page was found in hiperpool and
synchronously moved to virtual buffer pool
SYNC HP WRITES
Number of pages synchronously moved from the virtual buffer pool to the
hiperpool
ASYCN HP READS
Number of times that a requested page was found in hiperpool and
asynchronously moved to virtual buffer pool without the use of the
Asynchronous Data Mover Facility
ASYNC HP WRITES
Number of pages asynchronously moved from the virtual buffer pool to the
hiperpool without the use of the Asynchronous Data Mover Facility
READ FAILURES
Number of page read failures (other than those that occurred using the
Asynchronous Data Mover Facility)
WRITE FAILURES
Number of page write failures (other than those that occurred using the
Asynchronous Data Mover Facility)

102 Command Reference


-DISPLAY BUFFERPOOL (DB2)
Hiperpool activity (using the Asynchronous Data Mover Facility) (message
DSNB431I):

| Note: When Fast Synchronous Data Mover Facility (FSDMF) is installed, these
| counters will be zero.
HP READS
Number of pages moved asynchronously from the hiperpool to the virtual
pool using the Asynchronous Data Mover Facility
HP WRITES
Number of pages moved asynchronously from the virtual pool to the
hiperpool using the Asynchronous Data Mover Facility
READ FAILURES
Number of page read failures that occurred using the Asynchronous Data
Mover Facility
WRITE FAILURES
Number of page write failures using that occurred the Asynchronous Data
Mover Facility

Parallel processing activity (message DSNB440I):


PARALLEL REQUEST
Number of negotiations for task streams for parallel processing activity
DEGRADED PARALLEL
Number of times negotiation resulted in a degraded mode of operation

Examples
Example 1: A summary report is the default report if the DETAIL option is not
specified. The following is an example of a summary report which could be
produced by the command:
-DIS BUFFERPOOL(BP0) LIST(*) DBNAME(DSN8*)

DSNB401I - BUFFERPOOL NAME BP0, BUFFERPOOL ID 0, USE COUNT 20


DSNB402I - VIRTUAL BUFFERPOOL SIZE = 500 BUFFERS 736
ALLOCATED = 500 TO BE DELETED = 0
IN-USE/UPDATED = 0
DSNB403I - HIPERPOOL SIZE = 10000 BUFFERS, CASTOUT = YES
ALLOCATED = 0 TO BE DELETED = 0
BACKED BY ES = 0
DSNB404I - THRESHOLDS - 739
VP SEQUENTIAL = 80 HP SEQUENTIAL = 75
DEFERRED WRITE = 85 VERTICAL DEFERRED WRT = 80,0
PARALLEL SEQUENTIAL = 50 ASSISTING PARALLEL SEQT = 0
DSNB406I - VIRTUAL BUFFERPOOL TYPE = -737
CURRENT = PRIMARY
PENDING = PRIMARY
PAGE STEALING METHOD = LRU
DSNB460I - 740

Example 2: A detail report can be generated that includes all summary report
information and additional buffer pool related statistics. The following is an example
of a detail report that could be produced by the command:
-DISPLAY BUFFERPOOL(BP0) DETAIL

Chapter 2. Commands 103


-DISPLAY BUFFERPOOL (DB2)
DSNB401I - BUFFERPOOL NAME BP0, BUFFERPOOL ID 0, USE COUNT 10
DSNB402I - VIRTUAL BUFFERPOOL SIZE = 1000 BUFFERS
ALLOCATED = 1000 TO BE DELETED = 0
IN-USE/UPDATED = 200
DSNB403I - HIPERPOOL SIZE = 600000 BUFFERS, CASTOUT = YES
ALLOCATED = 600000 TO BE DELETED = 0
BACKED BY ES = 483651
DSNB404I - THRESHOLDS -
VP SEQUENTIAL = 80 HP SEQUENTIAL = 80
DEFERRED WRITE = 50 VERTICAL DEFERRED WRT = 10
PARALLEL SEQUENTIAL = 50
DSNB405I - HIPERSPACE NAMES - @001SSOP @002SSOP

DSNB409I - INCREMENTAL STATISTICS SINCE 10:32:48 OCT 23, 1993

DSNB411I - RANDOM GETPAGE = 230 SYNC READ I/O (R) = 180


SEQ. GETPAGE = 610 SYNC READ I/O (S) = 20
DMTH HIT = 0

DSNB412I - SEQUENTIAL PREFETCH -


REQUESTS = 0 PREFETCH I/O = 0
PAGES READ = 0

DSNB413I - LIST PREFETCH -


REQUESTS = 0 PREFETCH I/O = 0
PAGES READ = 0

DSNB414I - DYNAMIC PREFETCH -


REQUESTS = 0 PREFETCH I/O = 0
PAGES READ = 0

DSNB415I - PREFETCH DISABLED -


NO BUFFER = 0 NO READ ENGINE = 0
DSNB420I - SYS PAGE UPDATES = 0 SYS PAGES WRITTEN = 0
ASYNC WRITE I/O = 0 SYNC WRITE I/O = 0
DSNB421I - DWT HIT = 0 VERTICAL DWT HIT = 0
NO WRITE ENGINE = 0

DSNB430I - HIPERPOOL ACTIVITY (NOT USING ASYNCHRONOUS


DATA MOVER FACILITY) -
SYNC HP READS = 100 SYNC HP WRITES = 0
ASYNC HP READS = 0 ASYNC HP WRITES = 0
READ FAILURES = 0 WRITE FAILURES = 0

DSNB431I - HIPERPOOL ACTIVITY (USING ASYNCHRONOUS


DATA MOVER FACILITY) -
HP READS = 244 HP WRITES = 3
READ FAILURES = 0 WRITE FAILURES = 0

DSNB440I - PARALLEL ACTIVITY -


PARALL REQUEST = 0 DEGRADED PARALL = 0

DSN9022I - DSNB1CMD '-DISPLAY BUFFERPOOL' NORMAL COMPLETION

Example 3: With the summary or detail report, you can list open table spaces and
index spaces associated with the buffer pool. You can also request a display of
statistics for each listed table space and index space. An example of a report
generating this information could be produced by the command:
-DISPLAY BUFFERPOOL(BP0) LIST LSTATS

104 Command Reference


-DISPLAY BUFFERPOOL (DB2)
DSNB401I - BUFFERPOOL NAME BP0, BUFFERPOOL ID 0, USE COUNT 3
DSNB402I - VIRTUAL BUFFERPOOL SIZE = 1000 BUFFERS
ALLOCATED = 1000 TO BE DELETED = 0
IN-USE/UPDATED = 200
DSNB403I - HIPERPOOL SIZE = 100000 BUFFERS, CASTOUT = YES
ALLOCATED = 100000 TO BE DELETED = 0
BACKED BY ES = 89152
DSNB404I - THRESHOLDS -
VP SEQUENTIAL = 80 HP SEQUENTIAL = 80
DEFERRED WRITE = 50 VERTICAL DEFERRED WRT = 10
PARALLEL SEQUENTIAL = 50
DSNB405I - HIPERSPACE NAMES - @001SSOP
DSNB455I - SYNCHRONOUS I/O DELAYS -
AVERAGE DELAY = 22 MAXIMUM DELAY = 35
TOTAL PAGES = 23
DSN9022I - DSNB1CMD '-DISPLAY BUFFERPOOL' NORMAL COMPLETION

Chapter 2. Commands 105


-DISPLAY DATABASE (DB2)

-DISPLAY DATABASE (DB2)


The DB2 command DISPLAY DATABASE displays information about the status of
DB2 databases, table spaces, tables in segmented table spaces, LOB table spaces,
index spaces within a database, indexes on auxiliary tables, and partitions of
partitioned table spaces and index spaces.

DISPLAY DATABASE RESTRICT indicates if a table space, index space, or


partition is in any pending status. Use the ADVISORY option without the RESTRICT
option to display any objects that are in an advisory pending status, such as the
informational COPY pending or auxiliary warning advisory status.

In a data sharing environment, the command can be issued from any DB2 in the
group that has access to the database.

Abbreviation: -DIS DB

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Group

Authorization
No special privilege is required to issue -DISPLAY DATABASE.

The DISPLAY system privilege allows you to display status information for any
database. The resulting display lists those databases for which the primary
authorization ID or any of the secondary authorization IDs has the DISPLAYDB
privilege. Error messages are produced for those databases specified over which
the set of privileges does not include one of the following:
v DISPLAYDB privilege
v DISPLAY privilege
v DBMAINT, DBCTRL, or DBADM authority
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

106 Command Reference


-DISPLAY DATABASE (DB2)
Syntax

 DISPLAY DATABASE (  database-name ) 


*
dbname1:dbname2
dbname*
*dbname
*dbname*
*dbstring1*dbstring2*

 
USE
CLAIMERS
LOCKS
LPL
WEPR
,

SPACENAM (  space-name )
*
spacename1:spacename2 USE ONLY
spacename* CLAIMERS
*spacename LOCKS
*spacename* LPL
*spacestring1*spacestring2* WEPR
(1)
ONLY

 
, 50
LIMIT( integer )
PART(  integer ) *
integer1:integer2

 
AFTER ACTIVE RESTRICT ( ) ADVISORY ( )
, ,

 ACHKP  ICOPY
CHKP AUXW
COPY
GRECP
LPL
RBDP
RECP
REORP
RO
STOP
UT
UTRO
UTRW
UTUT
UT*
WEPR

Notes:
1 If you specify the ONLY option without the SPACENAM() keyword, only the LIMIT, AFTER, and
RESTRICT keywords apply. Chapter 2. Commands 107
-DISPLAY DATABASE (DB2)

Option descriptions
(database-name, ...)
Identifies one or more databases whose status is to be displayed.
(*) Displays information on all databases that are defined to the DB2 subsystem for
which the privilege set of the process has the required authorization.

dbname and dbstring can have any of the forms in the following table (where
dbname1 and dbname2 represent any strings of from one to eight characters, and
dbname represents any string of from one to seven characters):
Table 14. Forms of dbname and dbstring
Form Displays the status of...
dbname1:dbname2 All databases whose names collate greater than or equal to
dbname1 and less than or equal to dbname2
dbname* All databases whose names begin with the string dbname
*dbname All databases whose names end with the string dbname
*dbname* All databases whose names contain the string dbname
*dbstring1*dbstring2* All databases whose names contain the strings dbstring1 and
dbstring2

SPACENAM
Specifies what space to display. If you use SPACENAM, you must also specify
the corresponding database name. If (*) is used to specify multiple databases,
SPACENAM(*) can be specified to display all objects in these databases.
Abbreviation: SPACE, SP
(space-name, ...)
Lists one or more spaces whose status is to be displayed. You can write
space-name like database-name to designate:
v The name of a single table space or index space
v A range of names
v A partial name, including a beginning or ending pattern-matching
character (*), a pattern-matching character between two strings, or any
combination of these3
(*) Displays information about all table spaces and index spaces of the
specified database.

spacename and spacestring can have any of the forms in the following table
(where spacename1 and spacename2 represent any strings of from one to
eight characters, and spacename represents any string of from one to seven
characters):
Table 15. Forms of spacename and spacestring
Form Displays the status of...
spacename1::spacename2 All table spaces or index spaces whose names collate greater than or equal to
spacename1 and less than or equal to spacename2

3. Consecutive pattern-matching characters (*) are not allowed, and you cannot specify two pattern-matching characters in the middle
of a keyword string.

108 Command Reference


-DISPLAY DATABASE (DB2)
Table 15. Forms of spacename and spacestring (continued)
spacename* All table spaces or index spaces whose names begin with the string spacename
*spacename All table spaces or index spaces whose names end with the string spacename
*spacename* All table spaces or index spaces whose names contain the string spacename
*spacestring1*spacestring2* All table spaces or index spaces whose names contain the strings spacestring1 and
spacestring2

USE
Displays information about the following:
v The applications and subsystems of the database or space that has internal
DB2 resources allocated
v The applications and subsystems of the database or space on whose behalf
locks for the space are held or waited upon
v The connection IDs, correlation IDs, and authorization IDs for all applications
allocated to spaces and partitions whose statuses are displayed
v The LUWID and location of any remote threads accessing the local database
CLAIMERS
Displays information about the following:
v The claims on all table spaces, index spaces and partitions whose statuses
are displayed
v The LUWID and location of any remote threads accessing the local database
v The connection IDs, correlation IDs, and authorization IDs for all applications
allocated to spaces whose statuses are displayed
v The logical partitions that have logical claims and the claims associated with
them

CLAIMERS overrides both LOCKS and USE. If you specify CLAIMERS, any
references to LOCKS or USE are ignored.
LOCKS
Displays information about the following:
v The applications and subsystems on whose behalf locks are held, waited
upon, or retained for the database or space
v The transaction locks for all table spaces, tables, index spaces and partitions
whose statuses are displayed
v The connection IDs, correlation IDs, and authorization IDs for all applications
allocated to spaces whose statuses are displayed
v The LUWID and location of any remote threads accessing the local database
v The drain locks for a resource held by running jobs
v The logical partitions that have drain locks and the drain locks associated
with them
v The retained locks for a resource
v The page set or partition physical locks (P-locks) for a resource

LOCKS overrides USE. If both LOCKS and USE are specified, USE is ignored.

For a description of DB2 locking, see Part 5 (Volume 2) of DB2 Administration


Guide.
LPL
Displays logical page list entries.

Chapter 2. Commands 109


-DISPLAY DATABASE (DB2)
WEPR
Displays write error page range information.
ONLY
Displays information about the specified object.
without SPACENAM() keyword
Displays only database information. DB2 does not display information for
the spaces within the database you specified with the DISPLAY DATABASE
command. If you specify ONLY, the following keywords are valid:
v RESTRICT
v LIMIT
v AFTER
with SPACENAM() keyword
Displays the table spaces or indexes that have information requested by the
DISPLAY DATABASE command. If you specify SPACENAM() ONLY, you
must also specify one of the following keywords:
v USE
v CLAIMERS
v LOCKS
v LPL
v WEPR

DB2 displays tables with table locks when you specify both the LOCKS and
ONLY keywords.
PART (integer, ...)
Indicates the partition number of one or more partitions whose status is to be
displayed. The integer specified must identify a valid partition number for the
corresponding space name and database name. integer can be written to
designate either:
v A list of one or more partitions, or
v A range of all partition numbers that collate greater than or equal to integer1
and less than or equal to integer2
Both a list and a range cannot be specified.
LIMIT
Limits the number of messages to be displayed by the command.
(integer)
Is the maximum number of messages that are to be displayed. The default
is 50. The maximum number of messages that can be displayed is limited
by the space available.
(*) Limits the display to the space available.
AFTER
Displays the following information:
v If only a database name is used, AFTER continues the display of all other
databases whose names collate greater than that name.
v If SPACENAM and a table space or index space name are used, AFTER
continues the display to all other table spaces or index spaces in the same
database whose names collate greater than that name.

AFTER cannot be used with more than one database name, table space name,
index space name, with any pattern-matching character (*) within the database
name, or with the SPACENAM() keyword.

110 Command Reference


-DISPLAY DATABASE (DB2)
ACTIVE
Limits the display to table spaces or index spaces that have had internal DB2
resources allocated to applications and are in a started state or to databases
that contain such spaces.
Abbreviation: A
Default: Using neither ACTIVE nor RESTRICT displays information on all
databases defined to DB2.
RESTRICT
Limits the display to databases, table spaces, or indexes in a restricted status.
| This includes those page sets that have logical page list entries. Specifying one
| or more keywords further limits the display to the named objects only.
Abbreviation: RES
Use of a database is restricted if the database is in any one of the following
situations:
v It is started for read-only processing.
v It is started for utility-only processing.
v It is stopped.

Use of a table space or index space is restricted if:


v It is in one of the three situations above.
v It is being processed by a utility.
v It is in COPY-pending, CHECK-pending, RECOVER-pending, group buffer
pool RECOVER-pending, auxiliary CHECK-pending, or REORG-pending
status.
v It contains a page error range.
v It contains pages in the logical page list (LPL).

| Specify one or more of the following keywords to limit objects that are to be
| listed.
| ACHKP
| Displays objects in the auxiliary warning advisory state.
| CHKP Display objects that are in CHECK-pending status.
| COPY Display objects that are in COPY-pending status.
| GRECP
| Displays objects that are in group buffer pool RECOVER-pending
| status.
| LPL Displays logical page list entries.
|
# RBDP Displays index objects that are in REBUILD- or RECOVER-pending
# status. This includes the restricted states RBDP, LPL, and WEPR.
|
# RECP Displays objects that are in RECOVER-pending status, including the
# restricted states RECP, RECP*, LPL, and WEPR (write error page
# range).
| REORP
| Displays objects that are in REORG-pending status.
| RO Displays objects that are in read-only mode.
| STOP Displays objects that are stopped, including the restricted states STOP,
| STOPE, STOPP, and LSTOP.
| UT Displays objects that are in utility access mode.

Chapter 2. Commands 111


-DISPLAY DATABASE (DB2)
| UTRO Display objects that are serialized for utility access and available for
| read-only access.
| UTRW Display objects that are serialized for utility access and available for
| read-write access.
| UTUT Displays objects that are serialized for utility access and unavailable.
| UT* Displays objects that are in any utility access mode: UT, UTRW, UTRO,
| or UTUT.
| WEPR Displays write error page range information.
| ADVISORY
Limits the display to indexes and table spaces to which read-write access is
allowed, but for which some action is recommended.
Abbreviation: ADV
Use the DISPLAY DATABASE ADVISORY command without the RESTRICT
option to determine when:
v An index space is in the informational COPY pending (ICOPY) advisory
status.
v A base table space or LOB table space is in the auxiliary warning (AUXW)
advisory status.

| Specify one or more of the following keywords to limit the objects listed.
| AUXW
| Displays objects that are in the auxiliary warning advisory state.
| ICOPY
| Displays objects that are in the informational copy pending advisory
| state.

| For information about resetting an advisory status, see Part 2 of DB2 Utility
Guide and Reference.

Usage notes
Displaying DB2 catalog tables: You can always display the DB2 catalog tables.
However, if a table space in the catalog containing information about user
databases or user table spaces is stopped, those databases or table spaces cannot
be displayed. Trying to display them will cause an error. See Appendix D of DB2
SQL Reference for a list of table space names and assigned tables.

If you issue DISPLAY DATABASE LOCKS on the catalog (DSNDB06), you may see
a lock held on SYSDBASE with the correlation ID 020.DBCMD_05 or
020.DBCMD_06. This simply indicates the lock that DISPLAY DATABASE itself
needs and is normal.

Displaying restricted and advisory status objects: To display all resources that
are in restricted status, you must issue the DISPLAY DATABASE command twice.
To display table spaces and indexes in restricted status, use the SPACENAM
parameter with RESTRICT. To display databases in restricted status, do NOT use
the SPACENAM parameter. Spaces could be unavailable even if they show RW
mode if the database is in restricted status.

112 Command Reference


-DISPLAY DATABASE (DB2)
To display all resources that are in advisory status, issue the DISPLAY DATABASE
ADVISORY command without the RESTRICT option. For information about
resetting a restrictive or advisory status, see Part 2 of DB2 Utility Guide and
Reference.

Communications Database and Resource Limit Facility: If the command


specifies a table space or index space in the communications database or in the
active resource limit facility database, then the USE option displays the names of all
members of the data sharing group that are using the specified table space or index
space. Knowing which other members of the data sharing group might be using
these spaces is useful when considering whether to drop table spaces and index
spaces in the communications database and the resource limit facility database.

Displaying logical partitions: If you issue DISPLAY DATABASE with the PART
parameter for a logical partition of a type 2 index, DB2 does not display physical
claimers and physical locks in the output.

Displaying databases for declared temporary tables: DISPLAY DATABASE


displays information about databases that are created with the AS TEMP option and
the associated table spaces, but does not display information for declared
temporary tables or index spaces that the database contains.

Output
Message DSNT392I status information: The status codes that are displayed by
the DISPLAY DATABASE command and their respective descriptions are as follows:
ACHKP
Indicates an error in the LOB column of the base table space. The base
table space has the auxiliary CHECK-pending restrictive status.
| AREST
Indicates that an object (a table space, index space, or a physical partition
of a table space or index space) is in an advisory RESTART-pending state.
If backout activity against the object is not already underway, initiate it either
by issuing the RECOVER POSTPONED command, or by recycling the
system with the system parameter LBACKOUT=AUTO.
AUXW
Either the base table space is in the auxiliary warning advisory status,
indicating an error in the LOB column, or the LOB table space is in the
auxiliary warning advisory status, indicating an invalid LOB.
CHKP The object (a table space, a partition within a table space, or an index) is in
the CHECK-pending status.
COPY The object (a table space or a partition within a table space) is in the
COPY-pending status. An image copy is required for this object.
GRECP
The object is GBP-dependent and a group buffer pool RECOVER is
pending.
ICOPY
The index space is in the informational COPY-pending advisory status.
LPL The object has entries in the logical page list.
LSTOP
The logical partition of a nonpartitioning index is stopped.

Chapter 2. Commands 113


-DISPLAY DATABASE (DB2)
PSRBD
The entire nonpartitioning index space is in a page set REBUILD pending
status.
RBDP The physical or logical index partition is in the REBUILD pending status.
RBDP*
The logical partition of a nonpartitioning index is in the REBUILD pending
status, and the entire index is inaccessible to SQL applications. However,
only the logical partition needs to be rebuilt.
RECP The object (a table space, table space partition, index space, index
partition, or logical index partition) is in the RECOVER-pending status.
| REFP The object (a table space, index space, or an index) is in the
| REFRESH-pending status.
| RELDP
| The object has a release dependency.
REORP
The data partition is in the REORG-pending status.
RESTP
The table space or index space is in the restart-pending status.
RO The database, table space, table space partition, index space, or index
space partition is started for read-only activity.
RW The database, table space, table space partition, index space, or index
space partition is started for read and write activity.
STOP The database, table space, table space partition, index space, or index
space partition is stopped.
STOPE
The table space or index space was implicitly stopped because there is a
problem with the log RBA in a page. Message DSNT500I or DSNT501I is
issued when the error is detected, indicating the inconsistency.
STOPP
A stop is pending for the database, table space, table space partition, index
space, or index space partition.
UT The database, table space, table space partition, index space, or index
space partition is started for utility processing only.
UTRO A utility is in process, on the table space, table space partition, index space,
or index space partition, that allows only RO access. If the utility was
canceled before the object was drained, the object can allow SQL access
because the object was not altered by the utility.
UTRW A utility is in process, on the table space, table space partition, index space,
or index space partition, that allows RW access.
UTUT A utility is in process, on the table space, table space partition, index space,
or index space partition, that allows only UT access. If the utility was
canceled before the object was drained, the object can allow SQL access
because the object was not altered by the utility.
| WEPR Displays write error page range information.

114 Command Reference


-DISPLAY DATABASE (DB2)
Examples
Example 1: Display information about table space TBS33 in database CB3. USE
causes connection-name(CONNID), correlation-id(CORRID), and authorization ID
(USERID) information to be displayed.
-DISPLAY DATABASE(CB3) SPACENAM(TBS33) USE

The following output is generated:


DSNT360I - ***********************************************************
DSNT361I - * DISPLAY DATABASE SUMMARY
* GLOBAL USE
DSNT360I - ***********************************************************
DSNT362I - DATABASE = CB3 STATUS = RW
DBD LENGTH = 4028
DSNT397I -
NAME TYPE PART STATUS CONNID CORRID USERID
-------- ---- ---- ------------------ -------- ------------ --------
TBS33 TS 01 RW LSS001 DSN2SQL SYSADM
TBS33 TS 02 RW LSS001 DSN2SQL SYSADM
TBS33 TS 03 RW LSS001 DSN2SQL SYSADM
TBS33 TS 04 RW LSS001 DSN2SQL SYSADM
******* DISPLAY OF DATABASE CB3 ENDED **********************
DSN9022I . DSNTDDIS 'DISPLAY DATABASE' NORMAL COMPLETION

Example 2: Display information about table space TBS33 in database CB3 when
the table space is defined with LOCKPART YES. LOCKS displays lock information
for table spaces and tables specified; LUWIDs and locations of any remote threads;
and connection-name, correlation-id, and authorization ID information.
-DISPLAY DATABASE(CB3) SPACENAM(TBS33) LOCKS

The following output is generated:


DSNT360I - ***********************************************************
DSNT361I - * DISPLAY DATABASE SUMMARY
* GLOBAL LOCKS
DSNT360I - ***********************************************************
DSNT362I - DATABASE = CB3 STATUS = RW
DBD LENGTH = 4028
DSNT397I -
NAME TYPE PART STATUS CONNID CORRID LOCKINFO
-------- ---- ---- ------------------ -------- ------------ ---------
TBS33 TS 01 RW
TBS33 TS 02 RW
TBS33 TS 03 RW
TBS33 TS 04 RW LSS004 DSN2SQL H(IS,S,C)
TBS33 TS 04 RW LSS005 DSN2SQL H(IS,S,C)
******* DISPLAY OF DATABASE CB3 ENDED **********************

Example 3: Display information about table space TBS33 in database CB3.


CLAIMERS displays claim types and durations; LUWIDs and locations of any
remote threads; and connection-name, correlation-id, and authorization ID
information.
-DISPLAY DATABASE(CB3) SPACENAM(TBS33) CLAIMERS

The following output is generated:

Chapter 2. Commands 115


-DISPLAY DATABASE (DB2)
DSNT360I - ***********************************************************
DSNT361I - * DISPLAY DATABASE SUMMARY
* GLOBAL CLAIMERS
DSNT360I - ***********************************************************
DSNT362I - DATABASE = CB3 STATUS = RW
DBD LENGTH = 4028
DSNT397I -
NAME TYPE PART STATUS CONNID CORRID CLAIMINFO
-------- ---- ---- ------------------ -------- ------------ --------
TBS33 TS 01 RW
TBS33 TS 02 RW
TBS33 TS 03 RW
TBS33 TS 04 RW LSS001 DSN2SQL (RR,C)
TBS33 TS 04 RW LSS001 DSN2SQL (WR,C)
******* DISPLAY OF DATABASE CB3 ENDED *********************

Example 4: In a data sharing environment, display information about locks held


when the table space is defined with LOCKPART YES. The application identified as
LSS001 on member DB1G has locked partitions 1 and 2. LSS002 on member
DB2G has locked partitions 1 and 3. Partition 4 has no locks held on it.
-DISPLAY DATABASE(DSN8D51A) SPACENAM(TSPART) LOCKS

Output similar to the following output is generated:


NAME TYPE PART STATUS CONNID CORRID LOCKINFO
-------- ---- ---- ------------------ -------- ------------ ---------
TSPART TS 01 RO LSS001 DSN2SQL H-IS,P,C
- MEMBER NAME DB1G
TSPART TS 01 RO H-S,PP,I
- MEMBER NAME DB1G
TSPART TS 01 RO LSS002 DSN2SQL H-IS,P,C
- MEMBER NAME DB2G
TSPART TS 01 RO H-S,PP,I
- MEMBER NAME DB2G
TSPART TS 02 RW LSS001 DSN2SQL H-IS,P,C
- MEMBER NAME DB1G
TSPART TS 02 RW H-S,PP,I
- MEMBER NAME DB1G
TSPART TS 03 RW LSS002 DSN2SQL H-IS,P,C
- MEMBER NAME DB2G
TSPART TS 03 RW H-S,PP,I
- MEMBER NAME DB2G
TSPART TS 04 RW

If the table space is defined with LOCKPART NO, the display looks like this. The
LOCKINFO field shows a value of S, indicating that this is a table space lock. If
partitions are held in different statuses, those statuses are listed below the table
space locks.
NAME TYPE PART STATUS CONNID CORRID LOCKINFO
-------- ---- ---- ------------------ -------- ------------ ---------
TSPART TS LSS001 DSN2SQL H-IS,S,C
- MEMBER NAME DB1G
TSPART TS LSS002 DSN2SQL H-IS,S,C
- MEMBER NAME DB2G
TSPART TS 01 RO H-S,PP,I
- MEMBER NAME DB1G
TSPART TS 02 RW H-S,PP,I
- MEMBER NAME DB2G
TSPART TS 03 RW H-S,PP,I
- MEMBER NAME DB2G
TSPART TS 04 RW

116 Command Reference


-DISPLAY DATABASE (DB2)
Example 5: Display information about page sets in database DSNDB01 that have
entries in the logical page list. Limit the number of messages displayed to the space
available.
-DB1G DISPLAY DATABASE(DSNDB01) SPACENAM(*) LIMIT(*) LPL

Output similar to the following output is generated:


***********************************************************
DSNT361I -DB1G * DISPLAY DATABASE SUMMARY
* GLOBAL LPL
DSNT360I -DB1G
***********************************************************
DSNT362I -DB1G DATABASE = DSNDB01 STATUS = RW
DBD LENGTH = 8000
DSNT397I -DB1G
NAME TYPE PART STATUS LPL PAGES
-------- ---- ---- ------------------ ------------------
DBD01 TS RW,LPL,GRECP 000001,000004,00000C,000010
---- 000039-00003C
SPT01 TS RW
SCT02 TS RW
SYSLGRNG TS RW
SYSUTILX TS RW
SYSLGRNX TS RW,LPL,GRECP 000000-FFFFFF
DSNSCT02 IX RW
DSNSPT01 IX RW
DSNSPT02 IX RW
DSNLUX01 IX RW
DSNLUX02 IX RW
DSNLLX01 IX RW
DSNLLX02 IX RW
******* DISPLAY OF DATABASE DSNDB01 ENDED **********************
DSN9022I -DB1G DSNTDDIS 'DISPLAY DATABASE' NORMAL COMPLETION

Example 6: Suppose that table space TSPART, which is in database DSN8D71A, is


defined with the keyword LOCKPART NO, which means that DB2 does not do
selective partition locking on TSPART. When you specify this command:
-DB1G DISPLAY DATABASE(DSN8D71A) SPACE(TSPART) PART(1,4) LOCKS

two applications are accessing TSPART, and the partitions have different statuses.
In the output, DB2 displays the locks as table space locks, as shown here:
NAME TYPE PART STATUS CONNID CORRID LOCKINFO
-------- ---- ---- ------------------ -------- ------------ ---------
TSPART TS LSS001 DSN2SQL H-IS,S,C
TSPART TS LSS002 DSN2SQL H-IS,S,C
TSPART TS 01 RO
TSPART TS 04 RW

Example 7: Suppose that you have executed the ALTER TABLESPACE statement
on table space TSPART so that TSPART is now defined with LOCKPART YES.
LOCKPART YES causes DB2 to do selective partition locking on TSPART. When
you specify this command:
-DB1G DISPLAY DATABASE(DSN8D71A) SPACE(TSPART) PART(1:4) LOCKS

two applications are accessing TSPART. The application identified by connection ID


LSS001 has locked partitions 1 and 2. The application identified by connection ID
LSS002 has locked partitions 1 and 3. In the output, DB2 displays the locks as
partition locks, as shown here:
NAME TYPE PART STATUS CONNID CORRID LOCKINFO
-------- ---- ---- ------------------ -------- ------------ ---------
TSPART TS 01 RO LSS001 DSN2SQL H-IS,P,C

Chapter 2. Commands 117


-DISPLAY DATABASE (DB2)
TSPART TS 01 RO LSS002 DSN2SQL H-IS,P,C
TSPART TS 02 RW LSS001 DSN2SQL H-IS,P,C
TSPART TS 03 RW LSS002 DSN2SQL H-IS,P,C
TSPART TS 04 RW

Example 8: Display information about all table spaces and index spaces in the
range of databases from DBKD0101 to DBKD0106 that are in a restrictive status.
Limit the number of messages that are displayed to the available space.
-DISPLAY DATABASE(DBKD0101,DBKD0103) SPACENAM(*) RESTRICT LIMIT(*)

Output similar to the following output is generated:


DSNT360I - ***********************************
DSNT361I - * DISPLAY DATABASE SUMMARY
* RESTRICTED
DSNT360I - ***********************************
DSNT362I - DATABASE = DBKD0101 STATUS = RW
DBD LENGTH = 4028
DSNT397I -
NAME TYPE PART STATUS PHYERRLO PHYERRHI CATALOG PIECE
-------- ---- ---- ------------------ -------- -------- -------- -----
TLKD0101 TS RW,RESTP
IUKD011A IX RW,RESTP
IXKD011B IX RW,RESTP

Example 9: Display information about all table spaces that are in the auxiliary
warning advisory status (AUXW), and all index spaces that are in informational
COPY pending status (ICOPY) in database DBIQUQ01. Limit the number of
messages that are displayed to the available space.
-DISPLAY DATABASE(DBIQUQ01) SPACENAM(*) LIMIT(*) ADVISORY

Output similar to the following output is generated:


DSNT360I - ***********************************
DSNT361I - * DISPLAY DATABASE SUMMARY
* ADVISORY
DSNT360I - ***********************************
DSNT362I - DATABASE = DBIQUQ01 STATUS = RW
DBD LENGTH = 8066
DSNT397I -
NAME TYPE PART STATUS PHYERRLO PHYERRHI CATALOG PIECE
-------- ---- ---- ------------------ -------- -------- -------- -----
TPIQUQ01 TS 001 RW,AUXW
TPIQUQ01 TS 002 RW,AUXW
TPIQUQ01 TS 003 RW,AUXW
TPIQUQ01 TS 004 RW,AUXW
IAIQUQ01 IX RW,ICOPY
IAIQUQ02 IX RW,ICOPY
IAIQUQ03 IX RW,ICOPY
IAIQUQ04 IX RW,ICOPY
IPIQUQ01 IX 001 RW,ICOPY
IPIQUQ01 IX 002 RW,ICOPY
IPIQUQ01 IX 003 RW,ICOPY
IPIQUQ01 IX 004 RW,ICOPY
IUIQUQ03 IX RW,ICOPY
IXIQUQ02 IX RW,ICOPY
******* DISPLAY OF DATABASE DBIQUQ01 ENDED **********************
DSN9022I - DSNTDDIS 'DISPLAY DATABASE' NORMAL COMPLETION

118 Command Reference


-DISPLAY DDF (DB2)

| -DISPLAY DDF (DB2)


| The -DISPLAY DDF command displays information regarding the status and
| configuration of DDF, as well as statistical information regarding connections or
| threads controlled by DDF.

| Abbreviation: -DIS DDF

| Environment
| This command can be issued from an MVS console, a DSN session under TSO, a
| DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
| instrumentation facility interface (IFI).

| Data sharing scope: Member

| Authorization
| To execute this command, the privilege set of the process must include one of the
| following:
| v DISPLAY privilege
| v SYSOPR, SYSCTRL, or SYSADM authority

| DB2 commands issued from an MVS console are not associated with any
| secondary authorization IDs.

| Syntax
|

 DISPLAY DDF 
DETAIL

| Option descriptions
| DETAIL
| Displays additional configurational and statistical information.

| Output
| The -DISPLAY DDF command displays the following output:
| STATUS
| The operational status of DDF.
| LOCATION
| The location name of DDF.
| LUNAME
| The fully qualified LUNAME of DDF.
| GENERICLU
| The fully qualified generic LUNAME of DDF.
| IPADDR
| The IP address of DDF.
| TCPPORT
| The SQL listener port used by DDF.

Chapter 2. Commands 119


-DISPLAY DDF (DB2)
| RESPORT
| The resync listener port used by DDF.
| DOMAIN
| The SQL and resync domains used by DDF.

| Examples
| Example 1: Display DDF detail report where DDF has not yet been started:
| #dis ddf det
| DSNL080I # DSNLTDDF DISPLAY DDF REPORT FOLLOWS:
| DSNL081I STATUS=STOPDQ
| DSNL082I LOCATION LUNAME GENERICLU
| DSNL083I STL715B -NONE.SYEC715B -NONE
| DSNL084I IPADDR TCPPORT RESPORT
| DSNL085I -NONE 447 5002
| DSNL086I SQL DOMAIN=-NONE
| DSNL086I RESYNC DOMAIN=-NONE
| DSNL090I DT=A CONDBAT= 64 MDBAT= 64
| DSNL092I ADBAT= 0 QUEDBAT= 0 IN1DBAT= 0 CONQUED= 0
| DSNL093I DSCDBAT= 0 IN2CONS= 0
| DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE

| Example 2: Display DDF report where DDF is started:


| #dis ddf det
| DSNL080I # DSNLTDDF DISPLAY DDF REPORT FOLLOWS:
| DSNL081I STATUS=STARTD
| DSNL082I LOCATION LUNAME GENERICLU
| DSNL083I STL715B USIBMSY.SYEC715B -NONE
| DSNL084I IPADDR TCPPORT RESPORT
| DSNL085I 9.112.114.103 447 5002
| DSNL086I SQL DOMAIN=v7ec103.stl.ibm.com
| DSNL086I RESYNC DOMAIN=v7ec103.stl.ibm.com
| DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE

| Example 3: Display DDF detail report where DDF is started:


| #dis ddf det
| DSNL080I # DSNLTDDF DISPLAY DDF REPORT FOLLOWS:
| DSNL081I STATUS=STARTD
| DSNL082I LOCATION LUNAME GENERICLU
| DSNL083I STL715B USIBMSY.SYEC715B -NONE
| DSNL084I IPADDR TCPPORT RESPORT
| DSNL085I 9.112.114.103 447 5002
| DSNL086I SQL DOMAIN=v7ec103.stl.ibm.com
| DSNL086I RESYNC DOMAIN=v7ec103.stl.ibm.com
| DSNL090I DT=A CONDBAT= 64 MDBAT= 64
| DSNL092I ADBAT= 1 QUEDBAT= 0 IN1DBAT= 0 CONQUED= 0
| DSNL093I DSCDBAT= 0 IN2CONS= 0
| DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE

120 Command Reference


DISPLAY FUNCTION SPECIFIC (DB2)

-DISPLAY FUNCTION SPECIFIC (DB2)


The DB2 command DISPLAY FUNCTION SPECIFIC displays statistics about
external user-defined functions that DB2 applications access.

Abbreviation: -DIS FUNC SPEC

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

# Data sharing scope: Group or local, depending on the value of the SCOPE option.

Authorization
To execute this command, the privilege set of the process must include one of the
following authorities for each function:
v DISPLAY privilege
v Ownership of the function
v SYSOPR authority
v SYSCTRL authority
v SYSADM authority

If -DISPLAY FUNCTION SPECIFIC *.* or schema.partial-name* is specified, the


privilege set of the process must include one of the following authorities:
v SYSOPR authority
v SYSCTRL authority
v SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

(*.*)
 DISPLAY FUNCTION SPECIFIC 
,

(  schema.specific-function-name )
schema.partial-name*

 
LOCAL
SCOPE ( )
GROUP

Option descriptions
schema.specific-function-name
Displays information for the specific named function in the specified schema.
You cannot specify a function name as you can in SQL; you must use the
specific name. If a specific name was not specified on the CREATE FUNCTION
statement, query SYSIBM.SYSROUTINES for the correct specific name:

Chapter 2. Commands 121


DISPLAY FUNCTION SPECIFIC (DB2)
SELECT SPECIFICNAME, PARM_COUNT
FROM SYSIBM.SYSROUTINES
WHERE NAME='function_name'
AND SCHEMA='schema_name';

For overloaded functions, this query can return multiple rows.


schema.partial-name*
Displays information for a set of functions in the specified schema.
The specific names of all functions in the set begin with partial-name and can
end with any string, including the empty string. For example, schema1.ABC*
displays information for all functions with specific names that begin with ABC in
schema1.
(*.*)
Displays information for all functions that have been accessed by DB2
applications since the DB2 subsystem was started.
# SCOPE
# Specifies the scope of the command.
# (LOCAL)
# Specifies that the display only includes information from the local member
# only.
# (GROUP)
# Specifies that the display includes information from all members of the data
# sharing group.

# Usage notes
If you do not specify a partial or specific function name, DB2 displays information
for all functions that DB2 applications have accessed since the DB2 subsystem was
started.

This command does not apply to built-in functions or user-defined functions that are
sourced on another function.

Output
This command displays one output line for each function that a DB2 application has
accessed.

Information returned by this command reflects a dynamic status. By the time DB2
displays the information, the status might have changed.

Sample output: The DISPLAY FUNCTION SPECIFIC command generates the


following output:
DSNX975I - DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS -

------- SCHEMA=PAYROLL
FUNCTION STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
APPL1 STARTED 1 0 0 0 PAYROLL
APPL2 STARTED 1 0 0 0 PAYROLL
APPL3 STARTED 0 1 2 0 PAYROLL
APPL5 STOPREJ 0 0 0 0 SANDBOX
APPL6 STOPABN 0 0 0 0 PAYROLL
FUNC1 STOPQUE 0 0 0 0 SANDBOX

122 Command Reference


DISPLAY FUNCTION SPECIFIC (DB2)

DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE


DSN9022I - DSNX9COM '-DISPLAY FUNC' NORMAL COMPLETION

DISPLAY FUNCTION SPECIFIC command output: The DISPLAY FUNCTION


SPECIFIC command displays the following output:
FUNCTION
The specific name of the function.
STATUS
The status of the function. The possible values are:
STARTED
Requests for the function can be processed.
STOPQUE
Requests are queued.
STOPREJ
Requests are rejected.
STOPABN
Requests are rejected because of abnormal termination.
ACTIVE
The number of threads that are currently running the function.
QUEUED
The number of threads that are waiting for the function to be scheduled.
MAXQUE
The maximum number of threads that have waited concurrently for the
function to be scheduled since the DB2 subsystem was started.
TIMEOUT
The number of times an SQL statement timed out while waiting for a
request for the function to be scheduled.
WLM_ENV
The WLM environment where the function executes.

Message DSNX971I lists a range of functions that are stopped because a STOP
FUNCTION SPECIFIC command included a partial name with the pattern-matching
character (*). See “-STOP FUNCTION SPECIFIC” on page 321 for more
information.

Examples
Example 1: Display information about functions in the PAYROLL schema and the
HRPROD schema.
-DISPLAY FUNCTION SPECIFIC(PAYROLL.*, HRPROD.*)

This command produces output similar to the following output:


DSNX975I csect - DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-

------ SCHEMA=PAYROLL
FUNCTION STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
PAYRFNC1 STARTED 0 0 1 0 PAYROLL
PAYRFNC2 STOPQUE 0 5 5 3 PAYROLL
PAYRFNC3 STARTED 2 0 6 0 PAYROLL
USERFNC4 STOPREJ 0 0 1 0 SANDBOX

Chapter 2. Commands 123


DISPLAY FUNCTION SPECIFIC (DB2)
------ SCHEMA=HRPROD
FUNCTION STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
HRFNC1 STARTED 0 0 1 0 HRFUNCS
HRFNC2 STOPREJ 0 0 1 0 HRFUNCS
DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
DSN9022I - DSNX9COM '-DISPLAY FUNC' NORMAL COMPLETION

Example 2: Display information about specific functions in the PAYROLL schema.


-DISPLAY FUNCTION SPECIFIC(PAYROLL.USERFNC2,PAYROLL.USERFNC4)

This command produces output similar to the following output:


DSNX975I csect - DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-

------ SCHEMA=PAYROLL
FUNCTION STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
USERFNC2 STOPQUE 0 5 5 3 SANDBOX
USERFNC4 STOPREJ 0 0 1 0 SANDBOX
DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
DSN9022I - DSNX9COM '-DISPLAY FUNC' NORMAL COMPLETION

Example 3: Display information about all functions in the PAYROLL schema that
DB2 applications have accessed. This example assumes that the STOP FUNCTION
SPECIFIC(PAYROLL.*) ACTION(QUEUE) command is in effect at the time you
issue the DISPLAY FUNCTION SPECIFIC command:
-DISPLAY FUNCTION SPECIFIC(PAYROLL.*)

This command produces output similar to the following output:


DSNX975I csect - DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-

------ SCHEMA=PAYROLL
FUNCTION STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
USERFNC2 STOPQUE 0 5 5 3 SANDBOX
USERFNC4 STOPQUE 0 0 1 0 SANDBOX
FUNCTIONS USERFNC2 - USERFNC29999999999 STOP QUEUE
FUNCTIONS USERFNC4 - USERFNC49999999999 STOP QUEUE
DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
DSN9022I - DSNX9COM '-DISPLAY FUNC' NORMAL COMPLETION

124 Command Reference


-DISPLAY GROUP (DB2)

-DISPLAY GROUP (DB2)


The DB2 command DISPLAY GROUP displays information about the data sharing
group to which a DB2 subsystem belongs.

Abbreviation: -DIS GROUP

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Group

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v DISPLAY privilege
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

 DISPLAY GROUP 
DETAIL

Option descriptions
DETAIL
Displays information about the parallelism coordinator and parallelism assistant.

Usage notes
Member status: Message DSN7106I includes information about the XCF status of
the members (STATUS in the display output). The status can be ACTIVE,
QUIESCED, or FAILED.

ACTIVE indicates that the DB2 subsystem is active, and FAILED indicates that it is
failed. A QUIESCED status results from a STOP DB2 command and consists of
several subcategories:
QUIESCED
This is a normal quiesced state, as the result of a normal STOP DB2
command.
Q Q (quiesced) can be paired with one or more of the following letters:
I Indoubt or postponed abort units of recovery (URs) are outstanding.
This means retained locks are held.
C There was a castout error. The last updater of the page set or
partition could not write from the coupling facility to disk.

Chapter 2. Commands 125


-DISPLAY GROUP (DB2)
Make sure there are no connectivity problems between the coupling
facility and the processor before restarting DB2.
R There is retained information needed for DB2 to perform
resynchronization with one or more remote locations.
When DB2 is restarted, this resynchronization occurs.
ACTIVE
This is a normal active state without conditions.
A A (active) can be paired with the following letter:
I Indoubt or postponed abort units of recovery (URs) are outstanding.
This means retained locks are held.

Using this command in a non-data-sharing environment: DB2 issues the same


response, except for information which does not exist: group name, member name,
and member ID.

Output
DISPLAY GROUP command output: The DISPLAY GROUP command displays
the following output:
*** BEGIN
The name of the DB2 group
DB2 MEMBER
The names of its members
ID The IDs of its members
SUBSYS
The subsystem names of its members
CMDPREF
The command prefix for each member
STATUS
The status of each member (ACTIVE, QUIESCED with or without additional
conditions, or FAILED)
SYSTEM NAME
The names of the MVS system where the member is running, or was last
running in cases when the member status is QUIESCED or FAILED
IRLM SUBSYS
The name of the IRLM subsystem to which the DB2 member is connected
IRLMPROC
The procedure names of the connected IRLM
SYSTEM NAME
The MVS system name where the data sharing member runs on.
LVL A string of three numeric characters that list as follows:
v DB2 version
v DB2 release
v DB2 modification level
SCA The SCA structure size in KB and the percentage currently in use
LOCK1
The LOCK1 structure size in KB.

126 Command Reference


-DISPLAY GROUP (DB2)
The display also shows the following:
v The maximum number of lock entries possible for the lock table and how
many of those lock entries are currently in use. This number is an
approximate value.
v The maximum number of modify lock list entries and how many of those
list entries are currently in use.
For more information about the lock table and the list of modify locks, see
Chapter 6 of DB2 Data Sharing: Planning and Administration.
PARALLELISM COORDINATOR
Indicates whether this DB2 member can coordinate parallel processing.
PARALLELISM ASSISTANT
Indicates whether this DB2 member can assist with parallel processing.

If the output indicates that either the lock structure or SCA are 0% in use, that does
not necessarily mean that the structure is empty. It could mean that the structures
are very large and that the number of locks held or the number of records in the
SCA is less than 1%.

Description of message DSN7101I:


GROUP
The name of the data sharing group
GROUP LEVEL
A string of three numeric characters that denotes:
v DB2 version
v DB2 release
v DB2 modification level
This is the highest release with which any DB2 in the data sharing group
have been started.

Examples
Example 1: The following sample output for a data sharing group can be generated
by the command:
-DB1A DIS GROUP

Chapter 2. Commands 127


-DISPLAY GROUP (DB2)
DSN7100I -DB1A DSN7GCMD
*** BEGIN DISPLAY OF GROUP(DSNDB10 ) GROUP LEVEL(610)
GROUP ATTACH NAME(DB10)
--------------------------------------------------------------------
DB2 DB2 SYSTEM IRLM
MEMBER ID SUBSYS CMDPREF STATUS LVL NAME SUBSYS IRLMPROC
-------- --- ---- -------- -------- --- -------- ---- --------
DB1A 1 DB1A -DB1A ACTIVE 610 MVSA DJ1A DB1AIRLM
DB1B 2 DB1B -DB1B ACTIVE 610 MVSB DJ1B DB1BIRLM
DB1C 3 DB1C -DB1C ACTIVE 610 MVSC DJ1C DB1CIRLM
DB1D 4 DB1D -DB1D FAILED 610 MVSD DJ1D DB1DIRLM
DB1E 5 DB1E -DB1E QUIESCED 610 MVSE DJ1E DB1EIRLM
DB1F 6 DB1F -DB1F ACTIVE 610 MVSF DJ1F DB1FIRLM
DB1G 7 DB1G -DB1G ACTIVE 610 MVSG DJ1G DB1GIRLM
--------------------------------------------------------------------
SCA STRUCTURE SIZE: 1024 KB, STATUS= AC, SCA IN USE: 11 %
LOCK1 STRUCTURE SIZE: 1536 KB
NUMBER LOCK ENTRIES: 262144
NUMBER LIST ENTRIES: 7353, LIST ENTRIES IN USE: 0
*** END DISPLAY OF GROUP(DSNDB10 )
DSN9022I -DB1A DSN7GCMD 'DISPLAY GROUP ' NORMAL COMPLETION

Example 2: In a non-data-sharing environment, the following sample output is


generated by the command:
-DB1A DISPLAY GROUP

DSN7100I -DB1A DSN7GCMD


*** BEGIN DISPLAY OF GROUP(.......) GROUP LEVEL(...)
GROUP ATTACH NAME(....)
--------------------------------------------------------------------
DB2 DB2 SYSTEM IRLM
MEMBER ID SUBSYS CMDPREF STATUS LVL NAME SUBSYS IRLMPROC
-------- --- ---- -------- -------- --- -------- ---- --------
........ 0 DB1A -DB1A ACTIVE 610 MVSA DJ1A DB1AIRLM
--------------------------------------------------------------------
*** END DISPLAY OF GROUP(DSNDB10)
DSN9022I -DB1A DSN7GCMD 'DISPLAY GROUP ' NORMAL COMPLETION

Example 3: Using the DETAIL option, you can obtain more information about the
data sharing group as shown in the following example using the command:
-DB1A DIS GROUP DETAIL

128 Command Reference


-DISPLAY GROUPBUFFERPOOL (DB2)
DSN7100I -DB1A DSN7GCMD
*** BEGIN DISPLAY OF GROUP(DSNCAT ) GROUPLEVEL(610)
--------------------------------------------------------------------
DB2 SYSTEM IRLM
MEMBER ID SUBSYS CMDPREF STATUS NAME LVL SUBSYS IRLMPROC
-------- --- ---- -------- -------- -------- --- ---- --------
DB1A 1 DB1A -DB1A ACTIVE MVSA 610 AR21 ARLM21
DB1B 2 DB1B -DB1B ACTIVE MVSB 610 BR21 BRLM21
DB1C 3 DB1C -DB1C ACTIVE MVSC 510 CRLM CRLM21
DB2D 4 DB2D -DB2D FAILED MVSD 610 DR21 DRLM21
DB2E 5 DB2E -DB2E QUIESCED MVSE 610 ER21 ERLM21
DB2F 6 DB2F -DB2F ACTIVE MVSF 610 FR21 FRLM21
DB2G 7 DB2G -DB2G ACTIVE MVSG 610 GR21 GRLM21
--------------------------------------------------------------------
DB2 PARALLEL PARALLEL
MEMBER COORDINATOR ASSISTANT
-------- ----------- ---------
DB2A YES NO
DB2B YES YES
DB2B YES YES
DB1C **** ****
DB2D **** ****
DB2E **** ****
DB2F NO YES
DB2G NO NO
--------------------------------------------------------------------
SCA STRUCTURE SIZE: 1024 KB, STATUS= AC, SCA IN USE: 11 %
LOCK1 STRUCTURE SIZE: 1536 KB, LOCK1 IN USE: < 1 %
NUMBER LOCK ENTRIES: 262144, LOCK ENTRIES IN USE: 33
NUMBER LIST ENTRIES: 7353, LIST ENTRIES IN USE: 0
*** END DISPLAY OF GROUP(DSNCAT )
DSN9022I -DB1A DSN7GCMD 'DISPLAY GROUP ' NORMAL COMPLETION

-DISPLAY GROUPBUFFERPOOL (DB2)


The DB2 command DISPLAY GROUPBUFFERPOOL displays information about the
status of DB2 group buffer pools. It can also display related statistics.

Abbreviation: -DIS GBPOOL

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Group

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v DISPLAY privilege
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Chapter 2. Commands 129


-DISPLAY GROUPBUFFERPOOL (DB2)
Syntax

 DISPLAY GROUPBUFFERPOOL 
(*) *
, TYPE ( GCONN )
MCONN
(  gbpname ) NOCACHE
structure-name

 
MDETAIL GDETAIL
INTERVAL INTERVAL
( ) ( )
* *

 
NO
CONNLIST ( YES )

Option descriptions
(*) Displays the group buffer pool status for all group buffer pools.
gbpname
Names the group buffer pool for which status is to be displayed.
v 4-KB group buffer pools are named GBP0, GBP1, ..., GBP49.
v 8-KB group buffer pools are named GBP8K0, GBP8K1, ... , GBP8K9.
v 16-KB group buffer pools are named GBP16K0, GBP16K1, ... , GBP16K9.
v 32-KB group buffer pools are named GBP32K, GBP32K1, ... , GBP32K9.
(structure-name)
Names the backing coupling facility structure for the group buffer pool. The
coupling facility structure name has the following format:
groupname_gbpname

where groupname is the DB2 data sharing group name and the underscore (_)
separates groupname and gbpname.
TYPE
Indicates the type of group buffer pools (among those that are specified) for
which information is displayed.
(*) All group buffer pools specified. This is the default.
(GCONN)
Group buffer pools that are currently connected to any member of the data
sharing group. The connection can be “active” or “failed-persistent”.
(MCONN)
Group buffer pools that are currently connected to the member to which the
command is directed.
(NOCACHE)
Group buffer pools that have the GBPCACHE attribute set to NO.
MDETAIL
Shows a detailed statistical report for the specified group buffer pools, reflecting

130 Command Reference


-DISPLAY GROUPBUFFERPOOL (DB2)
the member’s activity for each group buffer pool. If the member to which the
command is directed has never been actively connected to the group buffer
pool, no detail report is shown.
(INTERVAL)
Shows incremental statistics. The values displayed are accumulated since
the last MDETAIL(INTERVAL) report for this member, if there was one. This
is the default.
(*) Shows cumulative statistics. The values displayed are accumulated since
this member first connected to the group buffer pool.
GDETAIL
Shows a detailed statistical report for the specified group buffer pools, reflecting
the activity of the entire group for each group buffer pool. If the member to
which the command is directed is not actively connected to the group buffer
pool, no detail report is shown.
(INTERVAL)
Shows incremental statistics. The values displayed are accumulated since
the last GDETAIL(INTERVAL) report, if there was one. This is the default.
(*) Shows cumulative statistics. The values displayed are accumulated since
the group buffer pool was most recently allocated or re-allocated.
CONNLIST
Specifies whether a connection list report is shown for the specified group
buffer pools, listing the connection names of the subsystems that are currently
connected to the group buffer pools and their connection status.
(NO)
Do not show the connection list report.
(YES)
Show the connection list report.

Output
The three report types are:
v A summary report
v A group detail report
v A member detail report

These reports are described here.

Summary report
You can display summary information about group buffer pools. The report indicates
whether this DB2 is actively connected to the group buffer pools you requested
information for. The summary report also shows the following information:

Group buffer pool characteristics:


v Threshold values
v Directory-to-data entry ratio (both pending and current)
v Checkpoint interval
v Recovery status (whether damage assessment is pending)

CFRM policy information about the group buffer pool:


v The allocation value specified in the CFRM policy and whether the group buffer
pool is currently allocated in the coupling facility.

Chapter 2. Commands 131


-DISPLAY GROUPBUFFERPOOL (DB2)
v The actual allocated size (which can be different from that specified in the CFRM
policy) and volatility status. DB2 requests non-volatile storage; however, it can
allocate in a volatile structure.
v The actual number of directory entries, data pages, and connection to the group
buffer pool.
The summary report contains additional information as follows:
AUTOMATIC RECOVERY
Indicates whether automatic recovery is allowed for this group buffer pool.
DUPLEX
Indicates the current option for the group buffer pool that is specified in the
active CFRM policy.
REBUILD STATUS
Indicates whether a rebuild is in progress for this group buffer pool. If so,
the phase of the rebuild is indicated: QUIESCE, CONNECT, or CLEANUP. If
the rebuild is in the process of stopping, the status indicates STOPPING.
DUPLEXING STATUS
Indicates the current state of the group buffer pool with respect to
duplexing.
CFNAME, CFLEVEL
Indicates the name and level of the coupling facility in which the group
buffer pool is allocated. If the group buffer pool is duplexed, this is the
coupling facility name and level associated with the primary group buffer
pool.

# Note: The DB2 CFLEVEL displayed in the DISPLAY


# GROUPBUFFERPOOL Summary Report may be lower than the
# actual CFLEVEL (displayed by the MVS D CF Command), but will
# never be lower than what is required to perform your structure
# operations. For detailed CFLEVEL information, see ″Understanding
# the CFLEVEL Returned by XCF and XES Services,″ in OS/390 MVS
# Programming: Sysplex Services Guide.
LAST GROUP BUFFER POOL CHECKPOINT
Indicates the date and time of the last group buffer pool checkpoint, the
LRSN that was recorded at that checkpoint, and the member name of the
group buffer pool structure owner.

Group detail report


The group detail report shows detailed statistical information reflecting the activity of
the entire group for the specified group buffer pools. This statistical information is
helpful in tuning the size and other characteristics of group buffer pools. See
Chapter 6 of DB2 Data Sharing: Planning and Administration for more information
about using this information. The report includes the same information as in the
summary report with the addition of:
READS
Information about reads.
This is a detailed accounting of the number of reads against the group
buffer pool, including the following:
v The number of reads where data was returned.

132 Command Reference


-DISPLAY GROUPBUFFERPOOL (DB2)
v The number of reads where data was not returned, broken down to
include more detailed information about whether the page was cached in
the coupling facility or not, and whether directory entries needed to be
created to fulfill requests for data.
WRITES
Information about writes.
This includes the number of writes for clean pages and changed pages,
and how many writes failed because there was not enough storage in the
group buffer pool.
CHANGED PAGES SNAPSHOT VALUE
The number of changed pages currently in the group buffer pool (a
snapshot value).
RECLAIMS
The number of reclaims of directory entries and data pages.
CASTOUTS
The number of castouts.
CROSS INVALIDATIONS
The number of cross-invalidations that occurred because of directory
reclaims and because of writes.
DUPLEXING STATISTICS FOR GBPn
This section of output indicates detailed duplexing statistics as follows:
CHANGED PAGES
Indicates the number of changed pages that are written to the
secondary group buffer pool. If the group buffer pool has been
duplexed for the entire reporting interval, this number approximates
the CHANGED PAGES counter that is reported in message
DSNB786I for the primary group buffer pool. The counts may not be
exactly the same, due to timing periods for gathering the counter
information for display or previous transaction failures that may
have occurred.
FAILED DUE TO LACK OF STORAGE
Indicates the number of writes to the secondary group buffer pool
that failed due to a lack of storage.
CHANGED PAGES SNAPSHOT VALUE
Indicates the number of changed pages that are currently cached in
the secondary group buffer pool. This number approximates the
CHANGED PAGES SNAPSHOT VALUE for the primary group
buffer pool, but is probably not identical due to the asynchronous
nature of gathering statistics for the two different coupling facility
structures.

Member detail report


The member detail report includes the summary report and additional information
about how a particular member’s system is responding to the current environment.
It categorizes reads and writes as synchronous or asynchronous. A large number of
synchronous reads or writes can indicate that you need to tune your group buffer
pools.
GBP CHECKPOINTS TRIGGERED
The number of checkpoints that occurred for this group buffer pool.

Chapter 2. Commands 133


-DISPLAY GROUPBUFFERPOOL (DB2)
PARTICIPATION IN REBUILD
The number of times this member participated in a rebuild for this group
buffer pool.
CASTOUTS
This section of output indicates detailed statistics for castout processing as
follows:
PAGES CAST OUT
Indicates how many data pages were cast out of the group buffer
pool by this member.
UNLOCK CASTOUT
The number of times that DB2 issued an unlock request to the
coupling facility for castout I/Os that completed. As pages are cast
out to disk, they are ″locked for castout″ in the coupling facility. The
castout lock ensures that only one system is doing castout for a
given page.
DB2 usually includes multiple pages in the write I/O request to disk
for castout. Therefore, the UNLOCK CASTOUT counter should
always be less than or equal to the value of the PAGES CASTOUT
counter; it should be significantly less if multiple pages are written
per I/O. For example, if there are 4 pages written per castout write
I/O on average, then PAGES CASTOUT should be four times larger
than UNLOCK CASTOUT.
READ CASTOUT CLASS
Number of requests made to the group buffer pool to determine
which pages belonging to a given page set or partition are cached
in the group buffer pool as changed pages and thus need to be
cast out.
READ CASTOUT CLASS is issued by the page set or partition
castout owner, and it is also issued by the group buffer pool
structure owner when the GBPOOLT threshold has been reached.
READ CASTOUT STATISTICS
The number of requests that are issued by the group buffer pool
structure owner when the GBPOOLT threshold is reached. This
determines which castout classes have changed pages. Generally
READ CASTOUT STATISTICS is issued only once or twice for each
occurrence of the GBPOOLT threshold.
READ DIRECTORY INFO
The number of requests to read the directory entries of all changed
pages in the group buffer pool. The group buffer pool structure
owner issues these requests at group buffer pool checkpoints. The
purpose of the request is to determine the oldest recovery LRSN to
use in case the group buffer pool fails. This recovery LRSN is
displayed in message DSNB798I.
The request to read directory information might be issued several
times for each group buffer pool checkpoint. If you see an
abnormally high number here, it might be that the requests are
being cut short by the model-dependent timeout criteria of the
coupling facility. To help alleviate this problem, upgrade those
coupling facilities to CFLEVEL=2 or above.

134 Command Reference


-DISPLAY GROUPBUFFERPOOL (DB2)
OTHER INTERACTIONS
This section of the output lists details of other interactions that this DB2 has
with this group buffer pool.
REGISTER PAGE
The number of times that DB2 registered interest to the group
buffer pool for a single page. These are register-only requests,
meaning that DB2 is not requesting that any data be returned for
the page because it knows that there is no data cached in the
group buffer pool for this page. The REGISTER PAGE request is
made only to create a directory entry for the page for
cross-invalidation when downgrading the P-lock on a page set or
partition from S mode to IS mode, or from SIX mode to IX mode.
UNREGISTER PAGE
The number of times that DB2 reversed registered interest from the
group buffer pool for a single page. This is generally done as DB2
uses pages from the local buffer pool that belong to partitions or
pagesets that are group buffer pool dependent.
DELETE NAME
The number of times that DB2 issued a request to the group buffer
pool to delete directory and data entries that were associated with a
given page set or partition. DB2 issues this request:
v When it converts a page set or partition from group buffer pool
dependent to non group buffer pool dependent.
v When the first DB2 member opens the object for GBPCACHE
ALL objects.
READ STORAGE STATS
The number of times that DB2 requested statistics information from
the group buffer pool. This number should usually be relatively low.
It is issued once per group buffer pool checkpoint by the group
buffer pool structure owner. It is also issued for DISPLAY
GROUPBUFFERPOOL GDETAIL requests and to record IFCID
0254.
DUPLEXING STATISTICS FOR GBP0-SEC
This section of the output lists details of other interactions that this DB2 has
with this group buffer pool.
CHANGED PAGES
Indicates the number of changed pages written to the secondary
group buffer pool. This number approximates the sum of the
synchronous writes of changed pages to the primary group buffer
pool and the asynchronous writes of changed pages to the primary
group buffer pool. The counts may not be exactly the same, due to
timing periods for gathering the counter information for display or
previous transaction failures that may have occurred.
FAILED DUE TO LACK OF STORAGE
Indicates the number of writes to the secondary group buffer pool
that failed due to a lack of storage.
COMPLETION CHECKS SUSPENDED
Indicates the number of times DB2 checked for the completion of
the write of a changed page to the secondary group buffer pool, but
the write had not yet completed; DB2 suspends the execution unit
until the write to the secondary group buffer pool completes.

Chapter 2. Commands 135


-DISPLAY GROUPBUFFERPOOL (DB2)
DELETE NAME LIST
Indicates the number of DELETE NAME LIST requests to delete a set of
pages from the secondary group buffer pool that have just been cast out
from the primary group buffer pool.
READ CASTOUT STATISTICS
Indicates the number of READ CASTOUT STATITICS requests to check for
orphaned data entries in the secondary group buffer pool. The DB2 member
that is the group buffer pool structure owner periodically issues these
requests to determine whether garbage collection is necessary.
DELETE NAME
Indicates the number of DELETE NAME requests to delete orphaned data
entries from the secondary group buffer pool. The DB2 member that is the
group buffer pool structure owner issues these requests if it determines that
garbage collection is necessary.

Examples
Example 1: This is an example of a summary report that can be produced by the
following command:
-DISPLAY GROUPBUFFERPOOL(GBP29)

Message DSNB799I is displayed if the group buffer pool is duplexed and the
secondary group buffer pool is currently allocated. If a secondary group buffer pool
is not allocated, message DSNB799I is not included in the output.

136 Command Reference


-DISPLAY GROUPBUFFERPOOL (DB2)
DSNB750I - DISPLAY FOR GROUP BUFFER POOL GBP29 FOLLOWS
DSNB755I - DB2 GROUP BUFFER POOL STATUS
CONNECTED = YES
CURRENT DIRECTORY TO DATA RATIO = 5
PENDING DIRECTORY TO DATA RATIO = 5
CURRENT GBPCACHE ATTRIBUTE = YES
PENDING GBPCACHE ATTRIBUTE = YES
DSNB756I - CLASS CASTOUT THRESHOLD = 10%
GROUP BUFFER POOL CASTOUT THRESHOLD = 50%
GROUP BUFFER POOL CHECKPOINT INTERVAL = 8 MINUTES
RECOVERY STATUS = NORMAL
AUTOMATIC RECOVERY = Y
DSNB757I - MVS CFRM POLICY STATUS FOR DSNCAT_GBP29 = NORMAL
MAX SIZE INDICATED IN POLICY = 2048 KB
DUPLEX INDICATOR IN POLICY = ENABLED
CURRENT DUPLEXING MODE = DUPLEX
ALLOCATED = YES
DSNB758I - ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
REBUILD STATUS = DUPLEXED
CFNAME = CACHE01
CFLEVEL = 5
DSNB759I - NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
NUMBER OF CONNECTIONS = 2
DSNB798I - LAST GROUP BUFFER POOL CHECKPOINT
17:08:41 OCT 16, 1997
GBP CHECKPOINT RECOVERY LRSN = AF6BBAEF3307
STRUCTURE OWNER = V61B
DSNB799I - SECONDARY GBP ATTRIBUTES
ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
CFNAME = LF01
CFLEVEL = 5
NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
DSNB790I - DISPLAY FOR GROUP BUFFER POOL GBP29 IS COMPLETE
DSN9022I - DSNB1CMD '-DISPLAY GBPOOL' NORMAL COMPLETION

Example 2: Assume you want a summary report about group buffer pool
twenty-nine, including all connections to that group buffer pool. Enter the following
command:
-DISPLAY GROUPBUFFERPOOL(GBP29) CONNLIST(YES)

This command produces output similar to the following output:

Chapter 2. Commands 137


-DISPLAY GROUPBUFFERPOOL (DB2)
DSNB750I - DISPLAY FOR GROUP BUFFER POOL GBP29 FOLLOWS
DSNB755I - DB2 GROUP BUFFER POOL STATUS
CONNECTED = YES
CURRENT DIRECTORY TO DATA RATIO = 5
PENDING DIRECTORY TO DATA RATIO = 5
CURRENT GBPCACHE ATTRIBUTE = YES
PENDING GBPCACHE ATTRIBUTE = YES
DSNB756I - CLASS CASTOUT THRESHOLD = 10%
GROUP BUFFER POOL CASTOUT THRESHOLD = 50%
GROUP BUFFER POOL CHECKPOINT INTERVAL = 8 MINUTES
RECOVERY STATUS = NORMAL
AUTOMATIC RECOVERY = Y
DSNB757I - MVS CFRM POLICY STATUS FOR DSNCAT_GBP29 = NORMAL
MAX SIZE INDICATED IN POLICY = 2048 KB
DUPLEX INDICATOR IN POLICY = ENABLED
CURRENT DUPLEXING MODE = SIMPLEX
ALLOCATED = YES
DSNB758I - ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
REBUILD STATUS = DUPLEXED
CFNAME = CACHE01
CFLEVEL = 5
DSNB759I - NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
NUMBER OF CONNECTIONS = 2
DSNB798I - LAST GROUP BUFFER POOL CHECKPOINT
17:08:41 OCT 16, 1997
GBP CHECKPOINT RECOVERY LRSN = AF6BBAEF3307
STRUCTURE OWNER = V61B
DSNB799I - SECONDARY GBP ATTRIBUTES
ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
CFNAME = LF01
CFLEVEL = 5
NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
DSNB766I - THE CONNLIST REPORT FOLLOWS
DSNB767I - CONNECTION NAME = DB2_V61B , CONNECTION STATUS = D
CONNECTOR'S RELEASE = 6100
DSNB767I - CONNECTION NAME = DB2_V61A , CONNECTION STATUS = D
CONNECTOR'S RELEASE = 6100
DSNB769I - THE CONNLIST REPORT IS COMPLETE
DSNB790I - DISPLAY FOR GROUP BUFFER POOL GBP29 IS COMPLETE
DSN9022I - DSNB1CMD '-DISPLAY GBPOOL' NORMAL COMPLETION

Example 3: This example shows a group detail report that is produced by the
command:
-DISPLAY GROUPBUFFERPOOL(GBP29) GDETAIL(*)

Message DSNB762I is displayed in the output only if the secondary group buffer
pool is allocated.

138 Command Reference


-DISPLAY GROUPBUFFERPOOL (DB2)
DSNB750I - DISPLAY FOR GROUP BUFFER POOL GBP29 FOLLOWS
DSNB755I - DB2 GROUP BUFFER POOL STATUS
CONNECTED = YES
CURRENT DIRECTORY TO DATA RATIO = 5
PENDING DIRECTORY TO DATA RATIO = 5
CURRENT GBPCACHE ATTRIBUTE = YES
PENDING GBPCACHE ATTRIBUTE = YES
DSNB756I - CLASS CASTOUT THRESHOLD = 10%
GROUP BUFFER POOL CASTOUT THRESHOLD = 50%
GROUP BUFFER POOL CHECKPOINT INTERVAL = 8 MINUTES
RECOVERY STATUS = NORMAL
AUTOMATIC RECOVERY = Y
DSNB757I - MVS CFRM POLICY STATUS FOR DSNCAT_GBP29 = NORMAL
MAX SIZE INDICATED IN POLICY = 2048 KB
DUPLEX INDICATOR IN POLICY = ENABLED
CURRENT DUPLEXING MODE = DUPLEX
ALLOCATED = YES
DSNB758I - ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
REBUILD STATUS = DUPLEXED
CFNAME = CACHE01
CFLEVEL = 5
DSNB759I - NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
NUMBER OF CONNECTIONS = 2
DSNB798I - LAST GROUP BUFFER POOL CHECKPOINT
17:08:41 OCT 16, 1997
GBP CHECKPOINT RECOVERY LRSN = AF6BBAEF3307
STRUCTURE OWNER = V61B
DSNB799I - SECONDARY GBP ATTRIBUTES
ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
CFNAME = LF01
CFLEVEL = 5
NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
DSNB783I - CUMULATIVE GROUP DETAIL STATISTICS SINCE 17:08:35 OCT 16,
1997
DSNB784I - GROUP DETAIL STATISTICS
READS
DATA RETURNED = 4
DSNB785I - DATA NOT RETURNED
DIRECTORY ENTRY EXISTED = 0
DIRECTORY ENTRY CREATED = 45
DIRECTORY ENTRY NOT CREATED = 0, 0
DSNB786I - WRITES
CHANGED PAGES = 5
CLEAN PAGES = 0
FAILED DUE TO LACK OF STORAGE = 0
CHANGED PAGES SNAPSHOT VALUE = 5
DSNB787I - RECLAIMS
FOR DIRECTORY ENTRIES = 0
FOR DATA ENTRIES = 0
CASTOUTS = 0

Chapter 2. Commands 139


-DISPLAY GROUPBUFFERPOOL (DB2)
DSNB788I - CROSS INVALIDATIONS
DUE TO DIRECTORY RECLAIMS = 0
DUE TO WRITES = 0
EXPLICIT = 0
DSNB762I - DUPLEXING STATISTICS FOR GBP29-SEC
WRITES
CHANGED PAGES = 5
FAILED DUE TO LACK OF STORAGE = 0
CHANGED PAGES SNAPSHOT VALUE = 5
DSNB790I - DISPLAY FOR GROUP BUFFER POOL GBP29 IS COMPLETE
DSN9022I - DSNB1CMD '-DISPLAY GBPOOL' NORMAL COMPLETION

Example 4: This example shows the member detail section from the report that is
produced by the command:
-DISPLAY GROUPBUFFERPOOL(GBP29) MDETAIL(*)

Messages DSNB764I and DSNB793I are displayed in the output only if the
secondary group buffer pool is allocated.

140 Command Reference


-DISPLAY GROUPBUFFERPOOL (DB2)
DSNB750I - DISPLAY FOR GROUP BUFFER POOL GBP29 FOLLOWS
DSNB755I - DB2 GROUP BUFFER POOL STATUS
CONNECTED = YES
CURRENT DIRECTORY TO DATA RATIO = 5
PENDING DIRECTORY TO DATA RATIO = 5
CURRENT GBPCACHE ATTRIBUTE = YES
PENDING GBPCACHE ATTRIBUTE = YES
DSNB756I - CLASS CASTOUT THRESHOLD = 10%
GROUP BUFFER POOL CASTOUT THRESHOLD = 50%
GROUP BUFFER POOL CHECKPOINT INTERVAL = 8 MINUTES
RECOVERY STATUS = NORMAL
AUTOMATIC RECOVERY = Y
DSNB757I - MVS CFRM POLICY STATUS FOR DSNCAT_GBP29 = NORMAL
MAX SIZE INDICATED IN POLICY = 2048 KB
DUPLEX INDICATOR IN POLICY = ENABLED
CURRENT DUPLEXING MODE = DUPLEX
ALLOCATED = YES
DSNB758I - ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
REBUILD STATUS = DUPLEXED
CFNAME = CACHE01
CFLEVEL = 5
DSNB759I - NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
NUMBER OF CONNECTIONS = 2
DSNB798I - LAST GROUP BUFFER POOL CHECKPOINT
17:08:41 OCT 16, 1997
GBP CHECKPOINT RECOVERY LRSN = AF6BBAEF3307
STRUCTURE OWNER = V61B
DSNB799I - SECONDARY GBP ATTRIBUTES
ALLOCATED SIZE = 2048 KB
VOLATILITY STATUS = VOLATILE
CFNAME = LF01
CFLEVEL = 5
NUMBER OF DIRECTORY ENTRIES = 1950
NUMBER OF DATA PAGES = 389
DSNB772I - CUMULATIVE MEMBER DETAIL STATISTICS SINCE 17:08:41 OCT 16,
1997
DSNB773I - MEMBER DETAIL STATISTICS
SYNCHRONOUS READS
DUE TO BUFFER INVALIDATION
DATA RETURNED = 0
DATA NOT RETURNED = 0
DSNB774I - DUE TO DATA PAGE NOT IN BUFFER POOL
DATA RETURNED = 0
DATA NOT RETURNED = 0
DSNB775I - PREFETCH READS
DATA NOT RETURNED = 0
REGISTER PAGE LIST NOT AVAILABLE
DATA RETURNED = 0
DSNB789I - REGISTER PAGE LIST = 0
RETRIEVE CHANGED PAGES = 0
RETRIEVE CLEAN PAGES = 0
FAILED READS DUE TO LACK OF STORAGE = 0
DSNB776I - SYNCHRONOUS WRITES
CHANGED PAGES = 5
CLEAN PAGES = 0
DSNB777I - ASYNCHRONOUS WRITES
CHANGED PAGES = 0
CLEAN PAGES = 0
FAILED WRITES DUE TO LACK OF STORAGE = 0

Chapter 2. Commands 141


-DISPLAY GROUPBUFFERPOOL (DB2)
DSNB778I - CASTOUT THRESHOLDS DETECTED
FOR CLASSES = 0
FOR GROUP BUFFER POOL = 0
GBP CHECKPOINTS TRIGGERED = 0
PARTICIPATION IN REBUILD = 1
DSNB796I - CASTOUTS
PAGES CASTOUT = 0
UNLOCK CASTOUT = 0
READ CASTOUT CLASS = 0
READ CASTOUT STATISTICS = 0
READ DIRECTORY INFO = 0
DSNB779I - ENGINES NOT AVAILABLE
FOR CASTOUT = 0
FOR WRITING = 0
DSNB797I - OTHER INTERACTIONS
REGISTER PAGE = 0
UNREGISTER PAGE = 0
DELETE NAME = 0
READ STORAGE STATISTICS = 0
EXPLICIT CROSS INVALIDATIONS = 0
ASYNCHRONOUS GBP REQUESTS = 0
DSNB764I - DUPLEXING STATISTICS FOR GBP29-SEC
WRITES
CHANGED PAGES = 5
FAILED DUE TO LACK OF STORAGE = 0
ASYNCHRONOUS COMPLETION CHECKS = 0
DSNB793I - DELETE NAME LIST = 0
READ CASTOUT STATISTICS = 0
DELETE NAME = 0
OTHER ASYNCHRONOUS GBP REQUESTS = 0
DSNB790I - DISPLAY FOR GROUP BUFFER POOL GBP29 IS COMPLETE
DSN9022I - DSNB1CMD '-DISPLAY GBPOOL' NORMAL COMPLETION

142 Command Reference


-DISPLAY LOCATION (DB2)

-DISPLAY LOCATION (DB2)


If you specify the DETAIL option, which is optional, each line could be followed by
information regarding conversations owned by DB2 system threads that are
communicating with the location.

The information returned by the DISPLAY LOCATION command reflects a dynamic


status. By the time the information is displayed, it is possible that the status has
changed.

Abbreviation: -DIS LOC

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v DISPLAY privilege
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

(*)
 DISPLAY LOCATION 
, DETAIL

(  location-name )
partial-location*
<luname>
ipaddr

Option descriptions
(*) Displays information for all remote locations.
(location-name)
Lists one or more location names, separated by commas. If location-name is
not specified, information for all remote locations is displayed.
Because DB2 does not receive a location name from requesters that are not
DB2 for OS/390 and z/OS subsystems, you can enter the LUNAME or IP
address of such a requester. Enclose the LUNAME by the less-than (<) and
greater-than (>) symbols. Enter the IP address in the form nnn.nnn.nnn.nnn.
For example, -DISPLAY LOCATION(<LULA>) displays information about a
remote location (that is not DB2 for OS/390 and z/OS) with the LUNAME of

Chapter 2. Commands 143


-DISPLAY LOCATION (DB2)
LULA. -DISPLAY LOCATION(124.63.51.17) displays information about clients
at the remote TCP/IP host whose dotted decimal IP address is 124.63.51.17.
(partial-location*)
Selects all location names that begin with the string partial-location and can end
with any string, including the empty string. For example, LOCATION(ABC*)
selects all location names that begin with the string 'ABC'.
You can use an asterisk (*) when specifying a LUNAME in the same manner as
described above for location names that are not DB2 for OS/390 and z/OS
subsystems. For example, -DISPLAY LOCATION(<LULA*) selects all remote
locations (that are not DB2 for OS/390 and z/OS) with an LUNAME that begins
with the string 'LULA'.
<luname>
Requests information about the remote clients that are connected to DDF
through the remote SNA LU that is specified.
(ipaddr)
Requests information about the clients that are connected to DDF through the
remote TCP/IP host. nnn.nnn.nnn.nnn is the dotted decimal IP address.
DETAIL
Displays additional information about conversation activity for DB2 system
threads, as shown in “Example 2” on page 145.

Output
The DISPLAY LOCATION command displays the following output:
LOCATION
The LOCATION of the remote system.
PRDID
The product identifier (PRDID) of the remote system. The PRDID is
displayed in the form nnnvvrrm, where:
nnn The database product
vv The product version
rr The product release
m The product modification level
LINKNAME
The address (LU name or IP address) of the remote system.
REQUESTERS
The number of active threads from the local subsystem that are accessing
the remote system.
SERVERS
The number of threads from the remote system that are accessing the local
subsystem.
CONVERSATIONS
The total number of conversations or sockets related to the partner system.

Examples
Example 1: Display information about threads and conversations with specific
remote locations, using the following command:
-DISPLAY LOCATION(SAN_JOSE,SAN_FRANCISCO)

DSNL200I - DISPLAY LOCATION REPORT FOLLOWS-

144 Command Reference


-DISPLAY LOCATION (DB2)
LOCATION PRDID LINKNAME REQUESTERS SERVERS CONVS
SAN_JOSE DSN05010 LUND1 1 0 1
SAN_FRANCISCO DSN05010 LUND3 1 0 1
DISPLAY LOCATION REPORT COMPLETE

Example 2: Display information about threads and conversations with all remote
locations. Additionally, display detail conversation information about DB2 system
threads that communicate with other locations. This is an example of the output
generated by the following command:
-DISPLAY LOCATION DETAIL

DSNL200I - DISPLAY LOCATION REPORT FOLLOWS-


LOCATION PRDID LINKNAME REQUESTERS SERVERS CONVS
SAN_JOSE DSN05010 LUND1 1 0 3
-SYSTASK SESSID A ST TIME
-SYSCON-O 00D359691359EE80 S 9128009214880
-SYSCON-I 00D359691359EE81 W R 9128009214881
MENLO_PARK DSN05010 LUND2 1 0 4
-SYSTASK SESSID A ST TIME
-SYSCON-O 00D359691359EE82 S 9128009214882
-SYSCON-I 00D359691359EE83 W R 9128009214883
-RESYNC 00D359691359EE84 V R 9128009214884
SAN_FRANCISCO DSN05010 LUND3 1 0 6
-SYSTASK SESSID A ST TIME
-SYSCON-O 0000000000000000 C 9128009214885
-SYSCON-I 00D359691359EE86 W R 9128009214886
-RESYNC 00D359691359EE87 W R 9128009214887
-RESYNC 00D359691359EE88 W R 9128009214888
-RESYNC 00D359691359EE89 W R 9128009214889
DISPLAY LOCATION REPORT COMPLETE

Example 3: Display information for a DB2 that is connected to the following DRDA
partners:
v A non-MVS server named DRDALOC via TCP/IP.
v Several TCP/IP clients from the same TCP/IP host as the DRDALOC server.
v A DB2 for MVS server named DB2SERV via SNA.
DISPLAY LOCATION(*)

DSNL200I - DISPLAY LOCATION REPORT FOLLOWS -


LOCATION PRDID LINKNAME REQUESTERS SERVERS CONVS
DRDALOC SQL03030 124.63.51.17 3 0 3
124.63.51.17 SQL03030 124.63.51.17 0 15 15
DB2SERV DSN05010 LULA 1 0 1
DISPLAY LOCATION REPORT COMPLETE

Example 4: The following example assumes DB2 is connected to the following


DRDA partners:
v DB2A is connected to this DB2, using TCP/IP for DRDA connections and SNA for
DB2 private protocol connections.
v DB2SERV is connected to this DB2 using only SNA.
DISPLAY LOCATION(*)

DSNL200I - DISPLAY LOCATION REPORT FOLLOWS -


LOCATION PRDID LINKNAME REQUESTERS SERVERS CONVS
DB2A DSN05010 LUDB2A 3 4 9
DB2A DSN05010 124.38.54.16 2 1 3
DB2SERV DSN04010 LULA 1 1 3
DISPLAY LOCATION REPORT COMPLETE

Chapter 2. Commands 145


DISPLAY LOG (DB2)

-DISPLAY LOG (DB2)


The DB2 command DISPLAY LOG displays log information and the status of the
offload task.

Abbreviation: DIS LOG

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the privilege set of the process must include one of the
following authorities:
v DISPLAY privilege
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands that are issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

 DISPLAY LOG 

Usage notes
Information provided by the DISPLAY LOG command: You can use the
DISPLAY LOG command to view the current LOGLOAD setting, including
information about the current active log data sets and status of the offload task. You
can obtain additional information about log data sets and checkpoint information by
using the Print Log Map utility (DSNJU004). For more information about the Print
Log Map utility, see Part 3 of DB2 Utility Guide and Reference.

Examples
Example 1: Display log information and status of the offload task.
DISPLAY LOG

This command produces output similar to the following output:


DSNJ370I - DSNJCOOA LOG DISPLAY
CURRENT COPY1 LOG = DSNC710.LOGCOPY1.DS03 IS 22% FULL
CURRENT COPY2 LOG = DSNC710.LOGCOPY2.DS03 IS 22% FULL
H/W RBA = 0000039A9F24, LOGLOAD = 150000
FULL LOGS TO OFFLOAD = 2 OF 6, OFFLOAD TASK IS (BUSY,ALLC)
DSNJ371I - DB2 RESTARTED 14:06:23 MAY 22, 1998
RESTART RBA 0000039A8000
DSN9002I - DSNJC001 'DIS LOG' NORMAL COMPLETION

This example shows the following information:

146 Command Reference


DISPLAY LOG (DB2)
v The active log data sets are 22% full. If you are running dual logs and the
percentages are different, the log data sets are of different sizes. DB2 switches
both active logs when one reaches the end of the file. This can result in unused
active log space if one log data set is larger than the other.
v The current LOGLOAD setting is 150000 log records between system
checkpoints. You can modify this value using the SET LOG command.
v Two of the six active log data sets require archiving. The status of the offload
task includes the indicator that it is busy, allocating an archive log data set. This
might be an indication of an outstanding tape mount on the system console. If
the status remains busy and no longer seems to be functioning, you can
terminate the task, and then restart it using the ARCHIVE LOG CANCEL
OFFLOAD command.
v DB2 was started at 14:06:23 on MAY 22, 1998, and began logging at RBA
0000039A8000.

Chapter 2. Commands 147


-DISPLAY PROCEDURE (DB2)

-DISPLAY PROCEDURE (DB2)


The DB2 command DISPLAY PROCEDURE displays statistics about stored
procedures accessed by DB2 applications. This command displays one output line
for each stored procedure that has been accessed by a DB2 application. You can
qualify stored procedure names with a schema name.

The information returned by the DISPLAY PROCEDURE command reflects a


dynamic status. By the time the information is displayed, it is possible that the
status could have changed.

Abbreviation: -DIS PROC

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or a CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Group or local, depending on the value of the SCOPE option.

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v DISPLAY privilege
v SYSOPR, SYSCTRL, or SYSADM authority
v Ownership of the stored procedure

If you specify -DISPLAY PROCEDURE *.* or schema.partial-name*, the privilege


set of the process must include one of the following authorities:
v SYSOPR authority
v SYSCTRL authority
v SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

(*.*)
 DISPLAY PROCEDURE 
, LOCAL
SCOPE ( )
(  schema.procedure-name ) GROUP
schema.partial-name*
procedure-name
partial-name*

Option descriptions
(*.*)
Displays information for all stored procedures in all schemas that have been
accessed by DB2 applications since DB2 was started.

148 Command Reference


-DISPLAY PROCEDURE (DB2)
(schema.procedure-name)
Displays the specified stored procedure in the specified schema.
(schema.partial-name*)
Displays a set of stored procedures in the specified schema that have been
accessed by DB2 applications since DB2 was started. The names of all
procedures in the set begin with partial-name and can end with any string,
including the empty string. For example, PAYROLL.ABC* displays information
for all stored procedure names beginning with ABC in the PAYROLL schema.
(procedure-name)
Displays one or more specific stored procedure names in the SYSPROC
schema. If no procedures are named, DB2 displays information for all stored
procedures that have been accessed by DB2 applications.
(partial-name*)
Displays information for a set of stored procedures in the SYSPROC schema
that have been accessed by DB2 applications since DB2 was started. The
names of all procedures in the set begin with partial-name and can end with
any string, including the empty string. For example, ABC* displays information
for all stored procedures in the SYSPROC schema with names that begin with
ABC.
SCOPE
Specifies the scope of the command.
(LOCAL)
Specifies to display information about procedures on the local member only.
(GROUP)
Specifies to display information about procedures on all members of the
data sharing group.

Output
Sample output: The DISPLAY PROCEDURE command generates the following
output:
DSNX940I - DSNX9DIS DISPLAY PROCEDURE REPORT FOLLOWS -

PROCEDURE STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV


APPL1 STARTED 1 0 0 0
APPL2 STARTED 1 0 0 0
APPL2 STARTED 0 1 2 0
APPL5 STOPREJ 0 0 0 0
APPL6 STOPABN 0 0 0 0
PROC1 STOPQUE 0 0 0 0

DSNX9DIS DISPLAY PROCEDURE REPORT COMPLETE

Description of output: Each output line displays:


PROCEDURE
The name of the stored procedure.
STATUS
The status of the stored procedure of the stored procedure. The possible
values are:
STARTED
Requests for the procedure can be processed.
STOPQUE
Requests are queued.

Chapter 2. Commands 149


-DISPLAY PROCEDURE (DB2)
STOPREJ
Requests are rejected.
STOPABN
Requests are rejected because of abnormal termination.
ACTIVE
The number of threads that are currently running the load module.
QUEUED
The number of threads that are waiting for the procedure to be scheduled.
MAXQUE
The maximum number of threads that have waited concurrently for the
procedure to be scheduled since DB2 was started. DB2 resets this value to
0 each time you execute the START PROCEDURE command.
TIMEOUT
The number of times an SQL CALL statement timed out while waiting for a
request for the procedure to be scheduled. DB2 resets this value to 0 each
time you execute the START PROCEDURE command.

Message DSNX943I lists a range of procedures that are stopped because a STOP
PROCEDURE command included a partial name with a pattern-matching character
(*) such as:
-STOP PROCEDURE(ABC*)

Message DSNX950I is returned when DISPLAY PROCEDURE is issued for a


procedure name that has not been accessed by a DB2 application.

Examples
Example 1: Display information about all stored procedures that have been
accessed by DB2 applications.
-DISPLAY PROCEDURE

This command produces output similar to the following output:


DSNX940I DSNX9DIS - DISPLAY PROCEDURE REPORT FOLLOWS-
PROCEDURE STATUS ACTIVE QUEUED MAXQUE TIMEOUT
USERPRC1 STARTED 0 0 1 0
USERPRC2 STOPQUE 0 5 5 3
USERPRC3 STARTED 2 0 6 0
USERPRC4 STOPREJ 0 0 1 0
DSNX9DIS DISPLAY PROCEDURE REPORT COMPLETE
DSN9022I - DSNX9COM '-DISPLAY PROC' NORMAL COMPLETION

Example 2: Display information about specific stored procedures in the SYSPROC


schema.
-DISPLAY PROCEDURE(SYSPROC.USERPRC2,USERPRC4)

This command produces output similar to the following output:


DSNX940I DSNX9DIS - DISPLAY PROCEDURE REPORT FOLLOWS-

------ SCHEMA=SYSPROC
PROCEDURE STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
USERPRC2 STOPQUE 0 5 5 3 SANDBOX
USERPRC4 STOPREJ 0 0 1 0 SANDBOX
DSNX9DIS DISPLAY PROCEDURE REPORT COMPLETE
DSN9022I - DSNX9COM '-DISPLAY PROC' NORMAL COMPLETION

150 Command Reference


-DISPLAY PROCEDURE (DB2)
Example 3: Display information about stored procedures in the PAYROLL and
HRPROD schemas.
-DISPLAY PROCEDURE(PAYROLL.*,HRPROD.*)

This command produces output similar to the following output:


DSNX940I DSNX9DIS - DISPLAY PROCEDURE REPORT FOLLOWS-

------ SCHEMA=PAYROLL
PROCEDURE STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
PAYPRC1 STARTED 0 0 1 0 PAYROLL
PAYPRC2 STOPQUE 0 5 5 3 PAYROLL
PAYPRC3 STARTED 2 0 6 0 PAYROLL
USERPRC4 STOPREJ 0 0 1 0 SANDBOX

------ SCHEMA=HRPROD
PROCEDURE STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
HRPRC1 STARTED 0 0 1 0 HRPROCS
HRPRC2 STOPREJ 0 0 1 0 HRPROCS
DSNX9DIS DISPLAY PROCEDURE REPORT COMPLETE
DSN9022I - DSNX9COM '-DISPLAY PROC' NORMAL COMPLETION

Example 4: Display information about all stored procedures in the SYSPROC


schema that have been accessed by DB2 applications. Assume the -STOP
PROCEDURE(SYSPROC.*) ACTION(QUEUE) command is in effect at the time this
command is issued.
-DISPLAY PROCEDURE(SYSPROC.*)

This command produces output similar to the following output:


DSNX940I DSNX9DIS - DISPLAY PROCEDURE REPORT FOLLOWS-

------ SCHEMA=SYSPROC
PROCEDURE STATUS ACTIVE QUEUED MAXQUE TIMEOUT WLM_ENV
USERPRC2 STOPQUE 0 5 5 3 SANDBOX
USERPRC4 STOPQUE 0 0 1 0 SANDBOX
PROCEDURES USERFNC2 - USERFNC29999999999 STOP QUEUE
PROCEDURES USERFNC4 - USERFNC49999999999 STOP QUEUE
DSNX9DIS DISPLAY PROCEDURE REPORT COMPLETE
DSN9022I - DSNX9COM '-DISPLAY PROC' NORMAL COMPLETION

Chapter 2. Commands 151


-DISPLAY RLIMIT (DB2)

-DISPLAY RLIMIT (DB2)


The DB2 command DISPLAY RLIMIT displays the current status of the resource
limit facility (governor). If the facility has already been started, -DISPLAY RLIMIT
also displays the ID of the resource limit specification table being used.

Abbreviation: -DIS RLIM

Environment
This command can be issued from an MVS console, a DSN session, a DB2I panel
(DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Authorization
To execute this command, the privilege set of the process must include the
following:
v SYSOPR authority
v SYSCTRL authority
v SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

 DISPLAY RLIMIT 

Example
Display the current status of the resource limit facility.
-DISPLAY RLIMIT

If the resource limit facility (RLF) is inactive, the following output is generated:
DSNT701I - RESOURCE LIMIT FACILITY IS INACTIVE
DSN9022I - DSNTCDIS 'DISPLAY RLIMIT' NORMAL COMPLETION

If the RLF is active, the value of field RESOURCE AUTHID on panel DSNTIPP is
SYSADM, and the resource limit specification table with
RLST NAME SUFFIX = 03 was started, the following output is generated:
DSNT700I = SYSADM.DSNRLST03 IS THE ACTIVE RESOURCE LIMIT
SPECIFICATION TABLE
DSN9022I = DSNTCDIS 'DISPLAY RLIMIT' NORMAL COMPLETION

152 Command Reference


-DISPLAY THREAD (DB2)

-DISPLAY THREAD (DB2)


The DB2 command DISPLAY THREAD displays current status information about
DB2 threads. A DB2 thread is either an allied thread, a database access thread, or
a parallel task thread. Threads can be active, inactive, indoubt, or postponed.

Distributed threads are those threads that have a connection with a remote location
(active or inactive) or that had a connection with a remote location (indoubt). An
allied thread and a parallel task thread can be distributed or nondistributed; a
database access thread is always distributed.

The -DISPLAY THREAD command allows you to select the type of information you
want to display by using one or more of the following criteria:
v Active threads, inactive threads, indoubt threads, postponed threads, or the set of
active, indoubt, and postponed threads (see discussion under the TYPE option
for more information)
v The allied threads associated with the address spaces whose connection names
are specified
v Allied threads
v Distributed threads
v Distributed threads associated with a specific remote location
v Detailed information about connections with remote locations
v A specific logical unit of work ID (LUWID)

The information returned by the DISPLAY THREAD command reflects a dynamic


status. When the information is displayed, it is possible that the status has changed.
Moreover, the information is consistent only within one address space and is not
necessarily consistent across all address spaces displayed.

Abbreviation: -DIS THD

Environment
This command can be issued from an MVS console, a DSN session under TSO, a
DB2I panel (DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

# Data sharing scope: Group or member, depending on the value of the SCOPE
# option.

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v DISPLAY privilege
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Chapter 2. Commands 153


-DISPLAY THREAD (DB2)
Syntax

 DISPLAY THREAD 
, MEMBER
SCOPE ( )
(  connection-name ) GROUP
partial-connection*
( * )

 
ACTIVE , DETAIL
TYPE( INDOUBT )
* LOCATION(  location-name )
INACTIVE partial-location*
POSTPONED *
,

LUWID(  luwid )
partial-luwid*
token

 
,

RRSURID (  rrs-urid )
( * )

Option descriptions
Only under certain conditions, as described below, are any of the following options
required.

If neither (connection-name) nor (*) is specified, then the following rules apply:
v If the command is issued from a DSN session under TSO, a DB2I panel (DB2
COMMANDS), or an IMS or CICS terminal, then the connection name is
inherited from the associated address space.
v If the command is not issued from one of the above environments, then the
following rules apply:
– If neither LOCATION nor LUWID is specified, then processing terminates with
a DSNV413I message.
– If LOCATION or LUWID is specified, then only distributed threads of the type
selected by the TYPE option are displayed.
– When location-name is explicitly specified, then only distributed threads of the
type selected by the TYPE option that either have (active or inactive threads)
or had (indoubt threads) a connection with the specified location are
displayed.
(connection-name, ...)
Lists one or more connection names (of 1 to 8 characters each). Allied threads
are selected only from the address spaces associated with those connection
names. The LOCATION option can restrict what is displayed:
v If LOCATION(*) is specified, then only distributed threads of the type
specified in the TYPE option are displayed.

154 Command Reference


-DISPLAY THREAD (DB2)
v When location-name is explicitly specified, then only distributed threads of
the specified type that either have (active or inactive threads) or had (indoubt
threads) a connection with the specified location are displayed.
(partial-connection*, ...)
Selects the connections that begin with the string partial-connection and can
end with any string, including the empty string. For example, DISPLAY
THREAD(CICS*,IMS*) selects all connection names that begin with the string
’CICS’ or ’IMS’. The LOCATION option can restrict the display exactly the same
way as described above for location-name.
(*)
Displays all threads in all address spaces attached to DB2 and all database
access threads of the types specified in the TYPE option. The LOCATION
option can restrict what is displayed:
v If LOCATION(*) is specified, then only distributed threads are displayed.
v When location-name is explicitly specified, then only distributed threads that
either have (active or inactive threads) or had (indoubt threads) a connection
with the specified location are displayed.

The default is to display only the connections associated with the transaction
manager from which the command was entered.
# SCOPE
# Specifies the scope of the command.
# (LOCAL)
# Displays only threads on the current member.
# (GROUP)
# Displays all threads on the data sharing group.
# TYPE
Tells what type of thread to display.
Abbreviation: T
(ACTIVE)
Displays only active threads. An active allied thread is connected to DB2 via
TSO, BATCH, IMS, CICS or CAF. An active database access thread is
connected via VTAM to another system and is performing work on behalf of
that system. If, during command processing, an active thread becomes
indoubt, it can appear twice—once as active and once as indoubt.
Abbreviation: A
The information produced by ACTIVE can be useful for debugging
purposes, especially messages DSNV403I and DSNV404I; the contents of
those messages are described in Part 2 of DB2 Messages and Codes.
(INDOUBT)
Displays only indoubt threads.
An indoubt thread is a participant in a two-phase commit protocol that has
completed the first phase of commit, and has then lost communication with
the commit coordinator, and does not know whether to commit or roll back
the updates that have been made.
The indoubt thread information displayed includes threads for which DB2
has a coordinator role, a participant role, or both coordinator and participant
roles.

Chapter 2. Commands 155


-DISPLAY THREAD (DB2)
The commit coordinator for an allied thread is either a transaction manager
(for example, IMS or CICS) or OS/390 RRS for threads that use RRSAF.
The commit coordinator for a database access thread is a requester at a
remote system.
Indoubt threads hold locks on all resources that were updated.
Abbreviation: I
(*) Displays active, indoubt, and postponed threads.
(INACTIVE)
Displays only inactive threads. An inactive thread is a database access
thread that is connected via VTAM to another system and is idle, waiting for
a new unit of work to begin from that system.
Abbreviation: INA
Use qualifiers such as complete location names or LUWIDs with this option.
When there are large numbers of inactive database access threads,
unqualified display requests could temporarily change the DB2 working set,
which can temporarily affect the performance of active threads.
(POSTPONED)
Displays information about units of work whose back-out processing has
been postponed.
Abbreviation: P
After you have identified postponed threads, use the RECOVER
POSTPONED command on page 255 to complete backout processing for
the postponed units of work.
LOCATION(location-name, ...)
Limits the display to distributed threads as described below.
Abbreviation: LOC
location-name
Displays only distributed threads of the specified type that either have
(active or inactive threads) or had (indoubt threads) a remote connection
with the specified location-name.
DB2 does not receive a location name from requesters that are not DB2 for
OS/390 and z/OS subsystems. To display information about a requester
that is not a DB2 for OS/390 and z/OS subsystem, enter its LUNAME or IP
address. Enclose the LUNAME by the less-than (<) and greater-than (>)
symbols. Enter the IP address in the form nnn.nnn.nnn.nnn. For example,
the following command displays information about a remote location (that is
not DB2 for OS/390 and z/OS) with the LUNAME of LULA:
-DISPLAY THREAD (*) LOCATION (<LULA>)

The following command displays information about a remote location (that


is not DB2 for OS/390 and z/OS) with an IP address of 123.34.101.98:
-DISPLAY THREAD (*) LOCATION (123.34.101.98)

DB2 uses the <LUNAME> notation or IP address in messages displaying


information about requesters other than DB2.
partial-location*
Selects all location names that begin with the string partial-location and can

156 Command Reference


-DISPLAY THREAD (DB2)
end with any string, including the empty string. For example,
LOCATION(SAN*) selects all location names that begin with the string
’SAN’.
You can use an asterisk (*) when specifying a LUNAME in the same
manner as described above for other location names that are not DB2 for
OS/390 and z/OS subsystems. For example, LOCATION(<LULA*) selects
all remote locations (that are not DB2 for OS/390 and z/OS) with an
LUNAME that begins with the string ’LULA’.
You cannot use an asterisk when you specify an IP address.
(*) Display all distributed threads of the specified type.
LUWID(luwid, ...)
Displays information about the distributed threads that have the specified
LUWID. It is possible for more than one thread to have the same LUWID.
luwid
Consists of a fully qualified LU network name followed by a period and an
LUW instance number.
The LU network name consists of a 1 to 8 character network ID, a period,
and a 1 to 8 character network LU name. The LUW instance number
consists of 12 hex characters that uniquely identify the unit of work.
partial-luwid*
Selects all LUWIDs that begin with the string partial-luwid and can end with
any string, including the empty string. For example, LUWID(NET1.*) selects
all LUWIDs with a network name of ’NET1’.
token
Identifies a specific thread in an alternate way. DB2 assigns a token to each
distributed thread it creates. A token is a one- to six-digit decimal number
that appears after the equal sign in all DB2 messages that display a
LUWID.
If there are no periods nor a ’*’ in the LUWID specification, DB2 assumes
that you are supplying a token. The token that DB2 assigns to a specific
LUWID is unique for that DB2 subsystem, but not necessarily unique across
subsystems.
DETAIL
Displays additional information about conversation or socket activity when
distributed information is displayed for active or inactive threads. DETAIL has no
effect on the display of indoubt threads.
| RRSURID(rrs-urid)
| Specifies that only threads that match the specified RRSURID selection criteria
| are to be displayed.
| v If RRSURID(rrs-urid) is specified, then any thread involved in the RRS URID
| which has the value rrs-urid, and that meets any other selection criteria that
| was specified, will be displayed.
| v If RRSURID(*) is specified, then any thread involved in any RRS URID, and
| that meets any other selection criteria that was specified, will be displayed.

Usage notes
Formatted report for distributed threads: The series of messages DSNV444I
through DSNV446I augment the formatted report for -DISPLAY THREAD

Chapter 2. Commands 157


-DISPLAY THREAD (DB2)
TYPE(ACTIVE or INACTIVE) for distributed threads. See these messages in Part 2
of DB2 Messages and Codes for an explanation of the formatted report.

Threads using private protocol and DRDA access: It is possible for a database
access thread that is connected to a requester to also be connected to another
database server location using DB2 private protocol access or DRDA access. In this
case, DB2 issues message DSNV445I for the requester, and message DSNV444I
and zero or more DSNV446I messages for the remote server connections. In this
case, the database access thread acts as an intermediate database server.

Participant threads waiting for the commit or abort decision: A DSNV465I


message is issued for an active participant thread that has completed phase 1 of
commit processing and has been waiting for the commit or abort decision from the
coordinator for more than 60 seconds.

DISPLAY THREAD output limit: If a DISPLAY THREAD command is issued from


the MVS console, the maximum number of lines of output for a single invocation of
the command is 255 lines (at which time a DSNV421I or DSNV422I message is
printed). If you do not receive the required information in the first 255 lines of
output, issue the command again, specifying the TYPE option and a specific
connection name, location, luwid, or a combination of these, as appropriate, to
reduce the output.

Showing parallel tasks: The DB2 DISPLAY THREAD command shows parallel
tasks by using a status type of PT. The parallel tasks are displayed immediately
after the originating task. If the thread has a status of PT, the connection name
contains blanks if the thread of the originating task is running on the same DB2.
This shows that these parallel tasks are related to the originating task. If the parallel
task is running on a DB2 that is different from the DB2 that runs the originating
task, then the connection name is shown and the entry is followed by message
DSNV443I.

Output
Table 16 shows sample -DISPLAY THREAD commands and the types of output
they generate. The DETAIL keyword is not included because it affects only the
amount of information displayed about a distributed thread.

| If RRSURID(*) is specified, then only threads involved in any RRS URID will be
| displayed. If RRSURID(rrs-urid) is specified, then only threads involved in that
| specific RRS URID will be displayed.
Table 16. Sample DISPLAY THREAD commands. The following output is generated when
commands are issued from different environments with different TYPE specifications.
(Specifying TYPE(*) displays the equivalent output of both TYPE(ACTIVE) and
TYPE(INDOUBT) in one report.)
ACTIVE INDOUBT INACTIVE
Command issued from a DSN session under TSO, DB2I, IMS or CICS, where the
connection name is inherited
-DIS THD 1 1 2
-DIS THD LOC(*) 3 3 2
-DIS THD LOC(location-name) 4 4 2
Command issued from MVS console
-DIS THD 6 6 6

158 Command Reference


-DISPLAY THREAD (DB2)
Table 16. Sample DISPLAY THREAD commands (continued). The following output is
generated when commands are issued from different environments with different TYPE
specifications. (Specifying TYPE(*) displays the equivalent output of both TYPE(ACTIVE) and
TYPE(INDOUBT) in one report.)
ACTIVE INDOUBT INACTIVE
-DIS THD LOC(*) 9 9 8
-DIS THD LOC(location-name) 10 10 11
Command issued from any source
-DIS THD(connection-name) 1,12 1,12,15 12
-DIS THD(connection-name) LOC(*) 3,12 3,12,15 12
-DIS THD(connection-name) LOC(location-name) 4,13 4,13,15 13
-DIS THD(*) 7 7,15 8
-DIS THD(*) LOC(*) 9 9,15 8
-DIS THD(*) LOC(location-name) 10 10,15 11
-DIS THD(*) LUWID(luwid or token) 5 5,15 5
-DIS THD(connection-name) LUWID(luwid or 14 14,15 14
token)
-DIS THD LUWID(luwid or token) 5 5,15 5
Description of display generated:
1. Allied threads of the specified TYPE with the connection name.
2. No threads (inactive threads are database access threads and have no inherited
connection name).
3. Distributed allied threads of the specified TYPE with the connection name.
4. Distributed allied threads of the specified TYPE with the connection name and a
distributed connection = location-name.
5. The threads of the specified TYPE that have LUWID = luwid or token.
6. Message DSNV413I is displayed to indicate an error.
7. All threads (both allied and database access) of the specified TYPE.
8. All inactive database access threads.
9. All distributed threads (both allied and database access) of the specified TYPE.
10. All distributed threads (both allied and database access threads) of the specified TYPE
with a distributed connection = location-name.
11. All inactive database access threads with a distributed connection = location-name.
12. Database access threads of the specified TYPE with the connection name.
13. Database access threads of the specified TYPE with the connection name and a
distributed connection = location-name.
14. A thread of the specified TYPE with the connection name and LUWID = luwid or token.
15. Messages DSNV407 and DSNV408 also display coordinator’s TCP/IP resync port
number; message DSNV446 also displays the participant’s TCP/IP resync port number.

If the DETAIL option is specified, then the following additional information is


displayed:
LOCATION
The location name of the remote system.
SESSID
For a VTAM connection, the VTAM defined session instance identifier of the
session on which the conversation is executing.
For a TCP/IP connection, the local and remote TCP/IP port numbers, in the
form local:remote. local is the port number for the local DB2 subsystem.
remote is the port number for the remote partner.

Chapter 2. Commands 159


-DISPLAY THREAD (DB2)
A If VTAM or TCP/IP has control of the conversation (if DB2 transferred
control of the thread to VTAM or TCP/IP for that conversation), there is a V
in the A (Active) column. A W indicates that DB2 has suspended processing
on this conversation until VTAM notifies DB2 that the VTAM event is
complete. The column is otherwise blank.
STATUS
This 2 byte column indicates the status of the conversation or socket. The
possible values for STATUS are:
Value Status
Sx Send
Rx Receive
Ax Allocation
Dx Deallocation
Cx Change number of sessions (CNOS) processing
Xx Exchange Log name processing
blank Not in one of the above mentioned states

x can be one of the following values:


1 = private protocol conversation with single-phase commit
2 = DRDA conversation with single-phase commit
3 = private protocol conversation with two-phase commit
4 = DRDA conversation with two-phase commit.

Examples
Example 1: The output of the command DISPLAY THREAD shows a token for
every thread, distributed or not. This example shows the token for an allied thread
that is not distributed. The token is 123. You can use the thread’s token as the
parameter in the command CANCEL THREAD.
-DIS THD(*) DETAIL

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH T * 5 BKH2C SYSADM BKH2 000D 123
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

Example 2: This example shows information about conversation activity when


distribution information is displayed for active threads. DB2 returns the following
message, indicating that the local site application is waiting for a conversation to be
allocated in DB2, and a DB2 server that is accessed by a DRDA client using
TCP/IP.
-DIS THD(*) LOCATION(*) DETAIL

This command produces output similar to the following output:


-DIS THD(*) LOC(*) DET
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
TSO TR * 3 SYSADM SYSADM DSNESPRR 002E 2
V436-PGM=DSNESPRR.DSNESM68, SEC=1, STMNT=116
V444-DB2NET.LUND0.A238216C2FAE=2 ACCESSING DATA AT
V446-USIBMSTODB22:LUND1
V447--LOCATION SESSID A ST TIME

160 Command Reference


-DISPLAY THREAD (DB2)
V448--USIBMSTODB22 0000000000000000 V A1 9015816504776
TSO RA * 11 SYSADM SYSADM DSNESPRR 001A 15
V445-STLDRIV.SSLU.A23555366A29=15 ACCESSING DATA FOR 123.34.101.98
V447--LOCATION SESSID A ST TIME
V448--123.34.101.98 446:3171 S2 9015611253108
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

Example 3: In this example, a system at STL has a TSO application and an IMS
application. The system at STL fails after DB2 commits the TSO application, but
before the commit decision has been communicated to the participant subsystems
at SJ and LA. The failure occurs before IMS has communicated the commit or
rollback decision to STL’s DB2. The DISPLAY THREAD commands that are issued
after the STL DB2 restarts but before reconnect with IMS. DISPLAY THREAD
commands that are issued at each location show output similar to the following
output:

At STL:
-DIS THD(*) TYPE(INDOUBT)

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV406I - INDOUBT THREADS -
COORDINATOR STATUS RESET URID AUTHID
STLIMS01 INDOUBT 0F201050A010 SM09H
V467-HAS LUWID IBM.STLDB21.15A86A876789.0010=1
V449-HAS NID=A5 AND ID=STLIMS01
V450-HAS PARTICIPANT INDOUBT AT
V446--IBMSJ0DB20001:STLDB22
IBMSTLDB20001 COMMITTED 0F20105B0000 JO78S
V467-HAS LUWID IBM.STLDB21.16B57B954427.0003=2
V450-HAS PARTICIPANT INDOUBT AT
V446--IBMSJ0DB20001:STLDB22 IBMLA0DB20001:STLDB23
DISPLAY INDOUBT REPORT COMPLETE -
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

At San Jose:
-DIS THD(*) TYPE(INDOUBT)

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV406I - INDOUBT THREADS -
COORDINATOR STATUS RESET URID AUTHID
IBMSTLDB20001:STLDB21 INDOUBT 03201050A010 HEU4443
V467-HAS LUWID IBM.STLDB21.15A86A876789.0010=8
V466-THREAD HAS BEEN INDOUBT FOR 00:05:20
IBMSTLDB20001:STDB21 INDOUBT 03201050B000 PP433MM
V467-HAS LUWID IBM.STLDB21.16B57B954427.0003=6
DISPLAY INDOUBT REPORT COMPLETE
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

At Los Angeles (both ACTIVE and INDOUBT threads are displayed):


-DIS THD(*) TYPE(*) DETAIL

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN

Chapter 2. Commands 161


-DISPLAY THREAD (DB2)
SERVER RA * 0 RUW2STAT JONES DISTSERV 0005 4
V465-THREAD HAS BEEN PREPARED FOR 00:05:20
V445-IBM.STLDB21.15A86A876789=4 ACCESSING DATA FOR
IBMSJ0DB20001:STLDB21
V447--LOCATION SESSID A ST TIME
V448--IBMSJ0DB20001 0000000400000004 W R4 9034817015032
DISPLAY ACTIVE REPORT COMPLETE
DSNV406I - INDOUBT THREADS -
COORDINATOR STATUS RESET URID AUTHID
IBMSTLDB20001:STLDB21 INDOUBT 03201050B000 SM43YY33
V467-HAS LUWID IBM.STLDB21.16B57B954427.0003=5
V466-THREAD HAS BEEN INDOUBT FOR 00:05:20
DISPLAY INDOUBT REPORT COMPLETE
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

Example 4: This example shows a thread executing within a stored procedure and
a thread waiting for a stored procedure to be scheduled. Assume that an application
makes a call to stored procedure PROC1 and then to stored procedure PROC2.
PROC2 is in a STOP QUEUE state.

The output for PROC1 while it is executing shows a status of SP in the ST column,
which indicates that a thread is executing within a stored procedure:
-DIS THD(*)

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS - 176
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH SP 3 RUNAPPL SYSADM PL01AP01 001D 43
V429 CALLING STORED PROCEDURE PROC1, LOAD MODULE LMPROC1
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DISPLAY THREAD' NORMAL COMPLETION

The output for PROC2, while it is queued, shows a status of SW in the ST column,
which indicates that a thread is waiting for a stored procedure to be scheduled:
-DIS THD(*)

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS - 198
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH SW * 13 RUNAPPL SYSADM PL01AP01 001D 43
V429 CALLING STORED PROCEDURE PROC2, LOAD MODULE
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DISPLAY THREAD' NORMAL COMPLETION

Example 5: This example shows an allied, nondistributed originating thread


(TOKEN=30) that is established (allocated according to plan) in addition to all of its
parallel tasks (PT) which are running on the same DB2. All parallel tasks are
displayed immediately following their corresponding originating thread.
16.32.57 DB1G DISPLAY THREAD(*)
16.32.57 STC00090 DSNV401I DB1G DISPLAY THREAD REPORT FOLLOWS -
16.32.57 STC00090 DSNV402I DB1G ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH T * 1 PUPPYDML USER001 DSNTEP3 0025 30
PT * 641 PUPPYDML USER001 DSNTEP3 002A 40
PT * 72 PUPPYDML USER001 DSNTEP3 002A 39
PT * 549 PUPPYDML USER001 DSNTEP3 002A 38
PT * 892 PUPPYDML USER001 DSNTEP3 002A 37

162 Command Reference


-DISPLAY THREAD (DB2)
PT * 47 PUPPYDML USER001 DSNTEP3 002A 36
PT * 612 PUPPYDML USER001 DSNTEP3 002A 35
PT * 545 PUPPYDML USER001 DSNTEP3 002A 34
PT * 432 PUPPYDML USER001 DSNTEP3 002A 33
PT * 443 PUPPYDML USER001 DSNTEP3 002A 32
PT * 252 PUPPYDML USER001 DSNTEP3 002A 31
DISPLAY ACTIVE REPORT COMPLETE
16.32.58 STC00090 DSN9022I DB1G DSNVDT '-DISPLAY THREAD' NORMAL
COMPLETION

Example 6: This example shows the detail report for a DB2 client that uses TCP/IP
to access a remote DRDA server.
DISPLAY THREAD(*) LOCATION(*)

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH TR * 6 BKH2C SYSADM YW1019C 0009 2
V444-STLDRIV.SSLU.A23555366A29=2 ACCESSING DATA AT
V446-USIBMSTODB22:123.34.101.98:446
V447--LOCATION SESSID A ST TIME
V448--USIBMSTODB22 4019:446 V R2 9015611253116
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

Example 7: This example shows the detail report for a DB2 server that is accessed
by a DRDA client using TCP/IP.
DISPLAY THREAD(*) LOCATION(*)

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH RA * 5 BKH2C SYSADM DISTSERV 0008 2
V445-STLDRIV.SSLU.A23555366A29=2 ACCESSING DATA FOR 123.34.101.98
V447--LOCATION SESSID A ST TIME
V448--123.34.101.98 446:3171 S2 9015611253108
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DIS THD' NORMAL COMPLETION

Example 8: This example shows information about units of work whose back-out
processing has been postponed.
-DISPLAY THREAD (*) TYPE (POSTPONED)

This command produces output similar to the following output:


DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV431I - POSTPONED ABORT THREADS -
COORDINATOR STATUS RESET URID AUTHID
BATCH ABORT-P 000002FF98EA ADMF001
BATCH ABORT-P 000002FF9000 ADMF001
DISPLAY POSTPONED ABORT REPORT COMPLETE
DSN9022I - DSNVDT '-DISPLAY THREAD' NORMAL COMPLETION

Example 9: This example shows the token for a thread that is executing a
user-defined function. The token is 18.
-DISPLAY THREAD(*) DETAIL

Chapter 2. Commands 163


-DISPLAY THREAD (DB2)
This command produces output similar to the following output:
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH T * 231 DISTHD ADMF001 0021 95
BATCH SW * 38 INSERT ADMF001 DSNTEP3 0025 18
V436-PGM=CLIP74C1.UFIP74C1, SEC=0, STMNT=0
V429 CALLING FUNCTION =SCIP7401.SP_UFIP74C1 ,
PROC=V61AWLM3, ASID=0030, WLM_ENV=WLMENV3
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT '-DISPLAY THREAD' NORMAL COMPLETION

| Example 10: This example shows information about a thread that is involved in an
| RRS Unit of Recovery.
| -DIS THD(*) RRSURID(*)

| This command produces output similar to the following.


| - 08.23.58 STC00149 DSNV401I ( DISPLAY THREAD REPORT FOLLOWS -
| - 08.23.58 STC00149 DSNV402I ( ACTIVE THREADS -
| - NAME ST A REQ ID AUTHID PLAN ASID TOKEN
| - RRSAF T 8 TGXID-111 ADMF001 TGXIDR 0023 35
| - V481-DB2 IS PARTICIPANT FOR RRS URID B4D0FC267EB020000000001101010000
| - V437-WORKSTATION= , USERID= ,
| - APPLICATION NAME= g g SQLD
| - DISPLAY ACTIVE REPORT COMPLETE
| - 08.23.58 STC00149 DSN9022I ( DSNVDT '-DIS THD' NORMAL COMPLETION

| Example 11: This example shows information about a thread where DB2 is the
| coordinator for an indoubt RRS Unit of Recovery. DB2 has committed the thread
| but has not been able to resolve the RRS UR with RRS.
| -DIS THD(*) TYPE(I) RRSURID(*)

| This command produces output similar to the following.


| - 09.27.21 STC00185 DSNV406I ( INDOUBT THREADS -
| - COORDINATOR STATUS RESET URID AUTHID
| - UNKNOWN COMMITTED 123456789ABC UNKNOWN
| - V480-DB2 IS COORDINATOR FOR RRS URID C4D4FA267EB040000000001201020000
| 00- DISPLAY INDOUBT REPORT COMPLETE
| - 09.27.21 STC00185 DSNV434I ( DSNVDT NO POSTPONED ABORT THREADS FOUND
| - 09.27.21 STC00185 DSN9022I ( DSNVDT '-DIS THD' NORMAL COMPLETION

164 Command Reference


-DISPLAY TRACE (DB2)

-DISPLAY TRACE (DB2)


The DB2 command DISPLAY TRACE displays a list of active traces. For more
information about this trace facility, see Part 4 (Volume 1) of DB2 Administration
Guide.

There is an additional option to this command and values for a few options that are
not described here. They are intended for service and use under the direction of
IBM support personnel. For details, see DB2 Diagnosis Guide and Reference.

Abbreviation: -DIS TRACE

Environment
This command can be issued from an MVS console, a DSN session, a DB2I panel
(DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

# Data sharing scope: Group or local, depending on the value of the SCOPE option.

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v DISPLAY privilege
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Chapter 2. Commands 165


-DISPLAY TRACE (DB2)
Syntax

( * )
 DISPLAY TRACE 
( PERFM ) LOCAL
( ACCTG ) SCOPE ( )
( STAT ) GROUP
( AUDIT )
( MONITOR )

 
destination block constraint block DETAIL(output-type) COMMENT(string)

destination block:

 DEST(  GTF ) 
SMF
SRV
OPn

constraint block:

* * *
, , ,

 PLAN(  plan-name ) AUTHID(  auth-id ) CLASS(  integer ) 

* *
, ,

 TNO(  integer ) LOCATION(  location-name ) 


<luname>
nnn.nnn.nnn.nnn

Option descriptions
None of the options are required. The command DISPLAY TRACE lists all active
traces. Each option that is used, except TNO, limits the effect of the command to
active traces that were started using the same option, either explicitly or by default,
with exactly the same parameter values. For example, the command
-DISPLAY TRACE (PERFM) CLASS (1,2)

lists only the active traces that were started using the options PERFM and CLASS
(1,2); it does not list, for example, any trace started using CLASS(1).
(*) Does not limit the list of traces. The default is (*).
The CLASS option cannot be used with -DISPLAY TRACE (*).

Each of the following keywords limits the list to traces of the corresponding type.
For further descriptions of each type, see “-START TRACE (DB2)” on page 299.

166 Command Reference


-DISPLAY TRACE (DB2)
Type (Abbrev)
Description
PERFM (P)
Performance records of specific events
ACCTG (A)
Accounting records for each transaction
STAT (S)
Statistical data
AUDIT (AU)
Audit data
MONITOR (MON)
Monitor data
# SCOPE
# Specifies the scope of the command.
# (LOCAL)
# Displays the trace for the local member only.
# (GROUP)
# Displays the trace for all members in the data sharing group.
# DETAIL(output-type)
Limits the information that a trace displays based on the output type specified
within parentheses.
The possible values for output-type are:
1 Display summary trace information: TRACE NUMBER, TYPE, CLASS,
DEST
2 Display qualification trace information: TRACE NUMBER, AUTHID,
PLAN, LOCATION
1,2 Display both summary and qualification information
* Display both summary and qualification information

If no parameter follows DETAIL, type 1 trace information is displayed.

An additional column, QUAL, is also displayed, indicating whether the trace is


qualified. Part of the summary trace information, the QUAL column can be used
to determine if further qualification information for the trace is available. This
information can be obtained by specifying DETAIL (2) or DETAIL (*). A QUAL
column value of YES indicates that additional information for this particular trace
exists in the qualification trace information; a value of NO indicates that no
additional information for this trace exists.
COMMENT(string)
Specifies that comment string appears in the trace output, except for the output
in the resident trace tables.
string is any character string; it must be enclosed between apostrophes if it
includes a blank, comma, or special character. The comment does not appear
in the display; it can be recorded in trace output, but only if commands are
being traced.
DEST
Limits the list to traces started for particular destinations. More than one value
can be specified, but do not use the same value twice. If you do not specify a
value for DEST, DB2 does not use the destination of where trace output is
recorded to limit the list of traces displayed.

Chapter 2. Commands 167


-DISPLAY TRACE (DB2)
Abbreviation: D
Possible values and their meanings are:
Value Trace destination
GTF The generalized trace facility
SMF The system management facility
SRV An exit to a user-written routine
OPn A specific destination. n can be a value from 1 to 8.

See “-START TRACE (DB2)” on page 299 for a list of allowable destinations for
each trace type.
PLAN(plan-name, ...)
Limits the list to traces started for particular application plans. Up to eight plan
names can be used. If more than one name is used, only one value can be
used for AUTHID, TNO, and LOCATION. Do not use this option with STAT.
The default is PLAN(*), which does not limit the list.
AUTHID(authorization-id, ...)
Limits the list to traces started for particular authorization identifiers. Up to eight
identifiers can be used. If more than one identifier is used, only one value can
be used for PLAN, TNO, and LOCATION. Do not use this option with STAT.
The default is AUTHID(*), which does not limit the list.
CLASS(integer, ...)
Limits the list to traces started for particular classes. For descriptions of the
allowable classes, see “-START TRACE (DB2)” on page 299.
The default is CLASS(*), which does not limit the list.
TNO(integer, ...)
Limits the list to particular traces, identified by their trace numbers (1 to 32, 01
to 09). Up to eight trace numbers can be used. If more than one number is
used, only one value each for PLAN, AUTHID, and LOCATION can be used.
The default is TNO(*), which does not limit the list.
LOCATION(location-name, ...)
Limits the list to traces started for threads that have a distributed relationship
with the specified location.
(location-name)
The location names that you supply are the 1 to 16 character identifiers
assigned to the DB2 subsystem whose traces you want to display. Supplying an
* as the location name indicates that the trace display must include all traces
started with any location name qualifier.
You can specify up to eight location names. If you specify more than one
location name, you can only specify one value each for PLAN, AUTHID, and
TNO.
LOCATION cannot be specified when you choose a statistics trace.
Requesters other than DB2 for OS/390 and z/OS: DB2 does not receive a
location name from requesters that are not DB2. To display information about a
requester that is not a DB2 for OS/390 and z/OS subsystem, enter its
LUNAME, enclosed by the less-than (<) and greater-than (>) symbols. For
example, the following command displays information about a remote location
with the LUNAME of LULA:
-DISPLAY TRACE (*) LOCATION (<LULA>)

168 Command Reference


-DISPLAY TRACE (DB2)
DB2 uses the < LUNAME> notation in messages displaying information about
requesters that are not DB2 for OS/390 and z/OS.

The default is LOCATION(*), which does not limit the list.


<luname>
Activates the DB2 trace for the remote clients that are connected to DDF
through the remote SNA LU that you specified in luname.
nnn.nnn.nnn.nnn
Activates the DB2 trace for the remote clients that are connected to DDF
through the remote TCP/IP host whose IP address is specified by
nnn.nnn.nnn.nnn.

Examples
Example 1: List all traces that have the generalized trace facility as their only
destination.
-DISPLAY TRACE (*) DEST (GTF)

Example 2: List the trace started for Example 2 of -START TRACE.


-DISPLAY TRACE (ACCTG) PLAN (DSN8BC71)
COMMENT ('ACCTG TRACE FOR DSN8BC71')

Example 3: List all active performance traces.


-DISPLAY TRACE=P

Example 4: List all active audit traces for threads that are connected to the DB2
subsystem with location name USIBMSTODB23.
-DISPLAY TRACE (AUDIT) LOCATION (USIBMSTODB23)

Example 5: Output from -DISPLAY TRACE is a set of messages that look like this:
- 10.26.34 -DISPLAY TRACE
- 10.26.34 STC 21 DSNW127I - CURRENT TRACE ACTIVITY IS -
- TNO TYPE CLASS DEST QUAL
- 01 STAT 01 SMF NO
- 02 ACCTG 01 SMF YES
- 03 PERFM 01,02,03 GTF YES
- 04 AUDIT 01,02,03,04, SMF YES
- 04 06,07
- 05 MON 01,02,03 OP1 NO
- *********END OF DISPLAY TRACE SUMMARY DATA*********
- 10.26.34 STC 21 DSN9022I - DSNWVCM1 '-DISPLAY TRACE' NORMAL COMPLETION

- 10.28.47 -DISPLAY TRACE DETAIL(*)


- 10.28.47 STC 21 DSNW127I - CURRENT TRACE ACTIVITY IS -
- TNO TYPE CLASS DEST QUAL
- 01 STAT 01 SMF NO
- 02 ACCTG 01 SMF YES
- 03 PERFM 01,02,03 GTF YES
- 04 AUDIT 01,02,03,04, SMF YES
- 04 06,07
- 05 MON 01,02,03 OP1 NO
- *********END OF DISPLAY TRACE SUMMARY DATA*********
- 10.28.47 STC 21 DSNW143I - CURRENT TRACE QUALIFICATIONS ARE -
- TNO AUTHID PLAN RMID LOCATION
- 01 * * *
- 02 * * *
- 03 USER01 * *
- 04 * * 14,16,18,26 DENVER
- 05 * PROG1 *

Chapter 2. Commands 169


-DISPLAY TRACE (DB2)
- 06 * * *
- ******END OF DISPLAY TRACE QUALIFICATION DATA******
- 10.28.47 STC 21 DSN9022I - DSNWVCM1 '-DISPLAY TRACE' NORMAL COMPLETION

170 Command Reference


-DISPLAY UTILITY (DB2)

-DISPLAY UTILITY (DB2)


The DB2 command DISPLAY UTILITY displays the status of utility jobs, including
utility jobs in a data sharing group.

The output from the command consists of informational messages only. One set of
messages is returned for each job identified by the command. For utility jobs in a
data sharing group, the output shows the member name of the system on which
each utility job is running.

The status from the display represents the current status, except in a data sharing
group when the utility is running on a member other than the one from which the
command is issued. In that case, the status is current as of the last checkpoint.

Abbreviation: -DIS UTIL

Environment
This command can be issued from an MVS console, a DSN session, a DB2I panel
(DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Group or member, depending on which option you choose

Authorization
None is required.

Syntax

 DISPLAY UTILITY ( utility-id ) 


partial-utility-id* ,
*
MEMBER(  member-name )

Option descriptions
Use at least one of the following options but do not use the same one more than
once.
(utility-id)
Identifies a single job by its utility identifier, the value given for the UID
parameter when the job was created.
If utility-id was created by the DSNU CLIST by default, it has the form of
tso-userid.control-file-name. For a list of values for control-file-name, see the
description of the UID parameter for the DSNU command procedure (CLIST) in
DB2 Utility Guide and Reference.
If utility-id was omitted, utility-id has the form userid.jobname.
(partial-utility-id*)
Identifies a set of utility jobs. A status message is shown for each utility
identifier that begins with the characters of partial-utility-id.

Chapter 2. Commands 171


-DISPLAY UTILITY (DB2)
For example, -DISPLAY UTILITY(ABCD*) shows the status of every utility job
known to DB2 whose identifier begins with the characters ABCD.
(*) Shows the status of all utility jobs known to DB2, including jobs currently
running in a data sharing group.
MEMBER (member-name, ...)
Restricts the display for the identified utility jobs to specific members of the data
sharing group. The default is to display utility jobs running on any member. In a
non-data-sharing environment, the option is ignored.

One set of messages is returned for each job identified by the command.

Usage notes
DISPLAY status: The status displayed in the returned message is the status at the
time the DB2 utility function received the command. Execution has proceeded,
therefore the current state of the utility can be different from the state reported. For
instance, the DISPLAY UTILITY command can indicate a particular utility identifier is
active, but, when the message is received by the requester, the utility job step could
have terminated so that the utility identifier is no longer known to DB2.

Command response: In a data sharing environment, messages DSNU100I,


DSNU105I, DSNU106I show the name of the member on which the utility job is
running. If you specify a single member name in the MEMBER option and that
member does not belong to the group, or if you specify a list of member names in
the MEMBER option and none of those members belong to the group, the
command fails and a message is issued.

Output
The output from -DISPLAY UTILITY consists of informational messages only.

Output during any phase of REORG with SHRLEVEL CHANGE or SHRLEVEL


REFERENCE: During any phase of REORG with SHRLEVEL CHANGE or
SHRLEVEL REFERENCE, the output of -DISPLAY UTILITY includes the information
in DSNU347I. During any phase of REORG with SHRLEVEL CHANGE, the output
of DISPLAY UTILITY includes information in DSNU384I as follows as shown in
“Example 4” on page 174
DEADLINE
Indicates a timestamp according to the most recently specified value of
DEADLINE.
MAXRO
Indicates the number of seconds, according to the most recently specified
value of MAXRO.
LONGLOG
Indicates either CONTINUE, TERM, or DRAIN according to the most
recently specified value of LONGLOG.
DELAY
Indicates the number of seconds according to the most recently specified
value of DELAY.

Output during LOG phase of REORG with SHRLEVEL CHANGE: During the
LOG phase of REORG with SHRLEVEL CHANGE, the output of -DISPLAY UTILITY
now includes the additional information found in message DSNU383I as shown in
“Example 4” on page 174 as follows:

172 Command Reference


-DISPLAY UTILITY (DB2)
CURRENT ITERATION NUMBER
Indicates the current iteration number.
WRITE ACCESS ALLOWED IN CURRENT ITERATION
Indicates “YES” or “NO” according to whether write access is allowed in the
current iteration of log processing.
ITERATION BEFORE PREVIOUS ITERATION
Indicates the ELAPSED TIME so far, and the NUMBER OF LOG
RECORDS PROCESSED in the iteration. Their values are 0 if the current
iteration number is 1 or 2.
PREVIOUS ITERATION
Indicates the ELAPSED TIME and the NUMBER OF LOG RECORDS
PROCESSED for the previous iteration. Their values are 0 if the current
iteration number is 1.
CURRENT ITERATION:
Indicates the ESTIMATED ELAPSED TIME, the ACTUAL ELAPSED TIME
SO FAR and the ACTUAL NUMBER OF LOG RECORDS BEING
PROCESSED.
CURRENT ESTIMATE FOR NEXT ITERATION
For the next iteration, indicates the currently ELAPSED TIME and the
currently estimated NUMBER OF LOG RECORDS TO BE PROCESSED.

Progress of utility processing: The DISPLAY UTILITY command provides the


user an estimate of how much processing the utility has completed. The output
displays information from message DSNU105I as seen in “Example 2” and includes:
COUNT
COUNT n is the number of pages or records processed in a utility phase.
COUNT has different meanings for different utilities. For utilities not
mentioned below, ignore this field.
| v For LOAD, COUNT representes the total number of records that have
| been loaded into all partitions when the command was issued. The count
| is zero from the time the RELOAD phase starts until the first LOAD
| subtask begins loading records into the first partition assigned to that
| subtask.
v For CHECK INDEX, RECOVER INDEX, and REORG, COUNT
represents the number of records processed.
v For COPY, MERGE COPY, RECOVER (restore phase), and RUNSTATS,
COUNT represents the number of pages processed.
v For STOSPACE, COUNT represents the number of table spaces or
indexes processed.
For more information, see DB2 Utility Guide and Reference.

Examples
Example 1: Display status information for all utility jobs currently known to DB2.
-DISPLAY UTILITY (*)

Example 2: Display the status of utilities on all members of the data sharing group.
-DB1G DISPLAY UTILITY (*)

The following output, which shows utility jobs on members DB1G and DB2G, is
generated:

Chapter 2. Commands 173


-DISPLAY UTILITY (DB2)
DSNU100I -DB1G DSNUGDIS USER = SAMPID
MEMBER = DB1G
UTILID = RUNTS
PROCESSING UTILITY STATEMENT 1
UTILITY = RUNSTATS
PHASE = RUNSTATS COUNT = 0
STATUS = STOPPED
DSNU100I -DB1G DSNUGDIS USER = SAMPID
MEMBER = DB2G
UTILID = CHKIX1
PROCESSING UTILITY STATEMENT 8
UTILITY = CHECK
PHASE = UNLOAD COUNT = 0
STATUS = STOPPED
DSN9022I -DB1G DSNUGCC '-DB1G DISPLAY UTILITY' NORMAL COMPLETION

Example 3: In a data sharing environment, display the status of utilities on member


DB1G.
-DB1G DISPLAY UTILITY (*) MEMBER (DB1G)

Example 4: This shows output from the command DISPLAY UTILITY:


-DB1G DISPLAY UTILITY(*)
DSNU105I -DB1G DSNUGDIS - USERID = SYSADM 973
MEMBER =
UTILID = REORGCP
PROCESSING UTILITY STATEMENT 1
UTILITY = REORG
PHASE = LOG COUNT = 0
STATUS = ACTIVE
DSNU347I -DB1G DSNUGDIS - 974
DEADLINE = NONE
DSNU384I -DB1G DSNUGDIS - 975
MAXRO = DEFER
LONGLOG = CONTINUE
DELAY = 1200 SECONDS
DSNU383I -DB1G DSNUGDIS - CURRENT ITERATION NUMBER = 4 976
WRITE ACCESS ALLOWED IN THIS ITERATION = YES
ITERATION BEFORE PREVIOUS ITERATION:
ELAPSED TIME = 00:00:00
NUMBER OF LOG RECORDS PROCESSED = 0
PREVIOUS ITERATION:
ELAPSED TIME = 00:00:00
NUMBER OF LOG RECORDS PROCESSED = 0
CURRENT ITERATION:
ESTIMATED ELAPSED TIME = 00:00:00
ACTUAL ELAPSED TIME SO FAR = 00:00:00
ACTUAL NUMBER OF LOG RECORDS BEING PROCESSED = 0
CURRENT ESTIMATE FOR NEXT ITERATION:
ELAPSED TIME = 00:00:00
NUMBER OF LOG RECORDS TO BE PROCESSED = 0
DSN9022I -DB1G DSNUGCCC '-DIS UTIL' NORMAL COMPLETION

174 Command Reference


DSN (TSO)

DSN (TSO)
The TSO command DSN enables you to issue DSN subcommands, namely:

ABEND BIND DCLGEN END


FREE REBIND RUN SPUFI

During a DSN session, you can enter DB2 commands or comments. DB2
commands must start with a hyphen (-). Comments must start with an asterisk (*).

During a DSN session, you can also issue TSO commands, except for FREE, RUN,
TEST, and TIME. To use TSO TEST to debug an application program, execute it
with the DSN command; for example:
TEST 'prefix.SDSNLOAD(DSN)' CP

The ABEND subcommand listed above is used for diagnostic purposes only, and is
intended to be used only under the direction of your IBM Support Center. Use it
only when diagnosing a problem with DSN or DB2. Percent commands are not
recognized during a DSN session, they are only supported by the TSO command
processor.

Environment
A DSN session runs under TSO in either foreground or background mode. When
you run it in background mode, you are not prompted for corrections or additional
required information.

You can also start a DSN session from a CLIST running in either foreground or
background mode.

Data sharing scope: Member

Authorization
None is required for the DSN command, but authorization is required for most
subcommands.

Syntax

 DSN 
DSN 0 TEST(integer)
SYSTEM( subsystem-name ) RETRY( integer )
group-attachment-name

 
YES
GROUP( )
NO

Option descriptions
None of the following options are required.
SYSTEM

Chapter 2. Commands 175


DSN (TSO)
(subsystem-name)
Specifies the name of the DB2 subsystem.
(group-attachment-name)
Specifies the group attachment name of the data sharing group.

The default is SYSTEM(DSN). This value can be modified during DB2


installation.
RETRY(integer)
Specifies the number (integer) of additional times connection to the DB2
subsystem should be attempted if DB2 is not up or the maximum number of
batch connections has been reached when DSN is issued. Retries occur at
30-second intervals.
The default is RETRY(0). The maximum number of retries is 120.
TEST(integer)
Specifies the last two digits (integer) of the module name in order to trace a
single DSN module. Specify a number greater than 100 to trace all DSN
modules. DSN trace information messages are written to the TSO SYSTSPRT
DD statement, and optionally, to the DSNTRACE DD statement.
| GROUP
| (YES) Specifies to consider group attach processing when the specified
| system is not active.
| (NO) Specifies that group attach processing is not considered.

| Usage notes
Beginning a DSN session: Issue the DSN command to begin a DSN session,
which allows you to enter DSN subcommands. These rules govern the session:
v In foreground operation, you are prompted for input by the prompt string DSN at
the terminal. In background mode, your input is read from the SYSTSIN data set.
v Except for delimited table names in the DCLGEN command, input in lowercase
letters is changed to uppercase.
v If duplicate keywords of any subcommand are specified, only the last of these
keywords is processed. For example, if both MEMBER(dbrm-member-name1)
and MEMBER(dbrm-member-name2) are specified with BIND PLAN, DB2
receives only the latter, MEMBER(dbrm-member-name2).
v If ATTENTION (PA1) is pressed during a DSN session, and PROMPT is specified
in the TSO user profile, message DSNE005 appears: EXECUTION IS
INTERRUPTED, ENTER C TO CANCEL, OR ANY OTHER REPLY TO RESUME THE
subcommand SUBCOMMAND.
If you enter C, the current subcommand is canceled and the current DB2
connection terminates; a new one is established, and another DSN prompt
appears. Any other reply, except ATTENTION, causes the current subcommand
to continue from the point at which it was interrupted.
If a DSN session is started from a CLIST, or a CLIST is executed under DSN,
CONTROL PROMPT must be specified in the CLIST in order to receive message
DSNE005.
v After a command is processed during a DSN session, you are prompted for
input. That cycle continues until you end the session.
v You can end the session by doing one of the following:
– Issue the END subcommand. Control is passed to TSO.

176 Command Reference


DSN (TSO)
– Press ATTENTION and respond to the message by pressing ATTENTION
again.
– Issue another DSN command. The old session ends and a new one begins.

DSN return code processing: At the end of a DSN session, register 15 contains
the highest value placed there by any DSN subcommand used in the session or by
any program run by the RUN subcommand. Your run-time environment might format
that value as a return code. The value does not, however, originate in DSN.

Examples
Example 1: Start a DSN session. If the attempt to connect to DB2 fails, five retries
(at 30 second intervals) are to be made.
DSN SYSTEM (DB2) RETRY (5)

Example 2: Start a DSN session, run a program, and then end the session and
return to TSO.
TSO prompt : READY
USER enters: DSN SYS (SSTR)
DSN prompt : DSN
USER enters: RUN PROGRAM (MYPROG)
DSN prompt : DSN
USER enters: END
TSO prompt : READY

Chapter 2. Commands 177


DSNC (CICS)

DSNC (CICS attachment facility)


The CICS attachment facility DSNC command allows you to enter DB2 commands
from CICS.

Environment
This command can be issued only from a CICS terminal.

Data sharing scope: Member

Authorization
This command requires the appropriate level of CICS authority, as described in the
appropriate CICS for MVS/ESA CICS-RACF Security Guide or CICS for MVS/ESA
Operations and Utilities Guide.

Entering the DSNC command requires no privileges from DB2 security. For a
description of the privileges required to issue a DB2 command using the DSNC
command, see the command’s description.

Syntax

 DSNC db2-command 
destination

Option descriptions
destination
Identifies another terminal to receive display information. It must be a valid
terminal that is defined to CICS and supported by CICS basic mapping support
(BMS).
db2-command
Specifies the exact DB2 command that you want to enter from a CICS terminal.
It must be preceded by a hyphen.

Usage note
Screen scrolling: The CICS SIT table keyword SKRxxxx can be used to support
the scrolling of DSNC DB2 commands from your terminal. For further information
regarding the SIT keywords and parameters, see CICS for MVS/ESA System
Definition Guide.

Example
Example: Issue the DB2 command -DISPLAY THREAD from a CICS terminal.
DSNC -DISPLAY THREAD

178 Command Reference


DSNC DISCONNECT (CICS)

DSNC DISCONNECT (CICS attachment facility)


The CICS attachment facility command DSNC DISCONNECT disconnects threads.

The command provides manual control to release resources being shared by


normal transactions so that special purpose processes, such as utilities, can have
exclusive access to the resources.

Abbreviation: DSNC DISC

Environment
This command can be issued only from a CICS terminal.

Data sharing scope: Member

Authorization
This command requires an appropriate level of CICS authority, as described in the
appropriate CICS for MVS/ESA CICS-RACF Security Guide.

Syntax

 DSNC DISCONNECT plan-name 

Option description
plan-name
Specifies a valid application plan.

Usage notes
Preventing creation of threads: The command DSNC DISCONNECT does not
prevent threads from being created on behalf of transactions. The command only
causes currently connected threads to be terminated as soon as they are not being
used by a transaction. To interrupt a transaction and cancel a thread faster, you can
use the command CANCEL THREAD. For details, see “-CANCEL THREAD (DB2)”
on page 77.

You can stop the transactions associated with a particular plan ID in CICS with the
MAXIMUM setting for TCLASS or MAXACTIVE setting for TRANCLASS. This
prevents new instances of the transaction from causing a re-creation of a thread.

Alternative for protected threads: You may want to deallocate a plan for rebinding
or for running a utility against the database. If you are using a protected thread, use
DSNC MODIFY rather than DSNC DISCONNECT. Modify the THRDA value of the
plan to zero to send all the threads to the pool. The protected thread will terminate
on its own within 60 seconds and DISCONNECT is unnecessary.

Example
Disconnect active threads for PLAN1.
DSNC DISC PLAN1

Chapter 2. Commands 179


DSNC DISPLAY (CICS)

DSNC DISPLAY (CICS attachment facility)


The CICS attachment facility command DSNC DISPLAY displays information on
CICS transactions accessing DB2 data, or statistical information associated with
entries in the resource control table (RCT).

Abbreviation: DSNC DISP

Environment
This command can be issued only from a CICS terminal.

Data sharing scope: Member

Authorization
This command requires an appropriate level of CICS authority, as described in the
CICS for MVS/ESA CICS-RACF Security Guide or CICS for MVS/ESA Operations
and Utilities Guide.

Syntax

 DSNC DISPLAY PLAN 


plan-name destination
TRANSACTION
transaction-id
STATISTICS

Option descriptions
PLAN plan-name
Displays information about transactions by plan name.
plan-name is a valid plan name for which information is displayed.
Default: If you do not specify plan-name (or if you specify an asterisk, *),
information is displayed for all active plan names listed in the resource control
table.
TRANSACTION transaction-id
Displays information about transactions by transaction ID.
Abbreviation: TRAN
transaction-id is a valid transaction ID for which information is displayed. For a
group transaction entry in the resource control table, you can enter an identifier
for any transaction associated with the group.
Default: If you do not specify a transaction ID, information is displayed for all
active transactions listed in the resource control table.
STATISTICS
Displays the statistical counters associated with each entry in the resource
control table. The counters concern the usage of the available connections of
the CICS attachment facility to DB2.
Abbreviation: STAT

180 Command Reference


DSNC DISPLAY (CICS)
If you issue this command from CICS while the CICS attachment facility is
active but the DB2 subsystem is not, a statistics display is produced with no
obvious indication that the subsystem is not operational. Message DSNC037A
appears in the CICS message log to indicate that the attachment facility is
waiting for DB2 to start.
For a description of the output produced by this parameter, see Part 4 (Volume
1) of DB2 Administration Guide.
destination
Is the identifier of another terminal to receive the requested display information.
It must be a valid terminal that is defined to CICS and supported by CICS basic
mapping support (BMS).

Usage notes
Entering parameters: Because the optional destination is sometimes preceded by
an optional plan name or transaction ID in the command, each parameter must be
unique and separately identifiable as either a name or a terminal identifier. If only
one parameter is entered, it is first checked to see whether it is a plan name or a
transaction ID, and it is then checked as a destination. To use a character string
that is both a plan name or transaction ID and also a valid terminal identifier, you
must use both the name and destination parameters to display the desired
information at the desired terminal.

Acknowledging display information sent to an alternate destination: When an


alternate destination is specified to receive the requested display information, the
following message is sent to the requesting terminal:
DSNC020I THE DISPLAY COMMAND IS COMPLETE

Output
The following is an example of the output for the DSNC DISPLAY (PLAN or
TRANSACTION) command. For each created thread, the output shows the plan or
transaction name. An 'A' in field A/I indicates that the thread is within a unit of work.
An 'I' indicates that the thread is waiting for a unit of work authorization ID for the
plan being used.

DSNC013I DISPLAY REPORT FOLLOWS


NAME A/I AUTH-ID
XP05 A SYSADM
DSNC020I THE DISPLAY COMMAND IS COMPLETE

For each entry in the RCT, the output of a DSNC DISPLAY STATISTICS command
as seen in “Example 4” on page 183 displays the following information:
TRAN Transaction name. For group entries, this is the name of the first transaction
defined in the group. DSNC shows the statistics for the TYPE=COMD RCT
entry. POOL shows statistics for the TYPE=POOL entry, unless the
TYPE=POOL entry contains the parameter TXID=x.
PLAN The plan name associated with this entry. Eight asterisks in this field
indicates that this transaction is using dynamic plan allocation. The
command processor transaction DSNC does not have a plan associated
with it because it uses a command processor.
CALLS
The total number of SQL statements issued by transactions associated with
this entry.

Chapter 2. Commands 181


DSNC DISPLAY (CICS)
AUTHS
The total number of sign-on invocations for transactions associated with this
entry. A sign-on does not indicate whether a new thread is created or an
existing thread is reused. If the thread is reused, a sign-on occurs only if
the authorization ID or transaction ID has changed.
W/P The number of times that all available threads for this entry were busy. This
value depends on the value of TWAIT for the entry.
If TWAIT was set to POOL in the RCT, W/P indicates the number of times
the transaction overflowed to the pool. An overflow to the pool shows up in
the transaction statistics only and is not reflected in the pool statistics.
If TWAIT was set to YES, this reflects the number of times that the thread
both had to wait, and could not attach a new subtask (number of started
tasks has reached THRDA).
The only time W/P is updated for the pool is when a transaction had to wait
for a pool thread and a new subtask could not be attached for the pool. The
W/P statistic is useful for determining if there are enough threads defined
for the entry.
HIGH The maximum number of threads required by transactions associated with
this entry at any time since the connection was started. This number
includes the transactions that were forced to wait or diverted to the pool. It
provides a basis for setting the maximum number of threads for the entry.
ABORTS
The total number of units of recovery which were rolled back. It includes
both abends and SYNCPOINT ROLLBACKS, including SYNCPOINT
ROLLBACKS generated by -911 SQL codes.
COMMITS
One of the following two fields is incremented each time a DB2 transaction
associated with this entry has a real or implied (such as EOT) syncpoint.
Units of recovery that do not process SQL calls are not reflected here.
1-PHASE
The total number of single phase commits for transactions associated with
this entry. This total does not include any two-phase commits (see the
explanation for 2-PHASE below). This total does include read-only commits
as well as single phase commits for units of recovery which have performed
updates. A two-phase commit is needed only when CICS is the recovery
coordinator for more than one resource manager.
2-PHASE
The total number of two-phase commits for transactions associated with this
entry. This number does not include one-phase commit transactions.

Examples
Example 1: Display information on all active plan IDs listed in the resource control
table. The display information is to be sent to another terminal designated as
MTO2.
DSNC DISP PLAN * MTO2

Example 2: Display information about all active transactions listed in the resource
control table.
DSNC DISP TRANSACTION

182 Command Reference


DSNC DISPLAY (CICS)
Example 3: Display statistical counters associated with each entry in the resource
control table.
DSNC DISP STAT

Example 4: This is an example of the output for the DSNC DISPLAY STATISTICS
command:
DSNC014I STATISTICS REPORT FOR 'DSNCRCTC' FOLLOWS
-----COMMITS-----
TRAN PLAN CALLS AUTHS W/P HIGH ABORTS 1-PHASE 2-PHASE
DSNC 1 1 1 1 0 0 0
POOL POOL 0 0 0 0 0 0 0
XC01 DSNXC01 22 1 11 2 0 7 5
XC02 DSNXC02 0 0 0 0 0 0 0
XA81 DSNA81 0 0 0 0 0 0 0
XCD4 DSNCED4 0 0 0 0 0 0 0
XP03 DSNTP03 1 1 0 1 0 1 0
XA20 DSNTA20 1 1 0 1 0 0 1
XA88 ******** 0 0 0 0 0 0 0
DSNC020I THE DISPLAY COMMAND IS COMPLETE

Chapter 2. Commands 183


DSNC MODIFY (CICS)

DSNC MODIFY (CICS attachment facility)


The CICS attachment facility command DSNC MODIFY modifies the ERRDEST
entry in the resource control table (RCT), or the maximum active thread value
associated with a given transaction or group name.

Abbreviation: DSNC MODI

Environment
This command can be issued only from a CICS terminal.

Data sharing scope: Member

Authorization
This command requires an appropriate level of CICS authority, as described in the
appropriate CICS for MVS/ESA CICS-RACF Security Guide or CICS for MVS/ESA
Operations and Utilities Guide.

Syntax

 DSNC MODIFY DESTINATION old new 


TRANSACTION transaction-id integer

Option descriptions
DESTINATION
Specifies that the ERRDEST parameter of the resource control table is to be
changed, replacing the “old” destination ID with the “new” destination ID.
Abbreviation: DEST
old
Is any destination ID currently active in the ERRDEST of the resource
control table.
new
Is a new destination identifier. The new destination is verified to ensure that
it is an existing transient data entry in the destination control table.
TRANSACTION
Specifies that the maximum active thread value associated with the given
transaction or group is to be modified.
Abbreviation: TRAN
transaction-id
Is a valid transaction identifier. If the change is for a group transaction entry
in the RCT, any transaction ID associated with the group can be entered to
identify the entry.
integer
Is a new maximum value.

184 Command Reference


DSNC MODIFY (CICS)
Usage notes
Protected threads: If you increase the active thread value using the command
DSNC MODIFY TRANSACTION, the attributes of the TYPE=ENTRY macro are
used. If the TYPE=ENTRY definition does not include a setting for an attribute, then
the TYPE=INIT value is used.

Issuing DSNC MODIFY TRANSACTION to increase the total threads permitted


allows creation of unprotected threads. For example, assume THRDS=2, THRDA=2
and THRDM=6. If the total number of threads permitted is increased, the additional
threads are unprotected.

The command DSNC MODIFY TRANSACTION can also allow creation of protected
threads. If THRDS=2, THRDA=2 and THRDM=6 and the value of THRDA is
modified to 1, one of the protected threads is eliminated. If the value of THRDA is
then modified back to 2, the thread that is re-created is protected.

TRANSACTION thread limit: The integer specified in the command DSNC


MODIFY TRANSACTION cannot be larger than the value specified for the THRDM
parameter of the DSNCRCT TYPE=ENTRY macro. The lowest possible value is
zero. The value specified for the THRDM parameter is an upper limit (provided
during initialization) on the number of threads to be connected for a transaction
group. For more information about defining the thread limit, see Part 2 of DB2
Installation Guide.

Example
Change the specification of the ERRDEST parameter in the resource control table
from MTO1 to MTO2.
DSNC MODI DEST MTO1 MTO2

Chapter 2. Commands 185


DSNC STOP (CICS)

DSNC STOP (CICS attachment facility)


The CICS attachment facility command DSNC STOP stops the attachment facility.

Environment
This command can be issued only from a CICS terminal.

Data sharing scope: Member

Authorization
This command requires an appropriate level of CICS authority, as described in the
appropriate CICS for MVS/ESA CICS-RACF Security Guide or CICS for MVS/ESA
Operations and Utilities Guide.

Syntax

QUIESCE
 DSNC STOP FORCE 

Option descriptions
QUIESCE
Specifies that the CICS attachment facility is to be stopped after CICS
transactions currently running terminate.
Abbreviation: Q
FORCE
Specifies that the CICS attachment facility is to be stopped immediately by
forcing disconnection with DB2, regardless of any transactions that are running.

Usage notes
Requirements for restarting: Using FORCE can leave threads in an indoubt
situation. Restarting requires reconnection of CICS and DB2 to resolve any indoubt
situations. In a data sharing environment, resolution of indoubt situations requires
that the CICS be reconnected to the same DB2 member.

Output destinations: Output from the command DSNC STOP is sent to both the
requesting terminal, and to the transient data queue for error messages defined in
the DSNCRCT TYPE=INITIAL macro.

Example
Stop the CICS attachment facility.
DSNC STOP FORCE

186 Command Reference


DSNC STRT (CICS)

DSNC STRT (CICS attachment facility)


The DSNC STRT command starts the CICS attachment facility, which allows CICS
application programs to access DB2 databases.

Environment
This command can be issued only from a CICS terminal.

Data sharing scope: Member

Authorization
This command requires an appropriate level of CICS authority, as described in the
appropriate CICS for MVS/ESA CICS-RACF Security Guide or CICS for MVS/ESA
Operations and Utilities Guide.

Syntax

 DSNC STRT 
rct-suffix ,ssid

Option descriptions
rct-suffix
Specifies the resource control table to be loaded when the CICS attachment
facility starts. The rct-suffix, which can be one or two bytes, is appended to
DSN2CT to create the name of the resource control table. (For example, if you
specify 33 as the rct-suffix, module DSN2CT33 is loaded.)
The default is the suffix specified in the CICS INITPARM parameter, a feature
of the new CICS attachment facility. If a suffix was not specified in INITPARM,
the default is 00, and module DSN2CT00 is loaded.
ssid
Specifies the subsystem ID (SSID) field of the resource control table, which
allows the attachment facility to connect to any DB2 subsystem using just one
resource control table. No blanks are allowed between the suffix and the SSID.
The default is the SSID specified in the CICS INITPARM parameter. If an SSID
was not specified in INITPARM, the default is the SSID specified in the
resource control table.

Usage note
Output destinations: Output from the DSNC START command is sent to both the
requesting terminal, and to the transient data queue for error messages defined in
the DSNCRCT TYPE=INIT macro.

Examples
Example 1: Start the CICS Version 4 Release 1 attachment facility. Use
DSN2CT33 to connect to SSID DB2P.
DSNC STRT 33,DB2P

Chapter 2. Commands 187


DSNC STRT (CICS)
Example 2: Start the CICS Version 4 Release 1 attachment facility. Use the default
resource control table with SSID DBA1.
DSNC STRT ,DBA1

Example 3: Start the CICS Version 4 Release 1 attachment facility. Use DSN2CTA
to connect to the SSID that is specified in DSN2CTA.
DSNC STRT A

188 Command Reference


DSNH (TSO CLIST)

DSNH (TSO CLIST)


The DSNH command procedure (a TSO CLIST) is a powerful yet easy method of
preparing an application program for execution. By issuing a single command, you
can select numerous options required for the preparation of an application and
execute it under TSO.

DSNH processing is a sequential process that can include any of the following
actions referred to by the two-letter step name:

For invoking the... Use step name


PL/I macro processor MP
DB2 precompiler PC
CICS command language translator TR
DSN BIND PLAN subcommand for binding a plan BI
DSN BIND PACKAGE subcommand for binding a package BP
Compiler or assembler for your program CO
A C compiler prelink utility for including compile-time parameters PL
Link-editor to produce an executable load module LE
DSN RUN subcommand to execute the program RU
Note: The step names are used in the heading of Table 18 on page 190.

Individual steps or a sequence of steps can be performed, and you can end the
process at any point you choose. Any steps in the process that are skipped must
have been previously completed successfully by DSNH. For guidance in preparing
an application program for execution, see DB2 Application Programming and SQL
Guide. See Table 1 on page 7 for a description of the DSN BIND subcommands.

Environment
The DSNH CLIST can run in TSO foreground or in batch under the TSO terminal
monitor program. DB2I uses the DSNH CLIST on the precompiler panel to control
program preparation. You can pass DSNH parameters from DB2I panels on the
″Other options″ lines.

Data sharing scope: Member

Authorization
See “BIND PACKAGE (DSN)” on page 32 for a description of the privileges
necessary to bind a package.

See “BIND PLAN (DSN)” on page 38 for a description of the privileges necessary to
bind a plan.

See “RUN (DSN)” on page 262 for a description of the privileges necessary to run a
plan.

Chapter 2. Commands 189


DSNH (TSO CLIST)
Syntax

 DSNH INPUT(data-set-name) 

 clist-parameter

Summary of DSNH CLIST parameters


The CLIST parameters provide the processing options for each step; specify them
when you execute DSNH. Some parameters are used for more than one step, as
indicated in Table 18. The figure shows where each parameter is used, using the
following notation:
v Y in any cell shows that the option listed at the beginning of the row is used in
the step whose name appears at the top of the column.
v * in any cell indicates that the option listed at the beginning of the row is used in
another step which affects the step whose name appears at the top of the
column.

Notation of CLIST parameters for the BIND PLAN and BIND PACKAGE steps:
Many parameters of BIND PLAN and of BIND PACKAGE provide the same function
and are spelled alike. CLIST parameters for BIND PLAN and BIND PACKAGE are
differentiated from general parameters and from each other by prefixes. A
parameter name prefixed by the letter B applies to the BIND PLAN subcommand; a
parameter name prefixed by the letter P applies to BIND PACKAGE.

In Table 18, a prefix is separated from the DB2 parameter name by a slash (/).
Table 17 shows the variations possible for a single parameter name.
Table 17. DSNH CLIST prefixing rules
Parameter value Function or subcommand Example
parameter If no prefix is specified, the parameter applies to DBRMLIB
a single function or subcommand.
B/parameter The prefix B is used to indicate that this variation BDBRMLIB
of the parameter applies only to the BIND PLAN
step.
P/parameter The prefix P is used to indicate that this variation PDBRMLIB
of the parameter applies only to the BIND
PACKAGE step.

Table 18. Summary of DSNH CLIST parameters


OPTIONS MP PC TR BI BP CO PL LE RU
ACQUIRE - - - Y - - - - *
P/ACTION - - - Y Y - - - -
ASMLIB - - - - - Y - - -
ASMLOAD - - - - - Y - - -
P/BDMEM - - - Y Y - - - -
P/BIND - - - Y Y - - - -
P/BLIB - - - Y - - - - -
P/BnLIB - - - Y - - - - -
P/BMEM - - - Y Y - - - -
CACHESIZE - - - Y - - - - -

190 Command Reference


DSNH (TSO CLIST)
Table 18. Summary of DSNH CLIST parameters (continued)
OPTIONS MP PC TR BI BP CO PL LE RU
CCLINK - - - - - - Y - -
CCLLIB - - - - - - - Y -
CCLOAD - - - - - Y - - -
CCMSGS - - - - - Y Y - -
CCOLIB - - - - - - Y - -
CCPLIB - - - - - - - Y -
CCPMSGS - - - - - - Y - -
CCSLIB - - - - - Y - - -
P/CICS - - - Y Y - - - -
CICSCOB - - Y - - - - Y -
CICSLLIB - - Y - - - - Y -
CICSOPT - - Y - - - - - -
CICSPRE - - Y - - - - Y -
CICSPLIB - - Y - - - - Y -
CICSVER - - Y - - - - Y -
CICSXLAT - - Y - - - - - -
CLIB Y - - - - Y - - -
CnLIB Y - - - - Y - - -
COBICOMP - - - - - - - Y -
COBILINK - - - - - - - Y -
COBIPLNK - - - - - - Y - -
COBIPMSG - - - - - - Y - -
COBLIB - - - - - - - Y -
COBLOAD - - - - - Y - - -
COBSOM - - - - - - Y - -
COB2CICS - - - - - - - Y -
COB2LIB - - - - - - - Y -
COB2LOAD - - - - - Y - - -
COMPILE - - - - - Y - - -
CONNECT - Y - - - - - - -
CONTROL Y - Y * - Y - Y Y
COPTION Y - - - - Y - - -
COPY - - - - Y - - - -
COPYVER - - - - Y - - - -
CPPCLASS - - - - - - Y - -
CPPCLINK - - - - - - Y - -
CPPCLLIB - - - - - - - Y -
CPPCSLIB - - - - - Y - - -
CPPLLIB - - - - - - Y - -
CPPPMSGS - - - - - - Y - -
CPPSLIB - - - - - Y - - -
CPPUTIL - - - - - Y - - -
CURRENTDATA - - - Y Y - - - -
CURRENTSERVER - - - Y - - - - -
DATE - Y - - - - - - -
P/DBPROTOCOL - - - Y Y - - - -
P/B/DBRMLIB - Y - Y Y - - - -
DECARTH - Y - - - - - - -
DECIMAL - Y - - - * - - -
P/DEFER - - - Y Y - - - -
P/DEGREE - - - Y Y - - - -
DELIMIT - Y Y - - Y - - -
P/DISABLE - - - Y Y - - - -
DISCONNECT - - - Y - - - - -

Chapter 2. Commands 191


DSNH (TSO CLIST)
Table 18. Summary of DSNH CLIST parameters (continued)
OPTIONS MP PC TR BI BP CO PL LE RU
P/DLIBATCH - - - Y Y - - - -
P/DYNAMICRULES - - - Y Y - - - -
P/ENABLE - - - Y Y - - - -
ENTRY - - - - - - - Y -
EXPLAIN - - - Y Y - - - -
P/FLAG Y Y Y Y Y Y - - -
FORTLIB - - - - - - - Y -
FORTLOAD - - - - - Y - - -
GRAPHIC - Y - - - - - - -
HOST Y Y Y * - Y - Y Y
P/IMSBMP - - - Y Y - - - -
P/IMSMPP - - - Y Y - - - -
IMSPRE - - - - - - - Y -
INPUT Y Y * * - Y - Y Y
P/ISOLATION - - - Y Y - - - -
P/KEEPDYNAMIC - - - Y Y - - - -
LINECOUNT Y Y Y - - Y - - -
LINK - - - - - - - Y -
LLIB - - - - - - - Y -
LnLIB - - - - - - - Y -
LOAD - - - - - - - Y Y
LOPTION - - - - - - - Y -
MACRO Y - Y - - - - - -
NOFOR Y - - - - - - - -
P/NODEFER - - - Y Y - - - -
P/OPTHINT - - - Y Y - - - -
OPTIONS - Y Y - - - - Y Y
OUTNAME Y Y - - - Y - Y Y
P/OWNER - - - Y Y - - - -
PACKAGE - - - - Y - - - -
PARMS - - - - - - - - Y
PASS - Y - - - - - - -
P/PATH - - - Y Y - - - -
PCLOAD - Y - - - - - - -
PKLIST - - - Y - - - - -
PLAN - - - Y - - - - Y
PLIB - Y - - - - - - -
PnLIB - Y - - - - - - -
PLI2LIB - - - - - - - Y -
PLILIB - - - - - - - Y -
PLILOAD Y - - - - Y - - -
POPTION - - - - - - Y - -
PRECOMP - Y - - - - - - -
PRELINK - - - - - - Y - -
PRINT Y Y Y - - Y - Y -
PSECSPAC Y Y Y - - Y - - Y
PSPACE Y Y Y - - Y - - Y
P/QUALIFIER - - - Y Y - - - -
RCTERM Y Y Y Y Y Y Y - Y
P/RELEASE - - - Y Y - - - -
REMOTE - - - - Y - - - -
P/REOPT - - - Y Y - - - -
REPLVER - - - - Y - - - -
RETAIN - - - Y - - - - -

192 Command Reference


DSNH (TSO CLIST)
Table 18. Summary of DSNH CLIST parameters (continued)
OPTIONS MP PC TR BI BP CO PL LE RU
RUN - Y Y - - - - Y Y
RUNIN - - - - - - - - Y
RUNOUT - - - - - - - - Y
SOMDLLI - - - - - Y Y - -
SOURCE Y Y Y - - Y - - -
SPACEUN Y Y Y - - Y - - Y
SQL - Y - - - - - - -
SQLDELIM - Y - - - - - - -
SQLERROR - - - - Y - - - -
SQLFLAG - Y - - - - - - -
SQLRULES - - - Y - - - - -
STDSQL - Y - - - - - - -
SUFFIX Y Y - - - - - - -
SYSTEM - - - * * - - - Y
TERM Y Y - - - Y - Y -
TIME - Y - - - - - - -
P/VALIDATE - - - Y Y - - - -
VERSION - Y - - - - - - -
WORKUNIT Y Y Y - - Y - - -
WSECSPAC Y Y Y - - Y - - -
WSPACE Y Y Y - - Y - - -
XLIB - - - - - - - Y -
XREF Y Y - - - Y - Y -

General parameter descriptions


Due to similarities in name and function, the CLIST parameters for BIND PLAN and
BIND PACKAGE are described separately from the parameters in Table 19. For a
summary of:
v BIND PLAN parameters, see Table 20 on page 207
v BIND PACKAGE parameters, see Table 21 on page 210.
Also see “DSNH/DSN subcommand summary” on page 207 for a description of
conventions used in those tables.

The only parameter required on the DSNH statement is INPUT; the others are
optional. In the table of general parameters that follow:
v Parameter values must be enclosed between parentheses.
v Parameter values need not be enclosed between apostrophes. However,
– If the value is a list of tokens with separators, it must be enclosed between
apostrophes.
– If the value is a data set name, your user identifier is prefixed to it. To avoid
the prefix, enclose the name between sets of three apostrophes.
v Most parameter values that are data set names (dsname) cannot include
member names. Exceptions are noted in the parameter descriptions.
v Underlined values are defaults. Default names can be changed to names specific
to your site when DB2 is installed.

Chapter 2. Commands 193


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters
DSNH CLIST
Parameter Value Comments
ASMLIB dsname Specifies a data set to be used as the standard MACLIB for High Level
Assembler/MVS.

The default is ‘‘‘SYS1.MACLIB’’’.


ASMLOAD dsname Specifies a data set that contains the High Level Assembler/MVS load
module.

dsname can include a member name.

The default is ‘‘‘SYS1.LINKLIB(ASMA90)’’’.


CCLINK dsname Specifies a data set that contains the C compiler prelink utility invocation
load module.

dsname can include a member name.

The default for HOST(C) is ‘‘‘CEE.V1R3M0.SCEERUN(EDCPRLK)’’’.

The default for HOST(CPP) is ‘‘‘CEE.V1R4M0.SCEERUN(EDCPRLK)’’’.


CCLLIB dsname Specifies the data set that contains the linkage editor include modules for
the C compiler routines.

The default for HOST(C) is ‘‘‘CEE.V1R3M0.SCEELKED’’’.

The default for HOST(CPP) is ‘‘‘CEE.V1R4M0.SCEELKED’’’.


CCLOAD dsname Specifies a data set that contains the C compiler invocation load module.

dsname can include a member name.

The default for HOST(C) is ‘‘‘EDC.V1R2M0.SEDCDCMP(EDCDC120)’’’.

The default for HOST(CPP) is ‘‘‘CBC.V3R1M0.SCBC3CMP(CBC310)’’’.


CCMSGS dsname Specifies a data set that contains the C compiler messages.

dsname can include a member name.

The default for HOST(C) is ‘‘‘EDC.V1R2M0.SEDCDMSG(EDCMSGE)’’’.

The default for HOST(CPP) is ‘‘‘CBC.V3R1M0.SCBC3MSG(EDCMSGE)’’’.


CCOLIB NONE Specifies the data set that contains C object modules to be included during
dsname the execution of the prelink utility step.
CCPLIB NONE Specifies the data set containing include modules for PLI routines. This
dsname parameter is used only for IBM C/370 Version 2 or earlier.
CCPMSGS dsname Specifies the data set containing prelink utility error messages.

The default for HOST(C) is ‘‘‘CEE.V1R3M0.SCEEMSGP(EDCPMSGE)’’’.

The default for HOST(CPP) is ‘‘‘CEE.V1R4M0.SCEEMSGP(EDCPMSGE)’’’.


CCSLIB dsname Specifies the data set that contains the C compiler headers.

The default for HOST(C) is ‘‘‘EDC.V1R2M0.SEDCDHDR’’’.

The default for HOST(CPP) is ‘‘‘CBC.V1R4M0.SCEEH.H’’’.

194 Command Reference


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
CICSOPT NONE Gives a list of additional CICS translator options. See the appropriate CICS
option-list application programming reference for information about translator options.

NONE gives no additional options.


CICSPRE prefix Gives the prefix for the CICS libraries. The library names are:
prefix.LOADLIB for translators
prefix.PL1LIBn for PL/I include
prefix.COBLIB for COBOL include

Leave this parameter blank to use CICSLLIB, CICSPLIB, CICSCOB.

The default is blank.


CICSLLIB dsname Specifies the CICS load library. To use this library, leave the CICSPRE
parameter blank.

The default is set on install panel DSNTIP3.


CICSPLIB dsname Specifies the CICS PL/I library. To use this library, leave the CICSPRE
parameter blank.

The default is set on install panel DSNTIP3.


CICSCOB dsname Specifies the CICS COBOL library. To use this library, leave the CICSPRE
parameter blank.

The default is set on install panel DSNTIP3.


CICSVER 21 Specifies the CICS release, as follows:
31
Value CICS Release
33
21 Using CICS/MVS 2.1.2.
41
31 Using CICS/ESA 3.1.1.
33 Using CICS/ESA 3.2.1 or 3.3.0.
41 Using CICS/ESA Version 4

The default is 33.


CICSXLAT NO Tells whether to execute the CICS command translator. The option is
YES effective only if you use RUN(CICS). You cannot use the option with the
MARGINS option of the translator.

The default is YES. The DB2I panel default is NO.


CLIB NONE Specifies a data set that contains host language source statements to be
CnLIB dsname included by the compiler or assembler. The parameters CnLIB (where n can
be 2, 3, or 4) are extensions of CLIB, used to simplify passing a list of data
set names.

Use NONE to specify no data set.


COBICOMP dsname Specifies the IBM COBOL data set required for compilation.

The default is ‘‘‘IGY.V1R2M0.SIGYCOMP’’’.


COBILINK dsname Specifies the IBM COBOL data set required for link edit.

The default is ‘‘‘CEE.V1R5M0.SCEELKED’’’.


COBIPLNK dsname Specifies the IBM COBOL data set required for prelink routines.

The default is ‘‘‘CEE.V1R5M0.SCEERUN’’’.

Chapter 2. Commands 195


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
COBIPMSG dsname Specifies the IBM COBOL data set required for prelink messages.

The default is ‘‘‘CEE.V1R5M0.SCEEMSGP(EDCPMSGE)’’’.


COBLIB dsname Specifies the linkage editor include library to be used for OS/VS COBOL
routines.

The default is ‘‘‘SYS1.COBLIB’’’.


COBLOAD dsname Specifies a data set that contains the OS/VS COBOL compiler load module.

dsname can include a member name.

The default is ‘‘‘SYS1.LINKLIB(IKFCBL00)’’’.


COBSOM dsname Specifies the IBM System Object Model (SOM) data set required for access
to SOM objects.

The default is ‘‘‘SOMMVS.V1R1M0.SGOSPLKD’’’.


COB2CICS dsname Specifies the linkage editor include library to be used for VS COBOL II CICS
routines.

The default is ‘‘‘SYS1.COB2CICS’’’.


COB2LIB dsname Specifies the linkage editor include library to be used for the VS COBOL II
or COBOL/370 routines.

The default is ‘‘‘SYS1.V1R3.COB2LIB’’’.


COB2LOAD dsname Specifies a data set that contains the VS COBOL II or COBOL/370 compiler
load module.

dsname can include a member name.

The default is ‘‘‘SYS1.V1R3.COB2COMP(IGYCRCTL)’’’.


COMPILE YES Tells whether to execute the compiler or assembler if the precompile step is
NO successful.
CONNECT (1) Specifies whether a CONNECT SQL statement should be processed as a
(2) type 1 CONNECT or a type 2 CONNECT statement. The DSNH(TSO
CLIST) command does not accept the CT(1) and CT(2) abbreviations for
this precompiler option.

The default is CONNECT(2).


CONTROL NONE CONTROL helps you trace the allocation of non-existent data sets. Use
CONLIST CONTROL if you have a problem without an obvious cause.
LIST
SYMLIST CONLIST displays CLIST commands after substitution for symbols and
before command execution.

LIST displays TSO commands after substitution for symbols and before
command execution.

SYMLIST displays all executable statements (TSO commands and CLIST


statements) before substitution for symbols.

196 Command Reference


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
COPTION NONE Gives a list of compiler or assembler options. For more information, see the
string manual that describes the compiler or assembler options for the specific
language you are using. For a list of restrictions on some options, see
“COBOL Options” on page 213.

NONE gives no options.


CPPCLASS dsname Specifies the data set containing C⁺⁺ class libraries.

The default is ‘‘‘CBC.V3R1M0.SCLB3CPP’’’.


CPPCLINK dsname Specifies the data set containing prelink utility modules used by the C⁺⁺
compiler.

The default is ‘‘‘CEE.V1R4M0.SCEERUN(EDCPRLK)’’’.


CPPCLLIB dsname Specifies the data set for C linkage editor automatic call library used by the
C⁺⁺ compiler.

The default is ‘‘‘CEE.V1R4M0.SCEELKED’’’.


CPPCSLIB dsname Specifies data set containing the C compiler headers used by the C⁺⁺
compiler.

The default is ‘‘‘CBC.V1R4M0.SCEEH.H’’’.


CPPLLIB dsname Specifies the data set containing the C⁺⁺ prelink automatic call library.

The default is ‘‘‘CEE.V1R4M0.SCEECPP’’’.


CPPPMSGS dsname Specifies the data set containing prelink utility error messages used by the
C⁺⁺ compiler.

The default is ‘‘‘CEE.V1R4M0.SCEEMSGP(EDCPMSGE)’’’.


CPPSLIB dsname Specifies the data set containing C⁺⁺ header files for class libraries.

The default is ‘‘‘CBC.V3R1M0.SCLB3H.H’’’.


CPPUTIL dsname Specifies the data set containing procedures to set up and execute the C⁺⁺
compiler.

The default is ‘‘‘CBC.V3R1M1.SCBC3UTL’’’.


DATE ISO Specifies the format of date values that are to be returned overriding the
JIS format specified as the location default.
USA
EUR The default is the value supplied when DB2 was installed, and is written in
LOCAL the data-only load module, DSNHDECP.

Chapter 2. Commands 197


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
DBRMLIB DEFAULT Specifies the partitioned data set, and optionally a member name, that
dsname(member) contains the DBRM library and member name used during the DB2
NONE precompile step. Because you can specify an individual DBRM member and
library names during each individual phase, you must use the DBRMLIB
parameter and associated prefixes to identify a specific phase. DBRMLIB
specifies the DBRM library and member defined on the DBRMLIB DD
statement during DB2 precompiler processing.

DEFAULT indicates that the same DBRM library data set defined for the
DB2 precompiler process (DBRMLIB(parameter)) is also used on the
LIBRARY(dsname) subcommand keyword. If the precompiler DBRMLIB was
not specified, then the default generated DBRMLIB library based upon the
INPUT data set name is used.

dsname is generated using the DSNH OUTNAME parameter value, or its


default TEMP, with the constant DBRM appended to the prefix; for example,
outname.DBRM or TEMP.DBRM.

member is obtained from the data set member name specified on the DSNH
INPUT parameter, or from the data set name as follows:
Given INPUT(outname.DBRM(dbrmmem)):
– outname.DBRM(dbrmmem) - If member name is specified
– outname.DBRM(dbrm) - If no member name is specified

NONE indicates that no LIBRARY(dsname) subcommand keyword is


specified on invocation.
DECARTH DEFAULT Sets the maximum precision of decimal numbers.
15
31 DEFAULT designates the value chosen, during installation, for the DECIMAL
ARITHMETIC field on the APPLICATION PROGRAMMING DEFAULTS
panel.

15 specifies that decimal arithmetic operations on decimal values with


precision 15 or less are performed in accordance with the existing rules for
determining the precision and scale of the result.

31 specifies that decimal arithmetic operations on decimal values with


precision 15 to 31 are performed in accordance with new rules for
determining the precision and scale of the result.

DECARTH is ignored for Fortran.


DECIMAL COMMA Gives the decimal point indicator for decimal and floating point literals.
PERIOD DECIMAL is valid only for COBOL programs; PERIOD is forced for all other
programs.

COMMA makes the indicator a comma.

PERIOD makes the indicator a period.

The default is the value of the DECIMAL POINT field, set on the DB2
APPLICATION PROGRAMMING DEFAULTS panel during installation.

198 Command Reference


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
DELIMIT DEFAULT Sets the APOST or QUOTE precompiler option to indicate the string
APOST delimiter used within host language statements. DELIMIT is effective only for
QUOTE COBOL programs; APOST is forced for all other programs.

DEFAULT designates the value chosen, during installation, for the STRING
DELIMITER field on the APPLICATION PROGRAMMING DEFAULTS panel.

APOST specifies the apostrophe as the string delimiter for host language
statements.

QUOTE specifies a quotation mark as the string delimiter for host language
statements.
ENTRY entry-name Specifies the entry point assigned by the linkage editor.

The default depends on the host language and the value of RUN.
v For the PL/I language, the ENTRY value default is:
– NONE if the RUN value is CICS
– PLISTART for any other RUN value.
v For the ASM language, the ENTRY value default is DLITASM if the RUN
value is IMS.
v For COBOL, the ENTRY value default is DLITCBL if the RUN value is
IMS.
v For any other language, the ENTRY value default is NONE (no specified
entry point) for any RUN value.
FLAG I Tells what messages you want to see. Use one of the values listed to show
C messages of the corresponding types:
E v I All informational, warning, error, and completion messages
W v W Only warning, error, and completion messages
v E Only error and completion messages
v C Only completion messages
FORTLIB dsname Specifies the linkage editor include library to be used for Fortran routines.

The default is ‘‘‘SYS1.VSF2FORT’’’.


FORTLOAD dsname Specifies a data set that contains the VS Fortran compiler load module.
dsname can include a member name.

The default is ‘‘‘SYS1.VSF2VCOMP(FORTVS2)’’’.


GRAPHIC NONE Specifies the value of the DSNHDECP MIXED option for the precompiler.
NO
YES NONE indicates that the default specified during install is used.

NO indicates that the data is not mixed DBCS.

YES indicates that all character data can be mixed DBCS.

GRAPHIC is ignored for C.

Chapter 2. Commands 199


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
HOST ASM Defines the host language within which SQL statements are embedded.
C
CPP If your program fits one of the following descriptions, you cannot use DB2I
COBOL to prepare it:
COB2 v An IBM COBOL for MVS & VM program that uses object-oriented
IBMCOB extensions
FORTRAN v A C⁺⁺ program that uses object-oriented extensions and consists of more
PLI than one compilation unit

The default is the value of the LANGUAGE DEFAULT field, set on the DB2
APPLICATION PROGRAMMING DEFAULTS panel during installation.
IMSPRE prefix Sets the prefix for RESLIB, used for routines to be included by the linkage
editor for IMS.

The default is IMSVS.


INPUT dsname Specifies the data set that contains the host language source and SQL
statements.

dsname can include a member name.


LINECOUNT integer Tells how many lines, including headings, are to be printed on each page of
printed output.

The default is 60.


LINK YES Tells whether to execute the linkage editor upon successful completion of
NO compilation or assembly.

YES indicates that the linkage editor is to be executed. The DSNHLI entry
point from the precompiler is directed to the appropriate language interface
module specified by the RUN parameter.

NO indicates that linkage editor processing is to be bypassed.


LLIB NONE Specifies a data set that contains object or load modules to be included by
LnLIB dsname the linkage editor. The parameters LnLIB (where n can be 2, 3, or 4) are
extensions of LLIB, used to simplify passing a list of data set names.

The LLIB and LnLIB libraries are concatenated with the XLIB library and the
linkage editor include libraries for the specific host language. Object and
load module libraries must not be mixed in this concatenation.

Use NONE to specify no data set.


LOAD dsname Specifies a data set that is to contain the output from the linkage editor (the
load module).

dsname can include a member name.

The default is RUNLIB.LOAD.


LOPTION NONE Gives a list of linkage editor options. For information on options you can
string use, see the appropriate MVS/ESA publication.

Use NONE to give no options.

200 Command Reference


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
MACRO YES Tells whether the macro preprocessor is to be executed before the
NO precompilation of a PL/I program. If the PL/I macro processor is used, the
PL/I *PROCESS statement must not be used to pass options to the PL/I
compiler. The COPTION parameter of the DSNH command can be used to
pass the needed options to the PL/I compiler.
NOFOR NO Allows elimination of all FOR UPDATE OF clauses in static SQL.
YES
When NOFOR is in effect, the FOR UPDATE OF clause is optional.
Positioned updates can be made to any columns that the user has authority
to update.

When NOFOR is not in effect, any query appearing in a DECLARE


CURSOR statement must contain a FOR UPDATE OF clause if the cursor is
used for positional updates. The clause must designate all the columns that
the cursor can update.

The option is implied when the STDSQL(YES) option is in effect.


OPTIONS NO Tells whether to print the options used when executing the precompiler or
YES the CICS command translator with the output listing.
OUTNAME TEMP Gives a prefix used to form intermediate data set names.
string
string must not be enclosed between apostrophes and must not have the
same initial character as the dsname for INPUT. It cannot contain special
characters.
PARMS NONE Gives a parameter string to be passed to the compiled program during its
string execution; the run time execution environment requested is TSO. If CAF is
specified as the run time execution environment, this parameter is ignored.

Use NONE to pass no parameter string.


PASS ONE or 1 Tells how many passes the precompiler is to use. One pass saves
TWO or 2 processing time, but requires that declarations of host variables in the
program precede any reference to those variables. PASS has no effect for
COBOL or Fortran; ONE is forced.

The default is ONE or 1 for PL/I and C.

The default is TWO or 2 for assembler.


PCLOAD dsname Specifies the precompiler load module.

dsname can include a member name.

The default is ‘‘‘prefix.SDSNLOAD(DSNHPC)’’’.


PLAN plan-name Specifies the application plan created by the bind process.

The default plan name is the first of the following available choices defined
in the INPUT data set:
v DBRM member name
v Leftmost qualifier

plan-name must not be DEFAULT.

If no name is found, a plan is not created.

Chapter 2. Commands 201


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
PLIB NONE Specifies the data set that contains host language source or SQL
PnLIB dsname statements included by the SQL INCLUDE statement during precompilation.
The parameters PnLIB (where n can be 2, 3, or 4) are extensions of PLIB,
used to simplify passing a list of data set names.

Use NONE to specify no data set.


PLI2LIB dsname Specifies the linkage editor common library used for PL/I routines.

The default is ‘‘‘SYS1.SIBMBASE’’’.


PLILIB dsname Specifies the linkage editor base library used for PL/I routines.

The default is ‘‘‘SYS1.PLIBASE’’’.


PLILOAD dsname Specifies a data set that contains the PL/I optimizing compiler load module.

dsname can include a member name.

The default is ‘‘‘SYS1.LINKLIB(IEL0AA)’’’.


POPTION NONE Gives a list of the C compiler language prelink utility options. For information
string on the options provided, refer to the IBM SAA AD/Cycle C/370 User's Guide.

Use NONE to give no options.


PRECOMP YES Tells whether to precompile.
NO
PRELINK YES Tells whether to execute the C compiler prelink utility to make your program
NO reentrant. This utility concatenates compile-time initialization information (for
writable static) from one or more text decks into a single initialization unit. If
this step is requested, it must follow the compile step and precede the
link-edit step.

This parameter can apply to IBMCOB that also has a prelink step. Whether
the prelink step applies to C or IBMCOB is determined by the choice of
values C, CPP, or IBMCOB for the HOST parameter.

Descriptions of the prelink process for C and IBMCOB are presented in their
respective language publications.

If PRELINK(YES) is specified or defaulted for a HOST language compiler


that does not support the prelink utility, DB2 will issue warning message
DSNH760I and prelink utility processing will be bypassed.

202 Command Reference


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
PRINT NONE Tells where to send printed output, including the lists of options, source,
dsname cross-reference, error, and summary information.
LEAVE
TERM NONE omits printed output.

dsname specifies a data set to be used for the output. Do not enclose
dsname between apostrophes. The current user profile is prefixed to
dsname. The following suffixes are also added:
v SYSCPRT.LIST for PL/I macro listings (these listings are overwritten by
the compiler listings)
v PCLIST for precompiler listings
v CXLIST for CICS command translator listings
v LIST for compiler listings
The PRINT parameter is ignored for the compile step when HOST(CPP)
is specified.
v SYSOUT.PRELLIST for C prelink utility listings
v LINKLIST for link-edit listings

LEAVE sends output to the specified print data set. You can allocate the
print data set:
v Dynamically
v In the JCL used to run the DSNH CLIST (if in batch mode)
v With the TSO ALLOCATE command (before running DSNH)

TERM sends output to the terminal.


PSECSPAC integer Tells the amount of secondary space to allocate for print data sets, in the
units given by SPACEUN.

The default is 20.


PSPACE integer Tells the primary size of the print data sets in the units given by SPACEUN.

The default is 20.


RCTERM integer Gives the least value of the return code from the precompile step that
prevents execution of later steps.

The default is 8.

Chapter 2. Commands 203


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
RUN TSO or YES Tells whether to execute the compiled program if the previous steps are
BATCH or NO successful, and, if so, in which environment it executes. Your choice for the
CAF RUN parameter might affect your choice for LLIB.
CICS
IMS TSO or YES indicate that the application program is to be scheduled for
RRSAF execution in the TSO environment, and execute the compiled program.

BATCH or NO indicate that the application program is not to be scheduled


for execution, and default to TSO as the execution environment.

CAF indicates that the application program is to be scheduled for execution


in the call attachment facility environment. Specify BATCH or NO with CAF
to indicate that the application program is not to be scheduled for execution,
but to identify CAF as the execution environment. (BATCH,CAF) or
(NO,CAF)

CICS indicates that the application program is not to be scheduled for


execution, and identifies CICS as the RUN time execution environment.
(CICS applications cannot run in TSO.)

IMS indicates that the application program is not to be scheduled for


execution, and identifies IMS as the RUN time execution environment. (IMS
applications cannot run in TSO.)

RRSAF indicates that the application program is not to be scheduled for


execution, and identifies RRSAF as the RUN time execution environment.
(RRSAF applications cannot run in TSO.)
RUNIN TERM Tells where to get input for the RUN step.
dsname
LEAVE TERM gets input from the terminal.
NONE
dsname specifies a data set to be used for the input.

LEAVE gets input from SYSIN if the only steps taken are LINK and RUN.
LEAVE gets input from FT05F001 if the language is Fortran. Do not use
LEAVE for any other cases.

NONE allocates no input file.


RUNOUT TERM Tells where to send output from the RUN step.
dsname
LEAVE TERM sends output to the terminal.
NONE
dsname specifies a data set to receive output.

LEAVE sends output to SYSPRINT if the only steps taken are LINK and
RUN. LEAVE sends output to FT06F001 if the language is Fortran. Do not
use LEAVE for any other cases.

NONE allocates no output file for the RUN step.


SOMDLLI dsname Tells the name to be passed of the SOM/MVS DLL import library.

The default is ‘‘‘SOM.SGOSIMP’’’.


SOURCE NO Tells whether the source code and diagnostics are to be printed with output
YES from the precompiler, CICS command translator, and compiler.

204 Command Reference


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
SPACEUN TRACK Specifies the unit of space for PSPACE and WSPACE.
CYLINDER
TRACK makes the space unit one track.

CYLINDER makes the space unit one cylinder.


SQL DB2 Interprets SQL statements and checks syntax for use by either DB2 for
ALL OS/390 and z/OS or other database management systems.

DB2 indicates that SQL statements are to be interpreted and syntax is to be


checked for use by DB2. SQL(DB2) is the recommended mode for DRDA
access when the server is a DB2 subsystem.

ALL indicates that SQL statements are to be interpreted for use by database
management systems that are not DB2 for OS/390 and z/OS. SQL syntax
checking is deferred until bind time so that the remote location can bind the
resulting DBRM. When SQL(ALL) is in effect, the precompiler issues an
informational message if SAA reserved words are used as identifiers.
SQL(ALL) is the recommended mode if you have written your application to
be executed in a environment that is not DB2 for OS/390 and z/OS.

The default is SQL(DB2).


SQLDELIM DEFAULT Sets the APOSTSQL or QUOTESQL precompiler option, to specify the SQL
APOSTSQL string delimiter and, by implication, the SQL escape character within SQL
QUOTESQL statements. Whichever character is chosen to be the string delimiter, the
other is used for the SQL escape character.

This parameter is effective only for COBOL. For PL/I, Fortran, and
assembler language programs, the precompiler forces the APOSTSQL
option.

DEFAULT designates the value chosen, during installation, for the SQL
STRING DELIMITER field on the APPLICATION PROGRAMMING
DEFAULTS panel.

APOSTSQL specifies that the string delimiter is the apostrophe (') and the
escape character is the quotation mark (").

QUOTESQL specifies that the string delimiter is the quotation mark (") and
the escape character is the apostrophe (').
SQLFLAG IBM or SAA Specifies the standard to be used to check the syntax of SQL statements.
STD or 86 Deviations from the standard are flagged by informational messages written
ssname to the precompiler output listing.
qualifier
IBM or SAA requests the use of the IBM SQL Version 2 syntax.

STD or 86 requests the use of the SQL92 Entry Level syntax.

ssname requests full semantics checking for catalog access using the
specified DB2 subsystem name. If ssname is not specified, only syntax
checking is performed.

qualifier specifies the qualifier to be used for unqualified object names. If


qualifier is specified, ssname must always be specified first. If qualifier is not
specified, the default is the authorization ID of the process that executed
the precompiler.

Chapter 2. Commands 205


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
STDSQL NO Interprets SQL using a subset of ANSI rules.
YES or 86
NO specifies that DB2 rules are used.

YES or 86 automatically implies that the NOFOR option is used.


SUFFIX YES Tells whether the TSO standard naming convention must be followed. That
NO convention adds a TSO authorization ID prefix and a host language suffix to
the name of the input data set (unless that name is enclosed between
apostrophes, or already ends in the appropriate suffix). For example, names
become userid.name.COBOL, userid.name.PLI, userid.name.Fortran, or
userid.name.ASM.
SYSTEM subsystem-name Gives the DB2 subsystem name as it is known to MVS.

The default is the installation-defined subsystem name (often DSN).


TERM TERM Tells where to send terminal output, including error information, error
dsname statements, and summary information.
LEAVE
NONE TERM sends output to the terminal.

dsname specifies a data set to be used for terminal output. Do not enclose
dsname between apostrophes. The following suffixes are added to dsname:
v PCTERM for precompiler output
v LIST for compiler output

LEAVE sends the output to the current allocation for SYSTERM.

NONE omits terminal output.


TIME ISO Specifies the format for time values that are to be returned, overriding the
JIS format specified as the location default.
USA
EUR There is no default, because this option overrides the default previously
LOCAL specified.
VERSION version-id Specifies the name of the version ID for the program and associated DBRM
AUTO during the DB2 precompile.

AUTO specifies that the consistency token is used to generate the version
ID. If the consistency token is a timestamp, the timestamp is converted into
ISO character format and used as the version identifier.

The default is no version ID if specified at precompiler invocation.


WORKUNIT unit Tells what device to use for print and work data sets.

unit can be a unit name or a device type.

The default in batch mode is any eligible device.

The default in any other mode is the UADS unit name for the current TSO
user.
WSECSPAC integer Tells the amount of secondary space to allocate for work data sets, in the
units given by SPACEUN.

The default is 20.


WSPACE integer Tells the primary size of the work data sets in the units given by SPACEUN.

The default is 20.

206 Command Reference


DSNH (TSO CLIST)
Table 19. General DSNH CLIST parameters (continued)
DSNH CLIST
Parameter Value Comments
XLIB dsname Specifies the linkage editor include library to be used for DB2 routines.

The default is ‘‘‘prefix.SDSNLOAD’’’.


XREF NO Tells whether a sorted cross-reference listing of symbolic names used in
YES source statements is to be printed with output from the precompiler.

DSNH/DSN subcommand summary


The following tables differentiate the functions that support BIND PLAN and BIND
PACKAGE. Each table associates the DSNH CLIST parameter and its
corresponding DSN BIND PLAN or BIND PACKAGE subcommand keyword, if any.
In general:
v The function and value of a CLIST parameter is identical to that of its
corresponding DSN subcommand keyword unless otherwise noted.
v A DSNH parameter value of NONE indicates that the corresponding DSN
keyword is not specified on subcommand invocation. Exceptions are noted where
applicable.

DSNH CLIST/BIND PLAN subcommand comparison


Table 20. DSNH CLIST/ BIND PLAN subcommand summary
DSNH CLIST BIND PLAN subcommand
Parameter Value Keyword Value Comments
ACQUIRE USE ACQUIRE USE
ALLOCATE ALLOCATE
ACTION REPLACE ACTION REPLACE
ADD ADD
BDMEM DEFAULT1 MEMBER dbrm-member-name 1
DBRM member name
dbrm-member-name obtained from one of the
NONE2 following sources, in the order
listed:
v BDBRMLIB member name
v DBRMLIB member name
v INPUT member name, or
generated using dsname.
2
Keyword is not specified on
subcommand invocation.
BIND YES1 (command-verb) 1
Execute BIND PLAN
NO2 subcommand.
2
Do not execute BIND PLAN
subcommand.
BLIB NONE1 LIBRARY dbrm-pds-name 1
Keyword is not specified on
dsname subcommand invocation.

Chapter 2. Commands 207


DSNH (TSO CLIST)
Table 20. DSNH CLIST/ BIND PLAN subcommand summary (continued)
DSNH CLIST BIND PLAN subcommand
Parameter Value Keyword Value Comments
1 2 1
BnLIB NONE LIBRARY list of n can be 2, 3, 4, 5, 6, 7, or
dsname dbrm-pds-names 8. Specify the first data set
name using the BLIB
parameter and any additional
data set names using this
parameter.
2
No additional data set
names.
BMEM1 NONE2 MEMBER list of 1
Specify the first DBRM
list of dbrm-member dbrm-member- member name using the
-names names BDMEM parameter and any
additional member names
individually using this
parameter.
2
No additional DBRM
member names.
CACHESIZE NONE1 CACHESIZE decimal-value2 1
The size is provided by the
decimal-value2 subsystem.
2
Specify a size from 0 to
4096 bytes.
CICS NONE1 CICS application-ids 1
Keyword is not specified on
application-ids subcommand invocation.
CURRENTDATA YES CURRENTDATA YES
NO NO
NONE
CURRENTSERVER NONE1 CURRENTSERVER location-name
location-name
DBPROTOCOL NONE DBPROTOCOL DRDA
DRDA PRIVATE
PRIVATE
BDBRMLIB DEFAULT1 LIBRARY dbrm-pds-name 1
The precompiler DBRMLIB
dsname(member) data set is used. If the
NONE2 precompiler DBRMLIB is not
specified, then the
default-generated DBRMLIB
library based upon the INPUT
data set is used.
2
Keyword is not specified on
subcommand invocation.
DEFER NONE1 DEFER PREPARE 1
Keyword is not specified on
PREPARE subcommand invocation.
DEGREE 1 DEGREE 1
ANY ANY

208 Command Reference


DSNH (TSO CLIST)
Table 20. DSNH CLIST/ BIND PLAN subcommand summary (continued)
DSNH CLIST BIND PLAN subcommand
Parameter Value Keyword Value Comments
DISABLE NONE DISABLE NONE
BATCH BATCH
CICS CICS
DB2CALL DB2CALL
IMS IMS
DLIBATCH DLIBATCH
IMSBMP IMSBMP
IMSMPP IMSMPP
RRSAF RRSAF
DISCONNECT EXPLICIT DISCONNECT EXPLICIT
AUTOMATIC AUTOMATIC
CONDITIONAL CONDITIONAL
DLIBATCH NONE1 DLIBATCH connection-name 1
Keyword is not specified on
list of subcommand invocation.
connection-ids
DYNAMICRULES RUN DYNAMICRULES RUN
BIND BIND
ENABLE NONE ENABLE NONE
* *
BATCH BATCH
CICS CICS
DB2CALL DB2CALL
IMS IMS

DLIBATCH DLIBATCH
IMSBMP IMSBMP
IMSMPP IMSMPP

RRSAF RRSAF
EXPLAIN NO EXPLAIN NO
YES YES
FLAG I FLAG I
C C
E E
W W
IMSBMP NONE1 IMSBMP imsid 1
Keyword is not specified on
imsid subcommand invocation.
IMSMPP NONE1 IMSMPP imsid 1
Keyword is not specified on
imsid subcommand invocation.
ISOLATION RR ISOLATION RR
RS RS
CS CS
UR UR
KEEPDYNAMIC NO KEEPDYNAMIC NO
YES YES
NODEFER NONE1 NODEFER PREPARE 1
Keyword is not specified on
PREPARE subcommand invocation.
OPTHINT (’ ’) OPTHINT (’ ’)
(’hint-id’) (’hint-id’)

Chapter 2. Commands 209


DSNH (TSO CLIST)
Table 20. DSNH CLIST/ BIND PLAN subcommand summary (continued)
DSNH CLIST BIND PLAN subcommand
Parameter Value Keyword Value Comments
1 1
OWNER NONE OWNER authorization-id Keyword is not specified on
authorization-id subcommand invocation.
PATH (schema-name) PATH (schema-name)
(USER)(schema- (USER)(schema-
name, USER...) name, USER...)
PKLIST NONE1 PKLIST list of collection-ids 1
The package names are not
list of and package- specified on subcommand
collection-ids names invocation.
and package-
names
PLAN plan-name1 PLAN plan-name 1
plan-name must not be
DEFAULT. The default
(primary-keyword) plan-name is the first of the
following available choices
defined in the INPUT data set:
v DBRM member name
v Leftmost qualifier
If no name is found, a plan is
not created.
QUALIFIER NONE1 QUALIFIER qualifier-name 1
Keyword is not specified on
implicit-qualifier subcommand invocation.
RELEASE COMMIT RELEASE COMMIT
DEALLOCATE DEALLOCATE
REOPT NONE1 NOREOPT VARS 1
Keyword is not specified on
VARS REOPT VARS subcommand invocation.
RETAIN NO1 RETAIN 1
Keyword is not specified on
YES2 subcommand invocation.
2
Keyword is specified on
subcommand invocation.
SQLRULES DB2 SQLRULES DB2
STD STD
VALIDATE RUN VALIDATE RUN
BIND BIND

DSNH CLIST/BIND PACKAGE subcommand comparison


Table 21. DSNH CLIST/ BIND PACKAGE subcommand summary
DSNH CLIST BIND PACKAGE subcommand
Parameter Value Keyword Value Comments
PACTION REPLACE ACTION REPLACE
ADD ADD
PBIND NO1 (command-verb) 1
Do not execute BIND
YES2 PACKAGE subcommand.
2
Execute BIND PACKAGE
subcommand.

210 Command Reference


DSNH (TSO CLIST)
Table 21. DSNH CLIST/ BIND PACKAGE subcommand summary (continued)
DSNH CLIST BIND PACKAGE subcommand
Parameter Value Keyword Value Comments
1 1
PCICS NONE CICS application-ids Keyword is not specified on
application-ids subcommand invocation.
COPY NONE1 COPY collection-id. 1
Keyword is not specified on
collection-id. package-id subcommand invocation.
package-id
COPYVER version-id COPYVER version-id
PCURRENTDATA NO CURRENTDATA YES
YES NO
NONE
PDBPROTOCOL NONE DBPROTOCOL DRDA
DRDA PRIVATE
PRIVATE
PDBRMLIB DEFAULT1 LIBRARY dbrm-pds-name 1
The precompiler DBRMLIB
dsname(member) data set is used. If the
NONE2 precompiler DBRMLIB is not
specified, then the
default-generated DBRMLIB
library based upon the INPUT
data set is used.
2
Keyword is not specified on
subcommand invocation.
PDEFER NONE1 DEFER PREPARE 1
Keyword is not specified on
PREPARE subcommand invocation.
PDEGREE 1 DEGREE 1
ANY ANY
PDISABLE NONE DISABLE NONE
BATCH BATCH
CICS CICS
DB2CALL DB2CALL
IMS IMS

DLIBATCH DLIBATCH
IMSBMP IMSBMP
IMSMPP IMSMPP

REMOTE REMOTE
RRSAF RRSAF
PDLIBATCH NONE1 DLIBATCH connection-name 1
Keyword is not specified on
list of subcommand invocation.
connection-ids
PDMEM DEFAULT1 MEMBER dbrm-member- 1
DBRM member name
dbrm-member- name obtained from one of the
name following sources, in the order
NONE2 listed:
v PDBRMLIB member name
v DBRMLIB member name
v INPUT member name, or
generated using dsname
2
Keyword is not specified on
subcommand invocation.

Chapter 2. Commands 211


DSNH (TSO CLIST)
Table 21. DSNH CLIST/ BIND PACKAGE subcommand summary (continued)
DSNH CLIST BIND PACKAGE subcommand
Parameter Value Keyword Value Comments
PDYNAMICRULES NONE DYNAMICRULES RUN
RUN BIND
BIND DEFINE
DEFINE INVOKE
INVOKE
PENABLE NONE ENABLE NONE
* *
BATCH BATCH
CICS CICS
DB2CALL DB2CALL
IMS IMS

DLIBATCH DLIBATCH
IMSBMP IMSBMP
IMSMPP IMSMPP

REMOTE REMOTE
RRSAF RRSAF
EXPLAIN NO EXPLAIN NO
YES YES
PFLAG I FLAG I
C C
E E
W W
PIMSBMP NONE1 IMSBMP imsid 1
Keyword is not specified on
imsid subcommand invocation.
PIMSMPP NONE1 IMSMPP imsid 1
Keyword is not specified on
imsid subcommand invocation.
PISOLATION NONE1 ISOLATION1 RR 1
For local packages, the
RR RS default value is the same as
RS CS that of the plan appended at
CS UR execution time. For remote
UR NC packages, the default value is
NC RR.
PKEEPDYNAMIC NONE KEEPDYNAMIC NO
NO YES
YES
PNODEFER NONE1 NODEFER PREPARE 1
Keyword is not specified on
PREPARE subcommand invocation.
POPTHINT (’ ’) OPTHINT (’ ’)
(’hint-id’) (’hint-id’)
POWNER NONE1 OWNER authorization-id 1
Keyword is not specified on
authorization-id subcommand invocation.
PACKAGE DEFAULT1 PACKAGE location-name. 1
Member name defined in the
location-name. collection-id INPUT parameter data set, or
collection-id the data set name if no
member name was specified.
PPATH (schema-name) PATH (schema-name)
(USER)(schema- (USER)(schema-
name, USER, ...) name, USER, ...)

212 Command Reference


DSNH (TSO CLIST)
Table 21. DSNH CLIST/ BIND PACKAGE subcommand summary (continued)
DSNH CLIST BIND PACKAGE subcommand
Parameter Value Keyword Value Comments
1 1
PQUALIFIER NONE QUALIFIER qualifier-name Keyword is not specified on
implicit-qualifier subcommand invocation.
PRELEASE NONE1 RELEASE1 COMMIT 1
For local packages, the
COMMIT DEALLOCATE default value is the same as
DEALLOCATE that of the plan appended at
execution time. For remote
packages, the default value is
NONE.
REOPT NONE1 NOREOPT VARS 1
Keyword is not specified on
VARS REOPT VARS subcommand invocation.
REMOTE NONE1 REMOTE network-name 1
Keyword is not specified on
location-name, subcommand invocation.
<luname>
REPLVER NONE1 REPLVER version-id 1
version-id is not specified on
version-id subcommand invocation.
SQLERROR NOPACKAGE SQLERROR NOPACKAGE
CONTINUE CONTINUE
PVALIDATE RUN VALIDATE RUN
BIND BIND

Usage notes
CICS translator: Do not use CICS translator options in the source language for
assembler programs; pass the options to the translator with the CICSOPT option.

COBOL options: The COBOL DYNAM option has several restrictions:


v You cannot use the option with CICS.
v You must use the VS COBOL II library or the Language Environment (Language
Environment for MVS & VM) library.
v To use the option with TSO or batch, the SDSNLOAD library must precede the
IMS RESLIB in the step library, job library, or link list concatenations.
v To use the option with IMS, the IMS RESLIB must precede DSNLOAD.

Several COBOL options require DD statements that are not provided by the DSNH
CLIST, as shown in Table 22.
Table 22. COBOL options that require additional DD statements
Option Statements required for...
CDECK SYSPUNCH
COUNT SYSCOUNT, SYSDBG, SYSDBOUT, SYSUT5, a debug file
DECK SYSPUNCH
DUMP SYSABEND, SYSDUMP, or SYSUDUMP
FDECK SYSPUNCH
FLOW SYSCOUNT, SYSDBG, SYSDBOUT, SYSUT5, a debug file
LVL SYSUT6
STATE SYSCOUNT, SYSDBG, SYSDBOUT, SYSUT5, a debug file

Chapter 2. Commands 213


DSNH (TSO CLIST)
Table 22. COBOL options that require additional DD statements (continued)
Option Statements required for...
SYMDUMP SYSCOUNT, SYSDBG, SYSDBOUT, SYSUT5, a debug file
SYST SYSOUT
SYSx SYSOUx
TEST SYSUT5

COBOL parameters: The BUF and SIZE parameters passed to the COBOL
compiler might have to be changed.

COPTION: Do not use the COPTION parameter to specify values for the
LINECOUNT, SOURCE, TERM, and XREF compiler options; use the DSNH
LINECOUNT, SOURCE, TERM, and XREF keywords.

Fortran and PL/I considerations: Variable-format input records are not supported.

Library limits: There can be at most eight bind libraries, four precompile libraries,
four compile libraries, and four link-edit libraries.

Link-edit:
v DSNH cannot process programs that need additional link-edit control statements,
and cannot link-edit programs that use the call attachment facility.
v You cannot use the NOLOAD and SYNTAX link-edit options.

NONE is a reserved word: NONE cannot be the name of an input or a load library,
or the value of the string passed with PARMS.

SQL host variables: SQL host variables must be explicitly defined.

SYSPROC: If compilation is done, the SYSPROC data set must include the DB2
CLIST library.

WORKUNIT parameter: You must use the WORKUNIT parameter when running
the DSNH CLIST in batch mode. This insures that the temporary and intermediate
data sets are allocated to the correct devices.

Examples
Example 1: Precompile, bind, compile, link-edit, and run the COBOL program in
data set prefix.SDSNSAMP(DSN8BC4).
v The compiler load module is in SYS1.LINKLIB (IKFCBL00).
v Additional load modules to be included are in prefix.RUNLIB.LOAD and
prefix.SDSNSAMP.
v The load module is be put into the data set prefix.RUNLIB.LOAD(DSN8BC4).
v The plan name is DSN8BC71 for the bind and run.
v DCLGEN data from prefix.SRCLIB.DATA is required for the precompile.
This example assumes that the DSNH CLIST is in your SYSPROC concatenation.
DSNH INPUT('prefix.SDSNSAMP(DSN8BC4)'') -
COBLOAD('SYS1.LINKLIB(IKFCBL00)'') -
LLIB('prefix.RUNLIB.LOAD'') -
L2LIB('prefix.SDSNSAMP'') -
LOAD('prefix.RUNLIB.LOAD'') -
PLAN(DSN8BC71) -
PLIB('prefix.SRCLIB.DATA'')

214 Command Reference


DSNH (TSO CLIST)
Example 2: Precompile, bind, compile, and link-edit the program in data set
prefix.SDSNSAMP.PLI(DSN8BP4).
v The program is written in PL/I; the macro pass is not needed.
v The PL/I compiler options MAP and LIST are to be used.
v Additional load modules to be included are in prefix.RUNLIB.LOAD and
prefix.SDSNSAMP.
v The PL/I optimizing compiler load module is in library SYS2.LINKLIB(IEL0AA).
v The DB2 subsystem identifier is SSTR.
v The load module is put into the data set prefix.RUNLIB.LOAD(DSN8BC4).
v Printed output is sent to the following data sets:
Output Data set
Precompiler listings
prefix.PROG.PCLIST
Compiler listings
prefix.PROG.LIST
Link edit listings
prefix.PROG.LINKLIST
v The plan name is DSN8BC71 for the bind and run.
v The DCLGEN data from prefix.SRCLIB.DATA is required for the precompile.
DSNH INPUT('prefix.SDSNSAMP(DSN8BP4)'') -
HOST(PLI) MACRO(NO) -
COPTION ('MAP LIST') -
LLIB('prefix.RUNLIB.LOAD'') -
L2LIB('prefix.SDSNSAMP'') -
PLILOAD('SYS2.LINKLIB(IEL0AA)'') -
SYSTEM(SSTR) -
LOAD('prefix.RUNLIB.LOAD'') -
PRINT(PROG) -
PLAN(DSN8BC71) -
PLIB('prefix.SRCLIB.DATA'')

The COPTION parameters are enclosed between single apostrophes so that they
are passed by TSO as a single parameter. If a single token is being passed as a
parameter, no apostrophes are needed. That same rule applies to the PARMS and
CICSOPT parameters.

If a data set name is being passed as a parameter, and you want TSO to add your
user prefix, no apostrophes are needed. If the usual TSO prefixing and suffixing
must not be performed, the data set name must be enclosed between sets of three
apostrophes if the CLIST is executed implicitly, and sets of six apostrophes if the
CLIST is executed explicitly.

The user prefix for that example is prefix; if it had been SMITH, the listing data set
names would be as shown above, except that SMITH would be used as the first
level qualifier. For example, the compiler listings would have gone to
SMITH.PROG.LIST.

Example 3: Invocation of the DB2-C sample application program


prefix.SDSNSAMP(DSN8BD3).
v The C linkage editor include library is EDC.V1R1M1.SEDCBASE
v The C compiler load module is EDC.V1R1M1.SEDCCOMP(EDCCOMP)
v Printed output is sent to the following data sets:
Output Data set
Precompiler listings
user_id.TEMP.PCLIST

Chapter 2. Commands 215


DSNH (TSO CLIST)
Compiler listings
user_id.TEMP.SYSCPRT.LIST
Prelink utility listings
user_id.TEMP.SYSOUT.PRELLIST
Link-edit listings
user_id.TEMP.LINKLIST
v The following C DD names are allocated based on the PRINT keyword value:
DD name
Allocation
SYSCPRT
Used in the compile step
SYSUT10
Used in the compile step
SYSOUT
Used in the prelink step.

SYSUT10 and SYSCPRT are always allocated to the same data set or
destination.
v SYSTERM is used in the compile step. It is based on the TERM keyword.
v CEEDUMP is used in the run step. It is based on the RUNOUT keyword.
v The LOPTION keyword values of AMODE(31) and RMODE(ANY) are required
when link editing the C sample program to insure 31-bit addressability during
execution.
ALLOC DD(SYSPROC) DSN('prefix.SDSNCLST ') SHR
%DSNH BIND(YES) ACQUIRE(USE) ACTION(REPLACE)-
EXPLAIN(NO) -
CICSXLAT(NO) -
COMPILE(YES) -
CCLLIB('EDC.V1R1M1.SEDCBASE'')-
CCLOAD('EDC.V1R1M1.SEDCCOMP(EDCCOMP)'')-
DBRM('prefix.DBRMLIB.DATA(DSN8BD3)'')-
DECIMAL(PERIOD) DELIMIT(DEFAULT) FLAG(I)-
HOST(C) ISOLATION(RR)-
INPUT('prefix.SDSNSAMP(DSN8BD3)'')-
LINK(YES)-
LLIB('prefix.RUNLIB.LOAD'')-
L2LIB('prefix.SDSNLOAD'')-
LOAD('prefix.RUNLIB.LOAD'')-
LOPTION('AMODE(31) RMODE(ANY)')-
MACRO(NO)-
OUTNAME(TEMP)-
PLAN(DSN8BD31) PRECOMP(YES)-
PLIB('prefix.SDSNSAMP'')-
PRELINK(NO)-
POPTION(NONE)-
PRINT(TEMP) RCTERM(8)-
RELEASE(COMMIT) RETAIN(YES)-
RUN(NO) RUNIN(TERM)-
RUNOUT(TERM) SOURCE(YES)-
SYSTEM(DSN) SQLDELIM(DEFAULT)-
VALIDATE(RUN)

216 Command Reference


END (DSN)

END (DSN)
The DSN subcommand END is used to end the DSN session and return to TSO.

Environment
This subcommand originates from a TSO input stream when DSN is running in
either background or foreground mode.

Data sharing scope: Member

Authorization
None is required.

Syntax

 END 

Usage note
Ending the DSN session in batch or foreground: In batch, if END is not found in
the SYSIN stream, /* or // ends the DSN session. From the foreground, pressing
the ATTENTION key twice ends the DSN session.

Example
End the DSN session and return to TSO.
TSO prompt : READY
USER enters: DSN SYS (SSTR)
DSN prompt : DSN
USER enters: RUN PROGRAM (MYPROG)
DSN prompt : DSN
USER enters: END
TSO prompt : READY

Chapter 2. Commands 217


FREE PACKAGE (DSN)

FREE PACKAGE (DSN)


The DSN subcommand FREE PACKAGE can be used to delete a specific version
of a package, all versions of a package, or whole collections of packages.

The FREE PACKAGE subcommand deletes corresponding table entries from the
catalog tables. Authorization for a package name is only removed when no more
versions of the package exist. After a version of a package has been freed, that
package name is then available for use in a BIND PACKAGE subcommand to
create a new package.

The FREE PACKAGE subcommand does not proceed until all currently executing
applications using the package finish executing.

For additional information about packages, see Part 5 of DB2 Application


Programming and SQL Guide.

Environment
You can enter this subcommand from DB2I, or from a DSN session under TSO that
is running in either foreground or background.

Data sharing scope: Group

Authorization
To execute this subcommand, the privilege set of the process must include one of
the following:
v Ownership of the package
v BINDAGENT privilege granted by the owner of the package
v SYSCTRL or SYSADM authority
v PACKADM authority for the collection or for all collections

The BIND privilege on a package is not sufficient to allow a user to free a package.

Syntax

 FREE PACKAGE 

 (  collection-id . package-id ) 
location-name. * * .( )
version-id
*
*

 
I
FLAG( W )
E
C

218 Command Reference


FREE PACKAGE (DSN)
Option descriptions
location-name
Specifies the location of the DBMS where the package is to be freed. The
location name must be defined in the SYSIBM.LOCATIONS table. If this table
does not exist or the DBMS is not found, you receive an error message. If the
location name is specified, the name of the local DB2 must be defined. See
Part 3 of DB2 Installation Guide for information on how to define a location
name within SYSIBM.LOCATIONS.
The default is the local DB2 if you omit location-name.
collection-id or (*)
Identifies the collection of the package to be freed. There is no default.
You can use an asterisk (*) to free all local packages with the specified
package-id in all the collections that you are authorized to free. (You cannot use
the * to free remote packages.)
package-id or (*)
Identifies the package to be freed. There is no default.
You can use an asterisk (*) to free all local packages in collection-id that you
are authorized to free. (You cannot use the * to free remote packages.)
version-id or (*)
Identifies the version of the package to be freed.
You can use an asterisk (*) to free all local packages in the collection-id and
package-id that you are authorized to free. (You cannot use the * to free remote
packages.)
If you specify () for version-id, then the empty string is used for the version ID.
If you omit the version-id, the default depends on how you specify package-id. If
you use * for package-id, version-id defaults to *. If you provide an explicit value
for package-id, version-id defaults to an empty string.
DBRMs created before DB2 Version 2 Release 3 use an empty string for
version-id by default.
(*)
Frees all local DB2 packages that you are authorized to free.
Specifying (*) is equivalent to specifying the package name as (*.*.(*)) or (*.*).
FLAG
Indicates what messages you want to see. Use one of the values listed to show
messages of the corresponding types.
(I) All: informational, warning, error, and completion messages.
(W) Only warning, error, and completion messages.
(E) Only error and completion messages.
(C) Only completion messages.

Usage notes
Freeing multiple packages: If you free multiple packages with this subcommand,
each successful free is committed before freeing the next package.

Chapter 2. Commands 219


FREE PACKAGE (DSN)
If an error occurs on a certain package specified explicitly in a list or implicitly with
(*), FREE PACKAGE terminates for that package and continues with the next
package to be processed.

Freeing trigger packages: You cannot free a trigger package using the FREE
PACKAGE subcommand.

For more information about dropping triggers, see Chapter 5 of DB2 SQL
Reference.

Examples
Example 1: Free version newver of the package TEST.DSN8BC71 located at
USIBMSTODB22. Generate only warning, error, and completion messages (not
informational messages).
FREE PACKAGE (USIBMSTODB22.TEST.DSN8BC71.(newver)) FLAG(W)

Example 2: Free all packages at the local server in the collection named
TESTCOLLECTION.
FREE PACKAGE (TESTCOLLECTION.*)

220 Command Reference


FREE PLAN (DSN)

FREE PLAN (DSN)


The DSN subcommand FREE PLAN deletes application plans from DB2.

The FREE PLAN subcommand deletes corresponding table entries from the
SYSIBM.SYSPLAN catalog tables. All authorization against an application plan
name is dropped. The application plan name is then available for use in a BIND
PLAN subcommand to create a new package.

The FREE PLAN subcommand does not proceed until all currently executing
applications using that plan finish executing.

For additional information on plans, see Part 5 of DB2 Application Programming and
SQL Guide.

Environment
You can enter this subcommand from DB2I, or from a DSN session under TSO that
is running in either foreground or background.

Data sharing scope: Group

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v Ownership of the plan
v BIND privilege on the plan
v BINDAGENT privilege granted by the plan owner
v SYSCTRL or SYSADM authority

Syntax

 FREE PLAN (  plan-name ) 


* I
FLAG( W )
E
C

Option descriptions
(plan-name, ...)
Lists the names of one or more plans you want to free.
(*) Frees all application plans over which you have BIND authority. Be careful
when using this form of the command.
FLAG
Indicates what messages you want to see. Use one of the values listed to show
messages of the corresponding types.
(I) All: informational, warning, error, and completion messages.
(W) Only warning, error, and completion messages.
(E) Only error and completion messages.

Chapter 2. Commands 221


FREE PLAN (DSN)
(C) Only completion messages.

Usage notes
Freeing multiple plans: If you free multiple plans with this subcommand, each
successful free is committed before freeing the next plan.

If an error occurs on a certain plan specified explicitly in a list or implicitly with (*),
FREE PLAN terminates for that plan and continues with the next plan to be
processed.

Example
Free plan DSN8BC71 from DB2. Generate only warning, error, and completion
messages (not informational messages).
FREE PLAN (DSN8BC71) FLAG (W)

222 Command Reference


MODIFY ..., ABEND (MVS IRLM)

MODIFY irlmproc,ABEND (MVS IRLM)


The MODIFY irlmproc, ABEND command terminates the IRLM abnormally. IRLM
processes this command even if there is a DB2 identified to it.

Abbreviation: F

Environment
This command can be issued only from an MVS console.

Data sharing scope: Member

Authorization
The command requires an appropriate level of MVS authority, as described in
OS/390 MVS System Commands.

Syntax

,DUMP
 MODIFY irlmproc,ABEND 
,NODUMP

Option descriptions
Parameters must be separated by commas with no spaces.
irlmproc
Identifies the procedure name of the IRLM that is to be terminated.
DUMP
Specifies that IRLM is to terminate abnormally with a U2020 abend. A system
dump is taken to the SYS1.DUMPXX data set. IRLM does not de-register from
ARM.
NODUMP
Specifies that IRLM is to FORCE the DBMS off and terminate normally without
generating a dump. All DBMS work is quiesced and IRLM stops itself.
A second invocation will cause IRLM to terminate abnormally with a U2020
abend; no dump will be taken.

Usage notes
Terminating IRLM: If there are any difficulties terminating IRLM, see “Usage note”
on page 324

Deregistering IRLM: You can use the NODUMP option to deregister IRLM before
stopping it. This action prevents the automatic restart manager from immediately
trying to restart IRLM.

Example
Enter on an MVS system console:
F KRLM001,ABEND

Chapter 2. Commands 223


MODIFY ..., ABEND (MVS IRLM)
Response on the MVS system console:
DXR124E IR21001 ABENDED VIA MODIFY COMMAND
*IEA911E COMPLETE DUMP ON SYS1.DUMP00
FOR ASID(0004)
ERROR ID = SEQ00001 CPU00 ASID0004 TIME08.34.59.9
DXR121I IR21001 END-OF-TASK CLEANUP SUCCESSFUL
IEF450I IR21001 IR21001 - ABEND=S000 U2020 REASON=00000000

The default is dump. If you do not want a dump, you must specify:
F KRLM001,ABEND,NODUMP

224 Command Reference


MODIFY ..., DIAG (MVS IRLM)

| MODIFY irlmproc,DIAG (MVS IRLM)


# The MODIFY irlmproc, DIAG command initiates diagnostic dumps for IRLM
# subsystems.

Abbreviation: F

Environment
This command can be issued only from an MVS console.

Data sharing scope: Group

Authorization
The command requires an appropriate level of MVS authority, as described in
OS/390 MVS System Commands.

Syntax

 MODIFY irlmproc,DIAG ,DELAY 


,PLOCK
,ALL
,NONE
,HANG

Option descriptions
Parameters must be separated by commas with no spaces.
irlmproc
Identifies the procedure name of the IRLM instance that is to be diagnosed.
DIAG
Indicates that this is a diagnostic dump.
DELAY
Directs IRLM to generate a dump the first time it detects that child lock
propagation to the coupling facility is taking longer than 45 seconds. The dump
is placed in the SYS1.DUMPxx data set.
| PLOCK
| Directs IRLM to generate a dump the first time it detects that P-lock negotiation
| is taking longer than two minutes. Dumps of the IRLM and DB2 address spaces
| are taken and placed in the SYS1.DUMPxx data set.
| ALL
| Directs IRLM to generate diagnostic dumps for IRLM or DBMS subsystems in a
| data sharing group for the following unusual conditions:
| v P-lock negotiation takes longer than two minutes
| v Child-lock propagation takes longer than 45 seconds

# If IRLM detects a delay in the child-lock propagation process, it retries the XES
# calls in order to recover.

Chapter 2. Commands 225


MODIFY ..., DIAG (MVS IRLM)
| NONE
| Disables generating all diagnostic dumps.
# HANG
# Collects IRLM SYSPLEX dumps when DEADLOCK or TIMEOUT issues are
# suspected. The dumps are taken during DEADLOCK processing. The
# DEADLOCK processing is stopped and the dynamic deadlock storage is
# collected. MVS DUMP services then schedules an SRB to restart DEADLOCK
# processing. Message DXR183I is issued by each IRLM as DEADLOCK
# processing is restarted. If message DXR183I is not issued by an IRLM, that
# IRLM must be terminated and restarted.

# Note: Always start the IRLM XCF CTRACE internally and wait 30 seconds
# before issuing this command.

# Usage note
# The MODIFY irlmproc,DIAG command should be used only under the direction of
# IBM service.

Restrictions: This command is active for only one incident per IRLM, that is, after
an IRLM instance detects the delay and initiates the dump. You can initiate one
dump per IRLM in the group. You must re-enter the command to initiate another
dump. Be aware that when you enter this command for one member of the data
sharing group, any member that detects the delay initiates a dump.

The irlmproc identifies the procedure name for IRLM. If multiple IRLM instances
exist in the same system, each procedure must have a unique procedure name.

Example
Issue this command to initiate one diagnostic dump for the IR21PROC IRLM
subsystem. The dump occurs once, after the propagation of child locks takes longer
than 45 seconds.
MODIFY IR21PROC,DIAG,DELAY

226 Command Reference


MODIFY ..., PURGE (MVS IRLM)

| MODIFY irlmproc,PURGE (MVS IRLM)


| The MODIFY irlmproc,PURGE command releases IRLM locks retained due to a
| DB2, IRLM, or system failure. The command causes all retained locks for the
| specified DB2 to be deleted from the system, thereby making them available for
| update. Since retained locks protect updated resources, it should be used only after
| understanding what the resources are and the consequence to data integrity if they
| are deleted.

| Abbreviation: F

| Environment
| This command can be issued only from an MVS console.

| Data sharing scope: Member

| Authorization
| The command requires an appropriate level of MVS authority, as described in
| OS/390 MVS System Commands.

| Syntax
|

 MODIFY irlmproc,PURGE,db2name 

| Option descriptions
| Use commas with no spaces to separate parameters.
| irlmproc
| Specifies the IRLM that is to process the command.
| db2name
| The DB2 name, as displayed by the STATUS command.

| Usage notes
| DB2 subsystem inactive: The DB2 subsystem which owns the retained locks must
| be inactive or else this command will fail.

| Example
| Example: Enter on an MVS system console:
| F IR21I,PURGE,DB2A

| Response on the MVS system console:


| DXR109I IR21001 PURGE COMMAND COMPLETED FOR DB2A
|

Chapter 2. Commands 227


MODIFY ..., SET (MVS IRLM)

MODIFY irlmproc,SET (MVS IRLM)


The MODIFY irlmproc, SET command performs the following tasks:
v Dynamically sets the maximum CSA allowed for IRLM.
v Dynamically sets the number of trace buffers allowed for IRLM.
# v Dynamically sets the number of LOCK LTE entries to be specified on the next
| connect to the XCF LOCK structure.
| v Dynamically sets the timeout value for a specified subsystem.
# v Dynamically sets the local deadlock frequency.

Abbreviation: F

Environment
This command can be issued only from an MVS console.

Data sharing scope: Member

Authorization
The command requires an appropriate level of MVS authority, as described in
OS/390 MVS System Commands.

Syntax

 MODIFY irlmproc,SET ,CSA=nnn 


,DEADLOCK=nnnn
,LTE=nnnn
,TIMEOUT=nnnn,subsystem-name
10
,TRACE= nnn

Option descriptions
Use commas with no spaces to separate parameters.
irlmproc
Specifies the IRLM that is to process the command.
SET
# Sets the following values for this IRLM:
CSA=nnn
Requests that IRLM dynamically set the maximum amount of common
storage area (CSA) for this IRLM to use for lock control structures. nnn
must be a one- to three-digit number from 1 through 999. The number
indicates what multiple of 1 MB of storage the specified IRLM will use.
For example, CSA=6 allows the IRLM to use 6 MB of CSA.
The lock control structures are allocated from extended common
storage area (ECSA) when PC=NO, or from IRLM private region when
PC=YES.
IRLM does not immediately allocate CSA storage for the new value you
set using this command; IRLM allocates storage as needed, not to
exceed the amount of CSA specified. If the amount of storage currently

228 Command Reference


MODIFY ..., SET (MVS IRLM)
allocated by IRLM is greater than the amount of CSA you specify using
this command, IRLM does not obtain more storage until normal
processing frees enough storage to bring the current allocation below
the new CSA value you set.
# DEADLOCK=nnnn
# Specifies the number, in milliseconds, indicating how often the local
# deadlock processing is scheduled. nnnn must be a number from 100
# through 5000 milliseconds. If a member of a sysplex group and all
# IRLMs are not enabled for subsecond deadlock processing, message
# DXR106E is issued.
# LTE=nnnn
# Specifies the number of LOCK Table Entries to be specified on the next
connect to the XCF LOCK structure. nnnn must be a number from 0
through 1024, and be an even power of two. Each increment in value
# represents 1048576 LTE entries. Note that this parameter is used for
| data sharing only.
| TIMEOUT=nnnn,subsystem-name
| Requests that IRLM dynamically set the timeout value for the specified
| subsystem. nnnn must be a number from 1 through 3600.
| subsystem-name is the DB2 subsystem name, as displayed by the
| MODIFY irlmproc,STATUS command.
TRACE=nnn
Requests that IRLM dynamically set the maximum number of 64 KB
trace buffers per trace type to the value you specify in nnn. nnn must
be a number from 10 through 255. If you specify a value outside of this
range, IRLM automatically adjusts the value to a value within the range.
The default is 10.
This value is used only when the external CTRACE writer is not
activated. The trace buffers are allocated from extended common
storage area (ECSA).
IRLM does not immediately acquire the number of trace buffers you set
using this command; IRLM allocates buffers as needed, not to exceed
the number of buffers you specified. If the number of trace buffers you
set is less than the number of currently allocated buffers, IRLM brings
the number within your specified range by releasing the oldest buffers
at the end of the next deadlock or timeout cycle.

Usage notes
Determining limits for CSA values: Do not modify the CSA value without first
contacting the system programmer to determine the amount of CSA storage that
can be used for IRLM.

Effect of an IRLM restart: The values you set using the MODIFY irlmproc,SET
command do not persist through a stop and restart of IRLM. The number of trace
buffers for each trace type returns to the default value of 10, and the value for
MAXCSA returns to the value you set for the MAXCSA parameter on the IRLM
startup procedure.

| TIMEOUT considerations: The TIMEOUT value must be a multiple of the local


| deadlock parameter. If the value entered is not an even multiple of the deadlock
| parameter, IRLM will increase the timeout value to the next highest multiple. This
| new value is used until the IRLM or identified subsystem is terminated, or the

Chapter 2. Commands 229


MODIFY ..., SET (MVS IRLM)
| timeout is changed again by the operator. The value specified on the command
| does not affect the timeout value in the DB2 ZParms.

# Effect of the LTE parameter: If a syntax error is made, message DXR106E is


# issued. Syntax errors include LTE value out-of-range. If this IRLM is not connected
# to the group, but the value specified is valid, a message DXR177I is issued stating
# that the value has been set, but the value will not be sent to any other member. If
# the member is already in the group, the value is sent to the Global Deadlock
# Manager IRLM to be broadcast to all other members. If the GDM does not have the
# code applied, no DXR177I message is issued on any member. If the GDM has the
# code, then all members with the code applied will issue the DXR177I message as
# the command is processed. This value is only used if the IRLM is the first to join
# the data sharing group, causing structure allocation or during a REBUILD. If any
# IRLM joins later, it will not have the updated value. If multiple MODIFY commands
# are issued on the same or multiple IRLMs, some DXR177I messages may be
# missing. The last DXR177I message issued is the value to be used on the next
# CONNECT.

# The value for the number of LOCK Table Entries specifed during normal group
startup and during REBUILD are used in the following order:
# 1. The value specified on the MODIFY irlmproc,SET,LTE= command, if greater
than 0.
# 2. The value from the LTE= in the IRLMPROC, if greater than 0.
| 3. The existing logic, which determines the nearest power of 2 after dividing the
| QUERY size returned by 2 times LTE width based on MAXUSRS.

| If an attempt is made to use a nonzero value from either option number 1 or 2, and
| that value is too large for the structure size returned on the QUERY, then the value
| from the next option in the sequence will be used instead.

# Deadlock value range for non-supporting members: When an IRLM that


# supports subsecond deadlock joins a group that has a member that does not
# support subsecond deadlock, if the deadlock value of the new member is less than
# one second, then the value is set to one second.

Examples
Example 1: Enter on an MVS system console:
# F IR21I,SET,CSA=10

Response on the MVS system console:


# DXR177 I IR21001 MAXCSA IS SET TO 10

# Explanation: IR21001 is the IRLM subsystem name concatenated with the IRLM
# system ID.

Example 2: Enter on an MVS system console:


F IR21PROC,SET,TRACE=20

Response on the MVS system console:


DXR177I IR21033 THE VALUE FOR TRACE IS SET TO 20.

| Example 3: Enter on an MVS system console:


| F IR21PROC,SET,TIMEOUT=60,DBMS

230 Command Reference


MODIFY ..., SET (MVS IRLM)
| Response on the MVS system console:
| DXR177I IR21033 THE VALUE FOR TIMEOUT IS SET TO 60 FOR DBMS

| Example 4: Enter on an MVS system console:


# F IR21PROC,SET,LTE=1024

| Response on the MVS system console:


# DXR177I IR21033 THE VALUE FOR LTE IS SET TO 1024

| Example 5: Enter on an MVS system console:


# F IR21I,SET,DEADLOCK=1000

# Response on the MVS system console:


# DXR177I IR21033 THE VALUE FOR DEADLOCK IS SET TO 1000 MILLISECONDS

Chapter 2. Commands 231


MODIFY ..., STATUS (MVS IRLM)

MODIFY irlmproc,STATUS (MVS IRLM)


This command displays information for one or more subsystems connected to the
specified IRLM designated using irlmproc. Each subsystem connected to the
specified IRLM is listed, including subsystem name, status, work unit and lock
information. Additionally, you can list an IRLM’s ID and service level. For a specified
IRLM, you can display the current storage allocated, as well as the greatest amount
of storage that has been allocated since the last time this IRLM was started.

Abbreviation: F

Environment
This command can be issued only from an MVS console.

Data sharing scope: Member or group, depending on which option you choose

Authorization
The command requires an appropriate level of MVS authority, as described in
OS/390 MVS System Commands.

Syntax

,irlmx
 MODIFY irlmproc,STATUS 
,ALLD
,ALLI
,MAINT
,STOR
,TRACE

Option descriptions
irlmproc
Specifies the IRLM that is to process the command.
irlmx
Specifies which IRLM’s status is to be displayed. irlmx is the concatenation of
the IRLM subsystem name and IRLM member ID as specified in the IRLM
startup procedure (DB2 installation panel DSNTIPI). An example is DB2G2 (ID
is 2).
ALLD
Requests the DB2 subsystem name and status of a DB2 that is identified to an
IRLM. In the data sharing group, this command lists information about all DB2s
that are currently identified to an IRLM, assuming that the IRLM on which the
command is issued is connected to the data sharing group. You can determine
if the IRLM is connected by issuing a MODIFY irlmproc,STATUS command and
checking that the output shows SCOPE=GLOBAL.
If a DB2 is down and holds retained locks, that DB2 is also displayed. However,
the IRLM that is displayed with that DB2 can vary depending on several
circumstances:
v Normally, it is the last IRLM to which DB2 identified.

232 Command Reference


MODIFY ..., STATUS (MVS IRLM)
v If there was a rebuild of the lock structure after the retained locks were
created, it is the IRLM with the lowest member ID at the time the rebuild
occurred.
v If a group restart is occurring and one DB2 is recovering on behalf of another
DB2, the IRLM that is displayed is the one associated with the DB2 doing the
peer recovery. For example, if DB2A is doing a peer recovery of DB2B, the
display might show:
NAME STATUS ... IRLM_NAME
DB2A UP IRLA
DB2B DOWN IRLA
ALLI
Requests the IRLM subsystem name, ID, status, and service level. In a data
sharing group, this command lists information about all IRLMs in the data
sharing group, assuming that the IRLM on which the command is issued is
connected to the data sharing group. You can determine is the IRLM is
connected by issuing a MODIFY irlmproc,STATUS command and checking that
the output shows SCOPE=GLOBAL.
If an IRLM is down, it is displayed only if its associated DB2 is down and holds
retained locks. The IRLM that is displayed can vary depending on several
circumstances:
v Normally, it is the last IRLM to which DB2 identified.
v If there was a rebuild of the lock structure after the retained locks were
created, it is the IRLM with the lowest member ID at the time the rebuild
occurred.
v If the failed DB2 had recovery done on its behalf by another DB2, the IRLM
that is displayed is the one associated with the DB2 that did the peer
recovery.
| MAINT
| For this IRLM only, displays the maintenance levels of IRLM load module
| CSECTS in a two-column format.
STOR
For this IRLM only, displays the current and ″high-water″ allocation for CSA and
ECSA storage.
TRACE
Requests information about IRLM subcomponent trace types. Information
includes whether a subcomponent trace type is active, how many trace buffers
are used by the trace, and whether the component trace external writer is active
for the trace.

Usage notes
Messages: If irlmx is not specified, or if this IRLM is in a non-data-sharing
environment, message DXR101I is issued. That message lists each subsystem
connected to the IRLM specified by irlmx, with an indication as to whether the
connection is active.

Displaying IRLM IDs: If irlmproc is started specifying SCOPE=GLOBAL, the


second line of the display indicates the IRLM IDs of the IRLMs.

Examples
Example 1: Enter on the MVS1 system console:
F IRTPROC,STATUS

Chapter 2. Commands 233


MODIFY ..., STATUS (MVS IRLM)
Response on MVS1 system console:
DXR101I IR2T001 STATUS SCOPE=LOCAL
SUBSYSTEMS IDENTIFIED PT01
NAME STATUS UNITS HELD WAITING RET_LKS
DSNT1 UP-NS 0005 0010 0002 0

Explanation: The operator on system 1 has requested information about the DB2
systems connected to the IRLM identified by the IRLM procedure named IRTPROC.

If the IRLM is SCOPE=GLOBAL on the irlmproc and is not connected to any group,
the status message shows:
DXR101I IR21001 STATUS SCOPE=DISCON

Example 2: Assume you have a data sharing group. Enter on a system console:
F DB1GIRLM,STATUS,ALLD

Response on system console:


# 14.02.10 STC00086 DXR102I DJ1G001 STATUS
# SUBSYSTEMS IDENTIFIED PT01
# NAME STATUS RET_LKS IRLMID IRLM_NAME IRLM_LEVL
# DB4G UP 0 004 DJ4G 006
# DB3G UP 0 003 DJ3G 012
# DB2G UP 0 002 DJ2G 021
# DB1G UP 0 001 DJ1G 021

Explanation: The output shows all the DB2s that are connected to IRLMs in this
data sharing group (the group to which the IRLM processing the request belongs).
The value “UP” in the STATUS field indicates that the DB2 is active. Other possible
values for STATUS include:
DOWN
The DB2 is failed. All “modify” type locks held by this DB2 have been
retained by IRLM. The DB2 is known to be down only if it has retained
locks.
SYSFAIL
The IRLM that DB2 is identified to has been disconnected from the data
sharing group. All “modify” type locks held by this DB2 have been retained
by IRLM. The DB2 is known to be SYSFAIL only if it has retained locks.

Example 3: Again, assume data sharing is in effect. Enter the following on the
system console:
F DB1GIRLM,STATUS,ALLI

The response on the console is:


17.17.03 STC00092 DXR103I LRLM007 STATUS
IRLMS PARTICIPATING IN DATA SHARING GROUP FUNCTION LEVEL=006
IRLM_NAME IRLMID STATUS LEVEL SERVICE MIN_LEVEL MIN_SERVICE
JRLM 005 UP 013 PN92893 006 IRLM2.1
KRLM 006 UP 006 IRLM2.1 006 IRLM2.1
LRLM 007 UP 013 PN92893 006 IRLM2.1

Explanation: The output shows the IRLMs that are participating in this data sharing
group (the group which includes the IRLM processing the request). Other
information includes:
STATUS
The value “UP” in the STATUS field indicates that the IRLM is active.

234 Command Reference


MODIFY ..., STATUS (MVS IRLM)
STATUS shows “DOWN” if the IRLM is failed. An IRLM is known to be
“DOWN” only if the DB2 that was identified to it has retained locks. This
connection between a failed DB2 and IRLM is lost after a rebuild or a group
restart.
LEVEL
The current IRLM function level.
SERVICE
The IRLM service or release that corresponds to the function level given in
″LEVEL″.
MIN_LEVEL
The minimum IRLM function level this IRLM can coexist with.
MIN_SERVICE
The IRLM service or release that corresponds to the function level given in
″MIN-LEVEL″.
Group Function Level
The IRLM function level in use by all the IRLMs in the data sharing group.

Example 4: Assume that this command is issued in a non-data sharing


environment. Enter the following on the system console:
F DB1GIRLM,STATUS,ALLI

The response on the console is:


15.12.01 STC00092 DXR103I VRLM007 STATUS
IRLMS PARTICIPATING IN DATA SHARING GROUP FUNCTION LEVEL=016
IRLM_NAME IRLMID STATUS LEVEL SERVICE MIN_LEVEL MIN_SERVICE
VRLM 007 UP 016 PQ15854 012 PN90337

Explanation: The output shows information only for the IRLM specified. The group
function level shown is the function level for the specified IRLM. Refer to Example 3
on page 234 for additional information on interpreting output.

Example 5: Enter the following command on the system console:


F IR21PROC,STATUS,STOR

The response on the console is:


DXR100I IR21001 STOR STATS
PC: NO MAXCSA: 6M
CSA USE: ACNT: 132K AHWM: 132K CUR: 4048K HWM: 4086K
ABOVE 16M: 72 4033K BELOW 16M: 6 15K
CLASS TYPE SEGS MEM TYPE SEGS MEM TYPE SEGS MEM
ACCNT T-1 1 64K T-2 1 64K T-3 1 4K
PROC WRK 11 58K SRB 3 3K OTH 2 2K
MISC VAR 60 4081K N-V 6 22K FIX 1 24K

Explanation: The example shows that current storage allocated for IRLM is 4048
KB, and the greatest amount that has been allocated since the last time IRLM was
started is 4086 KB. The storage for the locking structures (RHB and RLB) is
contained within ECSA, because this IRLM is defined with PC=NO. Use the
following information to interpret the display output:
PC Displays the current value for the PC option of the
IRLM startup procedure.

Chapter 2. Commands 235


MODIFY ..., STATUS (MVS IRLM)
MAXCSA Displays the current value for the MAXCSA option
of the IRLM startup procedure. The MAXCSA value
is 6 MB in this example.
CSA USE Shows storage use that is accountable toward the
MAXCSA value of the IRLM procedure. In this
output, the current use accountable storage (ACNT)
is 132 KB. The high water mark since the last time
IRLM was started (AHWM) is also 132 KB.
CUR Shows the total current CSA and ECSA usage. In
this case, the current usage (CUR) is 4048 KB, and
the high water mark (HWM) is 4086 KB. The
accountable storage is a subset of this total
storage.
ACCNT The ACCNT row of the report is a breakdown of
lock control block structures and their storage use.
T-1 Type one structures are for resources. In
this case, it shows that one storage
segment is held for a total of 64 KB.
T-2 Type two structures are for all resource
requests after the first request for a specific
resource. This example shows that one
storage segment is held for a total of 64
KB.
T-3 Type three structures are for requesters or
work units that are waiting for or hold
resources. This example shows that one
storage segment is held for a total of 4 KB.
PROC and MISC rows These rows contain usage information for CSA,
ECSA, and private storage used to process DBMS
requests. Use this information under the guidance
of IBM® Support Center for diagnosing problems.

For more information, see the explanation of message DXR100I in DB2 Messages
and Codes.

Example 6: Assume the IRLM was started with PC=YES. Enter the following
command on the system console:
F IR21PROC,STATUS,STOR

The response on the console is:


DXR100I JR21001 STOR STATS
PC: YES MAXCSA: N/A
CSA USE: ACNT: OK AHWM: OK CUR: 4362K HWM: 5830K
ABOVE 16M: 78 4376K BELOW 16M: 23 32K
CLASS TYPE SEGS MEM TYPE SEGS MEM TYPE SEGS MEM
ACCNT T-1 1 64K T-2 1 64K T-3 1 4K
PROC WRK 11 58K SRB 20 20K OTH 2 2K
MISC VAR 68 4497K N-V 6 22K FIX 1 24K

Explanation: This example was created using a poorly-tuned application, and shows
how important a well-tuned system is for predicting system storage needs. This
example illustrates what can happen when an application generates a high IRLM

236 Command Reference


MODIFY ..., STATUS (MVS IRLM)
lock contention rate; the high value of 20 segments with 20 KB each for type SRB
storage, and the high value of 23 segments with 23 KB each for storage below the
16 MB line are some of the results.

For more information about reducing lock contention, see Part 5 (Volume 2) of DB2
Administration Guide. For more information about tuning your system, see Chapter
6 of DB2 Data Sharing: Planning and Administration.

Example 7: Enter the following command on the system console:


F PR21PROC,STATUS,TRACE

The response on the console is:


DXR179I PR21034 TRACE USAGE
TRACE BUFFER STORAGE IN USE: 256 KB
MAXIMUM NUMBER OF TRACE BUFFERS ALLOWED PER TRACE TYPE: 10
TRACE TYPE ACTIVE BUFFERS IN USE CTRACE WRITER
---------- ------ -------------- -------------
SLM N 0 N
XIT Y 2 N
XCF N 0 N
DBM N 0 N
EXP Y 1 N
INT Y 1 N

Explanation: This example shows that the storage currently allocated for IRLM
tracing is 256 KB, the maximum number of trace buffers allowed per trace type is
set to 10, and the external CTRACE writer is not active. For more information about
the trace types, see “TRACE CT (MVS IRLM)” on page 340.

Use the TRACE CT command of MVS on page 340 to activate or deactivate traces.
You cannot turn off the EXP and INT traces. The XIT (for data sharing), EXP, and
INT traces are automatically activated when you start IRLM. All traces are
automatically activated with IRLMPROC TRACE=YES.

The trace size for each buffer is 64 KB. Use the MODIFY irlmproc,SET,TRACE=nnn
command on page 228 to change the maximum number of trace buffers.

| Example 8: Enter the following command on the system console:


| F IR21I, STATUS, MAINT

| The response on the console is:


| DXR104I IR21240 Maintenance levels
| LMOD.Csect MaintLv Date Csect APAR DATE
| DXRRLM00.DXRRL010 PQ35083 02/22/00 DXRRL020 PQ35083 02/22/00
| DXRRL030 PQ27464 08/18/99 DXRRL040 PQ35083 02/22/00

| Explanation: The output shows the maintenance levels of IRLM load module
| CSECTS in a two-column format.

Chapter 2. Commands 237


-MODIFY TRACE (DB2)

-MODIFY TRACE (DB2)


The DB2 command MODIFY TRACE does the following:
v Changes the trace events (IFCIDs) being traced for a particular active trace.
v Stops any IFCID previously active for the specified trace.
v Writes statistics records.

Abbreviation: -MOD TRA

Environment
This command can be issued from an MVS console, a DSN session, a DB2I panel
(DB2 COMMANDS), an IMS or CICS terminal, or a program using the
instrumentation facility interface (IFI).

Data sharing scope: Member

Traces started by a IFI/IFC program:

Before you modify an active trace, ensure that an IFI application program or the IFC
Selective Dump utility (DSN1SDMP) did not start the trace. If you modify a trace
started by DSN1SDMP, the DSN1SDMP utility abnormally terminates. When
DSN1SDMP terminates, it stops the trace. This stop could interfere with the
MODIFY TRACE command which stops and restarts the trace.

Authorization
To execute this command, the privilege set of the process must include one of the
following:
v TRACE privilege
v SYSOPR, SYSCTRL, or SYSADM authority

DB2 commands issued from an MVS console are not associated with any
secondary authorization IDs.

Syntax

*
,

 MODIFY TRACE ( PERFM ) CLASS(  integer ) TNO(integer) 


ACCTG
STAT
* AUDIT
, MONITOR

 IFCID(  ifcid_nbr ) 
COMMENT(string)

Option descriptions
TRACE
Determines which IFCIDs are started. For more descriptions of each trace type,
see “-START TRACE (DB2)” on page 299.

238 Command Reference


-MODIFY TRACE (DB2)
Table 23. Trace types
Type Description Abbreviation
PERFM Performance records of specific events P
ACCTG Accounting records for each transaction A
STAT Statistical data S
AUDIT Audit data AU
MONITOR Monitor data MON

One additional trace type is not described here. It is intended for service and is
to be used under the direction of IBM support personnel. For details, see DB2
Diagnosis Guide and Reference.
CLASS(integer, ...)
Limits the list to IFCIDs started for specified classes.
Abbreviation: C
integer is a class to which the list of IFCIDs started is limited. For descriptions
of the allowable classes, see “-START TRACE (DB2)” on page 299.
The default is CLASS(*), which starts all default IFCID classes.
TNO(integer)
Specifies the particular trace to be modified, identified by its trace number (1 to
32, 01 to 09). You can only specify one trace number. TNO is a required option
for the MODIFY TRACE command.
No default exists for the TNO keyword.
IFCID( ifcid_nbr, ...)
Specifies which other IFCIDs (trace events), in addition to those IFCIDs
contained in the classes specified in the CLASS option, are to be started. To
start only those IFCIDs specified in the IFCID option, use trace classes 30-32.
These classes have no predefined IFCIDs and are available for a location to
use. (See “Example” for an example of activating only those trace events
specified in the IFCID option.)
If you do not specify the IFCID option, only those IFCIDs contained in the
activated trace classes are started.
The maximum number of IFCIDs is 156. The range of values that are valid for
the IFCID option is 1 through 350, with the exception of: 4, 5, 185, 187, 217,
232, 234, 240, and 241.
The default is IFCID(*).
COMMENT(string)
Gives a comment that is reproduced in the trace output record (except in the
resident trace tables).
string is any character string; it must be enclosed between apostrophes if it
includes a blank, comma, or special character.

Example
Change trace number 6 so that it collects only statistics and accounting data. You
can define CLASS(30) at your site.
-MODIFY TRACE(S) IFCID(1,2,3) TNO(6) CLASS(30)
COMMENT ('STATS AND ACCOUNTING ON')

Chapter 2. Commands 239


REBIND PACKAGE (DSN)

REBIND PACKAGE (DSN)


The DSN subcommand REBIND PACKAGE rebinds an application package when
you make changes that affect the package, but have not changed the SQL
statements in the program. For example, you can use REBIND PACKAGE when
you change the authorizations, create a new index for the package, or use
RUNSTATS. When the REBIND PACKAGE(*) command is issued, trigger packages
will not be affected.

REBIND PACKAGE is generally faster and more economical than BIND PACKAGE.
You should use BIND PACKAGE with the ACTION(REPLACE) option under the
following conditions:
v When you change the SQL statements
v When you recompile the program
v You previously ran BIND PACKAGE with the SQLERROR(CONTINUE) option

For more information on using REBIND PACKAGE, see Part 5 of DB2 Application
Programming and SQL Guide.

Environment
You can use REBIND PACKAGE through DB2I, or enter the REBIND PACKAGE
subcommand from a DSN session running in foreground or background.

Data sharing scope: Group

Authorization
The package owner must have authorization to execute all SQL statements
embedded in the package for REBIND PACKAGE to build a package without
producing error messages. For VALIDATE(BIND), DB2 verifies the authorization at
bind time. For VALIDATE(RUN), DB2 verifies the authorization initially at bind time,
but if the authorization check fails, DB2 rechecks it at run time.

Table 24 explains the authorization required to run REBIND PACKAGE, depending


on the options specified.
Table 24. Summary of privileges for REBIND PACKAGE
Option Authorization required to run REBIND PACKAGE
REBIND PACKAGE The authorization IDs of the process must have one of the following:
with no change in v Ownership of the package
ownership, because v BIND privilege on the package
the OWNER keyword v BINDAGENT privilege from the owner of the package
is not specified. v PACKADM authority on the collection or on all collections
v SYSADM or SYSCTRL authority
REBIND PACKAGE The authorization IDs of the process must have one of the following:
with no change in v OWNER authorization-id must be one of the primary or secondary
ownership, although authorization IDs of the binder
the original owner is v BINDAGENT privilege from the owner of the package
specified for the v SYSADM or SYSCTRL authority
OWNER keyword.

240 Command Reference


REBIND PACKAGE (DSN)
Table 24. Summary of privileges for REBIND PACKAGE (continued)
Option Authorization required to run REBIND PACKAGE
REBIND PACKAGE The new OWNER must have one of the following:
with change of v BIND privilege on the package
ownership. (An v PACKADM authority on the collection or on all collections
authorization ID that is v SYSADM or SYSCTRL authority
not the original owner
is specified in the Specifying the OWNER: If any of the authorization IDs have the
OWNER keyword.) BINDAGENT privilege granted from the owner, then authorization-id
can specify the grantor as OWNER. Otherwise, OWNER
authorization-id must be one of the primary or secondary
authorization IDs of the binder.

For additional information on the authorization required to execute BIND PLAN, see
Part 5 (Volume 2) of DB2 Administration Guide.

Chapter 2. Commands 241


REBIND PACKAGE (DSN)
Syntax

 REBIND PACKAGE 

 (  collection-id . package-id ) 
location-name. * * .( )
version-id
*
*

 
OWNER(authorization-id) QUALIFIER(qualifier-name) CURRENTDATA( YES )
NO

 
DBPROTOCOL ( DRDA ) DEFER(PREPARE) DEGREE( 1 )
PRIVATE NODEFER(PREPARE) ANY

 
DYNAMICRULES( RUN ) ENCODING( ASCII ) EXPLAIN( YES )
BIND EBCDIC NO
DEFINE UNICODE
INVOKE ccsid

 
I IMMEDWRITE( NO ) ISOLATION( RR )
FLAG( W ) PH1 RS
E YES CS
C UR
NC

NOREOPT(VARS)
 
NO REOPT(VARS) OPTHINT ( ’hint-id’ )
KEEPDYNAMIC( YES )
 
,

PATH(  schema-name )
USER

 
(1) RELEASE( COMMIT ) VALIDATE( RUN )
PATHDEFAULT DEALLOCATE BIND

Notes:
1 The PATHDEFAULT keyword is mutually exclusive with the PATH keyword. Do not specify both
keywords in the same REBIND command.

242 Command Reference


REBIND PACKAGE (DSN)

enable block

 
,

ENABLE (  BATCH ) 
DISABLE DLIBATCH ,
DB2CALL
CICS DLIBATCH(  connection-name )
IMS ,
IMSBMP
IMSMPP CICS(  applid )
REMOTE ,
RRSAF
ENABLE(*) IMSBMP(  imsid )
,

IMSMPP(  imsid )
,

REMOTE(  location-name )
<luname>

Option descriptions
For descriptions of the options shown in the syntax diagram, see “Options of BIND
and REBIND for PLAN, PACKAGE, and TRIGGER PACKAGE” on page 44.

Usage note
If you rebind multiple packages, DB2 commits each successful rebind before
rebinding the next package.

Example
Rebind packages TEST.DSN8BC71.(MAY_VERSION) and
PRODUCTION.DSN8BC71.(DEC_VERSION), both located at the local location
USIBMSTODB22. The packages can run only from the CICS or the DLIBATCH
environments if the connection ID is CON2. This replaces the CON1 specified on
the BIND PACKAGE command.
REBIND PACKAGE (USIBMSTODB22.TEST.DSN8BC71.(MAY_VERSION),
USIBMSTODB22.PRODUCTION.DSN8BC71.(DEC_VERSION)) -
ENABLE (CICS,DLIBATCH) CICS (CON2)

Chapter 2. Commands 243


REBIND PLAN (DSN)

REBIND PLAN (DSN)


The DSN subcommand REBIND PLAN rebinds an application plan when you make
changes that affect the plan, but do not change the SQL statements in the
programs. For example, you can use REBIND PLAN when you change
authorizations, create a new index for the plan, or use RUNSTATS. If the rebind is
successful, the process prepares an application plan and updates its description in
the catalog table SYSPLAN.

REBIND PLAN is generally faster and more economical than BIND PLAN. But if
you change the SQL statements or recompile a program, you should use BIND
PLAN with the option ACTION(REPLACE).

For more information on using REBIND PLAN, see Part 5 of DB2 Application
Programming and SQL Guide.

Environment
You can use REBIND PLAN through DB2I, or enter the REBIND PLAN
subcommand from a DSN session running in foreground or background.

Data sharing scope: Group

Authorization
The plan owner must have authorization to execute all SQL statements embedded
in the plan for REBIND PLAN to build a plan without producing error messages. For
VALIDATE(BIND), DB2 verifies the authorization at bind time. For VALIDATE(RUN),
DB2 verifies the authorization initially at bind time, but if the authorization check
fails, DB2 rechecks it again at run time. If you use the PKLIST keyword, you must
have EXECUTE authority for the packages or collections specified on PKLIST.

Table 25 explains the authorization required to run REBIND PLAN, depending on


the options specified.
Table 25. Summary of privileges for REBIND PLAN
Option Authorization required to run REBIND PLAN
REBIND PLAN with no The authorization IDs of the process must have one of the