Db2 11 for z/OS

Administration Guide

IBM

SC19-4050-07
Db2 11 for z/OS

Administration Guide

IBM

SC19-4050-07
 Notes
Before using this information and the product it supports, be sure to read the general information under “Notices” at the
end of this information.

Subsequent editions of this PDF will not be delivered in IBM Publications Center. Always download the latest edition from
Db2 11 for z/OS Product Documentation.

September 13, 2019 edition

This edition applies to Db2 11 for z/OS (product number 5615-DB2), Db2 11 for z/OS Value Unit Edition (product
number 5697-P43), 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.
Specific changes are indicated by a vertical bar to the left of a change. A vertical bar to the left of a figure caption
indicates that the figure has changed. Editorial changes that have no technical significance are not noted.
© Copyright IBM Corporation 1982, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Contents
About this information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Who should read this information . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Db2 Utilities Suite for z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Terminology and citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Accessibility features for Db2 11 for z/OS . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to send your comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to read syntax diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Part 1. Designing and implementing Db2 databases . . . . . . . . . . . . . . 1

Chapter 1. Database objects and relationships . . . . . . . . . . . . . . . . . . . 3

Logical database design with the entity-relationship model . . . . . . . . . . . . . . . . . . . . 3
Modeling your data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Recommendations for logical data modeling . . . . . . . . . . . . . . . . . . . . . . . . 5
Practical examples of data modeling . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Entities for different types of relationships . . . . . . . . . . . . . . . . . . . . . . . . 6
Entity attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Entity normalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Logical database design with Unified Modeling Language . . . . . . . . . . . . . . . . . . . . 14
Physical database design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Denormalization of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Views to customize what data users see . . . . . . . . . . . . . . . . . . . . . . . . . 18
Indexes on table columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Hash access on tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
| Maintaining archive data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2. Implementing your database design . . . . . . . . . . . . . . . . . . 21

Implementing Db2 databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Creating Db2 databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Dropping Db2 databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Implementing Db2 storage groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Advantages of storage groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Creating Db2 storage groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Enabling SMS to control Db2 storage groups . . . . . . . . . . . . . . . . . . . . . . . 25
Deferring allocation of Db2-managed data sets . . . . . . . . . . . . . . . . . . . . . . 25
How Db2 extends data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Db2 space allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Managing Db2 data sets with DFSMShsm . . . . . . . . . . . . . . . . . . . . . . . . 31
Managing your own data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Defining index space storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Creating EA-enabled table spaces and index spaces . . . . . . . . . . . . . . . . . . . . . 40
Implementing Db2 table spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Table space types and characteristics in Db2 for z/OS . . . . . . . . . . . . . . . . . . . . 41
Implicitly defined table spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
| Creating table spaces explicitly . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
| Creating partition-by-range table spaces . . . . . . . . . . . . . . . . . . . . . . . . . 56
| Creating partition-by-growth table spaces . . . . . . . . . . . . . . . . . . . . . . . . 58
EA-enabled table spaces and index spaces . . . . . . . . . . . . . . . . . . . . . . . . 59
Implementing Db2 tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Creating base tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Guidelines for table names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
| Creating tables that use hash organization (deprecated). . . . . . . . . . . . . . . . . . . . 60
Creating temporary tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Creating temporal tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

© Copyright IBM Corp. 1982, 2017 iii

 Creating materialized query tables. . . . . . . . . . . . . . . . . . . . . . . . . . . 78
| Creating tables partitioned by data value ranges . . . . . . . . . . . . . . . . . . . . . . 79
Nullable partitioning columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Creating a clone table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
| Creating an archive table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Implementing Db2 views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Creating Db2 views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Guidelines for view names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
| Querying views that reference temporal tables. . . . . . . . . . . . . . . . . . . . . . . 86
How Db2 inserts and updates data through views . . . . . . . . . . . . . . . . . . . . . 87
Dropping Db2 views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Implementing Db2 indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Creating Db2 indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Guidelines for defining indexes. . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
How Db2 implicitly creates an index . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Implementing Db2 schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Creating a schema by using the schema processor . . . . . . . . . . . . . . . . . . . . . 91
Processing schema definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Loading data into Db2 tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Loading data with the LOAD utility . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Loading data by using the INSERT statement . . . . . . . . . . . . . . . . . . . . . . . 96
Loading data from DL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Implementing Db2 stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Dropping stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Implementing Db2 user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . 101
Creating user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Deleting user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Estimating disk storage for user data . . . . . . . . . . . . . . . . . . . . . . . . . . 102
General approach to estimating storage. . . . . . . . . . . . . . . . . . . . . . . . . 103
Calculating the space required for a table . . . . . . . . . . . . . . . . . . . . . . . . 105
Calculating the space required for an index . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 3. Altering your database design . . . . . . . . . . . . . . . . . . . . 115

Using the catalog in database design . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Retrieving catalog information about Db2 storage groups. . . . . . . . . . . . . . . . . . . 116
Retrieving catalog information about a table . . . . . . . . . . . . . . . . . . . . . . . 116
Retrieving catalog information about partition order . . . . . . . . . . . . . . . . . . . . 117
Retrieving catalog information about aliases . . . . . . . . . . . . . . . . . . . . . . . 117
Retrieving catalog information about columns . . . . . . . . . . . . . . . . . . . . . . 118
Retrieving catalog information about indexes . . . . . . . . . . . . . . . . . . . . . . . 119
Retrieving catalog information about views . . . . . . . . . . . . . . . . . . . . . . . 119
Retrieving catalog information about authorizations . . . . . . . . . . . . . . . . . . . . 120
Retrieving catalog information about primary keys . . . . . . . . . . . . . . . . . . . . . 121
Retrieving catalog information about foreign keys . . . . . . . . . . . . . . . . . . . . . 121
Retrieving catalog information about check pending . . . . . . . . . . . . . . . . . . . . 122
Retrieving catalog information about check constraints . . . . . . . . . . . . . . . . . . . 123
Retrieving catalog information about LOBs . . . . . . . . . . . . . . . . . . . . . . . 124
Retrieving catalog information about user-defined functions and stored procedures . . . . . . . . . . 124
Retrieving catalog information about triggers. . . . . . . . . . . . . . . . . . . . . . . 125
Retrieving catalog information about sequences . . . . . . . . . . . . . . . . . . . . . . 125
Adding and retrieving comments. . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Verifying the accuracy of the database definition . . . . . . . . . . . . . . . . . . . . . 127
Altering Db2 databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Altering Db2 storage groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Letting SMS manage your Db2 storage groups . . . . . . . . . . . . . . . . . . . . . . 128
Adding or removing volumes from a Db2 storage group . . . . . . . . . . . . . . . . . . . 129
Migrating existing data sets to a solid-state drive . . . . . . . . . . . . . . . . . . . . . 130
Altering table spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Changing the logging attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Changing the space allocation for user-managed data sets . . . . . . . . . . . . . . . . . . 134

iv Administration Guide
 Dropping and re-creating a table space to change its attributes . . . . . . . . . . . . . . . . . 134
Redistributing data in partitioned table spaces . . . . . . . . . . . . . . . . . . . . . . 136
Increasing partition size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Altering a page set to contain Db2-defined extents . . . . . . . . . . . . . . . . . . . . . 138
| Converting partitioned (non-UTS) table spaces to partition-by-range universal table spaces . . . . . . . 139
| Converting table spaces to use table-controlled partitioning . . . . . . . . . . . . . . . . . . 140
Altering Db2 tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Adding a column to a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Specifying a default value when altering a column . . . . . . . . . . . . . . . . . . . . . 147
Altering the data type of a column . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Altering a table for referential integrity . . . . . . . . . . . . . . . . . . . . . . . . . 156
Adding or dropping table check constraints . . . . . . . . . . . . . . . . . . . . . . . 160
Adding partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Altering partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Adding XML columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
| Altering tables for hash access (deprecated) . . . . . . . . . . . . . . . . . . . . . . . 173
| Altering the size of your hash spaces (deprecated) . . . . . . . . . . . . . . . . . . . . . 175
Adding a system period and system-period data versioning to an existing table . . . . . . . . . . . 176
Adding an application period to a table . . . . . . . . . . . . . . . . . . . . . . . . 178
Manipulating data in a system-period temporal table . . . . . . . . . . . . . . . . . . . . 179
Altering materialized query tables . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Altering the assignment of a validation routine . . . . . . . . . . . . . . . . . . . . . . 181
Altering a table to capture changed data . . . . . . . . . . . . . . . . . . . . . . . . 182
Changing an edit procedure or a field procedure . . . . . . . . . . . . . . . . . . . . . 183
Altering the subtype of a string column . . . . . . . . . . . . . . . . . . . . . . . . 183
Altering the attributes of an identity column . . . . . . . . . . . . . . . . . . . . . . . 184
Changing data types by dropping and re-creating the table . . . . . . . . . . . . . . . . . . 184
Moving a table to a table space of a different page size . . . . . . . . . . . . . . . . . . . 188
Altering Db2 views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Altering views by using the INSTEAD OF trigger . . . . . . . . . . . . . . . . . . . . . 190
| Changing data by using views that reference temporal tables . . . . . . . . . . . . . . . . . 190
Altering Db2 indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Alternative method for altering an index . . . . . . . . . . . . . . . . . . . . . . . . 192
Adding columns to an index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Altering how varying-length index columns are stored . . . . . . . . . . . . . . . . . . . 194
Altering the clustering of an index . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Dropping and redefining a Db2 index . . . . . . . . . . . . . . . . . . . . . . . . . 195
Reorganizing indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
| Pending data definition changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
| Materializing pending definition changes . . . . . . . . . . . . . . . . . . . . . . . . 200
| Restrictions for changes to objects that have pending data definition changes . . . . . . . . . . . . 203
Altering stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Altering user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Altering implicitly created XML objects. . . . . . . . . . . . . . . . . . . . . . . . . . 209
Changing the high-level qualifier for Db2 data sets . . . . . . . . . . . . . . . . . . . . . . 210
Defining a new integrated catalog alias. . . . . . . . . . . . . . . . . . . . . . . . . 210
Changing the qualifier for system data sets . . . . . . . . . . . . . . . . . . . . . . . 211
Changing qualifiers for other databases and user data sets . . . . . . . . . . . . . . . . . . 215
Tools for moving Db2 data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Moving Db2 data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Moving a Db2 data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Part 2. Operation and recovery . . . . . . . . . . . . . . . . . . . . . . . 225

Chapter 4. Controlling Db2 operations by using commands . . . . . . . . . . . . 227

Issuing commands from the z/OS console. . . . . . . . . . . . . . . . . . . . . . . . . 229
Issuing commands from TSO terminals . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Issuing commands from CICS terminals . . . . . . . . . . . . . . . . . . . . . . . . . 231
Issuing commands from IMS terminals . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Issuing commands from application programs . . . . . . . . . . . . . . . . . . . . . . . 232

Contents v
Destinations for command output messages . . . . . . . . . . . . . . . . . . . . . . . . 234
Unsolicited Db2 messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Chapter 5. Starting and stopping Db2 . . . . . . . . . . . . . . . . . . . . . . 237

Starting Db2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Messages at start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Subsystem parameters at start . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Application defaults module name at start . . . . . . . . . . . . . . . . . . . . . . . 239
Restricting access to data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Ending the wait state at startup . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Restart options after an abend . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Stopping Db2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Chapter 6. Submitting work to Db2 . . . . . . . . . . . . . . . . . . . . . . . 243

Submitting work by using DB2I . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Running TSO application programs . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Sources that Db2 checks to find authorization access for an application program . . . . . . . . . . . 244
Running IMS application programs . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Running CICS application programs. . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Running batch application programs . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Running application programs using CAF . . . . . . . . . . . . . . . . . . . . . . . . . 247
Running application programs using RRSAF . . . . . . . . . . . . . . . . . . . . . . . . 247

Chapter 7. Scheduling administrative tasks . . . . . . . . . . . . . . . . . . . 249

Interacting with the administrative task scheduler . . . . . . . . . . . . . . . . . . . . . . 249
Adding a task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Listing scheduled tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Listing the status of scheduled tasks. . . . . . . . . . . . . . . . . . . . . . . . . . 255
Updating the schedule for a task . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Stopping the execution of a task . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Removing a scheduled task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Manually starting the administrative task scheduler . . . . . . . . . . . . . . . . . . . . 259
Manually stopping the administrative task scheduler . . . . . . . . . . . . . . . . . . . . 259
Synchronization between administrative task schedulers in a data sharing environment . . . . . . . . 260
Troubleshooting the administrative task scheduler . . . . . . . . . . . . . . . . . . . . . 261
Architecture of the administrative task scheduler . . . . . . . . . . . . . . . . . . . . . . 264
The lifecycle of the administrative task scheduler . . . . . . . . . . . . . . . . . . . . . 265
Task lists of the administrative task scheduler . . . . . . . . . . . . . . . . . . . . . . 267
Architecture of the administrative task scheduler in a data sharing environment . . . . . . . . . . . 267
Accounting information for stored procedure tasks . . . . . . . . . . . . . . . . . . . . . 268
Security guidelines for the administrative task scheduler . . . . . . . . . . . . . . . . . . . . 269
User roles in the administrative task scheduler . . . . . . . . . . . . . . . . . . . . . . 270
Protection of the interface of the administrative task scheduler . . . . . . . . . . . . . . . . . 271
Protection of the resources of the administrative task scheduler . . . . . . . . . . . . . . . . 271
Secure execution of tasks in the administrative task scheduler . . . . . . . . . . . . . . . . . 272
Execution of scheduled tasks in the administrative task scheduler . . . . . . . . . . . . . . . . . 273
Multi-threading in the administrative task scheduler . . . . . . . . . . . . . . . . . . . . 273
Scheduling execution of a stored procedure . . . . . . . . . . . . . . . . . . . . . . . 275
How the administrative task scheduler works with Unicode. . . . . . . . . . . . . . . . . . 276
Scheduled execution of a JCL job . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Execution of scheduled tasks in a data sharing environment. . . . . . . . . . . . . . . . . . 277
Time zone considerations for the administrative task scheduler. . . . . . . . . . . . . . . . . 278

Chapter 8. Monitoring and controlling Db2 and its connections . . . . . . . . . . . 279

Controlling Db2 databases and buffer pools . . . . . . . . . . . . . . . . . . . . . . . . 279
Starting databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Monitoring databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Obtaining information about application programs . . . . . . . . . . . . . . . . . . . . . 285
Obtaining information about and handling pages in error . . . . . . . . . . . . . . . . . . 287
Making objects unavailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

vi Administration Guide
 Altering buffer pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Monitoring buffer pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Controlling user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Starting user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Monitoring user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Stopping user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Controlling Db2 utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Starting online utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Monitoring and changing online utilities . . . . . . . . . . . . . . . . . . . . . . . . 298
Controlling Db2 stand-alone utilities. . . . . . . . . . . . . . . . . . . . . . . . . . 298
Controlling the IRLM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
z/OS commands that operate on IRLM. . . . . . . . . . . . . . . . . . . . . . . . . 301
Starting the IRLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Stopping the IRLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Monitoring threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Types of threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Output of the DISPLAY THREAD command . . . . . . . . . . . . . . . . . . . . . . . 305
Displaying information about threads . . . . . . . . . . . . . . . . . . . . . . . . . 305
Monitoring all DBMSs in a transaction . . . . . . . . . . . . . . . . . . . . . . . . . 310
Controlling connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Controlling TSO connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Controlling CICS connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Controlling IMS connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Controlling RRS connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Controlling connections to remote systems . . . . . . . . . . . . . . . . . . . . . . . 336
Controlling traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Diagnostic traces for attachment facilities . . . . . . . . . . . . . . . . . . . . . . . . 360
Controlling the Db2 trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Diagnostic trace for the IRLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Setting the priority of stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . 362
| Setting special registers with profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Chapter 9. Managing the log and the bootstrap data set . . . . . . . . . . . . . . 367
How database changes are made . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Units of recovery and points of consistency . . . . . . . . . . . . . . . . . . . . . . . 367
How Db2 rolls back work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
How the initial Db2 logging environment is established . . . . . . . . . . . . . . . . . . . 369
How Db2 creates log records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
How Db2 writes the active log . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
How Db2 writes (offloads) the archive log. . . . . . . . . . . . . . . . . . . . . . . . 371
How Db2 retrieves log records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Managing the log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Quiescing activity before offloading . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Archiving the log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
| Adding an active log data set to the active log inventory with the SET LOG command. . . . . . . . . 379
Dynamically changing the checkpoint frequency. . . . . . . . . . . . . . . . . . . . . . 380
Setting limits for archive log tape units . . . . . . . . . . . . . . . . . . . . . . . . . 381
Monitoring the system checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Displaying log information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
| What to do before RBA or LRSN limits are reached . . . . . . . . . . . . . . . . . . . . . 382
| Converting the BSDS to the 10-byte RBA and LRSN . . . . . . . . . . . . . . . . . . . . 384
| Converting page sets to the 10-byte RBA or LRSN format . . . . . . . . . . . . . . . . . . 386
| Resetting the log RBA value in a data sharing environment (6-byte format). . . . . . . . . . . . . 388
| Resetting the log RBA value in a non-data sharing environment (6-byte format) . . . . . . . . . . . 389
Canceling and restarting an offload . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Displaying the status of an offload . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Discarding archive log records. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Locating archive log data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Management of the bootstrap data set . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Restoring dual-BSDS mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
BSDS copies with archive log data sets . . . . . . . . . . . . . . . . . . . . . . . . . 397

Contents vii
 Recommendations for changing the BSDS log inventory . . . . . . . . . . . . . . . . . . . 397

Chapter 10. Restarting Db2 after termination . . . . . . . . . . . . . . . . . . . 399

Methods of restarting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Types of termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Normal restart and recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Automatic restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Restart in a data sharing environment . . . . . . . . . . . . . . . . . . . . . . . . . 406
Restart implications for table spaces that are not logged . . . . . . . . . . . . . . . . . . . 406
Conditional restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Terminating Db2 normally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Restarting automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Deferring restart processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Performing conditional restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Conditional restart with system-level backups . . . . . . . . . . . . . . . . . . . . . . 410
Options for recovery operations after conditional restart . . . . . . . . . . . . . . . . . . . 411
Conditional restart records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Resolving postponed units of recovery . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Recovering from an error during RECOVER POSTPONED processing . . . . . . . . . . . . . . . 413

Chapter 11. Maintaining consistency across multiple systems . . . . . . . . . . . 415

Multiple system consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Two-phase commit process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Commit coordinator and multiple participants . . . . . . . . . . . . . . . . . . . . . . 417
Illustration of multi-site update . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Termination for multiple systems . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Consistency after termination or failure. . . . . . . . . . . . . . . . . . . . . . . . . 420
Normal restart and recovery for multiple systems . . . . . . . . . . . . . . . . . . . . . 421
Multiple-system restart with conditions. . . . . . . . . . . . . . . . . . . . . . . . . 422
Heuristic decisions about whether to commit or abort an indoubt thread . . . . . . . . . . . . . 422
Resolving indoubt units of recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Resolution of IMS indoubt units of recovery . . . . . . . . . . . . . . . . . . . . . . . 423
Resolution of CICS indoubt units of recovery. . . . . . . . . . . . . . . . . . . . . . . 424
Resolution of RRS indoubt units of recovery . . . . . . . . . . . . . . . . . . . . . . . 424
Resolving WebSphere Application Server indoubt units of recovery . . . . . . . . . . . . . . . 425
Resolving remote DBMS indoubt units of recovery . . . . . . . . . . . . . . . . . . . . . 428
Determining the coordinator's commit or abort decision . . . . . . . . . . . . . . . . . . . 428
Recovering indoubt threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Resetting the status of an indoubt thread . . . . . . . . . . . . . . . . . . . . . . . . 429
Resolving an indoubt unit of recovery during Db2 restart . . . . . . . . . . . . . . . . . . 430

Chapter 12. Backing up and recovering your data. . . . . . . . . . . . . . . . . 431

Plans for recovery of distributed data . . . . . . . . . . . . . . . . . . . . . . . . . . 432
| Plans for recovering the Db2 tables and indexes used to support Db2 query acceleration . . . . . . . . . 432
Plans for extended recovery facility toleration . . . . . . . . . . . . . . . . . . . . . . . 433
Plans for recovery of indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
| Actions to take when you back up data . . . . . . . . . . . . . . . . . . . . . . . . . 434
| Actions to avoid when you back up data . . . . . . . . . . . . . . . . . . . . . . . . . 435
Preparation for recovery: a scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Events that occur during recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Complete recovery cycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
A recovery cycle example when using image copies . . . . . . . . . . . . . . . . . . . . 439
How DFSMShsm affects your recovery environment . . . . . . . . . . . . . . . . . . . . 440
Tips for maximizing data availability during backup and recovery . . . . . . . . . . . . . . . . 441
Where to find recovery information . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
How to report recovery information . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Discarding SYSCOPY and SYSLGRNX records . . . . . . . . . . . . . . . . . . . . . . . 446
Preparations for disaster recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
System-wide points of consistency . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Recommendations for more effective recovery from inconsistency . . . . . . . . . . . . . . . . . 450

viii Administration Guide

 Actions to take to aid in successful recovery of inconsistent data . . . . . . . . . . . . . . . . 450
Actions to avoid in recovery of inconsistent data . . . . . . . . . . . . . . . . . . . . . 452
How to recover multiple objects in parallel . . . . . . . . . . . . . . . . . . . . . . . . 452
Recovery of page sets and data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Recovery of the work file database . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Page set and data set copies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
System-level backups for object-level recoveries . . . . . . . . . . . . . . . . . . . . . . 459
Recovery of data to a prior point in time . . . . . . . . . . . . . . . . . . . . . . . . . 460
Plans for point-in-time recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Point-in-time recovery with system-level backups . . . . . . . . . . . . . . . . . . . . . 462
Point-in-time recovery using the RECOVER utility . . . . . . . . . . . . . . . . . . . . . 464
Implications of moving data sets after a system-level backup . . . . . . . . . . . . . . . . . 474
Recovery of table spaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Recovery of indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Recovery of FlashCopy image copies . . . . . . . . . . . . . . . . . . . . . . . . . 479
Preparing to recover to a prior point of consistency . . . . . . . . . . . . . . . . . . . . 480
Preparing to recover an entire Db2 subsystem to a prior point in time using image copies or object-level backups 482
Creating essential disaster recovery elements . . . . . . . . . . . . . . . . . . . . . . . . 483
Resolving problems with a user-defined work file data set . . . . . . . . . . . . . . . . . . . 485
Resolving problems with Db2-managed work file data sets . . . . . . . . . . . . . . . . . . . 485
Recovering error ranges for a work file table space . . . . . . . . . . . . . . . . . . . . . . 486
Recovery of error ranges for a work file table space . . . . . . . . . . . . . . . . . . . . 486
Recovering after a conditional restart of Db2 . . . . . . . . . . . . . . . . . . . . . . . . 486
Recovery of the catalog and directory . . . . . . . . . . . . . . . . . . . . . . . . . 487
Regenerating missing identity column values. . . . . . . . . . . . . . . . . . . . . . . . 487
Recovery of tables that contain identity columns . . . . . . . . . . . . . . . . . . . . . 488
Recovering a table space and all of its indexes . . . . . . . . . . . . . . . . . . . . . . . 489
Recovery implications for objects that are not logged . . . . . . . . . . . . . . . . . . . . 489
Removing various pending states from LOB and XML table spaces . . . . . . . . . . . . . . . . 493
Restoring data by using DSN1COPY . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Backing up and restoring data with non-Db2 dump and restore . . . . . . . . . . . . . . . . . 494
Recovering accidentally dropped objects . . . . . . . . . . . . . . . . . . . . . . . . . 494
How to avoid accidentally dropping objects . . . . . . . . . . . . . . . . . . . . . . . 495
Recovering an accidentally dropped table . . . . . . . . . . . . . . . . . . . . . . . . 495
Recovering an accidentally dropped table space . . . . . . . . . . . . . . . . . . . . . . 497
Recovering a Db2 system to a given point in time using the RESTORE SYSTEM utility. . . . . . . . . . 501
Recovering by using Db2 restart recovery . . . . . . . . . . . . . . . . . . . . . . . . . 502
Recovering by using FlashCopy volume backups . . . . . . . . . . . . . . . . . . . . . . 503
Making catalog definitions consistent with your data after recovery to a prior point in time . . . . . . . . 503
Recovery of catalog and directory tables . . . . . . . . . . . . . . . . . . . . . . . . 506
Performing remote site recovery from a disaster at a local site . . . . . . . . . . . . . . . . . . 506
Recovering with the BACKUP SYSTEM and RESTORE SYSTEM utilities . . . . . . . . . . . . . 506
Recovering without using the BACKUP SYSTEM utility . . . . . . . . . . . . . . . . . . . 507
Backup and recovery involving clone tables . . . . . . . . . . . . . . . . . . . . . . . . 507
Recovery of temporal tables with system-period data versioning . . . . . . . . . . . . . . . . . 508
Data restore of an entire system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

Chapter 13. Recovering from different Db2 for z/OS problems . . . . . . . . . . . 509
Recovering from IRLM failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
Recovering from z/OS or power failure . . . . . . . . . . . . . . . . . . . . . . . . . 509
Recovering from disk failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Recovering from application errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Backing out incorrect application changes (with a quiesce point) . . . . . . . . . . . . . . . . 512
Backing out incorrect application changes (without a quiesce point) . . . . . . . . . . . . . . . 513
Recovering from IMS-related failures . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Recovering from IMS control region failure . . . . . . . . . . . . . . . . . . . . . . . 514
Recovering from IMS indoubt units of recovery . . . . . . . . . . . . . . . . . . . . . . 514
Recovering from IMS application failure . . . . . . . . . . . . . . . . . . . . . . . . 516
Recovering from a Db2 failure in an IMS environment . . . . . . . . . . . . . . . . . . . 517
Recovering from CICS-related failure . . . . . . . . . . . . . . . . . . . . . . . . . . 517
Recovering from CICS application failures. . . . . . . . . . . . . . . . . . . . . . . . 518

Contents ix
 Recovering Db2 when CICS is not operational . . . . . . . . . . . . . . . . . . . . . . 518
Recovering Db2 when the CICS attachment facility cannot connect to Db2 . . . . . . . . . . . . . 519
Recovering CICS indoubt units of recovery . . . . . . . . . . . . . . . . . . . . . . . 520
Recovering from CICS attachment facility failure . . . . . . . . . . . . . . . . . . . . . 523
Recovering from a QMF query failure . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Recovering from subsystem termination . . . . . . . . . . . . . . . . . . . . . . . . . 524
Recovering from temporary resource failure . . . . . . . . . . . . . . . . . . . . . . . . 525
Recovering from active log failures . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Recovering from being out of space in active logs . . . . . . . . . . . . . . . . . . . . . 526
Recovering from a write I/O error on an active log data set . . . . . . . . . . . . . . . . . . 527
Recovering from a loss of dual active logging . . . . . . . . . . . . . . . . . . . . . . 528
Recovering from I/O errors while reading the active log . . . . . . . . . . . . . . . . . . . 528
Recovering from archive log failures. . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Recovering from allocation problems with the archive log . . . . . . . . . . . . . . . . . . 530
Recovering from write I/O errors during archive log offload . . . . . . . . . . . . . . . . . 531
Recovering from read I/O errors on an archive data set during recovery . . . . . . . . . . . . . 531
Recovering from insufficient disk space for offload processing . . . . . . . . . . . . . . . . . 532
Recovering from BSDS failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Recovering from an I/O error on the BSDS . . . . . . . . . . . . . . . . . . . . . . . 533
Recovering from an error that occurs while opening the BSDS . . . . . . . . . . . . . . . . . 534
Recovering from unequal timestamps on BSDSs . . . . . . . . . . . . . . . . . . . . . . 534
Recovering the BSDS from a backup copy . . . . . . . . . . . . . . . . . . . . . . . . 535
Recovering from BSDS or log failures during restart . . . . . . . . . . . . . . . . . . . . . 537
Recovering from failure during log initialization or current status rebuild . . . . . . . . . . . . . 540
Recovering from a failure during forward log recovery . . . . . . . . . . . . . . . . . . . 552
Recovering from a failure during backward log recovery . . . . . . . . . . . . . . . . . . . 557
Recovering from a failure during a log RBA read request. . . . . . . . . . . . . . . . . . . 560
Recovering from unresolvable BSDS or log data set problem during restart. . . . . . . . . . . . . 561
Recovering from a failure resulting from total or excessive loss of log data . . . . . . . . . . . . . 563
Resolving inconsistencies resulting from a conditional restart . . . . . . . . . . . . . . . . . 567
Recovering from Db2 database failure . . . . . . . . . . . . . . . . . . . . . . . . . . 573
Recovering a Db2 subsystem to a prior point in time . . . . . . . . . . . . . . . . . . . . . 574
Recovering from a down-level page set problem. . . . . . . . . . . . . . . . . . . . . . . 575
Recovering from a problem with invalid LOBs . . . . . . . . . . . . . . . . . . . . . . . 577
Recovering from table space I/O errors. . . . . . . . . . . . . . . . . . . . . . . . . . 578
Recovering from Db2 catalog or directory I/O errors . . . . . . . . . . . . . . . . . . . . . 579
Recovering from integrated catalog facility failure . . . . . . . . . . . . . . . . . . . . . . 580
Recovering VSAM volume data sets that are out of space or destroyed . . . . . . . . . . . . . . 580
Recovering from out-of-disk-space or extent limit problems . . . . . . . . . . . . . . . . . . 581
Recovering from referential constraint violation . . . . . . . . . . . . . . . . . . . . . . . 585
Recovering from distributed data facility failure . . . . . . . . . . . . . . . . . . . . . . . 586
Recovering from conversation failure . . . . . . . . . . . . . . . . . . . . . . . . . 586
Recovering from communications database failure . . . . . . . . . . . . . . . . . . . . . 587
Recovering from database access thread failure . . . . . . . . . . . . . . . . . . . . . . 588
Recovering from VTAM failure . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
| Recovering from VTAM ACB OPEN problems . . . . . . . . . . . . . . . . . . . . . . 589
Recovering from TCP/IP failure . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Recovering from remote logical unit failure . . . . . . . . . . . . . . . . . . . . . . . 591
Recovering from an indefinite wait condition . . . . . . . . . . . . . . . . . . . . . . . 591
Recovering database access threads after security failure . . . . . . . . . . . . . . . . . . . 592
Performing remote-site disaster recovery . . . . . . . . . . . . . . . . . . . . . . . . . 593
Recovering from a disaster by using system-level backups . . . . . . . . . . . . . . . . . . 593
Restoring data from image copies and archive logs . . . . . . . . . . . . . . . . . . . . . 593
Recovering from disasters by using a tracker site . . . . . . . . . . . . . . . . . . . . . 608
Using data mirroring for disaster recovery . . . . . . . . . . . . . . . . . . . . . . . 619
Scenarios for resolving problems with indoubt threads . . . . . . . . . . . . . . . . . . . . 625
Scenario: Recovering from communication failure . . . . . . . . . . . . . . . . . . . . . 627
Scenario: Making a heuristic decision about whether to commit or abort an indoubt thread . . . . . . . 629
Scenario: Recovering from an IMS outage that results in an IMS cold start . . . . . . . . . . . . . 631
Scenario: Recovering from a Db2 outage at a requester that results in a Db2 cold start . . . . . . . . . 632
Scenario: What happens when the wrong Db2 subsystem is cold started . . . . . . . . . . . . . 636

x Administration Guide
 Scenario: Correcting damage from an incorrect heuristic decision about an indoubt thread . . . . . . . 638

Chapter 14. Reading log records . . . . . . . . . . . . . . . . . . . . . . . . 641

Contents of the log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
Unit of recovery log records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Checkpoint log records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Database page set control records . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Other exception information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
The physical structure of the log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Physical and logical log records . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
The log record header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
The log control interval definition (LCID) . . . . . . . . . . . . . . . . . . . . . . . . 650
Log record type codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Log record subtype codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Interpreting data change log records. . . . . . . . . . . . . . . . . . . . . . . . . . 657
Reading log records with IFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Gathering active log records into a buffer . . . . . . . . . . . . . . . . . . . . . . . . 658
Reading specific log records (IFCID 0129) . . . . . . . . . . . . . . . . . . . . . . . . 658
Reading complete log data (IFCID 0306) . . . . . . . . . . . . . . . . . . . . . . . . 659
| Reading complete log data for the GDPS Continuous Availability with zero data loss solution . . . . . . . 664
| Modifying Db2 for the GDPS Continuous Availability with zero data loss solution . . . . . . . . . . 664
| Modifying IFI READS calls for the GDPS Continuous Availability with zero data loss environment . . . . 667
| Recovering the compression dictionary data set without bringing down a Db2 data sharing group . . . . . 668
Reading log records with OPEN, GET, and CLOSE . . . . . . . . . . . . . . . . . . . . . . 668
JCL DD statements for Db2 stand-alone log services . . . . . . . . . . . . . . . . . . . . 669
Data sharing members that participate in a read. . . . . . . . . . . . . . . . . . . . . . 672
Registers and return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
Stand-alone log OPEN request. . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Stand-alone log GET request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
Stand-alone log CLOSE request . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Sample application that uses stand-alone log services . . . . . . . . . . . . . . . . . . . . 677
Reading log records with the log capture exit routine . . . . . . . . . . . . . . . . . . . . . 678
| How RBA and LRSN values are displayed . . . . . . . . . . . . . . . . . . . . . . . . 679

Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

Appendix A. Exit routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

Edit procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
Specifying edit procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
When edit routines are taken . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Parameter list for edit procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 685
Incomplete rows and edit routines . . . . . . . . . . . . . . . . . . . . . . . . . . 685
Expected output for edit routines. . . . . . . . . . . . . . . . . . . . . . . . . . . 686
Validation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
Specifying validation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
When validation routines are taken . . . . . . . . . . . . . . . . . . . . . . . . . . 688
Parameter list for validation routines . . . . . . . . . . . . . . . . . . . . . . . . . 689
Incomplete rows and validation routines . . . . . . . . . . . . . . . . . . . . . . . . 690
Expected output for validation routines . . . . . . . . . . . . . . . . . . . . . . . . 690
Date and time routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Specifying date and time routines . . . . . . . . . . . . . . . . . . . . . . . . . . 691
When date and time routines are taken . . . . . . . . . . . . . . . . . . . . . . . . . 692
Parameter list for date and time routines . . . . . . . . . . . . . . . . . . . . . . . . 693
Expected output for date and time routines . . . . . . . . . . . . . . . . . . . . . . . 694
Conversion procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
Specifying conversion procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 695
When conversion procedures are taken . . . . . . . . . . . . . . . . . . . . . . . . . 696
Parameter list for conversion procedures . . . . . . . . . . . . . . . . . . . . . . . . 696
Expected output for conversion procedures . . . . . . . . . . . . . . . . . . . . . . . 697
Field procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

Contents xi
 Field-definition for field procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 699
Specifying field procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
When field procedures are taken . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
Control blocks for execution of field procedures . . . . . . . . . . . . . . . . . . . . . . 701
Field-definition (function code 8) . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Field-encoding (function code 0) . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Field-decoding (function code 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Log capture routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Specifying log capture routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
When log capture routines are invoked . . . . . . . . . . . . . . . . . . . . . . . . . 712
Parameter list for log capture routines . . . . . . . . . . . . . . . . . . . . . . . . . 713
Routines for dynamic plan selection in CICS . . . . . . . . . . . . . . . . . . . . . . . . 714
General guidelines for writing exit routines . . . . . . . . . . . . . . . . . . . . . . . . 715
Coding rules for exit routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
Modifying exit routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
Execution environment for exit routines . . . . . . . . . . . . . . . . . . . . . . . . 716
Registers at invocation for exit routines. . . . . . . . . . . . . . . . . . . . . . . . . 716
Parameter list for exit routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Row formats for edit and validation routines . . . . . . . . . . . . . . . . . . . . . . . . 718
Column boundaries for edit and validation procedures . . . . . . . . . . . . . . . . . . . 718
Null values for edit procedures, field procedures, and validation routines . . . . . . . . . . . . . 719
Fixed-length rows for edit and validation routines . . . . . . . . . . . . . . . . . . . . . 719
Varying-length rows for edit and validation routines . . . . . . . . . . . . . . . . . . . . 719
Varying-length rows with nulls for edit and validation routines . . . . . . . . . . . . . . . . 720
EDITPROCs and VALIDPROCs for handling basic and reordered row formats . . . . . . . . . . . 721
Converting basic row format table spaces with edit and validation routines to reordered row format . . . . 721
Dates, times, and timestamps for edit and validation routines . . . . . . . . . . . . . . . . . 723
Parameter list for row format descriptions . . . . . . . . . . . . . . . . . . . . . . . . 724
Db2 codes for numeric data in edit and validation routines . . . . . . . . . . . . . . . . . . 725

Appendix B. Stored procedures for administration . . . . . . . . . . . . . . . . 727

Common SQL API stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 727
Versioning of XML documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
XML input documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
XML output documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
XML message documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
Troubleshooting Db2 stored procedure problems . . . . . . . . . . . . . . . . . . . . . . 732

Information resources for Db2 11 for z/OS and related products . . . . . . . . . . 733

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
Programming interface information . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
Terms and conditions for product documentation . . . . . . . . . . . . . . . . . . . . . . 738
Privacy policy considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743

xii Administration Guide

About this information
This information provides guidance information that you can use to perform a
variety of administrative tasks with Db2® for z/OS® (Db2).

Throughout this information, “Db2” means “Db2 11 for z/OS”. References to other
Db2 products use complete names or specific abbreviations.

Important: To find the most up to date content, always use IBM® Knowledge
Center, which is continually updated as soon as changes are ready. PDF manuals
are updated only when new editions are published, on an infrequent basis.

This information assumes that Db2 11 is running in new-function mode, and that
your application is running with the application compatibility value of 'V11R1'.
Availability of new function in Db2 11
The behavior of data definition statements such as CREATE, ALTER, and
DROP, which embed data manipulation SQL statements that contain new
capabilities, depends on the application compatibility value that is in effect
for the application. An application compatibility value of 'V11R1' must be
in effect for applications to use new capability in embedded statements
such as SELECT, INSERT, UPDATE, DELETE, MERGE, CALL, and SET
assignment-statement. Otherwise, an application compatibility value of
'V10R1' can be used for data definition statements.
Generally, new SQL capabilities, including changes to existing language
elements, functions, data manipulation statements, and limits, are available
only in new-function mode with applications set to an application
compatibility value of 'V11R1'.
Optimization and virtual storage enhancements are available in conversion
mode unless stated otherwise.
SQL statements can continue to run with the same expected behavior as in
DB2® 10 new-function mode with an application compatibility value of
'V10R1'.

Who should read this information

This information is primarily intended for system and database administrators. It
assumes that the user is familiar with:
v The basic concepts and facilities of Db2
v Time Sharing Option (TSO) and Interactive System Productivity Facility (ISPF)
v The basic concepts of Structured Query Language (SQL)
v The basic concepts of Customer Information Control System (CICS®)
v The basic concepts of Information Management System (IMS)
v How to define and allocate z/OS data sets using job control language (JCL).

Certain tasks require additional skills, such as knowledge of Transmission Control

Protocol/Internet Protocol (TCP/IP) or Virtual Telecommunications Access Method
(VTAM®) to set up communication between Db2 subsystems, or knowledge of the
IBM System Modification Program (SMP/E) to install IBM licensed programs.

© Copyright IBM Corp. 1982, 2017 xiii

 Db2 Utilities Suite for z/OS
Important: In Db2 11, the Db2 Utilities Suite for z/OS is available as an optional
product. 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.

Db2 11 utilities can use the DFSORT program regardless of whether you purchased
a license for DFSORT on your system. For more information, see the following
informational APARs:
v II14047
v II14213
v II13495

Db2 utilities can use IBM Db2 Sort for z/OS (5655-W42) as an alternative to
DFSORT for utility SORT and MERGE functions. Use of Db2 Sort for z/OS
requires the purchase of a Db2 Sort for z/OS license. For more information about
Db2 Sort for z/OS, see Db2 Sort for z/OS.
Related concepts:
Db2 utilities packaging (Db2 Utilities)

Terminology and citations

When referring to a Db2 product other than Db2 for z/OS, this information uses
the product's full name to avoid ambiguity.

| About the Db2 brand change: IBM is rebranding DB2 to Db2. As such, there will
| be changes to all the Db2 offerings. For example, “DB2 for z/OS” is now referred
| to as “Db2 for z/OS,” beginning with Db2 11. While IBM implements the change
| across the Db2 family of products, you might see references to the original name
| “DB2 for z/OS” or “DB2” in different IBM web pages and documents. “DB2 for
| z/OS” and “Db2 for z/OS” refer to the same product, when the PID, Entitlement
| Entity, version, modification, and release information match. For more information,
| see Revised naming for IBM Db2 family products.

The following terms are used as indicated:

Db2 Represents either the Db2 licensed program or a particular Db2 subsystem.
Tivoli OMEGAMON® XE for Db2 Performance Expert on z/OS
®

Refers to any of the following products:

v IBM Tivoli OMEGAMON XE for Db2 Performance Expert on z/OS
v IBM Db2 Performance Monitor on z/OS
v IBM Db2 Performance Expert for Multiplatforms and Workgroups
v IBM Db2 Buffer Pool Analyzer for z/OS
C, C++, and C language
Represent the C or C++ programming language.
CICS Represents CICS Transaction Server for z/OS.
IMS Represents the IMS Database Manager or IMS Transaction Manager.
™
MVS Represents the MVS element of the z/OS operating system, which is
equivalent to the Base Control Program (BCP) component of the z/OS
operating system.

xiv Administration Guide

 RACF®
Represents the functions that are provided by the RACF component of the
z/OS Security Server.

Accessibility features for Db2 11 for z/OS

Accessibility features help a user who has a physical disability, such as restricted
mobility or limited vision, to use information technology products successfully.

Accessibility features

The following list includes the major accessibility features in z/OS products,
including Db2 11 for z/OS. These features support:
v Keyboard-only operation.
v Interfaces that are commonly used by screen readers and screen magnifiers.
v Customization of display attributes such as color, contrast, and font size

Tip: The IBM Knowledge Center (which includes information for Db2 for z/OS)
and its related publications are accessibility-enabled for the IBM Home Page
Reader. You can operate all features using the keyboard instead of the mouse.

Keyboard navigation

For information about navigating the Db2 for z/OS ISPF panels using TSO/E or
ISPF, refer to the z/OS TSO/E Primer, the z/OS TSO/E User's Guide, and the z/OS
ISPF User's Guide. These guides describe how to navigate each interface, including
the use of keyboard shortcuts or function keys (PF keys). Each guide includes the
default settings for the PF keys and explains how to modify their functions.

Related accessibility information

IBM and accessibility

See the IBM Accessibility Center at http://www.ibm.com/able for more information
about the commitment that IBM has to accessibility.

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 z/OS documentation.

Send your comments by email to [email protected] 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 or a help topic title).

How to read syntax diagrams

Certain conventions apply to the syntax diagrams that are used in IBM
documentation.

Apply the following rules when reading the syntax diagrams that are used in Db2
for z/OS documentation:
v Read the syntax diagrams from left to right, from top to bottom, following the
path of the line.

About this information xv

 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.

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.

xvi Administration Guide

 ,

►► required_item ▼ repeatable_item ►◄

A repeat arrow above a stack indicates that you can repeat the items in the
stack.
v Sometimes a diagram must be split into fragments. The syntax fragment is
shown separately from the main syntax diagram, but the contents of the
fragment should be read as if they are on the main path of the diagram.

►► required_item fragment-name ►◄

fragment-name:

required_item
optional_name

v With the exception of XPath keywords, keywords appear in uppercase (for

example, FROM). Keywords must be spelled exactly as shown. XPath keywords
are defined as lowercase names, and 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.
Related concepts:
Commands in Db2 (Db2 Commands)
Db2 online utilities (Db2 Utilities)
Db2 stand-alone utilities (Db2 Utilities)

About this information xvii

xviii Administration Guide
Part 1. Designing and implementing Db2 databases

© Copyright IBM Corp. 1982, 2017 1

2 Administration Guide
Chapter 1. Database objects and relationships
The general tasks that are necessary to design a database are logical data modeling
and physical data modeling.

In logical data modeling, you design a model of the data without paying attention
to specific functions and capabilities of the DBMS that will store the data. In fact,
you could even build a logical data model without knowing which DBMS you will
use.

Physical data modeling begins when you move closer to a physical

implementation. The primary purpose of the physical design stage is to optimize
performance while ensuring the integrity of the data.

Logical database design with the entity-relationship model

Before you implement a database, you should plan or design the database so that
it satisfies all requirements.

Designing and implementing a successful database, one that satisfies the needs of
an organization, requires a logical data model. Logical data modeling is the process
of documenting the comprehensive business information requirements in an
accurate and consistent format. Analysts who do data modeling define the data
items and the business rules that affect those data items. The process of data
modeling acknowledges that business data is a vital asset that the organization
needs to understand and carefully manage. This section contains information that
was adapted from Handbook of Relational Database Design.

Consider the following business facts that a manufacturing company needs to

represent in its data model:
v Customers purchase products
v Products consist of parts
v Suppliers manufacture parts
v Warehouses store parts
v Transportation vehicles move the parts from suppliers to warehouses and then
to manufacturers

These are all business facts that a manufacturing company's logical data model
needs to include. Many people inside and outside the company rely on
information that is based on these facts. Many reports include data about these
facts.

Any business, not just manufacturing companies, can benefit from the task of data
modeling. Database systems that supply information to decision makers,
customers, suppliers, and others are more successful if their foundation is a sound
data model.

Modeling your data

Data analysts can perform the task of data modeling in a variety of ways.

© Copyright IBM Corp. 1982, 2017 3

 Procedure

To model data:
1. Build critical user views.
a. Carefully examining a single business activity or function.
b. Develop a user view, which is the model or representation of critical
information that the business activity requires.
This initial stage of the data modeling process is highly interactive. Because
data analysts cannot fully understand all areas of the business that they are
modeling, they work closely with the actual users. Working together,
analysts and users define the major entities (significant objects of interest)
and determine the general relationships between these entities.
In a later stage, the analyst combines each individual user view with all the
other user views into a consolidated logical data model.
2. Add keys to user views
Key business rules affect insert, update, and delete operations on the data. For
example, a business rule might require that each customer entity have at least
one unique identifier. Any attempt to insert or update a customer identifier that
matches another customer identifier is not valid. In a data model, a unique
identifier is called a primary key.
3. Add detail to user views and validate them.
a. Add other descriptive details that are less vital.
b. Associate these descriptive details, called attributes, to the entities.
For example, a customer entity probably has an associated phone number.
The phone number is a non-key attribute of the customer entity.
c. Validate all the user views
To validate the views, analysts use the normalization process and process
models. Process models document the details of how the business will use
the data.
4. Determine additional business rules that affect attributes.
a. Clarify the data-driven business rules.
Data-driven business rules are constraints on particular data values. These
constraints need to be true, regardless of any particular processing
requirements.
The advantage to defining data-driven business rules during the data
design stage, rather than during application design is that programmers of
many applications don't need to write code to enforce these business rules.
For example, Assume that a business rule requires that a customer entity
have a phone number, an address, or both. If this rule doesn't apply to the
data itself, programmers must develop, test, and maintain applications that
verify the existence of one of these attributes. Data-driven business
requirements have a direct relationship with the data, thereby relieving
programmers from extra work.
5. Integrate user views.
a. Combine into a consolidated logical data model the newly created different
user views.
b. Integrate other data models that already exist in the organization with the
new consolidated logical data model.
At this stage, analysts also strive to make their data model flexible so that it
can support the current business environment and possible future changes. For
example, assume that a retail company operates in a single country and that

4 Administration Guide
 business plans include expansion to other countries. Armed with knowledge of
these plans, analysts can build the model so that it is flexible enough to
support expansion into other countries.

Recommendations for logical data modeling

To build sound data models, analysts follow a well-planned methodology.

Follow these recommendation for building quality data models:

v Work interactively with the users as much as possible.
v Use diagrams to represent as much of the logical data model as possible.
v Build a data dictionary to supplement the logical data model diagrams.
A data dictionary is a repository of information about an organization's
application programs, databases, logical data models, users, and authorizations.
A data dictionary can be manual or automated.

Practical examples of data modeling

To better understand the key activities that are necessary for creating valid data
models, investigate one or more real-life data modeling scenarios.

You begin by defining your entities, the significant objects of interest. Entities are
the things about which you want to store information. For example, you might
want to define an entity, called EMPLOYEE, for employees because you need to
store information about everyone who works for your organization. You might also
define an entity, called DEPARTMENT, for departments.

Next, you define primary keys for your entities. A primary key is a unique
identifier for an entity. In the case of the EMPLOYEE entity, you probably need to
store a large amount of information. However, most of this information (such as
gender, birth date, address, and hire date) would not be a good choice for the
primary key. In this case, you could choose a unique employee ID or number
(EMPLOYEE_NUMBER) as the primary key. In the case of the DEPARTMENT
entity, you could use a unique department number (DEPARTMENT_NUMBER) as
the primary key.

After you have decided on the entities and their primary keys, you can define the
relationships that exist between the entities. The relationships are based on the
primary keys. If you have an entity for EMPLOYEE and another entity for
DEPARTMENT, the relationship that exists is that employees are assigned to
departments. You can read more about this topic in the next section.

After defining the entities, their primary keys, and their relationships, you can
define additional attributes for the entities. In the case of the EMPLOYEE entity,
you might define the following additional attributes:
v Birth date
v Hire date
v Home address
v Office phone number
v Gender
v Resume

Lastly, you normalize the data.

Related concepts:

Chapter 1. Database objects and relationships 5

 Entity normalization

Entities for different types of relationships

In a relational database, you can express several types of relationships.

Consider the possible relationships between employees and departments. If a given

employee can work in only one department, this relationship is one-to-one for
employees. One department usually has many employees; this relationship is
one-to-many for departments. Relationships can be one-to-many, many-to-one,
one-to-one, or many-to- many.

Subsections:
v “One-to-one relationships”
v “One-to-many and many-to-one relationships”
v “Many-to-many relationships” on page 7
v “Business rules for relationships” on page 7

The type of a given relationship can vary, depending on the specific environment.
If employees of a company belong to several departments, the relationship
between employees and departments is many-to-many.

You need to define separate entities for different types of relationships. When
modeling relationships, you can use diagram conventions to depict relationships
by using different styles of lines to connect the entities.

One-to-one relationships

When you are doing logical database design, one-to-one relationships are
bidirectional relationships, which means that they are single-valued in both
directions. For example, an employee has a single resume; each resume belongs to
only one person. The previous figure illustrates that a one-to-one relationship exists
between the two entities. In this case, the relationship reflects the rules that an
employee can have only one resume and that a resume can belong to only one
employee.

An employee
has a resume
Employee Resume
A resume is owned
by an employee

Figure 1. Assigning one-to-one facts to an entity

One-to-many and many-to-one relationships

A one-to-many relationship occurs when one entity has a multivalued relationship

with another entity. In the following figure, you see that a one-to-many
relationship exists between the two entities—employee and department. This figure
reinforces the business rules that a department can have many employees, but that
each individual employee can work for only one department.

6 Administration Guide
 Many employees work
for one department
Employee Department
One department can
have many employees

Figure 2. Assigning many-to-one facts to an entity

Many-to-many relationships
A many-to-many relationship is a relationship that is multivalued in both
directions. The following figure illustrates this kind of relationship. An employee
can work on more than one project, and a project can have more than one
employee assigned.

Employees work on
many projects
Employee Projects
Projects are worked on
by many employees

Figure 3. Assigning many-to-many facts to an entity

Business rules for relationships

Whether a given relationship is one-to-one, one-to-many, many-to-one, or

many-to-many, your relationships need to make good business sense. Therefore,
database designers and data analysts can be more effective when they have a good
understanding of the business. If they understand the data, the applications, and
the business rules, they can succeed in building a sound database design.

When you define relationships, you have a big influence on how smoothly your
business runs. If you don't do a good job at this task, your database and associated
applications are likely to have many problems, some of which may not manifest
themselves for years.

Entity attributes
When you define attributes for the entities, you generally work with the data
administrator to decide on names, data types, and appropriate values for the
attributes.

Attribute names
Most organizations have naming guidelines. In addition to following these
guidelines, data analysts also base attribute definitions on class words.

A class word is a single word that indicates the nature of the data that the attribute
represents.

The class word NUMBER indicates an attribute that identifies the number of an
entity. Therefore, attribute names that identify the numbers of entities should
include the class word of NUMBER. Some examples are EMPLOYEE_NUMBER,
PROJECT_NUMBER, and DEPARTMENT_NUMBER.

When an organization does not have well-defined guidelines for attribute names,
data analysts try to determine how the database designers have historically named

Chapter 1. Database objects and relationships 7

 attributes. Problems occur when multiple individuals are inventing their own
naming guidelines without consulting one another.

Data types of attributes

You must specify a data type for each attribute of an entity. Most organizations
have well-defined guidelines for using the different data types.

You might use the following data types for attributes of the EMPLOYEE entity:
v EMPLOYEE_NUMBER: CHAR(6)
v EMPLOYEE_LAST_NAME: VARCHAR(15)
v EMPLOYEE_HIRE_DATE: DATE
v EMPLOYEE_SALARY_AMOUNT: DECIMAL(9,2)

The data types that you choose are business definitions of the data type. During
physical database design, you might need to change data type definitions or use a
subset of these data types. The database or the host language might not support all
of these definitions, or you might make a different choice for performance reasons.

For example, you might need to represent monetary amounts, but Db2 and many
host languages do not have a data type MONEY. In the United States, a natural
choice for the SQL data type in this situation is DECIMAL(10,2) to represent
dollars. But you might also consider the INTEGER data type for fast, efficient
performance.
Related concepts:
Data types (Introduction to Db2 for z/OS)
Related reference:
CREATE TABLE (Db2 SQL)
SQL data type attributes (Db2 Programming for ODBC)

Appropriate values for attributes

When you design a database, you need to decide what values are acceptable for
the various attributes of an entity.

For example, you would not want to allow numeric data in an attribute for a
person's name. The data types that you choose limit the values that apply to a
given attribute, but you can also use other mechanisms. These other mechanisms
are domains, null values, and default values.

Subsections:
v “Domain”
v “Null values” on page 9
v “Default values” on page 9

Domain

A domain describes the conditions that an attribute value must meet to be a valid
value. Sometimes the domain identifies a range of valid values. By defining the
domain for a particular attribute, you apply business rules to ensure that the data
will make sense.

Example 1: A domain might state that a phone number attribute must be a 10-digit
value that contains only numbers. You would not want the phone number to be

8 Administration Guide
 incomplete, nor would you want it to contain alphabetic or special characters and
thereby be invalid. You could choose to use either a numeric data type or a
character data type. However, the domain states the business rule that the value
must be a 10-digit value that consists of numbers.

Example 2: A domain might state that a month attribute must be a 2-digit value
from 01 to 12. Again, you could choose to use datetime, character, or numeric data
types for this value, but the domain demands that the value must be in the range
of 01 through 12. In this case, incorporating the month into a datetime data type is
probably the best choice. This decision should be reviewed again during physical
database design.

Null values

When you are designing attributes for your entities, you will sometimes find that
an attribute does not have a value for every instance of the entity. For example,
you might want an attribute for a person's middle name, but you can't require a
value because some people have no middle name. For these occasions, you can
define the attribute so that it can contain null values.

A null value is a special indicator that represents the absence of a value. The value
can be absent because it is unknown, not yet supplied, or nonexistent. The DBMS
treats the null value as an actual value, not as a zero value, a blank, or an empty
string.

Just as some attributes should be allowed to contain null values, other attributes
should not contain null values.

Example: For the EMPLOYEE entity, you might not want to allow the attribute
EMPLOYEE_LAST_NAME to contain a null value.

Default values

In some cases, you may not want a given attribute to contain a null value, but you
don't want to require that the user or program always provide a value. In this case,
a default value might be appropriate.

A default value is a value that applies to an attribute if no other valid value is

available.

Example: Assume that you don't want the EMPLOYEE_HIRE_DATE attribute to

contain null values and that you don't want to require users to provide this data. If
data about new employees is generally added to the database on the employee's
first day of employment, you could define a default value of the current date.

Entity normalization
After you define entities and decide on attributes for the entities, you normalize
entities to avoid redundancy.

An entity is normalized if it meets a set of constraints for a particular normal form,

which this section describes. Normalization helps you avoid redundancies and
inconsistencies in your data. This section summarizes rules for first, second, third,
and fourth normal forms of entities, and it describes reasons why you should or
shouldn't follow these rules.

Chapter 1. Database objects and relationships 9

 Subsections:
v “First normal form”
v “Second normal form”
v “Third normal form” on page 11
v “Fourth normal form” on page 13

The rules for normal form are cumulative. In other words, for an entity to satisfy
the rules of second normal form, it also must satisfy the rules of first normal form.
An entity that satisfies the rules of fourth normal form also satisfies the rules of
first, second, and third normal form.

In this section, you will see many references to the word instance. In the context of
logical data modeling, an instance is one particular occurrence. An instance of an
entity is a set of data values for all of the attributes that correspond to that entity.

Example: The following figure shows one instance of the EMPLOYEE entity.

Figure 4. The EMPLOYEE entity

First normal form

A relational entity satisfies the requirement of first normal form if every instance of
an entity contains only one value, never multiple repeating attributes. Repeating
attributes, often called a repeating group, are different attributes that are inherently
the same. In an entity that satisfies the requirement of first normal form, each
attribute is independent and unique in its meaning and its name.

Example: Assume that an entity contains the following attributes:

EMPLOYEE_NUMBER
JANUARY_SALARY_AMOUNT
FEBRUARY_SALARY_AMOUNT
MARCH_SALARY_AMOUNT

This situation violates the requirement of first normal form, because

JANUARY_SALARY_AMOUNT, FEBRUARY_SALARY_AMOUNT, and
MARCH_SALARY_AMOUNT are essentially the same attribute, EMPLOYEE_
MONTHLY_SALARY_AMOUNT.

Second normal form

An entity is in second normal form if each attribute that is not in the primary key
provides a fact that depends on the entire key. A violation of the second normal
form occurs when a nonprimary key attribute is a fact about a subset of a
composite key.

Example: An inventory entity records quantities of specific parts that are stored at
particular warehouses. The following figure shows the attributes of the inventory

10 Administration Guide
entity.

Figure 5. Entity in violation of the second normal form

Here, the primary key consists of the PART and the WAREHOUSE attributes
together. Because the attribute WAREHOUSE_ADDRESS depends only on the
value of WAREHOUSE, the entity violates the rule for second normal form. This
design causes several problems:
v Each instance for a part that this warehouse stores repeats the address of the
warehouse.
v If the address of the warehouse changes, every instance referring to a part that is
stored in that warehouse must be updated.
v Because of the redundancy, the data might become inconsistent. Different
instances could show different addresses for the same warehouse.
v If at any time the warehouse has no stored parts, the address of the warehouse
might not exist in any instances in the entity.

To satisfy second normal form, the information in the previous figure would be in
two entities, as the following figure shows.

Figure 6. Entities that satisfy the second normal form

Third normal form

An entity is in third normal form if each nonprimary key attribute provides a fact
that is independent of other non-key attributes and depends only on the key. A
violation of the third normal form occurs when a nonprimary attribute is a fact
about another non-key attribute.

Chapter 1. Database objects and relationships 11

 Figure 7. Results of an update in a table that violates the third normal form

Example: The first entity in the previous figure contains the attributes
EMPLOYEE_NUMBER and DEPARTMENT_NUMBER. Suppose that a program or
user adds an attribute, DEPARTMENT_NAME, to the entity. The new attribute
depends on DEPARTMENT_NUMBER, whereas the primary key is on the
EMPLOYEE_NUMBER attribute. The entity now violates third normal form.

Changing the DEPARTMENT_NAME value based on the update of a single

employee, David Brown, does not change the DEPARTMENT_NAME value for
other employees in that department. The updated version of the entity as shown in
the previous figure illustrates the resulting inconsistency. Additionally, updating
the DEPARTMENT_ NAME in this table does not update it in any other table that
might contain a DEPARTMENT_NAME column.

You can normalize the entity by modifying the EMPLOYEE_DEPARTMENT entity

and creating two new entities: EMPLOYEE and DEPARTMENT. The following
figure shows the new entities. The DEPARTMENT entity contains attributes for
DEPARTMENT_NUMBER and DEPARTMENT_NAME. Now, an update such as
changing a department name is much easier. You need to make the update only to
the DEPARTMENT entity.

12 Administration Guide
Figure 8. Employee and department entities that satisfy the third normal form

Fourth normal form

An entity is in fourth normal form if no instance contains two or more

independent, multivalued facts about an entity.

Figure 9. Entity in violation of the fourth normal form

Example: Consider the EMPLOYEE entity. Each instance of EMPLOYEE could have
both SKILL_CODE and LANGUAGE_CODE. An employee can have several skills
and know several languages. Two relationships exist, one between employees and
skills, and one between employees and languages. An entity is not in fourth
normal form if it represents both relationships, as the previous figure shows.

Instead, you can avoid this violation by creating two entities that represent both
relationships, as the following figure shows.

Chapter 1. Database objects and relationships 13

 Figure 10. Entities that satisfy the fourth normal form

If, however, the facts are interdependent (that is, the employee applies certain
languages only to certain skills), you should not split the entity.

You can put any data into fourth normal form. A good rule to follow when doing
logical database design is to arrange all the data in entities that are in fourth
normal form. Then decide whether the result gives you an acceptable level of
performance. If the performance is not acceptable, denormalizing your design is a
good approach to improving performance.
Related concepts:
Practical examples of data modeling
Denormalization of tables

Logical database design with Unified Modeling Language

You can use the Unified Modeling Language (UML) to create a model of your
database design.

The Object Management Group is a consortium that created the UML standard.
UML modeling is based on object-oriented programming principals. The basic
difference between the entity-relationship model and the UML model is that,
instead of designing entities, you model objects. UML defines a standard set of
modeling diagrams for all stages of developing a software system. Conceptually,
UML diagrams are like the blueprints for the design of a software development
project.

Some examples of UML diagrams are as follows:

Class Identifies high-level entities, known as classes. A class describes a set of
objects that have the same attributes. A class diagram shows the
relationships between classes.
Use case
Presents a high-level view of a system from the user's perspective. A use
case diagram defines the interactions between users and applications or
between applications. These diagrams graphically depict system behavior.
You can work with use-case diagrams to capture system requirements,
learn how the system works, and specify system behavior.
Activity
Models the workflow of a business process, typically by defining rules for
the sequence of activities in the process. For example, an accounting
company can use activity diagrams to model financial transactions.
Interaction
Shows the required sequence of interactions between objects. Interaction
diagrams can include sequence diagrams and collaboration diagrams.

14 Administration Guide
 v Sequence diagrams show object interactions in a time-based sequence
that establishes the roles of objects and helps determine class
responsibilities and interfaces.
v Collaboration diagrams show associations between objects that define
the sequence of messages that implement an operation or a transaction.
Component
Shows the dependency relationships between components, such as main
programs and subprograms.

Developers can graphically represent the architecture of a database and how it

interacts with applications using one of many available UML modeling tools.
Similarities exist between components of the entity-relationship model and UML
diagrams. For example, the class structure corresponds closely to the entity
structure.

The logical data model provides an overall view of the captured business
requirements as they pertain to data entities. The data model diagram graphically
represents the physical data model. The physical data model applies the logical
data model's captured requirements to specific DBMS languages. Physical data
models also capture the lower-level detail of a DBMS database.

Database designers can customize the data model diagram from other UML
diagrams, which allows them to work with concepts and terminology, such as
columns, tables, and relationships, with which they are already familiar.
Developers can also transform a logical data model into a physical data model.

Because the data model diagram includes diagrams for modeling an entire system,
it allows database designers, application developers, and other development team
members to share and track business requirements throughout development. For
example, database designers can capture information, such as constraints, triggers,
and indexes, directly on the UML diagram. Developers can also transfer between
object and data models and use basic transformation types such as many-to-many
relationships.

Physical database design

After you complete the logical design of your database, you now move to the
physical design. The purpose of building a physical design of your database is to
optimize performance, while ensuring data integrity by avoiding unnecessary data
redundancies.

During physical design, you transform the entities into tables, the instances into
rows, and the attributes into columns. You and your colleagues must decide on
many factors that affect the physical design, such as:
v How to translate entities into physical tables
v What attributes to use for columns of the physical tables
v Which columns of the tables to define as keys
v What indexes to define on the tables
v What views to define on the tables
v How to denormalize the tables
v How to resolve many-to-many relationships

Chapter 1. Database objects and relationships 15

 Physical design is the time when you abbreviate the names that you chose during
logical design. For example, you can abbreviate the column name that identifies
employees, EMPLOYEE_NUMBER, to EMPNO. The column name size has a 30-
byte maximum, and the table name size has a 128-byte maximum.

The task of building the physical design is a job that never ends. You need to
continually monitor the performance and data integrity characteristics of a
database as time passes. Many factors necessitate periodic refinements to the
physical design.

Db2 lets you change many of the key attributes of your design with ALTER SQL
statements. For example, assume that you design a partitioned table so that it will
store 36 months of data. Later you discover that you need to extend that design to
hold 84 months of data. You can add or rotate partitions for the current 36 months
to accommodate the new design.

The remainder of this chapter includes some valuable information that can help
you build and refine your database's physical design.

Denormalization of tables
During physical design, analysts transform the entities into tables and the
attributes into columns.

Denormalization is a key step in the task of building a physical relational database

design. It is the intentional duplication of columns in multiple tables, and the
consequence is increased data redundancy.

The warehouse address column first appears as part of a table that contains
information about parts and warehouses. To further normalize the design of the
table, analysts remove the warehouse address column from that table. Analysts
also define the column as part of a table that contains information only about
warehouses.

Normalizing tables is generally the recommended approach. What if applications

require information about both parts and warehouses, including the addresses of
warehouses? The premise of the normalization rules is that SQL statements can
retrieve the information by joining the two tables. The problem is that, in some
cases, performance problems can occur as a result of normalization. For example,
some user queries might view data that is in two or more related tables; the result
is too many joins. As the number of tables increases, the access costs can increase,
depending on the size of the tables, the available indexes, and so on. For example,
if indexes are not available, the join of many large tables might take too much
time. You might need to denormalize your tables. Denormalization is the
intentional duplication of columns in multiple tables, and it increases data
redundancy.

Example: Consider the design in which both tables have a column that contains
the addresses of warehouses. If this design makes join operations unnecessary, it
could be a worthwhile redundancy. Addresses of warehouses do not change often,
and if one does change, you can use SQL to update all instances fairly easily.

Tip: Do not automatically assume that all joins take too much time. If you join
normalized tables, you do not need to keep the same data values synchronized in

16 Administration Guide
multiple tables. In many cases, joins are the most efficient access method, despite
the overhead they require. For example, some applications achieve 44-way joins in
subsecond response time.

When you are building your physical design, you and your colleagues need to
decide whether to denormalize the data. Specifically, you need to decide whether
to combine tables or parts of tables that are frequently accessed by joins that have
high performance requirements. This is a complex decision about which this book
cannot give specific advice. To make the decision, you need to assess the
performance requirements, different methods of accessing the data, and the costs of
denormalizing the data. You need to consider the trade-off: is duplication, in
several tables, of often-requested columns less expensive than the time for
performing joins?

Recommendations:
v Do not denormalize tables unless you have a good understanding of the data
and the business transactions that access the data. Consult with application
developers before denormalizing tables to improve the performance of users'
queries.
v When you decide whether to denormalize a table, consider all programs that
regularly access the table, both for reading and for updating. If programs
frequently update a table, denormalizing the table affects performance of update
programs because updates apply to multiple tables rather than to one table.

In the following figure, information about parts, warehouses, and warehouse

addresses appears in two tables, both in normal form.

Figure 11. Two tables that satisfy second normal form

The following figure illustrates the denormalized table.

Figure 12. The denormalized table

Resolving many-to-many relationships is a particularly important activity because

doing so helps maintain clarity and integrity in your physical database design. To
resolve many-to-many relationships, you introduce associative tables, which are
intermediate tables that you use to tie, or associate, two tables to each other.

Example: Employees work on many projects. Projects have many employees. In the
logical database design, you show this relationship as a many-to-many relationship
between project and employee. To resolve this relationship, you create a new
associative table, EMPLOYEE_PROJECT. For each combination of employee and
project, the EMPLOYEE_PROJECT table contains a corresponding row. The
primary key for the table would consist of the employee number (EMPNO) and
the project number (PROJNO).

Chapter 1. Database objects and relationships 17

 Another decision that you must make relates to the use of repeating groups.

Example: Assume that a heavily used transaction requires the number of wires that
are sold by month in a given year. Performance factors might justify changing a
table so that it violates the rule of first normal form by storing repeating groups. In
this case, the repeating group would be: MONTH, WIRE. The table would contain
a row for the number of sold wires for each month (January wires, February wires,
March wires, and so on).

Recommendation: If you decide to denormalize your data, document your

denormalization thoroughly. Describe, in detail, the logic behind the
denormalization and the steps that you took. Then, if your organization ever needs
to normalize the data in the future, an accurate record is available for those who
must do the work.
Related concepts:
Entity normalization
Database design with denormalization (Introduction to Db2 for z/OS)

Views to customize what data users see

A view offers an alternative way of describing data that exists in one or more
tables.

Some users might find that no single table contains all the data they need; rather,
the data might be scattered among several tables. Furthermore, one table might
contain more data than users want to see, or more than you want to authorize
them to see. For those situations, you can create views.

You might want to use views for a variety of reasons:

v To limit access to certain kinds of data
You can create a view that contains only selected columns and rows from one or
more tables. Users with the appropriate authorization on the view see only the
information that you specify in the view definition.
Example: You can define a view on the EMP table to show all columns except
SALARY and COMM (commission). You can grant access to this view to people
who are not managers because you probably don't want them to have access to
salary and commission information.
v To combine data from multiple tables
You can create a view that uses UNION or UNION ALL operators to logically
combine smaller tables, and then query the view as if it were one large table.
Example: Assume that three tables contain data for a period of one month. You
can create a view that is the UNION ALL of three fullselects, one for each month
of the first quarter of 2004. At the end of the third month, you can view
comprehensive quarterly data.

You can create a view any time after the underlying tables exist. The owner of a
set of tables implicitly has the authority to create a view on them. A user with
administrative authority at the system or database level can create a view for any
owner on any set of tables. If they have the necessary authority, other users can
also create views on a table that they did not create.
Related concepts:
Db2 views (Introduction to Db2 for z/OS)

18 Administration Guide
 Indexes on table columns
If you are involved in the physical design of a database, you will be working with
other designers to determine what columns you should index.

You will use process models that describe how different applications are going to
be accessing the data. This information is important when you decide on indexing
strategies to ensure adequate performance.

The main purposes of an index are:

v To optimize data access
In many cases, access to data is faster with an index than without an index. If
the DBMS uses an index to find a row in a table, the scan can be faster than
when the DBMS scans an entire table.
v To ensure uniqueness
A table with a unique index cannot have two rows with the same values in the
column or columns that form the index key. For example, if payroll applications
use employee numbers, no two employees can have the same employee number.
Unique indexes can include additional columns that are not part of a unique
constraint. Those columns are called INCLUDE columns. When you specify
INCLUDE columns in a unique index, queries can use the unique index for
index-only access. Including these columns can eliminate the need to maintain
extra indexes that are used solely to enable index-only access.
v To enable clustering
A clustering index keeps table rows in a specified sequence to minimize page
access for a set of rows.

In general, users of the table are unaware that an index is in use. Db2 decides
whether to use the index to access the table.
Related concepts:
Creation of indexes (Introduction to Db2 for z/OS)
Index access (ACCESSTYPE is 'I', 'IN', 'I1', 'N', 'MX', or 'DX') (Db2
Performance)
Related tasks:
Designing indexes for performance (Db2 Performance)
Related information:
Implementing Db2 indexes

Hash access on tables

You can use hash access to optimize data access for certain kinds of tables.

Introductory concepts
| Db2 hash spaces (deprecated) (Introduction to Db2 for z/OS)

If you are involved in the physical design of a database, you work with other
designers to determine when to enable hash access on tables.

The main purposes of hash access is to optimize data access. If your programs
regularly access a single row in a table and the table has a unique identifier for

Chapter 1. Database objects and relationships 19

 each row, you can use hash access to directly retrieve the data from individual
rows. Hash access requires that tables have at least one column with values that
are unique to each row.
Related concepts:
Hash access (ACCESSTYPE='H', 'HN', or 'MH') (Db2 Performance)
Related tasks:
| Creating tables that use hash organization (deprecated)
| Altering tables for hash access (deprecated)
| Monitoring hash access (deprecated) (Db2 Performance)

| Maintaining archive data

| Suppose that you have historical data that you want to save but do not intend to
| reference frequently. Db2 can store and maintain that data for you in a separate
| table that is called an archive table.

| About this task

| An archive table is associated with a particular base table that is called an

| archive-enabled table.

| Introductory concepts
| Archive-enabled tables and archive tables (Introduction to Db2 for z/OS)

| Procedure

| To maintain archive data:

| 1. Create an archive table.
| 2. Turn archiving on and off as needed by using the
| SYSIBMADM.MOVE_TO_ARCHIVE global variable, as described in “Creating
| an archive table” on page 83. When archiving is turned on, you cannot update
| the archive-enabled table.
| 3. For queries against the archive-enabled table, set them to include or exclude
| archive data as needed by using the SYSIBMADM.GET_ARCHIVE global
| variable, as described in Archive-enabled tables and archive tables (Introduction
| to Db2 for z/OS).
| Related reference:
| Built-in global variables (Db2 SQL)

20 Administration Guide
Chapter 2. Implementing your database design
Implementing your database design involves implementing Db2 objects, loading
and managing data, and altering your design as necessary.

Tip:

You can simplify your database implementation by letting Db2 implicitly create
certain objects for you. For example, if you omit the IN clause in a CREATE
TABLE statement, Db2 creates a table space and database for the table, and creates
other required objects such as:
v The primary key enforcing index and the unique key index
v The ROWID index (if the ROWID column is defined as GENERATED BY
DEFAULT)
v LOB table spaces and auxiliary tables and indexes for LOB columns

Related concepts:
Altering your database design
Related tasks:
Designing databases for performance (Db2 Performance)
Compressing your data (Db2 Performance)
Related reference:
CREATE TABLE (Db2 SQL)

Implementing Db2 databases

Db2 databases are a set of Db2 structures that include a collection of tables, their
associated indexes, and the table spaces in which they reside.

Use Db2 databases to collect and control data.

Related concepts:
Db2 databases (Introduction to Db2 for z/OS)

Creating Db2 databases

You can create a Db2 database by defining a database at the current server.

About this task

Creating a set of objects in a specific database has the following advantages.

v You can start and stop an entire database as a unit. You can display the status of
all objects in the database by using a single command that names only the
database. Therefore, place a set of related tables into the same database. (The
same database holds all indexes on those tables.)

© Copyright IBM Corp. 1982, 2017 21

 v If you want to improve concurrency and memory use, keep the number of tables
in a single database relatively small (maximum of 20 tables). For example, with
fewer tables, Db2 performs a reorganization in a shorter length of time.
v Having separate databases allows data definitions to run concurrently and also
uses less space for control blocks.

Procedure

To create a database, use one of the following approaches:

v Issue a CREATE DATABASE statement.
v Issue a CREATE TABLE statement and omit the IN clause. Db2 implicitly creates
the table space and database for the table. The name of the database is
DSNxxxxx, where xxxxx is the next five-digit number from a sequence.
Related concepts:
Db2 databases (Introduction to Db2 for z/OS)
Related reference:
CREATE DATABASE (Db2 SQL)

Dropping Db2 databases

You can drop a Db2 database by removing the database at the current server.
When you drop a database, all of its table spaces, tables, index spaces, and indexes
are dropped, too.

Procedure

To drop a database:

Issue the DROP DATABASE statement.

Related concepts:
Db2 databases (Introduction to Db2 for z/OS)
Related reference:
DROP (Db2 SQL)

Implementing Db2 storage groups

A storage group is a set of storage objects on which Db2 for z/OS data can be
stored. Db2 uses storage groups to allocate storage for table spaces and indexes,
and to define, extend, alter, and delete VSAM data sets.

You have the following options for creating storage groups and managing Db2
data sets:
v You can let Db2 manage the data sets. This option means less work for Db2
database administrators.
v You can let SMS manage some or all of the data sets, either when you use Db2
storage groups or when you use data sets that you have defined yourself. This
option offers a reduced workload for Db2 database administrators and storage
administrators. For more information, see “Enabling SMS to control Db2 storage
groups” on page 25.
v You can define and manage your own data sets using VSAM Access Method
Services. This option gives you the most control over the physical storage of
tables and indexes.
22 Administration Guide
 Related tasks:
Altering Db2 storage groups

Advantages of storage groups

Allowing Db2 to manage your data sets by using Db2 storage groups offers several
advantages.

The following list describes some of the things that Db2 does for you in managing
your auxiliary storage requirements:
v When a table space is created, Db2 defines the necessary VSAM data sets using
VSAM Access Method Services. After the data sets are created, you can process
them with access method service commands that support VSAM control-interval
(CI) processing (for example, IMPORT and EXPORT).

Exception: You can defer the allocation of data sets for table spaces and index
spaces by specifying the DEFINE NO clause on the associated statement
(CREATE TABLESPACE and CREATE INDEX), which also must specify the
USING STOGROUP clause.
v When a table space is dropped, Db2 automatically deletes the associated data
sets.
v When a data set in a segmented or simple table space reaches its maximum size
of 2 GB, Db2 might automatically create a new data set. The primary data set
allocation is obtained for each new data set.
v When needed, Db2 can extend individual data sets.
v When you create or reorganize a table space that has associated data sets, Db2
deletes and then redefines them, reclaiming fragmented space. However, when
you run REORG with the REUSE option and SHRLEVEL NONE, REORG resets
and reuses Db2-managed data sets without deleting and redefining them. If the
size of your table space is not changing, using the REUSE parameter could be
more efficient.

Exception: When reorganizing a LOB table space with the SHRLEVEL NONE
option, Db2 does not delete and redefine the first data set that was allocated for
the table space. If the REORG results in empty data sets beyond the first data
set, Db2 deletes those empty data sets.
v When you want to move data sets to a new volume, you can alter the volumes
list in your storage group. Db2 automatically relocates your data sets during the
utility operations that build or rebuild a data set (LOAD REPLACE, REORG,
REBUILD, and RECOVER).

Restriction: If you use the REUSE option, Db2 does not delete and redefine the
data sets and therefore does not move them.
For a LOB table space, you can alter the volumes list in your storage group, and
Db2 automatically relocates your data sets during the utility operations that
build or rebuild a data set (LOAD REPLACE and RECOVER).
To move user-defined data sets, you must delete and redefine the data sets in
another location.
Related concepts:
Managing your own data sets
Related information:
Managing Db2 data sets with DFSMShsm

Chapter 2. Implementing your database design 23

 Control interval sizing
A control interval is an area on disk where VSAM stores records and creates
distributed free space. A control interval is a unit of information that VSAM
transfers between virtual and auxiliary storage.

Db2 page sets are defined as VSAM linear data sets. Db2 can define data sets with
variable VSAM control intervals. One of the biggest benefits of variable VSAM
control intervals is an improvement in query processing performance.

The VARY DS CONTROL INTERVAL parameter on installation panel DSNTIP7

allows you to control whether Db2-managed data sets have variable VSAM control
intervals:
v A value of YES indicates that a Db2-managed data set is created with a VSAM
control interval that corresponds to the size of the buffer pool that is used for
the table space. This is the default value.
v A value of NO indicates that a Db2-managed data set is created with a fixed
VSAM control interval of 4 KB, regardless of the size of the buffer pool that is
used for the table space.

The following table shows the default and compatible control interval sizes for
each table space page size. For example, a table space with pages that are 16 KB in
size can have a VSAM control interval of 4 KB or 16 KB. Control interval sizing
has no impact on indexes. Index pages are always 4 KB in size.
Table 1. Default and compatible control interval sizes
Compatible control interval
Table space page size Default control interval size sizes
4 KB 4 KB 4 KB
8 KB 8 KB 4 KB, 8 KB
16 KB 16 KB 4 KB, 16 KB
32 KB 32 KB 4 KB, 32 KB

Creating Db2 storage groups

You can create Db2 storage groups by using the CREATE STOGROUP statement.
Db2 storage groups are a set of volumes on disks that hold the data sets in which
tables and indexes are stored.

Procedure

To create a Db2 storage group:

1. Issue the SQL statement CREATE STOGROUP.
2. Specify the storage group name.
Db2 storage group names are unqualified identifiers of up to 128 characters. A
Db2 storage group name cannot be the same as any other storage group name
in the Db2 catalog.

Results
After you define a storage group, Db2 stores information about it in the Db2
catalog. (This catalog is not the same as the integrated catalog facility catalog that
describes Db2 VSAM data sets). The catalog table SYSIBM.SYSSTOGROUP has a

24 Administration Guide
 row for each storage group, and SYSIBM.SYSVOLUMES has a row for each
volume. With the proper authorization, you can retrieve the catalog information
about Db2 storage groups by using SQL statements.

Enabling SMS to control Db2 storage groups

Managing data sets with the Storage Management Subsystem (SMS) family of
products can reduce workload for database administrators and storage
administrators.

Procedure

To enable SMS to control Db2 storage groups:

1. Issue a CREATE STOGROUP SQL statement to define a Db2 storage group. You
can specify SMS classes when you create a storage group.
2. Indicate how you want SMS to control the allocation of volumes in one of the
following ways:
v Specify an asterisk (*) for the VOLUMES attribute.
v Specify the DATACLAS, MGMTCLAS, or STORCLAS keywords.

What to do next

If you use Db2 to allocate data to specific volumes, you must assign an SMS
storage class with guaranteed space, and you must manage free space for each
volume to prevent failures during the initial allocation and extension. Using
guaranteed space reduces the benefits of SMS allocation, requires more time for
space management, and can result in more space shortages. You should only use
guaranteed space when space needs are relatively small and do not change.
Related tasks:
Migrating to DFSMShsm
Related reference:
CREATE STOGROUP (Db2 SQL)

Deferring allocation of Db2-managed data sets

When you execute a CREATE TABLESPACE statement with the USING
STOGROUP clause, Db2 generally defines the necessary VSAM data sets for the
table space. However, you might want to define a table space without immediately
allocating the associated data sets.

About this task

For example, you might be installing a software program that requires that many
table spaces be created, but your company might not need to use some of those
table spaces. You might prefer not to allocate data sets for the table spaces that you
will not be using.

The deferral of allocating data sets is recommended when:

v Performance of the CREATE TABLESPACE statement is important
v Disk resource is constrained

Procedure

To defer the physical allocation of Db2-managed data sets:

Chapter 2. Implementing your database design 25

 Issue a CREATE TABLESPACE statement with the DEFINE NO clause.
The DEFINE NO clause is allowed on some Db2 objects, such as explicitly created
LOB table spaces, auxiliary indexes, and XML indexes. Additionally, the
IMPDSDEF subsystem parameter specifies whether Db2 defines the underlying
data set for implicitly created table spaces and index spaces. When you specify this
subsystem parameter as NO, the data set is not defined when the table space or
index space is implicitly created.

Restriction: The DEFINE NO clause is not allowed for table spaces in a work file
database, or for user-defined data sets. (In the case of user-defined data sets, the
table space is created with the USING VCAT clause of the CREATE TABLESPACE
statement).
Do not use the DEFINE NO clause on a table space if you plan to use a tool
outside of Db2 to propagate data into a data set in the table space. When you use
DEFINE NO, the Db2 catalog indicates that the data sets have not yet been
allocated for that table space. Then, if data is propagated from a tool outside of
Db2 into a data set in the table space, the Db2 catalog information does not reflect
the fact that the data set has been allocated. The resulting inconsistency causes Db2
to deny application programs access to the data until the inconsistency is resolved.

Results

The table space is created, but Db2 does not allocate (that is, define) the associated
data sets until a row is inserted or loaded into a table in that table space. The Db2
catalog table SYSIBM.SYSTABLEPART contains a record of the created table space
and an indication that the data sets are not yet allocated.

How Db2 extends data sets

When a data set is created, Db2 allocates a primary allocation space on a volume
that has available space and that is specified in the Db2 storage group. Any
extension to a data set always gets a secondary allocation space.

If new extensions reach the end of the volume, Db2 accesses all candidate volumes
from the Db2 storage group and issues the Access Method Services command
ALTER ADDVOLUMES to add these volumes to the integrated catalog facility
(ICF) catalog as candidate volumes for the data set. Db2 then makes a request to
allocate a secondary extent on any one of the candidate volumes that has space
available. After the allocation is successful, Db2 issues the command ALTER
REMOVEVOLUMES to remove all candidate volumes from the ICF catalog for the
data set.

Db2 extends data sets when either of the following conditions occurs:
v The requested space exceeds the remaining space in the data set.
v 10% of the secondary allocation space (but not over 10 allocation units, based on
either tracks or cylinders) exceeds the remaining space.

If Db2 fails to extend a data set with a secondary allocation space because of
insufficient available space on any single candidate volume of a Db2 storage
group, Db2 tries again to extend with the requested space if the requested space is
smaller than the secondary allocation space. Typically, Db2 requests only one
additional page. In this case, a small amount of two units (tracks or cylinders, as
determined by DFSMS based on the SECQTY value) is allocated. To monitor data
set extension activity, use IFCID 258 in statistics class 3.

26 Administration Guide
 Nonpartitioned spaces

For a nonpartitioned table space or a nonpartitioned index space, Db2 defines the
first piece of the page set starting with a primary allocation space, and extends that
piece by using secondary allocation spaces. When the end of the first piece is
reached, Db2 defines a new piece (which is a new data set) and extends that new
piece starting with a primary allocation space.

Exception: When a table space requires a new piece, the primary allocation
quantity of the new piece is determined as follows:
v If the value of subsystem parameter MGEXTSZ is NO, the primary quantity is
the PRIQTY value for the table space. If PRIQTY is not specified, the default for
PRIQTY is used.
v If the value of MGEXTSZ is YES, the primary quantity is the maximum of the
following values:
– The quantity that is calculated through sliding scale methodology
– The primary quantity from rule 1
– The specified SECQTY value

Partitioned spaces
For a partitioned table space or a partitioned index space, each partition is a data
set. Therefore, Db2 defines each partition with the primary allocation space and
extends each partition's data set by using a secondary allocation space, as needed.

Extension failures

If a data set uses all possible extents, Db2 cannot extend that data set. For a
partitioned page set, the extension fails only for the particular partition that Db2 is
trying to extend. For nonpartitioned page sets, Db2 cannot extend to a new data
set piece, which means that the extension for the entire page set fails.

To avoid extension failures, allow Db2 to use the default value for primary space
allocation and to use a sliding scale algorithm for secondary extent allocations.

Db2 might not be able to extend a data set if the data set is in an SMS data class
that constrains the number of extents to less than the number that is required to
reach full size. To prevent extension failures, make sure that the SMS data class
setting for the number of allowed extents is large enough to accommodate 128 GB
and 256 GB data sets.
Related concepts:
Primary space allocation
Secondary space allocation
Related tasks:
Avoiding excessively small extents (Db2 Performance)

Db2 space allocation

Primary and secondary space allocation sizes are the main factors that affect the
amount of disk space that Db2 uses.

Chapter 2. Implementing your database design 27

 In general, the primary space allocation must be large enough to handle the
storage needs that you anticipate. The secondary space allocation must be large
enough for your applications to continue operating until the data set is
reorganized.

If the secondary space allocation is too small, the data set might have to be
extended more times to satisfy those activities that need a large space.

Primary space allocation

Db2 uses default values for primary space allocation of Db2-managed data sets.

The default values are:

v 1 cylinder (720 KB) for non-LOB table spaces
v 10 cylinders for LOB table spaces
v 1 cylinder for indexes

To indicate that you want Db2 to use the default values for primary space
allocation of table spaces and indexes, specify a value of 0 for the following
parameters on installation panel DSNTIP7, as shown in the following table.
Table 2. DSNTIP7 parameter values for managing space allocations
Installation panel DSNTIP7 parameter Recommended value
TABLE SPACE ALLOCATION 0
INDEX SPACE ALLOCATION 0

Thereafter:
v On CREATE TABLESPACE and CREATE INDEX statements, do not specify a
value for the PRIQTY option.
v On ALTER TABLESPACE and ALTER INDEX statements, specify a value of -1
for the PRIQTY option.

Primary space allocation quantities do not exceed DSSIZE or PIECESIZE clause

values.

Exception: If the OPTIMIZE EXTENT SIZING parameter (MGEXTSZ) on

installation panel DSNTIP7 is set to YES and the table space or index space has a
SECQTY setting of greater than zero, the primary space allocation of each
subsequent data set is the larger of the SECQTY setting and the value that is
derived from a sliding scale algorithm. See Secondary space allocation for
information about the sliding scale algorithm.

For those situations in which the default primary quantity value is not large
enough, you can specify a larger value for the PRIQTY option when creating or
altering table spaces and indexes. Db2 always uses a PRIQTY value if one is
explicitly specified.

If you want to prevent Db2 from using the default value for primary space
allocation of table spaces and indexes, specify a non-zero value for the TABLE
SPACE ALLOCATION and INDEX SPACE ALLOCATION parameters on
installation panel DSNTIP7.

28 Administration Guide
Secondary space allocation
Db2 can calculate the amount of space to allocate to secondary extents by using a
sliding scale algorithm.

The first 127 extents are allocated in increasing size, and the remaining extents are
allocated based on the initial size of the data set:
v For 32 GB, 64 GB, 128 GB, and 256 GB data sets, each extent is allocated with a
size of 559 cylinders.
v For data sets that range in size from less than 1 GB to 16 GB, each extent is
allocated with a size of 127 cylinders.

This approach has several advantages:

v It minimizes the potential for wasted space by increasing the size of secondary
extents slowly at first.
v It prevents very large allocations for the remaining extents, which would likely
cause fragmentation.
v It does not require users to specify SECQTY values when creating and altering
table spaces and index spaces.
v It is theoretically possible to reach maximum data set size without running out
of secondary extents.

In the case of severe DASD fragmentation, it can take up to 5 extents to satisfy a

logical extent request. In this situation, the data set does not reach the theoretical
data set size.

If you installed Db2 on the operating system z/OS Version 1 Release 7, or later,
you can modify the Extent Constraint Removal option. By setting the Extent
Constraint Removal option to YES in the SMS data class, the maximum number of
extents can be up to 7257. However, the limits of 123 extents per volume and a
maximum volume count of 59 per data set remain valid. For more information, see
Using VSAM extent constraint removal (DFSMS Using the New Functions).

Maximum allocation is shown in the following table. This table assumes that the
initial extent that is allocated is one cylinder in size.
Table 3. Maximum allocation of secondary extents
Maximum data set size, in Maximum allocation, in Extents required to reach
GB cylinders full size
1 127 54
2 127 75
4 127 107
8 127 154
16 127 246
32 559 172
64 559 255
128 559 414
256 559 740

Db2 uses a sliding scale for secondary extent allocations of table spaces
and indexes when:

Chapter 2. Implementing your database design 29

 v You do not specify a value for the SECQTY option of a CREATE TABLESPACE
or CREATE INDEX statement
v You specify a value of -1 for the SECQTY option of an ALTER TABLESPACE or
ALTER INDEX statement.

Otherwise, Db2 always uses a SECQTY value for secondary extent allocations, if
one is explicitly specified.

Exception: For those situations in which the calculated secondary quantity value
is not large enough, you can specify a larger value for the SECQTY option when
creating or altering table spaces and indexes. However, in the case where the
OPTIMIZE EXTENT SIZING parameter is set to YES and you specify a value for
the SECQTY option, Db2 uses the value of the SECQTY option to allocate a
secondary extent only if the value of the option is larger than the value that is
derived from the sliding scale algorithm. The calculation that Db2 uses to make
this determination is:
Actual secondary extent size = max ( min ( ss_extent, MaxAlloc ), SECQTY )

In this calculation, ss_extent represents the value that is derived from the sliding
scale algorithm, and MaxAlloc is either 127 or 559 cylinders, depending on the
maximum potential data set size. This approach allows you to reach the maximum
page set size faster. Otherwise, Db2 uses the value that is derived from the sliding
scale algorithm.

If you do not provide a value for the secondary space allocation quantity, Db2
calculates a secondary space allocation value equal to 10% of the primary space
allocation value and subject to the following conditions:
v The value cannot be less than 127 cylinders for data sets that range in initial size
from less than 1 GB to 16 GB, and cannot be less than 559 cylinders for 32 GB
and 64 GB data sets.
v The value cannot be more than the value that is derived from the sliding scale
algorithm.

The calculation that Db2 uses for the secondary space allocation value is:
Actual secondary extent size = max ( 0.1
× PRIQTY, min ( ss_extent, MaxAlloc ) )

In this calculation, ss_extent represents the value that is derived from the sliding
scale algorithm, and MaxAlloc is either 127 or 559 cylinders, depending on the
maximum potential data set size.

Secondary space allocation quantities do not exceed DSSIZE or PIECESIZE clause

values.

If you do not want Db2 to extend a data set, you can specify a value of 0 for the
SECQTY option. Specifying 0 is a useful way to prevent DSNDB07 work files from
growing out of proportion.

If you want to prevent Db2 from using the sliding scale for secondary extent
allocations of table spaces and indexes, specify a value of NO for the OPTIMIZE
EXTENT SIZING parameter on installation panel DSNTIP7.
Related concepts:
How Db2 extends data sets

30 Administration Guide
 Example of primary and secondary space allocation
Primary and secondary space allocation quantities are affected by a CREATE
statement and two subsequent ALTER statements.

This example assumes a maximum data set size of less than 32 GB, and the
following parameter values on installation panel DSNTIP7:
v TABLE SPACE ALLOCATION = 0
v INDEX SPACE ALLOCATION = 0
v OPTIMIZE EXTENT SIZING = YES
Table 4. Example of specified and actual space allocations
Actual
Actual primary secondary
Specified quantity Specified quantity
Action PRIQTY allocated SECQTY allocated
CREATE 100 KB 100 KB 1000 KB 2 cylinders
TABLESPACE
ALTER TABLESPACE -1 1 cylinder 2000 KB 3 cylinders
ALTER TABLESPACE 1 cylinder -1 1 cylinder

Managing Db2 data sets with DFSMShsm

You can use the Hierarchical Storage Management functional component
(DFSMShsm) of DFSMS to manage space and data availability among the storage
devices in your system.

You can also use DFSMShsm to move data sets that have not been recently used to
slower, less expensive storage devices. Moving the data sets helps to ensure that
disk space is managed efficiently.
Related concepts:
Managing your own data sets
Advantages of storage groups

Migrating to DFSMShsm
If you decide to use DFSMShsm for your Db2 data sets, you should develop a
migration plan with your system administrator.

About this task

With user-managed data sets, you can specify DFSMS classes on the Access
Method Services DEFINE command. With Db2 storage groups, you can specify
SMS classes in the CREATE STOGROUP statement, develop automatic class
selection routines, or both.

Restriction: If you use the BACKUP SYSTEM utility to create system-level

backups, do not use DFSMShsm to migrate Db2 table spaces and indexes. You can
use DFSMShsm to migrate or recall archive log data sets.

Procedure

To enable DFSMS to manage your Db2 storage groups:

1. Issue either a CREATE STOGROUP or ALTER STOGROUP SQL statement.

Chapter 2. Implementing your database design 31

 2. Specify one or more asterisks as volume-ID in the VOLUMES option, and
optionally, specify the SMS class options.
The following example causes all database data set allocations and definitions
to use nonspecific selection through DFSMS filtering services.

CREATE STOGROUP G202

VOLUMES (’*’)
VCAT vcat name
DATACLAS dataclass name
MGMTCLAS management class name
STORCLAS storage class name;

3. Define the SMS classes for your table space data sets and index data sets.
4. Code the SMS automatic class selection (ACS) routines to assign indexes to one
SMS storage class and to assign table spaces to a different SMS storage class.

Example

The following example shows how to create a storage group in a SMS

managed subsystem:
CREATE STOGROUP SGOS0101
VCAT REGSMS
DATACLAS REGSMSDC
MGMTCLAS REGSMSMC
STORCLAS REGSMSSC;

Related tasks:
Letting SMS manage your Db2 storage groups
Enabling SMS to control Db2 storage groups

How archive logs are recalled by DFSMShsm

DFSMShsm can automatically migrate and recall archive log data sets and image
copy data sets. If Db2 needs an archive log data set or an image copy data set that
DFSMShsm has migrated, a recall begins automatically and Db2 waits for the recall
to complete before continuing.

For processes that read more than one archive log data set, such as the RECOVER
utility, Db2 anticipates a DFSMShsm recall of migrated archive log data sets. When
a Db2 process finishes reading one data set, it can continue with the next data set
without delay, because the data set might already have been recalled by
DFSMShsm.

If you accept the default value YES for the RECALL DATABASE parameter on the
Operator Functions panel (DSNTIPO), Db2 also recalls migrated table spaces and
index spaces. At data set open time, Db2 waits for DFSMShsm to perform the
recall. You can specify the amount of time Db2 waits while the recall is being
performed with the RECALL DELAY parameter, which is also on panel DSNTIPO.
If RECALL DELAY is set to zero, Db2 does not wait, and the recall is performed
asynchronously.

You can use System Managed Storage (SMS) to archive Db2 subsystem data sets,
including the Db2 catalog, Db2 directory, active logs, and work file databases

32 Administration Guide
(DSNDB07 in a non-data-sharing environment). However, before starting Db2, you
should recall these data sets by using DFSMShsm. Alternatively, you can avoid
migrating these data sets by assigning them to a management class that prevents
migration.

If a volume has a STOGROUP specified, you must recall that volume only to
volumes of the same device type as others in the STOGROUP.

In addition, you must coordinate the DFSMShsm automatic purge period, the Db2
log retention period, and MODIFY utility usage. Otherwise, the image copies or
logs that you might need during a recovery could already have been deleted.

The RECOVER utility and the DFSMSdss RESTORE command

The RECOVER utility can run the DFSMSdss RESTORE command, which generally
uses extensions that are larger than the primary and secondary space allocation
values of a data set.

The RECOVER utility runs this command if the point of recovery is defined by an
image copy that was taken by using the CONCURRENT option of the COPY
utility.

When the RECOVER utility chooses a system-level backup for object-level

recovery, DFSMShsm is used to restore the data sets from the system-level backup.

The DFSMSdss RESTORE command extends a data set differently than Db2, so
after this command runs, you must alter the page set to contain extents that are
defined by Db2.
Related tasks:
Altering a page set to contain Db2-defined extents
Related reference:
RECOVER (Db2 Utilities)

Considerations for using the BACKUP SYSTEM utility and

DFSMShsm
If you plan to use the BACKUP SYSTEM utility to take volume-level copies of data
and logs, all of the Db2 data sets must reside on volumes that are managed by
DFSMSsms. You can take volume-level copies of the data and logs of a data
sharing group or a non-data-sharing Db2 subsystem.

Restriction: If you use the BACKUP SYSTEM utility to create system-level

backups, do not use DFSMShsm to migrate Db2 table spaces and indexes.

The BACKUP SYSTEM utility uses copy pools. A copy pool is a named set of
storage groups that can be backed up and restored as a unit; DFSMShsm processes
the storage groups collectively for fast replication. Each Db2 subsystem has up to
two copy pools, one for databases and one for logs.

Copy pools are also referred to as source storage groups. Each source storage
group contains the name of an associated copy pool backup storage group, which
contains eligible volumes for the backups. The storage administrator must define
both the source and target storage groups. Use the following Db2 naming
convention for a copy pool:
DSN$locn-name$cp-type

Chapter 2. Implementing your database design 33

 The variables that are used in this naming convention are described in the
following table.
Table 5. Naming convention variables for a copy pool
Variable Meaning
DSN The unique Db2 product identifier
$ A delimiter. You must use the dollar sign ($) character.
locn-name The Db2 location name
cp-type The copy pool type. Use DB for database and LG for log.

The Db2 BACKUP SYSTEM and RESTORE SYSTEM utilities invoke DFSMShsm to
back up and restore the copy pools. DFSMShsm interacts with DFSMSsms to
determine the volumes that belong to a given copy pool so that the volume-level
backup and restore functions can be invoked.

Tip: The BACKUP SYSTEM utility can dump the copy pools to tape automatically
if you specify the options that enable that function.
Related tasks:
Managing DFSMShsm default settings when using the BACKUP SYSTEM,
RESTORE SYSTEM, and RECOVER utilities
Related reference:
BACKUP SYSTEM (Db2 Utilities)
RESTORE SYSTEM (Db2 Utilities)

Incremental system-level backups

You can use the BACKUP SYSTEM utility to take incremental FlashCopy® backups
of the data of a non-data sharing Db2 subsystem or a Db2 data sharing group. All
of the Db2 data sets must reside on volumes that are managed by DFSMSsms.

| An incremental FlashCopy relationship is established for each source volume in the

| copy pool with corresponding target volumes. Multiple incremental FlashCopy
| backup versions are supported.

The following BACKUP SYSTEM utility keywords support this feature:

ESTABLISH FCINCREMENTAL
Specifies that a persistent incremental FlashCopy relationship is to be
established, if none exists for source copy volumes in the database copy
pool. Use this keyword once to establish the persistent incremental
FlashCopy relationships. Subsequent invocations of BACKUP SYSTEM
(without this keyword) will automatically process the persistent
incremental FlashCopy relationship.
END FCINCREMENTAL
Specifies that a last incremental FlashCopy backup be taken and for the
persistent incremental FlashCopy relationship to be withdrawn for all of
the volumes in the database copy pool. Use this keyword only if you do
not need additional incremental FlashCopy backups of the database copy
pool.

The first time that you use the ESTABLISH FCINCREMENTAL keyword in an
invocation of the BACKUP SYSTEM utility the persistent incremental FlashCopy

34 Administration Guide
 relationship is established. The incremental FlashCopy relationship exists until you
withdraw it by specifying the END FCINCREMENTAL keyword in the utility
control statement.

For the first invocation of BACKUP SYSTEM that specifies the ESTABLISH
FCINCREMENTAL keyword, all of the tracks of each source volume are copied to
their corresponding target volumes. For subsequent BACKUP SYSTEM requests,
only the changed tracks are copied to the target volumes.

If you keep more than one DASD FlashCopy version of the database copy pool,
you need to create full-copy backups for versions other than the incremental
version.

For example, you decide to keep two DASD FlashCopy versions of your database
copy pool. You invoke the BACKUP SYSTEM utility with the ESTABLISH
FCINCREMENTAL keyword. A full-copy of each volume is created, because the
incremental FlashCopy relationship is established for the first time. You invoke the
BACKUP SYSTEM utility the next day. This request creates the second version of
the backup. This version is a full-copy backup, because the incremental FlashCopy
relationship is established with the target volumes in the first version. The
following day you run the BACKUP SYSTEM utility again, but without the
ESTABLISH FCINCREMENTAL keyword. The incremental version is the oldest
version, so the incremental version is used for the FlashCopy backup. This time
only the tracks that have changed are copied. The result is a complete copy of the
source volume.

| DFSMShsm supports multiple versions of FlashCopy backups for a copy pool.

Related reference:
BACKUP SYSTEM (Db2 Utilities)

Managing your own data sets

You might choose to manage your own VSAM data sets for several reasons.

For example, consider the following reasons:

v You have a large nonpartitioned table space on several data sets. If you manage
your own data sets, you can better control the placement of individual data sets
on the volumes (although you can keep a similar type of control by using
single-volume Db2 storage groups).
v You want to prevent deleting a data set within a specified time period, by using
the TO and FOR options of the Access Method Services DEFINE and ALTER
commands. You can create and manage the data set yourself, or you can create
the data set with Db2 and use the ALTER command of Access Method Services
to change the TO and FOR options.
v You are concerned about recovering dropped table spaces. Your own data set is
not automatically deleted when a table space is dropped, making it easier to
reclaim the data.

Tip: As table spaces and index spaces expand, you might need to provide
additional data sets. To take advantage of parallel I/O streams when doing certain
read-only queries, consider spreading large table spaces over different disk
volumes that are attached on separate channel paths.
Related concepts:
Advantages of storage groups

Chapter 2. Implementing your database design 35

 Related information:
Managing Db2 data sets with DFSMShsm

Defining data sets

Db2 checks whether you have defined your data sets correctly.

About this task

You must define a data set for each of the following items:
v A simple or segmented table space
v A partition of a partitioned table space
v A partition of a partitioned index

You must define the data sets before you can issue the CREATE TABLESPACE,
CREATE INDEX, or ALTER TABLE ADD PARTITION SQL statements.

If you create a partitioned table space, you must create a separate data set for each
partition, or you must allocate space for each partition by using the PARTITION
option of the NUMPARTS clause in the CREATE TABLESPACE statement.

If you create a partitioned secondary index, you must create a separate data set for
each partition. Alternatively, for Db2 to manage your data sets, you must allocate
space for each partition by using the PARTITIONED option of the CREATE INDEX
statement.

If you create a partitioning index that is partitioned, you must create a separate
data set for each partition. Alternatively, for Db2 to manage your data sets, you
must allocate space for each partition by using the PARTITIONED option or the
PARTITION ENDING AT clause of the CREATE INDEX statement in the case of
index-controlled partitioning.

Procedure

To define and manage VSAM data sets yourself:

1. Issue a DEFINE CLUSTER statement to create the data set.
2. Give each data set a name that complies with the following format:
catname.DSNDBx.dbname.psname.y0001.znnn
3. In the DEFINE CLUSTER statement, specify the size of the primary and
secondary extents of the VSAM cluster. If you specify zero for the secondary
extent size, data set extension does not occur.
4. Specify that the data sets be LINEAR. Do not use RECORDSIZE; this attribute
is invalid. Use the CONTROLINTERVALSIZE attribute if you are using
variable-sized control intervals.
5. Specify the REUSE option. You must define the data set as REUSE before
running the DSN1COPY utility.
6. Use SHAREOPTIONS(3,3).

Example

The following example code shows an example of the DEFINE CLUSTER

command, which defines a VSAM data set for the SYSUSER table space in
database DSNDB06. Assume that an integrated catalog facility catalog named
DSNCAT is already defined.

36 Administration Guide
DEFINE CLUSTER -
(NAME(DSNCAT.DSNDBC.DSNDB06.SYSUSER.I0001.A001) -
LINEAR -
REUSE -
VOLUMES(DSNV01) -
RECORDS(100 100) -
SHAREOPTIONS(3 3) ) -
DATA -
(NAME(DSNCAT.DSNDBD.DSNDB06.SYSUSER.I0001.A001) -
CATALOG(DSNCAT)

For user-managed data sets, you must pre-allocate shadow data sets prior to
running the following against the table space:
v REORG with SHRLEVEL CHANGE
v REORG with SHRLEVEL REFERENCE
v CHECK INDEX with SHRLEVEL CHANGE
v CHECK DATA with SHRLEVEL CHANGE
v CHECK LOB with SHRLEVEL CHANGE

You can specify the MODEL option for the DEFINE CLUSTER command so that
the shadow is created like the original data set, as shown in the following example
code.
DEFINE CLUSTER -
(NAME(’DSNCAT.DSNDBC.DSNDB06.SYSUSER.x0001.A001’) -
MODEL(’DSNCAT.DSNDBC.DSNDB06.SYSUSER.y0001.A001’)) -
DATA -
(NAME(’DSNCAT.DSNDBD.DSNDB06.SYSUSER.x0001.A001’) -
MODEL(’DSNCAT.DSNDBD.DSNDB06.SYSUSER.y0001.A001’)) -

In the previous example, the instance qualifiers x and y are distinct and are equal
to either I or J. You must determine the correct instance qualifier to use for a
shadow data set by querying the Db2 catalog for the database and table space.

What to do next

The DEFINE CLUSTER command has many optional parameters that do not apply
when Db2 uses the data set. If you use the parameters SPANNED,
EXCEPTIONEXIT, BUFFERSPACE, or WRITECHECK, VSAM applies them to your
data set, but Db2 ignores them when it accesses the data set.

The value of the OWNER parameter for clusters that are defined for storage
groups is the first SYSADM authorization ID specified at installation.

When you drop indexes or table spaces for which you defined the data sets, you
must delete the data sets unless you want to reuse them. To reuse a data set, first
commit, and then create a new table space or index with the same name. When
Db2 uses the new object, it overwrites the old information with new information,
which destroys the old data.

Likewise, if you delete data sets, you must drop the corresponding table spaces
and indexes; Db2 does not drop these objects automatically.
Related concepts:
Advantages of storage groups
Related reference:
Data set naming conventions

Chapter 2. Implementing your database design 37

 Data set naming conventions:

When you define a data set, you must give each data set a name that is in the
correct format.

The correct format for the name of a data set is as follows:

catname.DSNDBx.dbname.psname.y0001.znnn
catalog-name
The catalog name or alias.
The data sets are linear VSAM data sets cataloged in the integrated catalog
facility catalog that catalog-name identifies. For more information about
catalog-name values, see Naming conventions (Db2 SQL).
Use the same name or alias here as in the USING VCAT clause of the
CREATE TABLESPACE and CREATE INDEX statements.
x C (for VSAM clusters) or D (for VSAM data components).
dbname Db2 database name. If the data set is for a table space, dbname must be the
name given in the CREATE TABLESPACE statement. If the data set is for
an index, dbname must be the name of the database containing the base
table. If you are using the default database, dbname must be DSNDB04.
psname Table space name or index name. This name must be unique within the
database.
You use this name on the CREATE TABLESPACE or CREATE INDEX
statement. (You can use a name longer than eight characters on the
CREATE INDEX statement, but the first eight characters of that name must
be the same as in the psname for that data set.)
y0001 Instance qualifier for the data set.
If you plan to run any of the following utilities, define two data sets, one
data set with a value of I for y, and one with a value of J for y:
v REORG with SHRLEVEL CHANGE or SHRLEVEL REFERENCE
v CHECK DATA with SHRLEVEL REFERENCE
v CHECK INDEX with SHRLEVEL REFERENCE
v CHECK LOB with SHRLEVEL REFERENCE
Otherwise, define one data set for the table space or index with a value of
I for y.
znnn Data set number. The first digit z of the data set number is represented by
the letter A, B, C, D, or E, which corresponds to the value 0, 1, 2, 3, or 4 as
the first digit of the partition number.
For partitioned table spaces, if the partition number is less than 1000, the
data set number is Annn in the data set name (for example, A999 represents
partition 999). For partitions 1000 to 1999, the data set number is Bnnn (for
example, B000 represents partition 1000). For partitions 2000 to 2999, the
data set number is Cnnn. For partitions 3000 to 3999, the data set number
is Dnnn. For partitions 4000 up to a maximum of 4096, the data set number
is Ennn.
The naming convention for data sets that you define for a partitioned
index is the same as the naming convention for other partitioned objects.
For simple or segmented table spaces, the number is 001 (preceded by A)
for the first data set. When little space is available, Db2 issues a warning

38 Administration Guide
 message. If the size of the data set for a simple or a segmented table space
approaches the maximum limit, define another data set with the same
name as the first data set and the number 002. The next data set will be
003, and so on.
You can reach the VSAM extent limit for a data set before you reach the
size limit for a partitioned or a nonpartitioned table space. If this happens,
Db2 does not extend the data set.
Related reference:
CREATE INDEX (Db2 SQL)
CREATE TABLESPACE (Db2 SQL)

Extending user-managed data sets

A user-managed data set is allocated by using only volumes that are defined for
that data set in the ICF catalog. Before the current volume runs out of space, you
must extend the data set.

Procedure

To extend a user-managed data set:

Issue the Access Method Services commands ALTER ADDVOLUMES or ALTER

REMOVEVOLUMES for candidate volumes.

Deleting user-managed data sets

If you manage the data sets of a storage structure yourself, at some point you
might need to delete data sets.

Procedure

To delete a user-managed data set:

Issue the DELETE CLUSTER command for candidate volumes.

Defining index space storage

Generally, the CREATE INDEX statement creates an index space in the same Db2
database that contains the table on which the index is defined, even if you defer
building the index.

Exceptions:
| v If you specify the USING VCAT clause for indexes that are not created on the
| Db2 catalog, you create and manage the data sets yourself.
v If you specify the DEFINE NO clause on a CREATE INDEX statement with the
USING STOGROUP clause, Db2 defers the allocation of the data sets for the
index space.

Procedure

To define your index space storage:

Issue a CREATE INDEX statement.

Optionally, for indexes that are not on Db2 catalog tables, include the USING
clause to specify whether you want Db2-managed or user-managed data sets. For
Db2-managed data sets, you can also specify the primary and secondary space

Chapter 2. Implementing your database design 39

 allocation parameters for the index or partition in the USING clause. If you do not
specify USING, Db2 assigns the index data sets to the default storage groups with
the default space attributes.
For indexes on Db2 catalog tables, Db2 defines and manages the index data sets.
The data sets are defined in the same SMS environment that is used for the catalog
data sets with default space attributes. If you specify the USING clause for indexes
on the catalog, Db2 ignores that clause.

Results

Information about space allocation for the index is stored in the Db2 catalog table
SYSIBM.SYSINDEXPART. Other information about the index is in the
SYSIBM.SYSINDEXES table.
Related reference:
CREATE INDEX (Db2 SQL)

Creating EA-enabled table spaces and index spaces

DFSMS has an extended-addressability function, which is necessary to create data
sets that are larger than 4 GB. Therefore, the term for page sets that are enabled for
extended addressability is EA-enabled.

About this task

You must use EA-enabled table spaces or index spaces if you specify a DSSIZE that
is larger than 4 GB in the CREATE TABLESPACE statement.

Procedure

To create EA-enabled page sets:

1. Use SMS to manage the data sets that are associated with the EA-enabled page
sets.
2. Associate the data sets with a data class (an SMS construct) that specifies the
extended format and extended addressability options.
To make this association between data sets and the data class, use an automatic
class selection (ACS) routine to assign the Db2 data sets to the relevant SMS
data class. The ACS routine does the assignment based on the data set name.
No performance penalty occurs for having non-EA-enabled Db2 page sets
assigned to this data class, too, if you would rather not have two separate data
classes for Db2.
For user-managed data sets, you can use ACS routines or specify the
appropriate data class on the DEFINE CLUSTER command when you create
the data set.
3. Create the partitioned or LOB table space with a DSSIZE of 8 GB or greater.
The partitioning index for the partitioned table space takes on the EA-enabled
attribute from its associated table space.
After a page set is created, you cannot use the ALTER TABLESPACE statement
to change the DSSIZE. You must drop and re-create the table space.
Also, you cannot change the data sets of the page set to turn off the extended
addressability or extended format attributes. If someone modifies the data class
to turn off the extended addressability or extended format attributes, Db2
issues an error message the next time that it opens the page set.

40 Administration Guide
 Creating partitioned table spaces that are enabled for EA

The following CREATE TABLESPACE statement creates an EA-enabled table space,

SALESHX. Assume that a large query application uses this table space to record
historical sales data for marketing statistics. The first USING clause establishes the
MYSTOGRP storage group and space allocations for all partitions:
CREATE TABLESPACE SALESHX
IN MYDB
USING STOGROUP MYSTOGRP
PRIQTY 4000
SECQTY 130
ERASE NO
DSSIZE 16G
NUMPARTS 48
(PARTITION 46
COMPRESS YES,
PARTITION 47
COMPRESS YES,
PARTITION 48
COMPRESS YES)
LOCKSIZE PAGE
BUFFERPOOL BP1
CLOSE NO;
Related tasks:
Creating table spaces explicitly

Implementing Db2 table spaces

Db2 table spaces are storage structures that store one or more data sets, which
store one or more tables.

Introductory concepts
Db2 table spaces (Introduction to Db2 for z/OS)

You can let Db2 create table spaces for your tables, or you can create them
explicitly before you create the tables. It is best to create partition-by-growth or
partition-by-range universal table spaces in most cases. Other table space types are
deprecated. That is, they are supported in Db2 11, but support might be removed
in the future.
Related tasks:
Converting table spaces to use table-controlled partitioning
Related reference:
CREATE TABLE (Db2 SQL)
CREATE TABLESPACE (Db2 SQL)

Table space types and characteristics in Db2 for z/OS

Db2 supports several different types of table spaces. The partitioning method and
segmented organization are among the main characteristics that define the table
space type.

Universal table spaces

Universal table spaces (UTS) combine the benefits of data partitions and segmented
organization. Each UTS table space always contains only a single table.

Chapter 2. Implementing your database design 41

 Universal table spaces offer the following advantages, when compared to the
deprecated non-UTS table space types:
v A choice of partitioning methods:
– Partitions based on ranges of data values, with Partition-by-range table spaces
– Partitions based on data growth and automatically managed by Db2, with
Partition-by-growth table spaces
v Improved space management for varying-length rows because a segmented
space-map page has more information about free space than a partitioned
space-map page
v Improved mass delete performance because mass delete in a segmented table
space organization tends to be faster than in non-segmented table space
organizations
v Table scans that are localized to segments
v Immediate reuse of all or most of the segments of a table after the table is
dropped or mass deleted

Non-UTS table space types

| Deprecated function: Non-UTS table spaces for base tables are deprecated and
| likely to be unsupported in the future.

Partitioned (non-UTS) table spaces use partitions based on ranges of data values,
like partition-by-range table spaces, but they do not use segmented organization.
Segmented (non-UTS) table spaces store the data from separate tables in different
segments, but they cannot be partitioned. Simple table spaces are not partitioned
or segmented.

Tip: For best results, convert all simple and other non-UTS table spaces to UTS
table space types as soon as possible. For more information about altering table
spaces, see Altering table spaces and ALTER TABLESPACE (Db2 SQL).

Db2 11 supports the creation of partitioned (non-UTS) and segmented (non-UTS)

table spaces but they are deprecated. Existing simple table spaces remain
supported in Db2 11. However, the creation of new simple table spaces is not
supported.

Comparison of table space types

The following table compares the characteristics of the various table space types
that Db2 for z/OS supports.
Table 6. Comparison of table space types
Type Segmented? Partitioned? Remarks
Partition-by-range Yes Yes, based on data value
table space ranges
Partition-by-growth Yes Yes, based on data
table space growth
LOB table space No No For auxiliary tables that
contain the data for
LOB columns.
XML table space Yes Yes, based on the UTS table spaces that
partitioning method of are created implicitly
the base table. for XML data.

42 Administration Guide
Table 6. Comparison of table space types (continued)
Type Segmented? Partitioned? Remarks
Partitioned (non-UTS) No Yes, based on data value This type is deprecated.
table space ranges
Segmented (non-UTS) Yes No This type is deprecated.
table space
Simple table space No No This type is
deprecated.1

Notes:
1. Db2 11 does not support creating simple table spaces. Existing simple table
spaces remain supported, but they are likely to be unsupported in the future.

Determining the table space type

The TYPE column of the SYSIBM.SYSTABLESPACE catalog table indicates the type
of each table space.
blank The table space was created without the LOB or MEMBER CLUSTER
options. If the DSSIZE column is zero, the table space is not greater than 64
gigabytes.
G Partition-by-growth table space.
L The table space can be greater than 64 gigabytes.
O The table space was defined with the LOB option (the table space is a LOB
table space).
P Implicit table space created for XML columns.
R Partition-by-range table space.
Related tasks:
Converting table spaces to use table-controlled partitioning
Related information:

Conversion from index-controlled partitioning to Universal Table Space (UTS)

Partition-by-range table spaces

A partition-by-range table space is a universal table space (UTS) that has partitions
based on ranges of data values. It holds data pages for a single table, and has
segmented space management capabilities within each partition.

In a partition-by-range table space, the partitions are based on the boundary values
that are defined for specific data columns. For example, the following figure
illustrates the data pages for a table with two partitions.

Partition 1
Key range A-L

Partition 2
Key range M-Z

Figure 13. Pages in a range-partitioned table space

Utilities and SQL statements can run concurrently on each partition. For example, a
utility job can work on part of the data while allowing other applications to
concurrently access data on other partitions. In that way, several concurrent utility
jobs can, for example, load all partitions of a table space concurrently. Because you

Chapter 2. Implementing your database design 43

 can work on part of your data, some of your operations on the data might require
less time. Also, you can use separate jobs for mass update, delete, or insert
operations instead of using one large job; each smaller job can work on a different
partition. Separating the large job into several smaller jobs that run concurrently
can reduce the elapsed time for the whole task.

You can create an index of any type on a table in a partition-by-range table space.

| Tip: Partition-by-range table spaces are the suggested alternative for partitioned
| (non-UTS) table spaces, which are deprecated.

| You can explicitly create partition-by-range table spaces by issuing CREATE

| TABLESPACE statements, or Db2 can create them for you, when you issue
| CREATE TABLE statements. For instructions, see Creating partition-by-range table
| spaces.
Related tasks:
Converting table spaces to use table-controlled partitioning
Creating partition-by-range table spaces
Creating table spaces explicitly
Related reference:
CREATE TABLESPACE (Db2 SQL)
CREATE TABLE (Db2 SQL)
Related information:

Conversion from index-controlled partitioning to Universal Table Space (UTS)

Partition-by-growth table spaces

A partition-by-growth table space is a universal table space (UTS) that has partitions
that Db2 manages automatically based on data growth. It holds data pages for
only a single table, and has segmented space management capabilities within each
partition.

Db2 manages partition-by-growth table spaces automatically as data grows, by

automatically adding a new partition when more space is needed to satisfy an
insert operation.

Partition-by-growth table spaces are best used when a table is expected to exceed
64 GB, or when a table does not have a suitable partitioning key.
Partition-by-growth table spaces can grow up to 128 TB, depending on the buffer
pool page size used, and the MAXPARTITIONS and DSSIZE values specified when
the table space is created.

The partitioned structure supports partition-level utility operations and parallelism

capabilities. A partition-by-growth table space also has segmented organization and
segmented space management capabilities within each partition. The segmented
structure provides better space management and mass delete capabilities.

| Tip: Partition-by-growth table spaces are the suggested alternative for single-table
| Db2-managed segmented (non-UTS) table spaces, which are deprecated.

You can explicitly create partition-by-growth table spaces by issuing CREATE

TABLESPACE statements, or Db2 can create them for you when you issue CREATE
TABLE statements. For instructions, see Creating partition-by-growth table spaces

44 Administration Guide
Restrictions for partition-by-growth table spaces:

The following restrictions apply to partition-by-growth table spaces:

v Db2 must manage space for the partitions (it cannot be user-managed) so that
Db2 can create new data sets as partitions become full.
v Partitions cannot be explicitly rotated, or altered. That is, ALTER TABLE
statements that specify ALTER PARTITION or ROTATE PARTITION cannot be
used for partition-by-growth table spaces.
v The PART option of the LOAD utility is not supported.
v The REBALANCE option of the REORG utility is not supported.
v A non-partitioning index (NPI) always uses a 5 byte record identifier (RID).
v Partitioned indexes are not supported.
Related tasks:
Creating table spaces explicitly
Related reference:
ALTER TABLE (Db2 SQL)
ALTER TABLESPACE (Db2 SQL)
CREATE TABLESPACE (Db2 SQL)
CREATE TABLE (Db2 SQL)

LOB table spaces

LOB table spaces (also known as large object or auxiliary table spaces) hold LOB
data, such as graphics, video, or large text strings. If your data does not fit entirely
within a data page, you can define one or more columns as LOB columns.

LOB objects can do more than store large object data. If you define your LOB
columns for infrequently accessed data, a table space scan on the remaining data in
the base table is potentially faster because the scan generally includes fewer pages.

A LOB table space always has a direct relationship with the table space that
contains the logical LOB column values. The table space that contains the table
with the LOB columns is, in this context, the base table space. LOB data is logically
associated with the base table, but it is physically stored in an auxiliary table that
resides in a LOB table space. Only one auxiliary table can exist in a large object
table space. A LOB value can span several pages. However, only one LOB value is
stored per page.

You must have a LOB table space for each LOB column that exists in a table. For
example, if your table has LOB columns for both resumes and photographs, you
need one LOB table space (and one auxiliary table) for each of those columns. If
the base table space is a partitioned table space, you need one LOB table space for
each LOB in each partition.

If the base table space is not a partitioned table space, each LOB table space is
associated with one LOB column in the base table. If the base table space is a
partitioned table space, each partition of the base table space is associated with a
LOB table space. Therefore, if the base table space is a partitioned table space, you
can store more LOB data for each LOB column.

The following table shows the approximate amount of LOB data that you can store
for a LOB column in each of the different types of base table spaces.

Chapter 2. Implementing your database design 45

 Table 7. Base table space types and approximate maximum size of LOB data for a LOB
column
Maximum (approximate) LOB data for
Base table space type each column
Segmented 16 TB
Partitioned, with NUMPARTS up to 64 1000 TB
Partitioned with DSSIZE, NUMPARTS up to 254 4000 TB
Partitioned with DSSIZE, NUMPARTS up to 4096 64000 TB

Recommendations:
v Consider defining long string columns as LOB columns when a row does not fit
in a 32 KB page. Use the following guidelines to determine if a LOB column is a
good choice:
– Defining a long string column as a LOB column might be better if the
following conditions are true:
- Table space scans are normally run on the table.
- The long string column is not referenced often.
- Removing the long string column from the base table is likely to improve
the performance of table space scans.
– LOBs are physically stored in another table space. Therefore, performance for
inserting, updating, and retrieving long strings might be better for non-LOB
strings than for LOB strings.
v Consider specifying a separate buffer pool for large object data.
Related concepts:
Creation of large objects (Introduction to Db2 for z/OS)
Related tasks:
Choosing data page sizes for LOB data (Db2 Performance)
Choosing data page sizes (Db2 Performance)
Related reference:
CREATE AUXILIARY TABLE (Db2 SQL)
CREATE LOB TABLESPACE (Db2 SQL)

XML table spaces

An XML table space is an implicitly created universal (UTS) table space that stores
an XML table.

An XML table space is implicitly created when an XML column is added to a base
table. If the base table is partitioned, one partitioned table space exists for each
XML column of data. An XML table space is always associated with the table space
that contains the logical XML column value. In this context, the table space that
contains the table with the XML column is called the base table space.

| If the base table is partitioned, one partitioned table space exists for each XML
| column of data.
Related concepts:
XML table space implicit creation (Introduction to Db2 for z/OS)
Related tasks:

46 Administration Guide
 Creating table spaces explicitly
Choosing data page sizes (Db2 Performance)

Partitioned (non-UTS) table spaces (deprecated)

A partitioned (non-UTS) table space stores data pages for a single table. Db2 divides
| the table space into partitions. Non-UTS table spaces for base tables are deprecated
| and likely to be unsupported in the future.

| Deprecated function: Non-UTS table spaces for base tables are deprecated and
| likely to be unsupported in the future.

| Tip: Convert existing partitioned (non-UTS) spaces to partition-by-range table

| spaces as soon as possible, as described in Converting partitioned (non-UTS) table
| spaces to partition-by-range universal table spaces.

The partitions are based on the boundary values that are defined for specific data
columns. Utilities and SQL statements can run concurrently on each partition.

In the following figure, each partition contains one part of a table.

Partition 1
Key range A-L

Partition 2
Key range M-Z

Figure 14. Pages in a partitioned table space

Definition of partitioned (non-UTS) table spaces

If you create a table space by specifying NUMPARTS without specifying the

SEGSIZE or MAXPARTITIONS options, Db2 creates a partitioned (non-UTS) table
space. The default table space SEGSIZE value is 32.

Characteristics of partitioned (non-UTS) table spaces

Partitioned (non-UTS) table spaces have the following characteristics:

v You can plan for growth. When you define a partitioned table space, Db2
usually distributes the data evenly across the partitions. Over time, the
distribution of the data might become uneven as inserts and deletes occur.
You can rebalance data among the partitions by redefining partition boundaries
with no impact to availability. You can also add a partition to the table and to
each partitioned index on the table; the new partition becomes available
immediately.
v You can spread a large table over several Db2 storage groups or data sets. The
partitions of the table do not all need to use the same storage group.
v Partitioned table spaces let a utility job work on part of the data while allowing
other applications to concurrently access data on other partitions. In that way,
several concurrent utility jobs can, for example, load all partitions of a table
space concurrently. Because you can work on part of your data, some of your
operations on the data might require less time.
v You can use separate jobs for mass update, delete, or insert operations instead of
using one large job; each smaller job can work on a different partition.

Chapter 2. Implementing your database design 47

 Separating the large job into several smaller jobs that run concurrently can
reduce the elapsed time for the whole task.
If your table space uses nonpartitioned indexes, you might need to modify the
size of data sets in the indexes to avoid I/O contention among concurrently
running jobs. Use the PIECESIZE parameter of the CREATE INDEX or the
ALTER INDEX statement to modify the sizes of the index data sets.
v You can put frequently accessed data on faster devices. Evaluate whether table
partitioning or index partitioning can separate more frequently accessed data
from the remainder of the table. You can put the frequently accessed data in a
partition of its own. You can also use a different device type.
v You can take advantage of parallelism for certain read-only queries. When Db2
determines that processing is likely to be extensive, it can begin parallel
processing of more than one partition at a time. Parallel processing (for
read-only queries) is most efficient when you spread the partitions over different
disk volumes and allow each I/O stream to operate on a separate channel.
Use the Parallel Sysplex® data sharing technology to process a single read-only
query across many Db2 subsystems in a data sharing group. You can optimize
Parallel Sysplex query processing by placing each Db2 subsystem on a separate
central processor complex.
v Partitioned table space scans are sometimes less efficient than table space scans
of segmented table spaces.
v Db2 opens more data sets when you access data in a partitioned table space
than when you access data in other types of table spaces.
v Nonpartitioned indexes and data-partitioned secondary indexes are sometimes a
disadvantage for partitioned tables spaces.
Related concepts:
Db2 data sharing (Introduction to Db2 for z/OS)
Partition-by-growth table spaces
Partition-by-range table spaces
Assignment of table spaces to physical storage (Introduction to Db2 for z/OS)

Related tasks:
Creating table spaces explicitly
Choosing data page sizes (Db2 Performance)
Related reference:
CREATE INDEX (Db2 SQL)
CREATE TABLESPACE (Db2 SQL)

Segmented (non-UTS) table spaces (deprecated)

Segmented non-UTS table spaces can store data for more than one table, especially
for relatively small tables. The pages hold segments, and each segment holds
| records from only one table. Non-UTS table spaces for base tables are deprecated
| and likely to be unsupported in the future.

| Deprecated function: Non-UTS table spaces for base tables are deprecated and
| likely to be unsupported in the future.

Segmented (non-UTS) table spaces hold a maximum of 64 GB of data and can

contain one or more VSAM data sets.

48 Administration Guide
Table space pages can be 4 KB, 8 KB, 16 KB, or 32 KB in size. The pages hold
segments, and each segment holds records from only one table. Each segment
contains the same number of pages, and each table uses only as many segments as
it needs.

When you run a statement that searches all the rows for one table, Db2 does not
need to scan the entire table space. Instead, Db2 can scan only the segments of the
table space that contain that table. The following figure shows a possible
organization of segments in a segmented table space.

Segment
Segment
Segment 4
5 ...
Segment 3
Segment 2 Table B
1 Table A
Table C
Table B
Table A

Figure 15. A possible organization of segments in a segmented table space

When you use an INSERT statement, a MERGE statement, or the LOAD utility to
insert records into a table, records from the same table are stored in different
segments. You can reorganize the table space to move segments of the same table
together.

Definition of a segmented (non-UTS) table space

You define a segmented (non-UTS) table space by using the CREATE

TABLESPACE statement with a SEGSIZE clause. If you use this clause, the value
that you specify represents the number of pages in each segment. The value must
be a multiple of 4 (in the range 4 - 64). The choice of the value depends on the size
of the tables that you store. The following table summarizes the recommendations
for SEGSIZE.
Table 8. Recommendations for SEGSIZE
Number of pages SEGSIZE recommendation
≤ 28 4 to 28
> 28 < 128 pages 32
≥ 128 pages 64

Another clause of the CREATE TABLESPACE statement is LOCKSIZE TABLE. This

clause is valid only for tables that are in segmented table spaces. Db2, therefore,
can acquire locks that lock a single table, rather than the entire table space.

If you want to leave pages of free space in a segmented (non-UTS) table space, you
must have at least one free page in each segment. Specify the FREEPAGE clause
with a value that is less than the SEGSIZE value.

Example: If you use FREEPAGE 30 with SEGSIZE 20, Db2 interprets the value of
FREEPAGE as 19, and you get one free page in each segment.

Restriction: If you are creating a segmented table (non-UTS) space for use by
declared temporary tables, you cannot specify the FREEPAGE or LOCKSIZE
clause.

Chapter 2. Implementing your database design 49

 Characteristics of segmented (non-UTS) table spaces

Segmented table spaces share the following characteristics:

v When Db2 scans all the rows for one table, only the segments that are assigned
to that table need to be scanned. Db2 does not need to scan the entire table
space. Pages of empty segments do not need to be fetched.
v When Db2 locks a table, the lock does not interfere with access to segments of
other tables.
v When Db2 drops a table, its segments become available for reuse immediately
after the drop is committed without waiting for an intervening REORG utility
job.
v When all rows of a table are deleted, all segments except the first segment
become available for reuse immediately after the delete is committed. No
intervening REORG utility job is necessary.
v A mass delete, which is the deletion of all rows of a table, operates much more
quickly and produces much less log information.
v If the table space contains only one table, segmenting it means that the COPY
utility does not copy pages that are empty. The pages might be empty as a result
of a dropped table or a mass delete.
v Some Db2 utilities, such as LOAD with the REPLACE option, RECOVER, and
COPY, operate on only a table space or a partition, not on individual segments.
Therefore, for a segmented table space, you must run these utilities on the entire
table space. For a large table space, you might notice availability problems.
v Maintaining the space map creates some additional overhead.
Related concepts:
Db2 performance management (Introduction to Db2 for z/OS)
Use of free space in data and index storage (Introduction to Db2 for z/OS)
Guidelines for data reorganization (Introduction to Db2 for z/OS)
Ways to improve performance for multiple users (Introduction to Db2 for
z/OS)
Related tasks:
Creating table spaces explicitly
Related reference:
CREATE TABLESPACE (Db2 SQL)

Simple table spaces (deprecated)

| A simple table space is not partitioned or segmented. Simple table spaces are
| deprecated, and the creation of new simple table spaces is not supported in Db2
| 11. However, Db2 can still use existing simple table spaces.

| Deprecated function: Non-UTS table spaces for base tables are deprecated and
| likely to be unsupported in the future.

You cannot create new simple table spaces, but you can alter and update or
retrieve data from existing simple table spaces. If you implicitly create a table
space or explicitly create a table space without specifying the SEGSIZE,
NUMPARTS, or MAXPARTITIONS clauses the result is a segmented table space
instead of a simple table space. By default, the segmented table space has a
SEGSIZE value of 4 and a LOCKSIZE value of ROW.

50 Administration Guide
 Tip: If you have any simple table spaces in your database, alter them to another
type of table space as soon as possible with the ALTER TABLESPACE statement. If
a simple table space contains only one table, alter it to a partition-by-range or
partition-by-growth universal table space.
Related concepts:
Segmented (non-UTS) table spaces (deprecated)
Related tasks:
Dropping and re-creating a table space to change its attributes
Creating table spaces explicitly
Choosing data page sizes (Db2 Performance)
Related reference:
CREATE TABLESPACE (Db2 SQL)
ALTER TABLESPACE (Db2 SQL)

Implicitly defined table spaces

| Db2 implicitly creates a partition-by-growth or partition-by-range table space when
| you issue a CREATE TABLE statement without specifying an existing table space
| name.

When Db2 defines a table space implicitly, it completes the following actions:
v Generates a table space for you.
v Derives a table space name from the name of your table, according to the
following rules:
– The table space name is the same as the table name if the following
conditions apply:
- No other table space or index space in the database already has that name.
- The table name has no more than eight characters.
- The characters are all alphanumeric, and the first character is not a digit.
– If another table space in the database already has the same name as the table,
Db2 assigns a name of the form xxxxnyyy, where xxxx is the first four
characters of the table name, and nyyy is a single digit and three letters that
guarantee uniqueness.
| v If the IN database clause is not specified, Db2 generates a database for you with
| the name DSNxxxxx, where xxxxx is a five-digit number.
v Uses default values for space allocation.
| v Uses the buffer pool for the specified database. However, Db2 chooses a suitable
| buffer pool for the table space from the subsystem parameter values TBSBPOOL,
| TBSBP8K, TBSBP16K, and TBSBP32K if any of the following conditions apply:
| – The IN database-name clause is not specified.
| – The IN database-name clause is specified, and the table record length does not
| fit in the database buffer pool page size.
| – The IN database-name clause is specified, and the table space is for a
| hash-organized table and it has a calculated optimal page size that is not the
| same as the database buffer pool page size.
v Creates the required LOB objects and XML objects.
v Creates unique indexes for UNIQUE constraints.
v Creates the primary key index.
v Creates the ROWID index, if the ROWID column is defined as GENERATED BY
DEFAULT.

Chapter 2. Implementing your database design 51

 Db2 stores the names and attributes of all table spaces in the
SYSIBM.SYSTABLESPACE catalog table, regardless of whether you define the table
spaces explicitly or implicitly.
Related concepts:
Table space types and characteristics in Db2 for z/OS
Related reference:
CREATE TABLE (Db2 SQL)
SYSTABLESPACE catalog table (Db2 SQL)

XML table space implicit creation

When you create an XML column in a table, Db2 implicitly creates an XML table
space. Db2 also creates an XML table to store the XML data, and a node ID.

Each XML column has its own table space. The XML table space does not have
limit keys. The XML data resides in the partition number that corresponds to the
partition number of the base row. Tables that contain XML columns also have the
following implicitly created objects:
v A hidden column to store the document ID.
The document ID is a Db2 generated value that uniquely identifies a row. The
document ID is used to identify documents within the XML table. The document
ID is common for all XML columns, and its value is unique within the table.
v A unique index on the document ID (document ID index).
The document ID index points to the base table RID. If the base table space is
partitioned, the document ID index is a non-partitioned secondary index (NPSI).
v The base table has an indicator column for each XML column containing a null
bit, invalid bit, and a few reserved bytes.

The XML table space inherits several attributes from the base table space, such as
the LOG, CCSID, and LOCKMAX clauses.

If an edit procedure is defined on the base table, the XML table inherits the edit
procedure.

For partition-by-growth table spaces, the DSSIZE value depends on the DSSIZE
value of the base table space. If the DSSIZE value of the base table space is less
than 1 GB, the DSSIZE value of the XML table space is 2G. Otherwise, the XML
table space inherits the DSSIZE value of the base table.

For more information see Storage structure for XML data (Db2 Programming for
XML).
Related reference:
ALTER TABLE (Db2 SQL)
CREATE TABLE (Db2 SQL)

| Creating table spaces explicitly

| Db2 can create table spaces for you. However, you might also create table spaces
| explicitly if you manage your own data sets, among other reasons.

52 Administration Guide
| Before you begin

| For information about how Db2 can create table spaces for you, see Implicitly
| defined table spaces.

| About this task

|
|

| You can create different types of table spaces. Partition-by-range and

| partition-by-growth universal table spaces (UTS) are best in most cases. Other
| types are deprecated. That is, they are supported in Db2 11, but support might be
| removed in the future. For more information about the different types, see Table
| space types and characteristics in Db2 for z/OS.

| Tip: You can alter table spaces after they are created, but the application of some
| statements, such as ALTER TABLESPACE with MAXPARTITIONS, prevent access
| to the database until alterations complete. Consider future growth when you define
| new table spaces.

| Procedure

| To explicitly create a table space:

| Issue a CREATE TABLESPACE statement and specify the type of table space to
| create and other attributes.
| 1. Specify the table space type to create. For instructions for creating each
| recommended types, see Creating partition-by-range table spaces and Creating
| partition-by-growth table spaces. The following table summarizes the table
| space attributes that determine the type of the resulting table space:
| Table 9. Table space types and related clauses
| Table space type to create Clauses to specify
| Partition-by-growth Any of the following combinations:
| v MAXPARTITIONS and NUMPARTS
| v MAXPARTITIONS and SEGSIZE n1
| v MAXPARTITIONS
| Partition-by-range NUMPARTS and SEGSIZE n1
2
| Segmented (non-UTS) One of the following combinations:
| v SEGSIZE n1
| v Omit MAXPARTITIONS, NUMPARTS, and
| SEGSIZE
2
| Partitioned (non-UTS) NUMPARTS and SEGSIZE 0
| Notes:
| 1. Where n is a non-zero value. The DPSEGSZ subsystem parameter determines the default
| value. For more information, see DEFAULT PARTITION SEGSIZE field (DPSEGSZ
| subsystem parameter) (Db2 Installation and Migration).
| 2. Non-UTS table spaces for base tables are deprecated and likely to be unsupported in the
| future.
|

Chapter 2. Implementing your database design 53

| 2. Specify other attributes for the table space. The following list introduces some
| CREATE TABLESPACE statement clauses that define the attributes of a table
| space. For the complete list, see CREATE TABLESPACE (Db2 SQL).
| table-space-name
| The table space name is an identifier of up to 8 characters. You can qualify
| a table space name with a database name. Consider the following facts
| about naming guidelines for table spaces:
| v If you do not qualify an explicit table space with a database name, the
| default database name is DSNDB04.
| v If you do not explicitly specify a table space, Db2 implicitly creates the
| table space with a derived name. The name is derived based on the
| name of the table that is being created.
| v Db2 either implicitly creates a new database for the table space, or uses
| an existing implicitly created database.
| BUFFERPOOL bpname
| Identifies the buffer pool that this table space is to use and determines the
| page size of the table space. The buffer pool is a portion of memory in
| which Db2 temporarily stores data for retrieval. For more information, see
| Tuning database buffer pools (Db2 Performance).
| MAXPARTITIONS
| Specifies the maximum number of partitions for a partition-by-growth table
| space. Within this clause, you can specify the NUMPARTS clause to specify
| the number of partitions that you want to create initially.
| NUMPARTS
| Specifies the number of partitions to initially create for the table space.
| COMPRESS
| Specifies whether to compress the data. You can compress data in a table
| space to store more data on each data page. For details, see Compressing
| your data (Db2 Performance).
| FREEPAGE integer
| Specifies how often Db2 is to leave a page of free space when the table
| space or partition is loaded or reorganized. You specify that Db2 is to set
| aside one free page for every integer number of pages. Using free pages can
| improve performance for applications that perform high-volume inserts or
| that update variable-length columns. For details, see Reserving free space
| for table spaces (Db2 Performance).
| PCTFREE integer
| Specifies the percentage of each page that Db2 leaves as free space when
| the table is loaded or reorganized. Specifying PCTFREE can improve
| performance for applications that use high-volume inserts or that update
| variable-length columns. For details, see Reserving free space for table
| spaces (Db2 Performance).
| LOCKSIZE
| Specifies the size of locks that Db2 is to use within the table space. Db2
| uses locks to protect data integrity. Use of locks results in some processing
| costs, so choose the lock size carefully. For details, see Specifying the size of
| locks for a table space (Db2 Performance).
| MAXROWS
| Specifies the maximum number of rows that Db2 places on each data page.
| The integer can range from 1 through 255. If you do not specify

54 Administration Guide
| MAXROWS, the default number of rows is 255. Do not use MAXROWS for
| a LOB table space or a table space in a work file database.
| MEMBER CLUSTER
| Specifies that data that is inserted by an INSERT operation is not clustered
| by the implicit clustering index (the first index), or the explicit clustering
| index. Db2 locates the data in the table space based on available space. You
| can use the MEMBER CLUSTER keyword on partition-by-range table
| spaces and partition-by-growth table spaces. For details, see Member
| affinity clustering (Db2 Data Sharing Planning and Administration).
| DSSIZE
| Specifies the maximum size in GB for each partition. The size of the table
| space depends on how many partitions are in the table space and the size
| of each partition. For a partition-by-growth table space, the maximum
| number of partitions depends on the value that is specified for the
| MAXPARTITIONS clause.

| Examples
| The following examples illustrate how to use SQL statements to create different
| types of table spaces.
| Creating partition-by-growth table spaces
| The following example CREATE TABLE statement implicitly creates by a
| partition-by-growth table space.
| CREATE TABLE TEST02TB(
| C1 SMALLINT,
| C2 DECIMAL(9,2),
| C3 CHAR(4))
| PARTITION BY SIZE EVERY 4G
| IN TEST02DB;
| COMMIT;

| The following SQL statement creates a partition-by-growth table space that

| has a maximum size of 2 GB for each partition, 4 pages per segment, with
| a maximum of 24 partitions for table space.
| CREATE TABLESPACE TEST01TS IN TEST01DB USING STOGROUP SG1
| DSSIZE 2G
| MAXPARTITIONS 24
| LOCKSIZE ANY
| SEGSIZE 4;
| COMMIT;
| Creating partition-by-range table spaces
| The following example SQL statement defines a partition-by-range table
| space with 16 pages per segment and 55 partitions. This universal table
| space uses a storage group SG1 and has LOCKSIZE ANY.
| CREATE TABLESPACE TS1 IN DB1 USING STOGROUP SG1
| NUMPARTS 55 SEGSIZE 16
| LOCKSIZE ANY;

| The following example SQL statement defines a partition-by-range table

| space with 64 pages per segment and 7 defer-defined partitions. This table
| space uses a storage group SG1 and compresses every odd-numbered
| partition.
| CREATE TABLESPACE TS1 IN DB1 USING STOGROUP SG1
| NUMPARTS 7
| (
| PARTITION 1 COMPRESS YES,

Chapter 2. Implementing your database design 55

| PARTITION 3 COMPRESS YES,
| PARTITION 5 COMPRESS YES,
| PARTITION 7 COMPRESS YES
| )
| SEGSIZE 64
| DEFINE NO;
| Creating segmented (non-UTS) table spaces (deprecated)
| The following example SQL statement creates a segmented (non-UTS) table
| space with 32 pages in each segment:
| CREATE TABLESPACE MYTS
| IN MYDB
| USING STOGROUP MYSTOGRP
| PRIQTY 30720
| SECQTY 10240
| SEGSIZE 32
| LOCKSIZE TABLE
| BUFFERPOOL BP0
| CLOSE NO;

| What to do next

| Generally, when you use the CREATE TABLESPACE statement with the USING
| STOGROUP clause, Db2 allocates data sets for the table space. However, if you
| also specify the DEFINE NO clause, you can defer the allocation of data sets until
| data is inserted or loaded into a table in the table space.

|
|
| Related concepts:
| Managing your own data sets
| Related tasks:
| Altering table spaces
| Choosing data page sizes (Db2 Performance)
| Choosing data page sizes for LOB data (Db2 Performance)
| Creating EA-enabled table spaces and index spaces
| Related reference:
| CREATE TABLESPACE (Db2 SQL)
| CREATE LOB TABLESPACE (Db2 SQL)
| SYSTABLESPACE catalog table (Db2 SQL)
| DEFAULT PARTITION SEGSIZE field (DPSEGSZ subsystem parameter) (Db2
| Installation and Migration)

| Creating partition-by-range table spaces

| You can create a partition-by-range table space to create partitions based on data
| value ranges and use segmented space management capabilities within each
| partition.

| About this task

| A partition-by-range table space is a universal table space (UTS) that has partitions
| based on ranges of data values. It holds data pages for a single table, and has
| segmented space management capabilities within each partition.

56 Administration Guide
| In a partition-by-range table space, the partitions are based on the boundary values
| that are defined for specific data columns. For example, the following figure
| illustrates the data pages for a table with two partitions.
|
|
Partition 1
Key range A-L

Partition 2
Key range M-Z

|
| Figure 16. Pages in a range-partitioned table space
|
| Utilities and SQL statements can run concurrently on each partition. For example, a
| utility job can work on part of the data while allowing other applications to
| concurrently access data on other partitions. In that way, several concurrent utility
| jobs can, for example, load all partitions of a table space concurrently. Because you
| can work on part of your data, some of your operations on the data might require
| less time. Also, you can use separate jobs for mass update, delete, or insert
| operations instead of using one large job; each smaller job can work on a different
| partition. Separating the large job into several smaller jobs that run concurrently
| can reduce the elapsed time for the whole task.

| You can create an index of any type on a table in a partition-by-range table space.

| Tip: Partition-by-range table spaces are the suggested alternative for partitioned
| (non-UTS) table spaces, which are deprecated.

| Procedure

| To create a partition-by-range table space, use one of the following approaches:

| v Issue a CREATE TABLE statement and specify the PARTITION BY RANGE
| clause. The following example creates a table in a partition-by-range table space,
| where the table space is implicitly created:
| CREATE TABLE TB01 (
| ACCT_NUM INTEGER,
| CUST_LAST_NM CHAR(15),
| LAST_ACTIVITY_DT VARCHAR(25),
| COL2 CHAR(10),
| COL3 CHAR(25),
| COL4 CHAR(25),
| COL5 CHAR(25),
| COL6 CHAR(55),
| STATE CHAR(55))
| IN DBB.TS01
|
| PARTITION BY RANGE (ACCT_NUM)
| (PARTITION 1 ENDING AT (199),
| PARTITION 2 ENDING AT (299),
| PARTITION 3 ENDING AT (399),
| PARTITION 4 ENDING AT (MAXVALUE));
| v Issue a CREATE TABLESPACE statement that specifies the NUMPARTS clause
| and SEGSIZE clause, and omits the MAXPARTITIONS clause. The following
| example creates a partition-by-range table space, TS1, in database DSN8D12A
| using storage group DSN8G120. The table space has 16 pages per segment and
| has 55 partitions.

Chapter 2. Implementing your database design 57

| CREATE TABLESPACE TS1
| IN DSN8D12A
| USING STOGROUP DSN8G120
| NUMPARTS 55
| SEGSIZE 16
| LOCKSIZE ANY;
| Related concepts:
| Partition-by-range table spaces
| Related reference:
| CREATE TABLE (Db2 SQL)
| CREATE TABLESPACE (Db2 SQL)

| Creating partition-by-growth table spaces

| You can create a partition-by-growth table space so that Db2 manages partitions
| based on data growth and uses segmented space management capabilities within
| each partition.

| About this task

| A partition-by-growth table space is a universal table space (UTS) that has partitions
| that Db2 manages automatically based on data growth. It holds data pages for
| only a single table, and has segmented space management capabilities within each
| partition.

| Db2 manages partition-by-growth table spaces automatically as data grows, by

| automatically adding a new partition when more space is needed to satisfy an
| insert operation.

| Partition-by-growth table spaces are best used when a table is expected to exceed
| 64 GB, or when a table does not have a suitable partitioning key.
| Partition-by-growth table spaces can grow up to 128 TB, depending on the buffer
| pool page size used, and the MAXPARTITIONS and DSSIZE values specified when
| the table space is created.

| The partitioned structure supports partition-level utility operations and parallelism

| capabilities. A partition-by-growth table space also has segmented organization and
| segmented space management capabilities within each partition. The segmented
| structure provides better space management and mass delete capabilities.

| Tip: Partition-by-growth table spaces are the suggested alternative for single-table
| Db2-managed segmented (non-UTS) table spaces, which are deprecated.

| Procedure

| To create a partition-by-growth table space, use one of the following approaches:

| v Issue a CREATE TABLE statement, and specify the PARTITION BY SIZE clause.
| Db2 implicitly creates a partition-by-growth table space for the new table. The
| following example creates a table in a partition-by-growth table space, where the
| table space is implicitly created:
| CREATE TABLE TS02TB
| (C1 SMALLINT,
| C2 DECIMAL(9,2),
| C3 CHAR(4))
| PARTITION BY SIZE EVERY 4G
| IN DATABASE DSNDB04;

58 Administration Guide
| v Issue a CREATE TABLESPACE statement and specify one of the following
| combinations of the MAXPARITIONS, NUMPARTS, and SEGSIZE CLAUSES:
| – Specify MAXPARTITIONS without NUMPARTS, for example:
| CREATE TABLESPACE TEST01TS IN TEST01DB USING STOGROUP SG1
| DSSIZE 2G
| MAXPARTITIONS 24
| LOCKSIZE ANY
| SEGSIZE 4;
| COMMIT;
| – Specify both MAXPARTITIONS and NUMPARTS.
| – Specify MAXPARTITIIONS and SEGSIZEn.
| Related concepts:
| Partition-by-growth table spaces
| Related reference:
| CREATE TABLESPACE (Db2 SQL)
| CREATE TABLE (Db2 SQL)

EA-enabled table spaces and index spaces

You can enable partitioned table spaces for extended addressability (EA), a
function of DFSMS. The term for table spaces and index spaces that are enabled for
extended addressability is EA-enabled.

You must use EA-enabled table spaces or index spaces if you specify a maximum
partition size (DSSIZE) that is larger than 4 GB in the CREATE TABLESPACE
statement.

Both EA-enabled and non-EA-enabled partitioned table spaces can have only one
table and up to 4096 partitions. The following table summarizes the differences.
Table 10. Differences between EA-enabled and non-EA-enabled table spaces
EA-enabled table spaces Non-EA-enabled table spaces
Holds up to 4096 partitions with DSSIZE 64G Holds up to 4096 partitions with DSSIZE 4G
Created with any valid value of DSSIZE DSSIZE cannot exceed 4G
Data sets are managed by SMS Data sets are managed by VSAM or SMS
Requires setup No additional setup

Related tasks:
Creating EA-enabled table spaces and index spaces
Creating table spaces explicitly
Related reference:
CREATE TABLESPACE (Db2 SQL)

Implementing Db2 tables

Use the columns and rows of Db2 tables as logical structures for storing data.
Related concepts:
Creation of tables (Introduction to Db2 for z/OS)
Related tasks:
Creating tables (Db2 Application programming and SQL)

Chapter 2. Implementing your database design 59

 Related reference:
CREATE TABLE (Db2 SQL)

Creating base tables

When you create a table, Db2 records a definition of the table in the Db2 catalog.

About this task

Creating a table does not store the application data. You can put data into the table
by using several methods, such as the LOAD utility or the INSERT statement.

Procedure

To create a base table that you designed:

Issue the CREATE TABLE statement.

Example

The following CREATE TABLE statement creates the EMP table, which is in a
database named MYDB and in a table space named MYTS:
CREATE TABLE EMP
(EMPNO CHAR(6) NOT NULL,
FIRSTNME VARCHAR(12) NOT NULL,
LASTNAME VARCHAR(15) NOT NULL,
DEPT CHAR(3) ,
HIREDATE DATE ,
JOB CHAR(8) ,
EDL SMALLINT ,
SALARY DECIMAL(9,2) ,
COMM DECIMAL(9,2) ,
PRIMARY KEY (EMPNO))
IN MYDB.MYTS;

This CREATE TABLE statement shows the definition of multiple columns.

Related reference:
CREATE TABLE (Db2 SQL)

Guidelines for table names

Most organizations have naming conventions to ensure that objects are named in a
consistent manner. Consider these basic requirements for table names.

The table name is an identifier of up to 128 characters. You can qualify the table
name with an SQL identifier, which is a schema. When you define a table that is
based directly on an entity, these factors also apply to the table names.

| Creating tables that use hash organization (deprecated)

When you create a table, you can organize the table by hash to improve the
| performance queries that access individual rows. Hash-organized table spaces are
| deprecated and likely to be unsupported in the future.

60 Administration Guide
 About this task

Deprecated function:

| Hash-organized tables are deprecated. Beginning in Db2 12, packages that are
| bound with APPLCOMPAT(V12R1M504) or higher cannot create hash-organized
| tables or alter existing tables to use hash-organization. Existing hash-organized
| tables remain supported, but they are likely to be unsupported in the future.

When you create new tables in universal table spaces, you can enable hash access
to that table by adding the organization-clause to your CREATE TABLE statement.

Procedure

To create a new table that is organized for hash access:

1. Specify ORGANIZE BY HASH in the organization-clause of your CREATE
TABLE statement.
2. Specify UNIQUE followed by the column names for one or more columns that
contain unique values in each row. You can specify more than one
column-name as long as no two rows in the table have the same values in
those columns. You can only specify columns that are defined as NOT NULL.
You can specify a maximum of 64 columns to be used as unique identifiers for
hash access. The sum of the column length attributes must not exceed 255. Db2
maintains the uniqueness of the hash key columns, and an index is not needed
for this purpose.
3. Specify HASH SPACE followed by an integer and a modifier that specifies the
size of the hash space. You can specify the size of the hash space in kilobytes,
megabytes, and gigabytes. Specify:
v K for kilobytes
v M for megabytes
v G for gigabytes
You can specify a size that is larger than your data to minimize the overhead of
access to data that overflows the hash space. The value that you specify is most
important if you do not reorganize the table and specify the
AUTOESTSPACE(YES) option soon after you create the table.
4. Commit the CREATE TABLE statement.

Results

After you organize a table for hash access, Db2 is likely but not certain to select
hash access for statements that access the table.

Example

Consider the following CREATE TABLE statement:

CREATE TABLE EMP
(EMPNO CHAR(6) NOT NULL,
FIRSTNME VARCHAR(12) NOT NULL,
LASTNAME VARCHAR(15) NOT NULL,
DEPT CHAR(3) ,
HIREDATE DATE ,
JOB CHAR(8) ,
EDL SMALLINT ,
SALARY DECIMAL(9,2) ,
COMM DECIMAL(9,2) ,

Chapter 2. Implementing your database design 61

 PRIMARY KEY (EMPNO))
IN MYDB.MYTS
ORGANIZE BY HASH UNIQUE (EMPNO)
HASH SPACE 64 M;

In this example the user creates a table named EMP in an explicitly defined table
space, sets the EMPNO column as the unique identifier for hash access, and
specifies a HASH SPACE size of 64 with the modifier M for megabytes.

What to do next

You can monitor the real-time-statistics information about your table to verify
whether the hash access path is used regularly and to verify that the use of disk
space is optimized.
Related tasks:
| Organizing tables for hash access to individual rows (deprecated) (Db2
Performance)
Managing space and page size for hash-organized tables (Db2 Performance)
| Monitoring hash access (deprecated) (Db2 Performance)
| Altering tables for hash access (deprecated)
| Altering the size of your hash spaces (deprecated)
Related reference:
CREATE TABLE (Db2 SQL)

Creating temporary tables

Temporary tables are useful when you need to sort or query intermediate result
tables that contain large numbers of rows and identify a small subset of rows to
store permanently. The two types of temporary tables are created temporary tables
and declared temporary tables.

About this task

Use a created temporary table when you need a permanent, sharable description of
a table, and you need to store data only for the life of an application process. Use a
declared temporary table when you need to store data for the life of an application
process, but you don't need a permanent, sharable description of the table.

Procedure

To create a temporary table:

1. Determine the type of temporary table that you want to create.
2. Issue the appropriate SQL statement for the type of temporary table that you
want to create:
v To define a created temporary table, issue the CREATE GLOBAL
TEMPORARY TABLE statement.
v To define a declared temporary table, issue the DECLARE GLOBAL
TEMPORARY TABLE statement.

62 Administration Guide
Creating created temporary tables
If you need a permanent, sharable description of a table but need to store data
only for the life of an application process, you can define and use a created
temporary table.

About this task

Db2 does not log operations that it performs on created temporary tables;
therefore, SQL statements that use created temporary tables can execute more
efficiently. Each application process has its own instance of the created temporary
table.

Procedure

To create a created temporary table:

Issue the CREATE GLOBAL TEMPORARY TABLE statement.

Example

The following statement defines a created temporary table that is named

TEMPPROD.
CREATE GLOBAL TEMPORARY TABLE TEMPPROD
(SERIALNO CHAR(8) NOT NULL,
DESCRIPTION VARCHAR(60) NOT NULL,
MFGCOSTAMT DECIMAL(8,2) ,
MFGDEPTNO CHAR(3) ,
MARKUPPCT SMALLINT ,
SALESDEPTNO CHAR(3) ,
CURDATE DATE NOT NULL);

Related tasks:
Setting default statistics for created temporary tables (Db2 Performance)
Related reference:
CREATE GLOBAL TEMPORARY TABLE (Db2 SQL)

Creating declared temporary tables

If you need to store data for the life of an application process, but you don't need a
permanent, sharable description of the table, you can define and use a declared
temporary table.

Procedure

To create a declared temporary table:

Issue the DECLARE GLOBAL TEMPORARY TABLE statement. Unlike other Db2
DECLARE statements, DECLARE GLOBAL TEMPORARY TABLE is an executable
statement that you can embed in an application program or issue interactively. You
can also dynamically prepare the statement.
When a program in an application process issues a DECLARE GLOBAL
TEMPORARY TABLE statement, Db2 creates an empty instance of the table. You
Chapter 2. Implementing your database design 63
 can populate the declared temporary table by using INSERT statements, modify
the table by using searched or positioned UPDATE or DELETE statements, and
query the table by using SELECT statements. You can also create indexes on the
declared temporary table. The definition of the declared temporary table exists as
long as the application process runs.
At the end of an application process that uses a declared temporary table, Db2
deletes the rows of the table and implicitly drops the description of the table.

Example

The following statement defines a declared temporary table, TEMP_EMP. (This

example assumes that you have already created the WORKFILE database and
corresponding table space for the temporary table.)
DECLARE GLOBAL TEMPORARY TABLE SESSION.TEMP_EMP
(EMPNO CHAR(6) NOT NULL,
SALARY DECIMAL(9, 2) ,
COMM DECIMAL(9, 2));

If specified explicitly, the qualifier for the name of a declared temporary table,
must be SESSION. If the qualifier is not specified, it is implicitly defined to be
SESSION.

Related reference:
DECLARE GLOBAL TEMPORARY TABLE (Db2 SQL)

Distinctions between Db2 base tables and temporary tables

Db2 base tables and the two types of temporary tables have several distinctions.

The following table summarizes important distinctions between base tables, created
temporary tables, and declared temporary tables.

64 Administration Guide
Table 11. Important distinctions between Db2 base tables and Db2 temporary tables
Area of
distinction Base tables Created temporary tables Declared temporary tables
Creation, CREATE TABLE statement CREATE GLOBAL DECLARE GLOBAL
persistence, and puts a description of the table TEMPORARY TABLE TEMPORARY TABLE statement
ability to share in catalog table SYSTABLES. statement puts a description does not put a description of the
table descriptions The table description is of the table in catalog table table in catalog table SYSTABLES.
persistent and is shareable SYSTABLES. The table The table description is not
across application processes. description is persistent and is persistent beyond the life of the
shareable across application application process that issued
The name of the table in the processes. the DECLARE statement and the
CREATE statement can be a description is known only to that
two-part or three-part name. The name of the table in the application process. Thus, each
If the table name is not CREATE statement can be a application process could have its
qualified, Db2 implicitly two-part- or three-part name. own possibly unique description
qualifies the name using the If the table name is not of the same table.
standard Db2 qualification qualified, Db2 implicitly
rules applied to the SQL qualifies the name using the The name of the table in the
statements. standard Db2 qualification DECLARE statement can be a
rules applied to the SQL two-part or three-part name. If
statements. the table name is qualified,
SESSION must be used as the
The table space that is used qualifier for the owner (the
by created temporary tables is second part in a three-part name).
reset by the following If the table name is not qualified,
commands: START DB2, START Db2 implicitly uses SESSION as
DATABASE, and START the qualifier.
DATABASE(dbname)
SPACENAM(tsname), where The table space used by declared
dbname is the name of the temporary tables is reset by the
database and tsname is the following commands: START DB2,
name of the table space. START DATABASE, and START
DATABASE(dbname)
SPACENAM(tsname), where
dbname is the name of the
database and tsname is the name
of the table space.
Table CREATE TABLE statement CREATE GLOBAL DECLARE GLOBAL
instantiation and creates one empty instance of TEMPORARY TABLE TEMPORARY TABLE statement
ability to share the table, and all application statement does not create an creates an empty instance of the
data processes use that one instance of the table. The first table for the application process.
instance of the table. The table implicit or explicit reference to Each application process has its
and data are persistent. the table in an OPEN, own unique instance of the table,
SELECT, INSERT, or DELETE and the instance is not persistent
operation that is executed by beyond the life of the application
any program in the process.
application process creates an
empty instance of the given
table. Each application process
has its own unique instance of
the table, and the instance is
not persistent beyond the life
of the application process.

Chapter 2. Implementing your database design 65

 Table 11. Important distinctions between Db2 base tables and Db2 temporary tables (continued)
Area of
distinction Base tables Created temporary tables Declared temporary tables
References to the References to the table name References to the table name References to that table name in
table in in multiple application in multiple application multiple application processes
application processes refer to the same processes refer to the same refer to a distinct description and
processes single persistent table single persistent table instance of the table for each
description and to the same description but to a distinct application process at the current
instance at the current server. instance of the table for each server.
application process at the
If the table name that is being current server. References to the table name in
referenced is not qualified, an SQL statement (other than the
Db2 implicitly qualifies the If the table name that is being DECLARE GLOBAL
name using the standard Db2 referenced is not qualified, TEMPORARY TABLE statement)
qualification rules that apply Db2 implicitly qualifies the must include SESSION as the
to the SQL statements. The name using the standard Db2 qualifier (the first part in a
name can be a two-part- or qualification rules that apply two-part table name or the
three-part name. to the SQL statements. The second part in a three-part name).
name can be a two-part or If the table name is not qualified
three-part name. with SESSION, Db2 assumes the
reference is to a base table.
Table privileges The owner implicitly has all The owner implicitly has all PUBLIC implicitly has all table
and authorization table privileges on the table table privileges on the table privileges on the table without
and the authority to drop the and the authority to drop the GRANT authority and has the
table. The owner's table table. The owner's table authority to drop the table. These
privileges can be granted and privileges can be granted and table privileges cannot be granted
revoked, either individually or revoked, but only with the or revoked.
with the ALL clause. ALL clause; individual table
privileges cannot be granted Any authorization ID can access
Another authorization ID can or revoked. the table without a grant of any
access the table only if it has privileges for the table.
been granted appropriate Another authorization ID can
privileges for the table. access the table only if it has
been granted ALL privileges
for the table.
Indexes and other Indexes and SQL statements Indexes, UPDATE (searched Indexes and SQL statements that
SQL statement that modify data (INSERT, or positioned), and DELETE modify data (INSERT, UPDATE,
support UPDATE, DELETE, and so (positioned only) are not DELETE, and so on) are
on) are supported. supported. supported.
Locking, logging, Locking, logging, and Locking, logging, and Some locking, logging, and
and recovery recovery do apply. recovery do not apply. Work limited recovery do apply. No
files are used as the space for row or table locks are acquired.
the table. Share-level locks on the table
space and DBD are acquired. A
segmented table lock is acquired
when all the rows are deleted
from the table or the table is
| dropped. Create and drop actions
| for the table are always logged.
| Logging of insert, update, and
| delete operations can be disabled
| with the NOT LOGGED option.
| Undo recovery (rolling back
changes to a savepoint or the
most recent commit point) is
supported, but redo recovery
(forward log recovery) is not
supported.

66 Administration Guide
Table 11. Important distinctions between Db2 base tables and Db2 temporary tables (continued)
Area of
distinction Base tables Created temporary tables Declared temporary tables
Table space and Table space and database Table space and database Table space and database
database operations do apply. operations do not apply. operations do apply.
operations
Table space The table can be stored in The table is stored in table The table is stored in a table
requirements and implicitly created table spaces spaces in the work file space in the work file database.
table size and databases. database.
limitations The table cannot span table
The table cannot span table The table can span work file spaces. Therefore, the size of the
spaces. Therefore, the size of table spaces. Therefore, the table is limited by the table space
the table is limited by the size of the table is limited by size (as determined by the
table space size (as the number of available work primary and secondary space
determined by the primary file table spaces, the size of allocation values that are
and secondary space each table space, and the specified for the table space's
allocation values that are number of data set extents data sets) and the shared usage
specified for the table space's that are allowed for the table of the table space among multiple
data sets) and the shared spaces. Unlike the other types users. When the table space is
usage of the table space of tables, created temporary full, an error occurs for the SQL
among multiple users. When tables do not reach size operation.
the table space is full, an error limitations as easily.
occurs for the SQL operation.

Related concepts:
Temporary tables (Db2 Application programming and SQL)
Related tasks:
Creating temporary tables
Setting default statistics for created temporary tables (Db2 Performance)
Related reference:
CREATE GLOBAL TEMPORARY TABLE (Db2 SQL)
DECLARE GLOBAL TEMPORARY TABLE (Db2 SQL)

Creating temporal tables

You can create a temporal table, which is a table that records the period of time
when a row is valid.
Related information:
Managing Ever-Increasing Amounts of Data with IBM Db2 for z/OS: Using
Temporal Data Management, Archive Transparency, and the IBM Db2 Analytics
Accelerator for z/OS (IBM Redbooks)

Temporal tables and data versioning

A temporal table is a table that records the period of time when a row is valid.

A period is an interval of time that is defined by two datetime columns in a

temporal table. A period contains a row-begin column and a row-end column. The
row-begin column indicates the beginning of the period, and the row-end column
indicates the end of the period. The beginning value of a period is inclusive, but
the ending value of a period is exclusive. For example, if the begin column has a
value of '01/01/1995', that date belongs in the row. Whereas, if the end column has
a value of '03/21/1995', that date is not part of the row.

Chapter 2. Implementing your database design 67

 Db2 supports two types of periods, which are the system period (SYSTEM_TIME)
and the application period (BUSINESS_TIME).

System-period data versioning

The system period consists of a pair of columns with system-maintained values that
indicate the period of time when a row is valid. The begin column contains the
timestamp value for when a row is created. The end column contains the
timestamp value for when a row is updated or deleted.

The system period is meaningful because of system-period data versioning.

System-period data versioning specifies that old rows are archived into another
table. The table that contains the current active rows of a table is called the
system-period temporal table. The table that contains the archived rows is called the
history table. You can delete the rows from the history table when those rows are no
longer needed, if you have the correct authorization. When you define a base table
to use system-period data versioning, or when you define system-period data
versioning on an existing table, you must create a history table, specify a name for
the history table, and create a table space to hold that table. You define versioning
by issuing the ALTER TABLE ADD VERSIONING statement with the USE
HISTORY TABLE clause.

For a list of restrictions that apply to system-period temporal tables, see

Restrictions for system-period data versioning.

Application-period data versioning

The application period consists of a pair of columns with application-maintained

values that indicate the period of time when a row is valid. The begin column
contains the value from which a row is valid. The end column contains the value
for when a row stops being valid. A table with only an application period is called
an application-period temporal table.

When you use the application period, determine the need for Db2 to enforce
uniqueness across time. You can create a UNIQUE index that is unique over a
period of time.

Bitemporal tables

A bitemporal table is a table that is both a system-period temporal table and an

application-period temporal table. You can use a bitemporal table to keep
application period information and system-based historical information. Therefore,
you have a lot of flexibility in how you query data, based on periods of time.
Related concepts:
Recovery of temporal tables with system-period data versioning
Related tasks:
Adding a system period and system-period data versioning to an existing table
Creating a system-period temporal table
Adding an application period to a table
Creating an application-period temporal table

Restrictions for system-period data versioning

When a table is enabled for system-period data versioning, certain restrictions
apply.

68 Administration Guide
v For point-in-time recovery, to keep the data in the system-period temporal table
and the data in the history table synchronized, you must recover the table
spaces for both tables as a set. You can recover the table spaces individually only
if you specify the VERIFYSET NO option in the RECOVER utility statement.
v You cannot run a utility operation that deletes data from a system-period
temporal table. These utilities include LOAD REPLACE, REORG DISCARD, and
CHECK DATA DELETE YES.
v You cannot run the CHECK DATA utility with the options LOBERROR
INVALIDATE, AUXERROR INVALIDATE, or XMLERROR INVALIDATE on a
system-period temporal table. The CHECK DATA utility will fail with return
code 8 and message DSNU076.
v You cannot alter the schema (data type, check constraint, referential constraint,
etc.) of a system-period temporal table or history table; however, you can add a
column to system-period temporal table.
v You cannot drop the history table or its table space.
v You cannot define a clone table on the system-period temporal table or the
history table.
v You cannot create another table in table space for either the system-period
temporal table or history table.
v On the history table, you cannot use the UPDATE, DELETE, or SELECT
statement syntax that specifies the application period.
v You cannot rename a column or table name of a system-period temporal table or
a history table.
Related concepts:
Temporal tables and data versioning
Related reference:
CHECK DATA (Db2 Utilities)

Creating a system-period temporal table

You can create a temporal table that has a system period and define system-period
data versioning on the table, so that the data is versioned after insert, update, and
delete operations.

Before you begin

You can also alter existing tables to use system-period data versioning. For more
information, see Adding a system period and system-period data versioning to an
existing table.

About this task

A system period is a system-maintained period in which Db2 maintains the

beginning and ending timestamp values for a row.

The row-begin column of the system period contains the timestamp value for when
a row is created. The row-end column contains the timestamp value for when a row
is removed. A transaction-start-ID column contains a unique timestamp value that
Db2 assigns per transaction, or the null value.

For a list of restrictions that apply to tables that use system-period data versioning,
see Restrictions for system-period data versioning.

Chapter 2. Implementing your database design 69

 Procedure

To create a temporal table with a system period and define system-period data
versioning on the table:
1. Issue a CREATE TABLE statement with a SYSTEM_TIME clause. The created
table must have the following attributes:
v A row-begin column that is defined as TIMESTAMP(12) NOT NULL with the
GENERATED ALWAYS AS ROW BEGIN attribute.
v A row-end column that is defined as TIMESTAMP(12) NOT NULL with the
GENERATED ALWAYS AS ROW END attribute.
v A system period (SYSTEM_TIME) defined on two timestamp columns. The
first column is the row-begin column and the second column is the row-end
column.
| v A transaction-start-ID column that defined as TIMESTAMP(12) NOT NULL
| with the GENERATED ALWAYS AS TRANSACTION START ID attribute.
v The only table in the table space
v The table definition is complete
It cannot have clone table defined on it, and it cannot have the following
attributes:
v Column masks
v Row permissions
v Security label columns
2. Issue a CREATE TABLE statement to create a history table that receives the old
rows from the system-period temporal table. The history table must have the
following attributes:
v The same number of columns as the system-period temporal table that it
corresponds to
v Columns with the same names, data types, null attributes, CCSIDs, subtypes,
hidden attributes, and field procedures as the corresponding system-period
temporal table. However, the history table cannot have any GENERATED
ALWAYS columns unless the system-period temporal table has a ROWID
GENERATED ALWAYS or ROWID GENERATED BY DEFAULT column. In
that case, the history table must have a corresponding ROWID GENERATED
ALWAYS column. .
v The only table in the table space
v The table definition is complete
| A history table cannot be a materialized query table, an archive-enabled table,
| or an archive table, cannot have a clone table defined on it, and cannot have
| the following attributes:
v Identity columns or row change timestamp columns
v ROW BEGIN, ROW END, or TRANSACTION START ID columns
v Column masks
v Row permissions
v Security label columns
v System or application periods
3. Issue the ALTER TABLE ADD VERSIONING statement with the USE HISTORY
TABLE clause to define system-period data versioning on the table. By defining
system-period data versioning, you establish a link between the system-period
temporal table and the history table.

70 Administration Guide
 Example

The following examples show how you can create a temporal table with a system
period, create a history table, and then define system-period data versioning on the
table. Also, a final example shows how to insert data.

The following example shows a CREATE TABLE statement for creating a temporal
table with a SYSTEM_TIME period. In the example, the sys_start column is the
row-begin column, sys_end is the row-end column, and create_id is the
transaction-start-ID column. The SYSTEM_TIME period is defined on the ROW
BEGIN and ROW END columns:
CREATE TABLE policy_info
(policy_id CHAR(10) NOT NULL,
coverage INT NOT NULL,
sys_start TIMESTAMP(12) NOT NULL GENERATED ALWAYS AS ROW BEGIN,
sys_end TIMESTAMP(12) NOT NULL GENERATED ALWAYS AS ROW END,
create_id TIMESTAMP(12) GENERATED ALWAYS AS TRANSACTION START ID,
PERIOD SYSTEM_TIME(sys_start,sys_end));

This example shows a CREATE TABLE statement for creating a history table:
CREATE TABLE hist_policy_info
(policy_id CHAR(10) NOT NULL,
coverage INT NOT NULL,
sys_start TIMESTAMP(12) NOT NULL,
sys_end TIMESTAMP(12) NOT NULL,
create_id TIMESTAMP(12))

To define versioning, issue the ALTER TABLE statement with the ADD
VERSIONING clause and the USE HISTORY TABLE clause, which establishes a
link between the system-period temporal table and the history table:
ALTER TABLE policy_info
ADD VERSIONING USE HISTORY TABLE hist_policy_info;

The following example shows how to insert data in the POLICY_ID and
COVERAGE columns of the POLICY_INFO table:
INSERT INTO POLICY_INFO (POLICY_ID, COVERAGE)
VALUES(’A123’, 12000);

| If you want to use temporal tables to track auditing information, see the example
| in “Scenario for tracking auditing information” on page 74.

Related concepts:
Temporal tables and data versioning
Related reference:
CREATE TABLE (Db2 SQL)
ALTER TABLE (Db2 SQL)
Related information:
Managing Ever-Increasing Amounts of Data with IBM Db2 for z/OS: Using
Temporal Data Management, Archive Transparency, and the IBM Db2 Analytics
Accelerator for z/OS (IBM Redbooks)

Chapter 2. Implementing your database design 71

 Creating an application-period temporal table
An application-period temporal table is a type of temporal table where you maintain
the values that indicate when a row is valid. The other type of temporal table is a
system-period temporal table where Db2 maintains the values that indicate when a
row is valid.

About this task

When you create an application-period temporal table, you define begin and end
columns to indicate the application period, or period of time when the row is
valid. The begin column contains the time from which a row is valid. The end
column contains the time when a row stops being valid.

Procedure

To create an application-period temporal table:

Issue a CREATE TABLE statement with the following items:

v Two columns to define the application period. These columns are the begin and
end columns. They must be type TIMESTAMP(6) WITHOUT TIME ZONE NOT
NULL or DATE NOT NULL, and they must be the same type. The data type
cannot be a user-defined type.
v The BUSINESS_TIME clause.

Example

Example of creating an application-period temporal table

The following example SQL statements create a table with an application
period and a unique index:
CREATE TABLE policy_info
(policy_id CHAR(4) NOT NULL,
coverage INT NOT NULL,
bus_start DATE NOT NULL,
bus_end DATE NOT NULL,
PERIOD BUSINESS_TIME(bus_start, bus_end));

CREATE UNIQUE INDEX ix_policy

ON policy_info (policy_id, BUSINESS_TIME WITHOUT OVERLAPS);

Related concepts:
Temporal tables and data versioning
Related reference:
CREATE TABLE (Db2 SQL)
CREATE INDEX (Db2 SQL)

Creating bitemporal tables

You can create a bitemporal table that maintains both system-based historical
information and application period information.

72 Administration Guide
About this task

You maintain system-based historical information by adding a system period to a

table, and you maintain application period information by adding an application
period to the table.

For a list of restrictions that apply to tables that use system-period data versioning,
see Restrictions for system-period data versioning.

Procedure

To create a bitemporal table and define system-period data versioning on the table:
1. Issue a CREATE TABLE statement with both the SYSTEM_TIME clause and the
BUSINESS_TIME clause. For more information about the requirements for the
history table, see Creating a system-period temporal table and Creating an
application-period temporal table.
2. Issue a CREATE TABLE statement to create a history table that receives the old
rows from the bitemporal table.
3. Issue the ALTER TABLE ADD VERSIONING statement with the USE HISTORY
TABLE clause to define system-period data versioning and establish a link
between the bitemporal table and the history table.

Example

The following examples show how you can create a bitemporal table, create a
history table, and then define system-period data versioning.

This example shows a CREATE TABLE statement with the SYSTEM_TIME and
BUSINESS_TIME clauses for creating a bitemporal table:
CREATE TABLE policy_info
(policy_id CHAR(4) NOT NULL,
coverage INT NOT NULL,
bus_start DATE NOT NULL,
bus_end DATE NOT NULL,
sys_start TIMESTAMP(12) NOT NULL GENERATED ALWAYS AS ROW BEGIN,
sys_end TIMESTAMP(12) NOT NULL GENERATED ALWAYS AS ROW END,
create_id TIMESTAMP(12) GENERATED ALWAYS AS TRANSACTION START ID,
PERIOD BUSINESS_TIME(bus_start, bus_end),
PERIOD SYSTEM_TIME(sys_start, sys_end));

This example shows a CREATE TABLE statement for creating a history table:
CREATE TABLE hist_policy_info
(policy_id CHAR(4) NOT NULL,
coverage INT NOT NULL,
bus_start DATE NOT NULL,
bus_end DATE NOT NULL,
sys_start TIMESTAMP(12) NOT NULL,
sys_end TIMESTAMP(12) NOT NULL,
create_id TIMESTAMP(12));

This example shows the ALTER TABLE ADD VERSIONING statement with the
USE HISTORY TABLE clause that establishes a link between the bitemporal table
and the history table to enable system-period data versioning. Also, a unique index
is added to the bitemporal table.

Chapter 2. Implementing your database design 73

 ALTER TABLE policy_info
ADD VERSIONING USE HISTORY TABLE hist_policy_info;
CREATE UNIQUE INDEX ix_policy
ON policy_info (policy_id, BUSINESS_TIME WITHOUT OVERLAPS);

Related concepts:
Temporal tables and data versioning
Related tasks:
Adding a system period and system-period data versioning to an existing table
Adding an application period to a table
Related reference:
CREATE TABLE (Db2 SQL)
ALTER TABLE (Db2 SQL)

| Scenario for tracking auditing information

| Db2 can track some basic auditing information for you. Db2 can track when the
| data was modified, who modified the data, and the SQL operation that modified
| the data.

| To track when the data was modified, define your table as a system-period
| temporal table. When data in a system-period temporal table is modified,
| information about the changes is recorded in its associated history table.

| To track who and what SQL statement modified the data, you can use
| non-deterministic generated expression columns. These columns can contain values that
| are helpful for auditing purposes, such as the value of the CURRENT SQLID
| special register at the time that the data was modified. You can define several
| variations of generated expression columns by using the appropriate CREATE
| TABLE or ALTER TABLE syntax. Each variation of generated expression column
| results in a different type of generated values.

| In the following scenario, a system-period temporal table is created with

| non-deterministic generated expression columns to track auditing information.

| Suppose that you issue the following statement to create a system-period temporal
| table called STT:
| CREATE TABLE STT (balance INT,
| user_id VARCHAR(128) GENERATED ALWAYS AS ( SESSION_USER ) ,
| op_code CHAR(1)
| GENERATED ALWAYS AS ( DATA CHANGE OPERATION )
| ... SYSTEM PERIOD (SYS_START, SYS_END));

| The user_id column is to store who modified the data. This column is defined as a
| non-deterministic generated expression column that will contain the value of the
| SESSION_USER special register at the time of a data change operation.

| The op_code column is to store the SQL operation that modified that data. This
| column is also defined as a non-deterministic generated expression column.

| Suppose that you then issue the following statements to create a history table for
| STT and to associate that history table with STT:

74 Administration Guide
| CREATE TABLE STT_HISTORY (balance INT, user_id VARCHAR(128) , op_code CHAR(1) ... );
|
| ALTER TABLE STT ADD VERSIONING
| USE HISTORY TABLE STT_HISTORY ON DELETE ADD EXTRA ROW;

| In the ALTER TABLE statement, the ON DELETE ADD EXTRA ROW clause
| indicates that when a row is deleted from STT, an extra row is to be inserted into
| the history table. This extra row in the history table is to contain values for the
| non-deterministic generated expression columns (user_id and op_code) at the time
| of the delete operation.

| Now, consider what happens as the STT table is modified. For simplicity, date
| values are used instead of time stamps for the period columns in this scenario.

| Assume that on 15 June 2010, user KWAN issues the following statement to insert
| a row into STT:
| INSERT INTO STT (balance) VALUES (1)

| After the insert, the tables contain the following data.

| Table 12. Data after insert
| Table Data (balance, user_id, op_code, sys_start, sys_end)
| STT (1, ’KWAN’, 'I', 2010-06-15, 9999-12-30)
| STT_HISTORY Empty
|

| Later, on 1 December 2011, user HAAS issues the following statement to update
| the row:
| UPDATE STT SET balance = balance + 9;

| This update results in the following data in the tables:

| Table 13. Data after update
| Table Data
| STT (10, ’HAAS’, ’U’, 2011-12-01, 9999-12-30)
| STT_HISTORY ▌row 1▐(1, ’KWAN’, ’I’, 2010-06-15, 2011-12-01)
|

| On 20 December 2013, user THOMPSON issues the following statement to delete

| the row:
| DELETE FROM STT;

| This deletion results in the following data in the tables:

| Table 14. Data after deletion
| Table Data
| STT Empty
| STT_HISTORY ▌row 1▐ (1, ’KWAN’, ’I’, 2010-06-15, 2011-12-01)
| ▌row 2▐ (10, ’HAAS’, ’U’, 2011-12-01, 2013-12-20)
| ▌row 3▐ (10, ’THOMPSON’, ’D’, 2013-12-20, 2013-12-20)
|

| The rows in STT_HISTORY contain the following information:

| Row 1 Row 1 records the history that resulted from the update statement that was

Chapter 2. Implementing your database design 75

| issued by HAAS and reflects the values of the row in the system-period
| temporal table before HAAS issued the update statement: user KWAN
| issued an insert statement (‘I’) on 15 June 2010 that set balance=1. This row
| was valid until 1 December 2011, which is the date that user HAAS issued
| the update statement that supplanted KWAN’s insert statement.
| Row 2
| Row 2 records the history that resulted from the delete statement that was
| issued by THOMPSON and reflects the values of the row in the
| system-period temporal table before THOMPSON issued the delete
| statement: user HAAS issued an update statement (‘U’) on 1 December
| 2011 that set balance=10. This row was valid until 20 December 2013,
| which is the date that THOMPSON issued the statement that deleted the
| row.
| Row 3 Because the ON DELETE ADD EXTRA ROW clause was specified in the
| definition of the system-period temporal table, row 3 was added to record
| information about the delete operation itself. Row 3 indicates that
| THOMPSON issued a delete statement (‘D’) on 20 December 2013 and that
| balance=10 at the time the row was deleted.

| Row 2 and row 3 are identical for user data (the value of the balance column). The
| difference is the auditing columns: the new generated expression columns that
| record who initiated the action and which data change operation the row
| represents.

| A SELECT statement with explicit or implicit FOR SYSTEM_TIME period

| specifications can transparently access historical data (or a combination of current
| and historical data). For this type of query, the third row in the history table is not
| included in the result.
| Related concepts:
| Temporal tables and data versioning
| Related reference:
| CREATE TABLE (Db2 SQL)
| ALTER TABLE (Db2 SQL)

Finding the name of a history table

A history table is a base table that is associated with a system-period temporal
table. A history table is used by Db2 to store the historical versions of the rows
from the associated system-period temporal table.

About this task

If you know the name of the system-period temporal table, you can find the name
of the corresponding history table.

Procedure

To find the name of a history table:

Issue a SELECT statement, such as:

76 Administration Guide
 SELECT VERSIONING_SCHEMA, VERSIONING_TABLE FROM SYSIBM.SYSTABLES WHERE
NAME = ’table-name’ AND CREATOR = ’creator-name’

Querying temporal tables

You can query a temporal table to retrieve data, based on the time criteria that you
specify.

About this task

A temporal table that includes a system period (SYSTEM_TIME) and is defined

with system-period data versioning is a system-period temporal table. A temporal
table that includes an application period (BUSINESS_PERIOD) is an
application-period temporal table.

Procedure

| To query a temporal table, use one of the following methods:

v Specify the time criteria in the query: Issue a SELECT statement, and in the
table-reference of the FROM clause, specify a period-specification. A
period-specification consists of the following clauses:
– FOR SYSTEM TIME or FOR BUSINESS TIME to indicate whether you want
to query a system-period temporal table or an application-period temporal
table
– AS OF, FROM, or BETWEEN to indicate the time criteria for which you want
data

The following example shows how you can request data, based on time criteria
from a system-period temporal table.
SELECT policy_id, coverage FROM policy_info
FOR SYSTEM_TIME AS OF ’2009-01-08-00.00.00.000000000000’;
Likewise, the following example shows how you can request data, based on
time criteria from an application-period temporal table.
SELECT policy_id, coverage FROM policy_info
FOR BUSINESS_TIME AS OF ’2008-06-01’;

If you are requesting historical data from a system-period temporal table that is
defined with system-period data versioning, Db2 rewrites the query to include
data from the history table.
| v Specify the time criteria by using special registers: The advantage of this
| method is that you can change the time criteria later and not have to modify the
| SQL and then rebind the application.
| 1. Write the SELECT statement without any time criteria specified.
| 2. When you bind the application, ensure that the appropriate bind options are
| set as follows:
| – If you are querying a system-period temporal table, ensure that
| SYSTIMESENSITIVE is set to YES.
| – If you are querying an application-period temporal table, ensure that
| BUSTIMESENSITIVE is set to YES.

Chapter 2. Implementing your database design 77

| 3. Before you call the application, set the appropriate special registers to the
| timestamp value for which you want to query data:
| – If you are querying a system-period temporal table, set CURRENT
| TEMPORAL SYSTEM_TIME.
| – If you are querying an application-period temporal table, set CURRENT
| TEMPORAL BUSINESS_TIME.

| For example, assume that you have system-period temporal table STT
| with the column POLICY_ID and you want to retrieve data from one year ago.
| You can set the CURRENT TEMPORAL SYSTEM_TIME period as follows:
| SET CURRENT TEMPORAL SYSTEM_TIME = CURRENT TIMESTAMP – 1 YEAR ;

| Then you can issue the SELECT statement:

| SELECT * FROM STT
| WHERE POLICY_ID = 123 ;

| Db2 interprets this SELECT statement as follows:

| SELECT * FROM STT
| FOR SYSTEM_TIME AS OF CURRENT TEMPORAL SYSTEM_TIME
| WHERE POLICY_ID = 123 ;

|
Related concepts:
Temporal tables and data versioning
Related reference:
from-clause (Db2 SQL)
table-reference (Db2 SQL)
BIND and REBIND options for packages, plans, and services (Db2
Commands)
CURRENT TEMPORAL BUSINESS_TIME (Db2 SQL)
CURRENT TEMPORAL SYSTEM_TIME (Db2 SQL)

Creating materialized query tables

Materialized query tables improve the performance of complex queries that operate
on very large amounts of data. Use the CREATE TABLE statement to create a
materialized query table.

About this task

Db2 uses a materialized query table to precompute the results of data that is
derived from one or more tables. When you submit a query, Db2 can use the
results that are stored in a materialized query table rather than compute the results
from the underlying source tables on which the materialized query table is defined.

Procedure

To create a new materialized query table:

Issue the CREATE TABLE statement.

78 Administration Guide
 Example

The following CREATE TABLE statement defines a materialized query table named
TRANSCNT. TRANSCNT summarizes the number of transactions in table TRANS
by account, location, and year.
CREATE TABLE TRANSCNT (ACCTID, LOCID, YEAR, CNT) AS
(SELECT ACCOUNTID, LOCATIONID, YEAR, COUNT(*)
FROM TRANS
GROUP BY ACCOUNTID, LOCATIONID, YEAR )
DATA INITIALLY DEFERRED
REFRESH DEFERRED
MAINTAINED BY SYSTEM
ENABLE QUERY OPTIMIZATION;

The fullselect, together with the DATA INITIALLY DEFERRED clause and the
REFRESH DEFERRED clause, defines the table as a materialized query table.

Related tasks:
Using materialized query tables to improve SQL performance (Db2
Performance)
Creating a materialized query table (Db2 Performance)
Registering an existing table as a materialized query table (Db2 Performance)

| Creating tables partitioned by data value ranges

| You can create tables that are partitioned based on ranges of data values. In such
| tables, each partition is defined by a limit key.

| Procedure

|
|
| To create tables that are partitioned based on ranges of data values:

| Issue a CREATE TABLE statement and specify the partitioning key column in the
| PARTITION BY clause and limit key values the PARTITION ENDING AT clauses.

| Example

| Assume that you create a large transaction table that includes the date of the
| transaction in a column named POSTED. You can specify that the transactions for
| each month are placed in separate partitions. To create the table, you can issue the
| following CREATE TABLE statement:
| CREATE TABLE TRANS
| (ACCTID ...,
| STATE ...,
| POSTED ...,
| ... , ...)
| PARTITION BY (POSTED)
| (PARTITION 1 ENDING AT (’01/31/2003’),
| PARTITION 2 ENDING AT (’02/28/2003’),
| ...
| PARTITION 13 ENDING AT (’01/31/2004’));

Chapter 2. Implementing your database design 79

| Related concepts:
| Partitioned (non-UTS) table spaces (deprecated)
| Partition-by-range table spaces
| Related tasks:
| Converting partitioned (non-UTS) table spaces to partition-by-range universal table
| spaces
| Converting table spaces to use table-controlled partitioning

Nullable partitioning columns

Db2 lets you use nullable columns as partitioning columns. The use of nullable
columns has different implications for table-controlled partitioning than for
index-controlled partitioning.

With table-controlled partitioning, Db2 can restrict the insertion of null values into
a table with nullable partitioning columns, depending on the order of the
partitioning key:
| v If the partitioning key is ascending, Db2 prevents the INSERT of a row with a
| null value for the key column, unless a partition is created that specifies
| MAXVALUE, which will hold the null values.
| v If the partitioning key is descending, Db2 prevents the INSERT of a row with a
| null value for the key column, unless a partition is created that specifies
| MINVALUE, which will hold the null values.

Example 1:

Assume that a partitioned table space is created with the following SQL
statements:
CREATE TABLESPACE TS IN DB
USING STOGROUP SG
NUMPARTS 4 BUFFERPOOL BP0;

CREATE TABLE TB (C01 CHAR(5),

C02 CHAR(5) NOT NULL,
C03 CHAR(5) NOT NULL)
IN DB.TS
PARTITION BY (C01)
PARTITION 1 ENDING AT (’10000’),
PARTITION 2 ENDING AT (’20000’),
PARTITION 3 ENDING AT (’30000’),
PARTITION 4 ENDING AT (’40000’));

| Because the CREATE TABLE statement does not specify the order in which to put
| entries, Db2 puts them in ascending order by default. Db2 subsequently prevents
| any INSERT into the TB table of a row with a null value for partitioning column
| C01, because no partition specifies MAXVALUE. If the CREATE TABLE statement
| had specified the key as descending and the first partition specified MINVALUE,
| Db2 would subsequently have allowed an INSERT into the TB table of a row with
| a null value for partitioning column C01. Db2 would have inserted the row into
| partition 1.

With index-controlled partitioning, Db2 does not restrict the insertion of null
values into a value with nullable partitioning columns.

80 Administration Guide
 Example 2: Assume that a partitioned table space is created with the following
SQL statements:
CREATE TABLESPACE TS IN DB
USING STOGROUP SG
NUMPARTS 4 BUFFERPOOL BP0;

CREATE TABLE TB (C01 CHAR(5),

C02 CHAR(5) NOT NULL,
C03 CHAR(5) NOT NULL)
IN DB.TS;

CREATE INDEX PI ON TB(C01) CLUSTER

(PARTITION 1 ENDING AT (’10000’),
PARTITION 2 ENDING AT (’20000’),
PARTITION 3 ENDING AT (’30000’),
PARTITION 4 ENDING AT (’40000’));

Regardless of the entry order, Db2 allows an INSERT into the TB table of a row
with a null value for partitioning column C01. If the entry order is ascending, Db2
inserts the row into partition 4; if the entry order is descending, Db2 inserts the
row into partition 1. Only if the table space is created with the LARGE keyword
does Db2 prevent the insertion of a null value into the C01 column.

Creating a clone table

You can create a clone table on an existing base table at the current server by using
the ALTER TABLE statement.

Before you begin

Although the ALTER TABLE syntax is used to create a clone table, the
authorization that is granted as part of the clone creation process is the same as
you would get during regular CREATE TABLE processing. The schema for the
clone table is the same as for the base table.

The base table must meet the following requirements:

v Be a universal table space
v Reside in a Db2-managed table space
v Be the only table in the table space
v Not already have a clone table defined on it
v Not be part of any referential constraints
v Not be defined with any AFTER triggers
v Not be a materialized query table
v Not be a created global temporary table or a declared global temporary table
v Not have any data sets that still need to be created. For example, you cannot
create a clone table on a base table that resides in a table space that was created
by using the DEFINE NO option and that has VSAM data sets that still need to
be created.
v Not have any pending definition changes.
| v Not have in-use table space versions or index versions. The OLDEST_VERSION
| and CURRENT_VERSION column values in the SYSIBM.SYSTABLESPACE or

Chapter 2. Implementing your database design 81

| SYSIBM.SYSIDEXES catalog tables must be identical. For information about how
| to remove in-use versions, see Removing in-use table space versions and
| Recycling index version numbers.
v Not have an incomplete definition

Also, consider the following restrictions that apply to clone tables:

v A clone table uses the statistics from the base table. RUNSTATS does not collect
statistics on a clone table, and Access Path Selection (APS) does not use
RUNSTATS statistics when accessing a clone table. This is in contrast to real-time
statistics, which keeps statistics for both the base and clone objects. Also,
autonomic statistics are not collected on a clone table.
v Catalog and directory tables cannot be cloned.
v Indexes cannot be created on a clone table. Indexes can be created on the base
table but not on the clone table. Indexes that are created on the base table apply
to both the base and clone tables.
v BEFORE triggers can be created on the base table but not on the clone table.
BEFORE triggers that are created on the base table apply to both the base and
clone tables.
v You cannot rename a base table that has a clone relationship.
v You cannot clone an RTS table.
v You cannot drop an AUX table or an AUX index on an object that is involved in
cloning.
v You cannot alter any table, or column attributes of a base table or clone table
when the objects are involved with cloning.
v The maximum number of partitions cannot be altered when a clone table resides
in a partition-by-growth table space.

Procedure

To create a clone table:

Issue the ALTER TABLE statement with the ADD CLONE option.
Creating or dropping a clone table does not impact applications that are accessing
base table data. No base object quiesce is necessary, and this process does not
invalidate packages or the dynamic statement cache.

Example

The following example shows how to create a clone table by issuing the ALTER
TABLE statement with the ADD CLONE option:
ALTER TABLE base-table-name ADD CLONE clone-table-name

Related tasks:
Exchanging data between a base table and clone table
Related reference:
ALTER TABLE (Db2 SQL)

Exchanging data between a base table and clone table

You can exchange table data and index data between the base table and clone table
by using the EXCHANGE statement.

82 Administration Guide
 Procedure

To exchange data between the base table and clone table:

Issue an EXCHANGE statement with the DATA BETWEEN TABLE table-name1

AND table-name2 syntax.
Exchanging data between the base table and the clone table does not invalidate
packages.

Example
EXCHANGE DATA BETWEEN TABLE table-name1 AND table-name2

What to do next

After a data exchange, the base and clone table names remain the same as they
were prior to the data exchange. No data movement actually takes place. The
instance numbers in the underlying VSAM data sets for the objects (tables and
indexes) do change, and this has the effect of changing the data that appears in the
base and clone tables and their indexes. For example, a base table exists with the
data set name *I0001.*. The table is cloned and the clone's data set is initially
named *.I0002.*. After an exchange, the base objects are named *.I0002.* and the
clones are named *I0001.*. Each time that an exchange happens, the instance
numbers that represent the base and the clone objects change, which immediately
changes the data contained in the base and clone tables and indexes.
Related tasks:
Creating a clone table
Related reference:
EXCHANGE (Db2 SQL)

| Creating an archive table

| You can create an archive table to manage historical data for an existing table. An
| archive table stores deleted rows from another table. That base table is called an
| archive-enabled table.

| Before you begin

| Check that the table for which you want to create an archive table meets the
| requirements that are specified in the description of the ENABLE ARCHIVE clause
| in ALTER TABLE (Db2 SQL).

| Procedure

| To create an archive table:

| 1. Create a table with the same columns as the table for which you want to
| archive data. For a complete list of requirements for archive tables, see the
| information about the ENABLE ARCHIVE clause in ALTER TABLE (Db2 SQL).

Chapter 2. Implementing your database design 83

| 2. Designate the original table as an archive-enabled table by issuing an ALTER
| TABLE statement with the ENABLE ARCHIVE clause. In that clause, specify
| the table that you created in the previous step as the archive table.
| 3. If you want rows to be automatically archived, set the global variable
| SYSIBMADM.MOVE_TO_ARCHIVE to Y or E. When this global variable is set
| to Y or E, Db2 automatically moves deleted rows to the archive table.
| Related concepts:
| Archive-enabled tables and archive tables (Introduction to Db2 for z/OS)
| Related reference:
| Built-in global variables (Db2 SQL)

Implementing Db2 views

When you design your database, you might need to give users access to only
certain pieces of data. You can give users access by designing and using views.

You can use views to perform the following tasks:

v Control access to a table
v Make data easier to use
v Simplify authorization by granting access to a view without granting access to
the table
v Show only portions of data in the table
v Show summary data for a given table
v Combine two or more tables in meaningful ways

Creating Db2 views

You can create a view on tables or on other views at the current server.

Before you begin

Before you create different column names for your view, remember the naming
conventions that you established when designing the relational database.

Procedure

To define a view:

Issue the CREATE VIEW SQL statement.

Unless you specifically list different column names after the view name, the
column names of the view are the same as those of the underlying table.

Example

Example of defining a view on a single table: Assume that you want to create a
view on the DEPT table. Of the four columns in the table, the view needs only
three: DEPTNO, DEPTNAME, and MGRNO. The order of the columns that you
specify in the SELECT clause is the order in which they appear in the view:

84 Administration Guide
CREATE VIEW MYVIEW AS
SELECT DEPTNO,DEPTNAME,MGRNO
FROM DEPT;

In this example, no column list follows the view name, MYVIEW. Therefore, the
columns of the view have the same names as those of the DEPT table on which it
is based. You can execute the following SELECT statement to see the view
contents:

SELECT * FROM MYVIEW;

The result table looks like this:

DEPTNO DEPTNAME MGRNO
====== ===================== ======
A00 CHAIRMANS OFFICE 000010
B01 PLANNING 000020
C01 INFORMATION CENTER 000030
D11 MANUFACTURING SYSTEMS 000060
E21 SOFTWARE SUPPORT ------

Example of defining a view that combines information from several tables: You
can create a view that contains a union of more than one table. Db2 provides two
types of joins—an outer join and an inner join. An outer join includes rows in
which the values in the join columns don't match, and rows in which the values
match. An inner join includes only rows in which matching values in the join
columns are returned.

The following example is an inner join of columns from the DEPT and EMP tables.
The WHERE clause limits the view to just those columns in which the MGRNO in
the DEPT table matches the EMPNO in the EMP table:

CREATE VIEW MYVIEW AS

SELECT DEPTNO, MGRNO, LASTNAME, ADMRDEPT
FROM DEPT, EMP
WHERE EMP.EMPNO = DEPT.MGRNO;

The result of executing this CREATE VIEW statement is an inner join view of two
tables, which is shown below:

Chapter 2. Implementing your database design 85

 DEPTNO MGRNO LASTNAME ADMRDEPT
====== ====== ======== ========
A00 000010 HAAS A00
B01 000020 THOMPSON A00
C01 000030 KWAN A00
D11 000060 STERN D11
Related tasks:
Altering Db2 views
Dropping Db2 views
Related reference:
CREATE VIEW (Db2 SQL)

Guidelines for view names

The name for a view is an identifier of up to 128 characters.

The following example shows a view name:

Object Name
View MYVIEW

Use the CREATE VIEW statement to define and name a view. Unless you
specifically list different column names after the view name, the column names of
the view are the same as those of the underlying table. When you create different
column names for your view, remember the naming conventions that you
established when designing the relational database.

| Querying views that reference temporal tables

| When you query a view that references a temporal table, you can specify a point in
| time or time range for a system period, an application period, or both.

| About this task

| A period specification that is after the name of a view in a table reference applies
| to all of the applicable table references in the fullselect of the definition of that
| view. If the view does not access any temporal tables, the period specification has
| no effect on the result table of the view.

| Restriction: The following restrictions apply:

| v A view reference followed by a period specification must not include any
| user-defined functions.
| v The definition of the view must not include a period specification.

| Procedure
| To query a view that references a temporal table, use one of the following
| methods:
| v Specify a period specification (either a SYSTEM_TIME period or
| BUSINESS_TIME period) following the name of a view in the FROM clause of a
| query.
| v Use the CURRENT TEMPORAL SYSTEM_TIME or CURRENT TEMPORAL
| BUSINESS_TIME special registers. In this case, you do not need to include a
| period specification in the query. For instructions on how to use these special
| registers instead of a period specification, see “Querying temporal tables” on
| page 77.

86 Administration Guide
| Example

|
|

| The following example shows how you can create a view that references a
| system-period temporal table (stt), a bitemporal table (btt), and a regular base table
| (rt). Then you can query the view based on a point in time.
| CREATE VIEW v0 (col1, col2, col3)
| AS SELECT stt.coverage, rt.id, btt.bus_end
| FROM stt, rt, btt WHERE stt.id = rt.id AND rt.id = btt.id;
|
| SELECT * FROM v0
| FOR SYSTEM_TIME AS OF TIMESTAMP '2013-01-10 10:00:00’;

|
|

| How Db2 inserts and updates data through views

After you define a view, you can refer to the name of a view in an INSERT,
UPDATE, or DELETE statement.

To ensure that the insert or update conforms to the view definition, specify the
WITH CHECK OPTION clause. The following example illustrates some
undesirable results of omitting that check.

Example 1: Suppose that you define a view, V1, as follows:

CREATE VIEW V1 AS
SELECT * FROM EMP
WHERE DEPT LIKE 'D%’;

A user with the SELECT privilege on view V1 can see the information from the
EMP table for employees in departments whose IDs begin with D. The EMP table
has only one department (D11) with an ID that satisfies the condition.

Assume that a user has the INSERT privilege on view V1. A user with both
SELECT and INSERT privileges can insert a row for department E01, perhaps
erroneously, but cannot select the row that was just inserted.

The following example shows an alternative way to define view V1.

Example 2: You can avoid the situation in which a value that does not match the
view definition is inserted into the base table. To do this, instead define view V1 to
include the WITH CHECK OPTION clause:
CREATE VIEW V1 AS SELECT * FROM EMP
WHERE DEPT LIKE 'D%’ WITH CHECK OPTION;

With the new definition, any insert or update to view V1 must satisfy the predicate
that is contained in the WHERE clause: DEPT LIKE ‘D%'. The check can be
valuable, but it also carries a processing cost; each potential insert or update must
be checked against the view definition. Therefore, you must weigh the advantage
of protecting data integrity against the disadvantage of performance degradation.

Chapter 2. Implementing your database design 87

 Dropping Db2 views
You can drop a Db2 view by removing the view at the current server.

Procedure
To drop a view:

Issue the DROP VIEW statement.

Related tasks:
Altering Db2 views
Creating Db2 views
Related reference:
DROP (Db2 SQL)

Implementing Db2 indexes

Db2 uses indexes for a variety of reasons. Db2 indexes enforce uniqueness on
column values, as in the case of parent keys. Db2 indexes are also used to cluster
data, to partition tables, to provide access paths to data, and to order retrieved
data without a sort.
Related concepts:
Indexes on table columns
Creation of indexes (Introduction to Db2 for z/OS)
Indexes that are padded or not padded (Introduction to Db2 for z/OS)
Related tasks:
Designing indexes for performance (Db2 Performance)
Compressing indexes (Db2 Performance)

Creating Db2 indexes

When you define an index, Db2 builds and maintains an ordered set of pointers to
rows of a base table or an auxiliary table.

Before you begin

Before you define an index, you need to define the table.

Procedure

To create a partitioning index, or a secondary index, and an index space at

the current server:

Issue the CREATE INDEX statement, and specify an index key.

88 Administration Guide
 Example

The following example creates a unique index on the EMPPROJACT table. A

composite key is defined on two columns, PROJNO and STDATE.
CREATE UNIQUE INDEX XPROJAC1
ON EMPPROJACT
(PROJNO ASC,
STDATE ASC)
INCLUDE(EMPNO, FIRSTNAME)

The INCLUDE clause, which is applicable only on unique indexes, specifies

additional columns that you want appended to the set of index key columns. Any
columns that are included with this clause are not used to enforce uniqueness.
These included columns might improve the performance of some queries through
index only access. Using this option might eliminate the need to access data pages
for more queries and might eliminate redundant indexes.

If you issue SELECT PROJNO, STDATE, EMPNO, and FIRSTNAME to the table on which
this index resides, all of the required data can be retrieved from the index without
reading data pages. This option might improve performance.

Related tasks:
Dropping and redefining a Db2 index
Related reference:
CREATE INDEX (Db2 SQL)

Guidelines for defining indexes

By following certain guidelines, you can successfully work with indexes.

Index names
The name for an index is an identifier of up to 128 characters. You can qualify this
name with an identifier, or schema, of up to 128 characters.

Example: The following example shows an index name:

Object Name
Index MYINDEX

The index space name is an eight-character name, which must be unique among
names of all index spaces and table spaces in the database.

Sequence of index entries

The sequence of the index entries can be in ascending order or descending order.
The ASC and DESC keywords of the CREATE INDEX statement indicate ascending
and descending order. ASC is the default.

Indexes on tables with large objects

You can use indexes on tables with LOBs the same way that you use them on
other tables, but consider the following facts:
v A LOB column cannot be a column in an index.

Chapter 2. Implementing your database design 89

 v An auxiliary table can have only one index. (An auxiliary table, which you
create by using the SQL CREATE AUXILIARY TABLE statement, holds the data
for a column that a base table defines.
v Indexes on auxiliary tables are different than indexes on base tables.

Creation of an index

If the table that you are indexing is empty, Db2 creates the index. However, Db2
does not actually create index entries until the table is loaded or rows are inserted.
If the table is not empty, you can choose to have Db2 build the index when the
CREATE INDEX statement is executed. Alternatively, you can defer the index build
until later. Optimally, you should create the indexes on a table before loading the
table. However, if your table already has data, choosing the DEFER option is
preferred; you can build the index later by using the REBUILD INDEX utility.

Copies of an index

If your index is fairly large and needs the benefit of high availability, consider
copying it for faster recovery. Specify the COPY YES clause on a CREATE INDEX
or ALTER INDEX statement to allow the indexes to be copied. Db2 can then track
the ranges of log records to apply during recovery, after the image copy of the
index is restored. (The alternative to copying the index is to use the REBUILD
INDEX utility, which might increase the amount of time that the index is
unavailable to applications.)

Deferred allocation of index space data sets

When you execute a CREATE INDEX statement with the USING STOGROUP
clause, Db2 generally defines the necessary VSAM data sets for the index space. In
some cases, however, you might want to define an index without immediately
allocating the data sets for the index space.

Example: You might be installing a software program that requires creation of

many indexes, but your company might not need some of those indexes. You
might prefer not to allocate data sets for indexes that you do not plan to use.

To defer the physical allocation of Db2-managed data sets, use the DEFINE NO
clause of the CREATE INDEX statement. When you specify the DEFINE NO
clause, Db2 defines the index but defers the allocation of data sets. The Db2
catalog table contains a record of the created index and an indication that the data
sets are not yet allocated. Db2 allocates the data sets for the index space as needed
when rows are inserted into the table on which the index is defined.
Related concepts:
Naming conventions (Db2 SQL)
Related reference:
CREATE INDEX (Db2 SQL)

How Db2 implicitly creates an index

In certain circumstances, Db2 implicitly creates the unique indexes that are used to
enforce the uniqueness of the primary keys or unique keys.

These circumstances include:

90 Administration Guide
 v When the PRIMARY KEY or UNIQUE clause is specified in the CREATE TABLE
statement and the CREATE TABLE statement is processed by the schema
processor
v When the table space that contains the table is implicitly created

When a ROWID column is defined as GENERATED BY DEFAULT in the CREATE

TABLE statement, and the CREATE TABLE statement is processed by SET
CURRENT RULES = 'STD', or the table space that contains the table is implicitly
created, Db2 implicitly creates the unique indexes used to enforce the uniqueness
of the ROWID column. The privilege set must include the USE privilege of the
buffer pool. Each index is created as if the following CREATE INDEX statement
were issued:
CREATE UNIQUE INDEX xxx ON table-name (column1,...)

Where:
v xxx is the name of the index that Db2 generates.
v table-name is the name of the table that is specified in the CREATE TABLE
statement.
v (column1,...) is the list of column names that were specified in the UNIQUE or
PRIMARY KEY clause of the CREATE TABLE statement, or the column is a
ROWID column that is defined as GENERATED BY DEFAULT.

In addition, if the table space that contains the table is implicitly created, Db2 will
check the DEFINE DATA SET subsystem parameter to determine whether to define
the underlying data set for the index space of the implicitly created index on the
base table.

If DEFINE DATA SET is NO, the index is created as if the following CREATE
INDEX statement is issued:
CREATE UNIQUE INDEX xxx ON table-name (column1,...) DEFINE NO

When you create a table and specify the organization-clause of the CREATE TABLE
statement, Db2 implicitly creates an index for hash overflow rows. This index
contains index entries for overflow rows that do not fit in the fixed hash space. If
the hash space that is specified in the organization-clause is adequate, the hash
overflow index should have no entries, or very few entries. The hash overflow
index for a table in a partition-by-range table space is a partitioned index. The
hash overflow index for a table in a partition-by-growth table space is a
non-partitioned index.

Db2 determines how much space to allocate for the hash overflow index. Because
this index will be sparsely populated, the size is relatively small compared to a
normal index.

Implementing Db2 schemas

Use schemas to provide a logical classification of objects in the database.

Creating a schema by using the schema processor

Schemas provide a logical classification of objects in the database. You can use the
schema processor to create a schema.

Chapter 2. Implementing your database design 91

 About this task

Creating a schema by using the CREATE SCHEMA statement is also supported for
compliance testing.

CREATE SCHEMA statements cannot be embedded in a host program or executed

interactively. To process the CREATE SCHEMA statement, you must use the
schema processor. The ability to process schema definitions is provided for
conformance to ISO/ANSI standards. The result of processing a schema definition
is identical to the result of executing the SQL statements without a schema
definition.

Outside of the schema processor, the order of statements is important. They must
be arranged so that all referenced objects have been previously created. This
restriction is relaxed when the statements are processed by the schema processor if
the object table is created within the same CREATE SCHEMA. The requirement
that all referenced objects have been previously created is not checked until all of
the statements have been processed. For example, within the context of the schema
processor, you can define a constraint that references a table that does not exist yet
or GRANT an authorization on a table that does not exist yet.

Procedure

To create a schema:
1. Write a CREATE SCHEMA statement.
2. Use the schema processor to execute the statement.

Example

The following example shows schema processor input that includes the definition
of a schema.
CREATE SCHEMA AUTHORIZATION SMITH

CREATE TABLE TESTSTUFF

(TESTNO CHAR(4),
RESULT CHAR(4),
TESTTYPE CHAR(3))

CREATE TABLE STAFF

(EMPNUM CHAR(3) NOT NULL,
EMPNAME CHAR(20),
GRADE DECIMAL(4),
CITY CHAR(15))

CREATE VIEW STAFFV1

AS SELECT * FROM STAFF
WHERE GRADE >= 12

GRANT INSERT ON TESTSTUFF TO PUBLIC

GRANT ALL PRIVILEGES ON STAFF

TO PUBLIC

92 Administration Guide
 Processing schema definitions
You must use the schema processor to process CREATE SCHEMA statements.

Before you begin

The schema processor sets the current SQLID to the value of the schema
authorization ID before executing any of the statements in the schema definition.
Therefore, that ID must have SYSADM or SYSCTRL authority, or it must be the
primary or one of the secondary authorization IDs of the process that executes the
schema processor. The same ID must have all the privileges that are needed to
execute all the statements in the schema definition.

Procedure

To process schema definitions:

1. Run the schema processor (DSNHSP) as a batch job. Use the sample JCL
provided in member DSNTEJ1S of the SDSNSAMP library.
The schema processor accepts only one schema definition in a single job. No
statements that are outside the schema definition are accepted. Only SQL
comments can precede the CREATE SCHEMA statement; the end of input ends
the schema definition. SQL comments can also be used within and between
SQL statements.
The processor takes the SQL from CREATE SCHEMA (the SYSIN data set),
dynamically executes it, and prints the results in the SYSPRINT data set.
2. Optional: If a statement in the schema definition has an error, the schema
processor processes the remaining statements but rolls back all the work at the
end. In this case, you need to fix the statement in error and resubmit the entire
schema definition.

Loading data into Db2 tables

You can use several methods to load data into Db2 tables.

The most common method for loading data into most of your tables is to use the
LOAD utility. This utility loads data into Db2 persistent tables from sequential data
sets by using BSAM. You can also use a cursor that is declared with an EXEC SQL
utility control statement to load data from another SQL table with the Db2 UDB
family cross-loader function. The LOAD utility cannot be used to load data into
Db2 temporary tables or system-maintained materialized query tables.

When loading tables with indexes, referential constraints, or table check

constraints, LOAD can perform several checks on the validity of data. If errors are
found, the table space that is being loaded, its index spaces, and even other table
spaces might be left in a restricted status. LOAD does not check the validity of
informational referential constraints. Plan to make necessary corrections and
remove restrictions after any LOAD job.

You can also use an SQL INSERT statement to copy all or selected rows of another
table, in any of the following methods:
v Using the INSERT statement in an application program
v Interactively through SPUFI
v With the command line processor

Chapter 2. Implementing your database design 93

 To reformat data from IMS DL/I databases and VSAM and SAM loading for the
LOAD utility, use Db2 DataPropagator.

Loading data with the LOAD utility

Use the LOAD utility to load one or more tables of a table space. If you are
loading a large number of rows, use the LOAD utility rather than inserting the
rows by using the INSERT statement.

Before you begin

Before using the LOAD utility, make sure that you complete all of the prerequisite
activities for your situation.

Procedure

To load data:

Run the LOAD utility control statement with the options that you need.

What to do next
Reset the restricted status of the table space that contains the loaded data.
Related concepts:
Before running LOAD (Db2 Utilities)
Row format conversion for table spaces
Related tasks:
Collecting statistics by using Db2 utilities (Db2 Performance)
Related reference:
LOAD (Db2 Utilities)

How the LOAD utility loads Db2 tables

Use the LOAD utility to load one or more persistent tables of a table space, or one
or more partitions of a table space. The LOAD utility operates on a table space, so
you must have authority for all tables in the table space when you run LOAD.

The LOAD utility loads records into the tables and builds or extends any indexes
defined on them. If the table space already contains data, you can choose whether
you want to add the new data to the existing data or replace the existing data.

Additionally, you can use the LOAD utility to do the following:

v Compress data and build a compression dictionary
v Convert data between compatible data types and between encoding schemes
v Load multiple tables in a single table space

Delimited input and output files

The LOAD and UNLOAD utilities can accept or produce a delimited file, which is
a sequential BSAM file with row delimiters and column delimiters. You can unload
data from other systems into one or more files that use a delimited file format and
then use these delimited files as input for the LOAD utility. You can also unload
Db2 data into delimited files by using the UNLOAD utility and then use these files
as input into another Db2 database.

94 Administration Guide
INCURSOR option

The INCURSOR option of the LOAD utility specifies a cursor for the input data
set. Use the EXEC SQL utility control statement to declare the cursor before
running the LOAD utility. You define the cursor so that it selects data from another
Db2 table. The column names in the SELECT statement must be identical to the
column names of the table that is being loaded. The INCURSOR option uses the
Db2 cross-loader function.

CCSID option

You can load input data into ASCII, EBCDIC, or Unicode tables. The ASCII,
EBCDIC, and UNICODE options on the LOAD utility statement let you specify
whether the format of the data in the input file is ASCII, EBCDIC, or Unicode. The
CCSID option of the LOAD utility statement lets you specify the CCSIDs of the
data in the input file. If the CCSID of the input data does not match the CCSID of
the table space, the input fields are converted to the CCSID of the table space
before they are loaded.

Availability during load

For nonpartitioned table spaces, data for other tables in the table space that is not
part of the table that is being loaded is unavailable to other application programs
during the load operation with the exception of LOAD SHRLEVEL CHANGE. For
partitioned table spaces, data that is in the table space that is being loaded is also
unavailable to other application programs during the load operation with the
exception of LOAD SHRLEVEL CHANGE. In addition, some SQL statements, such
as CREATE, DROP, and ALTER, might experience contention when they run
against another table space in the same Db2 database while the table is being
loaded.

Default values for columns

When you load a table and do not supply a value for one or more of the columns,
the action Db2 takes depends on the circumstances.
v If the column is not a ROWID or identity column, Db2 loads the default value of
the column, which is specified by the DEFAULT clause of the CREATE or
ALTER TABLE statement.
v If the column is a ROWID column that uses the GENERATED BY DEFAULT
option, Db2 generates a unique value.
v If the column is an identity column that uses the GENERATED BY DEFAULT
option, Db2 provides a specified value.
v With XML columns, if there is an implicitly created DOCID column in the table,
it is created with the GENERATED ALWAYS attribute.

For ROWID or identity columns that use the GENERATED ALWAYS option, you
cannot supply a value because this option means that Db2 always provides a
value.

XML columns

You can load XML documents from input records if the total input record length is
less than 32 KB. For input record length greater than 32 KB, you must load the
data from a separate file. (You can also use a separate file if the input record length
is less than 32 KB.)

Chapter 2. Implementing your database design 95

 When the XML data is to be loaded from the input record, specify XML as the
input field type. The target column must be an XML column. The LOAD utility
treats XML columns as varying-length data when loading XML directly from input
records and expects a two-byte length field preceding the actual XML value.

The XML tables are loaded when the base table is loaded. You cannot specify the
name of the auxiliary XML table to load.

XML documents must be well formed in order to be loaded.

LOB columns

The LOAD utility treats LOB columns as varying-length data. The length value for
a LOB column must be 4 bytes. The LOAD utility can be used to load LOB data if
the length of the row, including the length of the LOB data, does not exceed 32 KB.
The auxiliary tables are loaded when the base table is loaded. You cannot specify
the name of the auxiliary table to load.

Replacement or addition of data

You can use LOAD REPLACE to replace data in a single-table table space or in a
multiple-table table space. You can replace all the data in a table space (using the
REPLACE option), or you can load new records into a table space without
destroying the rows that are already there (using the RESUME option).

Loading data by using the INSERT statement

You can load data into tables is by using the INSERT statement.

Procedure

To load data into tables:

Issue an INSERT statement, and insert single or multiple rows.

What to do next

You can issue the statement interactively or embed it in an application program.

Related tasks:
Inserting multiple rows
Inserting a single row
Changing the logging attribute
Related reference:
INSERT (Db2 SQL)

Inserting a single row

The simplest form of the INSERT statement inserts a single row of data. In this
form of the statement, you specify the table name, the columns into which the data
is to be inserted, and the data itself.

Procedure

96 Administration Guide
To insert a single row:
1. Issue an INSERT INTO statement.
2. Specify the table name, the columns into which the data is to be inserted, and
the data itself.

Example

For example, suppose that you create a test table, TEMPDEPT, with the same
characteristics as the department table:
CREATE TABLE SMITH.TEMPDEPT
(DEPTNO CHAR(3) NOT NULL,
DEPTNAME VARCHAR(36) NOT NULL,
MGRNO CHAR(6) NOT NULL,
ADMRDEPT CHAR(3) NOT NULL)
IN DSN8D91A.DSN8S91D;

To now add a row to table TEMPDEPT, you can enter:

INSERT INTO SMITH.TEMPDEPT
VALUES (’X05’,’EDUCATION’,’000631’,’A01’);

What to do next

If you write an application program to load data into tables, you use that form of
INSERT, probably with host variables instead of the actual values shown in this
example.

Inserting multiple rows

You can use a form of INSERT that copies rows from another table.

Procedure

To add multiple rows to a table:

1. Issue an INSERT INTO statement. For example, the following statement loads
TEMPDEPT with data from the department table about all departments that
report to department D01.
INSERT INTO SMITH.TEMPDEPT
SELECT DEPTNO,DEPTNAME,MGRNO,ADMRDEPT
FROM DSN8910.DEPT
WHERE ADMRDEPT=’D01’;
2. Optional: Embed the INSERT statement in an application program to insert
multiple rows into a table from the values that are provided in host variable
arrays.
a. Specify the table name, the columns into which the data is to be inserted,
and the arrays that contain the data. Each array corresponds to a column.
For example, you can load TEMPDEPT with the number of rows in the host
variable num-rows by using the following embedded INSERT statement:
EXEC SQL
INSERT INTO SMITH.TEMPDEPT
FOR :num-rows ROWS
VALUES (:hva1, :hva2, :hva3, :hva4);

Chapter 2. Implementing your database design 97

 Assume that the host variable arrays hva1, hva2, hva3, and hva4 are populated
with the values that are to be inserted. The number of rows to insert must be
less than or equal to the dimension of each host variable array.

Implications of using an INSERT statement to load tables

If you plan to use the INSERT statement to load tables, you should consider some
of the implications.
v If you are inserting a large number of rows, you can use the LOAD utility.
Alternatively, use multiple INSERT statements with predicates that isolate the
data that is to be loaded, and then commit after each insert operation.
v When a table, whose indexes are already defined, is populated by using the
INSERT statement, both the FREEPAGE and the PCTFREE parameters are
ignored. FREEPAGE and PCTFREE are in effect only during a LOAD or REORG
operation.
v Set the NOT LOGGED attribute for table spaces when large volumes of data are
being inserted with parallel INSERT processes. If the data in the table space is
lost or damaged, it can be reinserted from its original source.
v You can load a value for a ROWID column with an INSERT and fullselect only
if the ROWID column is defined as GENERATED BY DEFAULT. If you have a
table with a column that is defined as ROWID GENERATED ALWAYS, you can
propagate non-ROWID columns from a table with the same definition.
v You cannot use an INSERT statement on system-maintained materialized query
tables.
v REBUILD-pending (RBDP) status is set on a data-partitioned secondary index if
you create the index after you insert a row into a table. In addition, the last
partition of the table space is set to REORG-pending (REORP) restrictive status.
v When you insert a row into a table that resides in a partitioned table space and
the value of the first column of the limit key is null, the result of the INSERT
depends on whether Db2 enforces the limit key of the last partition:
– When Db2 enforces the limit key of the last partition, the INSERT fails (if the
first column is ascending).
– When Db2 enforces the limit key of the last partition, the rows are inserted
into the first partition (if the first column is descending).
– When Db2 does not enforce the limit key of the last partition, the rows are
inserted into the last partition (if the first column is ascending) or the first
partition (if the first column is descending).
Db2 enforces the limit key of the last partition for the following table spaces:
– Table spaces using table-controlled or index-controlled partitioning that are
large (DSSIZE greater than, or equal to, 4 GB)
– Tables spaces using table-controlled partitioning that are large or non-large
(any DSSIZE)

Loading data from DL/I

You might want to convert data in IMS DL/I databases from a hierarchical
structure to a relational structure so that it can be loaded into Db2 tables.

98 Administration Guide
 Procedure

To convert the data:

Use the DataRefresher™ licensed program.

Related concepts:
Tools for moving Db2 data

Implementing Db2 stored procedures

You might choose to use stored procedures for code that is used repeatedly. Other
benefits of using stored procedures include reducing network traffic, returning
result sets to an application, or allowing access to data without granting the
privileges to the applications.

About this task

Introductory concepts
Procedures (Introduction to Db2 for z/OS)

A stored procedure is a compiled program that can execute SQL statements and is
stored at a local or remote Db2 server. You can invoke a stored procedure from an
application program or from the command line processor. A single call to a stored
procedure from a client application can access the database at the server several
times.

A typical stored procedure contains two or more SQL statements and some
manipulative or logical processing in a host language or SQL procedure
statements. You can call stored procedures from other applications or from the
command line. Db2 provides some stored procedures, but you can also create your
own.

Procedure

For detailed information about how to implement stored procedures:

See Implementing Db2 stored procedures.

Related tasks:
Creating an external stored procedure (Db2 Application programming and
SQL)
Creating an external SQL procedure (Db2 Application programming and SQL)

Creating a native SQL procedure (Db2 Application programming and SQL)

Related reference:
Procedures that are supplied with Db2 (Db2 SQL)

Creating stored procedures

The process that you follow to create a stored procedure depends on the type of
stored procedure that you want to create.

Chapter 2. Implementing your database design 99

 About this task

You can create one of the following types of stored procedures:

External stored procedures
A procedure that is written in a host language.
External SQL procedures
A procedure whose body is written entirely in SQL, but is created,
implemented, and executed like other external stored procedures.
Native SQL procedures
A procedure with a procedural body that is written entirely in SQL and is
created by issuing a single SQL statement, CREATE PROCEDURE. Native
SQL procedures do not have an associated external application program.

Procedure

To create a stored procedure:

1. Set up the stored procedure environment. This step is required for creating
external SQL procedures and external stored procedures. For native SQL
procedures this step is not required, unless the native SQL procedure calls an
external stored procedure or a user-defined function. For more information
about setting up the stored procedure environment, see Installation step 19:
Configure Db2 for running stored procedures and user-defined functions or
Migration step 25: Configure Db2 for running stored procedures and
user-defined functions in Db2 Installation Guide.
2. Create the stored procedure by following the process for the type of stored
procedure that you want to create. When you create a stored procedure, you
use the CREATE PROCEDURE statement to register a stored procedure with a
database server.

Related tasks:
Creating an external stored procedure (Db2 Application programming and
SQL)
Creating an external SQL procedure (Db2 Application programming and SQL)

Creating a native SQL procedure (Db2 Application programming and SQL)

Related reference:
CREATE PROCEDURE (Db2 SQL)
Related information:

Dropping stored procedures

Use the DROP statement to drop all versions of a stored procedure and its
associated packages at the current server.

100 Administration Guide

 About this task

You might want to drop a stored procedure for a number of reasons. You might
not use a particular stored procedure any longer, or you might want to drop a
stored procedure and re-create it. For example, you might want to migrate an
external SQL procedure to a native SQL procedure, because native SQL procedures
typically perform better and have more functionality than external SQL procedures.

Procedure

To drop a stored procedure:

Issue the DROP PROCEDURE statement, and specify the name of the stored
procedure that you want to drop.

Example
For example, to drop the stored procedure MYPROC in schema SYSPROC, issue
the following statement:
DROP PROCEDURE SYSPROC.MYPROC;

Related tasks:
Migrating an external SQL procedure to a native SQL procedure (Db2
Application programming and SQL)
Related reference:
DROP (Db2 SQL)

Implementing Db2 user-defined functions

In contrast to built-in Db2 functions, you can create and implement your own
external, sourced, or SQL functions.

Creating user-defined functions

The CREATE FUNCTION statement registers a user-defined function with a
database server.

Procedure

To create a user-defined function:

Issue the CREATE FUNCTION statement, and specify the type of function that you
want to create. You can specify the following types of functions:
v External scalar
v External table
v Sourced
v SQL scalar
Related concepts:

Chapter 2. Implementing your database design 101

 User-defined functions (Db2 SQL)
Related tasks:
Altering user-defined functions
Creating a user-defined function (Db2 Application programming and SQL)
Related reference:
CREATE FUNCTION (Db2 SQL)

Deleting user-defined functions

Use the DROP statement to delete a user-defined function at the current server.

Procedure

To delete a user-defined function:

1. Issue the DROP statement.
2. Specify FUNCTION or SPECIFIC FUNCTION.

Example

For example, drop the user-defined function ATOMIC_WEIGHT from the schema
CHEM:
DROP FUNCTION CHEM.ATOMIC_WEIGHT;

Related concepts:
User-defined functions (Db2 SQL)
Related reference:
DROP (Db2 SQL)

Estimating disk storage for user data

To properly estimate the amount of disk storage that is necessary to store your
data, you need to consider several factors.

About this task

Estimating the space requirements for Db2 objects is easier if you collect and
maintain a statistical history of those objects. The accuracy of your estimates
depends on the currentness of the statistical data.

Procedure

To estimate disk storage for user data:

Ensure that the statistics history is current by using the MODIFY STATISTICS
utility to delete outdated statistical data from the catalog history tables.
Related concepts:
General approach to estimating storage

102 Administration Guide

 Related tasks:
Collecting history statistics (Db2 Performance)
Collecting statistics history (Db2 Utilities)
Improving disk storage (Db2 Performance)
Related reference:
MODIFY STATISTICS (Db2 Utilities)

General approach to estimating storage

Estimating the space requirements for Db2 objects is easier if you collect and
maintain a statistical history of those objects.

The accuracy of your estimates depends on the currentness of the statistical data.
To ensure that the statistics history is current, use the MODIFY STATISTICS utility
to delete outdated statistical data from the catalog history tables.

The amount of disk space you need for your data is not just the number of bytes
of data; the true number is some multiple of that. That is,

space required = M
× (number of bytes of data)

The multiplier M depends on your circumstances. It includes factors that are

common to all data sets on disk, as well as others that are particular to Db2. It can
vary significantly, from a low of about 1.25 to 4.0 or more. For a first
approximation, set M=2.

Whether you use extended address volumes (EAV) is also a factor in estimating
storage. Although, the EAV factor is not a multiplier, you need to add 10 cylinders
for each object in the cylinder-managed space of an EAV. Db2 data sets might take
more space or grow faster on EAV compared to non-extended address volumes.
The reason is that the allocation unit in the extended addressing space (EAS) of
EAV is a multiple of 21 cylinders, and every allocation is rounded up to this
multiple. If you use EAV, the data set space estimation for an installation must take
this factor into account. The effect is more pronounced for smaller data sets.

For more accuracy, you can calculate M as the product of the following factors:
Record overhead
Allows for eight bytes of record header and control data, plus space
wasted for records that do not fit exactly into a Db2 page. The factor can
range from about 1.01 (for a careful space-saving design) to as great as 4.0.
A typical value is about 1.10.
Free space
Allows for space intentionally left empty to allow for inserts and updates.
You can specify this factor on the CREATE TABLESPACE statement. The
factor can range from 1.0 (for no free space) to 200 (99% of each page used
left free, and a free page following each used page). With default values,
the factor is about 1.05.
Unusable space
Track lengths in excess of the nearest multiple of page lengths. The
following table shows the track size, number of pages per track, and the
value of the unusable-space factor for several different device types.

Chapter 2. Implementing your database design 103

 Table 15. Unusable space factor by device type
Device type Track size Pages per track Factor value
3380 47476 10 1.16
3390 56664 12 1.15

Data set excess

Allows for unused space within allocated data sets, occurring as unused
tracks or part of a track at the end of any data set. The amount of unused
space depends upon the volatility of the data, the amount of space
management done, and the size of the data set. Generally, large data sets
can be managed more closely, and those that do not change in size are
easier to manage. The factor can range without limit above 1.02. A typical
value is 1.10.
Indexes
Allows for storage for indexes to data. For data with no indexes, the factor
is 1.0. For a single index on a short column, the factor is 1.01. If every
column is indexed, the factor can be greater than 2.0. A typical value is
1.20.

The following table shows calculations of the multiplier M for three different
database designs:
v The tight design is carefully chosen to save space and allows only one index on
a single, short field.
v The loose design allows a large value for every factor, but still well short of the
maximum. Free space adds 30% to the estimate, and indexes add 40%.
v The medium design has values between the other two. You might want to use
these values in an early stage of database design.

In each design, the device type is assumed to be a 3390. Therefore, the

unusable-space factor is 1.15. M is always the product of the five factors.
Table 16. Calculations for different database designs
Factor Tight design Medium design Loose design
Record overhead × 1.02 1.10 1.30
Free space × 1.00 1.05 1.30
Unusable space × 1.15 1.15 1.15
Data set excess × 1.02 1.10 1.30
Indexes = 1.02 1.20 1.40
Multiplier M 1.22 1.75 3.54

In addition to the space for your data, external storage devices are required for:
v Image copies of data sets, which can be on tape
v System libraries, system databases, and the system log
v Temporary work files for utility and sort jobs
A rough estimate of the additional external storage needed is three times the
amount calculated for disk storage.

Also, you need to add the EAV factor.

Related tasks:

104 Administration Guide

 Estimating disk storage for user data
Choosing data page sizes for LOB data (Db2 Performance)
Related information:
Calculating the space required for a table
Calculating the space required for an index

Calculating the space required for a table

The following information provides details about how to calculate the space that is
required for a table. Space allocation parameters are specified in kilobytes (KB).
v Calculations for record lengths and pages
v Estimating storage for LOBs
v Estimating storage when using the LOAD utility
Related tasks:
Compressing your data (Db2 Performance)

Calculations for record lengths and pages

In Db2, a record is the storage representation of a row. An important factor in
estimating the required amount of space for a table is the size of the records.

Records are stored within pages that are 4 KB, 8 KB, 16 KB, or 32 KB. Generally,
you cannot create a table in which the maximum record size is greater than the
page size.

Also, consider:
v Normalizing your entities
v Using larger page sizes
v Using LOB data types if a single column in a table is greater than 32 K

In addition to the bytes of actual data in the row (not including LOB and XML
data, which is not stored in the base row or included in the total length of the
row), each record has:
v A 6-byte prefix
v One additional byte for each column that can contain null values
v Two additional bytes for each varying-length column or ROWID column
v Six bytes of descriptive information in the base table for each LOB column
| v Six bytes of descriptive information in the base table for each XML column. Or,
| if the column can contain multiple versions of an XML document, then 14 bytes
| of descriptive information for each XML column.

The sum of each column's length is the record length, which is the length of data
that is physically stored in the table. You can retrieve the value of the
AVGROWLEN column in the SYSIBM.SYSTABLES catalog table to determine the
average length of rows within a table. The logical record length can be longer, for
example, if the table contains LOBs.

Every data page has:

v A 22-byte header
v A 2-byte directory entry for each record that is stored in the page

Chapter 2. Implementing your database design 105

 The maximum space available to store records in a 4 KB page is 4056 bytes.
Achieving that maximum in practice is not always simple. For example, if you are
using the default values, the LOAD utility leaves approximately 5 percent of a
page as free space when loading more than one record per page. Therefore, if two
records are to fit in a page, each record cannot be longer than 1927 bytes
(approximately 0.95 × 4056 × 0.5).

Furthermore, the page size of the table space in which the table is defined limits
the record length. If the table space is 4 KB, the record length of each record cannot
be greater than 4056 bytes. Because of the eight-byte overhead for each record, the
sum of column lengths cannot be greater than 4048 bytes (4056 minus the
eight-byte overhead for a record).

Db2 provides three larger page sizes to allow for longer records. You can improve
performance by using pages for record lengths that best suit your needs.

As shown in the following table, the maximum record size for each page size
depends on the size of the table space, whether the table is enabled for hash
access, and whether you specified the EDITPROC clause.
Table 17. Maximum record size (in bytes)
Table type 4 KB page 8 KB page 16 KB page 32 KB page
Non-hash table 4056 8138 16330 32714
Non-hash table 4046 8128 16320 32704
with EDITPROC
Hash table (hash 3817 7899 16091 32475
home page)
Hash table with 3807 7889 16081 32465
EDITPROC (hash
home page)

Creating a table using CREATE TABLE LIKE in a table space of a larger page size
changes the specification of LONG VARCHAR to VARCHAR and LONG
VARGRAPHIC to VARGRAPHIC. You can also use CREATE TABLE LIKE to create
a table with a smaller page size in a table space if the maximum record size is
within the allowable record size of the new table space.

Related concepts:
XML versions (Db2 Programming for XML)
General approach to estimating storage

Estimating storage for LOBs

Before calculating the storage that is required for LOB table spaces, you must
understand the size restrictions for large object (LOBs) data types.

About this task

Tables with LOBs can store byte strings up to 2 GB. A base table can be defined
with one or more LOB columns. The LOB columns are logically part of the base

106 Administration Guide

table but are physically stored in an auxiliary table. In place of each LOB column,
there is an indicator column, which is a column with descriptive information about
the LOB. When a base table has LOB columns, then each row of the table has a row
identifier, which is a varying-length 17-byte field. You must consider the overhead
of the indicator column and row identifiers when estimating table size. If the LOB
column is NULL or has a value of zero, no space is allocated in the auxiliary table.

Procedure

To estimate the storage required for LOB table spaces, complete the following
steps:
1. Begin with your estimates from other table spaces
2. Round the figure up to the next page size
3. Multiply the figure by 1.1

What to do next

An auxiliary table resides in a LOB table space. There can be only one auxiliary
table in a LOB table space. An auxiliary table can store only one LOB column of a
base table and there must be one and only one index on this column.

One page never contains more than one LOB. When a LOB value is deleted, the
space occupied by that value remains allocated as long as any application might
access that value.

When a LOB table space grows to its maximum size, no more data can be inserted
into the table space or its associated base table.

Estimating storage when using the LOAD utility

You must complete several calculations to estimate the storage that is required for
a table to be loaded by the LOAD utility.

About this task

For a table to be loaded by the LOAD utility, assume the following values:
v Let FLOOR be the operation of discarding the decimal portion of a real number.
v Let CEILING be the operation of rounding a real number up to the next highest
integer.
v Let number of records be the total number of records to be loaded.
v Let average record size be the sum of the lengths of the fields in each record,
using an average value for varying-length fields, and including the following
amounts for overhead:
– 8 bytes for the total record
– 1 byte for each field that allows nulls
– 2 bytes for each varying-length field
v Let percsave be the percentage of kilobytes saved by compression (as reported by
the DSN1COMP utility in message DSN1940I)
v Let compression ratio be percsave/100

Procedure

To calculate the storage required when using the LOAD utility, complete the
following steps:
1. Calculate the usable page size.
Chapter 2. Implementing your database design 107
 Usable page size is the page size minus a number of bytes of overhead (that is, 4
KB - 40 for 4 KB pages, 8 KB - 54 for 8 KB pages, 16 KB - 54 for 16 KB pages,
or 32 KB - 54 for 32 KB pages) multiplied by (100-p) / 100, where p is the value
of PCTFREE.
If your average record size is less than 16, then usable page size is 255
(maximum records per page) multiplied by average record size multiplied by
(100-p) / 100.
2. Calculate the records per page.
Records per page is MIN(MAXROWS, FLOOR(usable page size / average record
size)), but cannot exceed 255 and cannot exceed the value you specify for
MAXROWS.
3. Calculate the pages used.
Pages used is 2+CEILING(number of records / records per page).
4. Calculate the total pages used.
Total pages is FLOOR(pages used× (1+fp ) / fp ), where fp is the (nonzero) value
of FREEPAGE. If FREEPAGE is 0, then total pages is equal to pages used.
If you are using data compression, you need additional pages to store the
dictionary.
5. Estimate the number of kilobytes required for a table.
v If you do not use data compression, the estimated number of kilobytes is
total pages× page size (4 KB, 8 KB, 16 KB, or 32 KB).
v If you use data compression, the estimated number of kilobytes is total
pages× page size (4 KB, 8 KB, 16 KB, or 32 KB) × (1 - compression ratio).

Example

For example, consider a table space containing a single table with the following
characteristics:
v Number of records = 100000
v Average record size = 80 bytes
v Page size = 4 KB
v PCTFREE = 5 (5% of space is left free on each page)
v FREEPAGE = 20 (one page is left free for each 20 pages used)
v MAXROWS = 255

If the data is not compressed, you get the following results:

v Usable page size = 4056 × 0.95 = 3853 bytes
v Records per page = MIN(MAXROWS, FLOOR(3853 / 80)) = 48
v Pages used = 2 + CEILING(100000 / 48) = 2085
v Total pages = FLOOR(2085 × 21 / 20) = 2189
v Estimated number of kilobytes = 2189 × 4 = 8756

If the data is compressed, multiply the estimated number of kilobytes for an

uncompressed table by (1 - compression ratio) for the estimated number of kilobytes
required for the compressed table.
Related tasks:
Calculating the space that is required for a dictionary (Db2 Performance)
Related reference:
LOAD (Db2 Utilities)

108 Administration Guide

Calculating the space required for an index
The following information provides details about how to calculate the space that is
required for an index.
v Levels of index pages
v Estimating storage from the number of index pages

Space allocation parameters are specified in kilobytes (KB).

Levels of index pages

Indexes can have more than one level of pages. An index that is built by the
LOAD utility requires a certain amount of storage, which depends on the number
of index pages at all levels. The number of index pages at all levels depends on
whether the index is unique.

Index pages that point directly to the data in tables are called leaf pages and are
said to be on level 0. In addition to data pointers, leaf pages contain the key and
record-ID (RID).

If an index has more than one leaf page, it must have at least one nonleaf page
that contains entries that point to the leaf pages. If the index has more than one
nonleaf page, then the nonleaf pages whose entries point to leaf pages are said to
be on level 1. If an index has a second level of nonleaf pages whose entries point to
nonleaf pages on level 1, then those nonleaf pages are said to be on level 2, and so
on. The highest level of an index contains a single page, which Db2 creates when it
first builds the index. This page is called the root page. The root page is a 4-KB
index page. The following figure shows, in schematic form, a typical index.

Root Page

Page A Highest key of page A

Level 2 Page B Highest key of page B

Nonleaf Page A Nonleaf Page B

Page 1 Highest key of page 1

Level 1

Page X Highest key of page X Page Z Highest key of page Z

Leaf Page 1 Leaf Page X Leaf Page Z

Level 0
Key Record-ID Key Record-ID Key Record-ID

Table Row

Row Row

Figure 17. Sample index structure and pointers (three-level index)

If you insert data with a constantly increasing key, Db2 adds the new highest key
to the top of a new page. Be aware, however, that Db2 treats nulls as the highest
value. When the existing high key contains a null value in the first column that

Chapter 2. Implementing your database design 109

 differentiates it from the new key that is inserted, the inserted non-null index
entries cannot take advantage of the highest-value split.

Estimating storage from the number of index pages

Before you run a LOAD utility job to load an index, estimate the future storage
requirements of the index.

About this task

An index key on an auxiliary table used for LOBs is 19 bytes and uses the same
formula as other indexes. The RID value stored within the index is 5 bytes, the
same as for large table spaces (defined with DSSIZE greater than or equal to 4 GB).

In general, the length of the index key is the sum of the lengths of all the columns
of the key, plus the number of columns that allow nulls. The length of a
varying-length column is the maximum length if the index is padded. Otherwise, if
an index is not padded, estimate the length of a varying-length column to be the
average length of the column data, and add a two-byte length field to the estimate.
You can retrieve the value of the AVGKEYLEN column in the
SYSIBM.SYSINDEXES catalog table to determine the average length of keys within
an index.

The following index calculations are intended only to help you estimate the storage
required for an index. Because there is no way to predict the exact number of
duplicate keys that can occur in an index, the results of these calculations are not
absolute. It is possible, for example, that for a nonunique index, more index entries
than the calculations indicate might be able to fit on an index page.

Important: Space allocation parameters are specified in kilobytes.

In the following calculations, assume the following:

k The length of the index key.
n The average number of data records per distinct key value of a nonunique
index. For example:
v a = number of data records per index
v b = number of distinct key values per index
v n=a/b
f The value of PCTFREE.
p The value of FREEPAGE.
r The record identifier (RID) length. Let r = 4 for indexes on non-large table
spaces and r = 5 for indexes on large table spaces (defined with DSSIZE
greater than or equal to 4 GB) and on auxiliary tables.
S The value of the page size minus the length of the page header and page
tail.
FLOOR
The operation of discarding the decimal portion of a real number.
CEILING
The operation of rounding a real number up to the next highest integer.
MAX The operation of selecting the highest integer value.

110 Administration Guide

Procedure

To estimate index storage size, complete the following calculations:

1. Calculate the pages for a unique index.
a. Calculate the total leaf pages
1) Calculate the space per key
space per key is approximately k + r + 3
2) Calculate the usable space per page
usable space per page is approximately FLOOR((100 - f)× S / 100)
3) Calculate the entries per page
entries per page is approximately FLOOR(usable space per page / space per
key)
4) Calculate the total leaf pages
total leaf pages is approximately CEILING(number of table rows / entries
per page)
b. Calculate the total nonleaf pages
1) Calculate the space per key
space per key is approximately k + 7
2) Calculate the usable space per page
usable space per page is approximately FLOOR(MAX(90, (100 - f ))× S
/100)
3) Calculate the entries per page
entries per page is approximately FLOOR(usable space per page / space per
key)
4) Calculate the minimum child pages
minimum child pages is approximately MAX(2, (entries per page + 1))
5) Calculate the level 2 pages
level 2 pages is approximately CEILING(total leaf pages / minimum child
pages)
6) Calculate the level 3 pages
level 3 pages is approximately CEILING(level 2 pages / minimum child
pages)
7) Calculate the level x pages
level x pages is approximately CEILING(previous level pages / minimum
child pages)
8) Calculate the total nonleaf pages
total nonleaf pages is approximately (level 2 pages + level 3 pages + ...+ level
x pages until the number of level x pages = 1)
2. Calculate the pages for a nonunique index.
a. Calculate the total leaf pages
1) Calculate the space per key
space per key is approximately 4 + k + (n × (r+1))
2) Calculate the usable space per page
usable space per page is approximately FLOOR((100 - f )× S / 100)
3) Calculate the key entries per page
key entries per page is approximately n× (usable space per page / space per
key)
4) Calculate the remaining space per page
remaining space per page is approximately usable space per page - (key
entries per page / n)×space per key
5) Calculate the data records per partial entry

Chapter 2. Implementing your database design 111

 data records per partial entry is approximately FLOOR((remaining space per
page - (k + 4)) / 5)
6) Calculate the partial entries per page
partial entries per page is approximately (n / CEILING(n / data records per
partial entry)) if data records per partial entry >= 1, or 0 if data records per
partial entry < 1
7) Calculate the entries per page
entries per page is approximately MAX(1, (key entries per page + partial
entries per page))
8) Calculate the total leaf pages
total leaf pages is approximately CEILING(number of table rows / entries
per page)
b. Calculate the total nonleaf pages
1) Calculate the space per key
space per key is approximately k + r + 7
2) Calculate the usable space per page
usable space per page is approximately FLOOR (MAX(90, (100- f))× S /
100)
3) Calculate the entries per page
entries per page is approximately FLOOR((usable space per page / space per
key)
4) Calculate the minimum child pages
minimum child pages is approximately MAX(2, (entries per page + 1))
5) Calculate the level 2 pages
level 2 pages is approximately CEILING(total leaf pages / minimum child
pages)
6) Calculate the level 3 pages
level 3 pages is approximately CEILING(level 2 pages / minimum child
pages)
7) Calculate the level x pages
level x pages is approximately CEILING(previous level pages / minimum
child pages)
8) Calculate the total nonleaf pages
total nonleaf pages is approximately (level 2 pages + level 3 pages + ...+ level
x pages until x = 1)
3. Calculate the pages for an index that is not compressed.
a. Calculate the usable space per leaf page:
usable space per leaf page is approximately FLOOR((100 - f) × S / 100)
| The page size can be 4096 bytes (4 KB), 8192 bytes (8 KB), 16384 bytes (16
| KB), or 32768 bytes (32 KB). The length of the page header is 62 bytes. The
| length of the page tail is 20 bytes for 10-byte RBA or LRSN format, or 2
| bytes for 6-byte RBA or LRSN format.
b. Calculate the usable space per nonleaf page:
usable space per nonleaf page is approximately FLOOR (MAX (90, (100 - f ) ) ×
S / 100)
| The page size can be 4096 bytes (4 KB), 8192 bytes (8 KB), 16384 bytes (16
| KB), or 32768 bytes (32 KB). The length of the page header is 48 bytes. The
| length of the page tail is 20 bytes for 10-byte RBA or LRSN format, or 2
| bytes for 6-byte RBA or LRSN format.
c. Calculate the usable space per space map:

112 Administration Guide

 usable space per space map is approximately CEILING ( (tree pages + free pages)
/ S), where S equals (page size − header length − tail length) * 2 − 1.
| The page size can be 4096 bytes (4 KB), 8192 bytes (8 KB), 16384 bytes (16
| KB), or 32768 bytes (32 KB). The length of the page header is 28 bytes. The
| length of the page tail is 20 bytes for 10-byte RBA or LRSN format, or 2
| bytes for 6-byte RBA or LRSN format.
4. Calculate the pages for a compressed index.
a. Calculate the usable space per leaf page:
usable space per leaf page is approximately FLOOR((100 - f) × S / 100)
| The page size can be 4096 bytes (4 KB), 8192 bytes (8 KB), 16384 bytes (16
| KB), or 32768 bytes (32 KB). The length of the page header is 66 bytes. The
| length of the page tail is 20 bytes for 10-byte RBA or LRSN format, or 2
| bytes for 6-byte RBA or LRSN format.
b. Calculate the usable space per nonleaf page:
usable space per nonleaf page is approximately FLOOR (MAX (90, (100 - f ) ) ×
S / 100)
| The page size is 4096 bytes for 4 KB, 8 KB, 16 KB, and 32 KB page sizes.
| The length of the page header is 48 bytes. The length of the page tail is 20
| bytes for 10-byte RBA or LRSN format, or 2 bytes for 6-byte RBA or LRSN
| format.
c. Calculate the usable space per space map:
usable space per space map is approximately CEILING ( (tree pages + free
pages) / S), where S equals (page size − header length − tail length) * 2 − 1.
The page size is 4096 bytes for 4 KB, 8 KB, 16 KB, and 32 KB page sizes.
The length of the page header is 28 bytes, and the length of the page tail is
2 bytes.
5. Calculate the total space requirement by estimating the number of kilobytes
required for an index built by the LOAD utility.
a. Calculate the free pages
free pages is approximately FLOOR(total leaf pages / p), or 0 if p = 0
b. Calculate the space map pages
space map pages is approximately CEILING((tree pages + free pages) / S)
c. Calculate the tree pages
tree pages is approximately MAX(2, (total leaf pages + total nonleaf pages))
d. Calculate the total index pages
total index pages is approximately MAX(4, (1 + tree pages + free pages + space
map pages))
e. Calculate the total space requirement
total space requirement is approximately 4× (total index pages + 2)

Example

In the following example of the entire calculation, assume that an index is defined
with these characteristics:
v The index is unique.
v The table it indexes has 100000 rows.
v The key is a single column defined as CHAR(10) NOT NULL.
v The value of PCTFREE is 5.
v The value of FREEPAGE is 4.
v The page size is 4 KB.

Chapter 2. Implementing your database design 113

 Table 18. Sample of the total space requirement for a unique index
Quantity Calculation Result

Length of key k 10
Average number of duplicate keys n 1
PCTFREE f 5
FREEPAGE p 4

| Calculate total leaf pages

| Space per key k + 7 17
| Usable space per page FLOOR((100 - f ) × 4032/100) 3844
| Entries per page FLOOR(usable space per page / space per key) 225
|
| Total leaf pages CEILING(number of table rows / entries per page) 445

Calculate total nonleaf pages

Space per key k + 7 17
Usable space per page FLOOR(MAX(90, (100 - f )) × 4046/100) 3843
Entries per page FLOOR(usable space per page / space per key) 226
Minimum child pages MAX(2, (entries per page + 1)) 227
Level 2 pages CEILING(total leaf pages / minimum child pages) 2
Level 3 pages CEILING(level 2 pages / minimum child pages) 1

Total nonleaf pages (level 2 pages + level 3 pages +...+ level x pages until x = 1) 3

Calculate total space required

Free pages FLOOR(total leaf pages / p), or 0 if p = 0 111
Tree pages MAX(2, (total leaf pages + total nonleaf pages)) 448
Space map pages CEILING((tree pages + free pages)/8131) 1
Total index pages MAX(4, (1 + tree pages + free pages + space map pages)) 561

TOTAL SPACE REQUIRED, in KB 4 × (total index pages + 2) 2252

114 Administration Guide

Chapter 3. Altering your database design
After using a relational database for a while, you might want to change some
aspects of its design.

To alter the database design you need to change the definitions of Db2 objects.

If possible, use the following SQL ALTER statements to change the definitions of
Db2 objects.

When you cannot make changes with ALTER statements, you typically must use
the following process:
1. Use the DROP statement to remove the object.
Attention: The DROP statement has a cascading effect. Objects that are
dependent on the dropped object are also dropped. For example, all authorities
for those objects disappear, and packages that reference deleted objects are
marked invalid by Db2.
2. Use the COMMIT statement to commit the changes to the object.
3. Use the CREATE statement to re-create the object.
Related concepts:
Implementing your database design
Related reference:
Statements (Db2 SQL)
DROP (Db2 SQL)
COMMIT (Db2 SQL)

Using the catalog in database design

Retrieving information from the catalog by using SQL statements, can be helpful in
designing your relational database.

For a list of Db2 catalog tables and descriptions of the information that they
contain, see Db2 catalog tables (Db2 SQL).

The information in the catalog is vital to normal Db2 operation. You can retrieve
catalog information, but changing it can have serious consequences. Therefore you
cannot execute insert or delete operations that affect the catalog, and only a limited
number of columns exist that you can update. Exceptions to these restrictions are
the SYSIBM.SYSSTRINGS, SYSIBM.SYSCOLDIST, and SYSIBM.SYSCOLDISTSTATS
catalog tables, into which you can insert rows and proceed to update and delete
rows.

To retrieve information from the catalog, you need at least the SELECT privilege
on the appropriate catalog tables.

Note: Some catalog queries can result in long table space scans.

© Copyright IBM Corp. 1982, 2017 115

 Retrieving catalog information about Db2 storage groups
The SYSIBM.SYSSTOGROUP and SYSIBM.SYSVOLUMES tables contain
information about Db2 storage groups and the volumes in those storage groups.

Procedure

To obtain information about Db2 storage groups and the volumes in those storage
groups:

Query the SYSIBM.SYSSTOGROUP and SYSIBM.SYSVOLUMES tables. The

following query shows what volumes are in a Db2 storage group, how much space
is used, and when that space was last calculated.
SELECT SGNAME,VOLID,SPACE,SPCDATE
FROM SYSIBM.SYSVOLUMES,SYSIBM.SYSSTOGROUP
WHERE SGNAME=NAME
ORDER BY SGNAME;

Related reference:
SYSSTOGROUP catalog table (Db2 SQL)
SYSVOLUMES catalog table (Db2 SQL)

Retrieving catalog information about a table

The SYSIBM.SYSTABLES table contains information about every table, view, and
alias in your Db2 system.

About this task

The SYSIBM.SYSTABLES table contains a row for every table, view, and alias in
your Db2 system. Each row tells you whether the object is a table, a view, or an
alias, its name, who created it, what database it belongs to, what table space it
belongs to, and other information. The SYSTABLES table also has a REMARKS
column in which you can store your own information about the table in question.

Procedure

To retrieve catalog information about a table:

Query the SYSIBM.SYSTABLES table. The following example query displays all the
information for the project activity sample table:
SELECT *
FROM SYSIBM.SYSTABLES
WHERE NAME = ’PROJACT’
AND CREATOR = ’DSN8B10’;

116 Administration Guide

 Related concepts:
Adding and retrieving comments
Related reference:
SYSTABLES catalog table (Db2 SQL)

Retrieving catalog information about partition order

The LOGICAL_PART column in the SYSIBM.SYSTABLEPART table contains
information for key order or logical partition order.

Procedure

To retrieve catalog information about partition order:

Query the SYSIBM.SYSTABLEPART table. The following statement displays

information on partition order in ascending limit value order:
SELECT LIMITKEY, PARTITION
FROM SYSIBM.SYSTABLEPART
ORDER BY LOGICAL_PART;

Related reference:
SYSTABLEPART catalog table (Db2 SQL)

Retrieving catalog information about aliases

Query SYSIBM.SYSTABLES to obtain information about aliases.

About this task

You can use the SYSIBM.SYSTABLES table to find information about aliases by
referencing the following three columns:
v LOCATION contains your subsystem's location name for the remote system, if
the object on which the alias is defined resides at a remote subsystem.
v TBCREATOR contains the schema table or view.
v TBNAME contains the name of the table or the view.

You can also find information about aliases by using the following user-defined
functions:
v TABLE_NAME returns the name of a table, view, or undefined object found
after resolving aliases for a user-specified object.
v TABLE_SCHEMA returns the schema name of a table, view, or undefined object
found after resolving aliases for a user-specified object.

Chapter 3. Altering your database design 117

 v TABLE_LOCATION returns the location name of a table, view, or undefined
object found after resolving aliases for a user-specified object.

The NAME and CREATOR columns of the SYSTABLES table contain the name and
schema of the alias, and three other columns contain the following information for
aliases:
v TYPE is A.
v DBNAME is DSNDB06.
v TSNAME is SYSTSTAB.

If similar tables at different locations have names with the same second and third
parts, you can retrieve the aliases for them with a query like this one:
SELECT LOCATION, CREATOR, NAME
FROM SYSIBM.SYSTABLES
WHERE TBCREATOR=’DSN8B10’ AND TBNAME=’EMP’
AND TYPE=’A’;

Related reference:
SYSTABLES catalog table (Db2 SQL)
TABLE_NAME (Db2 SQL)
TABLE_SCHEMA (Db2 SQL)
TABLE_LOCATION (Db2 SQL)

Retrieving catalog information about columns

The SYSIBM.SYSCOLUMNS table has one row for each column of every table and
view.

Procedure

To obtain information about the columns of a table or view:

Query the SYSIBM.SYSCOLUMNS table.

The following statement retrieves information about columns in the sample
department table:
SELECT NAME, TBNAME, COLTYPE, LENGTH, NULLS, DEFAULT
FROM SYSIBM.SYSCOLUMNS
WHERE TBNAME=’DEPT’
AND TBCREATOR = ’DSN8B10’;

The result is shown below; for each column, the following information about each
column is given:
v The column name
v The name of the table that contains it
v Its data type
v Its length attribute. For LOB columns, the LENGTH column shows the length of
the pointer to the LOB.
v Whether it allows nulls
v Whether it allows default values

118 Administration Guide

 NAME TBNAME COLTYPE LENGTH NULLS DEFAULT
DEPTNO DEPT CHAR 3 N N
DEPTNAME DEPT VARCHAR 36 N N
MGRNO DEPT CHAR 6 Y N
ADMRDEPT DEPT CHAR 3 N N

Related tasks:
Retrieving catalog information about LOBs
Related reference:
SYSCOLUMNS catalog table (Db2 SQL)

Retrieving catalog information about indexes

The SYSIBM.SYSINDEXES table contains a row for every index, including indexes
on catalog tables.

Procedure

To obtain information about indexes:

Query the SYSIBM.SYSINDEXES table. For example, to retrieve a row about an

index named XEMPL2:
SELECT *
FROM SYSIBM.SYSINDEXES
WHERE NAME = ’XEMPL2’
AND CREATOR = ’DSN8B10’;

A table can have more than one index. To display information about all the indexes
of a table:
SELECT *
FROM SYSIBM.SYSINDEXES
WHERE TBNAME = ’EMP’
AND TBCREATOR = ’DSN8B10’;

Related reference:
SYSINDEXES catalog table (Db2 SQL)

Retrieving catalog information about views

For every view you create, Db2 stores descriptive information in several catalog
tables. Query these catalog tables to obtain information about views in your
database.

About this task

The following actions occur in the catalog after the execution of CREATE VIEW:

Chapter 3. Altering your database design 119

 v A row is inserted into the SYSIBM.SYSTABLES table.
v A row is inserted into the SYSIBM.SYSTABAUTH table to record the owner's
privileges on the view.
v For each column of the view, a row is inserted into the SYSIBM.SYSCOLUMNS
table.
v One or more rows are inserted into the SYSIBM.SYSVIEWS table to record the
text of the CREATE VIEW statement.
v For each table or view on which the view is dependent, a row is inserted into
the SYSIBM.SYSVIEWDEP table to record the dependency.

Procedure

To obtain information about views:

Query one or more catalog tables.

Related reference:
CREATE VIEW (Db2 SQL)
SYSTABLES catalog table (Db2 SQL)
SYSTABAUTH catalog table (Db2 SQL)
SYSCOLUMNS catalog table (Db2 SQL)
SYSVIEWS catalog table (Db2 SQL)
SYSVIEWDEP catalog table (Db2 SQL)

Retrieving catalog information about authorizations

The SYSIBM.SYSTABAUTH table contains information about who can access your
data.

Procedure

To obtain information about who can access your data:

Query the SYSIBM.SYSTABAUTH table. The following query retrieves the names
of all users who have been granted access to the DSN8B10.DEPT table.
SELECT GRANTEE
FROM SYSIBM.SYSTABAUTH
WHERE TTNAME = ’DEPT’
AND GRANTEETYPE <> ’P’
AND TCREATOR = ’DSN8B10’;

GRANTEE is the name of the column that contains authorization IDs for users of
tables. The TTNAME and TCREATOR columns specify the DSN8B10.DEPT table.
The clause GRANTEETYPE <> 'P' ensures that you retrieve the names only of
users (not application plans or packages) that have authority to access the table.

120 Administration Guide

 Related reference:
SYSTABAUTH catalog table (Db2 SQL)

Retrieving catalog information about primary keys

The SYSIBM.SYSCOLUMNS table identifies columns of a primary key in column
KEYSEQ; a nonzero value indicates the place of a column in the primary key.

Procedure

To obtain catalog information about primary keys:

Query the SYSIBM.SYSCOLUMNS table. To retrieve the creator, database, and

names of the columns in the primary key of the sample project activity table using
SQL statements, execute:
SELECT TBCREATOR, TBNAME, NAME, KEYSEQ
FROM SYSIBM.SYSCOLUMNS
WHERE TBCREATOR = ’DSN8B10’
AND TBNAME = ’PROJACT’
AND KEYSEQ > 0
ORDER BY KEYSEQ;

The SYSIBM.SYSINDEXES table identifies the primary index of a table by the

value P in column UNIQUERULE. To find the name, creator, database, and index
space of the primary index on the project activity table, execute:
SELECT TBCREATOR, TBNAME, NAME, CREATOR, DBNAME, INDEXSPACE
FROM SYSIBM.SYSINDEXES
WHERE TBCREATOR = ’DSN8B10’
AND TBNAME = ’PROJACT’
AND UNIQUERULE = ’P’;

Related reference:
SYSCOLUMNS catalog table (Db2 SQL)
SYSINDEXES catalog table (Db2 SQL)

Retrieving catalog information about foreign keys

The SYSIBM.SYSRELS and SYSIBM.SYSFOREIGNKEYS tables contain information
about referential constraints and the columns of the foreign key that defines the
constraint.

About this task

The SYSIBM.SYSRELS table contains information about referential constraints, and

each constraint is uniquely identified by the schema and name of the dependent
table and the constraint name (RELNAME). The SYSIBM.SYSFOREIGNKEYS table
contains information about the columns of the foreign key that defines the
constraint.

Chapter 3. Altering your database design 121

 Procedure

To obtain information about referential constraints and the columns of the foreign
key that defines the constraint:

Query the SYSIBM.SYSRELS table or the SYSIBM.SYSFOREIGNKEYS table. To

retrieve the constraint name, column names, and parent table names for every
relationship in which the project table is a dependent, execute:
SELECT A.CREATOR, A.TBNAME, A.RELNAME, B.COLNAME, B.COLSEQ,
A.REFTBCREATOR, A.REFTBNAME
FROM SYSIBM.SYSRELS A, SYSIBM.SYSFOREIGNKEYS B
WHERE A.CREATOR = ’DSN8B10’
AND B.CREATOR = ’DSN8B10’
AND A.TBNAME = ’PROJ’
AND B.TBNAME = ’PROJ’
AND A.RELNAME = B.RELNAME
ORDER BY A.RELNAME, B.COLSEQ;

To find information about the foreign keys of tables to which the project table is a
parent:
SELECT A.RELNAME, A.CREATOR, A.TBNAME, B.COLNAME, B.COLNO
FROM SYSIBM.SYSRELS A, SYSIBM.SYSFOREIGNKEYS B
WHERE A.REFTBCREATOR = ’DSN8B10’
AND A.REFTBNAME = ’PROJ’
AND A.RELNAME = B.RELNAME
ORDER BY A.RELNAME, B.COLNO;

Related reference:
SYSRELS catalog table (Db2 SQL)
SYSFOREIGNKEYS catalog table (Db2 SQL)

Retrieving catalog information about check pending

The SYSIBM.SYSTABLESPACE table contains information about table spaces that
are in check-pending status.

About this task

The SYSIBM.SYSTABLESPACE table indicates that a table space is in

check-pending status by a value in column STATUS: P if the entire table space has
that status, S if the status has a scope of less than the entire space.

Procedure

To obtain information about table spaces that are in check-pending status:

Query the SYSIBM.SYSTABLESPACE table. To list all table spaces whose use is
restricted for any reason, issue this command:
-DISPLAY DATABASE (*) SPACENAM(*) RESTRICT

122 Administration Guide

 To retrieve the names of table spaces in check-pending status only, with the names
of the tables they contain, execute:
SELECT A.DBNAME, A.NAME, B.CREATOR, B.NAME
FROM SYSIBM.SYSTABLESPACE A, SYSIBM.SYSTABLES B
WHERE A.DBNAME = B.DBNAME
AND A.NAME = B.TSNAME
AND (A.STATUS = ’P’ OR A.STATUS = ’S’)
ORDER BY 1, 2, 3, 4;

Related reference:
SYSTABLESPACE catalog table (Db2 SQL)

Retrieving catalog information about check constraints

The SYSIBM.SYSCHECKS and SYSIBM.SYSCHECKDEP tables contain information
about check constraints.

About this task

Information about check constraints is stored in the Db2 catalog in:

v SYSIBM.SYSCHECKS, which contains one row for each check constraint defined
on a table
v SYSIBM.SYSCHECKDEP, which contains one row for each reference to a column
in a check constraint

Procedure

To retrieve catalog information about check constraints:

Query the SYSIBM.SYSCHECKS and SYSIBM.SYSCHECKDEP tables. The

following query shows all check constraints on all tables named SIMPDEPT and
SIMPEMPL in order by column name within table schema. It shows the name,
authorization ID of the creator, and text for each constraint. A constraint that uses
more than one column name appears more than once in the result.
CREATE TABLE SIMPDEPT
(DEPTNO CHAR(3) NOT NULL,
DEPTNAME VARCHAR(12) CONSTRAINT CC1 CHECK (DEPTNAME IS NOT NULL),
MGRNO CHAR(6),
MGRNAME CHAR(6));
SELECT A.TBOWNER, A.TBNAME, B.COLNAME,
A.CHECKNAME, A.CREATOR, A.CHECKCONDITION
FROM SYSIBM.SYSCHECKS A, SYSIBM.SYSCHECKDEP B
WHERE A.TBOWNER = B.TBOWNER
AND A.TBNAME = B.TBNAME
AND B.TBNAME = ’SIMPDEPT’
AND A.CHECKNAME = B.CHECKNAME
ORDER BY TBOWNER, TBNAME, COLNAME;

Related reference:

Chapter 3. Altering your database design 123

 SYSCHECKS catalog table (Db2 SQL)
SYSCHECKDEP catalog table (Db2 SQL)

Retrieving catalog information about LOBs

The SYSIBM.SYSAUXRELS table contains information about the relationship
between a base table and an auxiliary table.

Procedure

To retrieve catalog information about LOBs:

Query the SYSIBM.SYSAUXRELS table. For example, this query returns

information about the name of the LOB columns for the employee table and its
associated auxiliary table schema and name:
SELECT COLNAME, PARTITION, AUXTBOWNER, AUXTBNAME
FROM SYSIBM.SYSAUXRELS
WHERE TBNAME = ’EMP’ AND TBOWNER = ’DSN8B10’;

Information about the length of a LOB is in the LENGTH2 column of the

SYSCOLUMNS table. You can query information about the length of the column as
it is returned to an application with the following query:
SELECT NAME, TBNAME, COLTYPE, LENGTH2, NULLS, DEFAULT
FROM SYSIBM.SYSCOLUMNS
WHERE TBNAME=’DEPT’
AND TBCREATOR = ’DSN8B10’;

Related reference:
SYSAUXRELS catalog table (Db2 SQL)
SYSCOLUMNS catalog table (Db2 SQL)

Retrieving catalog information about user-defined functions

and stored procedures
The SYSIBM.SYSROUTINES table contains information about routines.

Procedure

To retrieve information about user-defined functions and stored procedures:

Query the SYSIBM.SYSROUTINES table to obtain information about user-defined

functions and stored procedures. You can use this example to find packages with
stored procedures that were created prior to Version 6 and then migrated to the
SYSIBM.SYSROUTINES table:
SELECT SCHEMA, NAME FROM SYSIBM.SYSROUTINES
WHERE ROUTINETYPE = ’P’;

You can use this query to retrieve information about user-defined functions:

124 Administration Guide

 SELECT SCHEME, NAME, FUNCTION_TYPE, PARM_COUNT FROM SYSIBM.SYSROUTINES
WHERE ROUTINETYPE=’F’;

Related tasks:
Preparing a client program that calls a remote stored procedure (Db2
Application programming and SQL)
Related reference:
SYSROUTINES catalog table (Db2 SQL)

Retrieving catalog information about triggers

The SYSIBM.SYSTRIGGERS table contains information about triggers.

Procedure

To retrieve catalog information about triggers:

Query the SYSIBM.SYSTRIGGERS table to obtain information about the triggers

defined in your databases. You can issue this query to find all the triggers defined
on a particular table, their characteristics, and to determine the order they are
activated in:
SELECT DISTINCT SCHEMA, NAME, TRIGTIME, TRIGEVENT, GRANULARITY, CREADEDTS
FROM SYSIBM.SYSTRIGGERS
WHERE TBNAME = ’EMP’ AND TBOWNER = ’DSN8B10’;

Issue this query to retrieve the text of a particular trigger:

SELECT STATEMENT, CREATEDTS
FROM SYSIBM.SYSTRIGGERS
WHERE SCHEMA = schema_name
AND NAME = trigger_name
ORDER BY CREATEDTS;

Issue this query to determine triggers that must be rebound because they are
invalidated after objects are dropped or altered:
SELECT COLLID, NAME
FROM SYSIBM.SYSPACKAGE
WHERE TYPE = ’T’
AND (VALID = ’N’ OR OPERATIVE = ’N’);

Related reference:
SYSTRIGGERS catalog table (Db2 SQL)

Retrieving catalog information about sequences

The SYSIBM.SYSSEQUENCES and SYSIBM.SYSSEQUENCEAUTH tables contain
information about sequences.

Chapter 3. Altering your database design 125

 Procedure

To obtain information about sequences:

Query the SYSIBM.SYSSEQUENCES or SYSIBM.SYSSEQUENCEAUTH table. To

retrieve the attributes of a sequence, issue this query:
SELECT *
FROM SYSIBM.SYSSEQUENCES
WHERE NAME = ’MYSEQ’ AND SCHEMA = ’USER1B’;

Issue this query to determine the privileges that user USER1B has on sequences:
SELECT GRANTOR, NAME, DATEGRANTED, ALTERAUTH, USEAUTH
FROM SYSIBM.SEQUENCEAUTH
WHERE GRANTEE = ’USER1B’;

Related reference:
SYSSEQUENCES catalog table (Db2 SQL)
SYSSEQUENCEAUTH catalog table (Db2 SQL)

Adding and retrieving comments

After you create an object, you can provide explanatory information about it for
future reference. For example, you can provide information about the purpose of
the object, who uses it, and anything unusual about it.

You can create comments about tables, views, indexes, aliases, packages, plans,
distinct types, triggers, stored procedures, and user-defined functions. You can
store a comment about the table or the view as a whole, and you can also include
a comment for each column. A comment must not exceed 762 bytes.

A comment is especially useful if your names do not clearly indicate the contents
of columns or tables. In that case, use a comment to describe the specific contents
of the column or table.

Below are two examples of COMMENT:

COMMENT ON TABLE DSN8B10.EMP IS
’Employee table. Each row in this table represents one
employee of the company.’;
COMMENT ON COLUMN DSN8B10.PROJ.PRSTDATE IS
’Estimated project start date. The format is DATE.’;

After you execute a COMMENT statement, your comments are stored in the
REMARKS column of SYSIBM.SYSTABLES or SYSIBM.SYSCOLUMNS. (Any
comment that is already present in the row is replaced by the new one.) The next
two examples retrieve the comments that are added by the previous COMMENT
statements.

126 Administration Guide

 SELECT REMARKS
FROM SYSIBM.SYSTABLES
WHERE NAME = ’EMP’
AND CREATOR = ’DSN8B10’;
SELECT REMARKS
FROM SYSIBM.SYSCOLUMNS
WHERE NAME = ’PRSTDATE’ AND TBNAME = ’PROJ’
AND TBCREATOR = ’DSN8B10’;

Verifying the accuracy of the database definition

You can use the catalog to verify the accuracy of your database definition.

Procedure

To verify that you have created the objects in your database and check that no
errors are in your CREATE statements:

Query the catalog tables to verify that your tables are in the correct table space,
your table spaces are in the correct storage group, and so on.

Related reference:
Db2 catalog tables (Db2 SQL)

Altering Db2 databases

You can alter a Db2 database by changing the description of a database at the
current server.

Procedure
To change clauses that are used to create a database:

Issue the ALTER DATABASE statement. It supports changing the following

attributes of a database:
STOGROUP
Use this option to change the name of the default storage group to support
disk space requirements for table spaces and indexes within the database.
The new default Db2 storage group is used only for new table spaces and
indexes; existing definitions do not change.
BUFFERPOOL
Use this option to change the name of the default buffer pool for table
spaces and indexes within the database. Again, it applies only to new table
spaces and indexes; existing definitions do not change.
INDEXBP
Use this option to change the name of the default buffer pool for the
indexes within the database. The new default buffer pool is used only for
new indexes; existing definitions do not change.

Chapter 3. Altering your database design 127

 Related concepts:
Db2 databases (Introduction to Db2 for z/OS)
Related reference:
ALTER DATABASE (Db2 SQL)

Altering Db2 storage groups

To change the description of a storage group at the current server, use the ALTER
STOGROUP statement.

Procedure

To alter a storage group:

1. Issue an ALTER STOGROUP statement.
2. Specify whether you want SMS to manage your Db2 storage groups, or to add
or remove volumes from a storage group.

What to do next

If you want to migrate to another device type or change the catalog name of the
integrated catalog facility, you need to move the data.
Related concepts:
Moving Db2 data
Moving a Db2 data set
Related reference:
ALTER STOGROUP (Db2 SQL)
Related information:
Implementing Db2 storage groups

Letting SMS manage your Db2 storage groups

Using the SMS product Data Facility Storage Management Subsystem (DFSMS) to
manage your data sets can result in a reduced workload for Db2 database and
storage administrators.

Procedure

To let SMS manage the storage needed for the objects that the storage
group supports:
1. Issue an ALTER STOGROUP statement. You can specify SMS classes when you
alter a storage group.
2. Specify ADD VOLUMES ('*') and REMOVE VOLUMES (current-vols) where
current-vols is the list of the volumes that are currently assigned to the storage
group. For example,
ALTER STOGROUP DSN8G910
REMOVE VOLUMES (VOL1)
ADD VOLUMES (’*’);

Example

The following example shows how to alter a storage group to SMS-managed using
the DATACLAS, MGMTCLAS, or STORCLAS keywords.
128 Administration Guide
 ALTER STOGROUP SGOS5001
MGMTCLAS REGSMMC2
DATACLAS REGSMDC2
STORCLAS REGSMSC2;

What to do next

SMS manages every new data set that is created after the ALTER STOGROUP
statement is executed. SMS does not manage data sets that are created before the
execution of the statement.
Related tasks:
Migrating to DFSMShsm
Related reference:
ALTER STOGROUP (Db2 SQL)

Adding or removing volumes from a Db2 storage group

When you add or remove volumes from a storage group, all the volumes in that
storage group must be of the same type.

About this task

Also, when a storage group is used to extend a data set, the volumes must have
the same device type as the volumes that were used when the data set was defined

The changes that you make to the volume list by using the ALTER STOGROUP
statement have no effect on existing storage. Changes take effect when new objects
are defined or when the REORG, RECOVER, or LOAD REPLACE utilities are used
on those objects. For example, if you use the ALTER STOGROUP statement to
remove volume 22222 from storage group DSN8G910, the Db2 data on that volume
remains intact. However, when a new table space is defined by using DSN8G910,
volume 22222 is not available for space allocation.

Procedure

To add a new volume to a storage group:

1. Use the SYSIBM.SYSTABLEPART catalog table to determine which table spaces
are associated with the storage group. For example, the following query
indicates which table spaces use storage group DSN8G910:
SELECT TSNAME, DBNAME
FROM SYSIBM.SYSTABLEPART
WHERE STORNAME =’DSN8G910’ AND STORTYPE = ’I’;

2. Make an image copy of each table space. For example, issue the statement
COPY TABLESPACE dbname.tsname DEVT SYSDA.
3. Ensure that the table space is not being updated in such a way that the data set
might need to be extended. For example, you can stop the table space with the
Db2 command STOP DATABASE (dbname) SPACENAM (tsname).
4. Use the ALTER STOGROUP statement to remove the volume that is associated
with the old storage group and to add the new volume:

Chapter 3. Altering your database design 129

 ALTER STOGROUP DSN8G910
REMOVE VOLUMES (VOL1)
ADD VOLUMES (VOL2);

Restriction: When a new volume is added, or when a storage group is used to

extend a data set, the volumes must have the same device type as the volumes
that were used when the data set was defined.
5. Start the table space with utility-only processing by using the Db2 command
START DATABASE (dbname) SPACENAM (tsname) ACCESS(UT).
6. Use the RECOVER utility or the REORG utility to move the data in each table
space. For example, issue RECOVER dbname.tsname.
7. Start the table space with the Db2 command START DATABASE (dbname)
SPACENAM (tsname).

Migrating existing data sets to a solid-state drive

You can migrate Db2-managed data sets from a hard disk drive (HDD) to a
solid-state drive (SSD).

About this task

For user-managed data sets, you are responsible for defining and copying the data
sets to an SSD. However, whether the data sets are Db2-managed or user-managed,
all volumes that can contain secondary extents should have the same drive type as
the drive type of the primary extent volume. In addition, you must define all of
the pieces of a multi-piece data set on volumes that have the same drive type.

To migrate Db2-managed data sets to an SSD:

Procedure

Use one of the following options.

v Use DSN1COPY to move data sets from an HDD to an SSD. The drive type is
found by Db2 the next time that you open the data set.
v Issue the ALTER STOGROUP statement. For data sets that are managed by SMS,
use the ALTER STOGROUP statement to change DATACLAS, MGMTCLAS, or
STORCLAS to identify the new SSD volumes. For data sets that are not
managed by SMS, use the ALTER STOGROUP statement to add volumes that
contain SSD and drop volumes that contain HDD.
The storage group should be homogenous and contain either all SSDs or all
HDDs. The data set is moved to the new SSD volume at the next REORG after
the alter operation.
Using the ALTER STOGROUP statement has an availability advantage over
using the CREATE STOGROUP statement, because the ALTER TABLESPACE
USING STOGROUP statement must stop the object before the alter operation
can succeed. If you cannot make an existing storage group homogenous, you
must use the CREATE STOGROUP statement to define the storage groups to
contain SSD volumes.

Altering table spaces

Use the ALTER TABLESPACE statement to change the description of a table space
at the current server.

130 Administration Guide

 About this task

For partition-by-range and partition-by-growth table spaces, most attributes can be

changed with ALTER TABLESPACE statements, often through pending definition
changes.

Pending definition changes are changes that are not immediately materialized. For
detailed information about pending definition changes, how to materialize them,
and related restrictions, see Pending data definition changes

Immediate definition changes are changes that are materialized immediately. Most
immediate definition changes are restricted while pending definition changes exist
for an object. For a list of such restrictions, see Restrictions for changes to objects
that have pending data definition changes.

However, depending on the type of table space and the attributes that you want to
change, you might instead need to drop the table space, and create it again with
the new attributes. Many fewer types of changes are supported by ALTER
TABLESPACE statements for the deprecated non-UTS table space types. In such
cases, it is best to first convert the table space to a partition-by-range or
partition-by-growth table space first and then use ALTER TABLESPACE statements
with pending definition changes to make the changes.

Procedure

To change the attributes of a table space, use any of the following approaches:
v Use the ALTER TABLESPACE statements to change the table space type and
attributes, or to enable or disable MEMBER CLUSTER. For example, you might
make the following changes:
– Use the MAXPARTITIONS attribute of the ALTER TABLESPACE statement to
change the maximum partition size for partition-by-growth table spaces. You
can also use this attribute to convert a simple table space, or a single-table
segmented (non-UTS) table space to a partition-by-growth table space.
– Use the SEGSIZE attribute of the ALTER TABLESPACE statement to convert a
| partitioned (non-UTS) table space to a partition-by-range table space. For
| more information, see Converting partitioned (non-UTS) table spaces to
| partition-by-range universal table spaces.
v Drop the table space and create it again with the new attributes, as described in
Dropping and re-creating a table space to change its attributes. For example,
some changes are not supported by ALTER TABLESPACE statements, such as
the following changes:
– Changing the CCSID to an incompatible value
– Moving the table space to a different database
– Converting a multi-table table segmented (non-UTS) space to a UTS table
space type

What to do next

When ready, materialize any pending definition changes, as described in

Materializing pending definition changes.

Chapter 3. Altering your database design 131

 You can also use the DROP PENDING CHANGES clause to drop all pending
definition changes for the table space and for any of the objects in the table space.
Related concepts:
Table space types and characteristics in Db2 for z/OS
Pending data definition changes
Member affinity clustering (Db2 Data Sharing Planning and Administration)
Related tasks:
Changing the logging attribute
Related reference:
ALTER TABLESPACE (Db2 SQL)
SYSPENDINGDDL catalog table (Db2 SQL)
Related information:
Implementing Db2 table spaces

Changing the logging attribute

You can use the ALTER TABLESPACE statement to set the logging attribute of a
table space.

Before you begin

Important: Limit the use of the NOT LOGGED attribute. Logging is not generally
a performance bottleneck, given that in an average environment logging accounts
for less than 5% of the central processing unit (CPU) utilization. Therefore, you
should use the NOT LOGGED attribute only when data is being used by a single
task, where the table space can be recovered if errors occur.

Procedure

To change the logging attribute of a table space:

1. Issue an ALTER TABLESPACE statement.
2. Specify the LOGGED or NOT LOGGED attribute.
v LOGGED: Specifies that changes made to data in this table space are to be
recorded on the log.
v NOT LOGGED: Specifies that changes made to data in this table space are
not to be recorded on the log. The NOT LOGGED attribute suppresses the
logging of undo and redo information.

Results

The change in logging applies to all tables in this table space and also applies to all
indexes on those tables, as well as associated LOB and XML table spaces.
Related tasks:
Altering table spaces
Loading data by using the INSERT statement
Related reference:
ALTER TABLESPACE (Db2 SQL)

132 Administration Guide

The NOT LOGGED attribute
The NOT LOGGED attribute for a table space indicates that changes to tables in
the table space are not recorded on the log.

You should use the NOT LOGGED attribute only for situations where the data is
in effect being duplicated. If the data is corrupted, you can re-create it from its
original source, rather than from an image copy and the log. For example, you
could use NOT LOGGED when you are inserting large volumes of data with the
INSERT statement.

Restrictions: If you use the NOT LOGGED logging attribute, you can use images
copies for recovery with certain restrictions.
v The logging attribute applies to all partitions of a table space. NOT LOGGED
suppresses only the logging of undo and redo information; control records of the
table space continue to be logged.
v You can take full and incremental SHRLEVEL REFERENCE image copies even
though the table space has the NOT LOGGED attribute. You cannot take
SHRLEVEL CHANGE copies because the NOT LOGGED attribute suppresses
the logging of changes necessary for recovery.
v System-level backups taken with the BACKUP SYSTEM utility will contain NOT
LOGGED objects, but they cannot be used for object level recovery of NOT
LOGGED objects.

You can set the NOT LOGGED attribute when creating or altering table spaces.

When to use the NOT LOGGED attribute

Consider using the NOT LOGGED attribute in the following specific situations:
v For tables that summarize information in other tables, including materialized
query tables, where the data can be easily re-created.
v When you are inserting large volumes of data with the INSERT statement.
v When you are using LOAD RESUME.
To use table spaces that are not logged, when using LOAD RESUME, complete
the following steps:
1. Alter the table space to not logged before the load. Altering the logging
attribute requires exclusive use of the table space.
2. Run the LOAD utility with the RESUME option.
3. Before normal update processing, alter the table space back to logged, and
make an image copy of the table space.

Restriction: Online LOAD RESUME against a table space that is not logged is
not recoverable if the load fails. If an online load attempt fails and rollback is
necessary, the not logged table space is placed in LPL RECOVER-pending status.
If this happens, you must terminate the LOAD job, recover the data from a prior
image copy, and restart the online LOAD RESUME.

What happens when you change the logging attribute

Altering the logging attribute of a table space from LOGGED to NOT LOGGED
establishes a recoverable point for the table space. Indexes automatically inherit the
logging attribute of their table spaces. For the index, the change establishes a
recoverable point that can be used by the RECOVER utility. Each subsequent

Chapter 3. Altering your database design 133

 image copy establishes another recoverable point for the table space and its
associated indexes if the image copy is taken as a set.

Altering the logging attribute of a table space from NOT LOGGED to LOGGED
marks the table space as COPY-pending (a recoverable point must be established
before logging resumes). The indexes on the tables in the table space that have the
COPY YES attribute are unchanged.
Related concepts:
Recovery implications for objects that are not logged

Changing the space allocation for user-managed data sets

If the table space is supported by user-managed data sets, you must complete
several steps to change the space allocation.

Procedure

To change the space allocation for user-managed data sets, complete the following
steps:
1. Run the REORG TABLESPACE utility, and specify the UNLOAD PAUSE
option.
2. Make the table space unavailable with the STOP DATABASE command and the
SPACENAM option after the utility completes the unload and stops.
3. Delete and redefine the data sets.
4. Resubmit the utility job with the RESTART(PHASE) parameter specified on the
EXEC statement.

What to do next

The job now uses the new data sets when reloading.

Use of the REORG utility to extend data sets causes the newly acquired free space
to be distributed throughout the table space rather than to be clustered at the end.

Dropping and re-creating a table space to change its

attributes
One approach for changing the attributes of a space is to drop the table space and
create it again with different attributes. When you use this approach you must also
take action to preserve the data in the table space.

Before you begin

For best results, use this procedure only to change attributes of a table space that
cannot be changed with ALTER TABLESPACE statements. The techniques
described here are intended for changing the attributes of non-UTS table spaces.

For partition-by-growth or partition-by-range universal table spaces, it is best to

use ALTER TABLESPACE statements, which can change most attributes of a table
space with pending definition changes. For deprecated non-UTS types, consider
first converting the table space to a UTS type, and then use ALTER TABLESPACE
statements to make the required changes.

134 Administration Guide

Procedure

To drop and re-recreate a table space:

1. Locate the original CREATE TABLE statement and all authorization statements
for all tables in the table space (for example, TA1, TA2, TA3, ... in TS1). If you
cannot find these statements, query the Db2 catalog to determine the table's
description, the description of all indexes and views on it, and all users with
privileges on the table.
2. In another table space (for example, TS2), create tables TB1, TB2, TB3, ...
identical to TA1, TA2, TA3, ....

For example, use a statement such as:

CREATE TABLE TB1 LIKE TA1 IN TS2;
3. Optional: If necessary, unload the data. For example, use a statement such as:
REORG TABLESPACE DSN8D91A.TS1 LOG NO SORTDATA UNLOAD EXTERNAL;
Another way of unloading data from your old tables and loading the data
into new tables is by using the INCURSOR option of the LOAD utility. This
option uses the Db2 cross-loader function.
4. Optional: Alternatively, instead of unloading the data, you can insert the data
from your old tables into the new tables by issuing an INSERT statement for
each table. For example:
INSERT INTO TB1
SELECT * FROM TA1;

If a table contains a ROWID column or an identity column and you want to

keep the existing column values, you must define that column as
GENERATED BY DEFAULT. If the ROWID column or identity column is
defined with GENERATED ALWAYS, and you want Db2 to generate new
values for that column, specify OVERRIDING USER VALUE on the INSERT
statement with the subselect.
5. Drop the table space. For example, use a statement such as:
DROP TABLESPACE TS1;

The compression dictionary for the table space is dropped, if one exists. All
tables in TS1 are dropped automatically.
6. Commit the DROP statement. You must commit the DROP TABLESPACE
statement before creating a table space or index with the same name. When
you drop a table space, all entries for that table space are dropped from
SYSIBM.SYSCOPY. This makes recovery for that table space impossible from
previous image copies.
7. Create the new table space, TS1, and grant the appropriate user privileges.
You can also create a partitioned table space. For example, use a statement
such as:
CREATE TABLESPACE TS1
IN DSN8D91A
USING STOGROUP DSN8G910
PRIQTY 4000
SECQTY 130
ERASE NO
NUMPARTS 95
(PARTITION 45 USING STOGROUP DSN8G910
PRIQTY 4000
SECQTY 130

Chapter 3. Altering your database design 135

 COMPRESS YES,
PARTITION 62 USING STOGROUP DSN8G910
PRIQTY 4000
SECQTY 130
COMPRESS NO)
LOCKSIZE PAGE
BUFFERPOOL BP1
CLOSE NO;
8. Create the new tables TA1, TA2, TA3, ....
9. Re-create indexes on the tables, and grant user privileges on those tables.
10. Issue an INSERT statement for each table. For example:
INSERT INTO TA1
SELECT * FROM TB1;
If a table contains a ROWID column or an identity column and you want to
keep the existing column values, you must define that column as
GENERATED BY DEFAULT. If the ROWID column or identity column is
defined with GENERATED ALWAYS, and you want Db2 to generate new
values for that column, specify OVERRIDING USER VALUE on the INSERT
statement with the subselect.

11. Drop table space TS2. If a table in the table space has been created with
RESTRICT ON DROP, you must alter that table to remove the restriction
before you can drop the table space.
12. Re-create any dependent objects on the new tables TA1, TA2, TA3, ....
13. REBIND any packages that were invalidated as a result of dropping the table
space.
Related concepts:
Implications of dropping a table

Redistributing data in partitioned table spaces

When data becomes skewed across partitions, performance can be slower. For
example, data is skewed if some partitions are almost full while other partitions
have a considerable amount of excess space. Performance might improve if you
can redistribute the data more evenly across the partitions.

About this task

Redistributing data in partitioned table spaces is not always possible because of

application dependencies or other factors. If a partition is full and redistributing
the data is not practical, you might need to increase the partition size.

Procedure

To redistribute data in partitioned table spaces, use one of the following two
methods:
v Change the partition boundaries.
v Redistribute the data across partitions by using the REORG TABLESPACE utility.

Example

136 Administration Guide

 Assume that a table space contains product data that is partitioned by product ID
as follows: The first partition contains rows for product ID values 1 through 99.
The second partition contains rows for values 100 to 199. The third partition
contains rows for values 200 through 299. And the subsequent partitions are empty.

Suppose that after some time, because of the popularity of certain products, you
want to redistribute the data across certain partitions. You want the third partition
to contain values 200 through 249, the fourth partition to contain values 250
through 279, and the fifth partition to contain values 280 through 299.

To change the boundary for these partitions, issue the following statements:
ALTER TABLE PRODUCTS ALTER PARTITION 3
ENDING AT (’249’);
ALTER TABLE PRODUCTS ALTER PARTITION 4
ENDING AT (’279’);
ALTER TABLE PRODUCTS ALTER PARTITION 5
ENDING AT (’299’);

| Assume that the table is a partition-by-range table space or a partitioned

| (non-UTS) table space with table-controlled partitioning. Partitions 3, 4, and 5 are
| placed in advisory REORG-pending (AREOR) status. The data remains available.
| However, the changes are pending and are not materialized until you run REORG
| TABLESPACE.

Alternatively, instead of using ALTER TABLE statements with the ALTER

PARTITION clause, you can use the REBALANCE keyword as follows:
REORG TABLESPACE dbname.tsname PART(3:5) REBALANCE

| In this case, Db2 determines the appropriate limit key changes and redistributes
| the data accordingly.

Related tasks:
Increasing partition size
Creating tables partitioned by data value ranges
Related reference:
Syntax and options of the REORG TABLESPACE control statement (Db2
Utilities)
ALTER INDEX (Db2 SQL)
ALTER TABLE (Db2 SQL)
Advisory or restrictive states (Db2 Utilities)

Increasing partition size

If a partition is full and redistributing the data across partitions is not practical,
you might need to increase the partition size.

About this task

You can increase the maximum partition size of a partitioned table space to 128 GB
or 256 GB. Depending on the partition size and page size, increasing the maximum

Chapter 3. Altering your database design 137

 size of a partition can proportionally reduce the maximum number of partitions
that can be specified.

Procedure

To increase the maximum partition size of a partitioned table space:

1. If the table space uses index-based partitioning, convert it to table-based
partitioning, as described in Converting table spaces to use table-controlled
partitioning.
2. If the table space is not a partition-by-range universal table space, convert it as
described in Converting partitioned (non-UTS) table spaces to
partition-by-range universal table spaces.
3. Issue the ALTER TABLESPACE statement with the DSSIZE option to increase
the maximum partition size to 128 GB or 256 GB.
4. Issue the ALTER TABLESPACE statement with the PRIQTY and SECQTY
options to modify the primary and secondary space allocation for each
partition. This change allows the partition to grow to its anticipated maximum
size.
5. Run the REORG TABLESPACE utility with SHRLEVEL CHANGE or
SHRLEVEL REFERENCE to materialize the pending definition changes and
convert the table space. When reorganizing a table space that has pending
definition changes, the entire table space must be included. Therefore, you
cannot reorganize by partition. In addition, partition parallelism is disabled
during the UNLOAD and RELOAD phases.
A significant amount of disk space can be required when reorganizing an entire
table space. The amount of space required for the table space and indexes is
approximately two times of what is already allocated. If the amount of space
that is required is not available, you might need to use an alternative strategy
of unloading, dropping, creating, and loading the table space. With this
method, you can reorganize individual partitions in parallel and requires
significantly less disk space.
For tables that have LOB and XML columns, the table spaces are independent
from the base table space. You can alter and reorganize these table spaces
separately. Do not run the REORG utility with AUX YES to reorganize both the
base and LOB table spaces together, because in this case, the pending definition
changes for the LOB table space are not materialized.
Converting a 16 TB table space to a table with larger partitions or data sets can
take a significant amount of time.
Related tasks:
Redistributing data in partitioned table spaces
Related reference:
DROP (Db2 SQL)
ALTER TABLESPACE (Db2 SQL)
REORG TABLESPACE (Db2 Utilities)

Altering a page set to contain Db2-defined extents

After you use the RECOVER utility to run the DFSMSdss RESTORE command,
you must alter the page set to contain extents that are defined by Db2.

138 Administration Guide

 About this task

This step is required because the DFSMSdss RESTORE command extends a data
set differently than Db2.

Procedure

To alter a page set to contain extents that are defined by Db2:

1. Issue the ALTER TABLESPACE SQL statement.
After you use the ALTER TABLESPACE statement, the new values take affect
only when you use REORG or LOAD REPLACE.
2. Enlarge the primary and secondary space allocation values for Db2-managed
data sets.

What to do next

Using the RECOVER utility again does not resolve the extent definition.

For user-defined data sets, define the data sets with larger primary and secondary
space allocation values.
Related concepts:
The RECOVER utility and the DFSMSdss RESTORE command
Related reference:
ALTER TABLESPACE (Db2 SQL)

| Converting partitioned (non-UTS) table spaces to

| partition-by-range universal table spaces
| You can convert existing partitioned (non-UTS) table spaces, which are deprecated,
| to partition-by-range table spaces.

| About this task

| Partition-by-range table spaces are preferred over deprecated partitioned (non-UTS)

| tables spaces because the segmented structure of partition-by-range table spaces
| improves space management and faster performance for mass-deletes. Also, some
| capabilities introduced in DB2 9 and later releases are supported for
| partition-by-range table spaces but not for partitioned (non-UTS) tables spaces,
| such as:
| v Dropping columns
| v Altering the COMPRESS attribute of a table space
| v Altering the DSSIZE value
| v Altering the MEMBER CLUSTER attribute of a table space
| v Altering the buffer pool page size for a table space
| v Inline LOBs
| v Clone tables
| v Altering the compression attribute of an index as a pending definition change
| v Altering the buffer pool page size of an index as a pending definition change

| Learn more: For comprehensive background, how-to information, and examples

| for various paths for converting your deprecated “classic” partitioned (non-UTS)

Chapter 3. Altering your database design 139

| table spaces to partition-by-range table spaces, see the white paper Conversion
| from index-controlled partitioning to Universal Table Space (UTS).

| Procedure

| To convert a partitioned (non-UTS) table space to a partition-by-range table space,

| complete the following steps:
| 1. If table space uses index-controlled partitioning, convert it to use
| table-controlled partitioning, as described in Converting table spaces to use
| table-controlled partitioning.
| 2. Convert the table space to a partition-by-range universal table space by issuing
| an ALTER TABLESPACE statement that specifies segment size for the table
| space. For example, the following statement converts the ts-name table space to
| a partition-by-range universal table space with a segment size of 16 pages per
| segment.
| ALTER TABLESPACE ts-name SEGSIZE 16;

| The ALTER TABLESPACE statement is recorded as a pending data definition

| change.
| 3. Materialize the pending data definition change by running the REORG utility
| for the entire table space. When the REORG completes, the SYSTABLESPACE
| catalog table contains TYPE='R', which indicates a partition-by-range table
| space.
| Related reference:
| ALTER INDEX (Db2 SQL)
| ALTER TABLESPACE (Db2 SQL)
| Related information:
| +20272 (Db2 Codes)

| Converting table spaces to use table-controlled partitioning

| Before you can convert a partitioned (non-UTS) table space that uses
| index-controlled partitioning to a partition-by-range table space, you must convert
| it to use table controlled partitioning. Table spaces that use index-controlled
| partitioning, like all non-UTS table spaces are deprecated.

| Before you begin

| To exclude trailing columns that do not affect partitioning from the partitioning
| keys after the conversion, set the IX_TB_PART_CONV_EXCLUDE subsystem
| parameter to YES. For more information, see EXCLUDE PART KEY COLUMNS
| field (IX_TB_PART_CONV_EXCLUDE subsystem parameter) (Db2 Installation and
| Migration)

| To prevent the creation of any new tables that use index-controlled partitioning, set
| the PREVENT_NEW_IXCTRL_PART subsystem parameter to YES. For more
| information, see PREVENT INDEX PART CREATE field
| (PREVENT_NEW_IXCTRL_PART subsystem parameter) (Db2 Installation and
| Migration)

140 Administration Guide

| About this task

| For partitioned (non-UTS) table spaces, Db2 supports both table-controlled

| partitioning and index-controlled partitioning. Table-controlled partitioning provides
| more options and flexibility compared to index-controlled partitioning.
| Index-controlled partitioning requires partitioning index to control the partitioning.

| Non-UTS table spaces for base tables are deprecated and likely to be unsupported
| in the future.
| Table 19. Differences between table-controlled and index-controlled partitioning
| Table-controlled partitioning Index-controlled partitioning
| Requires no partitioning index or clustering Requires a partitioning index and a
| index. clustering index.
| Multiple partitioned indexes can be created Only one partitioned index can be created in
| in a table space. a table space.
| A table space partition is identified by both a A table space partition is identified by a
| physical partition number and a logical physical partition number.
| partition number.
| The high-limit key is always enforced, which The high-limit key is not enforced if the table
| means that key values that are out of range space is non-large.
| might result in errors or discarded data,
| depending on the operation involved.
|

| The conversion is also required before you can convert a partitioned (non-UTS)
| table space, to a partition-by-range table space.

| Learn more: For comprehensive background, how-to information, and examples

| for various paths for converting your deprecated “classic” partitioned (non-UTS)
| table spaces to partition-by-range table spaces, see the white paper Conversion
| from index-controlled partitioning to Universal Table Space (UTS).

| Procedure

| Certain index operations always cause Db2 to automatically convert an

| index-controlled partitioned table space to a table-controlled partitioned table
| space. To convert a table that uses index-controlled partitioning to use
| table-controlled partitioning, use one of the following actions:
| v Issue an ALTER INDEX statement with the NOT CLUSTER clause on the
| partitioning index.
| For example, you can issue the following two ALTER INDEX statements in the
| same commit scope to convert a table to use table-controlled partitioning and
| reactivate clustering for the index.
| ALTER INDEX index-name NOT CLUSTER;

| Db2 issues SQLCODE +20272 to indicate that the associated table space no
| longer uses index-controlled partitioning .
| ALTER INDEX index-name CLUSTER;

| This statement reactivates explicit clustering for the index.

| v Issue an ALTER TABLE statement to add a new partition, change a partition
| boundary, or rotate a partition to last on an index-controlled partitioned table

Chapter 3. Altering your database design 141

| space. In these cases, Db2 automatically converts to table-controlled partitioning,
| but does not automatically drop any indexes. Db2 assumes that any existing
| indexes are useful.
| v Issue a CREATE INDEX statement that specifies a PARTITIONED clause to
| create a partitioned index on the table space.
| v Issue a DROP INDEX statement to drop the partitioning index. When you drop
| a partitioning index, Db2 automatically converts the associated index-controlled
| partitioned table space to a table-controlled partitioned table space.

| Results

| After the conversion to table-controlled partitioning, Db2 changes the existing

| high-limit key value for non-large table spaces to the highest value for the key.
| Db2 also starts enforcing the high-limit key values, which is not the case for tables
| that use index-controlled partitioning.

| Db2 also invalidates any packages that depend on the table in the converted table
| space.

| Db2 places the last partition of the table space into a REORG-pending (REORP)
| state in the following situations:
| Adding or rotating a new partition
| Db2 stores the original high-limit key value instead of the default
| high-limit key value. Db2 puts the last partition into a REORP state, unless
| the high-limit key value is already being enforced, or the last partition is
| empty.
| Altering a partition results in the conversion to table-controlled partitioning
| Db2 changes the existing high-limit key to the highest value that is
| possible for the data types of the limit key columns. After the conversion
| to table-controlled partitioning, Db2 changes the high-limit key value back
| to the user-specified value and puts the last partition into a REORP state.

| Example

| For example, assume that you have a very large transaction table named TRANS
| that contains one row for each transaction. The table includes the following
| columns:
| v ACCTID is the customer account ID
| v POSTED is the date of the transaction

| The table space that contains TRANS is divided into 13 partitions, each containing
| one month of data. Two existing indexes are defined as follows:

|
|
| v A partitioning index is defined on the transaction date by the following CREATE
| INDEX statement with a PARTITION ENDING AT clause: The partitioning index
| is the clustering index, and the data rows in the table are in order by the
| transaction date. The partitioning index controls the partitioning of the data in
| the table space.
| v A nonpartitioning index is defined on the customer account ID:
| CREATE INDEX IX2 ON TRANS(ACCTID);

142 Administration Guide

|
|

| Db2 usually accesses the transaction table through the customer account ID by
| using the nonpartitioning index IX2. The partitioning index IX1 is not used for
| data access and is wasting space. In addition, you have a critical requirement for
| availability on the table, and you want to be able to run an online REORG job at
| the partition level with minimal disruption to data availability.

|
|
| 1. Drop the partitioning index IX1.
| DROP INDEX IX1;
| When you drop the partitioning index IX1, Db2 converts the table space from
| index-controlled partitioning to table-controlled partitioning. Db2 changes the
| high limit key value that was originally specified to the highest value for the
| key column.
| 2. Create a partitioned clustering index IX3 that matches the 13 data partitions in
| the table, as a replacement for IX2.
| CREATE INDEX IX1 ON TRANS(POSTED)
| CLUSTER
| (PARTITION 1 ENDING AT (’01/31/2002’),
| PARTITION 2 ENDING AT (’02/28/2002’),
| ...
| PARTITION 13 ENDING AT (’01/31/2003’));
| When you create the index IX3, Db2 creates a partitioned index with 13
| partitions that match the 13 data partitions in the table. Each index partition
| contains the account numbers for the transactions during that month, and those
| account numbers are ordered within each partition. For example, partition 11 of
| the index matches the table partition that contains the transactions for
| November, 2002, and it contains the ordered account numbers of those
| transactions.
| 3. Drop index IX2,which was replaced IX3.
| DROP INDEX IX2;
| COMMIT;
|
|

| What to do next

| The result of this procedure is a partitioned (non-UTS) table space, which is also a
| deprecated table space type. For best results, also convert the table space to a
| partition-by-range table space, as described in Converting partitioned (non-UTS)
| table spaces to partition-by-range universal table spaces.
| Related tasks:
| Creating tables partitioned by data value ranges
| Related reference:
| CREATE INDEX (Db2 SQL)
| CREATE TABLE (Db2 SQL)
| Related information:
| +20272 (Db2 Codes)

Chapter 3. Altering your database design 143

 Altering Db2 tables
When you alter a table, you do not change the data in the table. You merely
change the specifications that you used in creating the table.

Procedure

To alter a table:

Issue the ALTER TABLE statement. With the ALTER TABLE statement, you can:
v Add a new column
v Rename a column
| v Drop a column
v Change the data type of a column, with certain restrictions
v Add or drop a parent key or a foreign key
v Add or drop a table check constraint
v Add a new partition to a table space, including adding a new partition to a
partition-by-growth table space, by using the ADD PARTITION clause
v Change the boundary between partitions, extend the boundary of the last
partition, rotate partitions, or instruct Db2 to insert rows at the end of a table or
appropriate partition
v Register an existing table as a materialized query table, change the attributes of
a materialized query table, or change a materialized query table to a base table
v Change the VALIDPROC clause
v Change the DATA CAPTURE clause
v Change the AUDIT clause by using the options ALL, CHANGES, or NONE
v Add or drop the restriction on dropping the table and the database and table
space that contain the table
v Alter the length of a VARCHAR column using the SET DATA TYPE VARCHAR
clause
v Add or drop a clone table
v Alter APPEND attributes
v Drop the default value for a column
v Activate or deactivate row-level or column-level access control for the table

Tip: When designing row-level or column-level access control for a table, first
create the row permissions or column masks to avoid multiple invalidations to
packages and dynamically cached statements. After you create row permissions
or column masks, use the ALTER TABLE statement to activate row-level or
column-level access control for the table. If you must drop or alter a column
mask, first activate row-level access control to prevent access to the table, and
then drop or alter the column mask. Otherwise, the rows are accessible, but the
column values inside the rows are not protected.

If a security administrator with SECADM authority activates row-level access

control before the explicit creation of the row permission database object, a
default row permission is created. This default row permission blocks all access
to the table, including access by the owner.

144 Administration Guide

 Related concepts:
Row and column access control (Managing Security)
Related tasks:
| Altering tables for hash access (deprecated)
Related reference:
ALTER TABLE (Db2 SQL)

Adding a column to a table

When you use the ALTER TABLE statement to add a column to a table, the table
space is placed in an advisory REORG-pending (AREO*) state.

About this task

Also, the new column might become the rightmost column of the table, depending
on whether you use basic row format or reordered row format.

The physical records are not actually changed until values are inserted in the new
column. When you use the ALTER TABLE ADD COLUMN statement, packages are
not invalidated, unless the following criteria are true:
v The data type of the new column is DATE, TIME, or TIMESTAMP.
v You specify the DEFAULT keyword.
v You do not specify a constant (that is, you use the system default value).

However, to use the new column in a program, you need to modify and recompile
the program and bind the plan or package again. You also might need to modify
any program that contains a static SQL statement SELECT *, which returns the new
column after the plan or package is rebound. You also must modify any INSERT
statement that does not contain a column list.

Access time to the table is not affected immediately, unless the record was
previously fixed length. If the record was fixed length, the addition of a new
column causes Db2 to treat the record as variable length, and access time is
affected immediately.

Procedure

To change the records to fixed length:

1. Run the REORG utility with the COPY option on the table space, using the
inline copy.
2. Run the MODIFY utility with the DELETE option to delete records of all image
copies that were made before the REORG that you ran in step 1.
3. Create a unique index if you add a column that specifies PRIMARY KEY.

Results

Tip: Inserting values in the new column might degrade performance by forcing
rows onto another physical page. You can avoid this situation by creating the table
space with enough free space to accommodate normal expansion. If you already
have this problem, run REORG on the table space to fix it.

Chapter 3. Altering your database design 145

 You can define the new column as NOT NULL by using the DEFAULT clause
unless the column has a ROWID data type or is an identity column. If the column
has a ROWID data type or is an identity column, you must specify NOT NULL
without the DEFAULT clause. You can let Db2 choose the default value, or you can
specify a constant or the value of the CURRENT SQLID or USER special register as
the value to be used as the default. When you retrieve an existing row from the
table, a default value is provided for the new column. Except in the following
cases, the value for retrieval is the same as the value for insert:
v For columns of data type DATE, TIME, and TIMESTAMP, the retrieval defaults
are:
Data type
Default for retrieval
DATE
0001-01-01
TIME 00.00.00
TIMESTAMP
0001-01-01-00.00.00.000000
v For DEFAULT USER and DEFAULT CURRENT SQLID, the retrieved value for
rows that existed before the column was added is the value of the special
register when the column was added.

If the new column is a ROWID column, Db2 returns the same, unique row ID
value for a row each time you access that row. Reorganizing a table space does not
affect the values on a ROWID column. You cannot use the DEFAULT clause for
ROWID columns.

If the new column is an identity column (a column that is defined with the AS
IDENTITY clause), Db2 places the table space in REORG-pending (REORP) status,
and access to the table space is restricted until the table space is reorganized. When
the REORG utility is run, Db2
v Generates a unique value for the identity column of each existing row
v Physically stores these values in the database
v Removes the REORP status

You cannot use the DEFAULT clause for identity columns.

If the new column is a short string column, you can specify a field procedure for
it. If you do specify a field procedure, you cannot also specify NOT NULL.

Example

The following example adds a column to the table DSN8910.DEPT, which contains
a location code for the department. The column name is LOCATION_CODE, and
its data type is CHAR (4).
ALTER TABLE DSN8910.DEPT
ADD LOCATION_CODE CHAR (4);

Related concepts:
Row format conversion for table spaces

146 Administration Guide

Specifying a default value when altering a column
You can use the ALTER TABLE statement to add, change, or remove the default
value for a column.

About this task

Restrictions:
v You cannot alter a column to specify a default value if the table is referenced by
a view.
v If the column is part of a unique constraint or unique index, the new default to
a value should not be the same as a value that already exists in the column.
v The new default value applies only to new rows.

Procedure

To alter the default value for a column:

1. To set the default value, issue the following statement:
ALTER TABLE table-name ALTER COLUMN column-name
SET default-clause
You can use this statement to add a default value for a column that does not
already have one, or to change the existing default value.
2. To remove the default value without specifying a new one, issue the following
statement:
ALTER TABLE table-name ALTER COLUMN column-name
DROP DEFAULT

Example

For example, suppose that table MYEMP is defined as follows:

CREATE TABLE MYEMP LIKE EMP

Use the following statement to assign a default value to column JOB:

ALTER TABLE MYEMP ALTER COLUMN JOB SET DEFAULT ’PENDING’

Use the following statement to drop the default value from column JOB:
ALTER TABLE MYEMP ALTER COLUMN JOB DROP DEFAULT

Altering the data type of a column

You can use the ALTER TABLE statement to change the data types of columns in
existing tables in several ways.

About this task

In general, Db2 can alter a data type if the data can be converted from the old type
to the new type without truncation or without losing arithmetic precision.

Chapter 3. Altering your database design 147

 Restriction: The column that you alter cannot be a part of a referential constraint,
have a field procedure, be defined as an identity column, or be defined as a
column of a materialized query table.

When you alter the data type of a column in a table, Db2 creates a new version for
the table space that contains the data rows of the table.

Procedure

To alter the data type of a column:

1. Issue an ALTER TABLE statement.
2. Specify the data type change that you would like to make. Potential changes
include:
v Altering the length of fixed-length or varying-length character data types,
and the length of fixed-length or varying-length graphic data types.
v Switching between fixed-length and varying-length types for character and
graphic data.
v Switching between compatible numeric data types.

Results
When you change the data type of a column by using the ALTER TABLE
statement, the new definition of the column is stored in the catalog.

When you retrieve table rows, the columns are retrieved in the format that is
indicated by the catalog, but the data is not saved in that format. When you
change or insert a row, the entire row is saved in the format that is indicated by
the catalog. When you reorganize the table space (or perform a load replace), Db2
reloads the data in the table space according to the format of the current
definitions in the catalog.

Example:

Assume that a table contains basic account information for a small bank. The initial
account table was created many years ago in the following manner:
CREATE TABLE ACCOUNTS (
ACCTID DECIMAL(4,0) NOT NULL,
NAME CHAR(20) NOT NULL,
ADDRESS CHAR(30) NOT NULL,
BALANCE DECIMAL(10,2) NOT NULL)
IN dbname.tsname;

The columns, as currently defined, have the following problems:

v The ACCTID column allows for only 9999 customers.
v The NAME and ADDRESS columns were defined as fixed-length columns,
which means that some of the longer values are truncated and some of the
shorter values are padded with blanks.
v The BALANCE column allows for amounts up to 99,999,999.99, but inflation
rates demand that this column hold larger numbers.

148 Administration Guide

By altering the column data types in the following ways, you can make the
columns more appropriate for the data that they contain. The INSERT statement
that follows shows the kinds of values that you can now store in the ACCOUNTS
table.
ALTER TABLE ACCOUNTS ALTER COLUMN NAME SET DATA TYPE VARCHAR(40);
ALTER TABLE ACCOUNTS ALTER COLUMN ADDRESS SET DATA TYPE VARCHAR(60);
ALTER TABLE ACCOUNTS ALTER COLUMN BALANCE SET DATA TYPE DECIMAL(15,2);
ALTER TABLE ACCOUNTS ALTER COLUMN ACCTID SET DATA TYPE INTEGER;
COMMIT;

INSERT INTO ACCOUNTS (ACCTID, NAME, ADDRESS, BALANCE)

VALUES (123456, ’LAGOMARSINO, MAGDALENA’,
’1275 WINTERGREEN ST, SAN FRANCISCO, CA, 95060’, 0);
COMMIT;

The NAME and ADDRESS columns can now handle longer values without
truncation, and the shorter values are no longer padded. The BALANCE column is
extended to allow for larger dollar amounts. Db2 saves these new formats in the
catalog and stores the inserted row in the new formats.

Recommendation: If you change both the length and the type of a column from
fixed-length to varying-length by using one or more ALTER statements, issue the
ALTER statements within the same unit of work. Reorganize immediately so that
the format is consistent for all of the data rows in the table.

Related concepts:
Table space versions
Related tasks:
Altering the attributes of an identity column
Related reference:
ALTER TABLE (Db2 SQL)

What happens to an index on altered columns

Altering the data type of a column that is contained in an index has implications
for the index.

Example: Assume that the following indexes are defined on the ACCOUNTS table:
CREATE INDEX IX1 ON ACCOUNTS(ACCTID);
CREATE INDEX IX2 ON ACCOUNTS(NAME);

When the data type of the ACCTID column is altered from DECIMAL(4,0) to
INTEGER, the IX1 index is placed in a REBUILD-pending (RBDP) state.

Index inaccessibility and data availability

Whenever possible, Db2 tries to avoid using inaccessible indexes in an effort to

increase data availability. Db2 allows you to insert into, and delete from, tables that

Chapter 3. Altering your database design 149

 have non-unique indexes that are in an RBDP state. Db2 also allows you to delete
from tables that have unique indexes that are in an RBDP state.

REBUILD INDEX with the SHRLEVEL CHANGE option allows read and write
access to the data for most of the rebuild operation.

In certain situations, when an index is inaccessible, Db2 can bypass the index to
allow applications access to the underlying data. In these situations, Db2 offers
accessibility at the expense of performance. In making its determination of the best
access path, Db2 can bypass an index under the following circumstances:
v Dynamic PREPAREs
Db2 avoids choosing an index that is in an RBDP state. Bypassing the index
typically degrades performance, but provides availability that would not be
possible otherwise.
v Cached PREPAREs
Db2 avoids choosing an index that is both in an RBDP state and within a cached
PREPARE statement, because the dynamic cache for the table is invalidated
whenever an index is put into an RBDP state.

In the case of static BINDs, Db2 might choose an index that is in an RBDP state as
the best access path. Db2 does so by making the optimistic assumption that the
index will be available by the time it is actually used. (If the index is not available
at that time, an application can receive a resource unavailable message.)

Padding

When an index is not padded, the value of the PADDED column of the
SYSINDEXES table is set to N. An index is only considered not padded when it is
created with at least one varying length column and either:
v The NOT PADDED keyword is specified.
v The default padding value is NO.

When an index is padded, the value of the PADDED column of the SYSINDEXES
table is set to Y. An index is padded if it is created with at least one varying length
column and either:
v The PADDED keyword is specified
v The default padding is YES.

In the example of the ACCOUNTS table, the IX2 index retains its padding
attribute. The padding attribute of an index is altered only if the value is
inconsistent with the current state of the index. The value can be inconsistent, for
example, if you change the value of the PADDED column in the SYSINDEXES
table after creating the index.

| Whether indexes are padded by default depends on the Db2 release in which the
| index was created and the release in which the system was originally installed:
| v Indexes that were created in a pre-DB2 Version 8 release are padded by default.
| In this case, the value of the PADDED column of the SYSINDEXES catalog table
| is blank (PADDED = ' '). The PADDED column is also blank when there are no
| varying length columns.

150 Administration Guide

| v In subsystems that were migrated from a pre-DB2 Version 8 release, the default
| is to pad all indexes that have a key with at least one varying length column. In
| this case, the value of the PADDED column of the SYSINDEXES catalog table is
| YES (PADDED = 'Y').
| v In subsystems that were originally installed in DB2 Version 8 new-function mode
| or a later Db2 release, indexes that are created with at least one varying length
| column are not padded by default. In this case, the PADDED column of the
| SYSINDEXES catalog table is set to NO (PADDED = 'N').

Related concepts:
Indexes that are padded or not padded (Introduction to Db2 for z/OS)
Related tasks:
Saving disk space by using non-Padded indexes (Db2 Performance)
Related reference:
SYSINDEXES catalog table (Db2 SQL)

Reorganizing table spaces for schema changes

After you commit a schema change, Db2 puts the affected table space in an
advisory REORG-pending (AREO*) state. The table space stays in this state until
you reorganize the table space and apply the schema changes.

Procedure

To reorganize the table space and apply the schema changes:

| Run the REORG TABLESPACE utility. If the table space contains one table, REORG
| TABLESPACE updates the data format for the table to the format of the current
| table space version. If the table space contains more than one table, REORG
| TABLESPACE updates the data format for all tables that are not in version 0
| format to the format of the current table space version. The current table space
| version is the value of CURRENT_VERSION in the SYSIBM.SYSTABLESPACE
| catalog table.
Db2 uses table space versions to maximize data availability. Table space versions
enable Db2 to keep track of schema changes, and simultaneously, provide users
with access to data in altered table spaces. When users retrieve rows from an
altered table, the data is displayed in the format that is described by the most
recent schema definition, even though the data is not currently stored in this
format. The most recent schema definition is associated with the current table
space version.
Although data availability is maximized by the use of table space versions,
performance might suffer because Db2 does not automatically reformat the data in
the table space to conform to the most recent schema definition. Db2 defers any
reformatting of existing data until you reorganize the table space with the REORG
TABLESPACE utility. The more ALTER statements that you commit between
reorganizations, the more table space versions Db2 must track, and the more
performance can suffer.

Recommendation: Run the REORG TABLESPACE utility as soon as possible after

a schema change to correct any performance degradation that might occur and to
keep performance at its highest level.
Related concepts:

Chapter 3. Altering your database design 151

 Table space versions
Row format conversion for table spaces
Related tasks:
Removing in-use table space versions
Related reference:
REORG TABLESPACE (Db2 Utilities)

Table space versions

Db2 creates a table space version each time that you commit one or more specific
schema changes by using the ALTER TABLE statement.

| Versioning is always done at the table space level. The version of a table matches
| the table space version that it corresponds with. For example, consider that you
| have two tables in one table space, which is defined with DEFINE YES. The tables
| are named TABLE1 and TABLE2. The version for both tables and the table space is 0
| (zero). If TABLE1 is altered, the version for TABLE1 becomes SYSTABLES.VERSION = 1,
| and the table space version becomes SYSTABLESPACE.CURRENT_VERSION = 1. At this
| point, the version for TABLE2 is still SYSTABLES.VERSION = 0. Now, when the
| changes for TABLE1 are committed, and TABLE2 is altered, the version for TABLE2
| becomes SYSTABLES.VERSION = 2, which corresponds with the table space version
| of SYSTABLESPACE.CURRENT_VERSION = 2. The version of TABLE2 skips from 0 to 2,
| because SYSTABLESPACE.CURRENT_VERSION = 1 was already used by TABLE1.

The following schema changes might result in Db2 creating a table space version:
v Extending the length of a character (CHAR data type) or graphic (GRAPHIC
data type) column
v Changing the type of a column within character data types (CHAR, VARCHAR)
v Changing the type of a column within graphic data types (GRAPHIC,
VARGRAPHIC)
v Changing the type of a column within numeric data types (SMALL INTEGER,
INTEGER, FLOAT, REAL, FLOAT8, DOUBLE, DECIMAL)
v Adding a column to a table
v Extending the length of a varying character (VARCHAR data type) or varying
graphic (VARGRAPHIC data type) column, if the table already has a version
number that is greater than 0
v Altering the maximum length of a LOB column, if the table already has a
version number that is greater than 0
v Altering the inline length of a LOB column
v Extending the precision of the TIMESTAMP column

In general, Db2 creates only one table space version if you make multiple schema
changes in the same unit of work. If you make these same schema changes in
separate units of work, each change results in a new table space version. For
example, the first three ALTER TABLE statements in the following example are all
associated with the same table space version. The scope of the first COMMIT
statement encompasses all three schema changes. The last ALTER TABLE statement
is associated with the next table space version. The scope of the second COMMIT
statement encompasses a single schema change.

152 Administration Guide

 ALTER TABLE ACCOUNTS ALTER COLUMN NAME SET DATA TYPE VARCHAR(40);
ALTER TABLE ACCOUNTS ALTER COLUMN ADDRESS SET DATA TYPE VARCHAR(60);
ALTER TABLE ACCOUNTS ALTER COLUMN BALANCE SET DATA TYPE DECIMAL(15,2);
COMMIT;

ALTER TABLE ACCOUNTS ALTER COLUMN ACCTID SET DATA TYPE INTEGER;
COMMIT;

When Db2 does not create a new table space version

Db2 does not create a table space version under the following circumstances:
v You add a column to a table in the following situations:
– You created the table space with DEFINE NO, the current version is 0, and
you add a column before adding any data is added to the table. If you
commit the change and add another column, the version is still 0.
– You created the table space with DEFINE YES. After adding a column or
altering a column, committing the change, and adding no data to the table,
you add another column.
– A non-partitioned table space and a table that it contains are not in version 0
format. No data is in the current committed version format. You add a
column to the table.
v You extend the length of a varying character (VARCHAR data type) or varying
graphic (VARGRAPHIC data type) column, and the table does not have a
version number yet.
v You specify the same data type and length that a column currently has, so that
its definition does not actually change.
v You alter the maximum length of a LOB column and the table does not have a
version number yet.
Related tasks:
Altering the data type of a column
Altering the attributes of an identity column

Removing in-use table space versions

To prevent Db2 from running out of table space version numbers, and to prevent
subsequent ALTER statements from failing, you must remove unneeded, in-use
table space versions regularly.

About this task

Db2 can store up to 256 table space versions, numbered sequentially from 0 to 255.
The next consecutive version number after 255 is 1. Version number 0 is never
reused; it is reserved for the original version of the table space. The versions are
associated with schema changes that have not been applied, but are considered to
be in use. The range of used versions is stored in the catalog.

| If a table space has multiple tables, and one table is at version number 0, the oldest
| table space version is 0. When the current table space version reaches 255, you
| need to perform special processing to allow removal of table space versions.

Chapter 3. Altering your database design 153

 Procedure

To remove in-use table space versions:

1. Determine the range of version numbers that are currently in use for a table
space by querying the OLDEST_VERSION and CURRENT_VERSION columns
of the SYSIBM.SYSTABLESPACE catalog table.
Version numbers are considered to be unused if the schema changes that are
associated with them have been applied, and there are no image copies that
contain data at those versions.
| 2. If all reusable version numbers (1 to 255) are currently in use, decrease the
| number of in-use versions by following these steps:
| a. Perform this step only if the table space contains at least one table at
| version 0. Run the REPAIR utility with the INSERTVERSIONPAGES and
| SETCURRENTVERSION options to update the version number for the
| tables that are at version 0 to the current version number of the table space.
| b. Reorganize the table space by running the REORG TABLESPACE utility.
| Doing this converts all data in the table space to the format of the current
| version, and sets OLDEST_VERSION to CURRENT_VERSION, to indicate
| that there is only one in-use version.
| 3. Remove all image copies of the table space by running the MODIFY
| RECOVERY utility:
| MODIFY RECOVERY TABLESPACE table-space-name DSNUM ALL DELETE AGE(*)
| Doing this ensures that there are no image copies with in-use versions.
Related concepts:
The effect of MODIFY RECOVERY on version numbers (Db2 Utilities)
Effects of running REORG TABLESPACE (Db2 Utilities)
Related reference:
Syntax and options of the REPAIR control statement (Db2 Utilities)

Index versions
Db2 uses index versions to maximize data availability. Index versions enable Db2
to keep track of schema changes and provides users with access to data in altered
columns that are contained in indexes.

When users retrieve rows from a table with an altered column, the data is
displayed in the format that is described by the most recent schema definition,
even though the data is not currently stored in this format. The most recent
schema definition is associated with the current index version.

Db2 creates an index version each time you commit one of the following schema
changes:
Table 20. Situations when Db2 creates an index version
Db2 creates this type of corresponding
When you commit this change to a schema index version
Use the ALTER TABLE statement to change A new index version for each index that is
the data type of a non-numeric column that affected by this operation.
is contained in one or more indexes.
Use the ALTER TABLE statement to change A new index version for each index that is
the length of a VARCHAR column that is affected by this operation.
contained in one or more PADDED indexes.

154 Administration Guide

Table 20. Situations when Db2 creates an index version (continued)
Db2 creates this type of corresponding
When you commit this change to a schema index version
Use the ALTER TABLE statement to extend A new index version for each index that is
the length of a CHAR column in a table. affected by this operation.
Use the ALTER INDEX statement to add a One new index version; only one index is
column to an index. affected by this operation.

The index is set to REBUILD-pending status

if the column was not added to the table in
the same commit operation.
Add a new column to both a table and an A new index version for each index that is
index in the same commit operation. affected by this operation.

Exceptions: Db2 does not create an index version under the following
circumstances:
v When the index was created with DEFINE NO
v When you extend the length of a varying-length character (VARCHAR data
type) or varying-length graphic (VARGRAPHIC data type) column that is
contained in one or more indexes that are defined with the NOT PADDED
option
v When you specify the same data type and length that a column (which is
contained in one or more indexes) currently has, such that its definition does not
actually change

Db2 creates only one index version if, in the same unit of work, you make multiple
schema changes to columns that are contained in the same index. If you make
these same schema changes in separate units of work, each change results in a new
index version.
Related tasks:
Recycling index version numbers
Reorganizing indexes

Recycling index version numbers

To prevent Db2 from running out of index version numbers (and to prevent
subsequent ALTER statements from failing), you must recycle unused index
version numbers regularly.

About this task

Db2 can store up to 16 index versions, numbered sequentially from 0 - 15. The next
consecutive version number after 15 is 1. Version number 0 is never reused,
because it is reserved for the original version of the index. The versions that are
associated with schema changes that have not been applied yet are considered to
be “in use,” and the range of used versions is stored in the catalog. In use versions
can be recovered from image copies of the table space, if necessary.

Version numbers are considered to be unused if the schema changes that are
associated with them have been applied and no image copies contain data at those
versions.

Chapter 3. Altering your database design 155

 Procedure

To recycle unused index version numbers:

1.

Determine the range of version numbers that are currently in use for an index
by querying the OLDEST_VERSION and CURRENT_VERSION columns of the
SYSIBM.SYSINDEXES catalog table.

2. Next, run the appropriate utility to recycle unused index version numbers.
v For indexes that are defined as COPY YES, run the MODIFY RECOVERY
utility.
If all reusable version numbers (1 - 15) are currently in use, reorganize the
index by running REORG INDEX or REORG TABLESPACE before you
recycle the version numbers.
v For indexes that are defined as COPY NO, run the REORG TABLESPACE,
REORG INDEX, LOAD REPLACE, or REBUILD INDEX utility. These utilities
recycle the version numbers as they perform their primary functions.
Related concepts:
Index versions

Altering a table for referential integrity

You can alter a table to add, change, or remove referential constraints.

Before you begin

If you plan to let Db2 enforce referential integrity in a set of tables, see Referential
constraints (Db2 Application programming and SQL) for a description of the
requirements for referential constraints. Db2 does not enforce informational
referential constraints.
Related concepts:
Creation of relationships with referential constraints (Introduction to Db2 for
z/OS)
Related tasks:
Creating tables for data integrity (Db2 Application programming and SQL)
Related reference:
ALTER TABLE (Db2 SQL)

Adding referential constraints to existing tables

You can use the ALTER TABLE statement to add referential constraints to existing
tables.

About this task

Assume that the tables in the sample application (the Db2 sample activity table,
project table, project activity table, employee table, and department table) already
exist, have the appropriate column definitions, and are already populated.

156 Administration Guide

Now, suppose that you want to define relationships among the sample tables by
adding primary and foreign keys with the ALTER TABLE statement. The following
rules apply to these relationships:
v An existing table must have a unique index on its primary key columns before
you can add the primary key. The index becomes the primary index.
v You must add the parent key of the parent table before adding the
corresponding foreign key of the dependent table.

You can build the same referential structure in several different ways; however, the
following process might be the simplest to understand.

Procedure

To add a referential constraint to an existing table:

1. Create a unique index on the primary key columns for any table that does not
already have one.
2. For each table, issue the ALTER TABLE statement to add its primary key.
In the next steps, you issue the ALTER TABLE statement to add foreign keys
for each table, except for the activity table. The table space remains in
CHECK-pending status, which you can reset by running the CHECK DATA
utility with the DELETE(YES) option.
Deletions by the CHECK DATA utility are not bound by delete rules. The
deletions cascade to all descendents of a deleted row, which can be disastrous.
For example, if you delete the row for department (A00) from the department
table, the deletion might propagate through most of the referential structure.
The remaining steps prevent deletion from more than one table at a time.
3. Add the foreign keys for the department table and run CHECK DATA
DELETE(YES) on its table space. Then, correct any rows in the exception table,
and use INSERT to replace the rows in the department table. This table is now
consistent with existing data.
4. Drop the foreign key on MGRNO in the department table. This step drops the
association of the department table with the employee table, without changing
the data of either table.
5. Add the foreign key to the employee table, run the CHECK DATA utility again,
and correct any errors. If errors are reported, be particularly careful not to
make any row inconsistent with the department table when you make
corrections.
6. Add the foreign key on MGRNO to the department table, which again leaves
the table space in CHECK-pending status. Then, run the CHECK DATA utility.
If you have not changed the data since the previous check, you can use the
DELETE(YES) option, and the deletions will not cascade.
7. For each of the following tables, in the order shown, add its foreign keys, run
the CHECK DATA utility with the DELETE(YES) option, and correct any rows
that are in error:
a. Project table
b. Project activity table
c. Employee to project activity table

Adding parent keys and foreign keys

You can add primary parent keys, unique parent keys, and foreign keys to an
existing table.

Chapter 3. Altering your database design 157

 About this task

Introductory concepts
Creation of relationships with referential constraints (Introduction to Db2 for
z/OS)
Application of business rules to relationships (Introduction to Db2 for z/OS)

When you add parent keys and foreign keys to an existing table, you must
consider certain restrictions and implications.
v If you add a primary key, the table must already have a unique index on the key
columns. If multiple unique indexes include the primary key columns, the index
that was most recently created on the key columns becomes the primary index.
Because of the unique index, no duplicate values of the key exist in the table;
therefore you do not need to check the validity of the data.
v If you add a unique key, the table must already have a unique index with a key
that is identical to the unique key. If multiple unique indexes include the
primary key columns, Db2 arbitrarily chooses a unique index on the key
columns to enforce the unique key. Because of the unique index, no duplicate
values of the key exist in the table; therefore you do not need to check the
validity of the data.
v You can use only one FOREIGN KEY clause in each ALTER TABLE statement; if
you want to add two foreign keys to a table, you must execute two ALTER
TABLE statements.
v If you add a foreign key, the parent key and unique index of the parent table
must already exist. Adding the foreign key requires the ALTER privilege on the
dependent table and either the ALTER or REFERENCES privilege on the parent
table.
v Adding a foreign key establishes a referential constraint relationship. Db2 does
not validate the data when you add the foreign key. Instead, if the table is
populated (or, in the case of a nonsegmented table space, if the table space has
ever been populated), the table space that contains the table is placed in
CHECK-pending status, just as if it had been loaded with ENFORCE NO. In this
case, you need to execute the CHECK DATA utility to clear the CHECK-pending
status.
v You can add a foreign key with the NOT ENFORCED option to create an
informational referential constraint. This action does not leave the table space in
CHECK-pending status, and you do not need to execute CHECK DATA.

Procedure

To add a key to a table:

1. Choose the type of key that you want to add.

2. Add the key by using the ALTER TABLE statement.

Option Description
Adding a primary key To add a primary key to an existing table,
use the PRIMARY KEY clause in an ALTER
TABLE statement. For example, if the
department table and its index XDEPT1
already exist, create its primary key by
issuing the following statement:
ALTER TABLE DSN8910.DEPT
ADD PRIMARY KEY (DEPTNO);

158 Administration Guide

Option Description
Adding a unique key To add a unique key to an existing table, use
the UNIQUE clause of the ALTER TABLE
statement. For example, if the department
table has a unique index defined on column
DEPTNAME, you can add a unique key
constraint, KEY_DEPTNAME, consisting of
column DEPTNAME by issuing the
following statement:
ALTER TABLE DSN8910.DEPT
ADD CONSTRAINT KEY_DEPTNAME UNIQUE
(DEPTNAME);
Adding a foreign key To add a foreign key to an existing table, use
the FOREIGN KEY clause of the ALTER
TABLE statement. The parent key must exist
in the parent table before you add the
foreign key. For example, if the department
table has a primary key defined on the
DEPTNO column, you can add a referential
constraint, REFKEY_DEPTNO, on the
DEPTNO column of the project table by
issuing the following statement:
ALTER TABLE DSN8910.PROJ
ADD CONSTRAINT REFKEY_DEPTNO FOREIGN
KEY (DEPTNO) REFERENCES DSN8910.DEPT
ON DELETE RESTRICT;

Related tasks:
Creating indexes to improve referential integrity performance for foreign keys
(Db2 Performance)
Related reference:
ALTER TABLE (Db2 SQL)

Dropping parent keys and foreign keys

You can drop primary parent keys, unique parent keys, and foreign keys from an
existing table.

Before you begin

Before you drop a foreign key or a parent key, consider carefully the effects on
your application programs. The primary key of a table serves as a permanent,
unique identifier of the occurrences of the entities it describes. Application
programs often depend on that identifier. The foreign key defines a referential
relationship and a delete rule. Without the key, your application programs must
enforce the constraints.

Procedure

To drop a key, complete the following steps:

1. Choose the type of key that you want to drop.
2. Drop the key by using the ALTER TABLE statement.

Chapter 3. Altering your database design 159

 Option Description
Dropping a foreign key When you drop a foreign key using the
DROP FOREIGN KEY clause of the ALTER
TABLE statement, Db2 drops the
corresponding referential relationships. (You
must have the ALTER privilege on the
dependent table and either the ALTER or
REFERENCES privilege on the parent table.)
If the referential constraint references a
unique key that was created implicitly, and
no other relationships are dependent on that
unique key, the implicit unique key is also
dropped.
Dropping a unique key When you drop a unique key using the
DROP UNIQUE clause of the ALTER TABLE
statement, Db2 drops all the referential
relationships in which the unique key is a
parent key. The dependent tables no longer
have foreign keys. (You must have the
ALTER privilege on any dependent tables.)
The table's unique index that enforced the
unique key no longer indicates that it
enforces a unique key, although it is still a
unique index.
Dropping a primary key When you drop a primary key using the
DROP PRIMARY KEY clause of the ALTER
TABLE statement, Db2 drops all the
referential relationships in which the
primary key is a parent key. The dependent
tables no longer have foreign keys. (You
must have the ALTER privilege on any
dependent tables.) The table's primary index
is no longer primary, although it is still a
unique index.

Adding or dropping table check constraints

You can add or drop check constraints by using the ALTER TABLE statement.

Procedure

To add or drop check constraints:

Issue the ALTER TABLE statement.

160 Administration Guide

 Option Description
Adding check constraints You can define a check constraint on a table
by using the ADD CHECK clause of the
ALTER TABLE statement. If the table is
empty, the check constraint is added to the
description of the table.

If the table is not empty, what happens

when you define the check constraint
depends on the value of the CURRENT
RULES special register, which can be either
STD or Db2.
v If the value is STD, the check constraint is
enforced immediately when it is defined.
If a row does not conform, the table check
constraint is not added to the table and an
error occurs.
v If the value is Db2, the check constraint is
added to the table description but its
enforcement is deferred. Because some
rows in the table might violate the check
constraint, the table is placed in
check-pending status.

The ALTER TABLE statement that is used to

define a check constraint always fails if the
table space or partition that contains the
table is in a CHECK-pending status, the
CURRENT RULES special register value is
STD, and the table is not empty.
Dropping check constraints To remove a check constraint from a table,
use the DROP CONSTRAINT or DROP
CHECK clauses of the ALTER TABLE
statement. You must not use DROP
CONSTRAINT on the same ALTER TABLE
statement as DROP FOREIGN KEY, DROP
CHECK, DROP PRIMARY KEY, or DROP
UNIQUE.

Adding partitions
You can use ALTER TABLE statements to add partitions to all types of partitioned
table spaces.

About this task

You do not need to allocate extra partitions for expected growth when you create
partitioned table spaces because you can add partitions as needed.

You can add a partition as the last logical partition of any table in any type of
partitioned table space.

When you add partitions Db2 always uses the next physical partition that is not
already in use, until you reach the maximum number of partitions for the table
space.

Chapter 3. Altering your database design 161

 When Db2 manages your data sets, the next available data set is allocated for the
table space and for each partitioned index. When you manage your own data sets,
you must first define the data sets for the table space and the partitioned indexes
before you add a partition.

You cannot add or alter a partition for a materialized query table.

Procedure

To add partitions:

Add a partition after the last existing logical partition by issuing an ALTER TABLE
statement. In the ADD PARTITION clause, specify an ENDING AT value beyond
the existing limit of the last logical partition. If the table space is a large table
space, you can use the new partition immediately after the ALTER statement
completes. In this case, the partition is not placed in REORG-pending (REORP)
status because it extends the high-range values that were not previously used. For
non-large table spaces, the partition is placed in REORP status because the last
partition boundary was not previously enforced.

Examples

For example, consider a table space that contains a transaction table named
TRANS. The table is divided into 10 partitions, and each partition contains one
year of data. Partitioning is defined on the transaction date, and the limit key
value is the end of each year. The following table shows a representation of the
table space.
Table 21. An example table space with 10 partitions
Physical partition
Limit value number Data set name that backs the partition
12/31/2010 1 catname.DSNDBx.dbname.psname.I0001.A001
12/31/2011 2 catname.DSNDBx.dbname.psname.I0001.A002
12/31/2013 3 catname.DSNDBx.dbname.psname.I0001.A003
12/31/2013 4 catname.DSNDBx.dbname.psname.I0001.A004
12/31/2014 5 catname.DSNDBx.dbname.psname.I0001.A005
12/31/2015 6 catname.DSNDBx.dbname.psname.I0001.A006
12/31/2016 7 catname.DSNDBx.dbname.psname.I0001.A007
12/31/2017 8 catname.DSNDBx.dbname.psname.I0001.A008
12/31/2018 9 catname.DSNDBx.dbname.psname.I0001.A009
12/31/2019 10 catname.DSNDBx.dbname.psname.I0001.A010

Example 1: adding a partition after the last logical partition

To add a partition for the next year, you can issue the following statement:
ALTER TABLE TRANS ADD PARTITION ENDING AT (’12/31/2020’);

162 Administration Guide

 The following table shows a representative excerpt of the table space after
the partition for the year 2020 is added.
Table 22. An excerpt of the table space, showing the added partition 11
Physical partition
Limit value number Data set name that backs the partition
12/31/2018 9 catname.DSNDBx.dbname.psname.I0001.A009
12/31/2019 10 catname.DSNDBx.dbname.psname.I0001.A010
12/31/2020 11 catname.DSNDBx.dbname.psname.I0001.A011

What to do next

After you add partitions, you might need to complete any of the following actions.
Alter the attributes of added partitions
You might need to alter the attributes of the added partition. The attributes
of the new partition are either inherited or calculated. If it is necessary to
change specific attributes for the new partition, you must issue separate
ALTER TABLESPACE and ALTER INDEX statements after you add the
partition. Examine the catalog to determine whether the inherited values
require changes.
The added partition inherits most attributes from the previous last logical
partition.

For example, if you want to specify the space attributes for a new
partition, use the ALTER TABLESPACE and ALTER INDEX statements. For
example, suppose that the new partition is PARTITION 11 for the table
space and the index. Issue the following statements to specify quantities
for the PRIQTY, SECQTY, FREEPAGE, and PCTFREE attributes:
ALTER TABLESPACE tsname ALTER PARTITION 11
USING STOGROUP stogroup-name
PRIQTY 200 SECQTY 200
FREEPAGE 20 PCTFREE 10;

ALTER INDEX index-name ALTER PARTITION 11

USING STOGROUP stogroup-name
PRIQTY 100 SECQTY 100
FREEPAGE 25 PCTFREE 5;

Create auxiliary objects for LOB columns

If you add a partition to a base table that contains LOB columns, the table
space is explicitly created, and the CURRENT RULES special register is not
'STD', complete the following steps:
1. If necessary after you issue the ALTER TABLE ADD PARTITION
statement, create a LOB table space in the same database as its
associated base table space.

Chapter 3. Altering your database design 163

 2. Create an auxiliary table and associate the new auxiliary table with the
base table.
3. Issue the CREATE UNIQUE INDEX statement to create a unique index
on the auxiliary table.
Related concepts:
Pending data definition changes
Related reference:
ALTER TABLE (Db2 SQL)

Altering partitions
You can use the ALTER TABLE statement to alter the partitions of table spaces.

About this task

You can make the following changes:
v Change the boundary between partitions
v Rotate any logical partition to be the last partition
v Extend the boundary of the last partition
v Instruct Db2 to insert rows at the end of a table or appropriate partition

Procedure

To alter a partition:

Issue the ALTER TABLE statement and specify the options that you want to
change.

Changing the boundary between partitions

You can change the boundary of a partition by explicitly specifying a new value
for the limit key. The limit key is the highest value of the partitioning key for a
partition. The partitioning key is the column or columns that are used to determine
the partitions.

About this task

Alternatively, you can let Db2 determine any appropriate limit key changes to
more evenly distribute the data across partitions. If you want Db2 to determine
any limit key changes, follow the instructions in Redistributing data across
partitions by using REORG (Db2 Utilities).

Procedure

To change the boundary between partitions:

1. Use an ALTER statement to modify the limit key value for each partition
boundary that you want to change.
If the partitioned table space uses table-controlled partitioning, use an ALTER
TABLE statement with the ALTER PARTITION clause to alter the limit key. If
the partitioned table space uses index-controlled partitioning, use an ALTER
INDEX statement with the ALTER PARTITION clause.

164 Administration Guide

| Recommendation: If the table space uses index-controlled partitioning, alter it
| to use table-controlled partitioning before you alter the limit key. You can
| follow the example in Converting table spaces to use table-controlled
| partitioning.
| If you attempt to alter a limit key by using ALTER TABLE, the statement fails if
| both of the following conditions are true:
| v The table space uses index-controlled partitioning.
| v The PREVENT_ALTERTB_LIMITKEY subsystem parameter is set to YES.
| You can change the limit key values of all or most of the partitions. You can
| apply the changes to one or more partitions at a time.
| The effect of altering the limit keys depends on the type of table space:
| v For partition-by-range table spaces and partitioned (non-UTS) table spaces
| with table-controlled partitioning, the data remains available after the limit
| keys are altered.
| In most cases, altering the limit keys for those table spaces is a pending
| definition change that causes the partitions on either side of the boundary to
| be placed in advisory REORG-pending (AREOR) status.
| In some cases, a change to a limit key value is immediately materialized, and
| AREOR status is not set. Immediate materialization occurs when Db2
| determines that both of the following conditions are true:
| – The alteration does not move any data between partitions
| – No other pending definition change exists on the identified partition
| – No pending definition changes exist on the adjacent logical partition
| toward which the alteration moves the limit key of the identified partition.
| v For partitioned (non-UTS) table spaces with index-controlled partitioning,
| altering the limit keys is an immediate definition change. In these cases, the
| partitions on either side of the boundary are placed in REORG-pending
| (REORP) status, and the data is unavailable until the affected range of
| partitions are reorganized.
2. Run the REORG TABLESPACE utility to redistribute data in the partitioned
table space based on the new limit key values.
| This action also resets any AREOR or REORP states. The following example
| specifies options that help maximize performance while reorganizing the data:
REORG TABLESPACE DSN8S11E PART 2:3
NOSYSREC COPYDDN SYSCOPY STATISTICS TABLE INDEX(ALL)
This example reorganizes a range of partitions and includes the STATISTICS
keyword, which means that REORG collects statistics about the specified range
of partitions.
| You can reorganize a range of partitions, even if the partitions are not in
| AREOR or REORP status. However, you cannot reorganize only a subset of the
| range of partitions that are in AREOR or REORP status. You must reorganize
| the entire range to reset the restrictive status and materialize any pending limit
| key changes.
If you run REORG on partitions that are in REORP or advisory
REORG-pending (AREOR) status, consider the values that you set for the
following options:
SHRLEVEL
| You can specify SHRLEVEL REFERENCE or SHRLEVEL CHANGE
| when objects are in AREOR or REORP status. REORG materializes any

Chapter 3. Altering your database design 165

| pending definition changes. If you specify SHRLEVEL NONE, REORG
| does not materialize any pending limit key changes and any restrictive
| states are not reset.
KEEPDICTIONARY
| REORG ignores the KEEPDICTIONARY option for any partition that is
| in REORP or AREOR status. REORG automatically rebuilds the
| dictionaries for the affected partitions. However, if you specify a range
| of partitions that includes some partitions that are not in REORP status,
| REORG accepts the KEEPDICTIONARY option for those nonrestricted
| partitions.
DISCARDDN and PUNCHDDN
Specify the DISCARDDN and PUNCHDDN data sets when the limit
key for the last partition was reduced for a table space that is defined
as LARGE or DSSIZE. Otherwise, REORG terminates and issues
message DSNU035I and return code 8.
REORG writes SYSCOPY records as follows:
v If any partition is in REORP status when REORG runs, Db2 writes a
SYSCOPY record with STYPE=A for each partition that is specified on the
REORG job.
v If you take an inline image copy of a range of partitions, Db2 writes one
SYSCOPY record with ICTYPE=F for each partition. Each record has the
same data set name.
| If REORG materialized any pending limit key changes, the related plans and
| packages are invalidated.
Related tasks:
Creating tables partitioned by data value ranges
Related reference:
ALTER INDEX (Db2 SQL)
ALTER TABLE (Db2 SQL)
Syntax and options of the REORG TABLESPACE control statement (Db2
Utilities)
Advisory or restrictive states (Db2 Utilities)
PREVENT ALTER LIMITKEY field (PREVENT_ALTERTB_LIMITKEY
subsystem parameter) (Db2 Installation and Migration)

Rotating partitions
You can use the ALTER TABLE statement to rotate any logical partition to become
the last partition. Rotating partitions is supported for partitioned (non-UTS) table
spaces and partition-by-range table spaces, but not for partition-by-growth table
spaces.

About this task

Recommendation:

When you create a partitioned table space, you do not need to allocate extra
partitions for expected growth. Instead, you can use the ALTER TABLE ADD
PARTITION statement to add partitions as needed. If rotating partitions is
appropriate for your application, use the ALTER TABLE ROTATE PARTITION

166 Administration Guide

statement to avoid adding another partition.

Nullable partitioning columns: Db2 lets you use nullable columns as partitioning
columns. But with table-controlled partitioning, Db2 can restrict the insertion of
null values into a table with nullable partitioning columns, depending on the order
of the partitioning key. After a rotate operation, if the partitioning key is ascending,
Db2 prevents an INSERT of a row with a null value for the key column. If the
partitioning key is descending, Db2 allows an INSERT of a row with a null value
for the key column. The row is inserted into the first partition.

Procedure

To rotate a partition to be the last partition:

1. Issue the ALTER TABLE statement and specify the ROTATE PARTITION
option.
2. Optional: Run the RUNSTATS utility.

Example

For example, assume that the partition structure of the table space is sufficient
through the year 2006. The following table shows a representation of the table
space through the year 2006. When another partition is needed for the year 2007,
you determined that the data for 1996 is no longer needed. You want to recycle the
partition for the year 1996 to hold the transactions for the year 2007.
Table 23. An excerpt of a partitioned table space
Partition Limit value Data set name that backs the partition
P008 12/31/2004 catname.DSNDBx.dbname.psname.I0001.A008
P009 12/31/2005 catname.DSNDBx.dbname.psname.I0001.A009
P010 12/31/2006 catname.DSNDBx.dbname.psname.I0001.A010

To rotate the first partition for table TRANS to be the last partition, issue the
following statement:
ALTER TABLE TRANS ROTATE PARTITION FIRST TO LAST
ENDING AT (’12/31/2007’) RESET;

For a table with limit values in ascending order, the data in the ENDING AT clause
must be higher than the limit value for previous partitions. Db2 chooses the first
partition to be the partition with the lowest limit value.

For a table with limit values in descending order, the data must be lower than the
limit value for previous partitions. Db2 chooses the first partition to be the
partition with the highest limit value.

Chapter 3. Altering your database design 167

 The RESET keyword specifies that the existing data in the first logical partition is
deleted, and no delete triggers are activated. Because the oldest (or first) partition
is P001, Db2 assigns the new limit value to P001. This partition holds all rows in
the range between the new limit value of 12/31/2007 and the previous limit value
of 12/31/2006. The RESET operation deletes all existing data. You can use the
partition immediately after the ALTER completes. The partition is not placed in
REORG-pending (REORP) status, if the table is large, or if the last partition before
the rotation is empty.

The following table shows a representation of the table space after the first
partition is rotated to become the last partition.
Table 24. Rotating the first partition to be the last partition
Partition Limit value Data set name that backs the partition
P002 12/31/1997 catname.DSNDBx.dbname.psname.I0001.A002
P003 12/31/1998 catname.DSNDBx.dbname.psname.I0001.A003
P004 12/31/1999 catname.DSNDBx.dbname.psname.I0001.A004
P005 12/31/2000 catname.DSNDBx.dbname.psname.I0001.A005
P006 12/31/2001 catname.DSNDBx.dbname.psname.I0001.A006
P007 12/31/2002 catname.DSNDBx.dbname.psname.I0001.A007
P008 12/31/2003 catname.DSNDBx.dbname.psname.I0001.A008
P009 12/31/2004 catname.DSNDBx.dbname.psname.I0001.A009
P010 12/31/2005 catname.DSNDBx.dbname.psname.I0001.A010
P011 12/31/2006 catname.DSNDBx.dbname.psname.I0001.A011
P001 12/31/2007 catname.DSNDBx.dbname.psname.I0001.A001

Extending the boundary of the last partition

You can extend the boundary of the last partition of a table that uses
table-controlled partitioning without impacting data availability.

Procedure

To extend the boundary of the last partition:

Issue the ALTER TABLE statement with the ALTER PARTITION clause to specify a
new boundary for the last partition.

For more details on this process, see “Changing the boundary between partitions”
on page 164.

Example

The following table shows a representation of a table space through the year 2007.
You rotated the first partition to be the last partition. Now, you want to extend the
last partition so that it includes the year 2008.

168 Administration Guide

 Table 25. Table space through the year 2007
Partition Limit value Data set name that backs the partition
P002 12/31/1997 catname.DSNDBx.dbname.psname.I0001.A002
P003 12/31/1998 catname.DSNDBx.dbname.psname.I0001.A003
P004 12/31/1999 catname.DSNDBx.dbname.psname.I0001.A004
P005 12/31/2000 catname.DSNDBx.dbname.psname.I0001.A005
P006 12/31/2001 catname.DSNDBx.dbname.psname.I0001.A006
P007 12/31/2002 catname.DSNDBx.dbname.psname.I0001.A007
P008 12/31/2003 catname.DSNDBx.dbname.psname.I0001.A008
P009 12/31/2004 catname.DSNDBx.dbname.psname.I0001.A009
P010 12/31/2005 catname.DSNDBx.dbname.psname.I0001.A010
P011 12/31/2006 catname.DSNDBx.dbname.psname.I0001.A011
P001 12/31/2007 catname.DSNDBx.dbname.psname.I0001.A001

To extend the boundary of the last partition to include the year 2008, issue the
following statement:
ALTER TABLE TRANS ALTER PARTITION 1 ENDING AT (’12/31/2008’);

You can use the partition immediately after the ALTER statement completes. The
partition is not placed in any restrictive status, because it extends the high-range
values that were not previously used.
Related tasks:
Creating tables partitioned by data value ranges
Related reference:
ALTER TABLE (Db2 SQL)
Advisory or restrictive states (Db2 Utilities)

Splitting the last partition into two

To allow for future growth, you can truncate the last partition of a table space and
move some of the data into a new partition.

About this task

The results of truncating the last partition in a partitioned table space depend on
the table space type, whether there is any possibility that data could fall outside
the truncated partition, and whether the limit key value of the last partition before
truncation is MAXVALUE, MINVALUE, less than MAXVALUE, or greater than
MINVALUE.

| If the partition that you truncate is empty or there is no possibility that data could
| fall outside of the new boundary, and the last partition and the previous partition
| have no pending definition changes, the definition change occurs immediately. No
| restrictive or pending status is necessary.

Chapter 3. Altering your database design 169

| For all other cases, the following table shows the results of truncating the last
| partition.
| Table 26. Results of truncating the last partition
| Limit key of last partition is
| <MAXVALUE or Limit key of last partition is
| Table space type >MINVALUE MAXVALUE or MINVALUE
| A partitioned table space The change is a pending The change is an immediate
| with table-controlled definition change. The definition change. The
| partitioning affected partition is placed in affected partition is placed in
| advisory REORG-pending REORG-pending (REORP)
| (AREOR) status. The data is status. The data in the
| still available, but the partition is unavailable until
| definition change is not REORG is run.
| materialized until REORG is
| run.
| Any partitioned table space The change is an immediate The change is an immediate
| with index-controlled definition change. The definition change. The
| partitioning affected partition is placed in affected partition is placed in
| REORG-pending (REORP) REORG-pending (REORP)
| status. The data in the status. The data in the
| partition is unavailable until partition is unavailable until
| REORG is run. REORG is run.
|

You can reset the advisory REORG-pending or REORG-pending status in one of

the following ways:
| v Run REORG with the DISCARD option to reset the advisory REORG-pending
| status or REORG-pending status, set the new partition boundary, and discard
| the data rows that fall outside of the new boundary.
v Add a partition for the data rows that fall outside of the current partition
boundaries.

The topic describes the procedure for the second choice.

| The following steps assume that the data is in ascending order. The process is
| similar if the columns are in descending order.

Procedure
| v To split a partition into two when the limit key of the last partition is less than
| MAXVALUE:
| 1. Suppose that p1 is the limit key for the last partition. Issue the ALTER
| TABLE statement with the ADD PARTITION clause to add a partition with a
| limit key that is greater than p1.
| 2. Issue the ALTER TABLE statement with the ALTER PARTITION clause to
| specify a limit key that is less than p1 for the partition that is now the
| second-to-last partition. For more details on this process, see Changing the
| boundary between partitions.
| 3. Issue the ALTER TABLE statement with the ALTER PARTITION clause to
| specify p1 for the limit key of the new last partition.
| 4. Issue the REORG TABLESPACE utility on the new second-to-last and last
| partitions to remove the REORG-pending status on the last partition, and
| materialize the changes and remove the advisory REORG-pending status on
| the second-to-last partition.

170 Administration Guide

| v To split a partition into two when the limit key of the last partition is
| MAXVALUE, and the last partition and the previous partition have no pending
| definition changes:
| 1. Issue the ALTER TABLE statement with the ALTER PARTITION clause to
| specify limit key p1, which is less than MAXVALUE, for the last partition.
| For more details on this process, see Changing the boundary between
| partitions.
| 2. Issue the ALTER TABLE statement with the ADD PARTITION clause to add
| a new last partition, with a limit key that is greater than p1.
| 3. Issue the REORG TABLESPACE utility on the new second-to-last and last
| partitions to remove the REORG-pending status.

Example

For example, the following table shows a representation of a table space through
the year 2015, where each year of data is saved in separate partitions. Assume that
you want to split the data for 2015 into two partitions.

| You want to create a partition to include the data for the last six months of 2015
| (from 07/01/2015 to 12/31/2015). You also want partition P001 to include only the
| data for the first six months of 2015 (through 06/30/2015).
Table 27. Table space with each year of data in a separate partition
Partition Limit value Data set name that backs the partition
P002 12/31/2005 catname.DSNDBx.dbname.psname.I0001.A002
P003 12/31/2006 catname.DSNDBx.dbname.psname.I0001.A003
P004 12/31/2007 catname.DSNDBx.dbname.psname.I0001.A004
P005 12/31/2008 catname.DSNDBx.dbname.psname.I0001.A005
P006 12/31/2009 catname.DSNDBx.dbname.psname.I0001.A006
P007 12/31/2010 catname.DSNDBx.dbname.psname.I0001.A007
P008 12/31/2011 catname.DSNDBx.dbname.psname.I0001.A008
P009 12/31/2012 catname.DSNDBx.dbname.psname.I0001.A009
P010 12/31/2013 catname.DSNDBx.dbname.psname.I0001.A010
P011 12/31/2014 catname.DSNDBx.dbname.psname.I0001.A011
P001 12/31/2015 catname.DSNDBx.dbname.psname.I0001.A001

| To create a new last partition, issue the following statement:

| ALTER TABLE TRANS ADD PARTITION ENDING AT (’01/31/2016’);

| To truncate partition P001 to include data only through 06/30/2015, issue the
| following statement:
| ALTER TABLE TRANS ALTER PARTITION 1 ENDING AT (’06/30/2015’);

| To preserve the last partition key limit of 12/31/2015, issue the following
| statement:
| ALTER TABLE TRANS ALTER PARTITION 12 ENDING AT (’12/31/2015’);

Chapter 3. Altering your database design 171

 The following table shows a portion of the table space and the modified partitions:
Table 28. Table space with one year split into two partitions
Partition Limit value Data set name that backs the partition
P011 12/31/2014 catname.DSNDBx.dbname.psname.I0001.A011
P001 06/30/2015 catname.DSNDBx.dbname.psname.I0001.A001
P012 12/31/2015 catname.DSNDBx.dbname.psname.I0001.A012

Related reference:
ALTER TABLE (Db2 SQL)
Advisory or restrictive states (Db2 Utilities)

Inserting rows at the end of a partition

To specify how you want Db2 to insert rows at the end of a partition, you can use
the CREATE TABLE or ALTER TABLE statement.

Procedure

To insert rows at the end of a partition:

Issue a CREATE TABLE or ALTER TABLE statement and specify the APPEND
option. The APPEND option has the following settings:
YES Requests data rows to be placed into the table by disregarding the
clustering during SQL INSERT and online LOAD operations. Rather than
attempting to insert rows in cluster-preserving order, rows are appended at
the end of the table or appropriate partition.
NO Requests standard behavior of SQL INSERT and online LOAD operations,
namely that they attempt to place data rows in a well clustered manner
with respect to the value in the row's cluster key columns. NO is the
default option.

After populating a table with the APPEND option in effect, you can achieve
clustering by running the REORG utility.

Restriction: You cannot specify the APPEND option for tables created in XML or
work file table spaces.

Adding XML columns

You can add XML columns to regular relational tables by using the ALTER TABLE
statement.

About this task

When you add an XML column to a table, an XML table and XML table space are
implicitly created to store the XML data. If the new XML column is the first XML
column that you created for the table, Db2 also implicitly creates a BIGINT DOCID
column to store a unique document identifier for the XML columns of a row.

172 Administration Guide

 Db2 also implicitly creates indexes. If this is the first XML column that you created
for the table, Db2 implicitly creates an index on the DOCID column of the base
table.

An XML column has several restrictions. The column cannot:

v Be specified as part of the primary key
v Be specified as part of a UNIQUE key
v Have a DEFAULT value specified
v Be specified as part of the FOREIGN KEY references clause
v Be specified as part of the REFERENCES table-name clause
v Be specified in the PARTITION BY RANGE clause
v Be used in a materialized query table even if the table is specified WITH NO
DATA
v Be referenced in CHECK constraints
v Have GENERATED specified
v Have a FIELDPROC specified
v Have AS SECURITY LABEL specified
v Be added to a created temporary table
v The table that contains an XML column will not have its XML column value
passed to a VALIDPROC
v Be part of a transition table

Procedure

To add an XML column to an existing table:

Issue the ALTER TABLE statement and specify the ADD column-name XML option.

Example
ALTER TABLE orders ADD shipping_info XML;

Related tasks:
Altering implicitly created XML objects
Related reference:
ALTER TABLE (Db2 SQL)

| Altering tables for hash access (deprecated)

You can alter existing tables to take advantage of hash access organization to
| enable queries that access individual rows in a table. Hash-organized table spaces
| are deprecated and likely to be unsupported in the future.

Before you begin

Deprecated function:

Chapter 3. Altering your database design 173

| Hash-organized tables are deprecated. Beginning in Db2 12, packages that are
| bound with APPLCOMPAT(V12R1M504) or higher cannot create hash-organized
| tables or alter existing tables to use hash-organization. Existing hash-organized
| tables remain supported, but they are likely to be unsupported in the future.

Hash organization is only available for universal (UTS) table space types. If you
want to enable hash access on a table space of another type, you must first alter
the table space to a UTS type.

About this task

Enabling hash access requires a table space reorganization, and disables some
features such as index clustering.

Procedure

To alter an existing table to take advantage of hash organization:

1. Specify ADD ORGANIZE BY HASH in the organization-clause of your ALTER
TABLE statement.
a. Specify UNIQUE followed by the column names for one or more columns
that contain unique values in each row. You can specify more than one
column-name as long as no two rows in the table have the same values in
those columns. You can only specify columns that are defined as NOT
NULL. You can specify a maximum of 64 columns to be used as unique
identifiers for hash access. The sum of the column length attributes must
not exceed 255. Db2 maintains the uniqueness of the hash key columns, and
an index is not needed for this purpose.
b. Specify HASH SPACE followed by an integer and a modifier that specifies
the size of the hash space. You can specify the size of the hash space in
kilobytes, megabytes, and gigabytes. Specify:
v K for kilobytes
v M for megabytes
v G for gigabytes
You can specify a size that is larger than your data to minimize the
overhead of access to data that overflows the hash space. The size that you
specify is most important if you do not intend to immediately reorganize
the table space and specify the AUTOESTSPACE(YES) option, as is
recommended below. In that case, for more information about choosing an
appropriate size for the hash space, see Managing space and page size for
hash-organized tables (Db2 Performance).
2. Commit the ALTER TABLE statement.
3. Run the REORG TABLESPACE utility on the table space where your altered
table is located. If you specify AUTOESTSPACE(YES) in the REORG
TABLESPACE statement,Db2 automatically estimates the best size for the hash
space based on information from the real-time statistics tables. If you specify
AUTOESTSPACE(NO) in the REORG TABLESPACE statement, Db2 uses the
hash space that you specified.

Example

Consider the following ALTER TABLE statement:

174 Administration Guide

 ALTER TABLE EMP
ADD ORGANIZE BY HASH UNIQUE (EMPNO)
HASH SPACE 64 M;

In this example the user alters the EMP table, specifies to ADD ORGANIZE BY
HASH, sets the EMPNO column as the unique identifier, and specifies a HASH
SPACE of 64 with the modifier M for megabytes.

What to do next

Monitor the real-time-statistics information about your table to verify that the hash
access path is used regularly and to verify that the use of disk space is optimized.
Related tasks:
| Organizing tables for hash access to individual rows (deprecated) (Db2
Performance)
Managing space and page size for hash-organized tables (Db2 Performance)
| Monitoring hash access (deprecated) (Db2 Performance)
| Altering the size of your hash spaces (deprecated)
| Creating tables that use hash organization (deprecated)
Related reference:
ALTER TABLE (Db2 SQL)
REORG TABLESPACE (Db2 Utilities)

| Altering the size of your hash spaces (deprecated)

You can alter the size of your hash spaces when you are monitoring and tuning
| the performance of tables that are organized by hash. Hash-organized table spaces
| are deprecated and likely to be unsupported in the future.

About this task

Deprecated function:

| Hash-organized tables are deprecated. Beginning in Db2 12, packages that are
| bound with APPLCOMPAT(V12R1M504) or higher cannot create hash-organized
| tables or alter existing tables to use hash-organization. Existing hash-organized
| tables remain supported, but they are likely to be unsupported in the future.

When you tune the performance of tables that are organized by hash, you can alter
the size of the hash space with the ALTER TABLE statement.

Procedure

To alter the size of the hash space for a table, use one of the following approaches:
v Run the REORG TABLESPACE utility on the table space and specify
AUTOESTSPACE YES in the REORG TABLESPACE statement. Db2
automatically estimates a size for the hash space based on information from the
real-time statistics tables. If you specify AUTOESTSPACE NO in the REORG
TABLESPACE statement, Db2 uses the hash space that you explicitly specified
for the table space.

Chapter 3. Altering your database design 175

 v Specify ALTER ORGANIZATION in an ALTER TABLE statement.
1. Specify SET HASH SPACE followed by an integer and a modifier specifying
the size of the hash space. You can specify the size of the hash space in
kilobytes, megabytes, and gigabytes. Specify:
– K for kilobytes
– M for megabytes
– G for gigabytes
Specify the size of your hash space based on the predicted size of the table.
For more information about choosing an appropriate size for the hash space,
see Managing space and page size for hash-organized tables (Db2
Performance). For example, the following statement specifies a size of 64
megabytes for the hash space of the EMP table:
ALTER TABLE EMP
ALTER ORGANIZATION SET HASH SPACE 64 M;
2. Commit the ALTER TABLE statement.

What to do next

Monitor the real-time-statistics information about your table to ensure that the
hash access path is used regularly and that your disk space is used efficiently.
Related tasks:
| Organizing tables for hash access to individual rows (deprecated) (Db2
Performance)
Managing space and page size for hash-organized tables (Db2 Performance)
| Monitoring hash access (deprecated) (Db2 Performance)
| Altering tables for hash access (deprecated)
Related reference:
ALTER TABLE (Db2 SQL)
REORG TABLESPACE (Db2 Utilities)

Adding a system period and system-period data versioning to

an existing table
You can alter existing tables to use system-period data versioning.

About this task

A system period is a system-maintained period in which Db2 maintains the

beginning and ending timestamp values for a row.

The row-begin column of the system period contains the timestamp value for when
a row is created. The row-end column contains the timestamp value for when a row
is removed. A transaction-start-ID column contains a unique timestamp value that
Db2 assigns per transaction, or the null value.

For a list of restrictions that apply to tables that use system-period data versioning,
see Restrictions for system-period data versioning.

Procedure

To add a system period to a table and define system-period data versioning:

176 Administration Guide

 1. Issue the ALTER TABLE statement on the base table to alter or add row-begin,
row-end, and transaction-start-ID columns, and to define the system period.
After you alter the table, it must have the following attributes:
v A row-begin column that is defined as TIMESTAMP(12) NOT NULL with the
GENERATED ALWAYS AS ROW BEGIN attribute.
v A row-end column that is defined as TIMESTAMP(12) NOT NULL with the
GENERATED ALWAYS AS ROW END attribute.
v A system period (SYSTEM_TIME) defined on two timestamp columns. The
first column is the row-begin column and the second column is the row-end
column.
| v A transaction-start-ID column that defined as TIMESTAMP(12) NOT NULL
| with the GENERATED ALWAYS AS TRANSACTION START ID attribute.
v The only table in the table space
v The table definition is complete
2. Issue a CREATE TABLE statement to create a history table that will correspond
with the system-period temporal table. The history table must have the
following attributes:
v The same number of columns as the system-period temporal table that it
corresponds to
v Columns with the same names, data types, null attributes, CCSIDs, subtypes,
hidden attributes, and field procedures as the corresponding system-period
temporal table. However, the history table cannot have any GENERATED
ALWAYS columns unless the system-period temporal table has a ROWID
GENERATED ALWAYS or ROWID GENERATED BY DEFAULT column. In
that case, the history table must have a corresponding ROWID GENERATED
ALWAYS column. .
v The only table in the table space
v The table definition is complete
| A history table cannot be a materialized query table, an archive-enabled table,
| or an archive table, cannot have a clone table defined on it, and cannot have
| the following attributes:
v Identity columns or row change timestamp columns
v ROW BEGIN, ROW END, or TRANSACTION START ID columns
v Column masks
v Row permissions
v Security label columns
v System or application periods
3. Issue the ALTER TABLE ADD VERSIONING statement with the USE HISTORY
TABLE clause to define system-period data versioning on the table. This step
establishes a link between the system-period temporal table and the history
table.

Example

For example, consider that you created a table named policy_info by issuing the
following CREATE TABLE statement:
CREATE TABLE policy_info
(policy_id CHAR(10) NOT NULL,
coverage INT NOT NULL);

Chapter 3. Altering your database design 177

 Issue the following ALTER TABLE statements to add the begin and end columns
and a system period to the table:
ALTER TABLE policy_info ADD COLUMN sys_start TIMESTAMP(12) NOT NULL
GENERATED ALWAYS AS ROW BEGIN;

ALTER TABLE policy_info ADD COLUMN sys_end TIMESTAMP(12) NOT NULL

GENERATED ALWAYS AS ROW END;

ALTER TABLE policy_info ADD COLUMN trans_id TIMESTAMP(12);

GENERATED ALWAYS AS TRANSACTION START ID;

ALTER TABLE policy_info

ADD PERIOD SYSTEM_TIME(sys_start, sys_end);

To create a history table for this system-period temporal table, issue the following
CREATE TABLE statement:
CREATE TABLE hist_policy_info
(policy_id CHAR(10) NOT NULL,
coverage INT NOT NULL,
sys_start TIMESTAMP(12) NOT NULL,
sys_end TIMESTAMP(12) NOT NULL,
trans_id TIMESTAMP(12));

To define system-period data versioning between the system-period temporal table

and the history table, issue the following ALTER TABLE statement:
ALTER TABLE policy_info
ADD VERSIONING USE HISTORY TABLE hist_policy_info;

Related concepts:
Temporal tables and data versioning
Related information:
Managing Ever-Increasing Amounts of Data with IBM Db2 for z/OS: Using
Temporal Data Management, Archive Transparency, and the IBM Db2 Analytics
Accelerator for z/OS (IBM Redbooks)

Adding an application period to a table

You can alter a table to add an application period so that you maintain the
beginning and ending values for a row.

Procedure

To add an application period to a table:

Issue the ALTER TABLE statement with the ADD PERIOD BUSINESS_TIME
clause. The table becomes an application-period temporal table.

Example

For example, consider that you created a table named policy_info by issuing the
following CREATE TABLE statement:

178 Administration Guide

 CREATE TABLE policy_info
(policy_id CHAR(4) NOT NULL,
coverage INT NOT NULL,
bus_start DATE NOT NULL,
bus_end DATE NOT NULL);

You can add an application period to this table by issuing the following ALTER
TABLE statement:
ALTER TABLE policy_info ADD PERIOD BUSINESS_TIME(bus_start, bus_end);

You also can add a unique index to the table by issuing the following CREATE
INDEX statement:
CREATE UNIQUE INDEX ix_policy
ON policy_info (policy_id, BUSINESS_TIME WITHOUT OVERLAPS);

Restriction: You cannot issue the ALTER INDEX statement with ADD
BUSINESS_TIME WITHOUT OVERLAPS. Db2 issues SQL error code -104 with
SQLSTATE 20522.

Manipulating data in a system-period temporal table

You can do update, insert, delete, and merge operations on a system-period
temporal table.

| Before you begin

| Before you do any of these operations on a system-period temporal table, if your
| application is bound with SYSTIMESENSITIVE YES, make sure that the CURRENT
| TEMPORAL SYSTEM_TIME special register is null. Otherwise, if a value is in
| effect for this special register, update, insert, delete, and merge operations on
| system-period temporal tables are blocked.

Procedure

To manipulate data in a system-period temporal table:

Issue INSERT, UPDATE, DELETE, or MERGE statements to make the changes that
you want. Timestamp information is stored in the timestamp columns, and
historical rows are moved to the history table.

Restriction: You cannot issue SELECT FROM DELETE or SELECT FROM UPDATE
statements when the FOR PORTION OF option is specified for either the UPDATE
statement or the DELETE statement. Db2 issues an error in both of these cases
(SQL error code -104 with SQLSTATE 20522).

Example

The following example shows how you can insert data in the POLICY_INFO table
by specifying the DEFAULT keyword in the VALUES clause for each of the
generated columns:
INSERT INTO POLICY_INFO
VALUES (’A123’, 12000, DEFAULT, DEFAULT, DEFAULT);

Chapter 3. Altering your database design 179

 Related concepts:
Temporal tables and data versioning
Related reference:
CURRENT TEMPORAL SYSTEM_TIME (Db2 SQL)
SYSTIMESENSITIVE bind option (Db2 Commands)

Altering materialized query tables

You can use the ALTER TABLE statement to change a materialized query table to a
base table, or to change the attributes of a materialized query table.

Materialized query tables enable Db2 to use automatic query rewrite to optimize
queries. Automatic query rewrite is a process that Db2 uses to examine a query
and, if appropriate, to rewrite the query so that it executes against a materialized
query table that has been derived from the base tables in the submitted query.

| You can also use the ALTER TABLE statement to register an existing table as a
| materialized query table. For more information, see Registering an existing table as
| a materialized query table (Db2 Performance).
Related tasks:
Altering an existing materialized query table (Db2 Performance)

Changing a materialized query table to a base table

You can use the ALTER TABLE statement to change a materialized query table into
a base table.

Procedure

To change a materialized query table to a base table:

Issue an ALTER TABLE statement and specify the DROP MATERIALIZED QUERY
option. For example,
ALTER TABLE TRANSCOUNT DROP MATERIALIZED QUERY;

What to do next

After you issue this statement, Db2 can no longer use the table for query
optimization, and you cannot populate the table by using the REFRESH TABLE
statement.

Changing the attributes of a materialized query table

You can use the ALTER TABLE statement to change the attributes of an existing
materialized query table.

180 Administration Guide

 Procedure

To change the attributes of an existing materialized query table:

1. Issue the ALTER TABLE statement.
2. Decide which attributes to alter.

Option Description
Enable or disable automatic query rewrite. By default, when you create or register a
materialized query table, Db2 enables it for
automatic query rewrite. To disable
automatic query rewrite, issue the following
statement:
ALTER TABLE TRANSCOUNT DISABLE QUERY
OPTIMIZATION;
Switch between system-maintained and By default, a materialized query table is
user-maintained. system-maintained; the only way you can
change the data is by using the REFRESH
TABLE statement. To change to a
user-maintained materialized query table,
issue the following statement:
ALTER TABLE TRANSCOUNT SET MAINTAINED
BY USER;
Change back to a system-maintained Specify the MAINTAINED BY SYSTEM
materialized query table. option.

Changing the definition of a materialized query table

After you create a materialized query table, you can change the definition in one of
two ways.

Procedure

To change the definition of an existing materialized query table, use one of the
following approaches:
v Optional: Drop and re-create the materialized query table with a different
definition.
v Optional: Use ALTER TABLE statement to change the materialized query table
into a base table. Then, change it back to a materialized query table with a
different but equivalent definition (that is, with a different but equivalent
SELECT for the query).

Altering the assignment of a validation routine

You can use the ALTER TABLE statement to make certain changes to a validation
exit routine that is associated with a table, if one exists.

About this task

Chapter 3. Altering your database design 181

 If you have a validation exit routine associated with a table, you can use the
ALTER TABLE statement to make the following changes:
v Disassociate the validation routine from the table using the VALIDPROC NULL
clause. The routine is no longer given control when Db2 accesses the table. For
example:
ALTER TABLE DSN8910.EMP
VALIDPROC NULL;
v Assign a new validation routine to the table using the VALIDPROC clause.
(Only one validation routine can be connected to a table at a time; so if a
validation routine already exists, Db2 disconnects the old one and connects the
new routine.) Rows that existed before the connection of a new validation
routine are not validated. In this example, the previous validation routine is
disconnected and a new routine is connected with the program name
EMPLNEWE:
ALTER TABLE DSN8910.EMP
VALIDPROC EMPLNEWE;

To ensure that the rows of a table conform to a new validation routine, you must
run the validation routine against the old rows. One way to accomplish this is to
use the REORG and LOAD utilities.

Procedure

To ensure that the rows of a table conform to a new validation routine by using
the REORG and LOAD utilities:
1. Use REORG to reorganize the table space that contains the table with the new
validation routine. Specify UNLOAD ONLY, as in this example:
REORG TABLESPACE DSN8D91A.DSN8S91E
UNLOAD ONLY
This step creates a data set that is used as input to the LOAD utility.
2. Run LOAD with the REPLACE option, and specify a discard data set to hold
any invalid records. For example,
LOAD INTO TABLE DSN8910.EMP
REPLACE
FORMAT UNLOAD
DISCARDDN SYSDISC

The EMPLNEWE validation routine validates all rows after the LOAD step has
completed. Db2 copies any invalid rows into the SYSDISC data set.

Altering a table to capture changed data

You can use the ALTER TABLE statement to write data changes for that table to a
log in an expanded format.

Procedure

To alter a table to capture changed data:

1. Issue an ALTER TABLE statement.
2. Specify the DATA CAPTURE CHANGES option.

182 Administration Guide

 What to do next

You can retrieve the log by using a program such as the log apply feature of the
Remote Recovery Data Facility (RRDF) program offering, or Db2 DataPropagator.

LOB values are not available for DATA CAPTURE CHANGES. To return a table
back to normal logging, use DATA CAPTURE NONE.

Changing an edit procedure or a field procedure

You cannot use ALTER TABLE to change the assignment of an edit procedure or a
field procedure. However, with the assistance of Db2 utilities, you can change an
existing edit procedure or field procedure.

Procedure

To change an edit procedure or a field procedure for a table space in which the
maximum record length is less than 32 KB, use the following procedure:
1. Run the UNLOAD utility or run the REORG TABLESPACE utility with the
UNLOAD EXTERNAL option to unload the data and decode it using the
existing edit procedure or field procedure.
These utilities generate a LOAD statement in the data set (specified by the
PUNCHDDN option of the REORG TABLESPACE utility) that you can use to
reload the data into the original table space.
If you are using the same edit procedure or field procedure for many tables,
unload the data from all the table spaces that have tables that use the
procedure.
2. Modify the code of the edit procedure or the field procedure.
3. After the unload operation is completed, stop Db2.
4. Link-edit the modified procedure, using its original name.
5. Start Db2.
6. Use the LOAD utility to reload the data. LOAD then uses the modified
procedure or field procedure to encode the data.

What to do next
To change an edit procedure or a field procedure for a table space in which the
maximum record length is greater than 32 KB, use the DSNTIAUL sample program
to unload the data.

Altering the subtype of a string column

| If you add a column with a string data type, you can specify its subtype in the
| ALTER TABLE statement. Subtypes are valid for string columns of data types
| CHAR, VARCHAR, and CLOB.

| About this task

| The subtype is stored in the FOREIGNKEY column of SYSIBM.SYSCOLUMNS.

| An M in the FOREIGNKEY column when the MIXED DATA installation option is

| NO for a string column in an ASCII or EBCDIC table is interpreted as SBCS data,
| not MIXED data.

Chapter 3. Altering your database design 183

 Procedure

To alter the subtype of an existing string column:

Issue the ALTER TABLE statement.

For example:
ALTER TABLE table-name ALTER COLUMN column-name
SET DATA TYPE altered-data-type

Related reference:
ALTER TABLE (Db2 SQL)

Altering the attributes of an identity column

You can change the attributes of an identity column by using the ALTER TABLE
statement.

Procedure

To change the attributes of an identity column:

1. Issue an ALTER TABLE statement.
2. Specify the ALTER COLUMN option. This clause changes all of the attributes
of an identity column except the data type. However, if the ALTER TABLE
statement is rolled back, a gap in the sequence of identity column values can
occur because of unassigned cache values.

What to do next

Changing the data type of an identity column, like changing some other data
types, requires that you drop and then re-create the table.
Related concepts:
Identity columns (Db2 Application programming and SQL)
Table space versions
Related tasks:
Altering the data type of a column
Changing data types by dropping and re-creating the table
Related reference:
ALTER TABLE (Db2 SQL)

Changing data types by dropping and re-creating the table

Some changes to a table cannot be made with the ALTER TABLE statement.

About this task

For example, you must make the following changes by redefining the column (that
is, dropping the table and then re-creating the table with the new definitions):
v An original specification of CHAR (25) to CHAR (20)

184 Administration Guide

v A column defined as INTEGER to SMALLINT
v A column defined as NOT NULL to allow null values
v The data type of an identity column

Procedure

To change data types:

1. Unload the table.
2. Drop the table.
Attention: Be very careful about dropping a table. In most cases, recovering a
dropped table is nearly impossible. If you decide to drop a table, remember
that such changes might invalidate a package.
You must alter tables that have been created with RESTRICT ON DROP to
remove the restriction before you can drop them.
3. Commit the changes.
4. Re-create the table.

If the table has an identity column:

v Choose carefully the new value for the START WITH attribute of the identity
column in the CREATE TABLE statement if you want the first generated
value for the identity column of the new table to resume the sequence after
the last generated value for the table that was saved by the unload in step 1.
v Define the identity column as GENERATED BY DEFAULT so that the
previously generated identity values can be reloaded into the new table.

5. Reload the table.

Related tasks:
Altering the attributes of an identity column

Implications of dropping a table

Dropping a table has several implications that you should be aware of.

The DROP TABLE statement deletes a table. For example, to drop the project table,
run the following statement:
DROP TABLE DSN8910.PROJ;

The statement deletes the row in the SYSIBM.SYSTABLES catalog table that
contains information about DSN8910.PROJ. This statement also drops any other
objects that depend on the project table. This action results in the following
implications:
v The column names of the table are dropped from SYSIBM.SYSCOLUMNS.
v If the dropped table has an identity column, the sequence attributes of the
identity column are removed from SYSIBM.SYSSEQUENCES.
v If triggers are defined on the table, they are dropped, and the corresponding
rows are removed from SYSIBM.SYSTRIGGERS and SYSIBM.SYSPACKAGES.
v Any views based on the table are dropped.
v Packages that involve the use of the table are invalidated.
v Cached dynamic statements that involve the use of the table are removed from
the cache.

Chapter 3. Altering your database design 185

 v Synonyms for the table are dropped from SYSIBM.SYSSYNONYMS.
v Indexes created on any columns of the table are dropped, along with any
pending changes that are associated with the index.
v Referential constraints that involve the table are dropped. In this case, the project
table is no longer a dependent of the department and employee tables, nor is it a
parent of the project activity table.
v Authorization information that is kept in the Db2 catalog authorization tables is
updated to reflect the dropping of the table. Users who were previously
authorized to use the table, or views on it, no longer have those privileges,
because catalog rows are deleted.
v Access path statistics and space statistics for the table are deleted from the
catalog.
v The storage space of the dropped table might be reclaimed.
– If the table space containing the table is implicitly created (using the CREATE
TABLE statement without the TABLESPACE clause), the table space and any
pending changes that are associated with the table space are also dropped. If
the data sets are in a storage group, dropping the table space reclaims the
space. For user-managed data sets, you must reclaim the space yourself.
– If the table space containing the table is partitioned, or contains only the one
table, you can drop the table space.
– If the table space containing the table is segmented, Db2 reclaims the space.
– If the table space containing the table is simple, and contains other tables, you
must run the REORG utility to reclaim the space.
v If the table contains a LOB column, the auxiliary table and the index on the
auxiliary table are dropped. The LOB table space is dropped if it was created
with SQLRULES(STD).

If a table has a partitioning index, you must drop the table space or use LOAD
REPLACE when loading the redefined table. If the CREATE TABLE that is used to
redefine the table creates a table space implicitly, commit the DROP statement
before re-creating a table by the same name. You must also commit the DROP
statement before you create any new indexes with the same name as the original
indexes.

Related tasks:
Dropping and re-creating a table space to change its attributes

Objects that depend on the dropped table

Before dropping a table, check to see what objects are dependent on the table. The
Db2 catalog tables SYSIBM.SYSVIEWDEP, SYSIBM.SYSPLANDEP, and
SYSIBM.SYSPACKDEP indicate what views, application plans, and packages are
dependent on different Db2 objects.

Finding dependent views

The following example query lists the views, with their creators, that are affected if
you drop the project table:

186 Administration Guide

SELECT DNAME, DCREATOR
FROM SYSIBM.SYSVIEWDEP
WHERE BNAME = ’PROJ’
AND BCREATOR = ’DSN8910’
AND BTYPE = ’T’;

Finding dependent packages

The next example lists the packages, identified by the package name, collection ID,
and consistency token (in hexadecimal representation), that are affected if you drop
the project table:
SELECT DNAME, DCOLLID, HEX(DCONTOKEN)
FROM SYSIBM.SYSPACKDEP
WHERE BNAME = ’PROJ’
AND BQUALIFIER = ’DSN8910’
AND BTYPE = ’T’;

Finding dependent plans

The next example lists the plans, identified by plan name, that are affected if you
drop the project table:
SELECT DNAME
FROM SYSIBM.SYSPLANDEP
WHERE BNAME = ’PROJ’
AND BCREATOR = ’DSN8910’
AND BTYPE = ’T’;

Finding other dependencies

In addition, the SYSIBM.SYSINDEXES table tells you what indexes currently exist
on a table. From the SYSIBM.SYSTABAUTH table, you can determine which users
are authorized to use the table.

Re-creating a table
You can re-create a Db2 table to decrease the length attribute of a string column or
the precision of a numeric column.

Procedure

To re-create a Db2 table:

Chapter 3. Altering your database design 187

 1. If you do not have the original CREATE TABLE statement and all authorization
statements for the table (for example, call the table T1), query the catalog to
determine its description, the description of all indexes and views on it, and all
users with privileges on it.
2. Create a new table (for example, call the table T2) with the attributes that you
want.
3. Copy the data from the old table T1 into the new table T2 by using one of the
following methods:
a. Issue the following INSERT statement:

INSERT INTO T2
SELECT * FROM T1;

b. Load data from your old table into the new table by using the INCURSOR
option of the LOAD utility. This option uses the Db2 UDB family
cross-loader function.
4. Issue the statement DROP TABLE T1. If T1 is the only table in an explicitly
created table space, and you do not mind losing the compression dictionary, if
one exists, you can drop the table space instead. By dropping the table space,
the space is reclaimed.
5. Commit the DROP statement.
6. Use the statement RENAME TABLE to rename table T2 to T1.
7. Run the REORG utility on the table space that contains table T1.
8. Notify users to re-create any synonyms, indexes, views, and authorizations they
had on T1.

What to do next

If you want to change a data type from string to numeric or from numeric to
string (for example, INTEGER to CHAR or CHAR to INTEGER), use the CHAR
and DECIMAL scalar functions in the SELECT statement to do the conversion.
Another alternative is to use the following method:
1. Use UNLOAD or REORG UNLOAD EXTERNAL (if the data to unload in less
than 32 KB) to save the data in a sequential file, and then
2. Use the LOAD utility to repopulate the table after re-creating it. When you
reload the table, make sure you edit the LOAD statement to match the new
column definition.

This method is particularly appealing when you are trying to re-create a large
table.

Moving a table to a table space of a different page size

You can alter a table to use a different page size, or you can move a table to a table
space of a different page size.

Procedure

To move a table to a table space of a different page size:

188 Administration Guide

 1. Unload the table using UNLOAD FROM TABLE or REORG UNLOAD
EXTERNAL FROM TABLE.
2. Use CREATE TABLE LIKE on the table to re-create it in the table space of the
new page size.
3. Use Db2 Control Center, Db2 Administration Tool for z/OS, or catalog queries
to determine the dependent objects: views, authorization, plans, packages,
synonyms, triggers, referential integrity, and indexes.
4. Drop the original table.
5. Rename the new table to the name of the old table using RENAME TABLE.
6. Re-create all dependent objects.
7. Rebind plans and packages.
8. Reload the table using data from the SYSRECnn data set and the control
statements from the SYSPUNCH data set, which was created when the table
was unloaded.

Altering Db2 views

To alter a view, you must drop the view and create a new view with your
modified specifications.

Procedure

To drop and re-create a view:

1. Issue the DROP VIEW SQL statement.
2. Commit the drop. When you drop a view, Db2 also drops the dependent views.
3. Re-create the modified view using the CREATE VIEW SQL statement.

What to do next

Attention: When you drop a view, Db2 invalidates packages that are dependent
on the view and revokes the privileges of users who are authorized to use it. Db2
attempts to rebind the package the next time it is executed, and you receive an
error if you do not re-create the view.

To tell how much rebinding and reauthorizing is needed if you drop a view, see
the following table.
Table 29. Catalog tables to check after dropping a view
Catalog table What to check
SYSIBM.SYSPACKDEP Packages dependent on the view
SYSIBM.SYSVIEWDEP Views dependent on the view
SYSIBM.SYSTABAUTH Users authorized to use the view

Related tasks:
Creating Db2 views
Dropping Db2 views
Related reference:
DROP (Db2 SQL)
COMMIT (Db2 SQL)
CREATE VIEW (Db2 SQL)

Chapter 3. Altering your database design 189

 Altering views by using the INSTEAD OF trigger
Typically, you can only do normal insert, update, and delete operations on specific
types of views, but you can use the INSTEAD OF trigger to extend the
updatability of views.

About this task

Unlike other forms of triggers that are defined only on tables, INSTEAD OF
triggers are defined only on views. If you use the INSTEAD OF trigger, the
requested update operation against the view is replaced by the trigger logic, which
performs the operation on behalf of the view.

Procedure

To alter a view by using the INSTEAD OF trigger:

Issue the CREATE TRIGGER statement and specify the INSTEAD OF trigger for
insert, update, and delete operations on the view.
Related reference:
CREATE TRIGGER (Db2 SQL)

| Changing data by using views that reference temporal tables

| For a view that references an application-period temporal table or a bitemporal
| table, you can specify a period clause for an update or delete operation on the
| view.

| About this task

| Restriction: The view must not be defined with an INSTEAD OF trigger.

| Procedure
| To issue a data change operation on a view that references a temporal table:

| Specify a period clause for a BUSINESS_TIME period (FOR PORTION OF

| BUSINESS_TIME) following the name of the target view in an UPDATE or
| DELETE statement.

| Example
|
|

| The following example shows how you can create a view that references an
| application-period temporal table (att), and then specify a period clause for an
| update operation on the view.
| CREATE VIEW v7 (col1, col2, col3)
| AS SELECT coverage, bus_start, bus_end FROM att;
|
| UPDATE v7
| FOR PORTION OF BUSINESS_TIME FROM '2013-01-01’ TO '2013-06-01’
| SET col1 = col1 + 1.10;

190 Administration Guide

|
|
|
Altering Db2 indexes
You can add a new column to an index or change the description of an index at
the current server by issuing the ALTER INDEX statement.

About this task

With the ALTER INDEX statement, you can:

v Add a new column to an index.
v Alter the PADDED or NOT PADDED attribute to change how varying-length
columns are stored in the index.
v Alter the CLUSTER or NOT CLUSTER attribute to change how data is stored.
v Alter the compression setting using ALTER COMPRESS YES or ALTER
COMPRESS NO.
v Change the limit key for index-controlled partitioning to rebalance data among
the partitions in a partitioned table space.

For other changes, you must drop and re-create the index.

When you add a new column to an index, change how varying-length columns are
stored in the index, or change the data type of a column in the index, Db2 creates
a new version of the index.

Restrictions:
v If the padding of an index is changed, the index is placed in REBUILD-pending
(RBDP) status and a new version of the index is not created.
v Any alteration to use index compression places the index in RBDP status.
v You cannot add a column with the DESC attribute to an index if the column is a
VARBINARY column or a column with a distinct type that is based on the
VARBINARY type.

Procedure

To change the description of an index at the current server:

Issue the ALTER INDEX statement. The ALTER INDEX statement can be
embedded in an application program or issued interactively.
Related concepts:
Indexes that are padded or not padded (Introduction to Db2 for z/OS)
Related tasks:
Designing indexes for performance (Db2 Performance)
Related reference:
ALTER INDEX (Db2 SQL)
Related information:
Implementing Db2 indexes

Chapter 3. Altering your database design 191

 Alternative method for altering an index
You can minimize the potential for data outages by using the ALTER INDEX
statement with the BUFFERPOOL option.

The BUFFERPOOL option is supported as a pending definition change. If pending

changes do not exist at the table space level, you can materialize the pending
changes by running one of the following utilities:
v REORG INDEX with SHRLEVEL CHANGE or SHRLEVEL REFERENCE
v REORG TABLESPACE with SHRLEVEL CHANGE or SHRLEVEL REFERENCE

If pending changes exist at the table space level, you can materialize the pending
changes that are associated with the table space (including the pending changes for
the index) by running REORG TABLESPACE with SHRLEVEL CHANGE or
SHRLEVEL REFERENCE.

Adding columns to an index

You can add columns to an index in two ways. You can add a column to an index
when you add the column to a table, or you can specify that additional columns be
appended to the set of index key columns of a unique index.

Adding a column to an index when you add the column to a

table
When you use the ALTER INDEX statement to add a column to an existing index,
the new column becomes the rightmost column of the index key.

About this task

Restriction: You cannot add columns to IBM-defined indexes on the Db2 catalog.

Procedure

To add a column to an existing index:

1. Issue the ALTER INDEX ADD COLUMN SQL statement when you add a
column to a table.
2. Commit the alter procedure.

Results

If the column that is being added to the index is already part of the table on which
the index is defined, the index is left in a REBUILD-pending (RBDP) status.
However, if you add a new column to a table and to an existing index on that
table within the same unit of work, the index is left in advisory REORG-pending
(AREO*) status and can be used immediately for data access.

If you add a column to an index and to a table within the same unit of work, this
will cause table and index versioning.

Example

For example, assume that you created a table with columns that include
ACCTID, STATE, and POSTED:

192 Administration Guide

CREATE TABLE TRANS
(ACCTID ...,
STATE ...,
POSTED ...,
... , ...)
...;

You have an existing index on the STATE column:

CREATE INDEX STATE_IX ON TRANS(STATE);

To add a ZIPCODE column to the table and the index, issue the following
statements:
ALTER TABLE TRANS ADD COLUMN ZIPCODE CHAR(5);
ALTER INDEX STATE_IX ADD COLUMN (ZIPCODE);
COMMIT;

Because the ALTER TABLE and ALTER INDEX statements are executed within the
same unit of work, Db2 immediately can use the new index with the key STATE,
ZIPCODE for data access.

Related reference:
ALTER INDEX (Db2 SQL)

Adding columns to the set of index keys of a unique index

You can use the ALTER INDEX statement to specify that additional columns be
appended to the set of index key columns of a unique index.

About this task

Restriction: You cannot add columns to IBM-defined indexes on the Db2 catalog.

If you want to add a column to a unique index to allow index-only access of the
data, you first must determine whether existing indexes on a unique table are
being used to query the table. You can use the RUNSTATS utility, real-time
statistics, or the EXPLAIN statement to find this information. Those indexes with
the unique constraint in common are candidates for consolidation. Other
non-unique indexes might be candidates for consolidation, depending on their
frequency of use.

Procedure

To specify that additional columns be appended to the set of index key columns of
a unique index:
1. Issue the ALTER INDEX statement with the INCLUDE clause. Any column that
is included with the INCLUDE clause is not used to enforce uniqueness. These
included columns might improve the performance of some queries through
index only access. Using this option might eliminate the need to access data
pages for more queries and might eliminate redundant indexes.
2. Commit the alter procedure. As a result of this alter procedure, the index is
placed into page set REBUILD-pending (PSRBD) status, because the additional
columns preexisted in the table.
3. To remove the PSRBD status from the index, complete one of the following
options:

Chapter 3. Altering your database design 193

 v Run the REBUILD INDEX utility on the index that you ran the alter
procedure on.
v Run the REORG TABLESPACE utility on the index that you ran the alter
procedure on, or you can wait to run the alter procedure until just before the
REORG TABLESPACE utility is scheduled to run.
4. Run the RUNSTATS utility. The results will be used after the next step.
5. Perform REBIND on the static plans and packages.
6. Run the EXPLAIN statement to verify that the optimizer is choosing the index
with the included columns.
7. Drop the indexes that are consolidated and no longer needed.
8. Verify that the new index is satisfying your query needs by using the
RUNSTATS utility, real-time statistics, or the EXPLAIN statement.
Related reference:
ALTER INDEX (Db2 SQL)

Altering how varying-length index columns are stored

You can use the ALTER INDEX statement to change how varying-length column
values are stored in an index.

Procedure

To alter how varying-length column values are stored in an index, complete the
following steps:
1. Choose the padding attribute for the columns.
2. Issue the ALTER INDEX SQL statement.
v Specify the NOT PADDED clause if you do not want column values to be
padded to their maximum length. This clause specifies that VARCHAR and
VARGRAPHIC columns of an existing index are stored as varying-length
columns.
v Specify the PADDED clause if you want column values to be padded to the
maximum lengths of the columns. This clause specifies that VARCHAR and
VARGRAPHIC columns of an existing index are stored as fixed-length
columns.
3. Commit the alter procedure.

Results

The ALTER INDEX statement is successful only if the index has at least one
varying-length column.

What to do next

When you alter the padding attribute of an index, the index is placed into a
restricted REBUILD-pending (RBDP) state. When you alter the padding attribute of
a nonpartitioned secondary index (NPSI), the index is placed into a page set
REBUILD-pending (PSRBD) state. In both cases, the indexes cannot be accessed
until they are rebuilt from the data.

194 Administration Guide

 Related concepts:
Indexes that are padded or not padded (Introduction to Db2 for z/OS)
Related reference:
ALTER INDEX (Db2 SQL)

Altering the clustering of an index

You can use the ALTER INDEX SQL statement to change the clustering index for a
table.

Procedure

To change the clustering option of an index:

1. Issue the ALTER INDEX statement.
2. Specify the clustering option.

Restriction: You can only specify CLUSTER if there is not already another
clustering index. In addition, an index on a table that is organized by hash
cannot be altered to a clustering index.
v CLUSTER indicates that the index is to be used as the clustering index of the
table. The change takes effect immediately. Any subsequently inserted rows
use the new clustering index. Existing data remains clustered by the previous
clustering index until the table space is reorganized.
v NOT CLUSTER indicates that the index is not to be used as the clustering
index of the table. However, if the index was previously defined as the
clustering index, it continues to be used as the clustering index until you
explicitly specify CLUSTER for a different index.
If you specify NOT CLUSTER for an index that is not a clustering index, that
specification is ignored.
3. Commit the alter procedure.

Related reference:
ALTER INDEX (Db2 SQL)

Dropping and redefining a Db2 index

Dropping an index does not cause Db2 to drop any other objects. The consequence
of dropping indexes is that Db2 invalidates packages that use the index and
automatically rebinds them when they are next used.

Before you begin

Any primary key, unique key, or referential constraints associated with a unique
index must be dropped before you drop the unique index. However, you can drop
a unique index for a unique key without dropping the unique constraint if the
unique key was created before Version 9.

Commit the drop before you create any new table spaces or indexes by the same
name.

Chapter 3. Altering your database design 195

 Procedure

To drop and re-create an index:

1. Issue a DROP INDEX statement.
2. Commit the drop procedure. The index space associated with the index is also
dropped.
3. Re-create the modified index by issuing a CREATE INDEX statement.
4. Rebind any application programs that use the dropped index.

If you drop and index and then run an application program using that index
(and thereby automatically rebound), that application program does not use the
old index. If, at a later time, you re-create the index and the application
program is not rebound, the application program cannot take advantage of the
new index.
Related tasks:
Creating Db2 indexes
Related reference:
DROP (Db2 SQL)
CREATE INDEX (Db2 SQL)

Reorganizing indexes
A schema change that affects an index might cause performance degradation. In
this case, you might need to reorganize indexes to correct any performance
degradation.

About this task

Although data availability is maximized by the use of index versions, performance

might suffer because Db2 does not automatically reformat the data in the index to
conform to the most recent schema definition. Db2 defers any reformatting of
existing data until you reorganize the index and apply the schema changes. The
more ALTER statements (which affect indexes) that you commit between
reorganizations, the more index versions Db2 must track, and the more
performance can suffer.

Procedure

To reorganize an index:

Run the REORG INDEX utility as soon as possible after a schema change that
affects an index. You can also run the REORG TABLESPACE utility.
Related concepts:
Index versions
Related reference:
REORG INDEX (Db2 Utilities)
REORG TABLESPACE (Db2 Utilities)

196 Administration Guide

| Pending data definition changes
| Pending data definition changes are data definition changes that do not take effect
| immediately because the object must be reorganized to apply change. When you
| are ready to materialize pending data definition changes, you run the REORG
| utility to apply the pending changes to the definition and data. Objects that have
| pending definition changes remain available for use until it is convenient to apply
| the changes.

| ALTER statements with certain options can cause pending changes to the
| definition of database objects. When an ALTER statement is issued that causes
| pending changes to the definition of an object, semantic validation and
| authorization checking are performed. However, changes to the table definition
| and data are not applied and the object is placed in advisory REORG-pending state
| (AREOR), until the REORG utility is run to resolve the pending changes.

| Most pending data definition changes are supported only for universal table
| spaces, with the following exceptions:
| v Converting single-table simple or segmented (non-UTS) table spaces to
| partition-by-growth table spaces, with the MAXPARTITIONS attribute.
| v Converting partitioned (non-UTS) table spaces to partition-by-range table spaces,
| with the SEGSIZE attribute.
| v Changing partition boundaries for partitioned (non-UTS) table spaces.

| The pending changes are recorded in the SYSIBM.SYSPENDINGDDL catalog table.

| When the pending changes are applied, dependent packages are invalidated, the
| corresponding entries in the SYSIBM.SYSPENDINGDDL catalog table are removed,
| and the advisory REORG-pending state is removed.

| When pending definition changes occur

| The following situations can result in pending definition changes:

| ALTER TABLESPACE
| The following ALTER TABLESPACE options can cause pending changes to
| the definition of a table space:
| v BUFFERPOOL is a pending change to the definition of the table space if
| the data sets of the table space are already created and if one of the
| following conditions is true:
| – Pending definition changes already exist for the table space or any
| objects within the base table space.
| – The specified buffer pool has a different page size than the buffer
| pool that is currently being used for the table space.
| v DSSIZE is a pending change to the definition of the table space if the
| data sets of the table space are already created and if one of the
| following conditions is true:
| – Pending definition changes already exist for the table space or any
| associated indexes.
| – The specified DSSIZE is different than the value that is currently
| being used for the table space.
| v MAXPARTITIONS is a pending change if the table space is not a
| partition-by-growth table space.

Chapter 3. Altering your database design 197

| v SEGSIZE is a pending change to the definition of the table space if the
| data sets of the table space are already created and one of the following
| conditions is true:
| – Pending changes to the definition of the table space or its associated
| indexes already exist.
| – The specified SEGSIZE value for a universal table space is different
| than the existing value.
| – The table space is converted from a partitioned (non-UTS) table space
| to a partition-by-range table space.
| v MEMBER CLUSTER is a pending change.
| ALTER TABLE
| The following ALTER TABLE options can cause pending changes to the
| definition of the table under certain conditions:
| v DROP COLUMN, if the data sets of the table space are already created
| v ALTER PARTITION, to change the limit keys for the following types of
| partitioned table spaces:
| – Partition-by-range table spaces
| – Partitioned (non-UTS) table spaces with table-controlled partitioning.
| However, this operation is not a pending definition change under the
| following circumstances:
| - There is no possibility that data would move between partitions,
| and no other definition change is pending on the partition or the
| previous partition. In this case, the changes are immediate, and the
| partitions are not placed in a REORG-pending or advisory
| REORG-pending status.
| - The values in the limit key for the last partition are all altered from
| MAXVALUE to a value less than MAXVALUE, or from
| MINVALUE to a value greater than MINVALUE. In this case, the
| changes are immediate, and the partition is placed in
| REORG-pending status.
| ALTER INDEX
| The following ALTER INDEX options can cause pending changes to the
| definition of the specified index under certain conditions:
| v BUFFERPOOL is a pending change if all of the following conditions are
| true:
| – The data sets of the index are created
| – The index is defined on one of the following:
| - A table that is in a universal table space
| - An XML table that is associated with a base table that is in a
| universal table space
| - An auxiliary table that is associated with a base table that is in a
| universal table space
| – There are pending definition changes for the index, table, or table
| space
| – The buffer pool is changed to a buffer pool with a different size
| v COMPRESS is a pending change if all of the following conditions are
| true:
| – The data sets of the index are created
| – The index is defined on one of the following:

198 Administration Guide

| - A table that is in a universal table space
| - An XML table that is associated with a base table that is in a
| universal table space
| - An auxiliary table that is associated with a base table that is in a
| universal table space
| – There are pending definition changes for the index, table, or table
| space
| – The buffer pool is changed to a buffer pool with a different size
| ALTER INDEX BUFFERPOOL results in an immediate definition change
| except when all of the following conditions are true:
| v The data sets of the index are created
| v The index is defined on one of the following objects:
| – A table that is in a universal table space
| – An XML table that is associated with a base table this is in a universal
| table space
| – An auxiliary table that is associated with a base table that is in a
| universal table space
| v There are pending definition changes for the index or the table space, or
| the buffer pool is changed to a buffer pool with a different size.

| When pending changes are restricted

| ALTER TABLESPACE, ALTER TABLE and ALTER INDEX statements that result in
| pending definition changes are not supported in the following cases:
| v Options that cause pending changes cannot be specified with options that take
| effect immediately
| v Options that cause pending changes cannot be specified for the following
| objects:
| – The Db2 catalog
| – System objects
| – Objects in a work file database
| v The DROP PENDING CHANGES clause cannot be specified for a catalog table
| space
| v If the table space, or any table it contains is in an incomplete state, you cannot
| specify options that cause pending changes
| v For ALTER INDEX, if the definition of the table space or table on which the
| index is defined it not complete.

| Most immediate definition changes are restricted while pending definition changes
| exist for an object. For a list of such restrictions, see Restrictions for changes to
| objects that have pending data definition changes.
| Related concepts:
| Table space types and characteristics in Db2 for z/OS
| Related tasks:
| Altering table spaces
| Related reference:
| ALTER TABLE (Db2 SQL)
| ALTER TABLESPACE (Db2 SQL)

Chapter 3. Altering your database design 199

| ALTER INDEX (Db2 SQL)
| SYSPENDINGDDL catalog table (Db2 SQL)

| Materializing pending definition changes

| After generating pending definition changes by issuing ALTER statements, you
| must materialize pending definition changes at the table space level. Materialization
| of the pending definition changes means implementing the changes in the database
| system.

| About this task

| Pending definition changes are data definition changes that do not take effect
| immediately. When definition changes are pending, the affected objects are
| available until it is convenient to implement the changes.

| Most pending data definition changes are supported only for universal table
| spaces, with the following exceptions:
| v Converting single-table simple or segmented (non-UTS) table spaces to
| partition-by-growth table spaces, with the MAXPARTITIONS attribute.
| v Converting partitioned (non-UTS) table spaces to partition-by-range table space,
| with the SEGSIZE attribute.
| v Changing partition boundaries for partitioned (non-UTS) table spaces.

| Tip: Try to run REORG at a time when the data is not heavily accessed.
| Otherwise, application outages might occur, as described in Reorganization with
| pending definition changes (Db2 Utilities).

| Procedure

| To materialize pending data definition changes, use the following approaches:

| v Run the REORG TABLESPACE utility with SHRLEVEL REFERENCE or
| SHRLEVEL CHANGE. Do not specify FASTSWITCH NO.
| Also note the restrictions for REBALANCE and AUX NO in Syntax and options
| of the REORG TABLESPACE control statement (Db2 Utilities).

| Restriction: Using the REORG TABLESPACE utility with SHRLEVEL

| REFERENCE or SHRLEVEL CHANGE does not drop empty partitions from a
| partition-by-growth table space.
| v For pending definition changes for indexes, issue REORG INDEX statements.
| Only pending definition changes to the reorganized index are materialized.
| Pending definition changes to the table space or table remain pending.

| Examples

| Example: The following example provides a scenario that shows how you can use
| the ALTER TABLESPACE statement to generate pending definition changes, and
| then use the REORG TABLESPACE utility with SHRLEVEL REFERENCE to
| materialize pending definition changes at the table space level.

|
|
| Consider the following scenario:

200 Administration Guide

| 1. In Version 8, you created the simple table space TS1 in database DB1, such as:
| CREATE DATABASE DB1;
| CREATE TABLESPACE TS1
| BUFFERPOOL BP0
| IN DB1;
| CREATE TABLE USER1.TB1
| (
| COL1 INTEGER,
| COL2 VARCHAR(10)
| )
| IN DB1.TS1;
|
| CREATE INDEX USER1.IX1
| ON USER1.TB1
| ( COL2 )
| BUFFERPOOL BP0
| COPY YES
| ;
| 2. In the current release of Db2, you issue the following ALTER TABLESPACE
| statement to convert the simple table space to a partition-by-growth table space,
| and to change the buffer pool page size. Those changes are pending definition
| changes. Suppose that the changes take place at time 2012-10-04-
| 07.14.20.204010:
| ALTER TABLESPACE DB1.TS1 BUFFERPOOL BP8K0 MAXPARTITIONS 20 ;
| For each pending option in an ALTER statement, there is a corresponding entry
| in the SYSPENDINGDDL table. If you specify multiple pending options in one
| ALTER statement, each change has its own SYSPENDINGDDL entry, but the
| changes have the same create timestamp. In addition, the same ALTER
| statement text is stored repeatedly with each pending option entry that is
| specified with the ALTER statement. Therefore, issuing this ALTER
| TABLESPACE statement results in the table space being placed in AREOR state,
| and two pending option entries are inserted into the SYSPENDINGDDL table
| with OBJTYPE = 'S' for table space. This ALTER statement has not changed the
| current definition or data, so the buffer pool in SYSTABLESPACE still indicates
| BP0, and the table space is still a simple table space.
| 3. Later at the time of 2012-10-09-07.15.22.216020, you issue the following ALTER
| TABLESPACE statement that has one pending option:
| ALTER TABLESPACE DB1.TS1 SEGSIZE 64 ;

| This statement results in one entry being inserted into the SYSPENDINGDDL
| table with OBJTYPE = 'S', for table space. This ALTER statement has not
| changed the current definition or data, so the SEGSIZE in SYSTABLESPACE is
| still 0.
| 4. Next, you issue the following ALTER statement with one pending option at the
| time of 2012-12-14-07.20.10.405008:
| ALTER INDEX USER1.IX1 BUFFERPOOL BP16K0;

| This statement results in the index being placed in AREOR state, and an entry
| is inserted into the SYSPENDINGDDL table with OBJTYPE = 'I', for index. This
| ALTER statement has not changed the current definition or data, so the buffer
| pool in SYSINDEXES still indicates BP0 for the index.
| 5. You issue another ALTER statement that is exactly the same as the previous
| one, at the time of 2012-12-20-04.10.10.605058. This statement results in another
| entry being inserted into the SYSPENDINGDDL table with OBJTYPE = 'I', for
| index.

Chapter 3. Altering your database design 201

| 6. You run the following SELECT statement to query the SYSPENDINGDDL
| catalog table:
| SELECT DBNAME, TSNAME, OBJSCHEMA, OBJNAME, OBJTYPE, OPTION_SEQNO,
| OPTION_KEYWORD, OPTION_VALUE, CREATEDTS, STATEMENT_TEXT
| FROM SYSIBM.SYSPENDINGDDL
| WHERE DBNAME = ’DB1’
| AND TSNAME = ’TS1’
| ORDER BY CREATEDTS
| ;
| This query results in the following output:
| Table 30. Output from the SELECT statement for the SYSPENDINGDDL catalog
| DBNAME TSNAME OBJSCHEMA OBJNAME OBJTYPE
| DB1 TS1 DB1 TS1 S
| DB1 TS1 DB1 TS1 S
| DB1 TS1 DB1 TS1 S
| DB1 TS1 USER1 IX1 I
| DB1 TS1 USER1 IX1 I
|
| Table 31. Continuation of output from the SELECT statement for the SYSPENDINGDDL
| catalog
| OPTION_SEQNO OPTION_KEYWORD OPTION_VALUE CREATEDTS
| 1 BUFFERPOOL BP8K0 2012-10-04-
| 07.14.20.204010
| 2 MAXPARTITIONS 20 2012-10-04-
| 07.14.20.204010
| 1 SEGSIZE 64 2012-10-09-
| 07.15.22.216020
| 1 BUFFERPOOL BP16K0 2012-12-14-
| 07.20.10.405008
| 1 BUFFERPOOL BP16K0 2012-12-20-
| 04.10.10.605058
|
| Table 32. Statement text output for the SELECT statement for the SYSPENDINGDDL
| catalog
| STATEMENT_TEXT
| ALTER TABLESPACE DB1.TS1 BUFFERPOOL BP8K0 MAXPARTITIONS 20;
| ALTER TABLESPACE DB1.TS1 BUFFERPOOL BP8K0 MAXPARTITIONS 20;
| ALTER TABLESPACE DB1.TS1 SEGSIZE 64;
| ALTER INDEX USER1.IX1 BUFFERPOOL BP16K0;
| ALTER INDEX USER1.IX1 BUFFERPOOL BP16K0;
|
|
|
| 7. Next, you run the REORG INDEX utility with SHRLEVEL CHANGE on the
| index. For example:
| REORG INDEX USER1.IX1 SHRLEVEL CHANGE

| However, because pending definition changes exist for the table space, the
| REORG utility proceeds without materializing the pending definition changes
202 Administration Guide
| for the index, and issues warning DSNU275I with RC = 4 to indicate that no
| materialization has been done on the index, because there are pending
| definition changes for the table space. After the REORG utility runs, all the
| SYSPENDINGDDL entries still exist, and the AREOR state remains the same.
| 8. Now, you run the REORG TABLESPACE utility with SHRLEVEL REFERENCE
| on the entire table space. For example:
| REORG TABLESPACE DB1.TS1 SHRLEVEL REFERENCE

| The REORG utility materializes all of the pending definition changes for the
| table space and the associated index, applying the changes in the catalog and
| data. After the REORG utility runs, the AREOR state is cleared and all entries
| in the SYSPENDINGDDL table for the table space and the associated index are
| removed. The catalog and data now reflect a buffer pool of BP8K0,
| MAXPARTITIONS of 20, and SEGSIZE of 64.
| Related concepts:
| Reorganization with pending definition changes (Db2 Utilities)
| Table space types and characteristics in Db2 for z/OS
| Related reference:
| ALTER TABLE (Db2 SQL)
| ALTER TABLESPACE (Db2 SQL)
| ALTER INDEX (Db2 SQL)

| Restrictions for changes to objects that have pending data

| definition changes
| When data definition statements specify pending changes, immediate data
| definition pages cannot be issued in the same statement. Certain immediate
| changes are also restricted in subsequent data definition statements until the
| REORG utility is run to materialized the pending data definition changes.

| The following table lists immediate data definition changes that are restricted until
| any pending data definition changes are materialized for specific types of objects.
| Db2 issue SQLCODE -20385 for statements that cannot be processed because of
| pending data definition changes.

Chapter 3. Altering your database design 203

| Table 33. Restrictions for data definition changes for pending data definition changes
| Scope of Pending data definition Restricted immediate definition changes for
| change changes the table space and contained objects
|| Table space ALTER TABLESPACE with ALTER INDEX with ADD COLUMN
|| any of the following options: option
|| BUFFERPOOL ALTER INDEX with PIECESIZE option
|| DSSIZE ALTER INDEX with REGENERATE
| MAXPARTITIONS option
| SEGSIZE ALTER INDEX with VCAT option
| ALTER TABLE with immediate option(s)
| ALTER TABLESPACE with CCSID option
| ALTER TABLESPACE with FREEPAGE
| option
| ALTER TABLESPACE with VCAT option
| if table space is not partitioned by growth
| CREATE INDEX on table in table space
| CREATE TABLE in table space
| DROP INDEX of index enforcing ROWID
| GENERATED BY DEFAULT column in
| explicitly created table space
| DROP INDEX of empty auxiliary index
| in explicitly created LOB table space if
| pending changes exist for base table
| space or objects in base table space
| DROP TABLE if table space was
| explicitly created
| DROP TABLE of empty auxiliary table if
| pending changes exist for base table
| space or objects in base table space

204 Administration Guide

| Table 33. Restrictions for data definition changes for pending data definition
| changes (continued)
| Scope of Pending data definition Restricted immediate definition changes for
| change changes the table space and contained objects
|| Table ALTER TABLE statements ALTER INDEX with ADD COLUMN
|| with any of the following option
| options:
| ALTER INDEX with REGENERATE
|| DROP COLUMN option
|| ADD PARTITION ALTER TABLE with immediate option(s)
| ALTER TABLE ADD MQT definition
| referencing table with pending definition
| changes
| ALTER TABLESPACE with CCSID option
| CREATE FUNCTION of SQL table
| function referencing table with pending
| definition changes
| CREATE INDEX on table
| CREATE MASK on table or referencing
| table with pending definition changes
| CREATE PERMISSION on table or
| referencing table with pending definition
| changes
| CREATE TABLE of MQT referencing
| table with pending definition changes
| CREATE TRIGGER of INSTEAD OF
| trigger if view is dependent on table with
| pending definition changes
| CREATE TRIGGER on triggering table
| with pending definition changes
| DROP INDEX of index enforcing ROWID
| GENERATED BY DEFAULT column in
| explicitly created table space
| DROP TABLE of empty auxiliary table if
| pending changes exist for base table
| space or objects in base table space
| RENAME TABLE
| Column ALTER TABLE statements All restricted table-level operations.
| with any of the following
| options:
| DROP COLUMN
| Partition ALTER TABLE statements All restricted table-level operations, plus the
| with any of the following following operations:
|| options: v ALTER TABLE ADD PARTITION to insert
| ALTER PARTITION a partition if the last logical partition has
| pending definition changes to alter the
| limit key value

Chapter 3. Altering your database design 205

| Table 33. Restrictions for data definition changes for pending data definition
| changes (continued)
| Scope of Pending data definition Restricted immediate definition changes for
| change changes the table space and contained objects
|| Index ALTER INDEX statements ALTER INDEX with ADD COLUMN
|| with any of the following option
| options:
| ALTER INDEX with COMPRESS YES
|| BUFFERPOOL option
|| COMPRESS ALTER INDEX with PIECESIZE option
| ALTER INDEX with REGENERATE
| option
| ALTER INDEX with VCAT option
| ALTER TABLE with immediate option(s)
| CREATE INDEX on table in table space
| DROP INDEX of index enforcing ROWID
| GENERATED BY DEFAULT column in
| explicitly created table space
| DROP TABLE of empty auxiliary table if
| pending changes exist for base table
| space or objects in base table space
| RENAME INDEX
|

| Restrictions for recovery to before pending definition changes

| If you recover to a point-in-time before the materialization of most pending

| definition changes, many operations become restricted for the object until you run
| the REORG utility. The restrictions do not apply if the pending definition change is
| an ALTER TABLE statement with the ALTER PARTITION or ALTER COLUMN
| options.

| For details about these restrictions and how to resolve them, see Recovering to a
| point in time before pending definition changes were materialized.
| Related concepts:
| Reorganization with pending definition changes (Db2 Utilities)
| Related tasks:
| Materializing pending definition changes
| Related reference:
| ALTER TABLE (Db2 SQL)
| ALTER TABLESPACE (Db2 SQL)
| ALTER INDEX (Db2 SQL)
| SYSPENDINGDDL catalog table (Db2 SQL)
| Related information:
| -20385 (Db2 Codes)

Altering stored procedures

The process that you follow to alter a stored procedure depends on the type of
stored procedure and how you want to alter it.

206 Administration Guide

About this task

You can alter stored procedures in the following ways:

v For a native SQL procedure, you can alter the options and the body, and you can
manage multiple versions.
v For an external SQL procedure, you can alter only the options.
v For an external stored procedure (a procedure that is written in a host language),
you can alter the procedure options. If you alter the host language code, you
need to prepare the code again.

Procedure

To alter an existing stored procedure:

1. Follow the process for the type of change that you want to make:
v To alter the host language code for an external stored procedure, modify the
source and prepare the code again. (Precompile, compile, and link-edit the
application, and then bind the DBRM into a package.)
v To alter the body of a native SQL procedure, issue the ALTER PROCEDURE
statement with the REPLACE clause.
v To alter the description of any type of stored procedure, issue the ALTER
PROCEDURE statement with the options that you want.
2. Refresh the WLM environment if either of the following situations applies:
v For external SQL procedures or external procedures, you changed the stored
procedure logic or parameters.
v You changed the startup JCL for the stored procedures address space.

Restriction: In some cases, refreshing the WLM environment might not be

enough. For example, if the change to the JCL is to the NUMTCB value,
refreshing the WLM environment is not enough. The refresh fails because it
cannot start a new WLM address space that has a different NUMTCB from
the existing one. In this case, you need to do a WLM quiesce, followed by a
WLM resume.

Tip: To refresh the WLM environment, use the Db2-supplied WLM_REFRESH

stored procedure rather than the REFRESH command. (The REFRESH
command starts a new WLM address space and stops the existing one.)
3. If you disabled automatic rebinds, rebind any plans or packages that refer to
the stored procedure that you altered.

Example

Example of changing the WLM environment: The following example changes the
stored procedure SYSPROC.MYPROC to run in the WLM environment PARTSEC:
ALTER PROCEDURE SYSPROC.MYPROC
WLM ENVIRONMENT PARTSEC;

Example of changing the stored procedure to use another authorization ID:

Assume that you defined the stored procedure SYSPROC.MYPROC with the
SECURITY DEFINER option. When you specify the SECURITY DEFINER option,
the external security environment for the stored procedure uses the authorization
ID of the owner of the stored procedure to control access to non-SQL resources.

Chapter 3. Altering your database design 207

 The following example changes the stored procedure SYSPROC.MYPROC so that it
uses the authorization ID of the person who is running the stored procedure to
control access to non-SQL resources:
ALTER PROCEDURE SYSPROC.MYPROC
SECURITY USER;

Related tasks:
Implementing Db2 stored procedures
Related reference:
WLM_REFRESH stored procedure (Db2 SQL)
ALTER PROCEDURE (external) (Db2 SQL)
ALTER PROCEDURE (SQL - external) (Db2 SQL)
ALTER PROCEDURE (SQL - native) (Db2 SQL)

Altering user-defined functions

You can use the ALTER FUNCTION statement to update the description of
user-defined functions.

Procedure

To alter a user-defined function:

Issue the ALTER FUNCTION SQL statement.

Results

Changes to the user-defined function take effect immediately.

Example

Example 1: In the following example, two functions named CENTER exist in the
SMITH schema. The first function has two input parameters with INTEGER and
FLOAT data types, respectively. The specific name for the first function is FOCUS1.
The second function has three parameters with CHAR(25), DEC(5,2), and
INTEGER data types.

Using the specific name to identify the function, change the WLM environment in
which the first function runs from WLMENVNAME1 to WLMENVNAME2:
ALTER SPECIFIC FUNCTION SMITH.FOCUS1
WLM ENVIRONMENT WLMENVNAME2;

Example 2: The following example changes the second function when any
arguments are null:
ALTER FUNCTION SMITH.CENTER (CHAR(25), DEC(5,2), INTEGER)
RETURNS ON NULL CALL;

208 Administration Guide

 Related concepts:
User-defined functions (Db2 SQL)
Related tasks:
Creating user-defined functions
Creating a user-defined function (Db2 Application programming and SQL)
Related reference:
ALTER FUNCTION (external) (Db2 SQL)
ALTER FUNCTION (compiled SQL scalar) (Db2 SQL)
ALTER FUNCTION (SQL table) (Db2 SQL)

Altering implicitly created XML objects

You can alter implicitly created XML objects; however, you can change only some
of the properties for an XML object.

Procedure

To alter implicitly created XML objects:

Determine the restrictions on the XML object that you want to change. The
following table provides information about the properties that you can or cannot
change for a particular XML object.

Option Description
XML table space You can alter the following properties:
| v BUFFERPOOL (16 KB buffer pools only)
| v COMPRESS
| v PRIQTY
| v SECQTY
| v MAXROWS
| v GBPCACHE
| v USING STOGROUP
| v ERASE
| v LOCKSIZE (The only possible values are
| XML and TABLESPACE.)
| v SEGSIZE
| v DSSIZE
| v MAXPARTITIONS

XML table space attributes that are inherited

from the base table space, such as LOG, are
implicitly altered if the base table space is
altered.

Chapter 3. Altering your database design 209

 Option Description
XML table The ALTER TABLE ALTER PARTITION
statement is not supported if the table
contains an XML column.
Index You cannot alter the following properties:
v CLUSTER
v PADDED
v ADD COLUMN.

Related tasks:
Adding XML columns

Changing the high-level qualifier for Db2 data sets

The high-level qualifier for Db2 data sets is the catalog name of the integrated
catalog facility, which is commonly called the user catalog.

Before you begin

To concentrate on Db2-related issues, this procedure assumes that the catalog alias
resides in the same user catalog as the one that is currently used. If the new
catalog alias resides in a different user catalog, see DFSMS Access Method Services
Commands for information about planning such a move.

If the data sets are managed by the Storage Management Subsystem (SMS), make
sure that automatic class selection routines are in place for the new data set name.

About this task

You cannot change the high-level qualifier for Db2 data sets by using the Db2
installation or migration update process. You must use other methods to change
this qualifier for both system data sets and user data sets.

The following procedures do not actually move or copy data.

Changing the high-level qualifier for Db2 data sets is a complex task. You should
have experience with both Db2 and managing user catalogs.
Related concepts:
Moving Db2 data
Related information:
DFSMS Access Method Services Commands

Defining a new integrated catalog alias

You can define a new integrated catalog alias any time before you change the
high-level qualifier for system data sets or user data sets.

210 Administration Guide

 Procedure

To define the new high-level qualifier as an alias to a current integrated catalog:

Issue the following access method services command:

DEFINE ALIAS (NAME (newcat) RELATE (usercat) CATALOG (master-cat))
Related information:
DFSMS Access Method Services Commands

Changing the qualifier for system data sets

To change the qualifier for system data sets, you stop Db2, change the high-level
qualifier in the system parameter load module (possibly DSNZPARM), and
establish a new xxxxMSTR cataloged procedure before restarting Db2.

About this task

Important: The following steps must be done in sequence.

Changing the load module to reflect the new qualifier

To change the system parameter load module to specify the new qualifier for new
archive data sets and the Db2 catalog and directory data sets, you must follow the
installation process.

Procedure

To specify the new qualifier:

1. Run the installation CLIST, and specify INSTALL TYPE=INSTALL and DATA
SHARING FUNCTION=NONE.
2. Enter new values for the fields shown in the following table.
Table 34. CLIST panels and fields to change to reflect new qualifier
Panel name Field name Comments
DSNTIPA1 INSTALL TYPE Specify INSTALL. Do not specify a new
default prefix for the input data sets listed
on this panel.
DSNTIPA1 OUTPUT MEMBER
NAME
DSNTIPA2 CATALOG ALIAS
DSNTIPH COPY 1 NAME and These are the bootstrap data set names.
COPY 2 NAME
DSNTIPH COPY 1 PREFIX and These fields appear for both active and
COPY 2 PREFIX archive log prefixes.
DSNTIPT SAMPLE LIBRARY This field allows you to specify a field name
for edited output of the installation CLIST.
Avoid overlaying existing data sets by
changing the middle node, NEW, to
something else. The only members you use
in this procedure are xxxxMSTR and
DSNTIJUZ in the sample library.
DSNTIPO PARAMETER Change this value only if you want to
MODULE preserve the existing member through the
CLIST.

Chapter 3. Altering your database design 211

 The output from the CLIST is a new set of tailored JCL with new cataloged
procedures and a DSNTIJUZ job, which produces a new member.
3. Run the first two job steps of DSNTIJUZ to update the subsystem parameter
load module.
Unless you have specified a new name for the load module, make sure the
output load module does not go to the SDSNEXIT or SDSNLOAD library used
by the active Db2 subsystem.
If you are changing the subsystem ID in addition to the system data set name
qualifier, you should run job steps DSNTIZP and DSNTIZQ to update the
DSNHDECP or a user-specified application defaults module (parameter SSID).
Make sure that the updated dsnhdecp parameter does not go to the SDSNEXIT
or SDSNLOAD library that is used by the active Db2 subsystem. Use caution
when changing the subsystem ID. For more information, see "MVS PARMLIB
updates panel: DSNTIPM" for the discussion of panel DSNTIPM for PARMLIB
members where the subsystem ID has to be changed.

Stopping Db2 when no activity is outstanding

Before stopping Db2, make sure the subsystem does not have any outstanding
activity, such as outstanding units of recovery or pending writes. Ensuring that at
restart, Db2 does not need to access the data sets through the log, which contains
the old data set qualifiers.

Procedure

To stop Db2 when no activity is outstanding:

1. Stop Db2 by entering the following command:
-STOP DB2 MODE(QUIESCE)
This command allows Db2 to complete processing currently executing
programs.
2. Start Db2 by entering the following command:
-START DB2 ACCESS(MAINT)
3. Use the following commands to make sure the subsystem is in a consistent
state.
-DISPLAY THREAD(*) TYPE(*)
-DISPLAY UTILITY (*)
-TERM UTILITY(*)
-DISPLAY DATABASE(*) RESTRICT
-DISPLAY DATABASE(*) SPACENAM(*) RESTRICT
-RECOVER INDOUBT
Correct any problems before continuing.
4. Stop Db2 by entering the following command:
-STOP DB2 MODE(QUIESCE)

5. Run the print log map utility (DSNJU004) to identify the current active log data
set and the last checkpoint RBA.
6. Run DSN1LOGP with the SUMMARY (YES) option, using the last checkpoint
RBA from the output of the print log map utility you ran in the previous step.
212 Administration Guide
 The report headed DSN1157I RESTART SUMMARY identifies active units of
recovery or pending writes. If either situation exists, do not attempt to
continue. Start Db2 with ACCESS(MAINT), use the necessary commands to
correct the problem, and repeat steps 4 through 6 until all activity is complete.

Renaming system data sets with the new qualifier

When renaming system data sets with a new qualifier, assume that the new
qualifier and the old qualifier reside in the same user catalog.

Before you begin

Access method services does not allow ALTER where the new name does not
match the existing catalog structure for an SMS-managed VSAM data set. If the
data set is not managed by SMS, the rename succeeds, but Db2 cannot allocate it.

Db2 table spaces are defined as linear data sets with DSNDBC as the second node
of the name for the cluster and DSNDBD for the data component. The examples
shown here assume the normal defaults for Db2 and VSAM data set names. Use
access method services statements with a generic name (*) to simplify the process.
Access method services allows only one generic name per data set name string.

Procedure

To rename the system data sets:

1. Using IDCAMS, change the names of the catalog and directory table spaces. Be
sure to specify the instance qualifier of your data set, y, which can be either I
or J. For example,
ALTER oldcat.DSNDBC.DSNDB01.*.y0001.A001 -
NEWNAME (newcat.DSNDBC.DSNDB01.*.y0001.A001)
ALTER oldcat.DSNDBD.DSNDB01.*.y0001.A001 -
NEWNAME (newcat.DSNDBD.DSNDB01.*.y0001.A001)
ALTER oldcat.DSNDBC.DSNDB06.*.y0001.A001 -
NEWNAME (newcat.DSNDBC.DSNDB06.*.y0001.A001)
ALTER oldcat.DSNDBD.DSNDB06.*.y0001.A001 -
NEWNAME (newcat.DSNDBD.DSNDB06.*.y0001.A001)
2. Using IDCAMS, change the active log names. Active log data sets are named
oldcat.LOGCOPY1.COPY01 for the cluster component and
oldcat.LOGCOPY1.COPY01.DATA for the data component. For example,
ALTER oldcat.LOGCOPY1.* -
NEWNAME (newcat.LOGCOPY1.*)
ALTER oldcat.LOGCOPY1.*.DATA -
NEWNAME (newcat.LOGCOPY1.*.DATA)
ALTER oldcat.LOGCOPY2.* -
NEWNAME (newcat.LOGCOPY2.*)
ALTER oldcat.LOGCOPY2.*.DATA -
NEWNAME (newcat.LOGCOPY2.*.DATA)
3. Using IDCAMS, change the BSDS names. For example,
ALTER oldcat.BSDS01 -
NEWNAME (newcat.BSDS01)
ALTER oldcat.BSDS01.* -
NEWNAME (newcat.BSDS01.*)
ALTER oldcat.BSDS02 -
NEWNAME (newcat.BSDS02)
ALTER oldcat.BSDS02.* -
NEWNAME (newcat.BSDS02.*)

Chapter 3. Altering your database design 213

 Updating the BSDS with the new qualifier
Update the first BSDS with the new alias and correct data set names for the active
logs. In this step, you do not attempt to change the names of existing archive log
data sets.

Before you begin

If these catalog entries or data sets will not be available in the future, copy all the
table spaces in the Db2 subsystem to establish a new recovery point. You can
optionally delete the entries from the BSDS. If you do not delete the entries, they
will gradually be replaced by newer entries.

Procedure

To update the BSDS:

1. Run the change log inventory utility (DSNJU003).
Use the new qualifier for the BSDS because it has now been renamed. The
following example illustrates the control statements required for three logs and
dual copy is specified for the logs. This is only an example; the number of logs
can vary and dual copy is an option. The starting and ending log RBAs are
from the print log map report.
NEWCAT VSAMCAT=newcat
DELETE DSNAME=oldcat.LOGCOPY1.DS01
DELETE DSNAME=oldcat.LOGCOPY1.DS02
DELETE DSNAME=oldcat.LOGCOPY1.DS03
DELETE DSNAME=oldcat.LOGCOPY2.DS01
DELETE DSNAME=oldcat.LOGCOPY2.DS02
DELETE DSNAME=oldcat.LOGCOPY2.DS03
NEWLOG DSNAME=newcat.LOGCOPY1.DS01,COPY1,STARTRBA=strtrba,ENDRBA=endrba
NEWLOG DSNAME=newcat.LOGCOPY1.DS02,COPY1,STARTRBA=strtrba,ENDRBA=endrba
NEWLOG DSNAME=newcat.LOGCOPY1.DS03,COPY1,STARTRBA=strtrba,ENDRBA=endrba
NEWLOG DSNAME=newcat.LOGCOPY2.DS01,COPY2,STARTRBA=strtrba,ENDRBA=endrba
NEWLOG DSNAME=newcat.LOGCOPY2.DS02,COPY2,STARTRBA=strtrba,ENDRBA=endrba
NEWLOG DSNAME=newcat.LOGCOPY2.DS03,COPY2,STARTRBA=strtrba,ENDRBA=endrba
During startup, Db2 compares the newcat value with the value in the system
parameter load module, and they must be the same.
2. Using the IDCAMS REPRO command, replace the contents of BSDS2 with the
contents of BSDS01.
3. Run the print log map utility (DSNJU004) to verify your changes to the BSDS.
4. At a convenient time, change the DD statements for the BSDS in any of your
offline utilities to use the new qualifier.

Establishing a new xxxxMSTR cataloged procedure

After updating BSDS with the new qualifier and before you start Db2, establish a
new xxxxMSTR cataloged procedure.

Procedure

To establish a new xxxxMSTR cataloged procedure:

1. Update xxxxMSTR in SYS1.PROCLIB with the new BSDS data set names.
2. Copy the new system parameter load module to the active
SDSNEXIT/SDSNLOAD library.

Starting Db2 with the new xxxxMSTR and load module

You can start Db2 with the new xxxxMSTR cataloged procedure and load module.

214 Administration Guide

 Procedure

To start Db2 with the new xxxxMSTR cataloged procedure and load module:
1. Issue a START DB2 command with the module name as shown in the following
example.
-START DB2 PARM(new_name)
2. Optional: If you stopped DSNDB01 or DSNDB06 in Stopping Db2 when no
activity is outstanding, you must explicitly start them in this step.

Changing qualifiers for other databases and user data sets

You can change qualifiers for Db2 databases other than the catalog and directory.

Before you begin

DSNDB07 is a system database that contains no permanent data, and can be

deleted and redefined with the new qualifier. If you are changing the qualifier for
DSNDB07, do that before changing the rest of the user databases.

About this task

You can change the databases in the following list that apply to your environment:
v DSNDB07 (work file database)
v DSNDB04 (system default database)
v DSNDDF (communications database)
v DSNRLST (resource limit facility database)
v DSNRGFDB (the database for data definition control)
v Any other application databases that use the old high-level qualifier

At this point, the Db2 catalog tables SYSSTOGROUP, SYSTABLEPART, and

SYSINDEXPART contain information about the old integrated user catalog alias. To
update those tables with the new alias, you must use the following procedures.
Until you do so, the underlying resources are not available.

Important: Table spaces and indexes that span more than one data set require
special procedures. Partitioned table spaces can have different partitions allocated
to different Db2 storage groups. Nonpartitioned table spaces or indexes only have
the additional data sets to rename (those with the lowest level name of A002, A003,
and so on).

Changing your work database to use the new high-level qualifier

You can use one of two methods to change the high-level qualifier for your work
database or the system database DSNDB07.

The method that you use depends on if you have a new installation or a migrated
installation of Db2 for z/OS.

Changing your work database for a new installation of Db2:

You can change the high-level qualifier for your work database if you have a new
installation of Db2 for z/OS.

Procedure

To change your work database:

Chapter 3. Altering your database design 215

 1. Reallocate the database by using the installation job DSNTIJTM from
prefix.SDSNSAMP.
2. Modify your existing job by changing the job to remove the BIND step for
DSNTIAD and renaming the data set names in the DSNTTMP step to your new
names. Make sure that you include your current allocations.

Changing your work database for a migrated installation of Db2:

You can change the high-level qualifier for your work database if you have a
migrated installation of Db2 for z/OS.

About this task

Migrated installations do not have a usable DSNTIJTM, because the IDCAMS

allocation step is missing.

Procedure

To change your work database:

1. Stop the database by using the following command (for a database named
DSNDB07):
-STOP DATABASE (DSNDB07)
2. Drop the database by using the following SQL statement:
DROP DATABASE DSNDB07;
3. Re-create the database by using the following SQL statement:
CREATE DATABASE DSNDB07;
4. Define the clusters by using the following access method services commands.
You must specify the instance qualifier of your data set, y, which can be either I
or J.
ALTER oldcat.DSNDBC.DSNDB07.DSN4K01.y0001.A001
NEWNAME newcat.DSNDBC.DSNDB07.DSN4K01.y0001.A001
ALTER oldcat.DSNDBC.DSNDB07.DSN32K01.y0001.A001
NEWNAME newcat.DSNDBC.DSNDB07.DSN32K01.y0001.A001
Repeat the preceding statements (with the appropriate table space name) for as
many table spaces as you use.
5. Create the table spaces in DSNDB07 by using the following commands:
CREATE TABLESPACE DSN4K01
IN DSNDB07
BUFFERPOOL BP0
CLOSE NO
USING VCAT DSNC910;
CREATE TABLESPACE DSN32K01
IN DSNDB07
BUFFERPOOL BP32K
CLOSE NO
USING VCAT DSNC910;
6. Start the database by using the following command:
-START DATABASE (DSNDB07)

Changing user-managed objects to use the new qualifier

You can change user-managed objects to use the new high-level qualifier.

216 Administration Guide

 Procedure

To change user-managed objects:

1. Stop the table spaces and index spaces by using the following command:
-STOP DATABASE(dbname) SPACENAM(*)
2. Use the following SQL ALTER TABLESPACE and ALTER INDEX statements
with the USING clause to specify the new qualifier:
ALTER TABLESPACE dbname.tsname
USING VCAT newcat;
ALTER INDEX creator.index-name
USING VCAT newcat;
Repeat this step for all the objects in the database.
3. Using IDCAMS, rename the data sets to the new qualifier. Also, be sure to
specify the instance qualifier of your data set, y, which can be either I or J:
ALTER oldcat.DSNDBC.dbname.*.y0001.A001 -
NEWNAME (newcat.DSNDBC.dbname.*.y0001.A001)
ALTER oldcat.DSNDBD.dbname.*.y0001.A001 -
NEWNAME (newcat.DSNDBD.dbname.*.y0001.A001)
4. Start the table spaces and index spaces, using the following command:
-START DATABASE(dbname) SPACENAM(*)
5. Verify the success of the procedure by entering the following command:
-DISPLAY DATABASE(dbname)
6. Using SQL, verify that you can access the data.

What to do next

Renaming the data sets can be done while Db2 is down. They are included here
because the names must be generated for each database, table space, and index
space that is to change.

Changing Db2-managed objects to use the new qualifier

You can keep an existing Db2 storage group and change only the high-level
qualifier.

| About this task

| The following procedure applies to most Db2-managed objects, but not to

| partition-by-growth table spaces. For information about changing the high-level
| qualifier for partition-by-growth table spaces, follow the procedure in Moving
| Db2-managed data with REORG, RECOVER, or REBUILD.

Procedure

To change Db2-managed objects:

1. Remove all table spaces and index spaces from the storage group by converting
the data sets temporarily to user-managed data sets.
a. Stop each database that has data sets you are going to convert, using the
following command:
-STOP DATABASE(dbname) SPACENAM(*)

Restriction: Some databases must be explicitly stopped to allow any

alterations. For these databases, use the following command:
-STOP DATABASE(dbname)

Chapter 3. Altering your database design 217

 b. Convert to user-managed data sets with the USING VCAT clause of the
SQL ALTER TABLESPACE and ALTER INDEX statements, as shown in the
following statements.
The data sets are linear VSAM data sets cataloged in the integrated catalog
facility catalog that catalog-name identifies. For more information about
catalog-name values, see Naming conventions (Db2 SQL).
ALTER TABLESPACE dbname.tsname
USING VCAT catalog-name;
ALTER INDEX creator.index-name
USING VCAT catalog-name;
2. Drop the storage group, using the following statement:
DROP STOGROUP stogroup-name;
The DROP succeeds only if all the objects that referenced this STOGROUP are
dropped or converted to user-managed (USING VCAT clause).
3. Re-create the storage group using the correct volumes and the new alias, using
the following statement:
CREATE STOGROUP stogroup-name
VOLUMES (VOL1,VOL2)
VCAT catalog-name;
4. Using IDCAMS, rename the data sets for the index spaces and table spaces to
use the new high-level qualifier. Also, be sure to specify the instance qualifier
of your data set, y, which can be either I or J:
ALTER oldcat.DSNDBC.dbname.*.y0001.A001 -
NEWNAME newcat.DSNDBC.dbname.*.y0001.A001
ALTER oldcat.DSNDBD.dbname.*.y0001.A001 -
NEWNAME newcat.DSNDBD.dbname.*.y0001.A001
If your table space or index space spans more than one data set, be sure to
rename those data sets also.
5. Convert the data sets back to Db2-managed data sets by using the new Db2
storage group. Use the following SQL ALTER TABLESPACE and ALTER
INDEX statements:
ALTER TABLESPACE dbname.tsname
USING STOGROUP stogroup-name
PRIQTY priqty
SECQTY secqty;
ALTER INDEX creator.index-name
USING STOGROUP stogroup-name
PRIQTY priqty
SECQTY secqty;
If you specify USING STOGROUP without specifying the PRIQTY and
SECQTY clauses, Db2 uses the default values.
6. Start each database, using the following command:
-START DATABASE(dbname) SPACENAM(*)
7. Verify the success of the procedure by entering the following command:
-DISPLAY DATABASE(dbname)
8. Using SQL, verify that you can access the data.

Tools for moving Db2 data

Moving Db2 data can be complicated. Fortunately, several tools exist that can help
to simplify the process.

Important: Before copying any Db2 data, resolve any data that is in an
inconsistent state. Use the DISPLAY DATABASE command to determine whether

218 Administration Guide

any inconsistent state exists, and the RECOVER INDOUBT command or the
RECOVER utility to resolve the inconsistency. The copying process generally loses
all traces of an inconsistency except the problems that result.

Although Db2 data sets are created using VSAM access method services, they are
specially formatted for Db2 and cannot be processed by services that use VSAM
record processing. They can be processed by VSAM utilities that use
control-interval (CI) processing and, if they are linear data sets (LDSs), also by
utilities that recognize the LDS type.

Furthermore, copying the data might not be enough. Some operations require
copying Db2 object definitions. And when copying from one subsystem to another,
you must consider internal values that appear in the Db2 catalog and the log, for
example, the Db2 object identifiers (OBIDs) and log relative byte addresses (RBAs).

The following tools can help to simplify the operations:

v The REORG and LOAD utilities move data sets from one disk device type to
another within the same Db2 subsystem.
The INCURSOR option of the LOAD utility allows you to specify a cursor to
select data from another Db2 table or tables, which can be on a remote Db2
system. Use the EXEC SQL utility control statement to declare the cursor before
executing the LOAD utility. This option uses the Db2 UDB family cross-loader
function.
v The COPY and RECOVER utilities allow you to recover an image copy of a Db2
table space or index space onto another disk device within the same subsystem.
v The UNLOAD or REORG UNLOAD EXTERNAL utility unloads a Db2 table into
a sequential file and generates statements to allow the LOAD utility to load it
elsewhere.
v The DSN1COPY utility copies the data set for a table space or index space to
another data set. It can also translate the object identifiers and reset the log
RBAs in the target data set. When you use the OBIDXLAT option of DSN1COPY
to move objects from one system to another, use REPAIR VERSIONS to update
the version information in the catalog and directory for the target table space or
index.

You might also want to use the following tools to move Db2 data:
v The Db2 DataPropagator is a licensed program that can extract data from Db2
tables, DL/I databases, VSAM files, and sequential files.
v DFSMS, which contains the following functional components:
– Data Set Services (DFSMSdss)
Use DFSMSdss to copy data between disk devices. You can use online panels
to control this, through the Interactive Storage Management Facility (ISMF)
that is available with DFSMS.
– Data Facility Product (DFSMSdfp)
This is a prerequisite for Db2. You can use access method services EXPORT
and IMPORT commands with Db2 data sets when control interval processing
(CIMODE) is used.
– Hierarchical Storage Manager (DFSMShsm)
With the MIGRATE, HMIGRATE, or HRECALL commands, which can specify
specific data set names, you can move data sets from one disk device type to
another within the same Db2 subsystem. Do not migrate the Db2 directory,
Db2 catalog, and the work file database (DSNDB07). Do not migrate any data
sets that are in use frequently, such as the bootstrap data set and the active

Chapter 3. Altering your database design 219

 log. With the MIGRATE VOLUME command, you can move an entire disk
volume from one device type to another. The program can be controlled using
online panels, through the Interactive Storage Management Facility (ISMF).

The following table shows which tools are applicable to specific operations.
Table 35. Tools applicable to data-moving operations
Copying an entire
Tool Moving a data set Copying a database subsystem
REORG and LOAD Yes Yes No
UNLOAD Yes No No
COPY and RECOVER Yes No No
DSNTIAUL Yes Yes No
DSN1COPY Yes Yes No
™
DataRefresher or DXT Yes Yes No
DFSMSdss Yes No Yes
DFSMSdfp Yes No Yes
DFSMShsm Yes No No

Some of the listed tools rebuild the table space and index space data sets, and they
therefore generally require longer to execute than the tools that merely copy them.
The tools that rebuild are REORG and LOAD, RECOVER and REBUILD,
DSNTIAUL, and DataRefresher. The tools that merely copy data sets are
DSN1COPY, DFSMSdss, DFSMSdfp EXPORT and IMPORT, and DFSMShsm.

DSN1COPY is fairly efficient in use, but somewhat complex to set up. It requires a
separate job step to allocate the target data sets, one job step for each data set to
copy the data, and a step to delete or rename the source data sets. DFSMSdss,
DFSMSdfp, and DFSMShsm all simplify the job setup significantly.

Although less efficient in execution, RECOVER is easy to set up if image copies

and recover jobs already exist. You might only need to redefine the data sets
involved and recover the objects as usual.
Related concepts:
Db2 online utilities (Db2 Utilities)
DFSMShsm Storage Administration Reference
z/OS DFSMSdss Storage Administration
Related tasks:
Loading data from DL/I
Related information:
DFSMS Access Method Services Commands
DFSMShsm Managing Your Own Data

Moving Db2 data

Db2 provides several tools and options to make moving data easier.

You can move data within Db2 in several ways: copying a database, copying a Db2
subsystem, or by moving data sets within a particular Db2 subsystem.

220 Administration Guide

 Copying a relational database

Copying your relational database involves not only copying data, but also finding
or generating, and executing, SQL statements to create storage groups, databases,
table spaces, tables, indexes, views, synonyms, and aliases.

You can copy a database by using the DSN1COPY utility. As with the other
operations, DSN1COPY is likely to execute faster than the other applicable tools. It
copies directly from one data set to another, while the other tools extract input for
LOAD, which then loads table spaces and builds indexes. But again, DSN1COPY is
more difficult to set up. In particular, you must know the internal Db2 object
identifiers, which other tools translate automatically.

Copying an entire Db2 subsystem

Copying a Db2 subsystem from one z/OS system to another involves the
following:
v All the user data and object definitions
v The Db2 system data sets:
– The log
– The bootstrap data set
– Image copy data sets
– The Db2 catalog
– The integrated catalog that records all the Db2 data sets

Although you can have two Db2 subsystems on the same z/OS system, one cannot
be a copy of the other.

Only two of the tools listed are applicable: DFSMSdss DUMP and RESTORE, and
DFSMSdfp EXPORT and IMPORT.
Related concepts:
Moving a Db2 data set
Related tasks:
Changing the high-level qualifier for Db2 data sets
Related reference:
DSN1COPY (Db2 Utilities)

Moving a Db2 data set

You can move Db2 data by using the RECOVER, REORG, or DSN1COPY utilities,
or by using non-Db2 facilities, such as DFSMSdss.

Both the Db2 utilities and the non-Db2 tools can be used while Db2 is running, but
the space to be moved should be stopped to prevent users from accessing it.

If you use storage groups, then you can change the storage group definition to
include the new volumes.

The following procedures differ mainly in that the first procedure assumes that
you do not want to reorganize or recover the data. Generally, this means that the
first procedure is faster. In all cases, make sure that there is enough space on the
target volume to accommodate the data set.

Choose between the following methods for moving data sets:

Chapter 3. Altering your database design 221

 v Moving data without REORG or RECOVER
v Moving Db2-managed data with REORG, RECOVER, or REBUILD
Related tasks:
Altering Db2 storage groups

Moving data without REORG or RECOVER

You can move data that you do not want to reorganize or recover.

Procedure

To move data without using the REORG or RECOVER utilities:

1. Stop the database by issuing a STOP DATABASE command.

-STOP DATABASE(dbname) SPACENAM(*)

2. Move the data, using DSN1COPY or a non-Db2 facility.

3. Issue the ALTER INDEX or ALTER TABLESPACE statement to use the

new integrated catalog facility catalog name or Db2 storage group name.
4. Start the database by issuing a START DATABASE command.
-START DATABASE(dbname) SPACENAM(*)

Related reference:
DSN1COPY (Db2 Utilities)

Moving Db2-managed data with REORG, RECOVER, or REBUILD

You can create a storage group (possibly using a new catalog alias) and move the
data to that new storage group.

Procedure

To create a new storage group that uses the correct volumes and the new alias:
1. Execute the CREATE STOGROUP SQL statement to create the new storage
group.

For example:
CREATE STOGROUP stogroup-name
VOLUMES (VOL1,VOL2)
VCAT (newcat);

2. Issue the STOP DATABASE command on the database that contains the table
spaces or index spaces whose data sets you plan to move, to prevent access to
those data sets.

-STOP DATABASE(dbname) SPACENAM(*)

3. Execute ALTER TABLESPACE or ALTER INDEX SQL statements to assign the

table spaces or indexes to the new storage group.

222 Administration Guide

 ALTER TABLESPACE dbname.tsname
USING STOGROUP stogroup-name;
ALTER INDEX creator.index-name
USING STOGROUP stogroup-name;

4. Using IDCAMS, rename the data sets for the index spaces and table spaces to
use the high-level qualifier for the new storage group. Also, be sure to specify
the instance qualifier of your data set, y, which can be either I or J. If you have
run REORG with SHRLEVEL CHANGE or SHRLEVEL REFERENCE on any
table spaces or index spaces, the fifth-level qualifier might be J0001.
ALTER oldcat.DSNDBC.dbname.*.y0001.A001 -
NEWNAME newcat.DSNDBC.dbname.*.y0001.A001
ALTER oldcat.DSNDBD.dbname.*.y0001.A001 -
NEWNAME newcat.DSNDBD.dbname.*.y0001.A001
5. Issue the START DATABASE command to start the database for utility
processing only.

-START DATABASE(dbname) SPACENAM(*) ACCESS(UT)

6. Run the REORG utility or the RECOVER utility on the table space or index
space, or run the REBUILD utility on the index space.
7. Issue the START DATABASE command to start the database for full processing.

-START DATABASE(dbname) SPACENAM(*)

Chapter 3. Altering your database design 223

224 Administration Guide
Part 2. Operation and recovery

© Copyright IBM Corp. 1982, 2017 225

226 Administration Guide
Chapter 4. Controlling Db2 operations by using commands
You can control most aspects of the operational environment by issuing
commands. For most commands, Db2 issues output in the form of messages. Db2
also issues system messages for other situations. To operate and recover Db2
successfully, you must know how to issue commands and retrieve and interpret
command output messages and system messages.

Before you begin

Before you can issue commands, you must have the required authorities
and privileges. For descriptions of the authorities and privileges that are required
for particular commands, see the “Authorities” sections in the topics for each
command under About Db2 and related commands (Db2 Commands).

For more information about specific privileges and authorities, see Privileges and
authorities (Managing Security).

About this task

Introductory concepts
Commands for controlling Db2 and related facilities (Introduction to Db2 for
z/OS)
Db2 attachment facilities (Introduction to Db2 for z/OS)

You can control most aspects of the operational environment by using the DSN
command of TSO and its subcommands and Db2 commands. However, you might
also any of the following types of commands to control connections from various
attachment facilities, the z/OS internal resource lock manager (IRLM), and the
Administrative task scheduler:
v The TSO command DSN and its subcommands
v Db2 commands
v CICS attachment facility commands
v IMS commands
v Administrative task scheduler commands
v z/OS IRLM commands
v TSO CLISTs

For more information about the different types of commands that you can use
control Db2 operations, see Command types and environments in Db2 (Db2
Commands).

Within the z/OS environment, you can issue most types of commands from
different interactive contexts, including the following consoles and terminals:
v z/OS consoles
v TSO terminals, by any of the following methods:
– Issuing the DSN command from the TSO READY prompt
– Entering commands in the DB2 Commands panel inDB2I
v IMS terminals

© Copyright IBM Corp. 1982, 2017 227

 v Authorized CICS terminals

You might notice the similarities between the types of commands and the types of
consoles and terminals. However, do not confuse the types of commands with the
types of consoles and terminals. Although they are related, you can issue many of
the different commands types, and receive output messages, from many of the
different consoles or terminals.

The following table summarizes the capabilities to issue different type of

commands and receive output messages from specific consoles and terminals.
Table 36. Operational control summary
Type of IMS master Authorized
operation z/OS console TSO terminal terminal CICS terminal
Issue Db2 Yes Yes1 Yes1 Yes1
commands and
receive replies
Receive Db2 Yes No No No
unsolicited
output
Issue IMS Yes2 No Yes No
commands
Receive IMS No3 No Yes No
attachment
facility
unsolicited
output
Issue CICS Yes4 No No Yes
commands
Receive CICS No3 No No Yes5
attachment
facility
unsolicited
output

Notes:
1. Does not apply to START DB2. Commands that are issued from IMS must have
the prefix /SSR. Commands that are issued from CICS must have the prefix
DSNC.
2. This applies when using outstanding WTOR.
3. The “Attachment facility unsolicited output” does not include “Db2 unsolicited
output.”
4. Use the z/OS command MODIFY jobname CICS command. The z/OS console
must already be defined as a CICS terminal.
5. Specify the output destination for the unsolicited output of the CICS
attachment facility in the RDO.

You can issue many commands from the background within batch programs, such
as the following types of programs:
v z/OS application programs
v Authorized CICS programs
v IMS programs

228 Administration Guide

| v APF-authorized programs, such as a terminal monitor program (TMP)
v IFI application programs

Related tasks:
Submitting work to Db2
Related reference:
Executing the terminal monitor program (TSO/E Customization)
Writing JCL for command execution (TSO/E Customization)
Related information:
About Db2 and related commands (Db2 Commands)

Issuing commands from the z/OS console

You can issue commands to Db2 subsystem from the z/OS console.

About this task

More than one Db2 subsystem can run under z/OS. From the console, you
must add a prefix to a Db2 command with special characters that identify the
subsystem that the command is directed to. The 1 - 8-character prefix is called the
command prefix.

The command prefix of a Db2 subsystem is specified by the value of the

COMMAND PREFIX field on the DSNTIPM installation panel. The default
command prefix is a hyphen character concatenated with the subsystem name.

Procedure

To issue commands from a z/OS console:

Specify the command prefix for the Db2 subsystem before the command. For
example, the following command starts the Db2 subsystem that is uses -DSN1 for
the command prefix:
-DSN1 START DB2

Related reference:
COMMAND PREFIX field (Db2 Installation and Migration)
Related information:
About Db2 and related commands (Db2 Commands)

Issuing commands from TSO terminals

You can connect and issue commands from TSO terminals by issuing a DSN
command to invoke the DSN command processor explicitly, or through the DB2I
(Db2 Interactive) ISPF panels.

Chapter 4. Controlling Db2 operations by using commands 229

 About this task

Introductory concepts
Common ways to interact with Db2 for z/OS (Introduction to Db2 for z/OS)
TSO attachment facility (Introduction to Db2 for z/OS)

Procedure

To issue commands from a TSO terminal take one of the following actions:
v Issue a DSN command to start an explicit DSN session. The DSN command can
be issued in the foreground or background, when running under the TSO
terminal monitor program (TMP).

Examples:
Invoking a DSN session with five retries at 30-second intervals
For example, the following TSO command invokes a DSN session,
requesting five retries at 30-second intervals:
DSN SYSTEM (DB2) RETRY (5)
Displaying information about threads from a TSO session
The TSO terminal displays:
READY

You enter:
DSN SYSTEM (subsystem-name)

The TSO terminal displays:

DSN

You enter:
-DISPLAY THREAD

Db2 returns the following messages:

DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I
. - ACTIVE THREADS -
.
.
v Start a DB2I session to invoke and implicit DSN session. The following figure
shows the options of the DB2I Primary Option Menu.

230 Administration Guide

 DSNEPRI DB2I PRIMARY OPTION MENU SSID: DSN
COMMAND ===>

Select one of the following DB2 functions and press ENTER.

1 SPUFI (Process SQL statements)

2 DCLGEN (Generate SQL and source language declarations)
3 PROGRAM PREPARATION (Prepare a DB2 application program to run)
4 PRECOMPILE (Invoke DB2 precompiler)
5 BIND/REBIND/FREE (BIND, REBIND, or FREE plans or packages)
6 RUN (RUN an SQL program)
7 DB2 COMMANDS (Issue DB2 commands)
8 UTILITIES (Invoke DB2 utilities)
D DB2I DEFAULTS (Set global parameters)
X EXIT (Leave DB2I)

Figure 18. The ISPF panel for the DB2I Primary Option Menu

When you complete operations by using the DB2I panels, DB2I invokes CLISTs,
which start the DSN session and invoke appropriate subcommands.
Related concepts:
DSN command processor (Db2 Application programming and SQL)
Related tasks:
Running TSO application programs
Controlling TSO connections
Related reference:
DSN (TSO) (Db2 Commands)
The DB2I primary option menu (Introduction to Db2 for z/OS)
Related information:
About Db2 and related commands (Db2 Commands)

Issuing commands from CICS terminals

You can enter all Db2 commands except START DB2 from a CICS terminal that is
authorized to enter the DSNC transaction code.

Procedure

To issue commands from CICS terminals:

Use the DSNC transaction. CICS can attach to only one Db2 subsystem at a time,
so it does not use the Db2 command prefix. Instead, each command that is entered
through the CICS attachment facility must be preceded by a hyphen (-). The CICS
attachment facility routes the commands to the connected Db2 subsystem and
obtains the command responses.

Example

For example, you enter the following command:

DSNC -DISPLAY THREAD

Db2 returns the following messages:

Chapter 4. Controlling Db2 operations by using commands 231

 DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I
. - ACTIVE THREADS -
.
.

Related information:
Issuing commands to Db2 using the DSNC transaction (CICS Transaction
Server for z/OS)

Issuing commands from IMS terminals

You can enter all Db2 commands except START DB2 from either an IMS terminal
or program. The terminal or program must be authorized to enter the IMS /SSR
command.

About this task

An IMS subsystem can attach to more than one Db2 subsystem, so you
need to add a prefix. Commands that are directed from IMS to Db2 with a special
character that identifies which subsystem to direct the command to. That character
is called the command recognition character (CRC). It is specified it when you define
Db2 to IMS, in the subsystem member entry in IMS.PROCLIB.

Tip: You can use the same character for the CRC and the command prefix for a
single Db2 subsystem. However, to do that, you must specify a one character
command prefix. Otherwise you cannot match these identifiers.

Most examples in this information assume that both the command prefix and the
CRC are the hyphen (-) . However, if you can attach to more than one Db2
subsystem, you must issue your commands using the appropriate CRC. In the
following example, the CRC is a question mark character:

Example

You enter the following command:

/SSR ?DISPLAY THREAD

Db2 returns the following messages:

DFS058 SSR COMMAND COMPLETED
DSNV401I ? DISPLAY THREAD REPORT FOLLOWS -
DSNV402I
. ? ACTIVE THREADS -
.
.

Related reference:
COMMAND PREFIX field (Db2 Installation and Migration)
Related information:
IMS commands

Issuing commands from application programs

Certain kinds of application programs can issue Db2 commands.

232 Administration Guide

About this task

APF-authorized programs
As with IMS, Db2 commands (including START DB2) can be passed from
an APF-authorized program to multiple Db2 subsystems by the MGCRE
(SVC 34) z/OS service. Thus, the value of the command prefix identifies
the particular subsystem to which the command is directed. The subsystem
command prefix is specified, as in IMS, when Db2 is installed (in the
SYS1.PARMLIB member IEFSSNxx). Db2 supports the z/OS WTO
command and response token (CART) to route individual Db2 command
response messages to the invoking application program. Use of the CART
is necessary if multiple Db2 commands are issued from a single application
program.
For example, to issue DISPLAY THREAD to the default Db2 subsystem
from an APF-authorized program that runs as a batch job, use the
following code:
MODESUPV DS 0H
MODESET MODE=SUP,KEY=ZERO
SVC34 SR 0,0
MGCRE CMDPARM
EJECT
CMDPARM DS 0F
CMDFLG1 DC X’00’
CMDLENG DC AL1(CMDEND-CMDPARM)
CMDFLG2 DC X’0000’
CMDDATA DC C’-DISPLAY THREAD’
CMDEND DS 0C

Db2 returns the following messages:

DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I
. - ACTIVE THREADS -
.
.
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
IFI application programs
An application program can issue Db2 commands using the
instrumentation facility interface (IFI). This method of issuing commands
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. For commands that are executed asynchronously, the
return code indicates whether the command started successfully.
The IFI application program protocols are available through the IMS, CICS,
TSO attachment facilities, the call attachment facility (CAF), and the
Resource Recovery Services attachment facility (RRSAF).

Related concepts:
Submitting commands from monitor programs (Db2 Performance)
Related tasks:
Submitting work to Db2

Chapter 4. Controlling Db2 operations by using commands 233

 Related reference:
COMMAND (Db2 Performance)
Executing the terminal monitor program (TSO/E Customization)
Writing JCL for command execution (TSO/E Customization)

Destinations for command output messages

In most cases, Db2 command response are sent to the entering terminal or, for
batch jobs, to the printed listing. In CICS, you can direct command responses to
another terminal.

Name the other terminal as the destination (dest) in this command:

DSNC dest -START DATABASE

If a Db2 command is entered from an IMS or CICS terminal, the response

messages can be directed to different terminals. If the response includes more than
one message, the following cases are possible:
v If the messages are issued in a set, the entire set of messages is sent to the IMS
or CICS terminal that entered the command. For example, DISPLAY THREAD
issues a set of messages.
v If the messages are issued one after another, and not in a set, only the first
message is sent to the terminal that entered the command. Subsequent messages
are routed to one or more z/OS consoles using the WTO function. For example,
START DATABASE issues several messages one after another.
You can choose alternative consoles to receive the subsequent messages by
assigning them the routing codes that are placed in the DSNZPxxx module when
Db2 is installed. If you want to have all of the messages available to the person
who sent the command, route the output to a console near the IMS or CICS
master terminal.

For APF-authorized programs that run in batch jobs, command responses are
returned to the master console and to the system log if hardcopy logging is
available. Hardcopy logging is controlled by the z/OS system command VARY.

Related reference:
z/OS VARY command (MVS System Commands)
-DISPLAY THREAD (Db2) (Db2 Commands)
-START DATABASE (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Unsolicited Db2 messages

Unsolicited subsystem messages can be sent to the z/OS console that issues the
START DB2 command. They also can be sent to consoles that have been assigned the
routing codes that you listed in the DSNZPxxx module during Db2 installation.

234 Administration Guide

However, the following messages from the IMS and the CICS attachment facilities
are exceptions:
v Specific IMS attachment facility messages are sent to the IMS master terminal.
v Unsolicited CICS messages are sent to the transient data entries that are
specified for the MSGQUEUEn(name) attribute in the RDO (resource definition
online).
v CICS statistics messages that are issued because of shutdown are sent to the
transient data entry that is specified in the RDO (STATSQUEUE).

Some Db2 messages that are sent to the z/OS console are marked as critical with
the WTO descriptor code (11). This code signifies “critical eventual action
requested” by Db2. Preceded by an at sign (@) or an asterisk (*), critical Db2
messages remain on the screen until they are specifically deleted. This prevents the
messages from being missed by the operator, who is required to take a specific
action.
Related concepts:
How to interpret message numbers (Db2 Messages)
Related information:
Troubleshooting for CICS Db2 (CICS Db2 Guide)

Chapter 4. Controlling Db2 operations by using commands 235

236 Administration Guide
Chapter 5. Starting and stopping Db2
You start and stop Db2 by using the START DB2 and STOP DB2 commands.

Before you begin

Before Db2 is stopped, the system takes a shutdown checkpoint. This checkpoint
and the recovery log give Db2 the information it needs to restart.

About this task

You can limit access to data at startup and startup after an abend.

Starting Db2
You must start Db2 to make it active and available to Db2 subsystem is active and
available to TSO applications, and other subsystems such as IMS™ and CICS®.

About this task

When Db2 is installed, it is defined as a formal z/OS subsystem. Afterward, the

following message appears during any IPL of z/OS:
DSN3100I - DSN3UR00 - SUBSYSTEM ssnm READY FOR -START COMMAND

where ssnm is the Db2 subsystem name.

Procedure

To start a Db2 subsystem:

Issue the START DB2 command by using one of the following methods:
v Issue the START DB2 command from a z/OS console that is authorized to issue
system control commands (z/OS command group SYS).
The command must be entered from the authorized console and cannot be
submitted through JES or TSO.
Starting Db2 by a JES batch job or a z/OS START command is impossible. The
attempt is likely to start an address space for Db2 that will abend (most likely
with reason code X'00E8000F').
v Start Db2 from an APF-authorized program by passing a START DB2 command
to the MGCRE (SVC 34) z/OS service.

Related tasks:
Installation step 14: Start the Db2 subsystem (Db2 Installation and Migration)
Migration step 17: Start Db2 11 (Db2 Installation and Migration)
Starting the Db2 subsystem (Db2 Installation and Migration)
Related reference:

© Copyright IBM Corp. 1982, 2017 237

 -START DB2 (Db2) (Db2 Commands)

Messages at start
Db2 issues a variety of messages when you start Db2. The specific messages vary
based on the parameters that you specify.

At start time, Db2 issues some or all of the following messages.

$HASP373 xxxxMSTR STARTED
DSNZ002I - SUBSYS ssnm SYSTEM PARAMETERS
LOAD MODULE NAME IS dsnzparm-name
DSNY001I - SUBSYSTEM STARTING
DSNJ127I - SYSTEM TIMESTAMP FOR BSDS=87.267 14:24:30.6
DSNJ001I - csect CURRENT COPY n ACTIVE LOG DATA
SET IS DSNAME=...,
STARTRBA=...,ENDRBA=...
DSNJ099I - LOG RECORDING TO COMMENCE WITH
STARTRBA = xxxxxxxxxxxx
$HASP373 xxxxDBM1 STARTED
DSNR001I - RESTART INITIATED
DSNR003I - RESTART...PRIOR CHECKPOINT RBA=xxxxxxxxxxxx
DSNR004I - RESTART...UR STATUS COUNTS...
IN COMMIT=nnnn, INDOUBT=nnnn, INFLIGHT=nnnn,
IN ABORT=nnnn, POSTPONED ABORT=nnnn
DSNR005I - RESTART...COUNTS AFTER FORWARD RECOVERY
IN COMMIT=nnnn, INDOUBT=nnnn
DSNR006I - RESTART...COUNTS AFTER BACKWARD RECOVERY
INFLIGHT=nnnn, IN ABORT=nnnn, POSTPONED ABORT=nnnn
DSNR002I - RESTART COMPLETED
DSN9002I - DSNYASCP ’START DB2’ NORMAL COMPLETION
DSNV434I - DSNVRP NO POSTPONED ABORT THREADS FOUND
DSN9022I - DSNVRP ’RECOVER POSTPONED’ NORMAL COMPLETION

If any of the nnnn values in message DSNR004I are not zero, message DSNR007I is
issued to provide the restart status table.

Subsystem parameters at start

Starting Db2 invokes the load module for subsystem parameters. This load module
contains information that was specified when Db2 was installed.

For example, the module contains the name of the IRLM to connect to. In addition,
it indicates whether the distributed data facility (DDF) is available and, if it is,
whether it should be automatically started when Db2 is started. You can specify
PARM (module-name) on the START DB2 command to provide a parameter module
other than the one that is specified at installation.

The START DB2 command starts the system services address space, the database
services address space, and, depending on specifications in the load module for
subsystem parameters (DSNZPARM by default), the distributed data facility
address space. Optionally, another address space, for the internal resource lock
manager (IRLM), can be started automatically.

A conditional restart operation is available, but no parameters indicate normal or

conditional restart on the START DB2 command.

238 Administration Guide

 Related concepts:
Conditional restart
Related tasks:
Starting DDF
Related reference:
-START DB2 (Db2) (Db2 Commands)

Application defaults module name at start

You can use the DECP option of the START DB2 command to specify the application
defaults module that is loaded at Db2 startup.

Important: If your Db2 environment has a dependency on the name DSNHDECP,

you should not include the DECP option. Tools from an independent software
vendor, or your own applications might have a dependency on this module name.
For example, if a CAF or RRSAF application does an implicit identify or connect
operation, the module with the name DSNHDECP is used.

Restricting access to data

You can restrict access to data with an option of the START DB2 command.

Procedure

To restrict access to data:

Issue the START DB2 command with one of the following options:
ACCESS(MAINT)
To limit access to users who have installation SYSADM or installation
SYSOPR authority.
Users with those authorities can do maintenance operations such as
recovering a database or taking image copies. To restore access to all users,
stop Db2 and then restart it, either omitting the ACCESS keyword or
specifying ACCESS(*).
ACCESS(*)
To allow all authorized users to connect to Db2.

Ending the wait state at startup

JCL errors sometimes occur (for example, a device allocation error or an incorrect
region size). When JCL errors occur during startup of the database services address
space, the Db2 subsystem goes into wait status.

Procedure

To end the wait status:

Cancel the system services address space and the distributed data facility address
space from the console.

Chapter 5. Starting and stopping Db2 239

 What to do next

After Db2 stops, check the start procedures of all three Db2 address spaces for
correct JCL syntax.

To accomplish this check, compare the expanded JCL in the SYSOUT output with
the correct JCL provided in MVS JCL Reference. Then, take the member name of
the erroneous JCL procedure, which is also provided in the SYSOUT data set, to
the system programmer who maintains your procedure libraries. After finding out
which PROCLIB contains the JCL in question, locate the procedure and correct it.

Restart options after an abend

Starting Db2 after it abends is different from starting it after the STOP DB2
command is issued.

After the STOP DB2 command, Db2 finishes its work in an orderly way and takes
a shutdown checkpoint before stopping. When Db2 is restarted, it uses information
from the system checkpoint and recovery log to determine the system status at
shutdown.

When a power failure occurs, Db2 abends without being able to finish its work or
take a shutdown checkpoint. When Db2 is restarted after an abend, it refreshes its
knowledge of its status at termination by using information on the recovery log,
Db2 then notifies the operator of the status of various units of recovery.

You can indicate that you want Db2 to postpone some of the backout work that is
traditionally performed during system restart. You can delay the backout of
long-running units of recovery by using installation options LIMIT BACKOUT and
BACKOUT DURATION on panel DSNTIPL.

Normally, the restart process resolves all inconsistent states. In some cases, you
have to take specific steps to resolve inconsistencies. There are steps you can take
to prepare for those actions. For example, you can limit the list of table spaces that
are recovered automatically when Db2 is started.
Related tasks:
Restarting Db2 after termination
Related reference:
DSNTIPL: Active log data set parameters (Db2 Installation and Migration)

Stopping Db2
Before Db2 stops, all Db2-related write to operator with reply (WTOR) messages
must receive replies.

About this task

Procedure

To stop a Db2 subsystem:

Issue one of the following STOP DB2 commands:

v -STOP DB2 MODE(QUIESCE)

240 Administration Guide

v -STOP DB2 MODE(FORCE)
The following messages are returned:
DSNY002I - SUBSYSTEM STOPPING
DSN9022I - DSNYASCP ’-STOP DB2’ NORMAL COMPLETION
DSN3104I - DSN3EC00 - TERMINATION COMPLETE

If the STOP DB2 command is not issued from a z/OS console, messages DSNY002I
and DSN9022I are not sent to the IMS or CICS master terminal operator. They are
routed only to the z/OS console that issued the START DB2 command.

What to do next

Before restarting Db2, the following message must also be returned to the z/OS
console that is authorized to enter the START DB2 command:
DSN3100I - DSN3EC00 - SUBSYSTEM ssnm READY FOR -START COMMAND

Related concepts:
Normal termination
Related reference:
-START DB2 (Db2) (Db2 Commands)
-STOP DB2 (Db2) (Db2 Commands)

Chapter 5. Starting and stopping Db2 241

242 Administration Guide
Chapter 6. Submitting work to Db2
Application programs that run under TSO, IMS, or CICS can use Db2 resources by
executing embedded SQL statements or Db2 and related commands.

About this task

Application programs must meet certain conditions to embed SQL statements and
to authorize the use of Db2 resources and data. These conditions vary based on the
environment of the application program.

All application programming default values, including the subsystem name that
the programming attachment facilities use, are in the DSNHDECP load module.
Make sure that your JCL specifies the proper set of program libraries.
Related tasks:
Controlling Db2 operations by using commands
Related reference:
Executing the terminal monitor program (TSO/E Customization)

Submitting work by using DB2I

Using the interactive program DB2I (Db2 Interactive), you can run application
programs and perform many Db2 operations by entering values on panels. DB2I
runs under TSO using ISPF (Interactive System Productivity Facility) services.

About this task

Introductory concepts
Common ways to interact with Db2 for z/OS (Introduction to Db2 for z/OS)

Procedure

To submit work by using DB2I:

1. Log on to TSO by following your local procedures.
2. Enter ISPF.
3. Enter parameters to control operations.
Related concepts:
DSN command processor (Db2 Application programming and SQL)
Related tasks:
Issuing commands from TSO terminals

Running TSO application programs

You use the DSN command and a variety of DSN subcommands to run TSO
applications.

© Copyright IBM Corp. 1982, 2017 243

 Procedure

To run TSO application programs:

1. Log on to TSO.
2. Enter the DSN command.
3. Respond to the prompt by entering the RUN subcommand.

Results

The terminal monitor program (TMP) attaches the Db2-supplied DSN command
processor, which in turn attaches the application program.

Example

The following example runs application program DSN8BC3. The program is in

library prefix.RUNLIB.LOAD, which is the name that is assigned to the load
module library.
DSN SYSTEM (subsystem-name)
RUN PROGRAM (DSN8BC3) PLAN(DSN8BH11) LIB (’prefix.RUNLIB.LOAD’)
END

Sources that Db2 checks to find authorization access for an

application program
Db2 checks multiple sources to find authorization access for an application
program.

Db2 checks the sources in the order that they are listed. If the first source is
unavailable, Db2 checks the second source, and so on.
1. RACF USER parameter supplied at logon
2. TSO logon user ID
3. Site-chosen default authorization ID
4. IBM-supplied default authorization ID

You can modify either the RACF USER parameter or the TSO user ID by a locally
defined authorization exit routine.

Running IMS application programs

To run IMS application programs, you can enter transactions from an IMS terminal.
You also can invoke IMS transactions and commands by using the Db2-supplied
stored procedures DSNAIMS or DSNAIMS2.

About this task

Use the DSNAIMS stored procedure to send commands and single-segment

transactions. Use the DSNAIMS2 stored procedure to send commands and
multi-segment transactions.

244 Administration Guide

 Application programs that contain SQL statements run in the message processing
program (MPP), the batch message processing (BMP), the Fast Path region, or the
IMS batch region.

The program must be link-edited with the IMS language interface module
(DFSLI000). It can write to and read from other database management systems
using the distributed data facility, in addition to accessing DL/I and Fast Path
resources.

Db2 checks whether the authorization ID that IMS provides is valid. For
message-driven regions, IMS uses the SIGNON-ID or LTERM as the authorization
ID. For non-message-driven regions and batch regions, IMS uses the ASXBUSER
field (if RACF or another security package is active). The ASXBUSER field is
defined by z/OS as seven characters. If the ASXBUSER field contains binary zeros
or blanks (which indicates that RACF or another security package is not active),
IMS uses the PSB name instead.

An IMS terminal operator probably notices few differences between application

programs that access Db2 data and programs that access DL/I data because IMS
sends no Db2-related messages to a terminal operator. However, your program can
signal Db2 error conditions with a message of your choice. For example, at its first
SQL statement, a program receives an SQL error code if the resources that are to
run the program are not available or if the operator is not authorized to use the
resources. The program can interpret the code and issue an appropriate message to
the operator.

You can run batch DL/I jobs to access Db2 resources; Db2-DL/I batch support uses
the IMS attachment facility.
Related tasks:
Loading and running a batch program (Db2 Application programming and
SQL)
Related reference:
DSNAIMS stored procedure (Db2 SQL)
DSNAIMS2 stored procedure (Db2 SQL)
Related information:
Application programming design

Running CICS application programs

To run CICS applications, enter transactions from CICS terminals. You can also
invoke CICS transactions by using the CICS transaction-invocation stored
procedure.

About this task

CICS transactions that issue SQL statements must be link-edited with the CICS
attachment facility language interface module, DSNCLI, and the CICS command
language interface module. CICS application programs can issue SQL, DL/I, or
CICS commands. After CICS connects to Db2, any authorized CICS transaction can
issue SQL requests that can write to and read from multiple Db2 instances using
the distributed data facility. The application programs run as CICS applications.

Chapter 6. Submitting work to Db2 245

 Db2 checks an authorization ID that is related to the transaction against a plan that
is assigned to it. The authorization ID for the transaction can be the operator ID,
terminal ID, transaction ID, RACF-authenticated user ID, or another identifier that
is explicitly provided by the RDO (resource definition online).
Related concepts:
Ways to control access to Db2 subsystems (Introduction to Db2 for z/OS)
Related reference:
DSNACICS stored procedure (Db2 SQL)

Running batch application programs

Batch Db2 work can run in the TSO background under the TSO terminal monitor
program (TMP) or in an IMS batch message processing (BMP) region. IMS batch
regions can issue SQL statements.

About this task

For batch work that runs in the TSO background, the input stream can invoke TSO
command processors, particularly the DSN command processor for Db2. This input
stream can include DSN subcommands, such as RUN.

Example

The following example shows a TMP job:

//jobname JOB USER=SYSOPR ...
//GO EXEC PGM=IKJEFT01,DYNAMNBR=20
.
user DD statements
.
//SYSTSPRT DD SYSOUT=A
//SYSTSIN DD *
DSN SYSTEM (ssid)
.
subcommand (for example, RUN)
.
END
/*

In this example:
v IKJEFT01 identifies an entry point for TSO TMP invocation. Alternative entry
points that are defined by TSO are also available to provide additional return
code and abend termination processing options. These options permit the user to
select the actions to be taken by the TMP on completion of command or
program execution.
Because invocation of the TSO TMP using the IKJEFT01 entry point might not be
suitable for all user environments, refer to the TSO publications to determine
which TMP entry point provides the termination processing options that are best
suited to your batch execution environment.
v USER=SYSOPR identifies the user ID (SYSOPR in this case) for authorization
checks.
v DYNAMNBR=20 indicates the maximum number of data sets (20 in this case)
that can be dynamically allocated concurrently.

246 Administration Guide

 v z/OS checkpoint and restart facilities do not support the execution of SQL
statements in batch programs that are invoked by the RUN subcommand. If
batch programs stop because of errors, Db2 backs out any changes that were
made since the last commit point.
v (ssid) is the subsystem name or group attachment name.
Related tasks:
Backing up and recovering your data
Related reference:
Executing the terminal monitor program (TSO/E Customization)
Writing JCL for command execution (TSO/E Customization)

Running application programs using CAF

The call attachment facility (CAF) allows you to customize and control execution
environments more extensively than the TSO, z/OS, or IMS attachment facilities.
Programs that run in TSO foreground or TSO background can use either the DSN
session or CAF. z/OS batch and started task programs can use only CAF.

About this task

IMS batch applications can also access Db2 databases through CAF, however, this
method does not coordinate the commitment of work between the IMS and Db2
subsystems. Using the Db2 DL/I batch support for IMS batch applications is
highly recommended.

Procedure

To use the CAF:

Either link-edit or make available a load module known as the call attachment
language interface, or DSNALI. Alternatively, you can link-edit with the Universal
Language Interface program (DSNULI).
When the language interface is available, your program can use CAF to connect to
Db2 in the following ways:
v DSNALI only: Implicitly, by including SQL statements or IFI calls in your
program just as you would any program.
v DSNALI or DSNULI: Explicitly, by writing CALL DSNALI or CALL DSNULI
statements.

Related concepts:
Call attachment facility (Db2 Application programming and SQL)

Running application programs using RRSAF

The Resource Recovery Services attachment facility (RRSAF) is a Db2 attachment
facility that relies on a z/OS component called Resource Recovery Services (z/OS
RRS). z/OS RRS provides system-wide services for coordinating two-phase commit
operations across z/OS subsystems.

Chapter 6. Submitting work to Db2 247

 Before you begin

Before you can run an RRSAF application, z/OS RRS must be started. RRS runs in
its own address space and can be started and stopped independently of Db2.

Procedure

To use RRSAF:

Either link-edit or make available a load module known as the RRSAF language
interface, or DSNRLI. Alternatively, you can link-edit with the Universal Language
Interface program (DSNULI).
When the language interface is available, your program can use RRSAF to connect
to Db2 in the following ways:
v DSNRLI only: Implicitly, by including SQL statements or IFI calls in your
program just as you would any program.
v DSNRLI or DSNULI: Explicitly, by using CALL DSNRLI or CALL DSNULI
statements to invoke RRSAF functions. Those functions establish a connection
between Db2 and RRS and allocate Db2 resources.

Related concepts:
Resource Recovery Services attachment facility (Db2 Application programming
and SQL)
Related tasks:
Controlling RRS connections

248 Administration Guide

Chapter 7. Scheduling administrative tasks
The administrative task scheduler runs tasks that are defined in a task list
according to a requested schedule. Tasks can be stored procedures or JCL jobs.

About this task

You manage the task list of the administrative task scheduler through Db2 stored
procedures that add and remove tasks. You can monitor the task list and the status
of executed tasks through user-defined functions that are provided as part of Db2.

Tasks run according to a defined schedule, which can be based on an interval, a

point in time, or an event. Activity can be further restricted by a limit on the
number of invocations or by earliest and latest invocation dates.

Interacting with the administrative task scheduler

The administrative task scheduler is based on scheduled tasks. Db2 users can add,
remove, and list scheduled tasks that are executed at planned points in time by the
administrative task scheduler.

About this task

At each point in time when the administrative task scheduler detects that a task
should be executed, it drives the task execution according to the work described in
the task definition. There is no user interaction. The administrative task scheduler
delegates the execution of the task to one of its execution threads, which executes
the stored procedure or the JCL job described in the work definition of the task.
The execution thread waits for the end of the execution and notifies the
administrative task scheduler. The administrative task scheduler stores the
execution status of the task in its redundant task lists, in relation with the task
itself.

Adding a task
Use the stored procedure ADMIN_TASK_ADD to define new scheduled tasks. The
parameters that you use when you call the stored procedure define the schedule
and the work for each task.

About this task

The request and the parameters are transmitted to the administrative task
scheduler that is associated with the Db2 subsystem where the stored procedure
has been called. The parameters are checked and if they are valid, the task is
added to the task lists with a unique task name. The task name and the return
code are returned to the stored procedure for output.

At the same time, the administrative task scheduler analyzes the task to schedule
its next execution.
Related reference:
ADMIN_TASK_ADD stored procedure (Db2 SQL)

© Copyright IBM Corp. 1982, 2017 249

 Scheduling capabilities of the administrative task scheduler
The administrative task scheduler can execute a task once or many times, at fixed
points in time, or in response to events.

Five parameters define the scheduling behavior of the task, in one of four ways:
v interval: elapsed time between regular executions
v point-in-time: specific times for execution
v trigger-task-name alone: specific task to trigger execution
v trigger-task-name with trigger-task-cond and trigger-task-code: specific task with
required result to trigger execution

Only one of these definitions can be specified for any single task. The other
parameters must be null.
Table 37. Relationship of null and non-null values for scheduling parameters
Parameter specified Required null parameters
interval point-in-time
trigger-task-name
trigger-task-cond
trigger-task-code
point-in-time interval
trigger-task-name
trigger-task-cond
trigger-task-code
trigger-task-name alone interval
point-in-time
trigger-task-cond
trigger-task-code
trigger-task-name with trigger-task-cond and interval
trigger-task-code point-in-time

If interval, point-in-time, trigger-task-name, trigger-task-cond, and trigger-task-code are

all null, max-invocations must be set to 1.

You can restrict scheduled executions either by defining a window of time during
which execution is permitted or by specifying how many times a task can execute.
Three parameters control restrictions:
v begin-timestamp: earliest permitted execution time
v end-timestamp: latest permitted execution time
v max-invocations: maximum number of executions

The begin-timestamp and end-timestamp parameters are timestamps that define a

window of time during which tasks can start. Before and after this window, the
task will not start even if the schedule parameters are met. If begin-timestamp is
null, the window begins at the time when the task is added, and executions can
start immediately. If end-timestamp is null, the window extends infinitely into the
future, so that repetitive or triggered executions are not limited by time.
Timestamps must either be null values or future times, and end-timestamp cannot
be earlier than begin-timestamp.

For repetitive or triggered tasks, the number of executions can be limited using the
max-invocations parameter. In this case, the task executes no more than the number
of times indicated by the parameter, even if the schedule and the window of time

250 Administration Guide

would require the task to be executed. Executions that are skipped because they
overlap with previous executions that are still running are not counted toward
max-invocations.

The max-invocations parameter defines a limit but no requirement. If the task is

executed fewer times than indicated during its execution window, the maximum
number of executions will never be reached.

Defining task schedules

You can use different combinations of parameters to define schedules for task
executions.

Procedure

To define a new scheduled task:

Connect to the Db2 subsystem with sufficient authorization to call the

ADMIN_TASK_ADD stored procedure. The following task definitions show some
common scheduling options.

To define Do this
A task that executes only one time: Set max-invocations to 1.

Optionally, provide a value for the

begin-timestamp parameter to control when
execution happens. Leave other parameters
null.

For example, if max-invocations is set to 1 and

begin-timestamp is set to 2008-05-27-06.30.0,
the task executes at 6:30 AM on May 27,
2008.

With this definition, the task executes one

time. If begin-timestamp has been provided,
execution happens as soon as permitted.
A regular repetitive execution: Set interval to the number of minutes that
you want to pass between the start of one
execution and the start of the next execution.

Optionally, provide values for the

max-invocations, begin-timestamp, and
end-timestamp parameters to limit execution.
Leave other parameters null.

For example, if interval is set to 5 and

begin-timestamp is set to 2008-05-27-06.30.0,
the task executes at 6:30 AM on May 27,
2008, then again at 6:35, 6:40, and so forth.

With this definition, the task executes every

interval minutes, so long as the previous
execution has finished. If the previous
execution is still in progress, the new
execution is postponed interval minutes.
Execution continues to be postponed until
the running task completes.

Chapter 7. Scheduling administrative tasks 251

 To define Do this
An irregular repetitive execution: Set point-in-time to a valid UNIX cron format
string. The string specifies a set of times.

Optionally, provide values for the

max-invocations, begin-timestamp and
end-timestamp parameters to limit execution.
Leave other parameters null.

For example, if point-in-time is set to 0 22 * *

1,5, the task executes at 10:00 PM each
Monday and Friday.

With this definition, the task executes at each

time specified, so long as the previous
execution has finished. If the previous
execution is still in progress, the new
execution is skipped. Subsequent executions
continue to be skipped until the running task
completes.
An execution that is triggered when another Set trigger-task-name to the name of the
task completes: triggering task. Optionally set
trigger-task-cond and trigger-task-code to limit
execution based on the result of the
triggering task. The trigger-task-cond and
trigger-task-code parameters must either both
be null or both be non-null.

Optionally, provide values for the

max-invocations, begin-timestamp and
end-timestamp parameters to limit execution.
Leave other parameters null.

For example, assume that a scheduled

INSERT job has a task name of test_task. If
trigger-task-name is test_task, trigger-task-cond
is EQ, and trigger-task-code is 0, then this task
executes when the INSERT job completes
with a return code of 0.

With this definition, the task executes at each

time specified, so long as the previous
execution has finished. If the previous
execution is still in progress, the new
execution is skipped. Subsequent executions
continue to be skipped until the running task
completes.

252 Administration Guide

To define Do this
An execution that is triggered when Db2 Set trigger-task-name to DB2START.
starts:
Optionally, provide values for the
max-invocations, begin-timestamp and
end-timestamp parameters to limit execution.
Leave other parameters null.

For example, if trigger-task-name is

DB2START, begin-timestamp is
2008-01-01-00.00.0, and end-timestamp is
2009-01-01-00.00.0, the task executes each
time that Db2 starts during 2008.

With this definition, the task executes at each

Db2 start, so long as the previous execution
has finished. If the previous execution is still
in progress, the new execution is skipped.
Subsequent executions continue to be
skipped until the running task completes.
An execution that is triggered when Db2 Set trigger-task-name to DB2STOP.
stops:
Optionally, provide values for the
max-invocations, begin-timestamp and
end-timestamp parameters to limit execution.
Leave other parameters null.

With this definition, the task executes at each

Db2 stop, so long as the previous execution
has finished. If the previous execution is still
in progress, the new execution is skipped.
Subsequent executions continue to be
skipped until the running task completes.

Choosing an administrative task scheduler in a data sharing

environment
In a data sharing group, tasks can be added, removed, or executed in any of the
administrative task schedulers with the same result. Tasks are not localized to one
administrative task scheduler. A task can be added by one administrative task
scheduler, and then executed by any of the administrative task schedulers that are
in the data sharing group.

Procedure

To force a task to be executed on a particular administrative task scheduler:

Specify the associated Db2 subsystem ID in the db2-ssid parameter when you
schedule the task.

UNIX cron format

The UNIX cron format is a way of specifying time for the point-in-time parameter
of the ADMIN_TASK_ADD stored procedure.

The cron format has five time and date fields separated by at least one blank.
There can be no blank within a field value. Scheduled tasks are executed when the
minute, hour, and month of year fields match the current time and date, and at
least one of the two day fields (day of month, or day of week) match the current
date.

Chapter 7. Scheduling administrative tasks 253

 The allowed values for the time and date fields are:
Field Allowed values
minute
0-59
hour 0-23
day of month
1-31
month
v 1-12, where 1 is January
v Upper-, lower-, or mixed-case three-character strings, based on the
English name of the month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct,
nov, or dec.
day of week
v 0-7, where 0 or 7 is Sunday
v Upper-, lower-, or mixed-case three-character strings, based on the
English name of the day: mon, tue, wed, thu, fri, sat, or sun.

Ranges and lists

Ranges of numbers are allowed. Ranges are two numbers separated with a
hyphen. The specified range is inclusive.

Example: The range 8-11 for an hour entry specifies execution at hours 8, 9, 10 and
11.

Lists are allowed. A list is a set of numbers or ranges separated by commas.

Examples:
1,2,5,9
0-4,8-12

Unrestricted range

A field can contain an asterisk (*), which represents all possible values in the field.

The day of a command's execution can be specified by two fields: day of month
and day of week. If both fields are restricted by the use of a value other than the
asterisk, the command will run when either field matches the current time.

Example: The value 30 4 1,15 * 5 causes a command to run at 4:30 AM on the 1st
and 15th of each month, plus every Friday.

Step values

Step values can be used in conjunction with ranges. The syntax range/step defines
the range and an execution interval.

If you specify first-last/step, execution takes place at first, then at all successive
values that are distant from first by step, until last.

Example: To specify command execution every other hour, use 0-23/2. This
expression is equivalent to the value 0,2,4,6,8,10,12,14,16,18,20,22.

254 Administration Guide

 If you specify */step, execution takes place at every interval of step through the
unrestricted range.

Example: As an alternative to 0-23/2 for execution every other hour, use */2.

Listing scheduled tasks

You can use the ADMIN_TASK_LIST function to list tasks that are scheduled for
execution by the administrative task scheduler.

Procedure

To list scheduled tasks:

Connect to the Db2 subsystem with sufficient authorization to call the function
ADMIN_TASK_LIST. The function contacts the administrative task scheduler to
update the Db2 task list in the table SYSIBM.ADMIN_TASKS, if necessary, and
then reads the tasks from the Db2 task list. The parameters that were used to
create the task are column values of the returned table. The table also includes the
authorization ID of the task creator, in the CREATOR column, and the time that
the task was created, in the LAST_MODIFIED column.
Related reference:
ADMIN_TASK_LIST (Db2 SQL)

Listing the status of scheduled tasks

You can use user-defined table functions to view the last execution status of
scheduled tasks, to list multiple execution statuses of scheduled tasks, and to
display the results of a stored procedure task. Scheduled tasks are defined in the
task list of an administrative task scheduler.

Listing the last execution status of scheduled tasks

You can use the ADMIN_TASK_STATUS() table function to view the last execution
status of scheduled tasks.

About this task

Before a task is first scheduled, all columns of its execution status contain null
values, as returned by the ADMIN_TASK_STATUS() table function. Afterwards, at
least the TASK_NAME, USERID, DB2_SSID, STATUS, NUM_INVOCATIONS and
START_TIMESTAMP columns contain non-null values. This information indicates
when and under which user ID the task status last changed and the number of
times this task was executed. You can interpret the rest of the execution status
according to the different values of the STATUS column.

The ADMIN_TASK_STATUS() table function contacts the administrative task

scheduler to update the Db2 task list in the SYSIBM.ADMIN_TASKS table, if
necessary, and reads the tasks from this task list directly.

Procedure

To determine the last execution status of a scheduled task:

1. Issue the ADMIN_TASK_STATUS() table function to generate the status table.
2. Select the rows in the table that correspond to the task name.

Chapter 7. Scheduling administrative tasks 255

 Tip: You can relate the task execution status to the task definition by joining
the output tables from the ADMIN_TASK_LIST and ADMIN_TASK_STATUS()
table functions on the TASK_NAME column.

Results

The table that is created by the ADMIN_TASK_STATUS() table function indicates

the last execution of scheduled tasks. Each row is indexed by the task name and
contains the last execution status of the corresponding task.

If task execution has never been attempted, because the execution criteria have not
been met, the STATUS column contains a null value.

If the administrative task scheduler was not able to start executing the task, the
STATUS column contains NOTRUN. The START_TIMESTAMP and
END_TIMESTAMP columns are the same, and the MSG column indicates why the
task execution could not be started. All JCL job execution status columns are
NULL, but the Db2 execution status columns contain values if the reason for the
failure is related to Db2. (For example, a Db2 connection could not be established.)

If the administrative task scheduler started executing the task but the task has not
yet completed, the STATUS column contains RUNNING. All other execution status
columns contain null values.

If the task execution has completed, the STATUS column contains COMPLETED.
The START_TIMESTAMP and END_TIMESTAMP columns contain the actual start
and end times. The MSG column might contain informational or error messages.
The Db2 and JCL columns are filled with values when they apply.

If the administrative task scheduler was stopped during the execution of a task,
the status remains RUNNING until the administrative task scheduler is restarted.
When the administrative task scheduler starts again, the status is changed to
UNKNOWN, because the administrative task scheduler cannot determine if the
task was completed.
Related tasks:
Listing multiple execution statuses of scheduled tasks
Related reference:
ADMIN_TASK_STATUS (Db2 SQL)

Listing multiple execution statuses of scheduled tasks

You can use the ADMIN_TASK_STATUS table function with the max-history
parameter to view multiple execution statuses of scheduled tasks.

About this task

The ADMIN_TASK_STATUS(MAX_HISTORY) table function returns a row of data

for the most recent executions of each task (up to the max-history value). This
function contacts the administrative task scheduler to update the Db2 task list in
the SYSIBM.ADMIN_TASKS table and the status history for the task in the
SYSIBM.ADMIN_TASKS_HIST table, if necessary, and reads the task statuses from
theses tables.

To prevent the SYSIBM.ADMIN_TASKS_HIST table from containing too many

status entries, the administrative task scheduler limits the number of status entries
per task that are stored. This limit is specified by the MAXHIST parameter. This

256 Administration Guide

parameter is a positive integer with a default value of 10. When the limit is
reached, the oldest status entries are deleted. You can specify this parameter in the
started task when the administrative task scheduler starts, or you can modify this
parameter dynamically by using the MODIFY console command.

Procedure

To list multiple execution statuses of scheduled tasks:

1. Issue the ADMIN_TASK_STATUS(MAX_HISTORY) table function to generate
the status table. The max-history parameter specifies the number of execution
statuses that you want to view.
2. Select the rows in the table that correspond to the task name.
To order the execution statuses, you can use the NUM_INVOCATIONS and
START_TIMESTAMP columns in the table that is returned.
If a task ran fewer times than the max-history value, this function returns all of
the execution statuses. If the SYSIBM.ADMIN_TASKS_HIST table is not
available, this function returns only the last five execution statuses for each
task. If a task has not run yet, a row of data is returned with all columns
containing null values, except that the TASK_NAME column contains the name
of the task.

Tip: You can relate the task execution status to the task definition by joining
the output tables from the ADMIN_TASK_LIST and
ADMIN_TASK_STATUS(MAX_HISTORY) table functions on the TASK_NAME
column.
Related tasks:
Listing the last execution status of scheduled tasks
Related reference:
ADMIN_TASK_STATUS (Db2 SQL)

Displaying the results of a stored procedure task

If the task that was executed is a stored procedure, you can use the
ADMIN_TASK_OUTPUT table function to display the output parameter values
and result sets.

Before you begin

To call this user-defined table function, you must have MONITOR1 privilege.

About this task

If the task that was executed is not a stored procedure, the

ADMIN_TASK_OUTPUT table function returns an empty table. Also, if the
SYSIBM.ADMIN_TASKS_HIST table is not accessible (for example, if the Db2
subsystem is down), the output of previous executions are not available to the
ADMIN_TASK_OUTPUT table function and an empty table is returned.

Procedure

To display the results of a stored procedure task:

Call the ADMIN_TASK_OUTPUT table function. This user-defined table function

returns up to one row for each output parameter of the stored procedure and up to
one row for each column value of each row of each result set of the stored

Chapter 7. Scheduling administrative tasks 257

 procedure. If the output values and the result set values are too large to be stored
in the OUTPUT column of the SYSIBM.ADMIN_TASKS_HIST table, only the last
rows of the result sets are returned. The column and parameter values are returned
as strings.
Related reference:
ADMIN_TASK_OUTPUT (Db2 SQL)

Updating the schedule for a task

You can modify the schedule of a task that is in the task list for the administrative
task scheduler.

Procedure

To update the schedule for a task:

Call the ADMIN_TASK_UPDATE stored procedure. If the task that you want to
update is running, the changes go into effect after the current execution finishes.
Related reference:
ADMIN_TASK_UPDATE stored procedure (Db2 SQL)

Stopping the execution of a task

You can attempt to stop the execution of a task that is currently running.

About this task

Not all tasks can be canceled as requested. Only the administrative task scheduler
that currently executes the task can cancel a JCL task or a stored procedure task.

Procedure

To stop a task that is currently running:

Issue the ADMIN_TASK_CANCEL stored procedure on the Db2 subsystem that is

specified in the DB2_SSID column of the task status. For a task that is running, the
stored procedure cancels the Db2 thread or the JES job that the task runs in, and
issues a return code of 0 (zero). If the task is not running or if cancellation of the
task cannot be initiated, the stored procedure issues a return code of 12.
Related reference:
ADMIN_TASK_CANCEL stored procedure (Db2 SQL)

Removing a scheduled task

You can remove a scheduled task from the task list by using the
ADMIN_TASK_REMOVE stored procedure.

About this task

Even if a task has finished all of its executions and will never be executed again, it
remains in the task list until it is explicitly removed through a call to the
ADMIN_TASK_REMOVE stored procedure .

Restrictions:

258 Administration Guide

 v Only the user who scheduled a task or a user with SYSOPR, SYSADM, or
SYSCTRL authority can delete a task.
v A task cannot be removed while it is executing.
v A task that is the trigger for another task cannot be removed.

Procedure

To remove a scheduled task:

1. Optional: Issue the following SQL statement to identify tasks that will never
execute again:
SELECT T.TASK_NAME
FROM TABLE (DSNADM.ADMIN_TASK_LIST()) T,
TABLE (DSNADM.ADMIN_TASK_STATUS()) S
WHERE T.TASK_NAME = S.TASK_NAME AND
(S.NUM_INVOCATIONS = T.MAX_INVOCATIONS OR
T.END_TIMESTAMP < CURRENT TIMESTAMP) AND
STATUS <> ’RUNNING’
2. Confirm the name of the task that you want to remove.
3. Call the ADMIN_TASK_REMOVE stored procedure. You must provide the task
name as a parameter to the stored procedure. The scheduled task is removed
from the task list and its last execution status is deleted. Listing the scheduled
tasks and execution statuses no longer returns a row for this task. The task
name is freed up for future reuse.
Related reference:
ADMIN_TASK_REMOVE stored procedure (Db2 SQL)

Manually starting the administrative task scheduler

The administrative task scheduler normally starts when Db2 starts, but you can
start it manually if necessary.

Procedure

Use one of the following commands to start the administrative task scheduler:
v To start an administrative task scheduler that is named admtproc from the
operator's console using the default tracing option, issue the MVS system
command:
start admtproc
v To start an administrative task scheduler that is named admtproc from the
operator's console with tracing enabled, issue the MVS system command:
start admtproc,trace=on
v To start an administrative task scheduler that is named admtproc from the
operator's console with tracing disabled, issue the MVS system command:
start admtproc,trace=off

Results

When the administrative task scheduler starts, message DSNA671I displays on the
console.

Manually stopping the administrative task scheduler

You can manually stop the administrative task scheduler. You might want to do
this when you are doing problem determination or in preparation for maintenance.

Chapter 7. Scheduling administrative tasks 259

 Procedure

To stop the administrative task scheduler:

v Recommended method: To stop an administrative task scheduler that is named
admtproc from the operator's console, issue the following MVS system command:
modify admtproc,appl=shutdown

You can expect the following results:

– The administrative task scheduler stops accepting requests and will not start
new task executions. It waits until the execution of all currently running tasks
completes and then terminates.
– Message DSNA670I displays on the console.
v Alternate method: If the MODIFY command does not shut down the
administrative task scheduler, issue the following MVS system command:
stop admtproc

You can expect the following results:

– Any task that was invoked by the administrative task scheduler and is
currently executing is interrupted.
– Message DSNA670I displays on the console.
Interrupted tasks keep their status as RUNNING and are not rescheduled until
the administrative task scheduler is started again. At startup, the status of the
interrupted tasks is set to UNKNOWN, and message DSNA690I is written into
the status. Look for UNKNOWN in the results of the ADMIN_TASK_STATUS
user-defined function. If UNKNOWN is present in the STATUS column of the
output table, check to see if the task has completed. If an interrupted task has
not completed, you must terminate the work.

Synchronization between administrative task schedulers in a

data sharing environment
The administrative task schedulers of a data sharing group synchronize themselves
through their task lists.

When a task is added, the ADMIN_TASK_ADD stored procedure is called by a

Db2 member. The administrative task scheduler that is associated with this Db2
member adds the task to the common task list. The task list is shared among all
administrative task schedulers that are associated with the data sharing group
members. The next time that an administrative task scheduler accesses the list, it
detects the new task.

All administrative task schedulers of the data sharing group access this task list
once per minute to check for new tasks. The administrative task scheduler that
adds a task does not have to check the list, and can execute the task immediately.
Any other administrative task scheduler can execute a task only after finding it in
the updated task list. Any administrative task scheduler can remove a task without
waiting.

To remove a task, the ADMIN_TASK_REMOVE stored procedure is called by a

Db2 member. The administrative task scheduler that is associated with this Db2
member removes the task from the common task list. The next time that an
administrative task scheduler checks the list, which is within one minute after the
task has been removed, it detects that the task was deleted.

260 Administration Guide

 An administrative task scheduler cannot execute a task without first locking it in
the task list. Locking a task prevents deleted tasks from being executed, because a
deleted task is no longer in the list and cannot be locked. If a task cannot be
locked, it cannot be executed. The locking also prevents double executions. A task
that one administrative task scheduler has in progress is already locked, so no
other administrative task scheduler can lock and execute the task.

Troubleshooting the administrative task scheduler

Error and informational messages from the administrative task scheduler are
displayed on the console.

Error messages typically indicate a problem with the configuration of the

administrative task scheduler, or an error accessing its resources. Informational
messages identify important steps in the life cycle of the administrative task
scheduler, such as starting, stopping, automatically recovering one of the task lists,
and so forth.

Enabling tracing for administrative task scheduler problem

determination
If you need to perform problem determination on the administrative task scheduler
in response to a message, you can use a trace.

About this task

Use the MVS system command MODIFY to enable or disable tracing. When tracing
is enabled, the trace goes to SYSOUT in the job output of the started task of the
administrative task scheduler. The trace output helps IBM Support to troubleshoot
problems.

Procedure

To enable tracing for problem determination:

v To start a trace for an administrative task scheduler that is named admtproc, issue
the following MVS system command:
modify admtproc,appl=trace=on
Substitute the name of your administrative task scheduler for admtproc.
v To stop a trace for an administrative task scheduler that is named admtproc, issue
the following MVS system command:
modify admtproc,appl=trace=off
v To configure the system so that tracing starts automatically when the
administrative task scheduler starts, modify the procedure parameter TRACE in
the JCL job that starts the administrative task scheduler. This job has the name
that was assigned when the administrative task scheduler was installed. The job
was copied into one of the PROCLIB library during the installation. Specify
TRACE=ON.
To disable tracing, change the parameter to TRACE=OFF.

Recovering the administrative task scheduler task list

Two redundant, active copies of the task list exist to protect your system in case
there is a media failure. Console message DSNA679I indicates that one of these
copies is not accessible. If this happens, you can recover the task list.

Chapter 7. Scheduling administrative tasks 261

 About this task

One copy of the task list is a shared VSAM data set, by default
DSNC910.TASKLIST, where DSNC910 is the Db2 catalog prefix. The other copy is
stored in the table ADMIN_TASKS in the SYSIBM schema. Include these redundant
copies as part of your backup and recovery plan.

Tip: If Db2 is offline, message DSNA679I displays on the console. As soon as Db2
starts, the administrative task scheduler performs an autonomic recovery of the
ADMIN_TASKS table using the contents of the VSAM task list. When the recovery
is complete, message DSNA695I displays on the console to indicate that both task
lists are again available. (By default, message DSNA679I displays on the console
once per minute. You can change the frequency of this message by modifying the
ERRFREQ parameter. You can modify this parameter as part of the started task or
with a console command.)

Procedure

To recover the task list if it is lost or damaged:

v To recover if the ADMIN_TASKS task list is corrupted:
1. Create a new and operable version of the table.
2. Grant SELECT, UPDATE, INSERT and DELETE privileges on the table to the
administrative task scheduler started task user.
As soon as the ADMIN_TASKS table is accessible again, the administrative task
scheduler performs an autonomic recovery of the table using the content of the
VSAM task list.
v To recover if the VSAM file is corrupted, create an empty version of the VSAM
task list. As soon as the VSAM task list is accessible again, the administrative
task scheduler performs an autonomic recovery using the content of the
ADMIN_TASKS task list.
v If both task lists (the VSAM data set and the ADMIN_TASKS table) are
corrupted and inaccessible, the administrative task scheduler is no longer
operable. Messages DSNA681I and DSNA683I display on the console and the
administrative task scheduler terminates. To recover from this situation:
1. Create an empty version of the VSAM task list.
2. Recover the table space DSNADMDB.DSNADMTS, where the
ADMIN_TASKS table is located.
3. Restart the administrative task scheduler.
As soon as both task lists are accessible again, the administrative task scheduler
performs an autonomic recovery of the VSAM task list using the content of the
recovered ADMIN_TASKS table.
Related tasks:
Installation step 22: Set up the administrative task scheduler (Db2 Installation
and Migration)

Problems executing a task

When the administrative task scheduler has problems executing a task, the error
description is written into the last execution status. The problem might be that the
task did not execute successfully, or the administrative task scheduler detected an
error at the end of task execution.

Symptoms

262 Administration Guide

A task was scheduled successfully, but the action did not complete or did not
complete correctly.

Diagnosing the problem

Use the function ADMIN_TASK_STATUS to review the last execution status of a
task and identify any messages or return codes that were passed back to the
administrative task scheduler.

Important: The task status is overwritten as soon as the next execution of the task
starts.

Resolving the problem

Correct the underlying problem and review the schedule. The task can now be
executed successfully, but execution occurs only according to the schedule. Failed
executions are not rescheduled. If the task is no longer scheduled, for example
because it had a defined number of executions, you must remove it and add it
again, with adjusted criteria. If the task is still scheduled, you do not need to take
any further action unless the failed execution is required. You cannot adjust a
schedule, so if you do require the failed execution and all future executions, you
must remove the scheduled task and re-create it.

Problems in user-defined table functions

An SQL code and a few characters of an SQL error message are returned in
response to either the ADMIN_TASK_LIST function or the ADMIN_TASK_STATUS
function.

Symptoms
An SQL code is returned. When SQLCODE is -443, the error message cannot be
read directly, because only a few characters are available.

Diagnosing the problem

Problem diagnosis and resolution depends on the SQLCODE returned.
-443 The SQLCODE of -443 indicates that an error occurred in the function. Use
the message number, which is at the beginning of the truncated return
string, to diagnose the problem.
Any other value
Any other SQLCODE indicates that the error is not in the function or in
the administrative task scheduler. Troubleshoot the task itself.

Problems in stored procedures

An SQL code and a few characters of an SQL error message are returned in
response to either the ADMIN_TASK_ADD stored procedure or the
ADMIN_TASK_REMOVE stored procedure.

Symptoms
An SQL code is returned.

Diagnosing the problem

An SQL code other than 0 indicates that Db2 encountered a problem calling the
stored procedure.

An SQL code of 0 is accompanied by a return code and an error message in the

output parameters RETURN_CODE and MSG. The return code is 0 if the
scheduled task could be added or removed successfully. If the return code is 12, an

Chapter 7. Scheduling administrative tasks 263

 error occurred adding or removing the task, and the returned error message
describes the cause. The first eight characters of the error message contain the error
message ID.

Resolving the problem

Errors can originate with the stored procedure itself or with the administrative task
scheduler, in which case the error information is transmitted back to the stored
procedure for output. Most error messages are clearly in one category or the other.
For example, DSNA650I csect-name CANNOT CONNECT TO ADMIN SCHEDULER proc-name
indicates an error from the stored procedure. DSNA652I csect-name THE USER
user-name IS NOT ALLOWED TO ACCESS TASK task-name belongs to the
administrative task scheduler, which is checking the parameters and authorization
information passed to it.

Understanding the source of the error should be enough to correct the cause of the
problem. Most problems are incorrect usage of the stored procedure or an invalid
configuration.

Correct the underlying problem and resubmit the call to the stored procedure to
add or remove the task.

Architecture of the administrative task scheduler

The administrative task scheduler is a started task that can be seen as an additional
Db2 address space, even if it is in a separate process. The administrative task
scheduler is accessed through an SQL API and stores the scheduled tasks in two
redundant task lists.

The administrative task scheduler is part of Db2 for z/OS. When properly
configured, it is available and operable with the first Db2 start. The administrative
task scheduler starts as a task on the z/OS system during Db2 startup. The
administrative task scheduler has its own address space, named after the started
task name.

Each Db2 subsystem has its own distinct administrative task scheduler connected
to it. Db2 is aware of the administrative task scheduler whose name is defined in
the subsystem parameter ADMTPROC. The administrative task scheduler is aware
of Db2 by the subsystem name that is defined in the DB2SSID parameter of the
started task.

The administrative task scheduler has an SQL interface consisting of stored

procedures (ADMIN_TASK_ADD and ADMIN_TASK_REMOVE) and user-defined
table functions (ADMIN_TASK_LIST and ADMIN_TASK_STATUS) defined in Db2.
This SQL interface allows you to remotely add or remove administrative tasks, and
to list those tasks and their execution status.

The administrative task scheduler executes the tasks according to their defined
schedules. The status of the last execution is stored in the task lists as well, and
you can access it through the SQL interface.

The following figure shows the architecture of the administrative task scheduler.

264 Administration Guide

 Address space name is
same as started task name

DB2AMSTR DB2AADMT

START START
DB2 for z/OS Started task
DB2AADMT
Scheduler
Subsystem parameter
DB2 association
ADMTPROC = DB2AADMT DB2SSID = DB2A
Call
SSID = DB2A

SQL SQL interface

( stored procedures and SQL
user-defined functions) External task list
ADMTDD1 = prefix.TASKLIST

VSAM task list

DB2 task list consistency ..........
SYSIBM.ADMIN_TASKS
..........

Figure 19. Architecture of the administrative task scheduler

Related reference:
ADMIN_TASK_ADD stored procedure (Db2 SQL)
ADMIN_TASK_REMOVE stored procedure (Db2 SQL)

The lifecycle of the administrative task scheduler

The administrative task scheduler starts as a task on the z/OS system during Db2
startup or initialization. The administrative task scheduler remains active unless it
is explicitly stopped, even when Db2 terminates.

Every Db2 subsystem has a coordinated administrative task scheduler address

space that it can start with a z/OS started task procedure.

Two instances of the same administrative task scheduler cannot run

simultaneously. To avoid starting up a duplicate administrative task scheduler, at
startup the administrative task scheduler checks that there is no address space
other than itself with the same name. If another address space with the same name
is active, then the new administrative task scheduler immediately shuts down and
displays a console message (DSNA674I). The administrative task scheduler can
check the address spaces only in the same system, not the entire Sysplex.

When Db2 terminates, the administrative task scheduler remains active so that
scheduled JCL jobs can run. When Db2 starts again, it connects to the

Chapter 7. Scheduling administrative tasks 265

 administrative task scheduler automatically. It does not need to be restarted.

Start

scheduler
Scheduler
with name in
ADMTPROC already Start
yes running? no

RRSAF
start event

Connect to DB2

Scheduler executes
Stop Scheduler executes
JCL jobs &
JCL jobs only
stored procedures

RRSAF
stop event

Disconnect from DB2

Figure 20. The lifecycle of the administrative task scheduler

If you want the administrative task scheduler to terminate when Db2 is stopped,
you can specify the STOPONDB2STOP parameter in the started task before
restarting the administrative task scheduler. This parameter has no value. You
specify this parameter by entering STOPONDB2STOP without an equal sign (=) or
a value. When you specify this parameter, the administrative task scheduler
terminates after it finishes executing the tasks that are running and after executing
the tasks that are triggered by Db2 stopping. When Db2 starts again, the
administrative task scheduler is restarted.

Important: When you use the STOPONDB2STOP parameter to stop the

administrative task scheduler when Db2 is stopped, JCL tasks will not run. These
JCL tasks will not run, even if they could have run successfully had an
administrative task scheduler remained active.
Related tasks:
Installation step 22: Set up the administrative task scheduler (Db2 Installation
and Migration)

266 Administration Guide

Task lists of the administrative task scheduler
The administrative task scheduler manages tasks that are defined by users and
stores them in two redundant task lists. As a result, the administrative task
scheduler can continue working even if one task list is unavailable.

The two task lists are the Db2 table SYSIBM.ADMIN_TASKS and the VSAM data
set that is indicated in the data definition ADMTDD1 of the started task of the
administrative task scheduler. The administrative task scheduler maintains the
consistency between the two task lists.

The Db2 task list SYSIBM.ADMIN_TASKS is accessed through a connection to the

Db2 subsystem that is identified in the DB2SSID parameter of the started task of
the administrative task scheduler.

The administrative task scheduler works and updates both task lists redundantly,
and remains operable so long as at least one of the task lists is available. Therefore,
the administrative task scheduler continues working when Db2 is offline. If a task
list becomes unavailable, the administrative task scheduler continues to update the
task list. When both task lists are available again, the administrative task scheduler
automatically synchronizes them.

The SYSIBM.ADMIN_TASKS_HIST table is a history table that stores the status

and execution output of the tasks that are in the SYSIBM.ADMIN_TASKS table.
The administrative task scheduler manages the SYSIBM.ADMIN_TASKS_HIST
table simultaneously to the task lists that are in the SYSIBM.ADMIN_TASKS table
and the VSAM data set.

If the SYSIBM.ADMIN_TASKS_HIST table is not accessible (for example, if the Db2

subsystem is down), the output of previous executions are not available to the
DSNADM.ADMIN_TASK_OUTPUT user-defined function. However, even if the
SYSIBM.ADMIN_TASKS_HIST table is not accessible, the last five execution
statuses are available to the DSNADM.ADMIN_TASK_STATUS user-defined
function. The status and output of previous executions are stored in the task list
until they can be copied to the SYSIBM.ADMIN_TASKS_HIST table.

To prevent the SYSIBM.ADMIN_TASKS_HIST table from containing too many

status entries, the administrative task scheduler limits the number of status entries
per task that are stored. This limit is specified by the MAXHIST parameter. This
parameter is a positive integer with a default value of 10. When the limit is
reached, the oldest status entries are deleted. You can specify this parameter in the
started task when the administrative task scheduler starts, or you can modify this
parameter dynamically by using the MODIFY console command.
Related tasks:
Installation step 22: Set up the administrative task scheduler (Db2 Installation
and Migration)

Architecture of the administrative task scheduler in a data

sharing environment
In a data sharing environment, each Db2 for z/OS Version 9.1 or later member of a
data sharing group is associated with its own administrative task scheduler. Each
member is associated with its own administrative task scheduler, even when those
members run in the same z/OS system. The administrative task schedulers share
their resources and interface.

Chapter 7. Scheduling administrative tasks 267

 The task list is shared by all administrative task schedulers in a data sharing
group, accessing a shared task file on shared storage (VSAM data set defaulting to
DSNC910.TASKLIST, where DSNC910 is the Db2 catalog prefix) and a redundant
task list in the Db2 system table SYSIBM.ADMIN_TASKS.

The following figure shows a data sharing group with two Db2 members and their
associated administrative task schedulers.

DB2AMSTR DB2BMSTR

SQL interface
DB2 for z/OS (stored procedures and
user-defined functions)
Subsystem parameter Subsystem parameter

ADMTPROC = DB2AADMT Coupling ADMTPROC = DB2BADMT

facility
SSID = DB2A SSID = DB2B

DB2 task list

SYSIBM.ADMIN_TASKS

DB2AADMT DB2BADMT

Started consistency Started

task task

DB2 association DB2 association

DB2SSID = DB2A DB2SSID = DB2B

Security Security
DFLTUID = ... VSAM task list DFLTUID = ...
..........
External task list .......... External task list
ADMTDD1 = prefix.TASKLIST ADMTDD1 = prefix.TASKLIST

Figure 21. Administrative task schedulers in a data sharing group

Tasks are not localized to a administrative task scheduler. They can be added,
removed, or executed in any of the administrative task schedulers in the data
sharing group with the same result. However, you can force the task to execute on
a given administrative task scheduler by specifying the associated Db2 subsystem
ID in the DB2SSID parameter when you schedule the task. The tasks that have no
affinity to a given Db2 subsystem are executed among all administrative task
schedulers. Their distribution cannot be predicted.

Accounting information for stored procedure tasks

When executing a stored procedure task, the administrative task scheduler passes
accounting information to the stored procedure task when establishing a Resource
Recovery Services attachment facility (RRSAF) connection to Db2.

When executing a stored procedure task, the administrative scheduler sets the
following information in these special registers:

268 Administration Guide

 v CURRENT CLIENT_USERID: The client user ID is set to the name of the
execution user.
v CURRENT CLIENT_APPLNAME: The client application name is set to the name
of the administrative task scheduler.
v CURRENT CLIENT_ACCTNG: The DDF accounting string is set to the task
name.

This information enables the stored procedure to relate its own outputs to the task
execution status in the administrative task scheduler. For example, the stored
procedure can save a log in a table together with the name of the task that
executed it, so that you can relate the task execution status to this log.

Security guidelines for the administrative task scheduler

The administrative task scheduler uses controls on access and execution to help
maintain a secure environment.

Installation job DSNTIJRA is responsible for establishing the security environment

for the administrative task scheduler. Installation job DSNTIJRT is responsible for
establishing the security environment in Db2 for accessing the administrative task
scheduler interface.

The following figure shows all of the security checkpoints that are associated with
using the administrative task scheduler.

Chapter 7. Scheduling administrative tasks 269

 JES reader
Execute JCL

SQL Call DB2AADMT

DFLTUID XXX
DB2AMSTR
Task 1 Task 2

SQL call Execution Execution

stored procedures thread thread 3 Get PassTicket
and log in
DB2 for z/OS
Interface RACF
Add TASK 1
USERID = NULL PassTickets
Stored procedures
Call PASSWORD = NULL
ADMIN_TASK_ADD() scheduler
Add TASK 2 Users
1 Check USERID = XXX
PASSWORD = *** 2 Check XXX DFLTUID
access rights
credentials

Passwords
Task lists access
granted users

VSAM task list

DB2 task list Task 1
SYSIBM.ADMIN_TASKS consistency USERID = NULL
Task 2
USERID = XXX

Figure 22. Security checkpoints for the administrative task scheduler

Related tasks:
Installation step 20: Set up Db2-supplied routines (Db2 Installation and
Migration)
Migration step 23: Set up Db2-supplied routines (Db2 Installation and
Migration)
Installation step 22: Set up the administrative task scheduler (Db2 Installation
and Migration)
Related reference:
z/OS UNIX System Services Planning

User roles in the administrative task scheduler

Three user roles are involved in the use of the administrative task scheduler: the
started task user, the interface users, and the execution users.

The started task of an administrative task scheduler is associated to the STARTUID

user in RACF. The administrative task scheduler runs in the security context of this
user. This user, the started task user, should have access to the resources of the
administrative task scheduler. This user needs UPDATE access on the Db2 table
SYSIBM.ADMIN_TASKS and write access for the VSAM data set that contains the
redundant task list.

270 Administration Guide

 The users or groups of users who have access to the SQL interface of the
administrative task scheduler are allowed to add, remove, or list scheduled tasks.
To specify who is authorized to add, remove, or list a scheduled task, use the
GRANT command in Db2. All interface users are granted EXECUTE access on the
administrative task scheduler stored procedures and user-defined table functions.
They also are granted READ access on the SYSIBM.ADMIN_TASKS table.

Each scheduled task in the administrative task scheduler is associated with an

execution user who executes the task. When an execution user is not explicitly
defined, the administrative task scheduler uses a default execution user, DFLTUID,
| that is defined in the started task. DFLTUID must be an ID that can be used as a
| logon ID and has a password. DFLTUID cannot be a group ID. The execution
threads of the administrative task scheduler switch to the security context of the
execution user before executing a task.

Protection of the interface of the administrative task scheduler

The administrative task scheduler interface is protected against unauthorized
access by other users. Credentials of a task are checked but not stored.

Users with EXECUTE rights on one of the stored procedures or user-defined table
functions of the administrative task scheduler interface are allowed to execute the
corresponding functionality: adding a scheduled task, removing a scheduled task,
or listing the scheduled tasks or their execution status. The entire interface is
configured by default with PUBLIC access rights during the installation.

Recommendations:
v Grant rights to groups or roles, rather than to individual authorization IDs.
v Restrict access to the ADMIN_TASK_ADD and ADMIN_TASK_REMOVE stored
procedures to users with a business need for their use. Access to the
user-defined table functions that list tasks and execution status can remain
unrestricted.

The authorization ID of the Db2 thread that called the stored procedure
ADMIN_TASK_ADD is passed to the administrative task scheduler and stored in
the task list with the task definition. The ADMIN_TASK_ADD stored procedure
gathers the authorities granted to this authorization ID from the subsystem
parameters and from the catalog table, and passes them over to the administrative
task scheduler. The same mechanism is used in ADMIN_TASK_REMOVE to verify
that the user is permitted to remove the task.

A task in the task list of the administrative task scheduler can be removed by the
owner of the task, or by any user that has SYSOPR, SYSCTRL, or SYSADM
privileges. The owner of a task is the CURRENT SQLID of the process at the time
the task was added to the task list.

Protection of the resources of the administrative task

scheduler
The task lists of the administrative task scheduler are protected against
unauthorized use by users other than the started task execution user.

The VSAM resource (by default DSNCAT.TASKLIST, where DSNCAT is the Db2
catalog prefix) that stores the task list of the administrative task scheduler must be

Chapter 7. Scheduling administrative tasks 271

 protected in RACF against unauthorized access. Only the started task user has
UPDATE authority on the VSAM resources. No other users should have any
access.

A similar security concept is implemented for the SYSIBM.ADMIN_TASKS table,

which stores a redundant copy of the scheduled tasks. Only the started tasks user
has SELECT, INSERT, DELETE, or UPDATE authority on this resource. Users with
EXECUTE rights on the ADMIN_TASK_LIST and ADMIN_TASK_STATUS
user-defined functions have only SELECT authority on the
SYSIBM.ADMIN_TASKS table.

Secure execution of tasks in the administrative task scheduler

The execution threads of the administrative task scheduler always switch to the
security context of the execution user before executing a task. The user is
authenticated through the use of PassTickets.

The first action that is taken by the administrative task scheduler when starting
task execution is to switch its security context to the context of the execution user.
The execution user can be explicitly identified by the user-ID parameter of the
ADMIN_TASK_ADD stored procedure, or can be the default user.

If the task is a stored procedure, and the stored procedure must be executed in
Db2 with the privileges and rights of the secondary authentication IDs of the
execution user, make sure that Db2 was started with a sign-on exit routine.

If the task must run under a certain authority, including an authority that is
different from the caller of the stored procedure, credentials are passed on to the
administrative task scheduler. These credentials are not stored anywhere. They are
validated by RACF to ensure that the caller of the stored procedure at the task
definition time has the right to assume the security context. Therefore, you can use
a PassTicket (encrypted single-use password) in the password parameter of the
ADMIN_TASK_ADD stored procedure. If no credentials are provided, then the
administrative task scheduler executes the tasks under its default execution user.

The administrative task scheduler generates and uses PassTickets for executing the
tasks under the corresponding authority. Each task executes after switching to the
requested security context using the user ID and the generated PassTicket.

No password is stored in the administrative task scheduler, but the administrative

task scheduler is defined as a trusted program in RACF, and is allowed to get
PassTickets for any user. The administrative task scheduler sub-thread requires a
PassTicket from RACF and logs in using this single-use password. The execution of
the task then occurs in the switched security concept, allowing the task to have
access to the resources defined for this execution user. After the execution, the
security context is switched back to the scheduled task user.

| The started task module (DSNADMT0) of the administrative task scheduler uses
| the pthread_security_np() function to switch users. To set a thread-level security
| environment for the scheduler, follow the steps in Additional steps for enabling the
| administrative task scheduler and administrative enablement routines (Db2
| Installation and Migration).

The administrative task scheduler resources should be protected from unintended

impact when executing a task. Therefore, the started task user (STARTUID), which
has access to the administrative task scheduler resources, must not be used as the

272 Administration Guide

 default execution user (DFLTUID). Also, it should not be specified in the user-ID
parameter of the ADMIN_TASK_ADD stored procedure. The administrative task
scheduler will not start if the started task user and the default execution user are
identical. The default execution user should have as few rights as possible to avoid
impacting any resources if no user is defined for a task.

The default execution user has no authority, except to attach to Db2 and write to
the JES reader.
Related reference:
Processing of sign-on requests (Managing Security)

Execution of scheduled tasks in the administrative task scheduler

The administrative task scheduler manages the point in time, the security, the
input parameters, and the status of task execution.

The work of the administrative task scheduler is based on scheduled tasks that you
define. Each task is associated with a unique task name. Up to 9999 tasks are
supported in the administrative task scheduler at one time.

A scheduled task consists of a schedule and a work definition. The schedule tells
the administrative task scheduler when to execute the task. You define a window
of time during which execution is permitted, and either a time-based or
event-based schedule that triggers the execution of the job during this window.
The work definition specifies what to execute, either a JCL job or a stored
procedure, and the authority (user) under which to execute the task.

Multi-threading in the administrative task scheduler

The administrative task scheduler uses a pool of execution threads that allow it to
execute many tasks simultaneously.

The administrative task scheduler is multi-threaded. The administrative task

scheduler starts the execution of scheduled tasks, and waits for the tasks to
complete. The execution of a task is delegated by the administrative task scheduler
to one of its sub-threads that starts the execution, waits until the execution
completes, and gathers the execution status. Each sub-thread can be used for any
type of task.

The maximum number of sub-threads is determined by the MAXTHD parameter

of the started task, which by default is 99. Therefore, the administrative task
scheduler can execute up to 99 tasks simultaneously. To reduce the memory usage
of the administrative task scheduler, reduce the number of sub-threads by
specifying a lower value for the MAXTHD parameter. You specify this parameter
in the JCL of the started task. The JCL has the same name as the administrative
task scheduler, as defined in job DSNTIJMV.

Chapter 7. Scheduling administrative tasks 273

 MAXTHD
-Parameter of the started task.
-Control maximum number
JES reader of execution threads.
-Default value is 99.
Execute JCL

DB2AMSTR

SQL call Execution Execution Execution

DB2 for z/OS stored procedures thread thread thread

Stored procedures
SQL call ADMIN_TASK_ADD() Interface
Call
ADMIN_TASK_REMOVE() Add Task

Call
User-defined functions Remove Task name
scheduler
SQL
ADMIN_TASK_LIST()
select from Call
Refresh task lists
ADMIN_TASK_STATUS()

Task lists access

DB2 task list VSAM task list

consistency ..........
SYSIBM.ADMIN_TASKS
..........

Figure 23. Multi-threading in the administrative task scheduler

The minimum permitted value for the MAXTHD parameter is 1, but this value
should not be lower than the maximum number of tasks that you expect to execute
simultaneously. If there are more tasks to be executed simultaneously than there
are available sub-threads, some tasks will not start executing immediately. The
administrative task scheduler tries to find an available sub-thread within one
minute of when the task is scheduled for execution. As a result, multiple short
tasks might be serialized in the same sub-thread, provided that their total
execution time does not go over this minute.

The parameters of the started task are not positional. Place parameters in a single
string separated by blank spaces.

If the execution of a task still cannot start one minute after it should have started,
the execution is skipped, and the last execution status of this task is set to the
NOTRUN state. The following message displays on the operator's console.
DSNA678I csect-name THE NUMBER OF TASKS TO BE CONCURRENTLY
EXECUTED BY THE ADMIN SCHEDULER proc-name EXCEEDS max-threads

If you receive this message, increase the MAXTHD parameter value and restart the
administrative task scheduler.
Related tasks:
Installation step 22: Set up the administrative task scheduler (Db2 Installation
and Migration)

274 Administration Guide

 Related information:
DSNA677I (Db2 Messages)
DSNA678I (Db2 Messages)

Scheduling execution of a stored procedure

You can schedule a stored procedure to run at a particular time, at an interval, or
when a specified event occurs. The administrative task scheduler manages these
requests.

Procedure

To schedule execution of a stored procedure:

1. Add a task for the administrative task scheduler by using the
ADMIN_TASK_ADD stored procedure. When you add your task, specify which
stored procedure to run and when to run it. Use one of the following
parameters or groups of parameters of ADMIN_TASK_ADD to control when
the stored procedure is run:

Option Description
interval The stored procedure is to execute at the
specified regular interval.
point-in-time The stored procedure is to execute at the
specified times.
trigger-task-name The stored procedure is to execute when the
specified task occurs.
trigger-task-name trigger-task-cond The stored procedure is to execute when the
trigger-task-code specified task and task result occur.

Optionally, you can also use one or more of the following parameters to control
when the stored procedure runs:
begin-timestamp
Earliest permitted execution time
end-timestamp
Latest permitted execution time
max-invocations
Maximum number of executions

When the specified time or event occurs for the stored procedure to run, the
administrative task scheduler calls the stored procedure in Db2.
2. Optional: After the task finishes execution, check the status by using the
ADMIN_TASK_STATUS function. This function returns a table with one row
that indicates the last execution status for each scheduled task. If the scheduled
task is a stored procedure, the JOB_ID, MAXRC, COMPLETION_TYPE,
SYSTEM_ABENDCD, and USER_ABENDCD fields contain null values. In the
case of a Db2 error, the SQLCODE, SQLSTATE, SQLERRMC, and SQLERRP
fields contain the information that Db2 returned from calling the stored
procedure.
Related tasks:
Adding a task
Related reference:

Chapter 7. Scheduling administrative tasks 275

 ADMIN_TASK_ADD stored procedure (Db2 SQL)
ADMIN_TASK_STATUS (Db2 SQL)
Related information:

How the administrative task scheduler executes a stored

procedure
You can use the administrative task scheduler to execute stored procedures at a
specific time. You must first define a task for the stored procedure execution. Then,
when the specified time or event occurs for the stored procedure to run, the
administrative task scheduler calls the stored procedure.

Specifically, the administrative task scheduler performs the following actions:

1. The administrative task scheduler connects to the Db2 member that is specified
in the task parameter DB2SSID. If the administrative task scheduler cannot
establish a connection, it skips execution of the stored procedure and sets the
last execution status to the NOTRUN state.
2. The administrative task scheduler retrieves parameter values for the stored
procedure from Db2 by using the SELECT statement that is defined in the task
parameter procedure-input. If an error occurs when the administrative task
scheduler retrieves those parameter values, the administrative task scheduler:
v Does not call the stored procedure.
v Sets the last execution status of the task to the error code that is returned by
Db2.
3. The administrative task scheduler issues an SQL CALL statement with the
retrieved parameter values and a stored procedure name. The procedure name
is concatenated from the task parameters procedure-schema and procedure-name.
The SQL CALL statement is synchronous, and the execution thread is blocked
until the stored procedure finishes execution. The administrative task scheduler
sets the last execution status to the values that are returned by Db2.
4. The administrative task scheduler issues a COMMIT statement.
5. The administrative task scheduler closes the connection to Db2.

How the administrative task scheduler works with Unicode

The administrative task scheduler can retrieve and pass Unicode parameters to a
Db2 stored procedure.

If the stored procedure accepts Unicode parameters, or if it does not accept

Unicode parameters but the retrieved parameter values do not contain any special
character that cannot be expressed in EBCDIC or ASCII, no character will be
broken.

However, the Unicode values must be retrieved through a select statement

expressed in EBCDIC, so that special characters cannot be used in the table names
or in the column names where the parameter values are retrieved.

Scheduled execution of a JCL job

The administrative task scheduler sends the JCL job to the JES reader. The
execution sub-thread of the administrative task scheduler can optionally wait for
the job to terminate and purge the job from the JES job list.

276 Administration Guide

 One execution sub-thread of the administrative task scheduler is used to execute a
task that locates a data set containing a JCL job. The sub-thread reads the JCL job
from the data set where it is stored, identified by the task parameters JCL-library
and JCL-member. The data set can be sequential or partitioned. For a sequential
data set, JCL-member is NULL.

In the case of an error, the error is written into the last execution status of the task.
Otherwise, the job is submitted to the internal JES reader. According to the job_wait
parameter, the sub-thread waits for the execution completion or not. When the
sub-thread waits for completion, the last execution status includes the complete
returned values provided by the JES reader. Otherwise, it contains the JCL job ID
and a success message.
v If job_wait is set to NO, the sub-thread does not wait until the job completes
execution and returns immediately after the job submission. The task execution
status is set to the submission status, the result of the job execution itself will
not be available.
v If job_wait is set to YES, the sub-thread simulates a synchronous execution of the
JCL job. It waits until the job execution completes, get the job status from the JES
reader and fills in the last execution status of the task.
v If job_wait is set toPURGE, the sub-thread purges the job output from the JES
reader after execution. Execution is the same as for job_wait=YES.

JCL job execution status always contains a null value in the SQLCODE, SQLSTATE,
SQLERRMC, and SQLERRP fields. If the job can be submitted successfully to the
JES reader, the field JOB_ID contains the ID of the job in the JES reader. If the job
is executed asynchronously, the MAXRC, COMPLETION_TYPE,
SYSTEM_ABENDCD and USER_ABENDCD fields will also be null values, because
the sub-thread does not wait for job completion before writing the status. If the job
was executed synchronously, those fields contain the values returned by the JES
reader.

Execution of scheduled tasks in a data sharing environment

In a data sharing environment, all administrative task schedulers cooperate in the
execution of scheduled tasks.

However, if a task has a member affinity (for example, if the db2-ssid parameter
specifies the name of a Db2 member), only the administrative task scheduler that is
associated with that Db2 member will execute the task. Therefore, if this
administrative task scheduler is unavailable, the task will not be executed.

When a task has no member affinity (if the db2-ssid parameter is a null value), the
first administrative task scheduler that is available executes the task. If the task
execution can complete on this administrative task scheduler, other administrative
task schedulers will not try executing this task. However, if the administrative task
scheduler cannot start the execution, other administrative task schedulers will try
to start executing the task until one succeeds, or all fail in executing the task. An
administrative task scheduler is unavailable if its associated Db2 member is not
running, or if all of its execution threads are busy.

You cannot predict which administrative task scheduler will execute a task.
Successive executions of the same task can be done on different administrative task
schedulers.

Chapter 7. Scheduling administrative tasks 277

 Time zone considerations for the administrative task
scheduler
The administrative task scheduler is configured to work in a given time zone.

By default, the administrative task scheduler works in the time zone that is defined
for the z/OS operating system as the local time, provided that the z/OS
environment variable TZ is not set. If the TZ environment variable is set, the
administrative task scheduler works in the time zone that is defined for this
variable. You can set the TZ environment variable either in the z/OS Language
Environment® default settings, or in the CEEOPTS definition of the started task of
the administrative task scheduler.

When you add a task, you must specify the values for the begin-timestamp,
end-timestamp, and point-in-time parameters of the stored procedure in the time
zone that the administrative task scheduler works in. When listing scheduled tasks,
the BEGIN_TIMESTAMP, END_TIMESTAMP, and POINT_IN_TIME columns are
returned with values that are in time zone for the administrative task scheduler.
Likewise, when listing the status of a task, the LAST_MODIFIED,
START_TIMESTAMP, and END_TIMESTAMP columns are returned with values
that are in time zone for the administrative task scheduler.

Important: You must configure all of the administrative task schedulers for a data
sharing environment in the same time zone. Otherwise, the scheduled tasks might
run at a time when they are not intended to execute.

The following example shows how to set the time zone for Germany.
//CEEOPTS DD *
ENVAR("TZ=MEZ-1MESZ,M3.5.0,M10.5.0")
Related tasks:
Using the CEEOPTS DD statement (z/OS Language Environment
Customization)
Related reference:
ENVAR (z/OS Language Environment Customization)

278 Administration Guide

Chapter 8. Monitoring and controlling Db2 and its
connections
You can control and monitor various aspects of a Db2 for z/OS environment.
These operations require you to have more of an understanding of what Db2 is
doing.
Related tasks:
Controlling Db2 operations by using commands
Monitoring and analyzing Db2 performance data (Db2 Performance)
Controlling resource usage (Db2 Performance)
Setting limits for system resource usage by using the resource limit facility
(Db2 Performance)
Monitoring threads and connections by using profiles (Db2 Performance)
Updating subsystem parameter and application default values (Db2
Installation and Migration)

Controlling Db2 databases and buffer pools

You can use various commands to control Db2 databases and buffer pools. The
commands that you issue depend on the type of action that you want to take.

Procedure

To control databases and buffer pools:

Issue the START DATABASE, STOP DATABASE, or DISPLAY DATABASE

commands.
START DATABASE
Makes a database or individual partitions available. Also removes pages
from the logical page list (LPL).
DISPLAY DATABASE
Displays status, user, and locking information for a database.
STOP DATABASE
Makes a database or individual partitions unavailable after existing users
have quiesced. Db2 also closes and deallocates the data sets.

Related tasks:
Monitoring databases
Starting databases
Making objects unavailable
Related reference:

© Copyright IBM Corp. 1982, 2017 279

 -START DATABASE (Db2) (Db2 Commands)
-DISPLAY DATABASE (Db2) (Db2 Commands)
-STOP DATABASE (Db2) (Db2 Commands)

Starting databases
Issue the START DATABASE (*) command to start all databases for which you
have the STARTDB privilege.

About this task

The privilege can be explicitly granted, or it can belong implicitly to a level of
authority (DBMAINT and above). The command starts the database, but not
necessarily all the objects that it contains. Any table spaces or index spaces in a
restricted mode remain in a restricted mode and are not started.

The START DATABASE (*) command does not start the Db2 directory (DSNDB01),
the Db2 catalog (DSNDB06), or the Db2 work file database (called DSNDB07,
except in a data sharing environment). Start these databases explicitly by using the
SPACENAM option. Also, the START DATABASE (*) command does not start table
spaces or index spaces that have been explicitly stopped by the STOP DATABASE
command.

Use the PART keyword of the START DATABASE command to start the individual
partitions of a table space. It can also be used to start individual partitions of a
partitioning index or logical partitions of a nonpartitioning index. The started or
stopped state of other partitions is unchanged.

The START DATABASE and STOP DATABASE commands can be used with the
SPACENAM and PART options to control table spaces, index spaces, or partitions.

Example

For example, the following command starts two partitions of table space
DSN8S11E in the database DSN8D11A:
-START DATABASE (DSN8D11A) SPACENAM (DSN8S11E) PART (1,2)

Related reference:
-START DATABASE (Db2) (Db2 Commands)
-STOP DATABASE (Db2) (Db2 Commands)

Starting an object with a specific status

You can start a database, table space, or an index space with a specific status that
limits access to the object.

About this task

Objects can have the following status:

280 Administration Guide

Status Provides this access
RW Read-write. This is the default value.
RO Read-only. You cannot change the data.
UT Utility-only. The object is available only to the Db2 utilities.
RREPL
Read-or-replication-only. The object is available as read-only unless the
program is identified as a replication program.

Databases, table spaces, and index spaces are started with RW status when they
are created. You can make any of them unavailable by using the STOP DATABASE
command. Db2 can also make them unavailable when it detects an error.

Procedure

To start objects that have a specific status:

In cases when the object was explicitly stopped, you can make it available again by
issuing the START DATABASE command.

Example

For example, the following command starts all table spaces and index spaces in
database DSN8D11A for read-only access:
-START DATABASE (DSN8D11A) SPACENAM(*) ACCESS(RO)

The system responds with this message:

DSN9022I - DSNTDDIS ’-START DATABASE’ NORMAL COMPLETION

Related reference:
-START DATABASE (Db2) (Db2 Commands)
-STOP DATABASE (Db2) (Db2 Commands)
Related information:
DSN9022I (Db2 Messages)

Starting a table space or index space that has restrictions

Db2 can make an object unavailable for a variety of reasons. Typically, in those
cases, the data is unreliable, and the object needs some attention before it can be
started.

About this task

An example of such a restriction is when the table space is placed in

COPY-pending status. That status makes a table space or partition unavailable
until an image copy of the object is taken.

Important: These restrictions are a necessary part of protecting the integrity of the
data. If you start an object that has restrictions, the data in the object might not be
reliable.

Chapter 8. Monitoring and controlling Db2 and its connections 281

 However, in certain circumstances, it might be reasonable to force availability. For
example, a table might contain test data whose consistency is not critical.

Procedure

To start an object that has restrictions:

Issue the START DATABASE command with the ACCESS(FORCE) option.

This command releases most restrictions for the named objects. These objects must
be explicitly named in a list following the SPACENAM option.

Example

For example:
-START DATABASE (DSN8D11A) SPACENAM (DSN8S11E) ACCESS(FORCE)

Db2 cannot process the START DATABASE ACCESS(FORCE) request if

postponed-abort or indoubt units of recovery exist. The RESTP (restart-pending)
status and the AREST (advisory restart-pending) status remain in effect until either
automatic backout processing completes or you perform one of the following
actions:
v Issue the RECOVER POSTPONED command to complete backout activity.
v Issue the RECOVER POSTPONED CANCEL command to cancel all of the
postponed-abort units of recovery.
v Conditionally restart or cold start Db2.

Db2 cannot apply the START DATABASE ACCESS(FORCE) command to that

object if a utility from a previous release of Db2 places an object in one of the
following restrictive states:
v UTRO (utility restrictive state, read-only access allowed)
v UTRW (utility restrictive state, read and write access allowed)
v UTUT (utility restrictive state, utility exclusive control)

To reset these restrictive states, you must start the release of Db2 that originally ran
the utility and terminate the utility from that release.

Related tasks:
Resolving postponed units of recovery
Related reference:
-START DATABASE (Db2) (Db2 Commands)

Monitoring databases
You can use the DISPLAY DATABASE command to obtain information about the
status of databases and the table spaces and index spaces within each database. If
applicable, the output also includes information about physical I/O errors for
those objects.

282 Administration Guide

Procedure

To monitor databases:
1. Issue the DISPLAY DATABASE command as follows:
-DISPLAY DATABASE (dbname)

This command results in the following messages:

11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT361I - * DISPLAY DATABASE SUMMARY
11:44:32 * report_type_list
11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT362I - DATABASE = dbname STATUS = xx
DBD LENGTH = yyyy
11:44:32 DSNT397I -
NAME TYPE PART STATUS PHYERRLO PHYERRHI CATALOG PIECE
-------- ---- ----- --------------- --------- -------- -------- -----

D1 TS RW,UTRO
D2 TS RW
D3 TS STOP
D4 IX RO
D5 IX STOP
D6 IX UT
LOB1 LS RW
******* DISPLAY OF DATABASE dbname ENDED **********************
11:45:15 DSN9022I - DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION
In the preceding messages:
v report_type_list indicates which options were included when the DISPLAY
DATABASE command was issued.
v dbname is an 8-byte character string that indicates the database name. The
pattern-matching character, *, is allowed at the beginning, middle, and end of
dbname.
v STATUS is a combination of one or more status codes, delimited by commas.
The maximum length of the string is 17 characters. If the status exceeds 17
characters, those characters are wrapped onto the next status line. Anything
that exceeds 17 characters on the second status line is truncated.
2. Optional: Use the pattern-matching character, *, in the DISPLAY DATABASE,
START DATABASE, and STOP DATABASE commands. You can use the
pattern-matching character in the beginning, middle, and end of the database
and table space names.
3. Use additional keywords to tailor the DISPLAY DATABASE command so that
you can monitor what you want:
v The keyword ONLY can be added to the command DISPLAY DATABASE.
When ONLY is specified with the DATABASE keyword but not the
SPACENAM keyword, all other keywords except RESTRICT, LIMIT, and
AFTER are ignored. Use DISPLAY DATABASE ONLY as follows:
-DISPLAY DATABASE(*S*DB*) ONLY
This command results in the following messages:
11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT361I - * DISPLAY DATABASE SUMMARY
11:44:32 * GLOBAL
11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT362I - DATABASE = DSNDB01 STATUS = RW
DBD LENGTH = 8066
11:44:32 DSNT360I - ****************************************************

Chapter 8. Monitoring and controlling Db2 and its connections 283

 11:44:32 DSNT362I - DATABASE = DSNDB04 STATUS = RW
DBD LENGTH = 21294
11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT362I - DATABASE = DSNDB06 STATUS = RW
DBD LENGTH = 32985
11:45:15 DSN9022I - DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION
In the preceding messages:
– DATABASE (*S*DB*) displays databases that begin with any letter, have
the letter S followed by any letters, and then the letters DB followed by
any letters.
– ONLY restricts the display to databases names that fit the criteria.
v The RESTRICT option of the DISPLAY DATABASE command limits the
display to objects that are currently set to a restrictive status. You can
additionally specify one or more keywords to limit the display further to
include only objects that are set to a particular restrictive status.
v The ADVISORY option on the DISPLAY DATABASE command limits the
display to table spaces or indexes that require some corrective action. Use the
DISPLAY DATABASE ADVISORY command without the RESTRICT option
to determine when:
– An index space is in the informational COPY-pending (ICOPY) advisory
status.
– A base table space is in the auxiliary-warning (AUXW) advisory status.
v The OVERVIEW option of the DISPLAY DATABASE command displays all
objects within a database. This option shows each object in the database on
one line, does not isolate an object by partition, and does not show exception
states. The OVERVIEW option displays only object types and the number of
data set partitions in each object. OVERVIEW is mutually exclusive with all
keywords other than SPACENAM, LIMIT, and AFTER. Use DISPLAY
DATABASE OVERVIEW as follows:
-DISPLAY DATABASE(DB486A) SPACENAM(*) OVERVIEW
This command results in the following messages:
DSNT360I = ****************************************
DSNT361I = * DISPLAY DATABASE SUMMARY 483
* GLOBAL OVERVIEW
DSNT360I = ****************************************
DSNT362I = DATABASE = DB486A STATUS = RW 485
DBD LENGTH = 4028
DSNT397I = 486
NAME TYPE PARTS
-------- ---- -----

TS486A TS 0004
IX486A IX L0004
IX486B IX 0004
TS486C TS
IX486C IX
******* DISPLAY OF DATABASE DB486A ENDED *********************
DSN9022I = DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION
The display indicates that five objects are in database DB486A: two table
spaces and three indexes. Table space TS486A has four parts, and table space
TS486C is nonpartitioned. Index IX486A is a nonpartitioning index for table
space TS486A, and index IX486B is a partitioned index with four parts for
table space TS486A. Index IX486C is a nonpartitioned index for table space
TS486C.

284 Administration Guide

 Related reference:
Advisory or restrictive states (Db2 Utilities)
-DISPLAY DATABASE (Db2) (Db2 Commands)

Obtaining information about application programs

You can obtain various kinds of information about application programs that use
particular databases, table spaces, or index spaces by using the DISPLAY
DATABASE command. You can identify who or what is using an object and what
locks are being held on various objects.

Identifying who and what are using an object

You can obtain information about users and applications that are using an object,
and about the units of work that are accessing data.

About this task

You can obtain the following information:

v The names of the application programs currently using the database or space
v The authorization IDs of the users of these application programs
v The logical unit of work IDs of the database access threads that access data on
behalf of the specified remote locations

Procedure

To obtain information about objects:

Issue the DISPLAY DATABASE command with the SPACENAM option.

Example

For example, you can issue a command that names partitions 2, 3, and 4 in table
space TPAUGF01 in database DBAUGF01:
-DISPLAY DATABASE (DBAUGF01) SPACENAM (TPAUGF01) PART (2:4) USE

Db2 returns a list similar to this one:

DSNT360I : ***********************************
DSNT361I : * DISPLAY DATABASE SUMMARY
* GLOBAL USE
DSNT360I : ***********************************
DSNT362I : DATABASE = DBAUGF01 STATUS = RW
DBD LENGTH = 8066
DSNT397I :
NAME TYPE PART STATUS CONNID CORRID USERID
-------- ---- ----- ----------------- -------- ------------ --------

TPAUGF01 TS 0002 RW BATCH S3341209 ADMF001

- MEMBER NAME V61A
TPAUGF01 TS 0003 RW BATCH S3341209 ADMF001
- MEMBER NAME V61A
TPAUGF01 TS 0004 RW BATCH S3341209 ADMF001
- MEMBER NAME V61A
******* DISPLAY OF DATABASE DBAUGF01 ENDED **********************
DSN9022I : DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION

Chapter 8. Monitoring and controlling Db2 and its connections 285

 Determining which programs are holding locks on an object
You can use the DISPLAY DATABASE command to determine which programs are
holding locks on an object.

Procedure

To determine which application programs currently hold locks on the database or

space:

Issue the DISPLAY DATABASE command.

Example

For example, issue a command that names table space TSPART in database DB01:
-DISPLAY DATABASE(DB01) SPACENAM(TSPART) LOCKS

Db2 returns a list similar to this one:

17:45:42 DSNT360I - ****************************************************
17:45:42 DSNT361I - * DISPLAY DATABASE SUMMARY
17:45:42 * GLOBAL LOCKS
17:45:42 DSNT360I - ****************************************************
17:45:42 DSNT362I - DATABASE = DB01 STATUS = RW
17:45:42 DBD LENGTH = yyyy
17:45:42 DSNT397I -
NAME TYPE PART STATUS CONNID CORRID LOCKINFO
-------- ---- ----- ----------------- -------- ------------ ---------

TSPART TS 0001 RW LSS001 DSN2SQL H-IX,P,C

TSPART TS 0002 RW LSS001 DSN2SQL H-IX,P,C
TSPART TS 0003 RW LSS001 DSN2SQL H-IX,P,C
TSPART TS 0004 RW LSS001 DSN2SQL H-IX,P,C
******* DISPLAY OF DATABASE DB01 ENDED **********************
17:45:44 DSN9022I . DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION

Use the LOCKS ONLY keywords on the DISPLAY DATABASE command to

display only spaces that have locks. You can substitute the LOCKS keyword with
USE, CLAIMERS, LPL, or WEPR to display only databases that fit the criteria. Use
DISPLAY DATABASE as follows:
-DISPLAY DATABASE (DSNDB06) SPACENAM(*) LOCKS ONLY

This command results in the following messages:

11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT361I - * DISPLAY DATABASE SUMMARY
11:44:32 * GLOBAL LOCKS
11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT362I - DATABASE = DSNDB06 STATUS = RW
DBD LENGTH = 60560
11:44:32 DSNT397I -
NAME TYPE PART STATUS CONNID CORRID LOCKINFO
-------- ---- ----- ----------------- -------- ------------ ---------

SYSTSTSP TS RW DSN 020.DBCMD 06 H-IS,P,C

******* DISPLAY OF DATABASE DSNDB06 ENDED **********************
11:45:15 DSN9022I - DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION

286 Administration Guide

 Related reference:
-DISPLAY DATABASE (Db2) (Db2 Commands)
Related information:
DSNT361I (Db2 Messages)

Obtaining information about and handling pages in error

You can view information about pages that are in error.

Characteristics of pages that are in error

A page that is in error can be logically or physically in error.

A page is logically in error if its problem can be fixed without redefining new disk
tracks or volumes. For example, if Db2 cannot write a page to disk because of a
connectivity problem, the page is logically in error. Db2 inserts entries for pages
that are logically in error in a logical page list (LPL).

A page is physically in error if physical errors exist, such as device errors. Such
errors appear on the write error page range (WEPR). The range has a low and high
page, which are the same if only one page has errors.

If the cause of the problem is undetermined, the error is first recorded in the LPL.
If recovery from the LPL is unsuccessful, the error is then recorded on the error
page range.

Write errors for large object (LOB) table spaces that are defined with LOG NO
cause the unit of work to be rolled back. Because the pages are written during
normal deferred write processing, they can appear in the LPL and WEPR. The LOB
data pages for a LOB table space with the LOG NO attribute are not written to
LPL or WEPR. The space map pages are written during normal deferred write
processing and can appear in the LPL and WEPR.

A program that tries to read data from a page that is listed on the LPL or WEPR
receives an SQLCODE for “resource unavailable.” To access the page (or pages in
the error range), you must first recover the data from the existing database copy
and the log.

Displaying the logical page list

You can check the existence of logical page list (LPL) entries by issuing the
DISPLAY DATABASE command with the LPL option.

Procedure

To display a LPL entries:

Issue the DISPLAY DATABASE command with the LPL option. The ONLY option
restricts the output to objects that have LPL pages.

Chapter 8. Monitoring and controlling Db2 and its connections 287

 Example

For example:
-DISPLAY DATABASE(DBFW8401) SPACENAM(*) LPL ONLY

The following output is produced:

DSNT360I = ***********************************************************
DSNT361I = * DISPLAY DATABASE SUMMARY
* GLOBAL LPL
DSNT360I = ***********************************************************
DSNT362I = DATABASE = DBFW8401 STATUS = RW,LPL
DBD LENGTH = 8066
DSNT397I =
NAME TYPE PART STATUS LPL PAGES
-------- ---- ----- ----------------- ------------------

TPFW8401 TS 0001 RW,LPL 000000-000004

ICFW8401 IX L0001 RW,LPL 000000,000003
IXFW8402 IX RW,LPL 000000,000003-000005
---- 000007,000008-00000B
---- 000080-000090
******* DISPLAY OF DATABASE DBFW8401 ENDED **********************
DSN9022I = DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION

The display indicates that the pages that are listed in the LPL PAGES column are
unavailable for access.

Related reference:
-DISPLAY DATABASE (Db2) (Db2 Commands)

Removing pages from the logical page list

Although the Db2 subsystem always attempts automated recovery of logical page
list (LPL) pages when the pages are added to the LPL, you can also perform
manual recovery.

About this task

You can run only the following utilities on an object with pages in the LPL:
v LOAD with the REPLACE option
v MERGECOPY
v REBUILD INDEX
v RECOVER, except for:
RECOVER...PAGE
RECOVER...ERROR RANGE
v REPAIR with the SET statement
v REPORT

Procedure

When an object has pages on the LPL, to manually remove those pages and make
them available for access when Db2 is running:

288 Administration Guide

Use one of the following methods.
v Start the object with access (RW) or (RO). That command is valid even if the
table space is already started.
When you issue the START DATABASE command, message DSNI006I is
displayed, indicating that LPL recovery has begun. If second pass log apply for
LPL recovery starts, message DSNI051I is displayed. Message DSNI022I is
displayed periodically to give you the progress of the recovery. When recovery
is complete, message DSNI021I is displayed.
When you issue the START DATABASE command for a LOB table space that is
defined as LOG NO, and Db2 detects that log records that are required for LPL
recovery are missing due to the LOG NO attribute, the LOB table space is placed
in AUXW status, and the LOB is invalidated.
v Run the RECOVER or REBUILD INDEX utility on the object.
The only exception to this is when a logical partition of a nonpartitioned index
is in the LPL and has RECP status. If you want to recover the logical partition
by using REBUILD INDEX with the PART keyword, you must first use the
START DATABASE command to clear the LPL pages.
v Run the LOAD utility with the REPLACE option on the object.
v Issue an SQL DROP statement for the object.

Related reference:
-START DATABASE (Db2) (Db2 Commands)
LOAD (Db2 Utilities)
REBUILD INDEX (Db2 Utilities)
RECOVER (Db2 Utilities)
DROP (Db2 SQL)
Related information:
DSNI006I (Db2 Messages)
DSNI021I (Db2 Messages)
DSNI022I (Db2 Messages)
DSNI051I (Db2 Messages)

Displaying a write error page range

You can easily display the range of error pages.

Procedure

To display the range of error pages:

Issue the DISPLAY DATABASE command.

Chapter 8. Monitoring and controlling Db2 and its connections 289

 Example

For example:
-DISPLAY DATABASE (DBPARTS) SPACENAM (TSPART01) WEPR

The preceding command returns a list that is similar to this one:

11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT361I - * DISPLAY DATABASE SUMMARY
11:44:32 * GLOBAL WEPR
11:44:32 DSNT360I - ****************************************************
11:44:32 DSNT362I - DATABASE = DBPARTS STATUS = RW
DBD LENGTH = yyyy
11:44:32 DSNT397I -
NAME TYPE PART STATUS PHYERRLO PHYERRHI CATALOG PIECE
-------- ---- ----- --------------- -------- -------- -------- -----

TSPART01 TS 0001 RW,UTRO 00000002 00000004 DSNCAT 000

TSPART01 TS 0002 RW,UTRO 00000009 00000013 DSNCAT 001
TSPART01 TS 0003 RO
TSPART01 TS 0004 STOP
TSPART01 TS 0005 UT
******* DISPLAY OF DATABASE DBPARTS ENDED **********************
11:45:15 DSN9022I - DSNTDDIS ’DISPLAY DATABASE’ NORMAL COMPLETION

In the previous messages:

v PHYERRLO and PHYERRHI identify the range of pages that were being read
when the I/O errors occurred. PHYERRLO is an 8-digit hexadecimal number
representing the lowest page that is found in error, and PHYERRHI represents
the highest page that is found in error.
v PIECE, a 3-digit integer, is a unique identifier for the data set and supports the
page set that contains physical I/O errors.

Related reference:
-DISPLAY DATABASE (Db2) (Db2 Commands)
Related information:
DSNT361I (Db2 Messages)

Making objects unavailable

You can make databases, table spaces, and index spaces unavailable by using the
STOP DATABASE command.

Before you begin

If an object is in STOP-pending (STOPP) status, you must issue the START
DATABASE command to remove the STOPP status.

About this task

When you issue the STOP DATABASE command for a table space, the data sets
that contain that table space are closed and deallocated.

You also can stop Db2 subsystem databases (catalog, directory, and work file).
After the directory is stopped, installation SYSADM authority is required to restart
it.

290 Administration Guide

Procedure

To stop databases, table spaces, or index spaces:

Issue the STOP DATABASE command with the appropriate options.

How to issue the STOP DATABASE

Type of object that you want to stop command
To stop a physical partition of a table Use the PART option.
space:
To stop a physical partition of an index Use the PART option.
space:
To stop a logical partition within a Use the PART option.
nonpartitioning index that is associated
with a partitioned table space:
To stop any object as quickly as possible: Use the AT(COMMIT) option.
To stop user-defined databases: Start database DSNDB01 and table spaces
DSNDB01.DBD01, DSNDB01.SYSDBDXA,
and DSNDB01.SYSLGRNX before you stop
user-defined databases. If you do not do
start these objects, you receive message
DSNI003I. Resolve the problem and run the
job again.
To stop the work file database: Start database DSNDB01 and table spaces
DSNDB01.DBD01 DSNDB01.SYSDBDXA,
and DSNDB01.SYSLGRNX before you stop
the work file database. If you do not do start
these objects, you receive message DSNI003I.
Resolve the problem and run the job again.

Related reference:
-STOP DATABASE (Db2) (Db2 Commands)
-START DATABASE (Db2) (Db2 Commands)
Related information:
DSNI003I (Db2 Messages)

Commands to stop databases

The STOP DATABASE command has several options that you can use to control
how the database stops.

The following examples illustrate ways to use the STOP DATABASE command:
-STOP DATABASE (*)
Stops all databases for which you have STOPDB authorization, except the
Db2 directory (DSNDB01), the Db2 catalog (DSNDB06), or the Db2 work
file database (called DSNDB07, except in a data sharing environment), all
of which must be stopped explicitly.

Chapter 8. Monitoring and controlling Db2 and its connections 291

 -STOP DATABASE (dbname)
Stops a database and closes all of the data sets of the table spaces and
index spaces in the database.
-STOP DATABASE (dbname, ...)
Stops the named databases and closes all of the table spaces and index
spaces in the databases. If DSNDB01 is named in the database list, it
should be last on the list because stopping the other databases requires
that DSNDB01 be available.
-STOP DATABASE (dbname) SPACENAM (*)
Stops and closes all of the data sets of the table spaces and index spaces in
the database. The status of the named database does not change.
-STOP DATABASE (dbname) SPACENAM (space-name, ...)
Stops and closes the data sets of the named table space or index space. The
status of the named database does not change.
-STOP DATABASE (dbname) SPACENAM (space-name, ...) PART (integer)
Stops and closes the specified partition of the named table space or index
space. The status of the named database does not change. If the named
index space is nonpartitioned, Db2 cannot close the specified logical
partition.

The data sets containing a table space are closed and deallocated by the preceding
commands.

Related reference:
-STOP DATABASE (Db2) (Db2 Commands)

Altering buffer pools

Db2 stores buffer pool attributes in the Db2 bootstrap data set (BSDS). You can
change buffer pool attributes.

About this task

Buffer pool attributes, including buffer pool sizes, sequential steal thresholds,
deferred write thresholds, and parallel sequential thresholds, are initially defined
during the Db2 installation process.

Introductory concepts
Buffer pools (Introduction to Db2 for z/OS)
The role of buffer pools in caching data (Introduction to Db2 for z/OS)

Procedure

To alter buffer pool attributes:

Issue the ALTER BUFFERPOOL command.

Related concepts:
Buffer pool thresholds (Db2 Performance)
Related reference:
-ALTER BUFFERPOOL (Db2) (Db2 Commands)

292 Administration Guide

Monitoring buffer pools
You can display the current status for one or more active or inactive buffer pools.
You can also request a summary or detail report.

About this task

Buffer pools are areas of virtual storage that temporarily store pages of table spaces
or indexes.

Introductory concepts
Buffer pools (Introduction to Db2 for z/OS)
The role of buffer pools in caching data (Introduction to Db2 for z/OS)

Procedure

To monitor buffer pools:

Issue the DISPLAY BUFFERPOOL command.

Example

For example:
-DISPLAY BUFFERPOOL(BP0)

This command might produce a summary report such as the following:

!DIS BUFFERPOOL(BP0)
DSNB401I ! BUFFERPOOL NAME BP0, BUFFERPOOL ID 0, USE COUNT 27
DSNB402I ! BUFFER POOL SIZE = 2000 BUFFERS
VPSIZE MINIMUM = 2250 VPSIZE MAXIMUM = 3125
ALLOCATED = 2000 TO BE DELETED = 0
IN-USE/UPDATED = 0
DSNB406I ! PGFIX ATTRIBUTE -
CURRENT = NO
PENDING = YES
PAGE STEALING METHOD = LRU
DSNB404I ! THRESHOLDS -
VP SEQUENTIAL = 80
DEFERRED WRITE = 85 VERTICAL DEFERRED WRT = 10,15
PARALLEL SEQUENTIAL = 50 ASSISTING PARALLEL SEQT= 0
DSN9022I ! DSNB1CMD ’-DISPLAY BUFFERPOOL’ NORMAL COMPLETION

Related concepts:
Obtaining information about group buffer pools (Db2 Data Sharing Planning
and Administration)
Related tasks:
Tuning database buffer pools (Db2 Performance)
Monitoring and tuning buffer pools by using online commands (Db2
Performance)
Related reference:

Chapter 8. Monitoring and controlling Db2 and its connections 293

 -DISPLAY BUFFERPOOL (Db2) (Db2 Commands)
Related information:
DSNB401I (Db2 Messages)

Controlling user-defined functions

User-defined functions are extensions to the SQL language, which you can invoke in
an SQL statement wherever you can use expressions or built-in functions.

About this task

Introductory concepts
User-defined functions (Introduction to Db2 for z/OS)

User-defined functions, like stored procedures, run in WLM-established address

spaces. Because new functions are sometimes added to Db2, it is best to fully
qualify references to user-defined functions, or set the value of the CURRENT
PATH special register, so that the references resolve to the correct function in the
event of a name conflict.

Procedure

To control user-defined functions:

Issue the appropriate command for the action that you want to take.
START FUNCTION SPECIFIC
Activates an external function that is stopped.
DISPLAY FUNCTION SPECIFIC
Displays statistics about external user-defined functions accessed by Db2
applications.
STOP FUNCTION SPECIFIC
Prevents Db2 from accepting SQL statements with invocations of the
specified functions.

Related concepts:
Sample user-defined functions (Db2 SQL)
Function resolution (Db2 SQL)
Related tasks:
Monitoring and controlling stored procedures
Defining a user-defined function (Managing Security)
Related reference:
-START FUNCTION SPECIFIC (Db2) (Db2 Commands)
-DISPLAY FUNCTION SPECIFIC (Db2) (Db2 Commands)
-STOP FUNCTION SPECIFIC (Db2) (Db2 Commands)

294 Administration Guide

 SET PATH (Db2 SQL)
CURRENT PATH (Db2 SQL)

Starting user-defined functions

You can activate external functions that are stopped by using the Db2 START
FUNCTION SPECIFIC command.

About this task

You cannot start built-in functions or user-defined functions that are sourced on
another function.

Procedure

To activate all or a specific set of stopped external functions:

Issue the START FUNCTION SPECIFIC command.

Example

For example, assume that you want to start functions USERFN1 and USERFN2 in
the PAYROLL schema. Issue the following command:
START FUNCTION SPECIFIC(PAYROLL.USERFN1,PAYROLL.USERFN2)

The following output is produced:

DSNX973I START FUNCTION SPECIFIC SUCCESSFUL FOR PAYROLL.USERFN1
DSNX973I START FUNCTION SPECIFIC SUCCESSFUL FOR PAYROLL.USERFN2

Related reference:
-START FUNCTION SPECIFIC (Db2) (Db2 Commands)
Related information:
DSNX973I (Db2 Messages)

Monitoring user-defined functions

You can monitor external user-defined functions by using the DISPLAY
FUNCTION SPECIFIC command. This command displays statistics about the
functions and lists the range of functions that are stopped because of a STOP
FUNCTION SPECIFIC command.

About this task

This Db2 command displays statistics about external user-defined functions that
are accessed by Db2 applications. This command displays one output line for each
function that has been accessed by a Db2 application. Information returned by this
command reflects a dynamic status. By the time Db2 displays the information, the
status might have changed. Built-in functions or user-defined functions that are
sourced on another function are not applicable to this command.

Chapter 8. Monitoring and controlling Db2 and its connections 295

 Procedure

To monitor user-defined functions:

Issue the DISPLAY FUNCTION SPECIFIC command.

Example

For example, to display information about functions in the PAYROLL schema and
the HRPROD schema, issue this command:
-DISPLAY FUNCTION SPECIFIC(PAYROLL.*,HRPROD.*)

The following output is produced:

DSNX975I DSNX9DIS - DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-
------ SCHEMA=PAYROLL
FUNCTION STATUS ACTIVE QUED MAXQ TIMEOUT FAIL WLM_ENV
PAYRFNC1
STARTED 0 0 1 0 0 PAYROLL
PAYRFNC2
STOPQUE 0 5 5 3 0 PAYROLL
PAYRFNC3
STARTED 2 0 6 0 0 PAYROLL
USERFNC4
STOPREJ 0 0 1 0 1 SANDBOX
------ SCHEMA=HRPROD
FUNCTION STATUS ACTIVE QUED MAXQ TIMEOUT FAIL WLM_ENV
HRFNC1
STARTED 0 0 1 0 0 HRFUNCS
HRFNC2
STOPREJ 0 0 1 0 0 HRFUNCS
DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
DSN9022I - DSNX9COM ’-DISPLAY FUNC’ NORMAL COMPLETION

Related reference:
-DISPLAY FUNCTION SPECIFIC (Db2) (Db2 Commands)
-STOP FUNCTION SPECIFIC (Db2) (Db2 Commands)
Related information:
DSNX975I (Db2 Messages)

Stopping user-defined functions

You can prevent Db2 from accepting SQL statements with invocations of specific
functions by using the STOP FUNCTION SPECIFIC command. This command
does not prevent SQL statements with invocations of the functions from running if
they have already been queued or scheduled by Db2.

About this task

You cannot stop built-in functions or user-defined functions that are sourced on
another function.

296 Administration Guide

 Procedure

To stop access to all or a specific set of external functions:

Issue the STOP FUNCTION SPECIFIC command.

Example

For example, issue a command like the following one, which stops functions
USERFN1 and USERFN3 in the PAYROLL schema:
STOP FUNCTION SPECIFIC(PAYROLL.USERFN1,PAYROLL.USERFN3)

The following output is produced:

DSNX974I STOP FUNCTION SPECIFIC SUCCESSFUL FOR PAYROLL.USERFN1
DSNX974I STOP FUNCTION SPECIFIC SUCCESSFUL FOR PAYROLL.USERFN3

While the STOP FUNCTION SPECIFIC command is in effect, attempts to execute

the stopped functions are queued.

Related reference:
-STOP FUNCTION SPECIFIC (Db2) (Db2 Commands)
Related information:
DSNX974I (Db2 Messages)

Controlling Db2 utilities

Db2 utilities are classified into two groups: online and stand-alone.

About this task

The online utilities require Db2 to be running and can be controlled in several
different ways. The stand-alone utilities do not require Db2 to be running, and
they can be controlled only by means of JCL.
Related concepts:
Db2 online utilities (Db2 Utilities)
Db2 stand-alone utilities (Db2 Utilities)

Starting online utilities

Db2 utilities can dynamically create object lists from a pattern-matching expression
and can dynamically allocate the data sets that are required to process those
objects.

Procedure

To start a Db2 utility:

Prepare an appropriate set of JCL statements for a utility job. The input stream for
that job must include Db2 utility control statements.

Chapter 8. Monitoring and controlling Db2 and its connections 297

 Monitoring and changing online utilities
You can monitor the status of online utilities, change parameter values of some
utilities, and terminate a utility job prior to completion.

About this task

If a utility is not running, you need to determine whether the type of utility access
is allowed on an object of a specific status. The following table shows the
compatibility of utility types and object status.
Table 38. Compatibility of utility types and object status
Utility type Object access
Read-only RO
All RW (default access type for an object)
Db2 UT

Procedure

To monitor and change an online utility:

1. Issue the appropriate command for the action that you want to take.
ALTER UTILITY
Alters parameter values of an active REORG or REBUILD utility.
DISPLAY UTILITY
Displays the status of utility jobs.
TERM UTILITY
Terminates a utility job before its normal completion.
2. To change the status of an object, use the START DATABASE command with
the ACCESS option to start the object with a new status. For example:
-START DATABASE (DSN8D61A) ACCESS(RO)

Related concepts:
Db2 online utilities (Db2 Utilities)
Related reference:
-START DATABASE (Db2) (Db2 Commands)

Controlling Db2 stand-alone utilities

You use JCL to run the Db2 stand-alone utilities, most of which can run while Db2
is running.

Procedure

To run a Db2 stand-alone utility:

298 Administration Guide

1. Stop the table spaces and index spaces that are the object of the utility job. If
you do not do this, you might receive inconsistent output.
2. If the utility is one that requires that Db2 be stopped during utility execution,
use this command:
-STOP DB2 MODE (FORCE)
3. If the utility is one that requires that Db2 be running during utility execution
and if Db2 is not running, issue this command:
-START DB2
4. Create a JCL job that includes the utility control statement with code specific
data set names and associated parameters for your utility.

Stand-alone utilities
Some stand-alone utilities can be run only by means of JCL.

These stand-alone utilities are:

v DSN1COPY
v DSN1COMP
v DSN1PRNT
v DSN1SDMP
v DSN1LOGP
v DSNJLOGF
v DSNJU003 (change log inventory)
v DSNJU004 (print log map)

Most of the stand-alone utilities can be used while Db2 is running. However, for
consistency of output, the table spaces and index spaces must be stopped first
because these utilities do not have access to the Db2 buffer pools. In some cases,
Db2 must be running or stopped before you invoke the utility.

Stand-alone utility job streams require that you code specific data set names in the
JCL. To determine the fifth qualifier in the data set name, you need to query the
Db2 catalog tables SYSIBM.SYSTABLEPART and SYSIBM.SYSINDEXPART to
determine the IPREFIX column that corresponds to the required data set.

The change log inventory utility (DSNJU003) enables you to change the contents of
the bootstrap data set (BSDS). This utility cannot be run while Db2 is running
because inconsistencies could result. Use the STOP DB2 MODE(QUIESCE)
command to stop the Db2 subsystem, run the utility, and then restart Db2 with the
START DB2 command.

The print log map utility (DSNJU004) enables you to print the bootstrap data set
contents. The utility can be run when Db2 is active or inactive; however, when it is
run with Db2 active, the user's JCL and the Db2 started task must both specify
DISP=SHR for the BSDS data sets.
Related concepts:

Chapter 8. Monitoring and controlling Db2 and its connections 299

 Db2 stand-alone utilities (Db2 Utilities)

Controlling the IRLM

The internal resource lock manager (IRLM) subsystem manages Db2 locks.

About this task

The particular IRLM to which Db2 is connected is specified in the Db2 load
module for subsystem parameters. The particular IRLM is also identified as a z/OS
subsystem in the SYS1.PARMLIB member IEFSSNxx. That name is used as the
IRLM procedure name (irlmproc) in z/OS commands.

Each IMS and Db2 subsystem must use a separate instance of IRLM.

In a data sharing environment, the IRLM handles global locking, and each Db2
member has its own corresponding IRLM.

Procedure

To control the IRLM:

Issue the appropriate z/OS command for the action that you want to take.
In each command description, irlmproc is the IRLM procedure name and irlmnm is
the IRLM subsystem name.
MODIFY irlmproc,ABEND,DUMP
Abnormally terminates the IRLM and generates a dump.
MODIFY irlmproc,ABEND,NODUMP
Abnormally terminates the IRLM but does not generate a dump.
MODIFY irlmproc,DIAG
Initiates diagnostic dumps for IRLM subsystems in a data sharing group
when a delay occurs.
MODIFY irlmproc,SET
Dynamically sets the maximum amount of private virtual (PVT) storage or
the number of trace buffers that are used for this IRLM.
MODIFY irlmproc,STATUS
Displays the status for the subsystems on this IRLM.
START irlmproc
Starts the IRLM.
STOP irlmproc
Stops the IRLM normally.
TRACE CT,OFF,COMP=irlmnm
Stops IRLM tracing.
TRACE CT,ON,COMP=irlmnm
Starts IRLM tracing for all subtypes (DBM, SLM, XIT, and XCF).
TRACE CT,ON,COMP=irlmnm,SUB=(subname)
Starts IRLM tracing for a single subtype.

300 Administration Guide

 Related concepts:
IRLM names (Db2 Installation and Migration)
Related information:
Command types and environments in Db2 (Db2 Commands)

z/OS commands that operate on IRLM

You can use several z/OS commands to modify and monitor the IRLM connection.

MODIFY irlmproc,SET,PVT=nnn
Sets the maximum amount of private virtual (PVT) storage that this IRLM
can use for lock control structures.
MODIFY irlmproc,SET,DEADLOCK=nnnn
Sets the time for the local deadlock detection cycle.
MODIFY irlmproc,SET,LTE=nnnn
Sets the number of LOCK HASH entries that this IRLM can use on the
next connect to the XCF LOCK structure. Use this command only for data
sharing.
MODIFY irlmproc,SET,TIMEOUT=nnnn,subsystem-name
Sets the timeout value for the specified Db2 subsystem. Display the
subsystem-name by using MODIFY irlmproc,STATUS.
MODIFY irlmproc,SET,TRACE=nnn
Sets the maximum number of trace buffers that are used for this IRLM.
MODIFY irlmproc,STATUS,irlmnm
Displays the status of a specific IRLM.
MODIFY irlmproc,STATUS,ALLD
Displays the status of all subsystems known to this IRLM in the data
sharing group.
MODIFY irlmproc,STATUS,ALLI
Displays the status of all IRLMs known to this IRLM in the data sharing
group.
MODIFY irlmproc,STATUS,MAINT
Displays the maintenance levels of IRLM load module CSECTs for the
specified IRLM instance.
MODIFY irlmproc,STATUS,STOR
Displays the current and high-water allocation for private virtual (PVT)
storage, as well as storage that is above the 2-GB bar.
MODIFY irlmproc,STATUS,TRACE
Displays information about trace types of IRLM subcomponents.

Each IMS and Db2 subsystem must use a separate instance of IRLM.

Related information:

Chapter 8. Monitoring and controlling Db2 and its connections 301

 Command types and environments in Db2 (Db2 Commands)

Starting the IRLM

The internal resource lock manager (IRLM) must be available when you start Db2.

About this task

When Db2 is installed, you normally specify that the IRLM be started
automatically. Then, if the IRLM is not available when Db2 is started, Db2 starts it,
and periodically checks whether it is up before attempting to connect. If the
attempt to start the IRLM fails, Db2 terminates.

Consider starting the IRLM manually if you are having problems starting Db2 for
either of the following reasons:
v An IDENTIFY or CONNECT to a data sharing group fails.
v Db2 experiences a failure that involves the IRLM.

When you start the IRLM manually, you can generate a dump to collect diagnostic
information because IRLM does not stop automatically.

Procedure

If an automatic IRLM start has not been specified, to start IRLM:

Issue the z/OS START irlmproc command.

When started, the IRLM issues this message to the z/OS console:
DXR117I irlmnm INITIALIZATION COMPLETE

Stopping the IRLM

If the internal resource lock manager (IRLM) is started automatically by Db2, it
stops automatically when Db2 is stopped. If the IRLM is not started automatically,
you must stop it after Db2 stops.

Procedure

To stop IRLM:

Issue the z/OS STOP irlmproc command.

If you try to stop the IRLM while Db2 or IMS is still using it, you get the following
message:

DXR105E irlmnm STOP COMMAND REJECTED. AN IDENTIFIED SUBSYSTEM

IS STILL ACTIVE

302 Administration Guide

 If that happens, issue the STOP irlmproc command again, when the subsystems are
finished with the IRLM.
Alternatively, if you must stop the IRLM immediately, enter the following
command to force the stop:
MODIFY irlmproc,ABEND,NODUMP

The system responds with this message:

DXR165I KRLM TERMINATED VIA IRLM MODIFY COMMAND.
DXR121I KRLM END-OF-TASK CLEANUP SUCCESSFUL - HI-CSA 335K
- HI-ACCT-CSA 0K - HI-PVT 5402K

Results

Your Db2 subsystem will abend. An IMS subsystem that uses the IRLM does not
abend and can be reconnected.

IRLM uses the z/OS Automatic Restart Manager (ARM) services. However, it
de-registers from ARM for normal shutdowns. IRLM registers with ARM during
initialization and provides ARM with an event exit routine. The event exit routine
must be in the link list. It is part of the IRLM DXRRL183 load module. The event
exit routine ensures that the IRLM name is defined to z/OS when ARM restarts
IRLM on a target z/OS system that is different from the failing z/OS system. The
IRLM element name that is used for the ARM registration depends on the IRLM
mode. For local-mode IRLM, the element name is a concatenation of the IRLM
subsystem name and the IRLM ID. For global mode IRLM, the element name is a
concatenation of the IRLM data sharing group name, IRLM subsystem name, and
the IRLM ID.

IRLM de-registers from ARM when one of the following events occurs:
v PURGE irlmproc is issued.
v MODIFY irlmproc,ABEND,NODUMP is issued.
v Db2 automatically stops IRLM.

The command MODIFY irlmproc,ABEND,NODUMP specifies that IRLM de-register

from ARM before terminating, which prevents ARM from restarting IRLM.
However, this command does not prevent ARM from restarting Db2, and, if you
set the automatic restart manager to restart IRLM, Db2 automatically starts IRLM.

Monitoring threads
You monitor threads by using the Db2 DISPLAY THREAD command, which
displays current information about the status of threads.

About this task

The DISPLAY THREAD command displays information about:

v Threads that are processing locally
v Threads that are processing distributed requests
v Stored procedures or user-defined functions that the thread is executing
v Parallel tasks

Chapter 8. Monitoring and controlling Db2 and its connections 303

 Related tasks:
Managing Db2 threads (Db2 Performance)
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Types of threads
Threads are an important resource within a Db2 subsystem. A thread is a structure
that describes a connection made by an application and traces its progress in the
Db2 subsystem.
Allied threads
Allied threads are threads that are connected to Db2 from TSO, batch, IMS,
CICS, CAF, or RRSAF.
Database Access Threads
Distributed database access threads (sometimes called DBATs) are threads
that are connected through a network to access data at a Db2 server on
behalf distributed requesting systems. Database access threads are created
in the following situations:
| v When new connections are accepted from remote requesters
| v When Db2 is configured in INACTIVE mode, and a new request is
| received from a remote requester and no pooled database access thread
| is available to service the new request
Database access threads can operate in ACTIVE or INACTIVE mode. The
mode used for database access threads is controlled by the value of the
CMTSTAT subsystem parameter.
INACTIVE mode
When the value of the CMTSTAT subsystem parameter is
INACTIVE, a database access thread can be active or pooled. When
a database access thread is active, it is processing requests from
client connections within units of work. When a database access
thread is pooled, it is waiting for the next request from a client to
start a new unit of work.
INACTIVE mode database access threads are terminated under any
of the following conditions:
v After processing 200 units of work.
| v After being idle in the pool for the amount of time specified by
| the value of the POOLINAC subsystem parameter.
However, the termination of an INACTIVE mode thread does not
prevent another database access thread from being created to meet
processing demand, as long as the value of the MAXDBAT
subsystem parameter has not been reached.
ACTIVE mode
When the value CMTSTAT subsystem parameter is ACTIVE, a
database access thread is always active from initial creation to
termination.

304 Administration Guide

 Related reference:
DDF THREADS field (CMTSTAT subsystem parameter) (Db2 Installation and
Migration)
MAX REMOTE ACTIVE field (MAXDBAT subsystem parameter) (Db2
Installation and Migration)
IDLE THREAD TIMEOUT field (IDTHTOIN subsystem parameter) (Db2
Installation and Migration)

Output of the DISPLAY THREAD command

The output of the DISPLAY THREAD command can also indicate that a system
quiesce is in effect as a result of the ARCHIVE LOG command.

The DISPLAY THREAD command allows you to select which type of information
you want to include in the display by using one or more of the following:
v Active, indoubt, postponed-abort, or pooled threads
v Allied threads that are associated with the address spaces whose
connection-names are specified
v Allied threads
v Distributed threads
v Distributed threads that are 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 that is returned by the DISPLAY THREAD command reflects a

dynamic status. By the time the information is displayed, the status might have
changed. Moreover, the information is consistent only within one address space
and is not necessarily consistent across all address spaces.

To use the TYPE, LOCATION, DETAIL, and LUWID keywords, you must have
SYSOPR authority or higher.

More information about how to interpret this output can be found in the topics
describing the individual connections and in the description of message DSNV408I,
which is part of message DSNV401I.
Related tasks:
Archiving the log
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Displaying information about threads

Use the DISPLAY THREAD TYPE(INDOUBT) command to find information about
allied and database access indoubt threads. This command provides information
about threads where Db2 is a participant, a coordinator, or both.

About this task

Chapter 8. Monitoring and controlling Db2 and its connections 305

 The TYPE(INDOUBT) option tells you which systems still need indoubt resolution
and provides the LUWIDs that you need to recover indoubt threads. A thread that
has completed phase 1 of commit and still has a connection with its coordinator is
in the prepared state and is displayed as part of the DISPLAY THREAD active
report. If a prepared thread loses its connection with its coordinator, it enters the
indoubt state and terminates its connections to any participants at that time. Any
threads that are in the prepared or indoubt state when Db2 terminates are indoubt
after Db2 restart. However, if the participant system is waiting for a commit or
rollback decision from the coordinator, and the connection is still active, Db2
considers the thread active.

If a thread is indoubt at a participant, you can determine whether a commit or

abort decision was made at the coordinator by issuing the DISPLAY THREAD
command at the coordinator as described previously. If an indoubt thread appears
at one system and does not appear at the other system, the latter system backed
out the thread, and the first system must therefore do the same.
Related concepts:
Output of the DISPLAY THREAD command
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Displaying information by location

You can use the DISPLAY THREAD command to display thread information for
particular locations.

Procedure

To display information by location:

Issue the DISPLAY THREAD command with the LOCATION option, followed by a
list of location names.

Example

For example, you can specify an asterisk (*) after the THREAD and LOCATION
options:
-DISPLAY THREAD(*) LOCATION(*) DETAIL

When you issue this command, Db2 returns messages like the following:
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST▌1▐A▌2▐ REQ ID AUTHID PLAN ASID TOKEN
SERVER RA * 2923 DB2BP ADMF001 DISTSERV 0036 20▌3▐
V437-WORKSTATION=ARRAKIS, USERID=ADMF001,
APPLICATION NAME=DB2BP
V436-PGM=NULLID.SQLC27A4, SEC=201, STMNT=210
V445-09707265.01BE.889C28200037=203 ACCESSING DATA FOR
( 1)2002:91E:610:1::5▌4▐

306 Administration Guide

 V447-INDEX SESSID A ST TIME
V448-( 1) 446:1300▌5▐ W S2 9802812045091
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
Key Description
1 The ST (status) column contains characters that indicate the connection
status of the local site. The TR indicates that an allied, distributed thread
has been established. The RA indicates that a distributed thread has been
established and is in receive mode. The RD indicates that a distributed
thread is performing a remote access on behalf of another location (R) and
is performing an operation that involves DCE services (D). Currently, Db2
supports the optional use of DCE services to authenticate remote users.
2 The A (active) column contains an asterisk that indicates that the thread is
active within Db2. It is blank when the thread is inactive within Db2
(active or waiting within the application).
3 This LUWID is unique across all connected systems. This thread has a
token of 20 (it appears in two places in the display output).
4 This is the location of the partner. If the RDBNAME is not known, the
location column contains either an SNA LUNAME or IP address.
5 If the connection uses TCP/IP, the SESSID column contains "local:remote",
where local specifies the Db2 TCP/IP port number and remote specifies the
partner's TCP/IP port number.

Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Displaying information for non-Db2 locations

Because Db2 does not receive a location name from non-Db2 locations, you must
enter the LUNAME or IP address of the location for which you want to display
information.

About this task

The LUNAME is enclosed by the less-than (<) and greater-than (>) symbols. The IP
address can be in the dotted decimal or colon hexadecimal format.

Db2 uses the one of the following formats in messages that display information
about non-Db2 requesters:
v LUNAME notation
v Dotted decimal format
v Colon hexadecimal format

Chapter 8. Monitoring and controlling Db2 and its connections 307

 Procedure

To display information for non-Db2 locations:

Issue the DISPLAY THREAD command with the LOCATION option.

Example

For example, if you want to display information about a non-Db2 database

management system (DBMS) with the LUNAME of LUSFOS2, enter the following
command:
-DISPLAY THREAD (*) LOCATION (<LUSFOS2>)

Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Displaying conversation-level information about threads

Use the DISPLAY THREAD command with the LOCATION and DETAIL options
to display information about conversation activity when distribution information is
displayed for active threads.

About this task

The DETAIL option has no effect on the display of indoubt threads.

Procedure

To display conversation-level information about threads:

Issue the DISPLAY THREAD command with the LOCATION and DETAIL options:
-DISPLAY THREAD(*) LOCATION(*) DETAIL

Db2 returns the following messages, which indicate 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.
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
( 1)USIBMSTODB22-LUND1
V447--INDEX SESSID A ST TIME
V448--( 1) 0000000000000000 N▌1▐ A1▌2▐ 9015816504776
TSO RA * 11 SYSADM SYSADM DSNESPRR 001A 15
V445-STLDRIV.SSLU.A23555366A29=15 ACCESSING DATA FOR
( 1)123.34.101.98
V447--INDEX SESSID A ST TIME

308 Administration Guide

 V448--( 1) 446:3171 ▌3▐ S2 9015611253108
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
Key Description
▌1▐ The information on this line is part of message DSNV447I. The
conversation A (active) column for the server is useful in determining
when a Db2 thread is hung and whether processing is waiting in the
network stack (VTAM or TCP/IP) or in Db2. A value of W indicates that
the thread is suspended in Db2 and is waiting for notification from the
network that the event has completed. A value of N indicates that control
of the conversation is in the network stack.
▌2▐ The information on this line is part of message DSNV448I. The A in the
conversation ST (status) column for a serving site indicates that a
conversation is being allocated in Db2. A 2 would indicate DRDA access.
An R in the status column would indicate that the conversation is
receiving, or waiting to receive a request or reply. An S in this column for
a server indicates that the application is sending, or preparing to send a
request or reply.
▌3▐ The information on this line is part of message DSNV448I. The SESSID
column has changed. If the connection uses VTAM, the SESSID column
contains a VTAM session identifier. If the connection uses TCP/IP, the
SESSID column contains "local:remote", where local specifies the Db2 TCP/IP
port number and remote specifies the partner's TCP/IP port number.

Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Displaying threads by LUWID

Use the optional LUWID keyword, which is valid only when DDF is started, to
display threads by logical unit of work identifiers. The LUWIDs are assigned to the
thread by the site that originated the thread.

About this task

You can use an asterisk (*) in an LUWID keyword, like you can use an
asterisk in a LOCATION name. For example, issue the command DISPLAY THREAD
TYPE(INDOUBT) LUWID(NET1.*) to display all the indoubt threads whose LUWID has
a network name of NET1. The command DISPLAY THREAD TYPE(INDOUBT)
LUWID(IBM.NEW*) displays all indoubt threads whose LUWID has a network name
of "IBM" and whose LUNAME begins with "NEW."

Use the DETAIL keyword with the DISPLAY THREAD LUWID command to show
the status of every conversation that is connected to each displayed thread, and to
indicate whether a conversation is using DRDA access.

Chapter 8. Monitoring and controlling Db2 and its connections 309

 Procedure

To display threads by LUWIDs:

Issue the DISPLAY THREAD command with the following options:

-DISPLAY THREAD(*) LUWID (luwid) DETAIL

Db2 returns the following message:

-DISPLAY THREAD(*) LUWID (luwid) DET
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH TR 5 TC3923S0 SYSADM TC392 000D 2
V436-PGM=*.TC3923S0, SEC=1, STMNT=116
V444-DB2NET.LUNSITE0.A11A7D7B2057=2 ▌1▐ACCESSING DATA AT
( 1)USIBMSTODB22-LUNSITE1
V447--INDEX SESSID A ST TIME
V448--( 1) 00C3F4228C5A244C S2▌2▐ 8929612225354
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
Key Description
▌1▐ In the preceding display output, you can see that the LUWID has been
assigned a token of 2. You can use this token instead of the long version of
the LUWID to cancel or display the given thread. For example:
-DISPLAY THREAD(*) LUWID(2) DET
▌2▐ In addition, the status column for the serving site contains a value of S2.
The S means that this thread can send a request or response, and the 2
means that this is a DRDA access conversation.

Displaying threads by type

Use the DISPLAY THREAD command to display threads by type. For example,
you can display only the active threads that are executing a stored procedure or
user-defined function.

Procedure

To display threads by type:

Issue the DISPLAY THREAD command with the TYPE keyword. For example:
-DISPLAY THREAD(*) TYPE(PROC)

Monitoring all DBMSs in a transaction

Use the DETAIL keyword of the DISPLAY THREAD command to monitor all of
the requesting and serving database management systems (DBMSs) that are
involved in a transaction.

310 Administration Guide

About this task

For example, you could monitor an application that runs at USIBMSTODB21

requesting information from USIBMSTODB22, which must establish conversations
with secondary servers USIBMSTODB23 and USIBMSTODB24 to provide the
requested information. The following figure depicts such an example. In this
example, ADA refers to DRDA access, and SDA refers to Db2 private protocol
access. USIBMSTODB21 is considered to be upstream from USIBMSTODB22.
USIBMSTODB22 is considered to be upstream from USIBMSTODB23. Conversely,
USIBMSTODB23 and USIBMSTODB22 are downstream from USIBMSTODB22 and
USIBMSTODB21 respectively.

USIBMSTODB23
SDA

USIBMSTODB21 ADA USIBMSTODB22

SDA
USIBMSTODB24

Figure 24. Example of a Db2 transaction that involves four sites

The application that runs at USIBMSTODB21 is connected to a server at

USIBMSTODB22 by using DRDA access. If you enter the DISPLAY THREAD
command with the DETAIL keyword from USIBMSTODB21, you receive the
following output:
-DISPLAY THREAD(*) LOC(*) DET
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
V436-PGM=BKH2C.BKH2C, SEC=1, STMNT=4
V444-USIBMSY.SSLU.A23555366A29=2 ACCESSING DATA AT
( 1)USIBMSTODB22-SSURLU
V447--INDEX SESSID A ST TIME
V448--( 1) 0000000300000004 N R2 9015611253116
DISPLAY ACTIVE REPORT COMPLETE
11:26:23 DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

This output indicates that the application is waiting for data to be returned by the
server at USIBMSTODB22.

The server at USIBMSTODB22 is running a package on behalf of the application at

USIBMSTODB21 to access data at USIBMSTODB23 and USIBMSTODB24 by Db2
private protocol access. If you enter the DISPLAY THREAD command with the
DETAIL keyword from USIBMSTODB22, you receive the following output:
-DISPLAY THREAD(*) LOC(*) DET
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH RA * 0 BKH2C SYSADM YW1019C 0008 2
V436-PGM=BKH2C.BKH2C, SEC=1, STMNT=4
V445-STLDRIV.SSLU.A23555366A29=2 ACCESSING DATA FOR
( 1)USIBMSTODB21-SSLU

Chapter 8. Monitoring and controlling Db2 and its connections 311

 V444-STLDRIV.SSLU.A23555366A29=2 ACCESSING DATA AT
( 2)USIBMSTODB23-OSSLU
( 3)USIBMSTODB24-OSSURLU
V447--INDEX SESSID A ST TIME
V448--( 1) 0000000300000004 S2 9015611253108
V448--( 2) 0000000600000002 S1 9015611253077
V448--( 3) 0000000900000005 N R1 9015611253907
DISPLAY ACTIVE REPORT COMPLETE
11:26:34 DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

This output indicates that the server at USIBMSTODB22 is waiting for data to be
returned by the secondary server at USIBMSTODB24.

The secondary server at USIBMSTODB23 is accessing data for the primary server
at USIBMSTODB22. If you enter the DISPLAY THREAD command with the
DETAIL keyword from USIBMSTODB23, you receive the following output:
-DISPLAY THREAD(*) LOC(*) DET
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH RA * 2 BKH2C SYSADM YW1019C 0006 1
V445-STLDRIV.SSLU.A23555366A29=1 ACCESSING DATA FOR
( 1)USIBMSTODB22-SSURLU
V447--INDEX SESSID A ST TIME
V448--( 1) 0000000600000002 W R1 9015611252369
DISPLAY ACTIVE REPORT COMPLETE
11:27:25 DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

This output indicates that the secondary server at USIBMSTODB23 is not currently
active.

The secondary server at USIBMSTODB24 is also accessing data for the primary
server at USIBMSTODB22. If you enter the DISPLAY THREAD command with the
DETAIL keyword from USIBMSTODB24, you receive the following output:
-DISPLAY THREAD(*) LOC(*) DET
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH RA * 2 BKH2C SYSADM YW1019C 0006 1
V436-PGM=*.BKH2C, SEC=1, STMNT=1
V445-STLDRIV.SSLU.A23555366A29=1 ACCESSING DATA FOR
( 1)USIBMSTODB22-SSURLU
V447--INDEX SESSID A ST TIME
V448--( 1) 0000000900000005 S1 9015611253075
DISPLAY ACTIVE REPORT COMPLETE
11:27:32 DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

This output indicates that the secondary server at USIBMSTODB24 is currently

active.

The conversation status might not change for a long time. The conversation could
be hung, or the processing could be taking a long time. To determine whether the
conversation is hung, issue the DISPLAY THREAD command again and compare
the new timestamp to the timestamps from previous output messages. If the
timestamp is changing, but the status is not changing, the job is still processing. If
you need to terminate a distributed job, perhaps because it is hung and has been
holding database locks for a long time, you can use the CANCEL DDF THREAD
command if the thread is in Db2 (whether active or suspended). If the thread is in
VTAM, you can use the VARY NET TERM command.

312 Administration Guide

 Related tasks:
Canceling threads
Related reference:
-CANCEL THREAD (Db2) (Db2 Commands)
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Controlling connections
The method that you use to control connections between Db2 and another
subsystem or environment depends on the subsystem or environment that is
involved.

Controlling TSO connections

z/OS does not provide commands for controlling or monitoring a TSO connection
to Db2.

About this task

The connection is monitored instead by the Db2 command DISPLAY THREAD,

which displays information about connections to Db2 (from other subsystems as
well as from z/OS).

The command is generally entered from a z/OS console or an administrator's TSO

session.
Related tasks:
Issuing commands from TSO terminals
Monitoring threads
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)

Monitoring TSO and CAF connections

To display information about connections that use the TSO attachment facility and
the call attachment facility (CAF), issue the DISPLAY THREAD command.

About this task

The following table summarizes how the output for the DISPLAY THREAD
command differs for a TSO online application, a TSO batch application, a QMF™
session, and a call attachment facility application.
Table 39. Differences in DISPLAY THREAD information for different environments
Connection Name AUTHID Corr-ID1 Plan1
DSN (TSO TSO Logon ID Logon ID RUN .. Plan(x)
Online)

Chapter 8. Monitoring and controlling Db2 and its connections 313

 Table 39. Differences in DISPLAY THREAD information for different
environments (continued)
Connection Name AUTHID Corr-ID1 Plan1
DSN (TSO Batch) BATCH Job USER= Job Name RUN .. Plan(x)
QMF DB2CALL Logon ID Logon ID 'QMFvr0'
CAF DB2CALL Logon ID Logon ID OPEN parm

Notes:
1. After the application connects to Db2 but before a plan is allocated, this field is
blank.

The name of the connection can have one of the following values:
Name Connection to
TSO Program that runs in TSO foreground
BATCH
Program that runs in TSO background
DB2CALL
Program that uses the call attachment facility and that runs in the same
address space as a program that uses the TSO attachment facility

The correlation ID, corr-id, is either the foreground authorization ID or the

background job name.

The following command displays information about TSO and CAF threads,
including those threads that process requests to or from remote locations:
-DISPLAY THREAD(BATCH,TSO,DB2CALL)

314 Administration Guide

 DSNV401I = DISPLAY THREAD REPORT FOLLOWS -
DSNV402I = ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
▌1▐BATCH T * 2997 TEP2 SYSADM DSNTEP41 0019 18818
▌2▐BATCH RA * 1246 BINETEP2 SYSADM DSNTEP44 0022 20556
V445-DB2NET.LUND1.AB0C8FB44C4D=20556 ACCESSING DATA FOR SAN_JOSE
▌3▐TSO T 12 SYSADM SYSADM DSNESPRR 0028 5570
▌4▐DB2CALL T * 18472 CAFCOB2 SYSADM CAFCOB2 001A 24979
▌5▐BATCH T * 1 PUPPY SYSADM DSNTEP51 0025 20499
▌6▐ PT * 641 PUPPY SYSADM DSNTEP51 002D 20500
▌7▐ PT * 592 PUPPY SYSADM DSNTEP51 002D 20501
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I = DSNVDT ’-DIS THREAD’ NORMAL COMPLETION
Key Description
1 This is a TSO batch application.
2 This is a TSO batch application running at a remote location and accessing tables at
this location.
3 This is a TSO online application.
4 This is a call attachment facility application.
5 This is an originating thread for a TSO batch application.
6 This is a parallel thread for the originating TSO batch application thread.
7 This is a parallel thread for the originating TSO batch application thread.

Figure 25. DISPLAY THREAD output that shows TSO and CAF connections

Related tasks:
Monitoring threads
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Disconnecting from Db2 while under TSO

Several conditions can cause the TSO connection to Db2 to end.

About this task

The connection to Db2 ends, and the thread is terminated, when:

v You enter the END subcommand.
v You enter DSN again. (A new connection is established immediately.)
v You enter the CANCEL THREAD command (for threads that are active or
suspended in Db2).
v You enter the MVS CANCEL command.
v You press the attention key (PA1).
v Any of the following operations end, or you enter END or RETURN when using
any of them:

Chapter 8. Monitoring and controlling Db2 and its connections 315

 – SQL statements using SPUFI
– DCLGEN
– BIND/REBIND/FREE
– RUN

For example, the following command and subcommands establish a connection to

Db2, run a program, and terminate the connection:

TSO displays:
READY

You enter:
DSN SYSTEM (DSN)

DSN displays:
DSN

You enter:
RUN PROGRAM (MYPROG)

DSN displays:
DSN

You enter:
END

TSO displays:
READY

Controlling CICS connections

Certain CICS attachment facility commands can be entered from a CICS terminal
to control and monitor connections between CICS and Db2.

About this task

DSNC DISCONNECT
Terminates threads using a specific Db2 plan.
DSNC DISPLAY
Displays thread information or statistics.
DSNC MODIFY
Modifies the maximum number of threads for a transaction or group.
DSNC STOP
Disconnects CICS from Db2.
DSNC STRT
Starts the CICS attachment facility.

316 Administration Guide

CICS command responses are sent to the terminal from which the corresponding
command was entered, unless the DSNC DISPLAY command specifies an
alternative destination.

Related information:
Overview of the CICS Db2 interface (CICS Db2 Guide)
Command types and environments in Db2 (Db2 Commands)

Connecting from CICS

You can start a connection to Db2 at any time after CICS initialization by using the
CICS attachment facility. The CICS attachment facility is a set of Db2-provided
modules that are loaded into the CICS address space.

Procedure

To connect to Db2, use one of the following approaches:

v Issue the following command to start the attachment facility:
DSNC STRT ssid
For ssid, specify a Db2 subsystem ID to override the value that is specified in the
CICS INITPARM macro.
v Start the attachment facility automatically at CICS initialization by using a
program list table (PLT).

Restarting CICS
One function of the CICS attachment facility is to keep data synchronized between
the two systems.

About this task

If Db2 completes phase 1 but does not start phase 2 of the commit process, the
units of recovery that are being committed are termed indoubt. An indoubt unit of
recovery might occur if Db2 terminates abnormally after completing phase 1 of the
commit process. CICS might commit or roll back work without Db2 knowing
about it.

Db2 cannot resolve those indoubt units of recovery (that is, commit or roll back the
changes made to Db2 resources) until the connection to CICS is restarted.

Procedure

To restart CICS:

You must auto-start CICS (START=AUTO in the DFHSIT table) to obtain all
necessary information for indoubt thread resolution that is available from its log.
Do not perform a cold start. You specify the START option in the DFHSIT table.
If CICS has requests active in Db2 when a Db2 connection terminates, the
corresponding CICS tasks might remain suspended even after CICS is reconnected
to Db2. Purge those tasks from CICS by using a CICS-supplied transaction such as:

CEMT SET TASK(nn) FORCE

Chapter 8. Monitoring and controlling Db2 and its connections 317

 If any unit of work is indoubt when the failure occurs, the CICS attachment facility
automatically attempts to resolve the unit of work when CICS is reconnected to
Db2. Under some circumstances, however, CICS cannot resolve indoubt units of
recovery. You have to manually recover these indoubt units of recovery.
Related concepts:
CICS Transaction Server for z/OS Supplied Transactions
Related tasks:
Monitoring and CICS threads and recovering CICS-Db2 indoubt units of recovery
Related information:
Resource definition (CICS Transaction Server for z/OS)

Defining CICS threads

Every CICS transaction that accesses Db2 requires a thread to service the Db2
requests. Each thread uses one z/OS subtask to execute Db2 code for the CICS
application.

About this task

The DSNC STRT command starts the CICS Db2 attachment facility, which allows
CICS application programs to access Db2 databases.

Threads are created at the first Db2 request from the application if one is not
already available for the specific Db2 plan.
Related concepts:
CICS Transaction Server for z/OS Db2 Guide

Monitoring and CICS threads and recovering CICS-Db2 indoubt

units of recovery
No operator intervention is required for connecting applications because CICS
handles the threads dynamically. However, You can monitor threads by using CICS
attachment facility commands or Db2 commands.

About this task

Any authorized CICS user can monitor the threads and change the connection
parameters as needed. Operators can use the following CICS attachment facility
commands to monitor the threads:

Procedure
v Authorized CICS user can monitor the threads and change the connection
parameters as needed.
– Operators can use the following CICS attachment facility commands to
monitor the threads:
– DSNC DISPLAY PLAN plan-name destination
DSNC DISPLAY TRANSACTION transaction-id destination
These commands display the threads that the resource or transaction is using.
The following information is provided for each created thread:

318 Administration Guide

 - Authorization ID for the plan that is associated with the transaction (8
characters).
- PLAN/TRAN name (8 characters).
- A or I (one character).
If A is displayed, the thread is within a unit of work. If I is displayed, the
thread is waiting for a unit of work, and the authorization ID is blank.
– The following CICS attachment facility command is used to monitor CICS:
DSNC DISPLAY STATISTICS destination
v To display a list of postponed units of recovery, issue a DISPLAY THREAD
command.
-DISPLAY THREAD (connection-name) TYPE (POSTPONED)

The result is similar to the following output:

DSNV431I -POSTPONED ABORT THREADS - 480
COORDINATOR STATUS RESET URID AUTHID
CICS41 P-ABORT 00019B8ADE9E ADMF001
V449-HAS NID= CICS41.AACC9B739F125184 AND ID=GT00LE39
DISPLAY POSTPONED ABORT REPORT COMPLETE
DSN9022I -STR DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
v To display a list of indoubt units of recovery, you can issue a DISPLAY THREAD
command.
-DISPLAY THREAD (connection-name) TYPE (INDOUBT)

The result is similar to the following output:

DSNV407I -STR INDOUBT THREADS - 480
COORDINATOR STATUS RESET URID AUTHID
CICS41 INDOUBT 00019B8ADE9E ADMF001
V449-HAS NID= CICS41.AACC9B739F125184 AND ID=GT00LE39
DISPLAY INDOUBT REPORT COMPLETE
DSN9022I -STR DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
v To recover an indoubt unit of recovery, issue the following commands.
-RECOVER INDOUBT (connection-name) ACTION (COMMIT) ID (correlation-id)
-RECOVER INDOUBT (connection-name) ACTION (ABORT) ID (correlation-id)
The default value for connection-name is the connection name from which you
entered the command. The correlation-id is the correlation ID of the thread to be
recovered. You can determine the correlation ID by issuing the command
DISPLAY THREAD. Your choice for the ACTION parameter indicates whether to
commit or roll back the associated unit of recovery.
One of the following messages might be issued after you use the RECOVER
command:
DSNV414I - THREAD correlation-id COMMIT SCHEDULED
DSNV415I - THREAD correlation-id ABORT SCHEDULED

Related concepts:
Resolution of CICS indoubt units of recovery
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Chapter 8. Monitoring and controlling Db2 and its connections 319

 Disconnecting CICS applications
To disconnect a particular CICS transaction from Db2, you must abnormally
terminate the transaction.

Procedure

To disconnect a CICS application from Db2, use one of the following methods:
v The Db2 command CANCEL THREAD can be used to cancel a particular thread.
CANCEL THREAD requires that you know the token for any thread that you
want to cancel. Enter the following command to cancel the thread that is
identified by the token as indicated in the display output.
-CANCEL THREAD(46)
When you issue the CANCEL THREAD command for a thread, that thread is
scheduled to be terminated in Db2.
v The command DSNC DISCONNECT terminates the threads allocated to a plan
ID, but it does not prevent new threads from being created. This command frees
Db2 resources that are shared by the CICS transactions and allows exclusive
access to them for special-purpose processes such as utilities or data definition
statements.
The thread is not canceled until the application releases it for reuse, either at
SYNCPOINT or end-of-task.

Related concepts:
CICS Transaction Server for z/OS Db2 Guide

Disconnecting from CICS

To disconnect the Db2 attachment to CICS, you can do an orderly disconnection or
a forced disconnection.

About this task

Orderly termination is recommended whenever possible. An orderly

termination of the connection allows each CICS transaction to terminate before
thread subtasks are detached. Therefore, no indoubt units of recovery should exist
when you reconnect.

Forced termination is not recommended, but at times you might need to force the
connection to end. A forced termination of the connection can abnormally
terminate CICS transactions that are connected to Db2. Therefore, indoubt units of
recovery can exist at reconnect.

Procedure
v To disconnect CICS with an orderly termination, use one of the following
methods:
– Enter the DSNC STOP QUIESCE command. CICS and Db2 remain active.
For example, the following command stops the Db2 subsystem (QUIESCE)
allows the currently identified tasks to continue normal execution, and does
not allow new tasks to identify themselves to Db2:
-STOP DB2 MODE (QUIESCE)

320 Administration Guide

 The following message appears when the stop process starts and frees the
entering terminal (option QUIESCE):
DSNC012I THE ATTACHMENT FACILITY STOP QUIESCE IS PROCEEDING
When the stop process ends and the connection is terminated, the following
message is added to the output from the CICS job:
DSNC025I THE ATTACHMENT FACILITY IS INACTIVE
– Enter the CICS command CEMT PERFORM SHUTDOWN. During program
list table (PLT) processing, the CICS attachment facility is also named to shut
down. Db2 remains active. For information about this command, see CICS
shutdown (CICS Transaction Server for z/OS).
– Enter the Db2 command CANCEL THREAD. The thread terminates
abnormally.
v To disconnect CICS with a forced termination, use one of the following methods:
– Enter the DSNC STOP FORCE command. This command waits 15 seconds
before detaching the thread subtasks and in some cases can achieve an
orderly termination. This message appears when the stop process starts and
frees the entering terminal (option FORCE):
DSNC022I THE ATTACHMENT FACILITY STOP FORCE IS PROCEEDING

Db2 and CICS remain active.

– Enter the CICS command CEMT PERFORM SHUTDOWN IMMEDIATE. For
information about this command, see CICS shutdown (CICS Transaction
Server for z/OS).
– Enter the Db2 command STOP DB2 MODE (FORCE). CICS remains active.
A forced termination also occurs in the following situations:
– A Db2 abend occurs. CICS remains active.
– A CICS abend occurs. Db2 remains active.
– STOP is issued to the Db2 or CICS attachment facility. The CICS transaction
overflows to the pool. The transaction issues an intermediate commit. The
thread is terminated at commit time, and further Db2 access is not allowed.
When the stop process ends and the connection is terminated, the following
message is added to the output from the CICS job:
DSNC025I THE ATTACHMENT FACILITY IS INACTIVE

Controlling IMS connections

You use IMS operator commands to control and monitor the connection to Db2.

About this task

/START SUBSYS
Connects the IMS control region to a Db2 subsystem.
/TRACE
Controls the IMS trace.
/DISPLAY SUBSYS
Displays connection status and thread activity.
/DISPLAY OASN SUBSYS
Displays outstanding units of recovery.

Chapter 8. Monitoring and controlling Db2 and its connections 321

 /CHANGE SUBSYS
Deletes an indoubt unit of recovery from IMS.
/STOP SUBSYS
Disconnects IMS from a Db2 subsystem.

IMS command responses are sent to the terminal from which the corresponding
command was entered. Authorization to enter IMS commands is based on IMS
security.
Related information:
Command types and environments in Db2 (Db2 Commands)
IMS commands

Connections to the IMS control region

IMS makes one connection to its control region from each Db2 subsystem. IMS can
make the connection either automatically or in response to a command.

Connections are made in the following ways:

v Automatically during IMS cold start initialization or at warm start of IMS if a
Db2 connection was active when IMS is shut down.
v In response to the /START SUBSYS ssid command, where ssid is the Db2
subsystem identifier.
The command causes the following message to be displayed at the logical
terminal (LTERM):
DFS058 START COMMAND COMPLETED
The message is issued regardless of whether Db2 is active and does not imply
that the connection is established.

The order of starting IMS and Db2 is not vital. If IMS is started first, when Db2
comes up, Db2 posts the control region MODIFY task, and IMS again tries to
reconnect.

If Db2 is stopped by the STOP DB2 command, the /STOP SUBSYS command, or a
Db2 abend, IMS cannot reconnect automatically. You must make the connection by
using the /START SUBSYS command.

The following messages can be produced when IMS attempts to connect a Db2
subsystem. In each message, imsid is the IMS connection name.
v If Db2 is active, these messages are sent:
– To the z/OS console:
DFS3613I ESS TCB INITIALIZATION COMPLETE
– To the IMS master terminal:
DSNM001I IMS/TM imsid CONNECTED TO SUBSYSTEM ssnm
v If Db2 is not active, this message is sent to the IMS master terminal:
DSNM003I IMS/TM imsid FAILED TO CONNECT TO SUBSYSTEM ssnm
RC=00 imsid

RC=00 means that a notify request has been queued. When Db2 starts, IMS is
also notified.
No message goes to the z/OS console.

322 Administration Guide

IMS thread attachment
IMS connection threads describe the IMS application connection, traces progress,
processes resource functions, and delimits accessibility to Db2 resources and
services.

Execution of the first SQL statement of the program causes the IMS attachment
facility to create a thread and allocate a plan, whose name is associated with the
IMS application program module name. Db2 sets up control blocks for the thread
and loads the plan.

Duplicate IMS correlation IDs

Under certain circumstances, two threads can have the same correlation ID.

Two threads can have the same correlation ID (pst#.psbname) if all of these
conditions occur:
v Connections have been broken several times.
v Indoubt units of recovery were not recovered.
v Applications were subsequently scheduled in the same region.

To uniquely identify threads which have the same correlation ID (pst#.psbname)

requires that you be able to identify and understand the network ID (NID). For
connections with IMS, you should also be able to identify and understand the IMS
originating sequence number (OASN).

The NID is shown in a condensed form on the messages that are issued by the
Db2 DISPLAY THREAD command processor. The IMS subsystem name (imsid) is
displayed as the net_node. The net_node is followed by the 8-byte OASN, which is
displayed in hexadecimal format (16 characters), with all leading zeros omitted.
The net_node and the OASN are separated by a period.

For example, if the net_node is IMSA, and the OASN is 0003CA670000006E, the
NID is displayed as IMSA.3CA670000006E on the Db2 DISPLAY THREAD
command output.

If two threads have the same corr-id, use the NID instead of corr-id on the
RECOVER INDOUBT command. The NID uniquely identifies the work unit.

The OASN is a 4-byte number that represents the number of IMS scheduling since
the last IMS cold start. The OASN is occasionally found in an 8-byte format, where
the first 4 bytes contain the scheduling number, and the last 4 bytes contain the
number of IMS sync points (commits) during this schedule. The OASN is part of
the NID.

The NID is a 16-byte network ID that originates from IMS. The NID contains the
4-byte IMS subsystem name, followed by four bytes of blanks, followed by the
8-byte version of the OASN. In communications between IMS and Db2, the NID
serves as the recovery token.

Displaying IMS attachment facility threads

You use the DISPLAY THREAD command to display IMS attachment facility
threads.

Chapter 8. Monitoring and controlling Db2 and its connections 323

 About this task

DISPLAY THREAD output for Db2 connections to IMS differs depending on

whether Db2 is connected to a DL/I batch program, a control region, a
message-driven program, or a non-message-driven program. The following table
summarizes these differences.
Table 40. Differences in DISPLAY THREAD information for IMS connections
Connection Name AUTHID2 ID1,2 Plan1,2
DL/I batch DDITV02 JOBUSER= Job Name DDITV02
statement statement
Control region IMSID N/A N/A N/A
Message driven IMSID Signon ID or PST+ PSB RTT or program
ltermid
Non-message IMSID AXBUSER or PST+ PSB RTT or program
driven PSBNAME

Notes:
1. After the application connects to Db2 but before sign-on processing completes,
this field is blank.
2. After sign-on processing completes but before a plan is allocated, this field is
blank.

The following command displays information about IMS threads, including those
accessing data at remote locations:
-DISPLAY THREAD(imsid)

DSNV401I -STR DISPLAY THREAD REPORT FOLLOWS -

DSNV402I -STR ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
▌1▐SYS3 T * 3 0002BMP255 ADMF001 PROGHR1 0019 99
SYS3 T * 4 0001BMP255 ADMF001 PROGHR2 0018 97
▌2▐SYS3 N 5 SYSADM 0065 0
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I -STR DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
Key Description
1 This is a message-driven BMP.
2 This thread has completed sign-on processing, but a Db2 plan has not been
allocated.

Figure 26. DISPLAY THREAD output showing IMS connections

Terminating IMS attachment facility threads

When an application terminates, IMS invokes an exit routine to disconnect the
application from Db2. You cannot terminate a thread without causing an abend in
the IMS application with which it is associated.

324 Administration Guide

Procedure

To terminate an IMS application, use one of these methods:

v Terminate the application.
The IMS commands /STOP REGION reg# ABDUMP or /STOP REGION reg#
CANCEL can be used to terminate an application that runs in an online
environment. For an application that runs in the DL/I batch environment, the
z/OS command CANCEL can be used.
v Use the Db2 command CANCEL THREAD.
CANCEL THREAD can be used to cancel a particular thread or set of threads.
CANCEL THREAD requires that you know the token for any thread that you
want to cancel. Enter the following command to cancel the thread that is
identified by a token in the display output:
-CANCEL THREAD(46)
When you issue the CANCEL THREAD command, that thread is scheduled to
be terminated in Db2.
Related information:
IMS commands

Displaying IMS-Db2 indoubt units of recovery

You can display information about threads whose status is indoubt by using the
Db2 DISPLAY THREAD command.

About this task

One function of the thread that connects Db2 to IMS is to keep data in
synchronization between the two systems. If the application program requires it, a
change to IMS data must also be made to Db2 data. If Db2 abends while connected
to IMS, IMS might commit or back out work without Db2 being aware of it. When
Db2 restarts, that work is termed indoubt. Typically, some decision must be made
about the status of the work.

Procedure

To display a list of indoubt units of recovery:

Issue the DISPLAY THREAD command. For example:

-DISPLAY THREAD (imsid) TYPE (INDOUBT)

This command produces messages similar to the following:

DSNV401I -STR DISPLAY THREAD REPORT FOLLOWS -
DSNV406I -STR POSTPONED ABORTT THREADS - 920
COORDINATOR STATUS RESET URID AUTHID
SYS3 P-ABORT 00017854FF6B ADMF001
V449-HAS NID= SYS3.400000000 AND ID= 0001BMP255
BATCH P-ABORT 00017854A8A0 ADMF001
V449-HAS NID= DSN:0001.0 AND ID= RUNP10
BATCH P-ABORT 00017854AA2E ADMF001
V449-HAS NID= DSN:0002.0 AND ID= RUNP90
BATCH P-ABORT 0001785CD711 ADMF001
V449-HAS NID= DSN:0004.0 AND ID= RUNP12
DISPLAY POSTPONED ABORT REPORT COMPLETE
DSN9022I -STR DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

Chapter 8. Monitoring and controlling Db2 and its connections 325

 Related tasks:
Restarting Db2 after termination
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Recovering IMS-Db2 indoubt units of recovery

When you determine that indoubt units of recovery exist, you recover from this
situation by using the Db2 RECOVER INDOUBT command.

Procedure

To recover an indoubt unit:

Issue one of the following commands.

In each command, imsid is the connection name, and pst#.psbname is the
correlation ID that is listed by the command DISPLAY THREAD. Your choice of
the ACTION parameter tells whether to commit or roll back the associated unit of
recovery.
v -RECOVER INDOUBT (imsid) ACTION (COMMIT) ID (pst#.psbname)
v -RECOVER INDOUBT (imsid) ACTION (ABORT) ID (pst#.psbname)

Results

One of the following messages might be issued after you issue the RECOVER
command:
DSNV414I - THREAD pst#.psbname COMMIT SCHEDULED
DSNV415I - THREAD pst#.psbname ABORT SCHEDULED

Related tasks:
Resolving indoubt units of recovery

Displaying postponed IMS-Db2 units of recovery

You can display a list of postponed IMS-Db2 units of recovery.

About this task

Procedure

To display a list of postponed units of recovery:

Issue the DISPLAY THREAD command. For example:

-DISPLAY THREAD (imsid) TYPE (POSTPONED)

In this command, imsid is the connection name. The command produces messages
similar to these:

326 Administration Guide

 DSNV401I -STR DISPLAY THREAD REPORT FOLLOWS -
DSNV406I -STR POSTPONED ABORTT THREADS - 920
COORDINATOR STATUS RESET URID AUTHID
SYS3 P-ABORT 00017854FF6B ADMF001
V449-HAS NID= SYS3.400000000 AND ID= 0001BMP255
BATCH P-ABORT 00017854A8A0 ADMF001
V449-HAS NID= DSN:0001.0 AND ID= RUNP10
BATCH P-ABORT 00017854AA2E ADMF001
V449-HAS NID= DSN:0002.0 AND ID= RUNP90
BATCH P-ABORT 0001785CD711 ADMF001
V449-HAS NID= DSN:0004.0 AND ID= RUNP12
DISPLAY POSTPONED ABORT REPORT COMPLETE
DSN9022I -STR DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

Related tasks:
Restarting Db2 after termination
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Resolving IMS residual recovery entries

You can resolve IMS residual recovery entries (RREs).

About this task

At certain times, IMS builds a list of residual recovery entries (RREs). RREs are units
of recovery about which Db2 might be in doubt. RREs occur in the following
situations:
v If Db2 is not operational, IMS has RREs that cannot be resolved until Db2 is
operational. Those are not a problem.
v If Db2 is operational and connected to IMS, and if IMS rolled back the work that
Db2 has committed, the IMS attachment facility issues message DSNM005I. If
the data in the two systems must be consistent, this is a problem situation.
v If Db2 is operational and connected to IMS, RREs can still exist, even though no
messages have informed you of this problem. The only way to recognize this
problem is to issue the IMS /DISPLAY OASN SUBSYS command after the Db2
connection to IMS has been established.

Procedure

To resolve IMS RREs:

1. To display the residual recovery entry (RRE) information, issue the following
command:
/DISPLAY OASN SUBSYS subsystem-name
2. To purge the RRE, issue one of these commands:
v /CHANGE SUBSYS subsystem-name RESET
v /CHANGE SUBSYS subsystem-name RESET OASN nnnn
Where nnnn is the originating application sequence number that is listed in the
display. The originating application sequence number is the schedule number
of the program instance, indicating its place in the sequence of invocations of
that program since the last cold start of IMS. IMS cannot have two indoubt
units of recovery with the same schedule number.

Chapter 8. Monitoring and controlling Db2 and its connections 327

 Results

These commands reset the status of IMS; they do not result in any communication
with Db2.
Related information:
Recovering from IMS indoubt units of recovery

Controlling IMS dependent region connections

Controlling IMS dependent region connections involves connecting from
dependent regions, monitoring connection activity, and disconnecting from
dependent regions.

How IMS dependent region connections work:

The IMS attachment facility that is used in the control region is also loaded into
dependent regions. A connection is made from each dependent region to Db2. This
connection is used to pass SQL statements and to coordinate the commitment of
Db2 and IMS work.

The following process is used by IMS to initialize and connect.

1. Read the SSM from IMS.PROCLIB.
A subsystem member can be specified on the dependent region EXEC
parameter. If it is not specified, the control region SSM is used. If the region is
never to connect to Db2, specify a member with no entries to avoid loading the
attachment facility.
2. Load the Db2 attachment facility from prefix.SDSNLOAD.
For a batch message processing (BMP) program, the load is not done until the
application issues its first SQL statement. At that time, IMS attempts to make
the connection.
For a message processing program (MPP) region or IMS Fast Path (IFP) region,
the connection is made when the IMS region is initialized, and an IMS
transaction is available for scheduling in that region.
| An IMS subsystem establishes the following connections to Db2:
| v A control region coordinator connection
| v An application connection from each dependent region

If Db2 is not active, or if resources are not available when the first SQL statement
is issued from an application program, the action taken depends on the error
option specified on the SSM user entry. The options are:
Option Action
R The appropriate return code is sent to the application, and the SQL code is
returned.
Q The application abends. This is a PSTOP transaction type; the input
transaction is re-queued for processing, and new transactions are queued.
A The application abends. This is a STOP transaction type; the input
transaction is discarded, and new transactions are not queued.

The region error option can be overridden at the program level by using the
resource translation table (RTT).
Related concepts:
IMS attachment facility macro (DSNMAPN) (Db2 Installation and Migration)

328 Administration Guide

Disconnecting from IMS dependent regions:

Usually, IMS master terminal operators avoid disconnecting a dependent region

explicitly.

About this task

However, they might want to change values in the SSM member of IMS.PROCLIB.
To do that, they can issue /STOP REGION, update the SSM member, and issue /START
REGION.

Monitoring activity on connections from Db2

A thread is established from a dependent region when an application makes its
first successful Db2 request. You can issue IMS or Db2 commands to see
information about connections and the applications that currently use them.

Procedure

To monitor activity on connections, issue the following commands:

v From Db2:
-DISPLAY THREAD (imsid)
v From IMS:
/SSR -DISPLAY THREAD (imsid)

Results

Either command produces the following messages:

DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
conn-name s * req-ct corr-id auth-id pname asid token
conn-name s * req-ct corr-id auth-id pname asid token
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION
Related tasks:
Displaying information by location
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Monitoring activity of connections from IMS

You can monitor the connection to Db2 from IMS by using the /DISPLAY SUBSYS
command.

About this task

In addition to showing which program is active on each dependent region

connection, the display also shows the LTERM user name and gives the control
region connection status.

Chapter 8. Monitoring and controlling Db2 and its connections 329

 Procedure

To monitor the connection to Db2 from IMS:

Issue the /DISPLAY SUBSYS command with the following syntax:

/DISPLAY SUBSYS subsystem-name

The connection between IMS and Db2 is shown as one of the following states:
v CONNECTED
v NOT CONNECTED
v CONNECT IN PROGRESS
v STOPPED
v STOP IN PROGRESS
v INVALID SUBSYSTEM NAME=name
v SUBSYSTEM name NOT DEFINED BUT RECOVERY OUTSTANDING
The thread status from each dependent region is shown as one of the following
states:
v CONN
v CONN, ACTIVE (includes LTERM of user)

Example

The following four examples show the output that might be generated when you
issue the IMS /DISPLAY SUBSYS command.

The following figure shows the output that is returned for a DSN subsystem that is
not connected. The IMS attachment facility issues message DSNM003I in this
example.

0000 15.49.57 R 45,/DIS SUBSYS NEW

0000 15.49.57 IEE600I REPLY TO 45 IS;/DIS SUBSYS END
0000 15.49.57 JOB 56 DFS000I DSNM003I IMS/TM V1 SYS3 FAILED TO CONNECT TO SUBSYSTEM DSN RC=00 SYS3
0000 15.49.57 JOB 56 DFS000I SUBSYS CRC REGID PROGRAM LTERM STATUS SYS3
0000 15.49.57 JOB 56 DFS000I DSN : NON CONN SYS3
0000 15.49.57 JOB 56 DFS000I *83228/154957* SYS3
0000 15.49.57 JOB 56 *46 DFS996I *IMS READY* SYS3

Figure 27. Example of output from IMS /DISPLAY SUBSYS processing

The following figure shows the output that is returned for a DSN subsystem that is
connected. The IMS attachment facility issues message DSNM001I in this example.

0000 15.58.59 R 46,/DIS SUBSYS ALL

0000 15.58.59 IEE600I REPLY TO 46 IS;/DIS SUBSYS ALL
0000 15.59.01 JOB 56 DFS551I MESSAGE REGION MPP1 STARTED ID=0001 TIME=1551 CLASS=001,002,003,004
0000 15.59.01 JOB 56 DFS000I DSNM001I IMS/TM=V1 SYS3 CONNECTED TO SUBSYSTEM DSN SYS3
0000 15.59.01 JOB 56 DFS000I SUBSYS CRC REGID PROGRAM LTERM STATUS SYS3
0000 15.59.01 JOB 56 DFS000I DSN : CONN SYS3
0000 15.59.01 JOB 56 DFS000I *83228/155900* SYS3
0000 15.59.01 JOB 56 *47 DFS996I *IMS READY* SYS3

Figure 28. Example of output from IMS /DISPLAY SUBSYS processing

The following figure shows the output that is returned for a DSN subsystem that is
in a stopped status. The IMS attachment facility issues message DSNM002I in this
example.

330 Administration Guide

0000 15.59.28 R 47,/STO SUBSYS ALL
0000 15.59.28 IEE600I REPLY TO 47 IS;/STO SUBSYS ALL
0000 15.59.37 JOB 56 DFS058I 15:59:37 STOP COMMAND IN PROGRESS SYS3
0000 15.59.37 JOB 56 *48 DFS996I *IMS READY* SYS3
0000 15.59.44 R 48,/DIS SUBSYS ALL
0000 15.59.44 IEE600I REPLY TO 48 IS;/DIS SUBSYS ALL
0000 15.59.45 JOB 56 DFS000I DSNM002I IMS/TM V1 SYS3 DISCONNECTED FROM SUBSYSTEM DSN RC = E. SYS3
0000 15.59.45 JOB 56 DFS000I SUBSYS CRC REGID PROGRAM LTERM STATUS SYS3
0000 15.59.45 JOB 56 DFS000I DSN : STOPPED SYS3
0000 15.59.45 JOB 56 DFS000I *83228/155945* SYS3
0000 15.59.45 JOB 56 *49 DFS996I *IMS READY* SYS3

Figure 29. Example of output from the IMS /DISPLAY SUBSYS command

The following figure shows the output that is returned for a DSN subsystem that is
connected and region 1. You can use the values from the REGID and the
PROGRAM fields to correlate the output of the command to the LTERM that is
involved.

0000 16.09.35 JOB 56 R 59,/DIS SUBSYS ALL

0000 16.09.35 JOB 56 IEE600I REPLY TO 59 IS;/DIS SUBSYS ALL
0000 16.09.38 JOB 56 DFS000I SUBSYS CRC REGID PROGRAM LTERM STATUS SYS3
0000 16.09.38 JOB 56 DFS000I DSN : CONN SYS3
0000 16.09.38 JOB 56 DFS000I 1 CONN SYS3
0000 16.09.38 JOB 56 DFS000I *83228/160938* SYS3
0000 16.09.38 JOB 56 *60 DFS996I *IMS READY* SYS3
0000 16.09.38 JOB 56

Figure 30. Example of output from IMS /DISPLAY SUBSYS processing for a DSN subsystem that is connected and
the region ID (1) that is included.

Disconnecting from IMS

The connection between IMS and Db2 ends when either IMS or Db2 terminates.
Alternatively, the IMS master terminal operator can explicitly break the connection.

About this task

To break the connection, enter this command:

/STOP SUBSYS subsystem-name

That command sends the following message to the terminal that entered it, usually
the master terminal operator (MTO):
DFS058I STOP COMMAND IN PROGRESS

The /START SUBSYS subsystem-name command is required to re-establish the

connection.

In an implicit or explicit disconnect, the following message is sent to the IMS

master terminal:
DSNM002I IMS/TM imsid DISCONNECTED FROM SUBSYSTEM subsystem-name - RC=z

That message uses the following reason codes (RC):

Code Meaning
A IMS is terminating normally (for example, /CHE
FREEZE|DUMPQ|PURGE). Connected threads complete.
B IMS is terminating abnormally. Connected threads are rolled back. Db2
data is backed out now; DL/I data is backed out at IMS restart.

Chapter 8. Monitoring and controlling Db2 and its connections 331

 C Db2 is terminating normally after a STOP DB2 MODE (QUIESCE)
command. Connected threads complete.
D Db2 is terminating normally after a STOP DB2 MODE (FORCE) command,
or Db2 is terminating abnormally. Connected threads are rolled back. DL/I
data is backed out now. Db2 data is backed out now if Db2 terminated
normally; otherwise, it is backed out at restart.
E IMS is ending the connection because of a /STOP SUBSYS subsystem-name
command. Connected threads complete.

If an application attempts to access Db2 after the connection ended and before a
thread is established, the attempt is handled according to the region error option
specification (R, Q, or A).

Controlling RRS connections

You can start or restart a Resource Recovery Services attachment facility (RRSAF)
connection at any time after Resource Recovery Services (RRS) is started.

About this task

If RRS is not started, an IDENTIFY request fails with reason code X'00F30091'.

Application programs can use the following RRSAF functions to control

connections to Db2:
IDENTIFY
Establishes the task (TCB) as a user of the named Db2 subsystem. When
the first task within an address space issues a connection request, the
address space is initialized as a user of Db2.
SIGNON
Provides a user ID and, optionally, one or more secondary authorization
IDs that are to be associated with the connection. Invokes the sign-on exit
routine. Optionally, lets a thread join a global transaction.
AUTH SIGNON
Provides a user ID, an access control environment element (ACEE), and,
optionally, one or more secondary authorization IDs that are to be
associated with the connection. Invokes the sign-on exit routine.
CREATE THREAD
Allocates a plan. If you provide a plan name, Db2 allocates that plan. If
you provide a collection name, Db2 allocates a special plan named ?RRSAF
and a package list that contains the collection name.
After CREATE THREAD completes, Db2 can execute SQL statements.
TERMINATE THREAD
Deallocates the plan.
TERMINATE IDENTIFY
Removes the task as a user of Db2. If this is the last or only task in the
address space with a Db2 connection, the TERMINATE IDENTIFY
command terminates the address space connection to Db2.

332 Administration Guide

TRANSLATE
Returns an SQL code and printable text, in the SQLCA, that describes a
Db2 error reason code.

Related tasks:
Invoking the Resource Recovery Services attachment facility (Db2 Application
programming and SQL)
Programming for concurrency (Db2 Performance)

Abnormal termination involving Db2 and RRS

If Db2 abnormally terminates but RRS remains active, RRS might commit or roll
back work without Db2 knowledge. In a similar manner, if RRS abnormally
terminates after Db2 has completed phase 1 of commit processing for an
application, Db2 does not know whether to commit or roll back the work.

In either case, when Db2 restarts, that work is termed indoubt.

Db2 cannot resolve those indoubt units of recovery (that is, commit or roll back the
changes made to Db2 resources) until Db2 restarts with RRS.

If any unit of work is indoubt when a failure occurs, Db2 and RRS automatically
resolve the unit of work when Db2 restarts with RRS.

Displaying RRS indoubt units of recovery

You can display a list of the Resource Recovery Services (RRS) indoubt units of
recovery.

Procedure

To display a list of indoubt units of recovery:

Issue the following DISPLAY THREAD command:

-DISPLAY THREAD (RRSAF) TYPE (INDOUBT)

The command produces output that is similar to the following example:

DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV406I - INDOUBT THREADS -
COORDINATOR STATUS RESET URID AUTHID
RRSAF INDOUBT 00019B8ADE9E ADMF001
V449-HAS NID= AD64101C7EED90000000000101010000 AND ID= ST47653RRS
DISPLAY INDOUBT REPORT COMPLETE
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

For RRSAF connections, a network ID is the z/OS RRS unit of recovery ID (URID),
which uniquely identifies a unit of work. A z/OS RRS URID is a 32-character
number.

Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Chapter 8. Monitoring and controlling Db2 and its connections 333
 Related information:
DSNV401I (Db2 Messages)

Recovering RRS indoubt units of recovery manually

You might need to manually recover an indoubt unit of recovery if the RRS log is
lost. When that happens, message DSN3011I is displayed on the z/OS console.

Procedure

To recover an indoubt unit of recovery:

1. Determine the correlation ID of the thread to be recovered by issuing the
DISPLAY THREAD command.
2. Issue one of the following commands to recover the indoubt unit:
v -RECOVER INDOUBT (RRSAF) ACTION (COMMIT) ID (correlation-id)
v -RECOVER INDOUBT (RRSAF) ACTION (ABORT) ID (correlation-id)
The ACTION parameter of the RECOVER command indicates whether to
commit or roll back the associated unit of recovery.

Results

If you recover a thread that is part of a global transaction, all threads in the global
transaction are recovered.

The following messages might be issued when you issue the RECOVER INDOUBT
command:
DSNV414I - THREAD correlation-id COMMIT SCHEDULED
DSNV415I - THREAD correlation-id ABORT SCHEDULED

The following DSNV418I message might also be issued:

DSNV418I - RECOVER INDOUBT REJECTED FOR ID=correlation-id

If this message is issued, use the following NID option of RECOVER INDOUBT:
-RECOVER INDOUBT(RRSAF) ACTION(action) NID(nid)

where nid is the 32-character field that is displayed in the DSNV449I message.

Related concepts:
Multiple system consistency
Related tasks:
Resolving indoubt units of recovery
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
-RECOVER INDOUBT (Db2) (Db2 Commands)

Displaying RRS postponed units of recovery

You can display a list of the Resource Recovery Services (RRS) postponed units of
recovery.

334 Administration Guide

Procedure

To display a list of postponed units of recovery:

Issue the following DISPLAY THREAD command:

-DISPLAY THREAD (RRSAF) TYPE (POSTPONED)

The command produces output that is similar to the following example:

DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV406I - POSTPONED ABORT THREADS -
COORDINATOR STATUS RESET URID AUTHID
RRSAF P-ABORT 00019B8ADE9E ADMF001
V449-HAS NID= AD64101C7EED90000000000101010000 AND ID= ST47653RRS
DISPLAY POSTPONED ABORT REPORT COMPLETE
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

For RRSAF connections, a network ID is the z/OS RRS unit of recovery ID (URID),
which uniquely identifies a unit of work. A z/OS RRS URID is a 32-character
number.

Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)
Related information:
DSNV401I (Db2 Messages)

Monitoring and displaying RRSAF connections

The Resource Recovery Services attachment facility (RRSAF) allows an application
or application monitor to disassociate a Db2 thread from a TCB. Later the thread
can be associated with the same or a different TCB within the same address space.

About this task

RRSAF uses the RRS Switch Context (CTXSWCH) service to do this. Only
authorized programs can execute CTXSWCH.

Db2 stores information in an RRS CONTEXT about an RRSAF thread so that Db2
can locate the thread later. An application or application monitor can then invoke
CTXSWCH to disassociate the CONTEXT from the current TCB and then associate
the CONTEXT with the same TCB or a different TCB.

The following command displays information about RRSAF threads, including

those that access data at remote locations:
-DISPLAY THREAD(RRSAF)

The command produces output similar to the output in the following figure:

Chapter 8. Monitoring and controlling Db2 and its connections 335

 DSNV401I = DISPLAY THREAD REPORT FOLLOWS -
DSNV402I = ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
▌1▐RRSAF T 4 RRSTEST2-111 ADMF001 ?RRSAF 0024 13
▌2▐RRSAF T 6 RRSCDBTEST01 USRT001 TESTDBD 0024 63
▌3▐RRSAF DI 3 RRSTEST2-100 USRT002 ?RRSAF 001B 99
▌4▐RRSAF TR 9 GT01XP05 SYSADM TESTP05 001B 235
V444-DB2NET.LUND0.AA8007132465=16 ACCESSING DATA AT
V446-SAN_JOSE:LUND1
DISPLAY ACTIVE REPORT COMPLETE
Key Description
▌1▐ This is an application that used CREATE THREAD to allocate the special plan that
is used by RRSAF (plan name = ?RRSAF).
▌2▐ This is an application that connected to Db2 and allocated a plan with the name
TESTDBD.
▌3▐ This is an application that is currently not connected to a TCB (shown by status
DI).
▌4▐ This is an active connection that is running plan TESTP05. The thread is accessing
data at a remote site.

Figure 31. DISPLAY THREAD output showing RRSAF connections

Disconnecting RRSAF applications from Db2

To disconnect a Resource Recovery Services attachment facility (RRSAF) transaction
from Db2, you must abnormally terminate the transaction.

Procedure

To cancel a particular thread:

Issue the CANCEL THREAD command.

The CANCEL THREAD command requires that you know the token for any thread
that you want to cancel. Issue the DISPLAY THREAD command to obtain the
token number, and then enter the following command to cancel the thread:
-CANCEL THREAD(token)

When you issue the CANCEL THREAD command, Db2 schedules the thread for
termination.

Controlling connections to remote systems

You can control connections to remote systems that use distributed data by
controlling the threads. The types of threads that are involved in connecting to
other systems are allied threads and database access threads.

336 Administration Guide

About this task

An allied thread is a thread that is connected locally to your Db2 subsystem, that is
from TSO, CICS, IMS, or a stored procedures address space. A database access thread
is a thread that is initiated by a remote DBMS to your Db2 subsystem.
Related concepts:
Db2 commands for monitoring connections to other systems
Related tasks:
Resolving indoubt units of recovery
Related information:
Recovering from database access thread failure

Starting DDF
You can start the distributed data facility (DDF) if you have at least SYSOPR
authority.

About this task

When you install Db2, you can request that the DDF start automatically when Db2
starts.

Procedure

To start the DDF, if it has not already been started:

Issue the START DDF command.

When DDF is started and is responsible for indoubt thread resolution with remote
partners, message DSNL432I, message DSNL433I, or both, is generated. These
messages summarize the responsibility DDF has for indoubt thread resolution with
remote partners.
The following messages are associated with the START DDF command:
DSNL003I - DDF IS STARTING
DSNL004I - DDF START COMPLETE LOCATION locname
LU netname.luname
GENERICLU netname.gluname
DOMAIN domain
TCPPORT tcpport
SECPORT secport
RESPORT resport

If the DDF is not properly installed, the START DDF command fails, and message
,DSN9032I, - REQUESTED FUNCTION IS NOT AVAILABLE, is issued. If the DDF has
started, the START DDF command fails, and message ,DSNL001I, - DDF IS
ALREADY STARTED, is issued. Use the DISPLAY DDF command to display the status
of DDF.

Related concepts:
Maintaining consistency across multiple systems
Related reference:
-START DDF (Db2) (Db2 Commands)

Chapter 8. Monitoring and controlling Db2 and its connections 337

 -DISPLAY DDF (Db2) (Db2 Commands)
DSNTIPR: Distributed data facility panel 1 (Db2 Installation and Migration)

Suspending DDF server activity

You can use the STOP DDF MODE(SUSPEND) command to suspend distributed
data facility (DDF) server threads temporarily.

About this task

Suspending DDF server threads frees all resources that are held by the server
threads and lets the following operations complete:
v CREATE
v ALTER
v DROP
v GRANT
v REVOKE

When you issue the STOP DDF MODE(SUSPEND) command, Db2 waits for all
active DDF database access threads to become pooled or to terminate. Two
optional keywords on this command, WAIT and CANCEL, let you control how
long Db2 waits and what action Db2 takes after a specified time period.

Related reference:
-STOP DDF (Db2) (Db2 Commands)

Resuming DDF server activity

You can resume suspended distributed data facility (DDF) server activity.

Procedure

To resume suspended DDF server threads:

Issue the START DDF command.

Related reference:
-START DDF (Db2) (Db2 Commands)

Displaying information about DDF work

The DISPLAY DDF command displays information regarding the status of the
distributed data facility (DDF). This command also displays information that is
related to the start of DDF, such as the location name, the LU name, the IP address,
and domain names.

338 Administration Guide

Before you begin

To issue the DISPLAY DDF command, you must have SYSOPR authority or higher.

About this task

Tip: You can use the optional DETAIL keyword to receive additional configuration
and statistical information.

The DISPLAY DDF DETAIL command is especially useful, because the command
displays new inbound connections that are not indicated by other commands. For
example, sometimes new inbound connections are not yet reflected in the DISPLAY
THREAD report. Cases of when a new inbound connection is not displayed
include if DDF is in INACTIVE MODE, as denoted by a DT value of I in the
message DSNL090I, and DDF is stopped with mode SUSPEND, or the maximum
number of active database access threads has been reached. These new connections
are displayed in the DISPLAY DDF DETAIL report. However, specific details
regarding the origin of the connections, such as the client system IP address or LU
name, are not available until the connections are associated with a database access
thread.

Procedure

To display information about DDF work:

Enter one of the following commands:

v To show only the basic information, enter the DISPLAY DDF command.
-DISPLAY DDF
Db2 returns output similar to the following sample.
DSNL080I - DSNLTDDF DISPLAY DDF REPORT FOLLOWS-
DSNL081I STATUS=STARTD
DSNL082I LOCATION LUNAME GENERICLU
DSNL083I SVL650A USIBMSY.SYEC650A -NONE
DSNL084I TCPPORT=446 SECPORT=0 RESPORT=5001 IPNAME=-NONE
DSNL085I IPADDR=::9.110.115.106
DSNL085I IPADDR=2002:91E:610:1::5
DSNL086I SQL DOMAIN=v8ec103.svl.ibm.com
DSNL086I RESYNC DOMAIN=v8ec103.svl.ibm.com
DSNL087I ALIAS PORT SECPORT STATUS
DSNL088I ALIASLOC1 551 0 STATIC
DSNL088I ALIASLOC2 552 0 STATIC
DSNL088I ALIASLOC3 553 0 STATIC
DSNL088I ALIASLOC4 554 0 STATIC
DSNL088I ALIASLOC5 555 0 STATIC
DSNL088I ALIASLOC6 556 0 STATIC
DSNL088I ALIASLOC7 557 0 STATIC
DSNL088I ALIASLOC8 558 0 STATIC
DSNL089I MEMBER IPADDR=::9.110.115.112
DSNL089I MEMBER IPADDR=2002:91E:610:1::112
DSNL105I CURRENT DDF OPTIONS ARE:
DSNL106I PKGREL = COMMIT
DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE
v To show additional information, enter the DISPLAY DDF command with the
DETAIL option.
-DISPLAY DDF DETAIL

Chapter 8. Monitoring and controlling Db2 and its connections 339

 With the DETAIL option, the following additional information is included in the
output:
DSNL090I DT= A CONDBAT= 64 MDBAT= 64
DSNL092I ADBAT= 1 QUEDBAT= 0 INADBAT= 0 CONQUED= 0
DSNL093I DSCDBAT= 0 INACONN= 0
DSNL100I LOCATION SERVER LIST:
DSNL101I WT IPADDR IPADDR
DSNL102I 64 ::9.110.115.111 2002:91E:610:1::111
DSNL102I ::9.110.115.112 2002:91E:610:1::112
DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE

Related reference:
-DISPLAY DDF (Db2) (Db2 Commands)
Related information:
DSNL080I (Db2 Messages)

Db2 commands for monitoring connections to other systems:

By issuing certain Db2 commands, you can generate information about the status
of distributed threads.

DISPLAY DDF
Displays information about the status and configuration of the distributed
data facility (DDF), and about the connections or threads controlled by
DDF.
DISPLAY LOCATION
Displays statistics about threads and conversations between a remote Db2
subsystem and the local subsystem.
DISPLAY THREAD
Displays information about Db2, distributed subsystem connections, and
parallel tasks.

Displaying information about connections with other locations:

The DISPLAY LOCATION command displays summary information about

connections with other locations. You can also use this command to display
detailed information about the conversations with other locations.

Before you begin

Prerequisite: To issue the DISPLAY LOCATION command, you must have

SYSOPR authority or higher.

About this task

You can specify location names, SNA LU names, or IP addresses, and the DETAIL
keyword is supported.

340 Administration Guide

 To display information about connections with other locations:

Procedure

Issue the DISPLAY LOCATION command. For example:

-DISPLAY LOCATION(*)

Db2 returns output that is similar to the following example:

DSNL200I @ DISPLAY LOCATION REPORT FOLLOWS-
LOCATION PRDID T ATT CONNS
LUND0 DSN10011 R 1
LUND1 DSN10011 S 0
::FFFF:124.63.51.17..50000 SQL09073 R 3
::FFFF:124.63.51.17 SQL09073 S 15
DISPLAY LOCATION REPORT COMPLETE

You can use an asterisk (*) in place of the end characters of a location name. For
example, you can use DISPLAY LOCATION(SAN*) to display information about all
active connections between your Db2 subsystem and a remote location that begins
with “SAN”. The results include the number of conversations and conversation
role, requester, or server.
When Db2 connects with a remote location, information about that location,
persists in the report even if no active connections exist, including:
v The physical address of the remote location (LOCATION)
v The product identifier (PRDID)

Example

The DISPLAY LOCATION command displays the following types of information

for each DBMS that has active connections, except for the local subsystem:
v The network address for the location:
– For remote locations accessed through SNA connections, the location name
the SNA LU name.
– For remote locations accessed through TCP/IP connections, the location name
is the dotted decimal IPv4 or colon hexadecimal IPv6 address. If the T column
contains R, the IP address is concatenated with the port value of the remote
location.
v The PRDID, which identifies the database product at the location.
The format of product identifier values is pppvvrrm, where ppp is a 3-letter
product code (such as DSN for Db2), vv is the version, rr is the release, and m is
the modification level. For example, DSN11015 identifies Db2 11 in new-function
mode, the value is ‘DSN11015'. The product code (ppp) is one of the following
values:
AQT for IBM Db2 Analytics Accelerator for z/OS
ARI for DB2 Server for VSE & VM
DSN for Db2 for z/OS
JCC for IBM Data Server Driver for JDBC and SQLJ
QSQ for DB2 for i
SQL for Db2 for Linux, UNIX, and Windows
Modification (m) values have the following meanings:
| 0 Conversion and enabling-new-function modes for migration from DB2
| 10 (CM10, CM10*, ENFM10, and ENFM10*)

Chapter 8. Monitoring and controlling Db2 and its connections 341

| 5 New-function mode.
v Whether the local system is requesting data from the remote system, or acting as
a server to the remote system. 'R' indicates a requester connection from local
subsystem accessing the remote system. 'S' indicates a server connection from
remote system accessing the local subsystem.
v The number of connections that have a particular attribute from or to the
location. The attribute value is blank for the message line that contains the total
number of connections for the location. Additional lines for connections with
particular attributes are shown only when a detailed report is requested.
v The total number of conversations that are in use between the local system and
the remote system

For example, suppose two threads are at location USIBMSTODB21. One thread is a
database access thread that is related to a non-Db2 requester system, and the other
is an allied thread that goes from USIBMSTODb21 to the non-Db2 server system.
Both threads use SNA connections. The DISPLAY LOCATION command that is
issued at USIBMSTODB21 displays the following output:
DSNL200I @ DISPLAY LOCATION REPORT FOLLOWS-
LOCATION PRDID T ATT CONNS
LUND1 R 1
LULA DSN09010 S 1
DISPLAY LOCATION REPORT COMPLETE

The following output shows the result of the DISPLAY LOCATION(*) command when
Db2 is connected to the following DRDA partners:
v TCP/IP for DRDA connections to ::FFFF:124.38.54.16
v SNA connections to LULA.
DSNL200I @ DISPLAY LOCATION REPORT FOLLOWS-
LOCATION PRDID T ATT CONNS
::FFFF:124.38.54.16..446 DSN10015 R 2
::FFFF:124.38.54.16 DSN10015 S 1
LULA DSN09010 R 1
LULA DSN09010 S 2
LULA
DISPLAY LOCATION REPORT COMPLETE

The DISPLAY LOCATION command displays information for each remote location
that currently is, or once was, in contact with Db2. If a location is displayed with
zero conversations, one of the following conditions exists:
v Sessions currently exist with the partner location, but no active conversations are
allocated to any of the sessions.
v Sessions no longer exist with the partner, because contact with the partner has
been lost.

When you specify the DETAIL option in the DISPLAY LOCATION command, the
report might include additional messages lines for each remote location, including:
v Information about the number of conversations in the CONNS column with each
remote location that have particular attributes. that are identified by a value in
the ATT column. For example, the number of connections that use trusted
context are identified by TRS.
v Information about conversations that are owned by Db2 system threads, such as
those that are used for resynchronization of indoubt units of work.

342 Administration Guide

 Canceling SQL from an IBM data server driver
| You can use the SQLCancel() function for the C-based drivers or the
| Statement.cancel method for Java™-based drivers to cancel an SQL request
| running on a remote Db2 for z/OS server.

| Before you begin

| There are several types of IBM data server drivers available from Db2 for Linux,
| UNIX, and Windows. You can cancel SQL from a remote client running:
| v IBM Data Server Driver for ODBC and CLI
| v IBM Data Server Driver for JDBC and SQLJ type 4 connectivity

| Related information:
| IBM data server client and driver types

| About this task

| You can configure the cancel behavior by setting configuration properties for your
| client driver:
| v For C-based drivers, configure the InterruptProcessingMode property.
| v For Java-based drivers, configure the interruptProcessingMode and
| queryTimeoutInterruptProcessingMode properties.

| These properties determine the behavior when an application issues a cancel

| request or a query timeout interval is reached.

Procedure

To cancel SQL statements that are running on a remote Db2 for z/OS server:

| Issue an SQLCancel() function for C-based driver applications or a

| Statement.cancel method for Java-based driver applications.

| Note: A client driver can implicitly cancel an SQL statement when the query
| timeout interval is reached.

| Results

When you cancel an SQL statement from a client application, you do not eliminate
the original connection to the remote server. The original connection remains active
to process additional SQL requests. Any cursor that is associated with the canceled
statement is closed, and the Db2 server returns an SQLCODE of -952 to the client
application when you cancel a statement by using this method.

You can cancel only dynamic SQL codes that excludes transaction-level statements
(CONNECT, COMMIT, ROLLBACK) and bind statements from a client application.
Related reference:
SQLCancel function (CLI) - Cancel statement
Configuration of Sysplex workload balancing for non-Java clients
InterruptProcessingMode IBM Data Server Driver configuration keyword
Driver support for JDBC APIs

Chapter 8. Monitoring and controlling Db2 and its connections 343

 Common IBM Data Server Driver for JDBC and SQLJ properties
Configuration of Sysplex workload balancing for Java clients

Canceling threads
You can use the CANCEL THREAD command to terminate threads that are active
or suspended in Db2.

Before you begin

Using the CANCEL THREAD command requires SYSOPR authority or higher.

About this task

The command has no effect if the thread is not active or suspended in Db2.

If the thread is processing in VTAM or TCP/IP, you can use VTAM or

TCP/IP commands to terminate the conversations.

You can use the DISPLAY THREAD command to determine if a thread is hung in
Db2 or VTAM. In VTAM, there is no reason to use the CANCEL command.

Procedure

To terminate a thread, enter one of the following commands:

v To cancel a thread with a token, enter:
-CANCEL THREAD (token)
v Alternatively, you can use the following version of the command with either the
token or LUW ID:
-CANCEL DDF THREAD (token or luwid)

Results

The token is a 1-character to 5-character number that identifies the thread result.
When Db2 schedules the thread for termination, the following message for a
distributed thread is issued:
DSNL010I - DDF THREAD token or luwid HAS BEEN CANCELED

For a non-distributed thread, you see the following message:

DSNV426I - csect THREAD token HAS BEEN CANCELED

As a result of entering CANCEL THREAD, the following messages can be

displayed:
DSNL009I
DSNL010I
DSNL022I

CANCEL THREAD allows you to specify that a diagnostic dump be taken.

Related concepts:
Obtaining Db2 Diagnosis Guide and Reference ()
Related reference:
-CANCEL THREAD (Db2) (Db2 Commands)

344 Administration Guide

 Effects of the CANCEL THREAD command:

A database access thread can be in the prepared state, waiting for the commit
decision from the coordinator. When you issue the CANCEL THREAD command
for a database access thread that is in the prepared state, the thread is converted
from active to indoubt status.

| A prepared thread is converted from active to indoubt status in the following

| circumstances:
| v A DRDA database access thread is in the prepared state and is waiting for the
| commit decision from the coordinator at the time a CANCEL THREAD
| command is issued.
| v An RRSAF thread is involved in a z/OS RRS coordinated two-phase commit
| with two or more resource managers at the time a CANCEL THREAD command
| is issued.

The conversation with the coordinator and all conversations with downstream
participants are terminated, and message DSNL450I is returned. The resources that
are held by the thread are not released until the indoubt state is resolved. This is
accomplished automatically by the coordinator or by using the command
RECOVER INDOUBT.

When the command is entered at the Db2 subsystem that has a database access
thread servicing requests from a Db2 subsystem that owns the allied thread, the
database access thread is terminated. Any active SQL request (and all later
requests) from the allied thread result in a "resource not available" return code.

Related tasks:
Resolving indoubt units of recovery

Monitoring and controlling stored procedures

Stored procedures, such as native SQL procedures, external SQL procedures, and
external stored procedures, are user-written programs that run at a Db2 server.

About this task

External SQL procedures and external stored procedures run in WLM-established

address spaces. To monitor and control stored procedures in WLM-established
address spaces, you might need to use WLM commands rather than Db2
commands. When you execute a WLM command on a z/OS system that is part of
a Sysplex, the scope of that command is the Sysplex.
Related tasks:
Creating a stored procedure (Db2 Application programming and SQL)

Displaying information about stored procedures with Db2 commands:

Use the DISPLAY PROCEDURE command and the DISPLAY THREAD command
to obtain information about a stored procedure while it is running.

Chapter 8. Monitoring and controlling Db2 and its connections 345

 About this task

Because native SQL procedures do not run in WLM-established address spaces, the
best way to monitor native SQL procedures is by using the START TRACE
command and specifying accounting class 10, which activates IFCID 239.
Related concepts:
Db2 trace output (Db2 Performance)
Related reference:
-START TRACE (Db2) (Db2 Commands)
-DISPLAY THREAD (Db2) (Db2 Commands)
-DISPLAY PROCEDURE (Db2) (Db2 Commands)

Displaying statistics about stored procedures:

Issue the DISPLAY PROCEDURE command to display statistics about stored

procedures that are accessed by Db2 applications.

About this task

This command can display the following information about stored procedures:
v Status (started, stop-queue, stop-reject, or stop-abend)
v Number of requests that are currently running and queued
v Maximum number of threads that are running a stored procedure load module
and queued
v Count of timed-out SQL CALLs

Procedure

To display information about all stored procedures in all schemas that have been
accessed by Db2 applications:

Issue the DISPLAY PROCEDURE command.

For example:
-DISPLAY PROCEDURE

Note: To display information about a native SQL procedure, you must run the
procedure in DEBUG mode. If you do not run the native SQL procedure in
DEBUG mode (for example, in a production environment), the DISPLAY
PROCEDURE command will not return output for the procedure.

If you do run the procedure in DEBUG mode the WLM environment column in
the output contains the WLM ENVIRONMENT FOR DEBUG that you specified
when you created the native SQL procedure. The DISPLAY PROCEDURE output
shows the statistics of native SQL procedures as '0' if the native SQL procedures
are under the effect of a STOP PROCEDURE command.

346 Administration Guide

Example

The following example shows two schemas (PAYROLL and HRPROD) that have
been accessed by Db2 applications. You can also display information about specific
stored procedures.
DSNX940I csect - DISPLAY PROCEDURE REPORT FOLLOWS-
------ SCHEMA=PAYROLL
PROCEDURE STATUS ACTIVE QUED MAXQ TIMEOUT FAIL WLM_ENV
PAYRPRC1
STARTED 0 0 1 0 0 PAYROLL
PAYRPRC2
STOPQUE 0 5 5 3 0 PAYROLL
PAYRPRC3
STARTED 2 0 6 0 0 PAYROLL
USERPRC4
STOPREJ 0 0 1 0 1 SANDBOX
------ SCHEMA=HRPROD
PROCEDURE STATUS ACTIVE QUED MAXQ TIMEOUT FAIL WLM_ENV
HRPRC1
STARTED 0 0 1 0 1 HRPROCS
HRPRC2
STOPREJ 0 0 1 0 0 HRPROCS
DISPLAY PROCEDURE REPORT COMPLETE
DSN9022I = DSNX9COM ’-DISPLAY PROC’ NORMAL COMPLETION

Related reference:
-DISPLAY PROCEDURE (Db2) (Db2 Commands)

Displaying thread information about stored procedures:

Issue the DISPLAY THREAD command to display thread information about stored
procedures.

About this task

This command tells whether:

v A thread is waiting for a stored procedure to be scheduled.
v A thread is executing within a stored procedure.

Procedure

To display active threads that are running stored procedures and

user-defined functions:

Issue the DISPLAY THREAD command. For example:

-DISPLAY THREAD(*) TYPE(PROC)

Chapter 8. Monitoring and controlling Db2 and its connections 347

 Example

Example 1: The following example of output from the DISPLAY THREAD

command shows a thread that is executing an external SQL procedure or an
external stored procedure.
-display thread(*) type(proc) detail
DSNV401I ! DISPLAY THREAD REPORT FOLLOWS -
DSNV402I ! ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH SP 3 CALLWLM SYSADM PLNAPPLX 0022 5
V436-PGM=*.MYPROG, SEC=2, STMNT=1
V429 CALLING PROCEDURE=SYSADM .WLMSP ,
PROC=V61AWLM1, ASID=0085, WLM_ENV=WLMENV1
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I ! DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

The SP status indicates that the thread is executing within the stored procedure. An
SW status indicates that the thread is waiting for the stored procedure to be
scheduled.

Example 2: This example of output from the DISPLAY THREAD command shows
a thread that is executing a native SQL procedure. If you do not specify the
DETAIL option, the output will not include information that is specific to the
stored procedure.

Issuing the command -display thread(*) type(proc) detail results in the

following output:
SERVER RA * 22325 driver.exe USRT010 DISTSERV 0067 8
V437-WORKSTATION=CALADAN, SERID=USRT010,
APPLICATION NAME=driver.exe
V436-PGM=USRT010.MARKETWATCH_F1, SEC=3, STMNT=39
V442-CRTKN=9.30.129.213.15369.090129190416
V445-G91E81D8.C3B9.C3AB43861A26=8 ACCESSING DATA FOR
( 1)::FFFF:9.30.129.213
V447--INDEX SESSID A ST TIME V448--( 1) 50105:2364 W S2 902911191075

Example 3: The following example of output from the DISPLAY THREAD

command shows a thread that is executing a user-defined function.
-display thread(*) type(proc) detail
DSNV401I ! DISPLAY THREAD REPORT FOLLOWS -
DSNV402I ! ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH SP 27 LI33FN1 SYSADM MYPLAN 0021 4
V436-PGM=*.MYPROG, SEC=2, STMNT=1
V429 CALLING FUNCTION =SYSADM .FUNC1 ,
PROC=V61AWLM1, ASID=0085, WLM_ENV=WLMENV1
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I ! DSNVDT ’-DISPLAY THD’ NORMAL COMPLETION
Related reference:
-DISPLAY THREAD (Db2) (Db2 Commands)

Determining the status of an application environment:

Use the z/OS command DISPLAY WLM to determine the status of an application
environment in which a stored procedure runs.

348 Administration Guide

About this task

The output from the DISPLAY WLM command lets you determine whether a
stored procedure can be scheduled in an application environment.

For example, you can issue this command to determine the status of application
environment WLMENV1:
D WLM,APPLENV=WLMENV1

Results

You might get results like the following:

IWM029I 15.22.22 WLM DISPLAY
APPLICATION ENVIRONMENT NAME STATE STATE DATA
WLMENV1 AVAILABLE
ATTRIBUTES: PROC=DSNWLM1 SUBSYSTEM TYPE: DB2

The output indicates that WLMENV1 is available, so WLM can schedule stored
procedures for execution in that environment.

Refreshing WLM application environments for stored procedures:

When you make certain changes to a stored procedure or to the JCL startup
procedure for a WLM application environment, you need to refresh the WLM
application environment.

Before you begin

Before you refresh a WLM application environment, ensure that WLM is operating
in goal mode.

About this task

Refreshing the WLM environment starts a new instance of each address space that
is active for the WLM environment. Existing address spaces stop when the current
requests that are executing in those address spaces complete.

Refresh the WLM application environment if any of the following situations are
true:
v For external procedures (including external SQL procedures), you changed the
stored procedure logic, the load module, or the CREATE PROCEDURE
definition.
v For a Java stored procedure, you changed the properties that are pointed to by
the JAVAENV data set.
v You changed the JCL startup procedure for the WLM application environment.

Restriction: In some cases, refreshing the WLM environment might not be

sufficient to incorporate your change. For example, assume that you changed the
NUMTCB value in the JCL. The refresh fails because WLM cannot start a new
WLM address space that has a different NUMTCB value as the existing one. In
this case, you need to quiesce the WLM environment while you change the JCL
startup procedure, and resume the environment when your changes are
complete.

Chapter 8. Monitoring and controlling Db2 and its connections 349

 If you create a procedure that uses an existing WLM environment, you do not
need to refresh the WLM environment.

Procedure

To refresh a WLM application environment for stored procedures:

Perform one of the following actions:

v Call the WLM_REFRESH stored procedure.
v Issue the following z/OS command:
VARY WLM,APPLENV=environment-name,REFRESH
In this command, environment-name is the name of a WLM application
environment that is associated with one or more stored procedures. The
application environment is refreshed to incorporate the changed load modules
for all stored procedures and user-defined functions in the particular
environment.
Alternatively, when you make certain changes to the JCL startup procedure, you
must quiesce and then resume the WLM application environment rather than
refresh it. For these types of changes, use the following z/OS commands:
1. To stop all stored procedures address spaces that are associated with the WLM
application environment name, use the following z/OS command:
VARY WLM,APPLENV=name,QUIESCE

The address spaces stop when the current requests that are executing in those
address spaces complete.
This command puts the WLM application environment in QUIESCED state.
When the WLM application environment is in QUIESCED state, the stored
procedure requests are queued. If the WLM application environment is
restarted within a certain time, the stored procedures are executed. If a stored
procedure cannot be executed, the CALL statement returns SQL code -471 with
reason code 00E79002.
2. To restart all stored procedures address spaces that are associated with WLM
application environment name, use the following z/OS command:
VARY WLM,APPLENV=name,RESUME
New address spaces start when all JCL changes are established. Until that time,
work requests that use the new address spaces are queued.
Also, you can use the VARY WLM command with the RESUME option when
the WLM application environment is in the STOPPED state due to a failure.
This state might be the result of a failure when starting the address space, or
because WLM detected five abnormal terminations within 10 minutes. When an
application environment is in the STOPPED state, WLM does not schedule
stored procedures for execution in it. If you try to call a stored procedure when
the WLM application environment is in the STOPPED state, the CALL
statement returns SQL code -471 with reason code 00E7900C. After correcting
the condition that caused the failure, you need to restart the application
environment.
Related concepts:
WLM management of stored procedures (Db2 Installation and Migration)
Related tasks:
Setting up a WLM application environment for stored procedures during
installation (Db2 Installation and Migration)

350 Administration Guide

Related reference:
WLM_REFRESH stored procedure (Db2 SQL)
CREATE PROCEDURE (SQL - native) (Db2 SQL)
Related information:
Using Operator Commands for Application Environments (z/OS MVS
Planning: Workload Management)

Refreshing WLM environments for stored procedures automatically:

You can enable automatic refreshes for WLM environments for stored procedures.

Before you begin

If a security product is configured to authorize MVS console commands, you must

grant authorization for the Db2 ssnmMSTR address space to issue MVS
commands.

Procedure

To enable automatic refreshes of WLM environments for stored procedures:

Add the following DD statement to the startup procedure for the WLM-established
stored procedure address space:
//AUTOREFR DD DUMMY

Db2 saves the environment name in a list of environments to refresh automatically.

If the z/OS Resource Recovery Services (RSS) environment is recycled, but Db2
and the its associated WLM-established stored procedures address space are not
restarted, Db2 issues the following z/OS command to refresh each environment
that is named in the list:
VARY WLM,APPLENV=environment-name,REFRESH

Recommendation: To prevent the automatic issuing of duplicate and unnecessary

VARY WLM,APPLENV=applenvname commands, limit the number of startup procedures
that contain the //AUTOREFR DD statement . The WLM,APPLENV=applenvname
command has a Sysplex scope, which means that it affects all servers of an
application environment on all systems in the Sysplex. The result is that every Db2
subsystem issues its own WLM,APPLENV=applenvname command for each application
environment that is nominated by the //AUTOREFR DD statement in its startup
procedure.
Related concepts:
WLM management of stored procedures (Db2 Installation and Migration)
WLM address space startup procedure for Java routines (Db2 Application
Programming for Java)
Related tasks:
Assigning stored procedures and functions to WLM application environments
(Db2 Performance)
Refreshing WLM application environments for stored procedures
Defining application environments (MVS Planning: Workload Management)

Chapter 8. Monitoring and controlling Db2 and its connections 351

 Obtaining diagnostic information and debugging stored procedures:

You have several options for obtaining diagnostic information and debugging
stored procedures, depending on the type of stored procedure.

Procedure

To obtain diagnostic information and debug stored procedures:

Take the appropriate action, depending on the type of stored procedure that you
use.

Type of stored procedure Actions

All types of stored procedures v Look at the diagnostic information in
CEEDUMP. If the startup procedures for
your stored procedures address spaces
contain a DD statement for CEEDUMP,
Language Environment writes a small
diagnostic dump to CEEDUMP when a
stored procedure terminates abnormally.
The output is printed after the stored
procedures address space terminates. You
can obtain the dump information by
stopping the stored procedures address
space in which the stored procedure is
running.
v Debug the stored procedure as a
stand-alone program on a workstation.
v Record stored procedure debugging
messages to a disk file or JES spool file by
using the Language Environment
MSGFILE run time option.
v Store debugging information in a table.
This option works well for remote stored
procedures.
C stored procedures Use Debug Tool for z/OS.
C++ stored procedures Use Debug Tool for z/OS.
COBOL stored procedures Use Debug Tool for z/OS.
External applications Use a driver application.
External SQL procedures v Use the Unified Debugger.
v Use the Db2 stored procedure debugger,
which is part of IBM Data Studio.
Java stored procedures v Use the Unified Debugger.
v Use the Db2 stored procedure debugger,
which is part of IBM Data Studio.

352 Administration Guide

Type of stored procedure Actions
Native SQL procedures Use the GET DIAGNOSTICS statement. The
DB2_LINE_NUMBER parameter returns:
v The line number where an error is
encountered in parsing, binding, or
executing a CREATE or ALTER statement
for a native SQL procedure.
v The line number when a CALL statement
invokes a native SQL procedure and the
procedure returns with an error.
This information is not returned for an
external SQL procedure, and this value is
meaningful only if the statement source
contains new line control characters.

What to do next

Remember: After you finish debugging stored procedures, remember to disable

the debugging option that you used, so that you do not run debugging tools in a
production system.
Related tasks:
Refreshing WLM application environments for stored procedures
Related reference:
IBM Data Studio product documentation (IBM Data Studio, IBM Optim
Database Administrator, IBM infoSphere Data Architect)
Debug Tool for z/OS

Migrating stored procedures from test to production:

After developing and testing a stored procedure, you can migrate it from a test
environment to production.

About this task

The process that you follow to migrate a stored procedure from a test environment
to production depends on the type of stored procedure that you want to migrate.
The process that you follow also depends on the change management policy of
your site. You can migrate a native SQL procedure, an external SQL procedure, or
an external stored procedure. You also can choose to recompile to create new object
code and a new package on the production server, or you can choose not to
recompile.
Related tasks:
Implementing Db2 stored procedures

Migrating native SQL procedures from test to production:

Migrating native SQL procedures from a test environment to production is a

straightforward process.

Chapter 8. Monitoring and controlling Db2 and its connections 353

 About this task

Because native SQL procedures do not contain load modules that need to be
link-edited or WLM address spaces that need to be refreshed, you do not need to
determine whether you want to recompile to create new object code and a new
package on the production server.

Procedure

To migrate a native SQL procedure from a test environment to production:

Deploy the native SQL procedure to the new server.

Migrating external SQL procedures from test to production:

Use IBM Data Studio to migrate external SQL procedures from a test environment
to production.

About this task

External SQL procedures are usually built by using IBM Data Studio.

Procedure

To migrate an external SQL procedure from a test environment to production:

Use IBM Data Studio to deploy the stored procedure. The binary deploy capability
in IBM Data Studio promotes external SQL procedures without recompiling. The
binary deploy capability copies all necessary components from one environment to
another and performs the bind in the target environment.

Migrating external stored procedures from test to production:

Use the CREATE PROCEDURE statement to migrate external stored procedures

from a test environment to a production environment.

About this task

For Java stored procedures, you also can use IBM Data Studio to do a binary
deploy of the stored procedure. The binary deploy capability promotes Java stored
procedures without recompiling. The binary deploy capability copies all necessary
components from one environment to another and performs the bind in the target
environment.

Procedure

To migrate an external stored procedure from a test environment to

production:
1. Determine the change management policy of your site. You can choose to
recompile to create new object code and a new package on the production
server, or you can choose not to recompile.

354 Administration Guide

 2. Depending on your change management policy, complete the appropriate task.
v To migrate the stored procedure without recompiling:
a. Copy the CREATE PROCEDURE statement.
b. Modify the CREATE PROCEDURE statement to reflect the new schema,
new collection ID and new WLM application environment.
c. Define the stored procedure with the new CREATE PROCEDURE
statement. You can use the IBM-supplied programs DSNTIAD or
DSNTEP2.

Note: Make sure that the schema, collection ID and WLM application
environment correspond to the new environment or code level.
d. Copy the DBRM and bind the DBRM to produce a Db2 package.

Note: Make sure that the collection ID of the BIND statement and
collection ID of the CREATE PROCEDURE statement are the same.
e. Copy the load module and refresh the WLM application environment.
v To migrate the stored procedure and recompile to create new object code and
a new package on the production server:
a. Copy the CREATE PROCEDURE statement.
b. Modify the CREATE PROCEDURE statement to reflect the new schema,
new collection ID and new WLM application environment.
c. Define the stored procedure with the new CREATE PROCEDURE
statement. You can use the IBM-supplied programs DSNTIAD or
DSNTEP2.

Note: Make sure that the schema, collection ID and WLM application
environment correspond to the new environment or code level.
d. Copy the source code.
e. Precompile, compile, and link-edit. This step produces a DBRM and a
load module.
f. Bind the DBRM to produce a Db2 package.

Note: Make sure that the collection ID of the BIND statement and
collection ID of the CREATE PROCEDURE statement are the same.
g. Refresh the WLM application environment.

| Controlling autonomous procedures

| Autonomous procedures use a unit of work that is independent of the calling
| application. However, you can cancel the autonomous procedure by canceling the
| invoking thread.

| Procedure

|
|
| To control autonomous procedures:
| 1. Issue a DISPLAY THREAD command to find the status of the autonomous
| procedure and the token for the invoking thread. The token for the thread is

Chapter 8. Monitoring and controlling Db2 and its connections 355

| shown in a DSNV520I message. The following example output from a DISPLAY
| THREAD command shows that an autonomous procedure was invoked by the
| thread with the token 13:
| 19.26.27 >dis thd(*) service(stg)
| 19.26.27 STC00065 DSNV401I > DISPLAY THREAD REPORT FOLLOWS -
| 19.26.27 STC00065 DSNV402I > ACTIVE THREADS -
| NAME ST A REQ ID AUTHID PLAN ASID TOKEN
| BATCH RA * 1 TMH11003 SYSADM PLAN2 003D 13
| V492-LONG 12K 64VLONG 196K 64LONG 200K ;
| V442-CRTKN=USIBMSY.SYEC1DB2.C760EC93ED89 ;
| V445-USIBMSY.SYEC1DB2.C760EC93ED89=13 ACCESSING DATA FOR
| <SYEC1DB2>-SYEC1DB2 ;
| BATCH AT * 0 TMH11003 SYSADM PLAN2 003D 0
| V520-AUTONOMOUS PROCEDURE INVOKED BY THREAD WITH TOKEN = 13
| V492-LONG 12K 64VLONG 136K 64LONG 260K ;
| DISPLAY ACTIVE REPORT COMPLETE
| 2. Issue a CANCEL THREAD command to cancel the thread that invoked the
| autonomous procedure. For example, you might issue the following command
| to cancel the thread that invoked the autonomous procedure shown in the
| preceding example:
| -CANCEL THREAD (13)

|
|

| Results

| COMMIT and ROLLBACK operations that are applied within an autonomous

| procedure apply to all procedures and functions that are nested under the
| autonomous procedure.
| Related concepts:
| Autonomous procedures (Db2 Application programming and SQL)
| Related reference:
| -DISPLAY THREAD (Db2) (Db2 Commands)
| -CANCEL THREAD (Db2) (Db2 Commands)
| Related information:
| DSNV520I (Db2 Messages)

Monitoring DDF problems by using NetView

The NetView® program lets you have a single focal point from which to view
problems in the network. DDF sends an alert to NetView when a remote location
is either involved in the cause of the failure or affected by the failure.

About this task

To see the recommended action for solving a particular problem, enter the selection
number, and then press Enter. This displays the Recommended Action for Selected
Event panel, shown in the following figure.

356 Administration Guide

 N E T V I E W SESSION DOMAIN: CNM01 OPER2 11/03/89 10:30:06
NPDA-45A * RECOMMENDED ACTION FOR SELECTED EVENT * PAGE 1 OF 1
CNM01 AR ▌1▐ AS ▌2▐
+--------+ +--------+
DOMAIN RQST --- SRVR
+--------+ +--------+
USER CAUSED - NONE
INSTALL CAUSED - NONE
FAILURE CAUSED - SNA COMMUNICATIONS ERROR:
RCPRI=0008 RCSEC=0001 ▌1▐
FAILURE OCCURRED ON RELATIONAL DATA BASE USIBMSTODB21
ACTIONS - I008 - PERFORM PROBLEM DETERMINATION PROCEDURE FOR REASON
CODE ▌3▐00D31029 ▌2▐
I168 - FOR RELATIONAL DATA BASE USIBMSTODB22
REPORT THE FOLLOWING LOGICAL UNIT OF WORK IDENTIFIER
DB2NET.LUND0.A1283FFB0476.0001
ENTER DM (DETAIL MENU) OR D (EVENT DETAIL)

Figure 32. Recommended action for selected event panel in NetView. In this example, the AR
(USIBMSTODB21) reports the problem, which affects the AS (USIBMSTODB22).

Key Description
▌1▐ The system that is reporting the error. The system that is reporting the
error is always on the left side of the panel. That system name appears
first in the messages. Depending on who is reporting the error, either the
LUNAME or the location name is used.
▌2▐ The system that is affected by the error. The system that is affected by the
error is always displayed to the right of the system that is reporting the
error. The affected system name appears second in the messages.
Depending on what type of system is reporting the error, either the
LUNAME or the location name is used.
If no other system is affected by the error, this system does not appear on
the panel.
▌3▐ Db2 reason code.
Related concepts:
Obtaining Db2 Diagnosis Guide and Reference ()
Related reference:
IBM Tivoli NetView for z/OS User's Guide

DDF alerts:

Several major events generate alerts.

v Conversation failures
v Distributed security failures
v DDF abends
v DDM protocol errors
v Database access thread abends
v Distributed allied thread abends

Alerts for DDF are displayed on NetView Hardware Monitor panels and are
logged in the hardware monitor database. The following figure is an example of
the Alerts-Static panel in NetView.

Chapter 8. Monitoring and controlling Db2 and its connections 357

 N E T V I E W SESSION DOMAIN: CNM01 OPER2 11/03/89 10:29:55
NPDA-30B * ALERTS-STATIC *
SEL# DOMAIN RESNAME TYPE TIME ALERT DESCRIPTION:PROBABLE CAUSE
( 1) CNM01 AS *RQST 09:58 SOFTWARE PROGRAM ERROR:COMM/REMOTE NODE
( 2) CNM01 AR *SRVR 09:58 SOFTWARE PROGRAM ERROR:SNA COMMUNICATIONS
( 3) CNM01 P13008 CTRL 12:11 LINK ERROR:REMOTE DCE INTERFACE CABLE +
( 4) CNM01 P13008 CTRL 12:11 RLSD OFF DETECTED:OUTBOUND LINE
( 5) CNM01 P13008 CTRL 12:11 LINK ERROR:REMOTE DCE INTERFACE CABLE +
( 6) CNM01 P13008 CTRL 12:11 LINK ERROR:INBOUND LINE +
( 7) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
( 8) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
( 9) CNM01 P13008 CTRL 12:10 LINK ERROR:INBOUND LINE +
(10) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
(11) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
(12) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
(13) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
(14) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
(15) CNM01 P13008 CTRL 12:10 LINK ERROR:REMOTE DCE INTERFACE CABLE +
PRESS ENTER KEY TO VIEW ALERTS-DYNAMIC OR ENTER A TO VIEW ALERTS-HISTORY
ENTER SEL# (ACTION),OR SEL# PLUS M (MOST RECENT), P (PROBLEM), DEL (DELETE)

Figure 33. Alerts-static panel in NetView. DDF errors are denoted by the resource name AS
(server) and AR (requester). For Db2-only connections, the resource names are RS (server)
and RQ (requester).

Stopping DDF
You can stop the distributed data facility (DDF) if you have SYSOPR authority or
higher.

Procedure

To stop the DDF:

Use one of the following commands:

-STOP DDF MODE (QUIESCE)
-STOP DDF MODE (FORCE)

Results

The STOP DDF command causes the following messages to appear:

DSNL005I - DDF IS STOPPING
DSNL006I - DDF STOP COMPLETE

If the distributed data facility has already been stopped, the STOP DDF command
fails and message DSNL002I - DDF IS ALREADY STOPPED appears.

Stopping DDF using the QUIESCE option:

Stop DDF by using the QUIESCE option of the STOP DDF command whenever
possible. This option is the default.

About this task

With the QUIESCE option, the STOP DDF command does not complete
until all VTAM or TCP/IP requests have completed. In this case, no
resynchronization work is necessary when you restart DDF. If any indoubt units of
work require resynchronization, the QUIESCE option produces message DSNL035I.

358 Administration Guide

Use the FORCE option only when you must stop DDF quickly. Restart times are
longer if you use the FORCE option.

Procedure

To stop DDF with the QUIESCE option:

Issue the following command:

-STOP DDF MODE (QUIESCE)

Stopping DDF using the FORCE option:

Stop DDF by using the FORCE option of the STOP DDF command only when you
must stop DDF quickly.

About this task

When DDF is stopped with the FORCE option, and DDF has indoubt
thread responsibilities with remote partners, message DSNL432I, DSNL433I, or
both are issued.

DSNL432I shows the number of threads that DDF has coordination responsibility
over with remote participants who could have indoubt threads. At these
participants, database resources that are unavailable because of the indoubt threads
remain unavailable until DDF is started and resolution occurs.

DSNL433I shows the number of threads that are indoubt locally and need
resolution from remote coordinators. At the DDF location, database resources are
unavailable because the indoubt threads remain unavailable until DDF is started
and resolution occurs.

To force the completion of outstanding VTAM or TCP/IP requests, use the FORCE
option, which cancels the threads that are associated with distributed requests.

When the FORCE option is specified with STOP DDF, database access threads in
the prepared state that are waiting for the commit or abort decision from the
coordinator are logically converted to the indoubt state. The conversation with the
coordinator is terminated. If the thread is also a coordinator of downstream
participants, these conversations are terminated. Automatic indoubt resolution is
initiated when DDF is restarted.

Procedure

To stop DDF with the FORCE option:

Issue the following command:

-STOP DDF MODE (FORCE)

Chapter 8. Monitoring and controlling Db2 and its connections 359

 Stopping DDF using VTAM commands:

One way to force DDF to stop is to issue the VTAM VARY NET,INACT command.
This command makes VTAM unavailable and terminates DDF. VTAM forces the
completion of any outstanding VTAM requests immediately.

Procedure

To stop force DDF to stop:

Enter the following command:

VARY NET,INACT,ID=db2lu,FORCE

where db2lu is the VTAM LU name for the local Db2 system.
When DDF has stopped, you must issue the following command before you can
issue the START DDF command:
VARY NET,ACT,ID=db2lu

Controlling traces
Several traces are available for problem determination.

About this task

v Db2 trace
v IMS attachment facility trace
v CICS trace
v Three TSO attachment facility traces
v CAF trace stream
v RRS trace stream
v z/OS component trace used for IRLM
Related concepts:
Types of Db2 traces (Db2 Performance)

Diagnostic traces for attachment facilities

Several trace facilities provide diagnostic information.
v IMS provides a trace facility that shows the flow of requests across the
connections from the IMS control and IMS dependent regions to Db2. The trace
is recorded on the IMS log if the appropriate options are specified, and then it is
printed with DFSERA10 plus a formatting exit module.
In addition, the IMS attachment facility of Db2 provides an internal wraparound
trace table that is always active. When certain unusual error conditions occur,
these trace entries are externalized on the IMS log.
v You can use the CICS trace facility to trace the CICS attachment facility.
Use the transaction CETR to control the CICS trace facility. CETR provides a
series of menus that you can use to set CICS trace options to trace the CICS
attachment facility. For CICS 4.1 and later, set these values in the Component
Trace Options panel:
– For CICS 4.1, specify the value 2 in the FC field.
– For later releases, specify the value 2 in the RI field.
v The TSO attachment facility provides three tracing mechanisms:
The DSN trace stream

360 Administration Guide

 The CLIST trace facility
The SPUFI trace stream
v The call attachment facility trace stream uses the same ddname as the TSO DSN
trace stream, but is independent of TSO.
v The RRSAF trace stream uses the same ddname as the TSO DSN trace stream, but
is independent of TSO. An RRSAF internal trace is included in any ABEND
dump that is produced by RRSAF. This tracing facility provides a history of
RRSAF usage that can aid in diagnosing errors in RRSAF.
Related concepts:
CICS Transaction Server for z/OS Supplied Transactions

Controlling the Db2 trace

Db2 provides commands for controlling the collection of trace data.

Before you begin

To use the trace commands, you must have one of the following types of authority:
v SYSADM or SYSOPR authority
v Authorization to issue start and stop trace commands (the TRACE privilege)
v Authorization to issue the display trace command (the DISPLAY privilege)

Procedure

To issue trace commands:

Select the appropriate command for the action that you want to take. The trace
commands include:
START TRACE
Invokes one or more different types of trace.
DISPLAY TRACE
Displays the trace options that are in effect.
STOP TRACE
Stops any trace that was started by either the START TRACE command or
as a result of the parameters that were specified during installation or
migration.
MODIFY TRACE
Changes the trace events (IFCIDs) that are being traced for a specified
active trace.

You can specify several parameters to further qualify the scope of a trace. You can
trace specific events within a trace type as well as events within specific Db2 plans,
authorization IDs, resource manager IDs, and locations. You can also control where
trace data is sent.
When you install Db2, you can request that any trace type and class start
automatically when Db2 starts.

Related concepts:

Chapter 8. Monitoring and controlling Db2 and its connections 361

 Types of Db2 traces (Db2 Performance)
Related tasks:
Minimizing the volume of Db2 trace data (Db2 Performance)
Related reference:
DSNTIPN: Tracing parameters panel (Db2 Installation and Migration)
-START TRACE (Db2) (Db2 Commands)
-DISPLAY TRACE (Db2) (Db2 Commands)
-STOP TRACE (Db2) (Db2 Commands)
-MODIFY TRACE (Db2) (Db2 Commands)

Diagnostic trace for the IRLM

You can control diagnostic traces for the IRLM using z/OS commands.
MODIFY irlmproc,SET,TRACE
Dynamically sets the maximum number of trace buffers for each trace type.
IRLM uses this value only when the external component trace writer is not
activated.
MODIFY irlmproc,STATUS,TRACE
Displays the status of traces and the number of trace buffers that are used
for each trace type. Also displays indication of whether the external
component trace writer is active for the trace.
START irlmproc,TRACE=YES
Captures traces in wrap-around IRLM buffers at IRLM startup.
TRACE CT
Starts, stops, or modifies a diagnostic trace for IRLM. The TRACE CT
command acts independently of traces that are started automatically
during IRLM startup.

Recommendations:
v Do not use the external component trace writer to write traces to the data set.
v Activate all traces during IRLM startup. Use the following command to activate
all traces:
START irlmproc,TRACE=YES
Related information:
Command types and environments in Db2 (Db2 Commands)

Setting the priority of stored procedures

Stored procedure priority is inherited from the caller. The stored procedure always
runs at the dispatching priority of whatever called it.

About this task

For example, if you call a stored procedure from CICS, it runs at CICS priority. If
you call a stored procedure from batch, it runs at batch priority. If you call a stored
procedure from DDF, it runs at DDF priority.

362 Administration Guide

 Procedure

To set stored procedure priority:

1. When you set up WLM, ensure that the WLM address spaces are set up with
the default started task priority. WLM address spaces that use the default
started task priority perform system administrative work more efficiently.
2. Set up your service classes for the regular Db2 threads according to the priority
that you want to give to the stored procedure callers. The stored procedure has
the same priority as its caller.
Related tasks:
Setting up a WLM application environment for stored procedures during
installation (Db2 Installation and Migration)
Setting performance objectives for distributed workloads by using z/OS
Workload Manager (Db2 Performance)

| Setting special registers with profiles

| You can create profiles to specify that Db2 sets certain special register values for
| remote applications that meet the criteria that are defined in the profile.

| Before you begin

|
PSPI
|
| Before you can use profiles to set special registers, you must create a set of profile
| tables on the Db2 subsystem.

| The profile tables and related indexes are created when you run job DSNTIJSG
| during Db2 installation or migration.

| A complete set of profile tables and related indexes includes the following objects:
| v SYSIBM.DSN_PROFILE_TABLE
| v SYSIBM.DSN_PROFILE_HISTORY
| v SYSIBM.DSN_PROFILE_ATTRIBUTES
| v SYSIBM.DSN_PROFILE_ATTRIBUTES_HISTORY
| v SYSIBM.DSN_PROFILE_TABLE_IX_ALL
| v SYSIBM.DSN_PROFILE_TABLE_IX2_ALL
| v SYSIBM.DSN_PROFILE_ATTRIBUTES_IX_ALL

| About this task

| You can use profile tables to set the value of certain Db2 special registers that are
| listed in Rules for setting special registers in the profile table.

| Procedure

| To use profiles that modify special register values that can affect the behavior of
| dynamic SQL statements:
| 1. Create a profile by inserting rows in DSN_PROFILE_TABLE. The row defines
| the scope of the profile for the special register setting.

Chapter 8. Monitoring and controlling Db2 and its connections 363

| When more than one profile applies to a thread or connection, the evaluation of
| the different profiles is not simultaneous. Instead, the profiles are evaluated in
| the following order, according to the criteria that are specified in the profile.
| a. IP address or domain name, in the LOCATION column.
| b. Product identifier, in the PRDID column.
| c. Role and authorization identifier, in both ROLE and AUTHID columns.
| d. Role, in the ROLE column only.
| e. Authorization identifier, in the AUTHID column only.
| f. Server location name, location alias, or database name, in the LOCATION
| column.
| g. The location name of a requester, for monitored threads from a Db2 for
| z/OS requester, in the LOCATION column.
| h. Collection identifier and package name, in both COLLID and PKGNAME
| columns.
| i. Collection identifier, in the COLLID column only.
| j. Package name, in the PKGNAME column only.
| k. Client application name, in the CLIENT_APPLNAME column.
| l. Client user identifier, in the CLIENT_USERID column.
| m. Client workstation name, in the CLIENT_WRKSTNNAME column.
| Only the first evaluated applicable profile is applied. Because the evaluation of
| multiple profiles is not simultaneous, the number of connections or threads on
| the subsystem might change during the evaluation of multiple profiles.
| 2. Specify the special register that you want to set by inserting a row into
| SYSIBM.DSN_PROFILE_ATTRIBUTES with the following column values:
| PROFILE ID column
| Specify the profile that defines the scope of statements to which you want
| the subsystem parameter to apply. Use a value from the PROFILEID
| column in SYSIBM.DSN_PROFILE_TABLE.
| KEYWORDS column
| SPECIAL_REGISTER
| ATTRIBUTE1 column
| Specify the SET special register statement
| Example: Suppose that you insert the row in the following table into
| SYSIBM.DSN_PROFILE_ATTRIBUTES:
| Table 41. Sample data in SYSIBM.DSN_PROFILE_ATTRIBUTES.
| PROFILEID KEYWORDS ATTRIBUTE1 ATTRIBUTE TIMESTAMP
| 17 SPECIAL_REGISTER SET CURRENT 2013-10-23...
| APPLICATION
| COMPATIBILITY = 'V10R1'
|
| This row specifies that Db2 is to set the APPLICATION COMPATIBILITY
| special register to 'V10R1' when referenced by dynamic SQL in the application
| that is included in profile 17.
| 3. Load or reload the profile tables into memory by issuing the following
| command:
| START PROFILE
| Any rows with a Y in the PROFILE_ENABLED column in
| SYSIBM.DSN_PROFILE_TABLE are now in effect. Db2 applies the values for
| the specified parameters to the statements in the specified profile.

364 Administration Guide

| 4. When you no longer want Db2 to use the parameter values that you specified
| in the profile tables, disable the values with one of the following actions:
|| Option Description
| To disable the parameter values for a Delete that row from
| specific profile DSN_PROFILE_TABLE, or change the
| PROFILE_ENABLED column value to N.
| Then, reload the profile table by issuing the
| following command:
| START PROFILE
| To disable all actions that are specified in Issue the following command:
|| the profile tables STOP PROFILE
|
|
PSPI
|
| Related concepts:
| Profiles for monitoring and controlling Db2 for z/OS subsystems (Db2
| Performance)
| Related reference:
| Profile tables (Db2 Performance)

Chapter 8. Monitoring and controlling Db2 and its connections 365

366 Administration Guide
 Chapter 9. Managing the log and the bootstrap data set
The Db2 log registers data changes and significant events as they occur. The
bootstrap data set (BSDS) contains information about the data sets that contain the
log. You can perform a variety of tasks to ensure that Db2 logging satisfies the
needs of your environment.

About this task

Db2 writes each log record to a disk data set called the active log. When the active
log is full, Db2 copies its contents to a disk or tape data set called the archive log.
That process is called offloading.

| At migration to Db2 12, you cannot start Db2 12 until the BSDS is converted to use
| the 10-byte RBA and LRSN formats. You can convert the BSDS before or during the
| Db2 12 migration process.
Related information:
Reading log records

How database changes are made

Before you can fully understand how logging works, you need to be familiar with
how database changes are made to ensure consistency.

This section discusses units of recovery and rollbacks.

Units of recovery and points of consistency

A unit of recovery begins with the first change to the data after the beginning of the
job, or following the last point of consistency. The unit of recovery ends at a later
point of consistency.

A unit of recovery is the work that changes Db2 data from one point of consistency
to another. This work is done by a single Db2 DBMS for an application. The point
of consistency (also referred to as sync point or commit point) is a time when all
recoverable data that an application program accesses is consistent with other data.

The following figure shows an example of units of recovery within an application

program.

© Copyright IBM Corp. 1982, 2017 367

 Application process

Unit of recovery
SQL transaction 1 SQL transaction 2

Time
line

Application SQLT1 SQLT1 SQLT2 SQLT2 Commit Application

process begins ends begins ends (point of process
begins consistency) ends

Figure 34. A unit of recovery within an application process

In this example, the application process makes changes to databases at SQL

transactions 1 and 2. The application process can include a number of units of
recovery or just one, but any complete unit of recovery ends with a commit point.

For example, a bank transaction might transfer funds from account A to account B.
First, the program subtracts the amount from account A. Next, it adds the amount
to account B. After subtracting the amount from account A, the two accounts are
inconsistent. These accounts are inconsistent until the amount is added to account
B. When both steps are complete, the program can announce a point of consistency
and thereby make the changes visible to other application programs.

Normal termination of an application program automatically causes a point of

consistency. The SQL COMMIT statement causes a point of consistency during
program execution under TSO. A sync point causes a point of consistency in CICS
and IMS programs.
Related concepts:
Multiple system consistency

How Db2 rolls back work

If failure occurs within a unit of recovery, Db2 rolls back (backs out) any changes
to data. Rolling back returns the data to its state at the start of the unit of recovery;
that is, Db2 undoes the work.

For a partition-by-growth table space, if a new partition was added in the unit of
recovery, any uncommitted updates can be backed out, but the physical partition is
not deleted.

The events are shown in the following figure.

368 Administration Guide

 Point of New point of
consistency consistency

One unit of recovery

Time
Database updates Back out updates
line

Begin unit Begin Data is returned to

of recovery rollback its initial state; end
unit of recovery

Figure 35. Unit of recovery (rolling back)

The possible events that trigger "Begin rollback" in this figure include:
v SQL ROLLBACK statement
v Deadlock (reported as SQLCODE -911)
v Timeout (reported as SQLSTATE 40001)

The effects of inserts, updates, and deletes to large object (LOB) values are backed
out along with all the other changes that were made during the unit of work that
is being rolled back, even if the LOB values that were changed reside in a LOB
table space that has the LOG NO attribute.

An operator or an application can issue the CANCEL THREAD command with the
NOBACKOUT option to cancel long-running threads without backing out data
changes. Db2 backs out changes to catalog and directory tables regardless of the
NOBACKOUT option. As a result, Db2 does not read the log records and does not
write or apply the compensation log records. After CANCEL THREAD
NOBACKOUT processing, Db2 marks all objects that are associated with the
thread as refresh-pending (REFP) and puts the objects in a logical page list (LPL).

The NOBACKOUT request might fail for either of the following two reasons:
v Db2 does not completely back out updates of the catalog or directory (message
DSNI032I with reason 00C900CC).
v The thread is part of a global transaction (message DSNV439I).

Related reference:
REFRESH-pending status (Db2 Utilities)

How the initial Db2 logging environment is established

The initial Db2 logging environment is established during installation of Db2.

Installation panels enable you to specify options, such as whether to have dual
active logs (strongly recommended), what media to use for archive log volumes,
and how many log buffers to have.
Related reference:
DSNTIPH: System resource data set names panel (Db2 Installation and
Migration)

Chapter 9. Managing the log and the bootstrap data set 369
 How Db2 creates log records
Log records typically go through a standard life cycle.
1. Db2 registers changes to data and significant events in recovery log records.
2. Db2 processes recovery log records and breaks them into segments if necessary.
| 3. Log records are placed sequentially in output log buffers, which are formatted as
| VSAM control intervals (CIs). Each log record is identified by a continuously
| increasing RBA. For basic 6-byte RBA format, the range is 0 to 248-1, where 248
| represents 2 to the 48th power. For extended 10-byte RBA format, the range is 0
| to 280-1, where 280 represents 2 to the 80th power. (In a data sharing
| environment, a log record sequence number (LRSN) is also used to identify log
| records.)
4. The CIs are written to a set of predefined disk active log data sets, which are
used sequentially and recycled.
5. As each active log data set becomes full, its contents are automatically offloaded
to a new archive log data set.

If you change or create data that is compressed, the data logged is also
compressed. Changes to compressed rows that result from inserts, updates, and
deletes are also logged as compressed data. Updates to compressed indexes are not
logged as compressed data.

How Db2 writes the active log

Db2 writes the log buffers to an active log data set in response to several
conditions. The most common condition is that the Db2 subsystem forces the log
buffer to be written.

Db2 also writes the log buffers to an active log data set when they become full, or
when the write threshold is reached.

When Db2 forces the log buffer to be written (such as at commit time), the same
control interval can be written several times to the same location.

Be sure to set your subsystem parameters so that there are enough log buffers to
avoid the need to wait for a buffer to become available (DSN6LOGP OUTBUFF
parameter). Switching log data sets may also cause a temporary performance
impact when the switch takes place and the associated recovery checkpoint is
taken. This can be minimized by ensuring that the active log data sets are large
enough to avoid frequent switching. In addition, some events can cause log buffers
to be written before the ZPARM-defined threshold has been reached. These events
include, but are not limited to:
v Phase 1 commit
v Abort processing
v GBP-dependent index split
v Mass delete in a data-sharing environment
v Use of GBPCACHE NO
v All log buffers being filled

Consider the probable frequency of these events when you determine how often to
commit changes.

When Db2 is initialized, the active log data sets that are named in the BSDS are
dynamically allocated for exclusive use by Db2 and remain allocated exclusively to

370 Administration Guide

 Db2 (the data sets were allocated as DISP=OLD) until Db2 terminates. Those active
log data sets cannot be replaced, nor can new ones be added, without terminating
and restarting Db2. The size and number of log data sets is indicated by what was
specified by installation panel DSNTIPL. The use of dual active logs increases
availability as well as the reliability of recovery by eliminating a single point of
failure.

How Db2 writes (offloads) the archive log

The process of copying active logs to archive logs is called offloading.

The relationship of offloading to other logging events is shown schematically in the

following figure.

Write to Triggering
active log event

Offload
process
Write to
archive log

Record on
BSDS

Figure 36. The offloading process

During the process, Db2 determines which data set to offload. Using the last log
relative byte address (RBA) that was offloaded, as registered in the BSDS, Db2
calculates the log RBA at which to start. Db2 also determines the log RBA at which
to end, from the RBA of the last log record in the data set, and registers that RBA
in the BSDS.

When all active logs become full, the Db2 subsystem runs an offload and halts
processing until the offload is completed. If the offload processing fails when the
active logs are full, Db2 cannot continue doing any work that requires writing to
the log.
Related information:
Recovering from active log failures

What triggers an offload

An offload of an active log to an archive log can be triggered by several events.

The most common situations that trigger an offload include:

v An active log data set is full.
v Db2 starts, but an active log data set is full.
v The ARCHIVE LOG command is issued.

An offload can be also triggered by two uncommon events:

v An error occurs while writing to an active log data set. The data set is truncated
before the point of failure, and the record that failed to write becomes the first
record of the next data set. An offload is triggered for the truncated data set as
in a normal end-of-file condition. With dual active logs, both copies are
truncated so the two copies remain synchronized.
Chapter 9. Managing the log and the bootstrap data set 371
 v The last unarchived active log data set becomes full. Message DSNJ110E is
issued, stating the percentage of its capacity in use; IFCID trace record 0330 is
also issued if statistics class 3 is active. If all active logs become full, Db2 issues
the following message and stops processing until offloading occurs.
DSNJ111E - OUT OF SPACE IN ACTIVE LOG DATA SETS

Role of the operator in the offload process

When it is time to offload an active log, you can send a request to the z/OS
console operator to mount a tape or prepare a disk unit.

The value of the WRITE TO OPER field of the DSNTIPA installation panel
determines whether the request is received. If the value is YES, the request is
preceded by a WTOR (message number DSNJ008E) informing the operator to
prepare an archive log data set for allocating.

The operator need not respond to message DSNJ008E immediately. However,

delaying the response delays the offload process. It does not affect Db2
performance unless the operator delays response for so long that Db2 uses all the
active logs.

The operator can respond by canceling the offload. In that case, if the allocation is
for the first copy of dual archive data sets, the offload is merely delayed until the
next active log data set becomes full. If the allocation is for the second copy, the
archive process switches to single-copy mode, but for the one data set only.

When Db2 switches active logs and finds that the offload task has been active since
the last log switch, it issues the following message to notify the operator of a
possible outstanding tape mount or some other problem that prevents the offload
of the previous active log data set.
DSNJ017E - csect-name WARNING - OFFLOAD TASK HAS BEEN ACTIVE SINCE
date-time AND MAY HAVE STALLED

Db2 continues processing. The operator can cancel and then restart the offload.

Messages that are returned during offloading

During the offload process, Db2 sends a series of messages to the z/OS console.
Most of these messages include information about the RBA ranges in the various
log data sets.
v The following message appears during Db2 initialization when the current active
log data set is found, and after a data set switch. During initialization, the
STARTRBA value in the message does not refer to the beginning of the data set,
but to the position in the log where logging is to begin.
DSNJ001I - csect-name CURRENT COPY n ACTIVE LOG DATA SET IS
DSNAME=..., STARTRBA=..., ENDRBA=...
v The following message appears when an active data set is full:
DSNJ002I - FULL ACTIVE LOG DATA SET DSNAME=...,
STARTRBA=..., ENDRBA=...
v One of the following message appears when offload reaches end-of-volume or
end-of-data-set in an archive log data set:
The non-data sharing version of this message is:
DSNJ003I - FULL ARCHIVE LOG VOLUME DSNAME=..., STARTRBA=..., ENDRBA=...,
STARTTIME=..., ENDTIME=..., UNIT=..., COPYnVOL=...,
VOLSPAN=..., CATLG=...
The data sharing version of this message is:

372 Administration Guide

 DSNJ003I - FULL ARCHIVE LOG VOLUME DSNAME=..., STARTRBA=..., ENDRBA=...,
STARTLRSN=..., ENDLRSN=..., UNIT=..., COPYnVOL=...,
VOLSPAN=..., CATLG=...
v The following message appears when one data set of the next pair of active logs
is not available because of a delay in offloading, and logging continues on one
copy only:
DSNJ004I - ACTIVE LOG COPY n INACTIVE, LOG IN SINGLE MODE,
ENDRBA=...
v The following message appears when dual active logging resumes after logging
has been performed on one copy only:
DSNJ005I - ACTIVE LOG COPY n IS ACTIVE, LOG IN DUAL MODE,
STARTRBA=...
v The following message indicates that the offload task has ended:
DSNJ139I LOG OFFLOAD TASK ENDED

Effects of interruptions and errors on the offload process

Db2 can handle some types of interruptions during the offloading process.

Db2 handles interruptions to the offloading process in the following ways:

v The STOP DB2 command does not take effect until offloading is finished.
v A Db2 failure during offload causes offload to begin again from the previous
start RBA when Db2 is restarted.
v Offload handling of read I/O errors on the active log is described under
Recovering from active log failures, or write I/O errors on the archive log, under
Recovering from archive log failures.
v An unknown problem that causes the offload task to hang means that Db2
cannot continue processing the log. This problem might be resolved by retrying
the offload, which you can do by using the option CANCEL OFFLOAD of the
command ARCHIVE LOG.

Archive log data sets

Archive log data sets can be placed on standard tapes or disks and can be
managed by DFSMShsm (Data Facility Hierarchical Storage Manager). Archive logs
are always written by QSAM.

Archive logs are always read by using BSAM. The block size of an archive log data
set is a multiple of 4 KB.

Output archive log data sets are dynamically allocated, with names chosen by Db2.
The data set name prefix, block size, unit name, and disk sizes that are needed for
allocation are specified when Db2 is installed, and recorded in the DSNZPxxx
module. You can also choose, at installation time, to have Db2 add a date and time
to the archive log data set name.

Restrictions: Consider the following restrictions for archive log data sets and
volumes:
v You cannot specify specific volumes for new archive logs. If allocation errors
occur, offloading is postponed until the next time loading is triggered.
v Do not use partitioned data set extended (PDSE) for archive log data. PDSEs are
not supported for archive logs.
Related reference:
DSNTIPA: Archive log data set parameters panel (Db2 Installation and
Migration)

Chapter 9. Managing the log and the bootstrap data set 373
 DSNTIPH: System resource data set names panel (Db2 Installation and
Migration)

How dual archive logging works

Each log control interval (CI) that is retrieved from the active log is written to two
archive log data sets. The log records that are contained on a pair of dual archive
log data sets are identical, but ends-of-volumes are not synchronized for
multivolume data sets.

Archiving to disk offers faster recoverability but is more expensive than archiving
to tape. If you use dual logging, on installation panel DSNTIPA enables you to
specify that the primary copy of the archive log go to disk and the secondary copy
go to tape.

Dual archive logging increases recovery speed without using as much disk. The
second tape is intended as a backup, or it can be sent to a remote site in
preparation for disaster recovery. To make recovering from the COPY2 archive tape
faster at the remote site, use the installation parameter ARC2FRST to specify that
COPY2 archive log should be read first. Otherwise, Db2 always attempts to read
the primary copy of the archive log data set first.

Tips for archiving

You can archive to tape or disk.

Tips for archiving to tape:

If you choose to archive to tape, following certain tips can help you avoid
problems.

If the unit name reflects a tape device, Db2 can extend to a maximum of twenty
volumes. Db2 passes a file sequence number of 1 on the catalog request for the
first file on the next volume. Although a file sequence number of 1 might appear
to be an error in the integrated catalog facility catalog, be aware that this situation
causes no problems in Db2 processing.

If you choose to offload to tape, consider adjusting the size of your active log data
sets so that each data set contains the amount of space that can be stored on a
nearly full tape volume. That adjustment minimizes tape handling and volume
mounts, and it maximizes the use of tape resources. However, such an adjustment
is not always necessary.

If you want the active log data set to fit on one tape volume, consider placing a
copy of the BSDS on the same tape volume as the copy of the active log data set.
Adjust the size of the active log data set downward to offset the space that is
required for the BSDS.

Tips for archiving to disk:

If you choose to archive to disk, following certain tips can help you avoid
problems.

All archive log data sets that are allocated on disk must be cataloged. If you
choose to archive to disk, the field CATALOG DATA of installation panel DSNTIPA
must contain YES. If this field contains NO, and you decide to place archive log
data sets on disk, you receive message DSNJ072E each time an archive log data set
is allocated, although the Db2 subsystem still catalogs the data set.

374 Administration Guide

 If you use disk storage, ensure that the primary and secondary space quantities
and block size and allocation unit are large enough so that the disk archive log
data set does not attempt to extend beyond 15 volumes. The possibility of
unwanted z/OS B37 or E37 abends during the offload process is thereby
minimized. Primary space allocation is set with the PRIMARY QUANTITY field of
| the DSNTIPA installation panel. If the archive log data sets are allocated with the
| DSNTYPE=LARGE attribute, z/OS DFSMS allows the data sets to be up to
| 16777215 tracks (1118481 cylinders) on each volume. If the archive log data sets are
| allocated without the DSNTYPE=LARGE attribute, z/OS DFSMS limits the data
| sets to less than or equal to 65535 tracks (4369 cylinders) on each volume.

Tips for archiving with z/OS DFSMS:

You can use z/OS DFSMS (Data Facility Storage Management Subsystem) to
manage archive log data sets.

When archiving to disk, Db2 uses the number of online storage volumes for the
specified unit to determine a count of candidate volumes, up to a maximum of 15
volumes. If you are using SMS to direct archive log data set allocation, override
this candidate volume count by specifying YES for the SVOLARC subsystem
parameter. This enables SMS to manage the allocation volume count appropriately
when creating multi-volume disk archive log data sets.

Because SMS requires disk data sets to be cataloged, ensure that the value of the
CATALOG subsystem parameter is YES. Even if it does not, message DSNJ072E is
returned, and Db2 forces the data set to be cataloged.

Db2 uses the basic sequential access method (BSAM) to read archive logs from disk
and BSAM supports the use of extended format (EF) data sets.

Ensure that z/OS DFSMS does not alter the LRECL, BLKSIZE, or RECFM of the
archive log data sets. Altering these attributes could result in read errors when Db2
attempts to access the log data.

Attention: Db2 does not issue an error or a warning if you write or alter archive
data to an unreadable format.
Related concepts:
Db2 and DFSMS (Introduction to Db2 for z/OS)
Related reference:
SINGLE VOLUME field (SVOLARC subsystem parameter) (Db2 Installation
and Migration)
CATALOG DATA field (CATALOG subsystem parameter) (Db2 Installation
and Migration)

Automatic archive log deletion

You can use a disk or tape management system to delete archive log data sets or
tapes automatically.

The length of the retention period (in days), which is passed to the management
system in the JCL parameter RETPD, is determined by the RETENTION PERIOD
field on the DSNTIPA installation panel.

The default for the retention period keeps archive logs forever. Any other retention
period must be long enough to contain as many recovery cycles as you plan for.

Chapter 9. Managing the log and the bootstrap data set 375
 For example, if your operating procedures call for a full image copy every sixty
days of the least frequently-copied table space, and you want to keep two
complete image copy cycles on hand at all times, you need an archive log retention
period of at least 120 days. For more than two cycles, you need a correspondingly
longer retention period.

Tip: In case of data loss or corruption, retain all Db2 recovery log and image copy
data sets until you can identify the source of the data loss or corruption. You might
need these data sets to aid in nonstandard recovery procedures. On at least a
weekly basis, take an image copy backup of every Db2 table space object that was
updated and retain the Db2 recovery log data sets for a minimum of seven days. If
you detect data loss or corruption, prevent older Db2 recovery log and image copy
data sets from being discarded until the issue is assessed and resolved.

If archive log data sets or tapes are deleted automatically, the operation does not
update the archive log data set inventory in the BSDS. You can update the BSDS
with the change log inventory utility. This update is not required and recording
old archive logs in the BSDS wastes space. However, it does no harm because the
archive log data set inventory wraps and automatically deletes the oldest entries.
Related concepts:
Management of the bootstrap data set
Recommendations for changing the BSDS log inventory
Related reference:
DSNTIPA: Archive log data set parameters panel (Db2 Installation and
Migration)

How Db2 retrieves log records

Normal Db2 operation and recovery tasks rely on the availability of log records.
Db2 retrieves log records from different sources, depending on the situation.

About this task

Log records are retrieved by Db2 through the following events:

v A log record is requested using its RBA.
v Db2 searches for the log record in the following locations in the order in which
they are presented:
1. The log buffers.
2. The active logs. The bootstrap data set registers which log RBAs apply to
each active or archive log data set. If the record is in an active log, Db2
dynamically acquires a buffer, reads one or more CIs, and returns one record
for each request.
3. The archive logs. Db2 determines which archive volume contains the CIs,
dynamically allocates the archive volume, acquires a buffer, and reads the
CIs.

Managing the log

You can control and monitor log activity by using several Db2 commands and a
utility.

376 Administration Guide

Quiescing activity before offloading
You can use the MODE(QUIESCE) option of the ARCHIVE LOG command to
ensure that activity has stopped before the log is archived.

About this task

With this option, Db2 work is quiesced after a commit point, and the resulting
point of consistency is captured in the current active log before it is offloaded.
Unlike the QUIESCE utility, ARCHIVE LOG MODE(QUIESCE) does not force all
changed buffers to be written to disk and does not record the log RBA in
SYSIBM.SYSCOPY. It does record the log RBA in the bootstrap data set.

Consider using MODE(QUIESCE) when planning for offsite recovery. Using

MODE(QUIESCE) creates a system-wide point of consistency, which can minimize
the number of data inconsistencies when the archive log is used with the most
current image copy during recovery.

In a data sharing group, ARCHIVE LOG MODE(QUIESCE) might result in a delay

before activity on all members has stopped. If this delay is unacceptable to you,
consider using ARCHIVE LOG SCOPE(GROUP) instead. This command causes
truncation and offload of the logs for each active member of a data sharing group.
Although the resulting archive log data sets do not reflect a point of consistency,
all the archive logs are made at nearly the same time and have similar LRSN
values in their last log records. When you use this set of archive logs to recover the
data sharing group, you can use the ENDLRSN option in the CRESTART statement
of the change log inventory utility (DSNJU003) to truncate all the logs in the group
to the same point in time.

The MODE(QUIESCE) option suspends all new update activity on Db2 up to the
maximum period of time that is specified on the installation panel DSNTIPA. If the
time needed to quiesce is less than the time that is specified, the command
completes successfully; otherwise, the command fails when the time period
expires. This time amount can be overridden when you issue the command, by
using the TIME option:
-ARCHIVE LOG MODE(QUIESCE) TIME(60)

The preceding command allows for a quiesce period of up to 60 seconds before

archive log processing occurs.

Important: Use of this option during prime time, or when time is critical, can
cause a significant disruption in Db2 availability for all jobs and users that use Db2
resources.

By default, the command is processed asynchronously from the time you submit
the command. (To process the command synchronously with other Db2 commands,
use the WAIT(YES) option with QUIESCE; the z/OS console is then locked from
Db2 command input for the entire QUIESCE period.)

During the quiesce period:

v Jobs and users on Db2 are allowed to go through commit processing, but they
are suspended if they try to update any Db2 resource after the commit.

Chapter 9. Managing the log and the bootstrap data set 377
 v Jobs and users that only read data can be affected, because they can be waiting
for locks that are held by jobs or users that were suspended.
v New tasks can start, but they are not allowed to update data.

As shown in the following example, the DISPLAY THREAD output issues message
DSNV400I to indicate that a quiesce is in effect:
DSNV401I - DISPLAY THREAD REPORT FOLLOWS -
DSNV400I - ARCHIVE LOG QUIESCE CURRENTLY ACTIVE
DSNV402I - ACTIVE THREADS -
NAME ST A REQ ID AUTHID PLAN ASID TOKEN
BATCH T * 20 TEPJOB SYSADM MYPLAN 0012 12
DISPLAY ACTIVE REPORT COMPLETE
DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL COMPLETION

When all updates are quiesced, the quiesce history record in the BSDS is updated
with the date and time that the active log data sets were truncated, and with the
last-written RBA in the current active log data sets. Db2 truncates the current
active log data sets, switches to the next available active log data sets, and issues
message DSNJ311E, stating that offload started.

If updates cannot be quiesced before the quiesce period expires, Db2 issues
message DSNJ317I, and archive log processing terminates. The current active log
data sets are not truncated and not switched to the next available log data sets,
and offload is not started.

Regardless of whether the quiesce is successful, all suspended users and jobs are
then resumed, and Db2 issues message DSNJ312I, stating that the quiesce is ended
and update activity is resumed.

If ARCHIVE LOG is issued when the current active log is the last available active
log data set, the command is not processed, and Db2 issues this message:
DSNJ319I - csect-name CURRENT ACTIVE LOG DATA SET IS THE LAST
AVAILABLE ACTIVE LOG DATA SET. ARCHIVE LOG PROCESSING WILL
BE TERMINATED.

If ARCHIVE LOG is issued when another ARCHIVE LOG command is already in

progress, the new command is not processed, and Db2 issues this message:
DSNJ318I - ARCHIVE LOG COMMAND ALREADY IN PROGRESS.

Related reference:
DSNTIPA: Archive log data set parameters panel (Db2 Installation and
Migration)
-ARCHIVE LOG (Db2) (Db2 Commands)

Archiving the log

If you are a properly authorized operator, you can archive the current Db2 active
log data sets when necessary by issuing the ARCHIVE LOG command. Using the
ARCHIVE LOG command can help with diagnosis by enabling you to quickly
offload the active log to the archive log, where you can use DSN1LOGP to further
analyze the problem.

378 Administration Guide

 Before you begin

You must have either SYSADM authority or have been granted the ARCHIVE
privilege.

Procedure

To archive the log:

Enter the following command:

-ARCHIVE LOG

When you issue the preceding command, Db2 truncates the current active log data
sets, runs an asynchronous offload, and updates the BSDS with a record of the
offload. The RBA that is recorded in the BSDS is the beginning of the last complete
log record that is written in the active log data set that is being truncated.

Example
You can use the ARCHIVE LOG command as follows to capture a point of
consistency for the MSTR01 and XUSR17 databases:
-STOP DATABASE (MSTR01,XUSR17)
-ARCHIVE LOG
-START DATABASE (MSTR01,XUSR17)

In this simple example, the STOP command stops activity for the databases before
archiving the log.

Canceling log offloads

About this task

In some cases, the offload of an active log might be suspended when something
goes wrong with the offload process, such as a problem with allocation or tape
mounting. If the active logs cannot be offloaded, the Db2 active log data sets
become full and Db2 stops logging.

To cancel (and retry) an offload, issue this command:

-ARCHIVE LOG CANCEL OFFLOAD

When you enter the command, Db2 restarts the offload, beginning with the oldest
active log data set and proceeding through all active log data sets that need
offloading. If the offload fails again, you must fix the problem that is causing the
failure before the command can work.

| Adding an active log data set to the active log inventory with
| the SET LOG command
| You can use the SET LOG command to add a new active log data set to the active
| log inventory without stopping and starting Db2.

Chapter 9. Managing the log and the bootstrap data set 379
| Before you begin

| Before you issue the SET LOG command, define and format the new active log
| data sets.
| 1. Use the Access Method Services DEFINE command to define new active log
| data sets.
| 2. Use the DSNJLOGF utility to preformat the new active log data sets.
| If you do not preformat the active logs with the DSNJLOGF utility, the Db2
| database manager needs to preformat them the first time that they are used,
| which might have a performance impact.

| Procedure

| To add an active log data set to the active log inventory:

| Issue the SET LOG command with the NEWLOG and COPY keywords. If the Db2
| database manager can open the newly defined log data set, the log data set is
| added to the active log inventory in the bootstrap data set (BSDS). The new active
| log data set is immediately available for use without stopping and starting the
| database manager.
| Currently, the database manager uses active log data sets in the reverse order from
| the order in which you add them to the active log inventory with the SET LOG
| command. For example, suppose that the active log inventory contains data sets
| DS01, DS02, and DS03, and you add data set DS04 and then data set DS05. If data
| set DS03 is active, and you issue the ARCHIVE LOG command, the new active log
| becomes DS05. This behavior might change in the future, so schemes for adding
| and switching active logs should not depend on this order.
| Related reference:
| -SET LOG (Db2) (Db2 Commands)
| DSNJLOGF (preformat active log) (Db2 Utilities)

Dynamically changing the checkpoint frequency

You can use the LOGLOAD option, the CHKTIME option, or a combination of
both of these options of the SET LOG command to dynamically change the
checkpoint frequency without recycling Db2.

About this task

The LOGLOAD value specifies the number of log records that Db2 writes between
checkpoints. The CHKTIME value specifies the number of minutes between
checkpoints.

You specify the initial LOGLOAD and CHKTIME parameter values at installation
time. Also at installation time, you specify which of these values controls when a
checkpoint occurs, or whether both do. If you specify both the LOGLOAD and
CHKTIME options together, when the threshold for one is reached, a system
checkpoint is taken, and the counters for both thresholds are reset. In the following
example, the SET LOG command changes checkpoint scheduling to use both log
records and time:
-SET LOG BOTH CHKTIME(10) LOGLOAD(500000)

380 Administration Guide

 Either value affects the restart time for Db2. For example, during prime shift, your
Db2 shop might have a low logging rate but require that Db2 restart quickly if it
terminates abnormally. To meet this restart requirement, you can decrease the
LOGLOAD value to force a higher checkpoint frequency. In addition, during
off-shift hours, the logging rate might increase as batch updates are processed, but
the restart time for Db2 might not be as critical. In that case, you can increase the
LOGLOAD value which lowers the checkpoint frequency.

You also can use either the LOGLOAD option or the CHKTIME option to initiate
an immediate system checkpoint. For example:
-SET LOG LOGLOAD(0)
-SET LOG CHKTIME(0)

The CHKFREQ value that is altered by the SET LOG command persists only while
Db2 is active. On restart, Db2 uses the CHKFREQ value in the Db2 subsystem
parameter load module.

Related reference:
-SET LOG (Db2) (Db2 Commands)

Setting limits for archive log tape units

Use the Db2 SET ARCHIVE command to set the upper limit for the number of,
and the deallocation time of, tape units for the archive log.

About this task

This command overrules the values that are specified during installation, or in a
previous invocation of the SET ARCHIVE command. The changes that are initiated
by the SET ARCHIVE command are temporary. At restart, Db2 uses the values that
are set during installation.

Related reference:
-SET ARCHIVE (Db2) (Db2 Commands)

Monitoring the system checkpoint

Db2 schedules a system checkpoint every time it switches active log data sets,
regardless of the currently defined checkpoint frequency.

About this task

If Db2 switches active logs and finds that there has not been a system checkpoint
since the last log switch, it issues the following message to notify the operator that
the system checkpoint processor might not be functioning.
DSNJ016E - csect-name WARNING - SYSTEM CHECKPOINT PROCESSOR MAY
HAVE STALLED. LAST CHECKPOINT WAS TAKEN date-time

Db2 continues processing. This situation can result in a very long restart if logging
continues without a system checkpoint. If Db2 continues logging beyond the

Chapter 9. Managing the log and the bootstrap data set 381
 defined checkpoint frequency, quiesce activity and terminate Db2 to minimize the
restart time.

Procedure

To display the most recent checkpoint, use one of the following approaches:
v Issue the DISPLAY LOG command.
v Run the print log map utility (DSNJU004).
Related tasks:
Displaying log information
Related reference:
DSNJU004 (print log map) (Db2 Utilities)
-DISPLAY LOG (Db2) (Db2 Commands)

Displaying log information

You can use the DISPLAY LOG command to display the current checkpoint
frequency. You can obtain additional information about log data sets and
checkpoints from the print log map utility (DSNJU004).

About this task

The checkpoint frequency can be either the number of log records or the minutes
between checkpoints.

Procedure

To display log information:

Issue the DISPLAY LOG command, or use the print log map utility (DSNJU004).
Related reference:
-DISPLAY LOG (Db2) (Db2 Commands)
-SET LOG (Db2) (Db2 Commands)
DSNJU004 (print log map) (Db2 Utilities)

| What to do before RBA or LRSN limits are reached

| Before a Db2 subsystem or data sharing group reaches the end of the log RBA
| range, you must convert to the extended 10-byte format, or reset the log RBA
| value. The process that you use to reset the log RBA value depends on whether the
| Db2 subsystem is a member of a data sharing group or in a non-data sharing
| environment.

| About this task

| The log limits are expressed as RBA values in non-data-sharing environments and
| as LRSN timestamps in data-sharing environments. Approximately one year before
| the end of the LRSN is reached, message DSNJ034I is issued to inform you that the
| LRSN is approaching the log limit.

382 Administration Guide

| The log RBA is an ever-increasing 6-byte or 10-byte hexadecimal value. The 6-byte
| value starts as 0 (zero) when the Db2 subsystem is first installed and increases to a
| maximum value of x'FFFFFFFFFFFF' (2**48). The 10-byte value allows up to 2**80
| (x'FFFFFFFFFFFFFFFFFFFF').

| The rate at which the log RBA value increases through this range depends on the
| logging rate of the Db2 subsystem. When a heavy logging rate is sustained over a
| period of years, the log RBA value can begin to approach the end of the range.

| Two logging limits affect processing:

| Soft limit
| The soft limit occurs at RBA x'FFF800000000' or at an LRSN approximately
| two months before the 6-byte capacity is reached. When the soft limit is
| reached, user objects in basic 6-byte format are available for read-only
| access. Attempts to update these objects are rejected. If you need to update
| table spaces and indexes that have reached the soft limit, you can convert
| them to extended 10-byte page format. Ensure that all catalog and
| directory page sets are converted to extended format. Utilities that open an
| output object as unrecoverable can still run after the soft limit is reached. If
| the output object will be in extended format, such as for a REORG that
| converts from basic to extended format, the utility can run successfully.
| Hard limit
| The hard limit is the actual limit, and occurs when the RBA or LRSN no
| longer fits in 6 bytes. That value is x'00000000FFFFFFFFFFFF' for an RBA,
| and x'00FFFFFFFFFFFFFFFFFFFF' for an LRSN. When the actual limit is
| reached, you cannot update objects that are in basic format. Attempts to
| update an object that is in basic format are rejected. You must convert the
| BSDS before you can start Db2 after the hard limit is reached. The -START
| DB2 command abends if the BSDS is not converted. When the hard limit
| has been reached, no online utilities can run if the BSDS is not converted
| to support the 10-byte RBA format, or if catalog and directory page sets are
| not in extended format.

| Important: If the RBA for a non data sharing Db2 subsystem reaches or exceeds
| the hard or soft limit, you must either convert all table spaces and indexes to the
| 10-byte format or use the RBA reset procedure. Enabling data sharing is not
| sufficient to resolve the problem.

| Db2 might issue message DSNB233I to remind you to convert page sets to the
| 10-byte format.

| Procedure
| 1. Determine when the 6-byte RBA and LRSN limits are likely to be reached, by
| using one of the following methods:
| v Message DSNJ032I is issued at the active log switch when the RBA threshold
| is reached. If the RBA exceeds x'F00000000000' for the 6-byte RBA format or
| x'FFFFFFFF000000000000' for the 10-byte RBA format, the message is issued
| with the keyword WARNING and processing continues. If the RBA exceeds
| x'FFFF00000000' for the 6-byte RBA format or x'FFFFFFFFFF0000000000' for
| the 10-byte RBA format, the message is issued with the keyword CRITICAL,
| and Db2 is stopped. To resolve any outstanding units of work, Db2 restarts
| automatically in restart-light mode. Then, Db2 stop again. In this situation,
| you need to restart Db2 in ACCESS(MAINT) mode.

Chapter 9. Managing the log and the bootstrap data set 383
| Important: After the BSDS data sets have been converted to the 10-byte RBA
| or LRSN format, the DSNJ032I message is no longer issued, even if reaching
| the 6-byte RBA or 6-byte LRSN soft limit for table spaces or index spaces in
| basic format is imminent.

| Important: The rate of RBA usage is faster after the BSDS has been
| converted to the 10-byte format.
| v Calculate how much space is left in the log. You can use the print log map
| (DSNJU004) utility to obtain the highest written RBA value in the log.
| Subtract this RBA from x'FFFFFFFFFFFF' for the 6-byte RBA format or
| x'FFFFFFFFFFFFFFFFFFFF' for the 10-byte RBA format to determine how
| much space is left in the log.
| You can use the output for the print log map utility to determine how many
| archive logs are created on an average day. This number multiplied by the
| RBA range of the archive log data sets (ENDRBA minus STARTRBA)
| provides the average number of bytes that are logged per day. Divide this
| value into the space remaining in the log to determine approximately how
| much time is left before the end of the log RBA range is reached. If there is
| less than one year remaining before the end of the log RBA range is reached,
| start planning to reset the log RBA value. If less than three months remain
| before the end of the log RBA range is reached, you need to take immediate
| action to reset the log RBA value.
| 2. Convert the BSDS to the extended 10-byte format. For instructions, see
| Converting the BSDS to the 10-byte RBA and LRSN.
| In data sharing, if any Db2 member is approaching the logging limit for the
| 6-byte RBA but the LRSN is not approaching the limit of the 6-byte range,
| converting the BSDS of just that member sufficient to resolve the immediate
| problem and prevent outages. However, if the LRSN is also approaching the
| end of the 6-byte range, you must continue and convert page sets to use the
| 10-byte format before the limit is reached.

| Restriction: In Db2 11 conversion mode or enabling new-function mode,

| conversion to the 10-byte RBA and LRSN is not supported. If you cannot
| migrate to Db2 11 new-function mode before it reaches the limit of the 6-byte
| range, you must reset the 6-byte RBA. For data sharing, see Resetting the log
| RBA value in a data sharing environment (6-byte format). For non-data sharing,
| see Resetting the log RBA value in a non-data sharing environment (6-byte
| format).
| 3. Convert page sets to use the extended 10-byte format. For instructions, see
| Converting page sets to the 10-byte RBA or LRSN format.
| Related concepts:
| The extended 10-byte RBA and LRSN in Db2 11 (Db2 for z/OS What's New?)
| How RBA and LRSN values are displayed
| Related information:
|
| DSNB233I (Db2 Messages)

| Converting the BSDS to the 10-byte RBA and LRSN

| If the RBA or LRSN approaches the end of the range in Db2 11 new-function
| mode, you can convert the BSDS to the extended 10-byte format.

384 Administration Guide

| Before you begin

| Before you can convert the BSDS, the Db2 subsystem or data sharing member must
| be started in Db2 11 new-function mode. For instructions, see Migrating from
| enabling-new-function mode to new-function mode (Db2 Installation and
| Migration).

| Attention: In Db2 subsystems that are not data sharing members, if Db2 is
| already at risk of reaching the 6-byte RBA limit, it is strongly recommended that
| you first convert all catalog and directory objects, then convert all user objects to
| the 10-byte RBA format, before you convert the BSDS.

| Attention: After the BSDS is converted to the 10-byte format, Db2 stops issuing
| messages to warn you about the risk of reaching the 6-byte RBA or LRSN limits.
| The increased size of all log records also accelerates progress toward the 6-byte
| RBA logging limit.

| In Db2 subsystems that are not data sharing members, always convert all Db2
| catalog, directory, and user objects to use the extended 10-byte RBA format before
| you convert the BSDS, especially if Db2 is close to reaching the logging limit for
| the 6-byte RBA. Failure to convert page sets to the 10-byte RBA format before Db2
| reaches the 6-byte logging limit results in failed updates with reason code
| 00C2026D. No updates are allowed for any object that is still in the 6-byte format.

| In data sharing, if any Db2 member is approaching the logging limit for the 6-byte
| RBA but the LRSN is not approaching the limit of the 6-byte range, converting the
| BSDS of just that member sufficient to resolve the immediate problem and prevent
| outages. However, if the LRSN is also approaching the end of the 6-byte range,
| you must continue and convert page sets to use the 10-byte format before the limit
| is reached.

| At migration to Db2 12, you cannot start Db2 12 until the BSDS is converted to use
| the 10-byte RBA and LRSN formats. You can convert the BSDS before or during the
| Db2 12 migration process.

| Procedure

| To convert the BSDS to use the extended 10-byte RBA and LRSN format, complete
| the following steps:
| 1. Stop Db2.
| 2. Run job DSNTIJCB. The DSNTIJCB job for each Db2 subsystem or data sharing
| member is located in the prefix.NEW.SDSNSAMP sample library that is
| generated when you run the installation CLIST in MIGRATE mode. Db2 runs
| the DSNJCNVT conversion utility to convert the bootstrap data set records to
| support 10-byte RBA and LRSN fields. For more information, see DSNJCNVT
| (Db2 Utilities).
| 3. Start Db2.

| What to do next

| If you have not already done so, first convert all page sets for the Db2 catalog,
| directory, and , as described in Convert the BSDS, Db2 catalog, and directory to
| 10-byte RBA and LRSN format (Optional) (Db2 Installation and Migration). . Then
| convert all user objects to support the 10-byte RBA and LRSN, as described in

Chapter 9. Managing the log and the bootstrap data set 385
| Converting page sets to the 10-byte RBA or LRSN format. After Db2 reaches the
| hard logging limit, you might not be able to convert the catalog and directory page
| sets.

| You must continuously monitor the RBA and LRSN values until all catalog,
| directory, and user objects are converted to the 10-byte RBA or LRSN format.
| Failure to convert page sets before the 6-byte soft logging limit is reached results in
| failed updates with reason code 00C2026D, and any objects still in the 6-byte
| format become read-only. RBA or LRSN values greater than x'F00000000000'
| indicate that your system is at risk of reaching the 6-byte logging limit.

| For more information the RBA and LRSN logging limits, see What to do before
| RBA or LRSN limits are reached. For instructions for converting page sets to the
| 10-byte format, see Converting page sets to the 10-byte RBA or LRSN format.
| Related concepts:
| Management of the bootstrap data set

| Converting page sets to the 10-byte RBA or LRSN format

| To prevent RBAs and LRSNs from reaching the hard limits, convert user, catalog,
| and directory page sets to the 10-byte RBA or LRSN format.

| Before you begin

| At migration to Db2 12, you cannot start Db2 12 until the BSDS is converted to use
| the 10-byte RBA and LRSN formats. You can convert the BSDS before or during the
| Db2 12 migration process.

| Tip: In Db2 data sharing, you can get a incremental performance benefit by
| converting the BSDS to the extended 10-byte format before converting the page
| sets for Db2 catalog, directory, and user objects. However, for non-data sharing
| Db2 subsystems, it is best to convert the BSDS at the end of the conversion
| process.

| For instructions, see Converting the BSDS to the 10-byte RBA and LRSN.

| About this task

| If the RBA or LRSN has already reached the hard limit Db2 subsystems, the RBA
| or LRSN reset procedure must be used first, unless all the necessary tables and
| indexes have previously been converted to the extended 10-byte format. If
| database objects are in the basic 6-byte format, they cannot be updated after the
| hard limit is reached.

| Tip: Data pages and space map pages for the work file database use the 10-byte
| format as soon as they are first accessed in Db2 11 (in any migration mode),
| regardless of whether the Db2 subsystem is migrated from DB2 10 or is a new
| installation. However, for migrated subsystems, the Db2 catalog is not updated to
| reflect the format of the work files.

| For more information about how Db2 uses 10-byte format values used at migration
| to Db2 11, see The extended 10-byte RBA and LRSN in Db2 11 (Db2 for z/OS
| What's New?).

| Db2 might issue message DSNB233I to remind you to convert page sets to the
| 10-byte format.

386 Administration Guide

| Procedure

| To convert the RBA and LRSN to extended 10-byte format, complete the following
| steps:
| 1. Identify the objects to convert by querying the RBA_FORMAT columns of the
| SYSIBM.SYSTABLEPART and SYSIBM.SYSINDEXPART catalog tables.
| RBA_FORMAT='B', and blank values in those columns, indicate objects in the
| 6-byte format.
| 2. Enable Db2 to create new table spaces and indexes with the RBA or LRSN in
| extended 10-byte format, and convert the RBA for existing table spaces and
| indexes to extended 10-byte format:
| a. Run the installation CLIST and on panel DSNTIPA1 specify UPDATE for
| INSTALL TYPE. On panel DSNTIP7, set the OBJECT CREATE FORMAT
| and UTILITY OBJECT CONVERSION fields to EXTENDED. If any existing
| objects are in extended 10-byte format, you can set the UTILITY OBJECT
| CONVERSION subsystem parameter to NOBASIC to prevent the utilities
| from converting those table spaces back to basic 6-byte format.
| b. Run the updated DSNTIJUZ job to rebuild the subsystem parameter
| (DSNZPxxx) module.
| c. Issue the -SET SYSPARM command or restart Db2.
| 3. Identify objects to convert by checking the RBA_FORMAT column of the
| SYSIBM.SYSTABLEPART and SYSIBM.SYSINDEXPART catalog tables. If the
| RBA_FORMAT value is 'B' or blank, the object is in the basic 6-byte format.
| 4. Run LOAD REPLACE, REBUILD, or REORG with the
| RBALRSN_CONVERSION keyword specified with the EXTENDED option.
| During utility processing, any objects processed by the utility that are in basic
| 6-byte format are converted to extended 10-byte format. To verify the
| conversion, check the RBA_FORMAT column value of the
| SYSIBM.SYSTABLEPART and SYSIBM.SYSINDEXPART catalog tables. The
| value is 'E' for converted objects.

| Results

| New table spaces and indexes are created in extended format with 10-byte RBA or
| LRSN values, and existing table spaces and indexes are converted to extended
| format with 10-byte RBA or LRSN values.

| What to do next
| After the page sets for all Db2 catalog, directory, and user objects are converted,
| convert the BSDS to the extended 10-byte format after all page sets for Db2
| catalog, directory, and user objects. For instructions, see Converting the BSDS to
| the 10-byte RBA and LRSN.
| Related concepts:
| “How RBA and LRSN values are displayed” on page 679
| Related reference:
| DSNTIP7: SQL OBJECT DEFAULTS PANEL 1 (Db2 Installation and Migration)
|
| DSNJCNVT (Db2 Utilities)
| OBJECT CREATE FORMAT field (OBJECT_CREATE_FORMAT subsystem
| parameter) (Db2 Installation and Migration)

Chapter 9. Managing the log and the bootstrap data set 387
| UTILITY OBJECT CONVERSION field (UTILITY_OBJECT_CONVERSION
| subsystem parameter) (Db2 Installation and Migration)
| Syntax and options of the LOAD control statement (Db2 Utilities)
| Syntax and options of the REBUILD INDEX control statement (Db2 Utilities)
| Syntax and options of the REORG INDEX control statement (Db2 Utilities)
| Syntax and options of the REORG TABLESPACE control statement (Db2
| Utilities)
| Related information:
|
| DSNB233I (Db2 Messages)

| Resetting the log RBA value in a data sharing environment

| (6-byte format)
| Before the member of a data sharing group reaches the end of the log RBA range,
| you must reset the log RBA value for that member.

| Before you begin

| Db2 11 introduces extended 10-byte RBA and LRSN formats.

| The recommended response before your Db2 data sharing group reaches the end
| of the 6-byte log RBA range is to convert the BSDS and page sets to use the
| 10-byte format. For details see What to do before RBA or LRSN limits are reached
| and The extended 10-byte RBA and LRSN in Db2 11 (Db2 for z/OS What's New?).

| At migration to Db2 12, you cannot start Db2 12 until the BSDS is converted to use
| the 10-byte RBA and LRSN formats. You can convert the BSDS before or during the
| Db2 12 migration process.

| However, you can continue to use the following procedure in Db2 11 until you
| complete the conversion.

| Procedure

| To reset the log RBA value in a data sharing environment:

| 1. Issue the STOP DB2 command to quiesce the member that is approaching the
| end of the log RBA range.
| 2. Restart this member in ACCESS(MAINT) mode.
| 3. Issue the -DISPLAY THREAD command. Ensure that there are no INDOUBT or
| POSTPONED ABORT units of recovery.
| 4. Issue the -DISPLAY DATABASE(*) SPACENAM(*) RESTRICT command. Ensure that
| all restricted states are removed.
| 5. Quiesce the member again by issuing the -STOP DB2 command.
| 6. Optional: Start a new member to take over the work of the member that is
| quiesced. If using another member is an acceptable solution, you can leave the
| original member stopped indefinitely.
| 7. Optional: Before you cold start the member, complete this step to avoid a
| potential performance issue that is caused by log formatting. When the residual
| RBA range is greater than the log truncation point, Db2 resets the high used
| RBA (HURBA) for the active logs after the cold start of a member. This action

388 Administration Guide

| avoids log read errors that can result from reading residual log data with
| higher RBA values from peer members of the data sharing group. The first time
| the logs become current, Db2 must format the active logs ahead of the log
| writes until the log is full.
| To preformat the active logs before a cold start:
| a. Delete and redefine the active logs with IDCAMS.
| b. Format the empty logs by using the DSNJLOGF utility.
| c. Use the DSNJU003 utility to delete the active logs from the BSDS and add
| the logs back in with no RBA range. Adding the logs back in with no RBA
| range shows that the logs are empty.
| During the subsequent cold start, Db2 detects these changes to the active logs
| and does not reset the HURBA. Therefore, log formatting is not required ahead
| of the log writes.
| 8. To bring the original member back into the data sharing group, you must cold
| start the member with a STARTRBA of 0 (zero). To cold start the member:
| a. Make a full image copy of all data by using the COPY utility. For example,
| in a data sharing group with two members, where you are resetting the log
| RBA of the first member, make a full image copy by using the second
| member. The first member must remain quiesced for awhile. The length of
| time that the member is quiesced depends on how long it takes to establish
| a new recovery base and the time required for the logs from the quiesced
| member to no longer be required for any form of recovery. After you are
| satisfied that the logs are not required for recovery purposes, you can reset
| the log RBA for the quiesced member and restart the member.
| b. Stop all IFI applications that might issue READS calls for IFCID 0306 to
| read log records from the member that you are cold starting.
| c. Cold start the first member back to the RBA value of 0 (zero). This step
| removes all log data from the BSDS, and you can use the member again.
| This step requires utility DSNJU003 with the following options:
| CRESTART CREATE,STARTRBA=0,ENDRBA=0
| d. Restart all IFI applications that you stopped in step 8b.
| Related concepts:
| Expanded RBA and LRSN log records (Db2 for z/OS What's New?)
| Related tasks:
| What to do before RBA or LRSN limits are reached
| Related reference:
| COPY (Db2 Utilities)
| DSNJU003 (change log inventory) (Db2 Utilities)
| DSNJLOGF (preformat active log) (Db2 Utilities)

| Resetting the log RBA value in a non-data sharing

| environment (6-byte format)
| Before a Db2 subsystem in a non-data sharing environment reaches the end of the
| log RBA range, you need to reset the log RBA value for that subsystem.

| Before you begin

| Db2 11 introduces extended 10-byte RBA and LRSN formats. The recommended
| response before your Db2 subsystem reaches the end of the 6-byte log RBA range

Chapter 9. Managing the log and the bootstrap data set 389
| is to convert the BSDS and page sets to use the 10-byte format. For details see
| What to do before RBA or LRSN limits are reached and The extended 10-byte RBA
| and LRSN in Db2 11 (Db2 for z/OS What's New?).

| At migration to Db2 12, you cannot start Db2 12 until the BSDS is converted to use
| the 10-byte RBA and LRSN formats. You can convert the BSDS before or during the
| Db2 12 migration process.

| Having full backups of all Db2 subsystem volumes is recommended, including

| volumes with active and archive log data sets and the BSDSs.

| Procedure

| To reset the log RBA value in a non-data sharing environment by using the COPY
| utility:
| 1. Drop any user-created indexes on the SYSIBM.SYSTSCPY catalog table.
| 2. Alter all of the indexes on the catalog tables so that they have the COPY YES
| attribute by issuing the ALTER INDEX COPY YES statement, and commit the
| changes after running every 30 ALTER statements.

| Tip: You do not need to alter the following objects:

| v Db2 directory indexes. By default, these indexes already have the COPY
| YES attribute.
| v Indexes for the DSNDB06.SYSTSCPY catalog table space. You will be
| resetting the log RBA value for these indexes later in this procedure.
| 3. Issue the -STOP DB2 command to quiesce the subsystem that is approaching
| the end of the log RBA range.
| 4. Restart Db2 in ACCESS(MAINT) mode.
| 5. Issue the -DISPLAY THREAD command. Ensure that there are no INDOUBT or
| POSTPONED ABORT units of recovery.
| 6. Issue the -DISPLAY UTILITY command. Ensure there are no active or stopped
| utilities.
| 7. Issue the -DISPLAY DATABASE(*) SPACENAM(*) RESTRICT command. Ensure that
| all restricted states are removed.
| 8. Quiesce the Db2 subsystem again by issuing the -STOP DB2 command.
| 9. Use IDCAMS to delete and redefine the table spaces SYSUTILX, SYSTSCPY,
| and SYSLGRNX and their corresponding indexes. Then, re-initialize these
| page sets. For information about how to re-initialize these page sets, see
| members DSNTIJDE, DSNTIJIN, DSNTIJID, and DSNTIJIE in library
| SDSNSAMP.
| CAUTION:
| Edit these members so that only the pertinent page sets are processed.
| 10. Complete the following steps to enable the COPY utility to reset the log RBA
| values in data pages and index pages as they are copied:
| a. Edit member DSN6SPRC of the prefix.SDSNMACS library and locate the
| entry SPRMRRBA.
| b. Change the SPRMRRBA setting to '1' and save the change.
| c. Run the first two steps of your customized copy of job DSNTIJUZ to
| rebuild your Db2 subsystem parameter module (DSNZPxxx).
| 11. Stop all IFI applications that might issue READS calls for IFCID 0306 to read
| log records from the subsystem.

390 Administration Guide

| 12. Cold start the subsystem back to the RBA value of 0 (zero). This step removes
| all log data from the BSDS. This step requires utility DSNJU003 with the
| following options:
| CRESTART CREATE,STARTRBA=0,ENDRBA=0
| 13. Restart all IFI applications that you stopped in step 11 on page 390.
| 14. Start the Db2 subsystem in ACCESS(MAINT) mode.
| 15. Take new, full image copies of all table spaces and indexes by using the COPY
| utility with the SHRLEVEL REFERENCE option to automatically reset the log
| RBA values.
| a. COPY the DSNDB06.SYSTSTSS and DSNDB06.SYSTSISS catalog table
| spaces.
| b. Copy the rest of the catalog and directory table spaces and indexes,
| including any user-created Db2 catalog indexes.
| c. Alter indexes on user table spaces so that they have the COPY YES
| attribute by issuing the ALTER INDEX COPY YES statement, and commit
| the changes after running every 30 ALTER statements.
| d. Copy the table spaces and indexes in user-created databases. You can do
| this step and the next step in parallel.
| e. Copy the tables spaces and indexes in default database DSNDB04.
| Do not copy the table spaces in workfile database DSNDB07. Db2
| automatically resets the log RBA values in these table spaces when they are
| used.

| Restriction: Because FlashCopy technology does not reset the log RBA, you
| cannot use the COPY FLASHCOPY option in this situation.
| 16. Re-create any user-created indexes on the SYSIBM.SYSCOPY table that were
| dropped in step 1 of this procedure.
| 17. Verify that the log RBA values were reset:
| a. Run a query against the tables SYSIBM.SYSCOPY,
| SYSIBM.SYSTABLEPART, and SYSIBM.SYSINDEXPART to verify that all
| objects were copied.
| b. Use the DSN1PRNT utility with the FORMAT option to print several
| pages from some of the objects so that you can verify that the PGLOGRBA
| field in the pages are reset to zero. The COPY utility updates the
| PGLOGRBA field and other RBA fields in header pages (page zero) so
| these fields will contain non-zero values.
| 18. Stop Db2, and disable the reset RBA function in the COPY utility by following
| the instructions in step 10 and setting SPRMRRBA to '0'.
| 19. Restart Db2 for normal access.
| 20. Alter the Db2 catalog indexes and user-created indexes to have the COPY NO
| attribute by issuing the ALTER INDEX COPY NO statement. Commit the
| changes after every thirty ALTER statements. However, you should issue these
| ALTER statements over several days, because during this process SYSCOPY
| and SYSLGRNX records are deleted and contention might occur.

| Note: If the RBA fields for an object are not reset, abend04E RC00C200C1 is
| returned during SQL update, delete, and insert operations. The object also is
| placed in STOPE status. You can use the DSN1COPY utility with the RESET
| option to reset the log RBA values. This two-step process requires copying the
| data out and then back into the specified data sets. Before using DSN1COPY
| with the RESET option, make sure that the object is stopped by issuing the
| command -STOP DB(...) SPACENAM(...).
Chapter 9. Managing the log and the bootstrap data set 391
| Related concepts:
| Expanded RBA and LRSN log records (Db2 for z/OS What's New?)
| Related tasks:
| What to do before RBA or LRSN limits are reached
| Related reference:
| COPY (Db2 Utilities)

Canceling and restarting an offload

If the offload task remains stalled, the active logs eventually become full and Db2
stops database update activity.

Procedure

To cancel and restart an offload task:

Issue the ARCHIVE LOG CANCEL OFFLOAD command.

Displaying the status of an offload

You can use the DISPLAY LOG command to view information about the current
active log data sets and status of the offload task.

Procedure

To view the status of an offload task:

Issue the DISPLAY LOG command.

Related reference:
-DISPLAY LOG (Db2) (Db2 Commands)

Discarding archive log records

You must keep enough log records to recover units of work and databases.

About this task

To recover units of recovery, you need log records at least until all current actions
are completed. If Db2 terminates abnormally, restart requires all log records since
the previous checkpoint or the beginning of the oldest UR that was active at the
abend, whichever is first on the log.

To tell whether all units of recovery are complete, read the status counts in the Db2
restart messages. If all counts are zero, no unit-of-recovery actions are pending. If

392 Administration Guide

 indoubt units of recovery remain, identify and recover them by the methods
described in Monitoring and controlling Db2 and its connections.

To recover databases, you need log records and image copies of table spaces. How
long you keep log records depends, on how often you make those image copies. If
you do not already know what records you want to keep, see Backing up and
recovering your data for suggestions about recovery cycles.

Locating archive log data sets

To ensure that you can recover your data in the event of a failure, you need to
locate archive log data sets.

Before you begin

In preparation, you must:

v Keep all the logs that have been written since the most recent checkpoint of Db2,
so that Db2 can restart.
v Keep all the logs for two or more complete image copy cycles of your
least-frequently copied table space.

About this task

You can discard active data sets, based on their log RBA ranges. The earliest log
record that you need to retain is identified by a log RBA. You can discard any
archive log data sets that contain only records with log RBAs that are lower than
that RBA.

Procedure

To locate archive log data sets:

1. Resolve indoubt units of recovery. If Db2 is running with TSO, continue with
step 2 on page 394. If Db2 is running with IMS, CICS, or distributed data, the
following substeps apply:
a. Ensure that the period between one startup and the next startup is free of
any indoubt units of recovery. Ensure that no Db2 activity is going on when
you are performing this set of substeps. (To minimize impact on users,
consider planning this work for a non-prime shift.) To determine whether
indoubt units of recovery exist, issue the following Db2 command:
-DISPLAY THREAD TYPE(INDOUBT)
If you find no indoubt units of recovery, skip to step 2 on page 394.
b. If one or more indoubt units of recovery exist, take one of the following
actions:
v If IMS or CICS is involved with the indoubt units of work, start IMS or
CICS. Starting IMS or CICS causes that subsystem to resolve the indoubt
units of recovery. If the thread is a distributed indoubt unit of recovery,
restart the distributed data facility (DDF) to resolve the unit of work. If
DDF does not start or cannot resolve the unit of work, issue the following
command to resolve the unit of work:
-RECOVER INDOUBT
v Issue the following Db2 command:
-RECOVER INDOUBT

Chapter 9. Managing the log and the bootstrap data set 393
 c. Reissue the DISPLAY THREAD TYPE(INDOUBT) command to ensure that the
indoubt units have been recovered. When no indoubt units of recovery
remain, continue with step 2.
2. Find the startup log RBA. Keep at least all log records with log RBAs greater
than the one that is given in this message, which is issued at restart:
DSNR003I RESTART...PRIOR CHECKPOINT RBA=xxxxxxxxxxxx
If you suspended Db2 activity while performing step 1, restart Db2 now.
3. Find the minimum log RBA that is needed. Suppose that you have determined
to keep some number of complete image copy cycles of your least-frequently
copied table space. You now need to find the log RBA of the earliest full image
copy that you want to keep.
a. If you have any table spaces that were created so recently that no full image
copies of them have ever been taken, take full image copies of them. If you
do not take image copies of them, and you discard the archive logs that log
their creation, Db2 can never recover them.

The following SQL statement generates a list of the table spaces for
which no full image copy is available:
SELECT X.DBNAME, X.NAME, X.CREATOR, X.NTABLES, X.PARTITIONS
FROM SYSIBM.SYSTABLESPACE X
WHERE NOT EXISTS (SELECT * FROM SYSIBM.SYSCOPY Y
WHERE X.NAME = Y.TSNAME
AND X.DBNAME = Y.DBNAME
AND Y.ICTYPE = ’F’)
ORDER BY 1, 3, 2;

b. Issue the following SQL statement to find START_RBA values:

SELECT DBNAME, TSNAME, DSNUM, ICTYPE, TIMESTAMP, HEX(START_RBA)

FROM SYSIBM.SYSCOPY
ORDER BY DBNAME, TSNAME, DSNUM, TIMESTAMP;

The statement generates a list of all databases and the table spaces within
them, in ascending order by date.
c. Find the START_RBA value for the earliest full image copy (ICTYPE=F) that
you intend to keep. If your least-frequently copied table space is partitioned,
and you take full image copies by partition, use the earliest date for all the
partitions.
If you plan to discard records from SYSIBM.SYSCOPY and
SYSIBM.SYSLGRNX, note the date of the earliest image copy that you want
to keep.
4. Use job DSNTIJIC to copy all catalog and directory table spaces. Doing so
ensures that copies of these table spaces are included in the range of log
records that you plan to keep.
5. Locate and discard archive log volumes. Now that you know the minimum log
RBA, from step 3, suppose that you want to find archive log volumes that
contain only log records earlier than that. Proceed as follows:
a. Execute the print log map utility (DSNJU004) to print the contents of the
BSDS.

394 Administration Guide

 b. Find the sections of the output titled “ARCHIVE LOG COPY n DATA
SETS”. (If you use dual logging, two sections exist.) The STARTRBA and
ENDRBA columns in the output show the range of log RBAs that are
contained in each volume. Find the volumes (two, for dual logging) whose
ranges include the minimum log RBA that you found in step 3. These
volumes are the earliest volumes that you need to keep.
If no volumes have an appropriate range, one of the following cases applies:
v The minimum log RBA has not yet been archived, and you can discard
all archive log volumes.
v The list of archive log volumes in the BSDS wrapped around when the
number of volumes exceeded the maximum number that is allowed. The
maximum number is specified in the RECORDING MAX field
(MAXARCH subsystem parameter) of installation panel DSNTIPA. If the
BSDS does not register an archive log volume, it can never be used for
recovery. Therefore, consider adding information about existing volumes
to the BSDS.
Also, consider increasing the value of the MAXARCH subsystem
parameter to change the maximum number of archive log volumes that
are to be recorded in the BSDS.
c. Delete any archive log data set or volume (both copies, for dual logging)
whose ENDRBA value is less than the STARTRBA value of the earliest
volume that you want to keep.
Because BSDS entries wrap around, the first few entries in the BSDS archive
log section might be more recent than the entries at the bottom. Look at the
combination of date and time to compare age. Do not assume that you can
discard all entries above the entry for the archive log that contains the
minimum log RBA.
d. Delete the data sets. If the archives are on tape, scratch the tapes. If they are
on disks, run a z/OS utility to delete each data set. Then, if you want the
BSDS to list only existing archive volumes, use the change log inventory
utility (DSNJU003) to delete entries for the discarded volumes.
Related tasks:
Resolving indoubt units of recovery
Related reference:
DSNTIPA: Archive log data set parameters panel (Db2 Installation and
Migration)
DSNJU003 (change log inventory) (Db2 Utilities)
DSNJU004 (print log map) (Db2 Utilities)

Management of the bootstrap data set

The bootstrap data set (BSDS) is a VSAM key-sequenced data set that contains
information about the log data sets and the records that those data sets include.
The BSDS also contains information about buffer pool attributes.

The BSDS is defined with access method services when Db2 is installed and is
allocated by a DD statement in the Db2 startup procedure. It is deallocated when
Db2 terminates.

The active logs are first registered in the BSDS by job DSNTIJID, during Db2
| installation.To add a new active log data set or to delete an active log data set, you

Chapter 9. Managing the log and the bootstrap data set 395
| can use DSNJU003, the change the log inventory utility. To use DSNJU003, you
| need to first stop Db2 and then restart it after the DSNJU003 job has completed.
| Alternatively, you can add a new active log data set without stopping and starting
| Db2 by using the SET LOG command. Note that the SET LOG command does not
| support deletion of an active log data set.

Archive log data sets are dynamically allocated. When one is allocated, the data set
name is registered in the BSDS in separate entries for each volume on which the
archive log resides. The list of archive log data sets expands as archives are added,
and the list wraps around when a user-determined number of entries is reached.
The maximum number of archive log data sets that Db2 keeps in the BSDS
depends on the value of the MAXARCH subsystem parameter. The allowable
values for the MAXARCH subsystem parameter are between 10 and 10,000
(inclusive). If two copies of the archive log are being created, the BSDS will contain
records for both copies, resulting in between 20 and 20,000 entries.

You can manage the inventory of archive log data sets with the change log
inventory utility (DSNJU003).

A wide variety of tape management systems exist, along with the opportunity for
external manual overrides of retention periods. Because of that, Db2 does not have
an automated method to delete the archive log data sets from the BSDS inventory
of archive log data sets. Thus, the information about an archive log data set can be
in the BSDS long after the archive log data set is scratched by a tape management
system following the expiration of the retention period of the data set.

Conversely, the maximum number of archive log data sets might be exceeded, and
the data from the BSDS might be dropped long before the data set reaches its
expiration date.

If you specified at installation that archive log data sets are to be cataloged when
allocated, the BSDS points to the integrated catalog facility catalog for the
information that is needed for later allocations. Otherwise, the BSDS entries for
each volume register the volume serial number and unit information that is needed
for later allocation.

| The BSDS can be converted to use extended 10-byte RBA and LRSN format records
| any time after migration to Db2 11 new function mode. The BSDS must be
| converted to use extended 10-byte RBA and LRSN format records before Db2 is
| started in Db2 12.
Related concepts:
Automatic archive log deletion
Related tasks:
Convert the BSDS, Db2 catalog, and directory to 10-byte RBA and LRSN
format (Optional) (Db2 Installation and Migration)
Related reference:
| DSNJCNVT (Db2 Utilities)
| DSNJCNVB (Db2 Utilities)
DSNJU003 (change log inventory) (Db2 Utilities)
-SET LOG (Db2) (Db2 Commands)

396 Administration Guide

Restoring dual-BSDS mode
In dual-BSDS mode, Db2 keeps duplicate copies of the BSDS. If an I/O error
occurs, Db2 deallocates the failing copy and continues with a single BSDS.
However, you can restore the dual-BSDS mode.

Procedure

To restore dual-BSDS mode:

1. Use access method services to rename or delete the failing BSDS.
2. Define a new BSDS with the same name as the deleted BSDS.
3. Issue the Db2 RECOVER BSDS command to make a copy of the good BSDS in
the newly allocated data set.

BSDS copies with archive log data sets

Every time that a new archive log data set is created, a copy of the BSDS is also
created either on tape or on disk.

If the archive log is on tape, the BSDS is the first file on the first output volume. If
the archive log is on disk, the BSDS copy is a separate file, which could reside on a
separate volume.

Recommendation: For better offload performance and space utilization, use a

block size of 28672 for tape or 24576 for disk. (The default value is 24576.) If
required, you can change this value in the BLOCK SIZE field on installation panel
DSNTIPA. Also adjust the PRIMARY QUANTITY and SECONDARY QUANTITY
fields to reflect any changes in block size.

The data set names of the BSDS copy and the archive log are the same, except that
the first character of the last data set name qualifier in the BSDS name is B instead
of A, as in the following example:
Archive log name
DSNCAT.ARCHLOG1.A0000001
BSDS copy name
DSNCAT.ARCHLOG1.B0000001

If a read error occurs while copying the BSDS, the copy is not created. Message
DSNJ125I is issued, and the offload to the new archive log data set continues
without the BSDS copy.

The utility DSNJU004, print log map, lists the information that is stored in the
BSDS.
Related reference:
DSNJU004 (print log map) (Db2 Utilities)

Recommendations for changing the BSDS log inventory

You do not need to take special steps to keep the BSDS updated with records of
logging events. Db2 does that automatically.

However, you might want to change the BSDS if you:

v Add more active log data sets.

Chapter 9. Managing the log and the bootstrap data set 397
 v Copy active log data sets to newly allocated data sets, as when providing larger
active log allocations.
v Move log data sets to other devices.
v Recover a damaged BSDS.
v Discard outdated archive log data sets.
v Create or cancel control records for conditional restart.
v Add or change the DDF communication record.

You can change the BSDS by running the Db2 batch change log inventory
(DSNJU003) utility. You can only run this utility when Db2 is inactive.

You can copy an active log data set using the access method services IDCAMS
REPRO statement. The copy can be performed when only Db2 is down, because
Db2 allocates the active log data sets as exclusive (DISP=OLD) at Db2 startup. .
Related reference:
DSNJU003 (change log inventory) (Db2 Utilities)
Related information:
REPRO command (DFSMS Access Method Services for Catalogs)

398 Administration Guide

Chapter 10. Restarting Db2 after termination
When you need to restart Db2 after Db2 terminates normally or abnormally, keep
in mind these considerations, which are important for backup and recovery, and
for maintaining consistency.

About this task

The term object, used in any discussion of restarting Db2 after termination, refers to
any database, table space, or index space.
Related concepts:
Maintaining consistency across multiple systems
Related tasks:
Backing up and recovering your data

Methods of restarting
Db2 can restart in several different ways. Some options are based on how Db2
terminated or what your environment is.

Types of termination
Db2 terminates normally in response to the STOP DB2 command . If Db2 stops for
any other reason, the termination is considered abnormal.

Normal termination
In a normal termination, Db2 stops all activity in an orderly way.

You can use either STOP DB2 MODE (QUIESCE) or STOP DB2 MODE (FORCE).
The effects of each command are compared in the following table.
Table 42. Termination using QUIESCE and FORCE
Thread type QUIESCE FORCE
Active threads Run to completion Roll back
New threads Permitted Not permitted
New connections Not permitted Not permitted

You can use either command to prevent new applications from connecting to Db2.

When you issue the STOP DB2 MODE(QUIESCE) command, current threads can
run to completion, and new threads can be allocated to an application that is
running.

With IMS and CICS, STOP DB2 MODE(QUIESCE) allows a current thread to run
only to the end of the unit of recovery, unless either of the following conditions are
true:
v Open, held cursors exist.
v Special registers are not in their original state.

© Copyright IBM Corp. 1982, 2017 399

 Before Db2 can stop, all held cursors must be closed and all special registers must
be in their original state, or the transaction must complete.

With CICS, QUIESCE mode stops the CICS attachment facility, so an active task
might not necessarily run to completion.

For example, assume that a CICS transaction opens no cursors that are declared
WITH HOLD and modifies no special registers, as follows:
EXEC SQL
.
. ← -STOP DB2 MODE(QUIESCE) issued here
.
.
SYNCPOINT
.
.
.
EXEC SQL ← This receives an AETA abend

The thread is allowed to run only through the first SYNCPOINT.

When you issue the command STOP DB2 MODE(FORCE), no new threads are
allocated, and work on existing threads is rolled back.

A data object might be left in an inconsistent state, even after a shutdown with
mode QUIESCE, if it was made unavailable by the command STOP DATABASE, or
if Db2 recognized a problem with the object. MODE (QUIESCE) does not wait for
asynchronous tasks that are not associated with any thread to complete before it
stops Db2. This can result in data commands such as STOP DATABASE and
START DATABASE having outstanding units of recovery when Db2 stops. These
outstanding units of recovery become inflight units of recovery when Db2 is
restarted; then they are returned to their original states.

Abnormal terminations (abends)

An abnormal termination, or abend, is said to happen when Db2 does not terminate
in an orderly way.

An abend can leave data in an inconsistent state for any of the following reasons:
v Units of recovery might be interrupted before reaching a point of consistency.
v Committed data might not be written to external media.
v Uncommitted data might be written to external media.

Normal restart and recovery

Db2 uses its recovery log and the bootstrap data set (BSDS) to determine what to
recover when restarting. The BSDS identifies the active and archive log data sets,
the location of the most recent Db2 checkpoint on the log, and the high-level
qualifier of the integrated catalog facility catalog name.

After Db2 is initialized, the restart process goes through four phases, which are
described in the following sections:
“Phase 1: Log initialization” on page 401
“Phase 2: Current status rebuild” on page 402
“Phase 3: Forward log recovery” on page 403
“Phase 4: Backward log recovery” on page 404

400 Administration Guide

The terms inflight, indoubt, in-commit, and in-abort refer to statuses of a unit of work
that is coordinated between Db2 and another system, such as CICS, IMS, or a
remote DBMS. For definitions of those terms, see “Consistency after termination or
failure” on page 420.

At the end of the fourth phase recovery, a checkpoint is taken and committed
changes are reflected in the data.

Application programs that do not commit often enough cause long-running units
of recovery (URs). These long-running URs might be inflight after a Db2 failure.
Inflight URs can extend Db2 restart time. You can restart Db2 more quickly by
postponing the backout of long-running URs. Installation options LIMIT
BACKOUT and BACKOUT DURATION establish what work to delay during
restart.

If your Db2 subsystem has the UR checkpoint count option enabled, Db2 generates
console message DSNR035I and trace records for IFCID 0313 to inform you about
long-running URs. The UR checkpoint count option is enabled at installation time,
through field UR CHECK FREQ on panel DSNTIPL.

If your Db2 subsystem has the UR log threshold option enabled, Db2 generates
console message DSNB260I when an inflight UR writes more than the
installation-defined number of log records. Db2 also generates trace records for
IFCID 0313 to inform you about these long-running URs. The UR log threshold
option is established at installation time, through field UR LOG WRITE CHECK on
panel DSNTIPL.

Restart of large object (LOB) table spaces is like restart of other table spaces. LOB
table spaces that are defined with LOG NO do not log LOB data, but they log
enough control information (and follow a force-at-commit policy) so that they can
restart without loss of data integrity.

After Db2 has gone through a group or normal restart that involves group buffer
pool (GBP) failure, group buffer pool recovery pending (GRECP) can be
automatically initiated for all objects except the object that is explicitly deferred
during restart (ZPARM defer), or the object that is associated with the indoubt or
postponed-abort UR.
Related reference:
DSNTIPL: Active log data set parameters (Db2 Installation and Migration)

Phase 1: Log initialization

During the first restart phase, Db2 attempts to locate the last log RBA that was
written before termination. Logging continues at the subsequent RBA.

In phase 1:
1. Db2 compares the high-level qualifier of the integrated catalog facility catalog
name that is in the BSDS with the corresponding qualifier of the name in the
current subsystem parameter module (DSNZPxxx).
v If they are equal, processing continues with step 2 on page 402.
v If they are not equal, Db2 terminates with this message:
DSNJ130I ICF CATALOG NAME IN BSDS
DOES NOT AGREE WITH DSNZPARM.
BSDS CATALOG NAME=aaaaa,
DSNZPARM CATALOG NAME=bbbbb

Chapter 10. Restarting Db2 after termination 401

 Without the check, the next Db2 session could conceivably update an entirely
different catalog and set of table spaces. If the check fails, you probably have
the wrong parameter module. Start Db2 with the command START DB2
PARM(module-name), and name the correct module.
2. Db2 checks the consistency of the timestamps in the BSDS.
v If both copies of the BSDS are current, Db2 tests whether the two timestamps
are equal.
– If they are equal, processing continues with step 3.
– If they are not equal, Db2 issues message DSNJ120I and terminates. That
can happen when the two copies of the BSDS are maintained on separate
disk volumes (as recommended) and one of the volumes is restored while
Db2 is stopped. Db2 detects the situation at restart.
To recover, copy the BSDS with the latest timestamp to the BSDS on the
restored volume. Also recover any active log data sets on the restored
volume, by copying the dual copy of the active log data sets onto the
restored volume.
v If one copy of the BSDS was deallocated, and logging continued with a
single BSDS, a problem could arise. If both copies of the BSDS are
maintained on a single volume, and the volume was restored, or if both
BSDS copies were restored separately, Db2 might not detect the restoration.
In that case, log records that are not noted in the BSDS would be unknown
to the system.
3. Db2 finds in the BSDS the log RBA of the last log record that was written
before termination.
The highest RBA field (as shown in the output of the print log map utility) is
updated only when the following events occur:
v When Db2 is stopped normally (STOP DB2).
v When active log writing is switched from one data set to another.
v When Db2 has reached the end of the log output buffer. The size of this
buffer is determined by the OUTPUT BUFFER field of installation panel
DSNTIPL.
4. Db2 scans the log forward, beginning at the log RBA of the most recent log
record, up to the last control interval (CI) that was written before termination.
5. Db2 prepares to continue writing log records at the next CI on the log.
6. Db2 issues message DSNJ099I, which identifies the log RBA at which logging
continues for the current Db2 session. That message signals the end of the log
initialization phase of restart.
Related reference:
DSNTIPL: Active log data set parameters (Db2 Installation and Migration)
Related information:
Recovering from BSDS failures

Phase 2: Current status rebuild

During the second restart phase, Db2 determines the statuses of objects at the time
of termination. By the end of the phase, Db2 has determined whether any units of
recovery were interrupted by the termination.

In phase 2:
1. Db2 checks the BSDS to find the log RBA of the last complete checkpoint before
termination.

402 Administration Guide

 2. Db2 processes the RESTART or DEFER option of the parameter module of the
START DB2 command if any exist. The default is always RESTART ALL.
3. Db2 reads every log record from that checkpoint up to the end of the log
(which was located during phase 1), and identifies:
| v All exception conditions that exist for each database and all image copy
| information that is related to the DSNDB01.SYSUTILX, DSNDB01.DBD01,
| DSNDB06.SYSTSCPY, and DSNDB01.SYSDBDXA table spaces.
v All objects that are open at the time of termination.
v How far back in the log to go to reconstruct data pages that were not written
to disk.
The number of log records that are written between one checkpoint and the
next is set when Db2 is installed.
You can temporarily modify the checkpoint frequency by using the command
SET LOG. The value that you specify persists while Db2 is active; on restart,
Db2 uses the checkpoint type and frequency that is specified on installation
panel DSNTIPL1.
4. Db2 issues message DSNR004I, which summarizes the activity that is required
at restart for outstanding units of recovery.
5. Db2 issues message DSNR007I if any outstanding units of recovery are
discovered. The message includes, for each outstanding unit of recovery, its
connection type, connection ID, correlation ID, authorization ID, plan name,
status, log RBA of the beginning of the unit of recovery (URID), and the date
and time of its creation.

During phase 2, no database changes are made, nor are any units of recovery
completed. Db2 determines what processing is required by phase 3, forward log
recovery, before access to databases is allowed.
Related reference:
-SET LOG (Db2) (Db2 Commands)
DSNTIPL: Active log data set parameters (Db2 Installation and Migration)

Phase 3: Forward log recovery

During the third restart phase, Db2 completes the processing for all committed
changes and database write operations.

Db2 processing during phase 3 includes:

v Making all database changes for each indoubt unit of recovery and locking the
data to prevent access to it after restart
v Making database changes for inflight and in-abort units of recovery
v In the case of group restarts in which locks have been lost, acquiring locks to
prevent access to data that is in use by those units of recovery

Restart time is longer when lock information needs to be recovered during a group
restart, because Db2 needs to go back to the earliest begin_UR for an inflight UR
belonging to that subsystem. This is necessary to rebuild the locks that member
has obtained during the inflight UR. (A normal restart goes back only as far as the
earliest RBA that is needed for database writes or is associated with the begin_UR
of indoubt units of recovery.)

Db2 executes these steps:

1. Db2 detects whether a page set that is being recovered is at the same level ID
as it was when the page set was last closed. If it is not, Db2 issues message

Chapter 10. Restarting Db2 after termination 403

 DSNB232I and places the pages for that object on the logical page list (LPL).
Db2 does not restart that object. In this case, you must recover from the
down-level page set by using one of the methods described in Recovering
from a down-level page set problem.
2. Db2 scans the log forward, beginning at the lowest (earliest) log RBA that is
either required for completion of database writes or that is associated with the
“Begin Unit of Recovery” of units of recovery that require locks.
That log RBA is determined during phase 2. REDO log records for all units of
recovery are processed in this phase.
3. Db2 uses the log RBA of the earliest potential REDO log record for each object
(determined during phase 2). All earlier changes to the object have been
written to disk; therefore, Db2 ignores their log records.
4. Db2 reads the data or index page for each remaining REDO log record. The
page header registers the log RBA of the record of the last change to the page.
v If the log RBA of the page header is greater than or equal to that of the
current log record, the logged change has already been made and written to
disk, and the log record is ignored.
v If the log RBA in the page header is less than that of the current log record,
the change has not been made; Db2 makes the change to the page in the
buffer pool.
5. Db2 writes pages to disk as the need for buffers demands it.
6. Db2 marks the completion of each unit of recovery that is processed. If restart
processing terminates later, those units of recovery do not reappear in status
lists.
7. Db2 stops scanning at the current end of the log.
8. Db2 writes to disk all modified buffers that are not yet written.
9. Db2 issues message DSNR005I, which summarizes the number of remaining
in-commit or indoubt units of recovery. No in-commit units of recovery
should exist because all processing for these units should have completed. The
number of indoubt units of recovery should be equal to the number that is
specified in the previous DSNR004I restart message.
10. Db2 issues message DSNR007I, which identifies any outstanding unit of
recovery that still must be processed.

If Db2 encounters a problem while applying log records to an object during phase
3, the affected pages are placed in the logical page list. Message DSNI001I is issued
once per page set or partition, and message DSNB250E is issued once per page.
Restart processing continues.

Db2 issues status message DSNR031I periodically during this phase.

Related information:
Recovering from a down-level page set problem

Phase 4: Backward log recovery

During the fourth restart phase, Db2 changes that were performed for inflight or
in-abort units of recovery are reversed.

In phase 4:
1. Db2 scans the log backward, starting at the current end. The scan continues
until the earliest “Begin Unit of Recovery” record for any outstanding inflight
or in-abort unit of recovery.

404 Administration Guide

 If you specified limited backout processing, the scan might stop prematurely
(however, Db2 verifies that all catalog and directory changes are completely
backed out). In this case, the scan completes after Db2 receives the RECOVER
POSTPONED command. You can have Db2 automatically issue this command
after restart by specifying the AUTO option for limited backout processing, or
you can issue this command manually.
2. Db2 reads the data or index page for each remaining undo log record. The page
header registers the log RBA of the record of the last change to the page.
v If the log RBA of the page header is greater than or equal to that of the
current log record, the logged change has already been made and written to
disk, so Db2 reverses it.
v If the log RBA in the page header is less than that of the current log record,
the change has not been made and Db2 ignores it.
3. Db2 writes redo compensation information in the log for each undo log record,
as it does when backing out a unit of recovery. The redo records describe the
reversal of the change and facilitate media recovery. They are written under all
circumstances, even when:
v The disk version of the data did not need to be reversed.
v The page set has pages on the LPL.
v An I/O error occurred on the disk version of the data.
v The disk version of the data could not be allocated or opened.
v The page set is deferred at restart using the DEFER subsystem parameter.
4. Db2 writes pages to disk as the need for buffers demands it.
5. Db2 writes to disk all modified buffers that have not yet been written.
6. Db2 issues message DSNR006I, which summarizes the number of remaining
inflight, in-abort, and postponed-abort units of recovery. The number of inflight
and in-abort units of recovery should be zero; the number of postponed-abort
units of recovery might not be zero.
7. Db2 marks the completion of each completed unit of recovery in the log so
that, if restart processing terminates, the unit of recovery is not processed again
at the next restart.
8. If necessary, Db2 reacquires write claims for the objects on behalf of the
indoubt and postponed-abort units of recovery.
9. Db2 takes a checkpoint after all database writes have been completed.

If Db2 encounters a problem while applying a log record to an object during phase
4, the affected pages are placed in the logical page list. Message DSNI001I is issued
once per page set or partition, and message DSNB250E is issued once per page.
Restart processing continues.

Db2 issues status message DSNR031I periodically during this phase.

Automatic restart
If you run Db2 in a sysplex, you can have the automatic restart function of z/OS
automatically restart Db2 or IRLM after a failure.

When Db2 or IRLM stops abnormally, z/OS determines whether z/OS failed too,
and where Db2 or IRLM should be restarted. It then restarts Db2 or IRLM.

You must have Db2 installed with a command prefix scope of S to take advantage
of automatic restart.

Chapter 10. Restarting Db2 after termination 405

 Restart in a data sharing environment
In a data sharing environment, restart processing coordinates data recovery across
more than one Db2 subsystem.

When certain critical resources are lost, restart includes additional processing to
recover and rebuild those resources. This process is called group restart.
Related concepts:
Group restart phases (Db2 Data Sharing Planning and Administration)

Restart implications for table spaces that are not logged

Even if all tables that are modified by a transaction reside in table spaces that are
not logged, a unit of recovery is established before any of those updates are
performed. Undo processing continues to read the log in the backward direction,
looking for undo log records that need to be applied. Undo processing stops when
it detects the beginning of this unit of recovery as recorded on the log.

Therefore you still need to perform frequent commits to limit the distance that
undo processing might need to go backward on the log to find the beginning of
the unit of recovery. If a transaction that is not logged does not do frequent
commits, it is subject to being reported as a long-running unit of recovery in
message DSNR035I. This means that if such a unit of recovery persists for a
duration that qualifies as a long-running unit of recovery, message DSNR035I is
issued to identify it.

If, during restart, you need to undo work that has not been logged because of the
NOT LOGGED attribute, the table space loses its data integrity, and therefore must
be recovered. Recovery can be accomplished by using the RECOVER utility or by
reinserting the appropriate data. For example, a summary table can be re-created
by one or more INSERT statements; a materialized query table can be rebuilt by
using a REFRESH TABLE SQL statement.

To mark the need for recovery, the table space or partition is marked with
RECOVER-pending status. To prevent any access to the corrupt data, the table
space or partition is placed in the LPL. When undo processing places a table space
or partition in the logical page list (LPL) and marks it with RECOVER-pending
status, it also places all of the updated indexes on all tables in the table space in
the LPL. The corresponding partitions of data-partitioned secondary indexes
(DPSIs) are placed in the LPL, which prevents other processes that use index-only
access from seeing data whose integrity is in doubt. These indexes are also marked
with REBUILD-pending status.

After restart, when Db2 is operational, if undo processing is needed for a unit of
recovery in which modifications were made to the table space that was not logged,
the entire table space or partition is placed in the LPL, and the table space is
marked with RECOVER-pending status. This can happen, for example, as a result
of a rollback, abort, trigger error, or duplicate key or referential constraint
violation. The LPL ensures that no concurrently running agent can see any of the
data whose integrity is in doubt.

Avoid duplicate key or referential constraint violations in table spaces that are not
logged because the result is an unavailable table space that requires manual action.

When a table space or partition is placed in the LPL because undo processing is
needed for a table space that is not logged, either at restart time or during rollback

406 Administration Guide

 processing, automatic LPL recovery is not initiated, and a START DATABASE
command identifying this table space has no effect on its LPL status.

Conditional restart
A conditional restart is a Db2 restart that is directed by a user-defined conditional
restart control record (CRCR).

If you want to skip some portion of the log processing during Db2 restart, you can
use a conditional restart. However, if a conditional restart skips any database
change log records, data in the associated objects becomes inconsistent, and any
attempt to process them for normal operations might cause unpredictable results.
The only operations that can safely be performed on the objects are recovery to a
prior point of consistency, total replacement, or dropping.

In unusual cases, you might choose to make inconsistent objects available for use
without recovering them. For example, the only inconsistent object might be a table
space that is dropped as soon as Db2 is restarted, or the Db2 subsystem might be
used only for testing application programs that are still under development. In
cases like those, where data consistency is not critical, normal recovery operations
can be partially or fully bypassed by using conditional restart control records in
the BSDS.

Restart considerations for identity columns

Cold starts and conditional restarts that skip forward recovery can cause additional
data inconsistency within identity columns and sequence objects. After such
restarts, Db2 might assign duplicate identity column values and create gaps in
identity column sequences.
Related concepts:
Restarting a member with conditions (Db2 Data Sharing Planning and
Administration)
Related reference:
DSNJU003 (change log inventory) (Db2 Utilities)

Terminating Db2 normally

Whenever possible, ensure that Db2 terminates normally.

Procedure

To terminate Db2, issue either of the following commands:

v -STOP DB2 MODE (QUIESCE)
v -STOP DB2 MODE (FORCE)
During shutdown, use the command DISPLAY THREAD to check the shutdown
progress. If shutdown is taking too long, you can issue STOP DB2 MODE
(FORCE), but rolling back work can take as long as or longer than the completion
of QUIESCE.

Chapter 10. Restarting Db2 after termination 407

 Results

When stopping in either mode, the following steps occur:

1. Connections end.
2. Db2 ceases to accept commands.
3. Db2 disconnects from the IRLM.
4. The shutdown checkpoint is taken and the BSDS is updated.

Restarting automatically
You control how automatic restart works by using automatic restart policies.

About this task

When the automatic restart function is active, the default action is to restart the
subsystems when they fail. If this default action is not what you want, then you
must create a policy that defines the action that you want taken.

Procedure

To create a policy:

Identify the element names of the Db2 and IRLM subsystems.

v For a non-data-sharing Db2, the element name is 'Db2$' concatenated by the
subsystem name (Db2$DB2A, for example). To specify that a Db2 subsystem is
not to be restarted after a failure, include RESTART_ATTEMPTS(0) in the policy
for that Db2 element.
v For local mode IRLM, the element name is a concatenation of the IRLM
subsystem name and the IRLM ID. For global mode IRLM, the element name is
a concatenation of the IRLM data sharing group name, the IRLM subsystem
name, and the IRLM ID.
Related reference:
Adding MVS systems to a sysplex

Deferring restart processing

When a specific object is causing problems, you can defer its restart processing by
starting Db2 and preventing the problem object from going through restart
processing.

About this task

When you defer restart of an object, Db2 puts pages that are necessary for restart
of the object in the logical page list (LPL). Only those pages are inaccessible; the
rest of the object can still be accessed after restart.

Restrictions apply to Db2 activation of restart processing for available objects.

When DEFER ALL is specified at a site that has RECOVERYSITE for the SITETYP
subsystem parameter value, all pages for an object that is deferred are placed in
the LPL (as a page range, not as a large list of individual pages). The following
conditions apply:

408 Administration Guide

v If Db2 cannot open and read the DBD01 table space it does not put Db2 into
ACCESS(MAINT), and DSNX204I is not issued. Instead either DSNT500I or
DSNT501I 'resource unavailable' is issued.
v For a deferred restart scenario that needs to recover all Db2 objects after Db2 is
up, the recommendation is to set the DEFER and ALL subsystem parameters on
panel DSNTIPS and start Db2 with the ACCESS(MAINT) option.
v If DEFER ALL is specified, DSNX204I is not issued.
v With DEFER ALL, Db2 will not open any data sets, including SYSLGRNX and
DSNRTSTS, during any phase of restart, and will not attempt to apply any log
records.

Procedure

To defer restart processing, use one of the following approaches:

v To vary the device (or volume) on which the objects reside offline:
If the data sets that contain an object are not available, and the object requires
recovery during restart, Db2 flags it as stopped and requiring deferred restart.
Db2 then restarts without it.
v To delay the backout of a long-running UR, specify the following subsystem
parameters:
– LBACKOUT defined as YES, AUTO, LIGHT, or LIGHTAUTO indicates that
some backout processing is to postponed when restarting Db2. Issue the
RECOVER POSTPONED command to complete the backout processing when
the YES option is selected. Db2 does the backout work automatically after
Db2 is running and receiving new work when the AUTO option is selected.
For more information, see LIMIT BACKOUT field (LBACKOUT subsystem
parameter) (Db2 Installation and Migration).
– BACKODUR indicates the number of log records, specified as a multiplier,
that are to be read during the backward log scan phase of restart. For more
information see BACKOUT DURATION field (BACKODUR subsystem
parameter) (Db2 Installation and Migration).
The amount of backout processing that is to be postponed is determined by:
– The frequency of checkpoints
– The BACKODUR subsystem parameter
– The characteristics of the inflight and in-abort activity when Db2 stopped
Selecting a limited backout affects log processing during restart. The backward
processing of the log proceeds until the oldest inflight or in-abort UR with
activity against the catalog or directory is backed out, and until the requested
number of log records have been processed.
v To name the object with DEFER when installing Db2: On installation panel
DSNTIPS, you can use the following options:
– DEFER ALL defers restart log apply processing for all objects, including Db2
catalog and directory objects.
– DEFER list_of_objects defers restart processing only for objects in the list.
Alternatively, you can specify RESTART list_of_objects, which limits restart
processing to the list of objects in the list.
DEFER does not affect processing of the log during restart. Therefore, even if
you specify DEFER ALL, Db2 still processes the full range of the log for both the
forward and backward log recovery phases of restart. However, logged

Chapter 10. Restarting Db2 after termination 409

 operations are not applied to the data set. For more information, see DSNTIPS:
Databases and spaces to start automatically panel (Db2 Installation and
Migration).
Related tasks:
Resolving postponed units of recovery
Related reference:
-RECOVER POSTPONED (Db2) (Db2 Commands)
-START DB2 (Db2) (Db2 Commands)

Performing conditional restart

Normal recovery operations can be partially or fully bypassed by using conditional
restart control records in the BSDS.

Procedure

To perform a conditional restart:

1. Optional: When considering a conditional restart, it is often useful to run the
DSN1LOGP utility and review a summary report of the information contained
in the log.
2. While Db2 is stopped, run the change log inventory utility by using the
CRESTART control statement to create a new conditional restart control record.
3. Restart Db2. The recovery operations that take place are governed by the
current conditional restart control record.
4. Optional: For data sharing environments, use the LIGHT(YES) or
LIGHT(NOINDOUBTS) parameter on the START DB2 command to quickly
recover retained locks on a Db2 member.
Related concepts:
Messages at start

Conditional restart with system-level backups

You can recover a Db2 subsystem to a point in time (system point-in-time
recovery) where the log copy pool is restored from a system-level backup. In this
case, perform a conditional restart with a log truncation point that is less than or
equal to the data complete log record sequence number (LRSN) of the system-level
backup.

For example, create the conditional restart record by using the data complete LRSN
as the CRESTART ENDRBA, ENDLRSN, or SYSPITR log truncation point for the
change log inventory utility, DSNJU003. The data complete LRSN is externalized in
the DSNU1614I message that is issued by the BACKUP SYSTEM utility when a
system-level backup completes.

You can use the print log map utility, DSNJU004, to print the information for a
system-level backup. This information includes the data complete LRSN. Using the
DSNJU004 utility is beneficial if you did not preserve the job output or the log that
contains the DSNU1614I message.

410 Administration Guide

 Options for recovery operations after conditional restart
The recovery operations that take place during restart are controlled by the
currently active conditional restart control record. An active control record is
created or deactivated by running the change log inventory utility with the
CRESTART control statement.

You can choose to:

v Retain a specific portion of the log for future Db2 processing
v Read the log forward to recover indoubt and uncommitted units of recovery
v Read the log backward to back out uncommitted and in-abort units of recovery
v Do a cold start, not processing any log records

A conditional restart record that specifies left truncation of the log causes any
postponed-abort units of recovery that began earlier than the truncation RBA to
end without resolution. The combination of unresolved postponed-abort units of
recovery can cause more records than requested by the BACKODUR system
parameter to be processed. The left truncation RBA takes precedence over
BACKODUR in this case.

Be careful about doing a conditional restart that discards log records. If the
discarded log records contain information from an image copy of the Db2
directory, a future execution of the RECOVER utility on the directory fails.

Conditional restart records

In addition to information describing the active and archive logs, the BSDS
contains two queues of records that are associated with conditional restart.

The two queues are:

v A wrap-around queue of conditional restart control records. Each element in the
queue records the choices that you made when you created the record and the
progress of the restart operation that it controls. When the operation is complete,
the use count is set at 1 for the record, and the record is not used again.
v A queue of checkpoint descriptions. Because a conditional restart can specify use
of a particular log record range, the recovery process cannot automatically use
the most recent checkpoint. The recovery process must find the latest checkpoint
within the specified range, and that checkpoint queue is then used for that
purpose.

You can use the utility DSN1LOGP to read information about checkpoints and
conditional restart control records.
Related reference:
DSN1LOGP (Db2 Utilities)

Resolving postponed units of recovery

You can postpone some of the backout work that is associated with long-running
units of work during system restart by using the LBACKOUT subsystem
parameter. By delaying such backout work, the Db2 subsystem can be restarted
more quickly.

Chapter 10. Restarting Db2 after termination 411

 About this task

If you specify LBACKOUT = YES or LIGHT, you must use the RECOVER
POSTPONED command to resolve postponed units of recovery.

Procedure

To complete postponed backout processing on all units of recovery:

Use the RECOVER POSTPONED command. You cannot specify a single unit of
work for resolution. This command might take several hours to complete
depending on the content of the long-running job.
In some circumstances, you can elect to use the CANCEL option of the RECOVER
POSTPONED command. This option leaves the objects in an inconsistent state
(REFP) that you must resolve before using the objects. However, you might choose
the CANCEL option for the following reasons:
v You determine that the complete recovery of the postponed units of recovery
will take more time to complete than you have available. You also determine it
is faster to either recover the objects to a prior point in time or run the LOAD
utility with the REPLACE option.
v You want to replace the existing data in the object with new data.
v You decide to drop the object. To drop the object successfully, complete the
following steps:
1. Issue the RECOVER POSTPONED command with the CANCEL option.
2. Issue the DROP TABLESPACE statement.
v You do not have the Db2 logs to successfully recover the postponed units of
recovery.

Example

Output from the RECOVER POSTPONED command consists of informational

messages. In the following example, backout processing was performed against
two table space partitions and two index partitions:

| DSNV435I ! RESOLUTION OF POSTPONED ABORT URS HAS BEEN SCHEDULED

| DSN9022I ! DSNVRP ’RECOVER POSTPONED’ NORMAL COMPLETION
| DSNR047I ! DSNRBMON POSTPONED ABORT BACKOUT
| PROCESSING LOG RECORD AT RBA 00000000000002055000 TO RBA 00000000000001E6A20E
| DSNR047I ! DSNRBMON POSTPONED ABORT BACKOUT
| PROCESSING LOG RECORD AT RBA 00000000000002049000 TO RBA 00000000000001E6A20E
| DSNI024I ! DSNIARPL BACKOUT PROCESSING HAS COMPLETED
| FOR PAGESET DSNDB04 .I PART 00000004.
| DSNI024I ! DSNIARPL BACKOUT PROCESSING HAS COMPLETED
| FOR PAGESET DSNDB04 .PT PART 00000004.
| DSNI024I ! DSNIARPL BACKOUT PROCESSING HAS COMPLETED
| FOR PAGESET DSNDB04 .I PART 00000002.
| DSNI024I ! DSNIARPL BACKOUT PROCESSING HAS COMPLETED
| FOR PAGESET DSNDB04 .PT PART 00000002.

Figure 37. Example of output from RECOVER POSTPONED processing

If a required page cannot be accessed during RECOVER POSTPONED processing,

or if any other error is encountered while attempting to apply a log record, the
page set or partition is deferred and processing continues. Db2 writes a
compensation log record to reflect those deferrals and places the page in the logical
page list. Some errors that are encountered during recovery of indexes cause the
entire page set to be placed in the logical page list. Some errors halt the

412 Administration Guide

 construction of the compensation log and mark the page set as RECP.
Related tasks:
Deferring restart processing
Related reference:
LIMIT BACKOUT field (LBACKOUT subsystem parameter) (Db2 Installation
and Migration)
-RECOVER POSTPONED (Db2) (Db2 Commands)
DROP (Db2 SQL)

Recovering from an error during RECOVER POSTPONED processing

When an error prevents logging of a compensation log record, Db2 terminates
abnormally.

Procedure

If Db2 terminates abnormally:

1. Fix the error.
2. Restart Db2.
3. Re-issue the RECOVER POSTPONED command if automatic backout
processing has not been specified.
If the RECOVER POSTPONED processing lasts for an extended period, the
output includes DSNR047I messages to help you monitor backout processing.
These messages show the current RBA that is being processed and the target
RBA.
Related tasks:
Deferring restart processing
Related reference:
-RECOVER POSTPONED (Db2) (Db2 Commands)
Related information:
DSNR047I (Db2 Messages)

Chapter 10. Restarting Db2 after termination 413

414 Administration Guide
Chapter 11. Maintaining consistency across multiple systems
Data consistency issues arise when Db2 acts in conjunction with other systems,
such as IMS, CICS, or remote database management systems (DBMSs).

Multiple system consistency

Db2 can work with other DBMSs, including IMS, and other types of remote
DBMSs through the distributed data facility (DDF). Db2 can also work with other
Db2 subsystems through the DDF.

If data in more than one subsystem is to be consistent, all update operations at all
subsystems for a single logical unit of work must either be committed or backed
out.

Two-phase commit process

In a distributed system, the actions of a logical unit of work might occur at more
than one system.

When these actions update recoverable resources, the commit process ensures that
either all the effects of the logical unit of work persist, or none of the effects
persist. The commit process ensures this outcome despite component, system, or
communications failures.

Db2 uses a two-phase commit process to communicate between subsystems. The

two-phase commit process is controlled by one of the subsystems, called the
coordinator. The other systems that are involved are called the participants. Db2,
CICS, or WebSphere® Application Server are always the coordinator when they
interact with Db2. In transactions that include those systems, Db2 is always a
participant. Db2 is always the coordinator when it interacts with TSO, and Db2
completely controls the commit process in these interactions. In interactions with
other DBMSs, including other Db2 subsystems, your local Db2 can be either the
coordinator or a participant.

The following figure illustrates the two-phase commit process. Events in the
coordinator (IMS, CICS, or Db2) are shown on the upper line, events in the
participant on the lower line.

© Copyright IBM Corp. 1982, 2017 415

 Coordinator Phase 1 Phase 2
Old point of Commit Instant of New point of
consistency process begins Commit consistency
Application
synchronization
point

Time
1 2 3 4 5 6 7 8 9 10 11 12 13
line

Participant
Phase 1 Phase 2

Old point of New point of

consistency consistency

Begin unit of End unit of

recovery recovery

Period a Period b Period c Period d

Data is Data is Data is Data is

backed out backed out indoubt at committed
at restart at restart restart and at restart
either backed
out or
committed

Figure 38. Time line illustrating a commit that is coordinated with another subsystem

The numbers below are keyed to the timeline in the figure. The resultant state of
the update operations at the participant are shown between the two lines.
1. The data in the coordinator is at a point of consistency.
2. An application program in the coordinator calls the participant to update
some data, by executing an SQL statement.
3. This starts a unit of recovery in the participant.
4. Processing continues in the coordinator until an application synchronization
point is reached.
5. The coordinator then starts commit processing. IMS can do that by using a
DL/I CHKP call, a fast path SYNC call, a GET UNIQUE call to the I/O PCB,
or a normal application termination. CICS uses a SYNCPOINT command or a
normal application termination. A Db2 application starts commit processing
by an SQL COMMIT statement or by normal termination. Phase 1 of commit
processing begins.
6. The coordinator informs the participant that it is to prepare for commit. The
participant begins phase 1 processing.
7. The participant successfully completes phase 1, writes this fact in its log, and
notifies the coordinator.
8. The coordinator receives the notification.
9. The coordinator successfully completes its phase 1 processing. Now both
subsystems agree to commit the data changes because both have completed
phase 1 and could recover from any failure. The coordinator records on its log
the instant of commit—the irrevocable decision of the two subsystems to make
the changes.

416 Administration Guide

 The coordinator now begins phase 2 of the processing—the actual
commitment.
10. The coordinator notifies the participant that it can begin phase 2.
11. The participant logs the start of phase 2.
12. Phase 2 is successfully completed, which establishes a new point of
consistency for the participant. The participant then notifies the coordinator
that it is finished with phase 2.
13. The coordinator finishes its phase 2 processing. The data that is controlled by
both subsystems is now consistent and available to other applications.

On some occasions, the coordinator invokes the participant when no participant

resource has been altered since the completion of the last commit process. This can
happen, for example, when a SYNCPOINT is issued after performance of a series
of SELECT statements or when end-of-task is reached immediately after a
SYNCPOINT is issued. When this occurs, the participant performs both phases of
the two-phase commit during the first commit phase and records that the user or
job is read-only at the participant.

Commit coordinator and multiple participants

The principles and methods for maintaining consistency across more than two
systems are similar to those that are used to ensure consistency across two
systems. The main difference involves the role of a system as coordinator or
participant when a unit of work spans multiple systems.

The coordinator of a unit of work that involves two or more other DBMSs must
ensure that all systems remain consistent. After the first phase of the two-phase
commit process, the Db2 coordinator waits for the other participants to indicate
that they can commit the unit of work. If all systems are able, the Db2 coordinator
sends the commit decision and each system commits the unit of work.

If even one system indicates that it cannot commit, the Db2 coordinator
communicates the decision to roll back the unit of work at all systems. This
process ensures that data among multiple DBMSs remains consistent. When Db2 is
the participant, it follows the decision of the coordinator, whether the coordinator
is another Db2 or another DBMS.

Db2 is always the participant when interacting with IMS, CICS, or WebSphere
Application Server systems. However, Db2 can also serve as the coordinator for
other DBMSs or for other Db2 subsystems in the same unit of work. For example,
if Db2 receives a request from a coordinating system that also requires data
manipulation on another system, Db2 propagates the unit of work to the other
system and serves as the coordinator for that system.

In the following figure, DB2A is the participant for an IMS transaction, but Db2
becomes the coordinator for the two database servers (AS1 and AS2), for DB2B,
and for its respective Db2 servers (DB2C, DB2D, and DB2E).

Chapter 11. Maintaining consistency across multiple systems 417

 DB2C
AS1
Server

IMS/ DB2D
DB2A DB2B
CICS Server

DB2E
AS2 Server

Figure 39. Illustration of multi-site unit of work

If the connection between DB2A and the coordinating IMS system fails, the
connection becomes an indoubt thread. However, DB2A connections to the other
systems are still waiting and are not considered indoubt. Automatic recovery
occurs to resolve the indoubt thread. When the thread is recovered, the unit of
work commits or rolls back, and this action is propagated to the other systems that
are involved in the unit of work.

Illustration of multi-site update

You can set up a multi-site update that involves one coordinator and two
participants.

The following figure shows an example of a multi-site update with one coordinator
and two participants.

Coordinator
Phase 1 Phase 2

Prepare Commit

Time 1 2 3 4 5
line

Participant 1 Request Forget

Commit

Participant 2 Forget Forget

Figure 40. Illustration of multi-site update

The following process describes each action that the figure illustrates.
Phase 1
1. When an application commits a logical unit of work, it signals the Db2
coordinator. The coordinator starts the commit process by sending
messages to the participants to determine whether they can commit.
2. A participant (Participant 1) that is willing to let the logical unit of work
be committed, and which has updated recoverable resources, writes a

418 Administration Guide

 log record. It then sends a request-commit message to the coordinator
and waits for the final decision (commit or roll back) from the
coordinator. The logical unit of work at the participant is now in the
prepared state.
If a participant (Participant 2) has not updated recoverable resources, it
sends a forget message to the coordinator, releases its locks, and forgets
about the logical unit of work. A read-only participant writes no log
records. The disposition (commit or rollback) of the logical unit of work
is irrelevant to the participant.
If a participant wants to have the logical unit of work rolled back, it
writes a log record and sends a message to the coordinator. Because a
message to roll back acts like a veto, the participant in this case knows
that the logical unit of work is to be rolled back by the coordinator. The
participant does not need any more information from the coordinator
and therefore rolls back the logical unit of work, releases its locks, and
forgets about the logical unit of work. (This case is not illustrated in the
figure.)
Phase 2
1. After the coordinator receives request-commit or forget messages from
all its participants, it starts the second phase of the commit process. If
at least one of the responses is request-commit, the coordinator writes a
log record and sends committed messages to all the participants who
responded to the prepare message with request-commit. If neither the
participants nor the coordinator have updated any recoverable
resources, no second phase occurs, and no log records are written by
the coordinator.
2. Each participant, after receiving a committed message, writes a log
record, sends a response to the coordinator, and then commits the
logical unit of work.
If any participant responds with a roll back message, the coordinator
writes a log record and sends a roll back message to all participants.
Each participant, after receiving a roll back message writes a log record,
sends an acknowledgment to the coordinator, and then rolls back the
logical unit of work. (This case is not illustrated in the figure.)
3. The coordinator, after receiving the responses from all the participants
that were sent a message in the second phase, writes an 'end' record
and forgets the logical unit of work.

Important: If you try to resolve any indoubt threads manually, you need to know
whether the participants committed or rolled back their units of work. With this
information, you can make an appropriate decision regarding processing at your
site.

Termination for multiple systems

Termination for multiple systems is like termination for single systems, but with
some additional considerations.
v Using STOP DB2 MODE(FORCE) could create indoubt units of recovery for
threads that are between commit processing phases. These indoubt threads are
resolved after you reconnect to the coordinator.
v Data that is updated by an indoubt unit of recovery is locked and unavailable
for use by others. The unit could be indoubt when Db2 was stopped, or it could
be indoubt from an earlier termination that is not yet resolved.

Chapter 11. Maintaining consistency across multiple systems 419

 v A Db2 system failure can leave a unit of recovery in an indoubt state if the
failure occurs between phase 1 and phase 2 of the commit process.

Consistency after termination or failure

If a Db2 failure occurs while Db2 acts as a coordinator, Db2 has the information to
determine whether to commit or roll back after restart. However, if a Db2 failure
occurs while Db2 acts as the participant, Db2 must determine after restart whether
to commit or roll back units of recovery that were active at the time of the failure.

For certain units of recovery, Db2 has enough information to make the decision.
For others, Db2 must get information from the coordinator after the connection is
re-established.

The status of a unit of recovery after a termination or failure depends on the

moment when the incident occurred. The following figure shows possible statuses.

Coordinator Phase 1 Phase 2

Old point of Commit Instant of New point of
consistency process begins Commit consistency
Application
synchronization
point

Time
1 2 3 4 5 6 7 8 9 10 11 12 13
line

Participant
Phase 1 Phase 2

Old point of New point of

consistency consistency

Begin unit of End unit of

recovery recovery

Period a Period b Period c Period d

Data is Data is Data is Data is

backed out backed out indoubt at committed
at restart at restart restart and at restart
either backed
out or
committed

Figure 41. Time line illustrating a commit that is coordinated with another subsystem

Status Description and Processing

Inflight
The participant or coordinator failed before finishing phase 1 (period a or
b); during restart, both systems back out the updates.
Indoubt
The participant failed after finishing phase 1 and before starting phase 2
(period c); only the coordinator knows whether the failure happened before
or after the commit (point 9). If it happened before, the participant must
back out its changes; if it happened afterward, it must make its changes

420 Administration Guide

 and commit them. After restart, the participant waits for information from
the coordinator before processing this unit of recovery.
In-commit
The participant failed after it began its own phase 2 processing (period d);
it makes committed changes.
In-abort
The participant or coordinator failed after a unit of recovery began to be
rolled back but before the process was complete (not shown in the figure).
The operational system rolls back the changes; the failed system continues
to back out the changes after restart.
postponed-abort
If the LIMIT BACKOUT installation option is set to YES or AUTO, any
backout not completed during restart is postponed. The status of the
incomplete URs is changed from inflight or in-abort to postponed-abort.

Normal restart and recovery for multiple systems

When Db2 acts together with another system, the recovery log contains
information about units of recovery that are inflight, indoubt, in-abort,
postponed-abort, or in-commit.

The phases of restart and recovery deal with that information as follows:
Phase 1: Log initialization
This phase proceeds as described in “Phase 1: Log initialization” on page
401.
Phase 2: Current status rebuild
While reading the log, Db2 identifies:
v The coordinator and all participants for every unit of recovery.
v All units of recovery that are outstanding and their statuses (indoubt,
in-commit, in-abort, or inflight, as described under “Consistency after
termination or failure” on page 420).
Phase 3: Forward log recovery
Db2 makes all database changes for each indoubt unit of recovery and
locks the data to prevent access to it after restart. Later, when an indoubt
unit of recovery is resolved, processing is completed in one of these ways:
v For the ABORT option of the RECOVER INDOUBT command, Db2
reads and processes the log, reversing all changes.
v For the COMMIT option of the RECOVER INDOUBT command, Db2
reads the log but does not process the records because all changes have
been made.
At the end of this phase, indoubt activity is reflected in the database as
though the decision was made to commit the activity, but the activity is
not yet committed. The data is locked and cannot be used until Db2
recognizes and acts on the indoubt decision. (For a description of indoubt
units of recovery, see “Resolving indoubt units of recovery” on page 422.)
Phase 4: Backward log recovery
This phase reverses changes that are performed for inflight or in-abort
units of recovery. At the end of this phase, interrupted inflight and in-abort
changes are removed from the database (the data is consistent and can be
used) or removal of the changes is postponed (the data is inconsistent and
unavailable).

Chapter 11. Maintaining consistency across multiple systems 421

 If removal of the changes is postponed, the units of recovery become
known as postponed-abort units of recovery. The data with pending backout
work is in a restrictive state (restart pending) which makes the data
unavailable. The data becomes available at completion of backout work or
at cold start or conditional restart of Db2.
If the LIMIT BACKOUT system parameter is AUTO, completion of the
backout work begins automatically by Db2 when the system accepts new
work. If the LIMIT BACKOUT system parameter is YES, completion of the
backout work begins when the RECOVER POSTPONED command is
issued.

Multiple-system restart with conditions

In some circumstances, you might need to perform a multiple-system conditional
restart.

If conditional restart is performed when Db2 is acting together with other systems,
the following actions occur:
1. All information about another coordinator and other participants that are
known to Db2 is displayed by messages DSNL438I and DSNL439I.
2. This information is purged. Therefore the RECOVER INDOUBT command must
be used at the local Db2 when the local location is a participant, and at another
Db2 subsystem when the local location is the coordinator.
3. Indoubt database access threads continue to appear as indoubt, and no
resynchronization with either a coordinator or a participant is allowed.
Related tasks:
Resolving inconsistencies resulting from a conditional restart

Heuristic decisions about whether to commit or abort an

indoubt thread
From the perspective of Db2, a decision to commit or roll back an indoubt unit of
recovery by any means but the normal resynchronization process is a heuristic
decision.

If you commit or roll back a unit of work and your decision is different than the
other system's decision, data inconsistency occurs. This type of damage is called
heuristic damage.

If this situation should occur, and your system then updates any data that is
involved with the previous unit of work, your data is corrupted and is extremely
difficult to correct.

In order to make a correct decision, you must be absolutely sure that the action
you take on indoubt units of recovery is the same as the action that the
coordinator takes. Validate your decision with the administrator of the other
systems that are involved with the logical unit of work.

Resolving indoubt units of recovery

If Db2 loses its connection to another system, it attempts to recover all inconsistent
objects after restart. The information that is needed to resolve indoubt units of
recovery must come from the coordinating system.

422 Administration Guide

 About this task

Check the console for message DSNR036I for unresolved units of recovery
encountered during a checkpoint. This message might occur to remind operators of
existing indoubt threads.

Important: If the TCP/IP address that is associated with a DRDA server is subject
to change, the domain name of each DRDA server must be defined in the CDB.
This allows Db2 to recover from situations where the server's IP address changes
prior to successful resynchronization.
Related information:
DSNR036I (Db2 Messages)

Resolution of IMS indoubt units of recovery

The resolution of indoubt units of recovery in IMS has no effect on DL/I resources.
Because IMS is in control of recovery coordination, DL/I resources are never
indoubt.

When IMS restarts, it automatically commits or backs out incomplete DL/I work,
based on whether the commit decision was recorded on the IMS log. The existence
of indoubt units of recovery does not imply that DL/I records are locked until Db2
connects.

During the current status rebuild phase of Db2 restart, the Db2 participant makes a
list of indoubt units of recovery. IMS builds its own list of residual recovery entries
(RREs). The RREs are logged at IMS checkpoints until all entries are resolved.

When indoubt units of recovery are recovered, the following steps occur:
1. IMS either passes an RRE to the IMS attachment facility to resolve the entry or
informs the attachment facility of a cold start. The attachment facility passes the
required information to Db2.
2. If Db2 recognizes that an entry is marked by Db2 for commit and by IMS for
roll back, it issues message DSNM005I. Db2 issues this message for
inconsistencies of this type between Db2 and IMS.
3. The IMS attachment facility passes a return code to IMS, indicating that it
should either destroy the RRE (if it was resolved) or keep it (if it was not
resolved). The procedure is repeated for each RRE.
4. Finally, if Db2 has any remaining indoubt units of recovery, the attachment
facility issues message DSNM004I.

The IMS attachment facility writes all the records that are involved in indoubt
processing to the IMS log tape as type X'5501FE'.

For all resolved units of recovery, Db2 updates databases as necessary and releases
the corresponding locks. For threads that access offline databases, the resolution is
logged and acted on when the database is started.

Db2 maintains locks on indoubt work that was not resolved. This can create a
backlog for the system if important locks are being held. You can use the DISPLAY
DATABASE LOCKS command to find out which tables and table spaces are locked
by indoubt units of recovery. The connection remains active so that you can clean
up the IMS RREs. You can then recover the indoubt threads.

Chapter 11. Maintaining consistency across multiple systems 423

 Resolve all indoubt units of work unless software or operating problems occur,
such as with an IMS cold start. Resolution of indoubt units of recovery from IMS
can cause delays in SQL processing. Indoubt resolution by the IMS control region
takes place at two times:
v At the start of the connection to Db2, during which resolution is done
synchronously
v When a program fails, during which the resolution is done asynchronously

In the first case, SQL processing is prevented in all dependent regions until the
indoubt resolution is completed. IMS does not allow connections between IMS
dependent regions and Db2 before the indoubt units of recovery are resolved.
Related tasks:
Controlling IMS connections

Resolution of CICS indoubt units of recovery

The resolution of indoubt units of recovery has no effect on CICS resources.

CICS is in control of recovery coordination and, when it restarts, CICS

automatically commits or backs out each unit of recovery, depending on whether
an end-of-unit-of-work log record exists. The existence of indoubt work does not
lock CICS resources until Db2 connects.

A process to resolve indoubt units of recovery is initiated during startup of the

attachment facility. During this process:
v The attachment facility receives a list of indoubt units of recovery for this
connection ID from the Db2 participant and passes them to CICS for resolution.
v CICS compares entries from this list with entries in its own list. CICS determines
from its own list what action it took for the indoubt unit of recovery.
v For each entry in the list, CICS creates a task for the attachment facility,
specifying the final commit or abort direction for the unit of recovery.
v If Db2 does not have any indoubt unit of recovery, a dummy list is passed. CICS
then purges unresolved units of recovery from previous connections, if any exist.

If the units of recovery cannot be resolved because of conditions described in

messages DSNC001I, DSNC034I, DSNC035I, or DSNC036I, CICS enables the
connection to Db2. For other conditions, it sends message DSNC016I and
terminates the connection.

For all resolved units of recovery, Db2 updates databases as necessary and releases
the corresponding locks. For threads that access offline databases, the resolution is
logged and acted on when the database is started. Unresolved units of work can
remain after restart; you can then resolve them.
Related tasks:
Monitoring and CICS threads and recovering CICS-Db2 indoubt units of recovery

Resolution of RRS indoubt units of recovery

Sometimes a Db2 unit of recovery (for a thread that uses RRSAF) or an RRS unit of
recovery (for a stored procedure) enters the indoubt state.

This is a state where a failure occurs when the participant (Db2 for a thread that
uses RRSAF or RRS for a stored procedure) has completed phase 1 of commit

424 Administration Guide

 processing and is waiting for the decision from the commit coordinator. This
failure could be a Db2 abnormal termination, an RRS abnormal termination, or
both.

Normally, automatic resolution of indoubt units of recovery occurs when Db2 and
RRS re-establish communication with each other. If something prevents this, you
can manually resolve an indoubt unit of recovery. This process is not
recommended because it might lead to inconsistencies in recoverable resources.

The following errors make manual recovery necessary:

v An RRS cold start where the RRS log is lost.
If Db2 is a participant and has one or more indoubt threads, these indoubt
threads must be manually resolved in order to commit or abort the database
changes and to release database locks. If Db2 is a coordinator for an RRS unit of
recovery, Db2 knows the commit or abort decision but cannot communicate this
information to the RRS-compliant resource manager that has an indoubt unit of
recovery.
v If Db2 performs a conditional restart and loses information from its log,
inconsistent Db2 managed data might exist.
v In a Sysplex, if Db2 is restarted on a z/OS system where RRS is not installed,
Db2 might have indoubt threads.
This is a user error because RRS must be started on all processors in a Sysplex
on which RRS work is to be performed.

Both Db2 and RRS can display information about indoubt units of recovery. Both
also provide techniques for manually resolving these indoubt units of recovery.

In Db2, the DISPLAY THREAD command provides information about indoubt Db2
thread. The display output includes RRS unit of recovery IDs for those Db2 threads
that have RRS either as a coordinator or as a participant. If Db2 is a participant,
you can use the RRS unit of recovery ID that is displayed to determine the
outcome of the RRS unit of recovery. If Db2 is the coordinator, you can determine
the outcome of the unit of recovery from the DISPLAY THREAD output.

In Db2, the RECOVER INDOUBT command lets you manually resolve a Db2
indoubt thread. You can use RECOVER INDOUBT to commit or roll back a unit of
recovery after you determine what the correct decision is.

RRS provides an ISPF interface that provides a similar capability.

Resolving WebSphere Application Server indoubt units of

recovery
A global transaction is a unit of work that involves operations on multiple resource
managers, such as Db2. All of the operations that comprise a global transaction are
managed by a transaction manager, such as WebSphere Application Server.

About this task

When the transaction manager receives transactionally demarcated requests from

an application, it translates the requests into a series of transaction control
commands, which it directs to the participating resource managers.

Example: An application requests updates to multiple databases. The transaction

manager translates these update requests into transaction control commands that

Chapter 11. Maintaining consistency across multiple systems 425

 are passed to several resource managers. Each resource manager then performs its
own set of operations on a database. When the application issues a COMMIT, the
transaction manager coordinates the commit of the distributed transaction across
all participating resource managers by using the two-phase commit protocol. If any
resource manager is unable to complete its portion of the global transaction, the
transaction manager directs all participating resource managers to roll back the
operations that they performed on behalf of the global transaction.

If a communication failure occurs between the first phase (prepare) and the second
phase (commit decision) of a commit, an indoubt transaction is created on the
resource manager that experienced the failure. When an indoubt transaction is
created, a message like this is displayed on the console of the resource manager:
DSNL405I = THREAD
G91E1E35.GFA7.00F962CC4611.0001=217
PLACED IN INDOUBT STATE BECAUSE OF
COMMUNICATION FAILURE WITH COORDINATOR ::FFFF:9.30.30.53.
INFORMATION RECORDED IN TRACE RECORD WITH IFCID=209
AND IFCID SEQUENCE NUMBER=00000001

After a failure, WebSphere Application Server is responsible for resolving indoubt

transactions and for handling any failure recovery. To perform these functions, the
server must be restarted and the recovery process initiated by an operator. You can
also manually resolve indoubt transactions with the RECOVER INDOUBT
command.

Recommendation: Let WebSphere Application Server resolve the indoubt

transactions. Manually recover indoubt transactions only as a last resort to start
Db2 and to release locks.

Procedure

To manually resolve indoubt transactions:

1. Issue the command -DISPLAY THREAD(*) T(I) DETAIL to display indoubt
threads from the resource manager console.
This command produces output like this example:
=dis thd(*) t(i) detail
DSNV401I = DISPLAY THREAD REPORT FOLLOWS -
DSNV406I = INDOUBT THREADS -
COORDINATOR STATUS RESET URID AUTHID
▌1▐ ::FFFF:9.30.30.53..4007 INDOUBT 0000111F049A ADMF002
V437-WORKSTATION=jaijeetsvl, USERID=admf002,
APPLICATION NAME=db2jccmain
▌2▐ V440-XID=7C7146CE 00000014 00000021 F6EF6F8B
F36873BE A37AC6BC 256F295D 04BE7EE0
8DFEF680 D1A6EFD5 8C0E6343 67679239
CC15A350 65BFB8EA 670CEBF4 E85938E0
06
▌2▐ V467-HAS LUWID G91E1E35.GFA7.00F962CC4611.0001=217
V466-THREAD HAS BEEN INDOUBT FOR 00:00:17
DISPLAY INDOUBT REPORT COMPLETE
Key Description
▌1▐ Note that in this example, only one indoubt thread exists.
▌2▐ A transaction is identified by a transaction identifier, called an XID. The
first 4 bytes of the XID (in this case, 7C7146CE) identify the transaction

426 Administration Guide

 manager. Each XID is associated with a logical unit of work ID
(LUWID) at the Db2 server. Note the LUWID that is associated with
each transaction, for use in the recovery step.
2. Query the transaction manager to determine whether a commit or abort
decision was made for each transaction.
3. Based on the decision that is recorded by the transaction manager, recover each
indoubt thread from the resource manager console by either committing or
aborting the transaction. Specify the LUWID from the DISPLAY THREAD
command in step 1. Use either of the following commands:
v -RECOVER INDOUBT ACTION(COMMIT) LUWID(217)
v -RECOVER INDOUBT ACTION(ABORT) LUWID(217)
Either command produces output like this example:
=RECOVER INDOUBT ACTION(COMMIT) LUWID(217)
DSNV414I = THREAD
LUWID=G91E1E35.GFA7.00F962CC4611.0001=217 COMMIT
SCHEDULED
DSN9022I = DSNVRI ’-RECOVER INDOUBT’ NORMAL COMPLETION
4. Display indoubt threads again from the resource manager console by issuing
the -DISPLAY THREAD(*) T(I) DETAIL command.
This command produces output like this example:
=dis thd(*) t(i) detail
DSNV401I = DISPLAY THREAD REPORT FOLLOWS -
DSNV406I = INDOUBT THREADS -
COORDINATOR STATUS RESET URID AUTHID
▌1▐ ::FFFF:9.30.30.53..4007 COMMITTED-H 0000111F049A ADMF002
V437-WORKSTATION=jaijeetsvl, USERID=admf002,
APPLICATION NAME=db2jccmain
V440-XID=7C7146CE 00000014 00000021 F6EF6F8B
F36873BE A37AC6BC 256F295D 04BE7EE0
8DFEF680 D1A6EFD5 8C0E6343 67679239
CC15A350 65BFB8EA 670CEBF4 E85938E0
06
V467-HAS LUWID G91E1E35.GFA7.00F962CC4611.0001=217
- DISPLAY INDOUBT REPORT COMPLETE
Key Description
▌1▐ Notice that the transaction now appears as a heuristically committed
transaction (COMMITTED=H).
5. If the transaction manager does not recover the indoubt transactions in a timely
manner, reset the transactions from the resource manager console to purge the
indoubt thread information. Specify the IP address and port from the DISPLAY
THREAD command in step 1 by issuing the -RESET INDOUBT
IPADDR(::FFFF:9.30.30.53..4007)FORCE command.
This command produces output like this example:
=RESET INDOUBT IPADDR(::FFFF:9.30.30.53..4007)FORCE
DSNL455I = DB2 HAS NO INFORMATION RELATED TO
IPADDR 9.30.30.53:4007
DSNL454I = QUALIFYING INDOUBT INFORMATION FOR
IPADDR 9.30.30.53:4007 HAS BEEN PURGED

Chapter 11. Maintaining consistency across multiple systems 427

 Resolving remote DBMS indoubt units of recovery
When communicating with a remote DBMS, indoubt units of recovery can result
from failure with either the participant or coordinator. Failure also can result with
the communication link between the participant and coordinator, even if the
systems themselves have not failed.

About this task

Normally, if your subsystem fails while communicating with a remote system, you
should wait until both systems and their communication link become operational.
Your system then automatically recovers its indoubt units of recovery and
continues normal operation. When Db2 restarts while any unit of recovery is
indoubt, the data that is required for that unit of recovery remains locked until the
unit of recovery is resolved.

If automatic recovery is not possible, Db2 alerts you to any indoubt units of
recovery that you need to resolve. If releasing locked resources and bypassing the
normal recovery process is imperative, you can resolve indoubt situations
manually.

Important: In a manual recovery situation, you must determine whether the

coordinator decided to commit or abort and ensure that the same decision is made
at the participant. In the recovery process, Db2 attempts to automatically
resynchronize with its participants. If you decide incorrectly what the recovery
action of the coordinator is, data is inconsistent at the coordinator and participant.

Procedure

To resolve units of recovery manually, you must use the following approaches:
v Commit changes that were made by logical units of work that were committed
by the other system.
v Roll back changes that were made by logical units of work that were rolled back
by the other system.

Determining the coordinator's commit or abort decision

You can use several methods to ascertain the status of indoubt units of work at
other systems.

Procedure

To ascertain the status of indoubt units of work, use one of the following
approaches:
v Use a NetView program. Write a program that analyzes NetView alerts for each
involved system, and returns the results through the NetView system.
v Use an automated z/OS console to ascertain the status of the indoubt threads at
the other involved systems.

v Use the command DISPLAY THREAD TYPE(INDOUBT) LUWID(luwid).

If the coordinator Db2 system is started and no Db2 cold start was performed,
you can issue a DISPLAY THREAD TYPE(INDOUBT) command. If the decision
was to commit, the display thread indoubt report includes the LUWID of the
indoubt thread. If the decision was to abort, the thread is not displayed.
v Read the recovery log by using DSN1LOGP.

428 Administration Guide

 If the coordinator Db2 cannot be started, DSN1LOGP can determine the commit
decision. If the coordinator Db2 performed a cold start (or any type of
conditional restart), the system log should contain messages DSNL438I or
DSNL439I, which describe the status of the unit of recovery (LUWID).

Recovering indoubt threads

After you determine whether you need to commit or roll back an indoubt thread,
you can recover the thread by using the RECOVER INDOUBT command.

About this task

This command does not erase the indoubt status of the thread. The status still
appears as an indoubt thread until the systems go through the normal
resynchronization process. An indoubt thread can be identified by its LUWID,
LUNAME, or IP address. You can also use the LUWID token with the command.

Procedure

To recover an indoubt thread:

Issue the RECOVER INDOUBT command.

Use the ACTION(ABORT|COMMIT) option of the RECOVER INDOUBT command
to commit or roll back a logical unit of work (LUW). If your system is the
coordinator of one or more other systems that are involved with the logical unit of
work, your action propagates to the other system that are associated with the
LUW.

Example

Assume that you need to recover two indoubt threads. The first has
LUWID=DB2NET.LUNSITE0.A11A7D7B2057.0002, and the second has a token of
442. To commit the LUWs, enter the following command:
-RECOVER INDOUBT ACTION(COMMIT) LUWID(DB2NET.LUNSITE0.A11A7D7B2057.0002,442)

Related concepts:
Scenarios for resolving problems with indoubt threads

Resetting the status of an indoubt thread

After manual recovery of an indoubt thread, allow the systems to resynchronize
automatically. Automatic resynchronization resets the status of the indoubt thread.
However, you might need to take additional steps if heuristic damage or a protocol
error occurs.

Procedure
To delete indoubt thread information for a thread whose reset status is set to YES:

Issue the RESET INDOUBT command.

Db2 maintains this information until normal automatic recovery. You can purge
information about threads where Db2 is either the coordinator or participant. If the

Chapter 11. Maintaining consistency across multiple systems 429

 thread is an allied thread that is connected to IMS or CICS, the command applies
only to coordinator information about downstream participants. Information that is
purged does not appear in the next display thread report and is erased from the
Db2 logs.

Example

Assume that you need to purge information about two indoubt threads. The first
has an LUWID=DB2NET.LUNSITE0.A11A7D7B2057.0002 and a resync port number
of 123, and the second has a token of 442. Use the following command to purge
the information:
-RESET INDOUBT LUWID(DB2NET.LUNSITE0.A11A7D7B2057.0002:123,442)

You can also use a LUNAME or IP address with the RESET INDOUBT command.
You can use the keyword IPADDR in place of LUNAME or LUW keywords, when
the partner uses TCP/IP instead of SNA. The resync port number of the parameter
is required when using the IP address. The DISPLAY THREAD output lists the
resync port number. This allows you to specify a location, instead of a particular
thread. You can reset all the threads that are associated with that location by using
the (*) option.

Resolving an indoubt unit of recovery during Db2 restart

When Db2 logs are no longer available, you can resolve one, long-running indoubt
unit of recovery (UR) during Db2 restart by using the CRESTART control statement
of the DSNJU003 utility.

About this task

Use this method of resolving an indoubt UR only when the Db2 logs are not
available. All database updates for the indoubt UR are committed after Db2
restarts.

Procedure

To resolve an indoubt UR during Db2 restart:

Run the DSNJU003 utility and specify the CRESTART control statement with the
following options:
v STARTRBA, where the value is the first log RBA that is available after the
indoubt UR
v FORWARD=YES to allow forward-log recovery
v BACKOUT=YES to allow backward-log recovery
Related reference:
DSNJU003 (change log inventory) (Db2 Utilities)

430 Administration Guide

Chapter 12. Backing up and recovering your data
Db2 supports recovering data to its current state or to an earlier state. You can
recover table spaces, indexes, index spaces, partitions, data sets, and the entire
system. Developing backup and recovery procedures at your site is critical in order
to avoid costly and time-consuming loss of data.

About this task

Develop procedures for the following recovery actions:

v Create a point of consistency
v Recovering system and data objects to a point of consistency
v Back up the Db2 catalog and directory and your data
v Recover the Db2 catalog and directory and your data
v Recover from out-of-space conditions
v Recover from a hardware or power failure
v Recover from a z/OS component failure
v Recover from a disaster off-site

Recommendation: To improve recovery capability in the event of a disk failure,

use dual active logging, and place the copies of the active log data sets and the
bootstrap data sets on different disk volumes.

Tip: For best results, check the consistency of the Db2 catalog and directory
regularly, even outside of the migration process. For detailed instructions, see
Migration step 2: Verify the integrity of Db2 table spaces (optional) (Db2
Installation and Migration) and Migration step 4: Check for consistency between
catalog tables (optional) (Db2 Installation and Migration)

The following utilities are the principal tools for Db2 recovery:
v QUIESCE
v REPORT
v COPY
v COPYTOCOPY
v RECOVER
v MERGECOPY
v BACKUP SYSTEM
v RESTORE SYSTEM

This information provides an overview of these utilities to help you with your
backup and recovery planning. Note that the term page set in this information can
refer to a table space, index space, or any combination of these.
Related concepts:
How the initial Db2 logging environment is established
Related reference:
Implications of moving data sets after a system-level backup

© Copyright IBM Corp. 1982, 2017 431

 Plans for recovery of distributed data
In a distributed data environment, each unit of work is processed as a whole at the
target system, regardless of where a unit of work originates. Therefore, a unit of
work is recovered as a whole at the target system.

At a Db2 server, the entire unit is either committed or rolled back. It is not
processed if it violates referential constraints that are defined within the target
system. Whatever changes it makes to data are logged. A set of related table spaces
can be quiesced at the same point in the log, and image copies can be made of
them simultaneously. If that is done, and if the log is intact, any data can be
recovered after a failure and be internally consistent.

However, Db2 provides no special means to coordinate recovery between different

subsystems even if an application accesses data in several systems. To guarantee
consistency of data between systems, applications should be written so that all
related updates are done within one unit of work.

Point-in-time recovery (to the last image copy or to a relative byte address (RBA))
presents other challenges. You cannot control a utility in one subsystem from
another subsystem. In practice, you cannot quiesce two sets of table spaces, or
make image copies of them, in two different subsystems at exactly the same
instant. Neither can you recover them to exactly the same instant, because two
different logs are involved, and a RBA does not mean the same thing for both of
them.

In planning, the best approach is to consider carefully what the QUIESCE, COPY,
and RECOVER utilities do for you, and then plan not to place data that must be
closely coordinated on separate subsystems. After that, recovery planning is a
matter of agreement among database administrators at separate locations.

Db2 is responsible for recovering Db2 data only; it does not recover non-Db2 data.
Non-Db2 systems do not always provide equivalent recovery capabilities.

| Plans for recovering the Db2 tables and indexes used to support Db2
| query acceleration
| The process of recovering the Db2 tables and indexes that are created specifically
| for use with IBM Db2 Analytics Accelerator for z/OS is different than the process
| of recovering Db2 catalog tables and indexes.

| To support Db2 query acceleration with IBM Db2 Analytics Accelerator, certain
| Db2 tables and indexes are created and then used by both Db2 and IBM Db2
| Analytics Accelerator. These Db2 tables and indexes have the qualifier SYSACCEL
| and are not created in the Db2 catalog table spaces. Instead, they are created
| independently in separate table spaces by running DDL that is provided by IBM.
| Because these Db2 SYSACCEL objects are not part of the Db2 catalog space, they
| must be backed up and recovered separately, as you do with your user data. For
| these SYSACCEL objects, follow the recommended backup and recovery steps and
| strategies that are provided for user data.

| For more information about the SYSACCEL objects that are used to support Db2
| query acceleration and how they are created, see Tables that support query
| acceleration (Db2 SQL) and Creating database objects that support query
| acceleration (Db2 Installation and Migration).

432 Administration Guide

Plans for extended recovery facility toleration
Db2 can be used in an extended recovery facility (XRF) recovery environment with
CICS or IMS.

All Db2-owned data sets (executable code, the Db2 catalog, and user databases)
must be on a disk that is shared between the primary and alternate XRF
processors. In the event of an XRF recovery, Db2 must be stopped on the primary
processor and started on the alternate. For CICS, that can be done automatically, by
using the facilities provided by CICS, or manually, by the system operator. For
IMS, that is a manual operation and must be done after the coordinating IMS
system has completed the processor switch. In that way, any work that includes
SQL can be moved to the alternate processor with the remaining non-SQL work.
Other Db2 work (interactive or batch SQL and Db2 utilities) must be completed or
terminated before Db2 can be switched to the alternate processor. Consider the
effect of this potential interruption carefully when planning your XRF recovery
scenarios.

Plan carefully to prevent Db2 from being started on the alternate processor until
the Db2 system on the active, failing processor terminates. A premature start can
cause severe integrity problems in data, the catalog, and the log. The use of global
resource serialization (GRS) helps avoid the integrity problems by preventing
simultaneous use of Db2 on the two systems. The bootstrap data set (BSDS) must
be included as a protected resource, and the primary and alternate XRF processors
must be included in the GRS ring.

Plans for recovery of indexes

You can use the REBUILD INDEX utility or the RECOVER utility to recover Db2
indexes to currency.

The REBUILD INDEX utility reconstructs the indexes by reading the appropriate
rows in the table space, extracting the index keys, sorting the keys, and then
loading the index keys into the index. The RECOVER utility recovers indexes by
restoring an image copy or system-level backup and then applying the log. It can
also recover indexes to a prior point in time.

You can use the REBUILD INDEX utility to recover any index, and you do not
need to prepare image copies or system-level backups of those indexes.

To use the RECOVER utility to recover indexes, you must include the following
actions in your normal database operation:
v Create or alter indexes by using the SQL statement ALTER INDEX with the
option COPY YES before you backup and recover them using image copies or
system-level backups.
v Create image copies of all indexes that you plan to recover or take system-level
backups by using the BACKUP SYSTEM utility.

The COPY utility makes full image copies or concurrent copies of indexes.
Incremental copies of indexes are not supported. If full image copies of the index
are taken at timely intervals, recovering a large index might be faster than
rebuilding the index.

Chapter 12. Backing up and recovering your data 433

 Tip: You can recover indexes and table spaces in a single list when you use the
RECOVER utility. If you use a single list of objects in one RECOVER utility control
statement, the logs for all of the indexes and table spaces are processed in one
pass.

| Actions to take when you back up data

| When backing up data, you can take certain actions to improve the results
| associated with data recovery.
| During the installation of, or migration to, Db2 for z/OS Db2 11, make a full
| image copy of the Db2 directory and catalog with installation job DSNTIJIC .
| If this task was not done during installation or migration, use the COPY
| utility. to make a full image copy of the Db2 catalog and directory. If this
| task is not done and there are later problems with inconsistent data in the
| Db2 catalog or directory, the RECOVER utility cannot be used to resolve
| the problem.
| To speed recovery of the catalog and directory indexes, take a full image
| copy of all the index spaces when you copy the table spaces. This task
| enables you to recover the table spaces and index spaces at the same time.
| Periodically make image copies of the catalog, directory, and user databases
| This task minimizes the time the RECOVER utility requires to perform
| recovery. In addition, this task increases the probability that the necessary
| archive log data sets are still available. Make two copies of each level of
| image copy data sets to reduce the risk of loss or damage.
| To speed recovery of the indexes, take a full image copy of all the index
| spaces when you copy the table spaces. This task enables you to recover
| the table spaces and index spaces at the same time.
| Use dual logging for active log, archive log, and bootstrap data sets (BSDSs).
| This task increases the chance of recovering from all problems, and is
| especially useful for data inconsistency problems.
| Before you use RECOVER, rename the data sets
| If the image copy or log data sets are damaged, using the RECOVER
| utility might compound the problem. Therefore, before you use RECOVER,
| either use IDCAMS ALTER NEWNAME to rename the data sets, or run
| DSN1COPY to create a copy of the data sets.
| If the data sets were renamed, the RECOVER utility defines the underlying
| VSAM linear data sets (LDSs) for the table space or index spaces, restores
| the image copies, and applies log records. Then, if a problem occurs during
| RECOVER utility processing, a copy of the data (as it existed before you
| ran RECOVER) is still available.
| Keep back-level image copy data sets
| If an image copy of a table space or index space that contains inconsistent
| data is made, the RECOVER utility cannot resolve the data inconsistency
| problem. However, RECOVER can resolve the inconsistency if there is an
| older image copy of that table space or index space that is taken before the
| problem occurred. The MODIFY utility deletes the SYSCOPY record that
| describes an image copy. To retain a particular image copy for use by
| RECOVER, use the MODIFY utility with the TIMESTAMP of that image
| copy. This task also retains any later image copies.
| Maintain consistent referential structures
|
434 Administration Guide
| A referential structure is a set of tables and relationships that are designed
| with referential constraints, such that each table in the set is a parent or
| dependent of itself or another table in the set. To facilitate maintaining
| referential consistency, keep the number of table spaces in a table space set
| to a minimum, and avoid tables of different referential structures in the
| same table space. REPORT TABLESPACESET reports all members of a
| table space set defined by referential constraints.
| A referential structure must be kept consistent regarding point in time
| recovery. Use the QUIESCE utility to establish a point of consistency for a
| table space set, to which the table space set can later be recovered without
| introducing referential constraint violations.
| Related reference:
| COPY (Db2 Utilities)

| Actions to avoid when you back up data

| When backing up data, avoid certain actions to reduce problems that occur during
| data recovery.
| Do not discard archive logs that might be needed
| The RECOVER utility might need an archive log to recover from an
| inconsistent data problem. If discarded, the problem must be resolved
| manually without using the RECOVER utility.
| Do not make an image copy of a table space or index space that contains
| inconsistent data
| If the COPY utility is used to make an image copy of a table space or
| index space that contains inconsistent data, the RECOVER utility cannot
| recover a problem that involves that space (unless an older image copy is
| available that was taken before the problem occurred). Run DSN1COPY
| with the CHECK option to determine whether intra-page data
| inconsistency problems exist on table or index spaces before you make
| image copies of them. If a COPY of a catalog or directory table space is
| taken, run DSN1COPY CHECK (before image copies are taken) to verify
| the integrity of Db2 catalog and directory table spaces.
| Do not use the -TERM UTILITY command on utility jobs you want to restart
| If an error occurs while a utility is being run, the data on which the utility
| was operating remains at a commit point. If the utility stops while it has
| exclusive access to data, other applications cannot access that data. In this
| case, you can issue the -TERM UTILITY command to terminate the utility
| and make the data available to other applications. However, use the
| -TERM UTILITY command only if the utility job cannot be restarted or
| does not need to be restarted.
| Issuing the -TERM UTILITY command can cause two different situations:
| v If the utility is active, it terminates at its next commit point.
| v If the utility is stopped, it terminates immediately.
| By using the -TERM UTILITY command to terminate the REORG or LOAD
| utilities, or COPY utility for incremental image copies, the objects on which
| the utility was operating are left in an indeterminate state. Often, the same
| utility job cannot be rerun. The specific considerations vary for each utility,
| depending on the phase in process when you issue the command.
| Related tasks:
| Discarding archive log records
Chapter 12. Backing up and recovering your data 435
| Related reference:
| -TERM UTILITY (Db2) (Db2 Commands)
| COPY (Db2 Utilities)

Preparation for recovery: a scenario

You can use the RECOVER utility to recover table spaces or index spaces.

Db2 can recover a page set by using an image copy or system-level backup, the
recovery log, or both. The Db2 recovery log contains a record of all changes that
are made to the page set. If Db2 fails, it can recover the page set by restoring the
image copy or system-level backup and applying the log changes to it from the
point of the image copy or system-level backup.

The Db2 catalog and directory page sets must be copied at least as frequently as
the most critical user page sets. Moreover, you are responsible for periodically
copying the tables in the communications database (CDB), the application
registration table, the object registration table, and the resource limit facility
(governor), or for maintaining the information that is necessary to re-create them.
Plan your backup strategy accordingly.

The following backup scenario suggests how Db2 utilities might be used when
taking object level backups with the COPY utility:

Imagine that you are the database administrator for DBASE1. Table space TSPACE1
in DBASE1 has been available all week. On Friday, a disk write operation for
TSPACE1 fails. You need to recover the table space to the last consistent point
before the failure occurred. You can do that because you have regularly followed a
cycle of preparations for recovery. The most recent cycle began on Monday
morning:
Monday morning
You start the DBASE1 database and make a full image copy of TSPACE1
and all indexes immediately. That gives you a starting point from which to
recover. Use the COPY utility with the SHRLEVEL CHANGE option to
improve availability.
Tuesday morning
You run the COPY utility again. This time you make an incremental image
copy to record only the changes that have been made since the last full
image copy that you took on Monday. You also make a full index copy.
TSPACE1 can be accessed and updated while the image copy is being
made. For maximum efficiency, however, you schedule the image copies
when online use is minimal.
Wednesday morning
You make another incremental image copy, and then create a full image
copy by using the MERGECOPY utility to merge the incremental image
copy with the full image copy.
Thursday and Friday mornings
You make another incremental image copy and a full index copy each
morning.
Friday afternoon

436 Administration Guide

 An unsuccessful write operation occurs and you need to recover the table
space. You run the RECOVER utility. The utility restores the table space
from the full image copy that was made by MERGECOPY on Wednesday
and the incremental image copies that were made on Thursday and Friday,
and includes all changes that are made to the recovery log since Friday
morning.
Later Friday afternoon
The RECOVER utility issues a message announcing that it has successfully
recovered TSPACE1 to the current point in time.

This scenario is somewhat simplistic. You might not have taken daily incremental
image copies on just the table space that failed. You might not ordinarily recover
an entire table space. However, it illustrates this important point: with proper
preparation, recovery from a failure is greatly simplified.
Related reference:
COPY (Db2 Utilities)
RECOVER (Db2 Utilities)

Events that occur during recovery

During recovery, several events occur, such as reading the log and running utilities
that rely on image copies of the data.

Figure 43 on page 438 shows an overview of the recovery process. To recover a

page set, the RECOVER utility typically uses these items:
v A backup that is a full image copy or a system-level backup.
v For table spaces only, when the COPY utility is used, any later incremental
image copies; each incremental image copy summarizes all the changes that
were made to the table space from the time that the previous image copy was
made.
v All log records for the page set that were created since the image copy. If the log
has been damaged or discarded, or if data has been changed erroneously and
then committed, you can recover to a particular point in time by limiting the
range of log records that are to be applied by the RECOVER utility.

In the example shown in Figure 43 on page 438:

v Where the COPY utility is used, the RECOVER utility uses information in the
SYSIBM.SYSCOPY catalog table to:
– Restore the page set with the data in the full image copy (appearing, in
Figure 43 on page 438, at X'38000').
– For table spaces only, apply all the changes that are summarized in any later
incremental image copies. (Two copies appear in Figure 43 on page 438:
X'80020' and X'C0040'.)
– Apply all changes to the page set that are registered in the log, beginning at
the log RBA of the most recent image copy. (In Figure 43 on page 438,
X'C0040', that address is also stored in the SYSIBM.SYSCOPY catalog table.)

Chapter 12. Backing up and recovering your data 437

Figure 42. Overview of Db2 recovery from COPY utility. The figure shows one complete cycle of image copies. The
SYSIBM.SYSCOPY catalog table can record many complete cycles.

v Where the BACKUP SYSTEM utility is used, the RECOVER utility uses
information in the BSDS and in the SYSIBM.SYSCOPY catalog table to:
– Restore the page set from the most recent backup, in this case, it is a
system-level backup (appearing, in Figure 43 at X'80000').
– Apply all changes to the page set that are registered in the log, beginning at
the log RBA of the most recent system-level backup.

Figure 43. Overview of Db2 recovery from BACKUP SYSTEM utility. The figure shows one
complete cycle of image copies. The SYSIBM.SYSCOPY catalog table can record many
complete cycles.

Complete recovery cycles

In planning for recovery, you determine how often to take image copies or
system-level backups and how many complete cycles to keep. Those values tell
how long you must keep log records and image copies or system-level backups for
database recovery.

In deciding how often to take image copies or system-level backups, consider the
time needed to recover a table space. The time is determined by all of the
following factors:
v The amount of log to traverse
v The time that it takes an operator to mount and remove archive tape volumes
v The time that it takes to read the part of the log that is needed for recovery
v The time that is needed to reprocess changed pages

438 Administration Guide

 In general, the more often you make image copies or system-level backups, the less
time recovery takes, but the more time is spent making copies. If you use LOG NO
without the COPYDDN keyword or the FCCOPYDDN keyword when you run the
LOAD or REORG utilities, Db2 places the table space in COPY-pending status. You
must remove the COPY-pending status of the table space by making an image
copy before making further changes to the data.

However, if you run REORG or LOAD REPLACE with the COPYDDN keyword or
the FCCOPYDDN keyword, Db2 creates a full image copy of a table space during
execution of the utility, so Db2 does not place the table space in COPY-pending
status. Inline copies of indexes during LOAD and REORG are not supported.

If you use LOG YES and log all updates for table spaces, an image copy of the
table space is not required for data integrity. However, taking an image copy
makes the recovery process more efficient. The process is even more efficient if you
use MERGECOPY to merge incremental image copies with the latest full image
copy. You can schedule the MERGECOPY operation at your own convenience,
whereas the need for a recovery can arise unexpectedly. The MERGECOPY
operation does not apply to indexes.

Even if the BACKUP SYSTEM is used, it is important to take full image copies
(inline copies) during REORG and LOAD to avoid the COPY-pending status on the
table space.

Recommendation: Copy your indexes after the associated utility has run.
Optionally, you can take a FlashCopy image copy when running the REBUILD
INDEX or REORG INDEX utilities. Indexes are placed in informational
COPY-pending (ICOPY) status after running the LOAD TABLESPACE, REORG
TABLESPACE, REBUILD INDEX, or REORG INDEX utilities. Only structural
modifications of the index are logged when these utilities are run, so the log does
not have enough information to recover the index.

Use the CHANGELIMIT option of the COPY utility to let Db2 determine when an
image copy should be performed on a table space and whether a full or
incremental copy should be taken. Use the CHANGELIMIT and REPORTONLY
options together to let Db2 recommend what types of image copies to make. When
you specify both CHANGELIMIT and REPORTONLY, Db2 makes no image copies.
The CHANGELIMIT option does not apply to indexes.

In determining how many complete copy and log cycles to keep, you are guarding
against damage to a volume that contains an important image copy or a log data
set. A retention period of at least two full cycles is recommended. For enhanced
security, keep records for three or more copy cycles.

A recovery cycle example when using image copies

Log management for a user group involves using image copies. You need to
determine how often to make image copies.

Table 43 on page 440 suggests how often a user group with 10 locally defined table
spaces (one table per table space) might take image copies, based on frequency of
updating. Their least-frequently copied table is EMPSALS, which contains
employee salary data. If the group chooses to keep two complete image copy
cycles on hand, each time EMPSALS is copied, records prior to its previous copy
or copies, made two months ago, can be deleted. They will always have on hand
between two months and four months of log records.

Chapter 12. Backing up and recovering your data 439

 In the example, the most critical tables are copied daily. The Db2 catalog and
directory are also copied daily.
Table 43. Db2 log management example
Full image copy
Table space name Content Update activity period
ORDERINF Invoice line: part and Heavy Daily
quantity ordered
SALESINF Invoice description Heavy Daily
SALESQTA Quota information for Moderate Weekly
each sales person
SALESDSC Customer Moderate Weekly
descriptions
PARTSINV Parts inventory Moderate Weekly
PARTSINF Parts suppliers Light Monthly
PARTS Parts descriptions Light Monthly
SALESCOM Commission rates Light Monthly
EMPLOYEE Employee descriptive Light Monthly
data
EMPSALS Employee salaries Light Bimonthly

If you are using the BACKUP SYSTEM utility, you should schedule the frequency
of system-level backups based on your most critical data.

If you do a full recovery, you do not need to recover the indexes unless they are
damaged. If you recover to a prior point in time, you do need to recover the
indexes. See “Plans for recovery of indexes” on page 433 for information about
indexes.

How DFSMShsm affects your recovery environment

The Data Facility Hierarchical Storage Manager (DFSMShsm) can automatically
manage space and data availability among storage devices in your system. If you
use DFSMShsm, you need to know that it automatically moves data to and from
the Db2 databases.

Restriction: Because DFSMShsm can migrate data sets to different disk volumes,
you cannot use DFSMShsm in conjunction with the BACKUP SYSTEM utility. The
RECOVER utility requires that the data sets reside on the volumes where they had
been at the time of the system-level backup.

DFSMShsm manages your disk space efficiently by moving data sets that have not
been used recently to less-expensive storage. It also makes your data available for
recovery by automatically copying new or changed data sets to tape or disk. It can
delete data sets or move them to another device. Its operations occur daily, at a
specified time, and they allow for keeping a data set for a predetermined period
before deleting or moving it.

All DFSMShsm operations can also be performed manually.

DFSMShsm:
v Uses cataloged data sets
v Operates on user tables, image copies, and logs

440 Administration Guide

 v Supports VSAM data sets

If a volume has a Db2 storage group specified, the volume should be recalled only
to like devices of the same VOLSER as defined by CREATE or ALTER STOGROUP.

Db2 can recall user page sets that have been migrated. Whether DFSMShsm recall
occurs automatically is determined by the values of the RECALL DATABASE and
RECALL DELAY fields of installation panel DSNTIPO. If the value of the RECALL
DATABASE field is NO, automatic recall is not performed and the page set is
considered an unavailable resource. It must be recalled explicitly before it can be
used by Db2. If the value of the RECALL DATABASE field is YES, DFSMShsm is
invoked to recall the page sets automatically. The program waits for the recall for
the amount of time that is specified by the RECALL DELAY parameter. If the recall
is not completed within that time, the program receives an error message
indicating that the page set is unavailable but that recall was initiated.

The deletion of DFSMShsm migrated data sets and the Db2 log retention period
must be coordinated with use of the MODIFY utility. If not, you could need
recovery image copies or logs that have been deleted.
Related tasks:
Discarding archive log records
Related information:
DFSMShsm Managing Your Own Data

Tips for maximizing data availability during backup and recovery

You need to develop a plan for backup and recovery. Then, you need to become
familiar enough with that plan so that when an outage occurs, you can get back in
operation as quickly as possible.

Consider the following factors when you develop and implement your plan:
v “Decide on the level of availability you need”
v “Practice for recovery” on page 442
v “Minimize preventable outages” on page 442
v “Determine the required backup frequency” on page 442
v “Minimize the elapsed time of RECOVER jobs” on page 442
v “Minimize the elapsed time for COPY jobs” on page 443
v “Determine the right characteristics for your logs” on page 443
v “Minimize Db2 restart time” on page 443

Decide on the level of availability you need

Start by determining the primary types of outages you are likely to experience.
Then, for each of those types of outages, decide on the maximum amount of time
that you can spend on recovery. Consider the trade-off between cost and
availability. Recovery plans for continuous availability are very costly, so you need
to think about what percentage of the time your systems really need to be
available.

The availability of data is affected by the availability of related objects. For

example, if there is an availability issue with one object in a related set, the
availability of the others may be impacted as well. The related object set includes
base table spaces and indexes, objects related by referential constraints, LOB table
Chapter 12. Backing up and recovering your data 441
 space and indexes, and XML table spaces and indexes.

Practice for recovery

You cannot know whether a backup and recovery plan is workable unless you
practice it. In addition, the pressure of a recovery situation can cause mistakes. The
best way to minimize mistakes is to practice your recovery scenario until you
know it well. The best time to practice is outside of regular working hours, when
fewer key applications are running.

Minimize preventable outages

One aspect of your backup and recovery plan should be eliminating the need to
recover whenever possible. One way to do that is to prevent outages caused by
errors in Db2. Be sure to check available maintenance often, and apply fixes for
problems that are likely to cause outages.

Determine the required backup frequency

Use your recovery criteria to decide how often to make copies of your databases.

For example, if you use image copies and if the maximum acceptable recovery
time after you lose a volume of data is two hours, your volumes typically hold
about 4 GB of data, and you can read about 2 GB of data per hour, you should
make copies after every 4 GB of data that is written. You can use the COPY option
SHRLEVEL CHANGE or DFSMSdss concurrent copy to make copies while
transactions and batch jobs are running. You should also make a copy after
running jobs that make large numbers of changes. In addition to copying your
table spaces, you should also consider copying your indexes.

You can take system-level backups using the BACKUP SYSTEM utility. Because the
FlashCopy technology is used, the entire system is backed up very quickly with
virtually no data unavailability.

You can make additional backup image copies from a primary image copy by
using the COPYTOCOPY utility. This capability is especially useful when the
backup image is copied to a remote site that is to be used as a disaster recovery
site for the local site. Applications can run concurrently with the COPYTOCOPY
utility. Only utilities that write to the SYSCOPY catalog table cannot run
concurrently with COPYTOCOPY.

Minimize the elapsed time of RECOVER jobs

When recovering system-level backups from disk, the RECOVER utility restores
data sets serially by the main task. When recovering system-level backups from
tape, the RECOVER utility creates multiple subtasks to restore the image copies
and system-level backups for the objects.

If you are using system-level backups, be sure to have recent system-level backups
on disk to reduce the recovery time.

Restoring FlashCopy image copies happens very quickly. However, creating a

FlashCopy image copy with consistency (FLASHCOPY CONSISTENT) uses more
system resources and might take longer than creating an image copy by specifying

442 Administration Guide

FLASHCOPY YES. Specifying FLASHCOPY CONSISTENT might take longer,
because backing out uncommitted work requires reading the logs and updating the
image copy.

For point-in-time recoveries, recovering to quiesce points and SHRLEVEL

REFERENCE copies can be faster than recovering to other points in time.

If you are recovering to a non-quiesce point, the following factors can have an
impact on performance:
v The duration of URs that were active at the point of recovery.
v The number of Db2 members that have active URs to be rolled back.

Minimize the elapsed time for COPY jobs

You can use the COPY utility to make image copies of a list of objects in parallel.
Image copies can be made to either disk or tape.

Also, you can take FlashCopy image copies with the COPY utility. FlashCopy can
reduce both the unavailability of data during the copy operation and the amount
of time that is required for recovery operations.

Determine the right characteristics for your logs

Consider the following criteria when determining the right characteristics for your
logs:
v If you have enough disk space, use more and larger active logs. Recovery from
active logs is quicker than from archive logs.
v To speed recovery from archive logs, consider archiving to disk.
v If you archive to tape, be sure that you have enough tape drives so that Db2
does not have to wait for an available drive on which to mount an archive tape
during recovery.
v Make the buffer pools and the log buffers large enough to be efficient.

Minimize Db2 restart time

Many recovery processes involve restart of Db2. You need to minimize the time
that Db2 shutdown and startup take.

You can limit the backout activity during Db2 system restart. You can postpone the
backout of long-running units of recovery until after the Db2 system is operational.
Use the installation options LIMIT BACKOUT and BACKOUT DURATION to
determine what backout work will be delayed during restart processing.

The following major factors influence the speed of Db2 shutdown:

v Number of open Db2 data sets
During shutdown, Db2 must close and deallocate all data sets it uses if the fast
shutdown feature has been disabled. The default is to use the fast shutdown
feature. Contact IBM Support for information about enabling and disabling the
fast shutdown feature. The maximum number of concurrently open data sets is
determined by the Db2 subsystem parameter DSMAX. Closing and deallocation
of data sets generally takes .1 to .3 seconds per data set.
Be aware that z/OS global resource serialization (GRS) can increase the time to
close Db2 data sets. If your Db2 data sets are not shared among more than one

Chapter 12. Backing up and recovering your data 443

 z/OS system, set the GRS RESMIL parameter value to OFF, or place the Db2
data sets in the SYSTEMS exclusion RNL.
v Active threads
Db2 cannot shut down until all threads have terminated. Issue the Db2
command DISPLAY THREAD to determine if any threads are active while Db2
is shutting down. If possible, cancel those threads.
v Processing of SMF data
At Db2 shutdown, z/OS does SMF processing for all Db2 data sets that were
opened since Db2 startup. You can reduce the time that this processing takes by
setting the z/OS parameter DDCONS(NO).

The following major factors influence the speed of Db2 startup:

v Db2 checkpoint interval
The Db2 checkpoint interval indicates the number of log records that Db2 writes
between successive checkpoints. This value is controlled by the Db2 subsystem
parameter CHKFREQ. The default of 50000 results in good startup performance
in most cases.
You can use the LOGLOAD option, the CHKTIME option, or a combination of
both of these options of the SET LOG command to modify the CHKFREQ value
dynamically without recycling Db2. The value that you specify depends on your
restart requirements. The default value for the CHKTIME option is 5 minutes.
v Long-running units of work
Db2 rolls back uncommitted work during startup. The amount of time for this
activity is approximately double the time that the unit of work was running
before Db2 shut down. For example, if a unit of work runs for two hours before
a Db2 abend, it takes at least four hours to restart Db2. Decide how long you
can afford for startup, and avoid units of work that run for more than half that
long.
You can use accounting traces to detect long-running units of work. For tasks
that modify tables, divide the elapsed time by the number of commit operations
to get the average time between commit operations. Add commit operations to
applications for which this time is unacceptable.

Recommendation: To detect long-running units of recovery, enable the UR

CHECK FREQ option of installation panel DSNTIPL. If long-running units of
recovery are unavoidable, consider enabling the LIMIT BACKOUT option on
installation panel DSNTIPL.
v Size of active logs
If you archive to tape, you can avoid unnecessary startup delays by making each
active log big enough to hold the log records for a typical unit of work. This
lessens the probability that Db2 will need to wait for tape mounts during
startup.
Related concepts:
FlashCopy image copies (Db2 Utilities)
Related tasks:
Dynamically changing the checkpoint frequency
Deferring restart processing
Managing the opening and closing of data sets (Db2 Performance)
Setting the size of active log data sets (Db2 Performance)
Related reference:

444 Administration Guide

 -SET LOG (Db2) (Db2 Commands)

Where to find recovery information

Information that is needed for recovery is contained in several locations.
SYSIBM.SYSCOPY
SYSIBM.SYSCOPY is a catalog table that contains information about full
and incremental image copies. If concurrent updates were allowed when
making the copy, the log RBA corresponds to the image copy start time;
otherwise, it corresponds to the end time. The RECOVER utility uses the
log RBA to look for log information after restoring the image copy. The
SYSCOPY catalog table also contains information that is recorded by the
COPYTOCOPY utility.
SYSCOPY also contains entries with the same kinds of log RBAs that are
recorded by the utilities QUIESCE, REORG, LOAD, REBUILD INDEX,
RECOVER TOCOPY, and RECOVER TOLOGPOINT.
When the REORG utility is used, the time at which Db2 writes the log
RBA to SYSIBM.SYSCOPY depends on the value of the SHRLEVEL
parameter:
v For SHRLEVEL NONE, the log RBA is written at the end of the reload
phase.
If a failure occurs before the end of the reload phase, the RBA is not
written to SYSCOPY.
If a failure occurs after the reload phase is complete (and therefore, after
the log RBA is written to SYSCOPY), the RBA is not backed out of
SYSCOPY.
v For SHRLEVEL REFERENCE and SHRLEVEL CHANGE, the log RBA is
written at the end of the switch phase.
If a failure occurs before the end of the switch phase, the RBA is not
written to SYSCOPY.
If a failure occurs after the switch phase is complete (and thus, after the
log RBA is written to SYSCOPY), the RBA is not backed out of
SYSCOPY.
The log RBA is put in SYSCOPY regardless of whether the LOG option is
YES or NO, or whether the UNLOAD PAUSE option is specified.
| When DSNDB01.DBD01, DSNDB01.SYSUTILX, DSNDB06.SYSTSCPY, and
| DSNDB01.SYSDBDXA are quiesced or copied, a SYSCOPY record is created
| for each table space and any associated index that has the COPY YES
| attribute. For recovery reasons, the SYSCOPY records for these three
| objects are placed in the log.
SYSIBM.SYSLGRNX
SYSIBM.SYSLGRNX is a directory table that contains records of the log
RBA ranges that are used during each period of time that any recoverable
page set is open for update. Those records speed recovery by limiting the
scan of the log for changes that must be applied.
If you discard obsolete image copies, you should consider removing their
records from SYSIBM.SYSCOPY and the obsolete log ranges from
SYSIBM.SYSLGRNX.
BSDS (bootstrap data set)
The BSDS contains information about system-level backups, and the Db2

Chapter 12. Backing up and recovering your data 445

 archive log data sets. The RECOVER utility uses the recovery base log
point RBA or LRSN value associated with the system-level backup to look
for the log information after restoring the object from the system-level
backup.
In a data-sharing environment, each Db2 member keeps track of the
system-level backups taken on that particular member in its BSDS.
DFSMShsm
The RECOVER utility queries DFSMShsm for information about whether a
system-level backup resides on disk or tape.
Related reference:
Db2 catalog tables (Db2 SQL)

How to report recovery information

You can use the REPORT utility when you plan for recovery.

The REPORT utility provides information necessary for recovering a page set. The
REPORT utility displays:
v Recovery information from the SYSIBM.SYSCOPY catalog table
v Log ranges of the table space from the SYSIBM.SYSLGRNX directory
v Archive log data sets from the bootstrap data set
v The names of all members of a table space set
v Recovery information about system-level backup copies retrieved from the
bootstrap data sets of each member in the data sharing group

You can also use the REPORT utility to obtain recovery information about the
catalog and directory.

Use the output from the DFSMShsm LIST COPYPOOL command with the
ALLVOLS option, in conjunction with the Db2 system-level backup information in
the PRINT LOG MAP (DSNJU004) utility output, to determine whether the
system-level backups of your database copy pool still reside on DASD or if they
have been dumped to tape. For a data sharing system, you should run the print
log map utility with the MEMBER * option to obtain system-level backup
information from all members.
Related concepts:
REPORT output (Db2 Utilities)
Related reference:
LIST command (z/OS DFSMShsm Storage Administration Reference)
REPORT (Db2 Utilities)

Discarding SYSCOPY and SYSLGRNX records

Use the MODIFY utility to delete obsolete records from SYSIBM.SYSCOPY and
SYSIBM.SYSLGRNX.

About this task

To keep a table space and its indexes synchronized, the MODIFY utility deletes the
SYSCOPY and SYSLGRNX records for the table space and its indexes that are
defined with the COPY YES option.

446 Administration Guide

Procedure

To discard SYSCOPY and SYSLGRNX records:

1. Complete the first three steps of the procedure that is presented in Locating
archive log data sets. In the third step, note the date of the earliest image copy
that you intend to keep.

Important: The earliest image copies and log data sets that you need for
recovery to the present date are not necessarily the earliest ones that you want
to keep. If you foresee resetting the Db2 subsystem to its status at any earlier
date, you also need the image copies and log data sets that allow you to
recover to that date.
If the most recent image copy of an object is damaged, the RECOVER utility
seeks a backup copy. If no backup copy is available, or if the backup is lost or
damaged, RECOVER uses a previous image copy. It continues searching until it
finds an undamaged image copy or no more image copies exist. The process
has important implications for keeping archive log data sets. At the very least,
you need all log records since the most recent image copy; to protect against
loss of data from damage to that copy, you need log records as far back as the
earliest image copy that you keep.
2. Run the MODIFY RECOVERY utility to clean up obsolete entries in
SYSIBM.SYSCOPY and SYSIBM.SYSLGRNX.
Pick one of the following MODIFY strategies, based on keyword options, that is
consistent with your overall backup and recovery plan:
DELETE DATE
With the DELETE DATE keyword, you can specify date of the earliest
entry you want to keep.
DELETE AGE
With the DELETE AGE keyword, you can specify the age of the earliest
entry you want to keep.
RETAIN LAST
With the RETAIN LAST keyword, you can specify the number of image
copy entries you want to keep.
RETAIN GDGLIMIT
If GDG data sets are used for your image copies, you can specify
RETAIN GDGLIMIT keyword to keep the number of image copies
matching your GDG definition.
RETAIN LOGLIMIT
With the RETAIN LOGLIMIT keyword, you can clean up all of the
obsolete entries that are older than the oldest archive log in your BOOT
STRAP DATA SET (BSDS).
For example, you could enter one of the following commands:
The DELETE DATE option removes records that were written earlier than the
given date. You can also specify the DELETE AGE option to remove records
that are older than a specified number of days or the DELETE RETAIN option
to specify a minimum number of image copies to keep.
MODIFY RECOVERY TABLESPACE dbname.tsname
DELETE DATE date
MODIFY RECOVERY TABLESPACE dbname.tsname
RETAIN LAST( n )
The RETAIN LAST( n ) option keeps the n recent records and removes the
older one.

Chapter 12. Backing up and recovering your data 447

 You can delete SYSCOPY records for a single partition by naming it with the
DSNUM keyword. That option does not delete SYSLGRNX records and does
not delete SYSCOPY records that are later than the earliest point to which you
can recover the entire table space. Thus, you can still recover by partition after
that point.
The MODIFY utility discards SYSLGRNX records that meet the deletion criteria
when the AGE or DATE options are specified, even if no SYSCOPY records
were deleted.
You cannot run the MODIFY utility on a table space that is in
RECOVER-pending status.
Even if you take system-level backups, use the MODIFY utility to delete
obsolete records from SYSIBM.SYSCOPY and SYSIBM.SYSLGRNX. You do not
need to delete the system-level backup information in the bootstrap data set
(BSDS) because only the last 50 system-level backups are kept.

Preparations for disaster recovery

If a Db2 computing center is totally lost, you can recover on another Db2
subsystem at a recovery site. To do this, you must regularly back up the data sets
and the log for the recovery subsystem. As with all data recovery operations, the
objectives of disaster recovery are to minimize the loss of data, workload
processing (updates), and time.

You can provide shorter restart times after system failures by using the installation
options LIMIT BACKOUT and BACKOUT DURATION. These options postpone
the backout processing of long-running URs during Db2 restart.

For data sharing environments, you can use the LIGHT(YES) or

LIGHT(NOINDOUBTS) parameter to quickly bring up a Db2 member to recover
retained locks. This option is not recommended for refreshing a single subsystem
and is intended only for a cross-system restart for a system that has inadequate
capacity to sustain the Db2 IRLM pair. Restart light can be used for normal restart
and recovery.

For data sharing, you need to consider whether you want the Db2 group to use
light mode at the recovery site. A light start might be desirable if you have
configured only minimal resources at the remote site. If this is the case, you might
run a subset of the members permanently at the remote site. The other members
are restarted and then directly shutdown.

| It is important that the disaster recovery process does not convert any objects to or
| from 10 byte extended RBA or LRSN format during the recovery and rebuild
| process. If some objects are in extended 10-byte format, temporarily change the
| UTILITY_OBJECT_CONVERSION subsystem parameter to NONE before you
| begin a disaster recovery and do not specify the RBALRSN_CONVERSION
| keyword in the control statements. After the disaster recovery is complete, change
| the UTILITY_OBJECT_CONVERSION subsystem parameter to its original value.

To perform a light start at the remote site:

1. Start the members that run permanently with the LIGHT(NO) option. This is
the default.
2. Start other members in light mode. The members started in light mode use a
smaller storage footprint. After their restart processing completes, they
automatically shut down. If ARM is in use, ARM does not automatically restart
the members in light mode again.

448 Administration Guide

 3. Members started with LIGHT(NO) remain active and are available to run new
work.

Several levels of preparation for disaster recovery exist:

v Prepare the recovery site to recover to a fixed point in time.
For example, you could copy everything weekly with a DFSMSdss volume
dump (logical), manually send it to the recovery site, and then restore the data
there.
v For recovery through the last archive, copy and send the following objects to the
recovery site as you produce them:
– Image copies of all catalog, directory, and user page sets
– Archive logs
– Integrated catalog facility catalog EXPORT and list
– BSDS lists
With this approach you can determine how often you want to make copies of
essential recovery elements and send them to the recovery site.
After you establish your copy procedure and have it operating, you must
prepare to recover your data at the recovery site.
v Use the log capture exit routine to capture log data in real time and send it to
the recovery site.
Related concepts:
Log capture routines
Restart light (Db2 Data Sharing Planning and Administration)
Related tasks:
Reading log records with the log capture exit routine
Related reference:
DSNTIPL: Active log data set parameters (Db2 Installation and Migration)
Related information:
Performing remote-site disaster recovery

System-wide points of consistency

In any disaster recovery scenario, system-wide points of consistency are necessary
for maintaining data integrity and preventing a loss of data. A direct relationship
exists between the frequency at which you make and send copies to the recovery
site and the amount of data that you can potentially lose.

The following figure is an overview of the process of preparing to start Db2 at a

recovery site.

Chapter 12. Backing up and recovering your data 449

 Disaster

Local site time line *

Full copy Archive Archive Incremental Archive
archive log log log copy log
archive log
Recovery site time line

Take tapes Data range Start Recover

to the lost with Db2 Db2
recovery site first level
of recovery

Figure 44. Preparing for disaster recovery. The information that you need to recover is
contained in the copies of data (including the Db2 catalog and directory) and the archive log
data sets.

Recommendations for more effective recovery from inconsistency

Data inconsistency problems can often be resolved by using the RECOVER utility.
However, if the RECOVER utility requires data from the recovery log or image
copy data sets, and that data is damaged or unavailable, you might need to resolve
the problem manually.

Actions to take to aid in successful recovery of inconsistent

data
You need to take certain steps to prepare for the successful recovery of inconsistent
data when you set up the database.
v During the installation of, or migration to, Db2 11, make a full image copy of the
Db2 directory and catalog by using installation job DSNTIJIC.
If you did not take this copy during installation or migration, use the COPY
utility to make a full image copy of the Db2 catalog and directory. If you do not
take such a copy and later find inconsistent data in the Db2 catalog or directory,
you cannot use the RECOVER utility to resolve the problem.
This action is recommended even if you take system-level backups.
v Periodically make an image copy of the catalog, directory, and user databases.
These copies minimize the time that the RECOVER utility requires to recover the
data. This action also increases the probability that the necessary archive log
data sets are available when you need them. Keep two copies of each level of
image copy data set. Having a second copy reduces the risk in case one image
copy data set is lost or damaged.
This action is recommended even if you take system-level backups.
v Use dual logging for your active log, archive log, and bootstrap data sets.
Dual logging increases the probability that you can recover from unexpected
problems. Dual logging is especially useful in resolving data inconsistency
problems.
v Before you use RECOVER, rename your data sets.

Restriction: Do not rename your data sets if you take system-level backups.

450 Administration Guide

 If the image copy or log data sets are damaged, you can compound the problem
by using the RECOVER utility. Therefore, before you use RECOVER, rename
your data sets by using one of the following methods:
– Rename the data sets that contain the page sets that you want to recover.
– Copy your data sets by using DSN1COPY.
– For user-defined data sets, use access method services to define a new data
set with the original name.
The RECOVER utility applies log records to the new data set with the old name.
Then, if a problem occurs during RECOVER utility processing, you have a copy
(under a different name) of the data set that you want to recover.
v Keep earlier copies of your data.
If you make an image copy or system-level backup of a page set that contains
inconsistent data, RECOVER cannot resolve the data inconsistency problem.
However, you can use RECOVER TOCOPY or TOLOGPOINT to resolve the
inconsistency if you have an older image copy or system-level backup that was
taken before the problem occurred. You can also resolve the inconsistency
problem by using the RESTOREBEFORE recovery option to avoid using the
most recent image copy.
v Maintain consistency between related objects.
A referential structure is a set of tables, including indexes and their relationships.
It includes at least one table, and for every table in the set, all of the
relationships in which the table participates and all the tables to which it is
related. To help maintain referential consistency, keep the number of table spaces
in a table space set to a minimum. Also, avoid tables of different referential
structures in the same table space. The TABLESPACESET option of the REPORT
utility reports all members of a table space set that are defined by referential
constraints.
A referential structure must be kept consistent for point-in-time recovery. Use the
QUIESCE utility to establish a point of consistency for a table space set. Later
the table space set can be recovered to this point of consistency without
introducing referential constraint violations.
A base table space must be kept consistent with its associated LOB or XML table
spaces for point-in-time recovery. Use the TABLESPACESET option of the
REPORT utility to identify related objects. Related objects can include
referentially related objects and auxiliary LOB or XML table spaces and their
indexes. Run CHECK INDEX to validate the consistency of indexes with their
associated table data. Run CHECK DATA to validate the consistency of base
table space data with LOB, XML, and referentially related table spaces. If LOB
columns exist, run CHECK LOB on any related LOB table spaces to validate the
integrity of each LOB table space within itself.
Related concepts:
How the initial Db2 logging environment is established
Related tasks:
Installation step 21: Back up the Db2 directory and catalog: DSNTIJIC (Db2
Installation and Migration)
Related reference:
COPY (Db2 Utilities)
RECOVER (Db2 Utilities)
DSN1COPY (Db2 Utilities)
Related information:

Chapter 12. Backing up and recovering your data 451

 Using Access Method Services (DFSMS Access Method Services for Catalogs)

Actions to avoid in recovery of inconsistent data

To minimize problems when recovering inconsistent data, you can avoid doing
certain actions.
v Do not discard archive logs that you might need.
The RECOVER utility might need an archive log to recover from an inconsistent
data problem. If you have discarded it, you cannot use the RECOVER utility and
must resolve the problem manually.
v Do not make an image copy of a page set that contains inconsistent data.
| If you use the COPY utility to make an image copy of a page set that contains
| inconsistent data, the RECOVER utility cannot recover a problem that involves
| that page set unless you have an older image copy of that page set that was
| taken before the problem occurred. You can run DSN1COPY with the CHECK
| option to determine whether intra-page data inconsistency problems exist on
| page sets before making image copies of them. You can also specify the
| CHECKPAGE parameter on the COPY utility which will cause the image copy
| to fail if an inconsistent page is detected.
v Do not use the TERM UTILITY command on utility jobs that you want to
restart.
If an error occurs while a utility is running, the data on which the utility was
operating might continue to be written beyond the commit point. If the utility is
restarted later, processing resumes at the commit point or at the beginning of the
current phase, depending on the restart parameter that was specified. If the
utility stops while it has exclusive access to data, other applications cannot
access that data. In this case, you might want to issue the TERM UTILITY
command to terminate the utility and make the data available to other
applications. However, use the TERM UTILITY command only if you cannot
restart or do not need to restart the utility job.
When you issue the TERM UTILITY command, two different situations can
occur:
– If the utility is active, it terminates at its next commit point.
– If the utility is stopped, it terminates immediately.
If you use the TERM UTILITY command to terminate a utility, the objects on
which the utility was operating are left in an indeterminate state. Often, the
same utility job cannot be rerun. The specific considerations vary for each utility,
depending on the phase in process when you issue the command.
Related tasks:
Discarding archive log records
Related reference:
-TERM UTILITY (Db2) (Db2 Commands)
CHECK DATA (Db2 Utilities)
COPY (Db2 Utilities)

How to recover multiple objects in parallel

To recover multiple objects in parallel, you can either use the RECOVER utility
with the PARALLEL keyword or schedule concurrent RECOVER jobs.

You can use the PARALLEL keyword on the RECOVER utility to support the
recovery of a list of objects in parallel. For those objects in the list that can be
452 Administration Guide
 processed independently, multiple subtasks are created to restore the image copies
for the objects. The parallel function can be used for either disk or tape.

If an image copy on tape was taken at the table space level and not on partition or
data set level, the PARALLEL keyword cannot enable RECOVER utility on
different parts (RECOVER TABLESPACE name DSNUM 1 TABLESPACE name DSNUM 2 etc.)
to restore the parts in parallel. RECOVER must read the appropriate part of the
data set for every DSNUM specification. This means that for a table space level
copy on tape, the tape is always read from the beginning. It is recommended for
image copies to tape, that a partitioned table space should be copied at the
partition level and if practical, to different tape stacks. You can use LISTDEF with
PARTLEVEL to simplify your work.

When you use one utility statement to recover indexes and table spaces, the logs
for all indexes and tables spaces are processed in one pass. This approach results
in a significant performance advantage, especially when the required archive log
data is on tape, or the fast log apply function is enabled, or if both of these
conditions occur.

This parallel log processing for fast log apply is not dependent whether you
specify RECOVER TABLESPACE name DSNUM 1 TABLESPACE name DSNUM 2 etc. or only
RECOVER TABLESPACE name, because the log apply is always done at the
partition level. You should also note that if you have copies at the partition level,
you cannot specify RECOVER TABLESPACE dbname.tsname, you must specify RECOVER
TABLESPACE dbname.tsname DSNUM 1 TABLESPACE dbname.tsname DSNUM 2 etc.. You
can simplify this specification by using LISTDEF with PARTLEVEL if all parts
must be recovered.

You can schedule concurrent RECOVER jobs that process different partitions. The
degree of parallelism in this case is limited by contention for both the image copies
and the required log data.

Log data is read by concurrent jobs as follows:

v Active logs and archive logs are read entirely in parallel.
v A data set that is controlled by DFSMShsm is first recalled. It then resides on
disk and is read in parallel.
Related reference:
RECOVER (Db2 Utilities)
Related information:
DSNU512I (Db2 Messages)

Recovery of page sets and data sets

You can recover objects in several ways, if the objects have the LOGGED attribute.
v If you made backup copies of table spaces by using the COPY utility, the
COPYTOCOPY utility, or the inline copy feature of the LOAD or REORG utility,
use the RECOVER utility to recover the table spaces to the current or a previous
state.
v If you made backup copies of indexes by using the Db2 COPY utility, use the
RECOVER utility to recover the indexes to the current or a previous state.
Backing up indexes is optional.
v If you made system-level backups using the BACKUP SYSTEM utility, use the
RECOVER utility to recover the objects to the current or a previous state.

Chapter 12. Backing up and recovering your data 453

 v If you have z/OS Version 1.8 and have made backup copies using a method
outside of Db2 control, such as with DSN1COPY or the DFSMSdss concurrent
copy function, use the same method to restore the objects to a prior point in
time. Then, if you want to restore the objects to currency, run the RECOVER
utility with the LOGONLY option.

The RECOVER utility performs these actions:

v Restores the most current backup, which can be either a full image copy,
concurrent copy, or system-level backup.
v Applies changes recorded in later incremental image copies of table spaces, if
applicable, and applies later changes from the archive or active log.

RECOVER can act on:

v A table space, or list of table spaces
v An index, or list of indexes
v A specific partition or data set within a table space
v A specific partition within an index space
v A mixed list of table spaces, indexes, partitions, and data sets
v A single page
v A page range within a table space that Db2 finds in error
v The catalog and directory

Typically, RECOVER restores an object to its current state by applying all image
copies or a system-level backup and log records. It can also restore the object to a
prior state, which is one of the following points in time:
v A specified point on the log (use the TOLOGPOINT or TORBA keyword)
v A particular image copy (use the TOCOPY, TOLASTCOPY, or
TOLASTFULLCOPY keywords)

You can use the RECOVER utility with the BACKOUT YES keyword to recover
data to a prior state by backing out committed work from the current state of an
object.

With z/OS Version 1.8, the RECOVER utility can use system-level backups for
object level recovery. The RECOVER utility chooses the most recent backup of
either an image copy, concurrent copy, or system-level backup to restore. The most
recent backup determination is based on the point of recovery (current or prior
point in time) for the table spaces or indexes (with the COPY YES attribute) being
recovered.

The RECOVER utility can use image copies for the local site or the recovery site,
regardless of where you invoke the utility. The RECOVER utility locates all full
and incremental image copies.

The RECOVER utility first attempts to use the primary image copy data set. If an
error is encountered (allocation, open, or I/O), RECOVER attempts to use the
backup image copy. If Db2 encounters an error in the backup image copy or no
backup image copy exists, RECOVER falls back to an earlier full copy and
attempts to apply incremental copies and log records. If an earlier full copy in not
available, RECOVER attempts to apply log records only.

Not every recovery operation requires RECOVER; see also:

Recovering error ranges for a work file table space
Recovery of the work file database
Recovery of data to a prior point in time

454 Administration Guide

 Important: Be very careful when using disk dump and restore for recovering a
data set. Disk dump and restore can make one data set inconsistent with Db2
subsystem tables in some other data set. Use disk dump and restore only to restore
the entire subsystem to a previous point of consistency, and prepare that point as
described in the alternative in step Preparing to recover an entire Db2 subsystem
to a prior point in time using image copies or object-level backups.
Related reference:
Implications of moving data sets after a system-level backup
REBUILD INDEX (Db2 Utilities)
RECOVER (Db2 Utilities)

Recovery of the work file database

The work file database (called DSNDB07, except in a data sharing environment) is
used for temporary space for certain SQL operations, such as join and ORDER BY.

If DSNDB01.DBD01 or DSNDB01.SYSDBDXA is stopped or otherwise inaccessible

when Db2 is started, the descriptor for the work file database is not loaded into
main storage. Thus, the work file database is not allocated. To recover from this
condition after DSNDB01.DBD01 and DSNDB01.SYSDBDXA are available, stop and
then start the work file database again.

You cannot use RECOVER with the work file database.

Page set and data set copies

You can use the COPY utility to copy data from a page set to a z/OS sequential
data set on disk or tape. The COPY utility makes a full or incremental image copy,
depending on what you specify. You also can use the COPY utility to make copies
that can be used for local or off-site recovery operations.

In addition, you can use the COPY utility to create a FlashCopy image copy in
VSAM format from a page set. Fast replication makes the copy process virtually
instantaneous. FlashCopy image copies are always full copies.

Use the COPYTOCOPY utility to make additional image copies from a primary
image copy that you made with the COPY utility.

A full image copy is required for indexes.

You can use the CONCURRENT option of the COPY utility to make a copy, with
DFSMSdss concurrent copy, that is recorded in the Db2 catalog.

Use the MERGECOPY utility to merge several image copies. MERGECOPY does
not apply to indexes.

The CHANGELIMIT option of the COPY utility causes Db2 to make an image
copy automatically when a table space has changed past a default limit or a limit
that you specify. Db2 determines whether to make a full or incremental image
copy based on the values specified for the CHANGELIMIT option.
v If the percent of changed pages is greater than the low CHANGELIMIT value
and less than the high CHANGELIMIT value, then Db2 makes an incremental
image copy.
v If the percentage of changed pages is greater than or equal to the high
CHANGELIMIT value, then Db2 makes a full image copy.

Chapter 12. Backing up and recovering your data 455

 v If the ANY keyword is used with the CHANGELIMIT option is used, then Db2
makes a full image copy.

The CHANGELIMIT option does not apply to indexes.

If you want Db2 to recommend what image copies should be made but not to
make the image copies, use the CHANGELIMIT and REPORTONLY options of the
COPY utility. If you specify the parameter DSNUM(ALL) with CHANGELIMIT
and REPORTONLY, Db2 reports information for each partition of a partitioned
table space or each piece of a nonpartitioned table space. For partitioned objects, if
you only want the partitions in COPY-pending status or informational
COPY-pending status to be copied, then you must specify a list of partitions. You
can do this by invoking COPY on a LISTDEF list built with the PARTLEVEL
option. An output image copy data set is created for each partition that is in
COPY-pending or informational COPY-pending status.

If you want to copy objects that are in copy pending (COPY) or informational copy
pending (ICOPY), you can use the SCOPE PENDING option of the COPY utility. If
you specify the parameter DSNUM(ALL) with SCOPE PENDING for partitioned
objects, and if one or more of the partitions are in COPY or ICOPY, the copy will
be taken of the entire table or index space.

You can add conditional code to your jobs so that an incremental, full image copy,
or some other step is performed depending on how much the table space has
changed. When you use the COPY utility with the CHANGELIMIT option to
display image copy statistics, the COPY utility uses the following return codes to
indicate the degree that a table space or list of table spaces has changed:
Code Meaning
1 Successful; no CHANGELIMIT value is met. No image copy is
recommended or taken.
2 Successful; the percentage of changed pages is greater than the low
CHANGELIMIT value and less than the high CHANGELIMIT value. An
incremental image copy is recommended or taken.
3 Successful; the percentage of changed pages is greater than or equal to the
high CHANGELIMIT value. A full image copy is recommended or taken.

When you use generation data groups (GDGs) and need to make an incremental
image copy, you can take the following steps to prevent an empty image copy
output data set from being created if no pages have been changed. You can
perform either of the following actions:
v Make a copy of your image copy step, but add the REPORTONLY and
CHANGELIMIT options to the new COPY utility statement. The REPORTONLY
keyword specifies that you want only image copy information to be displayed.
Change the SYSCOPY DD card to DD DUMMY so that no output data set is
allocated. Run this step to visually determine the change status of your table
space.
v Add step 1 before your existing image copy step, and add a JCL conditional
statement to examine the return code and execute the image copy step if the
table space changes meet either of the CHANGELIMIT values.

You can use the COPY utility with the CHANGELIMIT option to determine
whether any space map pages are broken. You can also use the COPY utility to
identify any other problems that might prevent an image copy from being taken,

456 Administration Guide

such as the object being in RECOVER-pending status. You need to correct these
problems before you run the image copy job.

You can also make a full image copy when you run the LOAD or REORG utility.
This technique is better than running the COPY utility after the LOAD or REORG
utility because it decreases the time that your table spaces are unavailable.
However, only the COPY utility makes image copies of indexes.

In addition, you can make a FlashCopy image copy when you run the LOAD,
REORG TABLESPACE, REORG INDEX, or REBUILD INDEX utilities.
Related concepts:
Plans for recovery of indexes
FlashCopy image copies (Db2 Utilities)
Related reference:
COPY (Db2 Utilities)
MERGECOPY (Db2 Utilities)

Creating FlashCopy image copies

You can configure certain utilities to create image copies by using the FlashCopy
function that is provided by z/OS DFSMS and the IBM TotalStorage ESS storage
subsystems. FlashCopy can reduce both the unavailability of data during the copy
operation and the amount of time that is required for recovery operations.

About this task

The following Db2 utilities support the creation of FlashCopy image copies:
v COPY
v LOAD
v REBUILD INDEX
v REORG INDEX
v REORG TABLESPACE

FlashCopy image copies are output to VSAM data sets. The following utilities
accept the VSAM data sets that are produced by FlashCopy as input:
v COPYTOCOPY
v DSN1COMP
v DSN1COPY
v DSN1PRNT
v RECOVER

Procedure

To create a FlashCopy image copy:

Specify the FlashCopy option by using Db2 subsystem parameters, utility control
statement parameters, or both.
You can use the FlashCopy subsystem parameters to define the FlashCopy option
as the default behavior for each of the utilities that support the FlashCopy option.
When the FlashCopy subsystem parameters are enabled as the default behavior,
you do not need to specify the FlashCopy options in the utility control statement.
If you specify the FlashCopy options in both the subsystem parameters and the

Chapter 12. Backing up and recovering your data 457

 utility control statement parameters, the specifications in the utility control
statement override the specifications of the subsystem parameters.
When creating a FlashCopy image copy, the COPY and LOAD utilities can include
additional phases of execution, depending on the options that are specified in the
utility control statement.
When creating a FlashCopy image copy, the following utilities also can create one
to four additional sequential format image copies in a single execution:
v COPY
v LOAD with the REPLACE option specified
v REORG TABLESPACE

Recommendation: To provide a recovery base for media failures, create one or

more additional sequential format image copies when you create a FlashCopy
image copy.
Related concepts:
FlashCopy image copies (Db2 Utilities)
Related reference:
COPY (Db2 Utilities)
LOAD (Db2 Utilities)
REBUILD INDEX (Db2 Utilities)
REORG INDEX (Db2 Utilities)
REORG TABLESPACE (Db2 Utilities)

How to make concurrent copies using DFSMS

The concurrent copy function of the Data Facility Storage Management Subsystem
(DFSMS) can copy a data set at the same time that other processes access the data.
Using DFSMS does not significantly impact application performance.

The two ways to use the concurrent copy function of DFSMS are:
v Run the COPY utility with the CONCURRENT option. Db2 records the resulting
image copies in SYSIBM.SYSCOPY. To recover with these DFSMS copies, you
can run the RECOVER utility to restore those image copies and apply the
necessary log records to them to complete recovery.
v Make copies using DFSMS outside of Db2 control. To recover with these copies,
you must manually restore the data sets, and then run RECOVER with the
LOGONLY option to apply the necessary log records.

Backing up with RVA storage control or Enterprise Storage

Server
You can use the IBM RAMAC Virtual Array (RVA) storage control with the
peer-to-peer remote copy (PPRC) function or Enterprise Storage Server® to recover
Db2 subsystems at a remote site in the event of a disaster at the local site. Both of
these methods provide a faster way to recover subsystems.

About this task

You can use RVAs, PPRC, and the RVA fast copy function, SnapShot, to create
entire Db2 subsystem backups to a point in time on a hot stand-by remote site
without interruption of any application process. Another option is to use the
Enterprise Storage Server FlashCopy function to create point-in-time backups of
entire Db2 subsystems.

458 Administration Guide

 Using RVA SnapShot or Enterprise Storage Server FlashCopy for a Db2 backup
requires a method of suspending all update activity for a Db2 subsystem. You
suspend update activity to allow a remote copy of the entire subsystem to be made
without quiescing the update activity at the primary site. Use the SUSPEND option
on the SET LOG command to suspend all logging activity at the primary site,
which also prevents any database updates.

After the remote copy is created, use the RESUME option on the SET LOG
command to return to normal logging activities.
Related reference:
-SET LOG (Db2) (Db2 Commands)
Related information:
RAMAC Virtual Array: Implementing Peer-to-Peer Remote Copy (IBM
Redbooks)
RAMAC Virtual Array (IBM Redbooks)
IBM TotalStorage Enterprise Storage Server Introduction and Planning Guide

System-level backups for object-level recoveries

If a system-level backup is chosen as a recovery base for an object, DFSMShsm is
invoked by the RECOVER utility. This process restores the data sets for the object
from the system-level backup of the database copy pool.

You need to set subsystem parameter SYSTEM_LEVEL_BACKUPS to YES so that

the RECOVER utility will consider system-level backups.
v If the system-level backup resides on DASD, it is used for the restore of the
object.
v If the system-level backup no longer resides on DASD, and has been dumped to
tape, then the dumped copy is used for the restore of the object if FROMDUMP
was specified.

Message DSNU1520I is issued to indicate that a system-level backup was used as

the recovery base.

If DFSMShsm cannot restore the data sets, message DSNU1522I with reason code 8
is issued. If OPTIONS EVENT(ITEMERROR,SKIP) was specified, the object is
skipped and the recovery proceeds on the rest of the objects. Otherwise, the
RECOVER utility terminates.

If you specify YES for the RESTORE/RECOVER FROM DUMP option on

installation panel DSNTIP6 or if you specify the FROMDUMP option on the
RECOVER utility statement, then only dumps on tape of the database copy pool
are used for the restore of the data sets. In addition, if you specify a dump class
name on installation panel DSNTIP6 or if you specify the DUMPCLASS option on
the RECOVER utility statement, then the data sets will be restored from the
system-level backup that was dumped to that particular DFSMShsm dump class. If
you do not specify a dump class name on installation panel DSNTIP6 or on the
RECOVER utility statement, then the RESTORE SYSTEM utility issues the
DFSMShsm LIST COPYPOOL command and uses the first dump class listed in the
output.

Use the output from LISTCOPY POOL and PRINT LOG MAP to see the
system-level backup information.

Chapter 12. Backing up and recovering your data 459

 Use the output from the REPORT RECOVERY utility to determine whether the
objects to be recovered have image copies, concurrent copies, or a utility LOG YES
event that can be used as a recovery base. You also can determine if these objects
are contained in a system-level backup.

You can take system-level backups using the BACKUP SYSTEM utility. However, if
any of the following utilities were run since the system-level backup that was
chosen as the recovery base, then the use of the system-level backup is prohibited
for object level recoveries to a prior point in time:
v REORG TABLESPACE
v REORG INDEX
v REBUILD INDEX
v LOAD REPLACE
v RECOVER from image copy or concurrent copy

In the following illustration, RECOVER TOLOGPOINT receives message

DSNU1528I with return code 8, indicating that the recovery has failed.

Figure 45. Failed recovery

In this example, use RECOVER with RESTOREBEFORE X'A0000' to use inline

image recovery copy taken at X'90000' as a recovery base.
Related concepts:
How to report recovery information
Dump Tasks (z/OS DFSMShsm Storage Administration)

Recovery of data to a prior point in time

You can restore data to the state at which it existed at a prior point in time.

To restore data to a prior point in time, use the methods that are described in the
following topics:
v Options for restoring data to a prior point in time
v Restoring data by using DSN1COPY
v Backing up and restoring data with non-Db2 dump and restore

The following terms apply to the subject of recovery to a prior point in time:
Term Meaning
DBID Database identifier

460 Administration Guide

 OBID Data object identifier
PSID Table space identifier

Plans for point-in-time recovery

In some circumstances, you cannot recover to the current point in time. Plan for
this possibility by establishing a consistent point in time to which to recover if
these circumstances occur.

TOCOPY is a viable alternative in many situations in which recovery to the current

point in time is not possible or is not desirable. When making copies of a single
object, use SHRLEVEL REFERENCE to establish consistent points for TOCOPY
recovery. Copies that are made with SHRLEVEL CHANGE do not copy data at a
single instant, because changes can occur as the copy is made. A subsequent
RECOVER TOCOPY operation can produce inconsistent data.

When copying a list of objects, use SHRLEVEL REFERENCE. If a subsequent

recovery to a point in time is necessary, you can use a single RECOVER utility
statement to list all of the objects, along with TOLOGPOINT, to identify the
common RBA or LRSN value.

An inline copy that is made during LOAD REPLACE can produce unpredictable
results if that copy is used later in a RECOVER TOCOPY operation. Db2 makes the
copy during the RELOAD phase of the LOAD operation. Therefore, the copy does
not contain corrections for unique index violations and referential constraint
violations because those corrections occur during the INDEXVAL and ENFORCE
phases.

You can use the QUIESCE utility to establish an RBA or LRSN to recover to. The
RBA or LRSN can be used in point-in-time recovery.

For partitioned table spaces, if the data was redistributed across partitions by
running REORG (either REORG REBALANCE or REORG to materialize limit key
changes), additional recovery implications apply:
v If you recover to a point in time and use an image copy or system level-backup
that was taken before the redistributing REORG, the affected partitions are
placed in REORG-pending (REORP) status.
v If you recover to a point in time after you used ALTER to modify the limit keys
but before running REORG to redistribute the data, the affected partitions are
also placed in REORP status.

If you use the REORG TABLESPACE utility with the SHRLEVEL REFERENCE or
SHRLEVEL CHANGE option on only some partitions of a table space, you must
recover that table space at the partition level. When you take an image copy of
such a table space, the COPY utility issues the informational message DSNU429I.

You can take system-level backups using the BACKUP SYSTEM utility.

Recommendation: Restrict the use of the TOCOPY, TOLOGPOINT, TOLASTCOPY,

and TOLASTFULLCOPY options of the RECOVER utility to personnel with a
thorough knowledge of the Db2 recovery environment.
Related concepts:
Point-in-time recovery (Db2 Utilities)
Point-in-time recovery using the RECOVER utility

Chapter 12. Backing up and recovering your data 461

 Related reference:
RECOVER (Db2 Utilities)

Point-in-time recovery with system-level backups

System-level backups are fast replication backups that are created by using the
BACKUP SYSTEM utility.

The BACKUP SYSTEM utility invokes z/OS Version 1 Release 5 or later

DFSMShsm services to take volume copies of the data in a sharing Db2 system. All
Db2 data sets that are to be copied (and then recovered) must be managed by SMS.

The BACKUP SYSTEM utility requires z/OS Version 1 Release 5 or later data
structures called copy pools. Because these data structures are implemented in
z/OS, Db2 cannot generate copy pools automatically. Before you invoke the
BACKUP SYSTEM utility, copy pools must be allocated in z/OS.

The BACKUP SYSTEM utility invokes the DFSMShsm fast replication function to
take volume level backups using FlashCopy.

You can use the BACKUP SYSTEM utility to ease the task of managing data
recovery. Choose either DATA ONLY or FULL, depending on your recovery needs.
Choose FULL if you want to backup both your Db2 data and your Db2 logs.

Because the BACKUP SYSTEM utility does not quiesce transactions, the
system-level backup is a fuzzy copy, which might not contain committed data and
might contain uncommitted data. The RESTORE SYSTEM utility uses these
backups to restore databases to a given point in time. The Db2 data is made
consistent by Db2 restart processing and the RESTORE SYSTEM utility. Db2 restart
processing determines which transactions were active at the given recovery point,
and writes the compensation log records for any uncommitted work that needs to
be backed out. The RESTORE SYSTEM utility restores the database copy pool, and
then applies the log records to bring the Db2 data to consistency. During the
LOGAPPLY phase of the RESTORE SYSTEM utility, log records are applied to redo
the committed work that is missing from the system-level backup, and log records
are applied to undo the uncommitted work that might have been contained in the
system-level backup.
Data-only system backups
The BACKUP SYSTEM DATA ONLY utility control statement creates
system-level backups that contain only databases.
The RESTORE SYSTEM utility uses these backups to restore databases to a
given point in time. In this type of recovery, you lose only a few seconds
of data, or none, based on the given recovery point. However, recovery
time varies and might be extended due to the processing of the Db2 logs
during Db2 restart and during the LOGAPPLY phase of the RESTORE
SYSTEM utility. The number of logs to process depends on the amount of
activity on your Db2 system between the time of the system-level backup
and the given recovery point.
Full system backups
The BACKUP SYSTEM FULL utility control statement creates system-level
backups that contain both logs and databases. With these backups, you can
recover your Db2 system to the point in time of a backup by using normal
Db2 restart recovery, or to a given point in time by using the RESTORE
SYSTEM utility.

462 Administration Guide

 To recover your Db2 system to the point in time of a backup by using
normal Db2 restart recovery, stop Db2, and then restore both the database
and log copy pools outside of Db2 by using DFSMShsm FRRECOV
COPYPOOL (cpname) GENERATION (gen). After you successfully restart
Db2, your Db2 system has been recovered to a point of consistency based
on the time of the backup.
The RESTORE SYSTEM utility uses full system backup copies as input, but
the utility does not restore the volumes in the log copy pool. If your
situation requires that the volumes in the log copy pool be restored, you
must restore the log copy pool before restarting Db2. For example, you
should restore the log copy pool when you are using a full system-level
backup at your remote site for disaster recovery.
When you recover your Db2 system to the point in time of a full system
backup, you could lose a few hours of data, because you are restoring your
Db2 data and logs to the time of the backup. However, recovery time is
brief, because Db2 restart processing and the RESTORE SYSTEM utility
need to process a minimal number of logs.
If you choose not to restore the log copy pool prior to running the
RESTORE SYSTEM utility, the recovery is equivalent to the recovery of a
system with data-only backups. In this type of recovery, you lose only a
few seconds of data, or none, based on the given recovery point. However,
recovery time varies and might be extended due to the processing of the
Db2 logs during Db2 restart and during the LOGAPPLY phase of the
RESTORE SYSTEM utility. The number of logs to process depends on the
amount of activity on your Db2 system between the time of the
system-level backup and the given recovery point.

You can use the BACKUP SYSTEM utility to manage system-level backups on tape.
Choose either DUMP or DUMPONLY to dump to tape.

Restriction: The DUMP and DUMPONLY options require z/OS Version 1.8.

Use the DUMP and DUMPONLY options for:

v Managing the available DASD space.
v Retaining the system-level backups for the long term.
v Providing a means of recovery after a media failure.
v Remote site recovery procedure.
Related concepts:
Considerations for using the BACKUP SYSTEM utility and DFSMShsm
Related tasks:
Recovering a Db2 subsystem to a prior point in time
Recovering a Db2 system to a given point in time using the RESTORE SYSTEM
utility
Related reference:
Implications of moving data sets after a system-level backup
BACKUP SYSTEM (Db2 Utilities)
RESTORE SYSTEM (Db2 Utilities)
Related information:
Defining Copy Pools (DFSMSdfp Storage Administration)

Chapter 12. Backing up and recovering your data 463

 Point-in-time recovery using the RECOVER utility
Within certain limitations, the RECOVER utility can use system-level backups that
you created by using the BACKUP SYSTEM utility for object-level recoveries.

Restriction: Recovery of objects from system-level backups requires z/OS Version

1.8 or later. You also must set the SYSTEM_LEVEL_BACKUPS subsystem
parameter to YES.

The BACKUP SYSTEM utility invokes the DFSMShsm fast replication function to
take volume level backups using FlashCopy. The RESTORE phase of the RECOVER
utility is faster if you use these backups, because Db2 table spaces and index
spaces can be restored by using FlashCopy. You might need to change some utility
control statements to use FlashCopy technology for the LOAD utility, the REORG
utility, and the REBUILD INDEX utility.

If any of the following utilities were run since the system-level backup that was
chosen as the recovery base, the use of the system-level backup by the RECOVER
utility is prohibited:
v REORG TABLESPACE
v REORG INDEX
v REBUILD INDEX
v LOAD REPLACE
v RECOVER from image copy or concurrent copy

In these cases, the recovery terminates with message DSNU1528I and return code
8.

Note: For z/OS Version 1 Release 11 and later, the RECOVER utility can use a
system-level backup, even if the REBUILD INDEX, RECOVER, REORG, and LOAD
utilities ran after the system-level backup was created. The RECOVER utility has
been modified so that you can use system-level backups, even if a data set has
moved since the backup was created.

| If a REORG that removes dropped columns has run since the system-level backup
| that was chosen as the recovery base, the use of the system-level backup by the
| RECOVER utility is prohibited, and the recovery terminates with message
| DSNU556I and return code 8.

| For a partition-by-growth table space, a point-in-time recovery is not allowed if the

| recovery period includes REORG TABLESPACE deleting empty partitions. REORG
| TABLESPACE can delete the highest numbered partitions if they are empty and the
| REORG_DROP_PBG_PARTS subsystem parameter is set to ENABLE.
Related concepts:
Data restore of an entire system
Related reference:
Implications of moving data sets after a system-level backup
Related information:
DSNU1528I (Db2 Messages)

Options for restoring data to a prior point in time

TOCOPY, TOLOGPOINT, TOLASTCOPY, TORBA, and TOLASTFULLCOPY are
options of the RECOVER utility. These RECOVER utility options recover data to a

464 Administration Guide

prior time, not to the present time. Therefore, RECOVER utility jobs that use these
options result in what are referred to as point-in-time recoveries.

The TOCOPY, TOLASTCOPY, and TOLASTFULLCOPY options identify an image

copy as the point in time to which to recover. With these options, the RECOVER
utility restores objects to the value of a specified image copy and does not apply
subsequent changes from the log. If the image copy that is specified in one of these
options cannot be applied, the RECOVER utility uses an earlier full image copy
and applies the changes in the log up to the point-in-time at which the specified
image copy was taken.

If the image copy data set is cataloged when the image copy is made, the entry for
that copy in SYSIBM.SYSCOPY does not record the volume serial numbers of the
data set. You can identify that copy by its name by using TOCOPY data set name. If
the image copy data set was not cataloged when it was created, you can identify
the copy by its volume serial identifier by using TOVOLUME volser.

With TOLOGPOINT, the RECOVER utility restores the object from the most recent
of either a full image copy or system-level backup taken prior to the recovery
point. If a full image copy is restored, the most recent set of incremental copies
that occur before the specified log point are restored. The logged changes are
applied up to, and including, the record that contains the log point. If no full
image copy or system-level backup exists before the chosen log point, recovery is
attempted entirely from the log. The log is applied from the log point at which the
page set was created or the last LOAD or REORG TABLESPACE utility was run to
a log point that you specify. You can apply the log only if you have not used the
MODIFY RECOVERY utility to delete the SYSIBM.SYSLGRNX records for the log
range your recovery requires.

Uncommitted transactions running at the recover point-in-time are automatically

detected and the changes on the recovered objects are rolled back leaving them in
a transactionally consistent state.

You can use the TOLOGPOINT option in both data sharing and non-data-sharing
environments. In a non-data-sharing environment, TOLOGPOINT and TORBA are
interchangeable keywords that identify an RBA on the log at which recovery is to
stop. TORBA can be used in a data sharing environment only if the TORBA value
is before the point at which data sharing was enabled.

Recommendation: Use the TOLOGPOINT keyword instead of the TORBA

keyword. Although Db2 still supports the TORBA option, the TOLOGPOINT
option supports both data sharing and non-data-sharing environments and is used
for both of these environments throughout this information.

Data consistency for point-in-time recoveries

The RECOVER utility can automatically detect uncommitted transactions that are
running at the recover point in time and roll back the changes on the recovered
objects. After recovery, the objects are left in their transactionally consistent state.

RECOVER TOLOGPOINT and RECOVER TORBA have the recover with

consistency as their default behavior. However, RECOVER TOCOPY,
TOLASTCOPY, and TOLASTFULLCOPY using SHRLEVEL CHANGE image copy
do not ensure data consistency.

RECOVER TOLOGPOINT and RECOVER TOCOPY can be used on a single:

v Partition of a partitioned table space

Chapter 12. Backing up and recovering your data 465

 v Partition of a partitioning index space
v Data set of a simple table space

Tip: If you take SHRLEVEL CHANGE image copies and need to recover to a prior
point in time, then you can use the RBA or LRSN (the START_RBA syscopy
column value) associated with image copy as the TOLOGPOINT value.

All page sets must be restored to the same level; otherwise the data is inconsistent.

Point-in-time recovery can cause table spaces to be placed in CHECK-pending

status if they have table check constraints or referential constraints that are defined
on them. When recovering tables that are involved in a referential constraint, you
should recover all the table spaces that are involved in a constraint. This is the table
space set.

To avoid setting CHECK-pending status, you must perform both of the following
tasks:
v Recover the table space set to a quiesce point.
If you do not recover each table space of the table space set to the same quiesce
point, and if any of the table spaces are part of a referential integrity structure:
– All dependent table spaces that are recovered are placed in CHECK-pending
status with the scope of the whole table space.
– All table spaces that are dependent on the table spaces that are recovered are
placed in CHECK-pending status with the scope of the specific dependent
tables.
v Establish a quiesce point or take an image copy after you add check constraints
or referential constraints to a table.
If you recover each table space of a table space set to the same quiesce point, but
referential constraints were defined after the quiesce point, the CHECK-pending
status is set for the table space that contains the table with the referential
constraint.

The RECOVER utility sets various states on table spaces. The following
point-in-time recoveries set various states on table spaces:
v When the RECOVER utility finds an invalid column during the LOGAPPLY
phase on a LOB table space, it sets the table space to auxiliary-warning (AUXW)
status.
v When you recover a LOB or XML table space to a point in time that is not a
quiesce point or to an image copy that is produced with SHRLEVEL CHANGE,
the LOB or XML table space is placed in CHECK-pending (CHKP) status.
v When you recover the LOB or XML table space, but not the base table space, to
any previous point in time, the base table space is placed in auxiliary
CHECK-pending (ACHKP) status, and the index space that contains an index on
the auxiliary table is placed in REBUILD-pending (RBDP) status.
v When you recover only the base table space to a point in time, the base table
space is placed in CHECK-pending (CHKP) status.
v When you recover only the index space that contains an index on the auxiliary
table to a point in time, the index space is placed in CHECK-pending (CHKP)
status.
v When you recover partitioned table spaces with the RECOVER utility to a point
in time that is prior to the redistribution of data across partitions, all affected
partitions are placed in REORG-pending (REORP) status.

466 Administration Guide

v When you recover a table space to point in time prior to when an identity
column was defined with the RECOVER utility, the table space is placed in
REORG-pending (REORP) status.
v If you do not recover all objects that are members of a referential set to a prior
point in time with the RECOVER utility, or if you recover a referential set to a
point in time that is not a point of consistency with the RECOVER utility, all
dependent table spaces are placed in CHECK-pending (CHKP) status.
v When you recover a table space to a point in time prior to the REORG or
LOAD REPLACE that first materializes the default value for the row change
timestamp column, the table space that contains the table with the row change
timestamp column is placed in REORG-pending (REORP) status.

Important: The RECOVER utility does not back out CREATE or ALTER
statements. After a recovery to a previous point in time, all previous alterations to
identity column attributes remain unchanged. Because these alterations are not
backed out, a recovery to a point in time might put identity column tables out of
sync with the SYSIBM.SYSSEQUENCES catalog table. You might need to modify
identity column attributes after a recovery to resynchronize identity columns with
the catalog table.

If a table space or partition that is in reordered row format is recovered to a point

in time when the table space or partition was in basic row format, the table space
or partition will revert to basic row format.
Related concepts:
Recovering a table space that contains LOB or XML data (Db2 Utilities)
Related information:
Recovering from referential constraint violation

The RECOVER TOLOGPOINT option in a data sharing system:

You can use the RECOVER utility with the TOLOGPOINT option to recover a data
sharing Db2 subsystem.

The following figure shows a data sharing system with three Db2 members (A, B,
and C). Table space TS1 and TS2 are being recovered to time TR using the
RECOVER TOLOGPOINT option, they are listed in the same RECOVER job. UR1
was inflight at TR time running on member A, its start time was T1, at time T2 it
updated TS1, and at time T3 it updated TS2, T2 is earlier than T3. UR2 was
aborting at TR time running on member C, its start time was T4 and at time T5 it
updated TS2. There was no active UR on member B at time TR.

Chapter 12. Backing up and recovering your data 467

Figure 46. Using the RECOVER TOLOGPOINT option in a data sharing system

RECOVER utility job output messages

The RECOVER utility takes the following actions and provides the following
messages during recovery in a data sharing system.
LOGCSR phase
After the RECOVER LOGAPPLY phase, the RECOVER utility enters the
log analysis phase, known as the LOGCSR phase. The following messages
are issued during this phase:
DSNU1550I
Indicates the start of log analysis on member A.
DSNU1551I
Indicates the end of log analysis on member A.
DSNU1550I
Indicates the start of log analysis on member C.
DSNU1551I
Indicates the end of log analysis on member C.
DSNU1552I
Indicates the end of LOGCSR phase of RECOVER utility.
DSNU1553I
Issued after the end of the LOGCSR phase. The following
information is shown in the message:
v UR1 on member A modified TS1 at T2 time.
v UR1 on member A modified TS2 at T3 time.
v UR2 on member C modified TS2 at T5 time.

468 Administration Guide

LOGUNDO phase
The RECOVER utility enters the LOGUNDO phase. The following
messages are issued during this phase:
DSNU1554I
Indicates the start of backout for member A.
v Backout is performed on TS2 and TS1 and log records are read
from time TR to T2.
v There maybe one or more DSNU1555I messages showing the
backout progress for member A.
DSNU1556I
Indicates the end of backout on member A.
DSNU1554I
Indicates the start of backout on member C.
v Backout is performed on TS2 and log records are read from time
TR to T5.
v There may be one or more DSNU1555I messages showing the
backout progress for member C.
DSNU1556I
Indicates the end of backout for member C.
DSNU1557I
Indicates the end of the LOGUNDO phase of the RECOVER utility.
A special type of compensation log record will be written during the
LOGUNDO phase of log apply, known as the pseudo compensation log
record in the following context. For each undo log record applied during
the LOGUNDO phase, there will be one pseudo compensation log record
written for it. This is a REDO-only log record and not units of recovery
(UR) related. It will only be used for future log apply in the case that you
first recover objects to a point in time with consistency and then recover
the same objects again to currency using the same image copy used by
previous recover job.
This type of log record will be skipped by Db2 restart and the RESTORE
SYSTEM utility LOGAPPLY. This type of log record will always be written
to the active log data sets of the Db2 member that is running the
RECOVER job, although it may compensate the log record which was
originally from another Db2 member. The member ID part of this log
record will always store the ID of the Db2 member that is running the
RECOVER job.
During the LOGUNDO phase, if either of the following conditions exist:
v Applying the log record to a data page causes the data on the page
logically inconsistent.
v The UNDO log record has already been applied and the page is now
physically inconsistent.
The page is flagged as broken and the pseudo compensation log record of
the log record that is being backed out is written to the active log data set.
All of the subsequent log apply processes on this data page are skipped,
but the pseudo compensation log records of the skipped log records are
written to the active log data set. The log apply process continues for other
pages in the same table space and for other objects in the recover list. For
each error that is encountered, a DSNI012I message is issued. At the end,
the RECOVER utility completes with return code 8.

Chapter 12. Backing up and recovering your data 469

 If an error occurs on the index during the LOGUNDO phase, the entire
index is marked as REBUILD-pending (RBDP) and no further log is
applied on this index. You have to rebuild this index after the RECOVER
utility completes with return code 8.
UTILTERM phase
The RECOVER utility enters the UTILTERM phase, which is an existing
phase of the RECOVER utility.

The RECOVER TOLOGPOINT option in a non-data sharing system:

You can use the RECOVER utility with the TOLOGPOINT option to recover a
non-data sharing Db2 subsystem.

Figure 47 shows a non-data sharing system. Table spaces TS1 and TS2 are being
recovered to time TR using the RECOVER TORBA option. TS1 and TS2 are listed
in the same RECOVER job. UR1 was inflight at TR time, the start time was T1, at
time T2 it updated TS1, and at time T3 it updated TS2. T2 is earlier than T3. UR2
was aborting at TR time, the start time was T4, and at time T5 it updated TS2.

Figure 47. Using the RECOVER TOLOGPOINT option in a non-data sharing system

RECOVER utility job output messages

The RECOVER utility takes the following actions and provides the following
messages during recovery in a non-data sharing system.
LOGCSR phase
After the LOGAPPLY phase, the RECOVER utility enters the log analysis
phase, known as the LOGCSR phase. The following messages are issued
during this phase:
DSNU1550I
Indicates the start of log analysis.
DSNU1551I
Indicates the end of log analysis.
DSNU1552I
Indicates the end of the LOGCSR phase of the RECOVER utility.

470 Administration Guide

DSNU1553I
Issued after the end of the LOGCSR phase. The following
information is shown in the message:
v UR1 modified TS1 at T2 time.
v UR1 modified TS2 at T3 time.
v UR2 modified TS2 at T5 time.
LOGUNDO phase
The RECOVER utility enters the LOGUNDO phase. The following
messages are issued during this phase:
DSNU1554I
Indicates the start of backout.
v Backout is performed on TS2 and TS1 and log records
are read from time TR to T2.
v There may be one or more DSNU1555I messages
showing the backout progress.
DSNU1556I
Indicates the end of backout.
DSNU1557I
Indicates the end of LOGUNDO phase of the RECOVER
utility.
A special type of compensation log record will be written during
the LOGUNDO phase of log apply, known as the pseudo
compensation log record in the following context. For each undo
log record applied during the LOGUNDO phase, there will be one
pseudo compensation log record written for it. This is a
REDO-only log record and not units of recovery (UR) related. It
will only be used for future log apply in the case that you first
recover objects to a point in time with consistency and then recover
the same objects again to currency using the same image copy
used by previous recover job.
This type of log record will be skipped by Db2 restart and the
RESTORE SYSTEM utility LOGAPPLY. This type of log record will
always be written to the active log datasets of the Db2 member
that is running the RECOVER job, although it may compensate the
log record which was originally from another Db2 member. The
member ID part of this log record will always store the ID of the
Db2 member that is running the RECOVER job.
During the LOGUNDO phase, if either of the following conditions
exist:
v Applying the log record to a data page causes the data on the
page logically inconsistent.
v The UNDO log record has already been applied and the page is
now physically inconsistent.
The page is flagged as broken and the pseudo compensation log
record of the log record that is being backed out is written to the
active log dataset. All of the subsequent log apply processes on this
data page are skipped, but the pseudo compensation log records of
the skipped log records are written to the active log dataset. The
log apply process continues for other pages in the same table space
and for other objects in the recover list. For each error that is

Chapter 12. Backing up and recovering your data 471

 encountered, a DSNI012I message is issued. At the end, the
RECOVER utility completes with return code 8.
If an error occurs on the index during the LOGUNDO phase, the
entire index is marked as REBUILD-pending (RBDP) and no
further log is applied on this index. You have to rebuild this index
after the RECOVER utility completes with return code 8.
UTILTERM phase
The RECOVER utility enters the UTILTERM phase, which is an
existing phase of the RECOVER utility.

Recommendations for recovery of compressed data

Use care when recovering a single data set of a non-partitioned page set to a prior
point in time. If the data set that is recovered was compressed with a different
dictionary from the rest of the page set, you can no longer read the data.

| Recovering to a point in time before pending definition changes

| were materialized
| You can recover a partition-by-range table space, a LOB table space, or an XML
| table space to a point in time before you materialized pending definition changes.

| Procedure

| To recover a table space to a point in time that is before materialization of pending

| definition changes:
| 1. Run the RECOVER utility to recover the data to the point in time that you
| want.
| If you specify the TOCOPY, TOLASTCOPY, or TOLASTFULLCOPY option, you
| need to use an image copy that was taken with the SHRLEVEL REFERENCE
| option. If no appropriate image copies are available, you can run RECOVER
| with the TOLOGPOINT or TORBA option.
| For most types of pending definition changes, the table space is placed in
| REORG-pending (REORP) status after the RECOVER utility runs. Changes to
| partition limit keys are exceptions that require no subsequent REORG.

| Restrictions: After you complete this step, and before you complete the next
| step, you cannot perform any of the following actions:
| v Execute any of the following statements on the table space, on any objects in
| the table space, on indexes that are related to tables in the table space, or on
| auxiliary objects that are associated with the table space:
| – CREATE TABLE
| – CREATE AUXILIARY TABLE
| – CREATE INDEX
| – ALTER TABLE
| – ALTER INDEX
| – RENAME
| – DROP TABLE
| v Execute SQL statements that result in pending definition changes on any of
| the following objects:
| – The table space
| – Tables in the table space
| – Auxiliary table spaces that are related to the table space
| – Indexes on tables in the table space
| v Run any utilities that are not in this list:

472 Administration Guide

| – RECOVER to the same point in time
| – REORG
| – REPAIR DBD
| – REPORT RECOVERY
| 2. If the table space is in REORG-pending (REORP) status, run the REORG
| TABLESPACE utility with SHRLEVEL REFERENCE on the entire table space to
| complete the point-in-time recovery process.
| If there are pending definition changes on a base table space and on the LOB
| table space for a LOB column in the base table space, run REORG on the LOB
| table space first, and then run REORG on the base table space.

| Example

| The following example provides a scenario that shows how you can recover a table
| space to a point in time before pending definition changes were materialized, and
| then use the REORG TABLESPACE utility with SHRLEVEL REFERENCE to
| complete recovery.

|
|
| 1. In DB2 10 new-function mode or later, you execute the following ALTER
| TABLESPACE statement to change the buffer pool page size. This change is a
| pending definition change.
| ALTER TABLESPACE DB1.TS1 BUFFERPOOL BP8K0 MAXPARTITIONS 20 ;
| 2. In Db2 11 new-function mode or later, you run REORG to materialize the
| pending definition change.
| 3. You run the following RECOVER control statement to recover the table space to
| point in time 2012-10-09-07.15.22.216020.
| RECOVER TABLESPACE DB1.TS1
| TOLOGPOINT X’00000551BE7D’
| When this statement runs, the table space is placed in REORG-pending
| (REORP) state, and an entry is inserted into the SYSPENDINGDDL table with
| OBJTYPE = 'S', for table space.
| 4. You run the following SELECT statement to query the
| SYSIBM.SYSPENDINGDDL catalog table:
| SELECT DBNAME, TSNAME, OBJSCHEMA, OBJNAME, OBJTYPE, OPTION_SEQNO,
| OPTION_KEYWORD, OPTION_VALUE, CREATEDTS
| FROM SYSIBM.SYSPENDINGDDL
| WHERE DBNAME = ’DB1’
| AND TSNAME = ’TS1’
| ;
| This query results in the following output:
| Table 44. Output from the SELECT statement for the SYSPENDINGDDL catalog table after
| RECOVER to a point in time before materialization of pending definition changes
| DBNAME TSNAME OBJSCHEMA OBJNAME OBJTYPE
| DB1 TS1 DB1 TS1 S
|

Chapter 12. Backing up and recovering your data 473

| Table 45. Continuation of output from the SELECT statement for the SYSPENDINGDDL
| catalog table after RECOVER to a point in time before materialization of pending definition
| changes
| OPTION_SEQNO OPTION_KEYWORD OPTION_VALUE CREATEDTS
| 1 TOLOGPOINT 00000551BE7D 2012-10-04-
| 07.14.20.204010
|
|
|
| 5. Now, you run the REORG TABLESPACE utility with SHRLEVEL REFERENCE
| on the entire table space. For example:
| REORG TABLESPACE DB1.TS1 SHRLEVEL REFERENCE

| The REORG utility completes point-in-time recovery. After the REORG utility
| runs, the REORG-pending (REORP) state is cleared, and all entries in the
| SYSPENDINGDDL table for the table space are removed.
| Related reference:
| RECOVER (Db2 Utilities)
| REORG TABLESPACE (Db2 Utilities)
| SYSPENDINGDDL catalog table (Db2 SQL)

Implications of moving data sets after a system-level backup

If you operate on z/OS Version 1 Release 10 or earlier, the movement of data sets
after the creation of a system-level backup can affect the ability to do recovery to a
prior point in time.

Note: For z/OS Version 1 Release 11 and later, to recover data sets from a
system-level backup, the data sets do not need to reside on the same volume as
they were on when the backup was made. The RECOVER utility has been
modified so that you can use system-level backups, even if a data set has moved
since the backup was created.

You can still recover the objects if you have an object-level backup such as an
image copy or concurrent copy. Take object-level backups to augment system-level
backups, or take new system-level backups whenever a data set is moved.

You can force the RECOVER utility to ignore system-level backups and use the
latest applicable object-level backup by setting the SYSTEM-LEVEL-BACKUPS
parameter on installation panel DSNTIP6 to NO. This subsystem parameter can be
updated online.

Activities that can affect the ability to recover an object to a prior point in time
from a system-level backup include:
v Migrating to new disk storage or redistributing data sets for performance
reasons
The movement of data sets for disk management should be restricted or limited
when system-level backups are taken. When movement of data sets does occur,
a new system-level backup or object-level backup should immediately be taken.
v Using the DFSMShsm migrate and recall feature
Do not use the DFSMShsm migrate and recall feature if you take system-level
backups.

474 Administration Guide

 v Using REORG TABLESPACE or LOAD REPLACE
To minimize the impact of REORG TABLESPACE and LOAD REPLACE on
recoverability, you should always take an inline copy of the underlying table
space. You can then use this copy to recover at the object level.
v Using REORG INDEX or REBUILD INDEX
If a REORG INDEX or REBUILD INDEX is preventing the use of the
system-level backup during recovery of an index, you can use the REBUILD
INDEX utility to rebuild rather than recover the index.
v Using RECOVER from an image copy or concurrent copy

If you operate on z/OS Version 1 Release 10 or earlier, these activities prevent the
recovery at the object level to a point in time that would use the system-level
backup. This restriction happens because the current volume allocation information
in the ICF catalog for the data set (or data sets) differs from the volume allocation
at the time of the system-level backup.

Consider the following restrictions when planning your backup strategy:

v Data sets can move within a single volume, for example because the volume has
been defragmented. In this case, the ability to restore the data is not affected.
Recovery of data is not affected if the data set is extended to another volume
after it has been copied.
In the case where the data set originally spanned multiple volumes, the data set
would need to be reallocated with extents on each of the same volumes before it
could be recovered successfully. The amount of space for the data set extents at
the time of the backup can differ from the amount of space that is available at
recovery time.
v The RECOVER utility cannot use the copy pool backup as the source for a
recovery if the data set has been moved to different volumes, if you operate on
z/OS Version 1 Release 10 or earlier.
v The movement of one data set in a system-level backup does not prevent the
object-level recovery of other objects from the backup.
v The movement of data sets does not prevent the use of the RESTORE SYSTEM
utility.

Recovery of table spaces

The way that you recover Db2 table spaces depends on several factors, including
the type of table space that needs recovery.

When you recover table spaces to a prior point of consistency, you need to
consider:
v How partitioned table spaces, segmented table spaces, LOB table spaces, XML
table spaces, and table space sets can restrict recovery.
v If you take system-level backups, how certain utility events can prohibit
recovery to a prior point in time.
Related reference:
Implications of moving data sets after a system-level backup

Recovery of partitioned table spaces

Recovering partitioned table spaces to a point in time has several limitations.

Chapter 12. Backing up and recovering your data 475

 You cannot recover a table space to a point in time that is prior to rotating
partitions. After you rotate a partition, you cannot recover the contents of that
partition.

If you recover to a point in time that is prior to the addition of a partition, Db2
cannot roll back the definition of the partition. In such a recovery, Db2 clears all
data from the partition, and the partition remains part of the database.

If you recover a table space partition to a point in time that is before the data was
redistributed across table space partitions, you must include all partitions that are
affected by that redistribution in your recovery list.

See the information about point-in-time recovery for more details on these
restrictions.
Related concepts:
Point-in-time recovery (Db2 Utilities)

Recovery of segmented table spaces

You can restore data on a segmented table space to a prior point in time. When
you do this, information in the database descriptor (DBD) for the table space might
not match the restored table space.

If you use the Db2 RECOVER utility, the DBD is updated dynamically to match
the restored table space on the next non-index access of the table. The table space
must be in write access mode.

If you use a method outside of Db2 control, such as DSN1COPY to restore a table
space to a prior point in time, run the REPAIR utility with the LEVELID option to
force Db2 to accept the down-level data. Then, run the REORG utility on the table
space to correct the DBD.

Recovery of LOB table spaces

When you recover tables with LOB columns, recover the entire set of objects. The
entire set of objects includes the base table space, the LOB table spaces, and index
spaces for the auxiliary indexes.

If you use the RECOVER utility to recover a LOB table space to a prior point of
consistency, the RECOVER utility might place the table space in a pending state.
Related concepts:
Options for restoring data to a prior point in time

Recovery of XML table spaces

At times, recovering database objects to a prior point in time is necessary. When
this type of recovery is needed, all related objects (including XML objects) must be
recovered to a consistent point in time.

The RECOVER utility performs consistency checking of the recovery points of

these related objects during point-in-time recoveries. Use the REPORT utility with
the TABLESPACESET keyword to obtain a list of these related objects. Use the
QUIESCE utility with the TABLESPACESET keyword if you need to quiesce all
objects in the related set.

Recovery of table space sets

If you restore a page set to a prior state, restore all related tables and indexes to
the same point to avoid inconsistencies.

476 Administration Guide

 A group of related table spaces is called a table space set. Specifically, a table space
set includes the following groups of table spaces:
v Table spaces that contain referentially related tables
v A base table space and its LOB table spaces
v A base table space and its XML table spaces
v A table space with a system-period temporal table and the table space with the
related history table
| v A table space with an archive-enabled table and the table space with the related
| archive table

For example, in the Db2 sample application, a column in the EMPLOYEE table
identifies the department to which each employee belongs. The departments are
described by records in the DEPARTMENT table, which is in a different table
space. If only that table space is restored to a prior state, a row in the unrestored
EMPLOYEE table might identify a department that does not exist in the restored
DEPARTMENT table.

Run the CHECK INDEX utility to validate the consistency of indexes with their
associated table data. Run the CHECK DATA utility to validate the consistency of
base table space data with related table spaces. If LOB columns exist, run the
CHECK LOB utility on any related LOB table spaces to validate the integrity of
each LOB table space within itself.

You can use the REPORT utility with the TABLESPACESET option to determine all
of the page sets that belong to a single table space set. Then, you can restore those
page sets that are related. However, if page sets are logically related outside of Db2
in application programs, you are responsible for identifying all of those page sets
on your own.

To determine a valid quiesce point for a table space set, determine a RECOVER
TOLOGPOINT value.
Related concepts:
Creation of relationships with referential constraints (Introduction to Db2 for
z/OS)
LOB table spaces
XML table spaces
Temporal tables and data versioning
Archive-enabled tables and archive tables (Introduction to Db2 for z/OS)
Related reference:
CHECK DATA (Db2 Utilities)
CHECK INDEX (Db2 Utilities)
CHECK LOB (Db2 Utilities)
RECOVER (Db2 Utilities)
REPORT (Db2 Utilities)

Recovery of partition-by-growth table spaces

The RECOVER utility supports both table space-level and partition-level recovery
on a partition-by-growth table space.

Chapter 12. Backing up and recovering your data 477

 If an image copy was made on the partition level, the table space can only be
recovered at the partition level. A violation of this rule causes message DSNU512I
to be issued.

Because the number of partitions is defined on demand, the total number of

partitions in an image copy may not be consistent with the number of partitions
that reside in the current table space. In such a case, when recovering the table
space back to a point in time with an image copy that has less partitions, the
excess partitions in the table space will be empty because the recover process has
reset the partitions.

Recovery of indexes
When you recover indexes to a prior point of consistency, some rules apply.

In general, the following rules apply:

v If image copies exists for an indexes, use the RECOVER utility.
v If you take system-level backups, use the RECOVER utility. (This use requires
z/OS Version 1.8.)
v If indexes do not have image copies or system-level backups, use REBUILD
INDEX to re-create the indexes after the data has been recovered.

More specifically, you must consider how indexes on altered tables and indexes on
tables in partitioned table spaces can restrict recovery.

Before attempting recovery, analyze the recovery information.

Related concepts:
How to report recovery information
Related reference:
Implications of moving data sets after a system-level backup

Recovery of indexes on altered tables

Using some ALTER statements interferes with the use of the RECOVER utility to
restore the index to a point in time before the ALTER statement was used.

You cannot use the RECOVER utility to recover an index to a point in time that
existed before you issued any of the following ALTER statements on that index.
These statements place the index in REBUILD-pending (RBDP) status:
v ALTER INDEX PADDED
v ALTER INDEX NOT PADDED
v ALTER TABLE SET DATA TYPE on an indexed column for numeric data type
changes
v ALTER TABLE ADD COLUMN and ALTER INDEX ADD COLUMN that are not
issued in the same commit scope
v ALTER INDEX REGENERATE

When you recover a table space to prior point in time and the table space uses
indexes that were set to RBDP at any time after the point of recovery, you must
use the REBUILD INDEX utility to rebuild these indexes.

478 Administration Guide

 Related reference:
REBUILD INDEX (Db2 Utilities)
RECOVER (Db2 Utilities)

Recovery of indexes on tables in partitioned table spaces

The partitioning of secondary indexes allows you to copy and recover indexes at
the entire index level or individual partition level. Certain restrictions apply to
using the COPY and RECOVER utilities on the index level and partition level.

If you use the COPY utility at the partition level, you need to use the RECOVER
utility at the partition level, too. If you use the COPY utility at the partition level
and then try to the RECOVER utility the index, an error occurs. If the COPY utility
is used at the index level, you can use the RECOVER utility at either the index
level or the partition level.

You cannot recover an index space to a point in time that is prior to rotating
partitions. After you rotate a partition, you cannot recover the contents of that
partition to a point in time that is before the rotation.

If you recover to a point in time that is prior to the addition of a partition, Db2
cannot roll back the addition of that partition. In such a recovery, Db2 clears all
data from the partition, and it remains part of the database.

Recovery of FlashCopy image copies

Using FlashCopy image copies can reduce the amount of time that is required for
recovery operations.

To provide a recovery base for media failures, create one or more additional
sequential format image copies when you create a FlashCopy image copy. If the
FlashCopy image copy has been migrated or deleted, the recovery proceeds from
the sequential image copies if available. The following utilities can create
additional sequential format image copies in a single execution:
v COPY
v LOAD with the REPLACE option specified
v REORG TABLESPACE

You can recover an object to a specific FlashCopy image copy by specifying the
RECOVER utility with the TOCOPY, TOLASTCOPY, or TOLASTFULLCOPY
options. If the object is partitioned, you must specify the data set number on the
DSNUM parameter in the RECOVERY utility control statement for each partition
that is being recovered.

A FlashCopy image copy with consistency consumes more processing resources

when the image copy is created, and when the image copy is used for recovery. To
recover from a FlashCopy image copy with consistency, the RECOVER utility must
read the logs to apply changes that were made to the recovered object after the
point of consistency. Some of the changes could be work that was previously
backed out and that must be reapplied, because the work was uncommitted when
the FlashCopy image copy was created.

For recovery to a log point or full recovery, if uncommitted work was backed out
from the FlashCopy image copy during consistency processing, recovery requires

Chapter 12. Backing up and recovering your data 479

 more analysis of the logs during the preliminary LOGCSR phase (PRELOGC). The
preliminary log apply phase (PRELOGA) and the other log phases also require
more analysis.
Related concepts:
FlashCopy image copies (Db2 Utilities)
Related tasks:
Creating FlashCopy image copies

Preparing to recover to a prior point of consistency

Db2 begins recovery with the image copy or system-level backup that you made
and reads the log only up to the point of consistency. At that point, no indoubt
units of recovery hinder restarting Db2.

About this task

Related reference:
Implications of moving data sets after a system-level backup

Identifying objects to recover

You must recover dependent objects to the same point in time. Dependent objects
include table spaces that are part of a table space set.

Procedure

To identify the objects that must be recovered to the same point in time:

Run the REPORT utility with the TABLESPACESET option.

Related concepts:
Recovery of table space sets
Creation of relationships with referential constraints (Introduction to Db2 for
z/OS)
LOB table spaces
XML table spaces
Archive-enabled tables and archive tables (Introduction to Db2 for z/OS)
Related reference:
Syntax and options of the REPORT control statement (Db2 Utilities)

Resetting exception status

You need to determine whether the data is in an exception status, and then you
can release the data from any exception status.

Procedure

To determine whether the data is in an exception status:

Issue the DISPLAY DATABASE RESTRICT command.

Copying the data

You can use the COPY utility to copy the data, taking appropriate precautions
about concurrent activity.

480 Administration Guide

About this task

In one operation, you can copy the data and establish a point of consistency for a
list of objects by using the COPY utility with the option SHRLEVEL REFERENCE.
That operation allows only read access to the data while it is copied. The data is
consistent at the time when copying starts and remains consistent until copying
ends. The advantage of this operation is that the data can be restarted at a point of
consistency by restoring the copy only, with no need to read log records. The
disadvantage is that updates cannot be made while the data is being copied.

You can use the CONCURRENT option of the COPY utility to make a backup,
with DFSMSdss concurrent copy, that is recorded in the Db2 catalog.

Ideally, you should copy data without allowing updates. However, restricting
updates is not always possible. To allow updates while the data is being copied,
you can take either of the following actions:
v Use the COPY utility with the SHRLEVEL CHANGE option.
v Use an offline program to copy the data, such as DSN1COPY, DFSMShsm, or
disk dump.

If you allow updates while copying, step 3 is recommended. With concurrent

updates, the copy can include uncommitted changes. Those might be backed out
after copying ends. Thus, the copy does not necessarily contain consistent data,
and recovery cannot rely on the copy only. Recovery requires reading the log up to
a point of consistency, so you want to establish such a point as soon as possible.
Although RECOVER can recover your data to any point in time and ensure data
consistency, recovering to a quiesce point can be more efficient. Therefore, taking
periodic quiesce points is recommended, if possible.

You can copy all of the data in your system, including the Db2 catalog and
directory data by using the BACKUP SYSTEM utility. Since the BACKUP SYSTEM
utility allows updates to the data, the system-level backup can include
uncommitted data.
Related reference:
COPY (Db2 Utilities)

Establishing a point of consistency

After copying the data, immediately establish a point when the data is consistent
and no unit of work is changing it.

Procedure

To establish a single point of consistency, or a quiesce point, for one or more page
sets:

Run the QUIESCE utility.

Typically, you name all of the table spaces in a table space set that you want
recovered to the same point in time to avoid referential integrity violations.
Alternatively, you can use the QUIESCE utility with the TABLESPACESET
keyword for referential integrity-related tables.
The QUIESCE utility writes changed pages from the page set to disk. The
SYSIBM.SYSCOPY catalog table records the current RBA and the timestamp of the
quiesce point. At that point, neither page set contains any uncommitted data. A
row with ICTYPE Q is inserted into SYSCOPY for each table space that is quiesced.
Page sets DSNDB06.SYSTSCPY, DSNDB01.DBD01, DSNDB01.SYSUTILX, and

Chapter 12. Backing up and recovering your data 481

 DSNDB01.SYSDBDXA are an exception. Their information is written to the log.
Indexes are quiesced automatically when you specify WRITE(YES) on the
QUIESCE statement. A SYSIBM.SYSCOPY row with ICTYPE Q is inserted for
indexes that have the COPY YES attribute.
The QUIESCE utility allows concurrency with many other utilities; however, it
does not allow concurrent updates until it has quiesced all specified page sets and
depending on the amount of activity, that can take considerable time. Try to run
the QUIESCE utility when system activity is low.
Also, consider using the MODE(QUIESCE) option of the ARCHIVE LOG command
when planning for off-site recovery. It creates a system-wide point of consistency,
which can minimize the number of data inconsistencies when the archive log is
used with the most current image copy during recovery.

Example

The following statement quiesces two table spaces in database DSN8D11A:

QUIESCE TABLESPACE DSN8D11A.DSN8S11E
TABLESPACE DSN8D11A.DSN8S11D
Related tasks:
Archiving the log
Related reference:
QUIESCE (Db2 Utilities)

Preparing to recover an entire Db2 subsystem to a prior point in time

using image copies or object-level backups
Under certain circumstances, you might want to reset the entire Db2 subsystem to
a point of consistency.

Procedure

To prepare a point of consistency:

1. Display and resolve any indoubt units of recovery.
2. Use the COPY utility to make image copies of all the following types of data:
v User data
v Db2 catalog and directory table spaces, and optionally indexes
| v If you are using Db2 query acceleration with IBM Db2 Analytics Accelerator
| for z/OS, the table spaces and index spaces for the Db2 SYSACCEL tables
| and indexes
Copy SYSLGRNX and SYSCOPY last. Installation job DSNTIJIC creates image
copies of the Db2 catalog and directory table spaces. If you decide to copy your
directory and catalog indexes, modify job DSNTIJIC to include those indexes.

Alternate method: Alternatively, you can use an off-line method to copy the
data. In that case, stop Db2 first; that is, do the next step before doing this step.
If you do not stop Db2 before copying, you might have trouble restarting after
restoring the system. If you do a volume restore, verify that the restored data is
cataloged in the integrated catalog facility catalog. Use the access method
services LISTCAT command to get a listing of the integrated catalog.
3. Stop Db2 with the command STOP DB2 MODE (QUIESCE).

482 Administration Guide

 Important: Be sure to use MODE (QUIESCE); otherwise, I/O errors can occur
when you fall back before a Db2 restart.
Db2 does not actually stop until all currently executing programs have
completed processing.
4. When Db2 has stopped, use access method services EXPORT to copy all BSDS
and active log data sets. If you have dual BSDSs or dual active log data sets,
export both copies of the BSDS and the logs.
5. Save all the data that has been copied or dumped, and protect it and the
archive log data sets from damage.
Related tasks:
Installation step 21: Back up the Db2 directory and catalog: DSNTIJIC (Db2
Installation and Migration)

Creating essential disaster recovery elements

You must take steps to create essential disaster recovery elements. For example,
you must determine how often to make copies and send them to the recovery site.

Procedure
To create essential disaster recovery elements:
1. Make image copies:
a. Make copies of your data sets and Db2 catalogs and directories.
Use the COPY utility to make copies for the local subsystem and additional
copies for disaster recovery. You can also use the COPYTOCOPY utility to
make additional image copies from the primary image copy made by the
COPY utility. Install your local subsystem with the LOCALSITE option of
the SITE TYPE field on installation panel DSNTIPO. Use the
RECOVERYDDN option when you run COPY to make additional copies for
disaster recovery. You can use those copies on any Db2 subsystem that you
have installed using the RECOVERYSITE option.

Tip: You can also use these copies on a subsystem that is installed with the
LOCALSITE option if you run RECOVER with the RECOVERYSITE option.
Alternatively, you can use copies that are prepared for the local site on a
recovery site if you run RECOVER with the option LOCALSITE.

Important: Do not produce copies by invoking COPY twice.

b. Optional: Catalog the image copies if you want to track them.
c. Create a QMF report or use SPUFI to issue a SELECT statement to list the
contents of SYSCOPY.
d. Send the image copies, and report to the recovery site.
e. Record this activity at the recovery site when the image copies and the
report are received.
All table spaces should have valid image copies. Indexes can have valid
image copies or they can be rebuilt from the table spaces.
2. Make copies of the archive logs for the recovery site:
a. Use the ARCHIVE LOG command to archive all current Db2 active log data
sets.

Chapter 12. Backing up and recovering your data 483

 Recommendation: When using dual logging, keep both copies of the
archive log at the local site in case the first copy becomes unreadable. If the
first copy is unreadable, Db2 requests the second copy. If the second copy is
not available, the read fails.

However, if you take precautions when using dual logging, such as making
another copy of the first archive log, you can send the second copy to the
recovery site. If recovery is necessary at the recovery site, specify YES for
the READ COPY2 ARCHIVE field on installation panel DSNTIPO. Using
this option causes Db2 to request the second archive log first.
b. Optional: Catalog the archive logs if you want to track them.
You will probably need some way to track the volume serial numbers and
data set names. One way of doing this is to catalog the archive logs to
create a record of the necessary information. You can also create your own
tracking method and do it manually.
c. Use the print log map utility to create a BSDS report.
d. Send the archive copy, the BSDS report, and any additional information
about the archive log to the recovery site.
e. Record this activity at the recovery site when the archive copy and the
report are received.
3. Choose consistent system time:

Important: After you establish a consistent system time, do not alter the
system clock. Any manual change in the system time (forward or backward)
can affect how Db2 writes and processes image copies and log records.
a. Choose a consistent system time for all Db2 subsystems.
Db2 utilities, including the RECOVER utility, require system clocks that are
consistent across all members of a Db2 data-sharing group. To prevent
inconsistencies during data recovery, ensure that all system times are
consistent with the system time at the failing site.
b. Ensure that the system clock remains consistent.
4. Back up integrated catalog facility catalogs:
a. Back up all Db2-related integrated catalog facility catalogs with the VSAM
EXPORT command on a daily basis.
b. Synchronize the backups with the cataloging of image copies and archives.
c. Use the VSAM LISTCAT command to create a list of the Db2 entries.
d. Send the EXPORT backup and list to the recovery site.
e. Record this activity at the recovery site when the EXPORT backup and list
are received.
5. Back up Db2 libraries:
a. Back up Db2 libraries to tape when they are changed. Include the SMP/E,
load, distribution, and target libraries, as well as the most recent user
applications and DBRMs.
b. Back up the DSNTIJUZ job that builds the ZPARM and DECP modules.
c. Back up the data set allocations for the BSDS, logs, directory, and catalogs.
d. Document your backups.
e. Send backups and corresponding documentation to the recovery site.
f. Record activity at the recovery site when the library backup and
documentation are received.

484 Administration Guide

 What to do next

For disaster recovery to be successful, all copies and reports must be updated and
sent to the recovery site regularly. Data is up to date through the last archive that
is sent.
Related concepts:
Multiple image copies (Db2 Utilities)
Related tasks:
Archiving the log
Related information:
Performing remote-site disaster recovery

Resolving problems with a user-defined work file data set

You can resolve problems on a volume of a user-defined data set for the work file
database.

Procedure

To resolve problems:
1. Issue the following Db2 command:
-STOP DATABASE (DSNDB07)

Note: If you are adding or deleting work files, you do not need to stop
database DSNDB07.
2. Use the DELETE and DEFINE functions of access method services to redefine a
user work file on a different volume, and reconnect it to Db2.
3. Issue the following Db2 command:
-START DATABASE (DSNDB07)

Resolving problems with Db2-managed work file data sets

You can resolve problems on a volume in a Db2 storage group for the work file
database, such as a system I/O problem.

Procedure

To resolve problems with the work file database:

1. Issue the following SQL statement to remove the problem volume from the Db2
storage group:
ALTER STOGROUP stogroup-name
REMOVE VOLUMES (xxxxxx);
2. Issue the following Db2 command to stop the database:
-STOP DATABASE (DSNDB07)

Note: If you are adding or deleting work files, you do not need to stop
database DSNDB07.
3. Issue the following SQL statement to drop the table space that has the problem:
DROP TABLESPACE DSNDB07.tsname:
4. Re-create the table space. You can use the same storage group, because the
problem volume has been removed, or you can use an alternate volume.

Chapter 12. Backing up and recovering your data 485

 CREATE TABLESPACE tsname
IN DSNDB07
USING STOGROUP stogroup-name;
5. Issue the following command to restart the database:
-START DATABASE (DSNDB07)

Recovering error ranges for a work file table space

Page error ranges operate for work file table spaces in the same way as for other
Db2 table spaces, except for the process that you use to recover them. You cannot
reset error ranges in a work file table space by using the ERROR RANGE option of
the RECOVER utility.

Procedure

To recover error ranges for a work file table space:

1. Stop the work file table space.
2. Correct the disk error, using the ICKDSF service utility or access method
services to delete and redefine the data set.
3. Start the work file table space. When the work file table space is started, Db2
automatically resets the error range.

Recovery of error ranges for a work file table space

Db2 always resets any error ranges when the work file table space is initialized,
regardless of whether the disk error has really been corrected.

Work file table spaces are initialized when:

v The work file table space is stopped and then started.
v The work file database is stopped and then started, and the work file table space
was not previously stopped.
v Db2 is started and the work file table space was not previously stopped.

If the error range is reset while the disk error still exists, and if Db2 has an I/O
error when using the work file table space again, Db2 sets the error range again.

Recovering after a conditional restart of Db2

After a Db2 conditional restart in which a log record range is specified, a portion
of the Db2 recovery log is no longer available.

About this task

| If the unavailable portion includes information that is needed for internal Db2
| processing, an attempt to use the RECOVER utility to restore directory table spaces
| DSNDBD01 or SYSUTILX, or catalog table space SYSTSCPY fails with ABEND04E
| RC00E40119.

Procedure

Instead of using the RECOVER utility, use the following procedure to recover those
table spaces and their indexes:

486 Administration Guide

 1. Run DSN1COPY to restore the table spaces from an image copy.
2. Run the RECOVER utility with the LOGONLY option to apply updates from
the log records to the recovered table spaces.
3. Rebuild the indexes.
4. Make a full image copy of the table spaces, and optionally the indexes, to make
the table spaces and indexes recoverable.

Recovery of the catalog and directory

Catalog and directory objects must be recovered in a particular order.

The order differs, depending on whether you are in conversion mode,

enabling-new-function mode, or new-function mode. For some catalog and
directory objects the order differs, depending on whether objects were dropped or
deleted, and new objects created.

Sometimes the recovery of some catalog and directory objects depends on

information that is derived from other catalog and directory objects. You must
recover some of these objects in separate RECOVER utility control statements.

However, you can use the same RECOVER control statement to recover a catalog
or directory table space along with its corresponding IBM-defined indexes. After
these logically dependent objects are restored to an undamaged state, you can
recover the remaining catalog and directory objects in a single RECOVER utility
control statement. These restrictions apply regardless of the type of recovery that
you perform on the catalog.

You can use the REPORT utility to report on recovery information about the
catalog and directory.

To avoid restart processing of any page sets before attempts are made to recover
any of the members of the list of catalog and directory objects, you must set
subsystem parameters DEFER and ALL. You can do this by setting the values
DEFER in field 1 and ALL in field 2 of installation panel DSNTIPS.

Important: Recovering the Db2 catalog and directory to a prior point in time is
strongly discouraged.
Related concepts:
How to report recovery information
Copying catalog and directory objects (Db2 Utilities)
Related tasks:
Deferring restart processing
Recovering catalog and directory objects (Db2 Utilities)
Related reference:
RECOVER (Db2 Utilities)

Regenerating missing identity column values

You can regenerate missing identity column values.

Procedure

To regenerate missing identity column values:

Chapter 12. Backing up and recovering your data 487

 1. Choose a starting value for the identity column with the following
ALTER TABLE statement:
ALTER TABLE table-name
ALTER COLUMN identity-column-name
RESTART WITH starting-identity-value

2. Run the REORG utility to regenerate lost sequence values.

If you do not choose a starting value in step 1, the REORG utility generates a
sequence of identity column values that starts with the next value that Db2
would have assigned before the recovery.

Recovery of tables that contain identity columns

When you recover a table that contains an identity column, consider the point in
time to which you recover. Your recovery procedure can depend on whether that
identity column existed, or was not yet defined, at the point in time to which you
recover.

The following considerations apply for each of these two cases.

Identity column already defined

If you recover to a point in time at which the identity column existed, you might
create a gap in the sequence of identity column values. When you insert a row
after this recovery, Db2 produces an identity value for the row as if all previously
added rows still exist.

For example, assume that at time T1 an identity column that is incremented by 1

contains the identity column values 1 through 100. At T2, the same identity
column contains the values 1 through 1000. Now, assume that the table space is
recovered back to time T1. When you insert a row after the recovery, Db2
generates an identity value of 1001. This value leaves a gap from 101 to 1000 in the
values of the identity column.

To prevent a gap in identity column values, use the following ALTER TABLE
statement to modify the attributes of the identity column before you insert rows
after the recovery:
ALTER TABLE table-name
ALTER COLUMN identity-column-name
RESTART WITH next-identity-value

Tip: To determine the last value in an identity column, issue the MAX column
function for ascending sequences of identity column values, or the MIN column
function for descending sequences of identity column values. This method works
only if the identity column does not use CYCLE.

488 Administration Guide

 Identity column not yet defined

If you recover to a point in time at which the identity column was not yet defined,
that identity column remains part of the table. The resulting identity column no
longer contains values.

A table space that contains an identity column is set to REORG-pending (REORP)

status if you recover the table space to a point in time that is before the identity
column was defined. To access the recovered table, you need to remove this status.
Related concepts:
Data consistency for point-in-time recoveries

Recovering a table space and all of its indexes

You can recover a table space and all of its indexes (or a table space set and all
related indexes). Use a single RECOVER utility statement that specifies the
TOLOGPOINT option.

About this task

For the log point, you can identify a quiesce point or a common SHRLEVEL
REFERENCE copy point. This action avoids placing indexes in the
CHECK-pending or RECOVER-pending status. If the log point is not a common
quiesce point or SHRLEVEL REFERENCE copy point for all objects, use the
following procedure, which ensures that the table spaces and indexes are
synchronized and eliminates the need to run the CHECK INDEX utility.

With recovery to a point in time with consistency, which is the default recovery
type, you do not need to identify a quiesce point or a common SHRLEVEL
REFERENCE copy point. This recovery might be faster because inconsistencies do
not have to be resolved.

Procedure
To recover to a log point:
1. Use the RECOVER utility to recover table spaces to the log point.
2. Use concurrent REBUILD INDEX jobs to rebuild the indexes for each table
space.

Recovery implications for objects that are not logged

You can use the RECOVER utility on objects that have the NOT LOGGED
attribute. The NOT LOGGED attribute does not mean that the contents of an object
are not recoverable. However, the modifications to the object that is not logged are
not recoverable.

Objects that are not logged include the table space, the index, and the index space.
Recovery can be to any recoverable point. A recoverable point is established when:
v A table space is altered from logged to not logged.
v When an image copy is taken against an object that is not logged.
v An ALTER TABLE statement is issued with the ADD PARTITION clause, against
a table in a table space that has the NOT LOGGED attribute.
v Db2 adds a new partition in response to insertion of data into a
partition-by-growth table space.

Chapter 12. Backing up and recovering your data 489

 The TORBA or TOLOGPOINT keywords can also be used for a point-in-time
recovery on an object that is not logged, but the RBA or LRSN must correspond to
a recoverable point or message DSNU1504I is issued.

If a base table space is altered so that it is not logged, and its associated LOB table
spaces already have the NOT LOGGED attribute, then the point where the table
space is altered is not a recoverable point.

If Db2 restart recovery determines that a table space that is not logged might have
been in the process of being updated at the time of the failure, then the table space
or partition is placed in the LPL and is marked RECOVER-pending.
Related concepts:
The NOT LOGGED attribute
Related reference:
ALTER TABLE (Db2 SQL)

Clearing the informational COPY-pending status (ICOPY)

If you update a table space that is defined with the NOT LOGGED attribute, the
table space is put in informational COPY-pending status (ICOPY).

Procedure

To clear the ICOPY status:

1. First, use the DISPLAY DATABASE ADVISORY command to display the ICOPY
status for table spaces. For example:
DSNT36I1 - * DISPLAY DATABASE SUMMARY
* ADVISORY
DSNT360I - *************************************
DSNT362I - DATABASE = DBIQUA01 STATUS = RW
DBD LENGTH = 8066
DSNT397I -
NAME TYPE PART STATUS HYERRLO PHYERRHI CATALOG PIECE
-------- ---- ---- ------------ ------- -------- ------- -----
TPIQUQ01 TS 001 RW,AUXW
TPIQUQ01 TS 002 RW,AUXW
TPIQUQ01 TS 003 RW,AUXW
TPIQUQ01 TS 004 RW,ICOPY
2. To clear the ICOPY status, you must take a full image copy of the table space.

The LOG option of the LOAD or REORG utilities

The LOG option that you specify when you run the LOAD and REORG utilities
has different results depending on the logging attribute of the table space that is
being logged.

The following tables show how the logging attribute of the utility and the logging
attribute of the table space interact:

490 Administration Guide

Table 46. Attribute interaction for LOB table spaces
LOAD or REORG Table space logging Table space status
keyword attribute What is logged after completion
LOG YES LOGGED Control records and No pending status
LOB data redo
information. LOB
data undo
information is never
logged for LOB table
spaces.
LOG YES NOT LOGGED Control information. No pending status
LOG NO LOGGED Nothing. COPY-pending
LOG NO NOT LOGGED Nothing. No pending status

Table 47. Attribute interaction for non-LOB table spaces

LOAD or REORG Table space logging Table space status
keyword attribute What is logged after completion
LOG YES LOGGED Control records and No pending status
data.
LOG YES NOT LOGGED LOG YES is changed See Table 48
to LOG NO.
LOG NO LOGGED Nothing. COPY-pending
LOG NO NOT LOGGED Nothing. See Table 48

The following table shows the possible table space statuses for non-LOB tables
spaces that are not logged:
Table 48. Status of non-LOB table spaces that are not logged, after LOAD or REORG with
LOG NO keyword
Inline copy Records discarded Table space status
Yes No No pending status
Yes Yes ICOPY-pending
No not applicable ICOPY-pending

Clearing the RECOVER-pending status

If Db2 needs to undo work that has not been logged (as when a rollback occurs),
the table space has lost its data integrity and is marked RECOVER-pending. To
prevent access to corrupt data, Db2 places the pages in the logical page list (LPL).

About this task

Tip: Application programmers should commit frequently and try to avoid

duplicate key or referential integrity violations when modifying a table in a NOT
LOGGED table space.

If Db2 restart recovery determines that a not logged table space may have been in
the process of being updated at the time of the failure, then the table space or
partition is placed in the LPL and is marked RECOVER-pending. You have several
options for removing a table space from the LPL and resetting the
RECOVER-pending status:

Chapter 12. Backing up and recovering your data 491

 v Dropping and re-creating the table space and repopulating the table
v “Using a REFRESH TABLE statement”
v “Using the RECOVER utility”
v “Using the LOAD REPLACE utility”
v “Using a DELETE statement without a WHERE clause”
v “Using a TRUNCATE TABLE statement” on page 493

When a job fails and a rollback begins, the undo records are not available for table
spaces that are not logged during the back-out. Therefore, the rows that are in the
table space after recovery might not be the correct rows. You can issue the
appropriate SQL statements to re-create the intended rows.

Using a REFRESH TABLE statement:

About this task

Use the REFRESH TABLE statement to repopulate a materialized query table, but
only if the materialized query table is alone in its table space. If the table is not
alone in its table space, a utility must be used to reset the table space and remove
it from RECOVER-pending status.

Using the RECOVER utility:

About this task

Use the RECOVER utility to recover to a recoverable point.

You can run the RECOVER utility against a table space with the NOT LOGGED
logging attribute. To do so, the current logging attribute of the table space must
match the logging attribute of the recovery base (that is, the logging attribute of
the table space when the image copy was taken). If no changes have been made to
the table space since the last point of recovery, the utility completes successfully. If
changes have been made, the utility completes with message DSNU1504I.

You can use RECOVER with the TOCOPY, TOLASTFULLCOPY, or TOLASTCOPY

keyword to identify which image copy to use. You can also use TORBA or
TOLOGPOINT, but the RBA or LRSN must correspond to a recoverable point.

You cannot use RECOVER with the LOGONLY keyword.

Using the LOAD REPLACE utility:

About this task

Use the LOAD REPLACE utility or the LOAD REPLACE PART utility in the
following situations:
v With an input data set to empty the table space and repopulate the table.
v Without an input data set to empty the table space to prepare for one or more
INSERT statements to repopulate the table.

Using a DELETE statement without a WHERE clause:

492 Administration Guide

 About this task

Use the DELETE statement without a WHERE clause to empty the table, when the
table space is segmented or universal, the table is alone in its table space and the
table does not have:
v A VALIDPROC
v Referential constraints
v Delete Triggers
v A SECURITY LABEL column (or it does have such a column, but multilevel
security with row level granularity is not in effect)

Using a TRUNCATE TABLE statement:

About this task

Use the TRUNCATE TABLE statement to empty the table, when the table space is
segmented and the table is alone in its table space and the table does not have:
v A VALIDPROC
v Referential constraints
v A SECURITY LABEL column (or it does have such a column, but multilevel
security with row level granularity is not in effect)

Removing various pending states from LOB and XML table spaces
You can remove various pending states from a LOB table space or an XML table
space by using a collection of utilities in a specific order.

Procedure

To remove pending states from a LOB table space or an XML table space:
1. Use the REORG TABLESPACE utility to remove the REORP status.
2. If the table space status is auxiliary CHECK-pending status:
a. Use CHECK LOB for all associated LOB table spaces.
b. Use CHECK INDEX for all LOB indexes, as well as the document ID, node
ID, and XML indexes.
3. Use the CHECK DATA utility to remove the CHECK-pending status.

Restoring data by using DSN1COPY

You can use the DSN1COPY utility to restore data that was previously backed up
by the DSN1COPY utility or by the COPY utility. If you use the DSN1COPY utility
to restore data or move data, the data definitions for the target object must be
exactly the same as when the copy was created.

Chapter 12. Backing up and recovering your data 493

 About this task

You cannot use the DSN1COPY utility to restore data that was backed up with the
DFSMSdss concurrent copy facility.

Be careful when creating backups with the DSN1COPY utility. You must ensure
that the data is consistent, or you might produce faulty backup copies. One
advantage of using COPY to create backups is that it does not allow you to copy
data that is in CHECK-pending or RECOVER-pending status. You can use COPY
to prepare an up-to-date image copy of a table space, either by making a full
image copy or by making an incremental image copy and merging that
incremental copy with the most recent full image copy.

Keep access method services LISTCAT listings of table space data sets that
correspond to each level of retained backup data.
Related reference:
DSN1COPY (Db2 Utilities)

Backing up and restoring data with non-Db2 dump and restore

You can use certain non-Db2 facilities to dump and restore data sets and volumes.
However, certain limitations exist.

About this task

Even though Db2 data sets are defined as VSAM data sets, Db2 data cannot be
read or written by VSAM record processing because it has a different internal
format. The data can be accessed by VSAM control interval (CI) processing. If you
manage your own data sets, you can define them as VSAM linear data sets (LDSs),
and access them through services that support data sets of that type.

Access method services for CI and LDS processing are available in z/OS. IMPORT
and EXPORT use CI processing; PRINT and REPRO do not, but they do support
LDSs.

DFSMS Data Set Services (DFSMSdss) is available on z/OS and provides dump
and restore services that can be used on Db2 data sets. Those services use VSAM
CI processing.

Recovering accidentally dropped objects

If a table or table space is inadvertently dropped, you can recover the object.

About this task

When you recover a dropped object, you essentially recover a table space to a
point in time. If you want to use log records to perform forward recovery on the
table space, you need the IBM Db2 Log Analysis Tool for z/OS

Procedure
To recover the object:
1. Run regular catalog reports that include a list of all OBIDs in the subsystem.

494 Administration Guide

 2. Create catalog reports that list dependencies on the table or (such as referential
constraints, indexes, and so on). After a table is dropped, this information
disappears from the catalog.
3. If an OBID has been reused by Db2, run DSN1COPY to translate the OBIDs of
the objects in the data set. However, this event is unlikely; Db2 reuses OBIDs
only when no image copies exist that contain data from that table.

How to avoid accidentally dropping objects

To avoid the problem of accidentally dropping tables, you can create a table with
the clause WITH RESTRICT ON DROP.

When a table has been created with the clause WITH RESTRICT ON DROP, then
nobody can drop the table, or the table space or database that contains the table,
until the restriction on the table is removed. The ALTER TABLE statement includes
a clause to remove the restriction, as well as one to impose it.

Recovering an accidentally dropped table

To drop tables in a partitioned table space, you need to drop the table space itself.

Before you begin

To recover a dropped table, you need a full image copy or a DSN1COPY file that
contains the data from the dropped table.

For segmented or universal table spaces, the image copy or DSN1COPY file must
contain the table when it was active (that is, created). Because of the way space is
reused for segmented table spaces, this procedure cannot be used if the table was
not active when the image copy or DSN1COPY was made. For nonsegmented table
spaces, the image copy or DSN1COPY file can contain the table when it was active
or not active.

Procedure

To recover a dropped table:

1. If you know the DBID, the PSID, the original OBID of the dropped table, and
the OBIDs of all other tables in the table space, go to step 2 on page 496.
If you do not know all of the preceding items, use the following steps to find
them. For later use with DSN1COPY, record the DBID, the PSID, and the
OBIDs of all the tables in the table space, not just the dropped table.
a. For the data set that contains the dropped table, run DSN1PRNT with the
FORMAT and NODATA options. Record the HPGOBID field in the header
page and the PGSOBD field from the data records in the data pages.
For the auxiliary table of a LOB table space, record the HPGROID field in
the header page instead of the PGSOBD field in the data pages.
v Field HPGOBID is 4 bytes long and contains the DBID in the first 2
bytes and the PSID in the last 2 bytes.
v Field HPGROID (for LOB table spaces) contains the OBID of the table. A
LOB table space can contain only one table.

Chapter 12. Backing up and recovering your data 495

 v Field PGSOBD (for non-LOB table spaces) is 2 bytes long and contains
the OBID of the table. If your table space contains more than one table,
check for all OBIDs. By searching for all different PGSOBD fields. You
need to specify all OBIDs from the data set as input for the DSN1COPY
utility.
b. Convert the hex values in the identifier fields to decimal so that they can
be used as input for the DSN1COPY utility.
2. Use the SQL CREATE statement to re-create the table and any indexes on the
table.
3. To allow DSN1COPY to access the Db2 data set, stop the table space using the
following command:

-STOP DATABASE(database-name) SPACENAM(tablespace-name)

Stopping the table space is necessary to ensure that all changes are written out
and that no data updates occur during this procedure.
4. Find the OBID for the table that you created in step 2 by querying the
SYSIBM.SYSTABLES catalog table.

The following statement returns the object ID (OBID) for the table:
SELECT NAME, OBID FROM SYSIBM.SYSTABLES
WHERE NAME=’table_name’
AND CREATOR=’creator_name’;
This value is returned in decimal format, which is the format that you need
for DSN1COPY.

5. Run DSN1COPY with the OBIDXLAT and RESET options to perform the
OBID translation and to copy data from the dropped table into the original
data set. You must specify a previous full image copy data set, inline copy
data set, or DSN1COPY file as the input data set SYSUT1 in the control
statement. Specify each of the input records in the following order in the
SYSXLAT file to perform OBID translations:
a. The DBID that you recorded in step 1 on page 495 as both the translation
source and the translation target
b. The PSID that you recorded in step 1 on page 495 as both the translation
source and the translation target
c. The original OBID that you recorded in step 1 on page 495 for the dropped
table as the translation source and the OBID that you recorded in step 4 as
the translation target
d. OBIDs of all other tables in the table space that you recorded in step 2 as
both the translation sources and translation targets
Be sure that you have named the VSAM data sets correctly by checking
messages DSN1998I and DSN1997I after DSN1COPY completes.
6. Use DSN1COPY with the OBIDXLAT and RESET options to apply any
incremental image copies. You must apply these incremental copies in
sequence, and specify the same SYSXLAT records that step 5 specifies.

496 Administration Guide

 Important: After you complete this step, you have essentially recovered the
table space to the point in time of the last image copy. If you want to use log
records to perform forward recovery on the table space, you must use the IBM
Db2 Log Analysis Tool for z/OS at this point in the recovery procedure.
7. Start the table space for normal use by using the following command:

-START DATABASE(database-name) SPACENAM(tablespace-name)

8. Rebuild all indexes on the table space.

9. Execute SELECT statements on the previously dropped table to verify that
you can access the table. Include all LOB columns in these queries.
10. Make a full image copy of the table space.
11. Re-create the objects that are dependent on the recovered table.
When a table is dropped, objects that are dependent on that table (synonyms,
views, indexes, referential constraints, and so on) are dropped. (Aliases are not
dropped.) Privileges that are granted for that table are also dropped. Catalog
reports or a copy of the catalog taken prior to the DROP TABLE can make this
task easier.
Related concepts:
Implications of dropping a table
Page set and data set copies
Recovery of data to a prior point in time
Related tasks:
Recovering an accidentally dropped table space
Related reference:
DSN1COPY (Db2 Utilities)

Recovering an accidentally dropped table space

If you accidentally drop a table space, including LOB table spaces, you can recover
that table space.

About this task

You might accidentally drop a table space, for example, when all tables in an
implicitly created table space are dropped, or if someone unintentionally executes a
DROP TABLESPACE statement for a particular table space.

When a table space is dropped, Db2 loses all information about the image copies
of that table space. Although the image copy data set is not lost, locating it might
require examination of image copy job listings or manually recorded information
about the image copies.

The recovery procedures for user-managed data sets and for Db2-managed data
sets are slightly different.

Recovering accidentally dropped Db2-managed data sets

If a consistent full image copy or DSN1COPY file is available, you can use
DSN1COPY to recover a dropped table space that is part of the catalog.

Chapter 12. Backing up and recovering your data 497

 Procedure

To recover a dropped table space:

1. Find the original DBID for the database, the PSID for the table space, and the
OBIDs of all tables that are contained in the dropped table space. For
information about how to do this, see step Recovering an accidentally
dropped table.
2. Re-create the table space and all tables. This re-creation can be difficult when
any of the following conditions is true:
v A table definition is not available.
v A table is no longer required.
If you cannot re-create a table, you must use a dummy table to take its place.
A dummy table is a table with an arbitrary structure of columns that you delete
after you recover the dropped table space.
Attention: When you use a dummy table, you lose all data from the
dropped table that you do not re-create.
3. Re-create auxiliary tables and indexes if a LOB table space has been dropped.
4. To allow DSN1COPY to access the Db2 data set, stop the table space with the
following command:
-STOP DATABASE(database-name) SPACENAM(tablespace-name)

5. PSPI Find the new PSID and OBIDs by querying the

SYSIBM.SYSTABLESPACE and SYSIBM.SYSTABLES catalog tables.
The following statement returns the object ID for a table space; this is the
PSID.
SELECT DBID, PSID FROM SYSIBM.SYSTABLESPACE
WHERE NAME=’tablespace_name’ and DBNAME=’database_name’
AND CREATOR=’creator_name’;
The following statement returns the object ID for a table:
SELECT NAME, OBID FROM SYSIBM.SYSTABLES
WHERE NAME=’table_name’
AND CREATOR=’creator_name’;
These values are returned in decimal format, which is the format that you
need for DSN1COPY. (Find the OBID of the dummy table that you created in
step 2 if you could not re-create a table.) PSPI

6. Run DSN1COPY with the OBIDXLAT and RESET options to translate the
OBID and to copy data from a previous full image copy data set, inline copy
data set, or DSN1COPY file. Use one of these copies as the input data set
SYSUT1 in the control statement. Specify each of the input records in the
following order in the SYSXLAT file to perform OBID translations:
a. The DBID that you recorded in step 1 as both the translation source and
the translation target
b. The PSID that you recorded in step 1 as the translation source and the
PSID that you recorded in step 5 as the translation target
c. The OBIDs that you recorded in step 1 as the translation sources and the
OBIDs that you recorded in step 5 as the translation targets
Be sure that you name the VSAM data sets correctly by checking messages
DSN1998I and DSN1997I after DSN1COPY completes.
7. Use DSN1COPY with the OBIDXLAT and RESET options to apply any
incremental image copies to the recovered table space. You must apply these
incremental copies in sequence, and specify the same SYSXLAT records that
step Recovering accidentally dropped user-managed data sets specifies.

498 Administration Guide

 Important: After you complete this step, you have essentially recovered the
table space to the point in time of the last image copy. If you want to use log
records to perform forward recovery on the table space, you must use IBM
Db2 Recovery Expert for z/OS or IBM Db2 Log Analysis Tool for z/OS at this
point in the recovery procedure.
For more information about point-in-time recovery, see Recovery of data to a
prior point in time.
8. Start the table space for normal use by using the following command:
-START DATABASE(database-name) SPACENAM(tablespace-name)
9. Drop all dummy tables. The row structure does not match the table definition.
This mismatch makes the data in these tables unusable.
10. Reorganize the table space to remove all rows from dropped tables.
11. Rebuild all indexes on the table space.
12. Execute SELECT statements on each table in the recovered table space to
verify the recovery. Include all LOB columns in these queries.
13. Make a full image copy of the table space.
See Page set and data set copies for more information about the COPY utility.
14. Re-create the objects that are dependent on the table.
See step Recovering an accidentally dropped table for more information.
Related reference:
DSN1COPY (Db2 Utilities)

Recovering accidentally dropped user-managed data sets

You can recover dropped table spaces that are not part of the catalog. You need to
copy the data sets that contain the data from the dropped table space to redefined
data sets.

About this task

To copy the data sets, use the OBID-translate function of the DSN1COPY utility.

Procedure

To recover a dropped data set:

1. Find the DBID for the database, the PSID for the dropped table space, and the
OBIDs for the tables that are contained in the dropped table space. For
information about how to do this, see step 1 on page 495 of “Recovering an
accidentally dropped table” on page 495.
2. Rename the data set that contains the dropped table space by using the
IDCAMS ALTER command. Rename both the CLUSTER and DATA portion of
the data set with a name that begins with the integrated catalog facility
catalog name or alias.
3. Redefine the original Db2 VSAM data sets.
Use the access method services LISTCAT command to obtain a list of data set
attributes. The data set attributes on the redefined data sets must be the same
as they were on the original data sets.
4. Use SQL CREATE statements to re-create the table space, tables, and any
indexes on the tables.
5. To allow the DSN1COPY utility to access the Db2 data sets, stop the table
space by using the following command:
-STOP DATABASE(database-name) SPACENAM(tablespace-name)

Chapter 12. Backing up and recovering your data 499

 This step is necessary to prevent updates to the table space during this
procedure in the event that the table space has been left open.
6.

PSPI

Find the target identifiers of the objects that you created in step 4 on page 499
(which consist of a PSID for the table space and the OBIDs for the tables
within that table space) by querying the SYSIBM.SYSTABLESPACE and
SYSIBM.SYSTABLES catalog tables.
The following statement returns the object ID for a table space; this is the
PSID.
SELECT DBID, PSID FROM SYSIBM.SYSTABLESPACE
WHERE NAME=’tablespace_name’ and DBNAME=’database_name’
AND CREATOR=’creator_name’;
The following statement returns the object ID for a table:
SELECT NAME, OBID FROM SYSIBM.SYSTABLES
WHERE NAME=’table_name’
AND CREATOR=’creator_name’;
These values are returned in decimal format, which is the format that you
need for the DSN1COPY utility.

PSPI

7. Run DSN1COPY with the OBIDXLAT and RESET options to perform the
OBID translation and to copy the data from the renamed VSAM data set that
contains the dropped table space to the newly defined VSAM data set. Specify
the VSAM data set that contains data from the dropped table space as the
input data set SYSUT1 in the control statement. Specify each of the input
records in the following order in the SYSXLAT file to perform OBID
translations:
a. The DBID that you recorded in step 1 on page 499 as both the translation
source and the translation target
b. The PSID that you recorded in step 1 on page 499 as the translation source
and the PSID that you recorded in step 6 as the translation target
c. The original OBIDs that you recorded in step 1 on page 499 as the
translation sources and the OBIDs that you recorded in step 6 as the
translation targets
Be sure that you have named the VSAM data sets correctly by checking
messages DSN1998I and DSN1997I after DSN1COPY completes.
8. Use DSN1COPY with the OBIDXLAT and RESET options to apply any
incremental image copies to the recovered table space. You must apply these
incremental copies in sequence, and specify the same SYSXLAT records that
step 7 specifies.

Important: After you complete this step, you have essentially recovered the
table space to the point in time of the last image copy. If you want to use log
records to perform forward recovery on the table space, you must use the IBM
Db2 UDB Log Analysis Tool for z/OS.
For more information about point-in-time recovery, see “Recovery of data to a
prior point in time” on page 460.
9. Start the table space for normal use by using the following command:
-START DATABASE(database-name) SPACENAM(tablespace-name)
10. Rebuild all indexes on the table space.

500 Administration Guide

 11. Execute SELECT statements on each table in the recovered table space to
verify the recovery. Include all LOB columns in these queries.
12. Make a full image copy of the table space.
See “Page set and data set copies” on page 455 for more information about
the COPY utility.
13. Re-create the objects that are dependent on the table.
See step 11 on page 497 of “Recovering an accidentally dropped table” on
page 495 for more information.
Related reference:
DSN1COPY (Db2 Utilities)

Recovering a Db2 system to a given point in time using the RESTORE

SYSTEM utility
Use the RESTORE SYSTEM utility to recover your Db2 system to a given point in
time. Recovering to a given point in time minimizes the amount of data that you
lose when you recover.

Before you begin

The RESTORE SYSTEM utility uses system-level backups that contain only Db2
objects to restore your Db2 system to a given point in time. The following
prerequisites apply:
v Before you can use the RESTORE SYSTEM utility, you must use the BACKUP
SYSTEM utility to create system-level backups. Choose either DATA ONLY or
FULL, depending on your recovery needs. Choose FULL if you want to backup
both your Db2 data and your Db2 logs.
v When a system-level backup on tape is the input for the RESTORE SYSTEM
utility, the user who submits the job must have the following two RACF
authorities:
– Operations authority, as in ATTRIBUTES=OPERATIONS
– DASDVOL authority, which you can set in the following way:
SETROPTS GENERIC(DASDVOL)
REDEFINE DASDVOL * UACC(ALTER)
SETROPTS CLASSACT(DASDVOL)
SETROPTS GENERIC(DASDVOL) REFRESH

You can restrict this authority to specific user IDs.

This RACF authority is required, because the RESTORE SYSTEM utility invokes
DFSMSdss when tape is the input. However, when you restore database copy
pools from a FlashCopy on disk, the RESTORE SYSTEM utility invokes
DFSMShsm, which does not require Operations or DASDVOL authority.

Procedure

To recover data to a given point in time:

1. Issue the STOP DB2 command to stop your Db2 system. If your system is a
data sharing group, stop all members of the group.
2. If the backup is a full system backup, you might need to restore the log copy
pool outside of Db2 by using DFSMShsm FRRECOV COPYPOOL (cpname)
GENERATION (gen). For data-only system backups, skip this step.

Chapter 12. Backing up and recovering your data 501

 3. Create a conditional restart record, where the SYSPITR option specifies the
given point in time that you want to recover to. Run DSNJU003 (the change log
inventory utility) with the CRESTART SYSPITR and SYSPITRT options, and
specify the log truncation point that corresponds to the point in time to which
you want to recover the system. For data sharing systems, run DSNJU003 on all
active members of the data-sharing group, and specify the same LRSN
truncation point for each member. If the point in time that you specify for
recovery is prior to the oldest system backup, you must manually restore the
volume backup from tape.
4. For data sharing systems, delete all CF structures that the data sharing group
owns.
5. Restore any logs on tape to disk.
6. Issue the START DB2 command to restart your Db2 system. For data sharing
systems, start all active members.
7. Run the RESTORE SYSTEM utility. If you manually restored the backup, use
the LOGONLY option of RESTORE SYSTEM to apply the current logs.
8. Stop and restart Db2 again to remove ACCESS(MAINT) status.

Results

After the RESTORE SYSTEM utility completes successfully, your Db2 system has
been recovered to the given point in time with consistency.
Related concepts:
Backup and recovery involving clone tables
Related tasks:
Recovering a Db2 subsystem to a prior point in time
Related reference:
RESTORE SYSTEM (Db2 Utilities)
Related information:
Tape Authorization for DB2 RESTORE SYSTEM Utility

Recovering by using Db2 restart recovery

If you created a backup by using the BACKUP SYSTEM utility, you can recover
your Db2 subsystem to the point in time of the backup by using normal Db2
restart recovery.

Procedure

To recover your Db2 system to the point in time of a backup:

1. Back up your system by issuing the BACKUP SYSTEM FULL command.
DFSMShsm maintains up to 85 versions of system backups on disk at any
given time.
2. Recover the system:
a. Stop the Db2 subsystem. For data sharing systems, stop all members of the
group.
b. Use the DFSMShsm command FRRECOV * COPYPOOL(cpname)
GENERATION(gen) to restore the database and log copy pools that the
BACKUP SYSTEM utility creates. In this command, cpname specifies the
name of the copy pool, and gen specifies which version of the copy pool is
to be restored.

502 Administration Guide

 c. For data sharing systems, delete all CF structures that are owned by this
group.
d. Restore any logs on tape to disk.
e. Start Db2. For data sharing systems, start all active members.
f. For data sharing systems, execute the GRECP and LPL recovery, which
recovers the changed data that was stored in the coupling facility at the time
of the backup.
Related concepts:
Point-in-time recovery with system-level backups

Recovering by using FlashCopy volume backups

You can use FlashCopy volume backups to recover your Db2 system to the point
in time of a backup.

Procedure

To recover by using FlashCopy volume backups:

1. Back up your system:
a. Issue the Db2 command SET LOG SUSPEND to suspend logging and
update activity, and to quiesce 32 KB page writes and data set extensions.
For data sharing systems, issue the command to each member of the group.
b. Use the FlashCopy function to copy all Db2 volumes. Include any ICF
catalogs that are used by Db2, as well as active logs and BSDSs.
c. Issue the Db2 command SET LOG RESUME to resume normal Db2 update
activity. To save disk space, you can use DFSMSdss to dump the disk copies
that you just created to a lower-cost medium, such as tape.
2. Recover your system:
a. Stop the Db2 subsystem. For data sharing systems, stop all members of the
group.
b. Use DFSMSdss RESTORE to restore the FlashCopy data sets to disk.
c. For data sharing systems, delete all CF structures that are owned by this
group.
d. Start Db2. For data sharing systems, start all active members.
e. For data sharing systems, execute the GRECP and LPL recovery, which
recovers the changed data that was stored in the coupling facility at the
time of the backup.
Related information:
FlashCopy (DFSMS Advanced Copy Services)

Making catalog definitions consistent with your data after recovery to

a prior point in time
Avoiding point-in-time recovery of the catalog is easier than attempting to correct
the inconsistencies that this kind of recovery causes.

About this task

If you choose to recover catalog and directory tables to a prior point in time, you
need to first shut down the Db2 subsystem cleanly and then restart in
ACCESS(MAINT) mode before the recovery.

Chapter 12. Backing up and recovering your data 503

 Procedure

To make catalog definitions consistent with your data after a point-in-time

recovery:
1. Run the DSN1PRNT utility with the PARM=(FORMAT, NODATA) option on all
data sets that might contain user table spaces. The NODATA option suppresses
all row data, which reduces the output volume that you receive. Data sets that
contain user tables are of the following form, where y can be either I or J:
catname.DSNDBC.dbname.tsname.y0001.A00n

2. PSPI Execute the following SELECT statements to find a list of table space
and table definitions in the Db2 catalog:
SELECT NAME, DBID, PSID FROM SYSIBM.SYSTABLESPACE;
SELECT NAME, TSNAME, DBID, OBID FROM SYSIBM.SYSTABLES;

PSPI

3. For each table space name in the catalog, look for a data set with a
corresponding name. If a data set exists, take the following additional actions:
a. Find the field HPGOBID in the header page section of the DSN1PRNT
output. This field contains the DBID and PSID for the table space. Check if
the corresponding table space name in the Db2 catalog has the same DBID
and PSID.
b. If the DBID and PSID do not match, execute DROP TABLESPACE and
CREATE TABLESPACE statements to replace the incorrect table space entry
in the Db2 catalog with a new entry. Be sure to make the new table space
definition exactly like the old one. If the table space is segmented, SEGSIZE
must be identical for the old and new definitions.
You can drop a LOB table space only if it is empty (that is, it does not
contain auxiliary tables). If a LOB table space is not empty, you must first
drop the auxiliary table before you drop the LOB table space. To drop
auxiliary tables, you can perform one of the following actions:
v Drop the base table.
v Delete all rows that reference LOBs from the base table, and then drop
the auxiliary table.
c. Find the PGSOBD fields in the data page sections of the DSN1PRNT output.
These fields contain the OBIDs for the tables in the table space. For each
OBID that you find in the DSN1PRNT output, search the Db2 catalog for a
table definition with the same OBID.
d. If any of the OBIDs in the table space do not have matching table
definitions, examine the DSN1PRNT output to determine the structure of
the tables that are associated with these OBIDs. If you find a table whose
structure matches a definition in the catalog, but the OBIDs differ, proceed
to the next step. The OBIDXLAT option of DSN1COPY corrects the
mismatch. If you find a table for which no table definition exists in the
catalog, re-create the table definition by using the CREATE TABLE
statement. To re-create a table definition for a table that has had columns
added, first use the original CREATE TABLE statement, and then use
ALTER TABLE to add columns, which makes the table definition match the
current structure of the table.
e. Use the DSN1COPY utility with the OBIDXLAT option to copy the existing
data to the new tables in the table space, and translate the DBID, PSID, and
OBIDs.

504 Administration Guide

 If a table space name in the Db2 catalog does not have a data set with a
corresponding name, one of the following events has probably occurred:
v The table space was dropped after the point in time to which you recovered.
In this case, you cannot recover the table space. Execute DROP TABLESPACE
to delete the entry from the Db2 catalog.
v The table space was defined with the DEFINE(NO) option. In this case, the
data set is allocated when you insert data into the table space.
4. For each data set in the DSN1PRNT output, look for a corresponding Db2
catalog entry. If no entry exists, follow the instructions in “Recovering an
accidentally dropped table space” on page 497 to re-create the entry in the Db2
catalog.
5. If you recover the catalog tables SYSSEQ and SYSSEQ2, identity columns and
sequence objects are inconsistent. To avoid duplicate identity column values,
recover all table spaces that contain tables that use identity columns to the
point in time to which you recovered SYSSEQ and SYSSEQ2. To eliminate gaps
between identity column values, use the ALTER TABLE statement. For
sequence objects, use the ALTER SEQUENCE statement to eliminate these gaps.
6. Ensure that the IPREFIX values of user table spaces and index spaces that were
reorganized match the IPREFIX value in the VSAM data set names that are
associated with each table space or partition. If the IPREFIX that is recorded in
the Db2 catalog and directory is different from the VSAM cluster names, you
cannot access your data. To ensure that these IPREFIX values match, complete
the following procedure:
a. Query the SYSIBM.SYSTABLEPART and SYSIBM.SYSINDEXPART catalog
tables to determine the IPREFIX value that is recorded in the catalog for
objects that were reorganized.
b. Compare this IPREFIX value to the IPREFIX value in the VSAM data set
name that is associated with the table space or index space.
c. When IPREFIX values do not match for an object, rename the VSAM data
set to specify the correct IPREFIX.

Important: For objects involved in cloning, rename the base and clone
objects at the same time.
Example: Assume that the catalog specifies an IPREFIX of J for an object but
the VSAM data set that corresponds to this object is .
catname.DSNDBC.dbname.spname.I0001.A001
You must rename this data set to:
catname.DSNDBC.dbname.spname.J0001.A001
7. Delete the VSAM data sets that are associated with table spaces that were
created with the DEFINE NO option and that reverted to an unallocated state.
After you delete the VSAM data sets, you can insert or load rows into these
unallocated table spaces to allocate new VSAM data sets.
Related concepts:
Recovery of tables that contain identity columns
Related reference:
DROP (Db2 SQL)
CREATE TABLESPACE (Db2 SQL)
DSN1COPY (Db2 Utilities)
DSN1PRNT (Db2 Utilities)

Chapter 12. Backing up and recovering your data 505

 Recovery of catalog and directory tables
Recovering catalog and directory tables to a prior point in time is strongly
discouraged for several reasons.
v You must recover all table spaces that are associated with the catalog tables that
you recover to the same point in time. For example, if you recover any table
space in the Db2 catalog (DSNDB06) and directory (DSNDB01), all table spaces
(except SYSUTILX) must be recovered.
The catalog and directory contain definitions of all databases. When databases
DSNDB01 and DSNDB06 are restored to a prior point, information about later
definitions, authorizations, binds, and recoveries is lost. If you restore the catalog
and directory, you might need to restore user databases; if you restore user
databases, you might need to restore the catalog and directory.
v You might create catalog definitions that are inconsistent with your data. These
catalog and data inconsistencies are usually the result of one of the following
actions:
– A catalog table space was restored.
– SYSSEQ and SYSSEQ2 were recovered to a prior point in time.
– The definition of a table, table space, index, or index space was changed after
the data was last backed up.
v You can cause problems for user table spaces or index spaces that have been
reorganized with SHRLEVEL REFERENCE or SHRLEVEL CHANGE.
v You can cause a populated VSAM data set that was defined with DEFINE NO
option to revert back to the undefined state. To avoid errors, you must delete the
existing VSAM data sets before the table space or index can be accessed.

Performing remote site recovery from a disaster at a local site

After a disaster at your local site, you can recover at a remote site by using the
RESTORE SYSTEM utility.

About this task

You can use RESTORE SYSTEM to recover Db2 from the backups that the
BACKUP SYSTEM utility produces, or you can use RESTORE SYSTEM LOGONLY
to recover from backups that you produce in some other way. For Db2 remote-site
recovery procedures that do not use the RESTORE SYSTEM utility, see Performing
remote-site disaster recovery.

Recovering with the BACKUP SYSTEM and RESTORE

SYSTEM utilities
You can use the BACKUP SYSTEM and RESTORE SYSTEM utilities to recover
your Db2 subsystem.

Procedure

To recover your Db2 subsystem:

1. Prepare for recovery:
a. Use BACKUP SYSTEM FULL to take the system backup.
b. Transport the system backups to the remote site.
2. Recover:
a. Run the DSNJU003 utility using either of the following control statements:

506 Administration Guide

 v In this control statement, substitute log-truncation-point with the RBA or
LRSN of the point to which you want to recover
CRESTART CREATE, SYSPITR=log-truncation-point

where .
v In this control statement, substitute log-truncation-timestamp with the
timestamp of the point to which you want to recover.
CRESTART CREATE,SYSPITRT=log-truncation-timestamp
b. Start Db2.
c. Run the RESTORE SYSTEM utility by issuing the RESTORE SYSTEM control
statement.
This utility control statement performs a recovery to the current time (or to
the time of the last log transmission from the local site).

Recovering without using the BACKUP SYSTEM utility

You can recover your Db2 subsystem if you do not use the BACKUP SYSTEM
utility to produce backups.

Procedure

To recover your Db2 subsystem without using the BACKUP SYSTEM utility:
1. Prepare for recovery.
a. Issue the Db2 command SET LOG SUSPEND to suspend logging and
update activity, and to quiesce 32 KB page writes and data set extensions.
For data sharing systems, issue the command to each member of the data
sharing group.
b. Use the FlashCopy function to copy all Db2 volumes. Include any ICF
catalogs that are used by Db2, as well as active logs and BSDSs.
c. Issue the Db2 command SET LOG RESUME to resume normal Db2 activity.
d. Use DFSMSdss to dump the disk copies that you just created to tape, and
then transport this tape to the remote site. You can also use other methods
to transmit the copies that you make to the remote site.
2. Recover your Db2 subsystem.
a. Use DFSMSdss to restore the FlashCopy data sets to disk.
b. Run the DSNJU003 utility by using the CRESTART CREATE,
SYSPITR=log-truncation-point control statement.
The log-truncation-point is the RBA or LRSN of the point to which you want
to recover.
c. Restore any logs on tape to disk.
d. Start Db2.
e. Run the RESTORE SYSTEM utility using the RESTORE SYSTEM LOGONLY
control statement to recover to the current time (or to the time of the last
log transmission from the local site).

Backup and recovery involving clone tables

When you recover a clone table that has been exchanged, you can use an image
copy that was made prior to an exchange. However, no point-in-time recovery is
possible prior to the most recent exchange.

Introductory concepts

Chapter 12. Backing up and recovering your data 507

 Types of tables (Introduction to Db2 for z/OS)

Clone tables spaces and index spaces are stored in separate physical data sets. You
must copy them and recover them separately. Output from the REPORT utility
includes information about clone tables, if they exist.

The QUIESCE command and the COPY and RECOVER utilities each use the
CLONE keyword to function on clone objects.
v Running QUIESCE with the CLONE keyword establishes a quiesce point for a
clone object.
v Running the COPY utility with the CLONE keyword takes a copy of a clone
object.
v Running the RECOVER utility with the CLONE keyword recovers a clone object.

Recovery of temporal tables with system-period data versioning

You must recover a system-period temporal table that is defined with
system-period data versioning and its corresponding history table, as a set, to a
single point in time. You can recover the table spaces individually only if you
specify the VERIFYSET NO option in the RECOVER utility statement.

| If you specify TOCOPY, TOLASTCOPY, or TOLASTFULLCOPY in the RECOVER

| utility statement, you cannot explicitly specify the VERIFYSET option. However, in
| this case, VERIFYSET NO is the default.

If you recover a system-period temporal table with system-period data versioning

to a point in time before the table was altered to have system-period data
versioning, the table is still defined with system-period data versioning, but the
history table is empty.
Related concepts:
Temporal tables and data versioning

Data restore of an entire system

The RESTORE SYSTEM utility invokes z/OS DFSMShsm services to recover a Db2
subsystem to a prior point in time.

The RESTORE SYSTEM utility restores the databases in the volume copies that the
BACKUP SYSTEM utility provided. After restoring the data, the RESTORE
SYSTEM utility can then recover a Db2 subsystem to a given point in time.

The SYSPITR option of DSNJU003 CRESTART allows you to create a conditional

restart control record (CRCR) to truncate logs for system point-in-time recovery in
preparation for running the RESTORE SYSTEM utility.

The SYSPITRT option of DSNJU003 CRESTART allows you to add a timestamp, in

the ENDTIME format, to truncate logs for system point-in-time recovery restart.

You can specify a value of 'FFFFFFFFFFFF' to cause system point-in-time recovery

to occur without log truncation.
Related reference:
DSNJU003 (change log inventory) (Db2 Utilities)
RESTORE SYSTEM (Db2 Utilities)

508 Administration Guide

Chapter 13. Recovering from different Db2 for z/OS problems
You can troubleshoot and recover from many Db2 problems on your own by using
the provided recovery procedures.

Recovering from IRLM failure

You can recover from an IRLM failure, regardless of whether the failure results in a
wait, loop, or abend.

Symptoms
The IRLM waits, loops, or abends. The following message might be issued:
DXR122E irlmnm ABEND UNDER IRLM TCB/SRB IN MODULE xxxxxxxx
ABEND CODE zzzz

Environment
If the IRLM abends, Db2 terminates. If the IRLM waits or loops, the IRLM
terminates, and Db2 terminates automatically.

Resolving the problem

Operator response:
1. Start the IRLM if you did not set it for automatic start when you installed Db2.
2. Start Db2.
3. Connect IMS to Db2, by issuing the following command, where ssid is the
subsystem ID:
/START SUBSYS ssid
4. Connect CICS to Db2 by issuing the following command:
DSNC STRT
Related tasks
Connecting from CICS
Starting Db2
Starting the IRLM

Recovering from z/OS or power failure

You can recover from a situation in which z/OS or your processor power fails.

Symptoms
No processing is occurring.

Resolving the problem

Operator response:
v If the power failure or z/OS failure has occurred:
1. IPL z/OS, and initialize the job entry subsystem (JES).
2. If you normally run VTAM with Db2, start VTAM at this point.
3. Start the IRLM if it was not set for automatic start during Db2 installation.
4. Start Db2.
5. Use the RECOVER POSTPONED command if postponed-abort units of recovery
were reported after restarting Db2, and if the AUTO or LIGHTAUTO option

© Copyright IBM Corp. 1982, 2017 509

 of the LIMIT BACKOUT field on installation panel DSNTIPL was not
specified. If the LIGHTAUTO option is specified, postponed-abort units of
recovery are processed during the next normal Db2 restart.
6. Restart IMS or CICS.
– IMS automatically connects and resynchronizes when it is restarted.
– CICS automatically connects to Db2 if the CICS PLT contains an entry for
the attachment facility module DSNCCOM0. Alternatively, use the
command DSNC STRT to connect the CICS attachment facility to Db2.
v If you know that a power failure is imminent, issue a STOP DB2 MODE(FORCE)
command to allow Db2 to stop cleanly before the power is interrupted. If Db2 is
unable to stop completely before the power failure, the situation is no worse
than if Db2 were still operational.
Related concepts
Connections to the IMS control region
Related tasks
Connecting from CICS
Starting Db2
Starting the IRLM

Recovering from disk failure

When a disk hardware failure occurs and an entire unit is lost, you can recover
from this situation.

Symptoms
No I/O activity occurs for the affected disk address. Databases and tables that
reside on the affected unit are unavailable.

Resolving the problem

Operator response:
1. Assure that no incomplete I/O requests exist for the failing device. One way
to do this is to force the volume offline by issuing the following z/OS
command, where xxx is the unit address:
VARY xxx,OFFLINE,FORCE
To check disk status, issue the following command:
D U,DASD,ONLINE
The following console message is displayed after you force a volume offline:

UNIT TYPE STATUS VOLSER VOLSTATE

4B1 3390 O-BOX XTRA02 PRIV/RSDNT
The disk unit is now available for service.
If you previously set the I/O timing interval for the device class, the I/O
timing facility terminates all requests that are incomplete at the end of the
specified time interval, and you can proceed to the next step without varying
the volume offline. You can set the I/O timing interval either through the
IECIOSxx z/OS parameter library member or by issuing the following z/OS
command:
SETIOS MIH,DEV=devnum,IOTIMING=mm:ss.
2. Issue (or request that an authorized operator issue) the following Db2
command to stop all databases and table spaces that reside on the affected
volume:

510 Administration Guide

 -STOP DATABASE(database-name) SPACENAM(space-name)
If the disk unit must be disconnected for repair, stop all databases and table
spaces on all volumes in the disk unit.
3. Select a spare disk pack, and use ICKDSF to initialize from scratch a disk unit
with a different unit address (yyy) and the same volume serial number
(VOLSER).
// Job
//ICKDSF EXEC PGM=ICKDSF
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
REVAL UNITADDRESS(yyy) VERIFY(volser)
If you initialize a 3380 or 3390 volume, use REVAL with the VERIFY parameter
to ensure that you initialize the intended volume, or to revalidate the home
address of the volume and record 0. Alternatively, use ISMF to initialize the
disk unit.
4. Issue the following z/OS console command, where yyy is the new unit
address:
VARY yyy,ONLINE
5. To check disk status, issue the following command:
D U,DASD,ONLINE
The following console message is displayed:
UNIT TYPE STATUS VOLSER VOLSTATE
7D4 3390 O XTRA02 PRIV/RSDNT
| 6. Delete all table spaces (VSAM linear data sets) from the ICF catalog by issuing
| the following access method services command for each one of them, where y
| is either I or J:
| DELETE catnam.DSNDBC.dbname.tsname.y0001.Annn CLUSTER NOSCRATCH

| where nnn is the data set or partition number, left padded by 0 (zero).
| 7. For user-managed table spaces, define the VSAM cluster and data components
| for the new volume by issuing the access method services DEFINE CLUSTER
| command with the same data set name as in the previous step, in the
| following format:
| catnam.DSNDBx.dbname.tsname.y0001.znnn

| The y is I or J, the x is C (for VSAM clusters) or D (for VSAM data

| components), and znnn is the data set or partition number, left padded by 0
| (zero). For more information, see Data set naming conventions.
8. For a user-defined table space, define the new data set before an attempt to
recover it. You can recover table spaces that are defined in storage groups
without prior definition.
| 9. Issue the following Db2 command to start all the appropriate databases and
| table spaces that were previously stopped:
| -START DATABASE(database-name) SPACENAM(space-name)
10. Recover the table spaces by using the Db2 RECOVER utility.
Related reference
RECOVER (Db2 Utilities)
Related information
DFSMS Access Method Services Commands
Device Support Facilities (ICKDSF) Device Support Facilities (ICKDSF)
User's Guide and Reference

Chapter 13. Recovering from different Db2 for z/OS problems 511
 z/OS MVS System Commands
z/OS MVS Initialization and Tuning Reference

Recovering from application errors

You can recover from a problem in which an application program placed a
logically incorrect value in a table.

Symptoms
Unexpected data is returned from an SQL SELECT statement, even though the
SQLCODE that is associated with the statement is 0.

Causes
An SQLCODE of 0 indicates that Db2 and SQL did not cause the problem, so the
cause of the incorrect data in the table is the application.

Resolving the problem

System programmer response: You might be able to use the Db2 RECOVER utility
with the TOLOGPOINT option to restore the database to a point before the error
occurred. However, in many circumstances you must manually back out the
changes that were introduced by the application. Among those circumstances are:
v Other applications changed the database after the error occurred. If you recover
the table spaces that were modified by the bad application, all subsequent
changes that were made by the other applications are lost.
v Db2 checkpoints were taken after the error occurred. In this case, you can use
RECOVER TOLOGPOINT to restore the data up to the last checkpoint before the
error occurred. However, all subsequent changes to the database are lost.
If you have a situation for which using RECOVER TOLOGPOINT is appropriate,
you can use one of the following procedures as a basis for backing out the
incorrect changes that were made by the application. The procedure that you use
depends on whether you have established a quiesce point.

Backing out incorrect application changes (with a quiesce

point)
If you have an established quiesce point, you can back out incorrect changes that
your application made.

Procedure
To back out the incorrect changes:
1. Run the REPORT utility twice, once using the RECOVERY option and once
using the TABLESPACESET option. On each run, specify the table space that
contains the inaccurate data. If you want to recover to the last quiesce point,
specify the option CURRENT when running REPORT RECOVERY.
2. Examine the REPORT output to determine the RBA of the quiesce point.
3. Run RECOVER TOLOGPOINT with the RBA that you found, specifying the
names of all related table spaces.

Results

Recovering all related table spaces to the same quiesce point prevents violations of
referential constraints.

512 Administration Guide

 Backing out incorrect application changes (without a quiesce
point)
Even if you do not have an established quiesce point, you can back out incorrect
changes that your application made. Be aware, however, that if you use this
procedure, you lose any updates to the database that occurred after the last
checkpoint and before the application error occurred.

Procedure
To back out the incorrect changes:
1. Run the DSN1LOGP stand-alone utility on the log scope that is available at
Db2 restart, using the SUMMARY(ONLY) option.
2. Determine the RBA of the most recent checkpoint before the first bad update
occurred, from one of the following sources:
v Message DSNR003I on the operator's console, which looks similar to this
message:
DSNR003I RESTART ..... PRIOR CHECKPOINT RBA=000007425468
The required RBA in this example is X'7425468'.
This technique works only if no checkpoints have been taken since the
application introduced the bad updates.
v Output from the print log map utility. You must know the time that the first
bad update occurred. Find the last BEGIN CHECKPOINT RBA before that time.
3. Run DSN1LOGP again, using SUMMARY(ONLY), and specify the checkpoint
RBA as the value of RBASTART. The output lists the work in the recovery log,
including information about the most recent complete checkpoint, a summary
of all processing, and an identification of the databases that are affected by each
active user.
4. Find the unit of recovery in which the error was made. One of the messages in
the output (identified as DSN1151I or DSN1162I) describes the unit of recovery
in which the error was made. To find the unit of recovery, use your knowledge
of the time that the program was run (START DATE= and TIME=), the
connection ID (CONNID=), authorization ID (AUTHID=), and plan name
(PLAN=). In that message, find the starting RBA as the value of START=.
5. Run the Db2 RECOVER utility with the TOLOGPOINT option, and specify the
starting RBA that you found in the previous step.
6. Recover any related table spaces or indexes to the same point in time.
Related concepts
DSN1LOGP summary report
Related reference
DSN1LOGP (Db2 Utilities)

Recovering from IMS-related failures

When you work in a Db2-IMS environment and problems occur, you can recover
from those problems.

Symptoms
Problems that occur in a Db2-IMS environment can result in a variety of
symptoms:
v An IMS wait, loop, or abend is accompanied by a Db2 message that goes to the
IMS console. This symptom indicates an IMS control region failure.

Chapter 13. Recovering from different Db2 for z/OS problems 513
 v When IMS connects to Db2, Db2 detects one or more units of recovery that are
indoubt.
v When IMS connects to Db2, Db2 detects that it has committed one or more units
of recovery that IMS indicates should be rolled back.
v Messages are issued to the IMS master terminal, to the logical terminal, or both
to indicate that some sort of IMS or Db2 abend has occurred.

Environment
Db2 can be used in an XRF (Extended Recovery Facility) recovery environment
with IMS.

To resolve IMS-related problems, follow the appropriate procedure.

Related concepts
Plans for extended recovery facility toleration

Recovering from IMS control region failure

You can recover from a problem in which the IMS control region fails.

Symptoms
v IMS waits, loops, or abends.
v Db2 attempts to send the following message to the IMS master terminal during
an abend:
DSNM002 IMS/TM xxxx DISCONNECTED FROM SUBSYSTEM yyyy RC=RC
This message cannot be sent if the failure prevents messages from being
displayed.
v Db2 does not send any messages for this problem to the z/OS console.

Environment
v Db2 detects that IMS has failed.
v Db2 either backs out or commits work that is in process.
v Db2 saves indoubt units of recovery, which need to be resolved at reconnection
time.

Resolving the problem

Operator response: Use normal IMS restart procedures, which include starting IMS
by issuing the z/OS START IMS command. The following results occur:
1. All DL/I and Db2 updates that have not been committed are backed out.
2. IMS is automatically reconnected to Db2.
3. IMS passes the recovery information for each entry to Db2 through the IMS
attachment facility. (IMS indicates whether to commit or roll back.)
4. Db2 resolves the entries according to IMS instructions.

Recovering from IMS indoubt units of recovery

When IMS connects to Db2, and Db2 has indoubt units of recovery that have not
been resolved, these units of recovery need to be resolved.

Symptoms
If Db2 has indoubt units of recovery that IMS did not resolve, the following
message is issued at the IMS master terminal, where xxxx is the subsystem
identifier:
DSNM004I RESOLVE INDOUBT ENTRY(S) ARE OUTSTANDING FOR SUBSYSTEM xxxx

514 Administration Guide

Causes
When this message is issued, IMS was either cold started, or it was started with an
incomplete log tape. Message DSNM004I might also be issued if Db2 or IMS
abnormally terminated in response to a software error or other subsystem failure.

Environment
v The connection remains active.
v IMS applications can still access Db2 databases.
v Some Db2 resources remain locked out.

If the indoubt thread is not resolved, the IMS message queues might start to back
up. If the IMS queues fill to capacity, IMS terminates. Be aware of this potential
difficulty, and monitor IMS until the indoubt units of work are fully resolved.

Resolving the problem

System programmer response:
1. Force the IMS log closed by using the /DBR FEOV command.
2. Archive the IMS log.
3. Issue the command DFSERA10 to print the records from the previous IMS log
tape for the last transaction that was processed in each dependent region.
Record the PSB and the commit status from the X'37' log that contains the
recovery ID.
4. Run the DL/I batch job to back out each PSB that is involved that has not
reached a commit point. The process might be time-consuming because
transactions are still being processed. This process might also lock a number of
records, which could affect the rest of the processing and the rest of the
message queues.
5. Enter the Db2 command DISPLAY THREAD (imsid) TYPE (INDOUBT).
6. Compare the NIDs (IMSID + OASN in hexadecimal) that are displayed in the
DISPLAY THREAD output with the OASNs (4 bytes decimal) as shown in the
DFSERA10 output. Decide whether to commit or roll back.
7. Use DFSERA10 to print the X'5501FE' records from the current IMS log tape.
Every unit of recovery that undergoes indoubt resolution processing is
recorded; each record with an 'IDBT' code is still indoubt. Note the correlation
ID and the recovery ID, for use during the next step.
8.

Enter the following Db2 command, choosing to commit or roll back, and
specify the correlation ID:
-RECOVER INDOUBT (imsid) ACTION(COMMIT|ABORT) NID (nid)
If the command is rejected because of associated network IDs, use the same
command again, substituting the recovery ID for the network ID.

Related concepts
Duplicate IMS correlation IDs

Chapter 13. Recovering from different Db2 for z/OS problems 515
 Recovering IMS indoubt units of work that need to be rolled back
When units of recovery between IMS and Db2 are indoubt at restart time, Db2 and
IMS sometimes handle the indoubt units of recovery differently. When this
situation happens, you might need to roll back the changes.

Symptoms
The following messages are issued after a Db2 restart:
DSNM005I IMS/TM RESOLVE INDOUBT PROTOCOL PROBLEM WITH SUBSYSTEM xxxx

DFS3602I xxxx SUBSYSTEM RESOLVE-INDOUBT FAILURE,RC=yyyy

Causes
The reason that these messages are issued is that indoubt units of work exist for a
Db2-IMS application, and the way that Db2 and IMS handle these units of work
differs.

At restart time, Db2 attempts to resolve any units of work that are indoubt. Db2
might commit some units and roll back others. Db2 records the actions that it takes
for the indoubt units of work. At the next connect time, Db2 verifies that the
actions that it took are consistent with the IMS decisions. If the Db2 RECOVER
INDOUBT command is issued prior to an IMS attempt to reconnect, Db2 might
decide to commit the indoubt units of recovery, whereas IMS might decide to roll
back the units of recovery. This inconsistency results in the DSNM005I message
being issued. Because Db2 tells IMS to retain the inconsistent entries, the DFS3602I
message is issued when the attempt to resolve the indoubt units of recovery ends.

Environment
v The connection between Db2 and IMS remains active.
v Db2 and IMS continue processing.
v No Db2 locks are held.
v No units of work are in an incomplete state.

Resolving the problem

System programmer response: Do not use the Db2 RECOVER INDOUBT command.
The problem is that Db2 was not indoubt but should have been. Database updates
have probably been committed on one side (IMS or Db2) and rolled back on the
other side.
1. Enter the IMS command /DISPLAY OASN SUBSYS DB2 to display the IMS list of
units of recovery that need to be resolved. This command generates the list of
OASNs in a decimal format, not in a hexadecimal format.
2. Issue the IMS command /CHANGE SUBSYS DB2 RESET to reset all the entries in
the list. (No entries are passed to Db2.)
3. Use DFSERA10 to print the log records that were recorded at the time of failure
and during restart. Look at the X'37', X'56', and X'5501FE' records at reconnect
time. Notify IBM Support about the problem.
4. Determine what the inconsistent unit of recovery was doing by examining the
log information, and manually make the IMS and Db2 databases consistent.
Related concepts
Duplicate IMS correlation IDs

Recovering from IMS application failure

You can recover from a situation in which an IMS application abnormally
terminates in a Db2 environment.

516 Administration Guide

 Symptoms
The following messages are issued at the IMS master terminal and at the LTERM
that entered the transaction that is involved:
DFS555 - TRAN tttttttt ABEND (SYSIDssss);
MSG IN PROCESS: xxxx (up to 78 bytes of data) timestamp
DFS555A - SUBSYSTEM xxxx OASN yyyyyyyyyyyyyyyy STATUS COMMIT|ABORT

Causes
The problem might be caused by a usage error in the application or by a Db2
problem.

Environment
v The failing unit of recovery is backed out by both DL/I and Db2.
v The connection between IMS and Db2 remains active.

Resolving the problem

Operator response:
v If you think that the problem was caused by a usage error, investigate and
resolve the error.
v If you think that the problem is a Db2 problem, rather than a usage error, try to
diagnose the problem using standard diagnostic procedures. You might need to
contact IBM Support if you cannot resolve the problem yourself.
Related concepts
Obtaining Db2 Diagnosis Guide and Reference ()
Techniques for debugging programs in IMS (Db2 Application programming
and SQL)

Recovering from a Db2 failure in an IMS environment

When Db2 fails in a Db2-IMS environment, you can recover from this situation.

Symptoms
Db2 fails or is not running, and one of the following status situations exists:
v If you specified error option Q, the program terminates with a U3051 user abend
completion code.
v If you specified error option A, the program terminates with a U3047 user abend
completion code.

In either of these situations, the IMS master terminal receives IMS message
DFS554, and the terminal that is involved in the problem receives IMS message
DFS555.

Resolving the problem

Operator response:
1. Restart Db2.
2. Follow the standard IMS procedures for handling application abends.

Recovering from CICS-related failure

When you work in a Db2-CICS environment and problems occur, you can recover
from those problems.

Symptoms

Chapter 13. Recovering from different Db2 for z/OS problems 517
 Problems that occur in a Db2-CICS environment can result in a variety of
symptoms, such as:
v Messages that indicate an abend in CICS or the CICS attachment facility
v A CICS wait or a loop
v Indoubt units of recovery between CICS and Db2

Environment
Db2 can be used in an XRF (Extended Recovery Facility) recovery environment
with CICS.

Resolving the problem

To resolve CICS-related problems, follow the appropriate procedure.
Related concepts
Plans for extended recovery facility toleration

Recovering from CICS application failures

You can recover from a CICS application abend in a Db2 environment.

Symptoms
The following message is issued at the user's terminal:
DFH2206 TRANSACTION tranid ABEND abcode BACKOUT SUCCESSFUL

In this message, tranid represents the transaction that abnormally terminated, and
abcode represents the specific abend code.

Environment
v The failing unit of recovery is backed out in both CICS and Db2.
v The connection between CICS and Db2 remains active.

Resolving the problem

Operator response: Investigate the abend by reading about the abend code.
v For an AEY9 abend, start the CICS attachment facility.
v For an ASP7 abend, determine why the CICS SYNCPOINT was unsuccessful.
v For other abends, follow appropriate diagnostic procedures.
Related concepts
Obtaining Db2 Diagnosis Guide and Reference ()
CICS Transaction Server for z/OS troubleshooting and support

Recovering Db2 when CICS is not operational

You can recover Db2 from a situation in which CICS is not operational.

Symptoms
Any of the following symptoms might occur:
v CICS waits or loops.
v CICS abends, as indicated by messages or dump output.

Environment
Db2 performs each of the following actions:
v Detects the CICS failure.
v Backs out inflight work.

518 Administration Guide

 v Saves indoubt units of recovery that need to be resolved when CICS is
reconnected.

Diagnosing the problem

If you think that CICS is in a wait or loop situation, find the origin of the wait or
loop. The origin might be in CICS, in CICS applications, or in the CICS attachment
facility.

If you receive messages that indicate a CICS abend, examine the messages and
dump output for more information.

If threads are connected to Db2 when CICS terminates, Db2 issues message
DSN3201I. The message indicates that Db2 end-of-task (EOT) routines have
cleaned up and disconnected any connected threads.

Resolving the problem

Operator response:
1. Correct the problem that caused CICS to terminate abnormally.
2. Do an emergency restart of CICS. The emergency restart performs each of the
following actions:
v Backs out inflight transactions that changed CICS resources
v Remembers the transactions with access to Db2 that might be indoubt
3. Start the CICS attachment facility by entering the appropriate command for
your release of CICS. The CICS attachment facility performs the following
actions:
v Initializes and reconnects to Db2
v Requests information from Db2 about the indoubt units of recovery and
passes the information to CICS
v Allows CICS to resolve the indoubt units of recovery
Related tasks
Connecting from CICS
Related information
Troubleshooting for CICS Db2 (CICS Db2 Guide)

Recovering Db2 when the CICS attachment facility cannot

connect to Db2
You can recover Db2 when the CICS attachment facility cannot connect to Db2.

Symptoms
Any of the possible symptoms can occur:
v CICS remains operational, but the CICS attachment facility abends.
v The CICS attachment facility issues a message that indicates the reason for the
connection failure, or it requests a X'04E' dump.
v The reason code in the X'04E' dump indicates the reason for failure.
v CICS issues message DFH2206 that indicates that the CICS attachment facility
has terminated abnormally with the DSNC abend code.
v CICS application programs that try to access Db2 while the CICS attachment
facility is inactive are abnormally terminated. The code AEY9 is issued.

Environment

Chapter 13. Recovering from different Db2 for z/OS problems 519
 CICS backs out the abnormally terminated transaction and treats it like an
application abend.

Resolving the problem

Operator response: Start the CICS attachment facility by entering the appropriate
command for your release of CICS. After you start the CICS attachment facility, the
following events occur:
1. The CICS attachment facility initializes and reconnects to Db2.
2. The CICS attachment facility requests information about the indoubt units of
recovery and passes the information to CICS.
3. CICS resolves the indoubt units of recovery.

Recovering CICS indoubt units of recovery

When the CICS attachment facility abends, CICS and Db2 build lists of indoubt
units of work, either dynamically or during restart, depending on the failing
subsystem. If any units of recovery are indoubt at connect time, you can recover
from this situation.

Symptoms
One of the following messages is sent to the user-named CICS destination that is
specified for the MSGQUEUEn(name) attribute in the RDO (resource definition
online): DSN2001I, DSN2034I, DSN2035I, or DSN2036I.

Causes
For CICS, a Db2 unit of recovery might be indoubt if the forget entry (X'FD59') of
the task-related installation exit routine is absent from the CICS system journal.
The indoubt condition applies only to the Db2 unit of recovery in this case because
CICS already committed or backed out any changes to its resources.

A Db2 unit of recovery is indoubt for Db2 if an End Phase 1 is present and the
Begin Phase 2 is absent.

Environment
The following table summarizes the situations that can exist when CICS units of
recovery are indoubt.

Table 49. Situations that involve CICS abnormal indoubt units of recovery
Message ID Meaning
DSN2001I The named unit of recovery cannot be resolved by CICS because CICS
was cold started. The CICS attachment facility continues the startup
process.
DSN2034I The named unit of recovery is not indoubt for Db2, but it is indoubt
according to CICS log information. The reason is probably a CICS restart
with the wrong tape. The problem might also be caused by a Db2 restart
to a prior point in time.
DSN2035I The named unit of recovery is indoubt for Db2, but it is not in the CICS
indoubt list. This is probably due to an incorrect CICS restart. The CICS
attachment facility continues the startup process and provides a
transaction dump. The problem might also be caused by a Db2 restart to
a prior point in time.

520 Administration Guide

Table 49. Situations that involve CICS abnormal indoubt units of recovery (continued)
Message ID Meaning
DSN2036I CICS indicates rollback for the named unit of recovery, but Db2 has
already committed the unit of recovery. The CICS attachment facility
continues the startup process.

CICS retains details of indoubt units of recovery that were not resolved during
connection startup. An entry is purged when it no longer shows up on the list that
is presented by Db2 or, when the entry is present in the list, when Db2 resolves it.

Resolving the problem

System programmer response: If CICS cannot resolve one or more indoubt units
of recovery, resolve them manually by using Db2 commands. Using the steps in
this procedure is rarely necessary because it is required only where operational
errors or software problems have prevented automatic resolution.
1.

Obtain a list of the indoubt units of recovery from Db2 by issuing the following
command:
-DISPLAY THREAD (connection-name) TYPE (INDOUBT)
Messages like these are then issued:
DSNV401I - DISPLAY THREAD REPORT FOLLOWS - DSNV406I - INDOUBT THREADS - COORDINATOR
STATUS RESET URID AUTHID
coordinator_name status yes/no urid authid
DISPLAY INDOUBT REPORT COMPLETE DSN9022I - DSNVDT ’-DISPLAY THREAD’ NORMAL
COMPLETION
The corr_id (correlation ID) for CICS Transaction Server for z/OS 1.2 and
subsequent releases of CICS consists of:
Bytes 1 - 4
Thread type: COMD, POOL, or ENTR
Bytes 5 - 8
Transaction ID
Bytes 9 - 12
Unique thread number

Two threads can sometimes have the same correlation ID when the connection
has been broken several times and the indoubt units of recovery have not been
resolved. In this case, use the network ID (NID) instead of the correlation ID to
uniquely identify indoubt units of recovery.
The network ID consists of the CICS connection name and a unique number
that is provided by CICS at the time that the syncpoint log entries are written.
This unique number is an 8-byte store clock value that is stored in records that
are written to both the CICS system log and to the Db2 log at syncpoint
processing time. This value is referred to in CICS as the recovery token.
2. Scan the CICS log for entries that are related to a particular unit of recovery.
Look for a PREPARE record (JCRSTRID X'F959'), for the task-related installation

Chapter 13. Recovering from different Db2 for z/OS problems 521
 where the recovery token field (JCSRMTKN) equals the value that is obtained
from the network-ID. The network ID is supplied by Db2 in the DISPLAY
THREAD command output.
You can find the CICS task number by locating the prepare log record in the
CICS log for indoubt units of recovery. Using the CICS task number, you can
locate all other entries on the log for this CICS task.
You can use the CICS journal print utility DFHJUP to scan the log.
3. Use the change log inventory utility (DSNJU003) to scan the Db2 log for entries
that are related to a particular unit of recovery. Locate the End Phase 1 record
with the required network ID. Then use the URID from this record to obtain
the rest of the log records for this unit of recovery.
When scanning the Db2 log, note that the Db2 startup message DSNJ099I
provides the start log RBA for this session.
4. If needed, do indoubt resolution in Db2.

To invoke Db2 to take the recovery action for an indoubt unit of recovery, issue
the Db2 RECOVER INDOUBT command, where the correlation_id is unique:
DSNC -RECOVER INDOUBT (connection-name)
ACTION (COMMIT/ABORT)
ID (correlation_id)
If the transaction is a pool thread, use the value of the correlation ID (corr_id)
that is returned by DISPLAY THREAD for thread#.tranid in the RECOVER INDOUBT
command. In this case, the first letter of the correlation ID is P. The transaction
ID is in characters five through eight of the correlation ID.
If the transaction is assigned to a group (group is a result of using an entry
thread), use thread#.groupname instead of thread#.tranid. In this case, the first
letter of the correlation ID is a G, and the group name is in characters five
through eight of the correlation ID. The groupname is the first transaction that is
listed in a group.
Where the correlation ID is not unique, use the following command:
DSNC -RECOVER INDOUBT (connection-name)
ACTION (COMMIT|ABORT)
NID (network-id)
When two threads have the same correlation ID, use the NID keyword instead
of the ID keyword. The NID value uniquely identifies the work unit.
To recover all threads that are associated with connection-name, omit the ID
option.
The command results that are in either of the following messages indicate
whether the thread is committed or rolled back:
DSNV414I - THREAD thread#.tranid COMMIT SCHEDULED
DSNV414I - THREAD thread#.tranid ABORT SCHEDULED
When you resolve indoubt units of work, note that CICS and the CICS
attachment facility are not aware of the commands to Db2 to commit or abort
indoubt units of recovery because only Db2 resources are affected. However,
CICS keeps details about the indoubt threads that could not be resolved by
Db2. This information is purged either when the presented list is empty or
when the list does not include a unit of recovery that CICS remembers.
Investigate any inconsistencies that you found in the preceding steps.

Related reference

522 Administration Guide

 DSNJU003 (change log inventory) (Db2 Utilities)
Related information
Reading log streams using batch jobs (for example, DFHJUP) (CICS
Transaction Server for z/OS)

Recovering from CICS attachment facility failure

You can recover Db2 when the CICS attachment facility abends or when a CICS
attachment thread subtask abends.

Symptoms
The symptoms depend on whether the CICS attachment facility or one of its thread
subtasks terminated:
v If the main CICS attachment facility subtask abends, an abend dump is
requested. The contents of the dump indicate the cause of the abend. When the
dump is issued, shutdown of the CICS attachment facility begins.
v If a thread subtask terminates abnormally, a X'04E' dump is issued, and the
CICS application abends with a DSNC dump code. The X'04E' dump generally
indicates the cause of the abend. The CICS attachment facility remains active.

Resolving the problem

Operator response: Correct the problem that caused the abend by analyzing the
CICS formatted transaction dump or subtask SNAP dump. If the CICS attachment
facility shuts down, use CICS commands to stop the execution of any CICS-Db2
applications.

Recovering from a QMF query failure

Receipt of a -805 SQL code in a Db2 for z/OS environment that includes QMF
might occur after you start QMF or issue a QMF command. If the Db2 subsystem
was recently migrated to a new release or to new-function mode, you might need
to rerun certain QMF installation jobs.

Symptoms
One of the following QMF messages is issued:
v DSQ10202
v DSQ10205
v DSQ11205
v DSQ12105
v DSQ13005
v DSQ14152
v DSQ14153
v DSQ14154
v DSQ15805
v DSQ16805
v DSQ17805
v DSQ22889
v DSQ30805
v DSQ31805
v DSQ32029
v DSQ35805

Chapter 13. Recovering from different Db2 for z/OS problems 523
 v DSQ36805

Causes
Key QMF installation jobs were not run.

Environment
The Db2 for z/OS subsystem was migrated to a new release or to new-function
mode after completion of an installation or migration to a new QMF release.

Diagnosing the problem

User response:
v If your Db2 for z/OS subsystem was recently migrated to a new release or to
new-function mode, continue with "Resolving the problem."
v If your Db2 for z/OS subsystem was not recently migrated, see other possible
causes of the DSQxxxxx messages in Troubleshooting and correcting QMF bind
problems associated with a -805 SQL code.

Resolving the problem

User response: Rerun QMF installation jobs as described in Tasks to perform when
you upgrade Db2 for z/OS after you install QMF.

Recovering from subsystem termination

You can recover Db2 after Db2 or an operator-issued cancel causes the subsystem
to terminate.

Symptoms
When a Db2 subsystem terminates, the specific failure is identified in one or
messages. The following messages might be issued at the z/OS console:
DSNV086E - DB2 ABNORMAL TERMINATION REASON=XXXXXXXX
DSN3104I - DSN3EC00 -TERMINATION COMPLETE
DSN3100I - DSN3EC00 - SUBSYSTEM ssnm READY FOR -START COMMAND

The following message might be issued to the IMS master terminal:

DSNM002I IMS/TM xxxx DISCONNECTED FROM SUBSYSTEM
yyyy RC=rc

The following message might be issued to the CICS transient data error
destination, which is defined in the RDO:
DSNC2025I - THE ATTACHMENT FACILITY IS INACTIVE

Environment
v IMS and CICS continue.
v In-process IMS and CICS applications receive SQLCODE -923 (SQLSTATE
'57015') when accessing Db2.
In most cases, if an IMS or CICS application program is running when a -923
SQLCODE is returned, an abend occurs. This is because the application program
generally terminates when it receives a -923 SQLCODE. To terminate, some
synchronization processing occurs (such as a commit). If Db2 is not operational
when synchronization processing is attempted by an application program, the
application program abends. In-process applications can abend with an abend
code X'04F'.
v IMS applications that begin to run after subsystem termination begins are
handled according to the error options.

524 Administration Guide

 – For option R, SQL return code -923 is sent to the application, and IMS pseudo
abends.
– For option Q, the message is enqueued again, and the transaction abends.
– For option A, the message is discarded, and the transaction abends.
v CICS applications that begin to run after subsystem termination begins are
handled as follows:
– If the CICS attachment facility has not terminated, the application receives a
-923 SQLCODE.
– If the CICS attachment facility has terminated, the application abends (code
AEY9).

Resolving the problem

Operator response:
1. Restart Db2 by issuing the command START DB2.
2. For IMS environments, re-establish the IMS connection by issuing the IMS
command /START SUBSYS DB2.
3. For CICS environments, re-establish the CICS connection by issuing the CICS
attachment facility command DSNC STRT.

Recovering from temporary resource failure

Db2 sometimes experiences a temporary problem when it accesses log data sets. In
this case, you need to recover from the situation so that processing can continue as
normal.

Symptoms
Db2 issues messages for the access failure for each log data set. These messages
provide information that is needed to resolve the access error. For example:
DSNJ104I ( DSNJR206 RECEIVED ERROR STATUS 00000004
FROM DSNPCLOC FOR DSNAME=DSNC710.ARCHLOG1.A0000049

*DSNJ153E ( DSNJR006 CRITICAL LOG READ ERROR

CONNECTION-ID = TEST0001
CORRELATION-ID = CTHDCORID001
LUWID = V71A.SYEC1DB2.B3943707629D=10
REASON-CODE = 00D10345

Causes
Db2 might experience a problem when it attempts to allocate or open archive log
data sets during the rollback of a long-running unit of recovery. These temporary
failures can be caused by:
v A temporary problem with DFHSM recall
v A temporary problem with the tape subsystem
v Uncataloged archive logs
v Archive tape mount requests being canceled

Resolving the problem

User response: You can attempt to recover from temporary failures by issuing a
positive reply (Y) to the following message:
*26 DSNJ154I ( DSNJR126 REPLY Y TO RETRY LOG READ REQUEST, N TO ABEND

If the problem persists, quiesce other work in the system before replying N, which
terminates Db2.

Chapter 13. Recovering from different Db2 for z/OS problems 525
Recovering from active log failures
A variety of active log failures might occur, but you can recover from them.

Symptoms
Most active log failures are accompanied by or preceded by error messages to
inform you of out-of-space conditions, write or read I/O errors, or loss of dual
active logging.

If you receive message DSNJ103I at startup time, the active log is experiencing
dynamic allocation problems. If you receive message DSNJ104I, the active log is
experiencing open-close problems. In either case, you should follow procedures in
“Recovering from BSDS or log failures during restart” on page 537.

Recovering from being out of space in active logs

The available space in the active log is finite, so the active log might fill to capacity
for one of several reasons. For example, delays in offloading and excessive logging
can fill the active log. You can recover from out-of-space conditions in the active
log.

Symptoms
The following warning message is issued when the last available active log data
set is 5% full:
DSNJ110E - LAST COPY n ACTIVE LOG DATA SET IS nnn PERCENT FULL

The Db2 subsystem reissues the message after each additional 5% of the data set
space is filled. Each time the message is issued, the offload process is started.
IFCID trace record 0330 is also issued if statistics class 3 is active.

If the active log fills to capacity, after having switched to single logging, Db2 issues
the following message, and an offload is started.
DSNJ111E - OUT OF SPACE IN ACTIVE LOG DATA SETS

The Db2 subsystem then halts processing until an offload is completed.

Causes
The active log is out of space.

Environment
An out-of-space condition on the active log has very serious consequences.
Corrective action is required before Db2 can continue processing. When the active
log becomes full, the Db2 subsystem cannot do any work that requires writing to
the log until an offload is completed. Until that offload is completed, Db2 waits for
an available active log data set before resuming normal Db2 processing. Normal
shutdown, with either a QUIESCE or FORCE command, is not possible because the
shutdown sequence requires log space to record system events that are related to
shutdown (for example, checkpoint records).

Resolving the problem

Operator response:
1. Ensure that the offload is not waiting for a tape drive. If it is, mount a tape.
Db2 then processes the offload task.
2. If you are uncertain about what is causing the problem, enter the following
command:

526 Administration Guide

 -ARCHIVE LOG CANCEL OFFLOAD

This command causes Db2 to restart the offload task. Issuing this command
might solve the problem.
3. If issuing this command does not solve the problem, determine and resolve the
cause of the problem, and then reissue the command. If the problem cannot be
resolved quickly, have the system programmer define additional active logs
until you can resolve the problem.

System programmer response: Define additional active log data sets so that Db2
can continue its normal operation while the problem that is causing the offload
failures is corrected.
1. Use the z/OS command CANCEL to stop Db2.
2. Use the access method services DEFINE command to define new active log data
sets.
3. Run utility DSNJLOGF to initialize the new active log data sets.
4. Define the new active log data sets in the BSDS by using the change log
inventory utility (DSNJU003). .
5. Restart Db2. Offload is started automatically during startup, and restart
processing occurs.

Recommendation: To minimize the number of offloads that are taken per day in
your installation, consider increasing the size of the active log data sets.
Related reference
DSNJLOGF (preformat active log) (Db2 Utilities)
DSNJU003 (change log inventory) (Db2 Utilities)

Recovering from a write I/O error on an active log data set

You can recover from a situation in which a write error occurs on an active log
data set.

Symptoms
The following message is issued:
DSNJ105I - csect-name LOG WRITE ERROR DSNAME=..., LOGRBA=...,
ERROR STATUS= ccccffss

Causes
Although this problem can be caused by several problems, one possible cause is a
CATUPDT failure.

Environment
When a write error occurs on an active log data set, the following characteristics
apply:
v Db2 marks the failing Db2 log data set TRUNCATED in the BSDS.
v Db2 goes on to the next available data set.
v If dual active logging is used, Db2 truncates the other copy at the same point.
v The data in the truncated data set is offloaded later, as usual.
v The data set is not stopped; it is reused on the next cycle. However, if a
DSNJ104 message indicates a CATUPDT failure, the data set is marked
STOPPED.

Resolving the problem

Chapter 13. Recovering from different Db2 for z/OS problems 527
 System programmer response: If the DSNJ104 message indicates a CATUPDT
failure, use access method services and the change log inventory utility
(DSNJU003) to add a replacement data set. In this case, you need to stop Db2. The
timing of when you should take this action depends on how widespread the
problem is.
v If the additional problem is localized and does not affect your ability to recover
from any other problems, you can wait until the earliest convenient time.
v If the problem is widespread (perhaps affecting an entire set of active log data
sets), stop Db2 after the next offload.
Related reference
DSNJU003 (change log inventory) (Db2 Utilities)

Recovering from a loss of dual active logging

If you use dual active logs, which is generally recommended, and one of the active
log fails, Db2 reverts to use of a single active log. You can recover from this
situation and return to dual active-log mode.

Symptoms
The following message is issued:
DSNJ004I - ACTIVE LOG COPY n INACTIVE, LOG IN SINGLE MODE,
ENDRBA=...

Causes
This problem occurs when Db2 completes one active log data set and then finds
that the subsequent copy (COPY n) data sets have not been offloaded and are
marked STOPPED.

Environment
Db2 continues in single mode until offloading completes and then returns to dual
mode. If the data set is marked STOPPED, however, intervention is required.

Resolving the problem

System programmer response:
1. Verify that offload is proceeding and is not waiting for a tape mount. You
might need to run the Db2 print log map utility (DSNJU004) to determine the
status of all data sets.
2. If any data sets are marked STOPPED, use IDCAMS to delete the data sets, and
then re-add them by using the Db2 change log inventory utility (DSNJU003).
Related reference
DSNJU003 (change log inventory) (Db2 Utilities)

Recovering from I/O errors while reading the active log

You can recover from situations in which an I/O error occurs when Db2 is reading
the active log.

Symptoms
The following message is issued:
DSNJ106I - LOG READ ERROR DSNAME=..., LOGRBA=...,
ERROR STATUS=ccccffss

Environment

528 Administration Guide

v If the error occurs during offload, offload tries to identify the RBA range from a
second copy of the active log.
– If no second copy of the active log exists, the data set is stopped.
– If the second copy of the active log also has an error, only the original data
set that triggered the offload is stopped. Then the archive log data set is
terminated, leaving a discontinuity in the archived log RBA range.
– The following message is issued:
DSNJ124I - OFFLOAD OF ACTIVE LOG SUSPENDED FROM RBA xxxxxx
TO RBA xxxxxx DUE TO I/O ERROR
– If the second copy of the active log is satisfactory, the first copy is not
stopped.
v If the error occurs during recovery, Db2 provides data from specific log RBAs
that are requested from another copy or archive. If this is unsuccessful, recovery
fails and the transaction cannot complete, but no log data sets are stopped.
However, the table space that is being recovered is not accessible.

Resolving the problem

System programmer response:
v If the problem occurred during offload, determine which databases are affected
by the active log problem, and take image copies of those. Then proceed with a
new log data set.
v You can use the IDCAMS REPRO command to archive as much of the stopped
active log data set as possible. Then run the change log inventory utility to
notify the BSDS of the new archive log and its log RBA range. Repairing the
active log does not solve the problem because offload does not go back to
unload it.
v If the active log data set has been stopped, it is not used for logging. The data
set is not deallocated; it is still used for reading.
v If the data set is not stopped, an active log data set should nevertheless be
replaced if persistent errors occur. The operator is not told explicitly whether the
data set has been stopped. To determine the status of the active log data set, run
the print log map utility (DSNJU004).
v If you need to replace the data set:
1. Ensure that the data is saved.
If you have dual active logs, the data is saved on the other active log, which
becomes your new data set. Skip to step 4 on page 530.
If you are not using dual active logs, take the following steps to determine
whether the data set with the error has been offloaded:
a. Use the print log map utility (DSNJU004) to list information about the
archive log data sets from the BSDS.
b. Search the list for a data set whose RBA range includes the range of the
data set with the error.
2. If the data set with the error has been offloaded (that is, if the value for high
RBA offloaded in the print log map utility output is greater than the RBA
range of the data set with the error), manually add a new archive log to the
BSDS by using the change log inventory utility (DSNJU003). Use IDCAMS to
define a new log that has the same LRECL and BLKSIZE values as defined in
DSNZPxxx. You can use the access method services REPRO command to copy
a data set with the error to the new archive log. If the archive log is not
cataloged, Db2 can locate it from the UNIT and VOLSER values in the BSDS.
3. If an active log data set has been stopped, an RBA range has not been
offloaded; copy from the data set with the error to a new data set. If

Chapter 13. Recovering from different Db2 for z/OS problems 529
 additional I/O errors prevent you from copying the entire data set, a gap
occurs in the log and restart might fail, although the data still exists and is
not overlaid. If this occurs, see “Recovering from BSDS or log failures during
restart” on page 537.
4. Stop Db2, and use the change log inventory utility to update information in
the BSDS about the data set with the error.
a. Use DELETE to remove information about the bad data set.
b. Use NEWLOG to name the new data set as the new active log data set and
to give it the RBA range that was successfully copied.
The DELETE and NEWLOG operations can be performed by the same job step;
put DELETE before NEWLOG in the SYSIN input data set. This step clears the
stopped status, and Db2 eventually archives it.
c. Delete the data set that is in error by using access method services.
d. Redefine the data set so that you can write to it. Use the access method
services DEFINE command to define the active log data sets. If you use
dual logs and have a good copy of the log, use the REPRO command to
copy the contents to the new data set that you just created. If you do not
use dual logs, initialize the new data set by using the DSNJLOGF utility.
Related reference
PRIMARY QUANTITY field (PRIQTY subsystem parameter) (Db2
Installation and Migration)
DSNJU004 (print log map) (Db2 Utilities)

Recovering from archive log failures

You can recover from situations in which archive logging fails.

Symptoms
Archive log failures can result in a variety of Db2 and z/OS messages that identify
problems with archive log data sets.

One specific symptom that might occur is message DSNJ104I, which indicates an
open-close problem on the archive log.

Recovering from allocation problems with the archive log

You can recover from situations in which allocation problems occur for the archive
log.

Symptoms
The following message is issued:
DSNJ103I - csect-name LOG ALLOCATION ERROR DSNAME=dsname,
ERROR STATUS=eeeeiiii, SMS REASON CODE=ssssssss

z/OS dynamic allocation provides the ERROR STATUS information. If the

allocation is for offload processing, the following message is also issued:
DSNJ115I - OFFLOAD FAILED, COULD NOT ALLOCATE AN ARCHIVE DATA SET

Causes
Archive log allocation problems can occur when various Db2 operations fail; for
example:
v The RECOVER utility executes and requires an archive log. If neither archive log
can be found or used, recovery fails.

530 Administration Guide

 v The active log becomes full, and an offload is scheduled. Offload tries again the
next time it is triggered. The active log does not wrap around; therefore, if no
more active logs are available, the offload fails, but data is not lost.
v The input is needed for restart, which fails. If this is the situation that you are
experiencing, see Recovering from BSDS or log failures during restart

Resolving the problem

Operator response: Check the allocation error code for the cause of the problem,
and correct it. Ensure that drives are available, and run the recovery job again. If a
DFSMSdfp ACS user-exit filter exists for an archive log data set, be careful because
this can cause the Db2 subsystem to fail on a device allocation error when Db2
attempts to read the archive log data set.

Recovering from write I/O errors during archive log offload

You can recover from write I/O errors that occur during the offload of an archive
log.

Symptoms
No specific Db2 message is issued for write I/O errors. Only a z/OS error
recovery program message is issued.

If Db2 message DSNJ128I is issued, an abend in the offload task occurred, in which
case you should follow the instructions for this message.

Environment
v Offload abandons that output data set (no entry in BSDS).
v Offload dynamically allocates a new archive and restarts offloading from the
point at which it was previously triggered. For dual archiving, the second copy
waits.
v If an error occurs on the new data set, these additional actions occur:
– For dual archive mode, the following DSNJ114I message is generated, and the
offload processing changes to single mode.
DSNJ114I - ERROR ON ARCHIVE DATA SET, OFFLOAD CONTINUING
WITH ONLY ONE ARCHIVE DATA SET BEING GENERATED
– For single mode, the offload process abandons the output data set. Another
attempt to offload this RBA range is made the next time offload is triggered.
– The active log does not wrap around; if no more active logs are available,
data is not lost.

Resolving the problem

Operator response: Ensure that offload activity is allocated on a drive and control
unit that are operational.
Related information
DSNJ128I (Db2 Messages)

Recovering from read I/O errors on an archive data set during

recovery
You can recover from read I/O errors that occur on an archive log during recovery.

Symptoms
No specific Db2 message is issued; only the z/OS error recovery program message
is issued.

Chapter 13. Recovering from different Db2 for z/OS problems 531
 Environment
v If a second copy of the archive log exists, the second copy is allocated and used.
v If a second copy of the archive log does not exist, recovery fails.

Resolving the problem

Operator response: If you recover from tape, try recovering by using a different
drive. If this approach does not work, contact the system programmer.

System programmer response: Recover to the last image copy or to the RBA of the
last quiesce point.
Related reference
RECOVER (Db2 Utilities)

Recovering from insufficient disk space for offload processing

If offload processing terminates unexpectedly when Db2 is offloading the active
log data sets to disk, you can recover from this situation.

Symptoms
Prior to the failure, z/OS issues abend message IEC030I, IEC031I, or IEC032I.
Offload processing terminates unexpectedly. Db2 issues the following message:
DSNJ128I - LOG OFFLOAD TASK FAILED FOR ACTIVE LOG nnnnn

Additional z/OS abend messages might accompany message DSNJ128I.

Causes
The following situations can cause problems with insufficient disk space during
Db2 offload processing:
v The size of the archive log data set is too small to contain the data from the
active log data sets during offload processing. All secondary space allocations
have been used.
v All available space on the disk volumes to which the archive data set is being
written has been exhausted.
v The primary space allocation for the archive log data set (as specified in the load
module for subsystem parameters) is too large to allocate to any available online
disk device.

| Environment
| The archive data sets that are allocated to the offload task in which the error
| occurred are deallocated and deleted. Another attempt to offload the RBA range of
| the active log data sets is made the next time offload is invoked.

Resolving the problem

System programmer response: The actions that you take depend on what caused
Db2 message DSNJ128I to be issued:
v If z/OS abend message IEC030I precedes Db2 message DSNJ128I, increase the
primary or secondary allocations (or both) for the archive log data set in
DSNZPxxx. Another option is to reduce the size of the active log data set.
Modifications to DSNZPxxx require that you stop and start Db2 for the changes
to take effect. If the data that is to be offloaded is particularly large, you can
mount another online storage volume or make one available to Db2.
v If z/OS abend message IEC032I precedes message DSNJ128I, make space
available on the disk volumes, or make another online storage volume available

532 Administration Guide

 for Db2. After you make additional space available, issue the Db2 command
ARCHIVE LOG CANCEL OFFLOAD. Db2 then retries the offload.
v If z/OS abend message IEC032I precedes Db2 message DSNJ128I, make space
available on the disk volumes, or make available another online storage volume
for Db2. If this approach is not possible, adjust the value of PRIQTY in the
DSNZPxxx module to reduce the primary allocation. If the primary allocation is
reduced, you might need to increase the size of the secondary space allocation to
avoid future abends.
Related reference
PRIMARY QUANTITY field (PRIQTY subsystem parameter) (Db2
Installation and Migration)

Recovering from BSDS failures

When the bootstrap data set (BSDS) is damaged, you need to recover that BSDS,
regardless of whether you are running Db2 in dual-BSDS or single-BSDS mode.

Symptoms
If a BSDS is damaged, Db2 issues one of the following message numbers:
DSNJ126I, DSNJ100I, or DSNJ120I.
Related concepts
Management of the bootstrap data set

Recovering from an I/O error on the BSDS

When an I/O error occurs on the only copy of the BSDS, you need to recover the
BSDS before Db2 can operate normally. If an I/O error occurs on one copy of the
BSDS in a dual-BSDS mode environment, you need to recover that copy of the
BSDS before the next restart.

Symptoms
The following message is issued:
DSNJ126I - BSDS ERROR FORCED SINGLE BSDS MODE

The following messages are then issued:

DSNJ107I - READ ERROR ON BSDS
DSNAME=... ERROR STATUS=...
DSNJ108I - WRITE ERROR ON BSDS
DSNAME=... ERROR STATUS=...

Causes
A write I/O error occurred on a BSDS.

Environment
If Db2 is in a dual-BSDS mode and one copy of the BSDS is damaged by an I/O
error, the BSDS mode changes from dual-BSDS mode to single-BSDS mode. If Db2
is in a single-BSDS mode when the BSDS is damaged by an I/O error, Db2
terminates until the BSDS is recovered.

Resolving the problem

System programmer response:
1. Use access method services to rename or delete the damaged BSDS and to
define a new BSDS with the same name as the failing BSDS. You can find
control statements in job DSNTIJIN.

Chapter 13. Recovering from different Db2 for z/OS problems 533
 2. Issue the Db2 command RECOVER BSDS to make a copy of the good BSDS in the
newly allocated data set and to reinstate dual-BSDS mode.
Related tasks
Recovering the BSDS from a backup copy

Recovering from an error that occurs while opening the BSDS

You need to recover the bootstrap data set (BSDS) if an error occurs when Db2
opens the BSDS.

Symptoms
The following message is issued:
DSNJ100I - ERROR OPENING BSDS n DSNAME=..., ERROR STATUS=eeii

Resolving the problem

System programmer response:
1. Use access method services to delete or rename the damaged data set, to define
a replacement data set, and to copy (with the REPRO command) the remaining
BSDS to the replacement.
2. Use the START DB2 command to start the Db2 subsystem.
Related tasks
Recovering the BSDS from a backup copy

Recovering from unequal timestamps on BSDSs

When timestamps on different copies of the bootstrap data set (BSDS) differ, Db2
attempts to resynchronize the BSDSs and restore dual BSDS mode. If this attempt
succeeds,Db2 restart continues automatically. If this attempt fails, you need to
recover from the situation.

Symptoms
The following message is issued:
DSNJ120I - DUAL BSDS DATA SETS HAVE UNEQUAL TIMESTAMPS,
BSDS1 SYSTEM=..., UTILITY=..., BSDS2 SYSTEM=..., UTILITY=...

Causes
Unequal timestamps can occur for the following reasons:
v One of the volumes that contains the BSDS has been restored. All information of
the restored volume is outdated. If the volume contains any active log data sets
or Db2 data, their contents are also outdated. The outdated volume has the
lower timestamp.
v Dual BSDS mode has degraded to single BSDS mode, and you are trying to start
without recovering the bad copy of the BSDS.
v The Db2 subsystem abended after updating one copy of the BSDS, but prior to
updating the second copy.

Resolving the problem

Operator response: If Db2 restart fails, notify the system programmer.

System programmer response: If Db2 fails to automatically resynchronize the

BSDS data sets:
1. Run the print log map utility (DSNJU004) on both copies of the BSDS; compare
the lists to determine which copy is accurate or current.
2. Rename the outdated data set, and define a replacement for it.

534 Administration Guide

 3. Copy the good data set to the replacement data set, using the REPRO command
of access method services.
4. Use the access method services REPRO command to copy the current version of
the active log to the outdated data set if all the following conditions are true:
v The problem was caused by a restored outdated BSDS volume.
v The restored volume contains active log data.
v You were using dual active logs on separate volumes.
If you were not using dual active logs, cold start the subsystem.
If the restored volume contains database data, use the RECOVER utility to
recover that data after successful restart.

Recovering the BSDS from a backup copy

In some situations, the bootstrap data set (BSDS) becomes damaged, and you need
to recover the BSDS from a backup copy.

About this task

Db2 stops and does not restart until dual-BSDS mode is restored in the following
situations:
v Db2 is operating in single-BSDS mode, and the BSDS is damaged.
v Db2 is operating in dual-BSDS mode, and both BSDSs are damaged.

Procedure

To recover the BSDS from a backup copy:

1. Locate the BSDS that is associated with the most recent archive log data set.
The data set name of the most recent archive log is displayed on the z/OS
console in the last occurrence of message DSNJ003I, which indicates that
offloading has successfully completed. In preparation for the rest of this
procedure, keep a log of all successful archives that are noted by that message.
v If archive logs are on disk, the BSDS is allocated on any available disk. The
BSDS name is like the corresponding archive log data set name; change only
the first letter of the last qualifier, from A to B, as in the following example:
Archive log name
DSN.ARCHLOG1.A0000001
BSDS copy name
DSN.ARCHLOG1.B0000001
v If archive logs are on tape, the BSDS is the first data set of the first archive
log volume. The BSDS is not repeated on later volumes.
2. If the most recent archive log data set has no copy of the BSDS (presumably
because an error occurred during its offload), locate an earlier copy of the BSDS
from an earlier offload.
3. Rename or delete any damaged BSDS.
v To rename a damaged BSDS, use the access method services ALTER command
with the NEWNAME option.
v To delete a damaged BSDS, use the access method services DELETE command.
For each damaged BSDS, use access method services to define a new BSDS as a
replacement data set. Job DSNTIJIN contains access method services control
statements to define a new BSDS. The BSDS is a VSAM key-sequenced data set
(KSDS) that has three components: cluster, index, and data. You must rename
all components of the data set. Avoid changing the high-level qualifier.

Chapter 13. Recovering from different Db2 for z/OS problems 535
 4. Use the access method services REPRO command to copy the BSDS from the
archive log to one of the replacement BSDSs that you defined in the prior step.
Do not copy any data to the second replacement BSDS; data is placed in the
second replacement BSDS in a later step in this procedure.
a. Use the print log map utility (DSNJU004) to print the contents of the
replacement BSDS. You can then review the contents of the replacement
BSDS before continuing your recovery work.
b. Update the archive log data set inventory in the replacement BSDS.
Examine the print log map output, and note that the replacement BSDS
does not obtain a record of the archive log from which the BSDS was
copied. If the replacement BSDS is a particularly old copy, it is missing all
archive log data sets that were created later than the BSDS backup copy.
Therefore, you need to update the BSDS inventory of the archive log data
sets to reflect the current subsystem inventory.
Use the change log inventory utility (DSNJU003) NEWLOG statement to
update the replacement BSDS, adding a record of the archive log from
which the BSDS was copied. Ensure that the CATALOG option of the
NEWLOG statement is properly set to CATALOG = YES if the archive log
data set is cataloged. Also, use the NEWLOG statement to add any
additional archive log data sets that were created later than the BSDS copy.
c. Update DDF information in the replacement BSDS. If the Db2 subsystem for
your installation is part of a distributed network, the BSDS contains the
DDF control record. You must review the contents of this record in the
output of the print log map utility. If changes are required, use the change
log inventory DDF statement to update the BSDS DDF record.
d. Update the active log data set inventory in the replacement BSDS.
In unusual circumstances, your installation might have added, deleted, or
renamed active log data sets since the BSDS was copied. In this case, the
replacement BSDS does not reflect the actual number or names of the active
log data sets that your installation has currently in use.
If you must delete an active log data set from the replacement BSDS log
inventory, use the change log inventory utility DELETE statement.
If you need to add an active log data set to the replacement BSDS log
inventory, use the change log inventory utility NEWLOG statement. Ensure
that the RBA range is specified correctly on the NEWLOG statement.
If you must rename an active log data set in the replacement BSDS log
inventory, use the change log inventory utility DELETE statement, followed
by the NEWLOG statement. Ensure that the RBA range is specified correctly
on the NEWLOG statement.
e. Update the active log RBA ranges in the replacement BSDS. Later, when a
restart is performed, Db2 compares the RBAs of the active log data sets that
are listed in the BSDS with the RBAs that are found in the actual active log
data sets. If the RBAs do not agree, Db2 does not restart. The problem is
magnified when a particularly old copy of the BSDS is used. To resolve this
problem, use the change log inventory utility to change the RBAs that are
found in the BSDS to the RBAs in the actual active log data sets. Take the
appropriate action, described below, to change RBAs in the BSDS:
v If you are not certain of the RBA range of a particular active log data set,
use DSN1LOGP to print the contents of the active log data set. Obtain the
logical starting and ending RBA values for the active log data set from
the DSN1LOGP output. The STARTRBA value that you use in the change
log inventory utility must be at the beginning of a control interval.
Similarly, the ENDRBA value that you use must be at the end of a control

536 Administration Guide

 interval. To get these values, round the starting RBA value from the
DSN1LOGP output down so that it ends in X'000'. Round the ending
RBA value up so that it ends in X'FFF'.
v When the RBAs of all active log data sets are known, compare the actual
RBA ranges with the RBA ranges that are found in the BSDS (listed in the
print log map utility output).
If the RBA ranges are equal for all active log data sets, you can proceed
to step 4f without any additional work.
If the RBA ranges are not equal, adjust the values in the BSDS to reflect
the actual values. For each active log data set for which you need to
adjust the RBA range, use the change log inventory utility DELETE
statement to delete the active log data set from the inventory in the
replacement BSDS. Then use the NEWLOG statement to redefine the
active log data set to the BSDS.
f. If only two active log data sets are specified in the replacement BSDS, add a
new active log data set for each copy of the active log, and define each new
active log data set of the replacement BSDS log inventory.
If only two active log data sets are specified for each copy of the active log,
Db2 might have difficulty during restart. The difficulty can arise when one
of the active log data sets is full and has not been offloaded, whereas the
second active log data set is close to filling. Adding a new active log data set
for each copy of the active log can alleviate difficulties on restart in this
situation.
To add a new active log data set for each copy of the active log, use the
access method services DEFINE command. The control statements to
accomplish this task can be found in job DSNTIJIN. After the active log data
sets are physically defined and allocated, use the change log inventory
utility NEWLOG statement to define the new active log data sets of the
replacement BSDS. You do not need to specify the RBA ranges on the
NEWLOG statement.
5. Copy the updated BSDS copy to the second new BSDS data set. The dual
bootstrap data sets are now identical.
6. Optional: Use the print log map utility (DSNJU004) to print the contents of the
second replacement BSDS at this point.
7. If you have lost your current active log data set, refer to the following topics:
v “Recovering from BSDS or log failures during restart”
v Task 4: Truncate the log at the point of error, which provides information
about how to construct a conditional restart control record (CRCR).
8. Restart Db2, using the newly constructed BSDS. Db2 determines the current
RBA and what active logs need to be archived.
Related information
DFSMS Access Method Services Commands

Recovering from BSDS or log failures during restart

When the bootstrap data set (BSDS) or part of the recovery log for Db2 is damaged
or lost and that damage prevents restart, you need to recover from that situation.
What you do to recover varies based on the particular circumstances.

If the problem is discovered at restart, begin with one of the following recovery
procedures:
v “Recovering from active log failures” on page 526

Chapter 13. Recovering from different Db2 for z/OS problems 537
 v “Recovering from archive log failures” on page 530
v Recovering from BSDS failures

If the problem persists, return to the procedures in this section.

When Db2 recovery log damage terminates restart processing, Db2 issues messages
to the console to identify the damage and issue an abend reason code. (The SVC
dump title includes a more specific abend reason code to assist in problem
diagnosis.) If the explanations for the reason codes indicate that restart failed
because of some problem that is not related to a log error, contact IBM Software
Support.

To minimize log problems during restart, the system requires two copies of the
BSDS. Dual logging is also recommended.

Basic approaches to recovery: The two basic approaches to recovery from problems
with the log are:
v Restart Db2, bypassing the inaccessible portion of the log and rendering some
data inconsistent. Then recover the inconsistent objects by using the RECOVER
utility, or re-create the data by using REPAIR. Use the methods that are
described following this procedure to recover the inconsistent data.
v Restore the entire Db2 subsystem to a prior point of consistency. The method
requires that you have first prepared such a point; for suggestions, see Preparing
to recover to a prior point of consistency. Methods of recovery are described
under “Recovering from unresolvable BSDS or log data set problem during
restart” on page 561.

Bypassing the damaged log

Even if the log is damaged, and Db2 is started by circumventing the damaged
portion, the log is the most important source for determining what work was lost
and what data is inconsistent.

Bypassing a damaged portion of the log generally proceeds with the following
steps:
1. Db2 restart fails. A problem exists on the log, and a message identifies the
location of the error. The following abend reason codes, which appear only in
the dump title, can be issued for this type of problem. This is not an exhaustive
list; other codes might occur.

00D10261 00D10264 00D10267 00D1032A 00D1032C

00D10262 00D10265 00D10268 00D1032B 00E80084
00D10263 00D10266 00D10329

The following figure illustrates the general problem.

538 Administration Guide

 Log Start Log Error Log End

Time
line

RBA: X Y

Figure 48. General problem of damaged Db2 log information

2. Db2 cannot skip over the damaged portion of the log and continue restart
processing. Instead, you restrict processing to only a part of the log that is error
free. For example, the damage shown in the preceding figure occurs in the log
RBA range between X to Y. You can restrict restart to all of the log before X;
then changes later than X are not made. Alternatively, you can restrict restart to
all of the log after Y; then changes between X and Y are not made. In either
case, some amount of data is inconsistent.
3. You identify the data that is made inconsistent by your restart decision. With
the SUMMARY option, the DSN1LOGP utility scans the accessible portion of
the log and identifies work that must be done at restart, namely, the units of
recovery that are to be completed and the page sets that they modified.
Because a portion of the log is inaccessible, the summary information might not
be complete. In some circumstances, your knowledge of work in progress is
needed to identify potential inconsistencies.
4. You use the CHANGE LOG INVENTORY utility to identify the portion of the
log to be used at restart, and to tell whether to bypass any phase of recovery.
You can choose to do a cold start and bypass the entire log.
5. You restart Db2. Data that is unaffected by omitted portions of the log is
available for immediate access.
6. Before you allow access to any data that is affected by the log damage, you
resolve all data inconsistencies. That process is described under “Resolving
inconsistencies resulting from a conditional restart” on page 567.

Where to start

The specific procedure depends on the phase of restart that was in control when
the log problem was detected. On completion, each phase of restart writes a
message to the console. You must find the last of those messages in the console
log. The next phase after the one that is identified is the one that was in control
when the log problem was detected. Accordingly, start at:
v “Recovering from failure during log initialization or current status rebuild” on
page 540
v “Recovering from a failure during forward log recovery” on page 552
v “Recovering from a failure during backward log recovery” on page 557

As an alternative, determine which, if any, of the following messages was last

received and follow the procedure for that message. Other DSN messages can also
be issued.

Message ID Procedure to use

DSNJ001I “Recovering from failure during log initialization or current status
rebuild” on page 540
DSNJ100I “Recovering from unresolvable BSDS or log data set problem during
restart” on page 561

Chapter 13. Recovering from different Db2 for z/OS problems 539
 Message ID Procedure to use
DSNJ107 “Recovering from unresolvable BSDS or log data set problem during
restart” on page 561
DSNJ1191 “Recovering from unresolvable BSDS or log data set problem during
restart” on page 561
DSNR002I None. Normal restart processing can be expected.
DSNR004I “Recovering from a failure during forward log recovery” on page 552
DSNR005I “Recovering from a failure during backward log recovery” on page 557
DSNR006I None. Normal restart processing can be expected.
Other “Recovering from failure during log initialization or current status
rebuild”

Another procedure (“Recovering from a failure resulting from total or excessive

loss of log data” on page 563) provides information to use if you determine (by
using “Recovering from failure during log initialization or current status rebuild”)
that an excessive amount (or all) of Db2 log information (BSDS, active, and archive
logs) has been lost.

The last procedure,“Resolving inconsistencies resulting from a conditional restart”

on page 567, can be used to resolve inconsistencies introduced while using one of
the restart procedures in this information. If you decide to use “Recovering from
unresolvable BSDS or log data set problem during restart” on page 561, you do not
need to use “Resolving inconsistencies resulting from a conditional restart” on
page 567.

Because of the severity of the situations described, the procedures identify

“Operations management action”, rather than “Operator action”. Operations
management might not be performing all the steps in the procedures, but they
must be involved in making the decisions about the steps to be performed.
Related reference:
DSN1LOGP (Db2 Utilities)

Recovering from failure during log initialization or current

status rebuild
When a failure occurs during the log initialization phase or the current status
rebuild phase of restart, you need to recover from this situation.

Symptoms
An abend was issued, indicating that restart failed. In addition, either the last
restart message that was received was a DSNJ001I message that indicates a failure
during current status rebuild, or none of the following messages was issued:
v DSNJ001I
v DSNR004I
v DSNR005I

If none of the preceding messages was issued, the failure occurred during the log
initialization phase of restart.

Environment

540 Administration Guide

What happens in the environment depends on whether the failure occurred during
log initialization or current status rebuild.
Failure during log initialization
Db2 terminates because a portion of the log is inaccessible, and Db2 cannot
locate the end of the log during restart.
Failure during current status rebuild
Db2 terminates because a portion of the log is inaccessible, and Db2 cannot
determine the state of the subsystem at the prior Db2 termination. Possible
states include: outstanding units of recovery, outstanding database writes,
and exception database conditions.

Resolving the problem

Operations management response: To correct the problem, choose one of the
following approaches:
v Correct the problem that has made the log inaccessible, and start Db2 again. To
determine if this approach is possible, read the relevant information about the
messages and codes that you received. The explanations for the messages and
codes identify the corrective action that can be taken to resolve the problem.
v Restore the Db2 log and all data to a prior consistent point, and then start Db2.
This procedure is described in “Recovering from unresolvable BSDS or log data
set problem during restart” on page 561.
v Start Db2 without completing some database changes. Using a combination of
Db2 services and your own knowledge, determine what work is likely to be lost
if you truncate the log. The procedure for determining the page sets that contain
incomplete changes is described in “Restarting Db2 by truncating the log” on
page 543.

Failure during log initialization phase

When a failure occurs during the log initialization phase, certain characteristics of
the situation are evident.

The following figure illustrates the timeline of events that exist when a failure
occurs during the log initialization phase.

Log Start Begin URID1 Begin URID3 Log Error

Time
line

Page Set B Checkpoint RBA: X Y

Figure 49. Failure during log initialization

The portion of the log between log RBAs X and Y is inaccessible. For failures that
occur during the log initialization phase, the following activities occur:
1. Db2 allocates and opens each active log data set that is not in a stopped state.
2. Db2 reads the log until the last log record is located.
3. During this process, a problem with the log is encountered, preventing Db2
from locating the end of the log. Db2 terminates and issues an abend reason
code. Some of the abend reason codes that might be issued include:
v 00D10261
v 00D10262
v 00D10263
v 00D10264

Chapter 13. Recovering from different Db2 for z/OS problems 541
 v 00D10265
v 00D10266
v 00D10267
v 00D10268
v 00D10329
v 00D1032A
v 00D1032B
v 00D1032C
v 00E80084

During its operations, Db2 periodically records in the BSDS the RBA of the last log
record that was written. This value is displayed in the print log map report as
follows:
HIGHEST RBA WRITTEN: 00000742989E

Because this field is updated frequently in the BSDS, the “highest RBA written”
can be interpreted as an approximation of the end of the log. The field is updated
in the BSDS when any one of a variety of internal events occurs. In the absence of
these internal events, the field is updated each time a complete cycle of log buffers
is written. A complete cycle of log buffers occurs when the number of log buffers
that are written equals the value of the OUTPUT BUFFER field of installation
panel DSNTIPL. The value in the BSDS is, therefore, relatively close to the end of
the log.

To find the actual end of the log at restart, Db2 reads the log forward sequentially,
starting at the log RBA that approximates the end of the log and continuing until
the actual end of the log is located.

Because the end of the log is inaccessible in this case, some information is lost:
v Units of recovery might have successfully committed or modified additional
page sets past point X.
v Additional data might have been written, including those that are identified
with writes that are pending in the accessible portion of the log.
v New units of recovery might have been created, and these might have modified
data.

Because of the log error, Db2 cannot perceive these events.

A restart of Db2 in this situation requires truncation of the log.

Related tasks
Restarting Db2 by truncating the log

Description of failure during current status rebuild

When a failure occurs during current status rebuild, certain characteristics of the
situation are evident.

The following figure illustrates the timeline of events that exist when a failure
occurs during current status rebuild.

542 Administration Guide

 Log Start Begin URID1 Begin URID3 Log Error Log End

Time
line

Page Set B Checkpoint RBA: X Y

Figure 50. Failure during current status rebuild

The portion of the log between log RBAs X and Y is inaccessible. For failures that
occur during the current status rebuild phase, the following activities occur:
1. Log initialization completes successfully.
2. Db2 locates the last checkpoint. (The BSDS contains a record of its location on
the log.)
3. Db2 reads the log, beginning at the checkpoint and continuing to the end of the
log.
4. Db2 reconstructs the status of the subsystem as it existed at the prior
termination of Db2.
5. During this process, a problem with the log is encountered, preventing Db2
from reading all required log information. Db2 terminates and issues an abend
reason code. Some of the abend reason codes that might be issued include:
v 00D10261
v 00D10262
v 00D10263
v 00D10264
v 00D10265
v 00D10266
v 00D10267
v 00D10268
v 00D10329
v 00D1032A
v 00D1032B
v 00D1032C
v 00E80084

Because the end of the log is inaccessible in this case, some information is lost:
v Units of recovery might have successfully committed or modified additional
page sets past point X.
v Additional data might have been written, including those that are identified
with writes that are pending in the accessible portion of the log.
v New units of recovery might have been created, and these might have modified
data.

Because of the log error, Db2 cannot perceive these events.

A restart of Db2 in this situation requires truncation of the log.

Related tasks
Restarting Db2 by truncating the log

Restarting Db2 by truncating the log

A portion of the log is inaccessible during the log initialization or current status
rebuild phases of restart. When the log is inaccessible, Db2 cannot identify

Chapter 13. Recovering from different Db2 for z/OS problems 543
 precisely what units of recovery failed to complete, what page sets had been
modified, and what page sets have writes pending. You need to gather that
information, and restart Db2.

Task 1: Find the log RBA after the inaccessible part of the log:

The first task in restarting Db2 by truncating the log is to locate the log RBA after
the inaccessible part of the log.

About this task

The range of the log between RBAs X and Y is inaccessible to all Db2 processes.

Procedure

To find the RBA after the inaccessible part of the log, take the action that is
associated with the message number that you received (DSNJ007I, DSNJ012I,
DSNJ103I, DSNJ104I, DSNJ106I, and DSNJ113E):
v When message DSNJ007I is issued:
The problem is that an operator canceled a request for archive mount. Reason
code 00D1032B is associated with this situation and indicates that an entire data
set is inaccessible.
For example, the following message indicates that the archive log data set
DSNCAT.ARCHLOG1.A0000009 is not accessible. The operator canceled a
request for archive mount, resulting in the following message:
DSNJ007I OPERATOR CANCELED MOUNT OF ARCHIVE
DSNCAT.ARCHLOG1.A0000009 VOLSER=5B225.
To determine the value of X, run the print log map utility (DSNJU004) to list the
log inventory information. The output of this utility provides each log data set
name and its associated log RBA range, the values of X and Y.
v When message DSNJ012I is issued:
The problem is that a log record is logically damaged. Message DSNJ012I
identifies the log RBA of the first inaccessible log record that Db2 detects. The
following reason codes are associated with this situation:
– 00D10261
– 00D10262
– 00D10263
– 00D10264
– 00D10265
– 00D10266
– 00D10267
– 00D10268
– 00D10348
For example, the following message indicates a logical error in the log record at
log RBA X'7429ABA'.
DSNJ012I ERROR D10265 READING RBA 000007429ABA
IN DATA SET DSNCAT.LOGCOPY2.DS01
CONNECTION-ID=DSN,
CORRELATION-ID=DSN
A given physical log record is actually a set of logical log records (the log
records that are generally spoken of) and the log control interval definition
(LCID). Db2 stores logical records in blocks of physical records to improve
efficiency. When this type of an error on the log occurs during log initialization
or current status rebuild, all log records within the physical log record are

544 Administration Guide

 inaccessible. Therefore, the value of X is the log RBA that was reported in the
message, rounded down to a 4-KB boundary. (For the example message above,
the rounded 4-KB boundary value would be X'7429000'.)
v When message DSNJ103I or DSNJ104I is issued:
For message DSNJ103I, the underlying problem depends on the reason code that
is issued:
– For reason code 00D1032B, an allocation error occurred for an archive log
data set.
– For reason code 00E80084, an active log data set that is named in the BSDS
could not be allocated during log initialization.
For message DSNJ104I, the underlying problem is that an open error occurred
for an archive and active log data set.
In any of these cases, the message that accompanies the abend identifies an
entire data set that is inaccessible. For example, the following DSNJ103I message
indicates that the archive log data set DSNCAT.ARCHLOG1.A0000009 is not
accessible. The STATUS field identifies the code that is associated with the
reason for the data set being inaccessible.
DSNJ103I - csect-name LOG ALLOCATION ERROR
DSNAME=DSNCAT.ARCHLOG1.A0000009,ERROR
STATUS=04980004
SMS REASON CODE=reasond-code
To determine the value of X, run the print log map utility (DSNJU004) to list the
log inventory information. The output of the utility provides each log data set
name and its associated log RBA range, the values of X and Y.
Verify the accuracy of the information in the print log map utility output for the
active log data set with the lowest RBA range. For this active log data set only,
the information in the BSDS is potentially inaccurate for the following reasons:
– When an active log data set is full, archiving is started. Db2 then selects
another active log data set, usually the data set with the lowest RBA. This
selection is made so that units of recovery do not need to wait for the archive
operation to complete before logging can continue. However, if a data set has
not been archived, nothing beyond it has been archived, and the procedure is
ended.
– When logging begins on a reusable data set, Db2 updates the BSDS with the
new log RBA range for the active log data set and marks it as “Not
Reusable.” The process of writing the new information to the BSDS might be
delayed by other processing. Therefore, a possible outcome is for a failure to
occur between the time that logging to a new active log data set begins and
the time that the BSDS is updated. In this case, the BSDS information is not
correct.
If the data set is marked “Not Reusable,” the log RBA that appears for the active
log data set with the lowest RBA range in the print log map utility output is
valid. If the data set is marked “Reusable,” you can assume for the purposes of
this restart that the starting log RBA (X) for this data set is one greater than the
highest log RBA that is listed in the BSDS for all other active log data sets.
v When message DSNJ106I is issued:
The problem is that an I/O error occurred while a log record was being read.
The message identifies the log RBA of the first inaccessible log record that Db2
detects. Reason code 00D10329 is associated with this situation.
For example, the following message indicates an I/O error in the log at RBA
X'7429ABA'.
DSNJ106I LOG READ ERROR DSNAME=DSNCAT.LOGCOPY2.DS01,
LOGRBA=000007429ABA,ERROR STATUS=0108320C

Chapter 13. Recovering from different Db2 for z/OS problems 545
 A given physical log record is actually a set of logical log records (the log
records that are generally spoken of) and the log control interval definition
(LCID). When this type of an error on the log occurs during log initialization or
current status rebuild, all log records within the physical log record, and beyond
it to the end of the log data set, are inaccessible. This is due to the log
initialization or current status rebuild phase of restart. Therefore, the value of X
is the log RBA that was reported in the message, rounded down to a 4-KB
boundary. (For the example message above, the rounded 4-KB boundary value
would be X'7429000'.)
v When message DSNJ113E is issued:
The problem is that the log RBA could not be found in the BSDS. Message
DSNJ113E identifies the log RBA of the inaccessible log record. This log RBA is
not registered in the BSDS. Reason code 00D1032B is associated with this
situation.
For example, the following message indicates that the log RBA X'7429ABA' is
not registered in the BSDS:
DSNJ113E RBA 000007429ABA NOT IN ANY ACTIVE OR ARCHIVE
LOG DATA SET. CONNECTION-ID=DSN, CORRELATION-ID=DSN
Use the print log map utility (DSNJU004) to list the contents of the BSDS.
A given physical log record is actually a set of logical log records (the log
records that are generally spoken of) and the log control interval definition
(LCID). When this type of an error on the log occurs during log initialization or
current status rebuild, all log records within the physical log record are
inaccessible.
Using the print log map output, locate the RBA that is closest to, but less than,
X'7429ABA' for the value of X. If you do not find an RBA that is less than
X'7429ABA', a considerable amount of log information has been lost. If this is
the case, continue with “Recovering from a failure resulting from total or
excessive loss of log data” on page 563. Otherwise, continue with the next topic.
Related concepts
Description of failure during current status rebuild
Failure during log initialization phase
Related reference
DSNJU004 (print log map) (Db2 Utilities)
Related information
DSNJ007I (Db2 Messages)
DSNJ012I (Db2 Messages)
DSNJ103I (Db2 Messages)
DSNJ104I (Db2 Messages)
DSNJ106I (Db2 Messages)
DSNJ113E (Db2 Messages)

Task 2: Identify lost work and inconsistent data:

In certain recovery situations (such as when you recover by truncating the log),
you need to identify what work was lost and what data is inconsistent.

546 Administration Guide

Procedure

To identify lost work and inconsistent data:

1. Obtain available information to help you determine the extent of the loss. Db2
cannot determine what units of recovery are not completed, what database
state information is lost, or what data is inconsistent in this situation. The log
contains all such information, but the information is not available. The steps
below explain what to do to obtain the information that is available within Db2
to help you determine the extent of the loss. The steps also explain how to start
Db2 in this situation.
After restart, data is inconsistent. Results of queries and any other operations
on such data vary from incorrect results to abends. Abends that occur either
identify an inconsistency in the data or incorrectly assume the existence of a
problem in the Db2 internal algorithms.
Attention: If the inconsistent page sets are not identified and the problems in
them are not resolved after starting Db2, be aware that following this procedure
and allowing access to inconsistent data involves some risk.
a. Run the print log map utility. The report that the utility produces includes a
description of the last 100 checkpoints and provides, for each checkpoint the
following information:
v The location in the log of the checkpoint (begin and end RBA)
v The date and time of day that the checkpoint was performed
b. Locate the checkpoint on the log prior to the point of failure (X). Do that by
finding the first checkpoint with an end RBA that is less than X.
Continue with the step 2 unless one of the following conditions exists:
v You cannot find such a checkpoint. This means that a considerable
amount of log has been lost.
v You find the checkpoint, but the checkpoint is several days old, and Db2
has been operational during the interim.
In these two cases, use one of the following procedures:
v “Recovering from a failure resulting from total or excessive loss of log
data” on page 563
v “Recovering from unresolvable BSDS or log data set problem during
restart” on page 561
2. Determine what work is lost and what data is inconsistent. The portion of the
log that represents activity that occurred before the failure provides information
about work that was in progress at that point. From this information, you
might be able to deduce what work was in progress within the inaccessible
portion of the log. If use of Db2 was limited at the time or if Db2 was
dedicated to a small number of activities (such as batch jobs that perform
database loads or image copies), you might be able to accurately identify the
page sets that were made inconsistent. To make the identification, extract a
summary of the log activity up to the point of damage in the log by using the
DSN1LOGP utility.
v Use the DSN1LOGP utility to specify the “BEGIN CHECKPOINT” RBA prior
to the point of failure, which was determined in the previous task as the
RBASTART. Terminate the DSN1LOGP scan prior to the point of failure on
the log (X - 1) by using the RBAEND specification.
v Specify the last complete checkpoint. This is very important for ensuring that
complete information is obtained from DSN1LOGP.
v Specify the SUMMARY(ONLY) option to produce a summary report.

Chapter 13. Recovering from different Db2 for z/OS problems 547
 The following figure is an example of a DSN1LOGP job that obtains summary
information for the checkpoint that was described previously.

//ONE EXEC PGM=DSN1LOGP

//STEPLIB DD DSN=prefix.SDSNLOADSDSNLOAD,DISP=SHR
//SYSABEND DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
//SYSSUMRY DD SYSOUT=A
//BSDS DD DSN=DSNCAT.BSDS01,DISP=SHR
//SYSIN DD *
RBASTART (7425468) RBAEND (7428FFF) SUMMARY (ONLY)
/*

Figure 51. Sample JCL for obtaining DSN1LOGP summary output for restart

3. Analyze the DSN1LOGP utility output.

Related reference
DSN1LOGP (Db2 Utilities)

DSN1LOGP summary report:

The DSN1LOGP utility generates a summary report, which is placed in the

SYSSUMRY file. The report includes a summary of completed events and a restart
summary. You can use the information in this report to identify lost work and
inconsistent data that needs to be resolved.

The following figure shows an excerpt from the restart summary in a sample
DSN1LOGP summary report. The report is described after the figure.

| DSN1157I RESTART SUMMARY

| DSN1153I DSN1LSIT CHECKPOINT MEMBER=DB2A
| STARTRBA=0000000000002BBB8CAC ENDRBA=0000000000002BBC59E8
| STARTLRSN=00CA21F58479D042C000 ENDLRSN=00CA21F58480E67E4000
| DATE=12.250 TIME=14:20:29
|
| DSN1162I DSN1LPRT MEMBER=DB2A UR CONNID=BATCH CORRID=ARCHIVE AUTHID=SYSADM PLAN=ARCHIVE
| START DATE=00.161 TIME=11:27:30 DISP=INFLIGHT INFO=COMPLETE
| STARTRBA=0000000000002BBC888E STARTLRSN=00CA21F5849D6B88E000 NID=*
| LUWID=DSNCAT.SYEC1DB2.CA21F58084CF.0003 COORDINATOR=*
| PARTICIPANTS=*
| DATA MODIFIED:
| DATABASE=0119=JACKDB PAGE SET=0002=JACKTS
| DATABASE=0119=JACKDB PAGE SET=0005=TESTIX
|
| DSN1160I DATABASE WRITES PENDING:
| DATABASE=0001=DSNDB01 PAGE SET=0008=DSNDB01X START=0000000000002BB8BC60
| DATABASE=0001=DSNDB01 PAGE SET=001F=DBD01 START=0000000000002BB8BED8
| DATABASE=0006=DSNDB06 PAGE SET=006C=DSNADX01 START=0000000000002BB8EE55
| DATABASE=0006=DSNDB06 PAGE SET=0787=DSNADH02 START=0000000000002BB8E858
| DATABASE=0006=DSNDB06 PAGE SET=0076=DSNUCX01
| ....

Figure 52. Partial sample of DSN1LOGP summary output

The following message acts as a heading, which is followed by messages that

identify the units of recovery that have not yet completed and the page sets that
they modified:
DSN1157I RESTART SUMMARY

Following the summary of outstanding units of recovery is a summary of page sets

that have database writes that are pending.

548 Administration Guide

In each case (units of recovery or databases with pending writes), the earliest
required log record is identified by the START information. In this context, START
information is the log RBA of the earliest log record that is required in order to
complete outstanding writes for this page set.

Those units of recovery with a START log RBA equal to, or prior to, the point Y
cannot be completed at restart. All page sets that were modified by these units of
recovery are inconsistent after completion of restart when you attempt to identify
lost work and inconsistent data.

All page sets that are identified in message DSN1160I with a START log RBA value
equal to, or prior to, the point Y have database changes that cannot be written to
disk. As in the previously described case, all of these page sets are inconsistent
after completion of restart when you attempt to identify lost work and inconsistent
data.

At this point, you need to identify only the page sets in preparation for restart.
After restart, you need to resolve the problems in the page sets that are
inconsistent.

Because the end of the log is inaccessible, some information is lost; therefore, the
information is inaccurate. Some of the units of recovery that appear to be inflight
might have successfully committed, or they might have modified additional page
sets beyond point X. Additional data might have been written, including those
page sets that are identified as having pending writes in the accessible portion of
the log. New units of recovery might have been created, and these might have
modified data. Db2 cannot detect that these events occurred.

From this and other information (such as system accounting information and
console messages), you might be able to determine what work was actually
outstanding and which page sets are likely to be inconsistent after you start Db2.
This is because the record of each event contains the date and time to help you
determine how recent the information is. In addition, the information is displayed
in chronological sequence.

Task 3: Determine what status information is lost:

The third task in restarting Db2 by truncating the log is to determine what status
information has been lost.

About this task

Depending on what was going on in your environment before the problem

occurred, some amount of system status information might have been lost.

Procedure

To determine what system status information is lost:

1. If you already know what system status information is lost (such as in the case
in which utilities are in progress), you do not need to do anything. Continue
with the next topic.
2. If you do not already know what system status information is lost, examine all
relevant messages that provide details about the loss of status information
(such as in the cases of deferred restart pending or write error ranges). If the
messages provide adequate information about what information is lost, you do
not need to do anything more. Continue with the next step.
Chapter 13. Recovering from different Db2 for z/OS problems 549
 3. If you find that all system status information is lost, try to reconstruct this
information from recent console displays, messages, and abends that alerted
you to these conditions. These page sets contain inconsistencies that you must
resolve.

Task 4: Truncate the log at the point of error:

The fourth task in restarting Db2 by truncating the log is to truncate the log at the
point of error.

About this task

No Db2 process, including the RECOVER utility, allows a gap in the log RBA
sequence. You cannot process up to point X, skip over points X through Y, and
continue after Y.

Procedure

To truncate the log at the point of error:

Create a conditional restart control record (CRCR) in the BSDS by using the change
log inventory utility. Specify the following options:
ENDRBA=endrba
The endrba value is the RBA at which Db2 begins writing new log records.
If point X is X'7429000', specify ENDRBA=7429000 on the CRESTART
control statement.
At restart, Db2 discards the portion of the log beyond X'7429000' before
processing the log for completing work (such as units of recovery and
database writes). Unless otherwise directed, Db2 performs normal restart
processing within the scope of the log. Because log information is lost, Db2
errors might occur. For example, a unit of recovery that has actually been
committed might be rolled back. Also, some changes that were made by
that unit of recovery might not be rolled back because information about
data changes is lost.
FORWARD=NO
Terminates forward-log recovery before log records are processed. This
option and the BACKOUT=NO option minimize errors that might result
from normal restart processing.
BACKOUT=NO
Terminates backward-log recovery before log records are processed. This
option and the FORWARD=NO option minimize errors that might result
from normal restart processing.

Results

Recovering and backing out units of recovery with lost information might
introduce more inconsistencies than the incomplete units of recovery.

Example

The following example is a CRESTART control statement for the ENDRBA value of
X'7429000':
CRESTART CREATE,ENDRBA=7429000,FORWARD=NO,BACKOUT=NO

550 Administration Guide

Task 5: Start Db2 and resolve data inconsistencies:

The final task in restarting Db2 by truncating the log is to restart Db2 and resolve
inconsistencies.

Before you begin

You must have a CRESTART control statement with the correct ENDRBA value
and the FORWARD and BACKOUT options set to NO.

Procedure

To start Db2 and resolve data inconsistencies:

1. Start Db2 with the following command:
-START DB2 ACCESS (MAINT)
In response to this command, Db2 performs the following actions:
v Discards from the checkpoint queue any entries with RBAs that are beyond
the ENDRBA value in the CRCR (for example, X'7429000').
v Reconstructs the system status up to the point of log truncation.
v Performs pending database writes that the truncated log specifies and that
have not already been applied to the data. You can use the DSN1LOGP
utility to identify these writes. No forward recovery processing occurs for
units of work in a FORWARD=NO conditional restart. All pending writes for
in-commit and indoubt units of recovery are applied to the data. The
standard forward-log recovery processing for the different unit of work states
does not occur.
v Marks all units of recovery that have committed or are indoubt as complete
on the log.
v Leaves inflight and in-abort units of recovery incomplete. Inconsistent data is
left in tables that are modified by inflight or indoubt units of recovery. When
you specify a BACKOUT=NO conditional restart, inflight and in-abort units
of recovery are not backed out.
In a conditional restart that truncates the log, BACKOUT=NO minimizes Db2
errors for the following reasons:
– Inflight units of recovery might have been committed in the portion of the
log that the conditional restart discarded. If these units of recovery are
backed out (as would be normal during backward-log recovery) Db2
might back out database changes incompletely, which introduces
additional errors.
– Data that is modified by in-abort units of recovery might have been
modified again after the point of damage on the log. For in-abort units of
recovery, Db2 might have written backout processing to disk after the
point of log truncation. If these units of recovery are backed out (as would
be normal during backward-log recovery), Db2 might introduce additional
data inconsistencies by backing out units of recovery that are already
partially or fully backed out.
At the end of restart, the conditional restart control record (CRCR) is marked
“Deactivated” to prevent its use on a later restart. Until the restart completes
successfully, the CRCR is in effect. Until data is consistent or page sets are
stopped, start Db2 with the ACCESS (MAINT) option.
2. Resolve all data inconsistency problems.
Related concepts

Chapter 13. Recovering from different Db2 for z/OS problems 551
 Phase 4: Backward log recovery
Phase 3: Forward log recovery
Related tasks
Resolving inconsistencies resulting from a conditional restart

Recovering from a failure during forward log recovery

If a failure occurs during the forward-log recovery phase of restart, operations
management can recover from this situation.

Symptoms
A Db2 abend occurred, indicating that restart had failed. In addition, the last
restart message that was received was a DSNR004I message, which indicates that
log initialization completed; therefore, the failure occurred during forward log
recovery.

Environment
Db2 terminates because a portion of the log is inaccessible, and Db2 is therefore
unable to guarantee the consistency of the data after restart.

Resolving the problem

Operations management response: To start Db2 successfully, choose one of the
following approaches:
v Read the information about relevant messages and codes that you received to
determine if this approach is possible. The explanations of the messages and
codes identify any corrective action that you can take to resolve the problem. If
it is possible, correct the problem that made the log inaccessible, and start Db2
again.
v Restore the Db2 log and all data to a prior consistent point and start Db2. This
procedure is described in “Recovering from unresolvable BSDS or log data set
problem during restart” on page 561.
v Start Db2 without completing some database changes. Do this only if the exact
changes cannot be identified; all that can be determined is which page sets
might have incomplete changes and which units of recovery made modifications
to those page sets. The procedure for determining which page sets contain
incomplete changes and which units of recovery made the modifications is
described in “Recovering from BSDS or log failures during restart” on page 537.
Other topics might help you better understand the problem.

Forward-log recovery failure

When a failure occurs during the forward-log recovery phase of Db2 restart,
certain characteristics of the situation are evident.

The following figure illustrates the events surrounding a failure during the
forward-log recovery phase of Db2 restart.

Log Begin Begin Begin Begin Log

Start URID1 URID2 Log Error URID3 URID4 End

Time
line

Page RBA: X Y Page Checkpoint

Set A Set B

Figure 53. Illustration of failure during forward-log recovery

552 Administration Guide

The portion of the log between log RBA X and Y is inaccessible. The log
initialization and current status rebuild phases of restart completed successfully.
Restart processing was reading the log in a forward direction, beginning at some
point prior to X and continuing to the end of the log. Because of the inaccessibility
of log data (between points X and Y), restart processing cannot guarantee the
completion of any work that was outstanding at restart prior to point Y.

Assume that the following work was outstanding at restart:

v The unit of recovery that is identified as URID1 was in-commit.
v The unit of recovery that is identified as URID2 was inflight.
v The unit of recovery that is identified as URID3 was in-commit.
v The unit of recovery that is identified as URID4 was inflight.
v Page set A had writes that were pending prior to the error on the log,
continuing to the end of the log.
v Page set B had writes that were pending after the error on the log, continuing to
the end of the log.

The earliest log record for each unit of recovery is identified on the log line in
Figure 53 on page 552. In order for Db2 to complete each unit of recovery, Db2
requires access to all log records from the beginning point for each unit of recovery
to the end of the log.

The error on the log prevents Db2 from guaranteeing the completion of any
outstanding work that began prior to point Y on the log. Consequently, database
changes that are made by URID1 and URID2 might not be fully committed or
backed out. Writes that were pending for page set A (from points in the log prior
to Y) are lost.

Starting Db2 by limiting restart processing

When a portion of the log is inaccessible during forward recovery, starting Db2 is
possible. You need to identify the units of recovery for which database changes
cannot be fully guaranteed (either committed or backed out). You also need to
identify the page sets that these units of recovery changed.

About this task

You must determine which page sets are involved because after this procedure is
used, the page sets will contain inconsistencies that you must resolve. In addition,
using this procedure results in the completion of all database writes that are
pending.
Related concepts
Write operations (Db2 Performance)

Task 1: Find the log RBA after the inaccessible part of the log:

The first task in restarting Db2 by limiting restart processing is to locate the log
RBA that is after the inaccessible part of the log.

About this task

The range of the log between RBAs X and Y is inaccessible to all Db2 processes.

Chapter 13. Recovering from different Db2 for z/OS problems 553
 Procedure

To find the RBA after the inaccessible part of the log, take the action that is
associated with the message number that you received (DSNJ007I, DSNJ012I,
DSNJ103I, DSNJ104I, DSNJ106I, and DSNJ113E):
v When message DSNJ007I is issued:
The problem is that an operator canceled a request for archive mount. Reason
code 00D1032B is associated with this situation and indicates that an entire data
set is inaccessible.
For example, the following message indicates that the archive log data set
DSNCAT.ARCHLOG1.A0000009 is not accessible. The operator canceled a
request for archive mount, resulting in the following message:
DSNJ007I OPERATOR CANCELED MOUNT OF ARCHIVE
DSNCAT.ARCHLOG1.A0000009 VOLSER=5B225.
To determine the value of X, run the print log map utility (DSNJU004) to list the
log inventory information. The output of this utility provides each log data set
name and its associated log RBA range, the values of X and Y.
v When message DSNJ012I is issued:
The problem is that a log record is logically damaged. Message DSNJ012I
identifies the log RBA of the first inaccessible log record that Db2 detects. The
following reason codes are associated with this situation:
– 00D10261
– 00D10262
– 00D10263
– 00D10264
– 00D10265
– 00D10266
– 00D10267
– 00D10268
– 00D10348
For example, the following message indicates a logical error in the log record at
log RBA X'7429ABA'.
DSNJ012I ERROR D10265 READING RBA 000007429ABA
IN DATA SET DSNCAT.LOGCOPY2.DS01
CONNECTION-ID=DSN,
CORRELATION-ID=DSN
A given physical log record is actually a set of logical log records (the log
records that are generally spoken of) and the log control interval definition
(LCID). Db2 stores logical records in blocks of physical records to improve
efficiency. When this type of an error on the log occurs during forward log
recovery, all log records within the physical log record are inaccessible.
Therefore, the value of X is the log RBA that was reported in the message,
rounded down to a 4-KB boundary. (For the example message above, the
rounded 4-KB boundary value would be X'7429000'.)
v When message DSNJ103I or DSNJ104I is issued:
For message DSNJ103I, the underlying problem depends on the reason code that
is issued:
– For reason code 00D1032B, an allocation error occurred for an archive log
data set.
– For reason code 00E80084, an active log data set that is named in the BSDS
could not be allocated during log initialization.
For message DSNJ104I, the underlying problem is that an open error occurred
for an archive and active log data set.

554 Administration Guide

 In any of these cases, the message that accompanies the abend identifies an
entire data set that is inaccessible. For example, the following DSNJ103I message
indicates that the archive log data set DSNCAT.ARCHLOG1.A0000009 is not
accessible. The STATUS field identifies the code that is associated with the
reason for the data set being inaccessible.
DSNJ103I - csect-name LOG ALLOCATION ERROR
DSNAME=DSNCAT.ARCHLOG1.A0000009,ERROR
STATUS=04980004
SMS REASON CODE=reasond-code
To determine the value of X, run the print log map utility (DSNJU004) to list the
log inventory information. The output of the utility provides each log data set
name and its associated log RBA range, the values of X and Y.
v When message DSNJ106I is issued:
The problem is that an I/O error occurred while a log record was being read.
The message identifies the log RBA of the first inaccessible log record that Db2
detects. Reason code 00D10329 is associated with this situation.
For example, the following message indicates an I/O error in the log at RBA
X'7429ABA'.
DSNJ106I LOG READ ERROR DSNAME=DSNCAT.LOGCOPY2.DS01,
LOGRBA=000007429ABA,ERROR STATUS=0108320C
A given physical log record is actually a set of logical log records (the log
records that are generally spoken of) and the log control interval definition
(LCID). When this type of an error on the log occurs during forward log
recovery, all log records within the physical log record, and beyond it to the end
of the log data set, are inaccessible to the forward log recovery phase of restart.
This is due to the log initialization or current status rebuild phase of restart.
Therefore, the value of X is the log RBA that was reported in the message,
rounded down to a 4-KB boundary. (For the example message above, the
rounded 4-KB boundary value would be X'7429000'.)
v When message DSNJ113E is issued:
The problem is that the log RBA could not be found in the BSDS. Message
DSNJ113E identifies the log RBA of the inaccessible log record. This log RBA is
not registered in the BSDS. Reason code 00D1032B is associated with this
situation.
For example, the following message indicates that the log RBA X'7429ABA' is
not registered in the BSDS:
DSNJ113E RBA 000007429ABA NOT IN ANY ACTIVE OR ARCHIVE
LOG DATA SET. CONNECTION-ID=DSN, CORRELATION-ID=DSN
Use the print log map utility (DSNJU004) to list the contents of the BSDS.
A given physical log record is actually a set of logical log records (the log
records that are generally spoken of) and the log control interval definition
(LCID). When this type of an error on the log occurs during forward log
recovery, all log records within the physical log record are inaccessible.
Using the print log map output, locate the RBA that is closest to, but less than,
X'7429ABA' for the value of X. If you do not find an RBA that is less than
X'7429ABA', the value of X is zero. Locate the RBA that is closest to, by greater
than, X'7429ABA'. This is the value of Y.
Related concepts
Forward-log recovery failure
Related reference
DSNJU004 (print log map) (Db2 Utilities)
Related information

Chapter 13. Recovering from different Db2 for z/OS problems 555
 DSNJ007I (Db2 Messages)
DSNJ012I (Db2 Messages)
DSNJ103I (Db2 Messages)
DSNJ104I (Db2 Messages)
DSNJ106I (Db2 Messages)
DSNJ113E (Db2 Messages)

Task 2: Identify incomplete units of recovery and inconsistent page sets:

The second task in restarting Db2 by limiting restart processing is to identify

incomplete units of recovery and inconsistent page sets.

About this task

Units of recovery that cannot be fully processed are considered incomplete units of
recovery. Page sets that will be inconsistent after completion of restart are
considered inconsistent page sets.

Procedure

To identify incomplete units of recovery and inconsistent page sets:

1. Determine the location of the latest checkpoint on the log by looking at one of
the following sources, whichever is more convenient:
v The operator's console contains the following message, identifying the
location of the start of the last checkpoint on the log at log RBA X'876B355'.
For example:
DSNR003I RESTART ... PRIOR CHECKPOINT
RBA=00007425468
v The print log map utility output identifies the last checkpoint, including its
BEGIN CHECKPOINT RBA
2. Obtain a report of the outstanding work that is to be completed at the next
restart of Db2 by running the DSN1LOGP utility. When you run the
DSN1LOGP utility, specify the checkpoint RBA as the STARTRBA and the
SUMMARY(ONLY) option. In order to obtain complete information, be sure to
include the last complete checkpoint from running DSN1LOGP.
3. Analyze the output of the DSN1LOGP utility. The summary report that is
placed in the SYSSUMRY file contains two sections of information: a complete
summary of completed events and a restart summary.
Related concepts
DSN1LOGP summary report
Related reference
DSN1LOGP (Db2 Utilities)

Task 3: Restrict restart processing to the part of the log after the damage:

The third task in restarting Db2 by limiting restart processing is to restrict restart
processing to the part of the log that is after the damage.

556 Administration Guide

 Procedure

To restrict restart processing to the part of the log after the damage:
1. Create a conditional restart control record (CRCR) in the BSDS by using the
change log inventory utility.
2. Identify the accessible portion of the log beyond the damage by using the
STARTRBA specification, which will be used at the next restart.
3. Specify the value Y+1 (that is, if Y is X'7429FFF', specify STARTRBA=742A000).
Restart restricts its processing to the portion of the log beginning with the
specified STARTRBA and continuing to the end of the log. For example:
CRESTART CREATE,STARTRBA=742A000

Task 4: Start Db2 and resolve inconsistent data:

The final task in restarting Db2 by limiting restart processing is to start Db2 and
resolve problems with inconsistent data.

About this task

At the end of restart, the CRCR is marked DEACTIVATED to prevent its use on a
subsequent restart. Until the restart is complete, the CRCR will be in effect. Use
START DB2 ACCESS(MAINT) until data is consistent or page sets are stopped.

Procedure

To start Db2 and resolve data inconsistencies:

1. Start Db2 with the following command:
-START DB2 ACCESS (MAINT)

At the end of restart, the conditional restart control record (CRCR) is marked
“Deactivated” to prevent its use on a later restart. Until the restart completes
successfully, the CRCR is in effect. Until data is consistent or page sets are
stopped, start Db2 with the ACCESS (MAINT) option.
2. Resolve all data inconsistency problems.
Related tasks
Resolving inconsistencies resulting from a conditional restart

Recovering from a failure during backward log recovery

When a failure occurs during backward log recovery, Db2 terminates because it
cannot access a portion of the log that it needs. Operations management can
recover from this situation.

Symptoms
An abend is issued to indicate that restart failed because of a log problem. In
addition, the last restart message that is received is a DSNR005I message,
indicating that forward log recovery completed and that the failure occurred
during backward log recovery.

Environment
Because a portion of the log is inaccessible, Db2 needs to roll back some database
changes during restart.

Resolving the problem

Chapter 13. Recovering from different Db2 for z/OS problems 557
 Operations management response: To start Db2, choose one of the following
approaches:
v Read the information about relevant messages and codes that you received to
determine if this approach is possible. The explanations of the messages and
codes identify any corrective action that you can take to resolve the problem. If
it is possible, correct the problem that made the log inaccessible, and start Db2
again.
v Restore the Db2 log and all data to a prior consistent point and start Db2. This
procedure is described in “Recovering from unresolvable BSDS or log data set
problem during restart” on page 561.
v Start Db2 without completing some database changes. Do this only if the exact
changes cannot be identified; all that can be determined is which page sets
might have incomplete changes. The procedure for determining which page sets
contain incomplete changes is described in “Bypassing backout before
restarting.” Other related topics might help you better understand the problem.

Backward log recovery failure

If a failure occurs during the backward-log recovery phase of restart, operations
management can recover from this situation.

When a failure occurs during the backward log recovery phase, certain
characteristics of the situation are evident, as the following figure shows.

Log Begin Begin Begin Log

Start URID5 URID6 Log Error URID7 End

Time
line

RBA: X Y Checkpoint

Figure 54. Illustration of failure during backward log recovery

The portion of the log between log RBA X and Y is inaccessible. The restart process
was reading the log in a backward direction, beginning at the end of the log and
continuing backward to the point marked by Begin URID5 in order to back out the
changes that were made by URID5, URID6, and URID7. You can assume that Db2
determined that these units of recovery were inflight or in-abort. The portion of the
log from point Y to the end of the log has been processed. However, the portion of
the log from Begin URID5 to point Y has not been processed and cannot be
processed by restart. Consequently, database changes that were made by URID5
and URID6 might not be fully backed out. All database changes made by URID7
have been fully backed out, but these database changes might not have been
written to disk. A subsequent restart of Db2 causes these changes to be written to
disk during forward recovery.
Related concepts
Recommendations for changing the BSDS log inventory

Bypassing backout before restarting

A portion of the log becomes inaccessible when a failure occurs during backward
log recovery. Operations management can recover from this situation by starting
Db2 in a certain way, and then identifying the page sets that are inconsistent
because of the incomplete units of recovery.

558 Administration Guide

Procedure

To bypass backout before recovery:

1. Determine the units of recovery that cannot be backed out and the page sets
that will be inconsistent after the completion of restart.
a. Determine the location of the latest checkpoint on the log by looking at one
of the following sources, whichever is more convenient:
v The operator's console contains message DSNR003I, which identifies the
location of the start of the last checkpoint on the log at log RBA
X'7425468'.
DSNR003I RESTART ... PRIOR CHECKPOINT
RBA=00007425468
v The print log map utility output identifies the last checkpoint, including
its BEGIN CHECKPOINT RBA.
b. Obtain a report of the outstanding work that is to be completed at the next
Db2 restart by running the DSN1LOGP. When you run DSN1LOGP, specify
the checkpoint RBA as the RBASTART and the SUMMARY(ONLY) option.
Include the last complete checkpoint in the execution of DSN1LOGP in
order to obtain complete information.
Analyze the output of the DSN1LOGP utility. The summary report that is
placed in the SYSSUMRY file contains two sections of information. The
heading of first section of the output is the following message:
DSN1150I SUMMARY OF COMPLETED EVENTS
That message is followed by other messages that identify completed events,
such as completed units of recovery. That section of the output does not
apply to this procedure.
The heading of the second section of the output is the following message:
DSN1157I RESTART SUMMARY
That message is followed by others that identify units of recovery that are
not yet completed and the page sets that they modified. After the summary
of outstanding units of recovery is a summary of page sets with database
writes that are pending.
The restart processing that failed was able to complete all units of recovery
processing within the accessible scope of the log after point Y. Database
writes for these units of recovery are completed during the forward
recovery phase of restart on the next restart. Therefore, do not bypass the
forward recovery phase. All units of recovery that can be backed out have
been backed out.
All remaining units of recovery that are to be backed out (DISP=INFLIGHT
or DISP=IN-ABORT) are bypassed on the next restart because their
STARTRBA values are less than the RBA of point Y. Therefore, all page sets
that were modified by those units of recovery are inconsistent after restart.
This means that some changes to data might not be backed out. At this
point, you only need to identify the page sets in preparation for restart.
2. Use the change log inventory utility to create a conditional restart control
record (CRCR) in the BSDS, and direct restart to bypass backward recovery
processing during the subsequent restart by using the BACKOUT specification.
At restart, all units of recovery that require backout are declared complete by
Db2, and log records are generated to note the end of the unit of recovery. The
change log inventory utility control statement is:
CRESTART CREATE,BACKOUT=NO

Chapter 13. Recovering from different Db2 for z/OS problems 559
 3. Start Db2. At the end of restart, the CRCR is marked “Deactivated” to prevent
its use on a subsequent restart. Until the restart is complete, the CRCR is in
effect. Use START DB2 ACCESS(MAINT) until data is consistent or page sets are
stopped.
4. Resolve all inconsistent data problems. After the successful start of Db2, resolve
all data inconsistency problems. “Resolving inconsistencies resulting from a
conditional restart” on page 567 describes how to do this. At this time, make all
other data available for use.
Related concepts
DSN1LOGP summary report

Recovering from a failure during a log RBA read request

A failure might occur during a log RBA read request. For example, because of
problems with the BSDS, the requested RBA, which contains the dropped log data
set, cannot be read. You can recover from the situation.

Symptoms
Abend code 00D1032A is issued, and message DSNJ113E is displayed:
DSNJ113E RBA log-rba NOT IN ANY ACTIVE OR ARCHIVE
LOG DATA SET. CONNECTION-ID=aaaaaaaa, CORRELATION-ID=aaaaaaaa

Causes
The BSDS is wrapping around too frequently when log RBA read requests are
submitted; when the last archive log data sets were added to the BSDS, the
maximum allowable number of log data sets in the BSDS was exceeded. This
caused the earliest data sets in the BSDS to be displaced by the new entry.
Subsequently, the requested RBA containing the dropped log data set cannot be
read after the wrap occurs.

Resolving the problem

System programmer response:
1. Stop Db2 with the STOP DB2 command, if it has not already been stopped
automatically as a result of the problem.
2. Check any other messages and reason codes that are displayed, and correct the
errors that are indicated. Locate the output from an old execution of the print
log map utility, and identify the data set that contains the missing RBA. If the
data set has not been reused, run the change log inventory utility to add this
data set back into the inventory of log data sets.
3. Increase the maximum number of archive log volumes that can be recorded in
the BSDS. To do this, update the MAXARCH system parameter value as
follows:
a. Start the installation CLIST.
b. On panel DSNTIPA1, select UPDATE mode.
c. On panel DSNTIPT, change any data set names that are not correct.
d. On panel DSNTIPB, select the ARCHIVE LOG DATA SET PARAMETERS
option.
e. On panel DSNTIPA, increase the value of RECORDING MAX.
f. When the installation CLIST editing completes, rerun job DSNTIJUZ to
recompile the system parameters.
4. Start Db2 with the START DB2 command.
Related tasks

560 Administration Guide

 Updating subsystem parameter and application default values (Db2
Installation and Migration)
Related reference
RECORDING MAX field (MAXARCH subsystem parameter) (Db2
Installation and Migration)
DSNJU003 (change log inventory) (Db2 Utilities)

Recovering from unresolvable BSDS or log data set problem

during restart
During a restart of Db2, serious problems with the bootstrap data set (BSDS) or log
data sets might occur. However, operations management can recover from these
problems. Use of dual logging (active logs, archive logs, and bootstrap data sets)
can reduce your efforts in resolving these sorts of problems.

Symptoms
The following messages are issued:
v DSNJ100I
v DSNJ107I
v DSNJ119I

Causes
Any of the following problems might cause problems with the BSDS or log data
sets during restart:
v A log data set is physically damaged.
v Both copies of a log data set are physically damaged in the case of dual logging
mode.
v A log data set is lost.
v An archive log volume was reused even though it was still needed.
v A log data set contains records that are not recognized by Db2 because they are
logically broken.

Environment
Db2 cannot be started until this procedure is performed.

Resolving the problem

Operations management response: Serious cases such as this sometimes
necessitate a fallback to a prior shutdown level.
v If you decide to fall back (because the amount of lost information is not
excessive):
1. See Preparing to recover to a prior point of consistency.
2. Follow the procedure in Falling back to a prior shutdown point.
If you use do a fallback, all database changes between the shutdown point and
the present are lost. However, all the data that is retained will be consistent
within Db2.
v If you decide not to fall back (because too much log information has been lost),
use the alternative approach that is described in Recovering from a failure
resulting from total or excessive loss of log data.

Falling back to a prior shutdown point

When a failure occurs in your environment, you might decide to fall back to a
prior shutdown point.

Chapter 13. Recovering from different Db2 for z/OS problems 561
 Procedure

To fallback to a prior shutdown point:

1. Use the print log map utility on the most current copy of the BSDS. Even if
you are not able to do this, continue with the next step. (If you are unable to
do this, an error message is issued.)
2. Use the access method services IMPORT command to restore the backed-up
versions of the BSDS and active log data sets.
3. Use the print log map utility on the copy of the BSDS with which Db2 is to be
restarted.
4. Determine whether any archive log data sets must be deleted.
v If you have a copy of the most current BSDS, compare it to the BSDS with
which Db2 is to be restarted. Delete and uncatalog any archive log data sets
that are listed in the most current BSDS but are not listed in the previous
one. These archive log data sets are normal physical sequential (SAM) data
sets. If you are able to do this step, continue with step 5.
v If you were not able to print a copy of the most current BSDS and the
archive logs are cataloged, use access method services LISTCAT to check for
archive logs with a higher sequence number than the last archive log that is
shown in the BSDS that is being used to restart Db2.
– If no archive log data sets with a higher sequence number exist, you do
not need to delete or uncatalog any data sets, and you can continue with
step 5.
– Delete and uncatalog all archive log data sets that have a higher
sequence number than the last archive log data set in the BSDS that is
being used to restart Db2. These archive log data sets are SAM data sets.
Continue with the next step.
If the archive logs are not cataloged, you do not need to uncatalog them.
5. Issue the START DB2 ACCESS(MAINT) command until data is consistent or page
sets are stopped.
6. Determine what data needs to be recovered, what data needs to be dropped,
what data can remain unchanged, and what data needs to be recovered to the
prior shutdown point.
v For table spaces and indexes that might have been changed after the
shutdown point, use the Db2 RECOVER utility to recover these table spaces
and indexes. They must be recovered in the proper order.
v For data that has not been changed after the shutdown point (data used
with RO access), you do not need to use RECOVER or DROP.
v For table spaces that were deleted after the shutdown point, issue the
DROP statement. These table spaces will not be recovered.
v Re-create any objects that were created after the shutdown point.
You must recover all data that has potentially been modified after the
shutdown point. If you do not use the RECOVER utility to recover modified
data, serious problems might can occur because of data inconsistency.
If you try to access inconsistent data, any of the following events can occur
(and the list is not comprehensive):
v You can successfully access the correct data.
v You can access data without Db2 recognizing any problem, but it might not
be the data that you want (the index might be pointing to the wrong data).

562 Administration Guide

 v Db2 might recognize that a page is logically incorrect and, as a result,
abend the subsystem with an X'04E' abend completion code and an abend
reason code of X'00C90102'.
v Db2 might notice that a page was updated after the shutdown point and, as
a result, abend the requester with an X'04E' abend completion code and an
abend reason code of X'00C200C1'.
7. Analyze the CICS log and the IMS log to determine the work that must be
redone (work that was lost because of shutdown at the previous point).
Inform all users (TSO users, QMF users, and batch users for whom no
transaction log tracking has been performed) about the decision to fall back to
a previous point.
8. When Db2 is started after being shut down, indoubt units of recovery might
exist. This occurs if transactions are indoubt when the STOP DB2 MODE
(QUIESCE) command is issued. When Db2 is started again, these transactions
will still be indoubt to Db2. IMS and CICS cannot know the disposition of
these units of recovery.
To resolve these indoubt units of recovery, use the RECOVER INDOUBT command.
9. If a table space was dropped and re-created after the shutdown point, drop
and re-create it again after Db2 is restarted. To do this, use SQL DROP and
SQL CREATE statements.
Do not use the RECOVER utility to accomplish this, because it will result in
the old version (which might contain inconsistent data) that is being
recovered.
10. If any table spaces and indexes were created after the shutdown point,
re-create these after Db2 is restarted. You can accomplish this in these ways:
v For data sets that are defined in Db2 storage groups, use the CREATE
TABLESPACE statement, and specify the appropriate storage group names.
Db2 automatically deletes the old data set and redefines a new one.
v For user-defined data sets, use the access method services DELETE command
to delete the old data sets. After these data sets have been deleted, use the
access method services DEFINE command to redefine them; then use the
CREATE TABLESPACE statement.
Related reference
RECOVER (Db2 Utilities)

Recovering from a failure resulting from total or excessive

loss of log data
If a situation occurs that causes the entire log or an excessive amount of log data
to be lost or destroyed, operations management needs to recover from that
situation.

Symptoms
This situation is generally accompanied by messages or abend reason codes that
indicate that an excessive amount of log information, or the entire log, has been
lost.

Diagnosing the problem

In this situation, you need to rely on your own sources to determine what data is
inconsistent as a result of the failure; Db2 cannot provide any hints of
inconsistencies. For example, you might know that Db2 was dedicated to a few
processes (such as utilities) during the Db2 session, and you might be able to
identify the page sets that they modified. If you cannot identify the page sets that

Chapter 13. Recovering from different Db2 for z/OS problems 563
 are inconsistent, you must decide whether you are willing to assume the risk that
is involved in restarting Db2 under those conditions.

Resolving the problem

Operations management response: If you decide that a restart is needed, restart
Db2 without any log data by using the appropriate procedure, depending on
whether the log is totally or partially (but excessively) lost.

Recovering from a total loss of the log

If all system and user table spaces remain intact and you have a recent copy of the
BSDS, you can recover from a total loss of the log. Db2 can still be restarted, and
data that belongs to that Db2 subsystem can still be accessed.

Before you begin

All system and user table spaces must be intact, and you must have a recent copy
of the BSDS. Other VSAM clusters on disk, such as the system databases
DSNDB01, DSNDB04, and DSNB06, and also user databases are assumed to exist.

Procedure

To restart Db2 when the entire log is lost:

1. Define and initialize the BSDSs by recovering the BSDS from a backup copy.
2. Define the active log data sets by using the access method services DEFINE
command. Run utility DSNJLOGF to initialize the new active log data sets.
3. Prepare to restart Db2 with no log data. Each data and index page contains the
log RBA of the last log record that was applied against the page. Safeguards
within Db2 disallow a modification to a page that contains a log RBA that is
higher than the current end of the log. You have two choices:
v Determine the highest possible log RBA of the prior log. From previous
console logs that were written when Db2 was operational, locate the last
DSNJ001I message. When Db2 switches to a new active log data set, this
message is written to the console, identifying the data set name and the
highest potential log RBA that can be written for that data set. Assume that
this is the value X'8BFFF'. Add one to this value (X'8C000'), and create a
conditional restart control record that specifies the following change log
inventory control statement:
CRESTART CREATE,STARTRBA=8C000,ENDRBA=8C000
When Db2 starts, all phases of restart are bypassed, and logging begins at
log RBA X'8C000'. If you choose this method, you do not need to use the
RESET option of the DSN1COPY utility, and you can save a lot of time.
v Run the DSNJU003 utility, specifying the DELETE and NEWLOG options to
delete and create new logs for all active log data sets.
v Run the DSN1COPY utility, specifying the RESET option to reset the log RBA
in every data and index page. Depending on the amount of data in the
subsystem, this process might take quite a long time. Because the BSDS has
been redefined and reinitialized, logging begins at log RBA 0 when Db2
starts.
If the BSDS is not reinitialized, you can force logging to begin at log RBA 0
by constructing a conditional restart control record (CRCR) that specifies a
STARTRBA and ENDRBA that are both equal to 0, as the following
command shows:
CRESTART CREATE,STARTRBA=0,ENDRBA=0

564 Administration Guide

4. Start Db2. Use the START DB2 ACCESS(MAINT) command until data is consistent
or page sets are stopped.
5. After restart, resolve all inconsistent data as described in “Resolving
inconsistencies resulting from a conditional restart” on page 567.
Related tasks
Deferring restart processing
Recovering the BSDS from a backup copy
Related reference
DSNJLOGF (preformat active log) (Db2 Utilities)

Recovering from an excessive loss of active log data

When your site experiences an excessive loss of active log data, you can develop a
procedure for restarting in this situation. Do not redefine the BSDS.

About this task

You can recover from an excessive loss of active log data in one of two ways.

Recovering Db2 by creating a gap in the active log:

If your site experiences an excessive loss of active log data, you can recover by
creating a gap in the active log.

Procedure

To recover by creating a gap in the active log:

1. Use the print log map utility (DSNJU004) on the copy of the BSDS with which
Db2 is to be restarted.
2. Use the print log map output to obtain the data set names of all active log data
sets. Use the access method services LISTCAT command to determine which
active log data sets are no longer available or usable.
3. Use the access method services DELETE command to delete all active log data
sets that are no longer usable.
4. Use the access method services DEFINE command to define new active log data
sets. Run the DSNJLOGF utility to initialize the new active log data sets. Define
one active log data set for each one that is found to be no longer available or
usable in step 2. Use the active log data set name that is found in the BSDS as
the data set name for the access method services DEFINE command.
5. Refer to the print log map utility (DSNJU004) output, and note whether an
archive log data set exists that contains the RBA range of the redefined active
log data set. To do this, note the starting and ending RBA values for the active
log data set that was recently redefined, and look for an archive log data set
with the same starting and ending RBA values.
If no such archive log data sets exist:
a. Use the change log inventory utility (DSNJU003) DELETE statement to
delete the recently redefined active log data sets from the BSDS active log
data set inventory.
b. Use the change log inventory utility (DSNJU003) NEWLOG statement to
add the active log data set to the BSDS active log data set inventory. Do not
specify RBA ranges on the NEWLOG statement.
If the corresponding archive log data sets exist, two courses of action are
available:

Chapter 13. Recovering from different Db2 for z/OS problems 565
 v If you want to minimize the number of potential read operations on the
archive log data sets, use the access method services REPRO command to copy
the data from each archive log data set into the corresponding active log data
set. Ensure that you copy the proper RBA range into the active log data set.
Ensure that the active log data set is large enough to hold all the data from
the archive log data set. When Db2 does an archive operation, it copies the
log data from the active log data set to the archive log data set, and then
pads the archive log data set with binary zeros to fill a block. In order for the
access method services REPRO command to be able to copy all of the data
from the archive log data set to a recently defined active log data set, the
new active log data set might need to be larger than the original one.
For example, if the block size of the archive log data set is 28 KB, and the
active log data set contains 80 KB of data, Db2 copies the 80 KB and pads
the archive log data set with 4 KB of nulls to fill the last block. Thus, the
archive log data set now contains 84 KB of data instead of 80 KB. In order
for the access method services REPRO command to complete successfully, the
active log data set must be able to hold 84 KB, rather than just 80 KB of data.
v If you are not concerned about read operations against the archive log data
sets, complete the two steps that appear in the steps 5a on page 565 and 5b
on page 565 (as though the archive data sets did not exist).
6. Choose the appropriate point for Db2 to start logging. To do this, determine the
highest possible log RBA of the prior log. From previous console logs that were
written when Db2 was operational, locate the last DSNJ001I message. When
Db2 switches to a new active log data set, this message is written to the
console, identifying the data set name and the highest potential log RBA that
can be written for that data set. Assume that this is the value X'8BFFF'. Add
one to this value (X'8C000'), and create a conditional restart control record that
specifies the following change log inventory control statement:
CRESTART CREATE,STARTRBA=8C000,ENDRBA=8C000

When Db2 starts, all phases of restart are bypassed, and logging begins at log
RBA X'8C000'. If you choose this method, you do not need to use the RESET
option of the DSN1COPY utility, and you can save a lot of time.
7. To restart Db2 without using any log data, create a conditional restart control
record for the change log inventory utility (DSNJU003).
8. Start Db2. Use the START DB2 ACCESS(MAINT) command until data is consistent
or page sets are stopped.
9. After restart, resolve all inconsistent data as described in “Resolving
inconsistencies resulting from a conditional restart” on page 567.

Results

This procedure causes all phases of restart to be bypassed and logging to begin at
the point in the log RBA that you identified in step 6 (X'8C000' in the example
given in this procedure). This procedure creates a gap in the log between the
highest RBA kept in the BSDS and, in this example, X'8C000', and that portion of
the log is inaccessible.

What to do next

Because no Db2 process can tolerate a gap, including RECOVER, you need to take
image copies of all data after a cold start, even data that you know is consistent.
Related reference

566 Administration Guide

 DSNJU003 (change log inventory) (Db2 Utilities)

Recovering Db2 without creating a gap in the active log:

You can do a cold start without creating a gap in the log. Although this approach
does eliminate the gap in the physical log record, you cannot use a cold start to
resolve the logical inconsistencies.

Procedure

To recover without creating a gap in the active log:

1. Locate the last valid log record by using the DSN1LOGP utility to scan the log.
Message DSN1213I identifies the last valid log RBA.
2. Identify the last RBA that is known to be valid by examining message
DSN1213I. For example, if message DSN1213I indicates that the last valid log
RBA is X'89158', round this value up to the next 4-KB boundary, which in this
example is X'8A000'.
3. Create a conditional restart control record (CRCR). For example:
CRESTART CREATE,STARTRBA=8A000,ENDRBA=8A000
4. Start Db2 with the START DB2 ACCESS(MAINT) command until data is consistent
or page sets are stopped.
5. Take image copies of all data for which data modifications were recorded
beyond the log RBA that was used in the CRESTART statement (in this
example, X'8A000'). If you do not know what data was modified, take image
copies of all data.
If you do not take image copies of data that has been modified beyond the log
RBA that was used in the CRESTART statement, future RECOVER utility
operations might fail or result in inconsistent data.

What to do next

After restart, resolve all inconsistent data as described in “Resolving inconsistencies

resulting from a conditional restart.”

Resolving inconsistencies resulting from a conditional restart

When a conditional restart of the Db2 subsystem is done, several problems might
occur. Recovery from these problems is possible and varies based on the specific
situation.

About this task

The following problems might occur after a conditional restart of Db2:

v Some amount of work is left incomplete.
v Some data is left inconsistent.
v Information about the status of objects within the Db2 subsystem is made
unusable.

Inconsistencies in a distributed environment

In a distributed environment, when a Db2 subsystem restarts, Db2 indicates its
restart status and the name of its recovery log to the systems that it communicates
with. The two possible conditions for restart status are warm and cold.

Chapter 13. Recovering from different Db2 for z/OS problems 567
 A cold status is associated with a cold start, which is a process by which a Db2
subsystem restarts without processing any log records. Db2 has no memory of
previous connections with its partner. The general process that occurs with a cold
start in a distributed environment is as follows:
1. The partner (for example CICS) accepts the cold start connection and
remembers the recovery log name of the Db2 subsystem that experienced the
cold start.
2. If the partner has indoubt thread resolution requirements with the cold-starting
Db2 subsystem, those requirements cannot be satisfied.
3. The partner terminates its indoubt resolution responsibility with the
cold-starting Db2 subsystem. However, as a participant, the partner has indoubt
logical units of work that must be resolved manually.
4. Because the Db2 subsystem has an incomplete record of resolution
responsibilities, Db2 attempts to reconstruct as much resynchronization
information as possible.
5. Db2 displays the information that it was able to reconstruct in one or more
DSNL438 or DSNL439 messages.
6. Db2 then discards the synchronization information that it was able to
reconstruct and removes any restrictive states that are maintained on the object.

Resolving inconsistencies
In some problem situations, you need to determine what you must do in order to
resolve any data inconsistencies that exist.

Procedure

To resolve inconsistencies:
1. Determine the scope of any inconsistencies that are introduced by the situation.
a. If the situation is either a cold start that is beyond the current end of the log
or a conditional restart that skips backout or forward log recovery, use the
DSN1LOGP utility to determine what units of work have not been backed
out and which objects are involved. For a cold start that is beyond the end
of the log, you can also use DSN1LOGP to help identify any restrictive
object states that have been lost.
b. If a conditional restart truncates the log in a non-data sharing environment,
recover all data and indexes to the new current point in time, and rebuild
the data and indexes as needed. You need to recover or rebuild (or both
recover and rebuild) the data and indexes because data and index updates
might exist without being reflected in the Db2 log. When this situation
occurs, a variety of inconsistency errors might occur, including Db2 abends
with reason code 00C200C1.
2. Decide what approach to take to resolve inconsistencies by reading related
topics about the approaches:
v Recovery to a prior point of consistency
v Restoration of a table space
v Use of the REPAIR utility on the data
The first two approaches are less complex than, and therefore preferred over,
the third approach.
3. If one or more of the following conditions are applicable, take image copies of
all Db2 table spaces:
v You did a cold start.
v You did a conditional restart that altered or truncated the log.
568 Administration Guide
 v The log is damaged.
v Part of the log is no longer accessible.
When a portion of the Db2 recovery log becomes inaccessible, all Db2 recovery
processes have difficulty operating successfully, including restart, RECOVER,
and deferred restart processing. Conditional restart allows circumvention of the
problem during the restart process. To ensure that RECOVER does not attempt
to access the inaccessible portions of the log, secure a copy (either full or
incremental) that does not require such access. A failure occurs any time a Db2
process (such as the RECOVER utility) attempts to access an inaccessible
portion of the log. You cannot be sure which Db2 processes must use that
portion of the recovery log. Therefore, you need to assume that all data
recovery activity requires that portion of the log.
A cold start might cause down-level page set errors, which you can find out
about in different ways:
v Message DSNB232I is sometimes displayed during Db2 restart, once for each
down-level page set that Db2 detects. After you restart Db2, check the
console log for down-level page set messages.
– If a small number of those messages exist, run DSN1COPY with the
RESET option to correct the errors to the data before you take image
copies of the affected data sets.
– If a large number of those messages exist, the actual problem is not that
page sets are down-level but that the conditional restart inadvertently
caused a high volume of DSNB232I messages. In this case, temporarily
turn off down-level detection by turning off the DLDFREQ ZPARM.
In either case, continue with step 4.
v If you run the COPY utility with the SHRLEVEL REFERENCE option to
make image copies, the COPY utility sometimes issues message DSNB232I
about down-level page sets that Db2 does not detect during restart. If any of
those messages were issued when you are making image copies, correct the
errors, and continue making image copies of the affected data sets.
v If you use some other method to make image copies, you will find out about
down-level page set errors during normal operation. In this case, you need to
correct the errors by using the information in “Recovering from a down-level
page set problem” on page 575.
4. For any Db2 (catalog and directory) system table spaces that are inconsistent,
recover them in the proper order. You might need to recover to a prior point in
time, prior to the conditional restart.
5. For any objects that you suspect might be inconsistent, resolve the database
inconsistencies before proceeding.
v First, resolve inconsistencies in Db2 system databases DSNDB01 and
DSNDB06. Catalog and directory inconsistencies need to be resolved before
inconsistencies in other databases because the subsystem databases describe
all other databases, and access to other databases requires information from
DSNDB01 and DSNDB06.
v If you determine that the existing inconsistencies involve indexes only (not
data), use the REBUILD INDEX utility to rebuild the affected indexes.
Alternatively, you can use the RECOVER utility to recover the index if
rebuilding the indexes is not possible.
v For a table space that cannot be recovered (and is thus inconsistent),
determine the importance of the data and whether it can be reloaded. If the
data is not critical or can be reloaded, drop the table after you restart Db2,
and reload the data rather than trying to resolve the inconsistencies.

Chapter 13. Recovering from different Db2 for z/OS problems 569
 Related concepts:
Recovery of data to a prior point in time
Related tasks:
Recovering catalog and directory objects (Db2 Utilities)
Related reference:
LEVELID UPDATE FREQ field (DLDFREQ subsystem parameter) (Db2
Installation and Migration)
DSN1COPY (Db2 Utilities)
RECOVER (Db2 Utilities)

Restoring the table space:

You can restore the table space by reloading data into it or by re-creating the table
space, which requires advance planning. Either of these methods is easier than
using REPAIR.

About this task

Reloading the table space is the preferred approach, when it is possible, because
reloading is easier and requires less advance planning than re-creating a table
space. Re-creating a table space involves dropping and then re-creating the table
space and associated tables, indexes, authorities, and views, which are implicitly
dropped when the table space is dropped. Therefore, re-creating the objects means
that you need to plan ahead so that you will be prepared to re-establish indexes,
views, authorizations, and the data content itself.

Restriction:

You cannot drop Db2 system tables, such as the catalog and directory. For these
system tables, follow one of these procedures instead of this one:
v Recovery of data to a prior point in time
v “Using the REPAIR utility on inconsistent data” on page 571

Procedure

To restore the table space:

1. Decide whether you can reload the table space or must drop and re-create it.
v If you can reload the table space, run the appropriate LOAD utility jobs to
do so; specify the REPLACE option. After you load the content of the table
space, skip to step 6.
v If you cannot reload the table space, continue with step 2.
2. Issue an SQL DROP TABLESPACE statement for the table space that is
suspected of being involved in the problem.
3. Re-create the table space, tables, indexes, synonyms, and views by using SQL
CREATE statements.
4. Grant access to these objects the same way that access was granted prior to the
time of the error.
5. Reconstruct the data in the tables.
6. Run the RUNSTATS utility on the data.
7. Use the COPY utility to acquire a full image copy of all data.

570 Administration Guide

8. Use the REBIND command on all plans that use the tables or views that are
involved in this activity.
Related concepts:
Recovery of data to a prior point in time
Related tasks:
Using the REPAIR utility on inconsistent data
Related reference:
LOAD (Db2 Utilities)
COPY (Db2 Utilities)

Using the REPAIR utility on inconsistent data:

You can resolve inconsistencies with the REPAIR utility. However, using REPAIR is
not recommended unless the inconsistency is limited to a small number of data or
index pages.

About this task

Db2 does not provide a mechanism to automatically inform users about data that
is physically inconsistent or damaged. When you use SQL to access data that is
physically damaged, Db2 issues messages to indicate that data is not available due
to a physical inconsistency.

However, Db2 includes several utilities that can help you identify data that is
physically inconsistent before you try to access it. These utilities are:
v CHECK DATA
v CHECK INDEX
v CHECK LOB
v COPY with the CHECKPAGE option
v DSN1COPY with the CHECK option

Attention: If you decide to use this method to resolve data inconsistencies, use
extreme care. Use of the REPAIR utility to correct inconsistencies requires in-depth
knowledge of Db2 data structures. Incorrect use of the REPAIR utility can cause
further corruption and loss of data. Read this topic carefully because it contains
information that is important to the successful resolution of the inconsistencies.

Recommendation: Avoid using this procedure if you are experiencing extensive

data inconsistency because it is more time-consuming and complex (and therefore
prone to error) than recovering to a point in time or re-creating the table spaces. If
possible, use those alternative procedures instead.

Restrictions:
v Although the DSN1LOGP utility can identify page sets that contain
inconsistencies, this utility cannot identify the specific data modifications that
are involved in the inconsistencies within a given page set.
v Any pages that are on the logical page list (perhaps caused by this restart)
cannot be accessed by using the REPAIR utility.

Procedure

To use the REPAIR utility to resolve the inconsistency:

1. Issue the following command to start Db2 and allow access to data:

Chapter 13. Recovering from different Db2 for z/OS problems 571
 START DATABASE (dbase) SPACENAM (space) ACCESS(FORCE)
In this command, space identifies the table space that is involved.
2. If any system data is inconsistent, use the REPAIR utility to resolve those
inconsistencies. Db2 system data (such as data that is in the catalog and
directory) exists in interrelated tables and table spaces. Data in Db2 system
databases cannot be modified with SQL, so use of the REPAIR utility is
necessary to resolve the inconsistencies that are identified.
3. Determine if you have any structural violations in data pages. Db2 stores data
in data pages. The structure of data in a data page must conform to a set of
rules for Db2 to be able to process the data accurately. Using a conditional
restart process does not cause violations to this set of rules; but, if violations
existed prior to conditional restart, they continue to exist after conditional
restart.
4. Use the DSN1COPY utility with the CHECK option to identify any violations
that you detected in the previous step, and then resolve the problems, possibly
by recovering or rebuilding the object or by dropping and re-creating it.
5. Examine the various types of pointers that Db2 uses to access data (indexes,
hashes, and links), and identify inconsistencies that need to be manually
corrected.
Hash and link pointers exist in the Db2 directory database; link pointers also
exist in the catalog database. Db2 uses these pointers to access data. During a
conditional restart, data pages might be modified without update of the
corresponding pointers. When this occurs, one of the following actions might
occur:
v If a pointer addresses data that is nonexistent or incorrect, Db2 abends the
request. If SQL is used to access the data, a message that identifies the
condition, and the page in question is issued.
v If data exists but no pointer addresses it, that data is virtually invisible to all
functions that attempt to access it by using the damaged hash or link pointer.
The data might, however, be visible and accessible by some functions, such
as SQL functions that use another pointer that was not damaged. This
situation can result in inconsistencies.
If a row that contains a varying-length field is updated, it can increase in size.
If the page in which the row is stored does not contain enough available space
to store the additional data, the row is placed in another data page, and a
pointer to the new data page is stored in the original data page. After a
conditional restart, one of the following conditions might exist.
v The row of data exists, but the pointer to that row does not exist. In this
case, the row is invisible, and the data cannot be accessed.
v The pointer to the row exists, but the row itself no longer exists. Db2 abends
the requester when any operation (for instance, a SELECT) attempts to access
the data. If termination occurs, one or more messages are issued to identify
the condition and the page that contains the pointer.
6. Use the REPAIR utility to resolve any inconsistencies that you detected in the
previous step.
7. Reset the log RBA in every data and index page set that are to be corrected
with this procedure by using the DSN1COPY RESET option. This step is
necessary for the following reason. If the log was truncated, changing data by
using the REPAIR utility can cause problems. Each data and index page
contains the log RBA of the last recovery log record that was applied against
the page. Db2 does not allow modification of a page that contains a log RBA
that is higher than the current end of the log.

572 Administration Guide

 8. When all known inconsistencies have been resolved, take full image copies of
all modified table spaces, in order to use the RECOVER utility to recover from
any future problems. This last step is imperative.
Related concepts:
Recovery of data to a prior point in time
Obtaining Db2 Diagnosis Guide and Reference ()
Related tasks:
Restoring the table space
Related reference:
REPAIR (Db2 Utilities)

Recovering from Db2 database failure

If a Db2 failure occurs because of an allocation or open problem, you can recover
from this situation.

Symptoms
The symptoms vary based on whether the failure was an allocation or an open
problem:
Allocation problem
The following message indicates an allocation problem:
DSNB207I - DYNAMIC ALLOCATION OF DATA SET FAILED.
REASON=rrrr DSNAME=dsn

The rrrr is a z/OS dynamic allocation reason code.

Open problem
The following messages indicate an open problem:
IEC161I rc[(sfi)] - ccc, iii, sss, ddn,
ddd, ser, xxx, dsn, cat

DSNB204I - OPEN OF DATA SET FAILED. DSNAME = dsn

In the IEC161I message:

rc Is a return code.
sfi Is subfunction information, which is displayed only with certain
return codes.
ccc Is a function code.
iii Is a job name.
sss Is a step name.
ddn Is a DD name.
ddd Is a device number (if the error is related to a specific device).
ser Is a volume serial number (if the error is related to a specific
volume).
xxx Is a VSAM cluster name.
dsn Is a data set name.
cat Is a catalog name.

Environment
When this type of problem occurs:
v The table space is automatically stopped.
v Programs receive a -904 SQLCODE (SQLSTATE '57011').

Chapter 13. Recovering from different Db2 for z/OS problems 573
 v If the problem occurs during restart, the table space is marked for deferred
restart, and restart continues. The changes are applied later when the table space
is started.

Resolving the problem

Operator response:
1. Check reason code, and correct problems.
2. Ensure that drives are available for allocation.
3. Enter the command START DATABASE.
Related reference
MVS Authorized Assembler Services Guide

Recovering a Db2 subsystem to a prior point in time

You can recover a Db2 subsystem and data sharing group to a prior point in time
by using the BACKUP SYSTEM and RESTORE SYSTEM utilities.

About this task

In this recovery procedure, you create and populate a table that contains data that
is both valid and invalid. You need to restore your Db2 subsystem to a point in
time before the invalid data was inserted into the table, but after the point in time
when the valid data was inserted. Also, you create an additional table space and
table that Db2 will re-create during the log-apply phase of the restore process.

Procedure

To insert data into a table, determine the point in time that you want to recover to,
and then recover the Db2 subsystem to a prior point in time:
1. Issue the START DB2 command to start Db2 and all quiesced members of the
data sharing group. Quiesced members are ones that you removed from the
data sharing group either temporarily or permanently. Quiesced members
remain dormant until you restart them.
2. Issue SQL statements to create a database, a table space, and two tables with
one index for each table.
3. Issue the BACKUP SYSTEM DATA ONLY utility control statement to create a
backup copy of only the database copy pool for a Db2 subsystem or data
sharing group.
4. Issue an SQL statement to first insert rows into one of the tables, and then
update some of the rows.
5. Use the LOAD utility with the LOG NO attribute to load the second table.
6. Issue SQL statements to create an additional table space, table, and index in
an existing database. Db2 will re-create the additional table space and table
during the log-apply phase of the restore process.
7. Issue the SET LOG SUSPEND command or the SET LOG RESUME command
to obtain a log truncation point, logpoint1, which is the point you want to
recover to. For a non-data sharing group, use the RBA value. For a data
sharing group, use the lowest log record sequence number (LRSN) from the
active members.
The following example shows sample output for the SET LOG SUSPEND
command:

574 Administration Guide

| 14.21.49 -db2aset log suspend
| 14.21.49 STC00059 DSN9022I -DB2A DSNJC001 ’-SET LOG’ NORMAL COMPLETION
| 14.21.50 STC00059 *DSNJ372I -DB2A DSNJC09A UPDATE ACTIVITY HAS BEEN
| SUSPENDED FOR DB2A AT RBA 00000000000028B5588C, LRSN
| 00CA2981028F3D000000, PRIOR CHECKPOINT RBA 00000000000028B52667
8. Issue an SQL statement to first insert rows into one of the tables and then to
update and delete some rows.
9. Issue the STOP DB2 command to stop Db2 and all active members of the data
sharing group.
10. Run the DSNJU003 change log inventory utility to create a SYSPITR CRCR
record (CRESTART CREATE SYSPITR=logpoint1). The log truncation point is the
value that you obtained from issuing either the SET LOG SUSPEND command, or
the SET LOG RESUME command.
11. For a data sharing group, delete all of the coupling facility structures.
12. Issue the START DB2 command to restart Db2 and all members of the data
sharing group.
13. Run the RESTORE SYSTEM utility. For a data sharing group, this utility can
be run only on one member. If the utility stops and you must restart it, you
can restart the utility only on the member on which it was initially run.
14. After the RESTORE SYSTEM utility completes successfully, issue the STOP DB2
command to stop Db2 and all active members of the data sharing group. The
Db2 subsystem resets to RECOVER-pending status.
15. Issue the START DB2 command to restart Db2 and all members of the data
sharing group.
16. Issue the DISPLAY command to identify the utilities that are active and the
objects that are restricted. For example:
-DIS UTIL(*)
-DIS DB(DSNDB01) SP(*)
-DIS DB(DSNDB06) SP(*) LIMIT(*)
-DIS DB(DSNDB06) SP(*) LIMIT(*)RESTRICT
17. Stop all of the active utilities that you identified in the previous step.
18. Recover any objects that are in RECOVER-pending status or
REBUILD-pending status from the table that you created in step 6 on page
574.

Recovering from a down-level page set problem

When using a stand-alone utility or a non-Db2 utility, you might inadvertently
replace a Db2 page set with an incorrect or outdated copy. This type of copy is
called down-level. Using a down-level page set can cause complex problems;
therefore, you need to recover from this situation.

Symptoms
The following message is issued:
DSNB232I csect-name - UNEXPECTED DATA SET LEVEL ID ENCOUNTERED

The message also contains the level ID of the data set, the level ID that Db2
expects, and the name of the data set.

Causes
A down-level page set can be caused by:

Chapter 13. Recovering from different Db2 for z/OS problems 575
 v A Db2 data set is inadvertently replaced by an incorrect or outdated copy.
Usually this happens in conjunction with use of a stand-alone or non-Db2 utility,
such as DSN1COPY or DFSMShsm.
v A cold start of Db2 occurs.
v A VSAM high-used RBA of a table space becomes corrupted.

Db2 associates a level ID with every page set or partition. Most operations detect a
down-level ID, and return an error condition, when the page set or partition is first
opened for mainline or restart processing. The exceptions are the following
operations, which do not use the level ID data:
v LOAD REPLACE
v RECOVER
v REBUILD INDEX
v DSN1COPY
v DSN1PRNT

Environment
v If the error was reported during mainline processing, Db2 sends a "resource
unavailable" SQLCODE and a reason code to the application to explain the error.
v If the error was detected while a utility was processing, the utility generates a
return code 8.

Diagnosing the problem

Determine whether the message was issued during restart or at some other time
during normal operation. This information is important for determining what steps
to take below

Resolving the problem

System programmer response: The actions that you need to do to recover depend
on when the message was issued:
v If the message was issued during restart, take one of the following actions:
– Replace the data set with one that is at the proper level, by using DSN1COPY,
DFSMShsm, or some equivalent method. To check the level ID of the new
data set, run the stand-alone utility DSN1PRNT on it, with the options
PRINT(0) (to print only the header page) and FORMAT. The formatted print
output identifies the level ID.
– Recover the data set to the current time, or to a prior time, by using the
RECOVER utility.
– Replace the contents of the data set, by using LOAD REPLACE.
v If the message was issued during normal operation (not during restart):
1. Take one of the actions that are listed for situations when the message was
issued during restart.
2. Accept the down-level data set by changing its level ID. You can use the
REPAIR utility with the LEVELID statement. (You cannot use the LEVELID
option in the same job step with any other REPAIR utility control statement.)
Attention: If you accept a down-level data set or disable down-level
detection, your data might be inconsistent.

Related system programmer actions: Consider taking the following actions, which
might help you minimize or deal with down-level page set problems in the future:
v To control how often the level ID of a page set or partition is updated, specify a
value between 0 and 32767 on the LEVELID UPDATE FREQ field of panel
DSNTIPL.

576 Administration Guide

 v To disable down-level detection, specify 0 in the LEVELID UPDATE FREQ field
of panel DSNTIPL.
v To control how often level ID updates are taken, specify a value between 1 and
32767.
Related reference
LEVELID UPDATE FREQ field (DLDFREQ subsystem parameter) (Db2
Installation and Migration)
DSN1COPY (Db2 Utilities)
DSN1PRNT (Db2 Utilities)
LOAD (Db2 Utilities)
RECOVER (Db2 Utilities)
REPAIR (Db2 Utilities)

Recovering from a problem with invalid LOBs

If a LOB table space is defined with LOG NO and you need to recover that table
space, you can recover the LOB data to the point at which you made your last
image copy of the table space.

About this task

Unless your LOBs are fairly small, specifying LOG NO for LOB objects is
recommended for the best performance. However, to maximize recoverability,
specifying LOG YES is recommended. The performance cost of logging exceeds the
benefits that you can receive from logging such large amounts of data. If no
changes are made to LOB data, the logging cost is not an issue. However, you
should make image copies of the LOB table space to prepare for failures. The
frequency with which you make image copies is based on how often you update
LOB data.

Procedure

To recover LOB data from a LOB table space that is defined with LOG NO:
1. Run the RECOVER utility as you do for other table spaces:
RECOVER TABLESPACE dbname.lobts

If changes were made after the image copy, Db2 puts the table space in
auxiliary warning status, which indicates that some of your LOBs are invalid.
Applications that try to retrieve the values of those LOBs receive SQLCODE
-904. Applications can still access other LOBs in the LOB table space.
2. Get a report of the invalid LOBs by running CHECK LOB on the LOB table
space:
CHECK LOB TABLESPACE dbname.lobts

Db2 generates the following messages:

LOB WITH ROWID = ’xxxxxxx’ VERSION = n IS INVALID
3.

Chapter 13. Recovering from different Db2 for z/OS problems 577
 Fix the invalid LOBs, by updating the LOBs or setting them to the null value.
For example, suppose that you determine from the CHECK LOB utility that the
row of the EMP_PHOTO_RESUME table with ROWID
X'C1BDC4652940D40A81C201AA0A28' has an invalid value for column
RESUME. If host variable hvlob contains the correct value for RESUME, you can
use this statement to correct the value:
UPDATE DSN8B10. EMP_PHOTO_RESUME
SET RESUME = :hvlob
WHERE EMP_ROWID = ROWID(X’C1BDC4652940D40A81C201AA0A28’);

Recovering from table space I/O errors

You can recover a table space after I/O errors have occurred and caused the table
space to fail.

Symptoms
The following message is issued, where dddddddd is a table space name:
DSNU086I DSNUCDA1 READ I/O ERRORS ON SPACE=dddddddd.
DATA SET NUMBER=nnn.
I/O ERROR PAGE RANGE=aaaaaa, bbbbbb.

Any table spaces that are identified in DSNU086I messages must be recovered.
Follow the steps later in this topic.

Environment
Db2 remains active.

Resolving the problem

Operator response:
1. Fix the error range:
a. Use the command STOP DATABASE to stop the failing table space.
b. Use the command START DATABASE ACCESS (UT) to start the table space for
utility-only access.
c. Start a RECOVER utility step to recover the error range by using the
following statement:
DB2 RECOVER (dddddddd) ERROR RANGE
If you receive message DSNU086I again to indicate that the error range
recovery cannot be performed, continue with step 2.
d. Issue the command START DATABASE to start the table space for RO or RW
access, whichever is appropriate. If the table space is recovered, you do not
need to continue with the following procedure.
2. If error range recovery fails because of a hardware problem:
a. Use the command STOP DATABASE to stop the table space or table space
partition that contains the error range. As a result of this command, all
in-storage data buffers that are associated with the data set are externalized
to ensure data consistency during the subsequent steps.
b. Use the INSPECT function of the IBM Device Support Facility, ICKDSF, to
check for track defects and to assign alternate tracks as necessary.
Determine the physical location of the defects by analyzing the output of
messages DSNB224I, DSNU086I, and IOS000I. These messages are displayed

578 Administration Guide

 on the system operator's console at the time that the error range was
created. If damaged storage media is suspected, request assistance from IBM
Hardware Support before proceeding.
c. Use the command START DATABASE to start the table space with ACCESS(UT)
or ACCESS(RW).
d. Run the RECOVER utility with the ERROR RANGE option. Specify an error
range that, from image copies, locates, allocates, and applies the pages
within the tracks that are affected by the error ranges.
Related information
Device Support Facilities (ICKDSF) Device Support Facilities (ICKDSF)
User's Guide and Reference

Recovering from Db2 catalog or directory I/O errors

When the Db2 catalog or directory fails because of I/O errors, you need to recover
from this situation so that processing can return to normal.

Symptoms
The following message is issued, where dddddddd is the name of the table space
from the catalog or directory that failed (for example, SYSIBM.SYSCOPY):
DSNU086I DSNUCDA1 READ I/O ERRORS ON SPACE=dddddddd.
DATA SET NUMBER=NNN.
I/O ERROR PAGE RANGE=aaaaaa, bbbbbb

This message can indicate either read or write errors. You might also receive a
DSNB224I or DSNB225I message, which indicates an input or output error for the
catalog or directory.

Environment
Db2 remains active.

If the Db2 directory or any catalog table is damaged, only user IDs with the
RECOVERDB privilege in DSNDB06, or an authority that includes that privilege,
can perform the recovery. Furthermore, until the recovery takes place, only those
IDs can do anything with the subsystem. If an ID without proper authorization
attempts to recover the catalog or directory, message DSNU060I is displayed. If the
authorization tables are unavailable, message DSNT500I is displayed to indicate
that the resource is unavailable.

Resolving the problem

Operator response: Recover each table space in the failing Db2 catalog or directory.
If multiple table spaces need to be recovered, recover them in the recommended
order as defined in the information about the RECOVER utility.
1. Stop the failing table spaces.
2. Determine the name of the data set that failed by using one of the following
methods:
v Check prefix.SDSNSAMP (DSNTIJIN), which contains the JCL for installing
Db2. Find the fully qualified name of the data set that failed by searching for
the name of the table space that failed (the one that is identified in the
message as SPACE=dddddddd).
v Construct the data set name by performing one of the following actions:
– If the table space is in the Db2 catalog, the data set name format is:
DSNC110.DSNDBC.DSNDB06.dddddddd.I0001.A001

Chapter 13. Recovering from different Db2 for z/OS problems 579
 The dddddddd is the name of the table space that failed.
– If the table space is in the Db2 directory, the data set name format is:
DSNC110.DSNDBC.DSNDB01.dddddddd.I0001.A001
The dddddddd is the name of the table space that failed.
If you do not use the default (IBM-supplied) formats, the formats for data set
names might be different.
3. Use the access method services DELETE command to delete the data set,
specifying the fully qualified data set name.
4. After the data set is deleted, use the access method services DEFINE command
with the REUSE parameter to redefine the same data set, again specifying the
same fully qualified data set name. Use the JCL for installing Db2 to determine
the appropriate parameters.
5. Issue the command START DATABASE ACCESS(UT), naming the table space that is
involved.
6. Use the RECOVER utility to recover the table space that failed.
7. Issue the command START DATABASE, specifying the table space name and RO or
RW access, whichever is appropriate.
Related tasks
Recovering catalog and directory objects (Db2 Utilities)

Recovering from integrated catalog facility failure

Sometimes VSAM volume data sets might be out of space or destroyed. Also, you
might experience problems with other VSAM data sets being out of space or
unable to be extended any further.

Symptoms
The symptoms for integrated catalog facility problems vary according to the
underlying problems.

Recovering VSAM volume data sets that are out of space or

destroyed
If the VSAM volume data set (VVDS) is out of space or destroyed, you can recover
from the situation. You can recover by using Db2 commands, Db2 utilities, and
access method services.

Symptoms
Db2 sends the following message to the master console:
DSNP012I - DSNPSCT0 - ERROR IN VSAM CATALOG LOCATE FUNCTION
FOR data_set_name
CTLGRC=50
CTLGRSN=zzzzRRRR
CONNECTION-ID=xxxxxxxx,
CORRELATION-ID=yyyyyyyyyyyy
LUW-ID=logical-unit-of-work-id=token

VSAM might also issue the following message:

IDC3009I VSAM CATALOG RETURN CODE IS 50, REASON CODE IS
IGGOCLaa - yy

In this VSAM message, yy is 28, 30, or 32 for an out-of-space condition. Any other
values for yy indicate a damaged VVDS.

580 Administration Guide

 Environment
Your program is terminated abnormally, and one or more messages are issued.

Resolving the problem

Operator response: Begin by determining whether the VSAM volume data set is
out of space or has been destroyed. Then follow these steps:
1. Determine the names of all table spaces that reside on the same volume as the
VVDS. To determine the table space names, look at the VTOC entries list for
that volume, which indicates the names of all the data sets on that volume.
2. Use the Db2 COPY utility to take image copies of all table spaces of the
volume. Taking image copies minimizes reliance on the Db2 recovery log and
can speed up the processing of the Db2 RECOVER utility (to be mentioned in a
subsequent step).
If you cannot use the COPY utility, continue with this procedure. Be aware that
processing time increases because more information must be obtained from the
Db2 recovery log.
3. Use the command STOP DATABASE for all the table spaces that reside on the
volume, or use the command STOP DB2 to stop the entire Db2 subsystem if an
unusually large number or critical set of table spaces are involved.
4. If possible, use access method services to export all non-Db2 data sets that
resides on that volume.
5. Use access method services to recover all non-Db2 data sets that resides on that
volume.
6. Use access method services DELETE and DEFINE commands to delete and
redefine the data sets for all user-defined table spaces and Db2-defined data
sets when the physical data set has been destroyed. Db2 automatically deletes
and redefines all other STOGROUP-defined table spaces.
You do not need to delete and redefine table spaces that are
STOGROUP-defined because Db2 takes care of them automatically.
7. Issue the Db2 START DATABASE command to restart all the table spaces that were
stopped in step 3. If the entire Db2 subsystem was stopped, issue the START DB2
command.
8. Use the Db2 RECOVER utility to recover any table spaces and indexes.
Related tasks
Backing up and recovering your data
Related information
DFSMS Access Method Services Commands
DFSMS Managing Catalogs
DSNP012I (Db2 Messages)

Recovering from out-of-disk-space or extent limit problems

When a volume on which a data set is stored has insufficient space, or when the
data set reaches its maximum size or its maximum number of VSAM extents, you
can recover from this situation.

Symptoms
The symptoms vary based on the specific situation. The following messages and
codes might be issued:
v DSNP007I
v DSNP001I

Chapter 13. Recovering from different Db2 for z/OS problems 581
 v -904 SQL return code (SQLSTATE '57011')

Environment
For a demand request failure during restart, the object that is supported by the
data set (an index space or a table space) is stopped with deferred restart pending.
Otherwise, the state of the object remains unchanged.

Diagnosing the problem

Read the following descriptions of possible problems, and determine which
problem you are experiencing.
v Extend request failures: When an insert or update requires additional space, but
the space is not available in the current table space or index space, Db2 issues
the following message:
DSNP007I - DSNPmmmm - EXTEND FAILED FOR
data-set-name. RC=rrrrrrrr
CONNECTION-ID=xxxxxxxx,
CORRELATION-ID=yyyyyyyyyyyy
LUWID-ID=logical-unit-of-work-id=token
v Look-ahead warning: A look-ahead warning occurs when enough space is
available for a few inserts or updates, but the index space or table space is
almost full. On an insert or update at the end of a page set, Db2 determines
whether the data set has enough available space. Db2 uses the following values
in this space calculation:
– The primary space quantity from the integrated catalog facility (ICF) catalog
– The secondary space quantity from the ICF catalog
– The allocation unit size
If enough space does not exist, Db2 tries to extend the data set. If the extend
request fails, Db2 issues the following message:
DSNP001I - DSNPmmmm - data-set-name IS WITHIN
nK BYTES OF AVAILABLE SPACE.
RC=rrrrrrrr
CONNECTION-ID=xxxxxxxx,
CORRELATION-ID=yyyyyyyyyyyy
LUWID-ID=logical-unit-of-work-id=token

Resolving the problem

What you need to do depends on your particular circumstances.
v In most cases, if the data set has not reached its maximum size, you can enlarge
it. For the maximum sizes of data sets, see Limits in Db2 for z/OS (Db2 SQL).
v If the data set has reached its maximum size, you need to follow the appropriate
procedure, depending on the situation you face.

Extending a data set

If a user-defined data set reaches the maximum number of VSAM extents, you can
extend the data set by adding volumes.

Procedure

To extend a user-defined data set:

1. If possible, delete unneeded data on the current volume.
2. If deleting data from the volume does not solve the problem, add volumes to
the data set in one of the following ways:
v If the data set is defined in a Db2 storage group, add more volumes to the
storage group by using the SQL ALTER STOGROUP statement.

582 Administration Guide

 v If the data set is not defined in a Db2 storage group, add volumes to the
data set by using the access method services ALTER ADDVOLUMES command.

Enlarging a fully extended user-managed data set

If a user-managed data set reaches the maximum number of VSAM extents, you
can enlarge the data set.

Procedure

To enlarge a user-managed data set:

1. To allow for recovery in case of failure during this procedure, ensure that you
have a recent full image copy of your table spaces and indexes. Use the
DSNUM option to identify the data set for table spaces or partitioning indexes.
2. Issue the command STOP DATABASE SPACENAM for the last data set of the
supported object.
3. Delete the last data set by using access method services.
4. Redefine the data set, and enlarge it as necessary. The object must be a
user-defined linear data set. The limit is 32 data sets if the underlying table
space is not defined as LARGE or with a DSSIZE parameter, and the limit is
4096 for objects with greater than 254 parts. For a nonpartitioned index on a
table space that is defined as LARGE or with a DSSIZE parameter, the
maximum is MIN(4096, 232 / (index piece size/index page size)).
5. Issue the command START DATABASE ACCESS (UT) to start the object for
utility-only access.
6. To recover the data set that was redefined, use the RECOVER utility on the
table space or index, and identify the data set by the DSNUM option (specify
this DSNUM option for table spaces or partitioning indexes only).
The RECOVER utility enables you to specify a single data set number for a
table space. Therefore, you need to redefine and recover only the last data set
(the one that needs extension). This approach can be better than using the
REORG utility if the table space is very large and contains multiple data sets,
and if the extension must be done quickly.
If you do not copy your indexes, use the REBUILD INDEX utility.
7. Issue the command START DATABASE to start the object for either RO or RW
access, whichever is appropriate.
Related reference
-START DATABASE (Db2) (Db2 Commands)
-STOP DATABASE (Db2) (Db2 Commands)
RECOVER (Db2 Utilities)
REBUILD INDEX (Db2 Utilities)

Enlarging a fully extended Db2-managed data set

If a Db2-managed data set reaches the maximum number of VSAM extents, you
can enlarge the data set.

Procedure

To enlarge a Db2-managed data set:

Chapter 13. Recovering from different Db2 for z/OS problems 583
 1. Use the SQL statement ALTER TABLESPACE or ALTER INDEX with a USING
clause. (You do not need to stop the table space before you use ALTER
TABLESPACE.) You can give new values of PRIQTY and SECQTY in either the
same or a new Db2 storage group.
2. Use one of the following procedures. No movement of data occurs until this
step is completed.
v For indexes: If you have taken full image copies of the index, run the
RECOVER INDEX utility. Otherwise, run the REBUILD INDEX utility.
v For table spaces other than LOB table spaces: Run one of the following
utilities on the table space: REORG, RECOVER, or LOAD REPLACE.
v For LOB table spaces that are defined with LOG YES: Run the RECOVER
utility on the table space.
v For LOB table spaces that are defined with LOG NO:
a. Start the table space in read-only (RO) mode to ensure that no updates
are made during this process.
b. Make an image copy of the table space.
c. Run the RECOVER utility on the table space.
d. Start the table space in read-write (RW) mode.

Adding a data set

If a user-defined simple data set reaches its maximum size, you can use access
method services to define another data set.

Procedure

To add another data set:

1. Use access method services to define another data set. The name of the new
data set must follow the naming sequence of the existing data sets that support
the object. The last four characters of each name are a relative data set number:
If the last name ends with A001, the next name must end with A002, and so on.
Also, be sure to add either the character “I” or the character “J” to the name of
the data set. If the object is defined in a Db2 storage group, Db2 automatically
tries to create an additional data set. If that fails, access method services
messages are sent to an operator to indicate the cause of the problem.
2. If necessary, correct the problem (identified in the access method services
messages) to obtain additional space.

Redefining a partition (index-based partitioning)

Sometimes each partition in a partitioned object is restricted to a single data set. If
the data set reaches its maximum size, you need to redefine the partitions.
Redefining a partition in an index-based partitioning environment is different than
in a table-based partitioning environment.

Procedure

To redefine the partitions in an index-based partitioning environment:

1. Use the ALTER INDEX ALTER PARTITION statement to alter the key range
values of the partitioning index.
2. Use the REORG utility with inline statistics on the partitions that are affected
by the change in key range.
3. Use the RUNSTATS utility on the nonpartitioned indexes.
4. Rebind the dependent packages and plans.

584 Administration Guide

 Redefining a partition (table-based partitioning)
Sometimes each partition in a partitioned object is restricted to a single data set. If
the data set reaches its maximum size, you need to redefine the partitions.
Redefining a partition in a table-based partitioning environment is different than in
an index-based partitioning environment.

Procedure

To redefine the partitions in a table-based partitioning environment:

1. Use the SQL statement ALTER TABLE ALTER PARTITION to alter the partition
boundaries.
2. Use the REORG utility with inline statistics on the partitions that are affected
by the change in partition boundaries.
3. Use the RUNSTATS utility on the indexes.
4. Rebind the dependent packages and plans.

Enlarging a fully extended data set for the work file database
If you have an out-of-disk-space or extent limit problem with the work file
database (DSNDB07), you need to add space to the data set.

Procedure

To enlarge a fully extended data set for the work file database:

Add space to the Db2 storage group, choosing one of the following approaches:
v Use SQL to create more table spaces in database DSNDB07.
v Execute these steps:
1. Use the command STOP DATABASE(DSNDB07) to ensure that no users are
accessing the database.
2. Use SQL to alter the storage group, adding volumes as necessary.
3. Use the command START DATABASE(DSNDB07) to allow access to the database.

Recovering from referential constraint violation

When a referential constraint is violated, the table space is available for some
actions, but you cannot run certain utilities or use SQL to update the data in the
table space until you recover from this situation.

Symptoms
One of the following messages is issued at the end of utility processing, depending
on whether the table space is partitioned:
DSNU561I csect-name - TABLESPACE=tablespace-name PARTITION=partnum
IS IN CHECK PENDING
DSNU563I csect-name - TABLESPACE=tablespace-name IS IN CHECK PENDING

Causes
Db2 detected one or more referential constraint violations.

Environment
The table space is still generally available. However, it is not available to the
COPY, REORG, and QUIESCE utilities, or to SQL select, insert, delete, or update
operations that involve tables in the table space.

Resolving the problem

Chapter 13. Recovering from different Db2 for z/OS problems 585
 Operator response:
1. Use the START DATABASE ACCESS (UT) command to start the table space for
utility-only access.
2. Run the CHECK DATA utility on the table space. Consider these
recommendations:
v If you do not believe that violations exist, specify DELETE NO. If violations
do not exist, specifying DELETE NO resets the CHECK-pending status;
however, if violations do exist, the status is not reset.
v If you believe that violations exist, specify the DELETE YES option and an
appropriate exception table. Specifying DELETE YES results in deletion of all
rows that are in violation, copies them to an exception table, and resets the
CHECK-pending status.
v If the CHECK-pending status was set during execution of the LOAD utility,
specify the SCOPE PENDING option. This checks only those rows that are
added to the table space by LOAD, rather than every row in the table space.
3. Correct the rows in the exception table, if necessary, and use the SQL INSERT
statement to insert them into the original table.
4. Issue the command START DATABASE to start the table space for RO or RW
access, whichever is appropriate. The table space is no longer in
CHECK-pending status and is available for use. If you use the ACCESS
(FORCE) option of this command, the CHECK-pending status is reset.
However, using ACCESS (FORCE) is not recommended because it does not
correct the underlying violations of referential constraints.
Related reference
CHECK DATA (Db2 Utilities)

Recovering from distributed data facility failure

You can recover from various problems that occur for the distributed data facility
(DDF).

Symptoms
The symptoms for DDF failures vary based on the precise problems. The
symptoms include messages, SQL return codes, and apparent wait states.

Recovering from conversation failure

A VTAM APPC or TCP/IP conversation might fail during or after allocation. The
conversation is not available for use until you recover from the situation.

Symptoms
VTAM or TCP/IP returns a resource-unavailable condition along with the
appropriate diagnostic reason code and message. A DSNL500 or DSNL511
(conversation failed) message is sent to the console for the first failure to a location
for a specific logical unit (LU) mode or TCP/IP address. All other threads that
detect a failure from that LU mode or IP address are suppressed until
communications to the LU that uses that mode are successful.

Db2 returns messages DSNL501I and DSNL502I. Message DSNL501I usually means
that the other subsystem is not operational. When the error is detected, it is
reported by a console message, and the application receives an SQL return code.

If you use application-directed access or DRDA as the database protocols,

SQLCODE -30080 is returned to the application. The SQLCA contains the VTAM

586 Administration Guide

 diagnostic information, which contains only the RCPRI and RCSEC codes. For
SNA communications errors, SQLCODE -30080 is returned. For TCP/IP
connections, SQLCODE -30081 is returned.

Environment
The application can choose to request rollback or commit, both of which deallocate
all but the first conversation between the allied thread and the remote database
access thread. A commit or rollback message is sent over this remaining
conversation.

Errors during the deallocation process of the conversation are reported through
messages, but they do not stop the commit or rollback processing. If the
conversation that is used for the commit or rollback message fails, the error is
reported. If the error occurred during a commit process and if the remote database
access was read-only, the commit process continues. Otherwise the commit process
is rolled back.

Diagnosing the problem

System programmer response: Review the VTAM or TCP/IP return codes, and
possibly discuss the problem with a communications expert. Many VTAM or
TCP/IP errors, besides the error of an inactive remote LU or TCP/IP errors,
require a person who has a knowledge of VTAM or TCP/IP and the network
configuration to diagnose them.

Resolving the problem

Operator response: Correct the cause of the unavailable-resource condition by
taking the action that is required by the diagnostic messages that are displayed on
the console.
Related concepts
SQL codes (Db2 Codes)
Related information
z/OS Communications Server: SNA Messages

Recovering from communications database failure

You need to recover the communications database (CDB) when a failure occurs
during an attempt to access the CDB.

Symptoms
A DSNL700I message, which indicates that a resource-unavailable condition exists,
is sent to the console. Other messages that describe the cause of the failure are also
sent to the console.

Environment
If the distributed data facility (DDF) has already started when an individual CDB
table becomes unavailable, DDF does not terminate. Depending on the severity of
the failure, threads are affected as follows:
v The threads receive a -904 SQL return code (SQLSTATE '57011') with resource
type 1004 (CDB).
v The threads continue using VTAM default values.

The only threads that receive a -904 SQL return code are those that access locations
that have not had any prior threads. Db2 and DDF remain operational.

Chapter 13. Recovering from different Db2 for z/OS problems 587
 Resolving the problem
Operator response:
1. Examine the messages to determine the source of the error.
2. Correct the error, and then stop and restart DDF.

Recovering from a problem with a communications database that

is incorrectly defined
You need to recover from a situation in which the communications database (CDB)
is not correctly defined. This problem occurs when distributed data facility (DDF)
is started and the Db2 catalog is accessed to verify the CDB definitions.

Symptoms
A DSNL701I, DSNL702I, DSNL703I, DSNL704I, or DSNL705I message is issued to
identify the problem. Other messages that describe the cause of the failure are also
sent to the console.

Environment
DDF fails to start. Db2 continues to run.

Resolving the problem

Operator response:
1. Examine the messages to determine the source of the error.
2. Correct the error, and then restart DDF.

Recovering from database access thread failure

When a database access thread is deallocated, a conversation failure occurs, and
you need to recover from this situation.

Symptoms
In the event of a failure of a database access thread, the Db2 server terminates the
database access thread only if a unit of recovery exists. The server deallocates the
database access thread and then deallocates the conversation with an abnormal
indication (a negative SQL code), which is subsequently returned to the requesting
application. The returned SQL code depends on the type of remote access:
v DRDA access
For a database access thread or non-Db2 server, a DDM error message is sent to
the requesting site, and the conversation is deallocated normally. The SQL error
status code is a -30020 with a resource type 1232 (agent permanent error
received from the server).

Environment
Normal Db2 error recovery mechanisms apply, with the following exceptions:
v Errors that are encountered in the functional recovery routine are automatically
converted to rollback situations. The allied thread experiences conversation
failures.
v Errors that occur during commit, rollback, and deallocate within the DDF
function do not normally cause Db2 to abend. Conversations are deallocated,
and the database access thread is terminated. The allied thread experiences
conversation failures.

Diagnosing the problem

System programmer response: Collect all diagnostic information that is related to
the failure at the serving site. For a Db2 database access thread (DBAT), a dump is
produced at the server.
588 Administration Guide
 Resolving the problem
Operator response: Communicate with the operator at the other site to take the
appropriate corrective action, regarding the messages that are displayed at both the
requesting and responding sites. Ensure that you and operators at the other sites
gather the appropriate diagnostic information and give it to the programmer for
diagnosis.

Recovering from VTAM failure

When VTAM terminates or fails, you need to recover from the situation.

Symptoms
VTAM messages and Db2 messages are issued to indicate that distributed data
facility (DDF) is terminating and to explain why.

Causes
Environment
DDF terminates. An abnormal VTAM failure or termination causes DDF to issue a
STOP DDF MODE(FORCE) command. The VTAM commands Z NET,QUICK and Z
NET,CANCEL cause an abnormal VTAM termination. A Z NET,HALT causes a STOP DDF
MODE(QUIESCE) to be issued by DDF.

Resolving the problem

Operator response: Correct the condition that is described in the messages that are
received at the console, and restart VTAM and DDF.

| Recovering from VTAM ACB OPEN problems

| The Db2 distributed data facility (DDF) might terminate after startup due to a
| VTAM ACB OPEN failure. You can diagnose the situation to determine how to
| resolve the problem.

| Symptoms
| Db2 messages, such as DSNL013I and DSNL004I, are issued to indicate the
| problem.
| DSNL013I
| Contains the error field value that is returned from the VTAM ACB OPEN.
| For information about possible values, see OPEN macroinstruction error
| fields(z/OS Communications Server: IP and SNA Codes).
| DSNL004I
| Normally specifies a fully qualified LU name, network-name.luname. The
| absence of the network-name indicates a problem.

| Resolving the problem

| 1. Determine whether VTAM is up:
| v If VTAM is not up, start VTAM, and then start DDF.
| v If VTAM did not start completely before DDF was started, start VTAM, and
| then start DDF.
| If neither of these situations exists, continue with the next step.
| 2. If VTAM is up, determine the reason for the problem. One possible reason that
| the VTAM ACB OPEN failed is that one of the following problems exists for
| the LU name that was defined to Db2 through the Db2 change log inventory
| (DSNJU003) utility DDF statement:
| v The LU name is not defined to VTAM.

Chapter 13. Recovering from different Db2 for z/OS problems 589
| v The LU name is defined, but the LU did not start automatically during
| VTAM startup.
| v The LU name that is displayed in the DSNL004I message is not valid. In this
| case, stop Db2, run a DSNJU003 utility job, and restart Db2.
| To diagnose the problem within VTAM:
| a. Issue the following command: DISPLAY NET,ID=luname,SCOPE=ALL, where
| luname is displayed in message DSNL004I, and examine the output of the
| DISPLAY command.
| v If the output suggests that the LU name does not exist, display each
| APPL node by issuing the DISPLAY APPLS command. For command
| details, see DISPLAY APPLS command (z/OS Communications Server:
| SNA Operation).
| v If you do not find an active APPL node that contains the LU name or a
| model LU name (a wildcard LU name) that Db2 can use, take one of the
| following actions:
| – If no active APPL node exists and no APPL major node definition
| exists in any library that is referenced by the VTAM started procedure
| VTAMLST DD specification, define an APPL node to VTAM, start it,
| and then start DDF.
| – If no active APPL node exists, but an APPL major node definition
| exists in a library that is referenced by the VTAM started procedure
| VTAMLST DD specification, start the major node, and then start DDF.
| The cause of this situation is that the major node was not
| automatically started during VTAM startup.
| b. Work with your VTAM administrator to ensure that the required APPL
| node or APPL major node is started automatically during VTAM startup in
| the future. For more information, see The APPL statement (Db2 Installation
| and Migration).
| 3. If the previous steps do not resolve the problem, examine the reason code from
| the DSNL013I message. If the reason code is X'24', the PRTCT value in the
| APPL definition does not match the password value that was defined to Db2 in
| the DSNJU003 DDF statement. If the password specification to Db2 is missing
| or incorrect, with Db2 stopped, run a DSNJU003 utility job, specifying a DDF
| statement with the correct password, and restart Db2.
| 4. If none of the previous steps resolves the issue, contact your VTAM
| administrator for additional help in resolving the problem.

Recovering from TCP/IP failure

When TCP/IP terminates or fails, you need to recover from this situation.

Symptoms
TCP/IP messages and Db2 messages are issued to indicate that TCP/IP is
unavailable.

Environment
Distributed data facility (DDF) periodically attempts to reconnect to TCP/IP. If the
TCP/IP listener fails, DDF automatically tries to re-establish the TCP/IP listener
for the DRDA SQL port or the resync port every three minutes. TCP/IP
connections cannot be established until the TCP/IP listener is re-established.

Resolving the problem

Operator response:

590 Administration Guide

 1. Examine the messages that are received at the console to determine the cause of
the problem.
2. Correct the condition.
3. Restart TCP/IP. You do not need to restart DDF after a TCP/IP failure.

Recovering from remote logical unit failure

When a series of conversation or change number of sessions (CNOS) failures occur
from a remote logical unit (LU), you need to recover from this situation.

Symptoms
Message DSNL501I is issued when a CNOS request to a remote LU fails. The
CNOS request is the first attempt to connect to the remote site and must be
negotiated before any conversations can be allocated. Consequently, if the remote
LU is not active, message DSNL501I is displayed to indicate that the CNOS request
cannot be negotiated. Message DSNL500I is issued only once for all the SQL
conversations that fail as a result of a remote LU failure.

Message DSNL502I is issued for system conversations that are active to the remote
LU at the time of the failure. This message contains the VTAM diagnostic
information about the cause of the failure.

Environment
Any application communications with a failed LU receives a message to indicate a
resource-unavailable condition. Any attempt to establish communication with such
an LU fails.

Resolving the problem

System programmer response: Communicate with the other involved sites
regarding the unavailable-resource condition, and request that appropriate
corrective action be taken. If a DSNL502 message is received, activate the remote
LU, or ask another operator to do so.

Recovering from an indefinite wait condition

If a distributed thread is hung, an application might be in an indefinite wait
condition. For example, an allied thread might wait indefinitely for a response
from a remote server location. Another example is a database access thread that
waits for a new request from the remote requester location.

Symptoms
An application is in an indefinitely long wait condition. This can cause other Db2
threads to fail due to resources that are held by the waiting thread. Db2 sends an
error message to the console, and the application program receives an SQL return
code.

Environment
Db2 does not respond.

Diagnosing the problem

Operator response: To check for very long waits, look to see if the conversation
timestamp is changing from the last time it was used. If it is changing, the
conversation thread is not hung, but it is taking more time for a long query. Also,
look for conversation state changes, and determine what they mean.

Resolving the problem

Chapter 13. Recovering from different Db2 for z/OS problems 591
 Operator response:
1. Use the DISPLAY THREAD command with the LOCATION and DETAIL options to
identify the LUWID and the session allocation for the waiting thread.
2. Use the CANCEL DDF THREAD command to cancel the waiting thread.
3. If the CANCEL DDF THREAD command fails to break the wait (because the thread
is not suspended in Db2), try using VTAM commands such as VARY
TERM,SID=xxx or use the TCP/IP DROP command. For instructions on how to
use the VTAM commands and TCP/IP commands, see -CANCEL THREAD
(Db2) (Db2 Commands).
Related tasks
Canceling threads

Recovering database access threads after security failure

During database access thread allocation, the remote site might not have the
proper security to access Db2 through distributed data facility (DDF). When this
happens, you can recover from the situation.

Symptoms
Message DSNL500I is issued at the requester for VTAM conversations (if it is a
Db2 subsystem) with return codes RTNCD=0, FDBK2=B, RCPRI=4, and RCSEC=5.
These return codes indicate that a security violation has occurred. The server has
deallocated the conversation because the user is not allowed to access the server.
For conversations that use DRDA access, LU 6.2 communications protocols present
specific reasons for why the user access failed, and these reasons are
communicated to the application. If the server is a Db2 database access thread,
message DSNL030I is issued to describe what caused the user to be denied access
into Db2 through DDF. No message is issued for TCP/IP connections.

If the server is a Db2 subsystem, message DSNL030I is issued. Otherwise, the

system programmer needs to refer to the documentation of the server. If the
application uses DRDA access, SQLCODE –30082 is returned.

Causes
This problem is caused by a remote user who attempts to access Db2 through DDF
without the necessary security authority.

Resolving the problem

Operator response:
1. Read about the Db2 code 00D3103D.
2. Take the appropriate action:
v If the security failure involves a Db2 database access thread, provide the
DSNL030I message to the system programmer.
v If the security failure does not involve a Db2 server, work with the operator
or programmer at the server to get diagnostic information that is needed by
the system programmer.
Related information
00D3103D (Db2 Codes)

592 Administration Guide

Performing remote-site disaster recovery
When your local system experiences damage or disruption that prevents recovery
from that site, you can recover by using a remote site that you have set up for this
purpose.

Symptoms
The specific symptoms of a disaster that affects your local system hardware vary,
but when this happens, the affected Db2 subsystem is not operational.

Causes
Your local system hardware has suffered physical damage.

Resolving the problem

System programmer response: Coordinate the activities that are detailed in
“Restoring data from image copies and archive logs.”

Operator response: At the remote-site, the disaster-recovery procedures differ from

other recovery procedures because you cannot use the hardware at your local Db2
site to recover data. Instead, you use hardware at a remote site to recover after a
disaster by using one of a variety of methods.

Recovering from a disaster by using system-level backups

If you have recent system-level backups, you can use those backups along with
one of several utilities to recover after a disaster.

Procedure

To recover from a disaster by using system-level backups:

For a remote site recovery procedure where tape volumes that contain system data
are sent from the production site, specify the dump class that is available at the
remote site by using the following installation options on installation panel
DSNTIP6:
v Either RESTORE FROM DUMP or RECOVER FROM DUMP
v DUMP CLASS NAME

Restoring data from image copies and archive logs

Follow the appropriate procedure for restoring from image copies and archive logs,
depending on whether you are in a data sharing environment. Both procedures
assume that all logs, copies, and reports are available at the recovery site.
Related information
DFSMS Access Method Services Commands

Restoring data in a non-data sharing environment

If you are in a non-data sharing environment, you might need to recover from a
disaster by restoring data from image copies and logs. The procedure that you
follow assumes that all logs, image copies, and reports are available at the recovery
site.

Procedure

To recover from a disaster in a non-data sharing environment by using image

copies and archive logs:

Chapter 13. Recovering from different Db2 for z/OS problems 593
 1. If an integrated catalog facility catalog does not already exist, run job
DSNTIJCA to create a user catalog.
2. Use the access method services IMPORT command to import the integrated
catalog facility catalog.
3. Restore Db2 libraries. Some examples of libraries that you might need to
restore include:
v Db2 SMP/E libraries
v User program libraries
v User DBRM libraries
v Db2 CLIST libraries
v Db2 libraries that contain customized installation jobs
v JCL for creating user-defined table spaces
4. Use IDCAMS DELETE NOSCRATCH to delete all catalog and user objects. (Because
step 2 imports a user ICF catalog, the catalog reflects data sets that do not
exist on disk.)
5. Obtain a copy of installation job DSNTIJIN, which creates Db2 VSAM and
non-VSAM data sets. Change the volume serial numbers in the job to volume
serial numbers that exist at the recovery site. Comment out the steps that
create Db2 non-VSAM data sets, if these data sets already exist. Run
DSNTIJIN. However, do not run DSNTIJID.
6. Recover the BSDS:
a. Use the access method services REPRO command to restore the contents of
one BSDS data set (allocated in step 5). You can find the most recent BSDS
image in the last file (archive log with the highest number) on the latest
archive log tape.
b. Determine the RBA range for this archive log by using the print log map
utility (DSNJU004) to list the current BSDS contents. Find the most recent
archive log in the BSDS listing, and add 1 to its ENDRBA value. Use this
as the STARTRBA. Find the active log in the BSDS listing that starts with
this RBA, and use its ENDRBA as the ENDRBA.
c. Delete the oldest archive log from the BSDS.
d. Register this latest archive log tape data set in the archive log inventory of
the BSDS that you just restored by using the change log inventory utility
(DSNJU003). This step is necessary because the BSDS image on an archive
log tape does not reflect the archive log data set that resides on that tape.
After these archive logs are registered, use the print log map utility
(DSNJU004) to list the contents of the BSDS.
e. Adjust the active logs in the BSDS by using the change log inventory
utility (DSNJU003), as necessary:
1) To delete all active logs in the BSDS, use the DELETE option of
DSNJU003. Use the BSDS listing that is produced in step 6d to
determine the active log data set names.
2) To add the active log data sets to the BSDS, use the NEWLOG
statement of DSNJU003. Do not specify a STARTRBA or ENDRBA in
the NEWLOG statement. This specification indicates to Db2 that the
new active logs are empty.
f. If you are using the Db2 distributed data facility, update the LOCATION
and the LUNAME values in the BSDS by running the change log inventory
utility with the DDF statement.

594 Administration Guide

 g. List the new BSDS contents by using the print log map utility (DSNJU004).
Ensure that the BSDS correctly reflects the active and archive log data set
inventories. In particular, ensure that:
v All active logs show a status of NEW and REUSABLE.
v The archive log inventory is complete and correct (for example, the start
and end RBAs are correct).
h. If you are using dual BSDSs, make a copy of the newly restored BSDS data
set to the second BSDS data set.
7. Optional: Restore archive logs to disk. Archive logs are typically stored on
tape, but restoring them to disk might speed later steps. If you elect this
option, and the archive log data sets are not cataloged in the primary
integrated catalog facility catalog, use the change log inventory utility to
update the BSDS. If the archive logs are listed as cataloged in the BSDS, Db2
allocates them by using the integrated catalog and not the unit or VOLSER
that is specified in the BSDS. If you are using dual BSDSs, remember to
update both copies.
8. Use the DSN1LOGP utility to determine which transactions were in process at
the end of the last archive log. Use the following job control language where
yyyyyyyyyyyy is the STARTRBA of the last complete checkpoint within the
RBA range on the last archive log from the previous print log map:
//SAMP EXEC PGM=DSN1LOGP
//SYSPRINT DD SYSOUT=*
//SYSSUMRY DD SYSOUT=*
//ARCHIVE DD DSN=last-archive, DISP=(OLD,KEEP),UNIT=TAPE,
LABEL=(2,SL),VOL=SER=volser1
(NOTE FILE 1 is BSDS COPY
//SYSIN DD *
STARTRBA(yyyyyyyyyyyy) SUMMARY(ONLY)
/*

DSN1LOGP generates a report.

9. Examine the DSN1LOGP output, and identify any utilities that were executing
at the end of the last archive log. Determine the appropriate recovery action to
take on each table space that is involved in a utility job. If DSN1LOGP output
showed that utilities are inflight (PLAN=DSNUTIL), examine SYSUTILX to
identify the utility status and determine the appropriate recovery approach.
10. Modify DSNZPxxx parameters:
a. Run the DSNTINST CLIST in UPDATE mode. For more information, see
Tailoring Db2 11 installation and migration jobs with the CLIST (Db2
Installation and Migration)
b. To defer processing of all databases, select DATABASES TO START
AUTOMATICALLY from panel DSNTIPB. Panel DSNTIPS opens. On panel
DSNTIPS, type DEFER in the first field and ALL in the second field; then
press Enter. You are returned to panel DSNTIPB.
c. To specify where you are recovering, select OPERATOR FUNCTIONS from
panel DSNTIPB. Panel DSNTIPO opens. From panel DSNTIPO, type
RECOVERYSITE in the SITE TYPE field. Press Enter to continue.
| d. To prevent format conversions during Disaster Recovery, select SQL
| OBJECT DEFAULTS PANEL 1 from panel DSNTIPB. Panel DSNTIP7
| opens. From panel DSNTIP7, set the UTILITY_OBJECT_CONVERSION
| value to NONE. Press Enter to continue. Format conversions complicate
| the recovery process and can lead to failures. Reset this parameter to its
| original value after the Disaster Recovery completes.

Chapter 13. Recovering from different Db2 for z/OS problems 595
 e. Optional: Specify which archive log to use by selecting OPERATOR
FUNCTIONS from panel DSNTIPB. Panel DSNTIPO opens. From panel
DSNTIPO, type YES in the READ COPY2 ARCHIVE field if you are using
dual archive logging and want to use the second copy of the archive logs.
Press Enter to continue.
f. Reassemble DSNZPxxx by using job DSNTIJUZ (produced by the CLIST
started in the first step of this procedure).
At this point, you have the log, but the table spaces have not been
recovered. With DEFER ALL, Db2 assumes that the table spaces are
unavailable but does the necessary processing to the log. This step also
handles the units of recovery that are in process.
11. Create a conditional restart control record by using the change log inventory
utility with one of the following forms of the CRESTART statement:
v CRESTART CREATE,ENDRBA=nnnnnnnnn000
The nnnnnnnnn000 equals a value that is one more than the ENDRBA of the
latest archive log.
v CRESTART CREATE,ENDTIME=nnnnnnnnnnnn
The nnnnnnnnnnnn is the end time of the log record. Log records with a
timestamp later than nnnnnnnnnnnn are truncated.
12. Enter the command START DB2 ACCESS(MAINT).
You must enter this command, because real-time statistics are active and
enabled; otherwise, errors or abends could occur during Db2 restart
processing and recovery processing (for example, GRECP recovery, LPL
recovery, or the RECOVER utility).
Even though Db2 marks all table spaces for deferred restart, log records are
written so that in-abort and inflight units of recovery are backed out.
In-commit units of recovery are completed, but no additional log records are
written at restart to cause this. This happens when the original redo log
records are applied by the RECOVER utility.
At the primary site, Db2 probably committed or aborted the inflight units of
recovery, but you have no way of knowing.
During restart, Db2 accesses two table spaces that result in DSNT501I,
DSNT500I, and DSNL700I resource unavailable messages, regardless of DEFER
status. The messages are normal and expected, and you can ignore them.
The following return codes can accompany the message. Other codes are also
possible.
00C90081
This return code is issued for activity against the object that occurs
during restart as a result of a unit of recovery or pending writes. In
this case, the status that is shown as a result of DISPLAY is STOP,DEFER.
00C90094
Because the table space is currently only a defined VSAM data set, it
is in a state that Db2 does not expect.
00C90095
Db2 cannot access the page, because the table space or index space
has not been recovered yet.
00C900A9
An attempt was made to allocate a deferred resource.
13. Resolve the indoubt units of recovery. The RECOVER utility, which you run in
a subsequent step, fails on any table space that has indoubt units of recovery.
Because of this, you must resolve them first. Determine the proper action to

596 Administration Guide

 take (commit or abort) for each unit of recovery. To resolve indoubt units of
recovery, see Resolving indoubt units of recovery. From an installation
SYSADM authorization ID, enter the RECOVER INDOUBT command for all
affected transactions.
14. Recover the catalog and directory. The RECOVER function includes:
RECOVER TABLESPACE, RECOVER INDEX, or REBUILD INDEX. If you
have an image copy of an index, use RECOVER INDEX. If you do not have
an image copy of an index, use REBUILD INDEX to reconstruct the index
from the recovered table space.
a. Recover DSNDB01.SYSUTILX. This must be a separate job step.
b. Recover all indexes on SYSUTILX. This must be a separate job step.
c. Determine whether a utility was running at the time the latest archive log
was created by entering the DISPLAY UTILITY(*) command, and record the
name and current phase of any utility that is running. (You cannot restart a
utility at the recovery site that was interrupted at the disaster site. You
must use the TERM UTILITY command to terminate it. Use the TERM UTILITY
command on a utility that is operating on any object except
DSNDB01.SYSUTILX.)
d. Run the DIAGNOSE utility with the DISPLAY SYSUTIL option. The output
consists of information about each active utility, including the table space
name (in most cases). This is the only way to correlate the object name
with the utility. Message DSNU866I gives information about the utility,
and DSNU867I gives the database and table space name in USUDBNAM
and USUSPNAM, respectively.
e. Use the TERM UTILITY command to terminate any utilities that are in
progress on catalog or directory table spaces.
f. Recover the rest of the catalog and directory objects, starting with DBD01,
in the order shown in the description of the RECOVER utility.
15. Define and initialize the work file database:
a. Define temporary work files. Use installation job DSNTIJTM as a model.
b. Issue the command START DATABASE(work-file-database) to start the work file
database.
16. Use any method that you want to verify the integrity of the Db2 catalog and
directory. Use the catalog queries in member DSNTESQ of data set
DSN1110.SDSNSAMP after the work file database is defined and initialized.
17. If you use data definition control support, recover the objects in the data
definition control support database.
18. If you use the resource limit facility, recover the objects in the resource limit
control facility database.
19. Modify DSNZPxxx to restart all databases:
a. Run the DSNTINST CLIST in UPDATE mode.
b. From panel DSNTIPB, select DATABASES TO START AUTOMATICALLY.
Panel DSNTIPS opens. Type RESTART in the first field and ALL in the
second field, and press Enter. You are returned to DSNTIPB.
c. Reassemble DSNZPxxx by using job DSNTIJUZ (produced by the CLIST
started in step 3 on page 594).
20. Stop Db2.
21. Start Db2.
22. Make a full image copy of the catalog and directory.
23. Recover user table spaces and index spaces. If utilities were running on any
table spaces or index spaces, see “What to do about utilities that were in

Chapter 13. Recovering from different Db2 for z/OS problems 597
 progress at time of failure” on page 606. You cannot restart a utility at the
recovery site that was interrupted at the disaster site. Use the TERM UTILITY
command to terminate any utilities that are running against user table spaces
or index spaces.
a. To determine which, if any, of your table spaces or index spaces are
user-managed, perform the following queries for table spaces and index
spaces.
v Table spaces:
SELECT * FROM SYSIBM.SYSTABLEPART WHERE STORTYPE=’E’;
v Index spaces:
SELECT * FROM SYSIBM.SYSINDEXPART WHERE STORTYPE=’E’;
To allocate user-managed table spaces or index spaces, use the access
method services DEFINE CLUSTER command. To find the correct IPREFIX for
the DEFINE CLUSTER command, perform the following queries for table
spaces and index spaces.
v Table spaces:
SELECT DBNAME, TSNAME, PARTITION, IPREFIX FROM SYSIBM.SYSTABLEPART
WHERE DBNAME=dbname AND TSNAME=tsname
ORDER BY PARTITION;
v Index spaces:
SELECT IXNAME, PARTITION, IPREFIX FROM SYSIBM.SYSINDEXPART
WHERE IXCREATOR=ixcreator AND IXNAME=ixname
ORDER BY PARTITION;
Now you can perform the DEFINE CLUSTER command with the correct
IPREFIX (I or J) in the data set name:
catname.DSNDBx.dbname.psname.y0001.znnn
The y can be either I or J, x is C (for VSAM clusters) or D (for VSAM data
components), and spname is either the table space or index space name.
b. If your user table spaces or index spaces are STOGROUP-defined, and if
the volume serial numbers at the recovery site are different from those at
the local site, use the SQL statement ALTER STOGROUP to change them
in the Db2 catalog.
c. Recover all user table spaces and index spaces from the appropriate image
copies. If you do not copy your indexes, use the REBUILD INDEX utility
to reconstruct the indexes.
d. Start all user table spaces and index spaces for read-write processing by
issuing the command START DATABASE with the ACCESS(RW) option.
e. Resolve any remaining CHECK-pending states that would prevent COPY
execution.
f. Run queries for which the results are known.
24. Make full image copies of all table spaces and indexes with the COPY YES
attribute.
25. Finally, compensate for work that was lost since the last archive was created
by rerunning online transactions and batch jobs.

What to do next

Determine what to do about any utilities that were in progress at the time of
failure.
Related concepts
Preparations for disaster recovery

598 Administration Guide

 What to do about utilities that were in progress at time of failure
Related tasks
Defining data sets
Migration step 1: Actions to complete before migration (Db2 Installation
and Migration)
Recovering catalog and directory objects (Db2 Utilities)
Related reference
DSN1LOGP (Db2 Utilities)

Restoring data in a data sharing environment

If you are in a data sharing environment, you might need to recover from a
disaster by restoring data from image copies and logs. The procedure that you
follow assumes that all logs, image copies, and reports are available at the recovery
site.

About this task

Additional recovery procedures for data sharing environments are also available.

Procedure

To recover from a disaster by using image copies and archive logs:

1. If you have information in your coupling facility from practice startups,
remove old information from the coupling facility. If you do not have old
information in your coupling facility, continue with the step 2.
a. Enter the following z/OS command to display the structures for this data
sharing group:
D XCF,STRUCTURE,STRNAME=grpname*
b. For group buffer pools, enter the following command to force off the
connection of those structures:
SETXCF FORCE,CONNECTION,STRNAME=strname,CONNAME=ALL

Connections for the SCA are not held at termination; therefore you do not
need to force off any SCA connections.
c. Delete all the Db2 coupling facility structures that have a STATUS of
ALLOCATED by using the following command for each structure:
SETXCF FORCE,STRUCTURE,STRNAME=strname

This step is necessary to remove old information that exists in the coupling
facility from your practice startup when you installed the group.
2. If an integrated catalog facility catalog does not already exist, run job
DSNTIJCA to create a user catalog.
3. Use the access method services IMPORT command to import the integrated
catalog facility catalog.
4. Restore Db2 libraries. Some examples of libraries that you might need to
restore include:
v Db2 SMP/E libraries
v User program libraries
v User DBRM libraries
v Db2 CLIST libraries

Chapter 13. Recovering from different Db2 for z/OS problems 599
 v Db2 libraries that contain customized installation jobs
v JCL for creating user-defined table spaces
5. Use IDCAMS DELETE NOSCRATCH to delete all catalog and user objects. (Because
step 3 on page 599 imports a user ICF catalog, the catalog reflects data sets
that do not exist on disk.)
6. Obtain a copy of the installation job DSNTIJIN, which creates Db2 VSAM and
non-VSAM data sets, for the first data sharing member. Change the volume
serial numbers in the job to volume serial numbers that exist at the recovery
site. Comment out the steps that create Db2 non-VSAM data sets, if these data
sets already exist. Run DSNTIJIN on the first data sharing member. However,
do not run DSNTIJID.
For subsequent members of the data sharing group, run the DSNTIJIN that
defines the BSDS and logs.
7. Recover the BSDS by following these steps for each member in the data
sharing group:
a. Use the access method services REPRO command to restore the contents of
one BSDS data set (allocated in step 6) on each member. You can find the
most recent BSDS image in the last file (archive log with the highest
number) on the latest archive log tape.
b. Determine the RBA and LRSN ranges for this archive log by using the
print log map utility (DSNJU004) to list the current BSDS contents. Find
the most recent archive log in the BSDS listing, and add 1 to its ENDRBA
value. Use this as the STARTRBA. Find the active log in the BSDS listing
that starts with this RBA, and use its ENDRBA as the ENDRBA. Use the
STARTLRSN and ENDLRSN of this active log data set as the LRSN range
(STARTLRSN and ENDLRSN) for this archive log.
c. Delete the oldest archive log from the BSDS.
d. Register this latest archive log tape data set in the archive log inventory of
the BSDS that you just restored by using the change log inventory utility
(DSNJU003). This step is necessary because the BSDS image on an archive
log tape does not reflect the archive log data set that resides on that tape.
Running DSNJU003 is critical for data sharing groups. Include the group
buffer pool checkpoint information that is stored in the BSDS from the
most recent archive log.
After these archive logs are registered, use the print log map utility
(DSNJU004) with the GROUP option to list the contents of all BSDSs. You
receive output that includes the start and end LRSN and RBA values for
the latest active log data sets (shown as NOTREUSABLE). If you did not
save the values from the DSNJ003I message, you can get those values by
running DSNJU004, which creates output as shown below
The following sample DSNJU004 output shows the (partial) information
for the archive log member DB1G.
| ACTIVE LOG COPY 1 DATA SETS
| START RBA/LRSN/TIME END RBA/LRSN/TIME DATE/LTIME DATA SET INFORMATION
| ---------------------- ---------------------- ---------- --------------------
| 0000000007A5C5360000 0000000007A5DB31FFFF 2005.034 DSN=DSNT3LOG.DT31.LOGCOPY1.DS01
| 00CAC6509C994A000000 00CAC650C5EDD8000000 20:22 PASSWORD=(NULL) STATUS=REUSABLE
| 2013.015 14:41:16.4 2013.015 14:41:59.7
| 0000000007A5DB320000 0000000007A5F12DFFFF 2007.051 DSN=DSNT3LOG.DT31.LOGCOPY1.DS04
| 00CAC650C5EDD8000000 00CAC650EA3857000000 13:27 PASSWORD=(NULL) STATUS=REUSABLE
| 2013.015 14:41:59.7 2013.015 14:42:37.7
The following sample DSNJU004 output shows the (partial) information
for the archive log member DB2G.

600 Administration Guide

ACTIVE LOG COPY 1 DATA SETS
START RBA/LRSN/TIME END RBA/LRSN/TIME DATE LTIME DATA SET INFORMATION
-------------------- -------------------- -------- ----- --------------------

EMPTY DATA SET 1996.361 14:14 DSN=DSNDB0G.DB2G.LOGCOPY1.DS03

000000000000 000000000000 STATUS=NEW, REUSABLE
0000.000 00:00:00.0 0000.000 00:00:00.0
000000000000 0000000D6FFF 1996.361 14:14 DSN=DSNDB0G.DB2G.LOGCOPY1.DS01
ADFA00BB70FB AE3C45276DD7 STATUS=TRUNCATED, NOTREUSABLE
1996.361 22:30:51.4 1997.048 15:28:23.7
0000000D7000 00000045AFFF 1996.361 14:14 DSN=DSNDB0G.DB2G.LOGCOPY1.DS02
AE3C45276DD8 ............ STATUS=NOTREUSABLE
1997.048 15:28:23.7 ........ ..........
e. Adjust the active logs in the BSDS by using the change log inventory
utility (DSNJU003), as necessary:
1) To delete all active logs in the BSDS, use the DELETE option of
DSNJU003. Use the BSDS listing that is produced in step 7d on page
600 to determine the active log data set names.
2) To add the active log data sets to the BSDS, use the NEWLOG
statement of DSNJU003. Do not specify a STARTRBA or ENDRBA in
the NEWLOG statement. This specification indicates to Db2 that the
new active logs are empty.
f. If you are using the Db2 distributed data facility, update the LOCATION
and the LUNAME values in the BSDS by running the change log inventory
utility with the DDF statement.
g. List the new BSDS contents by using the print log map utility (DSNJU004).
Ensure that the BSDS correctly reflects the active and archive log data set
inventories. In particular, ensure that:
v All active logs show a status of NEW and REUSABLE.
v The archive log inventory is complete and correct (for example, the start
and end RBAs are correct).
h. If you are using dual BSDSs, make a copy of the newly restored BSDS data
set to the second BSDS data set.
8. Optional: Restore archive logs to disk for each member. Archive logs are
typically stored on tape, but restoring them to disk might speed later steps. If
you elect this option, and the archive log data sets are not cataloged in the
primary integrated catalog facility catalog, use the change log inventory utility
to update the BSDS. If the archive logs are listed as cataloged in the BSDS,
Db2 allocates them by using the integrated catalog and not the unit or
VOLSER that is specified in the BSDS. If you are using dual BSDSs, remember
to update both copies.
9. Use the DSN1LOGP utility to determine, for each member of the data sharing
group, which transactions were in process at the end of the last archive log.
Use the following job control language where yyyyyyyyyyyy is the STARTRBA
of the last complete checkpoint within the RBA range on the last archive log
from the previous print log map:
//SAMP EXEC PGM=DSN1LOGP
//SYSPRINT DD SYSOUT=*
//SYSSUMRY DD SYSOUT=*
//ARCHIVE DD DSN=last-archive, DISP=(OLD,KEEP),UNIT=TAPE,
LABEL=(2,SL),VOL=SER=volser1
(NOTE FILE 1 is BSDS COPY
//SYSIN DD *
STARTRBA(yyyyyyyyyyyy) SUMMARY(ONLY)
/*

DSN1LOGP generates a report.

Chapter 13. Recovering from different Db2 for z/OS problems 601
 10. Examine the DSN1LOGP output for each data sharing member, and identify
any utilities that were executing at the end of the last archive log. Determine
the appropriate recovery action to take on each table space that is involved in
a utility job. If DSN1LOGP output showed that utilities are inflight
(PLAN=DSNUTIL), examine SYSUTILX to identify the utility status and
determine the appropriate recovery approach.
11. Modify DSNZPxxx parameters for each member of the data sharing group:
a. Run the DSNTINST CLIST in UPDATE mode.
b. To defer processing of all databases, select DATABASES TO START
AUTOMATICALLY from panel DSNTIPB. Panel DSNTIPS opens. On panel
DSNTIPS, type DEFER in the first field and ALL in the second field; then
press Enter. You are returned to panel DSNTIPB.
c. To specify where you are recovering, select OPERATOR FUNCTIONS from
panel DSNTIPB. Panel DSNTIPO opens. From panel DSNTIPO, type
RECOVERYSITE in the SITE TYPE field. Press Enter to continue.
d. Optional: Specify which archive log to use by selecting OPERATOR
FUNCTIONS from panel DSNTIPB. Panel DSNTIPO opens. From panel
DSNTIPO, type YES in the READ ARCHIVE COPY2 field if you are using
dual archive logging and want to use the second copy of the archive logs.
Press Enter to continue.
e. Reassemble DSNZPxxx by using job DSNTIJUZ (produced by the CLIST
started in the first step of this procedure).
At this point, you have the log, but the table spaces have not been
recovered. With DEFER ALL, Db2 assumes that the table spaces are
unavailable but does the necessary processing to the log. This step also
handles the units of recovery that are in process.
12. Create a conditional restart control record for each data sharing member by
using the change log inventory utility with one of the following forms of the
CRESTART statement:
v CRESTART CREATE,ENDLRSN=nnnnnnnnnnnn
The nnnnnnnnnnnn is the LRSN of the last log record that is to be used
during restart.
v CRESTART CREATE,ENDTIME=nnnnnnnnnnnn
The nnnnnnnnnnnn is the end time of the log record. Log records with a
timestamp later than nnnnnnnnnnnn are truncated.
Use the same LRSN or system time-of-day clock timestamp value for all
members in a data sharing group. Determine the ENDLRSN value by using
one of the following methods:
v Use the DSN1LOGP summary utility. In the “Summary of Completed
Events” section, find the lowest LRSN value that is listed in the DSN1213I
message for the data sharing group. Use this value for the ENDLRSN in the
CRESTART statement.
v Use the print log map utility (DSNJU004) to list the BSDS contents. Find the
ENDLRSN of the last log record that is available for each active member of
the data sharing group. Subtract 1 from the lowest ENDLRSN in the data
sharing group. Use this value for the ENDLRSN in the CRESTART
statement. (In the sample output that is shown in step 7d on page 600, the
value is AE3C45273A77 - 1, which is AE3C45273A76.)
v If only the console logs are available, use the archive offload message
(DSNJ003I) to obtain the ENDLRSN. Compare the ending LRSN values for
the archive logs of all members. Subtract 1 from the lowest LRSN in the
data sharing group. Use this value for the ENDLRSN in the CRESTART

602 Administration Guide

 statement. (In the sample output that is shown in step 7d on page 600, the
value is AE3C45273A77 - 1, which is AE3C45273A76.)
Db2 discards any log information in the bootstrap data set and the active logs
with an RBA greater than or equal to nnnnnnnnn000 or an LRSN greater than
nnnnnnnnnnnn as listed in the preceding CRESTART statements.
Use the print log map utility to verify that the conditional restart control
record that you created in the previous step is active.
13. Enter the command START DB2 ACCESS(MAINT).
You must enter this command, because real-time statistics are active and
enabled; otherwise, errors or abends could occur during Db2 restart
processing and recovery processing (for example, GRECP recovery, LPL
recovery, or the RECOVER utility).
If a discrepancy exists among the print log map reports as to the number of
members in the group, which would be an unlikely occurrence, record the one
that shows the highest number of members. Start this Db2 subsystem first
using ACCESS(MAINT). Db2 prompts you to start each additional Db2
subsystem in the group.
After all additional members are successfully restarted, and if you are going to
run single-system data sharing at the recovery site, stop all except one of the
Db2 subsystems by using the STOP DB2 command with MODE(QUIESCE).
If you planned to use the light mode when starting the Db2 group, add the
LIGHT parameter to the START command. Start the members that run in
LIGHT(NO) mode first, followed by the light mode members.
Even though Db2 marks all table spaces for deferred restart, log records are
written so that in-abort and inflight units of recovery are backed out.
In-commit units of recovery are completed, but no additional log records are
written at restart to cause this. This happens when the original redo log
records are applied by the RECOVER utility.
At the primary site, Db2 probably committed or canceled the inflight units of
recovery, but you have no way of knowing.
During restart, Db2 accesses two table spaces that result in DSNT501I,
DSNT500I, and DSNL700I resource unavailable messages, regardless of DEFER
status. The messages are normal and expected, and you can ignore them.
The following return codes can accompany the message. Other codes are also
possible.
00C90081
This return code is issued for activity against the object that occurs
during restart as a result of a unit of recovery or pending writes. In
this case, the status that is shown as a result of DISPLAY is STOP,DEFER.
00C90094
Because the table space is currently only a defined VSAM data set, it
is in a state that Db2 does not expect.
00C900A9
An attempt was made to allocate a deferred resource.
14. Resolve the indoubt units of recovery. The RECOVER utility, which you run in
a subsequent step, fails on any table space that has indoubt units of recovery.
Because of this, you must resolve them first. Determine the proper action to
take (commit or abort) for each unit of recovery. To resolve indoubt units of
recovery, see Resolving indoubt units of recovery. From an installation
SYSADM authorization ID, enter the RECOVER INDOUBT command for all
affected transactions.

Chapter 13. Recovering from different Db2 for z/OS problems 603
 15. Recover the catalog and directory. The RECOVER function includes:
RECOVER TABLESPACE, RECOVER INDEX, or REBUILD INDEX. If you
have an image copy of an index, use RECOVER INDEX. If you do not have
an image copy of an index, use REBUILD INDEX to reconstruct the index
from the recovered table space.
a. Recover DSNDB01.SYSUTILX. This must be a separate job step.
b. Recover all indexes on SYSUTILX. This must be a separate job step.
c. Determine whether a utility was running at the time the latest archive log
was created by entering the DISPLAY UTILITY(*) command, and record the
name and current phase of any utility that is running. (You cannot restart a
utility at the recovery site that was interrupted at the disaster site. To
terminate a utility at the recovery site that was interrupted at the disaster
site, you must use the TERM UTILITY command.)
d. Run the DIAGNOSE utility with the DISPLAY SYSUTIL option. The output
consists of information about each active utility, including the table space
name (in most cases). This is the only way to correlate the object name
with the utility. Message DSNU866I gives information about the utility,
and DSNU867I gives the database and table space name in USUDBNAM
and USUSPNAM, respectively.
e. Use the TERM UTILITY command to terminate any utilities that are in
progress on catalog or directory table spaces.
f. Recover the rest of the catalog and directory objects, starting with DBD01,
in the order shown in the description of the RECOVER utility.
16. Define and initialize the work file database
a. Define temporary work files. Use installation job DSNTIJTM as a model.
b. Issue the command START DATABASE(work-file-database) to start the work file
database.
17. Use any method that you want to verify the integrity of the Db2 catalog and
directory. Use the catalog queries in member DSNTESQ of data set
DSN1110.SDSNSAMP after the work file database is defined and initialized.
18. If you use data definition control support, recover the objects in the data
definition control support database.
19. If you use the resource limit facility, recover the objects in the resource limit
control facility database.
20. Modify DSNZPxxx to restart all databases on each member of the data sharing
group:
a. Run the DSNTINST CLIST in UPDATE mode. For more information, see
Tailoring Db2 11 installation and migration jobs with the CLIST (Db2
Installation and Migration).
b. From panel DSNTIPB, select DATABASES TO START AUTOMATICALLY.
Panel DSNTIPS opens. Type RESTART in the first field and ALL in the
second field, and press Enter. You are returned to DSNTIPB.
c. Reassemble DSNZPxxx by using job DSNTIJUZ (produced by the CLIST
started in step 4 on page 599).
21. Stop Db2.
22. Start Db2.
23. Make a full image copy of the catalog and directory.
24. Recover user table spaces and index spaces. If utilities were running on any
table spaces or index spaces, see “What to do about utilities that were in
progress at time of failure” on page 606. You cannot restart a utility at the

604 Administration Guide

 recovery site that was interrupted at the disaster site. Use the TERM UTILITY
command to terminate any utilities that are running against user table spaces
or index spaces.
a. To determine which, if any, of your table spaces or index spaces are
user-managed, perform the following queries for table spaces and index
spaces.
v Table spaces:
SELECT * FROM SYSIBM.SYSTABLEPART WHERE STORTYPE=’E’;
v Index spaces:
SELECT * FROM SYSIBM.SYSINDEXPART WHERE STORTYPE=’E’;
To allocate user-managed table spaces or index spaces, use the access
method services DEFINE CLUSTER command. To find the correct IPREFIX for
the DEFINE CLUSTER command, perform the following queries for table
spaces and index spaces.
v Table spaces:
SELECT DBNAME, TSNAME, PARTITION, IPREFIX FROM SYSIBM.SYSTABLEPART
WHERE DBNAME=dbname AND TSNAME=tsname
ORDER BY PARTITION;
v Index spaces:
SELECT IXNAME, PARTITION, IPREFIX FROM SYSIBM.SYSINDEXPART
WHERE IXCREATOR=ixcreator AND IXNAME=ixname
ORDER BY PARTITION;
Now you can perform the DEFINE CLUSTER command with the correct
IPREFIX (I or J) in the data set name:
catname.DSNDBx.dbname.psname.y0001.znnn
The y can be either I or J, x is C (for VSAM clusters) or D (for VSAM data
components), and spname is either the table space or index space name.
b. If your user table spaces or index spaces are STOGROUP-defined, and if
the volume serial numbers at the recovery site are different from those at
the local site, use the SQL statement ALTER STOGROUP to change them
in the Db2 catalog.
c. Recover all user table spaces and index spaces from the appropriate image
copies. If you do not copy your indexes, use the REBUILD INDEX utility
to reconstruct the indexes.
d. Start all user table spaces and index spaces for read-write processing by
issuing the command START DATABASE with the ACCESS(RW) option.
e. Resolve any remaining CHECK-pending states that would prevent COPY
execution.
f. Run queries for which the results are known.
25. Make full image copies of all table spaces and indexes with the COPY YES
attribute.
26. Finally, compensate for work that was lost since the last archive was created
by rerunning online transactions and batch jobs.

What to do next

Determine what to do about any utilities that were in progress at the time of
failure.
Related concepts
Preparations for disaster recovery
What to do about utilities that were in progress at time of failure

Chapter 13. Recovering from different Db2 for z/OS problems 605
 Recovering data (Db2 Data Sharing Planning and Administration)
Related tasks
Migration step 1: Actions to complete before migration (Db2 Installation
and Migration)
Recovering catalog and directory objects (Db2 Utilities)
Related reference
DSN1LOGP (Db2 Utilities)

What to do about utilities that were in progress at time of failure

After you restore data from image copies and archives, you might need to take
some additional steps. For example, you need to determine what to do about any
utilities that were in progress at the time of the failure.

You might need to take additional steps if any utility jobs were running after the
last time that the log was offloaded before the disaster.

After restarting Db2, only certain utilities need to be terminated with the TERM
UTILITY command.

Allowing the RECOVER utility to reset pending states is preferable. However, you
might occasionally need to use the REPAIR utility to reset them. Do not start the
table space with ACCESS(FORCE) because FORCE resets any page set exception
conditions described in “Database page set controls.”

For the following utility jobs, perform the indicated actions:

CHECK DATA
Terminate the utility, and run it again after recovery is complete.
COPY After you enter the TERM UTILITY command, Db2 places a record in the
SYSCOPY catalog table to indicate that the COPY utility job was
terminated. This makes it necessary for you to make a full image copy.
When you copy your environment at the completion of the disaster
recovery scenario, you fulfill that requirement.
LOAD
Find the options that you specified in the following table, and perform the
specified actions. For the SORTKEYS option, you must specify a value that
is greater than zero for integer. If you specify zero for integer, the
SORTKEYS option does not apply.
Table 50. Actions to take when a LOAD utility job is interrupted
LOAD options specified What to do
LOG YES If the RELOAD phase completed, recover to the current
time. Recover the indexes.

If the RELOAD phase did not complete, recover to a prior

point in time. The SYSCOPY record that is inserted at the
beginning of the RELOAD phase contains the RBA or LRSN.
LOG NO and copy-spec If the RELOAD phase completed, the table space is complete
after you recover it to the current time. Recover the indexes.

If the RELOAD phase did not complete, recover the table

space to a prior point in time. Recover the indexes.

606 Administration Guide

Table 50. Actions to take when a LOAD utility job is interrupted (continued)
LOAD options specified What to do
LOG NO, copy-spec, and If the BUILD or SORTBLD phase completed, recover to the
SORTKEYS integer current time, and recover the indexes.

If the BUILD or SORTBLD phase did not complete, recover

to a prior point in time. Recover the indexes.
LOG NO Recover the table space to a prior point in time. You can use
the TOCOPY option of the RECOVER utility to do this.

To avoid extra loss of data in a future disaster situation, run the QUIESCE
utility on table spaces before invoking the LOAD utility. This enables you
to recover a table space by using the TOLOGPOINT option instead of
TOCOPY.
REORG
For a user table space, find the options that you specified in the following
table, and perform the specified actions.

Recommendation: Make full image copies of the catalog and directory

before you run REORG on them.
Table 51. Actions to take when the REORG utility is interrupted
REORG options specified What to do
LOG YES If the RELOAD phase completed, recover to the current
time. Recover the indexes.

If the RELOAD phase did not complete, recover to the

current time to restore the table space to the point before the
REORG job began. Recover the indexes.
LOG NO If the build or SORTBLD phase completed, recover to the
current time, and recover the indexes.

If the build or SORTBLD phase did not complete, recover to

the current time to restore the table space to the point before
the REORG job began. Recover the indexes.
SHRLEVEL CHANGE or If the SWITCH phase completed, terminate the utility.
SHRLEVEL REFERENCE Recover the table space to the current time. Recover the
indexes.

If the SWITCH phase did not complete, recover the table

space to the current time. Recover the indexes.

For a catalog or directory table space, the instructions are somewhat

different. For those table spaces that were using online REORG, find the
options that you specified in the preceding table, and perform the specified
actions.
If you have no image copies from immediately before REORG failed, use
this procedure:
1. From your DISPLAY UTILITY command and DIAGNOSE utility output,
determine what phase the REORG job was in and which table space it
was reorganizing when the disaster occurred.
2. Run the RECOVER utility on the catalog and directory in the correct
order. Recover all table spaces to the current time, except the table
space that was being reorganized at the time of the disaster. If the

Chapter 13. Recovering from different Db2 for z/OS problems 607
 RELOAD phase of the REORG job on that table space had not
completed when the disaster occurred, recover the table space to the
current time. Because REORG does not generate any log records prior
to the RELOAD phase for catalog and directory objects, a recovery to
the current time restores the data to the state that it was in before the
REORG job. If the RELOAD phase completed, perform the following
actions:
a. Run the DSN1LOGP utility against the archive log data sets from
the disaster site.
b. Find the begin-UR log record for the REORG job that failed in the
DSN1LOGP output.
c. Run the RECOVER utility with the TOLOGPOINT option on the
table space that was being reorganized. Use the URID of the
begin-UR record as the TOLOGPOINT value.
3. Recover or rebuild all indexes.
If you have image copies from immediately before the REORG job failed,
run the RECOVER utility with the TOCOPY option to recover the catalog
and directory, in the correct order.
Related tasks
Recovering catalog and directory objects (Db2 Utilities)

Recovering from disasters by using a tracker site

You can use a tracker site for disaster recovery. A Db2 tracker site is a separate Db2
subsystem or data sharing group that exists solely to keep shadow copies of the
data at your primary site.

About this task

Using a tracker site for disaster recovery is somewhat similar to other methods.

Recommendation: Test and document a disaster procedure that is customized for

your location.

From the primary site, you transfer the BSDS and the archive logs, and that tracker
site runs periodic LOGONLY recoveries to keep the shadow data up-to-date. If a
disaster occurs at the primary site, the tracker site becomes the takeover site.
Because the tracker site has been shadowing the activity on the primary site, you
do not need to constantly ship image copies; the takeover time for the tracker site
might be faster because Db2 recovery does not need to use image copies.

Characteristics of a tracker site

A tracker site is a separate Db2 subsystem or data sharing group that exists solely
for the purpose of keeping shadow copies of the data at your primary site.

Because the tracker site must use only the primary site logs for recovery, you must
not update the catalog and directory or the data at the tracker site. The Db2
subsystem at the tracker site disallows updates.
v The following SQL statements are not allowed at a tracker site:
– GRANT or REVOKE
– DROP, ALTER, or CREATE
– UPDATE, INSERT, or DELETE

608 Administration Guide

 Dynamic read-only SELECT statements are allowed, but not recommended. At
the end of each tracker site recovery cycle, databases might contain
uncommitted data, and indexes might be inconsistent with the data at the
tracker site.
v The only online utilities that are allowed are REPORT, DIAGNOSE, RECOVER,
REBUILD, and RESTORE SYSTEM LOGONLY. Recovery to a prior point in time
is not allowed.
v BIND is not allowed.
v TERM UTIL is not allowed for LOAD, REORG, REPAIR, and COPY.
v The START DATABASE command is not allowed when LPL or GRECP status exists
for the object of the command. Use of the START DATABASE command is not
necessary to clear LPL or GRECP conditions because you are going to be
running RECOVER jobs that clear the conditions.
v The START DATABASE command with ACCESS(FORCE) is not allowed.
v Down-level detection is disabled.
v Log archiving is disabled.
v Real-time statistics are disabled.

Setting up a tracker site

For disaster recovery purposes, you might want to set up a tracker site. To set up a
tracker site, you create a mirror image of your primary Db2 subsystem, and then
ensure that the tracker site is synchronized with the primary site.

Procedure

To set up the tracker site:

1. Create a mirror image of your primary Db2 subsystem or data sharing group.
This process is described in steps 1 through 4 of the normal disaster recovery
procedure, which includes creating catalogs and restoring Db2 libraries.
2. Modify the subsystem parameters as follows:
v Set the TRKSITE subsystem parameter to YES.
v Optionally, set the SITETYP parameter to RECOVERYSITE if the full image
copies that this site is to receive are created as remote site copies.
3. Use the access method services DEFINE CLUSTER command to allocate data sets
for all user-managed table spaces that you plan to send over from the primary
site.
4. Optional: Allocate data sets for user-managed indexes that you want to rebuild
during recovery cycles. The main reason that you rebuild indexes during
recovery cycles is for running efficient queries on the tracker site. If you do not
require indexes, you do not need to rebuild them for recovery cycles. For
nonpartitioning indexes on very large tables, you can include indexes for
LOGONLY recovery during the recovery cycle, which can reduce the amount of
time that it takes to bring up the disaster site. Be sure that you define data sets
with the proper prefix (either I or J) for both indexes and table spaces.
5. Send full image copies of all Db2 data at the primary site to the tracker site.
Optionally, you can use the BACKUP SYSTEM utility with the DATA ONLY
option and send copies of the database copy pool to the tracker site. If you
send copies that the BACKUP SYSTEM utility creates, this step completes the
tracker site setup procedure.
6. If you did not use the BACKUP SYSTEM utility in the prior, tailor installation
job DSNTIJIN to create Db2 catalog data sets.

Chapter 13. Recovering from different Db2 for z/OS problems 609
 What to do next

Important: Do not attempt to start the tracker site when you are setting it up. You
must follow the procedure described in “Establishing a recovery cycle by using
RESTORE SYSTEM LOGONLY” on page 611.
Related reference
BACKUP SYSTEM (Db2 Utilities)

| Migrating a tracker site to Db2 11 conversion mode or converting

| a tracker site to Db2 11 new-function mode
| When you migrate a DB2 10 production subsystem or data sharing group that has
| a tracker site to Db2 11 conversion mode or convert a Db2 11 production site to
| new-function mode, you need to follow a special procedure to migrate or convert
| the tracker site.

| Before you begin

| You need to migrate or convert the tracker site after you perform any of the
| following operations on the production site:
| v Migrate from DB2 10 new-function mode to Db2 11 conversion mode
| v Convert from Db2 11 conversion mode to Db2 11 enabling-new-function mode
| v Convert from Db2 11 enabling-new-function mode to Db2 11 new-function mode
| v Revert from Db2 11 new-function mode to Db2 11 conversion mode*

| You do not need to perform fallback of the tracker site after you perform fallback
| of a production site from Db2 11 conversion mode to DB2 10 new-function mode,
| unless the fallback process restores the catalog and directory to a point in time
| prior to the migration to Db2 11.

| Procedure

| To migrate or convert the tracker site to Db2 11, follow one of the following
| procedures:
| v If you use RESTORE SYSTEM for recovery cycles, follow the procedure in
| Establishing a recovery cycle by using RESTORE SYSTEM LOGONLY.
| v If you use the RECOVER utility for recovery cycles, follow these steps.
| 1. If the tracker site is a data sharing group, issue the z/OS SETXCF FORCE
| command to delete the shared communications area (SCA) structure.
| 2. Recover the BSDS and active logs using copies of the production site's BSDS
| and active logs.
| 3. Create a conditional restart control record (CRCR) in the BSDS by using the
| change log inventory utility.
| 4. Start Db2 on the tracker site. The subsystem parameter module for starting
| Db2 needs to include TRKRSITE=YES.
| 5. Recover the DSNDB01.SYSUTILX, DSNDB01.DBD01, and
| DSNDB01.SYSDBDXA table spaces, and rebuild their indexes.
| 6. Stop Db2.
| 7. Perform steps 1, 2, and 3 again.
| 8. Start Db2 on the tracker site with the TRKRSITE=YES option again, to cause
| Db2 to read the new database descriptor information from the
| DSNDB01.DBD01 table space.

610 Administration Guide

| 9. Recover all remaining catalog and directory table spaces, and rebuild their
| indexes.
| Related tasks
| Recovering catalog and directory objects (Db2 Utilities)
| Establishing a recovery cycle by using RESTORE SYSTEM LOGONLY
| Related reference
| z/OS SETXCF FORCE command (MVS System Commands)
| DSNJU003 (change log inventory) (Db2 Utilities)
| TRACKER SITE field (TRKRSITE subsystem parameter) (Db2 Installation
| and Migration)

Establishing a recovery cycle by using RESTORE SYSTEM

LOGONLY
Each time that you restore the logs and the BSDS from the primary site at your
tracker site, you establish a new recovery cycle. One way to establish a recovery
cycle is to use the RESTORE SYSTEM utility with the LOGONLY option.

Before you begin

Full image copies of all the data at the primary site must be available at the tracker
site.

About this task

Using the LOGONLY option of the RESTORE SYSTEM utility enables you to
periodically apply the active log, archive logs, and the BSDS from the primary site
at the tracker site.

Procedure

To establish a recovery cycle at your tracker site by using the RESTORE SYSTEM
utility:
1. While your primary site continues its usual workload, send a copy of the
primary site active log, archive logs, and BSDS to the tracker site. Send full
image copies for the following objects:
v Table spaces or partitions that are reorganized, loaded, or repaired with the
LOG NO option after the latest recovery cycle
v Objects that, after the latest recovery cycle, have been recovered to a point
in time

Recommendation: If you are taking incremental image copies, run the

MERGECOPY utility at the primary site before sending the copy to the tracker
site.
2. At the tracker site, restore the BSDS that was received from the primary site
by following these steps:
a. Locate the BSDS in the latest archive log that is now at the tracker site.
b. Register this archive log in the archive log inventory of the new BSDS by
using the change log inventory utility (DSNJU003).
c. Register the primary site active log in the new BSDS by using the change
log inventory utility (DSNJU003).

Chapter 13. Recovering from different Db2 for z/OS problems 611
 3. Use the change log inventory utility (DSNJU003) with the following
CRESTART control statement:
CRESTART CREATE,ENDRBA=nnnnnnnnn000, FORWARD=NO,BACKOUT=NO

In this control statement, nnnnnnnnn equals the RBA at which the latest
archive log record ends +1. Do not specify the RBA at which the archive log
begins because you cannot cold start or skip logs in tracker mode.
Data sharing
If you are recovering a data sharing group, you must use the
following CRESTART control statement on all members of the data
sharing group. The ENDLRSN value must be the same for all
members.
CRESTART CREATE,ENDLRSN=nnnnnnnnnnnn,FORWARD=NO,BACKOUT=NO

In this control statement, nnnnnnnnnnnn is the lowest LRSN of all the

members that are to be read during restart. Specify one of the
following values for the ENDLRSN:
v If you receive the ENDLRSN from the output of the print log map
utility (DSNJU004) or from the console logs using message
DSNJ003I, you must use ENDLRSN -1 as the input to the
conditional restart.
v If you receive the ENDLRSN from the output of the DSN1LOGP
utility (message DSN1213I), you can use the displayed value.
The ENDLRSN or ENDRBA value indicates the end log point for data
recovery and for truncating the archive log. With ENDLRSN, the missing log
records between the lowest and highest ENDLRSN values for all the members
are applied during the next recovery cycle.
4. If the tracker site is a data sharing group, delete all Db2 coupling facility
structures before restarting the tracker members.
5. If you used the DSN1COPY utility to create a copy of SYSUTILX during the
last tracker cycle, restore this copy with DSN1COPY.
Data sharing
For data sharing, restart every member of the data sharing group.
6. At the tracker site, stop and start Db2 to begin a tracker site recovery cycle.
7. At the tracker site, run the RESTORE SYSTEM utility with the LOGONLY
option to apply the logs (both archive and active) to the data at the tracker
site.
8. If the RESTORE SYSTEM utility issues a return code of 4, use the DSN1COPY
utility to make a copy of SYSUTILX and of indexes that are associated with
SYSUTILX before you recover or rebuild those objects. DSN1COPY issues a
return code of 4 if application of the log results in one or more Db2 objects
being marked as RECP or RBDP.
| 9. If you are performing this procedure on a tracker site because you migrated
| the production site to Db2 11 conversion mode, converted the production site
| to Db2 11 enabling-new-function mode or new-function mode, or reverted the
| production site from Db2 11 new-function mode to conversion mode*, and the
| RESTORE SYSTEM utility leaves directory table spaces DSNDB01.DBD01 and
| DSNDB01.SYSDBDXA in RECOVER-pending status, perform these sub-steps.
| Otherwise, continue the procedure with step 10 on page 613.
| a. Stop and start Db2 at the tracker site.
| b. Run the RECOVER utility on DSNDB01.DBD01 and
| DSNDB01.SYSDBDXA.

612 Administration Guide

| c. Run the REBUILD INDEX utility to rebuild the indexes on tables in
| DSNDB01.DBD01 and DSNDB01.SYSDBDXA.
10. Stop and start Db2 at the tracker site.
11. Issue the DISPLAY DATABASE RESTRICT command to display objects that are
marked RECP, RBDP, or LPL and to identify which objects are in a utility
progress state (such as UTUT or UTRO). Run the RECOVER or REBUILD
INDEX utility on these objects, or record which objects are in an exception
state so that you can recover them at a later time. The exception states of these
objects are not retained in the next recovery cycle.
12. After all recovery activity complete at the tracker site, shut down the Db2
tracker site.
13. Optional: Stop and start the Db2 tracker site several times before completing a
recovery cycle.
Related concepts
Media failures during LOGONLY recovery
Related tasks
Establishing a recovery cycle by using the RECOVER utility
Restoring data from image copies and archive logs

Establishing a recovery cycle by using the RECOVER utility

Each time that you restore the logs and the BSDS from the primary site at your
tracker site, you establish a new recovery cycle. One way to establish a recovery
cycle is to use the RECOVER utility.

Procedure

To establish a recovery cycle by using the RECOVER utility:

1. While your primary site continues its usual workload, send a copy of the
primary site active log, archive logs, and BSDS to the tracker site. Send full
image copies for the following objects:
v Table spaces or partitions that are reorganized, loaded, or repaired with the
LOG NO option after the latest recovery cycle.
v Objects that, after the latest recovery cycle, have been recovered to a point
in time.
v SYSUTILX. Send a full image copy to DSNDB01.SYSUTILX for normal (full
image copy and log) recoveries. For LOGONLY recoveries, create a copy of
DSNDB01.SYSUTILX by using the DSN1COPY utility.
Db2 does not write SYSLGRNX entries for DSNDB01.SYSUTILX, which can
lead to long recovery times at the tracker site. In addition, SYSUTILX and its
indexes are updated during the tracker cycle when you run your recoveries.
Because SYSUTILX must remain consistent with the SYSUTILX at the primary
site, discard the tracker cycle updates before the next tracker cycle.

Recommendation: If you are taking incremental image copies, run the

MERGECOPY utility at the primary site before sending the copy to the tracker
site.
2. At the tracker site, restore the BSDS that was received from the primary site
by using one of the following methods:
v Locate the BSDS in the latest archive log that is now at the tracker site.
v Register this archive log in the archive log inventory of the new BSDS by
using the change log inventory utility (DSNJU003).

Chapter 13. Recovering from different Db2 for z/OS problems 613
 v Register the primary site active log in the new BSDS by using the change
log inventory utility (DSNJU003).
3. Use the change log inventory utility (DSNJU003) with the following
CRESTART control statement:
CRESTART CREATE,ENDRBA=nnnnnnnnn000, FORWARD=NO,BACKOUT=NO
In this control statement, nnnnnnnnn000 equals the value of the ENDRBA of
the latest archive log plus 1. Do not specify STARTRBA because you cannot
cold start or skip logs in a tracker system.
Data sharing
If you are recovering a data sharing group, you must use the
following CRESTART control statement on all members of the data
sharing group. The ENDLRSN value must be the same for all
members.
CRESTART CREATE,ENDLRSN=nnnnnnnnnnnn,FORWARD=NO,BACKOUT=NO

In this control statement, nnnnnnnnnnnn is the lowest ENDLRSN of all

the members that are to be read during restart. Specify one of the
following values for the ENDLRSN:
v If you receive the ENDLRSN from the output of the print log map
utility (DSNJU004) or from message DSNJ003I at the console logs
use ENDLRSN -1 as the input to the conditional restart.
v If you receive the ENDLRSN from the output of the DSN1LOGP
utility (DSN1213I message), use the displayed value.

The ENDLRSN or ENDRBA value indicates the end log point for data
recovery and for truncating the archive log. With ENDLRSN, the missing log
records between the lowest and highest ENDLRSN values for all the members
are applied during the next recovery cycle.
4. If the tracker site is a data sharing group, delete all Db2 coupling facility
structures before restarting the tracker members.
5. At the tracker site, restart Db2 to begin a tracker site recovery cycle.
Data sharing
For data sharing, restart every member of the data sharing group.
6. At the tracker site, submit RECOVER utility jobs to recover database objects.
Run the RECOVER utility with the LOGONLY option on all database objects
that do not require recovery from an image copy.
You must recover database objects as the following procedure specifies:
a. Restore the full image copy or DSN1COPY of SYSUTILX.
If you are doing a LOGONLY recovery on SYSUTILX from a previous
DSN1COPY backup, make another DSN1COPY copy of that table space
after the LOGONLY recovery is complete and before recovering any other
catalog or directory objects.
After you recover SYSUTILX and either recover or rebuild its indexes, and
before you recover other system and user table spaces, determine what
utilities were running at the primary site.
b. Recover the catalog and directory in the correct order.
If you have user-defined catalog indexes, rebuilding them is optional until
the tracker Db2 site becomes the takeover Db2 site. (You might want to
rebuild them sooner if you require them for catalog query performance.)
However, if you are recovering user-defined catalog indexes, do the
recovery in this step.

614 Administration Guide

| Exception: If you have any user-defined, STOGROUP-managed indexes on
| the Db2 catalog and directory, you must rebuild IBM-defined indexes by
| name.
c. If needed, recover other system data such as the data definition control
support table spaces and the resource limit facility table spaces.
d. Recover user data and, optionally, rebuild your indexes.
You do not need to rebuild indexes unless you intend to run dynamic
queries on the data at the tracker site.
For a tracker site, Db2 stores the conditional restart ENDRBA or ENDLRSN in
the page set after each recovery completes successfully. By storing the log
truncation value in the page set, Db2 ensures that it does not skip any log
records between recovery cycles.
7. Issue the DISPLAY UTILITY(*) command for a list of currently running utilities.
8. Run the DIAGNOSE utility with the DISPLAY SYSUTIL statement to
determine the names of the object on which the utilities are running.
Installation SYSOPR authority is required.
9. Perform the following actions for objects at the tracker site on which utilities
are pending. Restrictions apply to these objects because Db2 prevents you
from using the TERM UTILITY command to remove pending statuses at a
tracker site.
v If a LOAD, REORG, REPAIR, or COPY utility job is in progress on any
catalog or directory object at the primary site, shut down Db2 subsystem.
You cannot continue recovering by using the list of catalog and directory
objects. Therefore, you cannot recover any user data. At the next recovery
cycle, send a full image copy of the object from the primary site. At the
tracker site, use the RECOVER utility to restore the object.
v If a LOAD, REORG, REPAIR, or COPY utility job is in progress on any user
data, at the next recovery cycle, send a full image copy of the object from
the primary site. At the tracker site, use the RECOVER utility to restore the
object.
v If an object is in the restart-pending state, use LOGONLY recovery to
recover the object when that object is no longer in a restart-pending state.
Data sharing
If read/write shared data (GPB-dependent data) is in the advisory
recovery pending state, the tracker Db2 site performs recovery
processing. Because the tracker Db2 site always performs a
conditional restart, the postponed indoubt units of recovery are not
recognized after the tracker Db2 site restarts.
10. After all recovery has completed at the tracker site, shut down the tracker Db2
site. This is the end of the tracker site recovery cycle.
11. Optional: Stop and start the tracker Db2 site several times before completing a
recovery cycle.
Related concepts
Media failures during LOGONLY recovery
Related tasks
Establishing a recovery cycle by using RESTORE SYSTEM LOGONLY
Restoring data from image copies and archive logs

Media failures during LOGONLY recovery

If an I/O error occurs during a LOGONLY recovery, you can recover the object by
using the image copies and logs after you correct the media failure.

Chapter 13. Recovering from different Db2 for z/OS problems 615
 If an entire volume is corrupted and you are using Db2 storage groups, you cannot
use the ALTER STOGROUP statement to remove the corrupted volume and add
another. (This is possible, however, for a non-tracker system.) Instead, you must
remove the corrupted volume and re-initialize another volume with the same
volume serial number before you invoke the RECOVER utility for all table spaces
and indexes on that volume.

Maintaining a tracker site

If you want to have a tracker site for possible disaster recovery needs, you need to
maintain it so that it can operate as required.

Procedure

To maintain a tracker site:

1. Keep the tracker site and primary site be at the same maintenance level to
avoid unexpected problems.
2. Between recovery cycles, apply maintenance as you normally do, by stopping
and restarting the Db2 subsystem or a Db2 data sharing member.
3. If a tracker site fails, restart it as you normally do.
4. Save your complete tracker site prior to testing a takeover site. This step is
necessary because bringing up a tracker site as the takeover site destroys the
tracker site environment. After testing the takeover site, you can restore the
tracker site and resume the recovery cycles.

Results

When restarting a data sharing group, the first member that starts during a
recovery cycle puts the ENDLRSN value in the shared communications area (SCA)
of the coupling facility. If an SCA failure occurs during a recovery cycle, you must
go through the recovery cycle again, using the same ENDLRSN value for your
conditional restart.

Making the tracker site be the takeover site

If a disaster occurs at the primary site, the tracker site must become the takeover
site.

Before you begin

Save your complete tracker site prior to testing a takeover site.

Procedure

To make the tracker site be the takeover site:

1. Restart the takeover site.
2. Apply log data or image copies that were en route when the disaster occurred.
3. Follow the appropriate procedure for making the tracker site a takeover site,
depending on whether you use RESTORE SYSTEM LOGONLY or the
RECOVER utility in your tracker site recovery cycles.
Related tasks
Maintaining a tracker site

616 Administration Guide

Recovering at a tracker site that uses the RESTORE SYSTEM utility:

One way that you can make the tracker site be the takeover site is by using the
RESTORE SYSTEM utility with the LOGONLY option in the recovery cycles at the
tracker site.

Procedure

To make the tracker site be the takeover site by using the RESTORE SYSTEM
utility with the LOGONLY option:
1. If log data for a recovery cycle is en route or is available but has not yet been
used in a recovery cycle, perform the procedure in “Establishing a recovery
cycle by using RESTORE SYSTEM LOGONLY” on page 611.
2. Ensure that the TRKSITE NO subsystem parameter is specified.
3. For scenarios other than data sharing, continue with step 4.
Data sharing
If this is a data sharing system, delete the coupling facility structures.
4. Start Db2 at the same RBA or ENDLRSN that you used in the most recent
tracker site recovery cycle. Specify FORWARD=YES and BACKOUT=YES in the
CRESTART statement; this takes care of uncommitted work.
5. Restart the objects that are in GRECP or LPL status by issuing the START
DATABASE(*) SPACENAM(*) command.
6. If you used the DSN1COPY utility to create a copy of SYSUTILX in the last
recovery cycle, use DSN1COPY to restore that copy.
7. Terminate any in-progress utilities by using the following procedure:
a. Enter the DISPLAY UTILITY(*) command .
b. Run the DIAGNOSE utility with DISPLAY SYSUTIL to get the names of
objects on which utilities are being run.
c. Terminate in-progress utilities in the correct order by using the TERM
UTILITY(*) command.
8. Rebuild indexes, including IBM and user-defined indexes on the Db2 catalog
and user-defined indexes on table spaces.
Related tasks
Restoring data from image copies and archive logs
Recovering at a tracker site that uses the RECOVER utility

Recovering at a tracker site that uses the RECOVER utility:

One way that you can make the tracker site be the takeover site is by using the
RECOVER utility in the recovery cycles at your tracker site.

Procedure

To make the tracker site be the takeover site by using the RECOVER utility:
1. Restore the BSDS, and register the archive log from the last archive log that you
received from the primary site.
2. For environments that do not use data sharing, continue with step 3.
Data sharing
If this is a data sharing system, delete the coupling facility structures.
3. Ensure that the DEFER ALL and TRKSITE NO subsystem parameters are
specified.

Chapter 13. Recovering from different Db2 for z/OS problems 617
 4. Take the appropriate action, which depends on whether you received more logs
from the primary site. If this is a non-data-sharing Db2 subsystem, the log
truncation point varies depending on whether you have received more logs
from the primary site since the last recovery cycle:
v If you did not receive more logs from the primary site:
Start Db2 using the same ENDRBA that you used on the last tracker cycle.
Specify FORWARD=YES and BACKOUT=YES; this takes care of
uncommitted work. If you have fully recovered the objects during the
previous cycle, they are current except for any objects that had outstanding
units of recovery during restart. Because the previous cycle specified NO for
both FORWARD and BACKOUT and you have now specified YES, affected
data sets are placed in the LPL. Restart the objects that are in LPL status by
using the following command:
START DATABASE(*) SPACENAM(*)
After you issue the command, all table spaces and indexes that were
previously recovered are now current. Remember to rebuild any indexes that
were not recovered during the previous tracker cycle, including user-defined
indexes on the Db2 catalog.
v If you received more logs from the primary site:
Start Db2 using the truncated RBA nnnnnnnnn000, which equals the value of
the ENDRBA of the latest archive log plus 1. Specify FORWARD=YES and
BACKOUT=YES. Run your recoveries as you did during recovery cycles.
Data sharing
You must restart every member of the data sharing group; use the
following CRESTART statement:
CRESTART CREATE,ENDLRSN=nnnnnnnnnnnn,FORWARD=YES,BACKOUT=YES

In this statement, nnnnnnnnnnnn is the LRSN of the last log record that
is to be used during restart. Specify one of the following values for the
ENDLRSN:
v If you receive the ENDLRSN from the output of the print log map
utility (DSNJU004) or from message DSNJ003I at the console logs use
ENDLRSN -1 as the input to the conditional restart.
v If you receive the ENDLRSN from the output of the DSN1LOGP
utility (DSN1213I message), use the displayed value.
The ENDLRSN or ENDRBA value indicates the end log point for data
recovery and for truncating the archive log. With ENDLRSN, the
missing log records between the lowest and highest ENDLRSN values
for all the members are applied during the next recovery cycle.
The takeover Db2 sites must specify conditional restart with a common
ENDLRSN value to allow all remote members to logically truncate the
logs at a consistent point.
5. As described for a tracker recovery cycle, recover SYSUTILX from an image
copy from the primary site, or from a previous DSN1COPY copy that was
taken at the tracker site.
6. Terminate any in-progress utilities by using the following procedure:
a. Enter the command DISPLAY UTILITY(*).
b. Run the DIAGNOSE utility with DISPLAY SYSUTIL to get the names of
objects on which utilities are being run.
c. Terminate in-progress utilities by using the command TERM UTILITY(*).

618 Administration Guide

 7. Continue with your recoveries either with the LOGONLY option or with image
copies. Remember to rebuild indexes, including IBM and user-defined indexes
on the Db2 catalog and user-defined indexes on table spaces.
Related tasks
Restoring data from image copies and archive logs
Recovering at a tracker site that uses the RESTORE SYSTEM utility

Using data mirroring for disaster recovery

Data mirroring is the automatic replication of current data from your primary site
to a secondary site. To recover after a disaster, you can use this secondary site for
your recovery site without the need to restore Db2 image copies. You also do not
need to apply Db2 logs to bring Db2 data to the current point in time.

About this task

The procedures for data mirroring are intended for environments that mirror an
entire Db2 subsystem or data sharing group, which includes the catalog, directory,
user data, BSDS, and active logs. You must mirror all volumes in such a way that
they terminate at exactly the same point. You can achieve this final condition by
using consistency groups.

Follow the appropriate procedure for recovering from a disaster by using data
mirroring.

Role of data mirroring in recovery from a rolling disaster

In a real disaster, your local site gradually and intermittently fails for a duration of
several seconds. This kind of Db2 failure is known as a rolling disaster. You can
recover from a rolling disaster by using data mirroring.

To use data mirroring for disaster recovery, you must mirror data from your local
site with a method that does not reproduce a rolling disaster at your recovery site.
To recover a Db2 subsystem and data with data integrity, you must use volumes
that end at a consistent point in time for each Db2 subsystem or data sharing
group. Mirroring a rolling disaster causes volumes at your recovery site to end
over a span of time rather than at one single point.

The following figure shows how a rolling disaster can cause data to become
inconsistent between two subsystems.

Chapter 13. Recovering from different Db2 for z/OS problems 619
 Primary Secondary

1. 12:00 log update

Disk fails Log Log
at 12:03 Device 2. 12:01 update Device
database

3. 12:02 mark log

complete
connection
is severed

Database Database
Disk fails Device Device
at 12:00

Figure 55. Data inconsistency caused by a rolling disaster

Example: In a rolling disaster, the following events at the primary site cause data
inconsistency at your recovery site. This data inconsistency example follows the
same scenario that the preceding figure depicts.
1. Some time prior to 12:00: A table space is updated in the buffer pool.
2. 12:00 The log record is written to disk on logical storage subsystem 1.
3. 12:01: Logical storage subsystem 2 fails.
4. 12:02: The update to the table space is externalized to logical storage subsystem
2 but is not written because subsystem 2 failed.
5. 12:03: The log record that indicates that the table space update was made is
written to disk on logical storage subsystem 1.
6. 12:03: Logical storage subsystem 1 fails.

Because the logical storage subsystems do not fail at the same point in time, they
contain inconsistent data. In this scenario, the log indicates that the update is
applied to the table space, but the update is not applied to the data volume that
holds this table space.

Important: Any disaster recovery solution that uses data mirroring must guarantee
that all volumes at the recovery site contain data for the same point in time.

Role of consistency groups in recovery

Generally a consistency group is a collection of volumes that contain consistent,
related data. Consistency groups play an important role in Db2 recovery.

A consistency group, which is a collection of related data, can span logical storage
subsystems and disk subsystems. For Db2 specifically, a consistency group contains
an entire Db2 subsystem or an entire Db2 data sharing group.

The following Db2 elements comprise a consistency group:

v Catalog tables
v Directory tables

620 Administration Guide

v BSDS
v Logs
v All user data
v ICF catalogs

Additionally, all objects within a consistency group must represent the same point
in time in at least one of the following situations:
v At the time of a backup
v After a normal Db2 restart

You can use the following methods to create consistency groups:

v XRC I/O timestamping and system data mover
v FlashCopy consistency groups
v GDPSfreeze policies
v The Db2 SET LOG SUSPEND command

When a rolling disaster strikes your primary site, consistency groups guarantee
that all volumes at the recovery site contain data for the same point in time. In a
data mirroring environment, you must perform both of the following actions for
each consistency group that you maintain:
v Mirror data to the secondary volumes in the same sequence that Db2 writes data
to the primary volumes.
In many processing situations, Db2 must complete one write operation before it
begins another write operation on a different disk group or a different storage
server. A write operation that depends on a previous write operation is called a
dependent write. Do not mirror a dependent write if you have not mirrored the
write operation on which the dependent write depends. If you mirror data out
of sequence, your recovery site will contain inconsistent data that you cannot
use for disaster recovery.
v Temporarily suspend and queue write operations to create a group point of
consistency when an error occurs between any pair of primary and secondary
volumes.
When an error occurs that prevents the update of a secondary volume in a
single-volume pair, this error might mark the beginning of a rolling disaster. To
prevent your secondary site from mirroring a rolling disaster, you must suspend
and queue data mirroring by taking the following steps after a write error
between any pairs:
1. Suspend and queue all write operations in the volume pair that experiences
a write error.
2. Invoke automation that temporarily suspends and queues data mirroring to
all your secondary volumes.
3. Save data at the secondary site at a point of consistency.
4. If a rolling disaster does not strike your primary site, resume normal data
mirroring after some amount of time that you define. If a rolling disaster
does strike your primary site, follow the recovery procedure in Recovering in
a data mirroring environment.

Recovering in a data mirroring environment

In a data mirroring environment, you can recover data at your secondary site from
a disaster at your primary site.

Chapter 13. Recovering from different Db2 for z/OS problems 621
 About this task

This procedure applies to all Db2 data mirroring scenarios except those that use
Extended Remote Copy (XRC). This general procedure is valid only if you have
established and maintained consistency groups before the disaster struck the
primary site. If you use data mirroring to recover, you must recover your entire
Db2 subsystem or data sharing group with data mirroring.

You do not need to restore Db2 image copies or apply Db2 logs to bring Db2 data
to the current point in time when you use data mirroring. However, you might
need image copies at the recovery site if the LOAD, UNLOAD, or RECOVER
utility was active at the time of the disaster.

Procedure

To recover at the secondary site after a disaster:

1. At your recovery site, IPL all z/OS images that correspond to the z/OS
images that you lost at your primary site.
2. For environments that do not use data sharing, continue with step 3.
Data sharing
For data sharing groups, you must remove old information from the
coupling facility.
a. Enter the following z/OS command to display the structures for
this data sharing group:
D XCF,STRUCTURE,STRNAME=grpname*
b. For group buffer pools and the lock structure, enter the following
command to force off the connections in those structures:
SETXCF FORCE,CONNECTION,STRNAME=strname,CONNAME=ALL
c. Delete all the Db2 coupling facility structures by using the
following command for each structure:
SETXCF FORCE,STRUCTURE,STRNAME=strname
3. If you are using the distributed data facility, set LOCATION and LUNAME in
the BSDS to values that are specific to your new primary site. To set
LOCATION and LUNAME, run the stand-alone change log inventory utility
(DSNJU003) with the following control statement:
DDF LOCATION=locname, LUNAME=luname
4. Start all Db2 members by using local DSNZPARM data sets and perform a
normal restart.
Data sharing
For data sharing groups, Db2 performs group restart. Shared data sets
are set to GRECP (group buffer pool RECOVER-pending) status, and
pages are added to the LPL (logical page list).
5. For scenarios other than data sharing, continue to step 6 on page 623.
Data sharing
For objects that are in GRECP status, Db2 automatically recovers the
objects during restart. Message DSNI049I is issued when the recovery
for all objects that are in GRECP status is complete. A message is
issued for each member, even if the member did not perform GRECP
recovery.
After message DSNI049I is issued:

622 Administration Guide

 a. Display all data sets with GRECP or LPL status by issuing the
following Db2 command:
-DISPLAY DATABASE(*) SPACENAM(*) RESTRICT(GRECP, LPL) LIMIT(*)

Record the output that this command generates.

6. Use the following Db2 command to display all utilities that the failure
interrupted:
-DISPLAY UTILITY(*)

If utilities are pending, record the output from this command, and continue to
the next step. You cannot restart utilities at a recovery site. You will terminate
these utilities in step 8. If no utilities are pending, continue to step number 9.
7. Use the DIAGNOSE utility to access the SYSUTIL directory table. You cannot
access this directory table by using normal SQL statements (as you can with
most other directory tables). You can access SYSUTIL only by using the
DIAGNOSE utility, which is normally intended to be used under the direction
of IBM Software Support.
Use the following control statement to run the DIAGNOSE utility job:
DIAGNOSE DISPLAY SYSUTIL
To stop the utility, issue this control statement:
END DIAGNOSE
Examine the output. Record the phase in which each pending utility was
interrupted, and record the object on which each utility was operating.
8. Terminate all pending utilities with the following command:
-TERM UTILITY(*)
9. For environments that do not use data sharing, continue to step 10.
Data sharing
For data sharing groups, use the following START DATABASE command
on each database that contains objects that are in LPL status:
-START DATABASE(database) SPACENAM(*)

When you use the START DATABASE command to recover objects, you
do not need to provide Db2 with image copies.

Tip: Use up to 10 START DATABASE commands for each Db2 subsystem

to increase the speed at which Db2 completes this operation. Multiple
commands that run in parallel complete faster than a single command
that specifies the same databases.
10. Start all remaining database objects with the following START DATABASE
command:
START DATABASE(*) SPACENAM(*)
11. For each object that the LOAD utility places in a restrictive status, take one of
the following actions:
v If the object was a target of a LOAD utility control statement that specified
SHRLEVEL CHANGE, restart the LOAD utility on this object at your
convenience. This object contains valid data.
v If the object was a target of a LOAD utility control statement that specified
SHRLEVEL NONE and the LOAD job was interrupted before the RELOAD
phase, rebuild the indexes on this object.

Chapter 13. Recovering from different Db2 for z/OS problems 623
 v If the object was a target of a LOAD utility control statement that specified
SHRLEVEL NONE and the LOAD job was interrupted during or after the
RELOAD phase, recover this object to a point in time that is before this
utility ran.
v Otherwise, recover the object to a point in time that is before the LOAD job
ran.
12. For each object that the REORG utility places in a restrictive status, take one
of the following actions:
v When the object was a target of a REORG utility control statement that
specified SHERLEVEL NONE:
– If the REORG job was interrupted before the RELOAD phase, no further
action is required. This object contains valid data, and the indexes on this
object are valid.
– If the REORG job was interrupted during the RELOAD phase, recover
this object to a point in time that is before this utility ran.
– If the REORG job was interrupted after the RELOAD phase, rebuild the
indexes on the object.
v When the object was a target of a REORG utility control statement that does
not specify SHRLEVEL NONE:
– If the REORG job was interrupted before the SWITCH phase, no further
action is required. This object contains valid data, and the indexes on this
object are valid.
– If the REORG job was interrupted during the SWITCH phase, no further
action is required. This object contains valid data, and the indexes on this
object are valid.
– If the REORG job was interrupted after the SWITCH phase, you might
need to rebuild non-partitioned secondary indexes.

Managing DFSMShsm default settings when using the BACKUP

SYSTEM, RESTORE SYSTEM, and RECOVER utilities
In some data mirroring situations, you might need to set or override the
DFSMShsm default settings for the BACKUP SYSTEM, RESTORE SYSTEM, and
RECOVER utilities.

About this task

For example, consider that the source volumes in the SMS storage groups for your
database or log copy pools are mirrored, or that the target volumes in the SMS
backup storage groups for your copy pools are mirrored. You can use IBM Remote
Pair FlashCopy (Preserve Mirror) for Peer-to-Peer Remote Copy (PPRC). Also, you
can allow FlashCopy to PPRC primary volumes. However, you might need to set
or override the DFSMShsm default settings for the BACKUP SYSTEM, RESTORE
SYSTEM, and RECOVER utilities.

Procedure

To manage the DFSMShsm default settings for these utilities:

Issue the DFSMShsm FRBACKUP PREPARE command.

v To set the DFSMShsm defaults for the BACKUP SYSTEM utility, the RESTORE
SYSTEM utility, and the RECOVER utility, issue the following command:
FRBACKUP CP cp-name PREPARE ALLOWPPRCP (FRBACKUP (x) FRRECOV (x))

624 Administration Guide

 v To override the DFSMShsm defaults for the RESTORE SYSTEM utility or the
RECOVER utility, issue the following command:
FRBACKUP CP cp-name PREPARE ALLOWPPRCP (FRRECOV (x))
Related concepts
Considerations for using the BACKUP SYSTEM utility and DFSMShsm
Related reference
FRBACKUP command: Requesting a fast replication backup or dump
version DFSMShsm Storage Administration Reference
Syntax and options of the RECOVER control statement (Db2 Utilities)
Syntax and options of the RESTORE SYSTEM control statement (Db2
Utilities)

Recovering with Extended Remote Copy

One method that ensures that data volumes remain consistent at your recovery site
involves Extended Remote Copy (XRC). In XRC remote mirroring, the DFSMS
Advanced Copy services function automatically replicates current data from your
primary site to a secondary site and establishes consistency groups.

Before you begin

This procedure assumes that you are familiar with basic use of XRC.

Procedure

To recover at an XRC secondary site after a disaster:

1. Issue the TSO command XEND XRC to end the XRC session.
2. Issue the TSO command XRECOVER XRC. This command changes your secondary
site to your primary site and applies the XRC journals to recover data that was
in transit when your primary site failed.
3. Complete the procedure in Recovering in a data mirroring environment.
Related information
Extended Remote Copy (DFSMS Advanced Copy Services)

Scenarios for resolving problems with indoubt threads

Indoubt threads can cause a variety of problems, but you can recover from these
problems.

The recovery scenarios for indoubt threads are based on a sample environment,
which this topic describes. System programmer, operator, and database
administrator actions are indicated for the examples as appropriate. In these
descriptions, the term “administrator” refers to the database administrator (DBA) if
not otherwise specified.
Configuration
The configuration includes four systems at three geographic locations:
Seattle (SEA), San Jose (SJ) and Los Angeles (LA). The system descriptions
are as follows.
v Db2 subsystem at Seattle, Location name = IBMSEADB20001, Network
name = IBM.SEADB21
v Db2 subsystem at San Jose, Location name = IBMSJ0DB20001, Network
name = IBM.SJDB21

Chapter 13. Recovering from different Db2 for z/OS problems 625
 v Db2 subsystem at Los Angeles, Location name = IBMLA0DB20001,
Network name = IBM.LADB21
v IMS subsystem at Seattle, Connection name = SEAIMS01
Applications
The following IMS and TSO applications run at Seattle and access both
local and remote data.
v IMS application, IMSAPP01, at Seattle, accesses local data and remote
data by DRDA access at San Jose, which accesses remote data on behalf
of Seattle by Db2 private protocol access at Los Angeles.
v TSO application, TSOAPP01, at Seattle, accesses data by DRDA access at
San Jose and at Los Angeles.
Threads
The following threads are described and keyed to Figure 56 on page 627.
Database access threads (DBAT) access data on behalf of a thread (either
allied or DBAT) at a remote requester.
v Allied IMS thread A at Seattle accesses data at San Jose by DRDA access.
– DBAT at San Jose accesses data for Seattle by DRDA access 1 and
requests data at Los Angeles by Db2 private protocol access 2.
– DBAT at Los Angeles accesses data for San Jose by Db2 private
protocol access 2.
v Allied TSO thread B at Seattle accesses local data and remote data at San
Jose and Los Angeles, by DRDA access.
– DBAT at San Jose accesses data for Seattle by DRDA access 3.
– DBAT at Los Angeles accesses data for Seattle by DRDA access 4.

626 Administration Guide

 Db2 at SJ
IBMSJ0DB20001

DBAT 1
CONNID=SEAINS01
CORRID=xyz
PLAN=IMSAPP01
LUWID=15,TOKEN=8
Db2 at SEA
IBMSEADB20001 DBAT 3
CONNID=BATCH
Allied Thread A CORRID=abc
CONNID=SEAIMS01 PLAN=TSOAPP01
CORRID=xyz LUWID=16,TOKEN=6
IMS
PLAN=IMSAPP01
NID=A5
LUWID=15,TOKEN=1 Db2 at LA
IBMLA0DB20001
Allied Thread B
CONNID=BATCH DBAT 2
TSO CORRID=abc CONNID=SERVER
PLAN=TSOAPP01 CORRID=xyz
LUWID=16,TOKEN=2 PLAN=IMSAPP01
LUWID=15,TOKEN=4

DBAT 4
CONNID=BATCH
CORRID=abc
PLAN=TSOAPP01
LUWID=16,TOKEN=5

Figure 56. Resolution of indoubt threads. Results of issuing DISPLAY THREAD TYPE(ACTIVE) at
each Db2 subsystem.

The results of issuing the DISPLAY THREAD TYPE(ACTIVE) command to

display the status of threads at all Db2 locations are summarized in the
boxes of the preceding figure. The logical unit of work IDs (LUWIDs) have
been shortened for readability, as follows:
v LUWID=15 is IBM.SEADB21.15A86A876789.0010.
v LUWID=16 is IBM.SEADB21.16B57B954427.0003.
For the purposes of procedures that are based on this configuration,
assume that both applications have updated data at all Db2 locations. In
the following problem scenarios, the error occurs after the coordinator has
recorded the commit decision, but before the affected participants have
recorded the commit decision. These participants are therefore indoubt.

Read one or more of the scenarios to learn how best to handle problems with
indoubt threads in your own environment.

Scenario: Recovering from communication failure

A communication failure can cause an indoubt thread.

Symptoms
A communication failure occurred between Seattle (SEA) and Los Angeles (LA)
after the database access thread (DBAT) at LA completed phase 1 of commit
processing. At SEA, the TSO thread, LUWID=16 and TOKEN=2 B, cannot complete
the commit with the DBAT at LA4.

Chapter 13. Recovering from different Db2 for z/OS problems 627
 At SEA, NetView alert A006 is generated, and message DSNL406 is displayed,
indicating that an indoubt thread at LA because of a communication failure. At LA,
alert A006 is generated, and message DSNL405 is displayed, to indicate that a
thread is in an indoubt state because of a communication failure with SEA.

Causes
A communication failure caused the indoubt thread.

Environment
The following figure illustrates the environment for this scenario.

Db2 at SJ
IBMSJ0DB20001

DBAT 1
CONNID=SEAINS01
CORRID=xyz
PLAN=IMSAPP01
LUWID=15,TOKEN=8
Db2 at SEA
IBMSEADB20001 DBAT 3
CONNID=BATCH
Allied Thread A CORRID=abc
CONNID=SEAIMS01 PLAN=TSOAPP01
CORRID=xyz LUWID=16,TOKEN=6
IMS
PLAN=IMSAPP01
NID=A5
LUWID=15,TOKEN=1 Db2 at LA
IBMLA0DB20001
Allied Thread B
CONNID=BATCH DBAT 2
TSO CORRID=abc CONNID=SERVER
PLAN=TSOAPP01 CORRID=xyz
LUWID=16,TOKEN=2 PLAN=IMSAPP01
LUWID=15,TOKEN=4

DBAT 4
CONNID=BATCH
CORRID=abc
PLAN=TSOAPP01
LUWID=16,TOKEN=5

Figure 57. Resolution of indoubt threads. Scenarios for resolving problems with indoubt threads contains a detailed
description of the scenario depicted in this figure.

At SEA, an IFCID 209 trace record is written. After the alert is generated and the
message is displayed, the thread completes the commit, which includes the DBAT
at SJ 3. Concurrently, the thread is added to the list of threads for which the SEA
Db2 subsystem has an indoubt resolution responsibility. The thread shows up in a
DISPLAY THREAD report for indoubt threads. The thread also shows up in a DISPLAY
THREAD report for active threads until the application terminates.

The TSO application is informed that the commit succeeded. If the application
continues and processes another SQL request, it is rejected with an SQL code to
indicate that it must roll back before any more SQL requests can be processed. This
is to ensure that the application does not proceed with an assumption based on
data that is retrieved from LA, or with the expectation that cursor positioning at
LA is still intact.

628 Administration Guide

 At LA, an IFCID 209 trace record is written. After the alert is generated and the
message displayed, the DBAT 4 is placed in the indoubt state. All locks remain
held until resolution occurs. The thread shows up in a DISPLAY THREAD report for
indoubt threads.

The Db2 subsystems, at both SEA and LA, periodically attempt to reconnect and
automatically resolve the indoubt thread. If the communication failure affects only
the session that is being used by the TSO application, and other sessions are
available, automatic resolution occurs in a relatively short time. At this time,
message DSNL407 is displayed by both Db2 subsystems.

Resolving the problem

Operator response: If message DSNL407 or DSNL415 for the thread that is
identified in message DSNL405 is not issued in a reasonable period of time, contact
the system programmer. A communication failure is making database resources
unavailable.

System programmer response: Determine and correct the cause of the

communication failure. When the problem is corrected, automatic resolution of the
indoubt thread occurs within a short time. If the failure cannot be corrected for a
long time, call the database administrator. The database administrator might want
to make a heuristic decision to release the database resources that are held for the
indoubt thread.

Scenario: Making a heuristic decision about whether to

commit or abort an indoubt thread
An organization might need to make a heuristic decision about whether to commit
or abort an indoubt thread.

Symptoms
In this scenario, an indoubt thread at Los Angeles (LA) holds database resources
that are needed by other applications. The organization makes a heuristic decision
about whether to commit or abort an indoubt thread.

Many symptoms are possible, including:

v Message DSNL405 to indicate a thread in the indoubt state
v A DISPLAY THREAD report of active threads showing a larger-than-normal number
of threads
v A DISPLAY THREAD report of indoubt threads continuing to show the same thread
v A DISPLAY DATABASE LOCKS report that shows a large number of threads that are
waiting for the locks that are held by the indoubt thread
v Some threads terminating due to timeout
v IMS and CICS transactions not completing

Environment
The following figure illustrates the environment for this scenario.

Chapter 13. Recovering from different Db2 for z/OS problems 629
 Db2 at SJ
IBMSJ0DB20001

DBAT 1
CONNID=SEAINS01
CORRID=xyz
PLAN=IMSAPP01
LUWID=15,TOKEN=8
Db2 at SEA
IBMSEADB20001 DBAT 3
CONNID=BATCH
Allied Thread A CORRID=abc
CONNID=SEAIMS01 PLAN=TSOAPP01
CORRID=xyz LUWID=16,TOKEN=6
IMS
PLAN=IMSAPP01
NID=A5
LUWID=15,TOKEN=1 Db2 at LA
IBMLA0DB20001
Allied Thread B
CONNID=BATCH DBAT 2
TSO CORRID=abc CONNID=SERVER
PLAN=TSOAPP01 CORRID=xyz
LUWID=16,TOKEN=2 PLAN=IMSAPP01
LUWID=15,TOKEN=4

DBAT 4
CONNID=BATCH
CORRID=abc
PLAN=TSOAPP01
LUWID=16,TOKEN=5

Figure 58. Resolution of indoubt threads. Scenarios for resolving problems with indoubt threads contains a detailed
description of the scenario depicted in this figure.

Resolving the problem

Database administrator response: Determine whether to commit or abort the
indoubt thread. First, determine the name of the commit coordinator for the
indoubt thread. This name matches the location name of the Db2 subsystem at
SEA, and it is included in the Db2 indoubt thread DISPLAY THREAD report at LA.
Then, have an authorized person at SEA perform one of the following actions:
v If the coordinator Db2 subsystem is active, or if it can be started, request a
DISPLAY THREAD report for indoubt threads, specifying the LUWID of the thread.
(Remember that the token that is used at LA is different than the token that is
used at SEA). If no report entry exists for the LUWID, the proper action is to
abort. If a report entry for the LUWID exists, it shows the proper action to take.
v If the coordinator Db2 subsystem is not active and cannot be started, and if
statistics class 4 was active when Db2 was active, search the SEA SMF data for
an IFCID 209 event entry that contains the indoubt LUWID. This entry indicates
whether the commit decision was commit or abort.
v If statistics class 4 is not available, run the DSN1LOGP utility, and request a
summary report. The volume of log data that is to be searched can be restricted
if you can determine the approximate SEA log RBA value that was in effect at
the time of the communication failure. A DSN1LOGP entry in the summary
report for the indoubt LUWID indicates whether the decision was commit or
abort.
After determining the correct action to take, issue the RECOVER INDOUBT command
at the LA Db2 subsystem, specifying the LUWID and the correct action.

630 Administration Guide

 System action: Issuing the RECOVER INDOUBT command at LA results in committing
or aborting the indoubt thread. Locks are released. The thread does not disappear
from the indoubt thread display until resolution with SEA is completed. The
RECOVER INDOUBT report shows that the thread is either committed or aborted by
heuristic decision. An IFCID 203 trace record is written, recording the heuristic
action.

Scenario: Recovering from an IMS outage that results in an

IMS cold start
An IMS outage can result in an IMS cold start. An organization that experiences
this situation can recover.

Symptoms
When IMS is cold started and later reconnects with the SEA Db2 subsystem, IMS is
not able to resolve the indoubt thread with Db2. Message DSNM004I is displayed
at the IMS master terminal.

Environment
The following figure illustrates the environment for this scenario.

Db2 at SJ
IBMSJ0DB20001

DBAT 1
CONNID=SEAINS01
CORRID=xyz
PLAN=IMSAPP01
LUWID=15,TOKEN=8
Db2 at SEA
IBMSEADB20001 DBAT 3
CONNID=BATCH
Allied Thread A CORRID=abc
CONNID=SEAIMS01 PLAN=TSOAPP01
CORRID=xyz LUWID=16,TOKEN=6
IMS
PLAN=IMSAPP01
NID=A5
LUWID=15,TOKEN=1 Db2 at LA
IBMLA0DB20001
Allied Thread B
CONNID=BATCH DBAT 2
TSO CORRID=abc CONNID=SERVER
PLAN=TSOAPP01 CORRID=xyz
LUWID=16,TOKEN=2 PLAN=IMSAPP01
LUWID=15,TOKEN=4

DBAT 4
CONNID=BATCH
CORRID=abc
PLAN=TSOAPP01
LUWID=16,TOKEN=5

Figure 59. Resolution of indoubt threads. Scenarios for resolving problems with indoubt threads contains a detailed
description of the scenario depicted in this figure.

The abnormal termination of IMS has left one allied thread A at the SEA Db2
subsystem indoubt. This is the thread whose LUWID=15. Because the SEA Db2
subsystem still has effective communication with the Db2 subsystem at SJ, the
LUWID=15 DBAT 1 at this subsystem is waiting for the SEA Db2 to communicate
the final decision and is not aware that IMS has failed. Also, the LUWID=15 DBAT

Chapter 13. Recovering from different Db2 for z/OS problems 631
 at LA 2, which is connected to SJ, is also waiting for SJ to communicate the final
decision. This cannot be done until SEA communicates the decision to SJ.
v The connection remains active.
v IMS applications can still access Db2 databases.
v Some Db2 resources remain locked out.

If the indoubt thread is not resolved, the IMS message queues can start to back up.
If the IMS queues fill to capacity, IMS terminates. Therefore, users must be aware
of this potential difficulty and must monitor IMS until the indoubt units of work
are fully resolved.

Resolving the problem

System programmer response: Issue the RECOVER INDOUBT command to resolve the
indoubt thread at the SEA Db2 subsystem. This completes the two-phase commit
process with the Db2 subsystems at SJ and LA, and the unit of work either
commits or aborts.
1. Force the IMS log closed by using the /DBR FEOV command, and then archive
the IMS log. Use the command DFSERA10 to print the records from the previous
IMS log tape for the last transaction that was processed in each dependent
region. Record the PSB and the commit status from the X'37' log that contains
the recovery ID.
2. Run the DL/I batch job to back out each PSB that is involved and that has not
reached a commit point. The process might take some time because transactions
are still being processed. The process might also lock up a number of records,
which could affect the rest of the processing and the rest of the message
queues.
3. Enter the Db2 command DISPLAY THREAD (imsid) TYPE (INDOUBT).
4. Compare the NIDs (IMSID + OASN in hexadecimal) that is displayed in the
DISPLAY THREAD messages with the OASNs (4 bytes decimal) as shown in the
DFSERA10 output. Decide whether to commit or roll back.
5. Use DFSERA10 to print the X'5501FE' records from the current IMS log tape.
Every unit of recovery that undergoes indoubt resolution processing is
recorded; each record with an 'IDBT' code is still indoubt. Note the correlation
ID and the recovery ID, for use during the next step.
6. Enter the following Db2 command, choosing to commit or roll back, and
specify the correlation ID:
-RECOVER INDOUBT (imsid) ACTION(COMMIT|ABORT) NID (nid)
If the command is rejected because network IDs are associated, use the same
command again, substituting the recovery ID for the network ID.
Related concepts
Duplicate IMS correlation IDs

Scenario: Recovering from a Db2 outage at a requester that

results in a Db2 cold start
When an outage at a Db2 requester results in a cold start, the organization that has
this situation can recover.

Symptoms
The Db2 subsystem at SEA is started with a conditional restart record in the BSDS
to indicate a cold start:
v When the IMS subsystem reconnects, it attempts to resolve the indoubt thread
that is identified in IMS as NID=A5. IMS has a resource recovery element (RRE)

632 Administration Guide

 for this thread. The SEA Db2 subsystem informs IMS that it has no knowledge
of this thread. IMS does not delete the RRE, and the RRE can be displayed by
using the IMS DISPLAY OASN command. The SEA Db2 subsystem also:
– Generates message DSN3005 for each IMS RRE for which Db2 has no
knowledge
– Generates an IFCID 234 trace event
v When the Db2 subsystems at SJ and LA reconnect with SEA, each detects that
the SEA Db2 subsystem has cold started. Both the SJ Db2 and the LA Db2
subsystem:
– Display message DSNL411
– Generate alert A001
– Generate an IFCID 204 trace event
v A DISPLAY THREAD report of indoubt threads at both the SJ and LA Db2
subsystems shows the indoubt threads and indicates that the coordinator has
cold started.

Causes
An abnormal termination of the SEA Db2 subsystem caused the outage.

Environment
The following figure illustrates the environment for this scenario.

Db2 at SJ
IBMSJ0DB20001

DBAT 1
CONNID=SEAINS01
CORRID=xyz
PLAN=IMSAPP01
LUWID=15,TOKEN=8
Db2 at SEA
IBMSEADB20001 DBAT 3
CONNID=BATCH
Allied Thread A CORRID=abc
CONNID=SEAIMS01 PLAN=TSOAPP01
CORRID=xyz LUWID=16,TOKEN=6
IMS
PLAN=IMSAPP01
NID=A5
LUWID=15,TOKEN=1 Db2 at LA
IBMLA0DB20001
Allied Thread B
CONNID=BATCH DBAT 2
TSO CORRID=abc CONNID=SERVER
PLAN=TSOAPP01 CORRID=xyz
LUWID=16,TOKEN=2 PLAN=IMSAPP01
LUWID=15,TOKEN=4

DBAT 4
CONNID=BATCH
CORRID=abc
PLAN=TSOAPP01
LUWID=16,TOKEN=5

Figure 60. Resolution of indoubt threads. Scenarios for resolving problems with indoubt threads contains a detailed
description of the scenario depicted in this figure.

Chapter 13. Recovering from different Db2 for z/OS problems 633
 The abnormal termination of the SEA Db2 subsystem has left the two DBATs at SJ
1, 3, and the LUWID=16 DBAT at LA 4 indoubt. The LUWID=15 DBAT at LA 2,
connected to SJ, is waiting for the SJ Db2 subsystem to communicate the final
decision.

The IMS subsystem at SEA is operational and has the responsibility of resolving
indoubt units with the SEA Db2 subsystem.

The Db2 subsystems at both SJ and LA accept the cold start connection from SEA.
Processing continues, waiting for the heuristic decision to resolve the indoubt
threads.

Resolving the problem

Database administrator response: At this point:
v Neither the SJ nor the LA administrator know if the SEA coordinator was a
participant of another coordinator. In this scenario, the SEA Db2 subsystem
originated LUWID=16. However, the SEA Db2 subsystem was a participant for
LUWID=15, which was being coordinated by IMS.
v The administrator at LA also does not know is the fact that SEA distributed the
LUWID=16 thread to SJ, where it is also indoubt. Likewise, the administrator at
SJ does not know that LA has an indoubt thread for the LUWID=16 thread. Both
SJ and LA need to make the same heuristic decision. The administrators at SJ
and LA also need to determine the originator of the two-phase commit.
v The recovery log of the originator indicates whether the decision was commit or
abort. The originator might have more accessible functions to determine the
decision. Even though the SEA Db2 subsystem cold started, you might be able to
determine the decision from its recovery log. Alternatively, if the failure occurred
before the decision was recorded, you might be able to determine the name of
the coordinator, if the SEA Db2 subsystem was a participant. You can obtain a
summary report of the SEA Db2 recovery log by running the DSN1LOGP utility.
v The LUWID contains the name of the logical unit (LU) where the distributed
logical unit of work originated. This logical unit is most likely in the system that
originated the two-phase commit.
v If an application is distributed, any distributed piece of the application can
initiate the two-phase commit. In this type of application, the originator of
two-phase commit can be at a different system than the site that is identified by
the LUWID.
v The administrator must determine if the LU name that is contained in the
LUWID is the same as the LU name of the SEA Db2 subsystem. If this is not the
case (it is the case in this example), the SEA Db2 subsystem is a participant in
the logical unit of work, and it is being coordinated by a remote system. The
DBA must communicate with that system and request that facilities of that
system be used to determine if the logical unit of work is to be committed or
aborted.
v If the LUWID contains the LU name of the SEA Db2 subsystem, the logical unit
of work originated at SEA and can be an IMS, CICS, TSO, or batch allied thread
of the SEA Db2 subsystem. The DISPLAY THREAD report for indoubt threads at a
Db2 participant includes message DSNV458 if the coordinator is remote. This
line provides external information that is provided by the coordinator to assist in
identifying the thread. A Db2 coordinator provides the following identifier:
connection-name.correlation-id

where connection-name is:

634 Administration Guide

 – SERVER: the thread represents a remote application to the Db2 coordinator
and uses DRDA access.
– BATCH: the thread represents a local batch application to the Db2
coordinator.
v Anything else represents an IMS or CICS connection name. The thread
represents a local application, and the commit coordinator is the IMS or CICS
system by using this connection name.
v In this example, the administrator at SJ sees that both indoubt threads have an
LUWID with the LU name that match the SEA Db2 subsystem LU name, and
furthermore, that one thread (LUWID=15) is an IMS thread and the other thread
(LUWID=16) is a batch thread. The LA administrator sees that the LA indoubt
thread (LUWID=16) originates at the SEA Db2 subsystem and is a batch thread.
v The originator of a Db2 batch thread is Db2. To determine the commit or abort
decision for the LUWID=16 indoubt threads, the SEA Db2 recovery log must be
analyzed, if possible. Run the DSN1LOGP utility against the SEA Db2 recovery
log, and look for the LUWID=16 entry. Three possibilities exist:
1. No entry is found. That portion of the Db2 recovery log is not available.
2. An entry is found but incomplete.
3. An entry is found, and the status is committed or aborted.
v In the third case, the heuristic decision at SJ and LA for indoubt thread
LUWID=16 is indicated by the status that is indicated in the SEA Db2 recovery
log. In the other two cases, the recovery procedure that is used when cold
starting Db2 is important. If recovery was to a previous point in time, the correct
action is to abort. If recovery included repairing the SEA Db2 database, the SEA
administrator might know what decision to make.
v The recovery logs at SJ and LA can help determine what activity took place. If
the administrator determines that updates were performed at SJ, LA, or both
(but not SEA), and if both SJ and LA make the same heuristic action, data
inconsistency probably exists. If updates were also performed at SEA, the
administrator can look at the SEA data to determine what action to take. In any
case, both SJ and LA should make the same decision.
v For the indoubt thread with LUWID=15 (the IMS coordinator), several
alternative paths to recovery are available. The SEA Db2 subsystem has been
restarted. When it reconnects with IMS, message DSN3005 is issued for each
thread that IMS is trying to resolve with Db2. The message indicates that Db2
has no knowledge of the thread that is identified by the IMS-assigned NID. The
outcome for the thread, either commit or abort, is included in the message. Trace
event IFCID=234 is also written to statistics class 4, which contains the same
information.
v If only one such message exists, or if one such entry is in statistics class 4, the
decision for indoubt thread LUWID=15 is known and can be communicated to
the administrator at SJ. If multiple such messages exist, or if multiple such trace
events exist, the administrator must match the IMS NID with the network
LUWID. Again, the administrator should use DSN1LOGP to analyze the SEA Db2
recovery log if possible. Now four possibilities exist:
1. No entry is found. That portion of the Db2 recovery log was not available.
2. An entry is found but is incomplete because of lost recovery log data.
3. An entry is found, and the status is indoubt.
4. An entry is found, and the status is committed or aborted.
v In the fourth case, the heuristic decision at SJ for the indoubt thread LUWID=15
is determined by the status that is indicated in the SEA Db2 recovery log. If an
entry is found and its status is indoubt, DSN1LOGP also reports the IMS NID
value. The NID is the unique identifier for the logical unit of work in IMS and

Chapter 13. Recovering from different Db2 for z/OS problems 635
 CICS. Knowing the NID enables correlation to the DSN3005 message, or to the
234 trace event, either of which provides the correct decision.
v If an incomplete entry is found, the NID might have been reported by
DSN1LOGP. If it was reported, use it as previously discussed.
v Determine if any of the following conditions exists:
– No NID is found.
– The SEA Db2 subsystem has not been started.
– Reconnecting to IMS has not occurred.
If any of these conditions exists, the administrator must use the correlation-id that
is used by IMS to correlate the IMS logical unit of work to the Db2 thread in a
search of the IMS recovery log. The SEA Db2 site provided this value to the SJ
Db2 subsystem when distributing the thread to SJ. The SJ Db2 site displays this
value in the report that is generated by the DISPLAY THREAD TYPE(INDOUBT)
command.
v For IMS, the correlation-id is:
pst#.psbname
v In CICS, the correlation-id consists of four parts:
Byte 1 - Connection type - G=Group, P=Pool
Byte 2 - Thread type - T=transaction, G=Group, C=Command
Bytes 3-4 - Thread number
Bytes 5—8 - Transaction-id
Related concepts
Scenario: What happens when the wrong Db2 subsystem is cold started

Scenario: What happens when the wrong Db2 subsystem is

cold started
When one Db2 subsystem, instead of another Db2 subsystem, is cold started,
threads are left indoubt. An organization that faces this situation can recover.

The following figure illustrates the environment for this scenario.

636 Administration Guide

 Db2 at SJ
IBMSJ0DB20001

DBAT 1
CONNID=SEAINS01
CORRID=xyz
PLAN=IMSAPP01
LUWID=15,TOKEN=8
Db2 at SEA
IBMSEADB20001 DBAT 3
CONNID=BATCH
Allied Thread A CORRID=abc
CONNID=SEAIMS01 PLAN=TSOAPP01
CORRID=xyz LUWID=16,TOKEN=6
IMS
PLAN=IMSAPP01
NID=A5
LUWID=15,TOKEN=1 Db2 at LA
IBMLA0DB20001
Allied Thread B
CONNID=BATCH DBAT 2
TSO CORRID=abc CONNID=SERVER
PLAN=TSOAPP01 CORRID=xyz
LUWID=16,TOKEN=2 PLAN=IMSAPP01
LUWID=15,TOKEN=4

DBAT 4
CONNID=BATCH
CORRID=abc
PLAN=TSOAPP01
LUWID=16,TOKEN=5

Figure 61. Resolution of indoubt threads. Scenarios for resolving problems with indoubt threads contains a detailed
description of the scenario depicted in this figure.

If the Db2 subsystem at SJ is cold started instead of the Db2 at SEA, the LA Db2
subsystem has the LUWID=15 2 thread indoubt. The administrator can see that
this thread did not originate at SJ, but that it did originate at SEA. To determine
the commit or abort action, the LA administrator requests that DISPLAY THREAD
TYPE(INDOUBT) be issued at the SEA Db2 subsystem, specifying LUWID=15. IMS
does not have any indoubt status for this thread because it completes the
two-phase commit process with the SEA Db2 subsystem.

The Db2 subsystem at SEA tells the application that the commit succeeded.

When a participant cold starts, a Db2 coordinator continues to include in the

display of information about indoubt threads all committed threads where the cold
starting participant was believed to be indoubt. These entries must be explicitly
purged by issuing the RESET INDOUBT command. If a participant has an indoubt
thread that cannot be resolved because of coordinator cold start, the administrator
can request a display of indoubt threads at the Db2 coordinator to determine the
correct action.
Related information:
Scenario: Recovering from communication failure
Scenario: Recovering from a Db2 outage at a requester that results in a Db2 cold
start

Chapter 13. Recovering from different Db2 for z/OS problems 637
 Scenario: Correcting damage from an incorrect heuristic
decision about an indoubt thread
If an incorrect heuristic decision is made regarding an indoubt thread, an
organization can recover from this incorrect decision.

Symptoms
When the Db2 subsystem at SEA reconnects with the Db2 at LA, indoubt
resolution occurs for LUWID=16. Both systems detect heuristic damage, and both
generate alert A004; each writes an IFCID 207 trace record. Message DSNL400 is
displayed at LA, and message DSNL403 is displayed at SEA.

Causes
This scenario is based on the conditions described in “Scenario: Recovering from
communication failure” on page 627.

The LA administrator is called to make an heuristic decision and decides to abort

the indoubt thread with LUWID=16. The decision is made without communicating
with SEA to determine the proper action. The thread at LA is aborted, whereas the
threads at SEA and SJ are committed. Processing continues at all systems. The Db2
subsystem at SEA has indoubt resolution responsibility with LA for LUWID=16.

Environment
The following figure illustrates the environment for this scenario.

Db2 at SJ
IBMSJ0DB20001

DBAT 1
CONNID=SEAINS01
CORRID=xyz
PLAN=IMSAPP01
LUWID=15,TOKEN=8
Db2 at SEA
IBMSEADB20001 DBAT 3
CONNID=BATCH
Allied Thread A CORRID=abc
CONNID=SEAIMS01 PLAN=TSOAPP01
CORRID=xyz LUWID=16,TOKEN=6
IMS
PLAN=IMSAPP01
NID=A5
LUWID=15,TOKEN=1 Db2 at LA
IBMLA0DB20001
Allied Thread B
CONNID=BATCH DBAT 2
TSO CORRID=abc CONNID=SERVER
PLAN=TSOAPP01 CORRID=xyz
LUWID=16,TOKEN=2 PLAN=IMSAPP01
LUWID=15,TOKEN=4

DBAT 4
CONNID=BATCH
CORRID=abc
PLAN=TSOAPP01
LUWID=16,TOKEN=5

Figure 62. Resolution of indoubt threads. Scenarios for resolving problems with indoubt threads contains a detailed
description of the scenario depicted in this figure.

In this scenario, processing continues. Indoubt thread resolution responsibilities

have been fulfilled, and the thread completes at both SJ and LA.
638 Administration Guide
Resolving the problem
Database administrator response: Correct the damage. This is not an easy task.
Since the time of the heuristic action, the data at LA might have been read or
written by many applications. Correcting the damage can involve reversing the
effects of these applications, also. The available tools are:
v DSN1LOGP utility, which generates a summary report that identifies the table
spaces that were modified by the LUWID=16 thread.
v The statistics trace class 4, which contains an IFCID 207 entry. This entry
identifies the recovery log RBA for the LUWID=16 thread.
Notify IBM Support about the problem.

Chapter 13. Recovering from different Db2 for z/OS problems 639
640 Administration Guide
 Chapter 14. Reading log records
Reading Db2 log records is useful for diagnostic and recovery purposes.

This information discusses three approaches to writing programs that read log
records.

Contents of the log

The log contains the information that is needed to recover the results of program
execution, the contents of the database, and the Db2 subsystem. The log does not
contain information for accounting, statistics, traces, or performance evaluation.

PSPI

The three main types of log records are unit of recovery, checkpoint, and database
page set control records.

Each log record has a header that indicates its type, the Db2 subcomponent that
made the record, and, for unit-of-recovery records, the unit-of-recovery identifier.
The log records can be extracted and printed by the DSN1LOGP utility.

The log relative byte address and log record sequence number

| For basic 6-byte RBA format, the Db2 log can contain up to 248 bytes, where 248 is 2
| to the 48th power. For extended 10-byte RBA format, the Db2 log can contain up to
| 280 bytes, where 280 is 2 to the 80th power. Each byte is addressable by its offset
| from the beginning of the log. That offset is known as its relative byte address (RBA).

A log record is identifiable by the RBA of the first byte of its header; that RBA is
called the relative byte address of the record. The record RBA is like a timestamp
because it uniquely identifies a record that starts at a particular point in the
continuing log.

In the data sharing environment, each member has its own log. The log record
sequence number (LRSN) identifies the log records of a data sharing member. The
LRSN might not be unique on a data sharing member. The LRSN is a hexadecimal
value derived from a store clock timestamp. Db2 uses the LRSN for recovery in the
data sharing environment.

| Effects of Db2 data compression

Log records can contain compressed data if a table contains compressed data. For
example, if the data in a Db2 row is compressed, all data logged because of
changes to that row is compressed. If logged, the record prefix is not compressed,
but all of the data in the record is in compressed format. Reading compressed data
requires access to the dictionary that was in use when the data was compressed.
| Log records can also contain previously existing dictionaries if DATA CAPTURE
| CHANGES is active for the table. Log records are written when the dictionary is
| rebuilt or no longer required.

PSPI

© Copyright IBM Corp. 1982, 2017 641

 Data Replication's Q Capture program requires access to the dictionary for a source
compressed table space when it processes an IFI 306 READS request. In this case, if
the compressed table space is in a data sharing environment, a lock on the table
space may cause a Group Buffer Pool dependency (GBPDEP).
Related reference:
DSN1LOGP (Db2 Utilities)

Unit of recovery log records

Most of the log records describe changes to the Db2 database. All such changes are
made within units of recovery.

This section describes changes to the Db2 database, the effects of these changes,
and the log records that correspond to the changes.

Undo and redo records

When a change is made to the database, Db2 logs an undo/redo record that
describes the change.

PSPI

The redo information is required if the work is committed and later must be
recovered. The undo information is used to back out work that is not committed.

If the work is rolled back, the undo/redo record is used to remove the change. At
the same time that the change is removed, a new redo/undo record is created that
contains information, called compensation information, that is used if necessary to
reverse the change. For example, if a value of 3 is changed to 5, redo compensation
information changes it back to 3.

If the work must be recovered, Db2 scans the log forward and applies the redo
portions of log records and the redo portions of compensation records, without
keeping track of whether the unit of recovery was committed or rolled back. If the
unit of recovery had been rolled back, Db2 would have written compensation redo
log records to record the original undo action as a redo action. Using this
technique, the data can be completely restored by applying only redo log records
on a single forward pass of the log.

Db2 also logs the creation and deletion of data sets. If the work is rolled back, the
operations are reversed. For example, if a table space is created using
Db2-managed data sets, Db2 creates a data set; if rollback is necessary, the data set
is deleted. If a table space using Db2-managed data sets is dropped, Db2 deletes
the data set when the work is committed, not immediately. If the work is rolled
back, Db2 does nothing.

PSPI

Database exception table records

Database exception table (DBET) log records register different types of information:
exception states and image copies of special table spaces.

PSPI

DBET log records also register exception information that is not related to units of
recovery.

642 Administration Guide

 Exception states

DBET log records register whether any database, table space, index space, or
partition is in an exception state. To list all objects in a database that are in an
exception state, use the command DISPLAY DATABASE (database name) RESTRICT.

Image copies of special table spaces

| Image copies of DSNDB01.SYSUTILX, DSNDB01.DBD01, DSNDB06.SYSTSCPY, and

| DSNDB01.SYSDBDXA are registered in the DBET log record rather than in
| SYSCOPY. During recovery, they are recovered from the log, and then image copies
| of other table spaces are located from the recovered SYSCOPY.
|
PSPI
|
| Related reference:
Other exception information
Related information:
DSNT361I (Db2 Messages)

Typical unit of recovery log records

A typical sequence of log records is written for an insert of one row through TSO.

PSPI

The following record types are included:

Begin_UR
The first request to change a database begins a unit of recovery. The log
record of that event is identified by its log RBA. That same RBA serves as
an ID for the entire unit of recovery (the URID). All records related to that
unit have that RBA in their log record headers (LRH). For rapid backout,
the records are also linked by a backward chain in the LRH.
Undo/Redo
Log records are written for each insertion, deletion, or update of a row.
They register the changes to the stored data, but not the SQL statement
that caused the change. Each record identifies one data or index page and
its changes.
End Phase 2 records
The end of a UR is marked by log records that tell whether the UR was
committed or rolled back, and whether Db2 has completed the work
associated with it. If Db2 terminates before a UR has completed, it
completes the work at the next restart.
Table 52. Example of a log record sequence for an INSERT of one row using TSO
Type of record Information recorded
1. Begin_UR Beginning of the unit of recovery. Includes the connection
name, correlation name, authorization ID, plan name, and
LUWID.
2. Undo/Redo for data Insertion of data. Includes the database ID (DBID), page set
ID, page number, internal record identifier (RID), and the
data inserted.
3. Undo/Redo for Index Insertion of index entry. Includes the DBID, index space
object ID, page number, and index entry to be added.

Chapter 14. Reading log records 643

 Table 52. Example of a log record sequence for an INSERT of one row using
TSO (continued)
Type of record Information recorded
4. Begin Commit 1 The beginning of the commit process. The application has
requested a commit either explicitly (EXEC SQL COMMIT)
or implicitly (for example, by ending the program).
5. Phase 1-2 Transition The agreement to commit in TSO. In CICS and IMS, an End
Phase 1 record notes that Db2 agrees to commit. If both
parties agree, a Begin Phase 2 record is written; otherwise, a
Begin Abort record is written, noting that the unit of
recovery is to be rolled back.
6. End Phase 2 Completion of all work required for commit.

Table 53 shows the log records for processing and rolling back an insertion.
Table 53. Log records written for rolling back an insertion
Type of record Information recorded
1. Begin_UR Beginning of the unit of recovery.
2. Undo/Redo for data Insertion of data. Includes the database ID (DBID), page set
ID, page number, internal record identifier, and the data
inserted.
3. Begin_Abort Beginning of the rollback process.
4. Compensation Redo/Undo Backing-out of data. Includes the database ID (DBID), page
set ID, page number, internal record ID (RID), and data to
undo the previous change.
5. End_Abort End of the unit of recovery, with rollback complete.

PSPI

Types of changes to data

The three basic types of changes to a data page are changes to control information,
changes to database pointers, and changes to the data.

PSPI

Changes to control information

Those changes include pages that map available space and indicators that
show that a page has been modified. The COPY utility uses that
information when making incremental image copies.
Changes to database pointers
Pointers are used in two situations:
v The Db2 catalog and directory, but not user databases, contain pointers
that connect related rows. Insertion or deletion of a row changes
pointers in related data rows.
v When a row in a user database becomes too long to fit in the available
space, it is moved to a new page. An address, called an overflow pointer,
that points to the new location is left in the original page. With this

644 Administration Guide

 technique, index entries and other pointers do not have to be changed.
Accessing the row in its original position gives a pointer to the new
location.
Changes to data
In Db2, a row is confined to a single page. Each row is uniquely identified
by a RID containing:
v The number of the page.
v A 1-byte ID that identifies the row within the page. A single page can
contain up to 255 rows. (A page in a catalog table space that has links
can contain up to 127 rows.) IDs are reused when rows are deleted.

The log record identifies the RID, the operation (insert, delete, or update), and the
data. Depending on the data size and other variables, Db2 can write a single log
record with both undo and redo information, or it can write separate log records
for undo and redo.

The following table summarizes the information logged for data and index
changes.
Table 54. Information logged for database changes
Operation Information logged
Insert data The new row.
v On redo, the row is inserted with its original RID.
v On undo, the row is deleted and the RID is made available for
another row.
Delete data The deleted row.
v On redo, the RID is made available for another row.
v On undo, the row is inserted again with its former RID.
Update data1 The old and new values of the changed data.
v On redo, the new data is replaced.
v On undo, the old data is replaced.
Insert index entry The new key value and the data RID.
Delete index entry The deleted key value and the data RID.
Add column The information about the column being added, if the table was
defined with DATA CAPTURE(CHANGES).
Alter column The information about the column being altered, if the table was
defined with DATA CAPTURE(CHANGES).
Roll back to a savepoint Information about the savepoint.
Modify table space Information about the table space version.
LOAD SHRLEVEL The database ID (DBID) and the page set ID (PSID) of the table
NONE RESUME YES space on which the operation was run.
LOAD SHRLEVEL The database ID (DBID) and the page set ID (PSID) of the table
NONE RESUME NO space on which the operation was run.
REPLACE
REORG TABLESPACE The database ID (DBID) and the page set ID (PSID) of the table
DISCARD space on which the operation was run.
CHECK DATA DELETE The database ID (DBID) and the page set ID (PSID) of the table
YES space on which the operation was run.

Chapter 14. Reading log records 645

 Table 54. Information logged for database changes (continued)
Operation Information logged
Point-in-time recovery The database ID (DBID) and the page set ID (PSID) of the table
by using the RECOVER space on which the operation was run.
utility with the
following options:
v TOCOPY
v TOLASTCOPY
v TOLASTFULLCOPY
v TORBA
v TOLOGPOINT
EXCHANGE DATA on The database ID (DBID) and the page set ID (PSID) of the table
a clone table space space on which the operation was run.
REPAIR SET DELETE The database ID (DBID) and the page set ID (PSID) of the table
space on which the operation was run.

Note:
1. If an update occurs to a table defined with DATA CAPTURE(CHANGES), the
entire before-image of the data row is logged.

PSPI

Checkpoint log records

Db2 takes periodic checkpoints during normal operation in order to reduce restart
time.

PSPI

Db2 takes checkpoints in the following circumstances:

v When a predefined number of log records have been written or a predetermined
amount of time in minutes has elapsed.
This number is defined by field CHECKPOINT FREQ on installation panel
DSNTIPL.
v When switching from one active log data set to another
v At the end of a successful restart
v At normal termination

At a checkpoint, Db2 logs its current status and registers the log RBA of the
checkpoint in the bootstrap data set (BSDS). At restart, Db2 uses the information in
the checkpoint records to reconstruct its state when it terminated.

Many log records can be written for a single checkpoint. Db2 can write one to
begin the checkpoint; others can then be written, followed by a record to end the
checkpoint. The following table summarizes the information logged.
Table 55. Contents of checkpoint log records
Type of log record Information logged
Begin_Checkpoint Marks the start of the summary information. All later records in
the checkpoint have type X'0100' (in the LRH).

646 Administration Guide

 Table 55. Contents of checkpoint log records (continued)
Type of log record Information logged
Unit of Recovery Identifies an incomplete unit of recovery (by the log RBA of the
Summary Begin_UR log record). Includes the date and time of its creation,
its connection ID, correlation ID, authorization ID, the plan
name it used, and its current state (inflight, indoubt, in-commit,
or in-abort).
Page Set Summary Contains information for allocating and opening objects at
restart, and identifies (by the log RBA) the earliest checkpoint
interval containing log records about data changes that have not
been applied to the DASD version of the data or index. There is
one record for each open page set (table space or index space).
Page Set Exception Identifies the type of exception state. There is one record for
Summary each database and page set with an exception state.
Page Set UR Summary Identifies page sets modified by any active UR (inflight,
Record in-abort, or in-commit) at the time of the checkpoint.
End_Checkpoint Marks the end of the summary information about a checkpoint.

PSPI

Related reference:
DSNTIPL: Active log data set parameters (Db2 Installation and Migration)
Database page set control records

Database page set control records

Page set control records primarily register the allocation, opening, and closing of
every page set (table space or index space).

PSPI

The same information is in the Db2 directory (SYSIBM.SYSLGRNX). It is also

registered in the log so that it is available at restart.

PSPI

Other exception information

Entries for data pages that are logically in error (logical page list, or LPL entries) or
physically in error (write error page range, or WEPR entries) are registered in the
database exception table (DBET) log record.

The physical structure of the log

The active log consists of VSAM data sets with certain required characteristics.

PSPI

The physical output unit written to the active log data set is a control interval (CI)
of 4096 bytes (4 KB). Each CI contains one VSAM record.

PSPI

Chapter 14. Reading log records 647

 Physical and logical log records
| The VSAM control interval (CI) provides 4096 bytes to hold Db2 information. That
| space is called a physical record. The information that is to be logged at a particular
| time forms a logical record, whose length varies independently of the space that is
| available in the CI.

|
PSPI
|
| One physical record can contain several logical records, one or more logical records
| and part of another logical record, or only part of one logical record. The physical
| record must also contain 37 bytes of Db2 control information if the log record is in
| 10-byte format, or 21 bytes of Db2 control information if the log record is in
| six-byte format. The control information is called the log control interval definition
| (LCID).

Figure 63 shows a VSAM CI containing four log records or segments, namely:

v The last segment of a log record of 768 bytes (X'0300'). The length of the
segment is 100 bytes (X'0064').
v A complete log record of 40 bytes (X'0028').
v A complete log record of 1024 bytes (X'0400').
v The first segment of a log record of 4108 bytes (X'100C'). The length of the
segment is 2911 bytes (X'0B5F').

0064 8000 Data from last segment of log record 1

0028 0064 Data from log record 2

0400 0028 Data from log record 3

0B5F 4400 Data from first segment of log

Record 4

FF 100C 0300 048C Log RBA 00 Timestamp

Log control interval definition (LCID)

VSAM record
ends here
For data sharing, the LRSN of
the last log record in this CI
Offset of last segment in this CI
(beginning of log record 4)
Total length of spanned record that
ends in this CI (log record 1)
Total length of spanned record that
begins in this CI (log record 4)

Figure 63. A VSAM CI and its contents

The term log record refers to a logical record, unless the term physical log record is
used. A part of a logical record that falls within one physical record is called a
segment.

648 Administration Guide

 PSPI

Related reference:
The log control interval definition (LCID)

The log record header

Each logical record includes a prefix, called a log record header (LRH), which
contains control information.

PSPI

The first segment of a log record must contain the header and some bytes of data.
If the current physical record has too little room for the minimum segment of a
new record, the remainder of the physical record is unused, and a new log record
is written in a new physical record.

The log record can span many VSAM CIs. For example, a minimum of nine CIs are
required to hold the maximum size log record of 32815 bytes. Only the first
segment of the record contains the entire LRH; later segments include only the first
two fields. When a specific log record is needed for recovery, all segments are
retrieved and presented together as if the record were stored continuously.
| Table 56. Contents of the log record header for 10-byte format
| Hex offset Length Information
| 00 4 Length of this record or segment
| 04 2 Length of any previous record or segment in this CI; 0 if
| this is the first entry in the CI.
| 06 1 Flags
| 07 1 Release identifier
| 08 1 Resource manager ID (RMID) of the Db2 component that
| created the log record
| 09 1 Flags
| 0A 16 Unit of recovery ID, if this record relates to a unit of
| recovery; otherwise, 0
| 1A 16 Log RBA of the previous log record, if this record relates to
| a unit of recovery; otherwise, 0
| 2A 1 Length of header
| 2B 1 Available
| 2C 2 Type of log record
| 2E 2 Subtype of the log record
| 30 12 Undo next LSN
| 3C 14 LRHTIME
| 4A 6 Available
|
| Table 57. Contents of the log record header for 6-byte format
Hex offset Length Information
00 2 Length of this record or segment

Chapter 14. Reading log records 649

| Table 57. Contents of the log record header for 6-byte format (continued)
Hex offset Length Information
02 2 Length of any previous record or segment in this CI; 0 if
this is the first entry in the CI. The two high-order bits tell
the segment type:
B'00' A complete log record
B'01' The first segment
B'11' A middle segment
B'10' The last segment
04 2 Type of log record
06 2 Subtype of the log record
08 1 Resource manager ID (RMID) of the Db2 component that
created the log record
09 1 Flags
0A 6 Unit of recovery ID, if this record relates to a unit of
recovery; otherwise, 0
10 6 Log RBA of the previous log record, if this record relates to
a unit of recovery; otherwise, 0
16 1 Release identifier
17 1 Length of header
18 6 Undo next LSN
1E 8 LRHTIME

PSPI

Related concepts:
Unit of recovery log records
Related reference:
Log record type codes
Log record subtype codes

The log control interval definition (LCID)

Each physical log block, also referred to as a control interval, includes a suffix
called the log control interval definition (LCID), which tells how record segments are
placed in the physical control interval.

|
PSPI
|
| The following tables describe the contents of the LCID. You can determine the
| LCID format by testing the first bit of the next to last byte. If the bit is 1, then the
| LCID is in the 10-byte format. If the bit is 0, the LCID is in the 6-byte format.
| Table 58. Contents of the log control interval definition for 10 byte RBA and LRSN
| Hex offset Length Information
| 00 1 An indication of whether the CI contains free space: X'00' =
| Yes, X'FF' = No
| 01 2 Reserved
| 03 4 Total length of a spanned record that begins in this CI

650 Administration Guide

| Table 58. Contents of the log control interval definition for 10 byte RBA and
| LRSN (continued)
| Hex offset Length Information
| 07 4 Total length of a spanned record that ends in this CI
| 0B 10 Log RBA of the start of the CI
| 15 10 LRSN (data sharing) or timestamp of the last log record in
| this CI (non-data sharing)
| 1F 2 Offset to last segment in the CI
| 21 2 Reserved
| 23 1 Format - the first bit is 1 if 10 byte format, all other bits
| reserved
| 24 1 Member ID (data sharing) or 0 (non-data sharing)
|
Table 59. Contents of the log control interval definition for 6 byte RBA and LRSN
Hex offset Length Information
00 1 An indication of whether the CI contains free space: X'00' =
Yes, X'FF' = No
01 2 Total length of a segmented record that begins in this CI; 0
if no segmented record begins in this CI
03 2 Total length of a segmented record that ends in this CI; 0 if
no segmented record ends in this CI
05 2 Offset of the last record or segment in the CI
07 6 Log RBA of the start of the CI
| 0D 6 LRSN (data sharing) or timestamp of the last log record in
| this CI (non-data sharing)
| 13 2 Member ID (data sharing) or 0 (non-data sharing)

Each recovery log record consists of two parts: a header, which describes the record,
and data. The following illustration shows the format schematically; the following
list describes each field.

Chapter 14. Reading log records 651

 Data (maximum 35920)
Reserved (6)
Member ID (2)
Area with 10-byte STCK or LRSN (12)
Area with 10-byte undo next LSN (right justified) (12)
Record subtype (2)
Record type (2)
Reserved (1)
Length of header (1)

Area with 10-byte link (right justified) (16)

Area with 10-byte unit of recovery ID (right justified) (16)

Flags (1)
Resource manager ID (1)

Release identifier (1)

Flags (1)
Length of previous record or segment (2)
Length of this record or segment (4)

Figure 64. 10-byte format of a Db2 recovery log record

The fields are:

| Length of this record
| The total length of the record in bytes.
| Length of previous record
| The total length of the previous record in bytes.
| Release identifier
| Identifies in which release the log was written.
| Resource manager ID
| Identifier of the resource manager that wrote the record into the log. When
| the log is read, the record can be given for processing to the resource
| manager that created it.
| Unit of recovery ID
| A unit of recovery to which the record is related. Other log records can be
| related to the same unit of recovery; all of them must be examined to
| recover the data. The URID is the RBA (relative byte address) of the
| Begin-UR log record, and indicates the start of that unit of recovery in the
| log.
| LINK Chains all records written using their RBAs. For example, the link in an
| end checkpoint record links the chains back to the begin checkpoint record.
| Log record header length
| The total length of the header of the log record.
| Type The code for the type of recovery log record.
| Subtype
| Some types of recovery log records are further divided into subtypes.
| Undo next LSN
| Identifies the log RBA of the next log record to be undone during
| backwards (UNDO processing) recovery.

652 Administration Guide

| STCK, or LRSN+member ID
| In a non-data-sharing environment, this is a 10-byte store clock value
| (STCK) reflecting the date and time the record was placed in the output
| buffer. The last 2 bytes contain zeros.
| In a data sharing environment, this contains a 10-byte log record sequence
| number (LRSN) followed by a 2-byte member ID.
| Data Data associated with the log record. The contents of the data field depend
| on the type and subtype of the recovery log record.

Data (maximum 35962)

STCK, or LSRN + member ID (8)

Undo next LSN (6)

Length of header (1)
Release identifier (1)

LINK (6)
Unit of recovery ID (6)

Flags (1)

Resource manager ID (1)

Record subtype (2)
Record type (2)

Length of previous record or segment (2)

Length of this record or segment (2)

Figure 65. 6-byte format of a Db2 recovery log record

Length of this record

The total length of the record in bytes.
Length of previous record
The total length of the previous record in bytes.
Type The code for the type of recovery log record.
Subtype
Some types of recovery log records are further divided into subtypes.
Resource manager ID
Identifier of the resource manager that wrote the record into the log. When
the log is read, the record can be given for processing to the resource
manager that created it.
Unit of recovery ID
A unit of recovery to which the record is related. Other log records can be
related to the same unit of recovery; all of them must be examined to
recover the data. The URID is the RBA (relative byte address) of the
Begin-UR log record, and indicates the start of that unit of recovery in the
log.
LINK Chains all records written using their RBAs. For example, the link in an
end checkpoint record links the chains back to the begin checkpoint record.
Chapter 14. Reading log records 653
 Release identifier
Identifies in which release the log was written.
Log record header length
The total length of the header of the log record.
Undo next LSN
Identifies the log RBA of the next log record to be undone during
backwards (UNDO processing) recovery.
STCK, or LRSN+member ID
In a non-data-sharing environment, this is a 6-byte store clock value
(STCK) reflecting the date and time the record was placed in the output
buffer. The last 2 bytes contain zeros.
In a data sharing environment, this contains a 6-byte log record sequence
number (LRSN) followed by a 2-byte member ID.
Data Data associated with the log record. The contents of the data field depend
on the type and subtype of the recovery log record.

PSPI

Related reference:
Log record type codes
Log record subtype codes

Log record type codes

The type code of a log record tells what kind of Db2 event the record describes.

PSPI

Code Type of event

0002 Page set control
0004 SYSCOPY utility
0010 System event
0020 Unit of recovery control
0100 Checkpoint
0200 Unit of recovery undo
0400 Unit of recovery redo
0800 Archive log command
1000 to 8000
Assigned by Db2
2200 Savepoint
4200 End of rollback to savepoint
4400 Alter or modify recovery log record

A single record can contain multiple type codes that are combined. For example,
0600 is a combined UNDO/REDO record; F400 is a combination of four
Db2-assigned types plus a REDO. A diagnostic log record for the TRUNCATE

654 Administration Guide

 IMMEDIATE statement is type code 4200, which is a combination of a diagnostic
log record (4000) and an UNDO record (0200). PSPI

Log record subtype codes

The log record subtype code provides a more granular definition of the event that
occurred and that generated the log record. Log record subtype codes are unique
only within the scope of the corresponding log record type code.

PSPI

Log record type 0004 (SYSCOPY utility) has log subtype codes that correspond to
the page set ID values of the table spaces that have their SYSCOPY records in the
log (SYSIBM.SYSUTILX, SYSIBM.SYSCOPY, DSNDB01.DBD01, and
DSNDB01.SYSDBDXA).

Log record type 0800 (quiesce) does not have subtype codes.

Some log record types (1000 - 8000 assigned by Db2) can have proprietary log
record subtype codes assigned.

Subtypes for type 0002 (page set control)

Code Type of event
0001 Page set open
0002 Data set open
0003 Page set close
0004 Data set close
0005 Page set control checkpoint
0006 Page set write
0007 Page set write I/O
0008 Page set reset write
0009 Page set status
| 000A Compression dictionary write

Subtypes for type 0010 (system event)

Code Type of event
0001 Begin checkpoint
0002 End checkpoint
0003 Begin current status rebuild
0004 Begin historic status rebuild
0005 Begin active unit of recovery backout
0006 Pacing record

Subtypes for type 0020 (unit of recovery control)

Code Type of event
0001 Begin unit of recovery

Chapter 14. Reading log records 655

 0002 Begin commit phase 1 (Prepare)
0004 End commit phase 1 (Prepare)
0008 Begin commit phase 2
000C Commit phase 1 to commit phase 2 transition
0010 End commit phase 2
0020 Begin abort
0040 End abort
0081 End undo
0084 End todo
0088 End redo

Subtypes for type 0100 (checkpoint)

Code Type of event
0001 Unit of recovery entry
0002 Restart unit of recovery entry

Subtypes for type 2200 (savepoint)

Code Type of event
0014 Roll back to savepoint
000E Release to savepoint

Subtypes for type 4200 (end of rollback to savepoint)

Code Type of event
0084 End of savepoint
0085 End of savepoint

Subtypes for type 4200 (diagnostic log record for TRUNCATE

IMMEDIATE)
Code Type of event
0085 Special begin for TRUNCATE IMMEDIATE
0086 Special commit for TRUNCATE IMMEDIATE

Subtypes for type 4400 (alter or modify log record)

Code Type of event
0083 Alter or modify log record used for Db2 replication

PSPI

Related reference:
DSN1LOGP (Db2 Utilities)

656 Administration Guide

 Interpreting data change log records
For specific log record types, Db2 provides the mapping and description that you
can use to interpret data changes that are made to Db2 tables from the log.

PSPI

The macros are contained in the data set library prefix SDSNMACS and are
documented by comments in the macros themselves.

Log record formats for the record types and subtypes are detailed in the mapping
macro DSNDQJ00. DSNDQJ00 provides the mapping of specific data change log
records, UR control log records, and page set control log records that you need to
interpret data changes by the UR. DSNDQJ00 also explains the content and usage
of the log records.

PSPI

Related reference:
Log record subtype codes

Reading log records with IFI

You can use the READA (read asynchronously) request of the instrumentation
facility interface (IFI) to read log records into a buffer. Use the READS (read
synchronously) request to read specific log control intervals from a buffer. You can
use these requests online while Db2 is running.

About this task

PSPI

You can write a program that uses IFI to capture log records while Db2 is running.
You can read the records asynchronously, by starting a trace that reads the log
records into a buffer and then issuing an IFI call to read those records out of the
buffer. Alternatively, you can read those log records synchronously, by using an IFI
call that returns those log records directly to your IFI program.

Restriction: Either the primary authorization ID or one of the secondary

authorization IDs must have the MONITOR2 privilege.

PSPI

Related concepts:
Programming for the instrumentation facility interface (IFI) (Db2 Performance)

Related tasks:
Requesting data synchronously from a monitor program (Db2 Performance)
Requesting data asynchronously from a monitor program (Db2 Performance)
Related reference:
READA (Db2 Performance)
READS (Db2 Performance)

Chapter 14. Reading log records 657

 Gathering active log records into a buffer
Use the START TRACE command to begin gathering active log records into a
buffer.

Procedure

PSPI

To gather active log records:

Issue the following START TRACE command in an instrumentation facility

interface (IFI) program:
-START TRACE(P) CLASS(30) IFCID(126) DEST(OPX)

where:
v P signifies to start a Db2 performance trace. Any of the Db2 trace types can be
used.
v CLASS(30) is a user-defined trace class (31 and 32 are also user-defined classes).
v IFCID(126) activates Db2 log buffer recording.
v DEST(OPX) starts the trace to the next available Db2 online performance (OP)
buffer. The size of this OP buffer can be explicitly controlled by the BUFSIZE
keyword of the START TRACE command. Valid sizes range from 256 KB to 16
MB. The number must be evenly divisible by 4.
When the START TRACE command takes effect, from that point forward until Db2
terminates, Db2 begins writing 4-KB log buffer VSAM control intervals (CIs) to the
OP buffer as well as to the active log. As part of the IFI COMMAND invocation,
the application specifies an ECB to be posted and a threshold to which the OP
buffer is filled when the application is posted to obtain the contents of the buffer.
The IFI READA request is issued to obtain OP buffer contents.

PSPI

Reading specific log records (IFCID 0129)

You can use IFCID 129 with an IFI READS (read synchronously) request to return
a specific range of log records from the active log into the return area that is
initialized by your program.

About this task

PSPI

Enter the following command into your IFI program:

CALL DSNWLI(READS,ifca,return_area,ifcid_area,qual_area)

IFCID 129 must appear in the IFCID area.

To retrieve the log control interval, your program must initialize certain fields in
the qualification area:
WQALLTYP
This is a 3-byte field in which you must specify CI (with a trailing blank),
which stands for “control interval”.

658 Administration Guide

 WQALLMOD
In this 1-byte field, you specify whether you want the first log CI of the
restarted Db2 subsystem, or whether you want a specific control interval as
specified by the value in the RBA field.
F The “first” option is used to retrieve the first log CI of this Db2 instance.
This option ignores any value in WQALLRBA and WQALLNUM.
P The “partial” option is used to retrieve partial log CIs for the log capture
exit routine. Db2 places a value in field IFCAHLRS of the IFI
communication area, as follows:
v The RBA of the log CI given to the log capture exit routine, if the last CI
written to the log was not full.
v 0, if the last CI written to the log was full.
When you specify option P, Db2 ignores values in WQALLRBA and
WQALLNUM.
R The “read” option is used to retrieve a set of up to 7 continuous log CIs. If
you choose this option, you must also specify the WQALLRBA and
WQALLNUM options, which the following text details.
WQALLRBA
In this 8-byte field, you specify the starting log RBA of the control intervals to
be returned. This value must end in X'000' to put the address on a valid
boundary. This field is ignored when using the WQALLMOD=F option.
If you specify an RBA that is not in the active log, reason code 00E60854 is
returned in the field IFCARC2, and the RBA of the first CI of the active log is
returned in field IFCAFCI of the IFCA. These 6 bytes contain the IFCAFCI
field.
WQALLNUM
In this 2-byte field, specify the number of control intervals you want returned.
The valid range is from X'0001' through X'0007', which means that you can
request and receive up to seven 4-KB log control intervals. This field is ignored
when using the WQALLMOD=F option.

If you specify a range of log CIs, but some of those records have not yet been
written to the active log, Db2 returns as many log records as possible. You can find
the number of CIs returned in field QWT02R1N of the self-defining section of the
record.

PSPI

Related concepts:
Log capture routines
Db2 trace output (Db2 Performance)
Related reference:
Qualification fields for READS requests (Db2 Performance)

Reading complete log data (IFCID 0306)

Several benefits are associated with use of IFCID 0306 to read log data.

About this task

PSPI The benefits of using IFCID 0306 are:

Chapter 14. Reading log records 659

 v IFCID 0306 can request Db2 to decompress log records if compressed, before
passing them to the return area of your IFI program.
| v In a data sharing environment, Db2 merges log records if the value of the IFI
| READS qualification WQALFLTR is X'00'. If WQALFLTR is X'03', log records are
| not merged.
v IFCID can retrieve log records from the archive data sets.
v Complete log records are always returned.

Procedure

To use IFCID 0306:

Issue an IFI READS call.

CALL DSNWLI(READS,ifca,return_area,ifcid_area,qual_area)

IFCID 0306 must appear in the IFCID area. IFCID 0306 returns complete log
records. Multi-segmented control interval log records are combined for a complete
log record.
Generally, catalog and directory objects cannot be in group buffer pool
RECOVER-pending (GRECP) status when an IFCID 0306 request accesses the
compression dictionary. Only log entries for tables that are defined with DATA
CAPTURE CHANGES enabled are decompressed.
PSPI

Related tasks:
Reading specific log records (IFCID 0129)

Specifying the return area

You must specify the return area for IFCID 0306 requests.

About this task

|
PSPI
|
| The return area for monitor programs that issue IFCID 0306 requests must reside
| either in ECSA key 7 storage or in the 64-bit common key 7 storage area above the
| 2-GB bar. The IFCARA64 processing flag in the IFCA controls the location of the
| return area. If the return area resides in 64-bit common storage, the first eight bits
| of the ECSA key 7 return area must contain a pointer to the location of the return
| area in the 64-bit common storage.

The IFI application program must set the eye-catcher to 'I306' at offset 4 in the
return area before making the IFCID 0306 call. An additional 60-byte area must be
included after the 4-byte length indicator and the 'I306' eye-catcher. This area is
used by Db2 between successive application calls and must not be modified by the
application.

The IFI application program must run in supervisor state to request the key 7
return area. The storage size of the return area must be a minimum of the largest
Db2 log record returned plus the additional area defined in DSNDQW04. Minimize
the number of IFI calls required to get all log data but do not over use ECSA by
the IFI program. The other IFI storage areas can remain in user storage key 8. The
IFI application must be in supervisor state and key 0 when making IFCID 0306
calls.

660 Administration Guide

 Important: The recommended size of the ECSA return area for IFCID 306 requests
is between 66 KB and 200 KB. Specifying more than 200 KB for this return area
might cause performance problems or even failures for other critical application
programs that depend on ECSA storage. Because the log record counter is a 2 byte
value, IFCID 306 might also return an incorrect count of log records if too much
space is specified for the ECSA return area.

IFCID 0306 has a unique return area format. The first section is mapped by
QW0306OF instead of the write header DSNDQWIN.

PSPI

Related concepts:
Programming for the instrumentation facility interface (IFI) (Db2 Performance)

| Shared memory storage requirements (Db2 Installation and Migration)

Related reference:
Instrumentation facility communications area (IFCA) (Db2 Performance)
Return area (Db2 Performance)
Trace fields for READS requests (Db2 Performance)

Qualifying log records

To retrieve IFCID 0306 log records, your program must initialize certain fields in
the qualification area that is mapped by DSNDWQAL.

PSPI

These qualification fields are:

WQALLMOD
In this 1-byte field, specify one of the following modes:
'D'
Retrieves the single log record whose RBA value and member id is
specified in WQALLRBA. Issuing a D request while holding a position in
the log, causes the request to fail and terminates the log position held.
'F'
Used as a first call to request log records beyond the LRSN or RBA
specified in WQALLRBA that meet the criteria specified in WQALLCRI.
'H'
Retrieves the highest LRSN or log RBA in the active log. The value is
returned in field IFCAHLRS of the IFI communications area (IFCA). There
is no data returned in the return area and the return code for this call will
indicate that no data was returned.
'N'
Used following mode F or N calls to request any remaining log records
that meet the criteria specified in WQALLCRI. * and any option specified
in WQALLOPT. As many log records as fit in the program's return area are
returned.
'T'
Terminates the log position that was held by any previous F or N request.
This allows held resources to be released.

Chapter 14. Reading log records 661

 Mode R is not used for IFCID 0306.
For both F or N requests, each log record that is returned contains a
record-level feedback area recorded in QW0306L. The number of log records
retrieved is in QW0306CT. The ending log RBA or LRSN of the log records to
be returned is in QW0306ES. If previous READS requests returned 00E60812
(successful end of READS), for a data sharing environment you can use either
QW0306ES and QW0306ES+1 in the next F call. For a non-data sharing
environment, use QW0306ES+1 as the start of the log read in the next F call.
The F call returns the next range from the last RBA that was provided.
Consider the following example:
First, the READS request ends with 00E60812:
| WQALLMOD WQALLRBA
| -------- --------------------
| READS input: C6 00000000CAC5B606C843
|
| QW0306ES QW0306CT IFCARC1 IFCARC2 IFCABM
| -------------------- -------- ------- -------- --------
| READS output: 00000000CAC5B606CB6C 0060 04 00E60812 00011F3F

In the next F call for a data sharing environment, you specify either QW0306ES
and QW0306ES+1 as the input for WQALLRBA:
| WQALLMOD WQALLRBA
| -------- --------------------
| READS input: C6 00000000CAC5B606CB6C
|
| QW0306ES QW0306CT IFCARC1 IFCARC2 IFCABM
| -------------------- -------- ------- -------- --------
| READS output: 00000000CAC5B606CE91 008E 04 00E60812 00004B7B
| WQALLCRI
| In this 1-byte field, indicate what types of log records are to be returned:
| X'00' (WQALLCR0)
| Only log records for changed data capture and unit of recovery control.
| X'01' (WQALLCR1)
| Only log records for changed data capture and unit of recovery control
| from the proxy data sharing group in a GDPS® Continuous Availability
| with zero data loss environment. Records are returned until the
| end-of-scope log point is reached.
| X'02' (WQALLCR2)
| All types of log records from the proxy data sharing group in a GDPS
| Continuous Availability with zero data loss environment. Records are
| returned until the end-of-scope log point is reached.
| X'03' (WQALLCR3)
| Only log records for changed data capture and unit of recovery control
| from the proxy data sharing group in a GDPS Continuous Availability with
| zero data loss environment. Records are returned until the end-of-log point
| is reached for all members of the data sharing group.
| X'04' (WQALLCR4)
| All types of log records from the proxy data sharing group in a GDPS
| Continuous Availability with zero data loss environment. Records are
| returned until the end-of-log point is reached for all members of the data
| sharing group.

662 Administration Guide

| X'FF' (WQALLCRA)
| All types of log records. Use of this option can retrieve large data volumes
| and degrade Db2 performance.
WQALLOPT
In this 1-byte field, indicate whether you want the returned log records to be
decompressed.
X'01'
Tells Db2 to decompress the log records before they are returned.
X'00'
Tells Db2 to leave the log records in the compressed format.
| WQALLRBA
| In this 12-byte field, specify the starting log RBA or LRSN of the control
| records to be returned. For IFCID 0306, this is used on the “first” option (F)
| request to request log records beyond the LRSN or RBA specified in this field.
| Determine the RBA or LRSN value from the H request. For RBAs, the value
| plus one should be used. For IFCID 0306 with D request of WQALLMOD, the
| high-order 2 bytes must specify member id and the low order 10 bytes contain
| the RBA.
| WQALWQLS
| In this 64-bit pointer, specify the address of an optional qualification block
| named WQLS, and mapped by DSNDWQAL, to filter log records returned for
| IFCID 0306. The qualification block consists of a header of type ’DBPS’, count
| of qualification items up to 50,000, and a list containing DBID and PSID pairs
| or DBID and OBID pairs. For table space log records, include DBID and PSID
| pairs. For table log records, include DBID and OBID pairs. WQALLCRI must
| be set to X'00' for this additional qualification.

A typical sequence of IFCID 0306 calls is:

WQALLMOD='H'
This call is necessary only if you want to find the current position in the log.
The LRSN or RBA is returned in IFCAHLRS. The return area is not used.

Important: To avoid data loss, before you issue an IFCID 0306 call with
WQALLMOD='H' to a proxy group in a GDPS Continuous Availability with
zero data loss environment, ensure that the Sysplex Timers for the source
Sysplex and the proxy Sysplex are set to within 150 milliseconds of each other.
WQALLMOD='F'
The WQALLRBA, WQALLCRI and WQALLOPT fields need to be set. If
00E60812 is returned, you have all the data for this scope. You should wait a
while before issuing another WQALLMOD='F' call. In a data sharing
environment, log buffers are flushed when a request with WQALLMOD='F'
request is issued.
WQALLMOD='N'
If the 00E60812 has not been returned, you issue this call until it is. You should
wait a while before issuing another WQALLMOD='F' call.
WQALLMOD='T'
This should only be used if you do not want to continue with the
WQALLMOD='N' before the end is reached. It has no use if a position is not
held in the log.

Chapter 14. Reading log records 663

 PSPI

| Reading complete log data for the GDPS Continuous Availability with
| zero data loss solution
| The GDPS Continuous Availability with zero data loss solution provides disaster
| recovery with continuous availability in a z/OS environment. When Db2
| participates in a GDPS Continuous Availability with zero data loss environment,
| IFI applications issue READS calls for IFCID 0306 to a proxy data sharing group,
| and the proxy data sharing group captures log records from a source data sharing
| group. Before the IFI applications can do that, you need to modify your Db2
| environment, and modify the IFI applications that capture log records.

| Before you begin

| To learn more about the GDPS Continuous Availability with zero data loss
| solution, contact IBM Resiliency services at [email protected].

| Modifying Db2 for the GDPS Continuous Availability with zero

| data loss solution
| If you are using the GDPS Continuous Availability with zero data loss solution
| with Db2 for the first time, you need to modify your Db2 data sharing groups.

| About this task

| You need to make a number of changes to your Db2 environment if one of the
| following situations is true:
| v You are using the original release of the GDPS Continuous Availability with zero
| data loss solution, and you are ready to upgrade to the GDPS Continuous
| Availability with zero data loss (GDPS Continuous Availability with zero data
| loss) solution.
| v You have not used the GDPS Continuous Availability with zero data loss
| solution before, and you are installing the GDPS Continuous Availability with
| zero data loss (GDPS Continuous Availability with zero data loss) solution.

| GDPS Continuous Availability with zero data loss solution terminology: A

| GDPS Continuous Availability with zero data loss solution that includes Db2
| requires three data sharing environments. The solution includes a source Db2 data
| sharing group, a proxy Db2 data sharing group, and a target Db2 data sharing
| group. The proxy group uses a capture program to capture changes to tables on the
| source group. The proxy group then uses a replication program to replicate the
| changes to the target group. A VSAM key-sequenced data set, called the
| compression dictionary data set (CDDS), must be defined in the source group. It holds
| the following items for use in capture and replication:
| v The expansion dictionaries for Db2 tables whose changes are captured
| Currently, the CDDS contains a maximum of three versions of the expansion
| dictionaries.
| v System status information that the proxy group uses to find the log data sets
| and to determine the status of the source group members

664 Administration Guide

| Procedure

| To prepare Db2 data sharing groups to use the GDPS Continuous Availability with
| zero data loss solution, follow these steps:
| 1. Convert all members of your source and proxy data sharing groups to Db2 11
| new-function mode.
| 2. Convert the BSDS data sets to extended 10-byte format by running the
| DSNTIJCB job on all members of your source and proxy data sharing groups.
| 3. Choose a member of the source data sharing group that is not running a
| capture program to be the first member to be upgraded. Create the CDDS on
| that member.
| To minimize the possibility of an out-of-space condition, you should define an
| SMS data class for the CDDS with the following attributes enabled:
| v Extended addressability
| v Extended format
| v Extent constraint relief
| v CA reclaim
| Define the CDDS with a DEFINE CLUSTER command like the one below. In
| your DEFINE CLUSTER command, you need to specify the same values that
| are shown in the example for these parameters:
| v KEYS
| v RECORDSIZE
| v SPANNED
| v SHAREOPTIONS
| v CONTROLINTERVALSIZE
| DEFINE CLUSTER -
| ( NAME(prefix.CDDS) -
| KEYS(8 0) -
| RECORDSIZE(66560 66560) -
| SPANNED -
| SHAREOPTIONS(3 3)) -
| DATA -
| ( CYLINDERS(1000 1000) -
| CONTROLINTERVALSIZE(16384)) -
| INDEX -
| ( CYLINDERS(20 20) -
| CONTROLINTERVALSIZE(512))
| The CDDS name must be of the form prefix.CDDS.
| 4. Stop Db2 on the first source member that is being upgraded.
| 5. On the first source member that is being upgraded, apply all Db2 PTFs that
| provide GDPS Continuous Availability with zero data loss support.
| 6. On the first source member that is being upgraded, set the following
| subsystem parameters:
| v Set subsystem parameter CDDS_MODE to SOURCE.
| v Set subsystem parameter CDDS_PREFIX to the prefix value that you
| specified when you created the CDDS.
| 7. Start Db2 on the first source member that is being upgraded.
| 8. Upgrade each of the remaining members of the source group, one at a time.
| To do that, follow these steps.

Chapter 14. Reading log records 665

| Important: If a member of the data sharing group is running a capture
| program, upgrade that member last. If no capture programs are running, you
| can upgrade the members in any order.
| a. Stop Db2 on the source member that is being upgraded.
| b. On the source member that is being upgraded, apply all Db2 PTFs that
| provide GDPS Continuous Availability with zero data loss support.
| c. On the source member that is being upgraded, set the following subsystem
| parameters:
| v Set subsystem parameter CDDS_MODE to SOURCE.
| v Set subsystem parameter CDDS_PREFIX to the prefix value that you
| specified when you created the CDDS.
| d. Start Db2 on the source member that is being upgraded.
| 9. After Db2 is started on the last member of the source group, run REORG
| TABLESPACE with the INITCDDS option to populate the CDDS.
| 10. Enable peer-to-peer remote recovery (PPRC) to mirror the BSDS data sets,
| active logs, archive logs, and the CDDS from the source group to the
| read-only volumes in the proxy group.
| 11. Upgrade the members of the proxy data sharing group, one at a time. To do
| that, follow these steps.
| a. Stop Db2 on the proxy member that is being upgraded.
| b. On the proxy member that is being upgraded, apply all Db2 PTFs that
| provide GDPS Continuous Availability with zero data loss support.
| c. On the proxy member that is being upgraded, set the following subsystem
| parameters:
| v Set subsystem parameter CDDS_MODE to PROXY.
| v Set subsystem parameter CDDS_PREFIX to the prefix value that you
| specified when you created the CDDS on the first source member.
| d. Start Db2 on the proxy member that is being upgraded.
| 12. Set the Sysplex Timer on the Sysplex for the source data sharing group and
| the Sysplex for the proxy data sharing group to the same value.

| Important: This step is essential to ensure zero data loss, and to avoid
| extended data replication latency.
| Related tasks:
| Convert the BSDS, Db2 catalog, and directory to 10-byte RBA and LRSN
| format (Optional) (Db2 Installation and Migration)
| Related reference:
| CDDS_MODE in macro DSN6LOGP (Db2 Installation and Migration)
| CDDS_PREFIX in macro DSN6LOGP (Db2 Installation and Migration)
| Syntax and options of the REORG TABLESPACE control statement (Db2
| Utilities)
| Allocation of data sets with space constraint relief attributes (z/OS DFSMS
| Using Data Sets)
| Extended format VSAM data sets (z/OS DFSMS Using Data Sets)
| Defining data class attributes (z/OS DFSMSdfp Storage Administration)
| Reclaiming CA space for a KSDS (z/OS DFSMS Using Data Sets)
| Related information:
666 Administration Guide
| DEFINE CLUSTER command (DFSMS Access Method Services for Catalogs)
| Defining volume and data set attributes for data classes (DFSMSdfp Storage
| Administration)

| Modifying IFI READS calls for the GDPS Continuous

| Availability with zero data loss environment
| When you implement the GDPS Continuous Availability with zero data loss (GDPS
| Continuous Availability with zero data loss) solution, you need to modify your
| programs that issue IFI READS calls for IFCID 0306 to capture log records.

| Before you begin

| Before you can capture log records in a GDPS Continuous Availability with zero
| data loss (GDPS Continuous Availability with zero data loss) environment, you
| need to perform the tasks that are described in Modifying Db2 for the GDPS
| Continuous Availability with zero data loss solution.

| Procedure

| To modify an IFI READS call for IFCID 0306 to capture log records in a GDPS
| Continuous Availability with zero data loss environment:

| Specify one of the following values in the WQALLCRI field in the IFI qualification
| area to indicate that log records are being returned by the proxy data sharing
| group.
| X'01' (WQALLCR1)
| Only log records for changed data capture and unit of recovery control from
| the proxy data sharing group in a GDPS Continuous Availability with zero
| data loss environment. Records are returned until the end-of-scope log point is
| reached.
| X'02' (WQALLCR2)
| All types of log records from the proxy data sharing group in a GDPS
| Continuous Availability with zero data loss environment. Records are returned
| until the end-of-scope log point is reached.
| X'03' (WQALLCR3)
| Only log records for changed data capture and unit of recovery control from
| the proxy data sharing group in a GDPS Continuous Availability with zero
| data loss environment. Records are returned until the end-of-log point is
| reached for all members of the data sharing group.
| X'04' (WQALLCR4)
| All types of log records from the proxy data sharing group in a GDPS
| Continuous Availability with zero data loss environment. Records are returned
| until the end-of-log point is reached for all members of the data sharing group.

| PSPI

| Related tasks:
| Reading complete log data (IFCID 0306)
| Modifying Db2 for the GDPS Continuous Availability with zero data loss solution
| Related reference:
| Qualification fields for READS requests (Db2 Performance)

Chapter 14. Reading log records 667

| Recovering the compression dictionary data set without
| bringing down a Db2 data sharing group
| If the compression dictionary data set (CDDS) becomes logically damaged, you
| need to recover or rebuild it.

| About this task

| An implementation of the GDPS Continuous Availability with zero data loss

| (GDPS Continuous Availability with zero data loss) solution uses a CDDS for the
| source data sharing group. Before you can recover a CDDS, the CDDS must be
| closed and deallocated. You can close and deallocate the CDDS without stopping
| the Db2 data sharing group by issuing the -STOP CDDS command. After you
| recover the CDDS, you can allocate and open the CDDS by issuing the -START
| CDDS command.

| Procedure

| To recover or rebuild a CDDS, follow these steps in the source data sharing group:
| 1. Issue the -STOP CDDS command to direct all members of the data sharing group
| to close and deallocate the CDDS.
| 2. Issue the DFSMSdss RESTORE command to restore the CDDS from the latest
| backup copy.
| If you do not have a backup copy, delete and redefine the CDDS. See
| Modifying Db2 for the GDPS Continuous Availability with zero data loss
| solution for an example of the CDDS definition.
| 3. Issue the -START CDDS command to direct all members of the data sharing
| group to allocate and open the CDDS.
| 4. Run REORG TABLESPACE with the INITCDDS option to repopulate the
| CDDS.
| You can specify the SEARCHTIME option with the INITCDDS option to allow
| REORG to populate the CDDS with an earlier dictionary than the dictionary
| that currently resides in the target table space.
| Related concepts:
| RESTORE command for DFSMSdss (z/OS DFSMSdss Storage Administration)
|
| Related tasks:
| Modifying Db2 for the GDPS Continuous Availability with zero data loss solution
| Related reference:
| Syntax and options of the REORG TABLESPACE control statement (Db2
| Utilities)
| -STOP CDDS (Db2) (Db2 Commands)
| -START CDDS (Db2) (Db2 Commands)

Reading log records with OPEN, GET, and CLOSE

You can use the assembler language DSNJSLR macro to submit OPEN, GET, and
CLOSE functions. Use this stand-alone method to capture log records that you
cannot read with the instrumentation facility interface (IFI) when Db2 stops
running.

668 Administration Guide

 About this task

PSPI

Db2 provides the following stand-alone log services that user-written application
programs can use to read Db2 recovery log records and control intervals even
when Db2 is not running:
v The OPEN function initializes stand-alone log services.
v The GET function returns a pointer to the next log record or log record control
interval.
v The CLOSE function deallocates data sets and frees storage.

To invoke these services, use the assembler language DSNJSLR macro and specify
one of the preceding functions.

These log services use a request block, which contains a feedback area in which
information for all stand-alone log GET calls is returned. The request block is
created when a stand-alone log OPEN call is made. The request block must be
passed as input to all subsequent stand-alone log calls (GET and CLOSE). The
request block is mapped by the DSNDSLRB macro, and the feedback area is
mapped by the DSNDSLRF macro.

When you issue an OPEN request, you can indicate whether you want to get log
records or log record control intervals. Each GET request returns a single logical
record or control interval depending on which you selected with the OPEN
request. If neither is specified, the default, RECORD, is used. Db2 reads the log in
the forward direction of ascending relative byte addresses or log record sequence
numbers (LRSNs).

If a bootstrap data set (BSDS) is allocated before stand-alone services are invoked,
appropriate log data sets are allocated dynamically by z/OS. If the bootstrap data
set is not allocated before stand-alone services are invoked, the JCL for your
user-written application to read a log must specify and allocate the log data sets to
be read.

Important: Use one of the following methods to read active logs while the Db2
subsystem that owns the logs is active:
v IFCID 0129
v IFCID 0306
v Log capture exit

There are no restrictions on reading archive logs.

PSPI

JCL DD statements for Db2 stand-alone log services

Stand-alone services, such as OPEN, GET, and CLOSE, use a variety of JCL DD
statements as they operate.

PSPI

The following tables list and describe the JCL DD statements that are used by
stand-alone services.

Chapter 14. Reading log records 669

 Table 60. JCL DD statements for Db2 stand-alone log services
JCL DD
statement Explanation
BSDS Specifies the bootstrap data set (BSDS). Optional. Another ddname can
be used for allocating the BSDS, in which case the ddname must be
specified as a parameter on the FUNC=OPEN. Using the ddname in this
way causes the BSDS to be used. If the ddname is omitted on the
FUNC=OPEN request, the processing uses DDNAME=BSDS when
attempting to open the BSDS.
ARCHIVE Specifies the archive log data sets to be read. Required if an archive data
set is to be read and the BSDS is not available (the BSDS DD statement
is omitted). Should not be present if the BSDS DD statement is present.
If multiple data sets are to be read, specify them as concatenated data
sets in ascending log RBA order.
ACTIVEn (Where n is a number from 1 to 7). Specifies an active log data set that is
to be read. Should not be present if the BSDS DD statement is present. If
only one data set is to be read, use ACTIVE1 as the ddname. If multiple
active data sets are to be read, use DDNAMEs ACTIVE1, ACTIVE2, ...
ACTIVEn to specify the data sets. Specify the data sets in ascending log
RBA order with ACTIVE1 being the lowest RBA and ACTIVEn being the
highest.

Table 61. JCL DD statements for Db2 stand-alone log services in a data-sharing environment
JCL DD
statement Explanation
GROUP If you are reading logs from every member of a data sharing group in
LRSN sequence, you can use this statement to locate the BSDSs and log
data sets needed. You must include the data set name of one BSDS in
the statement. Db2 can find the rest of the information from that one
BSDS.

All members' logs and BSDS data sets must be available. If you use this
DD statement, you must also use the LRSN and RANGE parameters on
the OPEN request. The GROUP DD statement overrides any MxxBSDS
statements that are used.

(Db2 searches for the BSDS DD statement first, then the GROUP
statement, and then the MxxBSDS statements. If you want to use a
particular member's BSDS for your own processing, you must call that
DD statement something other than BSDS.)
MxxBSDS Names the BSDS data set of a member whose log must participate in the
read operation and whose BSDS is to be used to locate its log data sets.
Use a separate MxxBSDS DD statement for each Db2 member. xx can be
any two valid characters.

Use these statements if logs from selected members of the data sharing
group are required and the BSDSs of those members are available. These
statements are ignored if you use the GROUP DD statement.

For one MxxBSDS statement, you can use either RBA or LRSN values to
specify a range. If you use more than one MxxBSDS statement, you must
use the LRSN to specify the range.

670 Administration Guide

Table 61. JCL DD statements for Db2 stand-alone log services in a data-sharing
environment (continued)
JCL DD
statement Explanation
MyyARCHV Names the archive log data sets of a member to be used as input. yy can
be any two valid characters that do not duplicate any xx used in an
MxxBSDS DD statement.

Concatenate all required archived log data sets of a given member in

time sequence under one DD statement. Use a separate MyyARCHV DD
statement for each member. You must use this statement if the BSDS
data set is unavailable or if you want only some of the log data sets
from selected members of the group.

If you name the BSDS of a member by a MxxBSDS DD statement, do not

name the log of the same member by an MyyARCHV statement. If both
MyyARCHV and MxxBSDS identify the same log data sets, the service
request fails. MyyARCHV statements are ignored if you use the GROUP
DD statement.
MyyACTn Names the active log data set of a member to be used as input. yy can
be any two valid characters that do not duplicate any xx used in an
MxxBSDS DD statement. Use the same characters that identify the
MyyARCHV statement for the same member; do not use characters that
identify the MyyARCHV statement for any other member. n is a number
from 1 to 16. Assign values of n in the same way as for ACTIVEn DD
statements.

You can use this statement if the BSDS data sets are unavailable or if
you want only some of the log data sets from selected members of the
group.

If you name the BSDS of a member by a MxxBSDS DD statement, do not

name the log of the same member by an MyyACTn statement.
MyyACTn statements are ignored if you use the GROUP DD statement.

The DD statements must specify the log data sets in ascending order of log RBA
(or LRSN) range. If both ARCHIVE and ACTIVEn DD statements are included, the
first archive data set must contain the lowest log RBA or LRSN value. If the JCL
specifies the data sets in a different order, the job terminates with an error return
code with a GET request that tries to access the first record breaking the sequence.
If the log ranges of the two data sets overlap, this is not considered an error;
instead, the GET function skips over the duplicate data in the second data set and
returns the next record. The distinction between out-of-order and overlap is as
follows:
v An out-of-order condition occurs when the log RBA or LRSN of the first record
in a data set is greater than that of the first record in the following data set.
v An overlap condition occurs when the out-of-order condition is not met but the
log RBA or LRSN of the last record in a data set is greater than that of the first
record in the following data set.

Gaps within the log range are permitted. A gap is created when one or more log
data sets containing part of the range to be processed are not available. This can
happen if the data set was not specified in the JCL or is not reflected in the BSDS.
When the gap is encountered, an exception return code value is set, and the next
complete record after the gap is returned.

Chapter 14. Reading log records 671

 Normally, the BSDS DD name is supplied in the JCL, rather than a series of
ACTIVE DD names or a concatenated set of data sets for the ARCHIVE ddname.
This is commonly referred to as “running in BSDS mode”.

PSPI

Related reference:
Stand-alone log CLOSE request
Stand-alone log OPEN request
Stand-alone log GET request

Data sharing members that participate in a read

The number of data sharing members whose logs participate in a particular read
request varies based on what statements are used.

PSPI

If you use the GROUP DD statement, then the determinant is the number of
members in the group. Otherwise, the number of different xxs and yys used in the
Mxx and Myy type DD statements.

For example, assume you need to read log records from members S1, S2, S3, S4, S5
and S6.
v S1 and S2 locate their log data sets by their BSDSs.
v S3 and S4 need both archive and active logs.
v S4 has two active log data sets.
v S5 needs only its archive log.
v S6 needs only one of its active logs.

You then need the following DD statements to specify the required log data sets:

MS1BSDS MS2BSDS MS3ARCHV MS4ARCHV MS5ARCHV MS6ACT1

MS3ACT1 MS4ACT1
MS4ACT2

The order of the DD statements in the JCL stream is not important.

PSPI

Registers and return codes

Db2 uses registers to store important information and return codes to help you
determine the status of stand-alone log activity.

PSPI

The request macro invoking these services can be used by reentrant programs. The
macro requires that register 13 point to an 18-word save area at invocation. In
addition, registers 0, 1, 14, and 15 are used as work and linkage registers. A return
code is passed back in register 15 at the completion of each request. When the
return code is nonzero, a reason code is placed in register 0. Return codes identify
a class of errors, while the reason code identifies a specific error condition of that
class. The stand-alone log return codes are shown in the following table.

672 Administration Guide

 Table 62. Stand-alone log return codes
Return code Explanation
0 Successful completion.
4 Exception condition (for example, end of file), not an error. This return
code is not applicable for OPEN and CLOSE requests.
8 Unsuccessful completion due to improper user protocol.
12 Unsuccessful completion. Error encountered during processing of a valid
request.

The stand-alone log services invoke executable macros that can execute only in
24-bit addressing mode and reference data below the 16-MB line. User-written
applications should be link-edited as AMODE(24), RMODE(24).

PSPI

Stand-alone log OPEN request

A stand-alone log OPEN request initializes the stand-alone log services.

PSPI

The syntax for the stand-alone log OPEN request is:

{label} DSNJSLR FUNC=OPEN
,LRSN=YES³NO
,DDNAME= address or (Reg. 2-12) optional
,RANGE= address or (Reg. 2-12) optional
,PMO=CI or RECORD
Keyword
Explanation
FUNC=OPEN
Requests the stand-alone log OPEN function.
LRSN
Tells Db2 how to interpret the log range:
NO: the log range is specified as RBA values. This is the default.
YES: the log range is specified as LRSN values.
DDNAME
Specifies the address of an 8-byte area which contains the ddname to be
used as an alternate to a ddname of the BSDS when the BSDS is opened,
or a register that contains that address.
| RANGE
| Specifies the address of a 32-byte area that contains the log range that is to
| be processed by subsequent GET requests against the request block that is
| generated by this request, or a register that contains that address.
| The area is 32-bytes. Bytes 7-16 contain starting RBA or LRSN value. Bytes
| 23-32 contain the end of the range or high RBA or LRSN value. An
| end-of-data condition is returned when a GET request tries to access a
| record with a starting RBA or LRSN value greater than this value. A value
| of 10 bytes of X'FF' indicates that the log is to be read until either the end
| of the log (as specified by the BSDS) or the end of the data in the last
| JCL-specified log data set is encountered.

Chapter 14. Reading log records 673

| If LRSN=NO, then the range is specified as RBA values. If LRSN=YES,
| then the range is specified as LRSN values.
| If BSDS, GROUP, or MxxBSDS DD statements are used for locating the log
| data sets to be read, the RANGE parameter is required. If the JCL
| determines the log data sets to be read, the RANGE parameter is optional.
PMO Specifies the processing mode. You can use OPEN to retrieve either log
records or control intervals in the same manner. Specify PMO=CI or
RECORD, then use GET to return the data you have selected. The default
is RECORD.
The rules remain the same regarding control intervals and the range
specified for the OPEN function. Control intervals must fall within the
range specified on the RANGE parameter.
Output
Explanation
GPR 1 General-purpose register 1 contains the address of a request block on
return from this request. This address must be used for subsequent
stand-alone log requests. When no more log GET operations are required
by the program, this request block should be used by a FUNC=CLOSE
request.
GPR 15
General-purpose register 15 contains a return code upon completion of a
request. For nonzero return codes, a corresponding reason code is
contained in register 0.
GPR 0 General-purpose register 0 contains a reason code associated with a
nonzero return code in register 15.

Log control interval retrieval

You can use the PMO option to retrieve log control intervals from archive log data
sets. DSNJSLR also retrieves log control intervals from the active log if the Db2
system is not active. During OPEN, if DSNJSLR detects that the control interval
range is not within the archive log range available (for example, the range purged
from BSDS), an error condition is returned.

Specify CI and use GET to retrieve the control interval you have chosen. The rules
remain the same regarding control intervals and the range specified for the OPEN
function. Control intervals must fall within the range specified on the RANGE
parameter.

Log control interval format

Log control intervals are returned in their actual format and the caller is
responsible for using the correct mapping. The format of the control interval can be
determined by examining the first bit of the second to last byte (offset 4094).

PSPI

Related reference:
JCL DD statements for Db2 stand-alone log services
Registers and return codes

674 Administration Guide

Stand-alone log GET request
A stand-alone log GET request returns a pointer to a buffer that contains the next
log record, based on position information in the request block.

PSPI

A log record is available in the area pointed to by the request block until the next
GET request is issued. At that time, the record is no longer available to the
requesting program. If the program requires reference to a log record's content
after requesting a GET of the next record, the program must move the record into
a storage area that is allocated by the program.

The first GET request, after a FUNC=OPEN request that specified a RANGE
parameter, returns a pointer in the request feedback area. This points to the first
record with a log RBA value greater than or equal to the low log RBA value
specified by the RANGE parameter. If the RANGE parameter was not specified on
the FUNC=OPEN request, then the data to be read is determined by the JCL
specification of the data sets. In this case, a pointer to the first complete log record
in the data set that is specified by the ARCHIVE, or by ACTIVE1 if ARCHIVE is
omitted, is returned. The next GET request returns a pointer to the next record in
ascending log RBA order. Subsequent GET requests continue to move forward in
log RBA sequence until the function encounters the end of RANGE RBA value, the
end of the last data set specified by the JCL, or the end of the log as determined
by the bootstrap data set.

The syntax for the stand-alone log GET request is:

{label} DSNJSLR FUNC=GET
,RBR=(Reg. 1-12)
Keyword
Explanation
FUNC=GET
Requests the stand-alone log GET function.
RBR Specifies a register that contains the address of the request block this
request is to use. Although you can specify any register between 1 and 12,
using register 1 (RBR=(1)) avoids the generation of an unnecessary load
register and is therefore more efficient. The pointer to the request block
(that is passed in register n of the RBR=(n) keyword) must be used by
subsequent GET and CLOSE function requests.
Output
Explanation
GPR 15
General-purpose register 15 contains a return code upon completion of a
request. For nonzero return codes, a corresponding reason code is
contained in register 0.
GPR 0 General-purpose register 0 contains a reason code associated with a
nonzero return code in register 15.

Reason codes 00D10261 - 00D10268 reflect a damaged log. In each case, the RBA of
the record or segment in error is returned in the stand-alone feedback block field
(SLRFRBA). A damaged log can impair Db2 restart; special recovery procedures are
required for these circumstances.

Chapter 14. Reading log records 675

 Information about the GET request and its results is returned in the request
feedback area, starting at offset X'00'. If there is an error in the length of some
record, the control interval length is returned at offset X'0C' and the address of the
beginning of the control interval is returned at offset X'08'.

On return from this request, the first part of the request block contains the
feedback information that this function returns. Mapping macro DSNDSLRF
defines the feedback fields which are shown in the following table. The
information returned is status information, a pointer to the log record, the length
of the log record, and the 6-byte or 10-byte log RBA value of the record.
Table 63. Stand-alone log get feedback area contents
Hex Length
Field name offset (bytes) Field contents
SLRFRC 00 2 Log request return code
SLRFINFO 02 2 Information code returned by dynamic allocation.
Refer to the z/OS SPF job management publication
for information code descriptions
SLRFERCD 04 2 VSAM or dynamic allocation error code, if register
15 contains a nonzero value.
SLRFRG15 06 2 VSAM register 15 return code value.
SLRFFRAD 08 4 Address of area containing the log record or CI
| SLRFRCLL 0C 4 Length of the log record or RBA
| SLRFRBA16 10 16 Log RBA of the log record
| SLRFDDNM 20 8 ddname of data set on which activity occurred
| SLRFMBID 28 8 Member identification of the current log record

PSPI

Related concepts:
X'D1......' codes (Db2 Codes)
Related tasks:
Recovering from different Db2 for z/OS problems
Related reference:
JCL DD statements for Db2 stand-alone log services
Registers and return codes

Stand-alone log CLOSE request

A stand-alone log CLOSE request deallocates any log data sets that were
dynamically allocated by previous processing. In addition, all storage that was
obtained by previous functions, including the request block that is specified on the
request, is freed.

PSPI

The syntax for the stand-alone log CLOSE request is:

{label} DSNJSLR FUNC=CLOSE
,RBR=(Reg. 1-12)

676 Administration Guide

 Keyword
Explanation
FUNC=CLOSE
Requests the CLOSE function.
RBR Specifies a register that contains the address of the request block that this
function uses. Although you can specify any register between 1 and 12,
using register 1 (RBR=(1)) avoids the generation of an unnecessary load
register and is therefore more efficient.
Output
Explanation
GPR 15
Register 15 contains a return code upon completion of a request. For
nonzero return codes, a corresponding reason code is contained in register
0.
GPR 0 Register 0 contains a reason code that is associated with a nonzero return
code that is contained in register 15. The only reason code used by the
CLOSE function is 00D10030.

PSPI

Related reference:
JCL DD statements for Db2 stand-alone log services
Registers and return codes
Related information:
00D10030 (Db2 Codes)

Sample application that uses stand-alone log services

Sample segments of an assembler program use three stand-alone log services
(OPEN, GET, and CLOSE) to process one log record.

PSPI

For example:

Chapter 14. Reading log records 677

 TSTJSLR5
. CSECT
.
.
OPENCALL EQU *
LA R2,NAME GET BSDS DDNAME ADDRESS
LA R3,RANGER GET ADDRESS OF RBA RANGE
DSNJSLR FUNC=OPEN,DDNAME=(R2),RANGE=(R3)
LTR R15,R15 CHECK RETURN CODE FROM OPEN
. BZ GETCALL OPEN OK, DO GET CALLS
.
.
*****************************************************************
* HANDLE ERROR FROM OPEN FUNCTION AT THIS POINT *
*****************************************************************
.
.
.
GETCALL EQU *
DSNJSLR FUNC=GET,RBR=(R1)
C R0,=X’00D10020’ END OF RBA RANGE ?
BE CLOSE YES, DO CLEANUP
C R0,=X’00D10021’ RBA GAP DETECTED ?
BE GAPRTN HANDLE RBA GAP
LTR R15,R15 TEST RETURN CODE FROM GET
. BNZ ERROR
.
.
.
.
.
******************************************************************
* PROCESS RETURNED LOG RECORD AT THIS POINT. IF LOG RECORD *
* DATA MUST BE KEPT ACROSS CALLS, IT MUST BE MOVED TO A *
* USER-PROVIDED AREA. *
******************************************************************
USING SLRF,1 BASE SLRF DSECT
L R8,SLRFFRAD GET LOG RECORD START ADDR
LR R9,R8
AH R9,SLRFRCLL GET LOG RECORD END ADDRESS
. BCTR R9,R0
.
.
CLOSE EQU *
. DSNJSLR FUNC=CLOSE,RBR=(1)
.
.
NAME DC C’DDBSDS’
RANGER
. DC X’00000000000000000005FFFF’
.
.
DSNDSLRB
DSNDSLRF
EJECT
R0 EQU 0
R1 EQU 1
R2
. EQU 2
.
.
R15 EQU 15
END

Figure 66. Excerpts from a sample program using stand-alone log services

PSPI

Reading log records with the log capture exit routine

You can use the log capture exit routine to capture Db2 log data in real time. You
can use this exit routine online while Db2 is running.

678 Administration Guide

 About this task

PSPI This installation exit routine presents log data to a log capture exit routine
when the data is written to the Db2 active log. Do not use this exit routine for
general purpose log auditing or tracking. The IFI interface is designed for this
purpose.

The log capture exit routine executes in an area of Db2 that is critical for
performance. As such, it is primarily intended as a mechanism to capture log data
for recovery purposes. In addition, the log capture exit routine operates in a very
restrictive z/OS environment, which severely limits its capabilities as a stand-alone
routine.

Procedure

To capture log records with the log capture exit routine:

You must write an exit routine (or use the one that is provided by the preceding
program offering) that can be loaded and called under the various processing
conditions and restrictions that are required by this exit routine. PSPI

Related concepts:
Contents of the log
Log capture routines
Related tasks:
Reading log records with IFI
Related reference:
The physical structure of the log

| How RBA and LRSN values are displayed

| In all migration modes, RBA and LRSN values are displayed in 10-byte. This
| 10-byte display is unrelated to migration of the catalog or directory, conversion of
| individual objects to EXTENDED format, or BSDS conversion. For recovery
| purposes, this 10-byte format is the preferred input format for Db2. When 10-byte
| RBA or LRSN values are specified as input to Db2, conversion to 6-byte format is
| performed internally as needed.

| Differences between the 6-byte and 10-byte formats

| The terms “basic” and “extended” are sometimes used to refer to the 6-byte and
| 10-byte formats. When these terms are used, basic format refers to the 6-byte format,
| and extended format refers to the extended 10-byte format.
| Conversion of RBA values
| A 6-byte RBA value is converted to the 10-byte format value by adding
| zeros to the 4 most significant bytes. That is, the zeros are added to the left
| side of the value, as shown in the following table.
|| 6-byte RBA value: 10-byte RBA value:
| 112233445566 00000000112233445566
|

Chapter 14. Reading log records 679

| Conversion LRSN values
| A 6-byte LRSN value is converted to a 10-byte value by adding one zero
| byte to the left side and 3 bytes added to the right side of the value, as
| shown in the following table.
|| 6-byte LRSN value: 10-byte LRSN value:
| 112233445566 00112233445566000000
|
| The three bytes on the right side might be might be zero or x'FF',
| depending on the situation. For the beginning of an LRSN range, zeros are
| used. For the end of an LRSN range, x'FF' is used.

| Internally, the values that are kept in memory are all 10 bytes, except when they
| need to be externalized to structures that remain in the 6-byte format. The values
| are stored internally as 10 bytes even in conversion mode. The conversion from the
| 10-byte values to 6-byte format is done at end points, such as when a log record is
| written, or when the PGLOGRBA field in a data or index page is updated.

| Even before the BSDS is converted to Db2 11 format on all data sharing members,
| 10-byte LRSN values might be displayed with non-zero digits in the low order 3
| bytes. LRSN values captured before the BSDS is converted continue to be
| displayed as they were saved until they are no longer available for display (for
| example, deleted by MODIFY RECOVERY). This behavior is normal and to be
| expected, given the many ways LRSN values are generated, stored, and handled in
| Db2. If these LRSN values are specified as input to Db2, specify them as shown. If
| the LRSN value contains non-zero digits in the low order 3 bytes, do not remove
| them. Any conversion that might be required takes place inside Db2.
| Related concepts:
| Expanded RBA and LRSN log records (Db2 for z/OS What's New?)
| The extended 10-byte RBA and LRSN in Db2 11 (Db2 for z/OS What's New?)
| Related tasks:
| What to do before RBA or LRSN limits are reached

680 Administration Guide

Part 3. Appendixes

© Copyright IBM Corp. 1982, 2017 681

682 Administration Guide
Appendix A. Exit routines
Db2 provides installation-wide exit points to the routines that you provide. These
exit routines are described in the following sections:
v Edit procedures
v Validation routines
v Date and time routines
v Conversion procedures
v Field procedures
v Log capture routines
v Routines for dynamic plan selection in CICS.
Related information:
Managing access through exit routines (Managing Security)

Edit procedures
An edit procedure is assigned to a table by the EDITPROC clause of the CREATE
TABLE statement. An edit procedure receives the entire row of a base table in
internal Db2 format. It can transform the row when it is stored by an INSERT or
UPDATE SQL statement or by the LOAD utility.

PSPI

An edit procedure can be defined as WITH ROW ATTRIBUTES or WITHOUT

ROW ATTRIBUTES in a CREATE TABLE statement. An edit procedure that is
defined as WITH ROW ATTRIBUTES uses information about the description of the
rows in the associated table. You cannot define an edit routine as WITH ROW
ATTRIBUTES on a table that has the following characteristics:
v The table contains a LOB, ROWID, or XML column.
v The table contains an identity column.
v The table contains a security label column.
v The table contains a column name that is longer than 18 EBCDIC bytes.

You cannot define an edit procedure as WITHOUT ROW ATTRIBUTES on a table

that has LOB columns.

The transformation your edit procedure performs on a row (possibly encryption or

compression) is called edit-encoding. The same routine is used to undo the
transformation when rows are retrieved; that operation is called edit-decoding.

The edit-decoding function must be the exact inverse of the edit-encoding function.
For example, if a routine encodes 'ALABAMA' to '01', it must decode '01' to
'ALABAMA'. A violation of this rule can lead to an abend of the Db2 connecting
thread, or other undesirable effects.

Your edit procedure can encode the entire row of the table, including any index
keys. However, index keys are extracted from the row before the encoding is done,

© Copyright IBM Corp. 1982, 2017 683

 therefore, index keys are stored in the index in edit-decoded form. Hence, for a table
with an edit procedure, index keys in the table are edit-coded; index keys in the
index are not edit-coded.

The sample application contains a sample edit procedure, DSN8EAE1. To print it,
use ISPF facilities, IEBPTPCH, or a program of your own. Or, assemble it and use
the assembly listing.

There is also a sample routine that does Huffman data compression, DSN8HUFF in
library prefix.SDSNSAMP. That routine not only exemplifies the use of the exit
parameters, it also has potentially some use for data compression. If you intend to
use the routine in any production application, please pay particular attention to the
warnings and restrictions given as comments in the code. You might prefer to let
Db2 compress your data.

PSPI

Related concepts:
General guidelines for writing exit routines

Specifying edit procedures

If you plan to use an edit procedure, you can specify it when you create the table.
However, you cannot add an edit procedure to an existing table, or alter a table
with an edit procedure to add a column; you must drop and re-create the table.

Procedure

PSPI

To specify an edit procedure for a table:

Specify the EDITPROC clause of the CREATE TABLE statement, followed by the
name of the procedure. The procedure is loaded on demand during operation. You
can specify the EDITPROC clause on a table that is activated with row and column
access control. The rows of the table are passed to these procedures if your security
administrator determines that these procedures are allowed to access sensitive
data.

PSPI

When edit routines are taken

An edit routine is invoked to edit-encode a row whenever an SQL statement or
LOAD utility job inserts or updates the row.

PSPI

An edit routine is invoked after any date routine, time routine, or field procedure.
If there is also a validation routine, the edit routine is invoked after the validation
routine. Any changes made to the row by the edit routine do not change entries
made in an index.

The same edit routine is invoked to edit-decode a row whenever Db2 retrieves one.
On retrieval, it is invoked before any date routine, time routine, or field procedure.
If retrieved rows are sorted, the edit routine is invoked before the sort. An edit

684 Administration Guide

 routine is not invoked for a DELETE operation without a WHERE clause that
deletes an entire table in a segmented table space.

PSPI

Parameter list for edit procedures

The parameter list for edit procedures contains pointers to other information,
including the authorization ID list.

PSPI

At invocation, registers are set, and the edit procedure uses the standard exit
parameter list (EXPL). The following table shows the exit-specific parameter list, as
described by macro DSNDEDIT.
Table 64. Parameter list for an edit procedure
Name Hex offset Data type Description
EDITCODE 0 Signed 4-byte Edit code telling the type of function to be
integer performed, as follows:
0 Edit-encode row for insert or
update
4 Edit-decode row for retrieval
EDITROW 4 Address Address of a row description. The value of
this parameter is 0 (zero) if both of the
following conditions are true:
v The edit procedure is insensitive to the
format in which Db2 stores the rows of
the table.
v The edit procedure is defined as
WITHOUT ROW ATTRIBUTES in
CREATE TABLE statements.
8 Signed 4-byte Reserved
integer
EDITILTH C Signed 4-byte Length of the input row
integer
EDITIPTR 10 Address Address of the input row
EDITOLTH 14 Signed 4-byte Length of output row. On entry, this is the
integer size of the area in which to place the output
row. The exit must not modify storage
beyond this length.
EDITOPTR 18 Address Address of the output row

PSPI

Incomplete rows and edit routines

Db2 passes input rows to an edit routine. If an input row has fewer fields than the
number of columns in the table, the edit routine must stop processing the row after
the last input field.

Appendix A. Exit routines 685

 PSPI

Columns for which no input field is provided and that are not in reordered row
format are always at the end of the row and are never defined as NOT NULL. In
this case, the columns allow nulls, they are defined as NOT NULL WITH
DEFAULT, or the columns are ROWID or DOCID columns.

Use macro DSNDEDIT to get the starting address and row length for edit exits.
Add the row length to the starting address to get the first invalid address beyond
the end of the input buffer; your routine must not process any address as large as
that.

The following diagram shows how the parameter list points to other row
information. The address of the nth column description is given by: RFMTAFLD +
(n-1)*(FFMTE-FFMT).

Register 1 EXPL
Address of
EXPL Address of
work area Work area
Address of (256 bytes)
edit parameter Length of
list work area
Reserved

Return code
Parameter list
Reason code
EDITCODE: Function to be
performed
Row descriptions
Address of row description
Number of columns
Reserved in row (n)
Length of input row Address of column
list
Address of input row
Row type
Length of output row

Address of output row Column descriptions

Output row Column length

Data type
...n
Input row Data attribute
Column name

Figure 67. How the edit exit parameter list points to row information

PSPI

Expected output for edit routines

The edit routines return different output depending on whether the input row is in
the coded or decoded form.

686 Administration Guide

 PSPI

If EDITCODE contains 0, the input row is in decoded form. Your routine must
encode it.
In that case, the maximum length of the output area, in EDITOLTH, is 10 bytes
more than the maximum length of the record. In counting the maximum length
for a row in basic row format, “record” includes fields for the lengths of
varying-length columns and for null indicators. In counting the maximum
length for a row in reordered row format, “record” includes fields for the
offsets to the varying length columns and for null indicators. The maximum
length of the record does not include the 6-byte record header.

If EDITCODE contains 4, the input row is in coded form. Your routine must
decode it.
In that case, EDITOLTH contains the maximum length of the record. In
counting the maximum length for a row in basic row format, “record” includes
fields for the lengths of varying length columns and for null indicators. In
counting the maximum length for a row in reordered row format, “record”
includes fields for the offsets to the varying-length columns and for null
indicators. The maximum length of the record does not include the 6-byte
record header.

In either case, put the result in the output area, pointed to by EDITOPTR, and put
the length of your result in EDITOLTH. The length of your result must not be
greater than the length of the output area, as given in EDITOLTH on invocation,
and your routine must not modify storage beyond the end of the output area.

Required return code: Your routine must also leave a return code in EXPLRC1 with
the following meanings:
Table 65. Required return code in EXPLRC1
Value Meaning
0 Function performed successfully.
Nonzero Function failed.

If the function fails, the routine might also leave a reason code in EXPLRC2. Db2
returns SQLCODE -652 (SQLSTATE '23506') to the application program and puts
the reason code in field SQLERRD(6) of the SQL communication area (SQLCA).

PSPI

Validation routines
Validation routines are assigned to a table by the VALIDPROC clause of the
CREATE TABLE and ALTER TABLE statement. A validation routine receives an
entire row of a base table as input. The routine can return an indication of whether
to allow a subsequent INSERT, UPDATE, DELETE, FETCH, or SELECT operation.

PSPI

Typically, a validation routine is used to impose limits on the information that can
be entered in a table; for example, allowable salary ranges, perhaps dependent on
job category, for the employee sample table.

Appendix A. Exit routines 687

 Although VALIDPROCs can be specified for a table that contains a LOB or XML
column, the LOB or XML values are not passed to the validation routine. The LOB
indicator column takes the place of the LOB column, and the XML indicator
column takes the place of the XML column. You cannot use VALIDPROC on a
table if the table contains a column name that is longer than 18 EBCDIC bytes.

The return code from a validation routine is checked for a 0 value before any
insert, update, or delete is allowed.

PSPI

Related concepts:
General guidelines for writing exit routines

Specifying validation routines

When you specify a validation routine for a table, the routine is loaded on demand
during operation.

About this task

You can add a validation routine to an existing table, but the routine is not
invoked to validate data that was already in the table.

Procedure

PSPI

To specify a validation routine for a table:

Issue the CREATE TABLE or ALTER TABLE statement with the VALIDPROC
clause.
You can specify the VALIDPROC clause on a table that is activated with row and
column access control. The rows of the table are passed to these routines if your
security administrator determines that these routines are allowed to access
sensitive data.
You can cancel a validation routine for a table by specifying the VALIDPROC
NULL clause in an ALTER TABLE statement.

PSPI

When validation routines are taken

A validation routine for a table is invoked when Db2 inserts or updates a row,
even for inserts that the LOAD utility makes.

PSPI

The routine is invoked for most delete operations, including a mass delete of all
the rows of a table. If there are other exit routines, the validation routine is
invoked before any edit routine, and after any date routine, time routine, or field
procedure.

PSPI

688 Administration Guide

Parameter list for validation routines
At invocation, registers are set, and the validation routine uses the standard exit
parameter list (EXPL).

PSPI

The following diagram shows how the parameter list points to other information.

Register 1 EXPL
Address of
EXPL Address of
work area Work area
(256 bytes)
Address of
Length of
validation
work area
parameter list
Reserved

Return code
Parameter list
Reason code
Reserved
Address of row description Row descriptions
Reserved Number of columns
in row (n)
Length of input row to be
validated Address of column
list
Address of input row to be
validated Row type
.
. Column descriptions
.

Column length
Data type ...n
Input row
Data attribute
Column name

Figure 68. How a validation parameter list points to information. The address of the nth
column description is given by: RFMTAFLD + (n-1)*(FFMTE-FFMT).

The following table shows the exit-specific parameter list, described by macro
DSNDRVAL.
Table 66. Parameter list for a validation routine
Name Hex offset Data type Description
0 Signed 4-byte Reserved
integer
RVALROW 4 Address Address of a row description.
8 Signed 4-byte Reserved
integer
RVALROWL C Signed 4-byte Length of the input row to be validated
integer

Appendix A. Exit routines 689

 Table 66. Parameter list for a validation routine (continued)
Name Hex offset Data type Description
RVALROWP 10 Address Address of the input row to be validated
14 Signed 4-byte Reserved
integer
18 Signed 4-byte Reserved
integer
RVALPLAN 1C Character, 8 Name of the plan issuing the request
bytes
RVALOPER 24 Unsigned 1-byte Code identifying the operation being
integer performed, as follows:
1 Insert, update, or load
2 Delete
RVALFL1 25 Character, 1 byte The high-order bit is on if the requester has
installation SYSADM authority. The
remaining 7 bits are reserved.
RVALCSTC 26 Character, 2 Connection system type code. Values are
bytes defined in macro DSNDCSTC.

PSPI

Incomplete rows and validation routines

Db2 passes input rows to a validation routine. If an input row has fewer fields
than the number of columns in the table, the routine must stop processing the row
after the last input field.

PSPI

Columns for which no input field is provided and that are not in reordered row
format are always at the end of the row and are never defined as NOT NULL. In
this case, the columns allow nulls, they are defined as NOT NULL WITH
DEFAULT, or the columns are ROWID or DOCID columns.

Use macro DSNDRVAL to get the starting address and row length for validation
exits. Add the row length to the starting address to get the first invalid address
beyond the end of the input buffer; your routine must not process any address as
large as that.

PSPI

Expected output for validation routines

The validation routines must leave a return code in EXPLRC1.

PSPI

The return code in EXPLRC1 has one of the following meanings:

690 Administration Guide

 Table 67. Required return code in EXPLRC1
Value Meaning
0 Allow insert, update, or delete
Nonzero Do not allow insert, update, or delete

If the operation is not allowed, the routine might also leave a reason code in
EXPLRC2. Db2 returns SQLCODE -652 (SQLSTATE '23506') to the application
program and puts the reason code in field SQLERRD(6) of the SQL communication
area (SQLCA).

PSPI

Date and time routines

A date routine is a user-written exit routine to change date values from a locally
defined format to a format that is recognized by Db2 and from the ISO format to
the locally defined format. Similarly, a time routine changes time values from a
locally defined format to one that is recognized by Db2and from the ISO format to
the locally-defined format.

PSPI

The following is a list of the formats recognized by Db2.

Table 68. Date and time formats
Format name Abbreviation Typical date Typical time
IBM European standard EUR 25.12.2004 13.30.05
International Standards Organization ISO 2004-12-25 13.30.05
Japanese Industrial Standard Christian JIS 2004-12-25 13:30:05
Era
IBM USA standard USA 12/25/2004 1:30 PM

Example: Suppose that you want to insert and retrieve dates in a format like
“September 21, 2006”. You can use a date routine that transforms the date to a
format that is recognized by Db2 on insertion, such as ISO: “2006-09-21”. On
retrieval, the routine can transform “2006-09-21” to “September 21, 2006”.

You can have either a date routine, a time routine, or both. These routines do not
apply to timestamps. Special rules apply if you execute queries at a remote DBMS,
through the distributed data facility.

PSPI

Related concepts:
General guidelines for writing exit routines

Specifying date and time routines

During Db2 installation, you can establish a date routine or time routine.

Appendix A. Exit routines 691

 Procedure

PSPI
To specify date and time routines:
1. Set LOCAL DATE LENGTH or LOCAL TIME LENGTH to the length of the
longest field that is required to hold a date or time in your local format.
Allowable values range from 10 to 254. For example, if you intend to insert and
retrieve dates in the form “September 21, 2006”, you need an 18-byte field. You
would set LOCAL DATE LENGTH to 18.
2. Replace all of the IBM-supplied exit routines. Use CSECTs DSNXVDTX,
DSNXVDTA, and DSNXVDTU for a date routine, and DSNXVTMX,
DSNXVTMA, and DSNXVTMU for a time routine. The routines are loaded
when Db2 starts.
3. To make the local date or time format the default for retrieval, set DATE
FORMAT or TIME FORMAT to LOCAL when installing Db2.
This specification has the effect that Db2 always takes the exit routine when you
retrieve from a DATE or TIME column. For example, suppose that you want to
retrieve dates in your local format only occasionally; most of the time you use
the USA format. You would set DATE FORMAT to USA.

What to do next

The installation parameters for LOCAL DATE LENGTH, LOCAL TIME LENGTH,
DATE FORMAT, and TIME FORMAT can also be updated after Db2 is installed. If
you change a length parameter, you might need to rebind the applications.

PSPI

When date and time routines are taken

A date or time routine is invoked to change a value from the locally defined
format to a format that is recognized by Db2.

A date or time routine is invoked in the following circumstances:

v

PSPI

When a date or time value is entered by an INSERT or UPDATE statement, or

by the LOAD utility
v When a constant or host variable is compared to a column with a data type of
DATE, TIME, or TIMESTAMP
v When the DATE or TIME scalar function is used with a string representation of
a date or time in LOCAL format
v When a date or time value is supplied for a limit of a partitioned index in a
CREATE INDEX statement

The exit is taken before any edit or validation routine.

v If the default is LOCAL, Db2 takes the exit immediately. If the exit routine does
not recognize the data (EXPLRC1=8), Db2 then tries to interpret it as a date or
time in one of the recognized formats (EUR, ISO JIS, or USA). Db2 rejects the
data only if that interpretation also fails.

692 Administration Guide

 v If the default is not LOCAL, Db2 first tries to interpret the data as a date or time
in one of the recognized formats. If that interpretation fails, Db2 then takes the
exit routine, if it exists.

Db2 checks that the value supplied by the exit routine represents a valid date or
time in some recognized format, and then converts it into an internal format for
storage or comparison. If the value is entered into a column that is a key column
in an index, the index entry is also made in the internal format.

On retrieval, a date or time routine can be invoked to change a value from ISO to
the locally-defined format when a date or time value is retrieved by a SELECT or
FETCH statement. If LOCAL is the default, the routine is always invoked unless
overridden by a precompiler option or by the CHAR function, as by specifying
CHAR(HIREDATE, ISO); that specification always retrieves a date in ISO format. If
LOCAL is not the default, the routine is invoked only when specifically called for
by CHAR, as in CHAR(HIREDATE, LOCAL); that always retrieves a date in the
format supplied by your date exit routine.

On retrieval, the exit is invoked after any edit routine or Db2 sort. A date or time
routine is not invoked for a DELETE operation without a WHERE clause that
deletes an entire table in a segmented table space.

PSPI

Parameter list for date and time routines

At invocation, registers are set, and the date or time routine uses the standard exit
parameter list (EXPL).

PSPI

The following diagram shows how the parameter list points to other information.

Register 1
EXPL
Address of
EXPL Address of
work area Work area
Address of (512 bytes)
parameter Length of
list work area
Return code
Parameter list
Address of function code
Function code:
Address of format length Function to be
performed
Address of LOCAL value

Address of ISO value

Length of local
format
ISO value

LOCAL value

Figure 69. How a date or time parameter list points to other information

Appendix A. Exit routines 693

 The following list shows the exit-specific parameters, described by macro
DSNDDTXP.
Table 69. Parameter list for a date or time routine
Name Hex offset Data type Description
DTXPFN 0 Address Address of a 2-byte integer containing a
function code. The codes and their
meanings are:
4 Convert from local format to ISO.
8 Convert from ISO to local format.
DTXPLN 4 Address Address of a 2-byte integer containing the
length in bytes of the local format. This is
the length given as LOCAL DATE
LENGTH or LOCAL TIME LENGTH when
installing Db2.
DTXPLOC 8 Address Address of the date or time value in local
format
DTXPISO C Address Address of the date or time value in ISO
format (DTXPISO). The area pointed to is
10 bytes long for a date, 8 bytes for a time.

PSPI

Expected output for date and time routines

The date and time routines return different output depending on the format of the
input value.

PSPI

If the function code is 4, the input value is in local format, in the area pointed to
by DTXPLOC. Your routine must change it to ISO, and put the result in the area
pointed to by DTXPISO.

If the function code is 8, the input value is in ISO, in the area pointed to by
DTXPISO. Your routine must change it to your local format, and put the result in
the area pointed to by DTXPLOC.

Your routine must also leave a return code in EXPLRC1, a 4-byte integer and the
third word of the EXPL area. The return code can have the following meanings:
Table 70. Required return code in EXPLRC1
Value Meaning
0 No errors; conversion was completed.
4 Invalid date or time value.
8 Input value not in valid format; if the function is insertion, and LOCAL
is the default, Db2 next tries to interpret the data as a date or time in one
of the recognized formats (EUR, ISO, JIS, or USA).
12 Error in exit routine.

694 Administration Guide

 PSPI

Conversion procedures
A conversion procedure is a user-written exit routine that converts characters from
one coded character set to another coded character set.

PSPI

In most cases, any conversion that is needed can be done by routines provided by
IBM. The exit for a user-written routine is available to handle exceptions.

PSPI

Related concepts:
General guidelines for writing exit routines

Specifying conversion procedures

You can specify a conversion procedure that converts characters from one coded
character set to another coded character set.

About this task

Procedure

To specify a conversion procedure:

Insert a row into the SYSIBM.SYSSTRINGS catalog table.

PSPI

The row must contain values for the following columns:

INCCSID
The coded character set identifier (CCSID) of the source string.
OUTCCSID
The CCSID of the converted string.
TRANSTYPE
The nature of the conversion. Values can be:
GG ASCII GRAPHIC to EBCDIC GRAPHIC
MM EBCDIC MIXED to EBCDIC MIXED
MP EBCDIC MIXED to ASCII MIXED
MS EBCDIC MIXED to EBCDIC SBCS
PM ASCII MIXED to EBCDIC MIXED
PP ASCII MIXED to ASCII MIXED
PS ASCII MIXED to EBCDIC SBCS
SM EBCDIC SBCS to EBCDIC MIXED
SP SBCS (ASCII or EBCDIC) to ASCII MIXED
SS EBCDIC SBCS to EBCDIC SBCS
TRANSPROC
The name of your conversion procedure.
IBMREQD
Must be N.

Appendix A. Exit routines 695

 Db2 does not use the following columns, but checks them for the allowable values
listed. Values you insert can be used by your routine in any way. If you insert no
value in one of these columns, Db2 inserts the default value listed.
ERRORBYTE
Any character, or null. The default is null.
SUBBYTE
Any character not equal to the value of ERRORBYTE, or null. The default
is null.
TRANSTAB
Any character string of length 256 or the empty string. The default is an
empty string.

PSPI

When conversion procedures are taken

A conversion procedure is invoked when it is required to convert the coded
character set that is identified by INCCSID to one that is identified by OUTCCSID.

Parameter list for conversion procedures

At invocation, registers are set, and the conversion procedure uses the standard
exit parameter list (EXPL).

PSPI

A conversion procedure does not use an exit-specific parameter list. Instead, the
area pointed to by register 1 at invocation includes three words, which contain the
addresses of the following items:
1. The EXPL parameter list
2. A string value descriptor that contains the character string to be converted
3. A copy of a row from SYSIBM.SYSSTRINGS that names the conversion
procedure identified in TRANSPROC.

The length of the work area pointed to by the exit parameter list is generally 512
bytes. However, if the string to be converted is ASCII MIXED data (the value of
TRANSTYPE in the row from SYSSTRINGS is PM or PS), then the length of the
work area is 256 bytes, plus the length attribute of the string.

The string value descriptor: The descriptor has the following formats:
Table 71. Format of string value descriptor for a conversion procedure
Name Hex offset Data type Description
FPVDTYPE 0 Signed 2-byte Data type of the value:
integer
Code Means
20 VARCHAR
28 VARGRAPHIC
FPVDVLEN 2 Signed 2-byte The maximum length of the string
integer
FPVDVALE 4 None The string. The first halfword is the string's
actual length in characters. If the string is
ASCII MIXED data, it is padded out to the
maximum length by undefined bytes.

696 Administration Guide

 The row from SYSSTRINGS: The row copied from the catalog table
SYSIBM.SYSSTRINGS is in the standard Db2 row format. The fields ERRORBYTE
and SUBBYTE each include a null indicator. The field TRANSTAB is of varying
length and begins with a 2-byte length field.

PSPI

Expected output for conversion procedures

Except in the case of certain errors, your conversion procedure should replace the
string in FPVDVALE with the converted string.

PSPI

When converting MIXED data, your procedure must ensure that the result is
well-formed. In any conversion, if you change the length of the string, you must
set the length control field in FPVDVALE to the proper value. Over-writing storage
beyond the maximum length of the FPVDVALE causes an abend.

Your procedure must also set a return code in field EXPLRC1 of the exit parameter
list.

The following is a list of the codes for the converted string in FPVDVALE:
Table 72. Codes for the converted string in FPVDVALE
Code Meaning
0 Successful conversion
4 Conversion with substitution

For the following remaining codes, Db2 does not use the converted string:
Table 73. Remaining codes for the FPVDVALE
Code Meaning
8 Length exception
12 Invalid code point
16 Form exception
20 Any other error
24 Invalid CCSID

Exception conditions: Return a length exception (code 8) when the converted

string is longer than the maximum length allowed.

For an invalid code point (code 12), place the 1- or 2-byte code point in field
EXPLRC2 of the exit parameter list.

Return a form exception (code 16) for EBCDIC MIXED data when the source string
does not conform to the rules for MIXED data.

Any other uses of codes 8 and 16, or of EXPLRC2, are optional.

Appendix A. Exit routines 697

 Error conditions: On return, Db2 considers any of the following conditions as a
“conversion error”:
v EXPLRC1 is greater than 16.
v EXPLRC1 is 8, 12, or 16 and the operation that required the conversion is not an
assignment of a value to a host variable with an indicator variable.
v FPVDTYPE or FPVDVLEN has been changed.
v The length control field of FPVDVALE is greater than the original value of
FPVDVLEN or is negative.

In the case of a conversion error, Db2 sets the SQLERRMC field of the SQLCA to
HEX(EXPLRC1) CONCAT X'FF' CONCAT HEX(EXPLRC2).

The following diagram shows how the parameter list points to other information.

Register 1
Address of EXPL
EXPL Address of
Work area
Address of work area
string value
list Length of
work area
Address of
SYSSTRINGS Reserved
row copy
Return code
Invalid code
String value descriptor
Data type of string
Copy of row from
Maximum string length
SYSIBM.SYSSTRINGS
String length
String value

Figure 70. Pointers at entry to a conversion procedure

PSPI

Field procedures
A field procedure is a user-written exit routine that is used to transform values in a
single, short string column. You can assign field procedures to a table by specifying
the FIELDPROC clause of the CREATE TABLE or ALTER TABLE statement.

PSPI

When values in the column are changed, or new values inserted, the field
procedure is invoked for each value, and can transform that value (encode it) in
any way. The encoded value is then stored. When values are retrieved from the
column, the field procedure is invoked for each value, which is encoded, and must
decode it back to the original string value.

Any indexes, including partitioned indexes, defined on a column that uses a field
procedure are built with encoded values. For a partitioned index, the encoded
value of the limit key is put into the LIMITKEY column of the SYSINDEXPART
698 Administration Guide
 table. Hence, a field procedure might be used to alter the sorting sequence of
values entered in a column. For example, telephone directories sometimes require
that names like “McCabe” and “MacCabe” appear next to each other, an effect that
the standard EBCDIC sorting sequence does not provide. And languages that do
not use the Roman alphabet have similar requirements. However, if a column is
provided with a suitable field procedure, it can be correctly ordered by ORDER BY.

The transformation your field procedure performs on a value is called

field-encoding. The same routine is used to undo the transformation when values
are retrieved; that operation is called field-decoding. Values in columns with a field
procedure are described to Db2 in two ways:
1. The description of the column as defined in CREATE TABLE or ALTER TABLE
appears in the catalog table SYSIBM.SYSCOLUMNS. That is the description of
the field-decoded value, and is called the column description.
2. The description of the encoded value, as it is stored in the data base, appears in
the catalog table SYSIBM.SYSFIELDS. That is the description of the
field-encoded value, and is called the field description.

Important: The field-decoding function must be the exact inverse of the

field-encoding function. For example, if a routine encodes 'ALABAMA' to '01', it
must decode '01' to 'ALABAMA'. A violation of this rule can lead to an abend of
the Db2 connecting thread, or other undesirable effects.

PSPI

Related concepts:
General guidelines for writing exit routines

Field-definition for field procedures

A field procedure is invoked when a table is created or altered to define the data
type and attributes of an encoded value to Db2. This operation is called
field-definition.

PSPI

The data type of the encoded value can be any valid SQL data type except DATE,
TIME, TIMESTAMP, LONG VARCHAR, or LONG VARGRAPHIC. The length,
precision, or scale of the encoded value must be compatible with its data type.

A user-defined data type can be a valid field if the source type of the data type is a
short string column that has a null default value. Db2 casts the value of the
column to the source type before it passes it to the field procedure.

PSPI

Related reference:
Value descriptor for field procedures

Specifying field procedures

To transform values in single, short string columns, you can assign field
procedures to the columns. If you plan to use a field procedure, specify it when
you create the table. In operation, the procedure is loaded on demand.

Appendix A. Exit routines 699

 About this task

PSPI

Restriction: Consider the following restrictions:

v You cannot use a field procedure on a column that was defined by using the
NOT NULL WITH DEFAULT clause.
v You cannot add a field procedure to an existing column of a table. However, you
can use the ALTER TABLE statement to add a new column that uses a field
procedure to an existing table.
v You cannot use a field procedure on a LOB, ROWID, or ROW CHANGE
TIMESTAMP column of a table. However, you can specify it for other columns
in the same table.
v You cannot use a field procedure on a column if the column name is longer than
18 EBCDIC bytes.

Procedure

To specify a field procedure for a column:

Issue the CREATE TABLE or ALTER TABLE statement with the FIELDPROC
clause.
The optional parameter list that follows the procedure name is a list of constants,
enclosed in parentheses, called the literal list. The literal list is converted by Db2
into a data structure called the field procedure parameter value list (FPPVL). That
structure is passed to the field procedure during the field-definition operation. At
that time, the procedure can modify it or return it unchanged. The output form of
the FPPVL is called the modified FPPVL. The modified FPPVL is stored in the Db2
catalog as part of the field description. The modified FPPVL is passed again to the
field procedure whenever that procedure is invoked for field-encoding or
field-decoding.

PSPI

When field procedures are taken

A field procedure that is specified for a column is invoked in certain conditions.

A field procedure is invoked generally in three conditions:

v

PSPI

For field-definition, when the CREATE TABLE or ALTER TABLE statement that
names the procedure is executed. During this invocation, the procedure is
expected to:
– Determine whether the data type and attributes of the column are valid.
– Verify the literal list, and change it if wanted.
– Provide the field description of the column.
– Define the amount of working storage needed by the field-encoding and
field-decoding processes.
v For field-encoding, when a column value is to be field-encoded. That occurs for
any value that:

700 Administration Guide

 – Is inserted in the column by an SQL INSERT statement, or loaded by the Db2
LOAD utility.
– Is changed by an SQL UPDATE statement.
– Is compared to a column with a field procedure, unless the comparison
operator is LIKE. The value being encoded is a host variable or constant.
(When the comparison operator is LIKE, the column value is decoded.)
– Defines the limit of a partition of an index. The value being encoded follows
ENDING AT in the PARTITION clause of CREATE INDEX.
If there are any other exit routines, the field procedure is invoked before any of
them.
v For field-decoding, when a stored value is to be field-decoded back into its
original string value. This occurs for any value that is:
– Retrieved by an SQL SELECT or FETCH statement, or by the unload phase of
the REORG utility.
– Compared to another value with the LIKE comparison operator. The value
being decoded is from the column that uses the field procedure.
In this case, the field procedure is invoked after any edit routine or Db2 sort.

A field procedure is never invoked to process a null value, nor for a DELETE
operation without a WHERE clause on a table in a segmented table space.

Recommendation: Avoid encoding blanks in a field procedure. When Db2

compares the values of two strings with different lengths, it temporarily pads the
shorter string with blanks (in EBCDIC or double-byte characters, as needed) up to
the length of the longer string. If the shorter string is the value of a column with a
field procedure, the padding is done to the encoded value, but the pad character is
not encoded. Therefore, if the procedure changes blanks to some other character,
encoded blanks at the end of the longer string are not equal to padded blanks at
the end of the shorter string. That situation can lead to errors; for example, some
strings that ought to be equal might not be recognized as such. Therefore,
encoding blanks in a field procedure is not recommended.

PSPI

Control blocks for execution of field procedures

Certain control blocks are used to communicate to a field procedure.

Parameter list (FPPL) for field procedures

The field procedure parameter list is pointed to by register 1 on entry to a field
procedure. It contains the addresses of five other areas.

PSPI

The following diagram shows those areas. The FPPL and the areas are described
by the mapping macro DSNDFPPB.

Appendix A. Exit routines 701

 FPPL Work area
Register 1
Work address

FPIB address
Field procedure
CVD address information
block (FPIB)
FVD address
FPPVL address
Column value
descriptor (CVD)

Field value
descriptor (FVD)

Field procedure
parameter value
list (FPPVL) or
literal list

Figure 71. Field procedure parameter list

PSPI

Work area for field procedures

The work area is a contiguous, uninitialized area of locally addressable, pageable,
swappable, and fetch-protected storage that is obtained in storage key 7 and
subpool 229.

PSPI

The work area can be used by a field procedure as working storage. A new area is
provided each time the procedure is invoked. The size of the area that you need
depends on the way you program your field-encoding and field-decoding
operations.

At field-definition time, Db2 allocates a 512-byte work area and passes the value of
512 bytes as the work area size to your routine for the field-definition operation. If
subsequent field-encoding and field-decoding operations need a work area of 512
bytes or less, your field definition doesn't need to change the value as provided by
Db2. If those operations need a work area larger than 512 bytes (i.e. 1024 bytes),
your field definition must change the work area size to the larger size and pass it
back to Db2 for allocation.

Whenever your field procedure is invoked for encoding or decoding operations,

Db2 allocates a work area based on the size (i.e. 1024 bytes) that was passed back
to it. Your field definition must not use a work area larger than what is allocated
by Db2, even though subsequent operations need the larger work area.

PSPI

702 Administration Guide

Information block (FPIB) for field procedures
The field procedure information block communicates general information to a field
procedure.

PSPI

The information block tells what operation is to be done, allows the field
procedure to signal errors, and gives the size of the work area. It has the following
formats:
Table 74. Format of FPIB, defined in copy macro DSNDFPPB
Name Hex offset Data type Description
FPBFCODE 0 Signed 2-byte Function code
integer
Code Means
0 Field-encoding
4 Field-decoding
8 Field-definition
FPBWKLN 2 Signed 2-byte Length of work area; the maximum is 32767
integer bytes.
FPBSORC 4 Signed 2-byte Reserved
integer
FPBRTNC 6 Character, 2 Return code set by field procedure
bytes
FPBRSNCD 8 Character, 4 Reason code set by field procedure
bytes
FPBTOKPT C Address Address of a 40-byte area, within the work
area or within the field procedure's static
area, containing an error message

PSPI

Parameter value list (FPPVL) for field procedures

The field procedure parameter value list communicates the literal list to the field
procedure during the field-definition process. The literal list is supplied in the
CREATE TABLE or ALTER TABLE statement.

PSPI

At that time, the field procedure can reformat the FPPVL; it is the reformatted
FPPVL that is stored in SYSIBM.SYSFIELDS and communicated to the field
procedure during field-encoding and field-decoding as the modified FPPVL.

The FPPVL has the following formats:

Table 75. Format of FPPVL, defined in copy macro DSNDFPPB
Name Hex offset Data type Description
FPPVLEN 0 Signed 2-byte Length in bytes of the area containing
integer FPPVCNT and FPPVVDS. At least 254 for
field-definition.

Appendix A. Exit routines 703

 Table 75. Format of FPPVL, defined in copy macro DSNDFPPB (continued)
Name Hex offset Data type Description
FPPVCNT 2 Signed 2-byte Number of value descriptors that follow,
integer equal to the number of parameters in the
FIELDPROC clause. Zero if no parameters
were listed.
FPPVVDS 4 Structure Each parameter in the FIELDPROC clause
has:
1. A signed 4-byte integer giving the
length of the following value descriptor,
which includes the lengths of
FPVDTYPE, FPVDVLEN, and
FPVDVALE.
2. A value descriptor

PSPI

Value descriptor for field procedures

A value descriptor describes the data type and other attributes of a value.

PSPI

Value descriptors are used with field procedures in these ways:

v During field-definition, they describe each constant in the field procedure
parameter value list (FPPVL). The set of these value descriptors is part of the
FPPVL control block.
v During field-encoding and field-decoding, the decoded (column) value and the
encoded (field) value are described by the column value descriptor (CVD) and
the field value descriptor (FVD).

The column value descriptor (CVD) contains a description of a column value and, if
appropriate, the value itself. During field-encoding, the CVD describes the value to
be encoded. During field-decoding, it describes the decoded value to be supplied
by the field procedure. During field-definition, it describes the column as defined
in the CREATE TABLE or ALTER TABLE statement.

The field value descriptor (FVD) contains a description of a field value and, if
appropriate, the value itself. During field-encoding, the FVD describes the encoded
value to be supplied by the field procedure. During field-decoding, it describes the
value to be decoded. Field-definition must put into the FVD a description of the
encoded value.

Value descriptors have the following formats:

704 Administration Guide

 Table 76. Format of value descriptors
Name Hex offset Data type Description
FPVDTYPE 0 Signed 2-byte Data type of the value:
integer
Code Means
0 INTEGER
4 SMALLINT
8 FLOAT
12 DECIMAL
16 CHAR
20 VARCHAR
24 GRAPHIC
28 VARGRAPHIC
FPVDVLEN 2 Signed 2-byte v For a varying-length string value, its
integer maximum length
v For a decimal number value, its precision
(byte 1) and scale (byte 2)
v For any other value, its length
FPVDVALE 4 None The value. The value is in external format,
not Db2 internal format. If the value is a
varying-length string, the first halfword is
the value's actual length in bytes. This field
is not present in a CVD, or in an FVD used
as input to the field-definition operation.
An empty varying-length string has a
length of zero with no data following.

PSPI

Related reference:
Field-definition for field procedures

Field-definition (function code 8)

You need to provide the input and output that are required for a field-definition
operation.

On entry

The input that provided to the field-definition operation and the output that is
required are as follows:

PSPI

The registers have the following information:

Table 77. Contents of the registers on entry
Register Contains
1 Address of the field procedure parameter list (FPPL)
2 through 12 Unknown values that must be restored on exit.
13 Address of the register save area.
14 Return address.

Appendix A. Exit routines 705

 Table 77. Contents of the registers on entry (continued)
Register Contains
15 Address of entry point of exit routine.

The contents of all other registers, and of fields not listed in the following tables,
are unpredictable.

The work area consists of 512 contiguous uninitialized bytes.

The FPIB has the following information:

Table 78. Contents of the FPIB on entry
Field Contains
FPBFCODE 8, the function code
FPBWKLN 512, the length of the work area

The CVD has the following information:

Table 79. Contents of the CVD on entry
Field Contains
FPVDTYPE One of these codes for the data type of the column value:
Code Means
16 CHAR
20 VARCHAR
24 GRAPHIC
28 VARGRAPHIC
FPVDVLEN The length attribute of the column

The FPVDVALE field is omitted. The FVD provided is 4 bytes long. The FPPVL
field has the information:
Table 80. Contents of the FPPVL on entry
Field Contains
FPPVLEN The length, in bytes, of the area containing the parameter value list. The
minimum value is 254, even if there are no parameters.
FPPVCNT The number of value descriptors that follow; zero if there are no
parameters.
FPPVVDS A contiguous set of value descriptors, one for each parameter in the
parameter value list, each preceded by a 4-byte length field.

On exit

The registers must have the following information:

Table 81. Contents of the registers on exit
Register Contains
2 through 12 The values that they contained on entry.
15 The integer zero if the column described in the CVD is valid for the
field procedure; otherwise the value must not be zero.

706 Administration Guide

 The following fields must be set as shown; all other fields must remain as on entry.

The FPIB must have the following information:

Table 82. Contents of the FPIB on exit
Field Contains
FPBWKLN The length, in bytes, of the work area to be provided to the
field-encoding and field-decoding operations; 0 if no work area is
required.
FPBRTNC An optional 2-byte character return code, defined by the field procedure;
blanks if no return code is given.
FPBRSNC An optional 4-byte character reason code, defined by the field procedure;
blanks if no reason code is given.
FPBTOKP Optionally, the address of a 40-byte error message residing in the work
area or in the field procedure's static area; zeros if no message is given.

Errors signalled by a field procedure result in SQLCODE -681 (SQLSTATE '23507'),

which is set in the SQL communication area (SQLCA). The contents of FPBRTNC
and FPBRSNC, and the error message pointed to by FPBTOKP, are also placed into
the tokens, in SQLCA, as field SQLERRMT. The meaning of the error message is
determined by the field procedure.

The FVD must have the following information:

Table 83. Contents of the FVD on exit
Field Contains
FPVDTYPE The numeric code for the data type of the field value. Any of the data
types listed in Table 76 on page 705 is valid.
FPVDVLEN The length of the field value.

Field FPVDVALE must not be set; the length of the FVD is 4 bytes only.

The FPPVL can be redefined to suit the field procedure, and returned as the
modified FPPVL, subject to the following restrictions:
v The field procedure must not increase the length of the FPPVL.
v FPPVLEN must contain the actual length of the modified FPPVL, or 0 if no
parameter list is returned.
The modified FPPVL is recorded in the catalog table SYSIBM.SYSFIELDS, and is
passed again to the field procedure during field-encoding and field-decoding. The
modified FPPVL need not have the format of a field procedure parameter list, and
it need not describe constants by value descriptors.

PSPI

Field-encoding (function code 0)

You need to provide the input and output that are required for a field-encoding
operation.

Appendix A. Exit routines 707

 On entry

The input that is provided to the field-encoding operation, and the output that is
required, are as follows:

PSPI

The registers have the following information:

Table 84. Contents of the registers on entry
Register Contains
1 Address of the field procedure parameter list (FPPL); see Parameter
list (FPPL) for field procedures for a schematic diagram.
2 through 12 Unknown values that must be restored on exit.
13 Address of the register save area.
14 Return address.
15 Address of entry point of exit routine.

The contents of all other registers, and of fields not listed, are unpredictable.

The work area is contiguous, uninitialized, and of the length specified by the field
procedure during field-definition.

The FPIB has the following information:

Table 85. Contents of the FPIB on entry
Field Contains
FPBFCODE 0, the function code
FPBWKLN The length of the work area

The CVD has the following following information:

Table 86. Contents of the CVD on entry
Field Contains
FPVDTYPE The numeric code for the data type of the column value, as shown in
Table 76 on page 705.
FPVDVLEN The length of the column value.
FPVDVALE The column value; if the value is a varying-length string, the first
halfword contains its length.

The FVD has the following information:

Table 87. Contents of the FVD on entry
Field Contains
FPVDTYPE The numeric code for the data type of the field value.
FPVDVLEN The length of the field value.
FPVDVALE An area of unpredictable content that is as long as the field value.

708 Administration Guide

 The modified FPPVL, produced by the field procedure during field-definition, is
provided.

On exit

The registers have the following information:

Table 88. Contents of the registers on exit
Register Contains
2 through 12 The values that they contained on entry.
15 The integer zero if the column described in the CVD is valid for the
field procedure; otherwise the value must not be zero.

The FVD must contain the encoded (field) value in field FPVDVALE. If the value
is a varying-length string, the first halfword must contain its length.

The FPIB can have the following information:

Table 89. Contents of the FPIB on exit
Field Contains
FPBRTNC An optional 2-byte character return code, defined by the field procedure;
blanks if no return code is given.
FPBRSNC An optional 4-byte character reason code, defined by the field procedure;
blanks if no reason code is given.
FPBTOKP Optionally, the address of a 40-byte error message residing in the work
area or in the field procedure's static area; zeros if no message is given.

Errors signalled by a field procedure result in SQLCODE -681 (SQLSTATE '23507'),

which is set in the SQL communication area (SQLCA). The contents of FPBRTNC
and FPBRSNC, and the error message pointed to by FPBTOKP, are also placed into
the tokens, in SQLCA, as field SQLERRMT. The meaning of the error message is
determined by the field procedure.

All other fields must remain as on entry.

PSPI

Field-decoding (function code 4)

You need to provide the input and output that are required for a field-decoding
operation.

On entry

PSPI

The registers have the following information:

Table 90. Contents of the registers on entry
Register Contains
1 Address of the field procedure parameter list (FPPL); see Figure 71 on
page 702 for a schematic diagram.

Appendix A. Exit routines 709

 Table 90. Contents of the registers on entry (continued)
Register Contains
2 through 12 Unknown values that must be restored on exit.
13 Address of the register save area.
14 Return address.
15 Address of entry point of exit routine.

The contents of all other registers, and of fields not listed, are unpredictable.

The work area is contiguous, uninitialized, and of the length specified by the field
procedure during field-definition.

The FPIB has the following information:

Table 91. Contents of the FPIB on entry
Field Contains
FPBFCODE 4, the function code
FPBWKLN The length of the work area

The CVD has the following information:

Table 92. Contents of the CVD on entry
Field Contains
FPVDTYPE The numeric code for the data type of the column value, as shown in
Table 76 on page 705.
FPVDVLEN The length of the column value.
FPVDVALE The column value. If the value is a varying-length string, the first
halfword contains its length.

The FVD has the following information:

Table 93. Contents of the FVD on entry
Field Contains
FPVDTYPE The numeric code for the data type of the field value.
FPVDVLEN The length of the field value.
FPVDVALE The field value. If the value is a varying-length string, the first halfword
contains its length.

The modified FPPVL, produced by the field procedure during field-definition, is

provided.

On exit

The registers have the following information:

Table 94. Contents of the registers on exit
Register Contains
2 through 12 The values they contained on entry.

710 Administration Guide

 Table 94. Contents of the registers on exit (continued)
Register Contains
15 The integer zero if the column described in the FVD is valid for the
field procedure; otherwise the value must not be zero.

The CVD must contain the decoded (column) value in field FPVDVALE. If the
value is a varying-length string, the first halfword must contain its length.

The FPIB can have the following information:

Table 95. Contents of the FPIB on exit
Field Contains
FPBRTNC An optional 2-byte character return code, defined by the field procedure;
blanks if no return code is given.
FPBRSNC An optional 4-byte character reason code, defined by the field procedure;
blanks if no reason code is given.
FPBTOKP Optionally, the address of a 40-byte error message residing in the work
area or in the field procedure's static area; zeros if no message is given.

Errors signalled by a field procedure result in SQLCODE -681 (SQLSTATE '23507'),

which is set in the SQL communication area (SQLCA). The contents of FPBRTNC
and FPBRSNC, and the error message pointed to by FPBTOKP, are also placed into
the tokens, in SQLCA, as field SQLERRMT. The meaning of the error message is
determined by the field procedure.

All other fields must remain as on entry.

PSPI

Log capture routines

A log capture exit routine makes Db2 log data available for recovery purposes in
real time.

PSPI

The routine receives data when Db2 writes data to the active log. Your local
specifications determine what the routine does with that data. The routine does not
enter or return data to Db2.

Performance factor: Your log capture routine receives control often. Design it with
care: a poorly designed routine can seriously degrade system performance.
Whenever possible, use the instrumentation facility interface (IFI), rather than a log
capture exit routine, to read data from the log.

General guidelines for writing exit routines applies, but with the following
exceptions to the description of execution environments:
A log capture routine can execute in either TCB mode or SRB mode, depending
on the function it is performing. When in SRB mode, it must not perform any
I/O operations nor invoke any SVC services or ESTAE routines.

PSPI

Appendix A. Exit routines 711

 Specifying log capture routines
You can specify a log capture routine to receive data when Db2 writes data to the
active log.

About this task

The module name for the log capture routine is DSNJL004, and its entry point is
DSNJW117. The module is loaded during Db2 initialization and deleted during
Db2 termination.

Procedure

PSPI

To specify a log capture routine:

Link module DSNJL004 into either the prefix.SDSNEXIT or the Db2

prefix.SDSNLOAD library.
Specify the REPLACE parameter of the link-edit job to replace a module that is
part of the standard Db2 library for this release. The module should have
attributes AMODE(64) and RMODE(ANY).

PSPI

When log capture routines are invoked

The log capture exit routine is invoked in three situations. Each situation is
identified by a character in the parameter list of the routine.

PSPI In two of those situations, processing operates in TCB mode; in one

situation, processing operates in SRB mode. The two modes have different
processing capabilities, which your routine must be aware of. The character
identifications, situations, and modes are:
v I=Initialization, Mode=TCB
The TCB mode allows all z/OS DFSMSdfp functions to be used, including ENQ,
ALLOCATION, and OPEN. No buffer addresses are passed in this situation. The
routine runs in supervisor state, key 7, and enabled.
This is the only situation in which Db2 checks a return code from the user's log
capture exit routine. The Db2 subsystem is sensitive to a return code of X'20'
here. Never return X'20' in register 15 in this situation.
v W=Write, Mode=SRB (service request block)
The SRB mode restricts the exit routine's processing capabilities. No supervisor
call (SVC) instructions can be used, including ALLOCATION, OPEN, WTO, any
I/O instruction, and so on. At the exit point, Db2 is running in supervisor state,
key 7, and is enabled.
On entry, the exit routine has access to buffers that have log control intervals
with “blocked log records”. The first and last buffer address and control interval
size fields can be used to determine how many buffers are being passed.
Performance consideration: All processing time that is required by the exit
routine lengthens the time required to write the Db2 log. The Db2 address space
usually has a high priority, and all work done in it in SRB mode precedes all

712 Administration Guide

 TCB access. Any errors or long processing times can impact all Db2 processing
and cause system-wide performance problems. The performance of your routine
is extremely critical in this phase.
v T=Termination, Mode=TCB
Processing capabilities are the same as for initialization.

A log control interval can be passed more than once. Use the timestamp to
determine the last occurrence of the control interval. This last occurrence should
replace all others. The timestamp is found in the control interval. PSPI

Parameter list for log capture routines

At invocation, registers are set, and the log capture routine uses the standard exit
parameter list (EXPL). You can ignore the reason and return codes in that list.

PSPI

| The following is a list of the exit-specific parameters; it is mapped by macro

| DSNDLOGX. The parameter list contains two 64-bit pointers that point to the
| standard EXPL parameter list and to the log capture exit parameter list (LOGX).
| Table 96. Log capture routine specific parameter list
| Name Hex offset Data type Description
| LOGXEYE 00 Character, 4 Eye catcher: LOGX
| bytes
| LOGXLNG 04 Signed 2-byte Length of parameter list
| integer
| 06 Character, 10 Reserved
| bytes
| LOGXTYPE 10 Character, 1 byte Situation identifier:
| I Initialization
| W Write
| T Termination
| P Partial control interval (CI) call
| LOGXFLAG 11 Hex Mode identifier.
| X'00' SRB mode
| X'01' TCB mode
| 12 Character, 14 Reserved
| bytes
| LOGXRBUF 20 Character, 8 Range of consecutive log buffers:
| bytes Address of first log buffer
| Address of last log buffer
| LOGXBUFL 28 Signed 4-byte Length of single log buffer (constant 4096)
| integer
| LOGXSSID 2C Character, 4 Db2 subsystem ID, 4 characters left justified
| bytes
| LOGXSTIM 30 Character, 8 Db2 subsystem startup time (TIME format
| bytes with DEC option: 0CYYDDDFHHMMSSTH)

Appendix A. Exit routines 713

| Table 96. Log capture routine specific parameter list (continued)
| Name Hex offset Data type Description
| LOGXREL 38 Character, 3 Db2 subsystem release level:
| bytes '810' for Version 8
| '910' for Version 9
| '101' for Version 10
| '111' for Version 11
| LOGXMAXB 3B Character, 1 byte Maximum number of buffers that can be
| passed on one call. The value remains
| constant while Db2 is active.
| 3C Character, 8 Reserved
| bytes
| LOGXUSR1 44 Character, 4 First word of a doubleword work area for the
| bytes user routine. (The content is not changed by
| Db2.)
| LOGXUSR2 48 Character, 4 Second word of user work area.
| bytes
| LOGXSRBA 4C Character, 16 First log RBA, set when Db2 is started. The
| bytes value remains constant while Db2 is active.
| LOGXARBA 5C Character, 16 Highest log archive RBA used. The value is
| bytes updated after completion of each log archive
| operation.
| 6C Character, 12 Reserved
| bytes
|

PSPI

Routines for dynamic plan selection in CICS

You can create application packages and plans that allow application programs to
access Db2 data at execution time. In a CICS environment, you can design CICS
transactions around the application packages and plans or use dynamic plan
allocation.

PSPI

You can enable dynamic plan allocation by using one of the following techniques:
v Use Db2 packages and versioning to manage the relationship between CICS
transactions and Db2 plans. This technique can help minimize plan outage time,
processor time, and catalog contention.
v Use a dynamic plan exit routine to determine the plan to use for each CICS
transaction.

Recommendation: Use Db2 packages and versioning, instead of a CICS dynamic

plan exit routine, for dynamic plan allocation.

PSPI

714 Administration Guide

General guidelines for writing exit routines
When you use the exit routines that Db2 supplies, consider some of the general
rules, requirements, and guidelines for using exit routines.

PSPI

Using an exit routine requires coordination with your system programmers. An

exit routine runs as an extension of Db2 and has all the privileges of Db2. It can
impact the security and integrity of the database. Conceivably, an exit routine
could also expose the integrity of the operating system. Instructions for avoiding
that exposure can be found in the appropriate z/OS publication.

PSPI

Related concepts:
Connection routines and sign-on routines (Managing Security)
Access control authorization exit routine (Managing Security)

Coding rules for exit routines

You must follow certain rules and requirements when coding an exit routine for
Db2.
v

PSPI

It must be written in assembler.

v It must reside in an authorized program library, either the library containing
Db2 modules (prefix.SDSNLOAD) or in a library concatenated ahead of
prefix.SDSNLOAD in the procedure for the database services started task (the
procedure named ssnmDBM1, where ssnm is the Db2 subsystem name).
Authorization routines must be accessible to the ssnmMSTR procedure. For all
routines, we recommend using the library prefix.SDSNEXIT, which is
concatenated ahead of prefix.SDSNLOAD in both started-task procedures.
v The following routines must have the names shown. The name of other routines
should not start with “DSN”, to avoid conflict with the Db2 modules.
Table 97. Required load module name
Type of routine Required load module name
Date DSNXVDTX
Time DSNXVTMX
Connection DSN3@ATH
Sign-on DSN3@SGN

v It must be written to be reentrant and must restore registers before return.

v It must be link-edited with the REENTRANT parameter.
v It must be written and link-edited to execute AMODE(31),RMODE(ANY).
v It must not invoke any Db2 services—for example, through SQL statements.
v It must not invoke any SVC services or ESTAE routines.

Even though Db2 has functional recovery routines of its own, you can establish
your own functional recovery routine (FRR), specifying MODE=FULLXM and

Appendix A. Exit routines 715

 EUT=YES.

PSPI

Modifying exit routines

Because exit routines operate as extensions of Db2, avoid changing or modifying
exit routines while Db2 is running.

Execution environment for exit routines

Exit routines are invoked by standard CALL statements.

PSPI

With some exceptions, which are noted under “General Considerations” in the
description of particular types of routine, the execution environment is:
v Supervisor state
v Enabled for interrupts
v PSW key 7
v No MVS locks held
v For local requests, under the TCB of the application program that requested the
Db2 connection
v For remote requests, under a TCB within the Db2 distributed data facility
address space
v 31-bit addressing mode
v Cross-memory mode
In cross-memory mode, the current primary address space is not equal to the
home address space. Therefore, some z/OS macro services you cannot use at all,
and some you can use only with restrictions. For more information about
cross-memory restrictions for macro instructions, which macros can be used
fully, and the complete description of each macro, refer to the appropriate z/OS
publication.

PSPI

Registers at invocation for exit routines

Registers are set when Db2 passes control to an exit routine.

PSPI

The following are registers that are set at invocation for exit routines:
Table 98. Contents of registers when Db2 passes control to an exit routine
Register Contains
1 Address of pointer to the exit parameter list. For a field procedure, the
address is that of the field procedure parameter list.
13 Address of the register save area.
14 Return address.
15 Address of entry point of exit routine.

716 Administration Guide

 PSPI

Parameter list for exit routines

The parameter list for an exit routine contains pointers to other information, which
generally includes the EXPL parameter list and the exit-specific parameter list.

PSPI

| The parameter list for the log capture exit routine consists of two 64-bit pointers.
| The parameter list for all other exit routines consists of two 31-bit pointers.
| Register 1 points to the address of parameter list EXPL, described by macro
| DSNDEXPL. The field that follows points to a second parameter list, which differs
| for each type of exit routine.

Register 1
Address of EXPL parameter list

Address of exit-specific parameter list

Figure 72. Use of register 1 on invoking an exit routine. (Field procedures and translate
procedures do not use the standard exit-specific parameter list.)

The following is a list of the EXPL parameters. Its description is given by macro
DSNDEXPL:
Table 99. Contents of EXPL parameter list
Hex
Name offset Data type Description
EXPLWA 0 Address Address of a work area to be used by the
routine
EXPLWL 4 Signed 4-byte Length of the work area. The value is:
integer 2048 for connection routines and sign-on
routines
512 for date and time routines and
translate procedures (see Note 1).
256 for edit, validation, and log capture
routines
EXPLRSV1 8 Signed 2-byte Reserved
integer
EXPLRC1 A Signed 2-byte Return code
integer
EXPLRC2 C Signed 4-byte Reason code
integer
EXPLARC 10 Signed 4-byte Used only by connection routines and
integer sign-on routines
EXPLSSNM 14 Character, 8 Used only by connection routines and
bytes sign-on routines
EXPLCONN 1C Character, 8 Used only by connection routines and
bytes sign-on routines

Appendix A. Exit routines 717

 Table 99. Contents of EXPL parameter list (continued)
Hex
Name offset Data type Description
EXPLTYPE 24 Character, 8 Used only by connection routines and
bytes sign-on routines
EXPLSITE 2C Character, 16 For SNA protocols, this is the location name
bytes of the requesting location or <luname>. For
TCP/IP protocols, this is the dotted decimal
IP address of the requester. If the value of
EXPLSITE_OFF is not 0, EXPLSITE is not
used.
EXPLLUNM 3C Character, 8 For SNA protocols, the locally known LU
bytes name of the requesting location. For TCP/IP
protocols, the character string 'TCPIP'.
EXPLNTID 44 Character, 17 For SNA protocols, the fully qualified
bytes network name of the requesting location. For
TCP/IP protocols, field reserved.
EXPLVIDS 55 Character, 1 byte Db2 version identifier
EXPLSITE_OFF 56 Signed 2-byte Offset from the beginning of the work area
integer to the extended location name of the Db2
site that originated the work request. Use
this value if the location name is greater
than 16 bytes. The extended location name
has the following format:
v Signed, 2-byte integer: Length of the
extended location name
v Character, 128 bytes: Extended location
name
Notes: When translating a string of type PC MIXED, a translation procedure has a work
area of 256 bytes plus the length attribute of the string.

PSPI

Row formats for edit and validation routines

In writing an edit or validation routine, you must be aware of the format in which
Db2 stores the rows of tables.

Column boundaries for edit and validation procedures

Db2 stores columns contiguously, regardless of word boundaries in physical
storage, except LOB and XML columns. LOB or XML values are not stored
contiguously; an indicator column is stored in a base table in place of the LOB or
XML values.

PSPI

You cannot specify edit procedures for any table that contains a LOB column. You
cannot define edit procedures as WITH ROW ATTRIBUTES for any table that
contains a ROWID column. In addition, LOB values are not available to validation
procedures; indicator columns and ROWID columns represent LOB columns as
input to a validation procedure.

718 Administration Guide

 Similarly, you cannot specify edit procedures as WITH ROW ATTRIBUTES for any
table that contains an XML column. XML values are not available to validation
procedures. DOCID and XML indicator columns represent XML columns as input
to a validation procedure.

PSPI

Null values for edit procedures, field procedures, and

validation routines
If null values are allowed for a column, an extra byte is stored before the actual
column value.

PSPI

This byte is X'00' if the column value is not null; it is X'FF' if the value is null. This
extra byte is included in the column length attribute (parameter FFMTFLEN).

PSPI

Fixed-length rows for edit and validation routines

If all columns in a table are of fixed length, the rows are stored in fixed-length
format. The rows are byte strings.

PSPI

Example: The sample project activity table has five fixed-length columns. The first
two columns do not allow nulls; the last three do.
Table 100. A row in fixed-length format
Column 1 Column 2 Column 3 Column 4 Column 5
MA2100 10 00 0.5 00 820101 00 821101

PSPI

Varying-length rows for edit and validation routines

The rows of a table with varying-length columns are varying-length rows if they
contain varying-length values. In basic row format, each varying-length value has a
2-byte length field in front of it. Those 2 bytes are not included in the column
length attribute.

PSPI

The following table shows a row of the sample department table in basic row
format. The first value in the DEPTNAME column indicates the column length as a
hexadecimal value.

Appendix A. Exit routines 719

 Table 101. A varying-length row in basic row format in the sample department table
DEPTNO DEPTNAME MGRNO ADMRDEPT LOCATION
C01 0012 Information 00 000030 A00 00 New York
center

Varying-length columns have no gaps after them. Hence, columns that appear after
varying-length columns are at variable offsets in the row. To get to such a column,
you must scan the columns sequentially after the first varying-length column. An
empty string has a length of zero with no data following.

ROWID and indicator columns are treated like varying length columns. Row IDs
are VARCHAR(17). A LOB indicator column is VARCHAR(4), and an XML
indicator column is VARCHAR(6). It is stored in a base table in place of a LOB or
XML column, and indicates whether the LOB or XML value for the column is null
or zero length.

In reordered row format, if a table has any varying-length columns, all fixed length
columns are placed at the beginning of the row, followed by the offsets to the
varying length columns, followed by the values of the varying length columns.

The following table shows the same row of the sample department table, but in
reordered row format. The value in the offset column indicates the offset value as a
hexadecimal value.
Table 102. A varying-length row in reordered row format in the sample department table
Offset
DEPTNO MGRNO ADMRDEPT LOCATION column DEPTNAME
C01 00 000030 A00 00 New York 20 Information
center

PSPI

Varying-length rows with nulls for edit and validation routines

A varying-length column can allow null values. In basic row format, the value in
the length field includes the length of the null indicator byte but does not include
the length field itself.

PSPI

The following table shows how the row would look in storage if nulls were
allowed in DEPTNAME. The first value in the DEPTNAME column indicates the
column length as a hexadecimal value.
Table 103. A varying-length row in basic row format in the sample department table
DEPTNO DEPTNAME MGRNO ADMRDEPT LOCATION
C01 0013 Information 00 000030 A00 00 New York
center

An empty string has a length of one, a X'00' null indicator, and no data following.

720 Administration Guide

 In reordered row format, if a table has any varying-length columns, with or
without nulls, all fixed length columns are placed at the beginning of the row,
followed by the offsets to the varying length columns, followed by the values of
the varying length columns.

PSPI

EDITPROCs and VALIDPROCs for handling basic and

reordered row formats
You can check the row format type (RFMTTYPE) to ensure that edit procedures
(EDITPROC) and validation procedures (VALIDPROC) produce predictable results.

PSPI

If you write new edit and validation routines on tables with rows in basic row
format (BRF) or reordered row format (RRF), make sure that EDITPROCs and
VALIDPROCs are coded to check RFMTTYPE and handle both BRF and RRF
formats.

If an EDITPROC or VALIDPROC handles only RRF, make sure that it checks

RFMTTYPE and returns an error or warning if it detects BRF. If an EDITPROC or
VALIDPROC that handles only BRF is to be used on tables in RRF, make sure that
it checks RFMTTYPE and returns an error or warning if it detects RRF.

PSPI

Converting basic row format table spaces with edit and

validation routines to reordered row format
You cannot convert the table spaces with edit and validation routines from basic
row format to reordered row format directly. You must perform additional tasks to
convert these table spaces.

Converting basic row format table spaces with edit routines to

reordered row format
You can convert basic row format table spaces to reordered row format. If some
tables in a table space have edit routines, you cannot convert the table space to
reordered row format directly. You must take other actions for the conversion to
succeed.

Procedure

PSPI To convert a table space to reordered row format, complete the following
steps for each table that has an edit routine:
1. Use the UNLOAD utility to unload data from the table or tables that have edit
routines.
2. Use the DROP statement to drop the table or tables that have edit routines.
3. Make any necessary modifications to the edit routines so that they can be used
with rows in reordered row format.
4. Use the REORG utility to reorganize the table space. Using the REORG utility
converts the table space to reordered row format.
5. Re-create tables with your modified edit routines. Also, re-create any additional
related objects, such as indexes and check constraints.

Appendix A. Exit routines 721

 6. Use the LOAD RESUME utility to load the data into the tables that have the
modified edit routines. PSPI

Converting basic row format table spaces with validation

routines to reordered row format
You can convert basic row format table spaces to reordered row format. If some
tables in a table space have validation routines, you cannot convert the table space
to reordered row format directly. You must take other actions for the conversion to
succeed.

Procedure

PSPI To convert a table space to reordered row format, complete the following
steps for each table that has a validation routine:
1. Use the ALTER TABLE statement to alter the validation routine to NULL.
2. Run the REORG utility or the LOAD REPLACE utility to convert the table
space to reordered row format.
3. Make any necessary modifications to the validation routine so that it can be
used with rows in reordered row format.
4. Use the ALTER TABLE statement to add the modified validation routine to the
converted table. PSPI

Row format conversion for table spaces

| The row format of a table space might be converted when you run the LOAD
| REPLACE or REORG TABLESPACE utilities.

If the Db2 subsystem parameter RRF is set to ENABLE, the table space is
converted from basic row format to reordered row format when you run the
LOAD REPLACE utility or the REORG TABLESPACE utility. (The default setting
for the RRF subsystem parameter is ENABLE.) If the RRF subsystem parameter is
set to DISABLE, the table space is not converted. Therefore, if the table space was
in basic row format before running the LOAD REPLACE utility or the REORG
TABLESPACE utility, the table space remains in basic row format. Likewise, if the
table space was in reordered row format before running either of these utilities, the
table space remains in reordered row format.

Exceptions:
v LOB table spaces and table spaces in the catalog and directory databases always
remain in basic row format, regardless of the RRF subsystem parameter setting,
or the setting of the ROWFORMAT keyword for the utility. (The ROWFORMAT
keyword specifies the output row format in a table space or partition. This
keyword overrides the existing RRF setting when specified.)
v XML table spaces always remain in reordered row format, regardless of the RRF
subsystem parameter setting or the utility keyword setting.
v For universal table spaces that are cloned, both the base table space and the
clone table space remain in the same format as when they were created,
regardless of the RRF subsystem parameter setting or the utility keyword
setting.
v When multiple data partitions are affected by the LOAD REPLACE utility or the
REORG TABLESPACE utility, and some of the partitions are in basic row format
and some are in reordered row format, the utilities convert every partition to
reordered row format. This behavior is the default, regardless of the RRF
subsystem parameter setting. Alternatively, you can specify ROWFORMAT BRF

722 Administration Guide

 in the utility statement for all affected partitions so that the table space is in
basic row format after the utility completes successfully.

Example

To convert an existing table space from reordered row format to basic row format,
run REORG TABLESPACE ROWFORMAT BRF against the table space. To keep the
table space in basic row format on subsequent executions of the LOAD REPLACE
utility or the REORG TABLESPACE utility, continue to specify ROWFORMAT BRF
in the utility statement. Alternatively, you can set the RRF subsystem parameter to
DISABLE.
Related reference:
REORDERED ROW FORMAT field (RRF subsystem parameter) (Db2
Installation and Migration)
REORG TABLESPACE (Db2 Utilities)
LOAD (Db2 Utilities)

Dates, times, and timestamps for edit and validation routines

The values in columns with data types of DATE, TIME, and TIMESTAMP are
stored in specific formats.

PSPI

The DATE format that consists of 4 total bytes :

Table 104. DATE format
Year Month Day
2 bytes 1 byte 1 byte

The TIME format, which consists of 3 total bytes:

Table 105. TIME format
Hours Minutes Seconds
1 byte 1 byte 1 byte

The following table shows the TIMESTAMP format, which consists of 7 to 13 total
bytes.
Table 106. TIMESTAMP format
Year Month Day Hours Minutes Seconds Partial second
2 bytes 1 byte 1 byte 1 byte 1 byte 1 byte 0 to 6 bytes

PSPI

Appendix A. Exit routines 723

 Parameter list for row format descriptions
Db2 passes a description of the row format to an edit routine or a validation
routine through a parameter list, which is generated by macro DSNDROW. The
description includes both the general row characteristics and the characteristics of
each column.

PSPI

DSNDROW defines the columns in the order as they are defined in the CREATE
TABLE statement or possibly the ALTER TABLE statement. For rows in the
reordered row format, the new column order in DSNDROW does not necessarily
correspond to the order in which the columns are stored in the row. The following
is the general row description:
Table 107. Description of a row format
Name Hex offset Data type Description
RFMTNFLD 0 Signed fullword Number of columns in a row
integer
RFMTAFLD 4 Address Address of a list of column descriptions
RFMTTYPE 8 Character, 1 byte Row type:
X'00' = row with fixed-length columns
X'04' = row with varying-length
columns in basic row format
X'08' = row with varying-length
columns in reordered row format
9 Character, 3 Reserved
bytes

The following is the description of each column:

Table 108. Description of a column format
Name Hex offset Data type Description
FFMTFLEN 0 Signed fullword Column length attribute
integer
FFMTFTYP 4 Character, 1 byte Data type code
FFMTNULL 5 Character, 1 byte Data attribute:
X'00' = Null values are allowed.
X'04' = Null values are not allowed.
FFMTFNAM 6 Character, 18 Column name
bytes

The following is a description of data type codes and length attributes.

Table 109. Description of data type codes and length attributes
Code
Data type (FFMTFTYP) Length attribute (FFMTFLEN)
BIGINT X'32' 8
BINARY X'34' Length of string
VARBIN X'38' Length of string

724 Administration Guide

 Table 109. Description of data type codes and length attributes (continued)
Code
Data type (FFMTFTYP) Length attribute (FFMTFLEN)
DECFLOAT X'40' 8 for DECFLOAT(16) or 16 for
DECFLOAT(34)
INTEGER X'00' 4
SMALLINT X'04' 2
FLOAT (single precision) X'08' 4
FLOAT (double precision) X'08' 8
DECIMAL X'0C' INTEGER(p/2), where p is the
precision
CHAR X'10' The length of the string
VARCHAR X'14' The length of the string
DATE X'20' 4
TIME X'24' 3
TIMESTAMP X'28' 7 + INTEGER( (p+1) / 2),
where p is the precision of the
TIMESTAMP. The length can be
7 to 13.
ROWID X'2C' 17
INDICATOR COLUMN X'30' 4 for a LOB indicator column or 6
for an XML indicator column

PSPI

Db2 codes for numeric data in edit and validation routines

Db2 stores numeric data in a specially encoded “Db2-coded” format .

PSPI

To retrieve numeric data in its original form, you must Db2-decode it according to
its data type:
Table 110. Db2 decoding procedure according to data type
Data type Db2 decoding procedure
SMALLINT Invert the sign bit (high-order bit).
Value Meaning
8001 0001 (+1 decimal)
7FF3 FFF3 (-13 decimal)
INTEGER Invert the sign bit (high-order bit).
Value Meaning
800001F2
000001F2 (+498 decimal)
7FFFFF85
FFFFFF85 (-123 decimal)

Appendix A. Exit routines 725

 Table 110. Db2 decoding procedure according to data type (continued)
Data type Db2 decoding procedure
FLOAT If the sign bit (high-order bit) is 1, invert only that bit.
Otherwise, invert all bits.
Value Meaning
C110000000000000
4110000000000000 (+1.0 decimal)
3EEFFFFFFFFFFFFF
C110000000000000 (-1.0 decimal)
DECIMAL Save the high-order hexadecimal digit (sign digit). Shift
the number to the left one hexadecimal digit. If the
sign digit is X'F', put X'C' in the low-order position.
Otherwise, invert all bits in the number and put X'D'
in the low-order position.
Value Meaning
F001 001C (+1)
0FFE 001D (-1)
BIGINT Invert the sign bit (high order bit).
Value Meaning
8000000000000854
0000000000000854 (2132 decimal)
7FFFFFFFFFFFFFE0
FFFFFFFFFFFFFFE0 (-32 decimal)
DECFLOAT Convert and return a DECFLOAT representation of a
number or string representation of a number.
Value Meaning
D8F77D00000000000C
222C000000001E80 (+7.500 decfloat)
270882FFFFFFFFFFF2
A2300000000003D0 (-7.50 decfloat)

PSPI

726 Administration Guide

Appendix B. Stored procedures for administration
Db2 provides stored procedures that you can call in your application programs to
perform administrative functions.

For the complete list of stored procedures that are provided with Db2 for z/OS,
see Procedures that are supplied with Db2 (Db2 SQL).
Related concepts:
Migration step 22: Configure Db2 for running stored procedures and
user-defined functions (optional) (Db2 Installation and Migration)
Supplied stored procedures for utility operations (Db2 Utilities)
Db2-supplied stored procedures for application programming (Db2
Application programming and SQL)
Related tasks:
Migration step 23: Set up Db2-supplied routines (Db2 Installation and
Migration)
Installing Db2-supplied routines during installation (Db2 Installation and
Migration)

Common SQL API stored procedures

Common SQL API stored procedures implement a cross-database and
cross-operating system SQL API that is portable across IBM data servers, including
Db2 for Linux, UNIX, and Windows.

The Common SQL API is a solution-level API that supports common tooling across
IBM data servers. This Common SQL API ensures that tooling does not break
when a data server is upgraded, and it notifies the caller when an upgrade to
tooling is available to capitalize on new data server functionality. Applications that
support more than one IBM data server will benefit from using the Common SQL
API, as it lowers the complexity of implementation. Such applications typically
perform a variety of common administrative functions. For example, you can use
these stored procedures to retrieve data server configuration information, return
system information about the data server, and return the short message text for an
SQLCODE.

The Common SQL API includes the following stored procedures that are supplied
with Db2:
v GET_CONFIG stored procedure (Db2 SQL)
v GET_MESSAGE stored procedure (Db2 SQL)
v GET_SYSTEM_INFO stored procedure (Db2 SQL)
v SET_PLAN_HINT stored procedure (Db2 SQL)

These stored procedures use version-stable XML documents as parameters. These

XML parameter documents adhere to a single, common document type definition
(DTD). This DTD is flexible enough to represent hierarchical structures and binary
data. The XML parameter documents can be parsed by using the Apache
Commons Configuration component.

© Copyright IBM Corp. 1982, 2017 727

 Each of the three XML parameter documents has a name and a version, and is
typically associated with one stored procedure. The three types of XML parameter
documents are:
v XML input documents
v XML output documents
v XML message documents
The XML input document is passed as input to the stored procedure. The XML
output document is returned as output, and the XML message document returns
messages. If the structure, attributes, or types in an XML parameter document
change, the version of the XML parameter document changes. The version of all
three of these documents remains in sync when you call a stored procedure. For
example, if you call the GET_SYSTEM_INFO stored procedure and specify the
major_version parameter as 1 and the minor_version parameter as 1, the XML input,
XML output, and XML message documents will be Version 1.1 documents.
Related reference:
Procedures that are supplied with Db2 (Db2 SQL)
Related information:
Apache Commons Configuration component
Common DTD

Versioning of XML documents

Common SQL API stored procedures support multiple versions of the three XML
parameter documents: XML input documents, XML output documents, and XML
message documents.

If the structure, attributes, or types in an XML parameter document change, the

version of the XML parameter document changes. Therefore, the content of an
XML parameter document varies depending on the version that you specify.

The version of all three of these documents remains in sync when you call a stored
procedure. For example, if you call the GET_SYSTEM_INFO stored procedure and
specify the major_version parameter as 1 and the minor_version parameter as 1, the
XML input, XML output, and XML message documents will be Version 1.1
documents.

Version information in an XML parameter document is expressed as key and value

pairs for Document Type Major Version and Document Type Minor Version. For
example, an XML output document might define the following keys and values in
a dictionary element:
<key>Document Type Name</key><string>Data Server Configuration Output</string>
<key>Document Type Major Version</key><integer>2</integer>
<key>Document Type Minor Version</key><integer>0</integer>

To determine the highest supported document version for a stored procedure,

specify NULL for the major_version parameter, the minor_version parameter, and all
other required parameters. The stored procedure returns the highest supported
document version as values in the major_version and minor_version output
parameters, and sets the xml_output and xml_message output parameters to NULL.

728 Administration Guide

 If you specify non-null values for the major_version and minor_version parameters,
you must specify a document version that is supported . If the version is invalid,
the stored procedure returns an error (-20457).

If the XML input document in the xml_input parameter specifies the Document Type
Major Version and Document Type Minor Version keys, the value for those keys
must be equal to the values that you specified in the major_version and
minor_version parameters, or an error (+20458) is raised.

XML input documents

The XML input document is passed as input to common SQL API stored
procedures and adheres to a single, common document type definition (DTD).

The XML input document consists of a set of entries that are common to all stored
procedures, and a set of entries that are specific to each stored procedure. The
XML input document has the following general structure:
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Document Type Name</key><string>Data Server Message Input</string>
<key>Document Type Major Version</key><integer>1</integer>
<key>Document Type Minor Version</key><integer>0</integer>
<key>Document Locale</key><string>en_US</string>
<key>Complete</key><false/>
<!-- Document type specific data appears here. -->
</dict>
</plist>

The Document Type Name key varies depending on the stored procedure. This
example shows an XML input document for the GET_MESSAGE stored procedure.
In addition, the values of the Document Type Major Version and Document Type
Minor Version keys depend on the values that you specified in the major_version
and minor_version parameters for the stored procedure.

If the stored procedure is not running in Complete mode, you must specify the
Document Type Name key, the required parameters, and any optional parameters
that you want to specify. Specifying the Document Type Major Version and
Document Type Minor Version keys are optional. If you specify the Document Type
Major Version and Document Type Minor Version keys, the values must be the
same as the values that you specified in the major_version and minor_version
parameters. You must either specify both or omit both of the Document Type Major
Version and Document Type Minor Version keys. Specifying the Document Locale
key is optional. If you specify the Document Locale key, the value is ignored.

Important: XML input documents must be encoded in UTF-8 and contain only
English characters.

Complete mode for returning valid XML input documents

You can use Complete mode to create a valid XML input document for the common
SQL API stored procedures. Then, you can customize the XML input document
and pass it back to the procedure.

If the Complete key is included and you set the value to true, the stored procedure
will run in Complete mode, and all other entries in the XML input document will
be ignored. The following example shows the minimal XML input document that
is required for the stored procedure to run in Complete mode:

Appendix B. Stored procedures for administration 729

 <?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Complete</key><true/>
</dict>
</plist>

If the stored procedure runs in Complete mode, a complete input document is

returned by the xml_output parameter of the stored procedure. The returned XML
document is a full XML input document that includes a Document Type and
sections for all possible required and optional parameters. The returned XML input
document also includes entries for Display Name, Hint, and the Document Locale.
Although these entries are not required (and will be ignored) in the XML input
document, they are usually needed when rendering the document in a client
application.

All entries in the returned XML input document can be rendered and changed in
ways that are independent of the operating system or data server. Subsequently,
the modified XML input document can be passed in the xml_input parameter in a
new call to the same stored procedure. This enables you to programmatically
create valid xml_input documents.

XML output documents

The XML output documents that are returned as output from common SQL API
stored procedures share a common set of entries.

At a minimum, the XML output documents that are returned in the xml_output
parameter include the following key and value pairs, followed by information that
is specific to each stored procedure:
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Document Type Name</key>
<string>Data Server Configuration Output</string>
<key>Document Type Major Version</key><integer>1</integer>
<key>Document Type Minor Version</key><integer>0</integer>
<key>Data Server Product Name</key><string>DSN</string>
<key>Data Server Product Version</key><string>9.1.5</string>
<key>Data Server Major Version</key><integer>9</integer>
<key>Data Server Minor Version</key><integer>1</integer>
<key>Data Server Platform</key><string>z/OS</string>
<key>Document Locale</key><string>en_US</string>
<!-- Document type specific data appears here. -->
</dict>
</plist>

The Document Type Name key varies depending on the stored procedure. This
example shows an XML output document for the GET_CONFIG stored procedure.
In addition, the values of the Document Type Major Version and Document Type
Minor Version keys depend on the values that you specified in the major_version
and minor_version parameters for the stored procedure.

Entries in the XML output document are grouped by using nested dictionaries.
Each entry in the XML output document describes a single piece of information. In
general, an XML output document is comprised of Display Name, Value, and Hint,
as shown in the following example:
<key>SQL Domain</key>
<dict>
<key>Display Name</key>

730 Administration Guide

 <string>SQL Domain</string>
<key>Value</key>
<string>v33ec059.svl.ibm.com</string>
<key>Hint</key>
<string />
</dict>

XML output documents are generated in UTF-8 and contain only English
characters.

XPath expressions for filtering output

You can use an XPath expression to filter the XML output that is returned by the
GET_CONFIG, GET_MESSAGE, and GET_SYSTEM_INFO stored procedures.

To filter the output, specify a valid XPath query string in the xml_filter parameter
of the stored procedure.

The following restrictions apply to the XPath expression that you specify:
v The XPath expression must reference a single value.
v The XPath expression must always be absolute from the root node. For example,
the following path expressions are allowed: /, nodename, ., and ... The following
expressions are not allowed: // and @
v The only predicates allowed are [path=’value’] and [n].
v The only axis allowed is following-sibling.
v The XPath expression must end with one of the following, and, if necessary, be
appended with the predicate [1]: following-sibling::string,
following-sibling:: data, following-sibling::date, following-sibling::real,
or following-sibling::integer.
v Unless the axis is found at the end of the XPath expression, it must be followed
by a ::dict, ::string, ::data, ::date, ::real, or ::integer, and if necessary, be
appended with the predicate [1].
v The only supported XPath operator is =.
v The XPath expression cannot contain a function, namespace, processing
instruction, or comment.

Tip: If the stored procedure operates in complete mode, do not apply filtering, or
an SQLCODE (+20458) is raised.

Example: The following XPath expression selects the value for the Data Server
Product Version key from an XML output document:
/plist/dict/key[.=’Data Server Product Version’]/following-sibling::string[1]

The stored procedure returns the string 9.1.5 in the xml_output parameter if the
value of the Data Server Product Version is 9.1.5. Therefore, the stored procedure
call returns a single value rather than an XML document.

XML message documents

An XML message document provides detailed information about an SQL warning
condition.

When a common SQL API stored procedure encounters an internal processing

error or invalid parameter, the data server returns an SQLCODE and the

Appendix B. Stored procedures for administration 731

 corresponding SQL message to the caller. When this occurs, the procedure returns
an XML message document in the xml_message parameter that contains additional
information about the warning.

An XML message document contains key and value pairs followed by details
about an SQL warning condition. The general structure of an XML message
document is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Document Type Name</key>
<string>Data Server Message</string>
<key>Document Type Major Version</key><integer>1</integer>
<key>Document Type Minor Version</key><integer>0</integer>
<key>Data Server Product Name</key><string>DSN</string>
<key>Data Server Product Version</key><string>9.1.5</string>
<key>Data Server Major Version</key><integer>9</integer>
<key>Data Server Minor Version</key><integer>1</integer>
<key>Data Server Platform</key><string>z/OS</string>
<key>Document Locale</key><string>en_US</string>
--- Details about an SQL warning condition are included here. ---
</dict>
</plist>

The details about an SQL warning will be encapsulated in a dictionary entry,

which is comprised of Display Name, Value, and Hint, as shown in the following
example:
<key>Short Message Text</key>
<dict>
<key>Display Name</key><string>Short Message Text</string>
<key>Value</key>
<string>DSNA630I DSNADMGC A PARAMETER FORMAT OR CONTENT ERROR WAS FOUND.
The XML input document must be empty or NULL.</string>
<key>Hint</key><string />
</dict>

XML message documents are generated in UTF-8 and contain only English
characters.

Troubleshooting Db2 stored procedure problems

If you encounter problems setting up, calling, or running stored procedures,
several troubleshooting techniques and tools are available in Db2 and z/OS.

Procedure

To troubleshoot Db2 stored procedures, perform one or more of the following

actions:
v For general information about the available debugging tools and techniques, see
Debugging stored procedures (Db2 Application Programming and SQL Guide).
v See if you are troubleshooting one of the following problems:
– For problems with implementing RRS, see “RRS error samples.”
– For problems with calling a particular stored procedure, you might not have
the required authorizations. See “Privileges to execute a stored procedure
called statically.”
– For troubleshooting Java stored procedures, see “Common problems.”
– For invoking programs that receive SQLCODE -430, see “Classical debugging
of stored procedures.”

732 Administration Guide

Information resources for Db2 11 for z/OS and related
products
Information about Db2 11 for z/OS and products that you might use in
conjunction with Db2 11 is available online in IBM Knowledge Center or on library
websites.

Obtaining Db2 for z/OS publications

Current Db2 11 for z/OS publications are available from the following websites:

http://www-01.ibm.com/support/docview.wss?uid=swg27039165

Links to IBM Knowledge Center and the PDF version of each publication are
provided.

Db2 for z/OS publications are also available for download from the IBM
Publications Center (http://www.ibm.com/shop/publications/order).

In addition, books for Db2 for z/OS are available on a CD-ROM that is included
with your product shipment:
v Db2 11 for z/OS Licensed Library Collection, LK5T-8882, in English. The
CD-ROM contains the collection of books for Db2 11 for z/OS in PDF format.
Periodically, IBM refreshes the books on subsequent editions of this CD-ROM.

Installable information center

You can download or order an installable version of the Information Management

Software for z/OS Solutions Information Center, which includes information about
Db2 11 for z/OS, QMF, IMS, and many Db2 Tools for z/OS products. You can
install this information center on a local system or on an intranet server. For more
information, see http://www-01.ibm.com/support/knowledgecenter/
SSEPEK_11.0.0/com.ibm.db2z11.doc/src/alltoc/installabledzic.html.

© Copyright IBM Corp. 1982, 2017 733

734 Administration Guide
Notices
This information was developed for products and services offered in the US. This
material might be available from IBM in other languages. However, you may be
required to own a copy of the product or product version in that language in order
to access it.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing IBM Corporation

North Castle Drive, MD-NC119
Armonk, NY 10504-1785 US

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may
not apply to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM websites are provided for

convenience only and do not in any manner serve as an endorsement of those
websites. The materials at those websites are not part of the materials for this IBM
product and use of those websites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

© Copyright IBM Corp. 1982, 2017 735

 Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:

IBM Director of Licensing IBM Corporation

North Castle Drive, MD-NC119
Armonk, NY 10504-1785 US

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.

The performance data and client examples cited are presented for illustrative
purposes only. Actual performance results may vary depending on specific
configurations and operating conditions.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to actual people or business enterprises is entirely
coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work must
include a copyright notice as shown below:

© (your company name) (year).

Portions of this code are derived from IBM Corp. Sample Programs.
© Copyright IBM Corp. (enter the year or years).

If you are viewing this information softcopy, the photographs and color
illustrations may not appear.

Programming interface information

This information is intended to help you to plan for and administer Db2 11 for
z/OS. This information also documents General-use Programming Interface and
Associated Guidance Information and Product-sensitive Programming Interface
and Associated Guidance Information provided by Db2 11 for z/OS.

736 Administration Guide

 General-use Programming Interface and Associated Guidance
Information
General-use Programming Interfaces allow the customer to write programs that
obtain the services of Db2 11 for z/OS.

General-use Programming Interface and Associated Guidance Information is

identified where it occurs by the following markings:

General-use Programming Interface and Associated Guidance Information...

Product-sensitive Programming Interface and Associated

Guidance Information

Product-sensitive Programming Interfaces allow the customer installation to

perform tasks such as diagnosing, modifying, monitoring, repairing, tailoring, or
tuning of this IBM software product. Use of such interfaces creates dependencies
on the detailed design or implementation of the IBM software product.
Product-sensitive Programming Interfaces should be used only for these
specialized purposes. Because of their dependencies on detailed design and
implementation, it is to be expected that programs written to such interfaces may
need to be changed in order to run with new product releases or versions, or as a
result of service.

Product-sensitive Programming Interface and Associated Guidance Information is

identified where it occurs by the following markings:

PSPI

Product-sensitive Programming Interface and Associated Guidance Information...

PSPI

Trademarks
IBM, the IBM logo, and ibm.com® are trademarks or registered marks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the web at "Copyright and
trademark information" at: http://www.ibm.com/legal/copytrade.shtml.

Linux is a registered trademark of Linus Torvalds in the United States, other

countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

Notices 737
 Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the following
terms and conditions:

Applicability: These terms and conditions are in addition to any terms of use for
the IBM website.

Personal use: You may reproduce these publications for your personal,
noncommercial use provided that all proprietary notices are preserved. You may
not distribute, display or make derivative work of these publications, or any
portion thereof, without the express consent of IBM.

Commercial use: You may reproduce, distribute and display these publications
solely within your enterprise provided that all proprietary notices are preserved.
You may not make derivative works of these publications, or reproduce, distribute
or display these publications or any portion thereof outside your enterprise,
without the express consent of IBM.

Rights: Except as expressly granted in this permission, no other permissions,

licenses or rights are granted, either express or implied, to the publications or any
information, data, software or other intellectual property contained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in its
discretion, the use of the publications is detrimental to its interest or, as
determined by IBM, the above instructions are not being properly followed.

You may not download, export or re-export this information except in full
compliance with all applicable laws and regulations, including all United States
export laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE

PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING
BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

Privacy policy considerations

IBM Software products, including software as a service solutions, (“Software
Offerings”) may use cookies or other technologies to collect product usage
information, to help improve the end user experience, to tailor interactions with
the end user, or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings
can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific
information about this offering’s use of cookies is set forth below.

This Software Offering does not use cookies or other technologies to collect
personally identifiable information.

If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies

738 Administration Guide

and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.

For more information about the use of various technologies, including cookies, for
these purposes, see IBM’s Privacy Policy at http://www.ibm.com/privacy and
IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details the
section entitled “Cookies, Web Beacons and Other Technologies” and the “IBM
Software Products and Software-as-a-Service Privacy Statement” at
http://www.ibm.com/software/info/product-privacy.

Notices 739
740 Administration Guide
Glossary
The glossary is available in IBM Knowledge Center.

See the Glossary topic for definitions of Db2 for z/OS terms.

© Copyright IBM Corp. 1982, 2017 741

742 Administration Guide
Index
A access method services (continued)
DEFINE CLUSTER command (continued)
abend REUSE option 36
AEY9 518 SHAREOPTIONS 36
ASP7 518 DEFINE command 485
backward log recovery 557 table spaces
CICS 320 re-creating 562
abnormal termination 518 to rename Db2 data sets 434
scenario 523 work files
waits 518 redefining 485
current status rebuild 542 access paths
disconnecting Db2 331 hash access 61, 173, 175
DXR122E 509 accessibility
effects 400 keyboard xv
forward log recovery 552 shortcut keys xv
IMS active log data sets
procedure 514 copying
scenario 517 IDCAMS REPRO statement 397
U3047 517 high-level qualifier
U3051 517 changing 210, 211, 212, 213, 214, 215
IRLM offloading 370
scenario 509 stopping
STOP command 302 effects 528
STOP DB2 command 302 active log inventory
log data sets
damage 537 adding 380
lost information 563 active logs
log initialization phase 541 dual logging 370
page problems 562 gaps
Resource Recovery Services (RRS) 333 creating 565
restarting 240, 540 offloading 371
SQLCODE -923 524 out-of-space conditions 526
VVDS (VSAM volume data set) recovering 526
destroyed 580 troubleshooting 526
out of space 580 truncation 371
accelerator tables VSAM data sets 647
recovering 432 writing 370
access method services ADMIN_TASK_ADD stored procedure
ALTER command 581 SQL codes 263
bootstrap data set (BSDS) 395 ADMIN_TASK_OUTPUT function 257
commands ADMIN_TASK_REMOVE stored procedure
ALTER 35 SQL codes 263
ALTER ADDVOLUMES 26, 35 administration
ALTER REMOVEVOLUMES 26 stored procedures 727
DEFINE 35, 562 administrative task schedulers
DEFINE CLUSTER 35, 36 ADMIN_TASK_ADD stored procedure 263
EXPORT 482 ADMIN_TASK_CANCEL stored procedure 258
IMPORT 218, 562 ADMIN_TASK_OUTPUT function 257
PRINT 494 ADMIN_TASK_REMOVE stored procedure 263
REPRO 494, 535 ADMIN_TASK_STATUS function
damaged bootstrap data set (BSDS) SQL codes 263
deleting 533 ADMIN_TASK_UPDATE stored procedure 258
renaming 533 architecture 264
damaged BSDS (bootstrap data set) data sharing environment
deleting 533 architecture 268
renaming 533 specifying 253
data sets synchronization 260
managing 35 task execution 277
DEFINE CLUSTER command interface
defining extents 36 security 271
examples 36 JCL jobs 277
LINEAR option 36

© Copyright IBM Corp. 1982, 2017 743

administrative task schedulers (continued) application errors
lifecycle 265 backing out
overview 249 without a quiesce point 513
resources application period 67
security 271 adding 178
security 269 application plans
starting 259 dependent objects 186
stopping 260 application programs
stored procedures call attachment facility (CAF)
accounting information 268 running 247
calling 275, 276 coding SQL statements
displaying results 257 for IMS 244
SQL codes 263 errors 512
SYSIBM.ADMIN_TASKS table 267 information
SYSIBM.ADMIN_TASKS_HIST table 267 obtaining 285
task execution 273 issuing commands 233
multi-thread 273 recovery procedures
security 272 CICS 518
task lists 267 IMS 517
recovering 262 RRSAF (Resource Recovery Services attachment facility)
task status running 248
listing 255, 256 running
tasks 249 batch 245
adding 249 CICS transactions 245
listing 255 error recovery 512
removing 258 IMS 244
sample schedule 251 TSO
scheduling 250 running 244
stopping 258 application-period temporal tables 67
updating 258 creating 72, 178
time zones 278 querying 77
tracing applications
disabling 261 CICS
enabling 261 connections 320
troubleshooting 261, 262 disconnecting 320
Unicode restrictions 276 archive log
user roles 270 retaining 434
user-defined table functions ARCHIVE LOG command 379
troubleshooting 263 archive log data sets
administrative tasks archiving
scheduling 249 DFSMS (Data Facility Storage Management
alias Subsystem) 375
retrieving catalog information about 117 BSDS (bootstrap data set) 395
ALTER BUFFERPOOL command 292 deleting 375
ALTER command dual logging 374
access method services 581 dynamic allocation 373
FOR option 35 high-level qualified
TO option 35 changing 214
ALTER DATABASE statement 127 high-level qualifier
ALTER FUNCTION statement 208 changing 210, 211, 212, 213, 214, 215
ALTER INDEX statement 47 locating 393
ALTER PROCEDURE statement 207 multivolumes 375
ALTER STOGROUP statement 128 offloading 370
ADD VOLUMES clause 129 overview 373
ALTER TABLE statement 144 recovering 530
DATA CAPTURE clause 182 retention period 375
default column values 147 types 373
VALIDPROC clause 181 writing 371
ALTER TABLESPACE statement 131 archive logs
application changes tapes
backing out setting limits 381
with quiesce point 512 archive table
application defaults module 239 creating 83
application environment archiving
status 349 disks 374
tapes 374

744 Administration Guide

attributes BSDS (bootstrap data set) (continued)
data types 8 dual copies 395
names 7 dual recovery 535
values 8 dual-BSDS mode 397
authorities failure symptoms 537
CICS high-level qualifier
controlling access 245 changing 210, 211, 213, 214
IMS application programs log inventory
controlling access 244 changing 397
authority managing 395
retrieving catalog information 120 recovery procedures 533
authorization access recovery scenarios 561
finding 244 restart usage 400
AUTOESTSPACE(YES) option restoring
REORG TABLESPACE utility 175 from archive logs 535
availability single recovery 535
recovering stand-alone log services 669
data sets 453 buffer pools
page sets 453 attributes
altering 292
controlling 279
B logging 370
monitoring 293
back-level image copy data sets 434
BACKUP SYSTEM utility 33, 34
Db2 subsystem
recovering 506 C
backups CAF connections
data monitoring 313
moving 474 call attachment facility (CAF)
data sets application programs
using DFSMShsm 440 running 247
databases CANCEL THREAD command 344
DSN1COPY 506 CICS threads 320
image copies 455 disconnecting from TSO 315
backward log recovery phase effects 345
failures 557 catalog alias
recovering 558 defining 211
restarting 404 catalog definitions
base table consistency 503
distinctions from temporary tables 64 catalog tables
base table spaces 45 image copies
base tables frequency 438, 439
creating 60 retrieving information about
basic direct access method (BDAM) 373 primary keys 121
basic row format 721 status 122
basic sequential access method (BSAM) 373 SYSAUXRELS 124
batch message processing (BMP) program 328 SYSCOLUMNS 185
batch processing updated by COMMENT ON statement 126
TSO 244 updated by CREATE VIEW statement 120
BDAM (basic direct access method) 373 SYSCOPY
bitemporal tables 67 discarding records 446
creating 73 image copies 642
system-period data versioning 73 image copy information 445
blank RECOVER utility 437
column with a field procedure 701 SYSFOREIGNKEYS 121
BMP (batch message processing) program SYSINDEXES
dependent regions dropping tables 186
connecting 328 SYSINDEXPART
bootstrap data set (BSDS) space allocation information 39
high-level qualifier SYSPLANDEP 186
changing 212, 215 SYSRELS
BSAM (basic sequential access method) describes referential constraints 121
archive log data sets SYSROUTINES 124
reading 373 SYSSEQUENCES 126
BSDS (bootstrap data set) SYSSTOGROUP 24
archive log information 395 sample query 116
defining 397 SYSSYNONYMS 185

Index 745
catalog tables (continued) CICS (continued)
SYSTABAUTH DSNC command 234
dropping tables 186 DSNC DISCONNECT command 320
table authorizations 120 dynamic plan selection
updated by CREATE VIEW statement 120 exit routine 714
view authorizations 120 environment
SYSTABLEAPART planning 245
partition order 117 facilities 714
SYSTABLEPART 129 diagnostic traces 360
SYSTABLES indoubt units of recovery 317
rows maintained 116 operating
updated by COMMENT ON statement 126 outstanding indoubt units 424
updated by CREATE VIEW statement 120 terminates AEY9 524
SYSTRIGGERS 125 programming
SYSVIEWDEP applications 245
view dependencies 186 recovery procedures 517
SYSVOLUMES 24 application failures 518
catalog tables, DB2 attachment facility failures 523
image copy 434 CICS not operational 518
catalog, DB2 DB2 connection failures 519
constraint information 123 indoubt units of recovery 520
database design 115, 127 restarting 317
retrieving information from 115 threads
catalogs connecting 318
Db2 two-phase commit 415
DSNDB06 database 445 CICS commands
recovery procedures 579 DSNC DISCONNECT 316
point-in-time recovery 486 DSNC DISPLAY 316
recovering 486, 487 DSNC DISPLAY PLAN 318
CDB (communications database) DSNC DISPLAY TRANSACTION 318
backing up 436 DSNC MODIFY
high-level qualifier ERRDEST option 316
changing 215 DSNC STOP 316
CDDS (compression dictionary data set) DSNC STRT 316, 318
recovering 668 example 317
CHANGE command responses 234
IMS CICS terminal
purging residual recovery entries 321 issuing commands 231
change log inventory utility CLONE keyword 507
bootstrap data set (BSDS) 299 clone tables
BSDS (bootstrap data set) backup and recovery 507
changing 397 creating 81
change number of sessions (CNOS) 591 CNOS (change number of sessions)
CHANGE SUBSYS command failures 591
IMS 327 coding
check constraints exit routines
adding 160 general rules 715
dropping 160 parameters 717
check pending status cold start
retrieving catalog information 122 bypassing the damaged log 538
checkpoint recovery procedures 411
queue 411 special situations 563
checkpoint frequency column
changing 380 retrieving
checkpoints catalog information 118
log records 641, 646 comments 126
CICS column boundaries 718
applications columns
disconnecting 320 adding 145
commands data types
accessing databases 316 altering 147
connecting 317 default values
connecting to Db2 altering 147
authorization IDs 245 dropping 184
connections XML
controlling 316 adding 172
disconnecting from Db2 320

746 Administration Guide

commands control region
DISPLAY BUFFERPOOL 293 IMS 328
issuing from application programs 233 controlling
issuing from CICS terminals 231 CICS connections 320
issuing from IMS terminals 232 conversion procedures
issuing from TSO consoles 230 expected output 697
issuing from z/OS console 229 invoking 696
prefix 229 overview 695
START Db2 229 parameter list 696
START FUNCTION SPECIFIC 295 specifying 695
COMMENT ON statement coordinator
examples 126 multi-site updates 417
storing 126 copy pools 34
commit SMS construct 33
two-phase process 415 COPY utility 48, 494
common SQL API backing up 506
XML message documents 731 data
communications failure copying 455
scenarios 627 restoring 506
Complete mode DFSMSdss concurrent copy 458, 481
common SQL API 729 copying
compression dictionary data set (CDDS) Db2 subsystems 220
recovering 668 relational databases 220
conditional restart correlation IDs 334
control record CICS 520
backward log recovery failures 559 duplicates 323, 520
current status rebuild failures 550 IMS 323
forward log recovery failures 557 outstanding unit of recovery 402
log initialization failures 550 RECOVER INDOUBT command 326
wrap-around queue 411 TSO connections 313
excessive loss of active log data 565 CREATE AUXILIARY TABLE statement 89
multiple systems 422 CREATE DATABASE statement 21
overview 407 CREATE FUNCTION statement 101
performing 410 CREATE GLOBAL TEMPORARY TABLE statement
total loss of log 564 distinctions from base tables 64
conditional restarts CREATE INDEX statement 47, 89
system-level backups 410 DEFINE NO clause 89
connections USING clause 39
CICS 316 CREATE PROCEDURE statement 100
controlling 313 CREATE STOGROUP statement 24
controlling IMS 321 VOLUMES('*') attribute 25, 31
Db2 316 CREATE TABLE statement 51, 96
displaying examples 60
IMS activity 329 XML table spaces
IDs creating implicitly 52
identifying a unit of recovery 512 CREATE TABLESPACE statement
message DSNR007I 402 creating explicitly 53
outstanding unit of recovery 402 DEFINE NO clause 25, 53
used by IMS 244 DSSIZE clause 47, 59
information DSSIZE option 40
displaying 340 EA-enabled index spaces 59
lost EA-enabled table spaces 59
on restart 423 LOCKSIZE TABLE clause 48
monitoring 279, 329, 340 NUMPARTS clause 45
consistency partitioned table spaces 47
maintaining 420 segmented table spaces 48
consistency groups 620 SEGSIZE clause 48
continuous operation USING STOGROUP clause 25, 53
data sets created temporary table
recovering 453 distinctions from base tables 64
table spaces created temporary tables 62
recovering 453 creating 63
control interval (CI) 370, 373, 648 CRESTART control statement
sizing 24 indoubt units of recovery
control intervals (CI) resolving 430
reading 669 cron format
UNIX 253

Index 747
current status rebuild data sets (continued)
failure recovery 540 high-level qualifier
phase of restart 402 changing 210
managing 22, 35
access method services 35
D DFSMShsm 31
using DFSMShsm 31
damaged data
with DB2 storage groups 23
renaming data sets 434
migrating 130
data
moving 221
access control
with utilities 222
START Db2 command 239
without utilities 222
backing up 506
naming 38
distributed
partitioned partitioning indexes 36
controlling connections 337
partitioned secondary indexes 36
exchanging 83
partitioned table spaces 36
inconsistencies
recovering 499
resolving 568
using non-Db2 dump 494
loading 93
renaming 450
a single row 96
user-managed 35
multiple rows 97
defining 36
modeling 4
space allocation 134
moving 220
VSAM 647
recovering 393
data sharing environment
restoring 506, 593
RECOVER TOLOGPOINT option 467
point-in-time recovery 460
restarting 406
data availability
data sharing members
maximizing 441
read requests 672
data classes
data types
assigning 40
altering 184
SMS construct 40
implications 149
data compression
specifying 8
log records 641
subtypes
logging 370
altering 183
data consistency
database
maintaining 415
designing
point-in-time recovery 465
using catalog 115
Data Facility Product (DFSMSdfp) 218
implementing a design 127
Data Facility Storage Management Subsystem (DFSMS) 47
database design 3
concurrent copy 458
hash access 19
copying data 458
implementing 21
recovery 458
logical 3
data management
physical 15
automatic 440
database exception table (DBET)
data mirroring 619
log records 647
recovery 619, 622
exception states 642
data pages
image copies 642
changes
database management systems (DBMSs)
control information 644
monitoring 311
data 644
database objects 3
pointers 644
databases
data set
access
damaged 434
controlling 337
data sets
access threads
adding 581, 584
failures 588
backing up
security failure 592
using DFSMS 458
altering 115, 127
copying 455
backing up
Db2-managed
copying data 455
extending 26, 28
backups
extension failures 26
planning 431
nonpartitioned spaces 26
changes
partitioned spaces 26
rollbacks 367
primary space allocation 28
units of recovery 367
recovering 498
controlling 279
secondary space allocation 28, 29, 31
copying 220
deferring allocation 25
creating 21
extending 581

748 Administration Guide

databases (continued) DB2 subsystem (continued)
designing 3 restarting 399, 557
logical data modeling 3 log truncation 544
physical data modeling 3 resolving inconsistencies 551
DL/I restoring 501
loading data 99 starting 553
dropping 22 startup
implementing 21 application defaults module 239
monitoring 283 termination scenario 524
page set control records 647 Db2-defined extents 139
recovering 453 Db2-managed data sets
failure scenarios 573 enlarging 583
planning 431 DB2-managed data sets
RECOVER TOCOPY 465 recovering 498
RECOVER TOLOGPOINT 465 Db2-managed objects
RECOVER TORBA 465 changing 217
starting 280 Db2-managed primary space allocation"
status information 283 status="unchanged">data sets
stopping 290, 291 Db2-managed
work file databases primary space allocation 31
DSNDB07 455 DB2I (Db2 Interactive)
DataRefresher 99 TSO connections 230
date routines DB2I (DB2 Interactive) 243
expected output 694 DBD01 directory table space
invoking 692 quiescing 481
overview 691 recovery information 445
parameter list 693 DDF
specifying 692 stopping 360
Db2 DDF (distributed data facility)
user databases, image copy 434 alerts 357
Db2 catalog failures
DSNDB06 database 445 recovering 586
recovery procedure 579 DDL registration tables
DB2 catalog recovery preparation 436
high-level qualifier DECLARE GLOBAL TEMPORARY TABLE statement
changing 215 distinctions from base tables 64
Db2 commands declared temporary table
commands distinctions from base tables 64
RECOVER INDOUBT 429 declared temporary tables 62
RESET INDOUBT 429 creating 63
responses 234 default database
START DATABASE 280 (DSNDB04) 215
START DB2 238 high-level qualifier
STOP DATABASE 280 changing 215
STOP DDF 358, 359 DEFINE command
Db2 DataPropagator access method services
tables FOR option 35
altering 182 re-creating table spaces 562
Db2 restart recovery 502 TO option 35
Db2 storage groups DELETE CLUSTER command 39
high-level qualifier DELETE command
changing 217 access method services 562
Db2 subsystem deleting
recovering 502, 503, 507 archive log data sets 375
RESTORE SYSTEM utility 508 denormalizing tables 16
recovery 641 dependent regions
starting 237 disconnecting 329
stopping 237, 240, 399, 407 DFSLI000 (IMS language interface module) 244
wait status 239 DFSMS (Data Facility Storage Management Subsystem)
DB2 subsystem archive log data sets 375
abend DFSMSdfp (Data Facility Product) 218
restarting 240 DFSMSdss (Data Set Services) 218
copying 221 DFSMSdss RESTORE command
operating 227 RECOVER utility 33
recovering 501 DFSMShsm
BACKUP SYSTEM utility 506 data classes
RESTORE SYSTEM utility 506 assigning indexes 31

Index 749
DFSMShsm (continued) DISPLAY DDF command 339
data classes (continued) DISPLAY FUNCTION SPECIFIC command 294, 295
assigning table spaces 31 DISPLAY LOCATION command 340
data sets DISPLAY LOG command 382
migrating 31 DISPLAY OASN command
DFSMShsm (Data Facility Hierarchical Storage Manager) IMS 514
advantages 31 displaying RREs 327
archive logs DISPLAY PROCEDURE command
recalling 32 examples 346
BACKUP SYSTEM utility 33 DISPLAY THREAD command 310
backups 440 DETAIL keyword 311
data sets DETAIL option
moving 218 controlling DDF connections 308
FRBACKUP PREPARE command 624 examples 347
recovery 440 IMS threads
DFSMShsm (Hierarchical Storage Manager) displaying 324
HMIGRATE command 218 showing 329
HRECALL command 218 LOCATION option 306, 307, 308
DFSMSsms (DFSMS storage management subsystem) LUWID keyword 309
BACKUP SYSTEM utility 34 output 305
diagnostic information TYPE (INDOUBT) option 520
obtaining 352 DISPLAY UTILITY command
directory log records 641
high-level qualifier DISPLAY WLM command 349
changing 215 distributed data
image copies recovering 432
frequency 438, 439 distributed data facility (DDF)
order of recovery information
I/O errors 579 displaying 339
point-in-time recovery 486 resuming 338
recovering 486, 487 server activity
SYSLGRNX table resuming 338
discarding records 446 starting 337
records log RBA ranges 445 stopping 358
directory, DB2 FORCE option 359
image copy 434 QUIESCE option 358
disability xv suspending 338
disaster recovery distributed environment
archive logs 593, 599 restart conditions 568
data mirroring 619 restarting
essential elements 483 DB2 subsystem 568
image copies 593, 599 DL/I databases
preparation 448 data
remote site recovery 506 loading 99
rolling disaster 619 down-level detection
scenarios 593 controlling 575
system-level backups 593 DSNTIPN panel 575
tracker sites 608 down-level page sets
disk dump and restore recovering 575
considerations 453 DROP statement 22, 88, 101, 102
disk storage TABLESPACE option 134
estimating 102 DROP TABLE statement 185
space requirements 102 DSN
disks command (TSO) 230
archiving 374 command processor 230
requirements 103 DSN command
storage TSO
estimating 103 command processor 246
storage group assignments END subcommand 315
altering 128 TSO applications
DISPLAY BUFFERPOOL command 293 running 244
DISPLAY command DSN1COPY utility 494
IMS data
SUBSYS option 321 restoring 506
DISPLAY DATABASE command 279, 283 log RBA
LPL option 287 resetting 571
SPACENAM option 285

750 Administration Guide

DSN1LOGP utility dual-BSDS mode
examples 547 restoring 397
limitations 571 dynamic plan selection in CICS
log records exit routine. 714
extracting 641
printing 641
lost work
showing 537
E
EA-enabled index spaces 59
output 548
EA-enabled page sets 40
DSNC DISCONNECT command
EA-enabled table spaces 59
CICS 316
edit procedures
DSNC DISPLAY command
changing 183
CICS 316, 318
column boundaries 718
PLAN option 318
overview 683
TRANSACTION option 318
parameter list 685
DSNC MODIFY command
specifying 684
CICS
edit routines 719, 720
ERRDEST option 316
data type values 723
DSNC STOP command
expected output 687
CICS 316
invoking 684
DSNC STRT command
row formats 718
CICS 316, 317, 318
Enterprise Storage Server
DSNCLI (CICS language interface module)
backups 458
CICS applications
entities
running 245
attribute names 7
DSNDB06 database
attributes 7, 8
high-level qualifier
values 8
changing 215
entity normalization 9
DSNDB07 database 455
first normal form 10
data sets
fourth normal form 13
extending 585
second normal form 10
problems
third normal form 11
resolving 485
entity relationships
DSNDEXPL mapping macro 717
business rules 6
DSNDROW mapping macro 724
many-to-many relationships 6
DSNDSLRB mapping macro 669
many-to-one relationships 6
DSNDSLRF mapping macro 675
one-to-many relationships 6
DSNJSLR macro
one-to-one relationships 6
log CLOSE requests 676
error pages
stand-alone sample program 677
displaying 289
DSNJU003 utility
exception status
CRESTART control statement 430
resetting 480
DSNTEJ1S job 92, 93
exit routine 716
DSNTIJIC job
general considerations 715
improving recovery
EXPORT command
inconsistent data 450
access method services 218, 482
DSNTIPA panel
WRITE TO OPER field 372
DSNTIPL panel
BACKOUT DURATION field 408 F
LIMIT BACKOUT field 408 failure symptoms
DSNTIPN panel abend
LEVEL UPDATE FREQ field 575 log problems 557
DSNTIPS panel restart failure 552
DEFER ALL field 408 BSDS (bootstrap data set) 537
RESTART ALL field 408 CICS
DSNZPxxx attachment abends 519
subsystem parameters module task abends 523
specifying 238 waits 518
DSNZPxxx module logs 537
ARCHWTOR option 372 lost information 563
dual logging messages
active log data sets 370 DFH2206 518
archive log data sets 374 DFS555 517
synchronization 371 DSNB207I 573
dual recovery logs 434 DSNJ 561
DSNJ001I 534

Index 751
failure symptoms (continued) GET_SYSTEM_INFO stored procedure
messages (continued) output
DSNJ004I 528 filtering 731
DSNJ100 561 global transactions 425
DSNJ103I 530 GUPI symbols 737
DSNJ105I 527
DSNJ106I 528
DSNJ107 561
DSNJ114I 531
H
hash access 19
DSNM002I 514
altering 175
DSNM005I 516
enabling
DSNM3201I 518
altering tables 173
DSNP007I 581
creating tables 61
DSNP012I 580
size 175
DSNU086I 578, 579
space 175
processing failure 509
heuristic damage 422
subsystem termination 524
Hierarchical Storage Manager (DFSMShsm) 218
fast copy function
history tables 67
Enterprise Storage Server FlashCopy 458
names
RVA SnapShot 458
finding 76
fast log apply
HMIGRATE command
RECOVER utility 452
DFSMShsm (Hierarchical Storage Manager) 218
field procedures
HRECALL command
changing 183
DFSMShsm (Hierarchical Storage Manager) 218
control blocks 701
field-decoding 709
field-definition 699, 705
field-encoding 708 I
information block (FPIB) 703 I/O errors
invoking 700 archive log data sets
overview 698 recovering 531
parameter list 701, 703 catalog 579
specifying 700 directory 579
value descriptor 704 occurrence 395
work area 702 table spaces 578
fixed-length rows 719 ICOPY status
FlashCopy backups clearing 490
incremental 34 identity columns
FlashCopy image copies attributes
creating 457 altering 184
recovery 479 conditional restart 407
FORCE option data
STOP DB2 command 331 loading 94
foreign keys recovering 488
dropping 159 values
format regenerating 487
column 724 IFCID (instrumentation facility component identifier)
row 724 0330 371, 526
forward log recovery identifiers by number
failures 552 0129 658
restart phase 403 0306 659, 664, 667
scenarios 552 IFI (instrumentation facility interface)
FREEPAGE clause log data
segmented table space 48 decompressing 659, 667
reading in GDPS Continuous Availability with zero data
loss environment 664
G log records
reading 657, 658
GDPS Continuous Availability with zero data loss
READA request 657
DB2 setup 664
READS request 657, 658
general-use programming information, described 737
image copies
GET_CONFIG stored procedure
catalog 438, 439
output
directory 438, 439
filtering 731
frequency 438
GET_MESSAGE stored procedure
incremental 438
output
recovery speed 438
filtering 731

752 Administration Guide

image copy index space data sets
data sets, back-level 434 deferred allocation 89
data sets, damaged index spaces
renaming, using access methods services 434 starting 280
DB2 catalog 434 storage
directory 434 allocating 39
user databases 434 with restrictions
IMPORT command starting 281
access method services 218, 562 index-based partitions
IMS redefining 581
connecting to Db2 index-controlled partitioning
attachment facility 328 converting to table-controlled 140
authorization IDs 244 tables
connection IDs 244 creating 79
controlling 321 indexes
dependent regions 328 altered tables
disconnecting applications 331 recovering 478
environment altering 191, 192
planning 244 clustering option 195
indoubt units of recovery 423 varying-length columns 194
language interface module (DFSLI000) columns
link-editing 244 adding 192
loops 514 copying 455
LTERM authorization IDs creating 88
message-driven regions 244 creating implicitly 90
operating defining 89
tracing 360 dropping 195
programming implementing 88
error checking 244 large objects (LOBs) 89
recovery procedures 513, 514, 516 naming 89
indoubt units of recovery 423 overview 19
running programs partitioned table spaces
batch work 244 rebalancing 136
threads 323, 325 recovering 478
waits 514 redefining 195
IMS commands reorganizing 196
CHANGE SUBSYS 321, 327 stopping 290
DISPLAY storage
SUBSYS option 329 allocating 109
DISPLAY OASN 327, 514 estimating 109, 110
DISPLAY SUBSYS 321, 329 structure
LTERM authorization IDs 329 index trees 109
responses 234 leaf pages 109
START REGION 329 root pages 109
START SUBSYS 321 subpages 109
STOP REGION 329 unique
STOP SUBSYS 321, 331 adding columns 193
TRACE SUBSYS 321 version numbers
IMS terminals recycling 155
issuing commands 232 versions 154
IMS threads indoubt threads
displaying 324 information
IMS.PROCLIB library displaying 305
connecting recovering 429
from dependent regions 328 resolving 625
inconsistent data status
identifying 547 resetting 429
recovering 452 indoubt units of recovery 516
indefinite wait condition CICS 520
recovering 591 displaying 325, 333
index IMS 514
catalog information about 119, 121 recovering 326
types inconsistent states 399
primary 121 recovering 334
index entries resolving 425, 430
sequence 89 Resource Recovery Services (RRS) 333

Index 753
informational COPY-pending status LOAD utility
clearing 490 CCSID option 94
INSERT statement 98 data
data moving 218
loading 93 delimited files 94
examples 96, 97 LOG option 490
segmented table spaces 48 segmented table spaces 48
installation storage
macros estimating 107
starting IRLM automatically 302 tables
INSTEAD OF triggers 190 availability 94
integrated catalog facility loading 94
alias names loading
changing 210 data
integrated catalog facility catalog DL/I 99
VVDS (VSAM volume data set) failure sequential data sets 94
recovering 580 tables 93
Interactive System Productivity Facility (ISPF) 243 INSERT statement 98
internal resource lock manager (IRLM) LOAD utility 94
controlling 300 LOB (large object)
IRLM (internal resource lock manager) retrieving catalog information 124
connections LOB table spaces 45
monitoring 301 pending states
diagnostic traces 362 clearing 493
element name recovering 476
global mode 302 LOBs
local mode 302 invalid
failure 509 recovering 577
recovery procedures 509 storage
starting estimating 106
automatically 302 locations
manually 302 displaying 306
starting automatically 238 non-DB2
stopping 302 displaying 307
issuing commands locks
from application programs 233 finding 286
log
archive
J dual
retaining 434
JCL jobs
recovery 434
scheduled execution 277
log activities
stand-alone 672
log capture exit routine 641
K log capture exit routines
key log records
foreign reading 679
catalog information 121 log capture routines
primary overview 711
catalog information 121 specifying 712
keys log CLOSE requests
adding stand-alone 676
foreign 158 log data
parent 158 decompressing 659
unique 158 GDPS Continuous Availability with zero data loss
solution 667
reading 659, 667
L log GET requests
stand-alone 675
language interface modules
log initialization phase
DSNCLI 245
failure recovery 540, 541
large objects (LOBs)
log OPEN requests
indexes 89
stand-alone 673
LCID (log control interval definition) 650
log RBA (relative byte address)
leaf pages 109
converting 386
indexes 109
data sharing environment 388
links
display 679
non-IBM Web sites 738

754 Administration Guide

log RBA (relative byte address) (continued) logs (continued)
non-data sharing environment 389 failure
resetting 388, 389 symptoms 537
log record header (LRH) 649 total loss 563
log record sequence number (LRSN) 641 forward recovery 403
log records implementing 375
active initialization phase 401
gathering 658 keeping
checkpoints 646 duration 392
contents 641 managing 367, 377, 439
control interval definition (LCID) 650 record retrieval 376
creating 370 recovery procedures
data compression 641 active logs 526
extracting 641 archive logs 530
format 650 recovery scenario 561
header 649 restarting 400, 404
interpreting 657 truncation 547
logical 648 lost work
physical 648 identifying 547
printing 641 LRH (log record header) 649
qualifying 661
RBA (relative byte address) 641
reading 641, 657, 658, 669, 679
redo 642
M
mapping macro
relative byte address (RBA) 641
DSNDEXPL 717
segments 648
DSNDROW 724
structure
mapping macros
page set control records 647
DSNDSLRB 669
subtype codes 655
DSNDSLRF 675
type codes 654
materialized query tables
types 641
altering 180
undo 642
attributes
units of recovery 643
altering 181
WQAxxx qualification fields 661
changing
log services
base tables 180
stand-alone 669, 677
creating 78
logging
definitions
implementing 375
altering 181
logging attributes
registering 180
changing 132
media failures
logical data modeling 3
recovering 616
examples 5
message by identifier
recommendations 5
$HASP373 238
logical database design 3
DFS058 322
Unified Modeling Language (UML) 14
DFS058I 331
logical page list (LPL) 287, 288
DFS3602I 516
displaying 287
DFS3613I 322
pages
DFS554I 517
recovering 288
DFS555A 517
removing 288
DFS555I 517
logs
DSN1150I 559
archiving 379
DSN1151I 513
backward recovery 404
DSN1157I 547, 559
BSDS (bootstrap data set) inventory
DSN1160I 547, 559
altering 397
DSN1162I 513, 547, 559
buffer
DSN1213I 567
retrieving log records 376
DSN2001I 520
displaying
DSN2025I 524
DISPLAY LOG command 382
DSN2034I 520
print log map utility 382
DSN2035I 520
dual
DSN2036I 520
archive logs 395
DSN3100I 237, 240, 524
minimizing restart efforts 561
DSN3104I 240, 524
synchronization 371
DSN3201I 518
establishing hierarchy 369
DSN9032I 337
excessive loss 563
DSNB204I 573
DSNB207I 573

Index 755
message by identifier (continued) message by identifier (continued)
DSNB232I 575 DSNM002I 329, 331, 514, 524
DSNC016I 424 DSNM003I 322, 329
DSNI006I 288 DSNM004I 423, 514
DSNI021I 288 DSNM005I 327, 423, 516
DSNI022I 288 DSNP001I 581
DSNI051I 288 DSNP007I 581
DSNJ001I 238, 372, 401, 537, 540 DSNP012I 580
DSNJ002I 372 DSNR001I 238
DSNJ003I 372, 535 DSNR002I 238, 537
DSNJ004I 372, 528 DSNR003I 238, 393, 513, 556, 559
DSNJ005I 372 DSNR004I 238, 402, 403, 537, 540, 552
DSNJ007I 544, 553 DSNR005I 238, 403, 537, 540, 557
DSNJ008E 372 DSNR006I 238, 404, 537
DSNJ012I 544, 553 DSNR007I 238, 402, 403
DSNJ072E 375 DSNR031I 403
DSNJ099I 238 DSNT360I 283, 285, 286, 289
DSNJ100I 533, 534, 537, 561 DSNT361I 283, 285, 286, 289, 642
DSNJ103I 530, 544, 553 DSNT362I 283, 285, 286, 289
DSNJ104I 530, 544, 553 DSNT397I 285, 286, 289
DSNJ105I 527 DSNU086I 578, 579
DSNJ106I 528, 544, 553 DSNU561I 585
DSNJ107I 533, 537, 561 DSNU563I 585
DSNJ108I 533 DSNV086E 524
DSNJ110E 371, 526 DSNV400I 377
DSNJ111E 371, 526 DSNV401I 313, 325, 326, 377, 520
DSNJ113E 544, 553, 560 DSNV402I 306, 329, 377
DSNJ114I 531 DSNV406I 325, 326, 520
DSNJ115I 530 DSNV408I 326, 334, 413, 520
DSNJ1191 537 DSNV414I 326, 334, 520
DSNJ119I 561 DSNV415I 326, 334, 520
DSNJ120I 401, 533, 534 DSNX940I 346
DSNJ124I 528 DSNY001I 238
DSNJ125I 397 DSNY002I 240
DSNJ126I 533 DSNZ002I 238
DSNJ127I 238 DXR105E 302
DSNJ128I 532 DXR117I 302
DSNJ130I 401 DXR1211 302
DSNJ139I 372 DXR122E 509
DSNJ311E 377 DXR1651 302
DSNJ312I 377 EDC3009I 580
DSNJ317I 377 IEC161I 573
DSNJ318I 377 message processing program (MPP)
DSNJ319I 377 connections 328
DSNL001I 337 messages
DSNL002I 359 CICS 235
DSNL003I 337 route codes 234
DSNL004I 337 unsolicited 235
DSNL005I 359 MIGRATE command
DSNL006I 359 DFSMShsm (Hierarchical Storage Manager) 218
DSNL009I 344 modeling
DSNL010I 344 data 4
DSNL030I 592 MODIFY utility
DSNL080I 339 image copies
DSNL200I 340 retaining 450
DSNL432I 359 moving
DSNL433I 359 data 220
DSNL500I 591 tools 218
DSNL501I 586, 591 data sets 221
DSNL502I 586, 591 with utilities 222
DSNL700I 587 without utilities 222
DSNL701I 588 MPP (message processing program)
DSNL702I 588 connections 328
DSNL703I 588 multi-site updates 417
DSNL704I 588 examples 418
DSNL705I 588 multiple systems
DSNM001I 322, 329 conditional restart 422

756 Administration Guide

N page sizes
calculating 105
NetView pages
monitoring errors 356 errors 287
network ID (NID) index size 109
CICS 520 information
IMS 323, 514 obtaining 287
NID (network ID) number of records 105
CICS 520 root 109
IMS 514 parent keys
thread identification 323 dropping 159
non-data sharing environment partial recovery 465
RECOVER TOLOGPOINT option 470 participants
non-UTS table spaces multi-site updates 417
partitioned 47 partition order
segmented 48 retrieving
NOT LOGGED attribute 132 catalog information 117
table spaces 133 partition size
null value increasing 137
effect on storage space 719 partition-by-growth table spaces 44
numeric data 725 recovering 478
partition-by-range 43
partition-by-range table spaces 43
O partitioned (non-UTS) table spaces 47
objects partitioned table spaces
dropped partition size
recovering 494 increasing 137
dropping recovering 476
avoiding 495 recovering indexes
information COPY utility 479
displaying 285 RECOVER utility 479
not logged partitioned tables
recovering 489 creating 79
XML partitioning columns
altering implicitly 209 nullable 80
offloading partitioning methods
active logs 371 differences 79
canceling 392 partitions
interruptions 373 adding 161
messages 372 altering 164
quiescing 377 boundaries
restarting 392 changing 164
status extending 168
DISPLAY LOG command 392 truncating 169
trigger events 371 index-controlled
offloads redefining 581
canceling 379 inserting rows 172
operating environments rebalancing with REORG 136
CICS 245 redefining
IMS 244 index-based partitioning 584, 585
originating sequence number (OASN) 323 redistributing 136
indoubt units of recovery 514 rotating 166
table-controlled
redefining 581
P PBR table spaces 43
pending definition changes
packages materializing 200, 472
invalidated periods
dropping a table 185 application 67
dropping a view 189 system 67
dropping an index 195 phases of execution
page errors restart 400
logical 287 physical data modeling 3
physical 287 physical database design 15
page sets plan selection exit routine
altering 139 description 714
control records 647 writing 714
copying 455

Index 757
point of consistency 367 RECOVER TOLOGPOINT option
IMS 415 data sharing environment 467
multiple system 415 non-data sharing environment 470
point-in-time recovery 460, 465, 501 RECOVER utility 464, 624
catalog 486 catalog tables 486
data consistency 465 data inconsistency 450
Db2 subsystem 574 deferred objects 407
directory 486 DFSMS concurrent copies 458
planning 461 DFSMSdss RESTORE command 33
RECOVER utility 464 directory tables 486
postponed units of recovery DSNDB07 database 485
resolving 412 fast log apply 452
postponed-abort unit of recovery 420 functions 453
prefix messages 453
command 229 object-level recoveries 459
primary space allocation objects 453
examples 31 options
PRINT command TOCOPY 465
access method services 494 TOLOGPOINT 465, 512
print log map utility 382, 393 TORBA 465
before fall back 562 recovery cycle 613
bootstrap data set (BSDS) contents 299 restrictions 455
prior point of consistency running in parallel 452
recovery procedures 480 segmented table spaces 48
product-sensitive programming information, described 737 RECOVER-pending status
profiles clearing 491
setting special register values 363 recovery
programming interface information, described 737 acceleration tables and indexes
PSB name planning 432
IMS 244 application changes
PSPI symbols 737 backing out 512
PSTOP transaction type 328 backward log recovery failures 558
BSDS (bootstrap data set) 535
catalog 486, 487
Q catalog definitions
consistency 503
QMF-related failures 523
communications failure 627
QSAM (queued sequential access method) 373
compressed data 472
queued sequential access method (QSAM) 373
data
QUIESCE option
moving 474
STOP DB2 command 331
data availability
maximizing 441
data sets 499
R Db2-managed 498
range-partitioned universal table spaces 43 DFSMS 458
RBA (relative byte address) DFSMShsm 440
range in messages 372 non-DB2 dump and restore 494
RDO (resource definition online) databases
MSGQUEUE attribute 235 active logs 641
STATSQUEUE attribute 235 backup copies 436
REBUILD-pending status RECOVER TOCOPY 465
for indexes 433 RECOVER TOLOGPOINT 465
RECORDING MAX field RECOVER TORBA 465
panel DSNTIPA Db2 outages
preventing frequent BSDS wrapping 560 cold start 632
records Db2 subsystem 565, 574
performance 105 DB2 subsystem 641
size DDF (distributed data facility) failures 586
calculating 105 directory 486
RECOVER BSDS command disk failures 510
copying BSDS 397 distributed data
RECOVER INDOUBT command 334, 429 planning 432
free locked resources 520 down-level page sets 575
RECOVER TABLESPACE utility FlashCopy image copies 479
modified data FlashCopy volume backups 503
recovering 562 heuristic decisions
correcting 638

758 Administration Guide

recovery (continued) recovery procedures (continued)
implications 489 Db2-related failures
IMS outage with cold start active log failures 526
scenario 631 archive log failures 530
IMS-related failures BSDS (bootstrap data set) 533
during indoubt resolution 516 catalog or directory I/O errors 579
indoubt units of recovery 514 database failures 573
inconsistent data 452 subsystem termination 524
resolving 557 table space I/O errors 578
indexes 433 IMS-related failures 512
indexes on tables application failures 517
partitioned table spaces 479 control region failures 514
indoubt threads 625 integrated catalog facility catalog
indoubt units of recovery VVDS failure 581
CICS 520 IRLM failures 509
IMS 326 out-of-disk-space 581
information QMF-related failures 523
reporting 446 restart 537
integrated catalog facility catalog VTAM ACB OPEN failures 589
VVDS failure 580 z/OS failures 509
invalid LOBs 577 z/OS power failures 509
LOB table spaces 476 recovery scenarios
logs Db2 cold start 636
truncating 544 failures
lost status information 549 current status rebuild phase 540
media 453 log initialization phase 540
multiple systems environment 421 heuristic decisions
objects making 629
dropped 494 referential constraint
identifying 480 existing tables
operations 437 adding 156
outages violation
minimizing 441 recovering 585
planning 461 referential structure
point in time 465, 574 consistency
prior point in time 460 maintaining 450
prior point of consistency 480 referential structures 434
procedures 509 registers 672
reducing time 438 relational databases
restart 482 copying 221
scenarios 632 relative byte address (RBA) 372, 679
segmented table spaces 476 REMARKS column
table spaces 578 SYSTABLES catalog table 116
COPY utility 494 remote DBMS (database management system)
dropped 497 indoubt units of recovery
DSN1COPY utility 494 resolving 428
point in time 481 remote logical units
QUIESCE 481 failures 591
RECOVER TOCOPY 465 renaming damaged Db2 data sets 434
RECOVER TOLOGPOINT 465 reordered row format 721
RECOVER TORBA 465 REORG TABLESPACE utility
work file 486 examples
tables 495 rebalancing partitions 136
temporary resource failures 525 REBALANCE option 136
work file table spaces 486 rebalancing partitions 136
XML table spaces 476 redistributing partitions 136
recovery cycle REORG utility
RECOVER utility 613 data
RECOVERY option moving 218
REPORT utility 512 examples 182
recovery procedures 581 LOG option 490
application program errors 512 segmented table spaces 48
CICS-related failures UNLOAD EXTERNAL 218
application failures 518 REPAIR utility
attachment facility failures 523 inconsistent data
indoubt units of recovery 520 resolving 571
not operational 518

Index 759
REPORT utility RESTORE SYSTEM utility (continued)
options Db2 subsystem
RECOVERY 512 recovering 506
TABLESPACESET 512 restoring
table spaces data 460
recovering 446 databases 501
REPRO command Db2 subsystem 501
access method services 494, 535 return areas
RESET INDOUBT command 429 specifying 660
residual recovery entry (RRE) 327 return codes 672
resource definition online (RDO) 235 RFMTTYPE
STATUSQUEUE attribute 316 BRF 721
resource limit facility RRF 721
recovery preparation 436 rolling disaster 619
resource managers root pages 109
indoubt units of recovery indexes 109
resolving 425 routines
Resource Recovery Services (RRS) conversion procedures 695, 696, 697
abend 333 date routines 691, 692, 693, 694
connections edit routines 684, 687
controlling 332 field procedures 698, 699, 700, 701, 702, 703, 704, 705, 708,
indoubt units of recovery 333 709
postponed units of recovery 335 log capture routines 711
Resource Recovery Services attachment facility (RRSAF) time routines 691, 692, 693, 694
connections validation routines 687, 688, 689, 690
displaying 335 writing 683
monitoring 335 row format conversion
disconnecting 336 table spaces 722
resource translation table (RTT) 328 row formats 719, 720
restart 407 ROWID column
automatic 405 data
backward log recovery loading 94
failure during 557 inserting 98
phase 404 rows
BSDS (bootstrap data set) problems 561 formats for exit routines 718
cold start situations 563 incomplete 690
conditional RRDF (Remote Recovery Data Facility)
control record governs 407 tables
excessive loss of active log data 565 altering 182
total loss of log 564 RRE (residual recovery entry)
current status rebuild phase 402 detecting 327
failure recovery 540 logged at IMS checkpoint 423
forward log recovery phase 403 not resolved 423
failure during 552 purging 327
implications RRSAF (Resource Recovery Services attachment facility)
table spaces 406 application programs
inconsistencies running 248
resolving 567 RTT (resource translation table)
log data set problems 561 transaction types 328
log initialization phase 401 RVA (RAMAC Virtual Array)
failure recovery 540 backups 458
lost connections 423
multiple-system environment 421
normal 400
recovery 411
S
sample library 93
recovery preparation 482
scheduled tasks
restart processing
adding 249
deferring 408
defining 251
limiting 553
listing 255
restarting
removing 258
Db2 subsystem 399, 408
status
RESTORE phase
listing 255
RECOVER utility 453
multiple executions 256
RESTORE SYSTEM
stopping 258
recovery cycle
updating 258
establishing 611
schema definition
RESTORE SYSTEM utility 33, 501, 508
authorization 93

760 Administration Guide

schema definition (continued) START DB2 command
processing 93 data access
schemas restricting 239
creating 92 issuing
implementing 91 from z/OS console 237
processing 92 modes 331
authorization 92 PARM option 238
processor 92 restarting 407
SDSNLOAD library START DDF command 337
loading 328 START FUNCTION SPECIFIC command 294, 295
SDSNSAMP library START REGION command
schema definitions IMS 329
processing 93 START SUBSYS command
secondary space allocation IMS 321
examples 31 START TRACE command 361, 658
segmented table spaces starting
characteristics 48 Db2 553
defining 48 STOP DATABASE command 279, 290
EA-enabled index spaces 47, 59 DSNDB07 database 485
EA-enabled table spaces 47, 59 examples 291
implementing 48 SPACENAM option 280
recovering 476 STOP DB2 command 240
SELECT statement FORCE option 331, 407
example QUIESCE option 407
SYSIBM.SYSCOLUMNS 118 STOP DDF command 358
SYSIBM.SYSINDEXES 119 FORCE option 359
SYSIBM.SYSTABAUTH 120 MODE(SUSPEND) option 338
SYSIBM.SYSTABLEPART 117 QUIESCE option 358
SYSIBM.SYSTABLES 116, 126 STOP FUNCTION SPECIFIC command 294, 296
examples 129 STOP REGION command
SYSIBM.SYSPLANDEP 186 IMS 329
SYSIBM.SYSVIEWDEP 186 STOP SUBSYS command
sequence IMS 321, 331
catalog information 126 STOP TRACE command 361
shortcut keys STOP transaction type 328
keyboard xv STOP-pending (STOPP) status 290
SIGNON-ID option storage
IMS 244 allocating
simple table spaces 50 for indexes 109
SMS (Storage Management Subsystem) 375 for tables 105
solid-state drive (SSD) LOBs 106
migrating 130 managing
space DFSMShsm 31
allocating reclaiming 185
for tables 35 storage group, DB2
space attributes 131 retrieving catalog information 116
specifying 161 storage groups
SPUFI advantages 23
disconnecting 315 altering 128
SQL statements changing 128
ADD ORGANIZE BY HASH clause 173 control interval (CI) sizing 24
ALTER TABLE 173 creating 24
canceling 343 implementing 22
CREATE TABLE managing 23
ORGANIZE BY HASH clause 61 SMS 25
SQL transaction with SMS 128
unit of recovery 367 volumes
SSM (subsystem member) adding 128, 129
error options 328 removing 129
specifying Storage Management Subsystem (SMS) 47
on EXEC parameter 328 archive log data sets 375
START DATABASE command 279 stored procedures
DSNDB07 database 485 administration 727
examples 280 altering 207
FORCE option 281 common SQL API 727
SPACENAM option 280 Complete mode 729
XML input documents 729

Index 761
stored procedures (continued) system-period data versioning (continued)
common SQL API (continued) restrictions 69
XML output documents 730 temporal tables 69
XML parameter documents 728 system-period temporal tables 67
creating 100 altering 179
debugging 352 creating 69, 176
diagnostic information 352 querying 77
displaying recovering 508
statistics 346 system-wide points of consistency 449
thread information 347
dropping 101
external
migrating 354
T
table
external SQL
creating
migrating 354
description 64
GET_CONFIG
retrieving
filtering output 731
catalog information 116
GET_MESSAGE
comments 126
filtering output 731
types 64
GET_SYSTEM_INFO
table check constraint
filtering output 731
catalog information 123
implementing 99
table space set
information
recovering 477
displaying 346
table spaces
migrating 353
altering 131, 200, 472
monitoring 345
copying 455
native SQL
creating
migrating 354
explicitly 53
prioritizing 362
data
scheduling 275
loading 93
SQLCODE -430 732
rebalancing 136
troubleshooting 732
defining
subsystem member (SSM) 328
implicitly 51
subsystem parameters
dropping 134
CATALOG 375
EA-enabled 40
SVOLARC 375
implementing 41
SVOLARC subsystem parameter 375
large object 45
syntax diagram
logging attribute 490
how to read xv
not logged 406
SYS1.LOGREC data set 524
NOT LOGGED attribute 133
SYS1.PARMLIB library
partition-by-growth (UTS) 44
IRLM
partition-by-range 43
specifying 300
partitioned
SYSCOPY
increasing partition size 137
catalog table records
partitioned (non-UTS) 47
retaining 446
quiescing 481
SYSIBMADM.MOVE_TO_ARCHIVE global variable
re-creating 134
effect 83
recovering 475, 489, 497, 578
SYSLGRNX directory table
reordered row format
REPORT utility information 446
converting 721, 722
table space records
reorganizing 151
retaining 446
restoring 570
SYSSYNONYMS catalog table 185
row format
SYSTABLES catalog table 185
converting 722
system checkpoints
schema changes
monitoring 381
applying 151
system period 67
segmented
adding 176
defining 48
system-level backups 462
EA-enabled index spaces 59
conditional restarts 410
EA-enabled table spaces 59
data
simple 50
moving 474
starting 280
disaster recovery 593
stopping 290
object-level recoveries 459
types 41
system-period data versioning 67
version numbers
bitemporal tables 73
recycling 153
defining 176
versions 151, 152

762 Administration Guide

table spaces (continued) takeover site
XML 46, 52 setting 616, 617
table-based partitions tapes
redefining 581 archiving 374
table-controlled partitioning TCP/IP
converting from index controlled 140 failure recovery 590
nullable partitioning columns 80 temporal tables 67
tables altering 179
creating 79 bitemporal 67
tables creating 67, 69
altered application period 72
recovering indexes 478 periods 67
altering 144 querying 77
application period 178 recovering 508
columns 145 system-period data versioning 69
system period 176 temporary tables
application-period temporal 67 created
bitemporal 67 creating 63
changes creating 62
capturing 182 types 62
check constraints TERM UTILITY command 435
adding 160 restrictions 452
dropping 160 terminal monitor program (TMP) 246
clone terminating
creating 81 Db2
creating 60 scenarios 524
data Db2 subsystem 399
exchanging 83 normal restart 400
dropping DB2 subsystem
implications 185 abend 400
history 67 multiple systems 419
identity column values termination
regenerating 487 types 399
identity columns threads
recovering 488 allied 337
implementing 59 attachment in IMS 323
inserting canceling 344
a single row 96 CICS 318
multiple rows 97 displaying 318
loading 93 conversation-level information
considerations 98 displaying 308
INSERT statement 96 database access 337
LOAD utility 94 displaying 309, 310
naming guidelines 60 IMS 329
page sizes indoubt
altering 188 displaying 305
moving 188 monitoring 303, 318
populating 93 termination
re-creating 187 CICS 316
recovering 495 IMS 325, 331
rows types
validating 181 active allied 304
space active database access 304
allocating 35 pooled database access 304
storage time routines
allocating 105 expected output 694
estimating 105 invoking 692
system-period temporal 67 overview 691
temporal 67 parameter list 693
XML columns specifying 692
adding 172 TMP (terminal monitor program)
tables spaces DSN command processor 230
with restrictions sample job 246
starting 281 TSO batch work 246
TABLESPACESET option TOCOPY option
REPORT utility 512 RECOVER utility 465

Index 763
TOLOGPOINT option two-phase commit (continued)
RECOVER utility 465 process 415
TORBA option
RECOVER utility 465
TRACE SUBSYS command
IMS 321
U
UDF
traces
catalog information 124
controlling 360, 361
Unified Modeling Language (UML) 14
IMS 360
unit of recovery ID (URID) 650
diagnostic
units of recovery
CICS 360
in-abort 420
IRLM 362
backward log recovery 404
tracker site 608
excluded in forward log recovery 403
characteristics 608
in-commit 420
converting
included in forward log recovery 403
takeover site 616, 617
indoubt 240, 420
disaster recovery 608
CICS 520
maintaining 616
displaying 325
migrating to Db2 11 conversion mode 610
IMS 514
recovering
included in forward log recovery 403
RECOVER utility 617
inconsistent states 399
RESTORE SYSTEM utility 617
recovering 334
recovery cycle
recovering IMS 326
RESTORE SYSTEM utility 611
resolving 423, 424, 425
setting up 609
inflight 420
transaction managers
backward log recovery 404
distributed transactions
excluded in forward log recovery 403
recovering 425
log records 642, 643
transactions
overview 367
CICS
postponed
accessing 318
displaying 326, 335
entering 245
postponed-abort 420
IMS 244
Resource Recovery Services (RRS) 335
connecting to Db2 321
rollbacks 420
thread attachment 323
rolling back 368
thread termination 325
SQL transactions 367
types 328
units of work
trigger
status
catalog information 125
determining 428
troubleshooting
universal table space
QMF-related failures 523
partition-by-growth 44
stored procedures 732
UNIX
truncation
cron format 253
active logs 371, 547
UNLOAD utility
TSO
delimited files 94
application programs
URID (unit of recovery ID) 650
conditions 244
user-defined data sets
running 244
extending 582
background execution 246
volumes
connections
adding 582
controlling 313
user-defined functions
disconnecting 315
altering 208
monitoring 313
controlling 294
DSNELI language interface module
creating 101
link editing 244
dropping 102
TSO commands
implementing 101
DSN 230
monitoring 295
END subcommand 315
starting 295
TSO connections
stopping 296
monitoring 313
user-managed data sets
TSO consoles
data classes
issuing commands 230
specifying 40
two-phase commit
deleting 39
CICS 415
enlarging 583
coordinator 415
extending 39
IMS 415
high-level qualifier
participants 415
changing 217

764 Administration Guide

user-managed data sets (continued) VSAM (virtual storage access method) (continued)
name format 36 control interval (CI) (continued)
requirements 36 log records 370
utilities processing 494
online VSAM volume data set (VVDS) 581
changing 298 recovering 580
controlling 297 VTAM
monitoring 298 failures
starting 297 recovering 589
running 288 VTAM ACB OPEN)
stand-alone 299 failure 589
controlling 297, 298 VTAM)
utility jobs recovery procedures 589
running VVDS (VSAM volume data set)
recovery procedures 606 recovering 580
UTS table space
partition-by-growth 44
UTS table spaces
partition-by-range 43
W
wait status
ending 239
WebSphere Application Server
V indoubt units of recovery 425
validation procedures WLM application environment
column boundaries 718 quiescing 349
validation routines 719, 720 refreshing 349
assignments restarting 349
altering 181 startup procedures 349
data type values 723 stopping 349
expected output 690 WLM_REFRESH stored procedure 349
incomplete 690 work
invoking 688 submitting 243
overview 687 work file database
parameter list 689 starting 280
row formats 718 work file databases
rows changing high-level qualifier 215
checking 181 migrated installation 216
specifying 688 new installation 215
VARY WLM command 349 data sets
version numbers enlarging 585
recycling 155 enlarging 581
view extending 585
using troubleshooting 455
adding comments 126 work file table spaces
retrieving catalog information 119 error ranges
retrieving comments 126 recovering 486
views write error page range (WEPR) 287
altering 189
INSTEAD OF triggers 190
creating 84
data change operations
X
XML columns
period clauses 190
adding 172
dependent objects 186
data
dropping 88, 189
loading 94
INSTEAD OF triggers 190
XML input documents
implementing 84
common SQL API 729
names 86
versioning 728
overview 18
XML message documents
period specifications 86, 190
versioning 728
querying
XML objects
period specifications 86
altering
updating 87
implicitly 209
period clauses 190
XML output documents
virtual storage access method (VSAM) 370
common SQL API 730
volume serial numbers 395
versioning 728
VSAM (virtual storage access method)
XML parameter documents
control interval (CI)
versioning 728
block size 373

Index 765
XML table spaces 46
creating implicitly 52
pending states
removing 493
recovering 476
XRC (Extended Remote Copy) 625
XRF (extended recovery facility)
CICS toleration 433
IMS toleration 433

Z
z/OS
commands
DISPLAY WLM 349
power failure
recovering 509
restart function 405
z/OS abend
IEC030I 532
IEC031I 532
IEC032I 532
z/OS commands
MODIFY irlmproc 300, 301, 302
MODIFY irlmproc,ABEND 302
START irlmproc 300, 302
STOP irlmproc 300, 302
TRACE 300
z/OS console
issuing commands to Db2 229

766 Administration Guide

IBM®

Product Number: 5615-DB2

5697-P43

Printed in USA

SC19-4050-07
Spine information:

Db2 11 for z/OS Administration Guide

IBM