IBM IMS High Performance Unload for z/OS

Users Guide
V ersion 1 Release 2

SC27-0936-06

IBM IMS High Performance Unload for z/OS

Users Guide
V ersion 1 Release 2

SC27-0936-06

Note Before using this information and the product it supports, read the information in Notices on page 483.

This edition applies to Release 2 of IMS High Performance Unload for z/OS (5655-E06) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC27-0936-05. Copyright International Business Machines Corporation 2000, 2007. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix About this information . . . . . . . Service updates and support information . Conventions used in this book . . . . . How to look up message explanations . . Searching an information center . . . Using a Web search . . . . . . . Using LookAt . . . . . . . . . . How to send your comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi . xxii . xxii . xxiii . xxiii . xxiii . xxiii . xxiv

Part 1. Using High Performance Unload . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Introduction . . . . . . . . . . . Terminology . . . . . . . . . . . . . . . . Summary of changes . . . . . . . . . . . . SC27-0936-06October 2007 . . . . . . . . SC27-0936-05January 2007 . . . . . . . . SC27-0936-04October 2005 . . . . . . . . SC27-0936-03November 2004 . . . . . . . SC27-0936-01 and SC27-0936-02January 2003 . SC27-0936-00November 2000 . . . . . . . Program functions . . . . . . . . . . . . . . Major features and benefits . . . . . . . . . Database organizations supported . . . . . . . System structure and data flow . . . . . . . . . Processing environment . . . . . . . . . . . Software requirements . . . . . . . . . . . Hardware requirements . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . Compatibility with prior products . . . . . . . . Publications and updates . . . . . . . . . . . High Performance Unload information on the Web . Receiving updates automatically . . . . . . . Prerequisite knowledge . . . . . . . . . . . How this information should be read . . . . . . Accessibility features for High Performance Unload . Accessibility features . . . . . . . . . . . . Keyboard navigation . . . . . . . . . . . . IBM and accessibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 11 12 12 12 13 13 14 15 15 15 16 16 18 18 18 18 18 18 18 19 19 19 20 20 20 20 21 21 25 25 25 26

Chapter 2. Job control language. . . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . Supported IMS region types and cataloged procedures . . Selecting region types . . . . . . . . . . . . . Modifying the DL/I JCL for High Performance Unload . . Parameters required by the IMS DBRC SCI registration .

Chapter 3. Using the Unload utilities . . . . . . . . . . . . . . . . 27 Program structure . . . . . . . . . . . . . . . . . . . . . . . . 27 FABHURG1 program structure . . . . . . . . . . . . . . . . . . 27
Copyright IBM Corp. 2000, 2007

iii

FABHFSU program structure . . . . . . . . . . Functions available in both Unload utilities . . . . . . Selecting an Unload utility for your use . . . . . . . FABHURG1 functions not available in FABHFSU . . FABHFSU functions not available in FABHURG1 . . Which Unload utility should be used . . . . . . . Restrictions common to FABHURG1 and FABHFSU . . Considerations . . . . . . . . . . . . . . . . For a logical parents concatenated key . . . . . . For an unloaded data set used for reorganization . . For database sharing . . . . . . . . . . . . For HALDB Online Reorganization capable partitions . For using a secondary index . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27 28 29 29 29 29 29 30 30 30 31 31 32 33 33 33 34 34 35 35 35 36 37 38 38 40 40 40 41 41 41 42 43 43 44 44 45 45 45 46 46 46 46 46 47 47 48 49 49 50 50 50 51 51

Chapter 4. Using FABHURG1 to unload IMS databases . Program functions and benefits . . . . . . . . . . . Program structure . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . Operating instructions . . . . . . . . . . . . . . Selecting a format for the unload output. . . . . . . . *HD format . . . . . . . . . . . . . . . . . *F1 format . . . . . . . . . . . . . . . . . *F2 format . . . . . . . . . . . . . . . . . *F3 format . . . . . . . . . . . . . . . . . *CS format . . . . . . . . . . . . . . . . . JCL requirements for FABHURG1 . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . . SYSIN data set . . . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . PCB control statement . . . . . . . . . . . . FRMT control statement . . . . . . . . . . . DEC control statement . . . . . . . . . . . . PARTITION control statement . . . . . . . . . SEGSTAT control statement . . . . . . . . . . CHECKREC control statement . . . . . . . . . MIGRATE control statement . . . . . . . . . . FALLBACK control statement . . . . . . . . . HSSROPT data set . . . . . . . . . . . . . . HSSRCABP data set. . . . . . . . . . . . . . OutputSYSPRINT data set . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . FABHURG1 Unload Parameters report . . . . . . . FABHURG1 Segment Statistics report . . . . . . . Examples . . . . . . . . . . . . . . . . . . . Example 1: Running FABHURG1 in ULU region . . . . Example 2: Running FABHURG1 in DLI region . . . . Chapter 5. Using FABHFSU to unload IMS databases Program functions and benefits . . . . . . . . . . Program structure . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . Operating instructions . . . . . . . . . . . . . Selecting a format for the unload output. . . . . . . HS format . . . . . . . . . . . . . . . . . . . . . . . .

iv

Users Guide

| |

UL format . . . . . . . . . . . . . . . . . . . . . VB format . . . . . . . . . . . . . . . . . . . . . VN format . . . . . . . . . . . . . . . . . . . . . JCL requirements for FABHFSU . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . . . . . CARDIN data set . . . . . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . DBD control statement . . . . . . . . . . . . . . . PSB control statement . . . . . . . . . . . . . . . DEC control statement . . . . . . . . . . . . . . . GOT control statement . . . . . . . . . . . . . . . PARTITION control statement . . . . . . . . . . . . SEGSTAT control statement . . . . . . . . . . . . . BLM/ELM control statements . . . . . . . . . . . . . END control statement . . . . . . . . . . . . . . . HSSROPT data set . . . . . . . . . . . . . . . . . HSSRCABP data set. . . . . . . . . . . . . . . . . OutputPRNTOUT data set . . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . FABHFSU Control Statements report . . . . . . . . . . . FABHFSU Control Specifications report . . . . . . . . . . FABHFSU Segment Statistics report . . . . . . . . . . . User exit . . . . . . . . . . . . . . . . . . . . . . Attributes of the routine . . . . . . . . . . . . . . . . Link-editing the routine . . . . . . . . . . . . . . . Loading the routine . . . . . . . . . . . . . . . . Information passed to the exit routine . . . . . . . . . . Segment prefix area . . . . . . . . . . . . . . . . Segment table (SGTBL) . . . . . . . . . . . . . . Using the key area . . . . . . . . . . . . . . . . Modifying segments in user exits . . . . . . . . . . . Activating the routine. . . . . . . . . . . . . . . . . Initialization and termination processing in the exit routine . . . Communicating with main logic . . . . . . . . . . . . . Contents of registers on entry . . . . . . . . . . . . Contents of registers on exit . . . . . . . . . . . . . Writing a user exit routine in COBOL . . . . . . . . . . . Enterprise COBOL, COBOL for OS/390, COBOL for MVS, and COBOL/370 . . . . . . . . . . . . . . . . . . VS COBOL II . . . . . . . . . . . . . . . . . . Writing a user exit routine in PL/I . . . . . . . . . . . . Sample exit routines . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Running FABHFSU in ULU region . . . . . . . Example 2: Running FABHFSU in the DLI region . . . . . . Chapter 6. Application programming interface What is High Performance Unload API? . . . . HSSR PCB requirements . . . . . . . . . PCB statement requirements . . . . . . . Processing option (PROCOPT) requirements . SENSEG statement requirements . . . . . HSSR PCB feedback information . . . . . . Interpreting PCB feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

51 53 54 54 56 56 56 57 57 58 62 63 63 64 65 66 67 67 67 67 67 67 68 69 71 71 71 72 72 72 73 74 74 75 75 76 76 77 78 78 78 79 79 79 80 80 83 83 84 84 84 85 85 85

Contents

| | | |

Status codes. . . . . . . . . . . . . . . . . . . . . . . DL/I calls or EXEC DLI command for HSSR PCB . . . . . . . . . . DL/I calls supported by each API set . . . . . . . . . . . . . . EXEC DLI commands supported by each API set . . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . . . . . . . Consideration for DB2 DL/I Batch interface . . . . . . . . . . . . Features of DB2 DL/I Batch support . . . . . . . . . . . . . . Program design considerations . . . . . . . . . . . . . . . . Restrictions on DB2 DL/I Batch support . . . . . . . . . . . . . Requirements for using DB2 DL/I Batch support. . . . . . . . . . EXEC parameters . . . . . . . . . . . . . . . . . . . . DD statements . . . . . . . . . . . . . . . . . . . . . Considerations for checkpoint and restart . . . . . . . . . . . . . MVS checkpoints . . . . . . . . . . . . . . . . . . . . . DL/I CHKP and XRST calls or EXEC DLI CHKP and XRST commands . Consideration for database sharing . . . . . . . . . . . . . . . Database sharing support . . . . . . . . . . . . . . . . . . Handling data set extensions . . . . . . . . . . . . . . . . . Support of the processing options GON and GOT . . . . . . . . . Support of database level sharing . . . . . . . . . . . . . . . Application program running in DLI or DBB region . . . . . . . . Application program running in a ULU region . . . . . . . . . . Considerations for block level sharing . . . . . . . . . . . . . Avoiding problems caused by the lack of read integrity . . . . . . . VSAM SHAREOPTIONS . . . . . . . . . . . . . . . . . . VSAM SHAREOPTIONS . . . . . . . . . . . . . . . . . Technical explanations . . . . . . . . . . . . . . . . . Consideration for HALDB single partition processing . . . . . . . . Chapter 7. Processing High Availability Large Databases . . . . High Availability Large Database and Unload utilities . . . . . . . High Availability Large Database (HALDB) . . . . . . . . . . Unloading a PHDAM or PHIDAM database . . . . . . . . . . Using FABHURG1 to unload a partitioned database . . . . . . . . Types of processing . . . . . . . . . . . . . . . . . . Unloading the entire database . . . . . . . . . . . . . . Unloading a partition or a sequence of partitions . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Unloading the entire database . . . . . . . . . Example 2: Unloading a partition . . . . . . . . . . . . . Example 3: Unloading a sequence of partitions . . . . . . . Using FABHFSU to unload a partitioned database . . . . . . . . Unloading the entire database . . . . . . . . . . . . . . . Unloading a partition or a sequence of partitions . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Unloading the entire database . . . . . . . . . Example 2: Unloading a partition . . . . . . . . . . . . . Example 3: Unloading a sequence of partitions . . . . . . . . Running your HSSR application program . . . . . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Coding JCL for your HSSR application program . . . Example 2: Coding HSSRCABP for sequential access for HALDB. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. 86 . 89 . 90 . 91 . 91 . 93 . 94 . 94 . 94 . 94 . 95 . 95 . 95 . 96 . 96 . 96 . 97 . 97 . 97 . 98 . 99 . 99 . 99 . 99 . 100 . 100 . 101 . 101 . 102 . . . . . . . . . . . . . . . . . . . . . . . . . . 103 103 103 103 105 105 105 106 107 107 107 108 108 109 109 109 110 110 110 111 111 112 112 112 112 113

vi

Users Guide

Example 3: Coding HSSRCABP for random access to HALDB Migration unload and fallback unload . . . . . . . . . . . Migration unload . . . . . . . . . . . . . . . . . . Performing the migration unload using FABHURG1 . . . . Considerations . . . . . . . . . . . . . . . . . Example of migration unload . . . . . . . . . . . . Exit routine FABHKEYX for distributing unload records . . . Fallback unload . . . . . . . . . . . . . . . . . . Performing the fallback unload using FABHURG1 . . . . . Example of fallback unload . . . . . . . . . . . . . Summary of HALDB restrictions for processing . . . . . . . . Restrictions for Unload utilities . . . . . . . . . . . . . FABHURG1 utility . . . . . . . . . . . . . . . . FABHFSU utility . . . . . . . . . . . . . . . . . Restrictions for user application programs . . . . . . . . Chapter 8. Specifying options for HSSR Engine Overview of control statements . . . . . . . HSSROPT data set . . . . . . . . . . . . Syntax of HSSROPT control statements . . . Description of control statements . . . . . . APISET control statement . . . . . . . BLDLPCK control statement . . . . . . BUTR control statement . . . . . . . . BYINDEX control statement . . . . . . . CABSTAT control statement . . . . . . CALLSTAT control statement . . . . . . CO control statement . . . . . . . . . DBDL1 control statement. . . . . . . . DBSTATS control statement . . . . . . DIAGG control statement. . . . . . . . DATXEXIT control statement . . . . . . GOTRETRY control statement . . . . . . HSSRDBD control statement . . . . . . HSSRPCB control statement . . . . . . KEYCHECK control statement . . . . . . LOUT control statement . . . . . . . . LSR control statement . . . . . . . . . NOFIX control statement . . . . . . . . NOVSAMOPT control statement . . . . . PARTINFO control statement . . . . . . PCBLIST control statement . . . . . . . RETRY control statement . . . . . . . RTEXIT control statement . . . . . . . SKERROR control statement . . . . . . SKIPVLC control statement . . . . . . . TRDB control statement . . . . . . . . TRHC control statement . . . . . . . . TRXC control statement . . . . . . . . Chapter 9. Reports and output from HSSR HSSRSTAT data set . . . . . . . . . Function . . . . . . . . . . . . . Format . . . . . . . . . . . . . HSSROPT Control Statements report . . HALDB Partition Definition report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

114 115 115 115 115 116 116 118 118 118 118 118 119 119 119 121 121 122 123 123 123 123 124 125 125 126 126 127 127 128 129 130 130 131 132 133 133 134 134 135 135 136 136 137 138 138 139 140 141 141 141 141 141 142

Engine . . . . . . . . . . . . . . .

Contents

vii

HALDB Partitions Accessed report . DB Call Statistics report . . . . . DB Statistics report . . . . . . . Randomizing Statistics report . . . DB Record Length Distribution report Data Set I/O Statistics report . . . CAB Statistics report . . . . . . HSSRTRAC data set . . . . . . . Function . . . . . . . . . . . Format . . . . . . . . . . . Trace Output report . . . . . . . Trace Output report with diagnostics HSSRSNAP data set . . . . . . . Function . . . . . . . . . . . Format . . . . . . . . . . . HSSR SNAPs . . . . . . . . . HSSRLOUT data set . . . . . . . HSSRBUTR data set . . . . . . . Function . . . . . . . . . . . Format . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

143 143 145 145 145 145 147 151 151 152 152 155 165 165 165 165 166 166 166 166 167 167 167 168 168 168 169 170 170 171 171 172 173 173 173 173 173 173 174 174 175 175 176 177 178 185 187 188 189 191 192 194 194 195 196

Chapter 10. Using Database Tuning Statistics . . . . . Introduction . . . . . . . . . . . . . . . . . . . Activating the DB Tuning Statistics . . . . . . . . . . JCL for the DB Tuning Statistics . . . . . . . . . . Input: HSSROPT data set . . . . . . . . . . . . DBSTATS control statement . . . . . . . . . . LOUT control statement . . . . . . . . . . . . Input: HSSRLDEF data set . . . . . . . . . . . . Output: HSSRSTAT data set . . . . . . . . . . . Output: HSSRLOUT data set . . . . . . . . . . . Printing long database records with FABHLDBR . . . . . JCL for the FABHLDBR utility . . . . . . . . . . . Input: HSSROPT data set . . . . . . . . . . . . TRDB control statement . . . . . . . . . . . . TRHC control statement . . . . . . . . . . . . Input: SYSIN data set . . . . . . . . . . . . . . NBR control statement . . . . . . . . . . . . LENGTH control statement . . . . . . . . . . . IO control statement . . . . . . . . . . . . . ROOT-ONLY control statement . . . . . . . . . Output: HSSRTRAC data set . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . Tuning a database with the DB Tuning Statistics . . . . . Description of the DB Tuning Statistics. . . . . . . . DB Statistics report . . . . . . . . . . . . . . Randomizing Statistics report . . . . . . . . . . DB Record Length Distribution report . . . . . . . Tuning the primary data set group of an HDAM database . Average number of I/O operations per database record Packing density of the root addressable area . . . . Number of RAPs per root segment . . . . . . . . CI size and block size . . . . . . . . . . . . . Bytes limit . . . . . . . . . . . . . . . . . Free block frequency factor . . . . . . . . . . . Free space within each block/CI . . . . . . . . .

viii

Users Guide

Examples of other indicators provided by the DB Tuning Statistics . . . Summary of suggested changes for the example database . . . . . . Other factors influencing the performance of access to an HDAM database . . . . . . . . . . . . . . . . . . . . . . . . Tuning a HIDAM database . . . . . . . . . . . . . . . . . . . Average number of I/O operations per database record . . . . . . . Periodical database reorganization . . . . . . . . . . . . . . . Free space specifications . . . . . . . . . . . . . . . . . . CI size and block size . . . . . . . . . . . . . . . . . . . . Databases with long database records . . . . . . . . . . . . . . Tuning a HISAM database . . . . . . . . . . . . . . . . . . . Average number of I/O operations per database record . . . . . . . KSDS record length (HISAM) . . . . . . . . . . . . . . . . . Periodical database reorganization . . . . . . . . . . . . . . . ESDS CI size . . . . . . . . . . . . . . . . . . . . . . . How to determine randomizing parameters by using a reasonable first guess method . . . . . . . . . . . . . . . . . . . . . . . . . Determining the block or CI size . . . . . . . . . . . . . . . . Determining the bytes limit . . . . . . . . . . . . . . . . . . Determining the number of blocks or CIs in the root addressable area Determining the number of RAPs per block/CI . . . . . . . . . . . Creating a database extract with FABHEXTR . . . . . . . . . . . . . JCL of the FABHEXTR exit routine . . . . . . . . . . . . . . . . Providing an EXIT control statement . . . . . . . . . . . . . . . Providing HSSREXTR control statements. . . . . . . . . . . . . . Sample JCL for creating a database unload extract . . . . . . . . . . Chapter 11. Using the Parallel Scan Facility of FABHFSU Overview of Parallel Scan Facility . . . . . . . . . . Steps necessary to run FABHFSU in PSF mode . . . . . Restrictions . . . . . . . . . . . . . . . . . . . JCL for utilities used for PSF . . . . . . . . . . . . FABHPSFM JCL . . . . . . . . . . . . . . . . FABHPSFC JCL . . . . . . . . . . . . . . . . FABHFSU JCL . . . . . . . . . . . . . . . . FABHPSFS JCL . . . . . . . . . . . . . . . . FABHPSFM program . . . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . FABHPSFM CARDIN data set . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . MAP control statement . . . . . . . . . . . . END control statement . . . . . . . . . . . . Output . . . . . . . . . . . . . . . . . . . FABHPSFM PRNTOUT data set . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . FABHFSU PSF Control Statements report . . . . . FABHFSU PSF Extent Mapping report . . . . . . . FABHPSFC program . . . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . FABHPSFC CARDIN data set . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . DBD control statement . . . . . . . . . . . . CTL control statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

196 197 206 208 208 208 209 209 209 210 210 210 211 211 211 212 212 212 213 213 214 214 216 217 219 219 221 222 223 223 223 224 225 226 226 226 226 226 226 228 228 228 228 228 228 228 230 231 231 231 231 231 232

Contents

ix

NPT control statement . . . . . . . . . PSB control statement . . . . . . . . . END control statement . . . . . . . . Output . . . . . . . . . . . . . . . FABHPSFC PRNTOUT data set . . . . . . Function . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . FABHFSU PSF Control Statements report . FABHFSU PSF Scan Control Data Set report FABHFSU utility . . . . . . . . . . . . . Control statements of FABHFSU . . . . . . PSC control statement . . . . . . . . . FABHPSFS program . . . . . . . . . . . Input . . . . . . . . . . . . . . . . FABHPSFS CARDIN data set . . . . . . . Function . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . SUM control statement . . . . . . . . END control statement . . . . . . . . Output . . . . . . . . . . . . . . . FABHPSFS PRNTOUT data set . . . . . . Function . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . FABHFSU PSF Control Statements report . FABHFSU PSF Summary report . . . . . Example . . . . . . . . . . . . . . . . Step 1Example of FABHPSFM . . . . . . Step 2Example of FABHPSFC . . . . . . Steps 3A, 3B, 3CExample of FABHFSU . . Step 4Example of FABHPSFS . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

233 234 234 234 234 235 235 235 235 237 237 237 238 238 238 238 239 239 240 240 240 240 241 241 241 245 245 246 247 248 249 249 249 249 250 250 252 252 252 255 255 255 256 256 256 257 257 257 257 258 258 258 258 260

Chapter 12. Unloading corrupted databases. . . . . . . . . Using the SKERROR option for FABHURG1 . . . . . . . . . Using the Pointer Bypass Option for FABHFSU . . . . . . . . Option 1 . . . . . . . . . . . . . . . . . . . . . . Option 2 . . . . . . . . . . . . . . . . . . . . . . Rules for unloading with Pointer Bypass or SKERROR option . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Using FABHURG1 to unloading a corrupted database Example 2: Using FABHFSU to unloading a corrupted database . Chapter 13. Compatibility with earlier products . . . . . Compatibility with DBT V2 HSSR . . . . . . . . . . . . Default buffer handler for ESDS and OSAM . . . . . . . Default values of CAB buffering parameters . . . . . . . Location of buffer pools and compatibility of exit routines . . HSSROPT control statements: HDSTATS and NOSAMEOPT Access method used in Unload utilities to write output records Specifying an HSSR PCB through KEYLEN . . . . . . . Support of PROCOPT=R and replace calls . . . . . . . Status code in PCB feedback . . . . . . . . . . . DFSVSAMP DD . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . Support and restriction for replace operations . . . . . Support of explicit HSSR calls . . . . . . . . . . . . FABHFSU control statements: CO and CON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Users Guide

CO control statement . . . . . . . . . . . . . CON control statement . . . . . . . . . . . . Date specification in PSC and CTL control statements . . Format of the Scan Control data set used in Parallel Scan Location of control blocks . . . . . . . . . . . . Product-sensitive macros. . . . . . . . . . . . . DECN control statement and the unloaded data set . . . Compatibility with DBT V1 HSSR . . . . . . . . . . . Compatibility with PO HSSR . . . . . . . . . . . . Program names . . . . . . . . . . . . . . . . Compatibility of application programs . . . . . . . . Reassembling . . . . . . . . . . . . . . . . Relink . . . . . . . . . . . . . . . . . . . Compatibility of exit routines . . . . . . . . . . . Compatibility of JCLs . . . . . . . . . . . . . . Procedures . . . . . . . . . . . . . . . . . Control statements . . . . . . . . . . . . . . Default options . . . . . . . . . . . . . . . . Return codes . . . . . . . . . . . . . . . . . Abend codes . . . . . . . . . . . . . . . . . Database Tuning Statistics . . . . . . . . . . . . Parallel Scan Facility . . . . . . . . . . . . . . DB2 DL/I Batch support . . . . . . . . . . . . . FABHLDBR utility . . . . . . . . . . . . . . . Mapping macros for control blocks and output records . . Compatibility with FSU II . . . . . . . . . . . . . . PSBGEN compatibility . . . . . . . . . . . . . . CON control statement . . . . . . . . . . . . . Chapter 14. Using JCL for IMS HD Reorganization Unload FABHURG1. . . . . . . . . . . . . . . . . . Preparing the DFSISVI0 exit . . . . . . . . . . . . JCL compatibility with IMS HD Reorganization Unload . . .

. . . . . . . . . Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . to . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

260 261 261 261 261 261 262 262 263 263 263 264 264 264 264 264 264 264 265 265 265 265 266 266 266 267 267 267

run . . . . . . 269 . . . . . . 269 . . . . . . 269

Part 2. Customization and diagnosis . . . . . . . . . . . . . . . . . . . . . 271

Chapter 15. Tuning buffer handlers . . . Chained Anticipatory Buffer Handler (CAB) . Description . . . . . . . . . . . . Restrictions . . . . . . . . . . . . Control statements that affect performance HSSRCABP control statements . . . CAB buffer sharing for HALDB . . . HSSROPT control statements . . . . HSSRCABP control statements . . . . CABDD control statement . . . . . OCCURRENCE control statement . . RANSIZE control statement . . . . . NBRSRAN control statement . . . . NBRDBUF control statement . . . . OVERFLOW control statement . . . REFT4 control statement . . . . . . INTER control statement . . . . . . PARTPROC control statement . . . . Tuning aids . . . . . . . . . . . . Tuning CAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 275 276 276 277 277 279 279 280 280 282 283 284 284 284 286 286 287 289 289

Contents

xi

How to tune CAB . . . . . . . . . . . . . . . . . . What you need to know before tuning CAB . . . . . . . . . Trade-off decisions between elapsed time and buffer space . . . Size of OSAM blocks and ESDS control intervals . . . . . . . SMF EXCP statistics . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: CAB control statements for FABHULU jobs . . . . Example 2: OCCURRENCE control statements for a VSAM ESDS database . . . . . . . . . . . . . . . . . . . . . Example 3: Specifying multiple CABDD groups . . . . . . . Basic Buffer Handler . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . Control statements that affect performance . . . . . . . . . . HSSROPT control statement . . . . . . . . . . . . . . BUF control statement . . . . . . . . . . . . . . . . . Tuning aid . . . . . . . . . . . . . . . . . . . . . . Tuning BB . . . . . . . . . . . . . . . . . . . . . . Buffering KSDS . . . . . . . . . . . . . . . . . . . . . "Native" VSAM . . . . . . . . . . . . . . . . . . . . Specifying and tuning the number of buffers . . . . . . . . . Tuning aids . . . . . . . . . . . . . . . . . . . . . VSAM LSR option for primary index databases . . . . . . . . Specifying the number of buffers . . . . . . . . . . . . . Tuning aids . . . . . . . . . . . . . . . . . . . . . Chapter 16. Using HSSR call test utility . . . . . . Program functions . . . . . . . . . . . . . . . Program structure . . . . . . . . . . . . . . . Typical uses . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . Operating instructions . . . . . . . . . . . . . . JCL for the FABHTEST utility . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . FABHTEST SYSIN data set . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . PCB control statement . . . . . . . . . . . GN and GHN control statement . . . . . . . . GNP and GHNP control statement . . . . . . . GNR and GHNR control statement . . . . . . . GU and GHU control statement . . . . . . . . REPL control statement . . . . . . . . . . . FABHTEST HSSROPT data set . . . . . . . . . FABHTEST HSSRCABP data set . . . . . . . . OutputFABHTEST SYSPRINT data set . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . Example 1: Using FABHTEST for problem determination Example 2: Using FABHTEST to test performance . . Chapter 17. Using Program functions Typical uses . . Program structure Restrictions . . . the . . . . . . . . buffer handler simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

289 290 291 292 292 293 293 293 294 295 295 296 296 296 297 297 297 297 297 298 298 298 298 299 299 299 299 299 300 300 300 301 301 301 301 301 302 304 304 305 305 306 306 306 306 307 307 308 309 309 309 310 310

xii

Users Guide

Operating instructions . . . . . . JCL of the FABHBSIM utility . . . Input . . . . . . . . . . . . FABHBSIM HSSROPT data set . FABHBSIM HSSRCABP data set . Output . . . . . . . . . . . Examples . . . . . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

310 310 311 311 311 311 311 313 313 314 315 317 317 317 317 318 318 319 319 320 320 321 322 322 323 323 323 324 325 325 325 325 326 326 328 328 329 330 330 331 333 333 335 335 336 336 337 339 339 339 340

Chapter 18. System programming interfaces . . . . Run-Time Environment exit (FABHRTEX) . . . . . . . Buffer Handler Initialization exit (FABHCEX) . . . . . . Return Code Edit exit (FABHRCEX) . . . . . . . . . Interface to Return Code Edit exit routine . . . . . . FABHRCEG sample JCL . . . . . . . . . . . . Writing user record-formatting routine . . . . . . . . Logic of FABHURG1 . . . . . . . . . . . . . Common logic . . . . . . . . . . . . . . . Record-formatting routine . . . . . . . . . . Optional user exit routine. . . . . . . . . . . Interface to user record-formatting and optional user exit Call parameters . . . . . . . . . . . . . . . Parameter 1: OUTPUT-AREA . . . . . . . . . Parameter 2: Database segment (Segment data) . . Parameter 3: Segment prefix . . . . . . . . . Parameter 4: HSSR PCB . . . . . . . . . . Parameter 5: HSDB . . . . . . . . . . . . Parameter 6: Reserved for system use . . . . . Parameter 7: RBA of segment prefix . . . . . . Parameter 8: Length of segment data . . . . . . Parameter 9: Key of next root . . . . . . . . . Parameters 1013 . . . . . . . . . . . . . Parameters 14n . . . . . . . . . . . . . Special SYSIN control statements for user exits . . . FRMT control statement . . . . . . . . . . . EXIT control statement . . . . . . . . . . . OFFS control statement . . . . . . . . . . . ULEN control statement . . . . . . . . . . . USEGMAX control statement . . . . . . . . . Get-by-RBA calls . . . . . . . . . . . . . . . Structure . . . . . . . . . . . . . . . . . Finding the RBA required by the Get-by-RBA call . . Coding and link-editing the routine . . . . . . . . Product-sensitive macros. . . . . . . . . . . . . Chapter 19. Setting site default options . Determining run-time parameters . . . . . Replacing the HSSR option table (FABHOPT) FABHOPTG sample JCL . . . . . . . . Coding the FABHTOPT macro . . . . . . Examples of FABHTOPT macro statements . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Part 3. Using Sequential Subset Randomizer . . . . . . . . . . . . . . . . . 341

Contents

xiii

Chapter 20. Introduction . . . . . . . . . . . . . . . . Characteristics of Sequential Subset Randomizer . . . . . . . . Program functions . . . . . . . . . . . . . . . . . . . Physical clustering of all database records . . . . . . . . . Database retrievals . . . . . . . . . . . . . . . . . . Generation of Sequential Subset Randomizer and database . . . Splitting the unloaded data set . . . . . . . . . . . . . . Providing statistical information . . . . . . . . . . . . . Differences between Sequential Subset Randomizer and Sequential Randomizers . . . . . . . . . . . . . . . . . . . . Advantages of Sequential Subset Randomizer . . . . . . . . Advantages of Sequential Randomizers . . . . . . . . . . Differences between Sequential Subset Randomizer and DFSHDC40 Advantages of Sequential Subset Randomizer . . . . . . . . Advantages of DFSHDC40 . . . . . . . . . . . . . . . Typical uses and benefits . . . . . . . . . . . . . . . . Program structure . . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . . . . . Chapter 21. Generation of Sequential Subset Randomizer . Job steps . . . . . . . . . . . . . . . . . . . . Data flow . . . . . . . . . . . . . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . Cataloged procedure . . . . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . . . SYSIN data set . . . . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . General rules for macro statements . . . . . . . . . FABITAB macro statement . . . . . . . . . . . . . FABIDEF macro statement . . . . . . . . . . . . . FABIGEN macro statement . . . . . . . . . . . . . END statement . . . . . . . . . . . . . . . . . Example 1: Generating Sequential Subset Randomizer, case 1 Example 2: Generating Sequential Subset Randomizer, case 2 Chapter 22. Splitting the unloaded database data set Job steps . . . . . . . . . . . . . . . . . Data flow . . . . . . . . . . . . . . . . . JCL . . . . . . . . . . . . . . . . . . . Output . . . . . . . . . . . . . . . . . . SYSPRINT data set . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . Split Unloaded Data Set Statistics report . . . . HDR data set . . . . . . . . . . . . . . . FKDn data set . . . . . . . . . . . . . . TRL data set . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . Chapter 23. Sequential Subset Job steps . . . . . . . . Data flow . . . . . . . . JCL requirements . . . . . InputHSSROPT data set . . Function . . . . . . . . Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

343 343 344 344 345 345 345 346 346 346 346 346 346 347 347 348 349 351 351 351 352 352 352 352 352 353 353 353 355 356 356 356 357 359 359 359 360 361 361 361 362 362 363 363 363 363 367 367 367 368 369 369

xiv

Users Guide

Format . . . . . . . . . . SSSTATS control statement . . . OutputHSSRSTAT data set . . . Function . . . . . . . . . . Format . . . . . . . . . . Sequential Subset Statistics report Example . . . . . . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

369 369 369 370 370 370 372 373 373 374 374 374 375 375 376 377 377

Chapter 24. Related user tasks . . . . . . . . . . . . . . . . Database design: Defining the subset IDs . . . . . . . . . . . . Application programming . . . . . . . . . . . . . . . . . . . Database administration . . . . . . . . . . . . . . . . . . . Specifying the relative amount of space to each subset . . . . . . Converting databases to HDAM databases randomized with Sequential Subset Randomizer . . . . . . . . . . . . . . . . . . . Converting from a database randomized with DFSHDC40 . . . . Converting from a database randomized with other randomizers . . Converting from a HISAM or HIDAM . . . . . . . . . . . . Monitoring the database . . . . . . . . . . . . . . . . . .

Part 4. Messages and codes . . . . . . . . . . . . . . . . . . . . . . . . 379

Chapter 25. Abend codes . . . . . . . . . . Abend code U4013 . . . . . . . . . . . . . Trapping abends issued by application programs . . OS PL/I V2 programs . . . . . . . . . . . COBOL or PL/I programs running under Language . . . . . . . . . . . . . . . . . . . . Environment . . . . . . . . . . . . . . . . . . . . . . . . . 381 381 381 381 381

Chapter 26. HSSR snaps . . . . . . . . . . . . . . . . . . . . 383 Chapter 27. Return codes . . . . . . FABHURG1 return codes . . . . . . FABHFSU return codes . . . . . . . FABHPSFS return codes . . . . . . . FABHBSIM and FABHTEST return codes. JCL for IMS HD Reorganization Unload to Chapter 28. Messages Message format . . . Message variables . . FABH messages . . FABI messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . run FABHURG1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 385 385 387 387 387 389 389 389 390 467

Part 5. Diagnosing problems . . . . . . . . . . . . . . . . . . . . . . . . 473

Chapter 29. Standard procedure for problem determination Chapter 30. Diagnostics Aid . . . . Running the Diagnostics Aid with JCL . Load Module/Macro APAR Status report Load Module APAR Status report. . Macro APAR Status report . . . . Messages and codes . . . . . . . Return codes . . . . . . . . . Abend codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 477 477 478 478 479 479 479

Contents

xv

Messages . . . . . . . . . . . . . . . . . . . . . . . . . 479 Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 Programming interface information . . . . . . . . . . . . . . . . . 484 Trademarks and service marks . . . . . . . . . . . . . . . . . . 485 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

xvi

Users Guide

Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. | 15. | 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. System structure and data flow . . . . . . . . . . . . . . . . . Adding IMSPLEX and PARM1 parameters to the FABHULU procedure . . . Example of the parameter specification for the FABHULU procedure . . . . FABHURG1 Unload Parameters report . . . . . . . . . . . . . . . FABHURG1 Segment Statistics report . . . . . . . . . . . . . . . FABHURG1 Segment Statistics for HALDB . . . . . . . . . . . . . FABHURG1 JCL for unloading an HDAM database . . . . . . . . . . FABHURG1 JCL specifying SYSIN control statements . . . . . . . . . FABHFSU Control Statements report . . . . . . . . . . . . . . . FABHFSU Control Specifications report . . . . . . . . . . . . . . FABHFSU Segment Statistics report . . . . . . . . . . . . . . . . FABHFSU Segment Statistics report (Partition-wide) . . . . . . . . . . Running FABHFSU in the ULU region . . . . . . . . . . . . . . . Running FABHFSU in the DLI region . . . . . . . . . . . . . . . JCL to run an application program using the DL/I calls . . . . . . . . . Example of the HALDB control statement for single partition processing . . Unloading the entire database . . . . . . . . . . . . . . . . . Unloading a partition or a sequence of partitions . . . . . . . . . . . Unloading a sequence of partitions . . . . . . . . . . . . . . . . HSSROPT Control Statements report . . . . . . . . . . . . . . . HALDB Partition Definition report . . . . . . . . . . . . . . . . HALDB Partitions Accessed report . . . . . . . . . . . . . . . . DB Call Statistics report . . . . . . . . . . . . . . . . . . . . DB Call Statistics report for HALDB . . . . . . . . . . . . . . . Data Set I/O Statistics report . . . . . . . . . . . . . . . . . . HALDB Buffering Statistics report for PHDAM . . . . . . . . . . . . CAB Statistics report for a nonpartitioned database . . . . . . . . . . Sample of Trace Output report when 1 SSA is specified . . . . . . . . Sample of Trace Output report when 15 SSAs and APISET 3 are specified . Trace Output report with diagnostics (CASE 1-A, CASE 1-B, and CASE 2) . Trace Output report with diagnostics (CASE 19-A) . . . . . . . . . . Trace Output report with diagnostics (CASE 19-B) . . . . . . . . . . Trace Output report with diagnostics (CASE 20) . . . . . . . . . . . Sample JCL for the FABHLDBR utility . . . . . . . . . . . . . . DB Tuning Statistics for the entire DB . . . . . . . . . . . . . . . DB Tuning Statistics for the HDAM root addressable area . . . . . . . DB Tuning Statistics for the HDAM overflow area . . . . . . . . . . Randomizing Statistics . . . . . . . . . . . . . . . . . . . . DB Record Length Distribution . . . . . . . . . . . . . . . . . DB Statistics after tuning . . . . . . . . . . . . . . . . . . . EXIT FABHEXTR control statement . . . . . . . . . . . . . . . HSSREXTR control statements . . . . . . . . . . . . . . . . . Sample JCL for creating an extract database . . . . . . . . . . . . Execution of a 3-Phase PSF job . . . . . . . . . . . . . . . . . FABHFSU PSF Control Statements report . . . . . . . . . . . . . FABHFSU PSF Extent Mapping report (HDAM database) . . . . . . . FABHFSU PSF Extent Mapping report (HIDAM database) . . . . . . . FABHFSU PSF Control Statements report . . . . . . . . . . . . . FABHFSU PSF Scan Control Data Set report . . . . . . . . . . . . FABHFSU PSF Control Statement report . . . . . . . . . . . . . FABHFSU PSF Summary report . . . . . . . . . . . . . . . . . FABHPSFM JCL for PSF mode . . . . . . . . . . . . . . . . . FABHPSFC JCL for PSF mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 . 26 . 26 . 46 . 47 . 47 . 47 . 48 . 67 . 69 . 70 . 71 . 80 . 81 . 92 . 102 . 105 . 106 . 107 . 142 . 142 . 143 . 144 . 145 . 146 . 148 . 151 . 154 . 154 . 160 . 163 . 164 . 165 . 175 . 178 . 181 . 183 . 185 . 188 . 198 . 214 . 216 . 217 . 222 . 228 . 230 . 230 . 235 . 236 . 241 . 243 . 246 . 247

Copyright IBM Corp. 2000, 2007

xvii

54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. 67. 68. 69. 70. 71. 72. 73. 74. 75. 76. 77. 78. 79. 80. 81. 82.

FABHFSU JCL for PSF mode. . . . . . . . . . . . . . . . . FABHPSFS JCL for PSF mode . . . . . . . . . . . . . . . . FABHURG1 JCL to unload a corrupted database . . . . . . . . . FABHFSU JCL to unload a corrupted database . . . . . . . . . . FABHTEST Control Statements report . . . . . . . . . . . . . FABHTEST JCL for problem determination . . . . . . . . . . . . FABHTEST JCL for performance testing . . . . . . . . . . . . . FABHBSIM JCL for simulating a buffer handler . . . . . . . . . . A user exit routine for FABHURG1 in COBOL . . . . . . . . . . . RBA of segment prefix . . . . . . . . . . . . . . . . . . . Sample code for capping . . . . . . . . . . . . . . . . . . How run-time parameters are determined . . . . . . . . . . . . Physical clustering with Sequential Subset Randomizer . . . . . . . Data flow of the generation of Sequential Subset Randomizer (SSRGEN) FABITAB macro statement . . . . . . . . . . . . . . . . . . FABIDEF macro statement . . . . . . . . . . . . . . . . . . FABIGEN macro statement . . . . . . . . . . . . . . . . . END statement . . . . . . . . . . . . . . . . . . . . . . Example 1: Generating Sequential Subset Randomizer, case 1 . . . . Example 2: Generating Sequential Subset Randomizer, case 2 . . . . Data flow for FABIUNLS. . . . . . . . . . . . . . . . . . . Split Unloaded Data Set Statistics report (IDTYPE=C) . . . . . . . . Split Unloaded Data Set Statistics report (IDTYPE=X) . . . . . . . . Example of database generation . . . . . . . . . . . . . . . Data flow for the SS-STATS routine . . . . . . . . . . . . . . Activating the SS-STATS routine . . . . . . . . . . . . . . . Sequential Subset Statistics report (IDTYPE=C) . . . . . . . . . . Sequential Subset Statistics report (IDTYPE=X) . . . . . . . . . . Example of JCL for database unload with SS-STATS . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

247 248 252 253 307 308 308 312 321 324 333 335 345 351 353 355 356 356 357 357 359 362 362 364 368 369 370 371 372

xviii

Users Guide

Tables
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. FABHX034 DD statements . . . . . . . . . . . . FABHURG1 DD statements . . . . . . . . . . . . FABHFSU control statements . . . . . . . . . . . Control statements for FABHFSU in standard mode . . . Fields in an SGTBL . . . . . . . . . . . . . . . Format of the key area . . . . . . . . . . . . . The SGLEVEL field in SGTBL . . . . . . . . . . . Register contents upon entry to an exit routine . . . . . Parameter list pointed to by register 1 upon entry . . . . Return codes . . . . . . . . . . . . . . . . . Examples of exit routines . . . . . . . . . . . . . HSSR PCB mask . . . . . . . . . . . . . . . Format of the DIB . . . . . . . . . . . . . . . Status codes returned from an HSSR call . . . . . . . DL/I call types supported by each API set . . . . . . . EXEC DLI command types supported by each API set . . List of HSSROPT control statements for HSSR Engine . DD statements for DB Tuning Statistics . . . . . . . DD statements for the FABHLDBR utility . . . . . . FABHPSFM DD statements . . . . . . . . . . . FABHPSFC DD statements . . . . . . . . . . . FABHFSU DD statements for PSF mode . . . . . . FABHPSFS DD statements . . . . . . . . . . . FABHPSFM control statements . . . . . . . . . . FABHPSFC control statements . . . . . . . . . . Maximum value for the total number of scan phases . . FABHFSU control statements for PSF mode . . . . . FABHPSFS control statements . . . . . . . . . . Differences of default values of CAB buffering parameters Location of control blocks . . . . . . . . . . . . Aliases of mapping macros for HSSR Engine . . . . . Changes of procedure names . . . . . . . . . . Names and aliases of HSSR modules . . . . . . . Changes of mapping macro names for HSSR Engine . . Aliases for FSU II modules . . . . . . . . . . . . Supported control statements for DFSURGU0. . . . . Overview of buffering services . . . . . . . . . . HSSRCABP control statements . . . . . . . . . . HSSROPT control statements . . . . . . . . . . HSSROPT control statements for Basic Buffering Handler FABHTEST DD statements . . . . . . . . . . . FABHBSIM DD statements . . . . . . . . . . . . Register contents upon entry to a user exit . . . . . . Parameters . . . . . . . . . . . . . . . . . FABHRTEX return codes . . . . . . . . . . . . FABHCEX return codes . . . . . . . . . . . . . Register contents upon entry to FABHRCEX . . . . . FABHRCEX parameters . . . . . . . . . . . . . Register contents at entry to routines . . . . . . . . Exit routine return codes . . . . . . . . . . . . Product-sensitive macros for system program interfaces . Options for which default values can be specified . . . Basic settings of FABHTOPT options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 . 38 . 54 . 56 . 73 . 74 . 76 . 76 . 77 . 77 . 79 . 86 . 86 . 87 . 90 . 91 . 121 . 168 . 172 . 223 . 223 . 224 . 225 . 226 . 231 . 232 . 237 . 239 . 256 . 261 . 262 . 264 . 265 . 266 . 267 . 270 . 275 . 277 . 280 . 296 . 300 . 310 . 314 . 314 . 314 . 315 . 317 . 317 . 319 . 320 . 334 . 336 . 337

Copyright IBM Corp. 2000, 2007

xix

54. DD statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 55. FABIUNLS DD statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 56. Additional DD statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

xx

Users Guide

About this information

This book is designed as a reference guide for use with IMS High Performance Unload for z/OS (also referred to as High Performance Unload). This book consists of the following five parts: v Part 1, Using High Performance Unload v Part 2, Customization and diagnosis v Part 3, Using Sequential Subset Randomizer v Part 4, Messages and codes v Part 5, Diagnosing problems This book also contains Notices. Part 1, Using High Performance Unload, contains the following chapters: v Chapter 1, Introduction, provides an introduction to the system structure and functions of High Performance Unload. v Chapter 2, Job control language, describes how to write JCL for High Performance Unload. v Chapter 3, Using the Unload utilities, is an introduction to FABHURG1 and FABHFSU, two database unload utilities provided by High Performance Unload. v Chapter 4, Using FABHURG1 to unload IMS databases, describes how to use the FABHURG1 unload utility. v Chapter 5, Using FABHFSU to unload IMS databases, describes how to use the FABHFSU unload utility. v Chapter 6, Application programming interface, describes how to write an application program for High Performance Unload. v Chapter 7, Processing High Availability Large Databases, describes how to process High Availability Large Database (HALDB) by using FABHURG1, FABHFSU, or user application program. v Chapter 8, Specifying options for HSSR Engine, describes control statements that change the behavior of High Performance Unload. v Chapter 9, Reports and output from HSSR Engine, describes the reports and outputs produced by High Performance Unload. v Chapter 10, Using Database Tuning Statistics, describes how to use Database Tuning Statistics report to tune your database. v Chapter 11, Using the Parallel Scan Facility of FABHFSU, describes how to use Parallel Scan Facility of FABHFSU. v Chapter 12, Unloading corrupted databases, describes how to use FABHURG1 and FABHFSU to unload corrupted databases. v Chapter 13, Compatibility with earlier products, gives details about the differences between High Performance Unload and earlier products and how to migrate to High Performance Unload from those products. v Chapter 14, Using JCL for IMS HD Reorganization Unload to run FABHURG1, on page 269, describes how to use IMS HD Reorganization Unload to run FABHURG1. Part 2, Customization and diagnosis describes how to tune or customize the High Speed Sequential Retrieval Engine (HSSR Engine), the core of High Performance Unload. This part contains the following chapters:
Copyright IBM Corp. 2000, 2007

xxi

v Chapter 15, Tuning buffer handlers, describes the buffer handlers and tells how to tune and customize them. v Chapter 16, Using HSSR call test utility, describes FABHTEST, a utility for tuning a buffer handler or diagnosing software errors in HSSR Engine. v Chapter 17, Using the buffer handler simulation utility, describes FABHBSIM, a utility for tuning buffer handlers. v Chapter 18, System programming interfaces, provides information for system programmers. v Chapter 19, Setting site default options, describes how to change the default options for some control statements for High Performance Unload. Part 3, Using Sequential Subset Randomizer describes how to use Sequential Subset Randomizer. Part 4, Messages and codes provides a complete list of the messages issued by High Performance Unload, HSSR Engine, or High Performance Unload utilities, and the codes returned from the components of High Performance Unload. Part 5, Diagnosing problems describes how to diagnose problems for High Performance Unload. Notices contains some general information. The technical changes for this edition are summarized under Summary of changes on page 12. Specific changes since the previous edition of this book are indicated by a vertical bar (|) to the left of a change. Editorial changes that have no technical significance are not noted. Always check the DB2 and IMS Tools Library page for the most current version of this publication: www.ibm.com/software/data/db2imstools/library.html

Service updates and support information

To find service updates and support information, including software fix packs, PTFs, Frequently Asked Question (FAQs), technical notes, troubleshooting information, and downloads, refer to the following Web page: www.ibm.com/software/data/db2imstools/support.html

Conventions used in this book

This book uses the following highlighting conventions: v Boldface type indicates commands or user interface controls such as names of fields, folder, icons, or menu choices. v Monospace type indicates examples of text that you enter exactly as shown. v Italic type indicates variables that you should replace with a value. It is also used to indicate book titles and to emphasize significant words. The following labels identify significant elements within this book: v Topics: is used to identify the significant subsections within each chapter.

xxii

Users Guide

How to look up message explanations

You can use any of the following methods to search for messages and codes:

Searching an information center

In the search box that is located in the top left toolbar of any Eclipse help system, such as the IBM Information Management Software for z/OS Solutions Information Center, enter the number of the message that you want to locate. For example, you can enter DFS1065A in the search field. Use the following tips to help you improve your message searches: v You can search for information on codes by entering the code; for example, enter -327. v Enter the complete or partial message number. You can use wild cards (* or ?) in the message number to broaden your search; for example, DFS20??I. The information center contains the latest message information for all of the information management products that are included in the information center.

Using a Web search

You can use any of the popular search engines that are available on the Web to search for message explanations. When you type the specific message number or code into the search engine, you will be presented with links to the message information in IBM information centers.

Using LookAt
LookAt is an online facility that you can use to look up explanations for most of the IBM messages you encounter, as well as for some system abends and codes. Using LookAt to find information is faster than a conventional search because in most cases LookAt goes directly to the message explanation. You can use LookAt from the following locations to find IBM message explanations for z/OS elements and features, z/VM, VSE/ESA, and Clusters for AIX and Linux: v The Internet. You can access IBM message explanations directly from the LookAt Web site at http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/. v Your z/OS TSO/E host system. You can install code on your z/OS or z/OSe systems to access IBM message explanations, using LookAt from a TSO/E command line (for example, TSO/E prompt, ISPF, or z/OS UNIX System Services running OMVS). v Your Microsoft Windows workstation. You can install code to access IBM message explanations on the z/OS Collection (SK3T-4269) using LookAt from a Microsoft Windows command prompt (also known as the DOS command line). v Your wireless handheld device. You can use the LookAt Mobile Edition with a handheld device that has wireless access and an Internet browser (for example, Internet Explorer for Pocket PCs, Blazer, or Eudora for Palm OS, or Opera for Linux handheld devices). Link to the LookAt Mobile Edition from the LookAt Web site. You can obtain code to install LookAt on your host system or Microsoft Windows workstation from a disk on your z/OS Collection (SK3T-4269) or from the LookAt

About this information

xxiii

Web site (click Download, and select the platform, release, collection, and location that suit your needs). More information is available in the LOOKAT.ME files available during the download process.

How to send your comments

Your feedback is important in helping to provide the most accurate and high-quality information. If you have any comments about this book, use either of the following options: v Use the online reader comment form, which is located at: www.ibm.com/software/data/rcf/ v Send your comments by e-mail to [email protected]. Be sure to include the name of the book, the part number of the book, the version of IMS High Performance Unload for z/OS, and, if applicable, the specific location of the text you are commenting on (for example, a page number or table number).

xxiv

Users Guide

Part 1. Using High Performance Unload

Chapter 1. Introduction . . . . . . . . . . . Terminology . . . . . . . . . . . . . . . . Summary of changes . . . . . . . . . . . . SC27-0936-06October 2007 . . . . . . . . SC27-0936-05January 2007 . . . . . . . . SC27-0936-04October 2005 . . . . . . . . SC27-0936-03November 2004 . . . . . . . SC27-0936-01 and SC27-0936-02January 2003 . SC27-0936-00November 2000 . . . . . . . Program functions . . . . . . . . . . . . . . Major features and benefits . . . . . . . . . Database organizations supported . . . . . . . System structure and data flow . . . . . . . . . Processing environment . . . . . . . . . . . Software requirements . . . . . . . . . . . Hardware requirements . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . Compatibility with prior products . . . . . . . . Publications and updates . . . . . . . . . . . High Performance Unload information on the Web . Receiving updates automatically . . . . . . . Prerequisite knowledge . . . . . . . . . . . How this information should be read . . . . . . Accessibility features for High Performance Unload . Accessibility features . . . . . . . . . . . . Keyboard navigation . . . . . . . . . . . . IBM and accessibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 11 12 12 12 13 13 14 15 15 15 16 16 18 18 18 18 18 18 18 19 19 19 20 20 20 20 21 21 25 25 25 26 27 27 27 27 28 29 29 29 29 29 30 30 30 31 31 32

Chapter 2. Job control language. . . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . Supported IMS region types and cataloged procedures . . Selecting region types . . . . . . . . . . . . . Modifying the DL/I JCL for High Performance Unload . . Parameters required by the IMS DBRC SCI registration . Chapter 3. Using the Unload utilities . . . . . . . Program structure . . . . . . . . . . . . . . . FABHURG1 program structure . . . . . . . . . FABHFSU program structure . . . . . . . . . . Functions available in both Unload utilities . . . . . . Selecting an Unload utility for your use . . . . . . . FABHURG1 functions not available in FABHFSU . . FABHFSU functions not available in FABHURG1 . . Which Unload utility should be used . . . . . . . Restrictions common to FABHURG1 and FABHFSU . . Considerations . . . . . . . . . . . . . . . . For a logical parents concatenated key . . . . . . For an unloaded data set used for reorganization . . For database sharing . . . . . . . . . . . . For HALDB Online Reorganization capable partitions . For using a secondary index . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4. Using FABHURG1 to unload IMS databases . . . . . . . . . 33

Copyright IBM Corp. 2000, 2007

Program functions and benefits . . . . . . . . Program structure . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . Operating instructions . . . . . . . . . . . Selecting a format for the unload output. . . . . *HD format . . . . . . . . . . . . . . *F1 format . . . . . . . . . . . . . . *F2 format . . . . . . . . . . . . . . *F3 format . . . . . . . . . . . . . . *CS format . . . . . . . . . . . . . . JCL requirements for FABHURG1 . . . . . . . Input . . . . . . . . . . . . . . . . . . SYSIN data set . . . . . . . . . . . . . Function . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . PCB control statement . . . . . . . . . FRMT control statement . . . . . . . . DEC control statement . . . . . . . . . PARTITION control statement . . . . . . SEGSTAT control statement . . . . . . . CHECKREC control statement . . . . . . MIGRATE control statement . . . . . . . FALLBACK control statement . . . . . . HSSROPT data set . . . . . . . . . . . HSSRCABP data set. . . . . . . . . . . OutputSYSPRINT data set . . . . . . . . . Function . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . FABHURG1 Unload Parameters report . . . . FABHURG1 Segment Statistics report . . . . Examples . . . . . . . . . . . . . . . . Example 1: Running FABHURG1 in ULU region . Example 2: Running FABHURG1 in DLI region .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

33 33 34 34 35 35 35 36 37 38 38 40 40 40 41 41 41 42 43 43 44 44 45 45 45 46 46 46 46 46 47 47 48 49 49 50 50 50 51 51 51 53 54 54 56 56 56 57 57 58 62 63 63 64 65

Chapter 5. Using FABHFSU to unload IMS databases Program functions and benefits . . . . . . . . . . Program structure . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . Operating instructions . . . . . . . . . . . . . Selecting a format for the unload output. . . . . . . HS format . . . . . . . . . . . . . . . . . UL format . . . . . . . . . . . . . . . . . VB format . . . . . . . . . . . . . . . . . VN format . . . . . . . . . . . . . . . . . JCL requirements for FABHFSU . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . CARDIN data set . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . DBD control statement . . . . . . . . . . . PSB control statement . . . . . . . . . . . DEC control statement . . . . . . . . . . . GOT control statement . . . . . . . . . . . PARTITION control statement . . . . . . . . SEGSTAT control statement . . . . . . . . . BLM/ELM control statements . . . . . . . . .

Users Guide

| |

END control statement . . . . . . . . . . . . . . . HSSROPT data set . . . . . . . . . . . . . . . . . HSSRCABP data set. . . . . . . . . . . . . . . . . OutputPRNTOUT data set . . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . FABHFSU Control Statements report . . . . . . . . . . . FABHFSU Control Specifications report . . . . . . . . . . FABHFSU Segment Statistics report . . . . . . . . . . . User exit . . . . . . . . . . . . . . . . . . . . . . Attributes of the routine . . . . . . . . . . . . . . . . Link-editing the routine . . . . . . . . . . . . . . . Loading the routine . . . . . . . . . . . . . . . . Information passed to the exit routine . . . . . . . . . . Segment prefix area . . . . . . . . . . . . . . . . Segment table (SGTBL) . . . . . . . . . . . . . . Using the key area . . . . . . . . . . . . . . . . Modifying segments in user exits . . . . . . . . . . . Activating the routine. . . . . . . . . . . . . . . . . Initialization and termination processing in the exit routine . . . Communicating with main logic . . . . . . . . . . . . . Contents of registers on entry . . . . . . . . . . . . Contents of registers on exit . . . . . . . . . . . . . Writing a user exit routine in COBOL . . . . . . . . . . . Enterprise COBOL, COBOL for OS/390, COBOL for MVS, and COBOL/370 . . . . . . . . . . . . . . . . . . VS COBOL II . . . . . . . . . . . . . . . . . . Writing a user exit routine in PL/I . . . . . . . . . . . . Sample exit routines . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Running FABHFSU in ULU region . . . . . . . Example 2: Running FABHFSU in the DLI region . . . . . . Chapter 6. Application programming interface . What is High Performance Unload API? . . . . . HSSR PCB requirements . . . . . . . . . . PCB statement requirements . . . . . . . . Processing option (PROCOPT) requirements . . SENSEG statement requirements . . . . . . HSSR PCB feedback information . . . . . . . Interpreting PCB feedback. . . . . . . . . Status codes. . . . . . . . . . . . . . DL/I calls or EXEC DLI command for HSSR PCB . DL/I calls supported by each API set . . . . . EXEC DLI commands supported by each API set JCL requirements . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . Consideration for DB2 DL/I Batch interface . . . Features of DB2 DL/I Batch support . . . . . Program design considerations . . . . . . . Restrictions on DB2 DL/I Batch support . . . . Requirements for using DB2 DL/I Batch support. EXEC parameters . . . . . . . . . . . DD statements . . . . . . . . . . . . Considerations for checkpoint and restart . . . . MVS checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

66 67 67 67 67 67 67 68 69 71 71 71 72 72 72 73 74 74 75 75 76 76 77 78 78 78 79 79 79 80 80 83 83 84 84 84 85 85 85 86 89 90 91 91 93 94 94 94 94 95 95 95 96 96

| | | |

Part 1. Using High Performance Unload

DL/I CHKP and XRST calls or EXEC DLI CHKP and XRST commands . Consideration for database sharing . . . . . . . . . . . . . . . Database sharing support . . . . . . . . . . . . . . . . . . Handling data set extensions . . . . . . . . . . . . . . . . . Support of the processing options GON and GOT . . . . . . . . . Support of database level sharing . . . . . . . . . . . . . . . Application program running in DLI or DBB region . . . . . . . . Application program running in a ULU region . . . . . . . . . . Considerations for block level sharing . . . . . . . . . . . . . Avoiding problems caused by the lack of read integrity . . . . . . . VSAM SHAREOPTIONS . . . . . . . . . . . . . . . . . . VSAM SHAREOPTIONS . . . . . . . . . . . . . . . . . Technical explanations . . . . . . . . . . . . . . . . . Consideration for HALDB single partition processing . . . . . . . . Chapter 7. Processing High Availability Large Databases . . . . High Availability Large Database and Unload utilities . . . . . . . High Availability Large Database (HALDB) . . . . . . . . . . Unloading a PHDAM or PHIDAM database . . . . . . . . . . Using FABHURG1 to unload a partitioned database . . . . . . . . Types of processing . . . . . . . . . . . . . . . . . . Unloading the entire database . . . . . . . . . . . . . . Unloading a partition or a sequence of partitions . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Unloading the entire database . . . . . . . . . Example 2: Unloading a partition . . . . . . . . . . . . . Example 3: Unloading a sequence of partitions . . . . . . . Using FABHFSU to unload a partitioned database . . . . . . . . Unloading the entire database . . . . . . . . . . . . . . . Unloading a partition or a sequence of partitions . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Unloading the entire database . . . . . . . . . Example 2: Unloading a partition . . . . . . . . . . . . . Example 3: Unloading a sequence of partitions . . . . . . . . Running your HSSR application program . . . . . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Coding JCL for your HSSR application program . . . Example 2: Coding HSSRCABP for sequential access for HALDB. Example 3: Coding HSSRCABP for random access to HALDB . . Migration unload and fallback unload . . . . . . . . . . . . . Migration unload . . . . . . . . . . . . . . . . . . . . Performing the migration unload using FABHURG1 . . . . . . Considerations . . . . . . . . . . . . . . . . . . . Considerations on region type . . . . . . . . . . . . . Consideration on DFSVSAMP . . . . . . . . . . . . . Consideration on database tuning statistics . . . . . . . . Consideration on hard-copy trace . . . . . . . . . . . . Example of migration unload . . . . . . . . . . . . . . Exit routine FABHKEYX for distributing unload records . . . . . FABHKEYX data set . . . . . . . . . . . . . . . . Example of migration unload with FABHKEYX exit . . . . . Fallback unload . . . . . . . . . . . . . . . . . . . . Performing the fallback unload using FABHURG1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. 96 . 97 . 97 . 97 . 98 . 99 . 99 . 99 . 99 . 100 . 100 . 101 . 101 . 102 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 103 103 103 105 105 105 106 107 107 107 108 108 109 109 109 110 110 110 111 111 112 112 112 112 113 114 115 115 115 115 115 116 116 116 116 116 116 117 118 118

Users Guide

Example of fallback unload . . . . . . Summary of HALDB restrictions for processing . Restrictions for Unload utilities . . . . . . FABHURG1 utility . . . . . . . . . FABHFSU utility . . . . . . . . . . Restrictions for user application programs .

. . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

118 118 118 119 119 119 121 121 122 123 123 123 123 124 125 125 126 126 127 127 128 129 130 130 131 132 133 133 134 134 135 135 136 136 137 138 138 139 140 141 141 141 141 141 142 143 143 145 145 145 145 147 151 151

Chapter 8. Specifying options for HSSR Engine Overview of control statements . . . . . . . HSSROPT data set . . . . . . . . . . . . Syntax of HSSROPT control statements . . . Description of control statements . . . . . . APISET control statement . . . . . . . BLDLPCK control statement . . . . . . BUTR control statement . . . . . . . . BYINDEX control statement . . . . . . . CABSTAT control statement . . . . . . CALLSTAT control statement . . . . . . CO control statement . . . . . . . . . DBDL1 control statement. . . . . . . . DBSTATS control statement . . . . . . DIAGG control statement. . . . . . . . DATXEXIT control statement . . . . . . GOTRETRY control statement . . . . . . HSSRDBD control statement . . . . . . HSSRPCB control statement . . . . . . KEYCHECK control statement . . . . . . LOUT control statement . . . . . . . . LSR control statement . . . . . . . . . NOFIX control statement . . . . . . . . NOVSAMOPT control statement . . . . . PARTINFO control statement . . . . . . PCBLIST control statement . . . . . . . RETRY control statement . . . . . . . RTEXIT control statement . . . . . . . SKERROR control statement . . . . . . SKIPVLC control statement . . . . . . . TRDB control statement . . . . . . . . TRHC control statement . . . . . . . . TRXC control statement . . . . . . . . Chapter 9. Reports and output from HSSR HSSRSTAT data set . . . . . . . . . Function . . . . . . . . . . . . . Format . . . . . . . . . . . . . HSSROPT Control Statements report . . HALDB Partition Definition report . . . . HALDB Partitions Accessed report . . . DB Call Statistics report . . . . . . . DB Statistics report . . . . . . . . . Randomizing Statistics report . . . . . DB Record Length Distribution report . . Data Set I/O Statistics report . . . . . CAB Statistics report . . . . . . . . HSSRTRAC data set . . . . . . . . . Function . . . . . . . . . . . . .

Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Part 1. Using High Performance Unload

Format . . . . . . Trace Output report . . Trace Output report with HSSRSNAP data set . . Function . . . . . . Format . . . . . . HSSR SNAPs . . . . HSSRLOUT data set . . HSSRBUTR data set . . Function . . . . . . Format . . . . . .

. . . . . . . . . . diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

152 152 155 165 165 165 165 166 166 166 166 167 167 167 168 168 168 169 170 170 171 171 172 173 173 173 173 173 173 174 174 175 175 176 177 178 185 187 188 189 191 192 194 194 195 196 196 196 196 197 197 197

Chapter 10. Using Database Tuning Statistics . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . Activating the DB Tuning Statistics . . . . . . . . . . . . . . JCL for the DB Tuning Statistics . . . . . . . . . . . . . . Input: HSSROPT data set . . . . . . . . . . . . . . . . DBSTATS control statement . . . . . . . . . . . . . . LOUT control statement . . . . . . . . . . . . . . . . Input: HSSRLDEF data set . . . . . . . . . . . . . . . . Output: HSSRSTAT data set . . . . . . . . . . . . . . . Output: HSSRLOUT data set . . . . . . . . . . . . . . . Printing long database records with FABHLDBR . . . . . . . . . JCL for the FABHLDBR utility . . . . . . . . . . . . . . . Input: HSSROPT data set . . . . . . . . . . . . . . . . TRDB control statement . . . . . . . . . . . . . . . . TRHC control statement . . . . . . . . . . . . . . . . Input: SYSIN data set . . . . . . . . . . . . . . . . . . NBR control statement . . . . . . . . . . . . . . . . LENGTH control statement . . . . . . . . . . . . . . . IO control statement . . . . . . . . . . . . . . . . . ROOT-ONLY control statement . . . . . . . . . . . . . Output: HSSRTRAC data set . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . Tuning a database with the DB Tuning Statistics . . . . . . . . . Description of the DB Tuning Statistics. . . . . . . . . . . . DB Statistics report . . . . . . . . . . . . . . . . . . Randomizing Statistics report . . . . . . . . . . . . . . DB Record Length Distribution report . . . . . . . . . . . Tuning the primary data set group of an HDAM database . . . . . Average number of I/O operations per database record . . . . Packing density of the root addressable area . . . . . . . . Number of RAPs per root segment . . . . . . . . . . . . CI size and block size . . . . . . . . . . . . . . . . . Bytes limit . . . . . . . . . . . . . . . . . . . . . Free block frequency factor . . . . . . . . . . . . . . . Free space within each block/CI . . . . . . . . . . . . . Examples of other indicators provided by the DB Tuning Statistics Percent of roots in the overflow area . . . . . . . . . . Number of I/Os on the RAP chain . . . . . . . . . . . Number of I/Os in the root addressable area . . . . . . . Number of I/Os in the overflow area . . . . . . . . . . Summary of suggested changes for the example database . . . Other factors influencing the performance of access to an HDAM database . . . . . . . . . . . . . . . . . . . . . Periodical database reorganization . . . . . . . . . . .

. . . 206 . . . 206

Users Guide

Databases with long database records . . . . . . . . . . . . . Compressed segments . . . . . . . . . . . . . . . . . . Inefficient space suballocation for the Sequential Subset Randomizer Tuning a HIDAM database . . . . . . . . . . . . . . . . . . . Average number of I/O operations per database record . . . . . . . Periodical database reorganization . . . . . . . . . . . . . . . Free space specifications . . . . . . . . . . . . . . . . . . CI size and block size . . . . . . . . . . . . . . . . . . . . Databases with long database records . . . . . . . . . . . . . . Tuning a HISAM database . . . . . . . . . . . . . . . . . . . Average number of I/O operations per database record . . . . . . . KSDS record length (HISAM) . . . . . . . . . . . . . . . . . Periodical database reorganization . . . . . . . . . . . . . . . ESDS CI size . . . . . . . . . . . . . . . . . . . . . . . How to determine randomizing parameters by using a reasonable first guess method . . . . . . . . . . . . . . . . . . . . . . . . . Determining the block or CI size . . . . . . . . . . . . . . . . Determining the bytes limit . . . . . . . . . . . . . . . . . . Determining the number of blocks or CIs in the root addressable area Determining the number of RAPs per block/CI . . . . . . . . . . . Creating a database extract with FABHEXTR . . . . . . . . . . . . . JCL of the FABHEXTR exit routine . . . . . . . . . . . . . . . . Providing an EXIT control statement . . . . . . . . . . . . . . . Providing HSSREXTR control statements. . . . . . . . . . . . . . Sample JCL for creating a database unload extract . . . . . . . . . . Chapter 11. Using the Parallel Scan Facility of FABHFSU Overview of Parallel Scan Facility . . . . . . . . . . Steps necessary to run FABHFSU in PSF mode . . . . . Restrictions . . . . . . . . . . . . . . . . . . . JCL for utilities used for PSF . . . . . . . . . . . . FABHPSFM JCL . . . . . . . . . . . . . . . . FABHPSFC JCL . . . . . . . . . . . . . . . . FABHFSU JCL . . . . . . . . . . . . . . . . FABHPSFS JCL . . . . . . . . . . . . . . . . FABHPSFM program . . . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . FABHPSFM CARDIN data set . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . MAP control statement . . . . . . . . . . . . END control statement . . . . . . . . . . . . Output . . . . . . . . . . . . . . . . . . . FABHPSFM PRNTOUT data set . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . FABHFSU PSF Control Statements report . . . . . FABHFSU PSF Extent Mapping report . . . . . . . FABHPSFC program . . . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . FABHPSFC CARDIN data set . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . DBD control statement . . . . . . . . . . . . CTL control statement . . . . . . . . . . . . . NPT control statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

207 207 207 208 208 208 209 209 209 210 210 210 211 211 211 212 212 212 213 213 214 214 216 217 219 219 221 222 223 223 223 224 225 226 226 226 226 226 226 228 228 228 228 228 228 228 230 231 231 231 231 231 232 233

Part 1. Using High Performance Unload

PSB control statement . . . . . . . . . END control statement . . . . . . . . Output . . . . . . . . . . . . . . . FABHPSFC PRNTOUT data set . . . . . . Function . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . FABHFSU PSF Control Statements report . FABHFSU PSF Scan Control Data Set report FABHFSU utility . . . . . . . . . . . . . Control statements of FABHFSU . . . . . . PSC control statement . . . . . . . . . FABHPSFS program . . . . . . . . . . . Input . . . . . . . . . . . . . . . . FABHPSFS CARDIN data set . . . . . . . Function . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . SUM control statement . . . . . . . . END control statement . . . . . . . . Output . . . . . . . . . . . . . . . FABHPSFS PRNTOUT data set . . . . . . Function . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . FABHFSU PSF Control Statements report . FABHFSU PSF Summary report . . . . . Example . . . . . . . . . . . . . . . . Step 1Example of FABHPSFM . . . . . . Step 2Example of FABHPSFC . . . . . . Steps 3A, 3B, 3CExample of FABHFSU . . Step 4Example of FABHPSFS . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

234 234 234 234 235 235 235 235 237 237 237 238 238 238 238 239 239 240 240 240 240 241 241 241 245 245 246 247 248 249 249 249 249 250 250 252 252 252 255 255 255 256 256 256 257 257 257 257 258 258 258 258 260 260

Chapter 12. Unloading corrupted databases. . . . . . . . . Using the SKERROR option for FABHURG1 . . . . . . . . . Using the Pointer Bypass Option for FABHFSU . . . . . . . . Option 1 . . . . . . . . . . . . . . . . . . . . . . Option 2 . . . . . . . . . . . . . . . . . . . . . . Rules for unloading with Pointer Bypass or SKERROR option . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: Using FABHURG1 to unloading a corrupted database Example 2: Using FABHFSU to unloading a corrupted database . Chapter 13. Compatibility with earlier products . . . . . Compatibility with DBT V2 HSSR . . . . . . . . . . . . Default buffer handler for ESDS and OSAM . . . . . . . Default values of CAB buffering parameters . . . . . . . Location of buffer pools and compatibility of exit routines . . HSSROPT control statements: HDSTATS and NOSAMEOPT Access method used in Unload utilities to write output records Specifying an HSSR PCB through KEYLEN . . . . . . . Support of PROCOPT=R and replace calls . . . . . . . Status code in PCB feedback . . . . . . . . . . . DFSVSAMP DD . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . Support and restriction for replace operations . . . . . Support of explicit HSSR calls . . . . . . . . . . . . FABHFSU control statements: CO and CON . . . . . . CO control statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Users Guide

CON control statement . . . . . . . . . . . . Date specification in PSC and CTL control statements . . Format of the Scan Control data set used in Parallel Scan Location of control blocks . . . . . . . . . . . . Product-sensitive macros. . . . . . . . . . . . . DECN control statement and the unloaded data set . . . Compatibility with DBT V1 HSSR . . . . . . . . . . . Compatibility with PO HSSR . . . . . . . . . . . . Program names . . . . . . . . . . . . . . . . Compatibility of application programs . . . . . . . . Reassembling . . . . . . . . . . . . . . . . Relink . . . . . . . . . . . . . . . . . . . Compatibility of exit routines . . . . . . . . . . . Compatibility of JCLs . . . . . . . . . . . . . . Procedures . . . . . . . . . . . . . . . . . Control statements . . . . . . . . . . . . . . Default options . . . . . . . . . . . . . . . . Return codes . . . . . . . . . . . . . . . . . Abend codes . . . . . . . . . . . . . . . . . Database Tuning Statistics . . . . . . . . . . . . Parallel Scan Facility . . . . . . . . . . . . . . DB2 DL/I Batch support . . . . . . . . . . . . . FABHLDBR utility . . . . . . . . . . . . . . . Mapping macros for control blocks and output records . . Compatibility with FSU II . . . . . . . . . . . . . . PSBGEN compatibility . . . . . . . . . . . . . . CON control statement . . . . . . . . . . . . . Chapter 14. Using JCL for IMS HD Reorganization Unload FABHURG1. . . . . . . . . . . . . . . . . . Preparing the DFSISVI0 exit . . . . . . . . . . . . JCL compatibility with IMS HD Reorganization Unload . . .

. . . . . . Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . to . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

261 261 261 261 261 262 262 263 263 263 264 264 264 264 264 264 264 265 265 265 265 266 266 266 267 267 267

run . . . . . . 269 . . . . . . 269 . . . . . . 269

Part 1. Using High Performance Unload

10

Users Guide

Chapter 1. Introduction
High Performance Unload functionally replaces the IMS HD Reorganization Unload utility (DFSURGU0). High Performance Unload is serviced by a high-performance database retrieval engine calledHigh Speed Sequential Retrieval (HSSR) Engine. High Performance Unload also has an application programming interface (API) that is compatible with the HSSR call API provided by High Speed Sequential Retrieval of IMS System Utilities, Data Base Tools (PID: 5685-093). The API enables DL/I application programs to use the HSSR Engine to read a database by using GN calls. Topics: v v v v v v v v Terminology Summary of changes on page 12 Program functions on page 15 System structure and data flow on page 16 Processing environment on page 18 Compatibility with prior products on page 18 Publications and updates on page 18 Accessibility features for High Performance Unload on page 20

Terminology
To make the text in this book easier to read, the version and release level of IMS has been abbreviated. The following abbreviation is used: IMS Version 8 refers to IMS Version 8 Release 1 IMS Version 9 refers to IMS Version 9 Release 1 IMS Version 10 refers to IMS Version 10 Release 1 Also, those versions of IMS are simply referred to as IMS, except where distinctions need to be made between the various versions. In this book, the following abbreviations for product names are used:
Short name DB2 High Performance Load High Performance Unload IMS IPR Product name DB2 UDB for z/OS (currently supported versions) IBM IMS High Performance Load for z/OS, Version 2 Release 1 (Program Number: 5655-M26) IBM IMS High Performance Unload for z/OS, Version 1 Release 2 (this product) IMS Database Manager (currently supported versions) IBM IMS Parallel Reorganization for z/OS, Version 3 Release 2 (Program Number: 5655-M28)

Copyright IBM Corp. 2000, 2007

11

And for withdrawn products:

Short name DBT HSSR Product name The generic name for the following program products: v IMS System Utilities/Data Base Tools, Version 2, High Speed Sequential Retrieval (Program Number: 5685-093) v IMS System Utilities/Data Base Tools, Version 1, High Speed Sequential Retrieval (Program Number: 5668-856) PO HSSR FSU II Program Offering High Speed Sequential Retrieval, Version 2 (IFP 5787-LAC) IMS/VS Fast Scan Utility II, Version 2 (FDP 5798-DFN)

Summary of changes
Change include publication updates and product enhancements. | | | | | | | | | | | | | | | | | |

SC27-0936-06October 2007
IMS High Performance Unload for z/OS, Version 1 Release 2 has the following improvements: v Functional and performance improvements: In the unload utilities (FABHURG1 and FABHFSU), the number of buffers that are automatically set for unload data set are increased. For the details, see JCL requirements for FABHURG1 on page 38 and JCL requirements for FABHFSU on page 54. If the STEPLIB is APF-authorized, HSSR Engine uses the Media Manager to read VSAM ESDS database data sets, which saves the use of CPU time. v Improvements in the usability and readability of the product are made in Chapter 6, Application programming interface, on page 83. IMS High Performance Unload for z/OS, Version 1 Release 2 does not support IMS that are lower than Version 7. Therefore, the names of the IMS libraries that are referred to by the catalog procedure, provided by the product, are changed to those of IMS Version 8 and higher. The documentation changes that are provided by APARs PK38688, PK47931, and PK49836 are applied.

SC27-0936-05January 2007
This edition covers the functional changes that are provided by the following APARs: PK11534, PK17804, PK24577, PK24974, PK28097, PK32595, and PK33118. The major enhancements are as follows: v The CHECKREC control statement is added to the FABHURG1 unload utility by APAR PK11534. See CHECKREC control statement on page 44. v The SKIPVLC control statement is added to HSSR Engine by APAR PK28097. See SKIPVLC control statement on page 138. v The Get Next call with two SSAs to retrieve the second level dependent segment is supported in HP Unload API by APAR PK32595. See DL/I calls supported by each API set on page 90. v IMS version 10 is supported by APAR PK33118.

12

Users Guide

 To use the parallel RECONs, you must specify the IMSPLEX= and the DBRCGRP= parameters in the JCL EXEC statement. See Parameters required by the IMS DBRC SCI registration on page 26. The FABHURG1 and FABHFSU unload utilities support the large format data set for unload data sets.

SC27-0936-04October 2005
This edition covers the functional enhancements provided by the following APARs: PQ97692, PQ99842, PK01994, PK04911, PK06057, PK07881, PK07882, PK08900, and PK11209. The major enhancements are as follows: v IBM-provided exit routine FABHKEYX is available in the FABHURG1 unload utility by APAR PK01994. See Exit routine FABHKEYX for distributing unload records on page 116. v Get Next call with a qualified SSA on root segments is supported in HP Unload API by APAR PK04911. See DL/I calls supported by each API set on page 90. v Keywords URG1BUFNO and FSUBUFNO are added to the default option table (FABHOPT) by APAR PK06057. See Replacing the HSSR option table (FABHOPT) on page 336. v Function to retrieve HDAM or HIDAM root segments in a secondary index sequence is supported by APAR PK07882. See For using a secondary index on page 32. v JCL compatibility with IMS HD Reorganization Unload is supported by APAR PK11209. See Chapter 14, Using JCL for IMS HD Reorganization Unload to run FABHURG1, on page 269.

SC27-0936-03November 2004
This edition covers the following functional enhancements to this product: PQ80191 This APAR enables the product to run under IMS Version 9 Release 1. PQ81675 This APAR adds the support of the DFSHALDB DD statement, which is used to select a single partition to be processed in the API function (DLI or DBB region) of High Performance Unload. For details, see Consideration for HALDB single partition processing on page 102. PQ83387 This APAR adds support for HALDB partitions that are defined as HALDB Online Reorganization (OLR) capable. See the considerations described in For HALDB Online Reorganization capable partitions on page 31. PQ85786 This APAR adds the function to set buffer numbers for VSAM KSDS automatically. PQ93668 This APAR adds the support of the IMSDALIB DD statement. IMS Parallel Reorganization for z/OS, Version 3 Release 1 requires High Performance Unload that has this APAR applied. This edition also includes the changes added by the following APARs: v PQ69413, PQ70680, PQ70768, PQ72433, PQ76387, PQ77099, and PQ79194.

Chapter 1. Introduction

13

SC27-0936-01 and SC27-0936-02January 2003

PQ48541 This APAR adds the description that the GOT control statement becomes valid if DBRC is inactive in the FABHFSU unload utility. PQ49420 This APAR modifies High Performance Unload so that using an uninitialized OSAM database as input causes an error. High Performance Unload is modified so that, before getting access to a database, it checks the status of each data set in that database. If it finds an uninitialized data set, it causes an abend U4013. For High Availability Large Database (HALDB), the first time High Performance Unload gets access to a partition, it checks the status of the data sets in that partition. If it finds an uninitialized data set, it causes an abend U4013. PQ55674 This APAR adds a new control statement, PARTEXTR, to the HSSREXTR DD for the FABHEXTR exit routine of the FABHURG1 unload utility. The PARTEXTR control statement specifies how many database records are to be extracted from each HALDB partition. PQ57815 This APAR modifies High Performance Unload so that Segment Edit/Compression routines are loaded and deleted by the IMS IMODULE service. The APAR also adds message FABH0853E. PQ57581 This APAR enables High Performance Unload to run under IMS Version 8. PQ59358 This DOC APAR is devoted to explanations for three messages: v The explanation for message FABH0431W is expanded to cover all the conditions in which that message is issued. v Explanations of messages FABH0092W and FABH0358W, which had been missing, are added. PQ59762 This DOC APAR adds a description of the conditions in which the header record flag introduced by APAR PQ22654 for HSSR V2R3 causes an incompatibility. If an unloaded data set has been created by specifying the DECN control statement for a database that contains a compressed segment, that data set is not compatible with an unloaded data set created by the IMS HD Reorganization Unload utility. PQ62843 This APAR adds support for the Return Code Edit exit. This APAR provides a new exit for the HSSR Engine of IMS High Performance Unload. This exit, called the Return Code Edit exit (FABHRCEX), can be used to modify the return codes issued by HSSR application programs. PQ66914 This DOC APAR adds the formerly insufficient explanation of HALDB formats. The description is now as follows: A HALDB can be unloaded in *HD format by FABHURG1, or in UL format by FABHFSU. Whichever format the HALDB is in, both the IPR Reload utility of IMS Parallel Reorganization for z/OS, Version 2 Release 1 and IMS High Performance Load for OS/390, Release 1 regard it internally, and therefore refer to it, as having PHD format.

14

Users Guide

PQ67004, PQ67296, PQ69199 These APARs add the following functions to the HSSR call: v The application programming interface for High Performance Unload is extended to support GN and GNP calls with an unqualified SSA for a dependent segment type of an HD database. v The application programming interface for High Performance Unload is extended to support EXEC DLI commands.

SC27-0936-00November 2000
This guide covers High Performance Unload, which is a follow-on product to the IMS System Utilities/Data Base Tools (DBT) Version 2 High Speed Sequential Retrieval (DBT V2 HSSR). The compatibility with DBT V2 HSSR and other prior products is summarized in Chapter 13, Compatibility with earlier products, on page 255. One of the major enhancements to High Performance Unload is the addition of support for IMS Version 7 (IMS V7), specially High Availability Large Database (HALDB), introduced in IMS V7. (See Chapter 7, Processing High Availability Large Databases, on page 103.)

Program functions
This section explains the program functions of High Performance Unload.

Major features and benefits

High Performance Unload offers the following features and benefits: v Fast segment retrieval from databases High Performance Unloads segment retrieval engine, HSSR Engine, provides the function to retrieve segments much faster than DL/I. The unload utilities FABHURG1 and FABHFSU benefit. Also, batch DL/I application programs that use GN calls to read database can use the facility. Programs that read large portions of a database sequentially may get significant reductions in elapsed time and CPU use. You do not have to recompile or relink-edit the application program to use HSSR Engine. v User exit facility to allow additional processing for retrieved segments Each of the unload utilities provides the user exit facility, which provides more control on unload process than IMS HD Reorganization Unload utility. v Ability to continue processing after sequence errors High Performance Unload optionally does sequence-key checks for twin chains. You can select the behavior for a sequence error from the following: High Performance Unload gets to abend (KEYCHECK ABEND) High Performance Unload returns a GG status code and does not unload the segment containing the error, or its dependents (KEYCHECK GG and SKERROR n) High Performance Unload returns a GX status code and unloads the segment in error (KEYCHECK GX) If the DIAGG control statement is specified, High Performance Unload gives you diagnostic information of each sequence error. v Reading a corrupted database High Performance Unload options give you greater control when you are unloading a database that has an incorrect pointer:
Chapter 1. Introduction

15

 SKERROR option can be used to bypass pointer errors. BYINDEX option can be used to force the roots of HIDAM or PHIDAM database to be accessed from the primary index. If the DIAGG control statement is specified, High Performance Unload gives you diagnostic information about each pointer error.

Database organizations supported

High Performance Unload supports the following database organizations: v HDAM (Hierarchical Direct Access Method) v HIDAM (Hierarchical Indexed Direct Access Method) v PHDAM (Partitioned HDAM) v PHIDAM (Partitioned HIDAM) v HISAM (Hierarchical Indexed Sequential Access Method) v SHISAM (Simple HISAM) You can unload a partition or a sequence of partitions of a PHDAM or PHIDAM database. Other database organizations are not supported by High Performance Unload. Notes: 1. Secondary index databases are supported, but are processed as independent databases. Processing of a partitioned secondary index is not supported. 2. IMS/ESA Partition Support Product for MVS/ESA (5697-A06) and IMS/ESA Partition Support Product for MVS/ESA Version 2 (5697-D85) are not supported.

System structure and data flow

An overview of the structure of High Performance Unload and its data flow is shown in Figure 1 on page 17. High Performance Unload runs in an IMS batch environment. High Performance Unload run-time environment initializer (FABHX034) is invoked first. The initializer gives control to the IMS region controller DFSRRC00, which passes control to the IMS program controller. High Performance Unload program controller is then invoked by the IMS program controller as an IMS batch application program. The High Performance Unload program controller calls HSSR Engine. HSSR Engine then reads the HSSROPT data set to initialize the Call Analyzer, Call Handler, and Trace and Diagnosis facilities, and reads the HSSRCABP data set to initialize the Buffer Handler. Call Analyzer initializes PCBs that have been specified to be serviced by HSSR Engine. Such PCBs are called HSSR PCBs (For details about HSSR PCB, see Chapter 6, Application programming interface, on page 83). Call Analyzer also initialize control blocks relating to the HSSR PCBs. Buffer Handler allocates a buffer pool for each data set group for each HSSR PCB. The High Performance Unload program controller loads the application program. Each DL/I call or EXEC DLI command to an HSSR PCB is processed by HSSR Engine. This call or command is called an HSSR call. If the PCB is not an HSSR PCB, HSSR Call Router passes control to the DL/I program request handler.

16

Users Guide

After the application program runs, it returns control to the High Performance Unload program controller. HSSR Engine terminates the processing and writes statistical reports to the HSSRSTAT data set. Then the program controller returns control to IMS. Any application program runs, it running in this High Performance Unloads run-time environment and serviced by HSSR Engine is called an HSSR application program. Unload utilities FABHURG1 and FABHFSU are HSSR application programs, and you can write your own HSSR application program.

Figure 1. System structure and data flow

The components of High Performance Unload are described in Part 1 and Part 2 of this guide: v For details about the JCL requirements for running an High Performance Unload job, see Chapter 2, Job control language, on page 21. v For details about the unload utilities FABHURG1 and FABHFSU, see: Chapter 3, Using the Unload utilities, on page 27 Chapter 4, Using FABHURG1 to unload IMS databases, on page 33 Chapter 5, Using FABHFSU to unload IMS databases, on page 49 Chapter 7, Processing High Availability Large Databases, on page 103 v For the requirements and considerations for HSSR application programs, see Chapter 6, Application programming interface, on page 83, and Chapter 7, Processing High Availability Large Databases, on page 103. v For details about the HSSROPT data set, see Chapter 8, Specifying options for HSSR Engine, on page 121. v For details about the reports and outputs produced by HSSR Engine, see Chapter 9, Reports and output from HSSR Engine, on page 141. v For details about the HSSRCABP data set, see Chapter 15, Tuning buffer handlers, on page 275.

Chapter 1. Introduction

17

Processing environment
This section explains the processing environments for High Performance Unload.

Software requirements
The operating system requirements of High Performance Unload are the same as those for IMS supported by High Performance Unload. High Performance Unload requires Database Manager of one of the currently supported versions of IMS. To use the Data Conversion exit of IMS, IMS/ESA Year 2000 Exit Tool Version 1 (5697-E04) is required (This product supports IMS versions up to Version 7). Note: No user-written Data Conversion exit routine (DFSDBUX1) is supported. | | To use the DB2 DL/I Batch support, one of the currently supported versions of DB2 UDB for z/OS is required.

Hardware requirements
The hardware requirements are the same as those for IMS.

Restrictions
High Performance Unload is subject to the following restrictions with respect to processing environment: v It cannot be run under IMS Utility Control Facility (UCF). v It does not support the checkpoint and restart capability. Restrictions related with each utility program are described in the chapters for each utility.

Compatibility with prior products

High Performance Unload is compatible with the following prior products: v DBT V2 HSSRIMS System Utilities/Data Base Tools Version 2, High Speed Sequential Retrieval (Program Number: 5685-093) v DBT V1 HSSRIMS System Utilities/Data Base Tools Version 1, High Speed Sequential Retrieval Program Number: 5668-856) v PO HSSRProgram Offering High Speed Sequential Retrieval Version 2 (IFP 5787-LAC) v FSU IIIMS/VS Fast Scan Utility II Version 2 (FDP 5798-DFN) See Chapter 13, Compatibility with earlier products, on page 255.

Publications and updates

This topic explains where to find DB2 and IMS Tools information on the Web, and explains how to receive information updates automatically.

High Performance Unload information on the Web

The DB2 and IMS Tools Library Web page provides current product documentation that you can view, print, and download. To locate publications with the most up-to-date information, refer to the following Web page:

18

Users Guide

http://www.ibm.com/software/data/db2imstools/library.html IBM Redbooks publications that cover DB2 and IMS Tools are available from the following Web page: http://www.ibm.com/software/data/db2imstools/support.html To automatically receive a weekly email that notifies you when new DCF documents are released, when existing product documentation is updated, and when new product documentation is available, you can register with the IBM My Support service. You can customize the service so that you receive information about only those IBM products that you specify.

Receiving updates automatically

To 1. 2. 3. register with the My Support service: Go to http://www.ibm.com/support/mysupport Enter your IBM ID and password, or create one by clicking register now. When the My Support page is displayed, click add products to select those products that you want to receive information updates about. The DB2 and IMS Tools category is located under Software->Data and Information Management->Database Tools & Utilities. 4. Click Subscribe to email to specify the types of updates that you would like to receive. 5. Click Update to save your profile.

Prerequisite knowledge
Before reading this information, you should understand basic IMS concepts, the IMS environment, and your installations IMS system.

How this information should be read

This information is designed for system programmers, application programmers, system analysts, database administrators, and computer operators who already have a working knowledge of IMS and wish to gain expertise in the use of High Performance Unload. If you have had no experience with DBT HSSR or PO HSSR, you should first read Chapter 1 to get a good start with this product. Chapter 1 covers the following general topics: v Introduction to the functions of High Performance Unload v Typical benefits you can get by using High Performance Unload v System structure of High Performance Unload v Processing environment for using High Performance Unload Then proceed to Chapter 2 to study how to write JCL for High Performance Unload. Chapter 2 covers the following topics: v JCL statements for High Performance Unload v IBM-supplied cataloged procedures If you will be using High Performance Unloads unload utility, FABHURG1 or FABHFSU, proceed to Chapter 3 and then to the chapter for that utility. High Performance Unload provides application programming interface. If you would like to write your own application program, read Chapter 6.
Chapter 1. Introduction

19

If you want to use High Performance Unload to process HALDB, read Chapter 7. If you want to change the behavior of High Performance Unload by coding control statements, read Chapter 8. Description of the report and outputs from HSSR Engine are in Chapter 9. If you want to refer to reports produced by High Performance Unload while tuning your database, read Chapter 10. If you want to unload a database that has a pointer error, read Chapter 12. If you are migrating from DBT HSSR or PO HSSR, read Chapter 13. Read Part 2 only if you need to tune or customize High Performance Unload.

Accessibility features for High Performance Unload

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 major accessibility feature in High Performance Unload is keyboard-only operation for ISPF editors. It uses the standard TSO/ISPF interface. Note: The Information Management Software for z/OS Solutions Information Center, which is available at IBM Information Management Software for z/OS Solutions Information Center, and its related publications are accessibility-enabled. You can operate all features using the keyboard instead of the mouse.

Keyboard navigation
You can access the information center and IMS ISPF panel functions by using a keyboard or keyboard shortcut keys. You can find information about navigating the information center using a keyboard in the information center home at IBM Information Management Software for z/OS Solutions Information Center. For information about navigating the IMS ISPF panels using TSO/E or ISPF, refer to the z/OS V1R1.0 TSO/E Primer, the z/OS V1R5.0 TSO/E Users Guide, and the z/OS V1R5.0 ISPF Users Guide, Volume 1. 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.

IBM and accessibility

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

20

Users Guide

Chapter 2. Job control language

A High Performance Unload job can run in a DL/I, DBB, or ULU region by using DL/I JCL that is modified for each of them to a small degree. The detailed JCL requirements are described in JCL requirements on page 21. A cataloged procedure is provided for each region type. The procedures are described in Supported IMS region types and cataloged procedures on page 25. Topics: v JCL requirements v Supported IMS region types and cataloged procedures on page 25

JCL requirements
In this chapter, JCL statements commonly used by High Performance Unload utilities and user-written HSSR application programs are described. When running one of the following utilities, see also the JCL requirement section for that utility: v FABHURG1 database unload utility: See JCL requirements for FABHURG1 on page 38. v FABHFSU database unload utility: See JCL requirements for FABHFSU on page 54. When using one of the following Database Tuning Statistics functions, see the JCL section in Chapter 10, Using Database Tuning Statistics, on page 167. v Customizing the DB Record Length Distribution report (HSSRLDEF data set) v Recording the length of each database record (HSSRLOUT data set) v Printing long database records (FABHLDBR utility). Table 1 summarizes the DD statements for FABHX034.
Table 1. FABHX034 DD statements DDNAME Use Input Input Input Input Input Input Input Input Output Output Output Output Output Output LRECL=133 LRECL=133 LRECL=133 LRECL=80 LRECL=80 LRECL=80 LRECL=80 Format Need Required Optional Optional Optional Optional Optional Optional Optional Required Optional Optional Optional Optional Required

STEPLIB HSSROPT HSSRCABP DFSVSAMP ddname HSSRLDEF RECONx IMSDALIB IEFRDER HSSRSTAT HSSRLOUT HSSRTRAC HSSRBUTR HSSRSNAP
Copyright IBM Corp. 2000, 2007

21

Table 1. FABHX034 DD statements (continued) DDNAME IMS IMSACB PROCLIB IMSMON Use Input Input Input Output Input IMSVS.ACBLIB IMSVS.PROCLIB DUMMY IMSVS.SDFSRESL Format Need Optional Optional Required Required Required

DFSRESLB

The following describes the EXEC and data definition statements of the JCL to run High Performance Unload: EXEC The EXEC statement must be in the following format:
// EXEC PGM=FABHX034,PARM=(DFSRRC00/DLI,pgmname,psbname,...)

The program invoked by the PGM keyword on the EXEC statement is the High Performance Unload run-time-environment initializer named FABHX034. The PARM parameters, except the first one, must be specified in the same format as the PARM parameters for the IMS DLIBATCH or DBBBATCH procedures. The first parameter must contain the name of the IMS region controller, DFSRRC00, followed by a slash (/) and the name of the IMS region in which the job is to run. The region name must be one of DBB, DLI, or ULU. For each region type, a cataloged procedure is provided. See Supported IMS region types and cataloged procedures on page 25. When a HALDB is processed, the fourteenth parameter, which is the DBRC parameter, must be 'Y'. | | | STEPLIB DD Points to the High Performance Unload library, the IMS RESLIB library, and the user libraries that contain user programs and DFSMDA members. Notes: | | | | | | | | | 1. You do not need to APF-authorize the STEPLIB libraries. If however, the STEPLIB is not authorized for example by having unauthorized libraries concatenated, the DFSRESLB DD statement must be specified. 2. If all concatenations of the JOBLIB/STEPLIB are APF-authorized, Media Manager is used for reading VSAM ESDS database data sets. This reduces CPU time. 3. If you do not want to authorize the library that contain the DFSMDA members, specify the IMSDALIB DD statement. HSSROPT DD This optional statement defines an input data set containing optional control statements for HSSR Engine. For more information on HSSROPT control statements, see HSSROPT data set on page 122. HSSRCABP DD This optional statement defines an input data set containing the control statements that change buffering parameters for the CAB buffer handler

22

Users Guide

provided by HSSR Engine. For more information about HSSRCBAP control statements, see Chained Anticipatory Buffer Handler (CAB) on page 275. Note: Chained Anticipatory Buffering (CAB) is the default buffering method provided by HSSR Engine. DFSVSAMP DD This DD describes the data set that contains the buffer pool information required by the IMS DL/I buffer handler. If this data set is not specified, it is dynamically created by High Performance Unload. For this reason, this data set should not usually be specified. If you want to provide this data set, you should specify the minimum required number of buffers in the DFSVSAMP data set, because High Performance Unload does not use the buffers taken with the parameters specified in this data set. Otherwise, a larger region size is required in order to run High Performance Unload. You should however, specify DL/I buffers in DFSVSAMP in the following cases: v When you specify the BLDLPCK control statement in HSSROPT data set. In this case, HSSR Engine issues DL/I calls internally to build LPCKs. v When you do a migration unload of a database in which a logical child is defined. In this case, HSSR Engine issues DL/I calls internally to get information to be written in the header of the unload record of the logical child. v When APISET 3 is specified in the HSSROPT data set or by the site default option table. In this case, if a call that is not supported in APISET 2 is issued, that call and all succeeding calls are passed to DL/I and are processed by DL/I action modules. The usual DFSVSAMP definitions should be used in tuning the processing of these internal DL/I calls. ddname DD These DDs define the database data set to be processed. One statement of this type must be present for each data set that appears in the DBD describing the database. The value of ddname must match the ddname in the DBD. For an HIDAM database, DD statements must also exist for the data sets that represent the index. The DD statements that specify the index must contain ddnames specified in the DBD for the index database. No DD statements are required for the secondary indexes that are associated with this database unless the secondary indexes are used. If the BLDLPCK control statement is specified in the HSSROPT data set, the database in which the logical parent is defined must be specified. You must not code DCB=BUFNO=n or AMP='BUFND=n' options to request access method buffers for database data sets; HSSR Engine allocates its own buffer pool for each data set group. Note: If you use dynamic allocation, do not use the DD statement for the database data sets. For HALDBs, no DD statement needs to be specified for any database data set, because the data set is always dynamically allocated. HSSRLDEF DD This optional statement defines the input data set that contains control statements for requesting the DB Record Length Distribution report with your
Chapter 2. Job control language

23

own database record length ranges. For more information on HSSRLDEF control statements, see Activating the DB Tuning Statistics on page 167. RECONx DD This statement provides RECON1, RECON2, and RECON3 DDs under the same conditions as for standard IMS jobs. If RECON data sets should be allocated dynamically, do not specify these DDs. IMSDALIB DD This optional statement defines the library that contains the DFSMDA members for dynamic allocation. Allocation of the database data sets and the RECON data sets will be attempted in the following order: 1. The DD statements coded in the JCL stream 2. Dynamic allocation by data set definition that is contained in RECON (only for HALDB data sets) 3. Dynamic allocation members in the IMSDALIB concatenation or in the JOBLIB/STEPLIB concatenation If you specify this library on the IMSDALIB DD statement, it is highly recommended that you remove the library from the STEPLIB concatenation. IEFRDER DD This required statement defines the IMS log data set. HSSRSTAT DD This optional statement defines the output data set for HSSR Engine to write statistical output after the termination of the application program. For the details, see HSSRSTAT data set on page 141. HSSRLOUT DD This optional statement defines the output sequential data set, in which a small record is written for each database record when the DB Tuning Statistics function is activated by coding the DBSTATS control statement in the HSSROPT data set. For details about this data set, see Activating the DB Tuning Statistics on page 167. Note: The BLKSIZE and LRECL for the HSSRLOUT data set should not be specified in JCL. HSSR Engine determines them dynamically from the key length of the root segment. HSSRTRAC DD This optional statement defines an output data set in which the trace data is written. The DD statement is required whenever any of the following functions have been activated by HSSROPT statements. v The trace options TRHC and TRDB v The compare option CO v The diagnostic option DIAGG For details about these control statements, see Chapter 8, Specifying options for HSSR Engine, on page 121. For details about this data set, see HSSRTRAC data set on page 151. HSSRBUTR DD This optional statement defines the output data set on which the buffer handler trace is written. It is ultimately used as input for a buffer simulation run with the FABHBSIM utility.
//HSSRBUTR DD DSN=xxx,DISP=(,KEEP),UNIT=tape,...

HSSRSNAP DD This required statement defines the output data set on which snapshots are

24

Users Guide

written when an error occurs during initialization of HSSR Engine. For details, see HSSRSNAP data set on page 165. The remaining five DD statements (that is, IMS, IMSACB, PROCLIB, IMSMON, and DFSRESLB) are for IMS. See IMS Utilities Reference: Database.

Supported IMS region types and cataloged procedures

Two tasks required in preparing your JCL for High Performance Unload job are: v Selecting a region type v Modifying the DL/I JCL for a High Performance Unload job The following two sections discuss the procedures for these tasks.

Selecting region types

The DLI region is used to run an HSSR application programs by using PSB and DBD libraries. The DBB region is used to run programs by using an ACB library. The ULU region is used primarily in running the unload utilities FABHURG1 and FABHFSU. To run an application program in the ULU region, you must specify the physical DBD, but PSB is not needed. This ensures that all segments are data-sensitive. In a ULU region, IMS assumes that the IMS HD Reorganization Unload utility is run. Consequently, in a database sharing environment, DBRC grants the database access to an HSSR application program or utility under the same conditions as for the IMS HD Reorganization Unload utility. Upon entry to the application program, the PCB list is passed to the application program in accordance with Assembler or COBOL conventions. A PCB for an HSSR application program run in a ULU region is defined as an HSSR PCB. Note: You can use the HSSROPT DBDL1 control statement to override the HSSR PCB and force DL/I calls to be made to the database. If your application program must be protected from the addition of new segment types to the database, it should not be run in a ULU region.

Modifying the DL/I JCL for High Performance Unload

To run a High Performance Unload job, you must modify the normal DL/I JCL procedure. Use one of the following three IBM-supplied cataloged procedures, or prepare a similar procedure of your own: v FABHDLI for DLI region v FABHDBB for DBB region v FABHULU for ULU region These cataloged procedures are in the HPS.SHPSSAMP sample library. FABHDLI is used to run batch application programs by using DL/I and HSSR with PSBs and DBDs. It is similar to the DL/I procedure DLIBATCH. FABHDBB is used in conjunction with ACBs to run batch application programs. It too is similar to the DL/I procedure DBBBATCH.

Chapter 2. Job control language

25

FABHULU is used in conjunction with the ULU region types to run utilities and generalized application programs. You must provide the name of a physical DBD with DBD=keyword.

Parameters required by the IMS DBRC SCI registration

When the IMS DBRC SCI registration requires the IMSplex name and the DBRC group identification, you must add the parameters such as IMSPLEX= or PARM1= to the FABHULU, FABHDLI, and FABHDBB catalog procedures by yourself as shown in Figure 2.
//FABHULU PROC IMSDSN=IMSVS,DBTLMD=HPS.SHPSLMD0,SOUT=*, // MBR=TEMPNAME,CTRL=DFSRRC00,DBD=,BUF=7, // SPIE=0,TEST=0,EXCPVR=0,RST=0,PRLD=,SRCH=0, // CKPTID=,MON=N,LOGA=0,FMTO=T,IMSID=,SWAP=,DBRC=, // IRLM=,IRLMNM=,IMSPLEX=,PARM1= //* //G EXEC PGM=FABHX034,PARM=(&CTRL/ULU,&MBR,&DBD,&BUF, // &SPIE&TEST&EXCPVR&RST,&PRLD,&SRCH,&CKPTID,&MON, // &LOGA,&FMTO,&IMSID,&SWAP,&DBRC,&IRLM,&IRLMNM, // ,,,,,,,,&IMSPLEX,,'&PARM1') Figure 2. Adding IMSPLEX and PARM1 parameters to the FABHULU procedure

In the JCL that uses the FABHULU procedure, you can specify the parameter values as shown in Figure 3. | | |
//UNLOAD // // EXEC FABHULU, MBR=FABHFSU,DBD=PHDV0100,DBRC=Y, IRLM=Y,IMSPLEX=PLEX1,PARM1=DBRCGRP=001

Figure 3. Example of the parameter specification for the FABHULU procedure

26

Users Guide

Chapter 3. Using the Unload utilities

High Performance Unload provides two unload utilities, FABHURG1 and FABHFSU, both of which run as HSSR application programs. The utilities take advantage of the services provided by HSSR Engine. FABHURG1 is relatively simple. FABHFSU provides more functions than FABHURG1, and is compatible with FSU II. Both unload utilities are usually run in the ULU region. In that ULU region, all database segment types are unloaded automatically. These utilities can also be run in DLI region, and FABHURG1 can be run in the DBB region. The unloaded data set produced by these unload utilities can be used as input to the IMS HD Reorganization Reload utility and to other reload utilities that are compatible with it. Topics: v v v v v Program structure Functions available in both Unload utilities on page 28 Selecting an Unload utility for your use on page 29 Restrictions common to FABHURG1 and FABHFSU on page 29 Considerations on page 30

Program structure
This section explains the program structure of the Unload utilities.

FABHURG1 program structure

FABHURG1 runs as an HSSR application program. It accepts user requests via the SYSIN data set. HSSROPT options and HSSRCABP options can also be specified as input to FABHURG1. The Segment Statistics Report is produced in addition to the standard outputs produced by HSSR Engine. For details about FABHURG1, see Chapter 4, Using FABHURG1 to unload IMS databases, on page 33.

FABHFSU program structure

The FABHFSU utility consists of four programs: FABHFSU, FABHPSFM, FABHPSFC, and FABHPSFS. Note: Unless otherwise stated, the term "FABHFSU" refers to program FABHFSU, and "FABHFSU utility" to set of programs; FABHFSU, FABHPSFM, FABHPSFC, and FABHPSFS. FABHFSU has two different modes: the standard mode and the Parallel Scan Facility (PSF) mode. In both the standard mode and the PSF mode, FABHFSU runs as an HSSR application program. It accepts user requests via the CARDIN data set. HSSROPT options and HSSRCABP options can also be specified as input to the FABHFSU program. The Segment Statistics Report is produced in addition to the standard outputs produced by HSSR Engine.

Copyright IBM Corp. 2000, 2007

27

In the PSF mode, FABHFSU performs individual scan phases, which can run separately or concurrently to unload a multivolume database. In the PSF mode, the information is obtained from the Scan Control data set created by FABHPSFC. For details about FABHFSU running in standard mode, see Chapter 5, Using FABHFSU to unload IMS databases, on page 49. For details about FABHFSU running in PSF mode, see Chapter 11, Using the Parallel Scan Facility of FABHFSU, on page 219.

Functions available in both Unload utilities

Both FABHURG1 and FABHFSU offer the following functions and benefits: v Fast segment retrieval from databases High Performance Unloads segment retrieval engine, HSSR Engine, provides the facility to retrieve segments much faster than DL/I. See System structure and data flow on page 16. v Unloading a database without decompressing compressed segments Both FABHURG1 and FABHFSU can unload a database that uses the Segment Edit/Compression Exit without decompressing the segments. This can decrease the CPU time and elapsed time. For details, see: DEC control statement on page 42. DEC control statement on page 62. v Unloading a selected partition or a selected sequence of partitions of a HALDB For details, see Chapter 7, Processing High Availability Large Databases, on page 103. v Ability to monitor the need for database reorganization by examining statistical reports For details, see Chapter 10, Using Database Tuning Statistics, on page 167. v Ability to monitor the quality of HDAM or PHDAM randomizing by examining statistical reports For details, see Chapter 10, Using Database Tuning Statistics, on page 167. v Ability to continue processing after sequence errors HSSR Engine optionally performs sequence-key checks for twin chains. You can select the behavior for a sequence error from the following: HSSR Engine gets to abend. HSSR Engine returns a GG status code and unloads neither the segment in error nor its dependents. HSSR Engine returns a GX status code and unloads the segment in error. v Reading a corrupted database Options in High Performance Unload increases the control you have when you unload a database that contains an incorrect pointer or incorrect HISAM records: Incorrect HD pointers can be bypassed. The processing of the remainder of the incorrect HISAM record can be skipped. The root segments of HIDAM or PHIDAM database can be accessed by use of the primary index, instead of traversing the root twin chain and the RAP chain. For details, see Chapter 12, Unloading corrupted databases, on page 249.

28

Users Guide

Selecting an Unload utility for your use

The differences between the functions provided by FABHURG1 and those provided by FABHFSU are explained in this section.

FABHURG1 functions not available in FABHFSU

v Unloading a database in *CS format v Migration unload to HALDB and fallback unload from HALDB v User exit that enables system programmers to write a user record-formatting routine for formatting output records and an optional exit routine for editing segment data

FABHFSU functions not available in FABHURG1

v v v v Multiple outputs with different formats User exit that is compatible with user exit of IPR Unload utility Parallel Scan Facility Compatibility with FSU II

Which Unload utility should be used

IBM recommends that you use FABHURG1 unload utility if you want to do the following: v Unload the database in one of the five unload formats provided by FABHURG1. v Extract a part of the database by using FABHEXTR exit routine. v Do a migration unload to HALDB or a fallback unload from HALDB. If you want to edit segment data or to discard some segments on the basis of criteria you chose, you should use FABHFSU and write an exit routine for it. User exits are provided for FABHURG1, but they are intended to be used mainly by system programmers who have good knowledge of IMS database and HSSR Engine.

Restrictions common to FABHURG1 and FABHFSU

The restrictions that are common to FABHURG1 and FABHFSU are described in this section. For details see: v For restrictions specific to FABHURG1, see Restrictions on page 34. v For restrictions specific to FABHFSU, see Restrictions on page 50. The restrictions that apply to HSSR application programs also apply to FABHURG1 and FABHFSU. See Restrictions on page 93 in Chapter 6, Application programming interface, on page 83. Furthermore, the following restrictions apply to both FABHURG1 and FABHFSU: v The DBD that specifies the input database must be a physical DBD. v FABHURG1 and FABHFSU do not support sensitive, virtually paired segments. In the ULU region, the virtual logical child segment is ignored. In the DLI and the DBB regions, the processing depends on the SKIPVLC control statement. For details of the SKIPVLC control statement, see SKIPVLC control statement on page 138.

Chapter 3. Using the Unload utilities

29

The restriction applies to the unloading of databases for reorganization, because the data set input to IMS HD Reorganization Reload utility does not contain virtually paired segments. Note: Virtually paired segments are unloaded by FABHURG1 when migration unload (to HALDB) is performed. v If either of the following segment occurrences is skipped or lost during the unload, FABHURG1 and FABHFSU cannot be used in a reorganization to unload a corrupted database having logical relationships: A logical parent segment having one or more logical children. A logical child segment that is physically paired. v Make sure that no segments required by the IMS HD Reorganization Reload utility are missing during reorganization for either of the following reasons: Having no segment types defined as data-sensitive by a SENSEG statement. (This will not happen when you use a ULU region in unloading.) Having a user exit routine set a return code indicating that some segments should be skipped. v No support is available for multivolume output data sets whose extents reside on volumes of more than one device type.

Considerations
This section explains the considerations of Unload utilities.

For a logical parents concatenated key

By default, for a logical child segment with a logical parents concatenated key (LPCK) that is specified as "virtual" on the SEGM statement of the DBD, FABHURG1 returns blanks in the I/O area that usually contains LPCK, and FABHFSU returns binary zeros in the area. To have HSSR Engine build the LPCK and return it in the I/O area, you must specify BLDLPCK control statement in the HSSROPT data set. For details, see BLDLPCK control statement on page 123. When you unload an uncorrupted database that has a logical child whose LPCK is defined as virtual, and if BLDLPCK statement is not specified, you must run the IMS Database Prereorganization utility with the control statement DBR= to get a successful reload and prefix resolution. The control statement DBIL= gives incorrect results in this case. You must specify BLDLPCK statement when you unload a corrupted database that has a logical pointer error in a logical child whose LPCK is defined as virtual. Since you suspect that logical pointers are incorrect, you must also run the Database Prereorganization utility, using the DBIL= control statement. Otherwise, you will get an incorrect reload that would be detected during prefix resolution.

For an unloaded data set used for reorganization

A data set created by FABHURG1 in *HD format or by FABHFSU in UL format can be used as input for the IMS HD Reorganization Reload utility (DFSURGL0). If an unloaded data set has been created by specifying a DECN control statement for a database that contains a compressed segment, that data set is not compatible with the unloaded data set created by the IMS HD Reorganization Unload utility. For details, see DEC control statement on page 42 and DEC control statement on page 62. You cannot reload such an unloaded data set by using the IMS HD

30

Users Guide

Reorganization Reload utility (DFSURGL0), but you can reload it by using the IMS High Performance Load (Load utility or PSSR utility) or the IPR Reload utility. There are the following differences, which do not affect DFSURGL0: v IMS adds padding bytes of binary zeros to make the length of the segment even; FABHURG1 and FABHFSU do not. v IMS overrides the BLKSIZE specified in the JCL with the computed values. FABHURG1 and FABHFSU is overridden by the BLKSIZE specified.

For database sharing

In general, like any other unload utility during reorganization, FABHURG1 and FABHFSU must have exclusive control of the database while they run. In some cases, however, you might want to read the database while it is being updated by IMS. The update might be done either by IMS within the same program or by another IMS subsystem through concurrent execution. For such cases, see Database sharing support on page 97. The considerations discussed in the section also apply to FABHURG1 and FABHFSU.

For HALDB Online Reorganization capable partitions

High Performance Unload supports HALDB, and how to process HALDB is described in Chapter 7, Processing High Availability Large Databases, on page 103. High Performance Unload supports also the PHDAM or the PHIDAM partitions that are defined as HALDB Online Reorganization (OLR) capable. If one or more partitions are in the following HALDB OLR status, High Performance Unload cannot process the HALDB: v HALDB OLR is currently running. v HALDB OLR for the partition is suspended and one of the following options is specified for FABHURG1 or FABHFSU: DECN User exit routine *CS format for PHDAM PARTEXTR When none of the above options is specified, High Performance Unload can process the partition. However, the following options for the HSSR Engine are ignored: BYINDEX CO DBSTATS KEYCHECK SKERROR Because the DBSTATS control statement is ignored, the following reports are not printed: DB Call Statistics Report Randomizing Statistics Report DB Record Length Distribution Report The CAB Statistics Report for the partition of which HALDB OLR is suspended and partitions that follow this partition are not printed.

Chapter 3. Using the Unload utilities

31

In this case, the performance decreases because the HSSR Engine passes the DL/I calls to the IMSs DL/I call handler from the partition. It is recommended that you run High Performance Unload after the completion of the HALDB OLR.

For using a secondary index

A secondary index can be used to retrieve HIDAM or HDAM root segments. The target segment of the secondary index must be root segment. In the ULU region, you can specify the name of the secondary index by DBD control statement on page 57 for FABHFSU or by BYINDEX control statement on page 125 for others. In the DLI or the DBB region, the index name on these control statement is ignored. HSSR Engine uses the secondary index, which is coded by the PROCSEQ= parameter in the specified PCB. When the secondary index is used, the value of the search field of the index segment is set to the key feedback area of the HSSR PCB, instead of the root key. User exits can specify a next root segment by the value of the search field. Restriction: The following secondary indexes are not supported: v Secondary index whose target is not root segment v Secondary index with symbolic pointing v Secondary index containing index pointer segments with nonunique keys v Secondary index for databases other than HIDAM or HDAM

32

Users Guide

Chapter 4. Using FABHURG1 to unload IMS databases

This chapter describes how to use the FABHURG1 unload utility. FABHURG1 is an HSSR application program and is a functional replacement of IMS HD Reorganization Unload utility (DFSURGU0) and HISAM Reorganization Utility (DFSURUL0). Topics: v v v v v v v v v Program functions and benefits Program structure Restrictions on page 34 Operating instructions on page 34 Selecting a format for the unload output on page 35 JCL requirements for FABHURG1 on page 38 Input on page 40 OutputSYSPRINT data set on page 46 Examples on page 47

Program functions and benefits

FABHURG1 unloads IMS databases supported by High Performance Unload. FABHURG1 unloads databases faster than the IMS HD Reorganization Unload utility, because it runs as an HSSR application program. FABHURG1 offers the following functions in addition to the functions described in Functions available in both Unload utilities on page 28: v Unloading a database into one of the five standard formats. One of the five standard formats is acceptable as input to IMS HD Reorganization Reload utility or a compatible utility. For input processing by application programs, the other four standard formats are more practical. For the details of each format, see Selecting a format for the unload output on page 35. v Migration and fallback unload functions for HALDB FABHURG1 can unload a database to migrate an HIDAM or HDAM database to a PHIDAM database or a PHDAM database. FABHURG1 can also unload a database to do fallback from a PHIDAM or PHDAM database to an HIDAM or HDAM database. The unloaded data set created is compatible with the unloaded data set created by IMS HD Reorganization Unload utility. For details, see Migration unload and fallback unload on page 115. v Creating a database extract to perform database tuning experiment Using the exit routine FABHEXTR provided by IBM, you can create a small database extract from a large database, for use in database tuning experiments. For the details, see Creating a database extract with FABHEXTR on page 213.

Program structure
FABHURG1 runs as an HSSR application program. See System structure and data flow on page 16. The utility accepts user requests via the SYSIN data set. You can specify options for HSSR Engine by coding control statements in the HSSROPT data set and the HSSRCABP data set.

Copyright IBM Corp. 2000, 2007

33

Notes: 1. For the HSSROPT data set, see Chapter 8, Specifying options for HSSR Engine, on page 121. 2. For the HSSRCABP data set, see Chapter 15, Tuning buffer handlers, on page 275. The Segment Statistics Report is produced in addition to the standard output reports produced by HSSR Engine Notes: 1. For the Segment Statistics Report, see OutputSYSPRINT data set on page 46. 2. For reports produced by HSSR Engine, see Chapter 9, Reports and output from HSSR Engine, on page 141.

Restrictions
The following restrictions apply to FABHURG1 in addition to the those listed in Restrictions common to FABHURG1 and FABHFSU on page 29: v If the BLDLPCK control statement is not specified in the HSSROPT data set, the following restrictions applies: When FABHURG1 retrieves a logical child segment for which the logical parents concatenated key (LPCK) has been specified as "virtual" on the SEGM statement of the DBD, blanks are returned to the part of the I/O area where the LPCK is to be placed. Therefore, you must specify BLDLPCK control statement when unloading such a database if you specified the database in the DBIL= statement when running IMS Database Prereorganization utility. For performance reason, you should not specify BLDLPCK statement if you specified the database in the DBR= statement when running the Prereorganization utility. Migration unload of the secondary index is not supported. Migration unload of the HISAM database is not supported. If PTR=H or PTR=HB is defined as the parent segment of virtual logical child, FABHURG1 does not support the migration unload of the database. Fallback unload of the partitioned secondary index (PSINDEX) is not supported.

v v v v

Operating instructions
To run the FABHURG1 utility, do the following: 1. Select region type from ULU, DLI, or DBB. Prepare a JCL. (See JCL requirements for FABHURG1 on page 38.) 2. Select a format for the unload output. (See Selecting a format for the unload output on page 35.) 3. Code the required SYSIN control statements. (See SYSIN data set on page 40.) 4. Code HSSROPT and HSSRCABP control statements to specify the options for HSSR Engine. This is optional. (See HSSROPT data set on page 45 and HSSRCABP data set on page 45.) 5. Submit the JCL to run the FABHURG1 job. 6. Check the output reports and messages. (See OutputSYSPRINT data set on page 46.)

34

Users Guide

If you want to unload a corrupted database, see Chapter 12, Unloading corrupted databases, on page 249. For migration and fallback unload, see Migration unload and fallback unload on page 115.

Selecting a format for the unload output

FABHURG1 can unload a database in any of five formats, *HD, *CS, *F1, *F2, and *F3. These formats are called standard formats of FABHURG1. The *HD format is the default format. It is acceptable as input to the IMS HD Reorganization Reload utility or to a compatible utility. The other formats are used for processing by application programs.

*HD format
If you use *HD format, you can replace the IMS HD Reorganization Unload utility with the faster FABHURG1 utility when reorganizing a database. The *HD format is the default format. Notes: 1. If an unload dataset has been created by specifying the DECN control statement for a database that contains a compressed segment, the data set is not compatible with an unloaded data set created by the IMS HD Reorganization Unload utility. For details, see DEC control statement on page 42. You cannot reload such an unloaded data set by using the IMS HD Reorganization Reload utility (DFSURGL0), but you can reload it by using IMS High Performance Load (Load utility or PSSR utility) or the IPR Reload utility. 2. FABHURG1 *HD output records can be compared against the output records created by the IMS HD Reorganization Unload utility. To do so, add the optional SYSUT1 statement to your JCL to define the IMS unloaded data set to be used in the comparison. For details, read about SYSUT1 DD on page 39.

*F1 format
This section describes the *F1 format. It is a product-sensitive programming interface. See Programming interface information on page 484 to understand the restrictions associated with this type of material. Product-Sensitive Programming Interface

Chapter 4. Using FABHURG1 to unload IMS databases

35

FORMAT OF *F1 RECORDS STATEMENT REC1 REC1LEN REC1ZZ REC1SC REC1LEV REC1DATA DSECT DC H0 DC H0 DC X00 DC X00 EQU * OFFSET DEC HEX 0 2 4 5 6 0 2 4 5 6 DESCRIPTION

RECORD LENGTH FIELD ZZ (RESERVED FOR MVS) SEGMENT CODE SEGMENT LEVEL SEGMENT DATA AS RETURNED BY HSSR

This format is to be used for processing by application programs. When you use the *F1 Format, a variable-length record is written for each retrieved database segment containing the following data fields: v Segment code v Segment level v Segment data as returned by the HSSR call and as seen by HSSR application programs Notes: 1. If the database contains segments shorter than 8 bytes, do not send the output to tape. (A block of less than 18 bytes is not acceptable for a tape.) 2. If the database contains segments shorter than 12 bytes, the output cannot be processed by some Sort/Merge programs. (Some Sort/Merge programs require records with at least 18 bytes.) End of Product-Sensitive Programming Interface

*F2 format
This section describes the *F2 format. It is a product-sensitive programming interface. See Programming interface information on page 484 to understand the restrictions associated with this type of material. Product-Sensitive Programming Interface

36

Users Guide

FORMAT OF *F2 RECORDS STATEMENT REC2 REC2LEN REC2ZZ REC2SC REC2LEV REC2SYM REC2IOAL DSECT DC H0 DC H0 DC X00 DC X00 DC CL8 DC H0 H0 H0 H0 OFFSET DEC HEX 0 2 4 5 6 14 16 18 20 22 0 2 4 5 6 E 10 12 14 16 DESCRIPTION

REC2KOFS DC REC2KEYL DC REC2MKL DC

REC2DATA EQU *

RECORD LENGTH FIELD ZZ (RESERVED FOR MVS) SEGMENT CODE SEGMENT LEVEL SYMBOLIC SEGMENT NAME SEGMENT DATA LENGTH AS RETURNED BY HSSR KEY OFFSET WITHIN DATA KEY LENGTH OF THIS SEGMENT 0 FOR COMPATIBILITY WITH *F3 FMT SEGMENT DATA AS RETURNED BY HSSR

This format is to be used for processing by application programs. When you use the *F2 Format, a variable-length output record is written for each retrieved segment of the database. It contains the following data fields: v Segment code v Segment level v Segment name v Length of segment as returned by the HSSR call v Offset of sequence field within segment data (zero if the segment has no sequence field) v Length of sequence field (If the segment has no sequence field, zero is used.) v A field containing zeros for compatibility with *F3 format (In this field, the *F3 format contains the actual length of the concatenated PCB key feedback area.) v The segment data as returned by the HSSR call and as seen by HSSR application programs End of Product-Sensitive Programming Interface

*F3 format
This section describes the *F3 format. It is a product-sensitive programming interface. To understand the restrictions associated with this type of material, see Programming interface information on page 484. Product-Sensitive Programming Interface

Chapter 4. Using FABHURG1 to unload IMS databases

37

FORMAT OF *F3 RECORDS STATEMENT REC3 REC3LEN REC3ZZ REC3SC REC3LEV REC3SYM REC3IOAL REC3KOFS REC3KEYL REC3MKL REC3DATA DSECT DC H0 DC H0 DC X00 DC X00 DC CL8 DC H0 DC DC DC EQU H0 H0 H0 * OFFSET DEC HEX 0 2 4 5 6 14 16 18 20 22 22 0 2 4 5 6 E 10 12 14 16 16 DESCRIPTION

REC3KFD EQU *

RECORD LENGTH FIELD ZZ (RESERVED FOR MVS) SEGMENT CODE SEGMENT LEVEL SYMBOLIC SEGMENT NAME SEGMENT DATA LENGTH AS RETURNED BY HSSR KEY OFFSET WITHIN DATA KEY LENGTH OF THIS SEGMENT PCB KEY-FEED-BACK-LENGTH SEGMENT DATA AS RETURNED BY HSSR PCB KEY-FEED-BACK-AREA

This format is to be used for processing by application programs. The *F3 format has the same format as the *F2 format, except the *F3 format also contains the concatenated PCB key feedback area after the segment data. End of Product-Sensitive Programming Interface

*CS format
The communication industry standard format. This format is usable as input to IPR Reload or High Performance Load. Note: If a logical relationship is defined in the database and the database is unloaded in *CS format, you cannot use the unloaded file for reorganization.

JCL requirements for FABHURG1

Since FABHURG1 is an HSSR application program, it requires standard FABHX034 JCL. Those DD statements are described in Chapter 2, Job control language, on page 21. The additional JCL requirements for FABHURG1 are shown in Table 2.
Table 2. FABHURG1 DD statements DDNAME SYSIN SYSPRINT SYSUT1 SYSUT2 SYSUT3 Use Input Output Input Output Output Format LRECL=80 LRECL=133 HD Unload Need Optional Required Optional Required Optional

EXEC This statement invokes procedures FABHULU, FABHDLI, or FABHDBB. The required format is one of the following:
// // // EXEC FABHULU,MBR=FABHURG1,DBD=dbdname EXEC FABHDLI,MBR=FABHURG1,PSB=psbname EXEC FABHDBB,MBR=FABHURG1,PSB=psbname

38

Users Guide

SYSIN DD This optional DD statement defines the input data set containing control statements for FABHURG1. For the description of the control statements, see SYSIN data set on page 40. SYSPRINT DD This required statement defines the output data set to which FABHURG1 writes error messages and segment statistics. The data set can be defined as:
//SYSPRINT DD SYSOUT=A

SYSUT1 DD This optional statement defines an input data set created (in a previous step) by the IMS HD Reorganization Unload utility. Use it only for problem determination. It activates a comparison of *HD output records with the output records created by the IMS HD Reorganization Unload utility. FABHURG1 does not compare the lengths of the header or trailer records. If a mismatch is detected, FABHURG1 ends abnormally with an error message. The record created by FABHURG1 is compared with the record in SYSUT1 before any optional user exit routine is invoked. For records containing a logical child with a logical parents concatenated key that is specified as "virtual" on the SEGM statement of the DBD, the comparison is done as follows: v If a BLDLPCK control statement is specified, the entire record is compared. v If no BLDLPCK control statement is specified, the entire record except the LPCK field is compared. If the utility detects that a segment is not sensitive, or if a user exit routine requests that one or more segments be skipped, the comparison is halted. SYSUT2 DD This required statement defines the primary output data set on which the database is unloaded. The data set can reside on a tape or a direct access device. It may also be defined as DUMMY. | | | | | | | You can specify the number of buffers in the URG1BUFNO= option in the default option table (FABHOPT). For details, see Chapter 19, Setting site default options, on page 335. The buffers are obtained above the 16MB line. If neither the BUFNO subparameter of the DCB parameter on the DD statement nor the URG1BUFNO= option is given, the number of buffers is determined automatically. The buffers are approximately 1MB in total size and are above the 16MB line. If a block size is not specified on the SYSUT2 DD statement, FABHURG1 uses the following block size: v For device type 3380, the default block size is 23K. If the database contains segments larger than 23K, the maximum block size of 32K is used. v For device type 3390, the default block size is 28K. If the database contains segments larger than 28K, the maximum block size of 32K is used. v For device type 9345, the default block size is 22K. If the database contains segments larger than 22K, the maximum block size of 32K is used. v For device types other than the preceding, the default is the maximum capacity for the device types. SYSUT3 DD This optional statement defines a secondary output data set that contains a

Chapter 4. Using FABHURG1 to unload IMS databases

39

second copy of the SYSUT2 data set. If SYSUT2 is defined as DUMMY, High Performance Unload ignores this statement. The same rules for BUFNO and BLKSIZE apply as for SYSUT2. Notes: 1. The LRECL values for SYSUT2 and SYSUT3 data sets are determined as follows: For the unload formats *F1, *F2, and *F3: v If the LRECL value prepared in the JCL DD statement is used when the value is specified in either of the following ways: Explicitly by the LRECL subparameter of DCB parameter or Implicitly, for example, by using a model data set or by using the DFSMS/MVS DATACLAS parameter. v If the LRECL value is not specified either explicitly or implicitly, the default record size (block size minus 4) is used. For *HD unload format: v The LRECL value prepared in the JCL DD statement is always ignored, and the default record size, (block size minus 4) is used. 2. The large format data set can be specified for SYSUT2 and SYSUT3 when z/OS Version 1 Release 7 or later and IMS Version 10 or later are used.

Input
This section describes the following three data sets that contain the following control statements: v SYSIN: Control statements for the FABHURG1 utility v HSSROPT: Control statements for HSSR Engine v HSSRCABP: Control statements for the buffer handler of HSSR Engine

SYSIN data set

This section explains the SYSIN data set.

Function
Normally, unless a user record-formatting routine or an optional user exit routine is invoked, only two control statements are required for FABHURG1: the PCB control statement and the FRMT control statement. If the defaults are taken, neither of these is required. Other control statements for general use are the following: v DEC v PARTITION v SEGSTAT v CHECKREC v MIGRATE v FALLBACK FABHURG1 provides a user exit interface for system programmers. System programmers can provide their own record-formatting routine to unload the database into their own format rather than one of the standard formats. For the SYSIN control statement intended mainly for system programmers to use, see Writing user record-formatting routine on page 317.

40

Users Guide

Format
This data set contains 80-byte fixed-length records. The control statements can be coded in the input stream or accessed as members of a partitioned data set.

PCB control statement

This optional control statement is used to select an HSSR PCB used for the database call in FABHURG1. Use this statement only when you run FABHURG1 in a DLI or DBB region and you want to specify an HSSR PCB other than the first one. If you run FABHURG1 in the ULU region, you do not need to specify the statement.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PCB pcbnbr dbdname

Position 1 5-14

Description Code the PCB keyword to identify this as a PCB statement. Code an HSSR-PCB number. Specify 1 for the first HSSR PCB in the PSB. The number specified need not contain leading zeros, nor need it be aligned. Note: HSSR-PCB number is the sequence number, within the PSB, that is assigned to each HSSR PCB. If, for example, the first and the third database PCBs are defined as HSSR PCBs, but not the second PCB, then the third database PCB has the HSSR-PCB number of 2.

16-23

Code a DBD name.

The HSSR PCB used for the database call in FABHURG1 is determined by the following rule: v If no PCB control statement is provided, the first HSSR PCB is used. v If dbdname is blank, the HSSR PCB identified by pcbnbr is used. v If dbdname is not blank, the first HSSR PCB that refers to the named DBD is used. v If no HSSR PCB that matches with the specification is defined, FABHURG1 issues an error message.

FRMT control statement

This optional control statement specifies the output format of the unloaded database. Use this statement only when specifying a format other than *HD.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 FRMT frmt

Position 1

Description Code the FRMT keyword to identify the format control statement.
Chapter 4. Using FABHURG1 to unload IMS databases

41

Code the output format name, which can be either of the following: v The name of one of the standard formats provided by the utility: *HD, *CS, *F1, *F2, or *F3. The default is the *HD unload format, for which you do not need this statement. v The load module name of a user record-formatting routine (see Writing user record-formatting routine on page 317).

Notes: 1. If you specify a control statement such as MIGRATE or FALLBACK, you cannot specify any format other than *HD. 2. If *CS is specified and one or more partitions of PHDAM are in the HALDB OLR cursor-active status, FABHURG1 ends abnormally.

DEC control statement

The DEC control statement, which activates the decompress option, specifies whether FABHURG1 is to decompress database segments.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DECd

Position 1 4

Description Code the DEC keyword to activate the decompress option. The 1-character entry d specifies whether compressed segments should be decompressed by FABHURG1. This entry is required. Use one of the following keywords: Keyword Y N Description Compressed segments are decompressed. This is the default. Compressed segments are not decompressed. Code N only when you want to have compressed segments in the output data sets. If an unloaded data set has been created by specifying this DECN option for a database that contains a compressed segment, the data set is not compatible with the unloaded data set created by the IMS HD Reorganization Unload utility. You cannot reload such an unloaded data set by using the IMS HD Reorganization Reload utility (DFSURGL0), but you can reload it by using the IMS High Performance Load (Load utility or PSSR utility) or the IPR Reload utility.

Notes: 1. The default of this control statement can be changed by replacing the default option table (FABHOPT). Specify the URG1DEC=NO parameter on the FABHTOPT macro statement. For details, see Chapter 19, Setting site default options, on page 335.

42

Users Guide

2. If there is a segment type for which a Segment Edit/Compression exit routine is specified and the use of a Data Conversion exit is designated, the DECN option is ignored and the process continues with DECY. 3. If the DECN option is specified and one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, FABHURG1 ends abnormally.

PARTITION control statement

When you restrict the partitions to be unloaded, use this optional control statement for a partitioned database.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PARTITION partnme nnnn

Position 1 11

Description Code the PARTITION keyword to identify this as a PARTITION statement. Code the partition name partnme from which you want to start the unloading. This is a required parameter.

19

This optional parameter nnnn specifies the total number of partitions to be unloaded. The number nnnn must be left-justified, and its length must be less than or equal to four. If this parameter is not specified, the default of 1 is assumed.

Notes: 1. When you specify the PARTITION control statement, you must pay attention to the sequence of partitions. If no partition selection exit routine is used, the sequence of partitions is determined from the sequence of high key values. If a partition selection exit routine is used, the sequence of partitions depends on the routine. 2. This control statement cannot be specified with a MIGRATE or FALLBACK control statement. 3. If you want to unload all partitions, you should not specify the PARTITION control statement.

SEGSTAT control statement

This optional control statement instructs FABHURG1 to produce the segment statistics report for each partition that is processed. See FABHURG1 Segment Statistics report on page 46 for partitions in the section OutputSYSPRINT data set on page 46.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 SEGSTAT PART

Position

Description

Chapter 4. Using FABHURG1 to unload IMS databases

43

1 9

Code the SEGSTAT keyword to identify the statement. Code the PART keyword to print the partition-wide segment statistics report for each partition that is processed and from which at least one segment is retrieved.

Note: In any one of the following cases, the partition-wide statistics are not printed: v The SEGSTAT statement is specified for a nonpartitioned database. v The PART keyword is not specified. v A keyword other than PART is specified as the operand of the SEGSTAT statement.

CHECKREC control statement

This optional control statement specifies whether the particular record is written just behind the header record in the unload data set. This record is used by IMS High Performance Load for it to know certain status of the database at unloading time. This control statement is used only for the *HD unload format.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 CHECKREC ddd

Position 1 10

Description Code the CHECKREC keyword to identify the statement. Use one of the following keywords: Keyword YES NO Description The particular record is written. The particular record is not written. This is the default.

Note: The default of this control statement can be changed by replacing the default option table (FABHOPT). Specify the URG1CHKRC=YES parameter on the FABHTOPT macro statement. For details, see Chapter 19, Setting site default options, on page 335.

MIGRATE control statement

This optional control statement is used to make FABHURG1 perform the migration unload of a nonpartitioned database.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 MIGRATE

Position 1

Description Code the MIGRATE keyword to make FABHURG1 perform the migration unload of a nonpartitioned database.

Notes:

44

Users Guide

1. This control statement cannot be specified with a control statement of PARTITION or FALLBACK. 2. If MIGRATE control statement is specified, FABHURG1 must be executed in the ULU region. 3. The input database must be either a HIDAM or an HDAM database. If PTR=H or PTR=HB is defined as the parent segment of virtual logical child, FABHURG1 does not support the migration unload of the database. Migration unload of a secondary index or HISAM database is not supported. 4. If a logical child is defined in the input database, and you want better performance, code an appropriate number of IMS buffer pools in DFSVSAMP DD of your JCL. For details, refer to JCL requirements on page 21.

FALLBACK control statement

This optional control statement is used to initiate the fallback unload of a partitioned database.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 FALLBACK

Position 1

Description Code the FALLBACK keyword to instruct FABHURG1 to perform the fallback unload of a partitioned database.

Notes: 1. This control statement cannot be specified with a control statement of PARTITION or MIGRATE. 2. If FALLBACK control statement is specified, FABHURG1 must be executed in the ULU region. 3. The input database must be either a PHIDAM or a PHDAM.

HSSROPT data set

For a complete description of the HSSROPT control statements, see HSSROPT data set on page 122. This data set is required when unloading a corrupted database. It contains the HSSROPT control statements SKERROR, DIAGG, and KEYCHECK. SKERROR causes incorrect HD pointers or HISAM records to be skipped; DIAGG generates diagnostic information on the incorrect pointers and records; and KEYCHECK GG returns a GG status code to FABHURG1 rather than ending abnormally when a sequence error is detected.

HSSRCABP data set

For a complete description of the HSSRCABP control statements, see HSSRCABP control statements on page 280. Any of the HSSRCABP options that are appropriate to your task can be used.

Chapter 4. Using FABHURG1 to unload IMS databases

45

OutputSYSPRINT data set

FABHURG1 produces the following reports in SYSPRINT data set: v FABHURG1 Unload Parameters Report v FABHURG1 Segment Statistics Report In addition to these reports, reports and statistics produced by HSSR Engine are written in HSSRSTAT and HSSRTRAC data sets (see Chapter 9, Reports and output from HSSR Engine, on page 141).

Function
FABHURG1 SYSPRINT data set contains the following two output reports: v FABHURG1 Unload Parameters Report v FABHURG1 Segment Statistics Report

Format
This data set contains 133-byte fixed-length records. When coded in the JCL, block size must be a multiple of 133.

FABHURG1 Unload Parameters report

This report contains the parameters used by FABHURG1 for this run (see Figure 4).

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHURG1 UNLOAD PARAMETERS" DATE: 10/26/2007 TIME: 01.01.01

PAGE: 1 FABHURG1 - V1.R2

SYSIN CONTROL STATEMENTS FOLLOW: PARTITION PARTDB1 5 SEGSTAT PART UTILITY PARAMETERS USED FOR THIS EXECUTION ARE: REGION-TYPE=ULU PSBNAME=HDAMPART DBDNAME=HDAMPART PCB 1 FRMT *HD NO EXIT OFFS 0 ULEN 0 USEGMAX 0 DECY CHECKREC NO

Figure 4. FABHURG1 Unload Parameters report

FABHURG1 Segment Statistics report

This report contains a printed copy of the segment statistics (see Figure 5 on page 47). The statistics provided for each segment are segment code, level, the number of segments retrieved for that segment type, and the number written to the output data set. If there is a difference between the number retrieved and the number written, that difference is shown. The totals and total errors for the database are provided. Also a message is printed stating that the database unload is complete.

46

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=ORDHDAM SEGMENT S-C LV RETRIEVED OUTPUT

"FABHURG1 SEGMENT STATISTICS" DATE: 10/26/2007 TIME: 13.05.34 DIFFERENCE

PAGE: 1 FABHURG1 - V1.R2

ORDER 1 1 6 6 0 ORDART 2 2 4 4 0 DELIVER 3 3 2 2 0 SCHEDULE 4 3 2 2 0 HISTORY 5 3 2 2 0 ---------------------------------------------------------------*TOTAL 16 16 0 *TOTAL ERRORS 0

Figure 5. FABHURG1 Segment Statistics report

Figure 6 shows the segment statistics report for a HALDB partition that is printed when 'SEGSTAT PART' control statement is specified.

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAMMDSG; PARTITION=PARTDB1 SEGMENT S-C LV RETRIEVED OUTPUT

"FABHURG1 SEGMENT STATISTICS" DATE: 10/26/2007 TIME: 12.34.56

PAGE: 1 FABHURG1 - V1.R2

DIFFERENCE

ORDER 1 1 5 5 0 ORDART 2 2 5 5 0 DELIVER 3 3 3 3 0 SCHEDULE 4 3 3 3 0 HISTORY 5 3 5 5 0 ------------------------------------------------------------*TOTAL 21 21 0

Figure 6. FABHURG1 Segment Statistics for HALDB

Examples
In this section, the following two examples are shown: v Example 1: Running FABHURG1 in ULU region v Example 2: Running FABHURG1 in DLI region on page 48 For examples that process HALDB, see Chapter 7, Processing High Availability Large Databases, on page 103.

Example 1: Running FABHURG1 in ULU region

To create an unloaded data set that can be used as input to the IMS HD Reorganization Reload utility, you can use the JCL shown in Figure 7.
// EXEC //HDAM //SYSPRINT //SYSUT2 // FABHULU,MBR=FABHURG1,DBD=USERDBD DD DSN=IMSDB.HDAM,DISP=SHR DD SYSOUT=A DD DSN=IMSDB.HDUNLD,DISP=(,CATLG),UNIT=TAPE, VOL=SER=xxxxxx

Figure 7. FABHURG1 JCL for unloading an HDAM database

The unloaded data set is specified by the SYSUT2 DD statement. In this example, the HDAM DD statement specifies the database data set to be unloaded.

Chapter 4. Using FABHURG1 to unload IMS databases

47

In the ULU region, the PCB that is dynamically created by IMS from the specified DBD is always treated as an HSSR PCB. You do not need to code a PCB control statement in the SYSIN data set. If you want to unload the database without decompressing the compressed segments, code the SYSIN DD as follows:
//SYSIN DD * DECN /*

An unloaded data set created by this method can be reloaded by IMS High Performance Load (Load utility or PSSR utility) or the IPR Reload utility.

Example 2: Running FABHURG1 in DLI region

If you run FABHURG1 in the DLI region, you must code a PCB statement in the SYSIN data set, and you must define the PCB as an HSSR PCB by coding a HSSRPCB or HSSRDBD control statement in the HSSROPT data set. You can use the JCL shown in Figure 8. In the example, an HSSRDBD statement is used to specify all PCBs that refer to the DBD as HSSR PCBs. The first database PCB that refers to the DBD is used to read the database, because only the DBD name is specified on the PCB control statement.
// EXEC FABHDLI,MBR=FABHURG1,PSB=USERPSB,DBRC=Y //SYSIN DD * PCB USERDBD FRMT *F1 /* //HSSROPT DD * HSSRDBD *ALL /* //SYSPRINT DD SYSOUT=A //SYSUT2 DD DSN=IMSDB.HDUNLD,DISP=(,CATLG),UNIT=TAPE, // VOL=SER=xxxxxx Figure 8. FABHURG1 JCL specifying SYSIN control statements

In this example, it is assumed that the RECON data sets and the database to be unloaded are dynamically allocated. The unloaded data set is in the specified format, because the FRMT control statement is coded to specify the unload formatin this case, *F1 format.

48

Users Guide

Chapter 5. Using FABHFSU to unload IMS databases

The FABHFSU unload utility unloads IMS databases and provides compatibility with FSU II. FABHFSU can produce multiple unloaded output data sets. Each unloaded data set can contain different combinations of segments in different formats. Running as an HSSR application program, FABHFSU makes full use of HSSR Engine. FABHFSU has two different modesthe standard mode and the Parallel Scan Facility (PSF) modein which the different types of unload operations are run. In both modes, the FABHFSU runs as an HSSR application program. In this chapter, the basic functions of FABHFSU run in the standard modes are explained. In the next chapter, the functions available in the PSF mode and the compatibility with FSU II are described. Topics: v v v v v v v v v v Program functions and benefits Program structure on page 50 Restrictions on page 50 Operating instructions on page 50 Selecting a format for the unload output on page 51 JCL requirements for FABHFSU on page 54 Input on page 56 OutputPRNTOUT data set on page 67 User exit on page 71 Examples on page 79

Program functions and benefits

FABHFSU, running in standard mode, offers the following functions in addition to those described in Functions available in both Unload utilities on page 28: v Ability to create up to three data sets in one single execution Different record formats can be specified for each output data set. If FABHFSU runs in the DLI region, different PCBs that refer to the same DBD can be specified for each output data set. v User exit facility for application programmers The user exit is compatible with the user exit of FABHFSU in DBT HSSR and with the user exit of IPR Unload. A different user exit routine can be specified for each output. v Unload a specified range or portion of an HISAM, HIDAM, or HDAM database You can unload the portion of the database to be read. For HISAM or HIDAM, the limits of the range are specified as keys. For HDAM, the limits of the range are defined as relative block numbers of the CIs or blocks in the Root Addressable Area.

Copyright IBM Corp. 2000, 2007

49

Program structure
FABHFSU runs as an HSSR application program (see System structure and data flow on page 16). The program accepts user requests via the CARDIN data set. Options for HSSR Engine can be specified by coding control statements in HSSROPT data set and HSSRCABP data set. For details, see: v For HSSROPT data set, see Chapter 8, Specifying options for HSSR Engine, on page 121. v For HSSRCABP data set, see Chapter 15, Tuning buffer handlers, on page 275. The Segment Statistics Report is produced in addition to the standard output reports produced by HSSR Engine. For details, see: v For the Segment Statistics Report, see OutputPRNTOUT data set on page 67. v For the reports produced by HSSR, see Chapter 9, Reports and output from HSSR Engine, on page 141.

Restrictions
FABHFSU has the following restrictions in addition to those described in Restrictions common to FABHURG1 and FABHFSU on page 29: v FABHFSU cannot be run in the DBB region; FABHDBB procedure cannot be used for FABHFSU. v HSSRPCB and HSSRDBD control statements specified in the HSSROPT data set are always ignored. In FABHFSU, HSSR PCBs are specified by the DBD control statement and the PSB control statement in the CARDIN data set (see CARDIN data set on page 56). v By default, for a logical child segment for which a logical parents concatenated key (LPCK) is specified as "virtual" on the SEGM statement of the DBD, binary zeros are returned to the I/O area when that segment is retrieved. This is because of the compatibility with FSU II. If you need to have the LPCK builtfor example, when you have specified the DBIL control statement in the Database Prereorganization utilityyou must specify the BLDLPCK control statement in the HSSROPT data set when you run the FABHFSU job. v The PROCOPT statement fields on the PCB and SENSEG statements can have any value acceptable to IMS, although only the PROCOPTs listed in Processing option (PROCOPT) requirements on page 84 have meaning to FABHFSU. Note: In a database-sharing environment, DBRC uses the PROCOPT values to check whether database access can be granted (see Handling data set extensions on page 97). v Field sensitivity can be specified during PSBGEN, but is ignored by FABHFSU.

Operating instructions
To run the FABHFSU utility in standard mode, do the following: 1. Select a region type from ULU and DLI, and prepare a JCL. (See JCL requirements for FABHFSU on page 54.) 2. Code DBD and PSB control statements in CARDIN data set to specify HSSR PCBs used for the database call and to specify the segment sensitivity. The DD

50

Users Guide

name and record format for each output data set can be specified in a PSB control statement. (See Selecting a format for the unload output on page 51 and CARDIN data set on page 56.) 3. If necessary, specify other control statements in CARDIN data set. (See CARDIN data set on page 56.) 4. If you want to specify options for HSSR Engine, code them in the HSSROPT and HSSRCABP control statements. (See HSSROPT data set on page 67 and HSSRCABP data set on page 67.) This is optional. 5. Submit the JCL to run the FABHFSU job. 6. Check the output reports and messages. (See OutputPRNTOUT data set on page 67.) To unload a corrupted database, see Chapter 12, Unloading corrupted databases, on page 249.

Selecting a format for the unload output

FABHFSU unloads a database into one of four applicable formats: HS, UL, VB, and VN. For each format, the output data set must be a sequential data set with RECFM=VB.

HS format
When the HS format is selected for the unload format, the output data set must be consistent with HSAM requirements. BLKSIZE must be specified on the ddname1 DD statement. If the maximum segment length is even, the minimum BLKSIZE must be equal to the maximum segment length plus 2. If the maximum segment length is odd, the minimum BLKSIZE must be equal to the maximum segment length plus 3. (For more information about the HSAM format, see the IMS Administration Guide: Database Manager.)

UL format
The UL format is the same as the IMS HD Reorganization Unload format. You can use it to replace the IMS HD Reorganization Unload utility with the faster FABHFSU utility when reorganizing a database. The UL format is acceptable to IMS HD Reorganization Reload utility or a compatible utility. (For more information, see IMS Utilities Reference: Database) Note: If an unloaded data set has been created by specifying the DECN control statement for a database that contains a compressed segment, the data set is not compatible with the unloaded data set created by the IMS HD Reorganization Unload utility. For details, see DEC control statement on page 62. You cannot reload such an unloaded data set by using IMS HD Reorganization Reload utility (DFSURGL0), but you can reload it by using IMS High Performance Load (Load utility or PSSR utility) or the IPR Reload utility. Block size can be specified on the ddname1 DD statement. Minimum BLKSIZE equals the length of the largest segment plus 43 bytes. Maximum BLKSIZE is determined by the output device. If block size is not specified on the ddname1 DD statement, FABHFSU uses one of the following block sizes: v For device type 3380, the default block size is 23K. If the database contains segments larger than 23K, the maximum block size, 32K, is used.
Chapter 5. Using FABHFSU to unload IMS databases

51

v For device type 3390, the default block size is 28K. If the database contains segments larger than 28K, the maximum block size, 32K, is used. v For device type 9345, the default block size is 22K. If the database contains segments larger than 22K, the maximum block size, 32K, is used. v For device types other than the preceding, the default is the maximum device capacity. If some segments have been dropped, make sure that the resulting database is valid.

52

Users Guide

VB format
This section describes the VB format. It is a product-sensitive programming interface. See Programming interface information on page 484 to understand the restrictions associated with this type of material. Product-Sensitive Programming Interface

FORMAT OF VB RECORDS STATEMENT RVB RVBLENN RVBZZ RVBSC RVBLEV RVBDATA DSECT DC H0 DC H0 DC X00 DC X00 EQU * OFFSET DEC HEX 0 2 4 5 6 0 2 4 5 6 DESCRIPTION

RECORD LENGTH FIELD RESERVED FOR MVS SEGMENT CODE SEGMENT LEVEL SEGMENT DATA AS RETURNED BY HSSR

This format is to be used for processing by application programs. When you use the VB Format, a variable-length record is written for each retrieved database segment containing the following data fields: v Segment code v Segment level v Segment data as returned by the HSSR call and as seen by HSSR application programs Block size is specified on the ddname1 DD statement. If the maximum segment length is even, the minimum BLKSIZE must be equal to the maximum segment length plus 10. If the maximum segment length is odd, the minimum BLKSIZE must be equal to the maximum segment length plus 11. If block size is not specified on the ddname1 DD statement, FABHFSU uses one of the following block sizes: v For device type 3380, the default block size is 23K. If the database contains segments larger than 23K, the maximum block size, 32K, is used. v For device type 3390, the default block size is 28K. If the database contains segments larger than 28K, the maximum block size, 32K, is used. v For device type 9345, the default block size is 22K. If the database contains segments larger than 22K, the maximum block size, 32K, is used. v For device types other than the preceding, the default is the maximum device capacity. If some segments have been dropped, make sure that the resulting database is valid. End of Product-Sensitive Programming Interface

Chapter 5. Using FABHFSU to unload IMS databases

53

VN format
This section describes the VN format. It is a product-sensitive programming interface. See Programming interface information on page 484 to understand the restrictions associated with this type of material. Product-Sensitive Programming Interface

FORMAT OF VN RECORDS STATEMENT RVN RVNLEN RVNZZ RVNSYM RVNSC RVNLEV RVNDATA DSECT DC H0 DC H0 DC CL8 DC X00 DC X00 EQU * OFFSET DEC HEX 0 2 4 12 13 14 0 2 4 C D E DESCRIPTION

RECORD LENGTH FIELD ZZ (RESERVED FOR MVS) SEGMENT NAME SEGMENT CODE SEGMENT LEVEL SEGMENT DATA AS RETURNED BY HSSR

This format is to be used for processing by application programs. The VN format has the same format as the VB format, except the VN format also contains the segment name in addition to the segment code. DCB requirements are the same as those for the VB. If the maximum segment length is even, the minimum BLKSIZE must be equal to the maximum segment length plus 18. If the maximum segment length is odd, the minimum BLKSIZE must be equal to the maximum segment length plus 19. End of Product-Sensitive Programming Interface

JCL requirements for FABHFSU

Since the FABHFSU is an HSSR application program, it requires standard FABHX034 JCL. Those DD statements are described in Chapter 2, Job control language, on page 21. The additional requirements for FABHFSU are shown in Table 3:
Table 3. FABHFSU control statements DDNAME CARDIN PRNTOUT ddname1 Use Input Output Output Format LRECL=80 LRECL=133 RECFM=VB Need Optional Required Required

EXEC This required statement invokes either the FABHULU or FABHDLI procedure (see Supported IMS region types and cataloged procedures on page 25). Before using either procedure, modify the JCL to include the correct names of the PSBLIB, DBDLIB. Use one of the following formats:
// EXEC FABHULU,MBR=FABHFSU,DBD=dbdname // EXEC FABHDLI,MBR=FABHFSU,PSB=psbname

54

Users Guide

Note: FABHFSU cannot be run in the DBB region. CARDIN DD This required DD statement defines the input data set containing the control statements for FABHFSU. For the details, see CARDIN data set on page 56. PRNTOUT DD This required statement defines the output data set to which FABHFSU writes error messages and segment statistics. For the details, see OutputPRNTOUT data set on page 67. The data set can be defined as:
//PRNTOUT DD SYSOUT=A

ddname1 DD This is the primary output data set containing the unloaded database. One DD statement is required for each PSB control statement (in the CARDIN data set) that specifies an output format other than NO. (ddname1 must be the name specified in the ddname1 field of the PSB control statement. See PSB control statement on page 58.) You can have up to three of those data sets. The large format data set can be specified for those data sets if z/OS Version 1 Release 7 or later and IMS Version 10 or later are used. The data set can reside either on tape or on a direct-access device, or it can be specified as DUMMY. For an HSAM output data set, specify the BLKSIZE on the DD statement. For the BLKSIZE of other output formats, see Selecting a format for the unload output on page 51 and the description of the PSB control statement. | | | | | | | You can specify the number of buffers in the FSUBUFNO= option in the default option table (FABHOPT). For details, see Chapter 19, Setting site default options, on page 335. The buffers are obtained above the 16MB line. If neither the BUFNO subparameter of the DCB parameter on the DD statement nor the FSUBUFNO= option is given, the number of buffers is determined automatically. The buffers are approximately 1MB in total size and are above the 16MB line. Note: The LRECL values for ddname1 are determined as follows. For VB and VN formats, the LRECL value prepared in the JCL DD statement is used when the value is specified either: v explicitly by the LRECL subparameter of the DCB parameter, or v implicitlyfor example, by using a model data set or the DFSMS/MVS DATACLAS parameter If the LRECL value is not specified either explicitly or implicitly, the default record size (block size minus 4) is used. For UL format, the LRECL value prepared in the JCL DD statement is always ignored, and the default record size (block size minus 4) is used. In addition to these DDs, the standard HSSRTRAC DD statement is required whenever HSSROPT options that produce trace and diagnostic data are specified. It is also required when the Pointer Bypass option is specified on a DBD control statement in the CARDIN data set (see DBD control statement on page 57). This causes the DIAGG option (see DIAGG control statement on page 128.) to be invoked automatically.

Chapter 5. Using FABHFSU to unload IMS databases

55

Input
This section describes the following three data sets and the control statements they contain: v CARDINFABHFSU utility control statements v HSSROPTControl statements for HSSR Engine v HSSRCABPControl statements for the buffer handler of HSSR Engine

CARDIN data set

This section explains the CARDIN data set.

Function
Usually, only three control statements are required for FABHFSU. These are DBD, PSB, and END. Other control statements that can be used for FABHFSU in standard mode are the following: v DEC v GOT v PARTITION v SEGSTAT v BLM and ELM Table 4 gives brief explanation for each control statement.
Table 4. Control statements for FABHFSU in standard mode Keyword DBD Function Identifies the database to be processed and specifies some processing options. Specifies the segment sensitivity and characteristics of the output data set to be created. Upto three PSB statements can be specified. Specifies whether to decompress compressed segments or not. Provides the support for PROCOPT=GOT. Description DBD control statement on page 57 PSB control statement on page 58 DEC control statement on page 42 GOT control statement on page 63 PARTITION control statement on page 43 SEGSTAT control statement on page 43 BLM/ELM control statements on page 65 END control statement on page 66

PSB

DEC

GOT

PARTITION

Restricts the partitions to be processed.

SEGSTAT

Specifies to produce the partition-wide segment statistics report. Specifies a portion of the database to be read.

BLM/ELM

END

Specifies the end of CARDIN control statements.

56

Users Guide

Format
This data set contains 80-byte fixed-length records. The control statements can be coded in the input stream or accessed as a member of a partitioned data set.

DBD control statement

The DBD control statement for the standard mode identifies the database to be scanned. Only one DBD control statement can be used. When running in the PSF mode, the same DBD control statement is specified in the FABHPSFC CARDIN data set. However, column 12 of the DBD control statement in FABHPSFC can contain a different value from that of the FABHFSU CARDIN data set.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DBDdbname index sednnn b

Position 1 4

Description Code the DBD keyword to identify the DBD control statement. DBD Name Code the name of the DBD that describes the physical database to be scanned. This required 8-character field must be left-justified with trailing blanks. The DBD must specify ACCESS=HDAM, HIDAM, PHDAM, PHIDAM, HISAM, or SHISAM.

12

Index Name The 8-character entry is optional and valid only for running in the ULU region. This entry specifies the name of index DBD that is either the primary index of the HIDAM database or a secondary index of the HIDAM or HDAM database if you want the root segments to be retrieved in the index sequence. For details, see For using a secondary index on page 32.

20

Sequence Check option This 1-character entry s determines if sequence checking is performed during the unload processing. Use one of the following keywords: Keyword Y N|blank Description Perform sequence checking. Do not perform sequence checking (default).

21

Sequence Error option The 1-character entry e determines if sequence errors are bypassed or processed by the output routines. Use one of the following keywords: Keyword A|blank Description Accept sequence errors (default). A GX status code is returned.

Chapter 5. Using FABHFSU to unload IMS databases

57

Bypass sequence errors. The segment in error, and all of its children, are skipped. A GG status code is returned.

22

Sequence Error Print option The 1-character entry d determines if diagnostic information is printed on sequence errors in the HSSRTRAC data set. Use one of the following keywords: Keyword Y|blank N Description Print diagnostic data on sequence errors (default). Do not print diagnostic data.

23

Sequence Error Threshold The 3-digit numeric entry nnn indicates the number of sequence errors to be allowed before ending the run. (The default value is 10.) Any number up to 999, with leading or trailing blanks, can be used. If you use the number 999, sequence errors do not cause the run to end.

28

Pointer Bypass option The 1-character entry b is used to activate the Pointer Bypass option. The Pointer Bypass option allows FABHFSU users to continue processing a database that contains bad pointers, instead of issuing an abend. The Pointer Bypass option automatically activates the DIAGG option. Use one of the following keywords: Keyword Blank 1 2 Description The Pointer Bypass option is inactive. This entry invokes the Pointer Bypass option. This entry forces FABHFSU to use the index, rather than the root twin forward pointers, to unload an HIDAM or PHIDAM database.

Note: See Chapter 12, Unloading corrupted databases, on page 249, on how to use this option.

PSB control statement

The PSB control statement for the standard mode identifies the characteristics of the output data sets to be created. From one to three PSB statements can be used for each execution of FABHFSU.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PSBpsbname ddname1 p#ofuserxit mkxsc extln

Position 1 4-11

Description Code the PSB keyword to identify the PSB control statement. PSB Name

58

Users Guide

The 8-character field contains either '*' or the name of the PSB coded on the EXEC statement of the JCL. Value * Description The keyword '*' on this field indicates that all segments described in the DBD are to be processed for this output data set. When running FABHFSU in ULU region, specify this value. PSB name If the name of the PSB coded on the EXEC statement is specified, it indicates that segment types passed to the output routines are controlled through the segment sensitivity of the PCB specified in positions 20-21. The name of the PSB must match the one supplied in the PARM field of the EXEC statement. The name must be left-justified with trailing blanks. Coding the PSB name is valid only for FABHFSU running in the DLI region. 12-19 Output DD Name This 8-character entry specifies the name of the DD statement that defines the data set to be created. It is required unless the output format specification in positions 2223 is NO. ddname1 must be left-justified with trailing blanks. 20-21 PCB Number The 2-character entry p# specifies which database PCB within the PSB is to be used. This determines the segments written into the output data set identified by the Output DD Name field. The PCB referred to must specify the dbdname that is specified in positions 411 of the DBD control statement. If the field is left blank, the first database PCB that refers to the DBD specified by the DBD control statement is used. The number p#, if specified, must be the sequence number that starts from the first database PCB in the PSB; TP PCBs are not counted. Specify 1 for the first database PCB in the PSB. Note: To assure compatibility with FABHFSU of DBT HSSR, it is processed as if 1 was specified when one of values '00', ' 0 ', or '0 ' is specified. 22-23 Output Format The 2-character entry of specifies the output format of the data set to be created. Use one of the following keywords: Keyword HS UL VB Description HSAM format. IMS HD Reorganization Unload format. Variable-length-blocked data set of the selected segments (one segment per logical record).

Chapter 5. Using FABHFSU to unload IMS databases

59

VN NO

The format is similar to VB except that the segment name is included in addition to the segment code. No output data set is created by FABHFSU. The output function can be handled in an exit routine.

For more information about these output formats, see Selecting a format for the unload output on page 51. 24 Exit Routine Name The 8-character entry specifies the name of a user exit routine. The name must be left-justified with trailing blanks. The load module must be in JOBLIB, STEPLIB, LINKLIB, or some other library. For more information, see User exit on page 71. Note: If a user exit routine is specified and one or more partitions are in the HALDB OLR cursor-active status, FABHFSU ends abnormally. 32 Segment Modification option The 1-character entry m indicates whether segments are to be modified by the user exit routine. Use one of the following keywords: Keyword Y Description Indicates that segments are to be modified by the user exit. This option does not support a change of the database segment length. If you change the segment length with the "Y" option, the result is unpredictable. For more details, see Modifying segments in user exits on page 74. E Indicates that segments are to be modified by the user exit. This option supports a change of the database segment length. The option is valid only for HDAM, HIDAM, PHDAM, and PHIDAM databases. An extra 100-byte field is added at the end of the segment data that is passed to the exit routine. This extra field can be used for segment extension. If the default length of this extra field is shorter than you require, you can change the length of the extra field by specifying the length in column 41 of the same PSB statement. If this option has been selected, any request to activate the compare option used for problem determination is deactivated. For details, see Modifying segments in user exits on page 74. N|blank 33 Indicates that segments are not to be modified by the user exit (default).

Concatenated Key option

60

Users Guide

The 1-character entry k indicates whether the fully concatenated key of each segment is to be built and passed to the exit routine. Use one of the following keywords: Keyword Y N|blank 34 Description Build concatenated key. Do not build concatenated key (default).

Exit Routine Control option The 1-character entry x indicates whether the user exit routine is given control before and after segments are processed (see User exit on page 71). Use one of the following keywords: Keyword Y N|blank Description Allow exit routine control. Do not allow exit routine control (default).

35

DBR Skip option The 1-character entry s, the Database Record (DBR) Skip option, indicates whether return code 12 or 16 is valid for the exit routine specified in columns 2431 of this statement. A return code 12, if valid, causes FABHFSU to skip the remaining segments associated with the current root segment and begin processing at the next root segment. Return code 16 causes a skip to a new root key value specified by the exit routine. Use this control statement only when a single PSB control statement is defined. The skipping invoked by one PSB statement affects all others included in the same run. For more information on return codes from the user exit routines, see Table 10 on page 77. Use one of the following codes: Keyword Y N|blank Description Allow DBR Skip option. Do not allow DBR Skip option (default).

36

Data Conversion option If a Data Conversion exit (DFSDBUX1 exit) is activated, the user exit routine specified by the Exit Routine Name option in column 24 receives the segment data that has been converted from the stored form to the application form. The 1-character entry c indicates whether the inverse conversionsthat is, the conversion from the application form to the stored formis done before the segment data edited in the exit routine is written into the output data set. Use one of the following codes: Keyword Description

Chapter 5. Using FABHFSU to unload IMS databases

61

Perform the conversion. This option is valid only for UL and HS unload format, and is valid only when the option 'DATXEXIT YES' is specified in the HSSROPT data set.

N|blank 37-40 41-45

Do not perform the conversion. This is the default.

The value specified in this 4-byte field is always ignored. Extension Length The 5-digit numeric entry extln specifies how many extra bytes are to be reserved for the segment extension in the exit routine. The length specified on this field, plus the maximum length of the segments in the database, will be used as the length of the work area for editing segments in the exit routine. This field can be valid only when the option 'E' is specified in column 32 of the PSB statement. If the option 'E' is specified and this field is blank, the default value, 100, is used. You can specify a value from 00000 through 32767. Notes: 1. If the resulting length of the segment editing work area is more than 32,767 bytes long, 32,767 is used as the length of the work area. 2. If option 'E' is not specified in column 32, the value specified on this field is ignored.

DEC control statement

The DEC control statement, which activates the decompress option, specifies whether FABHFSU is to decompress database segments.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DECd

Position 1 4

Description Code the DEC keyword to activate the decompress option. The 1-character entry d specifies whether compressed segments should be decompressed by FABHFSU. This entry is required. Use one of the following keywords: Keyword Y N Description Compressed segments are decompressed. This is the default. Compressed segments are not decompressed. Code N only when you want to have compressed segments in the output data sets. If an unloaded data set has been created by specifying this option for a database that contains a

62

Users Guide

compressed segment, that data set is not compatible with the unloaded data set created by the IMS HD Reorganization Unload utility. You cannot reload such an unloaded data set by using the IMS HD Reorganization Reload utility (DFSURGL0), but you can reload it by using IMS High Performance Load (Load utility or PSSR utility) or the IPR Reload utility. Notes: 1. The default of this control statement can be changed by replacing the default option table (FABHOPT). Specify the FSUDEC=NO parameter on the FABHTOPT macro statement. For details, see Chapter 19, Setting site default options, on page 335. 2. If there is a segment type for which a Segment Edit/Compression exit routine is specified and the use of a Data Conversion exit is designated, the DECN option is ignored and the process continues with DECY. 3. If the DECN option is specified and one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, FABHFSU ends abnormally.

GOT control statement

The optional GOT control statement is provided to request that the same function provided by HSSR Engine for PCBs with PROCOPT=GOT be activated for the PCB even if PROCOPT=GOT is not specified for the PCB used in the FABHFSU job. For the details of PROCOPT=GOT support, see Support of the processing options GON and GOT on page 98. If the GOT control statement is specified, FABHFSU ignores the PROCOPT of the PCB statement in PSBGEN and forces PROCOPT=GOT to be used. Note: The GOT control statement is effective only when DBRC is inactive for the FABHFSU job.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 GOT

Position 1

Description Code the GOT keyword to activate the support for PROCOPT=GOT.

PARTITION control statement

Use this optional control statement for HALDB when you restrict the partitions to be processed.

Chapter 5. Using FABHFSU to unload IMS databases

63

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PARTITION partnme nnnn

Position 1 11

Description Code the PARTITION keyword to identify this as a PARTITION statement. Code a partition name partnme from which you want to start the unloading. This is a required parameter.

19

This optional parameter nnnn specifies the total number of partitions to be unloaded. The number nnnn must be left-justified, and its length must be less than or equal to four. If this parameter is not specified, the default of 1 is assumed.

Note: If no partition selection exit routine is used, the sequence of partitions is determined from the sequence of high key values. If a partition selection exit routine is used, the sequence of partitions depends on the routine.

SEGSTAT control statement

This optional control statement makes FABHFSU to create a segment statistical report for each partition that is processed. See FABHFSU Segment Statistics report on page 69 for partitions in section OutputPRNTOUT data set on page 67.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 SEGSTAT PART

Position 1 9

Description Code the SEGSTAT keyword to identify the statement. Code the PART keyword to print the partition-wide segment statistics report for each partition that is processed and from which at least one segment is retrieved.

Notes: The partition-wide statistics are not printed if: 1. the SEGSTAT statement is specified for a nonpartitioned database. 2. the PART keyword is not specified. 3. a keyword other than PART is specified as the operand of the SEGSTAT statement.

64

Users Guide

BLM/ELM control statements

The optional BLM and ELM limit control statements define the portion of the database to be read. For HIDAM or HISAM, the limits are specified as keys. For HDAM, the limits are defined as relative block numbers of the CIs or blocks in the Root Addressable Area. Note: The BLM and ELM control statement cannot be specified for a PHDAM or PHIDAM database. Use the PARTITION control statement instead. One BLM or one ELM limit control statement can be used. If no limit control statements are provided, the entire database is read. These statements must immediately follow the DBD control statement.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 BLMtlimitval ELMtllkeyval

Position 1 4

Description Code the BLM or ELM keyword to identify a limit control statement. Limit Value Type The 1-character entry t identifies the limit value type. It indicates the format of the starting or ending limit field. Use one of the following keywords: Keyword R Description Indicates that the limit field contains the relative block number of the CI or block. This specification is valid only for HDAM. Indicates that the limit field contains keys in character format. This specification is valid only for HIDAM and HISAM. Indicates that the limit field contains keys in hexadecimal display format. This specification is only valid for HIDAM and HISAM.

5-78

Starting Limit Value or Ending Limit Value This 74-character field is a required field. For BLM, this field is the beginning limit value. It contains the value at which the scan is to begin. For ELM, this field is the ending limit value. It contains the value of the last database record to be included in the scan. v If R is specified as the limit value type, code the relative block number of the CI or block. The value is numeric with leading or trailing blanks; it must fall within the limits of the root addressable area. For BLM, the scan begins at the first RAP in the specified CI or block.

Chapter 5. Using FABHFSU to unload IMS databases

65

 For ELM, the scan ends after the last RAP in the specified CI or block has been processed. v If C is specified as the limit value type, code the length of the key value in positions 5 and 6 (maximum length is 74). Code the key value starting in position 7. You can specify a generic key by entering a key value length less than the key length of the root segment. FABHFSU pads the key value with X'00's up to the key length for the starting limit and with X'FF's up to the key length for the ending limit. For BLM, the scan begins at the first root segment with a key equal to or greater than the specified key value. If no starting limit value is specified, the scan begins at the logical beginning-of-data set. For ELM, the scan ends before processing the first root segment with a key greater than the indicated key value. If no ending limit value is specified, the scan proceeds to the logical end-of-data set. v If X is specified as the limit value type, code the hexadecimal string starting in position 5. Do not specify length. The hexadecimal string must contain an even number of characters (0-F) and be left-justified in the field. Field length is determined by the first blank encountered in the field. When generic keys are entered, they are padded as described for character keys. For BLM, the scan begins at the first root segment with a key equal to or greater than the specified key value. If no starting limit value is specified, the scan begins at the logical beginning-of-data set. For ELM, the scan ends before processing the first root segment with a key greater than the indicated key value. If no ending limit value is specified, the scan proceeds to the logical end-of-data set. Notes: 1. If you are using a Data Conversion exit for the database and you want to specify a limit value by specifying a key valuethat is, setting a Limit Value Type of C or Xyou must specify the key value in the stored form, not in the application form. 2. If a secondary index is used to retrieve root segments of HIDAM or HDAM, you can specify the limits by the value of search field of the index that has a limit value type of C or X.

END control statement

The END control statement specifies the end of the CARDIN control statements.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 End

Position 1

Description Code the END keyword to identify the END statement as the last statement of the CARDIN data set.

66

Users Guide

HSSROPT data set

For a complete description of the HSSROPT control statements, see HSSROPT data set on page 122. You can use any HSSROPT options that are appropriate for your task. When FABHFSU has the Pointer Bypass option specified on the DBD control statement, do not use the SKERROR and DIAGG options. These options are automatically activated by FABHFSU. DIAGG output requires an HSSRTRAC DD statement.

HSSRCABP data set

For complete description of the HSSRCABP control statements, see HSSRCABP control statements on page 277. Any of the HSSRCABP options that are appropriate to your task can be used.

OutputPRNTOUT data set

FABHFSU provides the following reports in PRNTOUT data set: v FABHFSU Control Statement report v FABHFSU Control Specification report v FABHFSU Segment Statistics report In addition to these reports, reports and statistics produced by HSSR Engine are written in HSSRSTAT and HSSRTRAC data sets (see Chapter 9, Reports and output from HSSR Engine, on page 141).

Function
The FABHFSU program produces the following output reports: v FABHFSU Control Statements report v FABHFSU Control Specifications report v FABHFSU Segment Statistics report

Format
The format is 133-byte fixed-length records. When coded in the JCL, block size must be a multiple of 133.

FABHFSU Control Statements report

This report prints out the CARDIN control statements that were input to FABHFSU (see Figure 9).

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU CONTROL STATEMENTS" DATE: 10/26/2007 TIME: 12.13.14

PAGE: 1 FABHB15 - V1.R2

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DBDHSHDP PSBHSHDPGB OUT1 PSBHSHDPGB OUT2 END UL UL

Figure 9. FABHFSU Control Statements report

Chapter 5. Using FABHFSU to unload IMS databases

67

FABHFSU Control Specifications report

This report contains information on the parameters specified on the CARDIN control statements (see Figure 10 on page 69). This report is produced for each output data set defined by the PSB control statement in the CARDIN data set. Scan Control Specifications Shows specifications or defaults from the DBD, BLM, and ELM control statements. Format Control Specifications Shows specifications or defaults from the PSB control statement. FSU File To Be Compared Shows specification or default from the CO control statement. See FABHFSU control statements: CO and CON on page 260. Concatenate Segment and Prefix Shows specification or default from the CON control statement. See FABHFSU control statements: CO and CON on page 260. Decompress Segments Shows specification or default from the DEC control statement. PROCOPT=GOT Support Shows specification or default from the GOT control statement. Partitioned DB Options Shows specification or default from the SEGSTAT and the PARTITION control statements for HALDB.

68

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU CONTROL SPECIFICATIONS" DATE: 10/26/2007 TIME: 12.59.59

PAGE: 1 FABHFSU - V1.R2

**** SCAN CONTROL SPECIFICATIONS **** PARALLEL SCAN NAME BASE DBD NAME INDEX DBD NAME SEQUENCE CHECK OPTION SEQUENCE ERROR OPTION SEQUENCE ERROR PRINT OPTION SEQUENCE ERROR THRESHOLD SEQUENCE ERROR ABEND OPTION BEGINN LIMIT CONTROL END LIMIT CONTROL POINTER BYPASS OPTION NO. PARALLEL SCAN DSN CHECK OPTION PSC WTO OPTION N.A N.A N.A N.A N.A N.A N.A N.A N.A N.A N.A N.A HDAMMDSG

**** FORMAT CONTROL SPECIFICATIONS **** FORMAT (CONTROL PSB) NUMBER CONTROL PSB NAME CONTROL PCB NUMBER OUTPUT DDNAME OUTPUT FORMAT EXIT ROUTINE NAME SEGMENT MODIFICATION OPTION CONCATENATED KEY OPTION EXIT OPEN/CLOSE CONTROL DBR SKIP OPTION DATA CONVERSION OPTION FSU FILE TO BE COMPARED SYSUT2 UL N.A N.A N.A N.A N.A N.A N.A 01 *

**** PARTITIONED DB OPTIONS **** CONCATENATE SEGMENT AND PREFIX N.A DECOMPRESS SEGMENTS PROCOPT=GOT SUPPORT YES N.A PARTITION SEGSTAT STARTING PARTITION NUMBER OF PARTITIONS YES PART1 0005

Figure 10. FABHFSU Control Specifications report

FABHFSU Segment Statistics report

This report provides statistics for each sensitive segment in the database (see Figure 11 on page 70). This report is produced for each output data set defined by the PSB control statement in the CARDIN data set. The content of the report is as follows: PSB Name Name of PSB Segment Name Name of segment Segment Level Level of segment Total Retrieved This count shows the number of each segment type retrieved. This count does not include segments bypassed due to sequence errors. Total Output This shows the number of each segment type processed by FABHFSU. If Output Format is NO, the value is zero. Differences between Total Retrieved and Total Output represent segments bypassed by the user exit routine.
Chapter 5. Using FABHFSU to unload IMS databases

69

Sequence errors This value represents the number of sequence errors detected for this segment type. If Sequence Check Option is N, this field is zero. Maximum Twins This is the maximum number of this segment type that occurs under any one root segment. This field is always N.A. (that is, not applicable). Maximum Children This is the maximum number of dependent children that occurs for this segment type. This field is always N.A. (that is, not applicable). Average Twins This is the Total Retrieved of this segment type divided by Total Retrieved of this segments parent. Average occurrences of this segment per parent occurrence. Average Children This value is the sum of all segment occurrences dependent on this segment type divided by the Total Retrieved of this segment type. (This value might be incorrect if sequence errors are bypassed or if the PCB is not sensitive to all dependents.) Total Retrieved This is the total number of segments retrieved. Total Output This is the total number of segments processed by FABHFSU. Total Sequence Errors This is the total number of sequence errors.

IMS HIGH PERFORMANCE UNLOAD 5655-E06 **** FORMAT PSB NAME PDBHD101 01 OUTPUT STATISTICS FOR DB=DBHD1010 **** SEGMENT SEGMENT TOTAL TOTAL NAME LEVEL RETRIEVED OUTPUT ROOTLEV1 1 10 10 DEP1LEV2 2 10 10 DEP2LEV2 2 11 11 DEP3LEV3 3 9 9 DEP4LEV2 2 11 11 DEP5LEV3 3 9 9 DEP6LEV3 3 11 11 TOTAL RETRIEVED 71 TOTAL OUTPUT 71 TOTAL SEQUENCE ERRORS 0

"FABHFSU SEGMENT STATISTICS" DATE: 10/26/2007 TIME: 18.32.56 SEQUENCE ERRORS 0 0 0 0 0 0 0 MAXIMUM TWINS N.A N.A N.A N.A N.A N.A N.A MAXIMUM CHILDREN N.A N.A N.A N.A N.A N.A N.A AVERAGE TWINS 1.00 1.00 1.10 .81 1.10 .81 1.00

PAGE: 1 FABHFSU - V1.R2 AVERAGE CHILDREN 6.10 .00 .81 .00 1.81 .00 .00

Figure 11. FABHFSU Segment Statistics report

If the database is a HALDB, and 'SEGSTAT PART' control statement is specified in the CARDIN data set, the partition-wide segment statistics report shown in Figure 12 on page 71 is also produced for each partition.

70

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06 **** FORMAT PSB NAME PHDO030A

"FABHFSU SEGMENT STATISTICS" DATE: 10/26/2007 TIME: 18.33.14 MAXIMUM TWINS N.A N.A N.A N.A N.A N.A N.A N.A N.A N.A MAXIMUM CHILDREN N.A N.A N.A N.A N.A N.A N.A N.A N.A N.A AVERAGE TWINS 1.00 1.00 1.00 2.00 2.00 1.00 2.00 2.00 2.00 2.00

PAGE: 1 FABHFSU - V1.R2 AVERAGE CHILDREN 27.00 .00 6.00 2.00 .00 18.00 8.00 .00 2.00 .00

01 OUTPUT STATISTICS FOR DB=PHDO0300, PARTITION=PHDO03A **** SEGMENT SEGMENT TOTAL TOTAL SEQUENCE NAME LEVEL RETRIEVED OUTPUT ERRORS ROOTLEV1 1 7 7 0 DEP1LEV2 2 7 7 0 DEP2LEV2 2 7 7 0 DEP3LEV3 3 14 14 0 DEP4LEV4 4 28 28 0 DEP5LEV2 2 7 7 0 DEP6LEV3 3 14 14 0 DEP7LEV4 4 28 28 0 DEP8LEV4 4 28 28 0 DEP9LEV5 5 56 56 0 TOTAL RETRIEVED 196 TOTAL OUTPUT 196 TOTAL SEQUENCE ERRORS 0

Figure 12. FABHFSU Segment Statistics report (Partition-wide)

User exit
This section describes the interface of the user exit for FABHFSU. It is a product-sensitive programming interface. Product-Sensitive Programming Interface The user exit routine enables you to perform additional selectivity or modification of segments before the segment data is written into the output data set. You can also control FABHFSU using various return codes from your exit routine. Note: The user exit interface is compatible with the user exit interface of FABHFSU in DBT HSSR and IPR Unload. You can use the exit routine that you wrote for these utilities if that routine does not depend on the CON optionthat is, if the routine does not expect that the segment prefix and the segment data are concatenated in contiguous virtual storage. For best performance, coding the exit routines in Assembler language is recommended. However, exit routines in COBOL and PL/I exit routines are also supported for application programmers. Exit routines must be placed into a load module library to which access is provided with a JOBLIB or STEPLIB JCL statement. End of Product-Sensitive Programming Interface

Attributes of the routine

This section describes the attributes of the routine.

Link-editing the routine

Product-Sensitive Programming Interface The routine must be link-edited in 31-bit addressing mode (AMODE 31). If the routine does not refer to the segment prefix area that is pointed to by the first

Chapter 5. Using FABHFSU to unload IMS databases

71

parameter, the routine can be link-edited in 24-bit addressing mode (AMODE 24). End of Product-Sensitive Programming Interface

Loading the routine

Product-Sensitive Programming Interface At initialization of FABHFSU, and before any HSSR call is issued to the database to be unloaded, FABHFSU examines each PSB control statement to determine whether an exit routine has been specified. If one has been, it is loaded from its resident library. End of Product-Sensitive Programming Interface

Information passed to the exit routine

Product-Sensitive Programming Interface FABHFSU invokes the user exit routine for each segment retrieved from the database before the segment record is written into the output data set. The following parameters are passed to the routine (see Communicating with main logic on page 76): Parameter Word 1 Word 2 Word 3 Word 4 Description Address of the segment prefix for the segment Address of the segment data Address of the segment-table (SGTBL) entry for the retrieved segment (see Segment table (SGTBL) on page 73 for the details.) Address of the Key Area (see Using the key area on page 74 for the details.)

You can refer to or edit the segment data by referring to the information in the SGTBL and Key Area. The address of the segment prefix area is passed to the exit routine for compatibility with the user exits for FABHFSU of DBT HSSR and IPR Unload (see Segment prefix area on page 72). End of Product-Sensitive Programming Interface

Segment prefix area

Product-Sensitive Programming Interface The area is always above the 16MB line; therefore, the address of the segment prefix is set into the parameter list as a 31-bit address. The exit routine (link-edited in 31-bit addressing mode) can refer to the segment prefix area, but must not modify the data in the area. If the segment code has to be checked, the routine should refer to SGCDE in the SGTBL entry instead of referring to the segment prefix. End of Product-Sensitive Programming Interface

72

Users Guide

Segment table (SGTBL)

Product-Sensitive Programming Interface The segment table (SGTBL) is a control block built by FABHFSU. Each entry of SGTBL contains the information for the segment just retrieved. Your exit routine can refer to the information, but must not modify the data in SGTBL unless the length of a fixed-length segment is changed. See Modifying segments in user exits on page 74. The Assembler mapping macro HPSUSGTB for an SGTBL entry is provided in HPS.SHPSMAC0 macro library. The fields of interest in an SGTBL are summarized in Table 5.
Table 5. Fields in an SGTBL Label SGNAME SGCDE SGPARCDE SGLEVEL SGPCNUM SGSNSFLG SGPACOP SGFDFLG SGDSG SGVLIND Offset (bytes) 0 8 9 10 11 12 13 14 15 16 Length (bytes) 8 1 1 1 1 1 1 1 1 1 Type Character Hex Hex Hex Hex Flag byte Flag byte Flag byte Hex Flag byte Description Segment name Segment code Parent segment code Segment level Number of physical children Sensitivity Compaction options Sequence field flag Data set group number Variable-length segment flag If the flag bit SGVL=X'04' is on, the segment has variable length. SGHIER SGMINLEN SGFDLEN SGFDDISP SGLEN 17 18 20 22 24 1 2 2 2 2 Flag byte Halfword Halfword Halfword Halfword Hierarchical pointer flag Minimum length of variable-length segment Length of sequence field Offset to sequence field Segment length for a fixed-length segment; maximum length for a variable-length segment The length does not include the length of the LPCK area if it is defined as virtual. SGPFXLEN 26 2 Halfword Prefix length

For other fields, see HPSUSGTB macro. End of Product-Sensitive Programming Interface

Chapter 5. Using FABHFSU to unload IMS databases

73

Using the key area

Product-Sensitive Programming Interface The key area is used for the following purposes: v If Y is specified for the concatenated key option on the PSB control statement, the fully concatenated key of each segment is built and passed to the exit routine in this area. If a secondary index is used, the value in the search field of the index segment is considered as the key of the root segment. If the DECN option is specified in CARDIN data set, compressed segments are not decompressed. The concatenated key might not be complete if the segment being processed is key-compressed or has a parent that is key-compressed; FABHFSU considers those segments unsequenced. If you need a completely concatenated key for such a database, you must not specify DECN. Note: If you are using a Data Conversion exit (DFSDBUX1 exit) for the database processed in the FABHFSU job, the concatenated key is passed in the application form. If you are not using the DFSDBUX1 exit, the concatenated key is passed in the stored form. v To skip the scan to a new root key value, the exit routine uses the concatenated key area to pass the new key back to FABHFSU. A generic key can be specified by returning a key length less than that required for a root key. If a secondary index is used, specify the value in the search field of the index segment for the next root. Set the return code of 16 to force FABHFSU to accept the skip. The DBR Skip option is also required to be Y in the PSB control statement. The exit routine can skip to any key that is lower than the upper limit for the unload process. A skip to a key beyond the upper limit simulates end-of-the-database. Note: If you are using a Data Conversion exit (DFSDBUX1 exit) for the database processed in the FABHFSU job, you must specify the new key in the application form. If you are not using the DFSDBUX1 exit, you must specify the new root key in the stored form. The format of the key area is shown in Table 6:
Table 6. Format of the key area Offset 0 2 Length (bytes) 2 variable Type Halfword Description Length of key area Key value

End of Product-Sensitive Programming Interface

Modifying segments in user exits

Product-Sensitive Programming Interface If you want to modify the content of segments, you must specify the option Y or E for the Segment Modification option of the PSB control statement if. See PSB control statement on page 58.

74

Users Guide

If you want to modify database segments in your exit routine, but you do not change the length of a segment, you should specify Y in column 32 of the PSB control statement. If this option is selected, each segment will be moved to a work area so that modifications made by an exit routine will not affect the same segment when it is being written to another data set, defined by another PSB control statement. Though any part of the data (except the size field of a variable length segment) can be changed by the user exit, you are cautioned against modifying the segment prefix or sequence fields. The Y option does not allow the exit routine to change the segment length. If you change the segment length with the Y option, the result is unpredictable. If you want to change the segment length, you must specify the E option instead of the Y option. The E option notifies FABHFSU that segments will be modified by the user exit. The option is valid only for HDAM, HIDAM, PHDAM, or PHIDAM databases. If the E option is specified on a PSB control statement, an extra 100-byte field is added at the end of the segment data field that is passed to the exit routine. This additional area can be used to extend the segment passed. If you have changed the length of a fixed-length segment, you must update the SGLEN field in the segment table SGTBL. When the segment is a logical child and the logical parents concatenated key (LPCK) is defined as virtual, the length passed through SGLEN does not include the length of the (virtual) LPCK field. In that case, the length of the virtual LPCK must not be included when SGLEN is updated. Furthermore, if you have changed the length of a variable-length segment, you must update the size field of the segment. However, you do not need to update the SGLEN field for a variable-length segment. Note: You do not need to regenerate a new DBD before running FABHFSU so that the new segment lengths are reflected to the DBD. End of Product-Sensitive Programming Interface

Activating the routine

Product-Sensitive Programming Interface FABHFSU calls the user exit routine as an Assembler subroutine. The linkage convention follows the MVS standard. The exit routine is called for each segment retrieved from the database before the segment record is written into the output data set. If your exit routine needs some kind of initialization and termination processing, specify Y for the Exit Routine Control option on the PSB control statement. End of Product-Sensitive Programming Interface

Initialization and termination processing in the exit routine

Product-Sensitive Programming Interface If the Exit Routine Control option is coded Y (see PSB control statement on page 58), the exit routine is called before the first segment is processed and again after the last segment is processed. The SGLEVEL field in SGTBL is shown in Table 7 on page 76:
Chapter 5. Using FABHFSU to unload IMS databases

75

Table 7. The SGLEVEL field in SGTBL Value of SGLEVEL X'00' X'FF' X'01'X'0F' Description This is the initialization call. It is issued before any segment processing begins. This is the termination call. It is issued after the last segment processing. This is the normal segment processing call, and the value in SGLEVEL shows the segment level of the segment just retrieved.

End of Product-Sensitive Programming Interface

Communicating with main logic

This section describes how to communicate with the main logic.

Contents of registers on entry

Product-Sensitive Programming Interface Table 8 and Table 9 on page 77 show register contents upon entry to the user exit routine:
Table 8. Register contents upon entry to an exit routine Register 1 13 14 15 Content Pointer to the parameter list Pointer to the register save area Return address Entry-point address of the routine

End of Product-Sensitive Programming Interface

76

Users Guide

Table 9 lists the parameters which are pointed to by register 1 upon entry. Product-Sensitive Programming Interface
Table 9. Parameter list pointed to by register 1 upon entry Word 1 2 3 4 Content Address of segment prefix area Address of segment data (see Note) Address of segment table (SGTBL) entry for the segment type Address of key area

Note: The second word (segment-data pointer) points to the beginning of the data portion of the segment. If the segment is a variable-length segment, the pointer points to the size field. If the segment is a fixed-length segment, the pointer points to the beginning of the data, and the segment length is available from the SGLEN field of the SGTBL entry.

End of Product-Sensitive Programming Interface

Contents of registers on exit

Product-Sensitive Programming Interface When the control is returned to the caller, the contents of all registers except for Register 15 must be restored. Register 15 must contain one of the return codes that are summarized in Table 10.
Table 10. Return codes Code 0 4 8 Meaning FABHFSU writes this segment in the output data set. FABHFSU does not write this segment in the output data set. FABHFSU bypasses this segment and stops the processing for this output data set. If the processing for all output data sets is stopped, FABHFSU ends the job step. FABHFSU bypasses this segment and skips the unload processing to the next root segment. Note: The DBR skip option must be coded as Y on the PSB control statement. See DBR Skip option on page 61. FABHFSU bypasses this segment and skips the unload processing to the root segment with the sequence key returned in the Key Area. If a Data Conversion (DFSDBUX1) exit routine is used for the database, the key of the next root must be specified in the application form. Note: The DBR skip option must be coded as Y on the PSB control statement. See DBR Skip option on page 61. 256+(any one of The segment work area contains a decompressed fixed-length segment the above codes) that is now in a true fixed format. The length of the fixed-length segment is in the SGLEN field of the SGTBL. If this code is returned, FABHFSU gets the length of the decompressed fixed-length segment from the SGLEN field. These return codes are allowed only for fixed-length segments.

12

16

Chapter 5. Using FABHFSU to unload IMS databases

77

If a code other than the above is returned, FABHFSU ends abnormally. End of Product-Sensitive Programming Interface

Writing a user exit routine in COBOL

Product-Sensitive Programming Interface When you write an exit routine in COBOL, you should know that a COBOL exit is always called as a subroutine of FABHFSU. Because FABHFSU is not a COBOL program and is not running in the Language Environment, you must use some methods to get better performance. End of Product-Sensitive Programming Interface | |

Enterprise COBOL, COBOL for OS/390, COBOL for MVS, and COBOL/370
Product-Sensitive Programming Interface

If your exit routine is compiled by Enterprise COBOL (Program Number: 5655-G53), COBOL for OS/390 and VM Version 2 (Program Number: 5648-A25), COBOL for MVS and VM (Program Number: 5688-197), or COBOL/370 (Program Number: 5688-197), you should use the run-time option module CEEUOPT to optimize the Language-Environment (LE) options. Because FABHFSU is not an LE-conforming Assembler program, RTEREUS=(ON) should be specified in CEEUOPT. TRAP=(OFF) option should also be specified, to avoid the overhead of intercepting abends in the COBOL user exit. End of Product-Sensitive Programming Interface

VS COBOL II
Product-Sensitive Programming Interface If your exit routine was compiled by VS COBOL II (Program Number: 5688-958) or OS/VS COBOL (Program Number: 5740-CB1) and run with VS COBOL II run-time library, use one of the following methods: 1. Generate the run-time option module IGZEOPT with RTEREUS=YES and STAE=NO; and link-edit it with the exit routine if that routine was compiled with VS COBOL II. If the routine was compiled with OS/VS COBOL, link-edit the IGZEOPT module with a copy of ILBONTR from the VS COBOL II subroutine compatibility library. At run time, this copy of ILBONTR must be available. 2. Specify the control statement RTEXIT=HPSUCOB2 in the HSSROPT data set. HPSUCOB2 sets up and terminates the COBOL II runtime environment. This method is useful if RTEREUS=NO is specified in your current IGZEOPT module that is linked with the exit routine. End of Product-Sensitive Programming Interface

78

Users Guide

Writing a user exit routine in PL/I

Product-Sensitive Programming Interface If an exit routine is written in PL/I, a special Assembler interface routine has to be linked to it. For the details of the interface routine, see the sample HPSUXPA0 in the HPS.SHPSSAMP sample library. When you use the interface routine, observe the following rules: 1. The PL/I routine must be compiled as an external procedure (no OPTIONS on the procedure statement). 2. The name on the procedure statement must be FSUEXIT. 3. The parameters in the PL/I routine must be declared as pointer variables. 4. Based variables must be used to access the data passed by FABHFSU to the exit routine. 5. The built-in function PLIRETC must be used to set the return code expected by FABHFSU. 6. The interface routine must be link-edited with the exit routine by use of the following link-edit control statement:
INCLUDE exitlib(FSUEXIT) INCLUDE somelib(FSUTOPLI) ENTRY FSUTOPLI NAME whatever FSUEXIT - NORMALLY ON SYSLIN INTERFACE ROUTINE ENTRY POINT IN INTERFACE ANY NAME YOU CHOOSE

7. The module name indicated as 'whatever' in this example is the name specified on the Exit Routine Name field of the PSB control statement. End of Product-Sensitive Programming Interface

Sample exit routines

Product-Sensitive Programming Interface The sample exit routines shown in Table 11 are provided as members in the HPS.SHPSSAMP sample library:
Table 11. Examples of exit routines Member name HPSUXAA0 HPSUXCA0 HPSUXPA0 Description Sample exit routine written in Assembler language Sample exit routine written in COBOL Sample exit routine written in PL/I

End of Product-Sensitive Programming Interface

Examples
This section describes two examples: v Example 1: Running FABHFSU in ULU region on page 80 v Example 2: Running FABHFSU in the DLI region on page 80 For examples of unloading a PHDAM or PHIDAM database, see Chapter 7, Processing High Availability Large Databases, on page 103.
Chapter 5. Using FABHFSU to unload IMS databases

79

Example 1: Running FABHFSU in ULU region

The FABHULU procedure can be used to run FABHFSU in the ULU region. The DBD name must be specified on the DBD= EXEC parameter and on the DBD control statement in CARDIN DD. The DBD must be a physical DBD. Since the job runs in the ULU region, PSB name '*' is specified for PSB control statements. In this example, two PSB statements are coded. The first PSB statement specifies the UL format and the DD name of OUT1 for the output data set. The output data set produced by the PSB statement can be reloaded by the IMS HD Reorganization Reload utility or a compatible utility. The second PSB statement specifies the VN format and the DD name of OUT2 for the output data set. The output data set is intended to be processed by an application program. In the example shown in Figure 13, SKILHDAM DD specifies the database to be unloaded.
// EXEC FABHULU,MBR=FABHFSU,DBD=SKILLINV //CARDIN DD * DBDSKILLINV PSB* OUT1 UL PSB* OUT2 VN END /* //PRNTOUT DD SYSOUT=A //SKILHDAM DD DSN=IMSDB.SKILLINV.DB,DISP=SHR //OUT1 DD DSN=IMSDB.UNLOAD1,DISP=(,KEEP),UNIT=TAPE //OUT2 DD DSN=IMSDB.UNLOAD2,DISP=(,KEEP),UNIT=TAPE Figure 13. Running FABHFSU in the ULU region

Example 2: Running FABHFSU in the DLI region

The FABHDLI procedure can be used to run FABHFSU in the DLI region. The PSB name must be specified on the PSB= EXEC parameter. The DBD control statement must be coded in CARDIN DD and must specify the DBD name for the database to be processed. The DBD must be a physical DBD. The three optionsSequence Check option (Y), Sequence Error option (A), and Sequence Error Print option (Y)specified in the DBD statement mean: v Y: sequence check is to be done. v A: sequence errors are to be processed. v Y: the diagnostic data is to be printed in the HSSRTRAC data set. Any incorrect pointers are bypassed, because the DBD statement also specifies Pointer Bypass option (1). In this example, two PSB statements are coded. All segments defined in the DBD are sensitive to the output defined by the OUT1 DD, because '*' is specified in the PSB name field of the first PSB statement. If no sequence errors or pointer errors are found, the output data set produced by the PSB statement can be reloaded by the IMS HD Reorganization Reload utility or a compatible utility, because the unload format UL is specified.

80

Users Guide

The second PSB statement specifies the VB format and the DD name of OUT2 for the output data set. Only segments of the types defined in the first DB PCB of the PSB OUT2PSB for the SKILLINV database are unloaded, because the PSB statement specifies the PSB name and the PCB Number field is left blank. A user exit routine, OUT2EXIT, is specified on the PSB statement. The OUT1 and OUT2 DD statements specify the data sets for unloading. In the example shown in Figure 14, it is assumed that the RECON data sets and the database data sets are dynamically allocated.
// EXEC FABHDLI,MBR=FABHFSU,PSB=OUT2PSB,DBRC=Y //CARDIN DD * DBDSKILLINV YAY 1 PSB* OUT1 UL PSBOUT2PSB OUT2 VBOUT2EXIT END /* //PRNTOUT DD SYSOUT=A //OUT1 DD DSN=IMSDB.UNLOAD1,DISP=(,KEEP),UNIT=TAPE //OUT2 DD DSN=IMSDB.UNLOAD2,DISP=(,KEEP),UNIT=TAPE Figure 14. Running FABHFSU in the DLI region

Chapter 5. Using FABHFSU to unload IMS databases

81

82

Users Guide

Chapter 6. Application programming interface

| | High Performance Unload provides an application programming interface (API) to run, by using HSSR Engine, an IMS DL/I batch application program. Topics: v v v v v v v v v v | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | What is High Performance Unload API? HSSR PCB requirements on page 84 HSSR PCB feedback information on page 85 DL/I calls or EXEC DLI command for HSSR PCB on page 89 JCL requirements on page 91 Restrictions on page 93 Consideration for DB2 DL/I Batch interface on page 94 Considerations for checkpoint and restart on page 96 Consideration for database sharing on page 97 Consideration for HALDB single partition processing on page 102

What is High Performance Unload API?

An application programming interface (API) in High Performance Unload enables an IMS DL/I batch application program, which reads a database sequentially, to use HSSR Engine without being recompiled or relink-edited. Through this API, the application program can retrieve a large number of segments more efficiently than the native IMS DL/I and the elapsed time and CPI time can be reduced. This API supports IMS DL/I calls and IMS EXEC DLI commands. GN and GNP calls with an unqualified segment search argument (SSA) are optimized. If the calls other than GU, GN, or GNP are included, do not run the application program on High Performance Unload. An overview of the system flow of an application program is shown in System structure and data flow on page 16. An application program that uses HSSR Engine for processing DL/I database calls is called an HSSR application program. To run an HSSR application in the DLI or the DBB region, a PSB is needed. In the PSB, you have to select one or more DBPCBs by specifying them in the HSSRPCB or the HSSRDBD control statement in the HSSROPT data set. The selected DBPCB is called an HSSR PCB. A DL/I call or a EXEC DLI command to the HSSR PCB is called an HSSR call. The HSSR calls are processed by HSSR Engine and the calls to the other DBPCBs processed by native IMS DL/I. Notes: 1. An application program must have been assembled, compiled, and link-edited in the same way as IMS DL/I batch application programs. For details, see IMS Application Programming: Database Manager. 2. The specification of HSSR PCBs through the KEYLEN keyword of PCB statement is supported for the compatibility with DBT HSSR. See Specifying an HSSR PCB through KEYLEN on page 257. 3. If the ULU region is used, you do not need to code the HSSRDBD or the HSSRPCB control statement. This region type is supported for the compatibility with DBT HSSR.

Copyright IBM Corp. 2000, 2007

83

HSSR PCB requirements

Each HSSR PCB that is specified in the HSSRPCB or the HSSRDBD control statement in the HSSROPT data set must satisfy all requirements described in the following sections: v PCB statement requirements on page 84 v Processing option (PROCOPT) requirements on page 84 v SENSEG statement requirements on page 85

PCB statement requirements

v The DBDNAME (or NAME) parameter must specify the name of a physical DBD. The name must not be the name of a logical DBD. v LIST=NO option must not be specified.

Processing option (PROCOPT) requirements

The PROCOPT parameter must specify one or certain combinations of the following codes (see IMS Utilities Reference for more information): Code PROCOPT=G Description Get function. If a database is shared at the database level when PROCOPT=G, DBRC grants access with read integrity. It prevents the concurrent execution of the application program and the updating by the IMS subsystem. Read only. (Use this code with G.) If a database is shared at the database level when PROCOPT=GO, DBRC grants access without read integrity. It enables the application program to run and the IMS subsystem to update the database concurrently. Read only. (Use this code with GO.) N allows the application program to avoid abends when referring to data that is being updated by another program. A GG status code is returned, and the program must decide whether to end or continue. Read Only. (Use this code with GO.) T works similarly to N, except that it causes DL/I to retry the operation automatically before returning the GG status code. Enables exclusive use of the database or segment. (Use this code with G.) If a database is shared at the database level when PROCOPT=GE, DBRC grants exclusive use to the database.

PROCOPT=O

PROCOPT=N

PROCOPT=T

PROCOPT=E

If you want to use PROCOPT=GON or GOT, see Consideration for database sharing on page 97. Notes: 1. PROCOPT=R is also accepted for compatibility with DBT HSSR, however, is not recommended. See Support of PROCOPT=R and replace calls on page 257.

84

Users Guide

2. PROCOPT=A is also accepted, however, is not recommended. Even if PROCOPT=A is specified, HSSR engine treats it as PROCOPT=G. The other functions I,R,and D are ignored. 3. PROCOPT=P is also accepted, however, is not recommended. Even if PROCOPT=P is specified, D command Code is not processed by HSSR engine.

SENSEG statement requirements

The following conditions must be satisfied: v SENSEG statements must be coded in the same hierarchical sequence as is defined in the DBD. v Field sensitivity must not be specified. v Either the PROCOPT field must be omitted in the SENSEG statements; or, if it is coded, the processing option must be G, GE, or K. Note: PROCOPT=R is also accepted for compatibility with DBT HSSR, but is, however, not recommended. See Support of PROCOPT=R and replace calls on page 257. |

HSSR PCB feedback information

This section describes the general-use programming interface. See Programming interface information on page 484 to understand the restrictions associated with this type of material.

Interpreting PCB feedback

General-Use Programming Interface An application program should never modify any information in the HSSR PCB. The access to PCB entries by the application program is restricted to read-only. After a call is made, the PCB feedback in the HSSR PCB contains the same information as a DL/I PCB with some exceptions. For details, see Status codes on page 86. End of General-Use Programming Interface Diagnosis, Modification, or Tuning Information Note: If PCBLIST HSSR which is the default, is specified, the PCB list that is passed to the application program is not the same as the PCB list built by IMS. If PCBLIST HSSR is specified, each list entry for a PCB that is defined as an HSSR PCB points to the corresponding HSSR PCB that has been built by HSSR Engine. An HSSR PCB that is passed to the application program is not the original IMS PCB, but the one rebuilt by High Performance Unloads program controller. HSSR Engine describes the results of the calls your program issues in the HSSR PCB. The HSSR PCB is referred to in the call in the same way as in IMS. End of Diagnosis, Modification, or Tuning Information

Chapter 6. Application programming interface

85

Table 12 shows the HSSR PCB mask, which is the same as IMS.
Table 12. HSSR PCB mask Descriptor Database Name Segment Level Number Status Code Processing Options Length 8 bytes 2 bytes 2 bytes 4 bytes See Status codes on page 86. If PCBLIST HSSR, the default, is specified the first two bytes are always 'GX' and the last two bytes list additional processing options, such as 'O ', ' ON', ' OT', 'E ', or 'R '. If the options are defined as GONP or GOTP in the PSB, the last two bytes are NP or TP. If PCBLIST IMS is specified, the content is the same as for IMS. Do not use this field. Note

Reserved Segment Name Length of Key Feedback Area Number of Sensitive Segments Key Feedback Area

4 bytes 8 bytes 4 bytes 4 bytes Variable length

Note: For the EXEC DLI command, the DL/I interface block (DIB) is used as the application programming interface. Every part except the status code is the same as the DIB of IMS. For details about the status codes, see Status codes on page 86. Table 13 shows the format of the DIB:
Table 13. Format of the DIB Descriptor Translator Version (DIBVER) Status Code (DIBSTAT) Segment name (DIBSEGM) Segment Level Number (DIBSEGLV) Key Feedback Length (DIBKFBL) Database Description Name (DIBDBDNM) Database Organization (DIBDBORG) Length 2 bytes 2 bytes 8 bytes 2 bytes 4 bytes 8 bytes 8 bytes

Status codes
The status codes listed in Table 14 on page 87 are returned as the result of an HSSR call.

86

Users Guide

Table 14. Status codes returned from an HSSR call Code blank Meaning Normal return. No errors were detected. I/O area Segment data is returned. PCB feedback PCB has a segment name and a segment level, and the concatenated key is set in the key feedback area. Unpredictable. You must not use the PCB feedback information. Unpredictable. You must not use the PCB feedback information.

AI

Data management OPEN Unpredictable. error This status code is returned when: v The randomizing routine returns a return code of 4. v The database is a HALDB, and the key supplied on the call was greater than the high key value for the last partition, or the user partition selection exit routine returned a return code of 4 after having been passed a key value with which to select a partition. No segment was returned.

FM

GB

End of database (issued only for GN and GHN calls or for GN commands).

No segment was returned.

The segment name is filled with blanks, and the segment level is set to C'00'; the key feedback area is nullified, and the length of the key feedback area is set to zero. You must not use the PCB feedback information.

Chapter 6. Application programming interface

87

Table 14. Status codes returned from an HSSR call (continued) Code GE Meaning I/O area PCB feedback For a GU and GHU call or a GU command, the segment name is filled with blanks, and the segment level is set to C'00'; the key feedback area is nullified, and the length of the key feedback area is set to zero. The content of the key feedback area is unpredictable. You must not use the PCB feedback information. For a GN, GHN, GNP, or GHNP call or for a GN or GNP command, the content of the PCB feedback area is unpredictable. You must not use it.

This status code is No segment was returned when a segment returned. that satisfies the segment search argument described in the call could not be found.

| |

GG

Pointer error, key sequence error, or other database error occurred. This code can be returned either when PROCOPT=GON or GOT is specified in the PCB, or when 'KEYCHECK GG' or SKERROR option is specified in the HSSROPT data set. The program issued a GNP or GHNP call or a GNP command when there was no parentage established, or the segment level specified in the call was not lower than the level of the established parent.

Unpredictable. Unpredictable. You must Note: HSSR Engine not use the PCB might skip retrieving feedback information. some segments while processing the first GN call or GN command that follows a GG status code.

GP

No segment was returned.

Unpredictable. You must not use the PCB feedback information.

88

Users Guide

Table 14. Status codes returned from an HSSR call (continued) Code GX Meaning Key sequence error occurred. (This code can be returned only when 'KEYCHECK GX' is specified in the HSSROPT data set.) For the EXEC DLI command, the status 'GX' is not returned to the application program, but message DFS1041 is issued in the EXEC DLI interface module (DFSEIPB0), and ends with an abend code of U1041. I/O area Segment data is returned. PCB feedback PCB has a segment name and a segment level, and the concatenated key is set in the key feedback area.

Notes: 1. If there is an error in a call statement or a command statement, the application program receives abend U4013, instead of status code AC, AD, AJ, or AK. 2. If hierarchic levels are changed after a successful GN, GHN, GNP, or GHNP call or a successful GN or GNP command, a status code of blank is returned instead of GA. 3. If segment types are changed after a successful GN, GHN, GNP, or GHNP call or a successful GN or GNP command, a status code of blank is returned instead of GK. 4. When a GN call or a GN command is issued after a GU call or a GU command that returned a GE status code, HSSR Engine may not return the same segment that DL/I would return. 5. The status code BA is not returned even if an INIT call or an ACCEPT command has been issued with the character string STATUS GROUPA in the I/O area. If a PROCOPT other than GON and GOT is specified for a PCB, and if HSSR Engine encounters unavailable data regarding the database that is referred to by the PCB, HSSR Engine issues an abend. |

DL/I calls or EXEC DLI command for HSSR PCB

An HSSR call is a DL/I call or an EXEC DLI command that is issued against an HSSR PCB. Each HSSR call is processed by HSSR Engine.

| | | | | | | |

The HSSR call is issued through the DL/I language interface, but the call is transferred to the HSSR Call Analyzer. The call is finally processed by either HSSR Call Handler or native IMS DL/I, depending on the type of the call or the API set that is specified by the APISET control statement in the HSSROPT data set. If APISET 1 (default) or 2 is specified and an unsupported call is issued against an HSSR PCB, the application processing ends abnormally. To avoid program termination, specify APISET 3 or remove the PCB from the list of HSSR PCBs that is specified by the HSSRPCB or the HSSRDBD control statement.
Chapter 6. Application programming interface

89

DL/I calls supported by each API set

APISET 1 is the system default. Table 15 shows the DL/I call types supported by each API set, and their effects with and without segment search arguments (SSAs): Note: For restrictions, see Restrictions on page 93.
Table 15. DL/I call types supported by each API set API set APISET 1 Call types supported The following call types are supported: v GU and GHU calls without SSA: the first root segment of the database is retrieved. v GU and GHU calls with an unqualified SSA that contains only the name of a root segment type. v GU and GHU calls with an SSA that is qualified on the root sequence key. In the SSA, any one of the following relational operators is available: equal-to (=b,b=, or EQ. b represents a single blank) greater-than-or-equal-to (>=,=>,or GE) v GN and GHN calls without SSAs. v GN and GHN calls with an unqualified SSA that contains the name of a root segment type. v GN and GHN calls with a SSA that is qualified on the root sequence key. In the SSA, any one of the following relational operators is available: equal-to (=b,b=, or EQ) greater-than-or-equal-to (>=,=>, or GE) greater-than (>b,b>, or GT) These calls are not supported for HDAM or PHDAM database. v GNP and GHNP calls without SSAs. APISET 2 The following call types are supported for HIDAM, HDAM, PHIDAM, and PHDAM in addition to the call types supported in APISET 1: v GN, GHN, GNP, and GHNP calls with an unqualified SSA that contains the name of a dependent segment type. v GN, GHN, GNP, and GHNP calls with a qualified SSA that contains the name of a dependent segment type at the second level. v GN, GHN, GNP, and GHNP calls with the following two SSAs: The first SSA is a qualified SSA on the root sequence key with an equal-to (=b,b=,or EQ) relational operator. For HDAM, the position at the root segment must be established by the preceding call. The second SSA is an unqualified or a qualified SSA that contains the name of a dependent segment type at the second level. Any other combination of two SSAs is not supported. APISET 3 The fully supported call types are the same as those in APISET 2. Once an unsupported call is issued for HIDAM, HDAM, PHIDAM, or PHDAM, the call and all the succeeding calls to the HSSR PCB are passed to the IMS DL/I call handler to continue the processing instead of ending it abnormally.

90

Users Guide

In APISET 1 or 2, if a user application issues a call that is not supported by the HSSR call handler, the call is printed in the Trace output report in the HSSRTRAC data set even if the TRHC and TRDB control statements are not specified in the HSSROPT data set. You check which call is not supported in this report. |

EXEC DLI commands supported by each API set

Note: If the EXEC DLI command is used in your application, you must specify PCBLIST IMS in the HSSROPT data set. For details of the PCBLIST IMS specification, see PCBLIST control statement on page 135. High Performance Unload supports three API sets. APISET 1 is the system default. Table 16 shows the EXEC DLI Command types supported by each API set, and their effects with and without SEGMENT options:
Table 16. EXEC DLI command types supported by each API set API set APISET 1 Command types supported The following command types are supported: v GU command without SEGMENT options. v GU command with a SEGMENT option that contains the name of a root segment type. APISET 2 The following command types are supported for HIDAM, HDAM, PHIDAM, and PHDAM in addition to the command types supported in APISET 1: v GN or GNP command with a SEGMENT option that contains the name of a dependent segment type. v GN or GNP command with a SEGMENT option and a WHERE option qualified on the sequence key of a second level dependent segment type. APISET 3 The supported call types are the same as those in APISET 2. Once an unsupported call is issued for HIDAM, HDAM, PHIDAM, or PHDAM, the call and all the succeeding calls to the HSSR PCB are passed to the IMS DL/I call handler to continue the processing instead of ending it abnormally.

An HSSR call gives the same results as a DL/I call or an EXEC DLI command, with some minor differences. For details, see HSSR PCB feedback information on page 85. For a complete description of the commands, options, and layout of the DIB and qualified commands, see IMS Application Programming: EXEC DLI commands. | | | | | | | | | |

JCL requirements
The JCL stream that is used to run an application program on High Performance Unload is not fully compatible with the JCL stream used for the native IMS DL/I batch. For the details, see JCL requirements on page 21. You can also use the IBM-supplied catalog procedures. For the details, see Supported IMS region types and cataloged procedures on page 25. To run your application program, the HSSROPT DD statement is needed to specify at least a HSSRPCB or HSSRDBD control statement. And it is recommended that you specify the following output DD statements, which are used to print the HSSR call statistics and the HSSR call traces.
Chapter 6. Application programming interface

91

| | | | | |

v HSSRSTAT DD statement v HSSRTRAC DD statement v HSSRSNAP DD statement Figure 15 is a sample JCL to run the application program named as YOURAPPL that issues IMS DL/I calls.

| //APPLGO EXEC PGM=FABHX034, | // PARM=(DFSRRC00/DLI,YOURAPPL,YOURPSB) | //* <--Change EXEC statement //STEPLIB DD DSN=IMSVS.SDFSRESL,DISP=SHR | // DD DSN=IMSTOOL.SHPSLMD0,DISP=SHR <--Add HP Unload LIB | // DD DSN=YOURPRJ.PGMLIB,DISP=SHR | //DFSRESLB DD DSN=IMSVS.SDFSRESL,DISP=SHR | //IMS DD DSN=IMSVS.PSBLIB,DISP=SHR | // DD DSN=IMSVS.DBDLIB,DISP=SHR | //PROCLIB DD DSN=IMSVS.PROCLIB,DISP=SHR | //IEFRDER DD DSN=NULLFILE, | // DISP=(,KEEP),VOL=(,,,99),UNIT=(TAPE,,DEFER), | // DCB=(RECFM=VBS,LRECL=3964,BLKSIZE=3968,DEN=3) | //SYSUDUMP DD SYSOUT=* | //IMSMON DD DUMMY | //HSSRSTAT DD SYSOUT=* <--- Add OUTPUT DD | //HSSRTRAC DD SYSOUT=* <--- Add OUTPUT DD | //HSSRSNAP DD SYSOUT=* <--- Add OUTPUT DD | //DFSSTAT DD SYSOUT=* <--- Add OUTPUT DD | //HSSROPT DD * <--- Add INPUT DD | HSSRPCB *ALL | APISET 3 | /* | //ddname DD DSN=your_database_DSN,... | | | | Figure 15. JCL to run an application program using the DL/I calls | In Figure 15, two control statements are specified in the HSSROPT data set: | v HSSRPCB *ALL defines that all DBPCBs in the PSB with the name YOURPSB | are HSSR PCBs. If you want to select one or more DBPCBs but not all, there | are two ways to do so: | Specify the PCB numbers as in HSSRPCB 001,003. | Specify as HSSRDBD dbdname to select all DBPCBs that refer to a specific | DBD with the name dbdname. | v APISET 3 enables all DL/I call types that are supported by this API. And if an | unsupported call is issued once, the succeeding call processing to the HSSR | PCB is taken over by native IMS DL/I. The statistics of the calls processed by | HSSR Engine is logged in the HSSRSTAT data set. For details, see HSSRSTAT | data set on page 141. And the statistics of the calls processed by native IMS | DL/I is logged in the DFSSTAT data set. To tune the IMS DL/I performance, add | the DFSVSAMP DD statement and specify IMS VSAM and OSAM buffers and | options in the data set. | If APISET 2 is specified instead of APISET 3, in the previous mentioned case | of the unsupported call, the application processing ends abnormally. Check which | call is unsupported in the Trace output report in the HSSRTRAC data set. For the | details of the supported calls and restrictions, see DL/I calls or EXEC DLI | command for HSSR PCB on page 89. | | | For other options, see Chapter 8, Specifying options for HSSR Engine, on page 121.

92

Users Guide

| |

Note: If your application uses the EXEC DLI commands, you must add the PCBLIST IMS control statement to the HSSROPT data set.

Restrictions
The following restrictions apply to an HSSR application program: v Logical DBD is not supported. v A sensitive virtual logical child (LCHILD) is not supported. v Field sensitivity for an HSSR PCB is not supported. v For the restrictions of secondary index processing, see For using a secondary index on page 32. v The following restrictions apply to HSSR calls: For details of call types supported in each API set, see DL/I calls supported by each API set on page 90. - If APISET 1 or 2 is specified, or if the target is a non-HD database, the following restrictions are applied: v An unqualified or qualified SSA is not fully supported. v Three or more SSAs are not supported. Two SSAs are supported restrictedly. v Command codes except for NULL(*-) command code are not supported. v Multiple qualification statements are not supported. - If APISET 3 is specified for non-HD database and the unsupported call is issued, HSSR Engine ends abnormally without passing the call to IMS DL/I. - A get-next call issued after GU calls that returned a GE status might not return the same segment as DL/I. For details about the EXEC DLI command types supported in each API set, see EXEC DLI commands supported by each API set on page 91. For the EXEC DLI commands, the restrictions corresponding the those for the DL/I calls apply. v The following restrictions apply to Application Interface Block (AIB) interface: HSSR calls using AIB interface are not supported. An HSSR call that uses the interface is passed to IMSs DL/I call handler and is processed as a DL/I call or an EXEC DLI command for the corresponding DL/I PCB. An HSSR application program that uses AIB system service calls might have problems. The use of AIB system service calls is not recommended. v In APISET 1 and 2, by default, for a logical child with a logical parents concatenated key (LPCK) that is specified as "virtual" on the SEGM statement of the DBD, HSSR Engine returns blanks in the I/O area that would usually hold the LPCK (as if field sensitivity were in effect). For compatibility with FSU II, FABHFSU returns binary zeros to the I/O area instead of blanks. If you need to have LPCKs built in the I/O area, you must specify the BLDLPCK control statement in the HSSROPT data sets. v The data capture exit routine is supported, with the following restrictions: A data capture exit routine cannot issue an HSSR call. If an application program issues an HSSR call for the PCB that follows, the call is transferred to the DL/I language interface and the message FABH0671W is issued with RC=USREXIT. The reason that caused the message is as follows: - PCB is generated with PROCOPT=R
Chapter 6. Application programming interface

93

- The DBD referred to by the PCB is generated with the data capture exit routine. In this case, therefore, the HSSR application program cannot take advantage of the HSSR Engine. v No user-written Data Conversion exit routine (DFSDBUX1) is supported. v DB2 DL/I Batch interface is supported, with restrictions. See Consideration for DB2 DL/I Batch interface on page 94. v DL/I checkpoint and restart calls are supported, with restrictions. See Considerations for checkpoint and restart on page 96. v An HSSR application program can run in a database-sharing environment. However, if the application program reads a database that is concurrently being updated by IMS, HSSR Engine does not guarantee read integrity. See Consideration for database sharing on page 97. v An application program that gets information from DL/I control blocks might have problems in the High Performance Unload environment.

Consideration for DB2 DL/I Batch interface

High Performance Unload supports the DB2 DL/I Batch interface, with some restrictions. For DL/I Batch support of DB2, you should also read the DB2 Application Programming and SQL Guide.

Features of DB2 DL/I Batch support

By using DB2 DL/I Batch interface, an HSSR application program can issue: v Any HSSR call, with the restrictions stated in Restrictions on page 93. v Any IMS batch call except a ROLS, SETS, or SYNC call, or any IMS batch command except a ROLS, SETS, or SYNC command. This is the same restriction as for DB2 DL/I Batch support. For further details about the restrictions on IMS batch calls, see DB2 Application Programming and SQL Guide. v IMS system service calls or commands with the same restrictions. See Considerations for checkpoint and restart on page 96. v Any SQL statements except COMMIT and ROLLBACK. The application program must use the IMS CHKP call or the IMS CHKP command to commit data, and the IMS ROLL or ROLB to roll back changes. v Any call or command to a standard or conventional access method such as QSAM or VSAM.

Program design considerations

The program design considerations for ordinary DB2 DL/I Batch support apply to High Performance Unload. You should be familiar with the program design considerations for the DB2 DL/I Batch support, especially those related to checkpoint calls and application program synchronization, or to checkpoint commands and application program synchronization.

Restrictions on DB2 DL/I Batch support

The restrictions described in Restrictions on page 93 apply also to HSSR application programs that use the DB2 DL/I Batch interface. The following restriction also applies:

94

Users Guide

v DB2 change data capture exit routine (DB2CDCEX) is supported, but a changed data capture exit routine cannot issue any HSSR call.

Requirements for using DB2 DL/I Batch support

You can use IBM-supplied cataloged procedure FABHDB2, which resides in the HPS.SHPSSAMP sample library. The required changes to the application program and the job step JCL are basically the same as for DB2 DL/I Batch support, except for the following: v Using DSNMTV01 on the MBR= parameter is not supported; the results obtained when it is used are unpredictable. You must specify a subsystem member, using the SSM= parameter on the procedure FABHDB2. Also, specify your HSSR application program name, using the MBR= parameter, and the name of the High Performance Unloads program controller, FABH000, as the ninth positional parameter PROG in the DDITV02 data set. For detailed information on how to specify the EXEC parameters and the DDITV02 DD on the DB2 DL/I Batch job step JCL, see the DB2 Application Programming and SQL Guide.

EXEC parameters
In the HSSR application program that uses DB2 DL/I Batch support, the following additional EXEC parameter must be provided: SSM= This required parameter specifies a 1- to 4-byte character identifier. When building the IMS.PROCLIB member that contains the information about each DB2 subsystem that IMS communicates with, you must generate the member name by concatenating this SSM identifier to the IMSID. Carefully provide the following EXEC parameter: MBR= This required parameter specifies the name of the HSSR application program. The DB2 module name DSNMTV01 must not be specified.

DD statements
Provide the following DD statement in your JCL: DDITV02 DD Specify the program controller name FABH000 as the ninth positional parameter PROG in this data set. For example:
//DDITV02 DD * DSN,SYS1,DSNMIN10,,R,-,BATCH001,DB2PLAN,FABH000 /*

The following DD statement is optional: DDOTV02 DD This optional DD statement defines the output data set in which the DB2 output information is written. If DCB is coded on the JCL, the specification must be RECFM=V or VB, LRECL=4092, and "BLKSIZE LRECL+4". If the DD statement is missing, message IEC130I is issued and processing continues without any output.

Chapter 6. Application programming interface

95

Considerations for checkpoint and restart

This section summarizes the restrictions and considerations that apply to the following: v MVS checkpoints v DL/I CHKP and XRST calls or EXEC DLI CHKP and XRST commands

MVS checkpoints
MVS checkpoints can cause unpredictable results in HSSR application programs. Therefore, HSSR application programs should not issue: v MVS checkpoints v Those basic DL/I CHKP calls or EXEC DLI CHKP commands that request MVS checkpoints. (For a detailed description of DL/I CHKP calls, see IMS Application Programming: Design Guide.)

DL/I CHKP and XRST calls or EXEC DLI CHKP and XRST commands
HSSR application programs can issue PCB DL/I CHKP and XRST calls or XRST commands to the I/O PCB. However, a DL/I CHKP call or an EXEC DLI CHKP command should not request an MVS checkpoint. v If PCBLIST HSSR (the default value) is specified, HSSR application programs can issue XRST calls with APISET 1 (also the default value). v If HSSR application programs issue XRST calls with PCBLIST IMS specified, you must specify APISET 3. v If XRST command is to be issued, you must specify APISET 3. HSSR Engine is not aware of CHKP and XRST calls or XRST commands. For HSSR PCBs, the behavior of HSSR Engine is not compatible with the behavior of DL/I. Be careful if you are concerned about compatibility between HSSR and DL/I. The differences between HSSR Engine and DL/I are as follows: v After a CHKP call or a CHKP command, the position of HSSR PCBs is not set to the beginning of the database. Therefore, the database position established after a CHKP call or a CHKP command is not compatible with HSSR Engine and DL/I. The HSSR Engines compare option might become useless in this environment. If you are concerned about compatibility, issue GU database calls or GU database commands to the HSSR PCBs after a DL/I CHKP call or an EXEC DLI command. v During a CHKP call or a CHKP command, the key feedback area of HSSR PCBs is not written to the IMS log. Instead, the IMS log may contain records for internal DL/I PCBs, which are unknown to the application program. v During an XRST call or an XRST command, key feedback information is not restored in HSSR PCBs. Application programs that need to record database positioning information for HSSR PCBs can record it themselves by providing it in user areas during a CHKP call or a CHKP command. The XRST call or the XRST command restores this logged information in user areas. For more detailed information about providing user calls, see IMS Application Programming: Design Guide.

96

Users Guide

Consideration for database sharing

In general, HSSR application programs, including FABHURG1 and FABHFSU, should be run with exclusive control of the database as any unload utility does during reorganization. In some cases, however, you might want to read the database while it is being updated by IMS. The update might be done by either IMS within the same program or another IMS subsystem that is running concurrently. This section provides hints for such a case.

Database sharing support

HSSR Engine supports the following database-sharing functions. However, it does not provide read integrity, if an HSSR application program reads a database that is being updated at the same time by IMS either within the same program or through concurrent execution of another IMS subsystem. v The capability to cope with data set extensions, which are created by concurrently updating IMS subsystems See Handling data set extensions on page 97. v Support for processing options GON and GOT See Support of the processing options GON and GOT on page 98. v Support for database level sharing through the use of the standard database access authorization logic of DBRC In a database-level sharing environment, an HSSR application program can read databases either with read integrity (with read processing intent; PROCOPT=G) or without read integrity (with read-only processing intent; PROCOPT=GO). See Support of database level sharing on page 99. v Ability to an HSSR application program to run in a block-level sharing environment In this case, HSSR Engine does not provide read integrity. See Considerations for block level sharing on page 99. Some problems may occur because the HSSR buffer handler does not synchronize the content of its buffers with the content of the IMS buffer handler. HSSR Engine is not aware of a modification to a block or CI unless IMS writes the modified block or CI from its buffers to DASD. It is also not aware of a modification if an HSSR buffer contains an older image of that block or CI. For example, the following problems that might occur with IMS in a database level sharing environment might also occur with HSSR Engine: v The HSSR application program might read uncommitted data or might read data that is no longer up-to-date. v The HSSR Engine might issue an abend or a GG status code due to what appears to be incorrect pointers in the segment prefix. v Additional problems can occur with VSAM KSDS, if HSSR Engine reads a KSDS that is updated by an IMS program that might create CI splits or CA splits. For methods of avoiding these problems, see Avoiding problems caused by the lack of read integrity on page 100.

Handling data set extensions

HSSR buffer handler can access OSAM blocks or VSAM CIs stored and update IMS subsystems in new extents of the data sets concurrently.
Chapter 6. Application programming interface

97

This support is provided in the following environments: v For OSAM: In all environments, including database level sharing and block level sharing v For VSAM: Only when all the following conditions are met: The updating IMS subsystem runs within the same MVS system. VSAM SHAREOPTIONS (3,3) are used. (See VSAM SHAREOPTIONS on page 100.) For OSAM and ESDS, this support is provided by default. For KSDS, this support must be explicitly activated by a RETRY KSDS control statement of the HSSROPT data set (for more details, see RETRY control statement on page 136).

Support of the processing options GON and GOT

For the processing options GON, HSSR Engine provides the same support as IMS. Upon encountering a database error, or what in a database sharing environment appears to be a database error, HSSR Engine returns a GG status code. For the processing option GOT, HSSR Engine provides slightly different support from IMS. Upon encountering a database error situation, or what in a database-sharing environment appears to be a database error situation, HSSR Engine does the following: 1. Retries many times to access the database, and waits for a specific number of seconds before each attempt (only for HDAM, HIDAM, PHDAM, and PHIDAM). The number of attempts and the waiting time can be specified on the GOTRETRY control statement. 2. Returns a GG status code if the attempts to access the database are not successful. 3. Invalidates all PCB-related buffers; database calls issued after a GG status code do not use old buffer copies but are satisfied with new database accesses. The buffer invalidation can increase the chances of an application program resuming its processing after a GG status code. The HSSR buffer handler invalidates buffers only for HDAM, HIDAM, PHDAM, and PHIDAM. Notice the following additional points concerning processing options GON and GOT: v The SKERROR option (see SKERROR control statement on page 137) can be considered a logical extension of the support that HSSR Engine provides for the processing options GON and GOT. When the SKERROR option has been activated, HSSR Engine does not reset the database position to the beginning of the database, but keeps the current database position. If the application program issues a GN call or a GN command after a GG status code, the database error is skipped (for example, the processing of an incorrect pointer is skipped) and HSSR Engine returns the next segment it can retrieve. Instead of using abends or retrying the database access by combining WAITs, GU calls or commands, and GN calls or commands, an application program can use SKERROR to continue the database retrieval by issuing GN calls or commands. The option can also be used by an application programs that can afford to skip the retrieval of one or more database segments. v The number of returned GG status code is reported in the HSSRSTAT data set. v To get detailed diagnosis information about the GG situation, activate the DIAGG option. (See DIAGG control statement on page 128.) v HSSR Engine does not have an interface to IRLM. Therefore, in a block level sharing environment with processing option GOT, HSSR Engine does not issue

98

Users Guide

IRLM test enqueues when attempting to reaccess the database during a GG situation. For HDAM, HIDAM, PHDAM, and PHIDAM databases, HSSR Engine tries to balance this lack of IRLM test enqueues by making many attempts to access the database, and by waiting before each attempt.

Support of database level sharing

High Performance Unload provides the same support for database level sharing as IMS. This support requires that DBRC be installed and active, and that the database be registered in the DBRC RECON data sets.

Application program running in DLI or DBB region

For an HSSR application program running in DLI or DBB region, DBRC authorizes database access to the job step under the same conditions as a normal IMS batch job step. Authorization for the database access depends on the following: v The database processing intent as specified through PROCOPT during PSBGEN v The database-sharing level defined in the RECON data sets v The current status indicators of the database, as recorded in the RECON data sets You have the following options during PSBGEN: 1. You can specify a read processing intent (PROCOPT=G) in order to have read integrity. DBRC then prevents concurrent execution of the HSSR application program with an IMS subsystem that updates the database. 2. You may specify a read-only processing intent (PROCOPT=GO) to be able to run your application program concurrently to other IMS subsystems that update the database. In this case, no read integrity is provided. You can also specify an exclusive processing intent (PROCOPT=GE) in order to have exclusive usage of the database.

Application program running in a ULU region

In a ULU region, DBRC authorizes database access to an HSSR application program under the same conditions as to the standard IMS HD Reorganization Unload utility. When an HSSR application program runs in the ULU region, HSSR Engine lets IMS and DBRC believe that it is the IMS HD Reorganization Unload utility that is being run. Note: Databases that have been registered for block-level sharing are shared by a ULU region at the database level. This is what IMS does for the IMS HD Reorganization Unload utility.

Considerations for block level sharing

HSSR Engine does not provide any special support for block level sharing, and does not provide an interface to the IRLM. It is, however, possible to run an HSSR application program in a block level sharing environment if no replace processing option is specified for HSSR PCBs. HSSR Engine behaves in the same way as in a database level sharing environment with read-only processing intent. Read integrity is not provided. When running in a block level sharing environment with read processing intent, HSSR Engine issues a warning message and runs with read-only processing intent. If you need to read, with read integrity, a database that has been registered with SHARELEVL 2 or SHARELEVL 3 (block level sharing), you can consider specifying
Chapter 6. Application programming interface

99

IRLM=N on the JCL and specifying a read processing intent during PSBGEN. In this case, sharing occurs at the database level, and DBRC prevents concurrent execution with an updating IMS subsystem.

Avoiding problems caused by the lack of read integrity

To avoid the problems caused by the lack of read integrity, you might use the following methods, Apply them only with care. v Frequency of SYNC points or checkpoint calls and commands in updating programs Updating IMS programs should rapidly write the content of modified buffers to DASD. This can be achieved by a high frequency of calls or commands, whether SYNC points or checkpoints, in the updating IMS application programs. v Avoiding CI splits and CA splits With ESDS and OSAM data sets, the exposure of reading inconsistent data is limited to the reading of database records that are modified by the updating IMS program. With KSDS data sets, the risk of reading inconsistent data is much higher if CI splits or CA splits occur. Reading a CI that has been split might create a skip of all the root segments that have been shifted out of the split CI. Reading a CA that has been split might create a skip of all the roots that have been shifted out of the split CA. Other incorrect results might also occur. To avoid these problems, allocate enough free space in the KSDS and re-create it frequently enough to reduce the number of CI splits and CA splits. For example a KSDS can be re-created by restoring with the IMS Database Recovery utility. Unless the occurrence of CI splits and CA splits can be kept very low while the HSSR application program is running, do not read an HISAM KSDS with HSSR Engine. v Free space for ESDS and OSAM data sets By specifying free space within the OSAM blocks and within the ESDS CIs, you can reduce the probability that insert and delete calls will create what may appear to HSSR buffer handler to be an incorrect pointer situation.

VSAM SHAREOPTIONS
This section presents information about a product-sensitive programming interface. To understand the restrictions associated with this type of material, see the Programming interface information on page 484. Product-Sensitive Programming Interface The considerations discussed here for the selection of appropriate VSAM SHAREOPTIONS are similar to the corresponding IMS considerations. You can select the VSAM SHAREOPTIONS (3,3), (2,3) or (1,3). If the application program does not issue HSSR REPL calls, VSAM SHAREOPTIONS (1,3) can be used. Note: Specifications of incorrect VSAM SHAREOPTIONS might result in OPEN errors. End of Product-Sensitive Programming Interface

100

Users Guide

VSAM SHAREOPTIONS
Product-Sensitive Programming Interface You can select either the VSAM SHAREOPTIONS (1,3), (2,3), or (3,3). VSAM SHAREOPTIONS (1,3) allows concurrent access to the following: v Multiple HSSR ACBs-that is, ACB, ACBs to multiple HSSR application programs issuing HSSR calls. v Multiple-input-only IMS ACBsthat is, ACBs to multiple IMS subsystems that issue DL/I calls or EXEC DLI commands to the database with a processing intent read or read-only. If an HSSR PCB has a replace processing option, SHAREOPTIONS (1,3) cannot be used. VSAM SHAREOPTIONS (2,3) allows concurrent access to multiple HSSR ACBs (to multiple HSSR application programs issuing HSSR calls), to multiple-input-only IMS ACBs (to multiple IMS subsystems that issue DL/I calls or EXEC DLI commands to the database with a processing intent read or read-only), and to one single-output IMS ACB (to one IMS subsystem that issues DL/I calls or EXEC DLI commands to the database with a processing intent update). VSAM SHAREOPTIONS (2,3) does not allow HSSR Engine to get access to a control interval that has been stored in a new extent of the data set by a concurrently updating IMS subsystem. VSAM SHAREOPTIONS (3,3) allow concurrent access to multiple HSSR ACBs (to multiple HSSR application programs issuing HSSR calls), and to multiple-input-only and output IMS ACBs (to multiple IMS subsystems that issue DL/I calls or EXEC DLI commands with read-only, read, and update processing intents). The VSAM SHAREOPTIONS (3,3) are one of the prerequisites that must be met in order for HSSR buffer handler to get access to control intervals that have been stored by concurrently updating IMS subsystems in new extents of the data set. End of Product-Sensitive Programming Interface

Technical explanations
Product-Sensitive Programming Interface The VSAM SHAREOPTIONS are used by the VSAM Open modules in order to control within one single operating system the concurrent access to a VSAM data set through input-only ACBs and through output ACBs. v The SHAREOPTIONS (3,3) allow concurrent access through multiple-output ACBs or through multiple-input-only ACBs. v The SHAREOPTIONS (2,3) allow concurrent access through one-single-output ACB and through multiple-input-only ACBs. v The SHAREOPTIONS (1,3) allow concurrent access through multiple-input-only ACBs or through one-single-output ACB. The following paragraphs explain which kind of ACBs are used in an IMS environment and in an High Performance Unload environment. An IMS subsystem is either one online IMS system with multiple message regions and BMP regions, or one IMS batch region. Each IMS subsystem uses one ACB for each VSAM data set in order to perform the I/O resulting from DL/I calls or EXEC
Chapter 6. Application programming interface

101

DLI commands. IMS opens the ACB either for input only (if the database processing intent is read or read-only) or for output (if the database processing intent is update). In a High Performance Unload job step, HSSR Engine uses its own read-only ACBs to do the I/O resulting from HSSR calls; ordinarily these are the only ACBs opened by the job step. In any of the following three conditions, IMS opens and uses one additional IMS: 1. The HSSR application program gets access to the same database with both HSSR calls and DL/I calls, or with both HSSR calls and EXEC DLI commands. 2. The compare option has been activated by coding the CO control statement in the HSSROPT data set, for problem determination. (The compare option internally reissues all HSSR calls to DL/I.) The LPCK-building option has been activated by coding the BLDLPCK control statement in the HSSROPT data set. (If the BLDLPCK option has been specified, HSSR Engine issues DL/I calls or EXEC DLI commands internally to get LPCKs.) 3. The application program issues HSSR REPL calls. The additional ACB used by IMS is opened by IMS either for input only, or for output (see the description above). End of Product-Sensitive Programming Interface

Consideration for HALDB single partition processing

By specifying the HALDB control statement on the DFSHALDB DD statement, you can select a single HALDB partition to be processed. This function is the same as the IMS function with the same name HALDB Single Partition Processing. | | | | | | | | | Figure 16 is an example of the HALDB control statement. Here, '001' is the DB PCB number and 'PHDO01C' is the partition name that is to be processed.
//DFSHALDB DD * HALDB PCB=(001,PHDO01C) /* Figure 16. Example of the HALDB control statement for single partition processing

For the details of the DFSHALDB DD statement and the HALDB control statement, see IMS Install. Vol. 2: System Definition and Tailoring. | | Note: If the application program issues GN calls repeatedly, and reaches the end of the partition, the status code GB is returned to the application program.

102

Users Guide

Chapter 7. Processing High Availability Large Databases

This chapter explains the processing of High Availability Large Databases. Topics: v v v v v v High Availability Large Database and Unload utilities Using FABHURG1 to unload a partitioned database on page 105 Using FABHFSU to unload a partitioned database on page 109 Running your HSSR application program on page 112 Migration unload and fallback unload on page 115 Summary of HALDB restrictions for processing on page 118

High Availability Large Database and Unload utilities

This section explains the High Availability Large Database and Unload utilities.

High Availability Large Database (HALDB)

In IMS Version 7 or later, HD databases can be partitioned by use of the HALDB Partition Definition utility (DSPXPDDU) of IMS. HD databases partitioned in this way are called High Availability Large Databases (HALDBs). If you partition an HDAM database, it becomes a partitioned hierarchical direct access method (PHDAM) database. If you partition a HIDAM database, it becomes a partitioned hierarchical indexed direct access method (PHIDAM) database. For details about PHDAM and PHIDAM databases, refer to the Database Administration Guide of IMS. You can use FABHURG1 and FABHFSU to unload PHIDAM and PHDAM databases. You can also write your own HSSR application program to access these databases, with some restrictions. Note: In this chapter, any reference to HALDB or a partitioned database means either a PHDAM or a PHIDAM database unless otherwise specified. The partitioned secondary index (PSINDEX) is not intended to be included.

Unloading a PHDAM or PHIDAM database

You can use the following unload utilities to unload all partitions of a PHDAM or a PHIDAM database: v FABHURG1 v FABHFSU in standard mode You can also use these utilities to unload a particular partition or a sequence of partitions from a PHDAM or PHIDAM database. If a HALDB is unloaded by FABHURG1 with *HD format or by FABHFSU with UL format, you can use the IMS HD Reorganization Reload utility or a compatible utility to reload it. If a HALDB has been unloaded by FABHURG1 with *HD format or by FABHFSU with UL format, IPR Reload and High Performance load regard it internally, and refer to it, as having PHD format. Both FABHURG1 and FABHFSU provide a function for unloading a particular partition or a sequence of partitions from a partitioned database. Unloading partition data sets in parallel, using the multiple FABHURG1 or FABHFSU jobs, reduces the elapsed time required for unloading a partitioned database.
Copyright IBM Corp. 2000, 2007

103

To process partitions that are defined as HALDB Online Reorganization (OLR) capable, see the considerations described in For HALDB Online Reorganization capable partitions on page 31. In FABHFSU utility, only the standard mode is supported for unloading a partitioned database, a partition of it, or a sequence of partitions of it. You cannot run FABHFSU in PSF mode for a partitioned database.

104

Users Guide

Using FABHURG1 to unload a partitioned database

FABHURG1 provides the following two methods to unload a partitioned database: v Unload the entire database v Unload a selected partition or a sequence of partitions The following control statement can be used to unload a partition or a sequence of partitions of a partitioned database: v PARTITION control statement in the SYSIN data set The following control statements can be used to print partition-wide statistics reports: v SEGSTAT control statement in the SYSIN data set v CALLSTAT control statement in the HSSROPT data set v PARTINFO control statement in the HSSROPT data set FABHURG1 also supports migration unload and fallback unload. The control statements used for migration and fallback are explained in Migration unload and fallback unload on page 115.

Types of processing
This section describes the processing types for HALDB.

Unloading the entire database

You can unload a partitioned database as a whole database with one FABHURG1 job step. Figure 17 shows the data flow for unloading and reloading an entire database:

Figure 17. Unloading the entire database

A FABHURG1 JCL used for a nonpartitioned database can be used with the following minor modifications: v You do not need to specify any DD statements for database data sets. v DBRC must be used.

Chapter 7. Processing High Availability Large Databases

105

v The DD statements for RECON data sets must be specified or dynamically allocated. No additional control statement is necessary. For an example of JCL used for unloading the entire database, refer to the section Example 1: Unloading the entire database on page 107.

Unloading a partition or a sequence of partitions

FABHURG1 can also be used to unload a single partition or a sequence of partitions from a partitioned database. The PARTITION control statement in the SYSIN data set is used to specify a partition, or a sequence or partitions, to be unloaded. For the details of the control statement, see the section PARTITION control statement on page 43. HSSR Engine allocates the buffers only for a selected partition or for a selected sequence of partitions. When a single partition is unloaded, the unloaded data set contains a header record, all segment records in the selected partition, and a trailer record. You can use the IMS HD Reorganization Reload utility or a compatible utility to reload the data set unloaded by the FABHURG1 utility in *HD format. Figure 18 shows the data flow for unloading and reloading each partition.

Figure 18. Unloading a partition or a sequence of partitions

For an example of JCL used for unloading a partition, refer to the section Example 2: Unloading a partition on page 108. FABHURG1 can also unload a sequence of partitions that is specified on a PARTITION control statement. When a sequence of partitions is unloaded, the unloaded data set contains the following records in the following sequence: 1. A header record 2. Segment records of all selected partitions in the partition sequence determined by the IMS partition selection logic 3. A trailer record

106

Users Guide

You can use the IMS HD Reorganization Reload utility or a compatible utility to reload the data set unloaded by the FABHURG1 utility in the *HD format. Figure 19 shows the data flow for unloading and reloading a sequence of partitions.

Figure 19. Unloading a sequence of partitions

For an example of JCL used for unloading a sequence of partitions, refer to the section Example 3: Unloading a sequence of partitions on page 108.

JCL requirements
In a FABHURG1 JCL for HALDB, the requirements are as follows: v DBRC must be used. v The DD statements for RECON data sets must be specified or dynamically allocated. v No DD statements for database data sets must be specified. v PARTITION control statement must be coded in the SYSIN data set.

Examples
This section provides three examples to unload a HALDB by FABHURG1.

Example 1: Unloading the entire database

The following is an example JCL to unload the entire database. The unloaded data set is defined by the SYSUT2 DD statement; the database that is unloaded is specified on the DBD parameter; DBRC=Y is specified so that DBRC is used; and the DD statements for RECON data sets are specified. All partition data sets are dynamically allocated by HSSR Engine. Because 'PARTINFO DEF' is specified, the HALDB Partition Definition report is produced.

Chapter 7. Processing High Availability Large Databases

107

Because 'SEGSTAT PART' is specified, the partition-wide Segment Statistics report is produced.
// EXEC FABHULU,MBR=FABHURG1,DBD=USERDBD,DBRC=Y //RECON1 DD DSN=IMSVS.RECON1,DISP=SHR //RECON2 DD DSN=IMSVS.RECON2,DISP=SHR //RECON3 DD DSN=IMSVS.RECON3,DISP=SHR //HSSROPT DD * PARTINFO DEF /* //SYSIN DD * SEGSTAT PART /* //SYSPRINT DD SYSOUT=A //SYSUT2 DD DSN=IMSDB.HDUNLD,DISP=(,CATLG),UNIT=TAPE, // VOL=SER=VOL001

Example 2: Unloading a partition

The following is an example JCL to unload a partition of a partitioned database. The unloaded data set is to be defined by the SYSUT2 DD statement; the database that is unloaded is specified on the DBD parameter; DBRC=Y is specified so that DBRC is used. In this example, it is assumed that the RECON data sets are dynamically allocated. The partition to be unloaded is specified by the PARTITION control statement in the SYSIN DD statement. All data sets for the selected partition PART10 are dynamically allocated by HSSR Engine.
// EXEC FABHULU,MBR=FABHURG1,DBD=USERDBD,DBRC=Y //SYSIN DD * PARTITION PART10 /* //SYSPRINT DD SYSOUT=A //SYSUT2 DD DSN=IMSDB.HDUNLD,DISP=(,CATLG),UNIT=TAPE, // VOL=SER=VOL001

Example 3: Unloading a sequence of partitions

The following is an example JCL to unload a sequence of partitions of a partitioned database. The unloaded data set is to be defined by the SYSUT2 DD statement; the database that is unloaded is specified on the DBD parameter; DBRC=Y is specified so that DBRC is used; and the DD statements for RECON data sets are specified. The partitions to be unloaded are five consecutive partitions. The first is partition PART10, which is specified on the PARTITION control statement in the SYSIN DD statement. All data sets for the selected partitions are dynamically allocated by HSSR. Because 'PARTINFO DEF,ACC' is specified, the HALDB Partition Definition report and the HALDB Partitions Accessed report are produced. Because 'SEGSTAT PART' is specified, the partition-wide Segment Statistics report is produced.

108

Users Guide

// EXEC FABHULU,MBR=FABHURG1,DBD=USERDBD,DBRC=Y //RECON1 DD DSN=IMSVS.RECON1,DISP=SHR //RECON2 DD DSN=IMSVS.RECON2,DISP=SHR //RECON3 DD DSN=IMSVS.RECON3,DISP=SHR //HSSROPT DD * PARTINFO DEF,ACC /* //SYSIN DD * SEGSTAT PART PARTITION PART10 5 /* //SYSPRINT DD SYSOUT=A //SYSUT2 DD DSN=IMSDB.HDUNLD,DISP=(,CATLG),UNIT=TAPE, // VOL=SER=VOL001

Using FABHFSU to unload a partitioned database

FABHFSU provides the following two methods for unloading a partitioned database: v Unload the entire database v Unload a selected partition or a sequence of partitions The following control statement can be used for unloading a partition or a sequence of partitions of a partitioned database: v PARTITION control statement in the CARDIN data set The following control statements can be used to print partition-wide statistics reports: v SEGSTAT control statement in the CARDIN data set v CALLSTAT control statement in the HSSROPT data set v PARTINFO control statement in the HSSROPT data set

Unloading the entire database

You can unload a partitioned database as a whole database with one FABHFSU job step. If you unload a partitioned database in UL format, you can use the IMS HD Reorganization Reload utility or a compatible utility to reload the unloaded database data set. The data flow is the same as that for FABHURG1. A standard mode FABHFSU JCL used for a nonpartitioned database can be used with the following minor modifications: v You do not need to specify any DD statements for the database data sets. v You must use DBRC. v You must specify DD statements for RECON data sets or allocate them dynamically. For an example of JCL used for unloading the entire database, refer to Example 1: Unloading the entire database on page 110.

Unloading a partition or a sequence of partitions

When FABHFSU runs in standard mode, it can be used to unload a single partition or a sequence of partitions from a partitioned database. The PARTITION control statement in the CARDIN data set is used to specify a partition or a sequence or partitions to be unloaded. For the details of the control statement, see PARTITION
Chapter 7. Processing High Availability Large Databases

109

control statement on page 63 in Chapter 5. HSSR Engine allocates the buffers only for a selected partition or for a selected sequence of partitions. When a single partition is unloaded, the unloaded data set contains a header record, all segment records in the selected partition, and a trailer record. You can use the IMS HD Reorganization Reload utility or a compatible utility to reload the UL-format data set that is unloaded by the FABHFSU utility. The data flow is the same as that for FABHURG1. For an example of JCL used for unloading a partition, refer to Example 2: Unloading a partition on page 111. FABHFSU can also unload a sequence of partitions that is specified on a PARTITION control statement. HSSR Engine allocates buffers only for those partitions. When a sequence of partitions is unloaded, the unloaded data set contains the following records in the following sequence: 1. a header record 2. segment records of all selected partitions in the partition sequence determined by the IMS partition selection logic 3. a trailer record You can use the IMS HD Reorganization Reload utility or a compatible utility to reload the UL-format data set that is unloaded by the FABHFSU utility. The data flow is the same as that for FABHURG1. For an example of JCL used for unloading a partition, refer to Example 3: Unloading a sequence of partitions on page 111.

JCL requirements
In any FABHFSU JCL for HALDB, the following are required: v DBRC must be used. v The DD statements for RECON data sets must be specified or dynamically allocated. v No DD statements for database data sets must be specified.

Examples
This section provides three examples to unload a HALDB by FABHFSU.

Example 1: Unloading the entire database

The following is an example JCL to unload the entire database. The database that is to be unloaded is specified on the DBD parameter; DBRC=Y is specified so that DBRC is used; and the DD statements for RECON data sets are specified. All partition data sets are dynamically allocated by HSSR Engine. The DBD statement specifies the DBD name. The PSB statement shows that the unloaded data set is specified by the OUTPUT DD statement and that the output records are written in the UL format. Because 'PARTINFO DEF' is specified, the HALDB Partition Definition report is produced.

110

Users Guide

// EXEC FABHULU,MBR=FABHFSU,DBD=SKILLINV,DBRC=Y //RECON1 DD DSN=IMSVS.RECON1,DISP=SHR //RECON2 DD DSN=IMSVS.RECON2,DISP=SHR //RECON3 DD DSN=IMSVS.RECON3,DISP=SHR //CARDIN DD * DBDSKILLINV PSB* OUTPUT UL END /* //HSSROPT DD * PARTINFO DEF /* //PRNTOUT DD SYSOUT=A //OUTPUT DD DSN=IMSDB.UNLOADDS,DISP=(,KEEP),UNIT=TAPE

Example 2: Unloading a partition

The following is an example JCL to unload a partition of a partitioned database. The database that is unloaded is specified on the DBD parameter; DBRC=Y is specified so that DBRC is used. In this example, it is assumed that the RECON data sets are dynamically allocated. The DBD statement specifies the DBD name. The PSB statement shows that the unloaded data set is specified by the OUTPUT DD statement and that the output records are written in the UL format. The partition to be unloaded is specified by the PARTITION control statement in the CARDIN DD statement. All data sets for the selected partition SKINVP1 are dynamically allocated by HSSR. Because 'SEGSTAT PART' is specified, the partition-wide Segment Statistics report is produced.
// EXEC FABHULU,MBR=FABHFSU,DBD=SKILLINV,DBRC=Y //CARDIN DD * DBDSKILLINV PSB* OUTPUT UL PARTITION SKINVP1 SEGSTAT PART END /* //PRNTOUT DD SYSOUT=A //OUTPUT DD DSN=IMSDB.UNLOADDS,DISP=(,KEEP),UNIT=TAPE

Example 3: Unloading a sequence of partitions

The following is an example JCL to unload a sequence of partitions from a partitioned database. The database that is unloaded is specified on the DBD parameter; DBRC=Y is specified so that DBRC is used; and the DD statements for RECON data sets are specified. The DBD statement specifies the DBD name. The PSB statement shows that the unloaded data set is specified by the OUTPUT DD statement and that the output records are written in the UL format.

Chapter 7. Processing High Availability Large Databases

111

The partitions to be unloaded are three consecutive partitions. The first is the partition SKINVP1, which is specified on the PARTITION control statement in the CARDIN DD statement. All data sets for the selected partitions are dynamically allocated by HSSR Engine. Because 'SEGSTAT PART' is specified, the partition-wide Segment Statistics report is produced. Because 'PARTINFO DEF,ACC' is specified in HSSROPT DD, the HALDB Partition Definition report and the HALDB Partitions Accessed report are produced.
// EXEC FABHULU,MBR=FABHFSU,DBD=SKILLINV,DBRC=Y //RECON1 DD DSN=IMSVS.RECON1,DISP=SHR //RECON2 DD DSN=IMSVS.RECON2,DISP=SHR //RECON3 DD DSN=IMSVS.RECON3,DISP=SHR //CARDIN DD * DBDSKILLINV PSB* OUTPUT UL PARTITION SKINVP1 3 SEGSTAT PART END /* //HSSROPT DD * PARTINFO DEF,ACC /* //PRNTOUT DD SYSOUT=A //OUTPUT DD DSN=IMSDB.UNLOADDS,DISP=(,KEEP),UNIT=TAPE

Running your HSSR application program

The following control statements, in addition to the standard control statement, can be used when you are processing a partitioned database: v PARTINFO control statement in the HSSROPT data set v CALLSTAT control statement in the HSSROPT data set v PARTPROC control statement in the HSSRCABP data set

JCL requirements
In an HSSR JCL processing HALDBs, the following are required: v DBRC must be used. v The DD statements for RECON data sets must be specified or dynamically allocated. v No DD statements for HALDB data sets must be specified.

Examples
This section provides three examples to run the HSSR application program for a HALDB.

Example 1: Coding JCL for your HSSR application program

You can use FABHDLI, FABHDBB, or FABHULU as the cataloged procedure to run your application program. In the following example, FABHDLI is used. Here, assume that the application program HSSRAPPL processes a PHDAM database and the second DB PCB in the PSB PSBAPPL1 is used to access the PHDAM database from the application program through HSSR calls.

112

Users Guide

Assume also that the partitions are accessed sequentially. DBRC=Y is specified so that DBRC is used. Also, the DD statements for RECON data sets are specified. No DD statement for database data sets for the PHDAM to be processed is specified, because all data sets are dynamically allocated by HSSR Engine. Because no HSSRCABP DD statement is coded, the default CAB buffering parameters are used for the job. Because partitions are accessed sequentially, no PARTPROC control statement needs to be specified in HSSRCABP DD.
// EXEC //RECON1 DD //RECON2 DD //RECON3 DD //HSSROPT DD HSSRPCB 002 /* //OUTPUT DD FABHDLI,MBR=HSSRAPPL,PSB=PSBAPPL1,DBRC=Y DSN=IMSVS.RECON1,DISP=SHR DSN=IMSVS.RECON2,DISP=SHR DSN=IMSVS.RECON3,DISP=SHR * DSN=TESTDS.HSSRAPPL.OUTPUT,DISP=OLD

Example 2: Coding HSSRCABP for sequential access for HALDB

Assume that the same application program and the same PSB as in Example 1 are used. Assume also that the data set group A of the partitions PART3 and PART5 of the PHDAM database are extremely disorganized and you want to allocate more sequential buffers than the default for these data sets. Then, for example, you would code the CABDD and NBRSRAN control statements in HSSRCABP DD as follows:
// EXEC //RECON1 DD //RECON2 DD //RECON3 DD //HSSROPT DD HSSRPCB 002 /* //OUTPUT DD //HSSRCABP DD CABDD PART3A NBRSRAN 10 CABDD PART5A NBRSRAN 20 /* FABHDLI,MBR=HSSRAPPL,PSB=PSBAPPL1,DBRC=Y DSN=IMSVS.RECON1,DISP=SHR DSN=IMSVS.RECON2,DISP=SHR DSN=IMSVS.RECON3,DISP=SHR * DSN=TESTDS.HSSRAPPL.OUTPUT,DISP=OLD *

If you want to change NBRSRAN for all data sets of data set group A, you can code as follows:

Chapter 7. Processing High Availability Large Databases

113

// EXEC FABHDLI,MBR=HSSRAPPL,PSB=PSBAPPL1,DBRC=Y //RECON1 DD DSN=IMSVS.RECON1,DISP=SHR //RECON2 DD DSN=IMSVS.RECON2,DISP=SHR //RECON3 DD DSN=IMSVS.RECON3,DISP=SHR //HSSROPT DD * HSSRPCB 002 /* //OUTPUT DD DSN=TESTDS.HSSRAPPL.OUTPUT,DISP=OLD //HSSRCABP DD * CABDD PART*A NBRSRAN 10 /*

Remember to specify the single quotation marks on both side of the operand of the CABDD statement so that the operand can be treated as a wild card specification. For the details of HSSRCABP control statements, see Chapter 15, Tuning buffer handlers, on page 275.

Example 3: Coding HSSRCABP for random access to HALDB

Although not recommended, random access to multiple partitions of an HALDB is supported. Assume that the same PSB as in Example 1 is used; but assume here that the application HSSRAPPL accesses the partitions of the PHDAM database PARTDB1 in random. You need to code the PARTPROC control statement for the database in HSSRCABP DD. If no more than two partitions are accessed at a time, you should code the PARTPROC statement as follows:
// EXEC FABHDLI,MBR=HSSRAPPL,PSB=PSBAPPL1,DBRC=Y //RECON1 DD DSN=IMSVS.RECON1,DISP=SHR //RECON2 DD DSN=IMSVS.RECON2,DISP=SHR //RECON3 DD DSN=IMSVS.RECON3,DISP=SHR //HSSROPT DD * HSSRPCB 002 /* //OUTPUT DD DSN=TESTDS.HSSRAPPL.OUTPUT,DISP=OLD //HSSRCABP DD * PARTPROC PARTDB1 R CABDD PART%A RANSIZE 8 NBRSRAN 4 NBRDBUF 16 REFT4 12 /*

If no more than three partitions are accessed at a time, you must code the third operand of the PARTPROC statement. See the following example.

114

Users Guide

// EXEC FABHDLI,MBR=HSSRAPPL,PSB=PSBAPPL1,DBRC=Y //RECON1 DD DSN=IMSVS.RECON1,DISP=SHR //RECON2 DD DSN=IMSVS.RECON2,DISP=SHR //RECON3 DD DSN=IMSVS.RECON3,DISP=SHR //HSSROPT DD * HSSRPCB 002 /* //OUTPUT DD DSN=TESTDS.HSSRAPPL.OUTPUT,DISP=OLD //HSSRCABP DD * PARTPROC PARTDB1 R 3 CABDD PART%A RANSIZE 8 NBRSRAN 4 NBRDBUF 16 REFT4 12 /*

For the details of HSSRCABP control statements, see Chapter 15, Tuning buffer handlers, on page 275.

Migration unload and fallback unload

Unloading a HDAM or HIDAM database in order to change the DL/I access method of the database to PHDAM or PHIDAM is called migration unload. The process of restoring HDAM or HIDAM databases that were migrated to PHDAM or PHIDAM is known as fallback. Unloading a PHDAM or PHIDAM database for fallback is called fallback unload. FABHURG1 can be used for both purpose. FABHFSU does not provide these functions.

Migration unload
The procedure for migrating nonpartitioned databases to HALDBs is described in the Database Administration Guide for IMS. The FABHURG1 unload utility can be used to replace the IMS HD Reorganization Unload utility (DFSURGU0) in the migration scenario. Note, however, the following: v FABHURG1 can be used for the migration unload of HDAM or HIDAM databases. v FABHURG1 does not support the migration unload of secondary indexes. Secondary indexes must be unloaded by the IMS HD Reorganization Unload utility. v FABHURG1 does not support the migration unload of HISAM databases. HISAM database must be unloaded by the IMS HD Reorganization Unload utility.

Performing the migration unload using FABHURG1

To unload an HDAM or HIDAM database for a migration, specify the MIGRATE control statement in SYSIN DD. For more information on the control statement, see Chapter 4. For a sample JCL, see the next section.

Considerations
There are some considerations when you perform a migration unload. Considerations on region type: FABHURG1 must be executed in a ULU region when migration unload is designated.

Chapter 7. Processing High Availability Large Databases

115

Consideration on DFSVSAMP: If you want to get better performance, when a logical child is defined in the input database, you should code an appropriate number of IMS buffer pools in DFSVSAMP DD of your JCL. For the details, see Chapter 2, Job control language, on page 21. Consideration on database tuning statistics: Statistics for the segment length and the number of I/Os for virtual logical segment types are not produced. Consideration on hard-copy trace: For the virtual logical child, the segment prefix reported in a call trace is the segment prefix of the paired real logical child.

Example of migration unload

The following is an example JCL to create an unloaded data set that can be used in migrating an HDAM or HIDAM database. The example uses the IBM-supplied FABHULU cataloged procedure. Assume that the database is an HDAM database and consists of three data set groups. The database data sets that are to be unloaded are defined by HDAMDD1, HDAMDD2, and HDAMDD3 DD statements; the unloaded data set is defined by the SYSUT2 DD statement. The MIGRATE control statement is specified in the SYSIN DD, which indicates that this is a migration unload.
// EXEC //HDAMDD1 //HDAMDD2 //HDAMDD3 //SYSIN MIGRATE /* //SYSPRINT //SYSUT2 // FABHULU,MBR=FABHURG1,DBD=HDAMDBD DD DSN=TESTDS.HDAMDS1,DISP=SHR DD DSN=TESTDS.HDAMDS2,DISP=SHR DD DSN=TESTDS.HDAMDS3,DISP=SHR DD * DD SYSOUT=A DD DSN=MIGDS1.MIGULDS,DISP=(,CATLG),UNIT=TAPE, VOL=SER=MIGDS1

Exit routine FABHKEYX for distributing unload records

In the migration unload, you can use the IBM-provided exit routine FABHKEYX to distribute the unload records to multiple unload files according to the root key values. The multiple unload files enable the Reload and the optional PSSR SORT for two or more HALDB partitions to run in parallel processes, which will reduce the elapsed time for migration. To use this exit, you must specify FABHKEYX as a exit routine name on the EXIT control statement in the SYSIN data set and prepare a list of the DD names and the high key values for the unload files in the FABHKEYX data set. In each unload file, the correct header and trailer records are added. Note: If the root key is compressed, the control statement EXIT FABHKEYX cannot be specified with the DECN control statement. FABHKEYX data set : The FABHKEYX data set contains 80-byte fixed-length records. The FABHKEYX exit routine reads this data set that contains a list of the DD names and the high key values to distribute the unload records.

116

Users Guide

The entries of the list must be in the format that is shown in below and be listed in ascending order of the high key values.
0........1.........2.........3.........4.........5.........6... 123456789012345678901234567890123456789012345678901234567890... DDname KeyString

Position 1-8

Description Output DD Name This 8-character entry specifies the name of the DD statement for each unload files. The format of each data set must be same as the SYSUT2 DD.

10-

Key String This variable-length string specifies a high key value. The key values must be enclosed by single quotes and preceded by the letter C or X: C indicates the character values and X indicates the hexadecimal values. When the key string is long, you can specify it on multiple lines as below:
DDNAME01 CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA CAAAAAAAAAAAA

Hexadecimal values must be even-length. If the high key is longer than the root key, the later extra will be ignored. If the high key is shorter, the high key value is padded with XFFs up to the defined root key length. Example of migration unload with FABHKEYX exit: The following is an example JCL to distribute the unload records for migration to HALDB to four unload files by using the FABHKEYX exit routine.
// EXEC FABHULU,MBR=FABHURG1,DBD=HDAMDBD //HDAMDD1 DD DSN=TESTDS.HDAMDS1,DISP=SHR //HDAMDD2 DD DSN=TESTDS.HDAMDS2,DISP=SHR //HDAMDD3 DD DSN=TESTDS.HDAMDS3,DISP=SHR //SYSIN DD * MIGRATE EXIT FABHKEYX //SYSPRINT DD SYSOUT=A //SYSUT2 DD DUMMY //FABHKEYX DD * ULFPART1 C2999999 ULFPART2 C5999999 ULFPART3 C9999999 ULFPART4 XFF //ULFPART1 DD DSN=MIGDS1.MIGULDS.ULFPART1, //ULFPART2 DD DSN=MIGDS2.MIGULDS.ULFPART2, //ULFPART3 DD DSN=MIGDS3.MIGULDS.ULFPART3, //ULFPART4 DD DSN=MIGDS3.MIGULDS.ULFPART4,

... ... ... ...

Notes: 1. You can define the SYSUT2 DD as DUMMY to reduce the elapsed time for the I/O operations. 2. It is recommended that you specify XFF for the last DD name in the FABHKEYX data set not to throw segments away.
Chapter 7. Processing High Availability Large Databases

117

Fallback unload
The procedure for the fallback unload of HALDBs is described in the Database Administration Guide of IMS. The FABHURG1 unload utility can be used as a replacement of the IMS HD Reorganization Unload utility (DFSURGU0) in the fallback scenario. Note, however, the following: v FABHURG1 can be used for the fallback unload of PHDAM or PHIDAM databases. v FABHURG1 does not support the fallback unload of partitioned secondary indexes (PSINDEXs). PSINDEXs must be unloaded by the IMS HD Reorganization Unload utility.

Performing the fallback unload using FABHURG1

Specify the FALLBACK control statement in SYSIN DD to unload a PHDAM or PHIDAM database for a fallback. See Chapter 4 for more information on the control statement. For sample JCL, see the next section. When fallback unload is designated, FABHURG1 must be executed in the ULU region.

Example of fallback unload

To create an unloaded data set that can be used for a fallback of a PHDAM or PHIDAM database, you can use the JCL shown in the following figure. The example uses the IBM-supplied FABHULU cataloged procedure. Assume that the database is a PHDAM database and consists of three data set groups. The DBRC=Y option must be specified on the EXEC statement. The unloaded data set is defined by the SYSUT2 DD statement. You do not need to code any DD statements for database data sets, because all data sets are dynamically allocated by HSSR Engine. The FALLBACK control statement is specified in the SYSIN DD, which indicates that this is a fallback unload.
// EXEC //RECON1 //RECON2 //RECON3 //SYSIN FALLBACK /* //SYSPRINT //SYSUT2 // FABHULU,MBR=FABHURG1,DBD=PHDAMDBD,DBRC=Y DD DSN=IMSVS.RECON1,DISP=SHR DD DSN=IMSVS.RECON2,DISP=SHR DD DSN=IMSVS.RECON3,DISP=SHR DD * DD SYSOUT=A DD DSN=FBKDS1.FBKULDS,DISP=(,CATLG),UNIT=TAPE, VOL=SER=FBKDS1

Summary of HALDB restrictions for processing

The following restrictions apply to the support that High Performance Unload provides for HALDB.

Restrictions for Unload utilities

This section explains the restrictions for Unload utilities.

118

Users Guide

FABHURG1 utility
v FABHURG1 does not support the migration unload of secondary indexes. v FABHURG1 does not support the migration unload of HISAM databases. v If PTR=H or PTR=HB is defined as the parent segment of virtual logical child, FABHURG1 does not support the migration unload of the database. v FABHURG1 does not support the fallback unload of partitioned secondary indexes.

FABHFSU utility
v FABHFSU cannot HALDB unload in PSF mode. v FABHFSU does not support migration unload. v FABHFSU does not support fallback unload.

Restrictions for user application programs

v A user HSSR application program cannot process only the selected partitions; HALDB is processed as an entire database.

Chapter 7. Processing High Availability Large Databases

119

120

Users Guide

Chapter 8. Specifying options for HSSR Engine

You can specify options for HSSR Engine by coding control statements in the HSSROPT data set. Topics: v Overview of control statements v HSSROPT data set on page 122

Overview of control statements

Control statements for HSSR Engine are specified in the HSSROPT data set. The options include: v Options for call analyzer and call handler components of HSSR Engine v Options for buffer handler component of HSSR Engine v Options for reports and outputs produced by HSSR Engine v Options for trace function provided by HSSR Engine v Options for problem determination You can tune HSSR Engines Chained Anticipatory Buffering (CAB) buffer handler by coding control statements in the HSSRCABP data set. For the details, see Chained Anticipatory Buffer Handler (CAB) on page 275. You can specify HSSRLDEF DD to change the range of lengths of database records in DB Tuning Statistics. For the details, see Input: HSSRLDEF data set on page 170. The control statements shown in Table 17 are provided to specify options for HSSR Engine. Control statements for options that control report output are also specified in the HSSROPT data set. For the description of each statement, see HSSROPT data set on page 122.
Table 17. List of HSSROPT control statements for HSSR Engine Used for Call Analyzer and Call Handler Keyword APISET BLDLPCK BYINDEX DATXEXIT HSSRDBD HSSRPCB KEYCHECK Function Specifies a set of call types that can be processed. Description See APISET control statement on page 123.

Whether to retrieve logical parents concatenated See BLDLPCK control keys (LPCKs) or not. statement on page 123. Unloads HIDAM root segments through the HIDAM index. Specifies whether the data conversion exit is to be activated. Specifies HSSR PCBs by using DBD names. Specifies HSSR PCBs by using PCB numbers. Specifies the action for key sequence errors. See BYINDEX control statement on page 125. See DATXEXIT control statement on page 129. See HSSRDBD control statement on page 130. See HSSRPCB control statement on page 131. See KEYCHECK control statement on page 132. See SKERROR control statement on page 137.

SKERROR SKIPVLC

Sets error skip count.

Specifies to ignore a sensitive virtual logical child See SKIPVLC control segment in the DLI or the DBB region. statement on page 138.

Copyright IBM Corp. 2000, 2007

121

Table 17. List of HSSROPT control statements for HSSR Engine (continued) Used for Buffer handler Keyword GOTRETRY Function Change the default retry parameters for PROCOPT=GOT. Specifies whether to share the LSR pool with DL/I. Specifies not to page-fix CAB buffer pools. Prevents the override of the read-ahead threshold values used by VSAM. Specifies a type of PCB list to be passed to the application program. Specifies that a failing KSDS I/O operation is to be retried. Controls the amount of CAB Statistics report. Specifies that partition-wide database call statistics are to be produced for each partition of HALDB. Provides a Database Tuning Statistics report. Generates diagnosis information for status GG. Specifies the record-selection criteria for HSSRLOUT data set. Produces Partition Definition reports and Partitions Accessed report. Activates the buffer trace function. Specifies the databases to be traced. Specifies the information to be reported by the trace function. Specifies the number of trace entries for wrap-around core trace. Specifies that the result of an HSSR call is to be compared with that of a DL/I call. Specifies that HSSR calls are to fall back to DL/I calls. Specifies the name of the run-time exit routine. Description See GOTRETRY control statement on page 130. See LSR control statement on page 133. See NOFIX control statement on page 134. See NOVSAMOPT control statement on page 134. See PCBLIST control statement on page 135. See RETRY control statement on page 136. See CABSTAT control statement on page 125. See CALLSTAT control statement on page 126. See DBSTATS control statement on page 127. See DIAGG control statement on page 128. See LOUT control statement on page 133. See PARTINFO control statement on page 135. See BUTR control statement on page 124 See TRDB control statement on page 138. See TRHC control statement on page 139. See TRXC control statement on page 140. See CO control statement on page 126. See DBDL1 control statement on page 127. See RTEXIT control statement on page 136.

LSR NOFIX NOVSAMOPT

PCBLIST RETRY Reports and outputs CABSTAT CALLSTAT

DBSTATS DIAGG LOUT PARTINFO Trace function BUTR TRDB TRHC TRXC Problem determination CO DBDL1 Other control statements RTEXIT

HSSROPT data set

This section explains the HSSROPT data set that contains the HSSROPT control statements.

122

Users Guide

Syntax of HSSROPT control statements

To code HSSROPT control statements, follow these format rules: v A control statement keywords must always begin in column 1. v A control statement keyword must be followed by a blank. v Additional control information is coded after the blank. v Continuation control statements are not allowed.

Description of control statements

This section describes each HSSROPT control statement.

APISET control statement

The APISET control statement specifies a set of HSSR call types that can be used in your HSSR application program.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 APISET 1 2 3

Position 1 8

Description Code the APISET keyword to specify a set of HSSR call types. Code 1, 2, or 3. For details about what each APISET supports, see DL/I calls supported by each API set on page 90.

APISET 1 is the default. IBM an recommends that you specify APISET 2 or 3 only if your application program issues a call that APISET 1 does not support. Notes: 1. The default of this control statement can be changed by replacing the default option table (FABHOPT). For details, see Chapter 19, Setting site default options, on page 335. 2. If you specify APISET 3, you cannot specify any of the following control statements can be specified: BYINDEX, DBSTATS, KEYCHECK, or SKERROR. 3. If you specify APISET 3, the BLDLPCK control statement is always activated. 4. If you specify APISET 3, the disposition of the database data sets must be DISP=SHR.

BLDLPCK control statement

By default, for a logical child segment with a logical parents concatenated key (LPCK) that is specified as "virtual" on the SEGM statement of the DBD, HSSR call handler returns blanks in the I/O area that would usually hold the LPCK. For compatibility with FSU II, FABHFSU returns binary zeros to the I/O area instead of blanks. You can use the BLDLPCK control statement to have HSSR call handler build the LPCK and return it in the I/O area.

Chapter 8. Specifying options for HSSR Engine

123

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 BLDLPCK

Position 1 Notes:

Description Code the BLDLPCK keyword to activate the BLDLPCK option.

1. If the LPCK is defined as "physical"that is, if the LPCK is physically stored as a part of the logical child segment in the databaseHSSR call handler ignores this option. 2. If the BLDLPCK statement is specified and there are a large number of virtual LPCKs in the database, the performance of High Performance Unload could be degraded. The BLDLPCK statement is necessary, however, if the control statement for the Pre-reorganization utility specifies that the DBIL for the logical child database is to be unloaded by FABHURG1 or FABHFSU. If the DBIL is specified for the database, symbolic keys in the unloaded database are used to match up logical children and parents. 3. If the BLDLPCK statement is specified for a database that has a logical child whose LPCK is defined as "virtual," the database data sets for all logical parent databases of such logical children must be specified on the JCL. If the DD statement for one of logical parent databases is not specified, HSSR call handler returns the status code of "AI" to the application program when the logical child segment is processed, and the part of the I/O area that should contain the LPCK is filled with blanks. FABHURG1 and FABHFSU issue the message FABH0560E, and the programs end processing. 4. The BLDLPCK statement is not supported for HISAM databases. 5. The BLDLPCK statement is ignored for a PHDAM or PHIDAM database. 6. The BLDLPCK statement is ignored if either MIGRATE or FALLBACK control statement is specified in the SYSIN data set for a FABHURG1 job. 7. If APISET 3 is specified, the BLDLPCK statement is ignored.

BUTR control statement

The BUTR control statement directs HSSR Engine to create a file containing a machine-readable trace of internal calls to the buffer handler. This trace, which is written to the HSSRBUTR data set, can be used as input to FABHBSIM, the HSSR Buffer Handler Simulation utility (see Chapter 17, Using the buffer handler simulation utility, on page 309).
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 BUTR

Position

Description

124

Users Guide

Code the BUTR keyword to instruct HSSR Engine to create a file containing a machine-readable trace of internal calls to the buffer handler.

Note: No buffer trace is taken for HALDBs.

BYINDEX control statement

The BYINDEX control statement instructs HSSR Engine to retrieve HIDAM or PHIDAM root segments sequentially via the HIDAM or PHIDAM index instead of via the root-twin chain. (If the root segments have no twin backward or hierarchical backward pointer, the BYINDEX control statement has no effect.) A secondary index can also be used for HIDAM or HDAM root segments.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 BYINDEX BYINDEX index

Position 1 9

Description Code the BYINDEX keyword to activate the BYINDEX option. Specifies a secondary index of the HIDAM or HDAM database if you want the root segments to be retrieved in the secondary index sequence. The target segment of the index must be the root segment. For details, see For using a secondary index on page 32.

Notes: 1. If APISET 3 is specified, this statement cannot be specified. 2. If one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, BYINDEX=YES is ignored. 3. FABHFSU ignores this control statement. Specify the index name in the DBD control statement in the CARDIN data set.

CABSTAT control statement

This control statement is used to control the amount of CAB statistics that HSSR Engine prints on the HSSRSTAT data set.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 CABSTAT NO YES

Position 1 9

Description Code the CABSTAT keyword to control the printing of the CAB statistics. Specify one of the following keywords: Keyword Description
Chapter 8. Specifying options for HSSR Engine

125

NO YES

Requests to limit CAB statistics to the main summary report. This is the default. Requests the printing of the detailed CAB statistics report on the HSSRSTAT data set.

Note: This default can be changed by replacing the default option table (FABHOPT). See Chapter 19, Setting site default options, on page 335.

CALLSTAT control statement

This control statement is used to produce the partition-wide database call statistics for each partition.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 CALLSTAT PART

Position 1 10

Description Code the CALLSTAT keyword. Code the PART keyword to print the partition-wide database call statistics reports for each partition that was processed and from which at least one segment was retrieved.

Note: In any one of the following cases, the partition-wide statistics are not printed: v If the CALLSTAT statement is specified for a nonpartitioned database. v If the PART keyword is not specified. v If a keyword other than PART is specified.

CO control statement
The compare (CO) control statement causes each HSSR call issued by the application program to be preceded by a DL/I call issued with the same SSA as the HSSR call. The resultant I/O areas and PCBs of both calls are compared internally. If a mismatch occurs, the I/O areas and the PCBs are printed on the HSSRTRAC data set. HSSR Engine either abends or returns to the application program.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 CO CO N

Position 1 4

Description Code the CO keyword to activate the compare option. Specify the action of HSSR Engine when a difference is found in HSSR and DL/I calls. Keyword blank Description HSSR Engine abends with a dump.

126

Users Guide

This option should normally be used when a mismatch is detected between HSSR and DL/I calls. N HSSR Engine returns control to the application program when a mismatch is detected between HSSR and DL/I calls.

Notes: 1. To use the CO control statement, the database data sets should be allocated with DISP=SHR. 2. If the database is being updated concurrently, the results of DL/I calls and HSSR calls may differ. In such a case, do not use the CO control statement. 3. If APISET 3 is specified, the comparison is not done for the calls that are finally processed by DL/I. 4. If one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, the blank keyword is ignored.

DBDL1 control statement

The DBDL1 control statement has the following functions: v Forces High Performance Unload program controller to define PCBs as DL/I PCBs. v Enables users to temporarily bypass software errors in HSSR Engine. v Enables users to make performance comparisons between HSSR and DL/I calls. v Enables an application using a particular PSB to run on one occasion with HSSR Engine, and on another occasion with DL/I.

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DBDL1 dbdname1,dbdname2,dbdname3,dbdname4 *ALL

Position 1 7

Description Code the DBDL1 keyword to force HSSR PCBs to be read as DL/I PCBs. Enter in this 8-character field either multiple dbdnames or the keyword *ALL. If dbdnames are specified, only the PCBs referring to those names are considered DL/I PCBs. If the keyword *ALL is specified, all PCBs are considered DL/I PCBs. Code dbdnames left-justified, followed by trailing blanks, if necessary, and separated by commas. A maximum of eight dbdnames can be coded.

Note: If multiple DBDL1 statements are provided, only the last is used.

DBSTATS control statement

The DBSTATS optional control statement activates the Database Tuning Statistics function.

Chapter 8. Specifying options for HSSR Engine

127

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DBSTATS nnnnn

Position 1 9

Description Code the DBSTATS keyword to instruct HSSR Engine to provide the Database Tuning Statistics report. Specify the number of buffers to be simulated with this entry. Enter any number up to 5 digits (1-32767), left-justified, and followed by a blank. If this entry is left blank, the default value of 4 is used.

For a complete description of the DBSTATS control statement and Database Tuning Statistics function, see Chapter 10, Using Database Tuning Statistics, on page 167. Notes: 1. If APISET 3 is specified, this statement cannot be specified. 2. If one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, this statement is ignored.

DIAGG control statement

The DIAGG control statement is used to request HSSR Engine to write diagnostic information to the HSSRTRAC data set whenever a GG or a GX status code is returned. This option is most important when you are unloading a database with the SKERROR option. The diagnosis information documents the location of the database errors and indicates which segment types may be missing in the unloaded database data set. When you activate the SKERROR control statement to unload a corrupted database, be sure to activate the DIAGG control statement, too. For the details of diagnosis information, see Trace Output report with diagnostics on page 155; especially, see Type of GG error on page 155 for a discussion of types of error cases.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DIAGG DIAGG DIAGONLY DIAGG [CB|BUF|CB,BUF|BUF,CB] DIAGG NOINT

Position 1

Description Code the DIAGG keyword to request that HSSR Engine write diagnosis information to the HSSRTRAC data set whenever a GG or a GX status code is returned. Enter one of the following keywords. You can specify both CB and BUF in a single statement, separated from each other with a comma.

128

Users Guide

Keyword blank

Description Interpreted as DIAGONLY. Note: You can change this interpretation by replacing the default option table (FABHOPT). See Chapter 19, Setting site default options, on page 335.

DIAGONLY CB BUF NOINT

Writes diagnosis information only. You cannot use this keyword with other keywords. Writes HSSR control blocks in addition to the diagnosis information. Writes buffer handler information in addition to the diagnosis information. Writes buffer handler information in addition to the diagnosis information. You cannot use this keyword with other keywords.

Notes: 1. The trace of control blocks of HSSR Engine, produced by specifying CB or BUF option for DIAGG control statement, is not intended to be reviewed by users, but might be needed by IBM Support Center to analyze a problem. 2. The DIAGG control statement can write more than 4000 print lines to the HSSRTRAC data set for each GG status code returned. For example, if a segment prefix contains 10 bad pointers, this could yield more than 40,000 print lines for the single bad segment prefix. Therefore, when the DIAGG option is active, the HSSRTRAC data set should be allocated in a way to avoid S722 or SB37 abends. For example, you can specify through the OUTLIM parameter a large number of SYSOUT print lines or you can allocate HSSRTRAC on tape.

DATXEXIT control statement

The DATXEXIT control statement specifies whether the Data Conversion exit is to be activated for HSSR calls and DL/I calls. Note: HSSR Engine support of Data Conversion exit routines is restricted to the Data Conversion exit routine provided by Year 2000 Exit Tool. No other Data Conversion exit routine is supported.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DATXEXIT YES NO

Position 1 10

Description Code the DATXEXIT keyword to specify the treatment of the Data Conversion exit routine DFSDBUX1. Enter one of the following keywords: Keyword NO Description Requests HSSR Engine not to call DFSDBUX1
Chapter 8. Specifying options for HSSR Engine

129

even if it is in a library concatenated to STEPLIB DD. The option 'DATXEXIT NO' has the same effect; the module DFSDBUX1 is removed from STEPLIB libraries. This is the default. YES Requests that HSSR Engine treat DFSDBUX1 in the same way that IMS does through IMSs Data Conversion exit. If 'DATXEXIT YES' is specified, the module DFSDBUX1 exists in a STEPLIB library, and the use of the Data Conversion exit is designated for a database, then DFSDBUX1 is called each time a DL/I call or an HSSR call is issued against the database.

GOTRETRY control statement

The GOTRETRY control statement is used to retry database accesses for PROCOPT=GOT. When encountering an incorrect pointer with HIDAM, HDAM, PHIDAM, and PHDAM databases, HSSR Engine, by default, attempts to access the database access four times, with 5-second intervals between attempts. GOTRETRY is used to change the default value for both the number of access attempts and the number of seconds to wait between these access attempts.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 GOTRETRY NBR=nnn,WAIT=sss

Position 1

Description Code the GOTRETRY keyword to instruct HSSR Engine to override the default number of reaccesses and the default number of seconds to wait before each reaccess attempt. This entry can contain one or both of the following keywords in any order: Keyword NBR=nnn Description This entry denotes the number of times that HSSR Engine should attempt to reaccess a database. (nnn is a left-justified number from 1 to 999.) This entry denotes the number of seconds that HSSR Engine should wait before it attempts to reaccess a database. (sss is any left-justified number from 0 to 999.)

10

WAIT=sss

HSSRDBD control statement

The HSSRDBD control statement has the following functions: v Defines all PCBs that refer to the specified DBDs as HSSR PCBs. v Enables an application issuing DL/I calls to run on one occasion with HSSR Engine, and on another occasion with DL/I.

130

Users Guide

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 HSSRDBD dbdname1,dbdname2,dbdname3,dbdname4,... *ALL

Position 1 9

Description Code the HSSRDBD keyword to force all PCBs that refer to the specified DBDs to be treated as HSSR PCBs. Enter in this 8-character field either multiple dbdnames delimited by a comma or the keyword *ALL. If the length of a dbdname is less than 8 bytes, it must be left-justified and padded with blanks. If dbdnames are specified, those PCBs that refer to specified DBD are considered to be HSSR PCBs. If the keyword *ALL is specified, all PCBs that refer to the DBD are considered to be HSSR PCBs.

Notes: 1. A maximum of 500 DBD names can be coded. 2. HSSRDBD control statement cannot be specified with an HSSRPCB control statement. 3. If the list of DBD names cannot fit into one line, the DBD names must be specified as multiple HSSRDBD statements, each of which must fit into a line. 4. If both an HSSRDBD statement that has the *ALL operand and a HSSRDBD statement that has the DBD list operand are specified, the *ALL specification has priority over all others. 5. If a DBD name is specified on an HSSRDBD statement and is also specified on a DBDL1 control statement, the specification by the DBDL1 statement has priority and all PCBs that refer to the DBD are treated as DL/I PCBs.

HSSRPCB control statement

The HSSRPCB control statement has the following functions: v Defines the specified DL/I PCBs as HSSR PCBs. v Enables an application issuing DL/I calls to run on one occasion with HSSR Engine, and on another occasion with DL/I.

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 HSSRPCB pcbnum1, pcbnum2, pcbnum3, pcbnum4,... *ALL

Position 1 9

Description Code the HSSRPCB keyword to force the specified PCBs to be treated as HSSR PCBs. Enter in this 3-digit field either multiple database PCB numbers delimited by a comma or the keyword *ALL. The PCB number for the first database PCB is 001. If the PCB numbers are specified,
Chapter 8. Specifying options for HSSR Engine

131

those PCBs are treated as HSSR PCBs. If the keyword *ALL is specified on this field, all database PCBs are considered to be HSSR PCBs. Notes: 1. A maximum of 500 PCBs can be coded. 2. The HSSRPCB control statement cannot be specified with the HSSRDBD statement. 3. If the list of PCB numbers cannot fit into one line, the PCB numbers must be specified as multiple HSSRPCB statements, each of which must fit into a line. 4. If both an HSSRPCB statement that has *ALL operand and an HSSRPCB statement that has PCB number operands are specified, the *ALL specification has priority over all others. 5. If a PCB specified on an HSSRPCB statement refers to a DBD that is specified on a DBDL1 control statement, the specification by DBDL1 statement has priority and the PCB is treated as a DL/I PCB.

KEYCHECK control statement

The KEYCHECK optional control statement is used when you want to be sure that the segment key fields are in ascending sequence.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 KEYCHECK ABEND GX GG

Position 1

Description Code the KEYCHECK keyword to activate the option that checks the key sequence. It must be used with one of the following three code options. (Separate the words with a space.) Code one of the following optional keywords: Keyword ABEND GX Description Performs key checking and ends abnormally if a sequence error is detected. Performs key checking and returns a warning GX status code if a sequence error is detected. The segment with the incorrect key is returned normally to the calling application program or utility. For the EXEC DLI command, the status 'GX' is not returned to the application program. Instead, message DFS1041 is issued in the EXEC DLI interface module (DFSEIPB0). It ends with a code of U1041. GG Performs a key check and returns a GG status code if a sequence error is detected. No segment will be returned to the calling application program or utility.

10

132

Users Guide

This option requires PROCOPT=GON, GOT, or an active SKERROR; if none of these conditions is specified, HSSR Engine abends instead of returning a GG status code. If the SKERROR control statement is active, HSSR Engine does not retrieve the incorrect segment or other related segments during the processing of the next GN call. If the SKERROR control statement is inactive, HSSR Engine resets the current position to the beginning of the database. Notes: 1. If APISET 3 is specified, this statement cannot be specified. 2. If one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, KEYCHECK=ABEND/GX/GG is ignored.

LOUT control statement

The LOUT control statement requests the output record selection for the HSSRLOUT data set, when the DBSTATS control statement activates the Database Tuning Statistics function. If the DBSTATS control statement is not specified at the same time, this option is ignored.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 LOUT LENGTH=llllllll LOUT IO=nn

Position 1 6

Description Specify the LOUT keyword to request an optional record selection for the HSSRLOUT data set. Specify one of the following optional keywords: Keyword Description

LENGTH=llllllll Requests that the HSSRLOUT data set contain only the records for database records whose length is greater than llllllll bytes. IO=nn Requests that the HSSRLOUT data set contain only the records for database records that require more than nn database I/Os for their retrieval.

For a complete description of the LOUT control statement and Database Tuning Statistics function, see Chapter 10, Using Database Tuning Statistics, on page 167.

LSR control statement

The optional LSR control statement is used to request that HSSR Engine share the local shared resource (LSR) pool with DL/I while processing primary index of HIDAM or PHIDAM databases. For the details of this option and how to code DFSVSAMP DD when 'LSR YES' is specified, see VSAM LSR option for primary index databases on page 298.
Chapter 8. Specifying options for HSSR Engine

133

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 LSR NO LSR YES

Position 1 5

Description Code the LSR keyword to specify the LSR option. Enter one of the following keywords: Keyword NO Description Requests that primary indexes of HIDAM and PHIDAM databases be processed with the NSR option. This is the default. Note: This default can be changed by replacing the default option table (FABHOPT). See Chapter 19, Setting site default options, on page 335. YES Requests that primary indexes of HIDAM and PHIDAM databases be processed with the LSR option, to improve the performance (through better look-aside buffering) of programs that issue numerous GU calls to HIDAM or PHIDAM databases.

NOFIX control statement

By default, buffer pools are page-fixed. To avoid page-fixing, you can use a NOFIX control statement.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 NOFIX

Position 1

Description Code the NOFIX keyword to activate the NOFIX option.

NOVSAMOPT control statement

The NOVSAMOPT control statement prevents the override of the read-ahead threshold value used by VSAM.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 NOVSAMOPT

Position

Description

134

Users Guide

Code the NOVSAMOPT keyword to activate the NOVSAMOPT option.

PARTINFO control statement

This optional control statement specifies whether any optional information is to be reported when a HALDB is processed.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PARTINFO DEF,ACC

Position 1 10

Description Code the PARTINFO keyword to initiate HSSR Engine to produce the partition information report. Specify which report should be produced. These parameters are not positional and can be specified in any order. If two or more parameters are specified, put a comma between parameters. Information specified on this statement affects the number of lines written in HSSRSTAT data set. At least one parameter must be specified. Keyword DEF ACC Description Initiate HSSR Engine to produce the HALDB Partition Definition report. Initiate HSSR Engine to produce the HALDB Partitions Accessed report.

PCBLIST control statement

The PCBLIST control statement specifies the type of PCB list that is to be passed to the application program.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PCBLIST HSSR IMS

Position 1 9

Description Code the PCBLIST keyword to specify a type of PCB list. Code one of the following keywords: HSSR The PCB list that is built by HSSR Engine and that can contain an entry that points to HSSR PCB is passed to the application program. The PCB list that is built by IMS is passed to the application program.

IMS

PCBLIST HSSR is the default.

Chapter 8. Specifying options for HSSR Engine

135

Notes: 1. The default of this control statement can be changed by replacing the default option table (FABHOPT). For details, see Chapter 19, Setting site default options, on page 335. 2. If your application program issues a DL/I system call that gets access to the IMS PCB list, it is recommended that you specify PCBLIST IMS. One such call is the INQY call with the FIND subfunction, which returns the PCB address of the requested PCB name. 3. If your application program issues an HSSR call as an EXEC DLI command, you must specify PCBLIST IMS.

RETRY control statement

The RETRY control statement is used to retry a failing KSDS I/O operation. In a database-sharing environment, HSSR Engine might encounter VSAM logical errors if it reads a KSDS data set that is being concurrently updated and is also subject to CI splits. By default, HSSR Engine abends in such a situation. You can use the optional RETRY control statement. However, to instruct HSSR Engine to refresh its buffers and retry the failing KSDS I/O operation, HSSR Engine accesses data that has been inserted, during a control area split, into a new control area at the end of the KSDS. Note: When HSSR Engine reads a KSDS data set that is subject to CI splits, any KSDS records that shifted out of the CI being split may be skipped. CI splits might also cause some records to be read twice.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 RETRY KSDS

Position 1 7

Description Code the RETRY keyword. Code the KSDS keyword to activate the HSSR Engines retry operation.

RTEXIT control statement

The RTEXIT control statement is used to specify the name of a run-time environment exit routine that can initialize and terminate processing required by the users environment, such as a COBOL II run-time environment. The FABHRTEX module is provided as the default run-time environment exit routine, which is a dummy exit routine that returns to HSSR Engine without any processing. If any initialization or termination processing is required by your environment, you can modify this routine or write your own exit routine. The run-time environment exit routine is called before and after an HSSR application program is invoked. If no RTEXIT control statement is specified, the IBM-supplied FABHRTEX module or the user-written FABHRTEX module is called as the run-time environment exit routine. See Run-Time Environment exit (FABHRTEX) on page 313.

136

Users Guide

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 RTEXIT xxxxxxxx

Position 1 8

Description Code the RTEXIT keywords. The left-justified load module name of the run-time environment exit routine.

SKERROR control statement

The SKERROR control statement allows database errors to be bypassed. This option enables retrieval from a database even if the database contains incorrect HD pointers or incorrect HISAM records. This bypass is achieved by skipping the processing either of the incorrect pointer or of the remainder of the incorrect HISAM record. A GG status code is returned. Thus, HSSR Engine cannot process segments with segment codes in error. SKERROR is used when a corrupted HIDAM, HDAM, PHIDAM, PHDAM, or HISAM database is unloaded with FABHURG1. You can then reload this database via the IMS HD Reorganization Reload utility or a compatible utility, to create a new version of the database. Although the new version meets the technical requirements for a valid IMS database, some segments may be omitted. For more details, see the following: v Chapter 12, Unloading corrupted databases, on page 249, for procedures to follow when recovering a corrupted database. v Trace Output report with diagnostics on page 155, for a discussion of the types of error cases encountered and printed on the Trace Output report. Notes: 1. If you spending APISET 3, you cannot specify this statement. 2. If one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, SKERROR=nnnnnnnnn is ignored.

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 SKERROR nnnnnnnnn

Position 1 9

Description Code the SKERROR keyword to activate the error-skipping option. This is the maximum number of incorrect records to be skipped. Enter up to 9 digits, left-justified and followed by a blank. If the field is left blank, HSSR Engine skips up to 9999 incorrect records. If more than this number of GG status codes are returned, HSSR Engine issues an abend.

When you include the SKERROR control statement to unload a corrupted database, be sure to include a DIAGG control statement.
Chapter 8. Specifying options for HSSR Engine

137

Note: The SKERROR control statement can be used for HSSR PCBs that do not have an update PROCOPT specified. For example, it can be used for HSSR PCBs that have PROCOPT equal to G, GE, GO, GON, or GOT; but it is ignored for all HSSR PCBs that have PROCOPT=R.

SKIPVLC control statement

The SKIPVLC control statement requests HSSR Engine to ignore a sensitive virtual logical child segment in the DLI or the DBB region. In the ULU region, the virtual logical child segment type is always ignored, therefore this control statement is not used.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 SKIPVLC YES NO

Position 1 9

Description Code the SKIPVLC keyword to ignore a sensitive virtual logical child segment in the HSSR PCB. Specify one of the following keywords: Keyword YES NO Description Requests HSSR Engine to ignore a sensitive virtual logical child segment in the HSSR PCB. Requests HSSR Engine not to ignore the sensitive virtual logical child. The HSSR Engine does not treat the PCB, in which the logical child segment is sensitive, as an HSSR PCB. This is the default. v HP Unload utilities such as FABHURG1, FABHFSU, and FABHTEST issue a user abend because the PCB is not an HSSR PCB. v In a user application program that uses the HP Unload API, all HSSR calls to the PCB fall back to DL/I calls.

TRDB control statement

The TRDB control statement must be used with the TRHC control statement. After the TRHC indicates the type of trace to be run, the TRDB control statement then identifies the specific databases on which these traces are run.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 TRDB *ALL dbdname1,dbdname2,dbdname3,dbdname4

Position 1 6

Description Code the TRDB keyword to activate the hard-copy tracing for specified database. Enter either dbdnames separated by commas or the keyword *ALL.

138

Users Guide

Each dbdname must meet the following requirements: v It must occupy eight bytes and be left-aligned. v If the name is less than eight characters, trailing blanks must be specified. v The last dbdname must be followed by a blank. If multiple TRDB statements are provided, only the last is used.

TRHC control statement

The TRHC control statement is the hard-copy tracing option of HSSR Engine. It is always used in combination with the TRDB control statement. When this option is active, HSSR Engine traces calls issued against the databases named in the TRDB control statement. It writes data about these calls on the HSSRTRAC data set.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 TRHC CALL,CB,CBX,BUF,BUFCB,START=n,NPF

Position 1 6

Description Code the TRHC keyword to activate the hard-copy tracing option. Enter one or more of the following keywords, separated by commas, specified in any order. The last keyword must be followed by a blank. Keyword CALL Description Traces call information such as call function, PCB, IOAREA, SSA, and segment prefix. Does a trace for the EXEC DLI command, just the same as for the DL/I call. This is because the command is converted to the format of a DL/I call and made to the HSSR call handler. CB or CBX Traces the control blocks of HSSR Engine. If CBX is specified, traces are also done for the extended control blocks of HSSR Engine. If both CB and CBX are specified, CBX is taken. BUF BUFCB START=n Traces buffer handler information. Traces the CAB buffer handler control blocks. Specifies the call number n. Trace begins at the n-th HSSR call issued by the application program. Enter any number up to nine digits, left-justified, and followed by a blank. Excludes the segment prefix information from the trace.

NPF

Only HSSR calls issued against the databases specified on the TRDB control statement are traced. Note: The trace of the control blocks of HSSR Enginewhich is called for by specifying the CB, CBX, BUF, or BUFCB option for the TRHC control

Chapter 8. Specifying options for HSSR Engine

139

statementis not intended to be reviewed by users, but might be needed by the IBM Support Center to analyze a problem.

TRXC control statement

The TRXC control statement activates the wrap-around core tracing option. HSSR Engine traces all HSSR calls issued by the application program and stores the information in a table maintained in storage. In the "user subpools" portion of the dump, table entries show the following information about the last n calls for each PCB: v Eye-catcher 'TRAC' v Last byte of application program call function v Last byte of PCB status code v Segment name v PCB key feedback area v Address within the buffers of the returned segment v Internal information about HSSR Engine

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 TRXC nnnnnnnnn

Position 1 6

Description Code TRXC to activate the wrap-around core trace of HSSR calls. Enter a number to designate the number of entries allocated for each HSSR PCB for wrap-around tracing. Enter up to 9 digits, left-justified and followed by a blank. If this position is left blank, the default value of 10 is used.

140

Users Guide

Chapter 9. Reports and output from HSSR Engine

HSSR Engine can produce four output data sets: v HSSRSTATcontains printed statistical reports v HSSRTRACcontains printed trace reports v HSSRSNAPprovides a snapshot of control blocks when there is an initialization error v HSSRLOUTcontains, for each database record, a record that can be used for tuning database v HSSRBUTRprovides buffer handler trace data for input to FABHBSIM Topics: v v v v v HSSRSTAT data set HSSRTRAC data set on page 151 HSSRSNAP data set on page 165 HSSRLOUT data set on page 166 HSSRBUTR data set on page 166

HSSRSTAT data set

This section explains the HSSRSTAT data set.

Function
This data set may contain the following printed reports: v HSSROPT Control Statements report v HALDB Partition Definition report v HALDB Partitions Accessed report v DB Call Statistics report v DB Statistics report v Randomizing Statistics report v DB Record Length Distribution report v Data Set I/O Statistics report v CAB Statistics report

Format
This data set contains 133-byte fixed-length records. When the block size is coded in the JCL, it must be a multiple of 133.

HSSROPT Control Statements report

This report contains the parameters used by HSSR Engine for this job execution (see Figure 20 on page 142).

Copyright IBM Corp. 2000, 2007

141

IMS HIGH PERFORMANCE UNLOAD 5655-E06 HSSROPT CONTROL STATEMENTS FOLLOWS:

"HSSROPT CONTROL STATEMENTS" DATE: 10/26/2007 TIME: 10.14.01

PAGE: 1 FABH015A - V1.R2

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 HSSRDBD DBDNAME1,DBX HSSRDBD DBDNAME2,DBDNAME3 DBSTATS RTEXIT FABHRRRR X DIAGG AAA SKERROR 500 NOFIX NOTE: X ON THE LEFT SIDE OF A CONTROL STATEMENT INDICATES THAT THE STATEMENT HAS AN ERROR AND IS IGNORED. HSSR-ENGINE PARAMETERS USED FOR THIS EXECUTION: KEYWORD ---------------APISET CABSTAT DBSTATS DIAGG GOTRETRY HSSRDBD LSR NOFIX PCBLIST RTEXIT SKERROR SKIPVLC DATXEXIT VALUES ------------------------------------------------------------------------------------------1 NO 4 DIAGONLY NBR=4,WAIT=5 DBDNAME1,DBDX ,DBDNAME2,DBDNAME3 NO HSSR FABHRRRR 500 NO NO

* * * * * *

NOTE: '*' INDICATES THAT THE PARAMETER IS SPECIFIED IN THE HSSROPT.

Figure 20. HSSROPT Control Statements report

HALDB Partition Definition report

If 'PARTINFO DEF' is specified in the HSSROPT data set, the report shown in Figure 21 is produced.

IMS HIGH PERFORMANCE UNLOAD 5655-E06 *** DBDNAME: PARTDB *** PHDAM VSAM 5 (N/A)

"HALDB PARTITION DEFINITION" DATE: 10/26/2007 TIME: 12.34.56

PAGE: 1 FABHP00 - V1.R2

DATABASE ORGANIZATION............ ACCESS METHOD.................... NUMBER OF PARTITIONS DEFINED..... PARTITION SELECTION EXIT.........

*** PARTITIONS LISTED IN ORDER OF PARTITION HIGH KEY *** SEQ 0001 0002 0003 0004 0005 NAME PART1 PART2 PART3 PART4 PART5 ID 1 2 3 4 5 HIGH KEY C19999999 C29999999 C39999999 C49999999 C59999999

Figure 21. HALDB Partition Definition report

142

Users Guide

HALDB Partitions Accessed report

If 'PARTINFO ACC' is specified in the HSSROPT data set, the report shown in Figure 22 is produced

IMS HIGH PERFORMANCE UNLOAD 5655-E06 *** DATABASE REFERENCED BY THE PCB #0001 *** DBDNAME........................... PARTDB NUMBER OF PARTITIONS DEFINED...... 5 NUMBER OF PARTITIONS PROCESSED.... 3 *** LIST OF PARTITIONS ACCESSED *** PART1 , PART2 , PART3

"HALDB PARTITIONS ACCESSED" DATE: 10/26/2007 TIME: 12.34.56

PAGE: 1 FABHP00 - V1.R2

Figure 22. HALDB Partitions Accessed report

DB Call Statistics report

This printed report provides statistics on the number of HSSR calls. The report contains the following information (see Figure 23 on page 144): JOBNAME Name of job. STEPNAME Name of the step for which DB Call Statistics are logged. If you use a cataloged procedure (that is, FABHDBB, FABHDLI, or FABHULU), this STEPNAME is shown as G.xxxxxxxx (where xxxxxxxx is the name specified for your EXEC statement). In Figure 23 on page 144, the cataloged procedure is used, and the name of EXEC statement is HSUNLD1. PGMNAME Name of application program. PSBNAME Name of PSB containing the PCBs that are used. DBDNAME Dbdname of the database referred to by the HSSR PCB. SEGNAME All segment names that are accessed. CALL WITH BLANK/GX STATUS CODES Number of HSSR GN or GHN, GU or GHU, and REPL calls for each segment type. Note: GNP and GHNP calls are listed under "GN/GHN." OTHER STATUS CODES Number of GB, GE, GG, VX, NI, and NE status codes returned for each segment type. NI and NE status codes together are listed under "NI/NE". PCB TOTALS Total number of calls and status codes for a single PCB. TOTAL HSSR CALLS Total number of calls and status codes. The following fields are reported only when the status code FM is received.
Chapter 9. Reports and output from HSSR Engine

143

STATUS:FM Number of FM status codes for a single PCB. TOTAL STATUS:FM Total number of FM status codes. The following fields are reported only when the status code GP is received: STATUS:GP Number of GP status codes for a single PCB. TOTAL STATUS:GP Total number of GP status codes.

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"DB CALL STATISTICS" DATE: 10/26/2007 TIME: 16.40.07

PAGE: 1 FABH070 - V1.R2

JOBNAME=OEFH2005 STEPNAME=G .HPUL PGMNAME=FABHURG1 PSBNAME=PHDV0100 ----------------------------------------------------------------------------------------------------------------------------------DBDNAME SEGNAME CALLS WITH BLANK/GX STATUS CODES OTHER STATUS CODES ----------------------------------------- --------------------------------------------------------------------GN/GHN GU/GHU REPL GB GE GG VX NI/NE PHDV0100 ROOTLEV1 DEP1LEV2 DEP2LEV2 DEP3LEV3 DEP4LEV4 DEP5LEV2 DEP6LEV3 DEP7LEV4 DEP8LEV4 DEP9LEV5 PCB-TOTALS TOTAL HSSR CALLS 10 10 10 20 40 10 20 40 40 80 280 1 --------------------------------------------------------------------------------------------------------------280 1 ===============================================================================================================

Figure 23. DB Call Statistics report

If 'CALLSTAT PART' is specified in the HSSROPT data set, the partition-wide DB Call Statistics report that is shown in Figure 24 on page 145 is printed for each HALDB partition that is processed, and from which at least one segment was retrieved. This is in addition to the database-wide DB Call Statistics report. The PARTITION=xxxxxxx shows the partition name.

144

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"DB CALL STATISTICS" DATE: 10/26/2007 TIME: 16.40.07

PAGE: 1 FABH070 - V1.R2

JOBNAME=OEFH2005 STEPNAME=G .HPUL PGMNAME=FABHURG1 PSBNAME=PHDV0100 PARTITION=PHDV01A ----------------------------------------------------------------------------------------------------------------------------------DDNAME SEGNAME CALLS WITH BLANK/GX STATUS CODES OTHER STATUS CODES ----------------------------------------- --------------------------------------------------------------------GN/GHN GU/GHU REPL GB GE GG VX NI/NE PHDV01AA ROOTLEV1 DEP1LEV2 DEP2LEV2 DEP3LEV3 DEP4LEV4 DEP5LEV2 DEP6LEV3 DEP7LEV4 DEP8LEV4 DEP9LEV5 PART-TOTALS 2 2 2 4 8 2 4 8 8 16 56 ---------------------------------------------------------------------------------------------------------------

Figure 24. DB Call Statistics report for HALDB

DB Statistics report
For a complete description, see Chapter 10, Using Database Tuning Statistics, on page 167.

Randomizing Statistics report

For a complete description, see Chapter 10, Using Database Tuning Statistics, on page 167.

DB Record Length Distribution report

For a complete description, see Chapter 10, Using Database Tuning Statistics, on page 167.

Data Set I/O Statistics report

This report contains statistics on I/O and buffer handler activities (see Figure 25 on page 146): JOBNAME Name of the job. STEPNAME Name of the step for which Data Set I/O Statistics are logged. If you use a cataloged procedure (that is, FABHDBB, FABHDLI, or FABHULU), this STEPNAME is shown as G.xxxxxxxx (where xxxxxxxx is the name specified for your EXEC statement). In Figure 25 on page 146, the cataloged procedure is used, and the name of the EXEC statement is URG1HD. PGMNAME Name of application program. PSBNAME Name of PSB containing the PCBs that are used. For each PCB data set combination the following information is printed: DDNAME ddname as coded on the DD1=keyword in the DBD that is referred to by the HSSR PCB.
Chapter 9. Reports and output from HSSR Engine

145

SIZE OF A BUF Buffer size. NUM OF BUFFERS Total number of buffers. IO DIRECT Number of issued direct I/O requests. IO SEQU Number of chained sequential I/O requests. RBA REQUESTS Number of buffer handler requests. PCT IO/REQ Percentage of issued I/O operations per buffer handler request. PCT IO/BLK Percentage of issued I/O operations per number of blocks or CIs contained in the data set. The TOTAL line appears once on the report: TOTAL This line contains totals of the above fields. TOTAL NUMBER OF BYTES IN BUFFER POOL The total number of bytes of the storage allocated for the buffer pool. Note: If one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, each count number is 0 for each data set of the partitions.

IMS HIGH PERFORMANCE UNLOAD 5655-E06 JOBNAME=THFH0601 DDNAME -------PHDV03AA OVFLW PHDV03AB PHDV03AC PHDV03BA OVFLW PHDV03BB PHDV03BC PHDV03CA OVFLW PHDV03CB PHDV03CC PHDV03DA OVFLW PHDV03DB PHDV03DC PHDV03EA OVFLW PHDV03EB PHDV03EC -------TOTAL STEPNAME=G .URG1HD

"DATA SET I/O STATISTICS" DATE: 10/26/2007 TIME: 16.16.15 PGMNAME=FABHURG1 PSBNAME=PHDV030H

PAGE: 1 FABH070 - V1.R2

SIZE OF NUM OF IO IO RBA PCT PCT A BUF BUFFERS DIRECT SEQU REQUESTS IO/REQ IO/BLK ------- ---------- ---------- ---------- ---------- ------- ------512 143 0 8 106 7.54 5.44 512 143 0 1 9 11.11 .68 4,096 66 0 1 5 20.00 8.33 2,048 66 0 2 10 20.00 9.52 512 143 0 8 102 7.84 5.44 512 143 0 1 7 14.28 .68 4,096 66 0 1 4 25.00 8.33 2,048 66 0 2 9 22.22 9.52 512 143 0 8 107 7.47 5.44 512 143 0 1 9 11.11 .68 4,096 66 0 1 4 25.00 8.33 2,048 66 0 2 9 22.22 9.52 512 143 0 8 103 7.76 5.44 512 143 0 1 7 14.28 .68 4,096 66 0 1 3 33.33 8.33 2,048 66 0 2 9 22.22 9.52 512 143 0 8 111 7.20 5.44 512 143 0 2 18 11.11 1.36 4,096 66 0 1 12 8.33 8.33 2,048 66 0 3 25 12.00 14.28 ------- ---------- ---------- ---------- ---------- ------- ------0 62 669 9.26 551,936

TOTAL NUMBER OF BYTES IN BUFFER POOL:

Figure 25. Data Set I/O Statistics report

146

Users Guide

CAB Statistics report

This report contains detailed CAB information for the data set referred to by each PCB (see Figure 27 on page 151). The following statistics are produced for each PCB for which CAB is used: v HALDB buffering statistics (only for HALDBs) v CAB environment (statistics) v I/O summary (statistics) v Timing Statistics If the 'CABSTAT YES' control statement is specified in the HSSROPT input data set, the following statistics are also produced: v Event statistics v Distribution of look-aside at nth position v Distribution of HRAN steal/delete per reference count value v Distribution of reference-count-difference v Distribution of distance from current Seq HRAN These statistics contain detailed technical information beyond what is usually required for CAB users. To use them, you need to have a good knowledge of CAB logic. For a database of multiple data set groups, these statistics, except the HALDB buffering statistics, are produced for each data set. For a HALDB, the statistics are produced for each partition that has been processed; also, if the database consists of multiple data set groups, the statistics are produced for each data set group for each partition. For a HDAM or PHDAM database, the statistics are produced for the root addressable area and for the overflow area. The DDNAME or the pair of partition name and DSGROUP name is printed on each page of the report. For a nonpartitioned database, the ddname as coded on the DD1= keyword in the DBD that is referred to by the HSSR PCB is printed. For a HALDB, the partition name and the character that identifies the data set group are printed. HALDB Buffering Statistics Figure 26 on page 148 shows a sample of HALDB buffering statistics report. These statistics are produced only for HALDB. The CAB parameters used for each data set are reported. The total storage size for CAB buffers for each data set group is also reported. Column 'A' of the table, titled 'CAB PARAMETERS FOR EACH PARTITION,' indicates whether the data set was accessed ('Y') or not ('N').

Chapter 9. Reports and output from HSSR Engine

147

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"CAB STATISTICS" DATE: 10/26/2007 TIME: 22.15.13 HALDB BUFFERING STATISTICS

PAGE: 1 FABHAP0 - V1.R2

DB=PHDV0300 PCB#= 1 ----------------------------------------------------------------------------------------------------------------------------------*** CAB PARTITION PROCESSING INTENT PARTPROC PHDV0300 S *** BUFFERING SUMMARY THE NUMBER OF PARTITIONS DEFINED.............. THE NUMBER OF PARTITIONS ACCESSED............. MAX NUMBER OF PARTITIONS ACCESSED AT A TIME... DSGROUP=A CAB PARAMETERS FOR THIS DSGROUP OVERFLOW CAB CAB PARAMETERS FOR EACH PARTITION (RAA) PARTITION A CI SIZE CIS/CA RANSIZE NBRSRAN NBRDBUF REFT4 INTER --------- - --------- --------- ------- ------- ------- ----- ----PHDV03A Y 512 49 13 8 26 13 NO PHDV03B Y 512 49 13 8 26 13 NO PHDV03C Y 512 49 13 8 26 13 NO PHDV03D Y 512 49 13 8 26 13 NO PHDV03E Y 512 49 13 8 26 13 NO THE SIZE OF CAB BUFFER FOR THIS DSGROUP (RAA) NUMBER OF BYTES IN SEQUENTIAL BUFFER... NUMBER OF BYTES IN DIRECT BUFFER....... 66,560 13,312 5 5 1

CAB PARAMETERS FOR EACH PARTITION (OVERFLOW) PARTITION A CI SIZE CIS/CA RANSIZE NBRSRAN NBRDBUF REFT4 INTER --------- - --------- --------- ------- ------- ------- ----- ----PHDV03A Y 512 49 13 8 26 13 NO PHDV03B Y 512 49 13 8 26 13 NO PHDV03C Y 512 49 13 8 26 13 NO PHDV03D Y 512 49 13 8 26 13 NO PHDV03E Y 512 49 13 8 26 13 NO THE SIZE OF CAB BUFFER FOR THIS DSGROUP (OVERFLOW) NUMBER OF BYTES IN SEQUENTIAL BUFFER... 66,560 NUMBER OF BYTES IN DIRECT BUFFER....... 13,312

Figure 26. HALDB Buffering Statistics report for PHDAM

CAB ENVIRONMENT Description of the environment and CAB parameter values specified in the HSSRCABP data set. I/O SUMMARY Summarization of CAB I/O. NBR OF BLOCKS WITHIN DATASET Number of OSAM blocks or ESDS CIs in the data set. This value is calculated by (high-used RBA)/(CI size). NBR OF CALLS TO BUFFER HANDLER Number of buffer handler requests. If basic buffering is used for the overflow area specified by the OVERFLOW control statement, the number of calls to the buffer handler for the overflow area is not included in this value. Buffer handler is called when the requested RBA is not in the current buffer.

148

Users Guide

LOOKASIDE TOTAL Number of buffer handler requests satisfied through look-aside buffering. INTRA-PCB: SEQ BUF The number of requested RBAs found in the sequence buffer of the intra-PCB (my PCB). INTRA-PCB: DIRECT BUF The number of requested RBAs found in the direct buffer of the intra-PCB (my PCB). INTER-PCB: The number of requested RBAs found in the buffers of the inter-PCB (PCB other than my PCB). The buffers for the inter-PCB are referred to only when the requested RBA was not found in the intra-PCB. NBR OF I/O Summary of number of I/O requests. For VSAM ESDS, one GET macro is used by one I/O request. For OSAM, the READ macro is used and the number of READ macros is: v 1 when direct I/O v The value of RANSIZE when chained sequential I/O TOTAL Total number of I/O requests. SEQUENTIAL TOTAL Total number of chained sequential I/O requests. SEQU IMMEDIATE Number of immediate chained sequential I/O requests. This I/O request is made when the requested RBA is higher than the highest RBA in the current sequential buffer and the requested RBA is not found in both of the sequential buffers and the direct buffers. SEQU OVERLAPPED Number of overlapped chained sequential I/O requests. This I/O request is made when the requested RBA is found in the sequential buffers and the next block or CI is not yet read in the next sequential buffer. DIRECT Number of immediate direct I/O requests. This I/O request is made when: v The requested RBA is less than the highest RBA in the current sequential buffer, and is not found in both of the sequential buffers and the direct buffers. v Chained sequential I/O request is made and the sequential buffers cannot be filled with blocks or CIs because the number of blocks or CIs that remain in the data set is less than the RANSIZE value. NBR OF BLOCKS READ Summary of number of blocks or CIs read. TOTAL Total number of blocks or CIs read.

Chapter 9. Reports and output from HSSR Engine

149

SEQUENTIAL TOTAL Total number of blocks or CIs with chained sequential I/O. SEQU IMMEDIATE Number of blocks or CIs with immediate chained sequential I/O. This value is calculated by: (Number OF I/O requests for SEQU IMMEDIATE) multiplied by (RANSIZE) SEQU OVERLAPPED Number of blocks or CIs with overlapped chained sequential I/O. This value is calculated by: (Number of I/O requests for SEQU OVERLAPPED) multiplied by (RANSIZE) DIRECT Number of blocks or CIs with immediate direct I/O. NBR OF UNREFERENCED SEQ BUFFERS Number of blocks or CIs that were deleted from sequential buffers although they were never referred to. With this number, whether the CAB decisions to perform chained sequential I/O is reasonable or not can be measured. TIMING STATISTICS Wait time for immediate chained sequential I/O, overlapped chained sequential I/O, and immediate direct I/O. MEAN WAIT TIME Average wait time for I/O request, reported by type of I/O. TOTAL WAIT TIME Total wait time for I/O request, reported by type of I/O. The rest of the statistics is obtained when the CABSTAT YES control statement is specified in the HSSROPT data set. These statistics contain detailed technical information beyond what is usually required for users of High Performance Unload. The statistics are: Event Statistics Detailed data on CAB I/O Distribution of look-aside at n th Position Detailed data on look-aside buffering Distribution of HRAN Steal/Delete per Reference Count Value Detailed data on CAB I/O in ranges Distribution of Reference-Count-Difference Detailed data on reference threshold parameters Distribution of Distance from Current Seq HRAN Detailed statistics on HRAN distribution. Figure 27 on page 151 shows a sample of CAB staticstics report for a non-partitioned database.

150

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"CAB STATISTICS" DATE: 10/26/2007 TIME: 12.14.27

PAGE: 1 FABHA90 - V1.R2

DDNAME=HSHDP ------------------------------------------------------------------------------------------------------------------------------------

*** CAB ENVIRONMENT OPERATING SYSTEM ACCESS METHOD BUFFER FIXING RANSIZE NBRSRAN NBRDRAN NBRDBUF OVERLAP REFT1 REFT2 REFT3 REFT4 NBHSIZE INTER ANYNEXT

z/OS 01.07.00 HBB7720 BSAM YES 2 4 4 3 YES 0 0 0 3 3 NO NO

*** I/O SUMMARY: NBR OF BLOCKS WITHIN DATASET... NBR OF CALLS TO BUFFERHANDLER.. LOOKASIDE TOTAL................ INTRA-PCB: SEQ BUF.......... INTRA-PCB: DIRECT BUF....... INTER-PCB................... NBR OF I/O TOTAL...................... SEQUENTIAL TOTAL........... SEQU IMMEDIATE.......... SEQU OVERLAPPED......... DIRECT..................... NBR OF BLOCKS READ TOTAL...................... SEQUENTIAL TOTAL........... SEQU IMMEDIATE.......... SEQU OVERLAPPED......... DIRECT..................... *** NBR OF UNREFERENCED SEQ BUFFERS *** TIMING STATISTICS IMMEDIATE SEQ I/O.......... OVERLAPPED SEQ I/O......... IMMEDIATE DIRECT I/O....... *TOTAL.....................

2,441 4,165 1,240 1,199 41 0 3,200 982 707 275 2,218 4,182 1,964 1,414 550 2,218 490

100.00 PCT OF CALLS 29.77 28.78 .98 0 76.83 23.57 16.97 6.60 53.25 100.40 47.15 33.94 13.20 53.25 PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT OF OF OF OF OF OF OF OF OF OF OF OF OF OF CALLS CALLS CALLS CALLS CALLS CALLS CALLS CALLS CALLS CALLS CALLS CALLS CALLS CALLS

170.62 PCT OF BLOCKS 50.79 49.11 1.67 0 131.09 40.22 28.96 11.26 90.86 171.32 80.45 57.92 22.53 90.86 PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT PCT OF OF OF OF OF OF OF OF OF OF OF OF OF OF BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS BLOCKS

24.94 PCT SEQ BUFFERS TOTAL WAIT TIME (SECONDS) 17 1 45 64

MEAN WAIT TIME (MILLIS) 24 6 20

Figure 27. CAB Statistics report for a nonpartitioned database

HSSRTRAC data set

This section explains the HSSRTRAC data set.

Function
The HSSROPT control statements, TRHC, TRDB, and DIAGG, cause trace information to be produced in the Trace Output report. Note: The trace data of control blocks of HSSR Engine, which is produced by specifying CB or BUFCB option for TRHC control statement, is not intended to be reviewed by users, but might be needed by IBM Support Center to analyze a problem.
Chapter 9. Reports and output from HSSR Engine

151

Format
This data set contains 133-byte fixed-length records. When the block size is coded in the JCL, it must be a multiple of 133.

Trace Output report

This hard-copy trace shows trace call data, control blocks data, buffer handler data, and CAB data. The samples of this report are shown in Figure 28 on page 154 and Figure 29 on page 154. The content of this report depends on the trace options chosen by the user. If the CALL option is specified for the TRHC control statement, the report contains a section that describes the following fields and data areas for database calls: FUNC The type of call requested for HSSR Engine. DBD The dbdname of the database referred to by the HSSR PCB. LEV Segment level. STAT Status code returned in the PCB. PROC Processing option coded in the PROCOPT field of the DBD. SEGN The name of the segment that is accessed. PCB The PCB number. The number for the first PCB is 0001. PARTITION Partition name (only for HALDB). KEYFEEDB Data returned in the key feedback area. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format. IO-AREA Data returned in the I/O area. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing 32 bytes of data in hexadecimal and EBCDIC format. SSA or SSA-n May show the Segment Search Argument. This gives the virtual storage address of the SSA traced on the right. There may be multiple lines, each showing 32 bytes of the SSA in hexadecimal and EBCDIC format. If APISET 1 or 2 is specified, the trace log shows the field name 'SSA'. If APISET 3 is specified, the trace log shows up to of 15 SSA fields, showing their names as 'SSA-1', 'SSA-2', 'SSA-3', etc. SEG-PREF Shows the prefix of the returned segment. Gives the virtual storage address of the segment prefix traced on the right. There may be multiple lines, each showing 32 bytes of the prefix in hexadecimal and EBCDIC format.

152

Users Guide

If NPF option is specified for the TRHC control statement, the SEG-PREF information is not printed. Notes: 1. If a Data Conversion exit routine (DFSDBUX1) is used for the segment accessed, the data shown in the KEYFEEDB, IO-AREA, and SSA fields is presented in the application form, not in the stored form 2. If a user application that is run by APISET 1 or 2 issues a DL/I call that is not supported by the HSSR call handler, the call data is printed in this report even if the TRHC and the TRDB control statements are not specified. Ignore LEV, STAT, SEGN and IO-AREA fields in the data. Diagnosis, Modification, or Tuning Information If the BUF option is specified for the TRHC control statement, the report contains a section of information that describes the following control blocks and areas showing buffer handler trace data: DBDNAME Name of the DBD referred to by the HSSR PCB. DSG Data set group number. PARTITION Partition name (only for HALDB). CALL-TYPE Type of buffer handler call. RC Return code returned by the buffer handler. HDMB Snap dump of "Communication area" of HDMB control block of HSSR Engine. DATA Data returned by buffer handler. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format. This data can be: v A KSDS record v An OSAM block v An ESDS control interval If the BUFCB option is specified for the TRHC control statement, and CAB buffering is used, the trace of the following control blocks of HSSR buffer handler is also printed: HDMB HDMC SEQ HRAN DIR HRAN If CB option is specified for the TRHC control statement, the traces of the following control blocks immediately before completion of an HSSR call are printed: HJCB HDMB HSDBS HPTRS

Chapter 9. Reports and output from HSSR Engine

153

End of Diagnosis, Modification, or Tuning Information

IMS HIGH PERFORMANCE UNLOAD 5655-E06 *** DB CALL *** FUNC=GN KEYFEEDB 000E5C84 IO-AREA 000E9968 000E9988 000E99A8 000E99C8 SSA-1 000E9D59 DBD=DBHD0070 LEV=01 STAT=

"TRACE OUTPUT" DATE: 10/26/2007 TIME: 12.34.16 PROC=GX SEGN=SG001LV1 PCB#=0001 *0100000001 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 *0100000001 * * * *SG001LV1 9804 * 8

PAGE: 1 FABH310 - V1.R2

F0F1F0F0 F0F0F0F0 F0F1 F0F1F0F0 F0F0F0F0 F0F14040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 E2C7F0F0 F1D3E5F1 40 01000000 0B1E0000 088E0000 08F80001

* * * * * * *

SEG-PREF 0734C818

Figure 28. Sample of Trace Output report when 1 SSA is specified

IMS HIGH PERFORMANCE UNLOAD 5655-E06 *** DB CALL *** FUNC=GN KEYFEEDB 000E5C84 000E5CA4 000E5CC4 000E5CE4 000E5D04 IO-AREA 000E9968 000E9988 000E99A8 000E99C8 SSA-1 SSA-2 SSA-3 SSA-4 SSA-5 SSA-6 SSA-7 SSA-8 SSA-9 SSA-10 SSA-11 SSA-12 SSA-13 SSA-14 SSA-15 000E9D59 000E9D62 000E9D6B 000E9D74 000E9D7D 000E9D86 000E9D8F 000E9D98 000E9DA1 000E9DAA 000E9DB3 000E9DBC 000E9DC5 000E9DCE 000E9DD7 DBD=DBHD0070 LEV=15 STAT= F0F0F0F0 F0F0F0F1 F0F1F0F1 F0F1F0F1 F0F4F0F0 F0F1F0F1 F0F1F0F5 F0F8F0F0 F0F0F0F0 F0F0F0F1

"TRACE OUTPUT" DATE: 10/26/2007 TIME: 12.33.27 PROC=GX SEGN=SG016LVF PCB#=0001 F0F1F0F3 F0F6F0F0 F0F0F0F0 F0F0F0F1 F0F1 F0F0F0F0 F0F0F0F1 F0F1F0F1 F0F1F0F3 F0F1F0F1 F0F1F0F7 F0F0F0F0 F0F0F0F0

PAGE: 1 FABH310 - V1.R2

F0F1F0F0 F0F4F0F0 F0F0F0F0 F0F0F0F1 F0F1F0F1

F0F2F0F0 F0F0F0F0 F0F0F0F1 F0F1F0F1 F0F1F0F5

F0F0F0F1 F0F1F0F1 F0F1F0F9 F0F2F0F0 F0F0F0F0

*01000000010102000001010300000101* *04000001010500000101060000010107* *00000101080000010109000001010000* *00010101000001010200000101030000* *0101040000010105000001 * *0105000001 * * * *SG001LV1 *SG003LV2 *SG004LV3 *SG005LV4 *SG006LV5 *SG007LV6 *SG008LV7 *SG009LV8 *SG010LV9 *SG011LVA *SG012LVB *SG013LVC *SG014LVD *SG015LVE *SG016LVF * * * * * * * * * * * * * * * * * * * * *

F0F1F0F5 F0F0F0F0 F0F14040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 E2C7F0F0 F1D3E5F1 40 E2C7F0F0 F3D3E5F2 40 E2C7F0F0 F4D3E5F3 40 E2C7F0F0 F5D3E5F4 40 E2C7F0F0 F6D3E5F5 40 E2C7F0F0 F7D3E5F6 40 E2C7F0F0 F8D3E5F7 40 E2C7F0F0 F9D3E5F8 40 E2C7F0F1 F0D3E5F9 40 E2C7F0F1 F1D3E5C1 40 E2C7F0F1 F2D3E5C2 40 E2C7F0F1 F3D3E5C3 40 E2C7F0F1 F4D3E5C4 40 E2C7F0F1 F5D3E5C5 40 E2C7F0F1 F6D3E5C6 40 10000000 0000

40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040

SEG-PREF 071D0374

Figure 29. Sample of Trace Output report when 15 SSAs and APISET 3 are specified

154

Users Guide

Trace Output report with diagnostics

The following diagnostic information appears on the report whenever you use the DIAGG option in conjunction with the SKERROR option when unloading a corrupted database and a GG or a GX status code is returned. See Figure 30 on page 160. The diagnostic information that is printed on the Trace Output Report varies with the database organization and the type of error detected by HSSR Engine. ************ BEGINNING OF GG DIAGNOSIS ************ Eye-catcher identifying the beginning of the DIAGG diagnosis. The line is printed three times. GG STATUS CODE FOR PCB psbname psbname of PSB containing PCB used; if run in the ULU region, this is the dbdname as specified on the EXEC statement. THE NAME OF THE PREVIOUSLY RETRIEVED SEGMENT IS: segname Segment name returned by the previous successful HSSR call. THE SNAP OF ITS CONCATENATED KEY FOLLOWS: Concatenated key of the segment. There may be one or more lines each showing up to 32 bytes of data in hexadecimal and EBCDIC format. The report contains a section that starts with the following line: --------------- TYPE OF GG ERROR ----------------The section contains information describing the type of GG error that was detected. The next line, "CASE nn:", identifies a type of GG error. Pointer or Key Sequence Errors For a pointer error or a key sequence error, the report tells which kind of pointer or key is incorrect and which type of segments may be skipped by the SKERROR option. The following is a description of each error case: CASE 1-A Incorrect segment prefix pointer other than root twin pointer. HSSR Engine handles the incorrect pointer as if it contained zero, and continues processing with the next appropriate pointer. In this case, HSSR Engine skips the retrieval of one or more dependent segments of the current database record. If the incorrect pointer is a physical child first pointer, the following segments are skipped: v Child segment v All twins on the physical twin chain or on the hierarchical chain of the above child v All dependents of the above segments If the incorrect pointer is a physical twin forward pointer, the following segments are skipped: v Twin segment v All further twins on the incorrect physical twin forward chain v All dependents of the above segments If the incorrect pointer is a hierarchical forward pointer, the following segments are skipped:
Chapter 9. Reports and output from HSSR Engine

155

v All further segments on the incorrect hierarchical twin forward chain v All dependents of the above segments CASE 1-B Incorrect HDAM root twin pointer. HSSR Engine handles the incorrect pointer as if it contained zero, and continues processing by skipping to the next HDAM root anchor point (RAP). In this case, HSSR Engine skips the retrieval of the following database segments: v All further roots on the incorrect twin chain (incorrect RAP synonym chain) v All dependents of the above roots CASE 1-C Incorrect HIDAM root twin pointer. HSSR Engine attempts to access the HIDAM root segment via the HIDAM index. If the pointer in the index record is correct, HSSR Engine does not skip the retrieval of any database segments. If the pointer in the index record is also incorrect, HSSR Engine skips to the next record, with the result that one root and all of its dependents are not retrieved. CASE 2 Incorrect HDAM root anchor pointer. HSSR Engine handles the incorrect RAP as if it contained zero, and continues processing by skipping to the next RAP. In this case, HSSR Engine skips the retrieval of: v All roots on the incorrect RAP synonym chain v All dependents of the above roots CASE 3 Incorrect HIDAM root index pointer. HSSR Engine continues processing by accessing the next Index record. In this case, HSSR Engine skips the retrieval of one root segment and all its dependents. CASE 4 Incorrect pointer to split data portion of a segment. HSSR Engine skips the retrieval of the following segments of the current database record: v Segment with the incorrect data pointer v All further segments on the remainder of a hierarchical forward pointer chain, if the segment is on such a chain v All dependents of the above segments CASE 5 KEYCHECK option detected sequence error. HSSR Engine uses the same logic as in case 4. This case includes the sequence error in the sequence key for a virtual logical child when a migration unload is being done. In that case, HSSR Engine skips the retrieval of the following occurrences of the logical child: v The occurrence at which the sequence error is detected

156

Users Guide

v All further occurrences of the logical child on the remainder of a logical child forward pointer chain CASE 9 Incorrect value for segment length field. HSSR Engine skips the retrieval of the following segments of the current database record: v Segment with the incorrect segment length field v All dependents of the above segments CASE 10 HISAM segment code is not 01 at beginning of root record. If error is due to an incorrect pointer used to chain ESDS records of a secondary index database, HSSR Engine resumes its retrieval with the logical next KSDS record; hence the retrieval of one or more database records is skipped. For other errors, HSSR Engine resumes its retrieval with the next root segment, skipping the retrieval of the remaining segments of the current database record. CASE 11 HISAM record has incorrect segment code or delete byte. HSSR Engine uses the same logic as in case 10. CASE 12 HISAM pointer to overflow record points outside of data set. HSSR Engine uses the same logic as in case 10. CASE 13 Key sequence error detected for a segment in an HISAM or secondary index database. HSSR Engine uses the same logic as in case 10. For HDAM and HIDAM databases, the report contains a section of information describing the incorrect pointer: -------------"HD-FROM INFO" FOLLOWS -------------An eye-catcher identifying the beginning of the "HD-FROM" information: RBA OF SEGMENT PREFIX CONTAINING THE BAD POINTER AND LOW+HIGH RBA OF ITS CI: Snap of one area containing three RBAs: v RBA of segment prefix (or RBA of the RAP) that contains the incorrect pointer. v Beginning RBA and ending RBA of the block or CI that contains the incorrect pointer. THE SEGMENT PREFIX CONTAINING THE BAD POINTER Snap of segment prefix that contains the incorrect pointer. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format. THE SEGMENT BUFFER Snap of the block, CI, or index record that contains the incorrect pointer. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format. For HDAM and HIDAM databases, the report contains a section of information describing the portion of the database "pointed to" by the incorrect pointer.
Chapter 9. Reports and output from HSSR Engine

157

-------------- "HD-TO INFO" FOLLOWS -------------An eye-catcher identifying the beginning of the "HD-TO" information: RBA OF POINTER TARGET AND LOW+HIGH RBA OF ITS CI: Snap of one area containing three RBAs: v RBA contained in the incorrect pointer (RBA "pointed to" by the incorrect pointer). v Beginning RBA and ending RBA of the block or CI that is "pointed to." THE TARGET OF THE BAD POINTER FOLLOWS Snap of the first 2 bytes "pointed to" by the incorrect pointer. If the incorrect pointer does not point outside of the data set, this area is snapped. THE TARGET BUFFER Snap of the block or CI "pointed to" by the incorrect pointer. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format. This snap is only provided if the "TO-" block or CI snapped in the "HD-TO" is not the same as the "FROM-" block or CI snapped in the "HD-FROM INFO". Otherwise, the message THE "TO" BUFFER IS THE SAME AS THE "FROM" BUFFER appears in this area. For HISAM and secondary index databases, the report contains data on the last KSDS record accessed by HSSR Engine. ---------- "HS ISAM/KSDS RECORD" FOLLOWS ----------An eye-catcher identifying the beginning of the "HS ISAM/KSDS RECORD." A snap of the last KSDS record accessed by HSSR Engine. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format. For HISAM and secondary index databases, the report contains information about the current ESDS/KSDS record. ------------ "HS CURRENT RECORD" FOLLOWS ----------An eye-catcher identifying the beginning of the "HS CURRENT RECORD." VSAM RBA OF BAD RECORD AND LOW+HIGH RBA.S OF ITS CI FOLLOWS ON SNAPS: Snap of one area containing three ESDS RBAs or three OSAM RRNs. v RBA of the ESDS record v Beginning RBA and ending RBA of the CI that contains the record. SNAP OF BAD SEGMENT CODE/DELETE BYTE AND OF BAD RECORD FOLLOWS: Snap of the first 2 bytes of the segment prefix and of the current ESDS/KSDS record. This gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format. IMS Call Handler or IMS Buffer Handler Errors If APISET 3 is specified, and a call to IMS causes an error, one of the following reports is issued. CASE 15 to CASE 18 are deleted. CASE 19-A The current database position is not valid.

158

Users Guide

This might happen if there is something that updates the database concurrently. The error causes the current position to be reset to the beginning. If status code 'GG' or 'GE' is returned in response to the INTERNAL RBA call, the following: v status code v the SNAP DUMP of SSA specified at the time of RBA call A sample of this report is provided in Figure 31 on page 163. CASE 19-B The current database position is not valid. This might happen if there is a something that updates the database concurrently. If an error occurrs when a DLI buffer handler is called for a DBDS, the following information is written in the report: v DDNAME of DSG v the return code from the buffer handler (PSTRTCDE) v the function code (PSTFNCTN) sent to the buffer handler v the key value (for key request) sent to the buffer handler A sample of this report is provided in Figure 32 on page 164. CASE 20 Staus 'GG' is returned when a call is made from an application to IMS. An error occurred in IMS after a call was made to IMS. The error resets the position of the database to the beginning. HSSR Engine does not generate any error report, because it cannot identify the reason for the error. The PCB information at the call time is reported in the CALL TRACE report that is generated after the DIAGG report. A sample of this report is provided in Figure 33 on page 165. The following line indicates the end of a DIAGG output: *************** END OF GG DIAGNOSIS *************** The line is printed three times. After printing a DIAGG output information, the DIAGG option forces a temporary activation of the hard-copy trace option, TRHC. The TRHC option remains in effect until the next database call is completed. The TRHC option enables you to determine whether the next call has been completed successfully, and to see the next retrieved segment. If the TRHC options is active, the Trace Output report contains the following: v Trace of the HSSR call that ended with a GG or a GX status code. v Trace of the first successful HSSR call after a GG or a GX status code was returned. This contains the name of the returned segment, a snap of the PCB key feedback area, and a snap of the returned segment. v Snaps of the buffer handler calls, if the keyword BUF is specified in the DIAGG statement. v Snaps of the control blocks of HSSR Engine, if the keyword CB is specified in the DIAGG statement.

Chapter 9. Reports and output from HSSR Engine

159

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"TRACE OUTPUT" DATE: 10/26/2007 TIME: 18.57.16

PAGE: 1 FABH310 - V1.R2

********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* GG STATUS CODE FOR PCB HDAM0010 THE NAME OF THE PREVIOUSLY RETRIEVED SEGMENT IS:ORDER THE SNAP OF ITS CONCATENATED KEY FOLLOWS: KEY 0006FB64 F0F0F0F0 F0F0F0F9 F0F0 *0000000900 *

------------------ TYPE OF GG ERROR ------------------------------------------CASE 1-A: CHILD-POINTER POINTS OUTSIDE OF DATASET THE BAD POINTER IS AT THE DECIMAL OFFSET 0006 WITHIN THE PREFIX OF THE SEGMENT=ORDER AND SHOULD POINT TO THE SEGMENT=ORDART

RETRIEVAL OF FOLLOWING SEGMENTS MAY BE SKIPPED: ONE ORDART ,ANY TWIN ON TWIN- OR HIERARCHICAL- CHAIN,

AND ALL OF THEIR DEPENDENTS ------------------ "HD-FROM INFO" FOLLOWS ------------------------------------RBA OF SEGMENT-PREFIX CONTAINING THE BAD POINTER AND LOW+HIGH RBA OF ITS CI: RBAS 0000BEDC 00001C10 00001C00 00001FFF * *

THE SEGMENT-PREFIX CONTAINING THE BAD POINTER PREFIX 071DF810 0100011C 00470FA3 0000 * *

------------------ "HD-TO INFO" FOLLOWS --------------------------------------RBA OF POINTER-TARGET FOLLOWS: RBAS 0000BEDC 0FA30000 * *

THE BAD POINTER POINTS OUTSIDE OF THE DATASET ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** *** DB CALL *** FUNC=GN KEYFEEDB 0006FB64 IO-AREA DBD=HDAM0010 LEV=01 STAT=GG PROC=GX SEGN=ORDER *0000000900 *

F0F0F0F0 F0F0F0F9 F0F0

Figure 30. Trace Output report with diagnostics (CASE 1-A, CASE 1-B, and CASE 2) (Part 1 of 3)

160

Users Guide

********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* GG STATUS CODE FOR PCB HDAM0010 PREVIOUS CALL WAS NOT SUCCESSFUL (OR NO PREVIOUS CALL) ------------------ TYPE OF GG ERROR ------------------------------------------CASE 1-B: TWIN-POINTER POINTS OUTSIDE OF DATASET THE BAD POINTER IS AT THE DECIMAL OFFSET 0002 WITHIN THE PREFIX OF THE SEGMENT=ORDER AND SHOULD POINT TO THE SEGMENT=ORDER

RETRIEVAL OF FOLLOWING SEGMENTS MAY BE SKIPPED: ONE ROOT, ANY OTHER ROOT ON SAME RAP CHAIN, AND ALL OF THEIR DEPENDENTS ------------------ "HD-FROM INFO" FOLLOWS ------------------------------------RBA OF SEGMENT-PREFIX CONTAINING THE BAD POINTER AND LOW+HIGH RBA OF ITS CI: RBAS 0000BEDC 00001C10 00001C00 00001FFF * * * *

THE SEGMENT-PREFIX CONTAINING THE BAD POINTER PREFIX 071DF810 0100011C 00470FA3 0000 ------------------ "HD-TO INFO" FOLLOWS --------------------------------------RBA OF POINTER-TARGET FOLLOWS: RBAS 0000BEDC 011C0047

THE BAD POINTER POINTS OUTSIDE OF THE DATASET ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** *** DB CALL *** FUNC=GN KEYFEEDB 0006FB64 IO-AREA *** DB CALL *** FUNC=GN KEYFEEDB 0006FB64 IO-AREA 00105EFF 00105F1F 00105F3F 00105F5F 00105F7F 00105F9F 00105FBF 00105FDF SEG-PREF 07267978 DBD=HDAM0010 LEV=01 STAT= PROC=GX SEGN=ORDER *0000001600 C4C5D940 F3F14040 40404040 40404040 40404040 40404040 40404040 40404040 C4C5E2C3 40404040 40404040 40404040 40404040 40404040 40404040 40404040 D9C9D7E3 40404040 40404040 40404040 40404040 40404040 40404040 40404040 C9D6D540 40404040 40404040 40404040 40404040 40404040 40404040 4040 D7D7D7D7 40404040 40404040 40404040 40404040 40404040 40404040 * DBD=HDAM0010 LEV=01 STAT=GG PROC=GX SEGN=ORDER *0000000900 *

F0F0F0F0 F0F0F0F9 F0F0

F0F0F0F0 F0F0F1F6 F0F0 F0F0F0F0 D7D7D7D7 40404040 40404040 40404040 40404040 40404040 40404040 F0F0F1F6 D7D7D740 40404040 40404040 40404040 40404040 40404040 40404040 F0F0D6D9 F9F6F1F2 40404040 40404040 40404040 40404040 40404040 40404040

*0000001600ORDER DESCRIPTION PPPP* *PPPPPPP 961231 * * * * * * * * * * * * * * *

01000000 00000000 2E7C

Figure 30. Trace Output report with diagnostics (CASE 1-A, CASE 1-B, and CASE 2) (Part 2 of 3)

Chapter 9. Reports and output from HSSR Engine

161

********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* GG STATUS CODE FOR PCB HDAM0010 THE NAME OF THE PREVIOUSLY RETRIEVED SEGMENT IS: ORDART THE SNAP OF ITS CONCATENATED KEY FOLLOWS: KEY 0006FB64 F0F0F0F0 F0F0F1F8 F0F0E3F0 F1F8F0F2 40F0 *0000001800T01802 0 *

------------------ TYPE OF GG ERROR ------------------------------------------CASE 2: HDAM ROOT-ANCHOR-POINT DOES NOT POINT TO ROOT RETRIEVAL OF FOLLOWING SEGMENTS MAY BE SKIPPED: ONE ROOT, ANY OTHER ROOT ON SAME RAP CHAIN, AND ALL OF THEIR DEPENDENTS ------------------ "HD-FROM INFO" FOLLOWS ------------------------------------RBA OF RAP CONTAINING THE BAD POINTER AND LOW+HIGH RBA OF ITS CI: RBAS 0000BEDC 00002008 00002000 000023FF * *

THE BAD RAP RAP 071E0008 00002010 * *

------------------ "HD-TO INFO" FOLLOWS --------------------------------------RBA OF POINTER-TARGET AND LOW+HIGH RBA OF ITS CI: RBAS 0000BEDC 00002010 00002000 000023FF * *

THE TARGET OF THE BAD POINTER FOLLOWS TARGET 071E0010 0200 * *

THE "TO" BUFFER IS THE SAME AS THE "FROM" BUFFER ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** *** DB CALL *** FUNC=GN KEYFEEDB 0006FB64 IO-AREA *** DB CALL *** FUNC=GN KEYFEEDB 0006FB64 IO-AREA 001063B9 001063D9 001063F9 00106419 00106439 00106459 00106479 00106499 SEG-PREF 071DF184 DBD=HDAM0010 LEV=01 STAT= PROC=GX SEGN=ORDER *0000000800 C4C5D940 F3F14040 40404040 40404040 40404040 40404040 40404040 40404040 C4C5E2C3 40404040 40404040 40404040 40404040 40404040 40404040 40404040 D9C9D7E3 40404040 40404040 40404040 40404040 40404040 40404040 40404040 C9D6D540 40404040 40404040 40404040 40404040 40404040 40404040 4040 C8C8C8C8 40404040 40404040 40404040 40404040 40404040 40404040 * DBD=HDAM0010 LEV=02 STAT=GG PROC=GX 40F0 SEGN=ORDART *0000001800T01802 0 *

F0F0F0F0 F0F0F1F8 F0F0E3F0 F1F8F0F2

F0F0F0F0 F0F0F0F8 F0F0 F0F0F0F0 C8C8C8C8 40404040 40404040 40404040 40404040 40404040 40404040 F0F0F0F8 C8C8C840 40404040 40404040 40404040 40404040 40404040 40404040 F0F0D6D9 F9F6F1F2 40404040 40404040 40404040 40404040 40404040 40404040

*0000000800ORDER DESCRIPTION HHHH* *HHHHHHH 961231 * * * * * * * * * * * * * * *

01000000 00000000 1688

Figure 30. Trace Output report with diagnostics (CASE 1-A, CASE 1-B, and CASE 2) (Part 3 of 3)

162

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"TRACE OUTPUT" DATE: 10/26/2007 TIME: 12.00.09

PAGE: 1 FABH310 - V1.R2

********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* GG STATUS CODE FOR PCB DBHD0010 THE NAME OF THE PREVIOUSLY RETRIEVED SEGMENT IS:SG001LV1 THE SNAP OF ITS CONCATENATED KEY FOLLOWS: KEY 001131E4 F0F2F0F0 F0F0F0F0 F0F1 *0200000001 *

------------------ TYPE OF GG ERROR ------------------------------------------CASE 19-A: THE DATABASE POSITION IS UNAVAILABLE INFORMATION OF INTERNAL RBA CALL STATUS CODE: GG THE SNAP OF SSA FOLLOWS: SSA-1 0000A238 E2C7F0F0 F1D3E5F1 5CE34D00 0138185D *SG001LV1*T( ) *

************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** *** DB CALL *** FUNC=GN KEYFEEDB IO-AREA SSA-1 SSA-2 07164AEE 07164AF7 E2C7F0F0 F1D3E5F1 40 E2C7F0F0 F4D3E5F2 40 *SG001LV1 *SG004LV2 * * DBD=DBHD0010 LEV=00 STAT=GG PROC=GXOT SEGN=

Figure 31. Trace Output report with diagnostics (CASE 19-A)

Chapter 9. Reports and output from HSSR Engine

163

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"TRACE OUTPUT" DATE: 10/26/2007 TIME: 12.07.42

PAGE: 1 FABH310 - V1.R2

********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* GG STATUS CODE FOR PCB DBHI0010 THE NAME OF THE PREVIOUSLY RETRIEVED SEGMENT IS:SG001LV1 THE SNAP OF ITS CONCATENATED KEY FOLLOWS: KEY 0008B244 F1F0F0F0 F0F0F0F0 F0F1 *1000000001 *

------------------ TYPE OF GG ERROR ------------------------------------------CASE 19-B: THE DATABASE POSITION IS UNAVAILABLE INFORMATION OF DL/I BUFFER HANDLER REQUEST PSTRTCDE: 18; PSTFNCTN: F2; DDNAME: DDHX0010 THE SNAP OF REQUESTED KEY FOLLOWS: KEY 00022569 F1F0F0F0 F0F0F0F0 F0F1 *1000000001 *

************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** *** DB CALL *** FUNC=GN KEYFEEDB IO-AREA SSA-1 SSA-2 07125CAE 07125CB7 E2C7F0F0 F1D3E5F1 40 E2C7F0F0 F4D3E5F2 40 *SG001LV1 *SG004LV2 * * DBD=DBHI0010 LEV=00 STAT=GG PROC=GXOT SEGN=

Figure 32. Trace Output report with diagnostics (CASE 19-B)

164

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"TRACE OUTPUT" DATE: 10/26/2007 TIME: 12.11.14

PAGE: 1 FABH310 - V1.R2

********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* ********************* BEGINNING OF GG DIAGNOSIS ******************************* GG STATUS CODE FOR PCB DBHD0160 THE NAME OF THE PREVIOUSLY RETRIEVED SEGMENT IS:SG005LV3 THE SNAP OF ITS CONCATENATED KEY FOLLOWS: KEY 000721E4 F0F4F0F0 F0F0F0F0 F0F1F0F4 F0F3F0F0 F0F0F0F1 F0F4F0F4 F0F0F0F0 F0F1 *040000000104030000010404000001 *

------------------ TYPE OF GG ERROR ------------------------------------------CASE 20: STATUS CODE=GG RETURNED ON THE INTERNAL DL/I CALL ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** ************************ END OF GG DIAGNOSIS ********************************** *** DB CALL *** FUNC=GN KEYFEEDB IO-AREA SSA-1 SSA-2 SSA-3 071A7848 071A7851 071A785A E2C7F0F0 F1D3E5F1 40 E2C7F0F0 F4D3E5F2 40 E2C7F0F0 F5D3E5F3 40 *SG001LV1 *SG004LV2 *SG005LV3 * * * DBD=DBHD0160 LEV=00 STAT=GG PROC=GXOT SEGN=

Figure 33. Trace Output report with diagnostics (CASE 20)

HSSRSNAP data set

This section explains the HSSRSNAP data set.

Function
This data set provides a snapshot of control blocks of HSSR Engine whenever HSSR Engine detects abnormalities while the control block are being initialized. An error message is written. The initialization ends, and HSSR Engine "falls back" to DL/I. All HSSR PCBs are considered DL/I PCBs, and the application program runs using DL/I action modules instead of HSSR Engine. If the HSSRSNAP DD statement is omitted, HSSR Engine abends instead of falling back to DL/I. If you want HSSR Engine to fall back to DL/I without a snap, code this data set as DUMMY.

Format
This data set contains 133-byte fixed-length records. When coded in the JCL, block size must be a multiple of 133.

HSSR SNAPs
When a snap is taken, the control blocks of HSSR Engine are provided. The snap gives the virtual storage addresses of the data traced on the right. There may be multiple lines, each showing up to 32 bytes of data in hexadecimal and EBCDIC format.
Chapter 9. Reports and output from HSSR Engine

165

HSSRLOUT data set

See Output: HSSRLOUT data set on page 171.

HSSRBUTR data set

This section explains the HSSRBUTR data set.

Function
This data set provides buffer handler trace information generated by an unload utility or application program for the HSSR Buffer Handler Simulation utility, FABHBSIM.

Format
This data set contains variable-length records that are read by FABHBSIM.

166

Users Guide

Chapter 10. Using Database Tuning Statistics

Notes: 1. The description in this chapter for an HDAM database also applies to each partition of a PHDAM database. 2. The description in this chapter for a HIDAM database also applies to each partition of a PHIDAM database. Topics: v v v v v Introduction Activating the DB Tuning Statistics Printing long database records with FABHLDBR on page 171 Tuning a database with the DB Tuning Statistics on page 176 Creating a database extract with FABHEXTR on page 213

Introduction
You can request HSSR Engine to create the optional DB Tuning Statistics report during the sequential processing or unloading of a database. Activation of the DB Tuning Statistics function makes it possible to obtain the following statistics reports: v DB Statistics Report v Randomizing Statistics Report You can use these reports to: v Periodically monitor the need for reorganization of HDAM, HIDAM, and HISAM databases. v Monitor the effectiveness of HDAM randomizing parameters (such as the size of the root addressable area, the number of RAPs, the block/CI size, or the bytes limit). The DB Tuning Statistics function provides the following additional capabilities to aid your database tuning: v Creating the optional DB Record Length Distribution report with your own definition of the database record length ranges. v Creating the HSSRLOUT data set to record the length of each database record. v Using the FABHLDBR utility to print long database records with the HSSRLOUT data set as an input. You can use the FABHEXTR exit routine of the FABHURG1 utility to create a small database extract that can be used to perform database tuning experiments. Creation of a smaller extract database can be useful when the database administrator intends to tune the randomizing parameters of a large HDAM database through an iterative "try-and-see" process.

Activating the DB Tuning Statistics

The DB Tuning Statistics function is activated by the DBSTATS control statement in the HSSROPT data set. The statistics report is created in the HSSRSTAT data set. JCL statements and input control statements for this function are described in the following sections.

Copyright IBM Corp. 2000, 2007

167

JCL for the DB Tuning Statistics

The DB Tuning Statistics function requires standard FABHX034 JCL. The DD statements are described in JCL requirements on page 21. The additional requirements for this function are shown in Table 18:
Table 18. DD statements for DB Tuning Statistics DDNAME HSSROPT HSSRLDEF HSSRSTAT HSSRLOUT Use Input Input Output Output Format LRECL=80 LRECL=80 LRECL=133 Need Required Optional Optional Optional

HSSROPT DD This statement defines the input data set that contains the DBSTATS control statement, which activates the DB Tuning Statistics. The data set also contains the optional LOUT statement, which is used for HSSRLOUT records selection. HSSRLDEF DD This optional statement defines the input data set that contains control statements for requesting the DB Record Length Distribution report with your own database record length ranges. HSSRSTAT DD This optional statement defines the output data set for the statistical output. HSSRLOUT DD This optional statement defines the output sequential data set, in which a small record for each database record is written. Each record of the data set consists of: v Length of the database record (fullword) v The number of database I/Os required to read all database segments of the database record (fullword) v Key of the database root segment Note: The BLKSIZE and LRECL for the HSSRLOUT data set should not be specified on JCL. They are determined dynamically by HSSR Engine on the basis of the key length of the root segment. The LRECL is 8 bytes plus the length of the key of the database root segment.

Input: HSSROPT data set

DB Tuning Statistics uses control statements in the HSSROPT data set as input. This section describes these control statements.

DBSTATS control statement

The DBSTATS control statement activates the DB Tuning Statistics function.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DBSTATS nnnnnnnnn

168

Users Guide

Position 1 9

Description Code the DBSTATS keyword to instruct HSSR Engine to provide the DB Tuning Statistics. Specify the number of buffers to be simulated. Enter any number up to 9 digits, left-justified, and followed by a blank. If this entry is left blank, the default value of 4 is used. HSSR Engine simulates the LRU algorithms of the IMS OSAM buffer pool and the IMS VSAM buffer pool to provide statistics of the number of I/O operations. If the application program uses multiple HSSR PCBs, HSSR Engine assumes that each PCB has its own dedicated buffer pool containing the user-specified or default number of buffers.

LOUT control statement

The LOUT control statement requests that, when the DBSTATS control statement activates the DB Tuning Statistics report, the HSSRLOUT data set should only contain records that satisfy one or both of the following conditions: v Database records that are longer than the specified limit. v Database records that require more than the specified number of database I/Os. This option is ignored if the DBSTATS control statement is not specified at the same time.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 LOUT LENGTH=llllllll LOUT IO=nn

Position 1 6

Description Code the LOUT keyword to request an optional record selection for the HSSRLOUT data set. Code one of the following optional keywords for each LOUT statement: Keyword LENGTH=llllllll Description Requests that the HSSRLOUT data set should contain only the records for database records whose length is greater than llllllll bytes. Requests that the HSSRLOUT data set should contain only the records for database records that require more than nn database I/Os for retrieval.

IO=nn

Notes: 1. You can specify both LENGTH= and IO= parameters, either on a single LOUT control statement or separately (on multiple LOUT statements). If you specify both parameters on a single LOUT statement, separate them with a comma, as follows:
Chapter 10. Using Database Tuning Statistics

169

LOUT LENGTH=100,IO=15

2. If you specify both LENGTH= and IO= parameters, both conditions are ANDed (that is, database records that satisfy both conditions are written in the HSSRLOUT data set.) 3. If an incorrect parameter keyword or an incorrect parameter value is detected on an LOUT statement, the rest of the parameter specification on that statement is ignored. For example, the IO= parameter specification on the following statement is ignored, because the LENGTH= parameter value is incorrect:
LOUT LENGTH=1A,IO=10

Input: HSSRLDEF data set

DB Tuning Statistics provides, by default, a report of the distribution of database record lengths. In this default report, the ranges of database record lengths are denoted as 1/16th, 2/16th, 3/16th, and so on, of the CI/block size. However, these default ranges are not always appropriate for your use. If you want a report with different a unit of measure for describing ranges of database record lengths, you should: 1. Provide an HSSRLDEF DD statement in your JCL. 2. Provide control statements in the HSSRLDEF data set. One control statement should be provided for each range of database record length that should appear in the statistics report. Each control statement contains the highest value of the range. Each value must start in column 1 of the control statement. The values must be provided in ascending sequence. For example, if you wish to have the DB Record Length Distribution report for the ranges 050 bytes, 51100 bytes, 101200 bytes, 201300 bytes, 3011000 bytes, and 100110000 bytes, the following control statements are required:
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 //HSSRLDEF DD * 50 100 200 300 1000 10000

Output: HSSRSTAT data set

The DB Tuning Statistics function writes the following statistical reports into the HSSRSTAT data set: v DB Statistics report v Randomizing Statistics report v DB Record Length Distribution report (optional) For a complete description for the reports, see Tuning a database with the DB Tuning Statistics on page 176.

170

Users Guide

Output: HSSRLOUT data set

The HSSRLOUT data set is a sequential data set in which a small record for each database record is written. Each record consists of: v Length of the database record (fullword) v The number of database I/Os required to read all database segments of the database record (fullword) v Key of the database root segment The HSSRLOUT data set can be: v Printed as is (for example, with a PRINT command of IDCAMS). v Printed (for example, with the PRINT command of IDCAMS) after a sort. The records are sorted in descending sequence of the first 4 bytes of each record. This generates a list of records ordered in decreasing sequence of their database record lengths. v Processed by the FABHLDBR utility (to obtain a printed output of only the longest database records or database records that require the largest number of database I/Os). See Printing long database records with FABHLDBR on page 171 for details. As an option, you can request that the HSSRLOUT data set only contain a record for: v Database records that are longer than the specified limit v Database records that require more than the specified number of database I/Os You can achieve this by providing the LOUT control statement in the HSSROPT data set. See LOUT control statement on page 169 for details. Note: Since the records of the HSSRLOUT data set do not contain database names, it is difficult for you to interpret and process the content of the HSSRLOUT data set created during the execution of a program that accesses multiple databases. For this reason, it is recommended that you create the HSSRLOUT data set only during the execution of programs or utilities that access a single database.

Printing long database records with FABHLDBR

The FABHLDBR utility is used for printing the longest database records of a database or the database records that require a large number of I/Os for their retrieval. The input for the utility is the HSSRLOUT data set, which has been created by the DB Tuning Statistics during the previous execution of HSSR Engine. JCL for the DB Tuning Statistics on page 168 describes the HSSRLOUT data set, and LOUT control statement on page 169 describes how to request HSSR Engine to make a selection of HSSRLOUT data set records. The HSSRLOUT data set contains one record for each database record with the following data: v Length of the database record (fullword) v The number of database I/Os required to read all database segments of the database record (fullword) v Key of the database root segment For each record in the HSSRLOUT data set, the FABHLDBR utility issues:
Chapter 10. Using Database Tuning Statistics

171

v A GU call in order to retrieve the database root segment v GN calls to retrieve dependent segments of the database record (optional) Each retrieved database segment is printed in a snaplike fashion (the printing of the database segments is not done directly by the FABHLDBR utility, but by the hardcopy trace option). The FABHLDBR utility also provides, in the printed output, the length of each database record (the length includes the length of the segment prefixes) and the number of I/Os required to read all database segments of the database record. Optionally, you can request on the SYSIN data set that FABHLDBR: 1. Stops processing after retrieving or printing nnnnn database records. 2. Processes only the HSSRLOUT records for the database records that are longer than or equal to mmmmmmm bytes. 3. Processes only the HSSRLOUT records for the database records that require nn or more I/Os. 4. Retrieves or prints only the database root segments.

JCL for the FABHLDBR utility

The FABHLDBR utility requires standard FABHX034 JCL. The DD statements are described in JCL requirements on page 21. The additional requirements for the FABHLDBR utility are shown in Table 19.
Table 19. DD statements for the FABHLDBR utility DDNAME HSSROPT SYSIN SYSUT1 ddname HSSRTRAC Use Input Input Input Input Output LRECL=133 Format LRECL=80 LRECL=80 Need Required Optional Required Required Required

EXEC This statement invokes the procedure FABHDLI, FABHDBB, or FABHULU. The required format is one of the following:
// EXEC FABHDLI,MBR=FABHLDBR,PSB=psbname // EXEC FABHDBB,MBR=FABHLDBR,PSB=psbname // EXEC FABHULU,MBR=FABHLDBR,DBD=dbdname

HSSROPT DD This statement is required to define the input data set that contains the TRDB and TRHC control statements, which activate the hardcopy trace option. SYSIN DD This optional statement defines the input data set that contains the control statements for controlling the FABHLDBR process. SYSUT1 DD This required statement defines the input HSSRLOUT data set. ddname DD This required statement defines the input IMS database data set.

172

Users Guide

HSSRTRAC DD This required statement defines the output data set in which the snaplike print of long database records is written.

Input: HSSROPT data set

The FABHLDBR utility uses the hardcopy trace option to print database segments. You need to specify the TRDB and TRHC control statements in the HSSROPT data set to activate the hardcopy trace option.

TRDB control statement

The TRDB control statement in the HSSROPT data set requests that the trace of HSSR Engine be activated. You need this control statement to obtain the snaplike print of database segments. For a complete description of the TRDB control statement, see TRDB control statement on page 138.

TRHC control statement

The TRHC control statement in the HSSROPT data set requests that the hardcopy trace option be activated. You need this control statement to obtain the snaplike print of database segments. For a complete description of the TRHC control statement, see TRHC control statement on page 139.

Input: SYSIN data set

Optionally, you can request on control statements in the SYSIN data set that FABHLDBR: v Stops processing after retrieving or printing nnnnn database records. v Processes only the HSSRLOUT records for those database records that are longer than or equal to mmmmmmm bytes. v Processes only the HSSRLOUT records for those database records that require nn or more I/Os. v Retrieves or prints only the database root segments. The following sections describe the control statements.

NBR control statement

The NBR control statement requests FABHLDBR to stop processing after retrieving or printing the specified number of database records.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 NBR nnnnn

Position 1 5

Description Code the NBR keyword to activate the NBR option. Specify the number of database records FABHLDBR processes. After the specified number of database records are retrieved or printed, FABHLDBR stops processing. Enter any number up to 5 digits, left-justified, and followed by a blank.

LENGTH control statement

The LENGTH control statement requests FABHLDBR to process only HSSRLOUT records for those database records that are longer than or equal to the specified
Chapter 10. Using Database Tuning Statistics

173

length.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 LENGTH mmmmmmm

Position 1 8

Description Code the LENGTH keyword to activate the LENGTH option. Specify the length of a database record. FABHLDBR processes only the HSSRLOUT records that correspond to the database records that are longer than or equal to the specified length. Enter any number up to 7 digits, left-justified, and followed by a blank.

IO control statement
The IO control statement requests FABHLDBR to process only HSSRLOUT records that correspond to the database records that require nn or more I/Os.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 IO nn

Position 1 4

Description Code the IO keyword to activate the IO option. Specify the number of I/Os. FABHLDBR processes only HSSRLOUT records for those database records that require more than or equal to the specified number of I/Os. Enter any number up to 2 digits, left-justified, and followed by a blank. For a HIDAM database, the number of I/Os required to read the index database is not included in this value. For a HISAM database, HSSR Engine assumes that access to the KSDS requires only one I/O.

ROOT-ONLY control statement

The ROOT-ONLY control statement requests FABHLDBR to retrieve or print only the database root segments.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 ROOT-ONLY

Position 1

Description Code the ROOT-ONLY keyword to activate the ROOT-ONLY option. FABHLDBR retrieves or prints only the database root segments.

174

Users Guide

Output: HSSRTRAC data set

This data set contains the snaplike print of long database records. The format of the snaplike print is the same as the one described in HSSRTRAC data set on page 151. See this section for a complete description of the HSSRTRAC data set.

Example
The sample shown in Figure 34 shows the sample JCL for the FABHLDBR utility.

//STEP1 EXEC FABHULU,MBR=FABHURG1,DBD=dbdname //hdamdb DD DSN=user.hdam,DISP=SHR //HSSRLOUT DD DSN=&&LOUT,UNIT=SYSDA,SPACE=(TRK,(3,3)), // DISP=(,PASS) //SYSUT2 DD DUMMY //DFSVSAMP DD DSN=IMSVS.PROCLIB(DFSVSAMP),DISP=SHR //HSSROPT DD * DBSTATS LOUT LENGTH=8000 //* //* //* //SORT EXEC PGM=SORT,REGION=4096K //SORTIN DD DSN=&&LOUT,DISP=(OLD,PASS) //SORTOUT DD DSN=&&LOUT2,UNIT=SYSDA,SPACE=(TRK,(3,3)), // DISP=(,PASS) //SYSOUT DD SYSOUT=* //SORTWK01 DD UNIT=SYSDA,SPACE=(TRK,20) //SORTWK02 DD UNIT=SYSDA,SPACE=(TRK,20) //SORTWK03 DD UNIT=SYSDA,SPACE=(TRK,20) //SYSPRINT DD SYSOUT=* //SYSIN DD * SORT FIELDS=(1,4,CH,D) END //* //* //* //PRINT EXEC FABHULU,MBR=FABHLDBR,DBD=dbdname //HSSRTRAC DD SYSOUT=* //hdamdb DD DSN=user.hdam,DISP=SHR //SYSUT1 DD DSN=&&LOUT2,DISP=(OLD,PASS) //SYSIN DD * NBR 100 //DFSVSAMP DD DSN=IMSVS.PROCLIB(DFSVSAMP),DISP=SHR //HSSROPT DD * TRDB *ALL TRHC CALL,NPF Figure 34. Sample JCL for the FABHLDBR utility

This example consists of three job steps: v The first job step creates the HSSRLOUT data set, while the database is scanned by HSSR Engine. The scan can be done, for example, by using the FABHURG1 database unload utility with the FABHULU JCL procedure (instead of FABHURG1, any other HSSR application program that processes the whole database sequentially would also do the job). Note that: The HSSRLOUT DD statement is required for creating the HSSRLOUT data set. The SYSUT2 data set of FABHURG1 can be set to DUMMY, if you do not need to obtain an unloaded data set.

Chapter 10. Using Database Tuning Statistics

175

 The DBSTATS control statement in the HSSROPT data set is required for creating the HSSRLOUT data set. The LOUT control statement in the HSSROPT is optional. In the example as described in Figure 34 on page 175, the control statement specifies that the HSSRLOUT data set only contain records for those database records whose lengths are equal to or over 8000 bytes. This reduces the size of the HSSRLOUT data set. v The second job step sorts the HSSRLOUT data set in descending sequence of the bytes 1-4 of the records (that is, in descending sequence of the database record length). v The third job step invokes the FABHLDBR utility with the FABHULU JCL procedure. Notice the following points: The HSSRTRAC is the output data set that will contain the snaplike print of long database records. In the example, the HSSRTRAC output is written to SYSOUT. The SYSUT1 DD statement defines the HSSRLOUT data set, which has been sorted in the previous job step. The NBR control statement in the SYSIN data set requests that the utility stops after retrieving or printing 100 longest database records. The TRDB control statement in the HSSROPT data set requests that the trace of HSSR Engine be activated. This control statement is required for obtaining the snaplike print of the database segments. The TRHC control statement in the HSSROPT data set requests that the hardcopy trace option be activated. This control statement is required for obtaining the snaplike print of database segments. The CALL parameter of the TRHC control statement requests a trace of the database segments and of their concatenated keys. The NPF parameter requests that the database segment prefix should not be traced.

Tuning a database with the DB Tuning Statistics

Activation of the optional DB Tuning Statistics during the sequential processing of a database or during a database unload provides statistics that make easy for you to: 1. Evaluate and monitor the effectiveness of HDAM randomizing parameters (such as the size of the root addressable area, the number of RAPs, the block or CI size, or the bytes limit) 2. Periodically monitor the need for reorganizing HDAM, HIDAM, or HISAM databases. How is it possible to determine whether the HDAM randomizing parameters are efficient and whether a database needs to be reorganized? The DB Tuning Statistics provide an important indicator to use in answering this question. This key indicator is the average number of I/Os required to read at random all database segments of one database record. By looking at this number in the DB Tuning Statistics reports, the database administrator can quickly determine whether a database is well organized and well randomized. Ideally, this number would be 1.00. If the number is larger than 1.30, then the database may be disorganized or inefficiently randomized. Other key indicators in the DB Tuning Statistics can be used to determine the cause of the problem, for example, to determine:

176

Users Guide

v Whether the HDAM root addressable area is overcrowded and whether its size should be increased. The DB Tuning Statistics answer this question by printing the packing density of the HDAM root addressable area (this is the percentage of DASD space occupied by database segments in the HDAM root addressable area). Experience shows that, with efficient randomizer modules (for example, DFSHDC40, Sequential Subset Randomizer), a reasonable goal for the packing density is often in the range of 70% to 80%. v Whether the number of HDAM RAPs is appropriate. The DB Tuning Statistics show the ratio between the number of RAPs and the number of roots. Experience shows that, with efficient randomizer modules (for example, DFSHDC40, Sequential Subset Randomizer), a reasonable ratio is around 1.5. v Whether the block or CI size is appropriate for the average database record length and for the distribution of the database record length. v Whether the HDAM bytes limit is appropriate for the average database record length and the distribution of the database record length. The following sections contain an example of the DB Tuning Statistics output for an existing HDAM database, together with a short description of the counters in the output. Then, in further sections, you will see how you can use some general "rules of thumb" and the most important key indicators of the DB Tuning Statistics for the tuning of an HDAM, HIDAM, or HISAM database. Restriction: The general "rules of thumb" described in the following sections are not directly applicable to partitioned databases.

Description of the DB Tuning Statistics

If you have activated the DB Tuning Statistics by providing a DBSTATS control statement in the HSSROPT data set, HSSR Engine writes one or more pages of statistics information in the HSSRSTAT data set, as follows: 1. Statistics about: v The number of I/Os required to read at random the database segments of one database record v The length of database records This information is provided on multiple pages: v Two pages for the database as a whole (for an example, see Figure 35 on page 178) v Two pages for the root addressable area of an HDAM database (for an example, see Figure 36 on page 181) v Two pages for the overflow area of an HDAM database (for an example, see Figure 37 on page 183) v Two pages for each secondary data set group 2. (Printed only for HDAM databases) Statistics with key indicators that represent the quality of randomizing (for an example, see Figure 38 on page 185). 3. (If you have provided control statements in the HSSRLDEF data set) An additional report containing the distribution of database record lengths (see Input: HSSRLDEF data set on page 170 for details). If you have provided an HSSRLOUT DD statement (see JCL for the DB Tuning Statistics on page 168 for details), then you will also obtain a sequential data set in which the length of each (or of the longest) database record is written.

Chapter 10. Using Database Tuning Statistics

177

Figure 35 shows an example of the pages with statistical information printed by the DB Tuning Statistics on the HSSRSTAT data set. Notes: 1. For HALDB, the DB Statistics report is produced for each data set of each partition. 2. For PHDAM, the Randomizing Statistics report is produced for each partition.

DB Statistics report
IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 TOTAL FOR WHOLE DB *** DBDGEN SPECIFICATIONS: DB-ORG HDAM DDNAME DSHDAM01 BLOCK/CI-SIZE 4,096 FREE SPACE - FREE BLOCK FREQUENCY FACTOR(FBFF) 0 - FREE SPACE PERCENTAGE FACTOR(FSPF) 15 *** KEY INDICATORS FOR QUALITY OF PHYSICAL ORGANIZATION: AVG NBR I/O IN THIS DB - PER DB-R IN THIS DB AVG DB-R LENGTH IN THIS DB - PER DB-R IN THIS DB ACTUAL PCT FREE SPACE DEFINED PCT FREE SPACE *** I/O SUMMARY: NBR I/O IN THIS DB NBR DB-RECORDS - WITH I/O IN THIS DB *** DB-RECORD LENGTH SUMMARY: TOTAL DB-R LENGTH IN THIS DB - LENGTH (BYTES) NBR DB-RECORDS - IN THIS DB 3,052,423 4,472 8,353 4,472 1.86 682 17.02 ACTUAL PCT FREE SPACE = (ALLOCED DASD - TOTAL DB-R)/ALLOCED DASD * 100 N/A "DB STATISTICS" DATE: 10/26/2007 TIME: 19.36.20 PAGE: 1 FABHC00 - V1.R2

Figure 35. DB Tuning Statistics for the entire DB (Part 1 of 2)

178

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 TOTAL FOR WHOLE DB NBR I/O TO READ ***AT RANDOM*** THE RETRIEVED SEGMENTS OF ONE DB RECORD WITH 4 PCB-BUFFERS

"DB STATISTICS" DATE: 10/26/2007 TIME: 19.36.20

PAGE: 2 FABHC00 - V1.R2

DB RECORD LENGTH (INCL PREFIXES OF SEGMENTS) EXPRESSED IN BLOCKSIZE/CI-SIZE UNITS (ONE BLKSIZE/CI-SIZE = 4,096 BYTES) LENGTH NBR DB-R PCT CUM PCT ---------------------------------------------<= 1/16 <= 2/16 <= 3/16 <= 4/16 <= 5/16 <= 6/16 <= 7/16 <= 8/16 <= 9/16 <=10/16 <=11/16 <=12/16 <=13/16 <=14/16 <=15/16 25 339 3,237 714 94 18 5 11 3 5 3 3 1 2 2 2 8 .55 7.58 72.38 15.96 2.10 .40 .11 .24 .06 .11 .06 .06 .02 .04 .04 .04 .17 .55 8.13 80.52 96.48 98.59 98.99 99.10 99.35 99.41 99.53 99.59 99.66 99.68 99.73 99.77 99.82 100.00

NBR IO NBR DB-R PCT CUM PCT ----------------------------------------------

<= <= <= <= <=

1 2 3 4 5

2,048 1,522 559 213 85 31 6 4 3 0

45.79 34.03 12.50 4.76 1.90 .69 .13 .08 .06 .00

45.79 79.83 92.33 97.09 98.09 99.68 99.82 99.91 99.97 99.97

<= <=

1 2

<= 6 <= 7 <= 8 <= 9 <= 10

<= 20 1 .02 100.00 ----------------------------------------------

----------------------------------------------

Figure 35. DB Tuning Statistics for the entire DB (Part 2 of 2)

v At the top of the left side of the figure, there is a description of the following DBDGEN/IDCAMS specifications: DBD name DD name KSDS and ESDS record length (for HISAM) Actual OSAM block size or ESDS CI size Percentage of free space left empty in each block or CI during database load and database reload Free block frequency factor v Further below on the left side of the figure, there are key indicators, which are used to see whether the database is well organized: v The average number of I/Os required to read all database segments of a database record (see notes 1 and 2 below). v The average database record length. The reported average database record length includes the size of the segment prefixes and the size of the segment data as stored on DASD (see note 1 below). v The actual free space percentage. This is the percentage of the DASD space that is neither occupied by the prefix portion nor by the data portion of database segments. (This definition is not very accurate, since DASD space occupied by

Chapter 10. Using Database Tuning Statistics

179

RAPs, by free space elements, by free space anchor points, and by BIT maps are not included in this percentage. However, in most cases, this inaccuracy is not large and does not really matter.) When computing the actual free space percentage, HSSR Engine does not take into account blocks or CIs beyond the current high-used RBA. See also note 1 below. The defined free space percentage. This figure is computed by combining both free space parameters defined during DBDGEN (that is, the free block frequency factor and the free space within each block or CI). Then HSSR Engine prints the following totals: The total number of I/Os to read all database segments The total length of all database records in the database (see note 1 below) The number of database records (see note 1 below) Then, still further below on the left-hand side of Figure 35 on page 178, there is a table showing the distribution of the number of I/Os required to read at random all the database segments of one database record (see notes 1 and 2 below). The table contains the number, the percentage, and the accumulated percentage of database records that can be read with one or more I/O operations. In the right-hand part of Figure 35 on page 178, there is a table describing the distribution of the database record length. The reported database record length includes the size of the segment prefix and the size of the segment data as stored on DASD (for compressible segments, the size of the segment after compression). See also note 1 below. The table contains the number, the percentage, and the accumulated percentage, of database records that are in the following ranges of database record length: Less than or equal to the 1/16th of the block or CI size 1/16th - 2/16th of the block or CI size 2/16th - 3/16th of the block or CI size And so on Note that the tables showing the distribution of the I/O numbers and the tables showing the distribution of the database record length are printed side by side. This makes it easier to recognize whether large numbers of I/Os per database record are due to large database record sizes. The DB Tuning Statistics report also provides, optionally, a table showing the distribution of the database record length with user-provided definitions for the database record length intervals. The use definitions for the database record length intervals are provided on control cards in the HSSRLDEF data set. For example, you may request a table showing the distribution of the database record lengths for following database record length intervals: 50, 100, 150, 200, 250, 300, 350, 400, 450, 500, 600, 700, 800, 900, 1000, 1500, and so on.

Notes: 1. While computing database record lengths and the number of I/Os, HSSR Engine takes into account only the database segments that have been retrieved by the application program or utility. The statistic modules of HSSR Engine are not aware of any database records of database segments that have not been retrieved. 2. While computing the number of I/Os, HSSR Engine assumes that the root segment is retrieved through a GU call. HSSR Engine also assumes that at the time that the GU call is issued, the buffer pools do not contain any block or CI containing a portion of the RAP chain or containing a database segment of the database record.

180

Users Guide

For an HDAM database, HSSR Engine includes the number of I/Os required to chase the RAP synonym chain. For a HIDAM database, HSSR Engine does not include in these figures the number of I/Os required to access the primary index of the HIDAM database. For a HISAM database, HSSR Engine assumes that the access to the KSDS record requires one I/O operation (additional I/Os to access the index component of the KSDS cluster are not included in these figures). While computing the number of I/Os, HSSR Engine attempts to simulate the behavior of the IMS buffer pools. If, for example, the retrieval of the database segments of a database record requires access to blocks n1, n2, and n3, or n2 and n1, then HSSR Engine will report that (with a buffer pool of three buffers) the number of I/Os is three (not five).

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 (ROOT ADDRESSABLE AREA) *** DBDGEN SPECIFICATIONS:

"DB STATISTICS" DATE: 10/26/2007 TIME: 19.36.20

PAGE: 3 FABHC00 - V1.R2

DB-ORG HDAM DDNAME DSHDAM01 (RAA) BLOCK/CI-SIZE 4,096 FREE SPACE - FREE BLOCK FREQUENCY FACTOR(FBFF) 0 - FREE SPACE PERCENTAGE FACTOR(FSPF) 15 *** KEY INDICATORS FOR QUALITY OF PHYSICAL ORGANIZATION: AVG NBR I/O IN RAA - PER DB-R IN RAA - PER DB-R IN THIS DB AVG DB-R LENGTH IN RAA - PER DB-R IN RAA - PER DB-R IN THIS DB ACTUAL PCT FREE SPACE DEFINED PCT FREE SPACE *** I/O SUMMARY: NBR I/O IN RAA NBR DB-RECORDS - WITH I/O IN RAA - IN THIS DB *** DB-RECORD LENGTH SUMMARY: TOTAL DB-R LENGTH IN RAA - LENGTH (BYTES) NBR DB-RECORDS - IN RAA - IN THIS DB 2,549,078 4,203 4,472 6,543 4,472 4,472 1.46 1.46 606 570 17.14 ACTUAL PCT FREE SPACE = (ALLOCED DASD - TOTAL DB-R)/ALLOCED DASD * 100 15.00 DEFINED PCT FREE SPACE = FSPF + 100/FBFF - FSPF/FBFF

Figure 36. DB Tuning Statistics for the HDAM root addressable area (Part 1 of 2)

Chapter 10. Using Database Tuning Statistics

181

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 (ROOT ADDRESSABLE AREA) NBR I/O TO READ ***AT RANDOM*** THE RETRIEVED SEGMENTS OF ONE DB RECORD WITH 4 PCB-BUFFERS

"DB STATISTICS" DATE: 10/26/2007 TIME: 19.36.20

PAGE: 4 FABHC00 - V1.R2

DB RECORD LENGTH (INCL PREFIXES OF SEGMENTS) EXPRESSED IN BLOCKSIZE/CI-SIZE UNITS (ONE BLKSIZE/CI-SIZE = 4,096 BYTES) LENGTH NBR DB-R PCT CUM PCT ---------------------------------------------<= 1/16 <= 2/16 <= 3/16 24 311 3,868 .57 7.39 92.02 .57 7.97 100.00

NBR IO NBR DB-R PCT CUM PCT ----------------------------------------------

<= <= <= <= <=

1 2 3 4 5

3,166 822 294 128 45

70.79 18.38 6.57 2.86 1.00

70.79 89.17 95.75 98.61 99.61

<= 6 9 .20 99.82 <= 7 5 .11 99.93 <= 8 2 .04 99.97 <= 9 1 .02 100.00 ----------------------------------------------

----------------------------------------------

Figure 36. DB Tuning Statistics for the HDAM root addressable area (Part 2 of 2)

Figure 36 on page 181 is similar to Figure 35 on page 178. The statistics, however, do not reflect the number of I/Os in the whole database and the total database record size; instead, they reflect the number of I/Os in the root addressable area and the database record size in the root addressable area.

182

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 (OVERFLOW AREA) *** DBDGEN SPECIFICATIONS:

"DB STATISTICS" DATE: 10/26/2007 TIME: 19.36.20

PAGE: 5 FABHC00 - V1.R2

DB-ORG HDAM DDNAME DSHDAM01 (OVFLW AREA) BLOCK/CI-SIZE 4,096 FREE SPACE - FREE BLOCK FREQUENCY FACTOR(FBFF) 0 - FREE SPACE PERCENTAGE FACTOR(FSPF) 15 *** KEY INDICATORS FOR QUALITY OF PHYSICAL ORGANIZATION: AVG NBR I/O IN OVFLW AREA - PER DB-R IN OVFLW AREA - PER DB-R IN THIS DB AVG DB-R LENGTH IN OVFLW AREA - PER DB-R IN OVFLW AREA - PER DB-R IN THIS DB ACTUAL PCT FREE SPACE DEFINED PCT FREE SPACE *** I/O SUMMARY: NBR I/O IN OVFLW AREA NBR DB-RECORDS - WITH I/O IN OVFLW AREA - IN THIS DB *** DB-RECORD LENGTH SUMMARY: TOTAL DB-R LENGTH IN OVFLW AREA - LENGTH (BYTES) NBR DB-RECORDS - IN OVFLW AREA - IN THIS DB 503,345 1,655 4,472 1,811 1,655 4,472 1.09 .40 304 112 16.41 ACTUAL PCT FREE SPACE = (ALLOCED DASD - TOTAL DB-R)/ALLOCED DASD * 100 15.00 DEFINED PCT FREE SPACE = FSPF + 100/FBFF - FSPF/FBFF

Figure 37. DB Tuning Statistics for the HDAM overflow area (Part 1 of 2)

Chapter 10. Using Database Tuning Statistics

183

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"DB STATISTICS" DATE: 10/26/2007 TIME: 19.36.20

PAGE: 6 FABHC00 - V1.R2

STATISTICS FOR DB=HDAM0010 (OVERFLOW AREA)

NBR I/O TO READ ***AT RANDOM*** THE RETRIEVED SEGMENTS OF ONE DB RECORD WITH 4 PCB-BUFFERS NBR IO NBR DB-R PCT CUM PCT ----------------------------------------------

DB RECORD LENGTH (INCL PREFIXES OF SEGMENTS) EXPRESSED IN BLOCKSIZE/CI-SIZE UNITS (ONE BLKSIZE/CI-SIZE = 4,096 BYTES) LENGTH NBR DB-R PCT CUM PCT ---------------------------------------------<= 1/16 <= 2/16 <= 3/16 <= 4/16 <= 5/16 <= 6/16 <= 7/16 <= 8/16 <= 9/16 <=10/16 <=11/16 <=12/16 <=13/16 <=14/16 <=15/16 1,143 201 183 70 21 10 3 6 2 1 1 4 2 0 1 1 6 69.06 12.14 11.05 4.22 1.26 .60 .18 .36 .12 .06 .06 .24 .12 .00 .06 .06 .36 69.06 81.20 92.26 96.49 97.76 98.36 98.54 98.91 99.03 99.09 99.15 99.39 99.51 99.51 99.57 99.63 100.00

<= <= <= <= <=

1 2 3 4 5

1,541 99 9 3 1 0 0 1 0 0

93.11 5.98 .54 .18 .06 .00 .00 .06 .00 .00

93.11 99.09 99.63 99.81 99.87 99.87 99.87 99.93 99.93 99.93

<= 1 <= 2

<= 6 <= 7 <= 8 <= 9 <= 10

<= 20 1 .06 100.00 ----------------------------------------------

----------------------------------------------

Figure 37. DB Tuning Statistics for the HDAM overflow area (Part 2 of 2)

Figure 37 on page 183 is similar to Figure 35 on page 178. The statistics, however, do not reflect the number of I/Os in the whole database and the total database record size; instead, they reflect the number of I/Os in the HDAM overflow area and the database record size in the HDAM overflow area.

184

Users Guide

Randomizing Statistics report

IMS HIGH PERFORMANCE UNLOAD 5655-E06 "RANDOMIZING STATISTICS" DATE: 10/26/2007 TIME: 19.36.20 PAGE: 1 FABHC00 - V1.R2

STATISTICS FOR RETRIEVED ROOTS OF DB=HDAM0010 WITH RANDOMIZER=DFSHDC10 *** DBDGEN SPECIFICATIONS: NBR RAPS PER BLOCK/CI HIGHEST BLOCK/CI IN RAA BYTES-LIMIT BLOCK/CI-SIZE FREE SPACE: - FREE BLOCK FREQUENCY FACTOR(FBFF) - FREE SPACE PERCENTAGE FACTOR(FSPF) *** KEY INDICATORS FOR QUALITY OF RANDOMIZING: AVG NBR I/O - PER DB-R - ON RAP CHAIN PER ROOT - ON RAP CHAIN PER RAP CHAIN - IN RAA PER DB-R - IN OVERFLOW AREA PER DB-R NBR OF ACCESSED RAPS WHICH ARE USED - NBR - PCT OF ACCESSED RAPS NBR OF ACCESSED ROOTS IN OVERFLOW AREA - NBR - PCT OF ACCESSED ROOTS PACKING DENSITY OF RAA NBR OF RAPS PER ROOT AVG POSITION OF ROOT SEGMENTS ON RAP SYNONYM CHAINS AVG NUMBER OF SYNONYMS ON RAP SYNONYM CHAINS AVG DB-R LENGTH 1.86 1.34 1.53 1.46 .40 2,327 77.56 269 6.01 82.86 .66 1.73 1.92 682 4 750 700 4,096 0 15

Figure 38. Randomizing Statistics (Part 1 of 2)

Chapter 10. Using Database Tuning Statistics

185

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"RANDOMIZING STATISTICS" DATE: 10/26/2007 TIME: 19.36.20

PAGE: 2 FABHC00 - V1.R2

STATISTICS FOR RETRIEVED ROOTS OF DB=HDAM0010 WITH RANDOMIZER=DFSHDC10 NBR I/O ON RAP CHAIN TO READ ***AT RANDOM*** THE ROOT SEGMENTS WITH 4 PCB-BUFFERS NBR IO NBR ROOTS PCT CUM PCT ---------------------------------------------<= <= <= <= <= <= 1 2 3 4 5 6 3,157 1,125 170 16 3 1 70.59 25.15 3.80 .35 .06 .02 70.59 95.75 99.55 99.91 99.97 100.00

POSITION OF ROOT SEGMENTS ON RAP CHAINS POSITION NBR ROOTS PCT CUM PCT ---------------------------------------------<= <= <= <= <= <= <= 1 2 3 4 5 6 7 2,327 1,344 544 177 64 14 2 52.03 30.05 12.16 3.95 1.43 .31 .04 52.03 82.08 94.25 98.21 99.64 99.95 100.00

Figure 38. Randomizing Statistics (Part 2 of 2)

Figure 38 on page 185 provides information that can be used to evaluate and monitor the quality of the HDAM randomizing parameters. v At the top of the figure, there is a description of the following DBDGEN or IDCAMS specifications: DBD name Name of the randomizing module Number of RAPs per block or CI Highest block number or CI number in the root addressable area Bytes limit Actual block size or CI size Percentage of free space left empty in each block or CI during database load and database reload Free block frequency factor v Further below there are some key indicators, which describe the quality of the randomizing. These important indicators can also be used to understand how poor randomizing parameters can be changed to enhance the quality of the randomizing. These key indicators are: The average number of I/Os required to read all database segments of one database record (see notes 1 and 2 below). The average number of I/Os required to read a root segment at random while following the RAP chain (see notes 1 and 2 below). The average number of I/Os in the root addressable area required to read at random all database segments of one database record. This number includes I/Os in the root addressable area that are required to read the root and the

186

Users Guide

dependent database segments and the I/Os in the root addressable area that are required to follow the RAP chain (see notes 1 and 2 below). The average number of I/Os in the overflow area required to read at random all database segments of one database record. This number includes the I/Os in the overflow area that are required to read the root and the dependent database segments and I/Os in the overflow area that are required to follow the RAP chain (see notes 1 and 2 below). The percentage of used RAPs. This number is computed by dividing the total number of RAPs in the root addressable area by the number of accessed RAPs that are nonzero (that is, RAPs that are used). The percentage of the retrieved roots that are located in the overflow area. The packing density of the root addressable area. This is the percentage of the DASD space in the root addressable area space that is occupied by the prefix portion and data portion of database segments (see note 1 below).

The number of RAPs per root. This is a ratio computed by dividing the number of RAPs in the root addressable area by the number of roots that have been read through HSSR GN calls. The average position of the (retrieved) roots on the RAP chains. The average database record length (see note 1 below). v The following tables are near the bottom of the report: A table containing the number, percentage and accumulated percentage of database roots that require, during random GU processing 1, 2, 3, 4, and so on, I/O operations while following the RAP synonym chain (see notes 1 and 2 below). A table describing the number, percentage and accumulated percentage of database root segments that are on the first, second, third, and so on, position of a RAP synonym chain (see note 1 below). Notes: 1. When computing database record lengths and the number of I/Os, HSSR Engine takes into account only those database segments that have been retrieved by the application program or utility. The statistic modules of HSSR Engine are not aware of any database records or database segments that have not been retrieved. 2. When computing the number of I/Os, HSSR Engine assumes that the root segment is retrieved through a GU call. HSSR Engine also assumes that at the time the GU call is issued, the buffer pools do not contain any block or CI containing a portion of the RAP chain or containing a database segment of the database record. When computing the number of I/Os, HSSR Engine attempts to simulate the LRU algorithm of the IMS buffer pools. If, for example, the retrieval of the database segments of one database record requires access to blocks n1, n2, and n3, or n2 and n1, then HSSR Engine will report that (for a buffer pool of three buffers) the number of I/Os is three (not five).

DB Record Length Distribution report

Figure 39 on page 188 shows the DB record length distribution report.

Chapter 10. Using Database Tuning Statistics

187

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"DB RECORD LENGTH DISTRIBUTION" DATE: 10/26/2007 TIME: 20.09.01 DATABASE RECORD LENGTH DISTRIBUTION FOR DB=HDAM0010

PAGE: 1 FABHC00 - V1.R2

LENGTH NBR DB-R PCT CUM PCT --------------------------------------------------<= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= 500 550 600 650 700 750 800 850 900 950 1000 1050 1100 1150 1200 1250 1300 1350 1400 1450 1500 1600 1700 1800 1900 2000 2500 3000 3500 4000 5000 6000 7000 8000 349 740 264 1,355 260 551 176 329 113 82 81 34 32 12 18 9 7 4 5 3 3 1 1 3 4 6 7 7 3 5 2 2 2 2 7.80 16.54 5.90 30.29 5.81 12.32 3.93 7.35 2.52 1.83 1.81 .76 .71 .26 .40 .20 .15 .08 .11 .06 .06 .02 .02 .06 .08 .13 .15 .15 .06 .11 .04 .04 .04 .04 7.80 24.35 30.25 60.55 66.36 78.68 82.62 89.98 92.50 94.34 96.15 96.91 97.62 97.89 98.30 98.50 98.65 98.74 98.85 98.92 98.99 99.01 99.03 99.10 99.19 99.32 99.48 99.64 99.70 99.82 99.86 99.91 99.95 100.00

Figure 39. DB Record Length Distribution

The statistics in Figure 39 are printed only if you request a DB Record Length Distribution Report with your own definition of the database record length ranges (as described in Input: HSSRLDEF data set on page 170). This is achieved by providing control cards in the HSSRLDEF data set. The reported database record length includes the size of the segment prefixes and the size of the segment data as stored on DASD (for compressible segment, the size of the segment data reflects the size of the compressed segment). The table contains the number, the percentage, and the accumulated percentage of database records that are in the user-defined ranges of database record length. When computing database record lengths, HSSR Engine takes into account only the database segments that have been retrieved by the application program or utility. The statistics modules of HSSR Engine are not aware of any database records or database segments that have not been retrieved.

Tuning the primary data set group of an HDAM database

This section and its subsections discuss the most important indicators in the DB Tuning Statistic output and how these indicators can be used to tune an HDAM database. Tuning an HDAM database is an iterative process. When changing randomizing parameters, database administrators with little tuning experience should change

188

Users Guide

only one randomizing parameter at a time, and then observe the impact of this change. This can be done by the following sequence of activities: 1. Unloading the database 2. Changing a randomizing parameter and DBDGEN 3. Reloading the database with the modified randomizing parameter 4. Executing FABHURG1 or FABHFSU unload utility to obtain new DB Tuning Statistics and to observe the impact of the modified randomizing parameter 5. Depending on the results of the observations in step 4 above, attempting other changes of the randomizing parameters (step 2) If the database is very large, it is often not practical to do multiple consecutive reloads or unloads in order to observe the effect of multiple consecutive changes. In this case, the database administrator can use the FABHEXTR exit routine in order to create a small database extract consisting of a subset of the real-life database records (see Creating a database extract with FABHEXTR on page 213). The database administrator can then perform his tuning experiments with this smaller database extract. Disclaimers: 1. The content of the following sections is based on experience at one installation with the tuning of the real-life HDAM databases. It is possible that with other HDAM databases, some of the presented material does not apply exactly and that some of the recommendations made will not always produce the expected results. More specifically, you should be aware that it is often difficult to tune HDAM databases with large database record sizes (for example, average database record sizes larger than one half of the block or CI size) using the general "rules of thumb." 2. The following sections provide target values for some key indicators (for example, 1.20 or 1.30 for the average number of I/Os required for the reading of all database segments of one database record, 70%75% for the packing density of the root addressable area). These suggested target values are provided as guidance for database administrators who do not have practical experience with tuning of their databases. After gaining experience with the tuning of the real-life databases of his installation, the database administrator will probably review and adapt the proposed target values to his specific databases. Therefore, the provided target values should be regarded as general rules of thumb, providing a reasonable starting point when concrete tuning experience with the real-life databases of the installation is lacking.

Average number of I/O operations per database record

Obviously, HDAM randomizing can be considered to be efficient if the average number of I/O operations required to read at random all database segments of one database record is low. The average number of I/Os required to read at random all database segments of one database record is one of the most important indicators of the quality of the randomizing. This average number of I/Os is printed by the DB Tuning Statistics as shown in Figure 38 on page 185, to the right of the phrase "AVG NBR I/O: - PER DB-R." By looking at this average number in the DB Tuning Statistics, the database administrator can very rapidly see whether a database is efficiently randomized.

Chapter 10. Using Database Tuning Statistics

189

For an ideal database consisting of one single data set group, this average number would be 1.0. In real life, this ideal value of 1.0 can seldom be achieved and the average number of database I/Os per database record will be higher. Note, that due to the "law of the large numbers" it is easier to achieve a good randomizing value when the block size, divided by average database record length, is large. As a general rule of thumb, the database can be considered as fairly well randomized if the average number of I/Os per database record is below: v 1.20 (for databases with an average database record length below one tenth of the block or CI size) v 1.30 (for databases with larger average database record lengths.) For numbers above 1.20/1.30, the database can often be considered to be poorly randomized (unless the database record length is large). In this case, the database administrator can use other numbers provided by the DB Tuning statistics in order to determine the reason for the poor randomizing. These other numbers in the DB Tuning Statistics can be used to give an answer to the questions in the following checklist and to find, in most cases, the reason for poor randomizing: 1. Is the size of the root addressable area appropriate? (See Packing density of the root addressable area on page 191 for details.) 2. Is the number of RAPs appropriate? (See Number of RAPs per root segment on page 192 for details.) 3. Is the HDAM bytes limit appropriate for the database record lengths in this database? (See Bytes limit on page 194 for details.) 4. Is the block size or CI size appropriate for the database record lengths of this database? (See CI size and block size on page 194 for details.) 5. Is the database record length excessive? (See Databases with long database records on page 207 for details.) 6. Is the amount of Free Space specified during DBDGEN equal to zero? (See Free block frequency factor on page 195 for details.) 7. Is a database reorganization overdue in order to reduce database segment scattering in the overflow area? (See Periodical database reorganization on page 206 for details.) 8. For a Sequential Subset Randomizer: Is the relative amount of DASD space allocated to each subset of database records appropriate? (See Inefficient space suballocation for the Sequential Subset Randomizer on page 207 for details.) Notes: 1. Any reference to the Sequential Subset Randomizer in this chapter is not intended to state or imply that this product should be used instead of the standard DFSHDC40 randomizing module. 2. HSSR Engine does not know which database record occurrences are the most frequently accessed. For some databases, it is sometimes the longest database records requiring the largest number of I/Os that are the most often accessed database records. In this case, the average number of I/Os per database record reported by HSSR Engine is different from the average number of I/Os per accessed database record. 3. HSSR Engine does not know which segment types are the most frequently accessed. With some databases, it is sometimes only one or

190

Users Guide

two segment types that are often accessed. In this case, the job step used to produce the DB Tuning Statistics can be run with a PSB, which is sensitive only to these two segment types. The DB Tuning Statistics of such a job will probably be more representative than the DB Tuning Statistics of a job that was sensitive to all segment types. For detailed statistics about the "probability of I/O" for each segment type, see "Segment and Pointer Statistics Report" of IMS High Performance Pointer Checker. Discussion of the example In the example of Figure 38 on page 185, the average number of I/Os per database record is 1.86. This number is substantially higher than the target values of 1.20 and 1.30. A quick glance at the average database record length shows that the average database record length is not large (1/6th of the CI size); therefore the reason for the poor average number of I/Os per database record is not large database record lengths. Hence it seems probable that the high average number of I/Os per database record is due to poor randomizing parameters and that the average number of I/Os can be substantially reduced. The next sections show how the DB Tuning Statistics can be used to understand why this database is currently inefficiently randomized, and how the randomizing can be improved. Note that both the average number of I/Os per database record in the root addressable area and in the overflow area are far from their ideal values. They are 1.46 for the root addressable area (RAA) and 0.40 for the overflow area (the ideal values being 1.00 and 0.00). A high value in the RAA is often an indication that the packing density of the root addressable area is too high (see Packing density of the root addressable area on page 191). A high value of I/Os in the overflow area is often an indication that the bytes limit is too low (see Bytes limit on page 194 for details).

Packing density of the root addressable area

The packing density of the HDAM root addressable area can be found in Figure 38 on page 185 to the right of the phrase "PACKING DENSITY OF RAA." With the standard DFSHDC40 randomizer and with the Sequential Subset Randomizer, a reasonable rule of thumb is a packing density of approximately 75% (for databases with an average database record length smaller than one tenth of the CI/block size) or 70% (for databases with a larger average database record length). Notes: 1. Aiming for higher packing densities saves DASD space, but often decreases the performance of HDAM database accesses. Each installation will have probably its own idea of what is the ideal trade-off between DASD space and performance and regarding the ideal packing density. For example, some installations may want packing densities of 75% and 80% (instead of the target values of 70% and 75%). 2. For small or medium-sized HDAM databases (when saving DASD space is not important), it is often reasonable to aim for a packing density below 70%.

Chapter 10. Using Database Tuning Statistics

191

3. If the total size of all database records will eventually grow, it is then reasonable to oversize the root addressable area at database reload time, in order to provide enough space for the future data growth. You can change the packing density of the root addressable area by varying the number of blocks or CIs in the root addressable area and by varying the size of a block or CI. Increasing the number of blocks or CIs or increasing the block or CI size will increase the size of the root addressable area and lower its packing density; this will usually increase the performance of random accesses to the database. Varying the bytes limit may also change the packing density of the root addressable area (reducing the bytes limit will tend to store more information in the overflow area and less information in the root addressable area; this will hence tend to reduce the packing density in the root addressable area). As a rule of thumb, you should increase the size of the root addressable area, if the DB Tuning Statistics shows that: v The packing density is higher than the recommended target values of 70% and 75% v The average number of I/Os in the root addressable area per database record is higher than 1.15. Discussion of the example In the example of Figure 38 on page 185, the packing density of the root addressable area is 82.86%. This is higher than the recommended value of 70% for databases with this type of average database record length. This high packing density provides a probable and partial explanation for the following numbers, which look poor: v The average number of I/O on RAP chain per root, which is 1.34 (usually this number should not be much higher than 1.10). v The average number of I/O in RAA per database record, which is 1.46 (usually this number should not be much higher than 1.15). v The percentage of accessed roots in the overflow area, which is 6.01 (usually this number should not be much higher than 1.0). In this case, you could decrease the packing density of the root addressable area. Bytes limit on page 194 shows that the bytes limit is already too low, so a decrease of the packing density should not be attempted through a decrease of the bytes limit. Instead, a decrease of the packing density should be achieved by increasing the number of blocks or CIs in the root addressable area (or by an increase of the block or CI size).

Number of RAPs per root segment

This ratio is found in Figure 38 on page 185, to the right of the phrase "NBR OF RAPS PER ROOT." Generally, the number of RAPs should be approximately 1.5 times the number of database records. In case of doubt, it is better to specify too many than too few RAPs (since a RAP is only 4 bytes and hence inexpensive in terms of DASD space)1. Note1: An exception to this recommendation is an Intersystem block-level sharing environment with sequential database processing. In such an environment, the

192

Users Guide

number of RAPs should not be too large, since access to each RAP may create intersystem block-level sharing delays.

Chapter 10. Using Database Tuning Statistics

193

Discussion of the example In the example in Figure 38 on page 185, the number of RAPs per root is 0.66. This is much too low. This low number probably contributes to the high average number of I/Os per root on the RAP chains (which is 1.34). You could increase the number of RAPs per CI/Block to increase this ratio to 1.5.

CI size and block size

The current CI size/block size is shown in the top portion of Figure 38 on page 185. A general rule of thumb is a 4 KB CI/block size for HDAM. However, if the average database record length is higher than 800 bytes (that is, larger than 1/5th of the block or CI size), then an increase of the block or CI size from 4 KB to 8 KB might improve the performance of HDAM database accesses (especially if the database administrator wants a high packing density (more than 70%) of the root addressable area). In this case, an increase of the CI size/block size from 4 KB to 8 KB can often reduce the number of I/O operations (but will increase slightly the time of an I/O operation). CI/block sizes larger than 8 KB should be an exception (for example, for very large average database record sizes). Discussion of the example In the example in Figure 38 on page 185, the average database record size is 682. This is approximately 1/6th of the block or CI size. 1/6th of the block or CI size is not very large and seems acceptable. However, it could be reasonable to experiment with an 8 KB block or CI size. A decision to increase the block or CI size from 4 KB to 8 KB for this database is probably a matter of the personal taste of the database administrator.

Bytes limit
The bytes limit is the maximum number of bytes of a database record that can be stored into the root addressable area in a series of insert calls unbroken by a call to another database record. The current bytes limit is shown in the top portion of Figure 38 on page 185. The database administrator needs to perform a trade-off when specifying a bytes limit. Specifying a bytes limit that is too small will result in the storing of too many database segments into the overflow area. Access to these many database segments in the overflow area will usually trigger additional I/Os (since these database segments are not stored in the same block or CI as the root segment in the root addressable area); these additional I/Os will adversely affect the performance of access to the HDAM database. Specifying a bytes limit that is too high (for example, 10 times the average database record length) may create a situation where one individual database record occupies too much space in the root addressable area. Other database records of the same block or CI or of neighboring blocks or CIs will then have an insufficient amount of DASD space available for the storing of their own database segments in the same block or CI as the RAP2. Access to the database segments of these other database records will require additional I/Os. This will adversely affect the performance of access to the HDAM database.

194

Users Guide

Note2: Specification of a bytes limit that is too high often creates a "cascade" effect. If, for example, one database record randomizing to block n is allowed to store as many as five block sizes worth of data in the root addressable area, then the database records that are randomized to neighboring blocks (for example, block n, n+1, n+2, n+3, and n+4) cannot be stored in the same block as their RAPs. The segments of these database records will spill into blocks n+5, n+6, and so forth, and will create problems for the database records that are randomized in block n+5, n+6, and so on. Note that the PSSR utility of IMS High Performance Load assists in preventing such cascading effects. The DB Tuning Statistics provide the following information, which is useful when evaluating whether the current bytes limit is appropriate: v The table containing the distribution of the database record length (see Figure 35 on page 178) v The average number of I/Os per database record in the overflow area (see Figure 38 on page 185). Discussion of the example The table printed by the DB Tuning Statistics (shown in the top-right-hand portion of Figure 35 on page 178) is useful for a reasonable determination of the bytes limit. The example of Figure 35 on page 178 shows that: v 80.52 percent of the database records have a database record length smaller than 3/16th of a block or CI. v 96.48 percent of the database records have a database record length smaller than 4/16th of a block or CI. v 98.59 percent of the database records have a database record length smaller than 5/16th of a block or CI. Based on this information, the current bytes limit (which is 700 according to Figure 38 on page 185) seems too low. With a bytes limit of 700, at least 19.48% (=100%-80.52%) of the database records will have, after a database reload, some dependent segments in the overflow area. This low bytes limit is one of the major reasons for the high average number (0.40) of I/Os per database record in the overflow area. You could increase the current bytes limit from 700 bytes to 5/16th of the block or CI size; which is 1280 bytes. 1280 bytes is not excessive, when compared with the average database record length of 862. With a bytes limit of 1280, approximately 98.59% of the database records will have all their database segments in the root addressable area. This will hopefully reduce the average number of I/Os per database record in the overflow area, which is currently 0.40.

Free block frequency factor

As explained inIMS Administration Guide: Database Manager, specifying a free block frequency factor on the DATASET macro of DBDGEN for the first data set group of HDAM is self-defeating. For data set groups other than the first HDAM data set group, a free block frequency specification is often useful.

Chapter 10. Using Database Tuning Statistics

195

Free space within each block/CI

Specification on the DATASET macro of DBDGEN of free space within each block or CI has both advantages and disadvantages. Free space within each block or CI is often advantageous, if the database will have a large number of insert activities after database load/reload in the overflow area. In this case, free space specifications often reduce the scattering of database segments of the same database record into a large number of different blocks or CIs during subsequent insert activities. The percentage of specified free space should be taken into account when determining the size of the RAA. For example, when specifying 10% of free space, some database administrators increase the size of the root addressable area by 10%, since the free space is not available at database load time or database reload time. Free space within each block or CI is disadvantageous if few database segments are inserted after database load/reload or if nearly all database segments can be stored in the root addressable area. Discussion of the example: For the example described in the previous figures, one should experiment without free space specifications. Why? Because after the recommended increase of the packing density of the root addressable area, enough free space will be available in the RAA; and because after the recommended increase of the bytes limit, only few database segments will be stored in the overflow area.

Examples of other indicators provided by the DB Tuning Statistics

Percent of roots in the overflow area: This number can be found in Figure 38 on page 185, to the right of the phrase "NBR OF ACCESSED ROOTS IN OVERFLOW AREA: - PCT OF ACCESSED ROOTS." Normally this percent should be very small (below 1 percent). Higher values will increase the average number of I/Os required to access a root segment and will decrease the performance. The reason for a high value is often an overcrowded root addressable area. Discussion of the example In the example of Figure 38 on page 185, the percentage of roots in the overflow area is too high: 6.01. You could increase the root addressable area (see Packing density of the root addressable area on page 191) to take care of this problem. Number of I/Os on the RAP chain: This number can be found in Figure 38 on page 185 to the right of the phrase "AVG NBR I/O: - ON RAP CHAIN PER ROOT." Normally, this number should not be substantially larger than 1.10. The reason for a high value is often an overcrowded root addressable area, too few RAPs, a block or CI size that is too small, or a bytes limit that is too high.

196

Users Guide

Discussion of the example In the example of Figure 38 on page 185, the average number of I/Os on the RAP chain is too high: 1.34. The recommended increase of the root addressable area (see Packing density of the root addressable area on page 191) and an increase of the number of RAPs (see Number of RAPs per root segment on page 192) should take care of this problem. Number of I/Os in the root addressable area: This number can be found in Figure 38 on page 185 to the right of the phrase "AVG NBR I/O: - IN RAA PER DB-R." Normally, this number should not be substantially larger than 1.20. The reason of a higher value is often an overcrowded root addressable area, too few RAPs, a block or CI size that is too small, or a bytes limit that is too high. Discussion of the example In the example of Figure 38 on page 185, the average number of I/Os in the RAA is too high: 1.46. The recommended increase of the root addressable area (see Packing density of the root addressable area on page 191) and an increase of the number of RAPs (see Number of RAPs per root segment on page 192) should take care of this problem. Number of I/Os in the overflow area: This number can be found in Figure 38 on page 185 to the right of the phrase "AVG NBR I/O: - IN OVERFLOW AREA PER DB-R." Normally, this number should not be substantially larger than 0.20. The reason of a higher value is often a bytes limit which is too low, a block or CI size which is too small for the database record length of the database, database records that are very long, or a database that needs to be reorganized in order to reduce the fragmentation of database segments of the same database record into multiple blocks or CIs. Discussion of the example In the example of Figure 38 on page 185, the average number of I/Os in the overflow area is too high: 0.40. The recommended increase of the bytes limit (see Bytes limit on page 194) should take care of this problem.

Summary of suggested changes for the example database

In the previous discussion of the example of DB Tuning Statistics, the following changes were suggested: v Increase the size of the root addressable area in order to decrease its packing density (the target packing density being approximately 70%). v Increase the number of RAPs (the target ratio of RAPs per root being 1.5). v Increase the bytes limit (to approximately 1280 bytes). v Get rid of free space specifications. Figure 40 on page 198 contains the DB Tuning Statistics of the database after the suggested changes have been made. Notice the considerable improvements of the different indicators. For example, the average number of I/Os per database record has improved from 1.86 to 1.16.

Chapter 10. Using Database Tuning Statistics

197

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 TOTAL FOR WHOLE DB *** DBDGEN SPECIFICATIONS: DB-ORG HDAM DDNAME DSHDAM01 BLOCK/CI-SIZE 4,096 FREE SPACE - FREE BLOCK FREQUENCY FACTOR(FBFF) 0 - FREE SPACE PERCENTAGE FACTOR(FSPF) 0 *** KEY INDICATORS FOR QUALITY OF PHYSICAL ORGANIZATION: AVG NBR I/O IN THIS DB - PER DB-R IN THIS DB AVG DB-R LENGTH IN THIS DB - PER DB-R IN THIS DB ACTUAL PCT FREE SPACE DEFINED PCT FREE SPACE *** I/O SUMMARY: NBR I/O IN THIS DB NBR DB-RECORDS - WITH I/O IN THIS DB *** DB-RECORD LENGTH SUMMARY: TOTAL DB-R LENGTH IN THIS DB - LENGTH (BYTES) NBR DB-RECORDS - IN THIS DB 3,052,423 4,472 5,197 4,472 1.16

"DB STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 1 FABHC00 - V1.R2

682 27.16 ACTUAL PCT FREE SPACE = (ALLOCED DASD - TOTAL DB-R)/ALLOCED DASD * 100 N/A

Figure 40. DB Statistics after tuning (Part 1 of 9)

198

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 TOTAL FOR WHOLE DB NBR I/O TO READ ***AT RANDOM*** THE RETRIEVED SEGMENTS OF ONE DB RECORD WITH 4 PCB-BUFFERS

"DB STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 2 FABHC00 - V1.R2

DB RECORD LENGTH (INCL PREFIXES OF SEGMENTS) EXPRESSED IN BLOCKSIZE/CI-SIZE UNITS (ONE BLKSIZE/CI-SIZE = 4,096 BYTES) LENGTH NBR DB-R PCT CUM PCT ---------------------------------------------<= 1/16 <= 2/16 <= 3/16 <= 4/16 <= 5/16 <= 6/16 <= 7/16 <= 8/16 <= 9/16 <=10/16 <=11/16 <=12/16 <=13/16 <=14/16 <=15/16 25 339 3,237 714 94 18 5 11 3 5 3 3 1 2 2 2 8 .55 7.58 72.38 15.96 2.10 .40 .11 .24 .06 .11 .06 .06 .02 .04 .04 .04 .17 .55 8.13 80.52 96.48 98.59 98.99 99.10 99.35 99.41 99.53 99.59 99.66 99.68 99.73 99.77 99.82 100.00

NBR IO NBR DB-R PCT CUM PCT ----------------------------------------------

<= <= <= <= <= <=

1 2 3 4 5 6

3,925 413 100 26 6 2

87.76 9.23 2.23 .58 .13 .04

87.76 97.00 99.23 99.82 99.95 100.00

<= 1 <= 2

----------------------------------------------

----------------------------------------------

Figure 40. DB Statistics after tuning (Part 2 of 9)

Chapter 10. Using Database Tuning Statistics

199

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 (ROOT ADDRESSABLE AREA) *** DBDGEN SPECIFICATIONS:

"DB STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 3 FABHC00 - V1.R2

DB-ORG HDAM DDNAME DSHDAM01 (RAA) BLOCK/CI-SIZE 4,096 FREE SPACE - FREE BLOCK FREQUENCY FACTOR(FBFF) 0 - FREE SPACE PERCENTAGE FACTOR(FSPF) 0 *** KEY INDICATORS FOR QUALITY OF PHYSICAL ORGANIZATION: AVG NBR I/O IN RAA - PER DB-R IN RAA - PER DB-R IN THIS DB AVG DB-R LENGTH IN RAA - PER DB-R IN RAA - PER DB-R IN THIS DB ACTUAL PCT FREE SPACE DEFINED PCT FREE SPACE *** I/O SUMMARY: NBR I/O IN RAA NBR DB-RECORDS - WITH I/O IN RAA - IN THIS DB *** DB-RECORD LENGTH SUMMARY: TOTAL DB-R LENGTH IN RAA - LENGTH (BYTES) NBR DB-RECORDS - IN RAA - IN THIS DB 2,966,533 4,472 4,472 5,113 4,472 4,472 1.14 1.14 663 663 27.65 ACTUAL PCT FREE SPACE = (ALLOCED DASD - TOTAL DB-R)/ALLOCED DASD * 100 .00 DEFINED PCT FREE SPACE = FSPF + 100/FBFF - FSPF/FBFF

Figure 40. DB Statistics after tuning (Part 3 of 9)

200

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 (ROOT ADDRESSABLE AREA) NBR I/O TO READ ***AT RANDOM*** THE RETRIEVED SEGMENTS OF ONE DB RECORD WITH 4 PCB-BUFFERS

"DB STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 4 FABHC00 - V1.R2

DB RECORD LENGTH (INCL PREFIXES OF SEGMENTS) EXPRESSED IN BLOCKSIZE/CI-SIZE UNITS (ONE BLKSIZE/CI-SIZE = 4,096 BYTES) LENGTH NBR DB-R PCT CUM PCT ---------------------------------------------<= <= <= <= <= 1/16 2/16 3/16 4/16 5/16 25 339 3,237 714 157 .55 7.58 72.38 15.96 3.51 .55 8.13 80.52 96.48 100.00

NBR IO NBR DB-R PCT CUM PCT ----------------------------------------------

<= <= <= <= <=

1 2 3 4 5

3,978 384 81 23 4

88.95 8.58 1.81 .51 .08

88.95 97.54 99.35 99.86 99.95 ----------------------------------------------

<= 6 2 .04 100.00 ----------------------------------------------

Figure 40. DB Statistics after tuning (Part 4 of 9)

Chapter 10. Using Database Tuning Statistics

201

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 (OVERFLOW AREA) *** DBDGEN SPECIFICATIONS:

"DB STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 5 FABHC00 - V1.R2

DB-ORG HDAM DDNAME DSHDAM01 (OVFLW AREA) BLOCK/CI-SIZE 4,096 FREE SPACE - FREE BLOCK FREQUENCY FACTOR(FBFF) 0 - FREE SPACE PERCENTAGE FACTOR(FSPF) 0 *** KEY INDICATORS FOR QUALITY OF PHYSICAL ORGANIZATION: AVG NBR I/O IN OVFLW AREA - PER DB-R IN OVFLW AREA - PER DB-R IN THIS DB AVG DB-R LENGTH IN OVFLW AREA - PER DB-R IN OVFLW AREA - PER DB-R IN THIS DB ACTUAL PCT FREE SPACE DEFINED PCT FREE SPACE *** I/O SUMMARY: NBR I/O IN OVFLW AREA NBR DB-RECORDS - WITH I/O IN OVFLW AREA - IN THIS DB *** DB-RECORD LENGTH SUMMARY: TOTAL DB-R LENGTH IN OVFLW AREA - LENGTH (BYTES) NBR DB-RECORDS - IN OVFLW AREA - IN THIS DB 85,890 63 4,472 84 63 4,472 1.33 .01 1,363 19 4.69 ACTUAL PCT FREE SPACE = (ALLOCED DASD - TOTAL DB-R)/ALLOCED DASD * 100 .00 DEFINED PCT FREE SPACE = FSPF + 100/FBFF - FSPF/FBFF

Figure 40. DB Statistics after tuning (Part 5 of 9)

202

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06 STATISTICS FOR DB=HDAM0010 (OVERFLOW AREA) NBR I/O TO READ ***AT RANDOM*** THE RETRIEVED SEGMENTS OF ONE DB RECORD WITH 4 PCB-BUFFERS

"DB STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 6 FABHC00 - V1.R2

DB RECORD LENGTH (INCL PREFIXES OF SEGMENTS) EXPRESSED IN BLOCKSIZE/CI-SIZE UNITS (ONE BLKSIZE/CI-SIZE = 4,096 BYTES)

NBR IO NBR DB-R PCT CUM PCT ----------------------------------------------

LENGTH NBR DB-R PCT CUM PCT ---------------------------------------------<= 1/16 <= 2/16 <= 3/16 <= 4/16 <= 5/16 <= 6/16 <= 7/16 <= 8/16 <= 9/16 <=10/16 <=11/16 <=12/16 <=13/16 <=14/16 <=15/16 18 4 11 4 5 3 3 1 2 2 2 0 1 1 0 0 6 28.57 6.34 17.46 6.34 7.93 4.76 4.76 1.58 3.17 3.17 3.17 .00 1.58 1.58 .00 .00 9.52 28.57 34.92 52.38 58.73 66.66 71.42 76.19 77.77 80.95 84.12 87.30 87.30 88.88 90.47 90.47 90.47 100.00

<= 1 44 69.84 69.84 <= 2 17 26.98 96.82 <= 3 2 3.17 100.00 ----------------------------------------------

<= <=

1 2

----------------------------------------------

Figure 40. DB Statistics after tuning (Part 6 of 9)

Chapter 10. Using Database Tuning Statistics

203

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"RANDOMIZING STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 1 FABHC00 - V1.R2

STATISTICS FOR RETRIEVED ROOTS OF DB=HDAM0010 WITH RANDOMIZER=DFSHDC10 *** DBDGEN SPECIFICATIONS: NBR RAPS PER BLOCK/CI HIGHEST BLOCK/CI IN RAA BYTES-LIMIT BLOCK/CI-SIZE FREE SPACE: - FREE BLOCK FREQUENCY FACTOR(FBFF) - FREE SPACE PERCENTAGE FACTOR(FSPF) *** KEY INDICATORS FOR QUALITY OF RANDOMIZING: AVG NBR I/O - PER DB-R - ON RAP CHAIN PER ROOT - ON RAP CHAIN PER RAP CHAIN - IN RAA PER DB-R - IN OVERFLOW AREA PER DB-R NBR OF ACCESSED RAPS WHICH ARE USED - NBR - PCT OF ACCESSED RAPS NBR OF ACCESSED ROOTS IN OVERFLOW AREA - NBR - PCT OF ACCESSED ROOTS PACKING DENSITY OF RAA NBR OF RAPS PER ROOT AVG POSITION OF ROOT SEGMENTS ON RAP SYNONYM CHAINS AVG NUMBER OF SYNONYMS ON RAP SYNONYM CHAINS AVG DB-R LENGTH 1.16 1.06 1.07 1.14 .01 3,347 47.81 0 .00 72.35 1.56 1.30 1.33 682 7 1,000 1,280 4,096 0 0

Figure 40. DB Statistics after tuning (Part 7 of 9)

204

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"RANDOMIZING STATISTICS" DATE: 10/26/2007 TIME: 20.09.01

PAGE: 2 FABHC00 - V1.R2

STATISTICS FOR RETRIEVED ROOTS OF DB=HDAM0010 WITH RANDOMIZER=DFSHDC10 NBR I/O ON RAP CHAIN TO READ ***AT RANDOM*** THE ROOT SEGMENTS WITH 4 PCB-BUFFERS NBR IO NBR ROOTS PCT CUM PCT ---------------------------------------------<= <= <= <= 1 2 3 4 4,188 271 12 1 93.64 6.04 .26 .02 93.64 99.70 99.97 100.00

POSITION OF ROOT SEGMENTS ON RAP CHAINS POSITION NBR ROOTS PCT CUM PCT ---------------------------------------------<= <= <= <= <= <= 1 2 3 4 5 6 3.347 917 175 27 5 1 74.84 20.50 3.91 .60 .11 .02 74.84 95.34 99.26 99.86 99.97 100.00

Figure 40. DB Statistics after tuning (Part 8 of 9)

Chapter 10. Using Database Tuning Statistics

205

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"DB RECORD LENGTH DISTRIBUTION" DATE: 10/26/2007 TIME: 20.09.01 DATABASE RECORD LENGTH DISTRIBUTION FOR DB=HDAM0010

PAGE: 1 FABHC00 - V1.R2

LENGTH NBR DB-R PCT CUM PCT --------------------------------------------------<= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= <= 500 550 600 650 700 750 800 850 900 950 1000 1050 1100 1150 1200 1250 1300 1350 1400 1450 1500 1600 1700 1800 1900 2000 2500 3000 3500 4000 5000 6000 7000 8000 349 740 264 1,355 260 551 176 329 113 82 81 34 32 12 18 9 7 4 5 3 3 1 1 3 4 6 7 7 3 5 2 2 2 2 7.80 16.54 5.90 30.29 5.81 12.32 3.93 7.35 2.52 1.83 1.81 .76 .71 .26 .40 .20 .15 .08 .11 .06 .06 .02 .02 .06 .08 .13 .15 .15 .06 .11 .04 .04 .04 .04 7.80 24.35 30.25 60.55 66.36 78.68 82.62 89.98 92.50 94.34 96.15 96.91 97.62 97.89 98.30 98.50 98.65 98.74 98.85 98.92 98.99 99.01 99.03 99.10 99.19 99.32 99.48 99.64 99.70 99.82 99.86 99.91 99.95 100.00

Figure 40. DB Statistics after tuning (Part 9 of 9)

Other factors influencing the performance of access to an HDAM database

The following sections describe other factors that influence the performance in the access to an HDAM database. Periodical database reorganization: The overflow area of an HDAM database tends to become physically disorganized, if a large amount of database segments are inserted into the overflow area after a database load or reload. You can detect the need for reorganization of an HDAM database by observing how the average number of I/Os per database record evolves over time. A substantial increase of the number of I/Os indicates a probable need for database reorganization. You can also detect the need for reorganization by looking at the Data Set I/O Statistics after a sequential processing of the database by FABHURG1, FABHFSU, or an HSSR application program. After such a processing, look in the Data Set I/O Statistics for the counters that describe the number of DIRECT IO and SEQ IO in the overflow area. (You will find this information only if the CAB buffer handler has been used and if an OVERFLOW CAB has been activated.) Large overflow areas

206

Users Guide

may benefit from a database reorganization if the number of direct I/Os in the overflow area is much higher than the number of sequential I/Os in the overflow area. Databases with long database records: For HDAM databases with a high percentage of very long database records (for example, 8 KB or more), it is difficult to achieve a low value for the average number of I/O per database record. Whether the database record length is high can be determined by looking at the DB Tuning Statistics; they provide the average database record length and a table with the distribution of the database record length. Some of the actions that can be taken, in order to limit the performance problems of long database records, are: v Define the bytes limit in such a way that: The root segment and a reasonable amount of dependent segments can be stored in the same block of the root addressable area as the root segment. The remaining dependent segments are stored in the overflow area. A practice sometimes used is to load the most often referred-to database segments in the root addressable area at database initial load or reload time; the less frequently referred-to database segments are then inserted after the initial load/reload. Sometimes less frequently accessed segment types can be stored in a separate data set group. Bytes limits larger than the block or CI size should not be used if the database administrator intends to store database roots in the majority of the blocks or CIs of the root addressable area. v Use a large block or CI size (for example, 12 KB). v Evaluate usage of database segment compression in order to reduce the average size of database records. v Evaluate changes to the database design in order to reduce the average size of database records. v Evaluate usage of multiple data set groups. Compressed segments: Using a compression exit routine in order to store the segments on DASD in a compressed format can be useful, especially if the compression can significantly reduce the average database record size in such a way that the average number of database I/Os required to read at random all database segments of a database record can be lowered. When using compression routines, beware of segment splits created by replace calls that extend the compressed size of a database segment. Some protection against such replace calls can be achieved by avoiding high packing densities in the root addressable area and by defining enough free space for nonprimary data set groups. Inefficient space suballocation for the Sequential Subset Randomizer: The quality of the randomizing with the Sequential Subset Randomizer depends on a reasonable suballocation of space to each subset of database records. The output of the FABIGEN and of the SS-STATS statistics of HSSR Engine can be used to compare: v The relative amount of space that has been allocated during FABIGEN to each subset (see per mill figures in the compilation output of the FABIGEN).

Chapter 10. Using Database Tuning Statistics

207

v The relative amount of DASD space occupied by all database segments of one subset (see per mill figures of the SS-STATS). In case of large discrepancies, the database might need to be reloaded after a change of the space suballocations for the FABIGEN.

Tuning a HIDAM database

This section explains how to tune a HIDAM database.

Average number of I/O operations per database record

Obviously, a database can be considered to be efficiently organized, if the average number of I/O operations required to read at random all database segments of one database record is low. The average number of I/Os required to read at random all database segments of one database record is one of the most important indicators for the quality of the physical organization of the database. This average number of I/O is printed by the DB Tuning Statistics in Figure 35 on page 178, to the right of the phrase "AVG NBR I/O IN THIS DB" (note that HSSR Engine ignores I/Os required to access the index of the HIDAM database record). By looking at this average number in the DB Tuning Statistics, the database administrator can very rapidly see whether a database is efficiently organized. For an ideal database consisting of one single data set group, this average number would be 1.0. In real life, this ideal value of 1.0 can seldom be achieved and the average number of database I/Os per database record will be higher. As a general rule of thumb, the database can be considered to be fairly well organized if the average number of I/Os per database record is below: v 1.10 (for databases with an average database record length below one 10th of the block or CI size) v 1.20 (for databases with larger database record lengths) For numbers above 1.10 or 1.20, the database can often be considered to be poorly organized. In this case, the following questions should be asked in order to find the reason for a poor organization: 1. Is a database reorganization overdue in order to reduce database segment scattering? (See Periodical database reorganization on page 208 for details.) 2. Is the amount of free space specified during DBDGEN sufficient? (See Free space specifications on page 209 for details.) 3. Is the block size or CI size appropriate for the database record lengths of this database? (See CI size and block size on page 209 for details.) 4. Is the database record length excessive? (See Databases with long database records on page 209 for details.)

Periodical database reorganization

An HIDAM database tends to become physically disorganized if a high amount of database segments are inserted after a database load or reload.

208

Users Guide

You can detect the need for a reorganization of an HIDAM database by observing how the average number of I/Os per database record evolves over time. A substantial increase of the number of I/Os indicates a probable need for database reorganization. You can also detect the need for a reorganization of the database by looking at the Data Set I/O Statistics after a sequential processing or unloading of the database. After such a processing, look in the Data Set I/O Statistics for those counters that describe the number of DIRECT IO and SEQ IO (you will find this information only if the CAB buffer handler has been used). Databases might benefit from a database reorganization if the number of direct I/Os is higher than the number of sequential I/Os.

Free space specifications

Specification of enough free space (both in form of free space in each block or CI and in the form of a free block frequency factor) allows the support of more database inserts between two database reorganizations. The DB Tuning Statistics shows (for an example, see the top portion of Figure 35 on page 178): v How much free space has been specified in each block or CI v Whether every nth block or CI has been left entirely free. The DB Tuning Statistics allows also for the comparison of the actual percentage of free space (ACTUAL PCT FREE SPACE) and the defined percentage of free space (DEFINED PCT FREE SPACE). You might wish to observe how the actual percentage of free space is reduced as the database becomes older and older.

CI size and block size

The current CI size/block size is shown in the top portion of Figure 35 on page 178. As a general rule of thumb, use a 4 KB CI/block size for the data portion of HIDAM. However, if the average database record length is more than 1000 bytes (that is, larger than 1/4th of the block or CI size), then an increase of the block or CI size from 4 KB to 8 KB might improve the performance of HIDAM database accesses. In these cases an increase of the CI size/block size from 4 KB to 8 KB can often reduce the number of I/O operations (but will increase slightly the time of an I/O operation). CI/block sizes larger than 8 KB should be an exception (for example, for very large average database record sizes).

Databases with long database records

For HIDAM databases with a high percentage of very long database records (for example, 32 KB or more), it is difficult to achieve a low value for the average number of I/O per database record. Some of the actions that can be taken to limit the performance problems of long database records are: v Use a large block or CI size (for example, 12 KB) v Evaluate usage of database segment compression in order to reduce the average size of database records

Chapter 10. Using Database Tuning Statistics

209

v Evaluate storage of the most often referred-to database segments in the same block or CI as the root. The less frequently referred-to database segments can be inserted after the initial load/reload or can be stored in another data set group. v Evaluate changes to the database design in order to reduce the average size of database records.

Tuning a HISAM database

This section explains how to tune a HISAM database.

Average number of I/O operations per database record

Obviously, an HISAM database can be considered to be efficiently organized if the average number of I/O operations required to read, at random, all database segments of one database record is low. The average number of I/Os required to read at random all database segments of one database record is one of the most important indicators for the quality of the physical organization of the database. This average number of I/O is printed by the DB Tuning Statistics, as shown in Figure 35 on page 178, right of the phrase "AVG NBR I/O IN THIS DB." (HSSR Engine counts the reading of a KDSD record as a single I/O and ignores I/Os required to access the VSAM index CIs.) By looking at this average number in the DB Tuning Statistics, the database administrator can very rapidly see whether a database is efficiently organized. For an ideal HISAM database, this average number would be 1.0. In real life, this ideal value of 1.0 can seldom be achieved and the average number of database I/Os per database record will be higher. For numbers above 1.30, the HISAM database can often be considered as poorly organized. In this case, the following questions should be asked in order to find the reason for a poor organization: 1. Is the KSDS record length appropriate? (See KSDS record length (HISAM) on page 210 for details.) 2. Is a database reorganization overdue in order to reduce database segment scattering? (See Periodical database reorganization on page 211 for details.) 3. Is the ESDS CI size appropriate for the database record lengths of this DB? (See ESDS CI size on page 211 for details.)

KSDS record length (HISAM)

The database administrator needs to perform trade-offs when determining the KSDS record length for a HISAM database. Selecting a large KSDS LRECL allows reduction of the number of database records that cannot be stored entirely in the KSDS record. This will reduce the average number of I/Os per database record. On the other hand, selection of a KSDS LRECL that is too large may represent a waste of DASD space, if a high percentage of database record do not fill reasonably the KDSD record. The table containing the distribution of the database record length (see Figure 39 on page 188) provides assistance in determining a reasonable KSDS LRECL.

210

Users Guide

Note: By default, HSSR Engine prints only a table with following ranges of database record length: 1/16, 2/16, 3/16, and so on of the ESDS CI size. These default ranges of database record lengths are seldom sufficient to determine a good KSDS LRECL. To get a table with more appropriate ranges of database record length, provide in the HSSRLDEF data set control statements defining database record length ranges of your choice (for example, database record length ranges of 50 or 100 bytes).

Periodical database reorganization

The ESDS portion of an HISAM database tends to become physically disorganized if a large amount of database segments are inserted after a database load or reload. The need for a reorganization of the ESDS portion of an HISAM database can be detected by observing how the average number of I/Os per database record evolves over time. A substantial increase of the number of I/Os indicates a probable need for database reorganization. The need to reorganize the ESDS part of a HISAM database can also be detected by looking at the Data Set I/O Statistics after a sequential processing or unloading of the database. After such a processing, look in the Data Set I/O Statistics for the counters that describe the number of DIRECT IO and SEQ IO. (You will find this information only if the CAB buffer handler has been used.) Databases might benefit from a database reorganization if the number of direct I/Os is higher than the number of sequential I/Os. Note that the need for a reorganization of the KSDS portion of an HISAM database can be determined by looking at the number of CI splits and CA splits of the KSDS (these numbers can be found in LISTCAT listings of IDCAMS).

ESDS CI size
The current ESDS CI size is shown in the top portion of Figure 35 on page 178. As a general rule of thumb, use a 4 KB CI size for the ESDS portion of HISAM database. However, for long database records, an increase of the ESDS CI size from 4 KB to 8 KB might improve the performance of HISAM database accesses.

How to determine randomizing parameters by using a reasonable first guess method

This section is provided to assist database administrators who do not have experience with the specifications of efficient HDAM randomizing parameters. This section contains general rules of thumb for using a "first guess" method to determine the values of the following parameters, which have an impact on the randomizing performance of an HDAM database: v The block or CI size v The bytes limit v The number of blocks or CIs in the root addressable area v The number of RAPs per block or CI The following discussion assumes that the values of these parameters are determined in the sequence listed here.

Chapter 10. Using Database Tuning Statistics

211

After loading or reloading the database with the randomizing parameters determined by the first-guess method, the database administrator can obtain DB Tuning Statistics in order to verify the efficiency of the first-guess randomizing parameters. Then, if necessary, the randomizing parameters could be adjusted with an iterative, experimental "try and see" process (that is, change the value of a randomizing parameter, reload the database, and observe in the DB Tuning Statistics the effect of the changed parameter).

Determining the block or CI size

A recommended general rule of thumb is a 4 KB block or CI size. However, if the average database record length reported in the DB Tuning Statistics is larger than 800 bytes, then a larger block or CI size could be tried. v If the average database record length is in the range of 8001600 bytes, an 8 KB block or CI size is often a better bet. v If the average database record length is in the range of 16002400 bytes, a 12 KB block or CI size should be investigated. v For average database record lengths substantially longer than 2400 bytes, the first-guess method described in this section often does not apply. Block or CI sizes larger than 12 KB should be an exception. Block or CI sizes smaller than 4 KB are seldom reasonable.

Determining the bytes limit

As explained in Bytes limit on page 194, the database administrator needs to perform trade-offs when specifying a bytes limit. To define a reasonable bytes limit, the database administrator should check the distribution of the database record lengths in the DB Tuning Statistics. The table with the distribution of the database length records should be used in order to determine the bytes limit in such a way that: v The bytes limit is large enough, in order to allow for a high percentage of database records the storage of all their database segments in the root addressable area. v The bytes limit is small enough in order to prevent the cascading effect described in Bytes limit on page 194. If the average database record length is around 1/5th of the block or CI size, then (as a first guess, which could be revised by experiments by the database administrator) the bytes limit should not be larger than twice the database record length. For smaller average database record lengths, the ratio between bytes limit and average database record length can be larger than 2. For larger average database record lengths, the ratio between bytes limit and average database record length should be smaller than 2. v The bytes limit should not be larger than the block or CI size.

Determining the number of blocks or CIs in the root addressable area

In order to determine the number of blocks or CIs in the root addressable area, the database administrator must have previously determined the block or CI size and the bytes limit (as described in Determining the block or CI size and Determining the bytes limit).

212

Users Guide

Then the database administrator should: 1. Select a target packing density for the root addressable area. As described in Packing density of the root addressable area on page 191, a good bet would be a packing density of 75% (for databases with an average database record length smaller than one tenth of the block or CI size) or of 70% (for databases with a larger average database record length). 2. Estimate the total lengths (expressed in bytes) of all the database segments that should be stored in the root addressable area. This estimate can be done by using: a. The total lengths of all database segments (expressed in bytes) reported by the DB Tuning Statistics b. The selected bytes limit c. The distribution of the database record lengths reported by the DB Tuning Statistics Example: a. In Figure 35 on page 178, the reported total length of all database segments is 3,052,423. b. As suggested at the end of Bytes limit on page 194, a bytes limit of 1208 bytes can be selected. c. As shown in Figure 35 on page 178, 98.59% of database records have a database record length smaller than or equal to 1280 bytes (5/16 bytes of the CI size). In this example, based on the above figures, you can estimate the total length of all database segments that should be stored in the root addressable areas; approximately 98.6% of 3,052,423 bytes. 3. Divide the total length of database segments to be stored in the root addressable area by the target packing density in order to obtain the size (in bytes) of the root addressable area. 4. Divide the size in bytes of the root addressable area by the block or CI size in order to obtain the number of blocks or CIs in the root addressable area.

Determining the number of RAPs per block/CI

As a general rule of thumb, the total number of RAPs should be around 1.5 times the number of database records. In case of doubt, it is better to specify too many than too few RAPs. Since the number of database records is printed by the DB Tuning Statistics, the database administrator can multiply this number by 1.5 in order to obtain the desired total number of RAPs. Then, in order to obtain the number of RAP per block or CI, the total number of RAPs should be divided by the number of blocks or CIs in the root addressable area (and rounded up to the next integer).

Creating a database extract with FABHEXTR

FABHEXTR allows the creation of a small database extract from a large database. The database extract can be used to perform database tuning experiments. Creation of a smaller extract database can be useful when the database administrator intends to tune the randomizing parameters of a large HDAM database through an interactive "try-and-see" process.

Chapter 10. Using Database Tuning Statistics

213

FABHEXTR is a user exit routine of the FABHURG1 database unload utility. Based on control statements, FABHEXTR directs the FABHURG1 utility to include, in its database unload output file, only a subset of the real-life database records. The unloaded database extract is then used as input to the standard IMS HD Reload utility, which will create an extract database. Assume, for example, you have a large HDAM database with 1 million database records, which takes 20 hours to reorganize. An iterative try-and-see tuning process for such a huge database is not realistic because of the large amount of time required for the database reorganization of each interaction step. However, if the database administrator creates a small database extract consisting of 5000 database records, then the database reorganization for this database extract no longer takes 20 hours, but only 6 minutes. The database administrator can then perform a lot of different experiments with different values for the randomizing parameters with this small database. The user of FABHEXTR can define, in an EXTR control statement, the number (n) of consecutive database records that should be included in the extract database. Usually these will be the first n database records of the original database. However, you can specify, in an optional SKIP control statement, that the FABHURG1 utility should skip m database records before extracting n consecutive database records. For a HALDB, an alternative way to extract database records from a HALDB partition is provided. The user can define, in a PARTEXTR control statement, the number (n) of consecutive database records that should be extracted from each HALDB partition. The first n database records of each partition are extracted and put in the same unloaded data set.

JCL of the FABHEXTR exit routine

The use of the FABHEXTR exit routine requires, in addition to the usual JCL for the FABHURG1 utility, the following: v A SYSIN DD statement for the data set of FABHURG1 control statements. This data set must contain an EXIT control statement with the name of the FABHEXTR exit routine. v An HSSREXTR DD statement for the data set of FABHEXTR control statements. This data set must contain either an EXTR control statement describing the number of database records to be extracted from the entire database, or a PARTEXTR control statement describing the number of database records to be extracted from each HALDB partition. If an EXTR control statement is specified, this data set can also contain a SKIP control statement.

Providing an EXIT control statement

The following JCL is required to activate the FABHEXTR exit routine during an HSSR database unload with FABHURG1:
//SYSIN DD * EXIT FABHEXTR Figure 41. EXIT FABHEXTR control statement

The control statement must have the following format: v Columns 14 must contain EXIT. v Column 5 must contain a blank.

214

Users Guide

v Columns 613 must contain FABHEXTR.

Chapter 10. Using Database Tuning Statistics

215

Providing HSSREXTR control statements

An HSSREXTR DD statement is required by the FABHEXTR exit routine. This DD statement must point to a sequential data set or to a member of PDS, which contains control statements. The data set must contain either an EXTR control statement or a PARTEXTR control statement. If it contains an EXTR control statement, it can also contain a SKIP control statement. A PARTEXTR control statement can be specified only for HALDB.
//HSSREXTR DD EXTR nnnnnnnn SKIP mmmmmmmm or //HSSREXTR DD * PARTEXTR nnnnnnnnn Figure 42. HSSREXTR control statements *

The EXTR control statement must have the following format: v Columns 14 must contain EXTR. v Column 5 must contain a blank. v The number of consecutive database records to be extracted must be coded from column 6 onward. The number must be less than or equal to 999999999. The optional SKIP control statement that can be specified with the EXTR control statement must have the following format: v Columns 14 must contain SKIP. v Column 5 must contain a blank. v The number of database records to be skipped at the beginning of the database must be coded from column 6 onward. The number must be less than or equal to 999999999. The PARTEXTR control statement must have the following format: v Columns 1-8 must contain PARTEXTR. v Column 9 must contain a blank. v The number of consecutive database records to be extracted from each HALDB partition must be coded from column 10 onward. The number must be less than or equal to 999999999. No leading zeros need to be specified, but the number must be left-justified. This control statement is valid only for HALDB. If the number of database records in a partition is less than the number specified in the PARTEXTR control statement, all records in the partition are unloaded. v You cannot specify more than one PARTEXTR control statement. v If the PARTEXTR control statement is specified, you cannot specify both the EXTR and SKIP control statement concurrently. Notes: 1. If the extracted database is being used for experimenting with the tuning of HDAM randomizing parameters, the database administrator will need to use a test version of the DBD that is smaller than the root addressable size of the original database. For example, if the original database contains 200,000 blocks in the root addressable area, and if the extract database will contain only one hundredth of the original

216

Users Guide

database records, then the size of the root addressable area of the extract database should be reduced by the same proportion of one hundred and should be set to 2000 blocks. 2. If the database is involved in a logical relationship, you must run (as for any other IMS database reorganization) the Database Pre-Reorganization utility (DFSURPR0) before reloading the database extract. The other IMS utilities (Database Scan, Database Prefix Resolution, Database Prefix Update) used to support logical relationships during a database reorganization should not be run. 3. Duplicate control statements are not allowed. PARTEXTR control statement must not be specified with either EXTR or SKIP control statement. 4. For HALDB, the order of the partitions to be processed is determined by the main logic of FABHURG1. If the partitions to be processed are restricted by the PARTITION control statement specified in SYSIN of FABHURG1, database records are unloaded from only the selected partitions. If you want to process all of the partitions, you should not specify the PARTITION control statement. 5. If the CO control statement is specified in HSSROPT DD and the PARTEXTR control statement is specified in HSSREXTR DD, the message FABH0205W is issued and the CO control statement is ignored. 6. If the PARTEXTR control statement is specified and one or more partitions of PHDAM or PHIDAM are in a HALDB OLR cursor-active status, FABHURG1 ends abnormally.

Sample JCL for creating a database unload extract

Figure 43 shows a sample JCL for creating an extract database.
//UNLOAD EXEC //SYSUT2 DD //SYSIN DD * EXIT FABHEXTR //HSSREXTR DD * EXTR 10000 //DBDD DD //* //* //* //RELOAD EXEC //STEPLIB DD //DFSRESLB DD //IMS DD //DFSUINPT DD //DBDD DD //... (other DD FABHULU,MBR=FABHURG1,DBD=dbdname DISP=(,PASS),DSN=&&UNLOAD,UNIT=SYSDA,SPACE=(CYL,(3,3))

DISP=SHR,DSN=user.db

PGM=DFSRRC00,PARM=ULU,DFSURGL0,dbdname ... .. DISP=SHR,DSN=IMSVS.TEST.DBDLIB DISP=(OLD,DELETE),DSN=&&UNLOAD DISP=(,CATLG),DSN=extract.db,....... statements required by Reload Utility)

Figure 43. Sample JCL for creating an extract database

Notes on this sample: 1. For the first job step, in addition to the usual JCL required to do an unload with the FABHURG1 Unload utility, you see: a. A SYSIN data set with an EXIT control statement, which requests the activation of FABHEXTR.

Chapter 10. Using Database Tuning Statistics

217

b. An HSSREXTR data set with an EXTR control statement, which requests that the (first) 10000 database records be included in the database unload extract. 2. The second job step is a standard database reload performed with the standard IMS HD Reload utility DFSURGL0. Notice, however, that the IMS DD statement will point to a DBDLIB containing the test version of the DBD, which is used for the tuning experiments.

218

Users Guide

Chapter 11. Using the Parallel Scan Facility of FABHFSU

This chapter describes how to use the Parallel Scan Facility of FABHFSU. FABHFSU provides this facility for the compatibility with JCL written for FSU II. Topics: v v v v v v v v v Overview of Parallel Scan Facility Steps necessary to run FABHFSU in PSF mode on page 221 Restrictions on page 222 JCL for utilities used for PSF on page 223 FABHPSFM program on page 226 FABHPSFC program on page 230 FABHFSU utility on page 237 FABHPSFS program on page 238 Example on page 245

Overview of Parallel Scan Facility

The FABHFSU Parallel Scan Facility (PSF) makes possible a significant reduction in the amount of elapsed time required to scan multivolume databases. It does so by scanning separate, predefined portions of the database simultaneously. A PSF run results in multiple output data sets that must be combined to represent the output of a complete scan. PSF supports only HDAM and HIDAM databases; PHDAM and PHIDAM databases are not supported. Note: For the explanation of how to unload partitions of a PHDAM or PHIDAM database in parallel, see Chapter 7, Processing High Availability Large Databases, on page 103. The following four programs are used in Parallel Scan Facility: FABHPSFM FABHPSFC Provides assistance to the user in determining how to divide the database into portions to be scanned by PSF phases. Processes the control statements that define the scan and builds a Scan Control data set that is used by the remaining functions to obtain and record information about the scan. In the PSF mode, FABHFSU performs individual scan phases, which can run separately or concurrently to unload a multivolume database. In the PSF mode, the information is obtained from the Scan Control data set created by FABHPSFC. Creates summarized statistics and data set concatenation sequences. For an unload format, prepares the header and trailer records required. This is the last program to be run.

FABHFSU

FABHPSFS

Because all facilities provided for a typical FABHFSU run are available for individual PSF scan phases, PSF can benefit as follows: v Earlier detection of severe errors that must not be bypassed. This is especially advantageous when the error is toward the end of the database or if there are multiple errors. v Reduced recovery time from database errors. This is possible because only the affected scan phases need to be rerun. Therefore, other scan phases (even those in which the beginning node is located beyond the point of error in the database) can continue to run while the errors are being analyzed or corrected.
Copyright IBM Corp. 2000, 2007

219

v Reduced recovery time from a permanent write error at unload time or a permanent read error at reload time. This is possible because only affected scan phases need to be rerun. If dual outputs are being created, this would not be relevant unless both formats encountered permanent errors or damages.

220

Users Guide

Steps necessary to run FABHFSU in PSF mode

To run FABHFSU in PSF mode, follow these steps (see Figure 44 on page 222, which shows the steps necessary to run a 3-phase PSF run): Step 1 Run the FABHPSFM program as an MVS batch job to provide information about the database extents. This helps you to determine phase limit definitions. This step is optional and is provided as an aid only. Run the FABHPSFC program as an MVS batch job to define the scan parameters and the phase data in the Scan Control data set.

Step 2

Step 3A, 3B, 3C... Run the specified number of FABHFSU jobs or job steps (in this case, three jobs) in any sequence or, preferably, in parallel. The number of FABHFSU jobs to run is specified as input for FABHFSU. Step 4 Run the FABHPSFS program as an MVS batch job to obtain the summarized statistics, output data set concatenation sequences, and header and trailer data set (if applicable).

The statistics generated by each phase in step 3 apply only to the portion of the data set processed by that phase. The summarized statistics generated in step 4 apply to the entire database. Step 4 usually does not run until all of the step 3 phases have completed, but it does provide a status report indicating where the individual phases stand. Step 4 can be appended to each step 3 phase as a conditional job step such that it runs only when the last phase completes.

Chapter 11. Using the Parallel Scan Facility of FABHFSU

221

Figure 44. Execution of a 3-Phase PSF job

Restrictions
The restrictions on FABHFSU in standard mode apply also to FABHFSU in PSF mode. (See Restrictions on page 50.) Furthermore, FABHFSU does not support the unloading of an HISAM database under PSF mode.

222

Users Guide

JCL for utilities used for PSF

This section explains the JCLs for utilities that are used for Parallel Scan Facility.

FABHPSFM JCL
The FABHPSFM program is an MVS batch program. The execution of this program is optional. The DD statements listed in Table 20 are required.
Table 20. FABHPSFM DD statements DDNAME IMS CARDIN ddname3 ddname4 PRNTOUT SYSUDUMP Use Input Input Input Input Output Output LRECL=133 Format Partitioned data set (DSORG=PO) LRECL=80 Need Required Required Required Optional Required Optional

EXEC The EXEC statement must be in the following format:

// EXEC PGM=FABHPSFM

IMS DD This required DD statement defines the library containing the DBD that describe the database to be scanned. CARDIN DD This required DD statement defines the input data set containing control statements for FABHPSFM (see FABHPSFM CARDIN data set on page 226). ddname3 DD This required DD statement defines the primary data set of the DBD that is specified in the CARDIN DD statement. ddname4 DD If the database is an HIDAM database, this DD statement is required to define the index data set of the DBD that is specified in the CARDIN DD statement. PRNTOUT DD This required statement defines the output data set to which FABHPSFM writes error messages and segment statistics (see FABHPSFM PRNTOUT data set on page 228). The data set can be defined as:
//PRNTOUT DD SYSOUT=A

SYSUDUMP DD This optional DD statement defines the dump data set for this program. The data set can reside on a printer, tape, or direct access device, or be routed through the output stream.

FABHPSFC JCL
The FABHPSFC program is an MVS batch program. The DD statements listed in Table 21 are required.
Table 21. FABHPSFC DD statements DDNAME IMS Use Input Format Partitioned data set (DSORG=PO) Need Required

Chapter 11. Using the Parallel Scan Facility of FABHFSU

223

Table 21. FABHPSFC DD statements (continued) DDNAME CARDIN CNTLDD Use Input Output Format LRECL=80 LRECL=(480 * Number of phases) + 412 BLKSIZE=LRECL+4 RECFM=VB LRECL=133 Need Required Required

PRNTOUT SYSUDUMP

Output Output

Required Optional

EXEC The EXEC statement must be in the following format:

// EXEC PGM=FABHPSFC

IMS DD This required DD statement defines the library containing the DBD that describe the database to be scanned. CARDIN DD This required DD statement defines the input data set containing control statements for FABHPSFC (see FABHPSFC CARDIN data set on page 231). CNTLDD DD This required DD statement defines the output Scan Control data set, which has the following format:
//CNTLDD DD DSN=fsuscancntl,...

DSN is the user data set name assigned when the Scan Control data set is created by FABHPSFC. PRNTOUT DD This required DD statement defines the output data set to which FABHPSFC writes error messages and segment statistics (see FABHPSFC PRNTOUT data set on page 234). The data set can be defined as:
//PRNTOUT DD SYSOUT=A

SYSUDUMP DD This optional DD statement defines the dump data set for this program. The data set can reside on a printer, tape, or direct access device, or be routed through the output stream.

FABHFSU JCL
The DD statement in Table 22, in addition to the DD statements used in standard mode (see JCL requirements for FABHFSU on page 54), is required for FABHFSU in PSF mode.
Table 22. FABHFSU DD statements for PSF mode DDNAME CNTLDD Use Input and Output Format LRECL=80 Need Required for PSF

CNTLDD DD This DD statement defines the input and output Scan Control data set, which has the following format:
//CNTLDD DD DSN=fsuscancntl,DISP=SHR

224

Users Guide

DSN is the user data set name assigned when Scan Control Data Set is created by FABHPSFC.

FABHPSFS JCL
The FABHPSFS program is an MVS batch program. The DD statements listed in Table 23 are required.
Table 23. FABHPSFS DD statements DDNAME IMS CARDIN CNTLDD ddname5 ddname6 PRNTOUT SYSUDUMP Use Input Input I/O Output Output Output Output LRECL=133 Format Partitioned data set (DSORG=PO) LRECL=80 Created by FABHPSFC Need Required Required Required Required Optional Required Optional

EXEC The EXEC statement must be in the following format:

// EXEC PGM=FABHPSFS

IMS DD This required DD statement defines the library containing the DBD that describe the database to be scanned. CARDIN DD This required DD statement defines the input data set containing control statements for FABHPSFS (see FABHPSFS CARDIN data set on page 238). CNTLDD DD This required DD statement defines the input and output Scan Control data set, which has the following format:
//CNTLDD DD DSN=fsuscancntl,...

DSN is the user data set name assigned when the Scan Control data set is created by FABHPSFC. ddname5 DD This DD statement defines the data set containing the trailer record of the unloaded database. One DD statement is required for each PSB control statement in the CARDIN DD statement defined by FABHPSFC. (The name of ddname5 must be the same as the one specified in the ddname1 field of the PSB control statement.) ddname6 DD This DD statement defines the data set containing the header record of the unloaded database. When the separate header record option is specified on the CTL control statement of CARDIN DD statement defined by FABHPSFC, this DD statement is required. One DD statement is required for each PSB control statement in the CARDIN DD statement defined by FABHPSFC. (The name of ddname6 must be the same as the one of ddname5, except the first two characters must be 'XH'.) PRNTOUT DD This required DD statement defines the output data set to which FABHPSFS
Chapter 11. Using the Parallel Scan Facility of FABHFSU

225

writes error messages and segment statistics (see FABHPSFS PRNTOUT data set on page 240). The data set can be defined as:
//PRNTOUT DD SYSOUT=A

SYSUDUMP DD This optional DD statement defines the dump data set for this program. The data set can reside on a printer, tape, or direct access device, or be routed through the output stream.

FABHPSFM program
This section describes the input and output for the FABHPSFM program.

Input
The control statements for the FABHPSFM program are specified in the CARDIN data set.

FABHPSFM CARDIN data set

This section explains the FABHPSFM CARDIN data set.

Function
The FABHPSFM program provides information to assist you in determining how to divide the database into portions to be scanned by PSF phases. This information is useful as input for FABHPSFC. FABHPSFM supplies the following extent information for the primary data set group of an HDAM or HIDAM database: v Volume serial number of each extent v Starting relative block for each extent v Number of relative block for each extent v High allocated block v First overflow block (HDAM only) v High used CI (VSAM only)
Table 24. FABHPSFM control statements Control statements Function MAP END Directs the FABHPSFM program. Specifies end of FABHPSFM CARDIN control statements. Mode PSF PSF

Format
This data set contains 80-byte fixed-length records. The control statements can be coded in the input stream or accessed as a member of a partitioned data set.

MAP control statement

FABHPSFM is directed by the MAP control statement for the PSF. Only one MAP control statement can be used.

226

Users Guide

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 MAPdbdname dlidbd k oxxxxxxxxyy

Position 1 4

Description Code the MAP keyword to identify the MAP control statement. Code the database name that describes the physical database to be scanned. This required 8-character field is left-justified with trailing blanks. The DBD must specify ACCESS=HDAM or HIDAM. This 8-character entry dlidbd specifies the database name that describes the primary index of the HIDAM database. This entry is required for HIDAM databases. A secondary index which points to the HIDAM or the HDAM root segments can be specified instead of the primary index. In this case, the values of the search field of the index are shown in the FABHFSU PSF Extent Mapping report.

12

20

This 1-character entry k indicates the key type when the printed report is necessary. Keys longer than 80 bytes print in hex format regardless of the type specified. Use one of the following keywords: Keyword C X Description For character keys (default) For all types other than character keys.

23

The 1-character entry o selects the key option. Use one of the following keywords: Keyword Y A N D Description All keys within the search delta of the specified relative block are listed. All keys are listed. The select key option is not used. All keys within the search delta of the first block in the first extent on each volume beyond the first volume are listed. (This option scans the entire index once for each volume of the database.) Up to 10 keys that fall within the first 10 blocks of each extent are listed. Up to 20 keys that fall within the first 10 blocks of the first extent of each volume beyond the first volume are listed (default).

E V

24

The 8-digit numeric entry xxxxxxxx indicates the relative block for which all keys of that block plus any keys in the blocks within the specified search delta are listed. This value can range from 00000001 to 99999999. This entry is required if position 23 is specified with Y. The 2-digit numeric entry yy specifies the number of blocks on
Chapter 11. Using the Parallel Scan Facility of FABHFSU

32

227

either side of the base relative block for which keys are listed. This value can range from 00 to 99. This entry is required if the position 23 is specified with Y or D. For key option Y, the base relative block is indicated by the number in columns 2431; for key option D, each base relative block is the first block of the first extent of each volume beyond the first volume.

END control statement

The END control statement is the same as described in END control statement on page 66.

Output
Reports are produced in the PRNTOUT data set.

FABHPSFM PRNTOUT data set

This section explains the FABHPSFM PRNTOUT data set.

Function
The FABHPSFM program produces the following output reports for the primary data set group of HIDAM or HDAM database: v FABHFSU PSF Control Statements Report v FABHFSU PSF Extent Mapping Report

Format
The format is 133-byte fixed-length records. When coded in the JCL, block size must be a multiple of 133.

FABHFSU PSF Control Statements report

This report prints out the CARDIN control statements that were input to FABHPSFM (see Figure 45).

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF CONTROL STATEMENTS" DATE: 10/26/2007 TIME: 12.21.37

PAGE: 1 FABHPSFM - V1.R2

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 MAPMSHDP END

Figure 45. FABHFSU PSF Control Statements report

FABHFSU PSF Extent Mapping report

This report is useful when you specify the node point value in the NPT control statement as input for FABHPSFC (see Figure 46 on page 230 and Figure 47 on page 230). This report is produced for each output data set defined in the CARDIN data set. The content of the report is as follows: VOL SER Volume serial number of each extent EXTENT Sequential number of extent START CYL Starting cylinder for each extent

228

Users Guide

NO CYLS Number of cylinders START REL BLOCK or START REL CI Starting relative block number or CIs NO BLOCKS or NO CIS Number of blocks or CIs TRK/CYL Number of tracks per cylinder BLK/TRK Number of blocks per track HIGH ALLOC BLK or HIGH ALLOC CI High-allocated block or CI VSAM HI USED CI High-used CI (VSAM only). HDAM FST OFLO BLK or HDAM FST OFLO CI First overflow block or CI (HDAM only) BLK/CI Number of blocks per CI (VSAM only) REL BLOCK or REL CI Relative block number or CI number. This information is provided only for HIDAM databases. NODE POINT KEY CANDIDATES This shows the key candidates for the node point. This information is provided only for HIDAM databases. For a HDAM database without a secondary index, you should pick the relative block numbers as node point values from the above information. Normally the relative block numbers of the lowest extent of each new volume (beyond the first volume and up to the volume that contains the beginning of the overflow area) should be specified as node points. For a HIDAM database, you can specify the key value from NODE POINT KEY CANDIDATES as a node point value. The number of key candidates listed here depends on how you specify the options of the positions 23, 2431, and 3233 in the MAP control statement.

Chapter 11. Using the Parallel Scan Facility of FABHFSU

229

IMS HIGH PERFORMANCE UNLOAD 5655-E06 DDNAME = MSHDP VOL START NO SER EXTENT CYL CYLS IMS22C IMSDBT IMSDBT IMSDBT IMSDBT IMSDBT IMSDBT 0 1 2 3 4 5 6 1089 159 153 1661 1664 1677 1680 003 003 003 003 003 003 003 START REL CI 0 810 1,620 2,430 3,240 4,050 4,860 NO CIS 810 810 810 810 810 810 810

"FABHFSU PSF EXTENT MAPPING" DATE: 10/26/2007 TIME: 12.21.37

PAGE: 1 FABHPSFM - V1.R2

TRK/ BLK/ CYL TRK 15 15 15 15 15 15 15 18 18 18 18 18 18 18

HIGH ALLOC CI

VSAM HI USED CI

HDAM FST OFLO CI

BLK/CI 1 1 1 1 1 1

5,669

4,993

5,000

Figure 46. FABHFSU PSF Extent Mapping report (HDAM database)

IMS HIGH PERFORMANCE UNLOAD 5655-E06 DDNAME = ESDSDATA VOL START NO SER EXTENT CYL CYLS IMS31B 0 1609 002 START REL CI 0 NO CIS 540

"FABHFSU PSF EXTENT MAPPING" DATE: 10/26/2007 TIME: 14.48.06

PAGE: 1 FABHPSFM - V1.R2

TRK/ BLK/ CYL TRK 15 18

HIGH ALLOC CI 539

VSAM HI USED CI 4

HDAM FST OFLO CI

BLK/CI 1

Figure 47. FABHFSU PSF Extent Mapping report (HIDAM database) (Part 1 of 2)

IMS HIGH PERFORMANCE UNLOAD 5655-E06 VOL SER EXTENT IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B IMS31B 0 0 0 0 0 0 0 0 0 0 0 0 0 REL CI 0 0 0 0 0 0 0 0 0 0 0 0 0 NODE POINT KEY CANDIDATES KEY1004000 KEY106C000 KEY1084000 KEY113C000 KEY1174000 KEY120C000 KEY1274000 KEY129C000 KEY1344000 KEY138C000 KEY1414000 KEY147C000 KEY1484000

"FABHFSU PSF EXTENT MAPPING" DATE: 10/26/2007 TIME: 14.48.06

PAGE: 2 FABHPSFM - V1.R2

Figure 47. FABHFSU PSF Extent Mapping report (HIDAM database) (Part 2 of 2)

FABHPSFC program
This section describes the input and output for the FABHPSFC program.

230

Users Guide

Input
The control statements for the FABHPSFC program are specified in the CARDIN data set.

FABHPSFC CARDIN data set

This section explains the FABHPSFC CARDIN data set.

Function
The Control Data Set Creation program, FABHPSFC, must be run before any scan phase in the PSF mode. FABHPSFC processes all the FABHFSU control statements that define the scan. FABHPSFC also creates a Scan Control data set to contain information about the scan and control the execution of the multiple scan phases that follow. The scan is defined in the following terms: v The database to be scanned (DBD control statement) v The PSF specifications (CTL control statement) v The subareas to be scanned in parallel (NPT control statement) v The output formats to be produced (PSB control statement) FABHPSFC analyzes the input, creates the necessary information in the Scan Control data set, and reports the scan specifications and the limits of the indicated phases. Table 25 lists the FABHPSFC control statements.
Table 25. FABHPSFC control statements Control statements Function DBD CTL NPT PSB END Identifies database to be scanned. Directs the FABHPSFC program. Defines area of database to be scanned by the PSF. Identifies characteristics of output data sets to be created. Specifies end of FABHPSFC CARDIN control statements. Mode PSF PSF PSF PSF PSF

Format
This data set contains 80-byte fixed-length records. The control statements can be coded in the input stream or accessed as a member of a partitioned data set.

DBD control statement

The DBD control statement is the same as described in DBD control statement on page 57. However, in FABHPSFC, column 12 of the DBD control statement can contain the name of the primary index of the HIDAM database. A secondary index of the HIDAM or the HDAM database can be specified in the ULU region. The DBD control statement specified in FABHPSFC CARDIN data set applies to all phases of FABHFSU.

Chapter 11. Using the Parallel Scan Facility of FABHFSU

231

CTL control statement

The CTL control statement is required to run FABHPSFC for the PSF. Only one CTL control statement is used.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 CTLpsname yyyydddxxwcnnh

Position 1 4

Description Code the CTL keyword to identify the CTL control statement. Code a 18-character name of the Scan Control data set for the parallel scan operation. This name is defined in the CNTLDD DD statement, and is used in the entire PSF mode. All scan phases must specify this name in order to gain access to the Scan Control data set. This 8-character entry is left-justified with trailing blanks. This required 7-digit numeric entry yyyyddd allows the Julian date to be overridden. yyyy is the year and ddd is the day of the year. This entry specifies the last date that FABHFSU scan phases will be allowed access to the Scan Control data set unless the date is specifically overridden in the PSC control statement. This required 2-digit numeric entry xx indicates the total number of scan phases participating in this parallel scan operation. This value must equal the number of NPT control statements plus 1. The maximum value is shown in Table 26.

12

19

Table 26. Maximum value for the total number of scan phases Device type 3380 3390 9345 Value 67 67 67 Limiting factor Max BLKSIZE (32760) Max BLKSIZE (32760) Max BLKSIZE (32760)

21

The 1-character entry w determines whether messages are written to the operator console when all scan phases have been started or all scan phases have been completed. Use one of the following keywords: Keyword Y N Description Messages are written. No operator messages are written (default).

22

The 1-character entry c determines whether FABHFSU will verify the data set name of the DD statement, which is specified in the PSB control statement for the output data set. The data set name should match the following FABHFSU standard naming convention: FABHFSU DSN= nnnnnnnn.scanname.wwxx. PHASEyy FABHPSFS DSN= nnnnnnnn.scanname.ULxx.HEADER DSN= nnnnnnnn.scanname.ULxx.TRAILER

232

Users Guide

where: nnnnnnnn. = Optional high level qualifiers supplied by the user. If the length of the qualifiers is N, N+1 must be specified in position 21. Name assigned for the parallel scan operation in positions 411. The output format as specified in the respective PSB control statement (HS, UL, VB, VN). Relative occurrence number of the PSB control statement (01, 02, or 03) that defines this output. Number of the phase being run.

scanname = ww = vxx = yy =

Use one of the following keywords: Keyword Y N 23 Description The data set names used must conform to the naming standard. If not, the execution ends. No checking is performed on data set names (default).

This 2-digit numeric entry nn specifies the position (relative to 1) where the parallel scan name begins in the data set name of the DD statement. This value can range from 01 to 31. No checking is done before this position. This entry is required if the position 22 is specified with Y. The 1-character entry h determines whether the UL header record is to be written to a separate output data set by the FABHPSFS program. Use one of the following keywords: Keyword Y N Description The UL header record is written. No UL header record is written (default).

25

NPT control statement

The NPT node point control statement defines the portion of the database to be scanned for the PSF. For an indexed database, the node points are specified as keys. For an HDAM database with no secondary index, the node points are defined as relative block numbers of the CIs or blocks in the root addressable area. The NPT control statement must immediately follow the CTL control statement. If no NPT control statements are provided, the entire database will be scanned in a single phase. One or more NPT control statements can optionally be used.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 NPTtnodepointvalue NPTtllkeyvalue

Position 1

Description Code the NPT keyword to identify the NPT control statement.
Chapter 11. Using the Parallel Scan Facility of FABHFSU

233

This required 1-character entry t identifies the node point value type. It indicates the format of the node point value field. Use one of the following keywords: Keyword R C X Description Indicates that the node point value field contains the relative block number of the CI or block. Indicates that the node point value field contains keys in character format. Indicates the node point value field contains keys in hexadecimal display format.

Note: C and X are valid for the HIDAM database or the HDAM database that is associated with an index. If the secondary index is used to retrieve the root segments, specify the value in the search field of the secondary index instead of the root key. 580 This node point value field (76-character field) is required. v If type R is specified, code the relative block number of the CI or block. The value is up to 8-digit numeric with leading or trailing blanks; it must fall within the limits of the root addressable area. v If type C is specified, code the length of the key value in positions 5 and 6 (maximum length is 74). Code the key value starting in position 7. You can specify a generic key by entering a key value length less than the key length of the root segment. FABHFSU pads the key value with X'00's up to the key length. v If type X is specified, code the hexadecimal string starting in position 5. Do not specify length. The hexadecimal string must contain an even number of characters (0-F) and be left-justified in the field. Field length is determined by the first blank encountered in the field. When generic keys are entered, they are padded as described for character keys.

Note: If you are using a Data Conversion exit for the database and you want to specify a node point value by using a key valuethat is, setting a node point value type of 'C' or 'X'you must specify the key value in the stored form, not in the application form.

PSB control statement

The PSB control statement is the same as described in PSB control statement on page 58. The PSB control statement applies to all phases of FABHFSU.

END control statement

The END control statement is the same as described in END control statement on page 66.

Output
Reports are produced in PRNTOUT data set.

FABHPSFC PRNTOUT data set

This section explains the FABHPSFC PRNTOUT data set.

234

Users Guide

Function
The FABHPSFC program produces the following output reports: v FABHFSU PSF Control Statements Report v FABHFSU PSF Scan Control Data Set Report

Format
The format is 133-byte fixed-length records. When coded in the JCL, block size must be a multiple of 133.

FABHFSU PSF Control Statements report

This report prints out the CARDIN control statements that were input to FABHPSFC (see Figure 48).

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF CONTROL STATEMENTS" DATE: 10/26/2007 TIME: 12.52.06

PAGE: 1 FABHPSFC - V1.R2

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 DBDMSHDP NB 999 2 CTLSCANCNTL8936505NN NPTR810 NPTR1620 NPTR3240 NPTR4860 PSB* OUT1 UL END

NNNN

Figure 48. FABHFSU PSF Control Statements report

FABHFSU PSF Scan Control Data Set report

This report contains information on the parameters specified on the CARDIN control statements that were input to the Scan Control data set (see Figure 49 on page 236). This report is produced for each output data set defined by the PSB control statement in the CARDIN data set. Scan Control Specifications Shows specifications or defaults from CTL and DBD control statements Format Control Specifications Shows specifications or defaults from PSB control statement Phase Control Specifications Shows starting and ending block values of each scan phase based on specifications from NPT control statement.

Chapter 11. Using the Parallel Scan Facility of FABHFSU

235

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF SCAN CONTROL DATA SET REPORT" DATE: 10/26/2007 TIME: 12.52.06

PAGE: 1 FABHPSFC - V1.R2

*** SCAN CONTROL SPECIFICATIONS *** PARALLEL SCAN NAME BASE DBD NAME INDEX DBD NAME SEQUENCE CHECK OPTION SEQUENCE ERROR OPTION SEQUENCE ERROR PRINT OPTION SEQUENCE ERROR THRESHOLD SEQUENCE ERROR ABEND OPTION NO N.A N.A N.A N.A SCANCNTL MSHDP

*** FORMAT CONTROL SPECIFICATIONS *** FORMAT (CONTROL PSB) NUMBER CONTROL PSB NAME CONTROL PCB NUMBER OUTPUT DDNAME OUTPUT FORMAT EXIT ROUTINE NAME SEGMENT MODIFICATION OPTION CONCATENATED KEY OPTION EXIT OPEN/CLOSE CONTROL OUT1 UL N.A N.A N.A N.A N.A 01 *

LIMIT CONTROL POINTER BYPASS OPTION NO. PARALLEL SCANS DSN CHECK OPTION PSC WTO OPTION SEP HEADER OPTION

YES NO 05 NO NO NO

DBR SKIP OPTION

Figure 49. FABHFSU PSF Scan Control Data Set report (Part 1 of 2)

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF SCAN CONTROL DATA SET REPORT" DATE: 10/26/2007 TIME: 12.52.06

PAGE: 2 FABHPSFC - V1.R2

**** PHASE CONTROL SPECIFICATIONS **** PHASE 01 STARTING BLOCK ENDING BLOCK PHASE 02 STARTING BLOCK ENDING BLOCK PHASE 03 STARTING BLOCK ENDING BLOCK PHASE 04 STARTING BLOCK ENDING BLOCK PHASE 05 STARTING BLOCK ENDING BLOCK BEGINNING OF FILE 809 810 1,619 1,620 3,239 3,240 4,859 4,860 END OF FILE

Figure 49. FABHFSU PSF Scan Control Data Set report (Part 2 of 2)

236

Users Guide

FABHFSU utility
This section describes the FABHFSU control statements used in the PSF mode. The output reports are explained in OutputSYSPRINT data set on page 46.

Control statements of FABHFSU

When running in the PSF mode, the CARDIN data set contains the PSC and the END control statements. The DEC and GOT control statements can optionally be used in the PSF mode, but the DBD, PSB, BLM, ELM, PARTITION, and SEGSTAT control statements are not allowed as input to PSF. Table 27 lists the FABHFSU control statements used in the PSF mode.
Table 27. FABHFSU control statements for PSF mode Control statements PSC Function Identifies the Scan Control data set that directs the phases of the scan. Decompresses any compressed segments. Provides support for PROCOPT GOT. Specifies the end of CARDIN control statements. Description See PSC control statement on page 237. See DEC control statement on page 62. See GOT control statement on page 63. See END control statement on page 66.

DEC GOT END

PSC control statement

The PSC control statement activates the PSF mode. PSF mode differs from standard mode in that the data required by FABHFSU is obtained from the Scan Control data set instead of the CARDIN data set. Make sure you have a CNTLDD DD statement and refer to the PSF operating instructions.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PSCpsname dbdname xxnnbryyyyddd

Position 1 4

Description Code the PSC keyword to activate the PSF mode to unload large databases using multiple scans. Code the name of the Scan Control data set as specified in the CTL control statement as input for FABHPSFC, which creates the Scan Control data set. This name is defined in the CNTLDD DD statement, and is used in the entire PSF mode. This 8-character entry is left-justified with trailing blanks. Code the database name as specified in the DBD control statement as input for FABHPSFC, which creates the Scan Control data set. This required 8-character entry is left-justified with trailing blanks.

12

Chapter 11. Using the Parallel Scan Facility of FABHFSU

237

20

The required 2-digit entry xx specifies the expected number of scan phases in the PSF job. This value is the same as the value specified in the CTL control statement as input for FABHPSFC, which creates the Scan Control data set. The required 2-digit entry nn specifies the phase number for this particular scan phase. This value can range from 01 to the expected number of scan phases specified in positions 2021 of this statement. The 1-character entry b allows overriding of the Pointer Bypass option specified in the DBD control statement as input for FABHPSFC, which creates the Scan Control data set. This can be specified for a particular scan phase or all scan phases. Use one of the following keywords: Keyword Blank 1 2 Description This entry accepts the Pointer Bypass option specified in the Scan Control data set. The entry invokes the Pointer Bypass option. The entry forces FABHFSU to use the index, rather than the root twin forward pointers, to unload an HIDAM database.

22

24

25

The 1-character entry r allows a particular scan phase to be rerun regardless of prior completion status. Use one of the following keywords: Keyword Y N|blank Description Rerun the scan phase. Do not rerun the scan phase (default).

26

The 7-digit entry yyyyddd allows the Julian date to be overridden. yyyy is the year and ddd is the day of the year. This value overrides the value specified in the CTL control statement as input for FABHPSFC, which creates the Scan Control data set.

FABHPSFS program
This section describes the input and output for the FABHPSFS program.

Input
The control statements for the FABHPSFS program are specified in the CARDIN data set.

FABHPSFS CARDIN data set

This section explains the FABHPSFS CARDIN data set.

Function
The FABHPSFS program provides the following two basic functions: v Report the status of an in-progress parallel scan v Wrap up a "completed" parallel scan. These two purposes are performed by the specification of blank/STATUS/ RERUN/FORCE option in the position 20 of the SUM control statement.

238

Users Guide

The STATUS option, which can be run anytime after the FABHPSFC program has run, reports the current status of the scan from the Scan Control data set. The "wrap-up" function has three options, normal (the default), RERUN, and FORCE. Normal wrap-up must be run after all phases have completed (if they have not, it defaults to a STATUS run). It can be run only once and ends abnormally if run multiple times. It produces the summarized statistics for the entire scan. It also produces for each output format a concatenation sequence of the output data sets created by each phase. If any of the output formats is called for an Unload (UL) output, FABHPSFS creates one additional output data set that contains the "Trailer Label" required by HD Reorganization Reload and optionally another data set containing a separate "Header Label." All these data sets must be concatenated in the proper sequence by JCL for the input of any following job (that is, IMS HD Reorganization Reload). The RERUN option can be used to re-create the output of the normal wrap-up function after a normal wrap-up has been run. The FORCE option can be used to force normal wrap-up when one or more phases are not intended to be run. Table 28 lists the FABHPSFS control statements.
Table 28. FABHPSFS control statements Control statements Function SUM END Directs the FABHPSFS program. Specifies end of FABHPSFS CARDIN control statements. Mode PSF PSF

Format
This data set contains 80-byte fixed-length records. The control statements can be coded in the input stream or accessed as a member of a partitioned data set.

SUM control statement

FABHPSFS is directed by the SUM control statement for the PSF. Only one SUM control statement can be used.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 SUMpsname dbdname opt1 123

Position 1 4 12

Description Code the SUM keyword to identify the SUM control statement. Code a 18-character name for the parallel scan operation as specified in the CTL control statement as input for FABHPSFC. This required 8-character entry dbdname indicates the database name as specified in the DBD control statement as input for FABHPSFC. This 6-character entry opt1 determines the following optional keywords:
Chapter 11. Using the Parallel Scan Facility of FABHFSU

20

239

Keyword blank

Description Normal wrap-up function runs and the full summary report is provided (default). This option must be run after all phases have been completed. Only the current status of the scan is reported. This option can be run at anytime after the FABHPSFC program has run. The full summary report is re-created. The unloaded trailer data set can also be re-created as specified in position 26, 27, or 28. This option allows only some of the PSF phases are to be run. Note: When this option is selected, and when the first phase is not to be run, the "Separate Header" option is required to be used for reload. (Without specifying the "Separate Header" option, the header is not created when the first phase is not run.)

STATUS

RERUN

FORCE

26

The 1-character entry 1 is applicable only if the RERUN option is specified in position 20. This option allows for the re-creation of the header or trailer data set defined by the first PSB control statement. Use one of the following optional keywords: Keyword Y N H T Description Both header and trailer are re-created. Neither header nor trailer is re-created (default). Only header is re-created. Only trailer is re-created.

27

This is the same option as the option of position 26, except that it applies to the output data set defined by the second PSB control statement. This is the same option as the option of position 26, except that it applies to the output data set defined by the third PSB control statement.

28

END control statement

The END control statement is the same as described in END control statement on page 66.

Output
Reports are produced in the PRNTOUT data set.

FABHPSFS PRNTOUT data set

This section explains the FABHPSFS PRNTOUT data set.

Function
FABHPSFS produces the following output reports: v FABHFSU PSF Control Statements Report v FABHFSU PSF Summary Report

240

Users Guide

Format
The format is 133-byte fixed-length records. When coded in the JCL, block size must be a multiple of 133.

FABHFSU PSF Control Statements report

This report prints out the CARDIN control statements that were input to FABHPSFS (see Figure 50).

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF CONTROL STATEMENTS" DATE: 10/26/2007 TIME: 13.09.36

PAGE: 1 FABHPSFS - V1.R2

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 SUMSCANCNTLMSHDP END

Figure 50. FABHFSU PSF Control Statement report

FABHFSU PSF Summary report

This report provides the summarized statistics for the entire scan (see Figure 51 on page 243). This report is produced for each output data set defined by the PSB control statement in the CARDIN data set. This report contains the summary information on the parameters specified on the CARDIN control statements (see part 1 of the sample report shown in Figure 51 on page 243). Scan Control Specifications Shows specifications or defaults from CTL and DBD control statements Format Control Specifications Shows specifications or defaults from PSB control statement This report provides statistics for each sensitive segment in the database (see part 2 of the sample report shown in Figure 51 on page 243). PSB Name Name of PSB Segment Name Name of segment Segment Level Level of segment Total Retrieved This count shows the number of each segment type retrieved. This count does not include segments bypassed due to sequence errors. Total Output This shows the number of each segment type processed by FABHFSU. If Output Format is NO, the value is zero. Differences between Total Retrieved and Total Output represent segments bypassed by the user exit routine. Sequence errors This value represents the number of sequence errors detected for this segment type. If Sequence Check Option is N, this field is zero.

Chapter 11. Using the Parallel Scan Facility of FABHFSU

241

Maximum Twins This is the maximum number of this segment type that occurs under any one root segment. Maximum Children This is the maximum number of dependent children that occurs for this segment type. Average Twins This is the Total Retrieved of this segment type divided by Total Retrieved of this segments parent. Average occurrences of this segment per parent occurrence. Average Children This value is the sum of all segment occurrences dependent on this segment type divided by the Total Retrieved of this segment type. (This value might be incorrect if sequence errors are bypassed or if the PCB is not sensitive to all dependents.) Total Retrieved This is the total number of the segments retrieved. Total Output This is the total number of the segments processed by FABHFSU. Total Sequence Errors This is the total number of sequenced errors. This report contains information on the DFSUINPT DD statements when you reload the unloaded database data sets (see part 3 of the sample report shown in Figure 51 on page 243). It shows the sequence of the concatenation of the header data set, unloaded data sets, and trailer data set. Part 4 of this sample report contains the following information: Oper Type Operation Type. This field shows the output format type. Header Last The following three fields all pertain to the latest header label: Status, Date, and Time. Trailer Last The following three fields all pertain to the latest trailer label: Status, Date, and Time. Total Phases The total number of scan phases in the PSF job. Phase Number The phase number of a particular scan phase. Phase Last The following three fields all pertain to the latest scan phase: Date, Time, and Status. Phase Reruns The total number of the FABHPSFS jobs rerun by the rerun option of the SUM control statement. Seq Errors The number of sequence errors.

242

Users Guide

Pntrs Bypsd This shows whether the Pointer Bypass Option was specified or not. Synad Error This shows whether a synad error was detected or not.

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF SUMMARY REPORT" DATE: 10/26/2007 TIME: 13.09.36

PAGE: 1 FABHPSFS - V1.R2

*** SCAN CONTROL SPECIFICATIONS *** PARALLEL SCAN NAME BASE DBD NAME INDEX DBD NAME SEQUENCE CHECK OPTION SEQUENCE ERROR OPTION SEQUENCE ERROR PRINT OPTION SEQUENCE ERROR THRESHOLD SEQUENCE ERROR ABEND OPTION NO N.A N.A N.A N.A SCANCNTL MSHDP

*** FORMAT CONTROL SPECIFICATIONS *** FORMAT (CONTROL PSB) NUMBER CONTROL PSB NAME CONTROL PCB NUMBER OUTPUT DDNAME OUTPUT FORMAT EXIT ROUTINE NAME SEGMENT MODIFICATION OPTION CONCATENATED KEY OPTION EXIT OPEN/CLOSE CONTROL OUT1 UL N.A N.A N.A N.A N.A 01 *

LIMIT CONTROL POINTER BYPASS OPTION NO. PARALLEL SCANS DSN CHECK OPTION PSC WTO OPTION SEP HEADER OPTION

YES NO 05 NO NO NO

DBR SKIP OPTION

Figure 51. FABHFSU PSF Summary report (Part 1 of 4)

Chapter 11. Using the Parallel Scan Facility of FABHFSU

243

IMS HIGH PERFORMANCE UNLOAD 5655-E06 **** FORMAT 01 OUTPUT STATISTICS **** PSB NAME * SEGMENT SEGMENT NAME LEVEL HSHDPRT HSHDPDR HSHDPSR HSHDPMC HSHDPIR HSHDPMG HSHDPSF HSHDPCB HSHDPSD HSHDPAX HSHDPSA 1 2 2 2 2 2 2 2 2 2 2 TOTAL RETRIEVED 2,000 2,000 4,000 6,000 2,000 4,000 6,000 2,000 4,000 6,000 2,000 4,000 TOTAL OUTPUT 2,000 2,000 4,000 6,000 2,000 4,000 6,000 2,000 4,000 6,000 2,000 4,000 44,000 44,000 0

"FABHFSU PSF SUMMARY REPORT" DATE: 10/26/2007 TIME: 13.09.36

PAGE: 2 FABHPSFS - V1.R2

SEQUENCE ERRORS 0 0 0 0 0 0 0 0 0 0 0 0

MAXIMUM TWINS 1 1 2 3 1 2 3 1 2 3 1 2

MAXIMUM CHILDREN 21 0 0 0 0 0 0 0 0 0 0 0

AVERAGE TWINS 1.00 1.00 2.00 3.00 1.00 2.00 3.00 1.00 2.00 3.00 1.00 2.00

AVERAGE CHILDLEN 21.00 .00 .00 .00 .00 .00 .00 .00 .00 .00 .00 .00

HSHDPCR 2 TOTAL RETRIEVED TOTAL OUTPUT TOTAL SEQUENCE ERRORS

Figure 51. FABHFSU PSF Summary report (Part 2 of 4)

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF SUMMARY REPORT" DATE: 10/26/2007 TIME: 13.09.36

PAGE: 3 FABHPSFS - V1.R2

**** FORMAT 01 DSN CONCATENATION SEQUENCE **** 1. IMS31B.SCANCNTL.UL01.PHASE01 2. IMS31B.SCANCNTL.UL01.PHASE02 3. IMS31B.SCANCNTL.UL01.PHASE03 4. IMS31B.SCANCNTL.UL01.PHASE04 5. IMS31B.SCANCNTL.UL01.PHASE05 6. IMS31B.SCANCNTL.UL01.TRAILER

Figure 51. FABHFSU PSF Summary report (Part 3 of 4)

244

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHFSU PSF SUMMARY REPORT" DATE: 10/26/2007 TIME: 13.09.36

PAGE: 4 FABHPSFS - V1.R2

**** FORMAT 01 OF 01 PHASE STATUS ****

OPER H E A D E R L A S T TYPE STATUS DATE TIME UL

T R A I L E R L A S T STATUS DATE TIME COMPL 892 13:09:37

TOTAL PHASE P H A S E L A S T PHASE SEQ PNTRS SYNAD PHASES NUMBER DATE TIME STATUS RERUNS ERRORS BYPSD ERROR 5 1 2 3 4 5 00252 13:02:53 00252 12:56:59 00252 12:58:59 00252 12:58:58 00252 12:56:31 COMPLETE COMPLETE COMPLETE COMPLETE COMPLETE 0 0 0 0 0 0 0 0 0 0 NO NO NO NO NO

Figure 51. FABHFSU PSF Summary report (Part 4 of 4)

Example
To unload a multivolume IMS database in PSF mode, you can use the JCLs shown in Figure 52 on page 246 Figure 55 on page 248. In this example, three individual parallel scan phases are utilized to unload an HDAM database. In each phase, FABHFSU scans and unloads only a predefined portion of the database controlled by a Scan Control data set. Step 1 gets a primary data set extent information of the database. Based on the information, step 2 creates a Scan Control data set to define scan parameters and the number of parallel scan phases. Step 4 generates a set of summarized statistics and concatenation sequence of the output data sets unloaded by each parallel scan phase. Step 4 creates two data sets that contain "Header record" and "Trailer record" required by the IMS HD Reorganization Reload utility.

Step 1Example of FABHPSFM

The TESTDB DD statement identifies the primary data set of the DBD specified by the MAP control statement in the CARDIN DD statement. The extent information of the primary data set is reported to SYSOUT class A defined by the PRNTOUT DD statement. This information helps to determine the phase limit definition in step 2.

Chapter 11. Using the Parallel Scan Facility of FABHFSU

245

//*----------------------------------------------------------------------------//* PSF STEP 1 - GET DATABASE EXTENTS INFORMATION //*----------------------------------------------------------------------------//FSUMAP EXEC PGM=FABHPSFM //IMS DD DSN=IMSVS.DBDLIB,DISP=SHR //TESTDB DD DSN=TESTDS.HDAM.VSAM,DISP=OLD //PRNTOUT DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //CARDIN DD * MAPTESTDB END /* Figure 52. FABHPSFM JCL for PSF mode

Step 2Example of FABHPSFC

The CNTLDD DD statement identifies the Scan Control data set created by this job step. The CARDIN DBD control statement specifies the DBD name of the database. The CARDIN CTL control statement defines a parallel scan name (SCANCNTL) for use in getting access to the Scan Control data set; defines the Julian date as the last day of 2000; and sets the number of parallel scan phases to 03. Y in column 22 specifies that the data set names match the naming standard. The beginning position of the parallel scan name in the data set is 08 in columns 2324. Y in column 25 specifies that the header record is written to the separate output data set in step 4. Two CARDIN NPT control statements define the scan limit of each parallel scan phases. The first phase scans the database from the beginning of the database to the relative CI number 1000. The second phase scans the database from the relative CI number 1001 to the number 4000, and the third phase scans it from the number 4001 to the end of the database. The CARDIN PSB control statement specifies the name of the DD statement (OUTDATA) that defines the data set to be created.

246

Users Guide

//*----------------------------------------------------------------------------//* PSF STEP 2 - CREATE SCAN CONTROL DATA SET //* ---------------------------------------------------------------------------//FSUCTRL EXEC PGM=FABHPSFC //IMS DD DSN=IMSVS.DBDLIB,DISP=SHR //CNTLDD DD DSN=TESTDS.CONTROL,DISP=(NEW,CATLG), // UNIT=SYSDA,VOL=SER=TESTVOL,SPACE=(TRK,(4,1)), // DCB=(BLKSIZE=4096,LRECL=4092,RECFM=VB) //PRNTOUT DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //CARDIN DD * DBDTESTDB CTLSCANCNTL200036603NY08Y NPTR1001 NPTR4001 PSB* OUTDATA 00UL END /* Figure 53. FABHPSFC JCL for PSF mode

Steps 3A, 3B, 3CExample of FABHFSU

The CNTLDD DD statement identifies the Scan Control data set created by FABHPSFC in a previous job step. The CARDIN PSC control statement specifies that there are 3 expected scan phases. A portion of the database with the dbdname TESTDB is unloaded in this scan phase. The Scan Control data set created by FABHPSFC is named SCANCNTL. The OUTDATA DD statement specifies a data set on which this portion of the IMS database is unloaded. Two other job steps in PSF mode would be required to complete the unloading of this database. The JCL for the job steps is the same, except for modifying the PSC control statement and the ddname DD (OUTDATA) statement to specify parameters required for phase 2 and phase 3.
//*----------------------------------------------------------------------------//* PSF STEP 3A - UNLOAD DATABASE (FABHFSU) - PHASE 1 OF 3 //* ---------------------------------------------------------------------------//UNLOAD1 EXEC FABHULU,MBR=FABHFSU,DBD=TESTDB,DBRC=N,IRLM=N //CNTLDD DD DSN=TESTDS.CONTROL,DISP=SHR //TESTDB DD DSN=TESTDS.HDAM.VSAM,DISP=SHR //OUTDATA DD DSNAME=UNLOAD.SCANCNTL.UL01.PHASE01, // DISP=(NEW,KEEP),UNIT=SYSDA, // SPACE=(CYL,(100,25),RLSE) //PRNTOUT DD SYSOUT=A //CARDIN DD * PSCSCANCNTLTESTDB 0301 END /* Figure 54. FABHFSU JCL for PSF mode

Chapter 11. Using the Parallel Scan Facility of FABHFSU

247

Step 4Example of FABHPSFS

The XHTDATA DD statement defines a data set containing the header record of the unloaded data sets. The name of this DD statement must begin with 'XH'. The OUTDATA DD statement defines a data set containing the trailer record of the unloaded data sets. The name of this DD statement (OUTDATA) must be equal to ddname1 of CARDIN PSB control statement in step 2. The CNTLDD DD statement identifies the Scan Control data set. The CARDIN SUM control statement specifies the parallel scan name (SCANCNTL) to access the Scan Control data set.
//*----------------------------------------------------------------------------//* PSF STEP 4 - SUMMARIZE STATISTICS AND DATA SETS SEQUENCE //* ---------------------------------------------------------------------------//FSUSUMM EXEC PGM=FABHPSFS //IMS DD DSN=IMSVS.DBDLIB.DISP=SHR //CNTLDD DD DSN=TESTDS.CONTROL,DISP=OLD //XHTDATA DD DSNAME=UNLOAD.SCANCNTL.UL01.HEADER,DISP=(NEW,KEEP) // UNIT=SYSDA,SPACE=(TRK,(4,1)), // DCB=(BLKSIZE=4096,LRECL=4092,RECFM=VB) //OUTDATA DD DSNAME=UNLOAD.SCANCNTL.UL01.TRAILER,DISP=(NEW,KEEP) // UNIT=SYSDA,SPACE=(TRK,(4,1)), // DCB=(BLKSIZE=4096,LRECL=4092,RECFM=VB) //PRNTOUT DD SYSOUT=A //SYSUDUMP DD SYSOUT=A //CARDIN DD * SUMSCANCNTLTESTDB END /* Figure 55. FABHPSFS JCL for PSF mode

When you reload the unloaded database data sets with the IMS HD Reorganization Reload utility or an equivalent program, you must specify the concatenation of the header data set, unloaded data sets, and trailer data set on the DFSUINPT DD statement. The sequence of the concatenation is reported in the PRNTOUT data set of step 4. The following is an example to specify DD statements:
//DFSUINPT DD DD DD DD DD DSN=UNLOAD.SCANCNTL.UL01.HEADER,DISP=OLD DSN=UNLOAD.SCANCNTL.UL01.PHASE01,DISP=OLD DSN=UNLOAD.SCANCNTL.UL01.PHASE02,DISP=OLD DSN=UNLOAD.SCANCNTL.UL01.PHASE03,DISP=OLD DSN=UNLOAD.SCANCNTL.UL01.TRAILER,DISP=OLD

248

Users Guide

Chapter 12. Unloading corrupted databases

The following paragraphs discuss the problems you may encounter with corrupted databases, and the options available for repairing the databases. Topics: v Using the SKERROR option for FABHURG1 v Using the Pointer Bypass Option for FABHFSU v Rules for unloading with Pointer Bypass or SKERROR option on page 250 v Examples on page 252

Using the SKERROR option for FABHURG1

If a database contains incorrect physical HD pointers or HISAM records that you cannot correct by standard IMS recovery procedures such as database backout or database recovery, you can correct the errors with IBM IMS Database Repair Facility (Program Number: 5655-E03) or AMASPZAP. The procedure requires a database specialist who understands how ZAPs can repair the database. As an alternative, High Performance Unloads HSSR Engine offers the SKERROR option. SKERROR allows FABHURG1 to unload HIDAM, HDAM, PHIDAM, PHDAM, or HISAM databases, even if they contain incorrect physical pointers or incorrect HISAM records. SKERROR skips the processing of incorrect pointers or records, which omits some occurrences of segments on the unloaded database data set. You can then use the unloaded database as input to the standard IMS HD Reorganization Reload utility or a compatible utility to reconstruct a new database. Unless the corrupted database involves logical relationships, your new database is now error-free from a technical IMS standpoint.

Using the Pointer Bypass Option for FABHFSU

You can use the Pointer Bypass option, instead of SKERROR, for FABHFSU to unload a corrupted database. You can select either one of two available options for Pointer Bypass option (see Option 1 and Option 2 on page 250). Both options enables FABHFSU to continue processing a database that contains bad pointers. Since most of the data is good (and if it is possible to obtain an unload of the database), its reconstruction can be aided by reorganizing the database. The logic invoked by this option treats an incorrect pointer as X'00000000' (end of chain), and FABHFSU proceeds with the next logical pointer path. This means that one or more segments are bypassed and are not contained in any output data set. If the database contains logical relationships, prefix resolution might fail on a subsequent reload because a logical parent segment has been bypassed. This can be corrected by locating the logical child records that refer to the logical parent and eliminating them from the unloaded data set. After reload, the relationships can then be reestablished with maintenance programs.

Option 1
Option 1 (indicated by a 1 in column 28 of the DBD control statement) invokes the Pointer Bypass option using normal retrieval techniques. The usual retrieval methods are as follows:

Copyright IBM Corp. 2000, 2007

249

v HIDAM and PHIDAM with twin backward on root segment: The primary index is used to find the first root segment. The root twin forward pointer is then followed. If a pointer error is encountered in the root twin forward pointer, HSSR Engine attempts to locate the next root via the primary index. v HDAM and PHDAM: Retrieval begins at the first RAP and follows the root twin forward until a "0" pointer or pointer error is encountered. The retrieval then continues at the next RAP.

Option 2
Option 2 (indicated by a 2 in column 28 of the DBD control statement) is applicable only to HIDAM and PHIDAM. It forces FABHFSU to use the index (rather than the root twin forward pointers) to unload the database. Note: Specifying a FABHFSU Pointer Bypass option automatically activates both the SKERROR option and the DIAGG option for HSSR Engine.

Rules for unloading with Pointer Bypass or SKERROR option

Follow the rules below when you unload a corrupted database: 1. The DIAGG option is automatically invoked by FABHFSU when the Pointer Bypass option is specified. For FABHURG1, DIAGG is specified on a control statement in the HSSROPT data set. The DIAGG option provides the following diagnosis information (in addition to technical information addressing highly skilled database specialists): v Information about the last segment that was successfully unloaded before encountering the database error: The segment name The concatenated PCB key feedback area v Information about the first segment that was successfully unloaded after the database error: The segment name The concatenated PCB key feedback area The segment data v The name of those segment types, for which some segment occurrences might be missing on the unloaded data set. The preceding information can be used to locate the error and to see which segment types might be missing from a segment. Using this information, you can then determine which lost database segments should be inserted after a successful reload into the database. For each incorrect pointer, the DIAGG option might write more than 4000 print lines on the HSSRTRAC data set. To avoid S722 or SB37 system abends, allocate the HSSRTRAC data set on a tape or allow the job to produce a large number of printed lines. (One example would be through the use of a OUTLIM JCL parameter.) 2. For FABHFSU, it is recommended that you specify (on the DBD control statement) the Sequence Check option as Y and the Sequence Error option as B. With these options, HSSR Engine performs more extensive error-checking while unloading a corrupted database. When the default Sequence Error option of A is used, the unloaded database data set may contain segments that are not in sequence. This can prevent a successful reload. 3. For FABHURG1, the SKERROR option requires that you consider activating the KEYCHECK GG option. The KEYCHECK GG option lets HSSR Engine perform

250

Users Guide

more error-checking while unloading a corrupted database. However, do not use the KEYCHECK GG option if you are going to reload the unloaded database and if you do not want to lose any segments in the original database. Note: When SKERROR option is used without KEYCHECK GG option, the unloaded database might contain segments that are not in key sequence. 4. Before using the new database created through the unload and reload process, determine how many segments were skipped or lost during the unloading process. This can be achieved by: a. Reloading the database without destroying the original corrupted database. b. Running HD Pointer Checker utility of IBM IMS High Performance Pointer Checker for z/OS (Program Number: 5655-K53) on the original corrupted database. c. Comparing the number of occurrences of each segment type in the original corrupted database (shown by HD Pointer Checker utility) to the segment statistics (provided in HSSRSTAT and in PRNTOUT). PRNTOUT shows how many segments have been successfully unloaded. By combining information about the number of skipped or lost segments with the DIAGG key feedback information, you can decide whether the new database is acceptable. Be sure that you run the HD Pointer Checker utility on the new database to confirm that the new database is free of IMS technical errors. After a "crash," the corrupted databases should be recovered with standard IMS recovery procedures such as Emergency Restart, Database Backout, and Database Recovery utility. A High Performance Unloads unload utility with the SKERROR or Pointer Bypass option should be run only after these recovery procedures are completed. Neither the SKERROR nor Pointer Bypass option copes with DASD I/O errors. The use of either option requires a prior recovery from DASD I/O errors through standard recovery procedures. The following points apply to databases involved in logical relationships: Unloading and reloading of huge databases that are heavily involved in logical relationships might require many hours for the scanning, unloading, reloading, prefix resolution, prefix update, and image copy. For such databases, consider using IBM IMS Database Repair Facility (Program Number: 5655-E03) as an alternative to the unload and reload approach. If you suspect that logical pointers (logical parent pointers, logical child pointers, logical twin pointers, or counter fields) are incorrect, run the Prereorganization utility, using the DBIL= control statement. Unload and reload all related databases. (Refer to the description of the HD Reorganization Unload utility DFSURGU0 in IMS Utilities Reference: Database.) When you unload a corrupted database with a logical pointer error in a logical child segment with the virtual LPCK defined, you must specify the BLDLPCK control statement in the HSSROPT data set. If the corrupted database is involved in a logical relationship, FABHFSU cannot be used (without postprocessing of its output by user programs) for a successful unload/reload/prefix resolution and prefix update process if one of the following types of segment occurrence is skipped or lost during the unload: v A logical parent segment that has one or more logical children v A logical child segment that is physically paired For such cases, investigate the use of the IBM IMS Database Repair Facility.
Chapter 12. Unloading corrupted databases

| | |

5.

6.

7.

8.

251

Examples
In this section, the following two JCL examples are shown: v Example 1: Using FABHURG1 to unloading a corrupted database v Example 2: Using FABHFSU to unloading a corrupted database

Example 1: Using FABHURG1 to unloading a corrupted database

To unload a corrupted database, you can use the JCL shown in Figure 56. The unloaded data set is defined by the SYSUT2 DD statement; the database that is unloaded is defined by the HDAM DD statement. HSSROPT options SKERROR, KEYCHECK GG, and DIAGG are specified. OUTLIM is specified on the HSSRTRAC DD statement.
// EXEC FABHULU,MBR=FABHURG1,DBD=USERDBD //HSSROPT DD * SKERROR 10 KEYCHECK GG DIAGG /* //HDAM DD DSN=TESTDS.HDAM,DISP=SHR //SYSPRINT DD SYSOUT=A //SYSUT2 DD DSN=TESTDS.HDUNLD,DISP=(,CATLG),UNIT=TAPE, // VOL=SER=xxxxxx //HSSRTRAC DD SYSOUT=A,OUTLIM=10000000 Figure 56. FABHURG1 JCL to unload a corrupted database

Example 2: Using FABHFSU to unloading a corrupted database

To unload a corrupted database by using FABHFSU in the standard mode, you can use the JCL shown in Figure 57 on page 253. The FABHDLI procedure used specifies the PSB named OUT2PSB. The OUT1 and OUT2 DD statements define two unloaded data sets. The database that is unloaded is defined by the SKILHDAM DD statement. The CARDIN DBD statement specifies the IMS database to FABHFSU. It specifies that sequence checking is to be done, sequence errors are to be processed, and diagnostic data is to be printed. The Pointer Bypass option is to be activated. Incorrect segments are not unloaded. The CARDIN PSB statements specify the two output data sets to FABHFSU. OUT1 specifies a data set unloaded in the IMS HD Reorganization Unload format. The "*" indicates that all segments defined in the DBD are unloaded. OUT2 specifies the VB-format output data set. Only segment types defined in the first DB PCB of the PSB OUT2PSB for the SKILLINV database are unloaded. A user exit routine, OUT2EXIT, is specified.

252

Users Guide

// EXEC FABHDLI,MBR=FABHFSU,PSB=OUT2PSB //CARDIN DD * DBDSKILLINV YAY 1 PSB* OUT1 UL PSBOUT2PSB OUT2 VBOUT2EXIT END /* //SKILHDAM DD DSN=SKIL.INV.DB,DISP=SHR //PRNTOUT DD SYSOUT=A //OUT1 DD DSN=TESTDS.UNLOAD1,DISP=(,KEEP),UNIT=TAPE //OUT2 DD DSN=TESTDS.UNLOAD2,DISP=(,KEEP),UNIT=TAPE Figure 57. FABHFSU JCL to unload a corrupted database

Chapter 12. Unloading corrupted databases

253

254

Users Guide

Chapter 13. Compatibility with earlier products

This chapter discusses the compatibility of High Performance Unload with the following earlier products: v DBT V2 HSSR IMS System Utilities/Data Base Tools Version 2, High Speed Sequential Retrieval (Program Number: 5685-093) v DBT V1 HSSR IMS System Utilities/Data Base Tools Version 1, High Speed Sequential Retrieval (Program Number: 5668-856) v PO HSSR Program Offering High Speed Sequential Retrieval Version 2 (IFP 5787-LAC) v FSU II IMS/VS Fast Scan Utility II Version 2 (FDP 5798-DFN) Topics: v v v v Compatibility Compatibility Compatibility Compatibility with with with with DBT V2 HSSR DBT V1 HSSR on page 262 PO HSSR on page 263 FSU II on page 267

Compatibility with DBT V2 HSSR

High Performance Unload is compatible with DBT V2 HSSR, with the following exceptions: v Default buffer handler for ESDS and OSAM v Default values of CAB buffering parameters v Location of buffer pools and compatibility of exit routines v HSSROPT control statements: HDSTATS and NOSAMEOPT v Access method used in unload utilities to write output records v Specifying an HSSR PCB through KEYLEN v v v v v v v v Support of PROCOPT=R and replace calls Support of explicit HSSR calls FABHFSU control statements: CO and CON Date specification in PSC and CTL control statements Format of the Scan Control data set used in Parallel Scan Facility Location of control blocks Product-sensitive macros DECN control statement and the unloaded data set

For compatibility of High Performance Unload with Sequential Subset Randomizer, see Part 3.

Default buffer handler for ESDS and OSAM

In High Performance Unload, the default buffer handler for ESDS and OSAM is CAB, whereas in DBT V2 HSSR the default is BB. If your JCL for DBT V2 HSSR does not specify HSSRCABP control statements to use CAB, running the job on High Performance Unload will require more storage. To avoid the storage problem, the function to change the default buffer handler is provided. For the details, see Chapter 19, Setting site default options, on page 335.
Copyright IBM Corp. 2000, 2007

255

Default values of CAB buffering parameters

The default values for CAB buffering parameters RANSIZE, NBRSRAN, NBRDBUF, and OVERFLOW in High Performance Unload are different from those in DBT V2 HSSR. Table 29 lists the differences of the default values of CAB buffering parameters.
Table 29. Differences of default values of CAB buffering parameters CAB parameter RANSIZE NBRSRAN NBRDBUF REFT4 OVERFLOW Default value in High Performance Unload Automatically determined from the characteristics of database data set 8 Twice the number assigned to RANSIZE Equals to RANSIZE CAB Default value in DBT V2 HSSR 8 4 4 12 BB

If your JCL for DBT V2 HSSR uses the default values for CAB buffering parameters, running the job on High Performance Unload may require more storage. To avoid this storage problem, the function to fallback the default values to the ones that are compatible with DBT V2 HSSR is provided. For the details, see Chapter 19, Setting site default options, on page 335.

Location of buffer pools and compatibility of exit routines

High Performance Unload always allocates buffer pools above the 16MB line. In DBT V2 Release 2 HSSR, buffer pools are allocated above the 16MB line only for VSAM data sets. In DBT V2 Release 3 HSSR buffer pools are allocated above the 16MB line for OSAM data sets also only when DFSMS Version 1 or later is used. Because of these differences, you may need to link-edit your FABHURG1 exit routine or FABHFSU exit routine with the 31-bit addressing mode. For the details, see: v Writing user record-formatting routine on page 317. v Chapter 18, System programming interfaces, on page 313 for the requirements for FABHURG1 exit routines. v User exit on page 71 in Chapter 5, Using FABHFSU to unload IMS databases, on page 49 for the requirements for FABHFSU exit routines.

HSSROPT control statements: HDSTATS and NOSAMEOPT

The HDSTATS control statement in DBT V2 HSSR is accepted in High Performance Unload, and is treated as an alias for the DBSTATS control statement. In High Performance Unload, HDSTATS is effective for HISAM databases as well as HD databases. The NOSAMEOPT control statement in DBT V2 HSSR is accepted in High Performance Unload, but has no effect.

256

Users Guide

Access method used in Unload utilities to write output records

In FABHURG1 and FABHFSU of High Performance Unload, the access method used to write output records is always QSAM and the default buffer size is determined by the block size of the output data set. In DBT V2 HSSR, both BSAM and QSAM are supported; performance is better with QSAM than with BSAM. The affected DDs are SYSUT2 and SYSUT3 of FABHURG1, and the output DD specified by a PSB control statement of FABHFSU. In DBT V2 HSSR, the access method used for writing output records to the unloaded data set is specified in the FRMT statement for FABHURG1 or PSB statement for FABHFSU. These parameters are ignored in High Performance Unload; QSAM is always used.

Specifying an HSSR PCB through KEYLEN

The following method for specifying an HSSR PCB is supported for compatibility; 1. Code a PCB that satisfies all requirements stated in HSSR PCB requirements on page 84. 2. Assign a value of 200 or greater to the KEYLEN keyword parameter for the PCB. HSSR will then recognizes the PCB as an HSSR PCB. For a PCB defined this way, the value specified on the KEYLEN keyword parameter is just the indicator of an HSSR PCB and is not related to key length. That value can also be usedif the basic buffer handler (BB) is used to access the database data setsto change the default number of basic buffers that HSSR allocates for each database data set of the database referenced by the PCB. The default number of BB buffers, when it is used, is determined as follows: v If the KEYLEN value is 200 or 201, two basic buffers are allocated for each ESDS or OSAM data set of the database referenced by the PCB. v If the KEYLEN value is greater than or equal to 202, the number of basic buffers is equal to the value minus 200. Number of Basic Buffers for an HSSR PCB If an HSSR PCB is defined by the use of either an HSSRPCB or an HSSRDBD control statement, and the value to the KEYLEN keyword for the PCB is less than 200, BB allocates six basic buffers for each data set as a default. If the KEYLEN value for the PCB is greater than or equal to 200, the number of basic buffers to be allocated is the same as that described above. If some other number of buffers is preferable, use the BUF control statement to allocate that number of buffers.

Support of PROCOPT=R and replace calls

PROCOPT=R is supported for compatibility. If a database is shared at the database level when PROCOPT=GR, DBRC grants access with integrity for updating the IMS subsystem (see Support and restriction for replace operations on page 258).

Status code in PCB feedback

The following DL/I status codes, in addition to the blank status code, are returned after a REPL call for an HSSR PCB: Status Code NE NI VX Meaning Unable to find the segment. There is a duplicate segment in the unique secondary index. VX is used during a REPL call to signal that the application program has not respected the restrictions for HSSR Engine. When
Chapter 13. Compatibility with earlier products

257

VX is displayed, the replace was not performed. Database positioning information is maintained normally.

DFSVSAMP DD
HSSR Engine handles replace calls by issuing IMS DL/I GH and REPL calls internally. IMS uses its own OSAM or VSAM buffer pools to process these DL/I calls. If your application program issues REPL calls, the usual DFSVSAMP control statements must be coded to tune the processing of these internal DL/I calls.

Restrictions
The following restrictions apply to PROCOPT=R and replace calls: v PROCOPT=R cannot be specified for HISAM, SHISAM, or secondary index databases. v PROCOPT=R cannot be specified for PHDAM or PHIDAM databases. v PROCOPT=R cannot be specified for logical child segments that have the following attributes: Physically paired Logical parents concatenated key defined as "virtual" if the BLDLPCK control statement is not specified in the HSSROPT data set v PROCOPT=R cannot be specified for secondary index source segments other than root segments. v The REPL call for PHDAM and PHIDAM databases is not supported. v The segment length of a variable or compressed segment must not be modified by a replace call.

Support and restriction for replace operations

HSSR Engine provides limited support of replace calls for application programs that replace a small or moderate number of retrieved database segments and modify a small or moderate number of accessed database blocks or CIs. This support includes standard IMS logging of database changes, standard IMS sync point processing, and a standard DBRC interface as provided by the host IMS batch subsystem.

Support of explicit HSSR calls

Explicit HSSR calls (ASMHSSR, CBLHSSR, and PLIHSSR) are supported in High Performance Unload for compatibility with DBT HSSR and PO HSSR. An explicit HSSR call consists of a name, a count parameter, a call function, a PCB, an I/O area, and an SSA (if any). PL/I application programs must include a count parameter. The explicit HSSR call names are ASMHSSR for Assembler application programs, CBLHSSR for COBOL application programs, and PLIHSSR for PL/I application programs. The following examples show the format of the call statement for each type of application program: v Assembler application programs: Retrieval calls without SSA and REPL calls:
CALL ASMHSSR,(function,pcb,ioarea),VL CALL ASMHSSR,(three,function,pcb,ioarea),VL

Retrieval calls with SSA:

CALL ASMHSSR,(function,pcb,ioarea,ssa),VL CALL ASMHSSR,(four,function,pcb,ioarea,ssa),VL

v COBOL application programs:

258

Users Guide

 Retrieval calls without SSA and REPL calls:

CALL CBLHSSR USING FUNCTION,PCB,IOAREA. CALL CBLHSSR USING THREE,FUNCTION,PCB,IOAREA

Retrieval calls with SSA:

CALL CBLHSSR USING FUNCTION,PCB,IOAREA,SSA. CALL CBLHSSR USING FOUR,FUNCTION,PCB,IOAREA,SSA

v PL/I application programs: Retrieval calls without SSA and REPL calls:
CALL PLIHSSR (three,function,pcb,ioarea);

Retrieval calls with SSA:

CALL PLIHSSR (four,function,pcb,ioarea,ssa);

For a complete description of the call functions, parameters, and layout of the PCB and SSA, seeIMS Application Programming: Database. Notes: 1. HSSR call parameters (count parameter, call function, PCB address, and number of parameters) are validated by HSSR Engine. If you specify HSSR PCB as a DL/I PCB, HSSR Engine does not validate HSSR call parameters, but instead transfers the call to DL/I. 2. An application program that uses explicit HSSR calls should be linked with the language interface module (ASMHSSR, CBLHSSR, or PLIHSSR) in the same way that a DL/I program is linked with the DL/I language interface. 3. The language interface modules ASMHSSR, CBLHSSR, and PLIHSSR are not reentrant. Therefore, the application program cannot be reentrant after link-editing. 4. For the LANG=PLI option on PSBGEN, PLICALLA entry point, and the compatibility with Language Environment for your application program written in PL/I, refer toIMS Application Programming: Database; the same restrictions apply to the HSSR application program. 5. The module attributes (AMODE, RMODE, and so forth) of the language interface modules (ASMHSSR, CBLHSSR, and PLIHSSR) must not be changed even if the language interface module is dynamically invoked by the application program. 6. The language interface modules provided by DBT V2 Release 1 HSSR might cause a system abend 0C4 in the explicit HSSR call to a DL/I PCB. This problem is solved by applying APAR PK24577 to High Performance Unload. 7. The language interface modules provided by DBT V2 Release 2 HSSR may cause the system abend 0C1. You can check whether the cause of the problem is in the old language interface module by doing: a. Browse or dump the HSSR application program. b. Look for the string 'FABHHSSR' followed by the IBM copyright statement. c. Check the string 'APAR(xxxxxxx)' that follows the copyright statement. The substring 'xxxxxxx' indicates the maintenance level of the language interface module. If 'xxxxxxx' is either 'KHK0013' or 'PN61005,' it is definite that the cause of the problem is in the language interface module.

Chapter 13. Compatibility with earlier products

259

The solution for the problem is to re-link-edit the application program with the language interface module provided by High Performance Unload.

FABHFSU control statements: CO and CON

The following control statements are accepted by FABHFSU for compatibility: v CO v CON

CO control statement
The CO control statement activates the compare option, which instructs FABHFSU to compare the content of one of its output data sets with the content of an FSU II output data set. (This option should be used only for problem determination.) Up to three CO control statements can be provided in the CARDIN data set after the PSB control statement. Note: The CO control statement cannot be specified for a PHDAM or PHIDAM database.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 COn ddname2

Position 1 3

Description Code the CO keyword to activate the compare option. The required 1-digit entry n is used to specify the FABHFSU output data set to be compared. Code values of 1, 2, or 3. n specifies that output data set defined by the nth PSB control statement is to be compared with an FSU II data set. The required 8-character entry defines the name of the DD statement that defines the FSU II output data set to be compared. ddname2 is left-justified with trailing blanks. This output data set must have been created in a prior job or job step. Also, in your FABHFSU JCL, you must code a ddname2 DD statement that specifies the data set to be compared. If the data sets are HSAM output data sets, the FSU II and the FABHFSU output data sets must have the same block size. Notes: 1. FABHFSU ends abnormally when it detects a relevant mismatch between itself and the FSU II output data sets. It also issues an error message. 2. Do not use IEBCOMPR to compare FABHFSU to FSU II output data sets, since they are not always identical. 3. The CO control statement cannot be used when NO is specified for the output format of the unloaded data set. 4. When the BLDLPCK statement is specified, the CO control statement for HS-format output records is ignored.

12

260

Users Guide

CON control statement

See CON control statement on page 267 in Compatibility with FSU II.

Date specification in PSC and CTL control statements

In High Performance Unload, the year in the expiration date for a Scan Control data set is specified in four digits for the PSC control statement of FABHFSU and for the CTL control statement for FABHPSFC. This is same for DBT V2 Release 3 HSSR. In DBT V2 Release 2 HSSR, the year is specified in two digits. It is recommended that the year in the above two control statements in your new JCLs be coded in four digits, although the two-digit specification is also accepted.

Format of the Scan Control data set used in Parallel Scan Facility
The format of the Scan Control data set created in Parallel Scan Facility of FABHFSU is the same as that for DBT V2 Release 3 HSSR, but is different from the one for DBT V2 Release 2 HSSR. Therefore, the Scan Control data sets must be created again if you are migrating from DBT V2 Release 2 HSSR.

Location of control blocks

Product-Sensitive Programming Interface In High Performance Unload, HDMB and HRAN control blocks are above the 16MB line. Table 30 shows where each product-sensitive control block of HSSR Engine is. The minus sign (-) indicates that the block is in private storage; the plus sign (+) indicates that the block is in extended private storage.
Table 30. Location of control blocks Control block HDMB HJCB HPCB HPTR HRAN HSDB Location in High Performance Unload + + Location in DBT V2 -

User exit routines that refer to HDMB or HRAN control block and that have been link-edited with 24-bit addressing mode must be modified so that they can refer to the control blocks above the 16MB line. End of Product-Sensitive Programming Interface

Product-sensitive macros
Product-Sensitive Programming Interface For compatibility with DBT V2 Release 1 HSSR and DBT V1 HSSR, the aliases listed in Table 31 on page 262 are provided for the mapping macros of control blocks of HSSR Engine.

Chapter 13. Compatibility with earlier products

261

These macros are in the HPS.SHPSMAC0 macro library.

Table 31. Aliases of mapping macros for HSSR Engine Control block HDMB HJCB HPCB HPTR HRAN HSDB Mapping macro FABHDMB FABHJCB FABHPCB FABHPTR FABHRAN FABHSDB Alias HDMB HJCB HPCB HPTR HRAN HSDB

For the users who have difficulty in changing the name of mapping macros, an alias is provided for each of these macros to support compatibility. These aliases, however, may not be provided in future releases of this product, so you should be careful in deciding to use the aliases. End of Product-Sensitive Programming Interface

DECN control statement and the unloaded data set

The format of the unloaded data set created by DBT V2 HSSR when the DECN control statement is specified for the FABHURG1 or FABHFSU unload utility was changed by APAR PQ22654. The new format is not compatible with any format that predates that APAR. For details, see the APAR. The unloaded data set created by IMS High Performance Unload is the same as that created by DBT V2R3 HSSR with APAR PQ22654 applied. If you are migrating from DBT V2R3 HSSR, and APAR PQ22654 has not been applied, you may have a problem with any existing reload job for which the input is an unload data set created by DBT V2 HSSR.

Compatibility with DBT V1 HSSR

High Performance Unload supports compatibility with DBT V1 HSSR in the following ways: v JCL can be used without modification. v Input control statements can be used without modification except that the following input control statements may need minor modifications if the same results of the DBT V1 HSSR are required: DIAGG control statement in the HSSROPT data set Position 22 of the DBD control statement in the FABHFSU CARDIN data set Note: For complete explanations on these specifications, see HSSROPT data set on page 122. See also CARDIN data set on page 56. v An application program that uses a DBT V1 HSSR call can be used without reassembling or re-link-editing. v A user exit routine of DBT V1 HSSR needs the following modification to be run under High Performance Unload: A user exit routine must be reassembled or re-link-edited or both in the same IMS system environment under which the routine is used, if the IMS macros that depend on the IMS release levels are used in the routine.

262

Users Guide

 A user exit routine that refers to the HDMBOKEY field of the HDMB control block must be modified from a 3-byte-long field to a 4-byte-long field. A user exit routine can be run either in AMODE=24 or AMODE=31, but a user exit must be link-edited with AMODE=31. See Writing user record-formatting routine on page 317 for the requirements for FABHURG1 exit routines; see User exit on page 71 for the requirements for FABHFSU exit routines. Other differences are the same as those for DBT V2 HSSR. See Compatibility with DBT V2 HSSR on page 255.

Compatibility with PO HSSR

High Performance Unload supports compatibility with PO HSSR. This section is intended for users who are migrating from PO HSSR to High Performance Unload. In v v v v v v v v v v v v this section, the following compatibility issues are discussed: Program names Compatibility of application programs Compatibility of exit routines Compatibility of JCLs Default options Return codes Abend codes Database Tuning Statistics Parallel Scan Facility DB2 DLIBATCH support FABHLDBR utility Mapping macros for control blocks and output records

Compatibility with Branch Office Randomizer, one of the functions provided by PO HSSR, is supported by Sequential Subset Randomizer. See Part 3.

Program names
To keep the compatibility of JCLs, the following aliases for load modules are provided:
Module name FABHX034 FABHBSIM FABHFSU FABHTEST FABHURG1 FABHLDBR FABHEXTR Alias X034000 HSSRBSIM HSSRFSU HSSRTEST HSSRURG1 HSSRLDBR HSSREXTR

No aliases are provided for the cataloged procedures. If you want to use the names of PO HSSR cataloged procedures, copy the corresponding cataloged procedures of High Performance Unload by the names of those for PO HSSR. See Compatibility of JCLs on page 264.

Compatibility of application programs

This section describes the compatibility of application programs.
Chapter 13. Compatibility with earlier products

263

Reassembling
Reassembling your application program by use of the product-sensitive macros is required only for programs or user exit routines that refer to either the HTCB or the HDMB control block.

Relink
Basically, no relink is required for running the application programs written for PO HSSR on High Performance Unload. Relinking with the language interface module (ASMHSSR, CBLHSSR, or PLIHSSR) is required only if you want to run an application under the IMS DL/I batch region controller (DFSRRC00). This is not recommended, but PO HSSR supports it. Include the corresponding language interface module (ASMHSSR, CBLHSSR, or PLIHSSR) from High Performance Unloads HPS.SHPSLMD0 library, and link-edit it with the application program; otherwise an unexpected result, such as a system abend, may occur.

Compatibility of exit routines

The consideration described in Location of control blocks on page 261 applies also to the migration from PO HSSR. See also Mapping macros for control blocks and output records on page 266.

Compatibility of JCLs
This section describes the compatibility of JCLs.

Procedures
As was explained in Program names on page 263, the names of IBM-supplied cataloged procedures for High Performance Unload are different from those for PO HSSR. If you want to continue using the names in PO HSSR, copy the corresponding cataloged procedures by the names in PO HSSR. Table 32 lists the cataloged procedures.
Table 32. Changes of procedure names Region type DLI Region DBB Region ULU Region Name in High Performance Unload FABHDLI FABHDBB FABHULU Name in PO HSSR DLIHSSR DBBHSSR ULUHSSR

Control statements
In High Performance Unload, the year is stated in four digits in each of the following control statements: v PSC control statement of FABHFSU v CTL control statement for FABHPSFC It is recommended that the control statements for your new JCLs be coded in this new format, although the two-digit format is still accepted.

Default options
Certain differences between the default option values of PO HSSR and those of High Performance Unload may interfere with smooth JCL migration. As a solution,

264

Users Guide

High Performance Unload provides the capability to change the default values to those of PO HSSR by replacing the default option table (FABHOPT). This capability also covers the PO HSSRs HSSRGEN function, in which default options are specified. For details, refer to Chapter 19, Setting site default options, on page 335.

Return codes
v The return codes from FABHURG1, FABHFSU, FABHBSIM, and FABHTEST are the same as those from the corresponding PO HSSR utilities HSSRURG1, HSSRFSU, HSSRBSIM, and HSSRTEST, respectively, except that RC01 is returned for empty databases. v FABHPSFS returns RC01 if no segment was retrieved in all PSF phases. This return code is different from that returned from the FSUSUMM utility of FSU-II.

Abend codes
High Performance Unload uses only one abend code, U4013. You cannot change the code.

Database Tuning Statistics

Database tuning statistics are provided by High Performance Unload, too. The layout of the tuning statistics report is slightly different from that provided by PO HSSR, but the contents are the same. You can use the same database tuning method you used with the PO HSSR Database Tuning Statistics reports. See Chapter 10, Using Database Tuning Statistics, on page 167.

Parallel Scan Facility

High Performance Unload supports compatibility with FSU II. It provides the following aliases to support JCL compatibility with FSU II. The only change you must make is to specify the name of the High Performance Unload load module library in the STEPLIB DD. Table 33 shows the names and aliases of the HSSR modules.
Table 33. Names and aliases of HSSR modules Name in High Performance Unload FABHPSFC FABHPSFS FABHPSFM Alias FSUCTRL FSUSUMM FSUMAP

However, the following options specified in the DBD or PSB control statements of the FSUCTRL data set are ignored by High Performance Unload: v For the DBD control statement: Print line count (position 26) Checkpoint option (position 30) Checkpoint frequency (position 31) Optional scan mode (position 40) FSU service aids area (position 48) v For the PSB control statement Format SYNAD option (position 36)
Chapter 13. Compatibility with earlier products

265

The format of the scan control data set CNTLDD created by FSU II FSUCTRL is different from the one created by High Performance Unload. You cannot use the scan control data set created by FSU II FSUCTRL as an input of FABHFSU or FABHPSFS of High Performance Unload. You must rerun a series of JCLs for a parallel scan by using High Performance Unload.

DB2 DL/I Batch support

The method of running a PO HSSR application program that issues SQL calls is described in "Job Control to Run in An HSSR/IMS-Batch/DB2 Mixed-Mode Environment" in PO HSSR Program Descriptions and Operations Manual. This method is supported by High Performance Unload for compatibility with the JCLs written for PO HSSR. However, the method used in the IBM-supplied cataloged procedure FABHDB2 is recommended for your use. In the FABHDB2 procedure, you must specify the following: v In the EXEC statement, specify your HSSR application program name with the MBR= keyword parameter. v In the EXEC statement, specify the DB2 subsystem ID (ssid) with the SSM= keyword parameter. v In the DDITV02 data set, specify the name FABH000, which is the High Performance Unloads program controller, with the ninth positional parameter. For more details about FABHDB2 procedure, see the section Consideration for DB2 DL/I Batch interface on page 94 in Chapter 6, Application programming interface, on page 83.

FABHLDBR utility
The FABHLDBR utility provides the same function as the HSSRLDBR utility of PO HSSR. The name HSSRLDBR is available as an alias of FABHLDBR, so you can use this utility without changing your JCL. For a description of the FABHLDBR utility, see Chapter 10, Using Database Tuning Statistics, on page 167.

Mapping macros for control blocks and output records

Product-Sensitive Programming Interface Users who are usingin their exit routine or application programsthe mapping macros provided by PO HSSR must change the name of those macros when they reassemble those programs in High Performance Unload environment. The relationship between the names of the mapping macros in PO HSSR and those in High Performance Unload is described in Table 34.
Table 34. Changes of mapping macro names for HSSR Engine Macro name in High Performance Unload FABHDMB FABHJCB FABHPCB FABHPTR FABHRAN FABHSDB Macro name in PO HSSR HDMB HJCB HPCB HPTR HRAN HSDB

266

Users Guide

Table 34. Changes of mapping macro names for HSSR Engine (continued) Macro name in High Performance Unload FABHURGR FABHFSUR Macro name in PO HSSR HURGUREC FSUREC

For users who have difficulty in changing the name of mapping macros, an alias is provided for each of these macros to support compatibility. These aliases, however, may not be provided in future releases of this product, so you should be careful in deciding to use the aliases. End of Product-Sensitive Programming Interface

Compatibility with FSU II

FABHFSU provides the following compatibility with FSU II: v FABHFSU output data sets are compatible with FSU II output data sets. v Under FABHFSU, FSU II user exit routines can run without changes and without recompilation. The user exit routine must not access or modify internal, undocumented FSU II control block information. v FABHFSU can often use the same PSBs as FSU II (see PSBGEN compatibility on page 267 for details some minor modifications may be required). v FSU II control statements can usually be used without changes for FABHFSU. They might require minor changes if the different PCBs used to control the content of the output data sets are not contained in the same PSB. v High Performance Unload provides the aliases shown in Table 35 for the FSU II modules. These aliases allow the FSU II JCL to run the FABHFSU PSF.
Table 35. Aliases for FSU II modules Name in High Performance Unload FABHPSFM FABHPSFC FABHPSFS Name in FSU-II FSUMAP FSUCTRL FSUSUMM

PSBGEN compatibility
To ease conversions from FSU II to FABHFSU, some PSBGEN restrictions do not apply to FABHFSU. For example: v The PROCOPT statement fields on the PCB and SENSEG statements can have any value acceptable to IMS. v Field sensitivity can be specified during PSBGEN, but is ignored by FABHFSU.

CON control statement

The CON control statement in CARDIN data set for FABHFSU, which activates the concatenate option, allows you to run some FSU II user exit routines under FABHFSU. The exit routines expect to find the segment prefix and the segment data concatenated in contiguous virtual storage.

Chapter 13. Compatibility with earlier products

267

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 CON

Position 1

Description Code the CON keyword to activate the concatenate option. When you invoke a user exit routine, both FABHFSU and FSU II pass the address of the segment prefix and the segment data to the user exit routine. For FSU II, the segment prefix and the segment data are contiguous in virtual storage. With FABHFSU, the segment prefix and the segment data are not contiguous in virtual storage. The CON control statement instructs FABHFSU to concatenate the segment prefix and the segment data in contiguous virtual storage, before invoking the user exit routine. Since concatenation requires additional CPU cycles, use the CON control statement only for user exit routines that access both the segment prefix and the segment data and assume both are contiguous in virtual storage.

268

Users Guide

Chapter 14. Using JCL for IMS HD Reorganization Unload to run FABHURG1
You can use a JCL that is written for IMS HD Reorganization Unload (DFSURGU0) to run FABHURG1, by adding the High Performance Unloads SHPSLMD0 library ahead of the IMS RESLIB in the STEPLIB concatenation, and by using the DFSISVI0 exit of IMS. Topics: v Preparing the DFSISVI0 exit v JCL compatibility with IMS HD Reorganization Unload

Preparing the DFSISVI0 exit

To run FABHURG1 by using a JCL that was written for IMS HD Reorganization Unload utility, you must prepare the DFSISVI0 exit of IMS. To use the exit, the following level of IMS is required: v APAR PK03282 for IMS Version 7 v APAR PK03616 for IMS Version 8 v APAR PK03617 for IMS Version 9 And you must create a copy of the load module FABHSVI0 with the name DFSISVI0 in a library concatenated to STEPLIB DD.

JCL compatibility with IMS HD Reorganization Unload

Once the DFSISVI0 exit for FABHURG1 is prepared, you can use essentially the same JCL as that used for the IMS HD Reorganization Unload utility (DFSURGU0) to run FABHURG1. EXEC statement The parameters ULU and DFSURGU0 must be specified, otherwise the DFSISVI0 exit does not invoke FABHURG1. DD statements STEPLIB DD Add the SHPSLMD0 library of IMS High Performance Unload to this DD statements ahead of the IMS.SDFSRESL data set. The DFSISVI0 member must be placed in a library. SYSIN DD This data set can contain control statements for either DFSURGU0 or FABHURG1, but not both. Table 36 on page 270 lists the control statements for DFSURGU0 that can be specified for SYSIN DD. The control statement for HSSR Engine can be specified in the HSSROPT data set. SYSPRINT DD This data set contains the statistics reports produced by FABHURG1. The LRECL is 121. The statistics that are produced by HSSR Engine are printed in the HSSRSTAT DD and the HSSRTRAC DD if these DDs are specified. DFSURGU1 DD This required statement defines the primary output data set instead of SYSUT2 DD.

Copyright IBM Corp. 2000, 2007

269

DFSURGU2 DD This optional statement defines the secondary output data set instead of SYSUT3 DD. database DD The DD statements for database data sets are optional. If the DD statements are not present for a non-partitioned database, dynamic allocation will be done by using the DFSMDA member if one is present in STEPLIB or IMSDALIB. The other DD statements are described in IMS Utilities Reference.
Table 36. Supported control statements for DFSURGU0 Control statement for DFSURGU0 PARTITION=partname ,NUMBER=nnn ,STAT=ccc MIGRATE=YES FALLBACK=YES Interpreted control statement for FABHURG1 PARTITION partname nnn SEGSTAT PART (for STAT=DET) MIGRATE FALLBACK

Restrictions: 1. The restrictions in listed in Restrictions on page 34 apply to this processing. 2. If any of the following options are specified, IMS HD Reorganization unload (DFSURGU0) is forced to run instead of FABHURG1. v IMS batch region type other than ULU v DFSUCKPT DD for checkpoint function v DFSURSRT DD for restart function v The control statements for DFSURGU0 other than PARTITION, MIGRATE, and FALLBACK. v MIGRATE=YES for HISAM databases v MIGRATE=YES for secondary indexes v MIGRATX=YES v FALLBACK=YES for PSINDEX databases v Running under IMS Utility Control Facility (DFSUCF00) 3. SB (sequential buffering) is not used even if it specifies the following: v DFSCTL DD statement v The PCB SB= statement in the PSBGEN v DFSSBUX0 (exit routine)

270

Users Guide

Part 2. Customization and diagnosis

Chapter 15. Tuning buffer handlers . . . . . . . . . . . . . Chained Anticipatory Buffer Handler (CAB) . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . . . . . Control statements that affect performance . . . . . . . . . . HSSRCABP control statements . . . . . . . . . . . . . CAB buffer sharing for HALDB . . . . . . . . . . . . . HSSROPT control statements . . . . . . . . . . . . . . HSSRCABP control statements . . . . . . . . . . . . . . CABDD control statement . . . . . . . . . . . . . . . OCCURRENCE control statement . . . . . . . . . . . . RANSIZE control statement . . . . . . . . . . . . . . . NBRSRAN control statement . . . . . . . . . . . . . . NBRDBUF control statement . . . . . . . . . . . . . . OVERFLOW control statement . . . . . . . . . . . . . REFT4 control statement . . . . . . . . . . . . . . . . INTER control statement . . . . . . . . . . . . . . . . PARTPROC control statement . . . . . . . . . . . . . . Tuning aids . . . . . . . . . . . . . . . . . . . . . . Tuning CAB . . . . . . . . . . . . . . . . . . . . . How to tune CAB . . . . . . . . . . . . . . . . . . What you need to know before tuning CAB . . . . . . . . . Well organized databases . . . . . . . . . . . . . . Avoiding performance degradation due to inserts . . . . . . Trade-off decisions between elapsed time and buffer space . . . Size of OSAM blocks and ESDS control intervals . . . . . . . SMF EXCP statistics . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . Example 1: CAB control statements for FABHULU jobs . . . . Example 2: OCCURRENCE control statements for a VSAM ESDS database . . . . . . . . . . . . . . . . . . . . . Example 3: Specifying multiple CABDD groups . . . . . . . Basic Buffer Handler . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . Control statements that affect performance . . . . . . . . . . HSSROPT control statement . . . . . . . . . . . . . . BUF control statement . . . . . . . . . . . . . . . . . Tuning aid . . . . . . . . . . . . . . . . . . . . . . Tuning BB . . . . . . . . . . . . . . . . . . . . . . Buffering KSDS . . . . . . . . . . . . . . . . . . . . . "Native" VSAM . . . . . . . . . . . . . . . . . . . . Specifying and tuning the number of buffers . . . . . . . . . Tuning aids . . . . . . . . . . . . . . . . . . . . . VSAM LSR option for primary index databases . . . . . . . . Specifying the number of buffers . . . . . . . . . . . . . Tuning aids . . . . . . . . . . . . . . . . . . . . . Chapter 16. Using HSSR Program functions . . . Program structure . . . Typical uses . . . . . Restrictions . . . . . . Operating instructions . .
Copyright IBM Corp. 2000, 2007

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

275 275 276 276 277 277 279 279 280 280 282 283 284 284 284 286 286 287 289 289 289 290 290 290 291 292 292 293 293 293 294 295 295 296 296 296 297 297 297 297 297 298 298 298 298 299 299 299 299 299 300

call test . . . . . . . . . . . . . . .

utility . . . . . . . . . . . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

271

JCL for the FABHTEST utility . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . FABHTEST SYSIN data set . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . PCB control statement . . . . . . . . . . . GN and GHN control statement . . . . . . . . GNP and GHNP control statement . . . . . . . GNR and GHNR control statement . . . . . . . GU and GHU control statement . . . . . . . . REPL control statement . . . . . . . . . . . FABHTEST HSSROPT data set . . . . . . . . . FABHTEST HSSRCABP data set . . . . . . . . OutputFABHTEST SYSPRINT data set . . . . . . . Function . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . Example 1: Using FABHTEST for problem determination Example 2: Using FABHTEST to test performance . . Chapter 17. Using the buffer handler simulation Program functions . . . . . . . . . . . . Typical uses . . . . . . . . . . . . . . Program structure . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . Operating instructions . . . . . . . . . . . JCL of the FABHBSIM utility . . . . . . . . Input . . . . . . . . . . . . . . . . . FABHBSIM HSSROPT data set . . . . . . FABHBSIM HSSRCABP data set . . . . . . Output . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

300 300 301 301 301 301 301 302 304 304 305 305 306 306 306 306 307 307 308 309 309 309 310 310 310 310 311 311 311 311 311 313 313 314 315 317 317 317 317 318 318 319 319 320 320 320 321 321 322 322 323 323 323 324

Chapter 18. System programming interfaces . . . . . . . . . Run-Time Environment exit (FABHRTEX) . . . . . . . . . . . . Buffer Handler Initialization exit (FABHCEX) . . . . . . . . . . . Return Code Edit exit (FABHRCEX) . . . . . . . . . . . . . . Interface to Return Code Edit exit routine . . . . . . . . . . . FABHRCEG sample JCL . . . . . . . . . . . . . . . . . Writing user record-formatting routine . . . . . . . . . . . . . Logic of FABHURG1 . . . . . . . . . . . . . . . . . . Common logic . . . . . . . . . . . . . . . . . . . . Record-formatting routine . . . . . . . . . . . . . . . Optional user exit routine. . . . . . . . . . . . . . . . Interface to user record-formatting and optional user exit routines . . Call parameters . . . . . . . . . . . . . . . . . . . . Parameter 1: OUTPUT-AREA . . . . . . . . . . . . . . Description of OUTPUT-AREA for user record-formatting routine Description of OUTPUT-AREA for optional user exit routine . . Parameter 2: Database segment (Segment data) . . . . . . . Parameter 3: Segment prefix . . . . . . . . . . . . . . Parameter 4: HSSR PCB . . . . . . . . . . . . . . . Parameter 5: HSDB . . . . . . . . . . . . . . . . . Parameter 6: Reserved for system use . . . . . . . . . . Parameter 7: RBA of segment prefix . . . . . . . . . . . Parameter 8: Length of segment data . . . . . . . . . . .

272

Users Guide

Parameter 9: Key of next root . . . . . . . . . . Parameters 1013 . . . . . . . . . . . . . . Parameters 14n . . . . . . . . . . . . . . Special SYSIN control statements for user exits . . . . FRMT control statement . . . . . . . . . . . . EXIT control statement . . . . . . . . . . . . OFFS control statement . . . . . . . . . . . . ULEN control statement . . . . . . . . . . . . USEGMAX control statement . . . . . . . . . . Get-by-RBA calls . . . . . . . . . . . . . . . . Structure . . . . . . . . . . . . . . . . . . Finding the RBA required by the Get-by-RBA call . . . HJCB (Job Control Block of HSSR Engine) . . . . HSDB (Segment Descriptor Block of HSSR Engine) . HDMB (Data Management Block of HSSR Engine) . Coding and link-editing the routine . . . . . . . . . Product-sensitive macros. . . . . . . . . . . . . . Chapter 19. Setting site default options . Determining run-time parameters . . . . . Replacing the HSSR option table (FABHOPT) FABHOPTG sample JCL . . . . . . . . Coding the FABHTOPT macro . . . . . . Examples of FABHTOPT macro statements . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

325 325 325 325 326 326 328 328 329 330 330 331 331 332 332 333 333 335 335 336 336 337 339 339 339 340

Part 2. Customization and diagnosis

273

274

Users Guide

Chapter 15. Tuning buffer handlers

HSSR Engine provides two buffer handlers, called HSSR buffer handlers, that provide buffering services for ESDS and OSAM databases: v Chained Anticipatory Buffer Handler (CAB) v Basic Buffer Handler (BB) CAB provides better buffer handling than BB for well-organized HIDAM, HDAM, PHIDAM, and PHDAM databases, and well organized HISAM overflow area. CAB uses more buffer space than BB; however, CAB uses virtual and real storage for a shorter elapsed time. The performance of both buffer handlers depends on how well the databases are organized. Either CAB or BB can replace the DL/I buffer handler. A major advantage of the two HSSR buffer handlers over the DL/I buffer handler is that HSSR buffer handlers reduce the path length of database calls. Both HSSR buffer handlers provide one buffer pool for each PCB. Within a PCB, a buffer pool is provided for each data set group. By contrast, the DL/I buffer handler provides common buffer pools, which are shared by multiple PCBs and multiple data sets. Note: For HALDBs, a buffer pool is provided for each data set group and each buffer pool is shared by all partitions. Table 37 summarizes the buffering functions available to HSSR application programs.
Table 37. Overview of buffering services Chained Sequential I/O ESDS (CAB) OSAM (CAB) ESDS (BB) OSAM (BB) KSDS* Y Y Y Anticipatory Overlapped I/O Y Y Y Look-aside Buffering Y Y Y Y Y Reference Pattern Analysis Y Y -

*: KSDS is buffered by VSAM, not by HSSR buffer handlers. VSAM provides the following buffering functions: v Direct I/O v Immediate-chained sequential I/O v Anticipatory overlapped chained sequential I/O v Look-aside buffering

Topics: v Chained Anticipatory Buffer Handler (CAB) v Basic Buffer Handler on page 295 v Buffering KSDS on page 297

Chained Anticipatory Buffer Handler (CAB)

This section explains the Chained Anticipatory Buffer Handler (CAB).

Copyright IBM Corp. 2000, 2007

275

Description
The Chained Anticipatory Buffer Handler (CAB) is a highly efficient HSSR buffer handler for ESDS and OSAM databases. It is designed to reduce the I/O time, I/O wait time, and elapsed time for HSSR application programs. CAB is the more advanced of the two HSSR buffer handlers. CAB uses the following buffering methods to improve buffering performance: Direct I/O Enables direct access to a single ESDS CI or OSAM block. Immediate (non-overlapped) chained sequential I/O Enables reading of multiple consecutive ESDS CIs or OSAM blocks (called ranges) through Channel Command Word (CCW) chaining. Anticipatory (overlapped) chained sequential I/O Allows CAB to perform overlapped "look-ahead" I/O. This involves the overlapping of CAB I/O with processing and other I/O of the same job step. (Overlapped I/O is also performed with CCW chaining.) CAB decides dynamically when to start overlapped I/O, on the basis of the reference pattern analysis (see below). Reference pattern analysis Forecasts and decides whether chained sequential I/O of multiple blocks or CIs or direct I/O of one single block or CI is preferable. The forecast is based on statistics about reference patterns within the most recently referred-to relative byte address (RBA) ranges of the data set. For example, assume that a segment was inserted after the last database load or reload, and that this segment was stored in an OSAM block or ESDS CI far away from the blocks or CIs containing the other segments of either the same or neighboring database records. In such a case, CAB might forecast that direct I/O is superior to chained sequential I/O for reading the block or CI containing the inserted segment. Look-aside buffering Is an efficient buffering method also used by BB and DL/I buffer handlers. Inter-PCB look-aside buffering (optional) Inter-PCB look-aside is a method that enables CAB to attempt to find a requested RBA in buffers of other HSSR PCBs. If HSSR PCB 1 and HSSR PCB 2 refer to the same database, and if look-aside buffering for HSSR PCB 1 is unsuccessful, HSSR buffer handler tries to find the requested data in the CAB buffers of HSSR PCB 2. If the data is found, the buffer of HSSR PCB 2 is copied into a buffer of HSSR PCB 1.

Restrictions
When CAB is used for ESDS data sets, two restrictions must be observed: v The number of VSAM buffers for the ESDS data set is chosen by CAB. This number must not be overridden by means of JCL specifications or IDCAMS specifications. Do not code the BUFND, BUFSP, and STRNO operands in the AMP parameter of the DD statements. Avoid coding the BUFFERSPACE parameter on a DEFINE or ALTER command. v If multiple HSSR PCBs defined in the PSB refer to the same ESDS database, CAB can be used to buffer only one of these PCBs. Use the BB to buffer the other PCBs referring to this ESDS database. Inter-PCB look-aside buffering option can be activated between CAB buffer and BB buffer for the same ESDS database.

276

Users Guide

Control statements that affect performance

CAB buffering parameters and options are determined automatically on the basis of the characteristics of the database data sets. There is usually no need for tuning. For severely fragmented databases, however, allocating more buffers than the default could improve the performance of your job. In those cases, HSSRCABP control statements should be used. See HSSRCABP control statements on page 277 for the details. Some control statements that are specified in the HSSROPT data set can also affect the performance of CAB. See HSSROPT control statements on page 279 for the details.

HSSRCABP control statements

HSSRCABP data set contains the CAB control statements that are used to change CAB buffering parameters and options for a specified data set or for a specified group of data sets. The statements make it possible to override the default values of the CAB parameters. For information on tuning buffers, see Tuning CAB on page 289, which contains a brief description of the HSSRCABP control statements. For a detailed description of each control statement, see HSSRCABP control statements on page 280. Table 38 lists the HSSRCABP control statements.
Table 38. HSSRCABP control statements Control statement CABDD Description This control statement defines a data set or a group of data sets to which the succeeding CAB control statements apply. See CABDD control statement on page 280. OCCURRENCE This optional control statement specifies the HSSR PCB to which the specifications of the control statement set apply. It is used when multiple HSSR PCBs refer to the same database. See OCCURRENCE control statement on page 282. RANSIZE This optional control statement specifies the size of a range, which is the fixed number of ESDS CIs or OSAM blocks read together in one chained sequential I/O operation. The default value for RANSIZE is determined from the characteristics of each database data set; the default value is determined as follows: v For OSAM, the value is equal to the number of blocks per track v For ESDS, the value is equal to: Half of the number of CIs per CA if the CI size is greater than 2,048 bytes One-fourth of the number of CIs per CA if the CI size is less than or equal to 2,048 bytes This default is efficient for relatively well organized databases. A RANSIZE value smaller than the default can be specified to reduce the buffer space. (In this case, the REFT4 parameter value, if it is coded, must also be reduced.) See RANSIZE control statement on page 283.

Chapter 15. Tuning buffer handlers

277

Table 38. HSSRCABP control statements (continued) Control statement NBRSRAN Description This optional control statement specifies the number of whole ranges to be buffer-resident for look-aside buffering. The NBRSRAN parameter affects the number of successful look-aside operations, as well as buffer space. With well-organized databases, NBRSRAN can be reduced to the minimum value of 3 (because look-aside operations are less important with well organized databases) to reduce the buffer space. With disorganized databases, increasing NBRSRAN can sometimes increase the number of successful look-aside operations. This decreases the number of direct and chained sequential I/Os. See NBRSRAN control statement on page 284. NBRDBUF This optional control statement specifies the number of single blocks or CIs read with direct I/O to be buffer-resident for look-aside buffering. See NBRDBUF control statement on page 284. OVERFLOW This optional control statement affects the buffering of the prime data set group of an HDAM or PHDAM database and describes how the overflow area should be buffered. The OVERFLOW parameter affects the buffering of HDAM and PHDAM databases. If a large number of I/O operations are performed in the overflow area, either the OVERFLOW CAB option (default) or the OVERFLOW SHR option is recommended, because either of them allows chained sequential I/O in the overflow area. Note that the OVERFLOW CAB option requires more buffer space than OVERFLOW SHR. The OVERFLOW BB is reasonable if only a few I/O operations are performed in the overflow area. However, it does not allow chained sequential I/O in the overflow area. See OVERFLOW control statement on page 284. REFT4 This optional control statement is used as a reference threshold value to help determine whether chained sequential I/O or direct I/O should be performed. The default value of REFT4 equals to that of RANSIZE. This value can be decreased or increased, to regulate the number of direct and chained sequential I/O operations. This parameter does not affect the number of buffers to be allocated by CAB. See REFT4 control statement on page 286. INTER This optional control statement activates the CAB inter-PCB look-aside, which enables CAB to attempt to find a requested RBA within buffers of other HSSR PCBs that refer to the same database. See INTER control statement on page 286.

278

Users Guide

Table 38. HSSRCABP control statements (continued) Control statement PARTPROC Description This optional control statement, valid only for HALDB, specifies the access intent for the database or the databases specified on the statement. For a HALDB, CAB buffers are shared among data sets that belong to the same data set group. If only one partition is accessed at a time, as in the unload utilities such as FABHURG1 or FABHFSU utility, you do not need to use this control statement. If more than one partition is accessed randomly, you must specify the number of partitions that are accessed at a time. For the detailed description of PARTPROC statement and the buffer sharing for HALDB, refer to the subsection CAB buffer sharing for HALDB on page 279. See PARTPROC control statement on page 287.

HSSRCABP control statements may be included in the input stream or stored in a partitioned data set (PDS). To centralize all CAB buffering specifications, it is a good practice to store HSSRCABP control statements in a PDS. Each member of the PDS should contain a set of HSSRCABP control statements for one given data set. The HSSRCABP DD statement of the High Performance Unload jobs can then refer to the members of this PDS. Multiple members can be referred to through concatenated DD statements.

CAB buffer sharing for HALDB

For HALDBs, CAB buffers are shared among data sets that belong to the same data set group. If only one partition is accessed at a time, as in the unload utilities such as FABHURG1 or FABHFSU utility, do not code the PARTPROC control statement. In this case, the CAB buffer for each data set group is used exclusively for the partition that HSSR buffer handler accesses at that time. If more than one partition is accessed randomly at a time from your HSSR application program, you must specify a PARTPROC control statement for the HALDB, with R as the second operand and the number of partitions that are accessed at a time as the third operand. CAB buffer handler then calculates the required number of buffers on the basis of the CAB parameters specified for each data sets. It allocates enough buffer space so that CAB buffering requirements specified by the CAB control statement are met for each data set as long as partitions more than the number specified in the PARTPROC statement are not accessed. The total amount of storage used for the CAB buffer space for the HALDB is reported in the HALDB Buffering Statistics report (see HALDB Buffering Statistics on page 147).

HSSROPT control statements

This input data set provides control statements that affect CAB buffering. Table 39 on page 280 shows a brief review of the HSSROPT control statements that you might want to consider using with CAB. (For a detailed description, see HSSROPT
Chapter 15. Tuning buffer handlers

279

data set on page 122.)

Table 39. HSSROPT control statements Control statements BUTR Description This optional control statement activates a trace of CAB buffering activities. The trace is written to the data set defined by the HSSRBUTR DD statement. This data set is used as input to FABHBSIM to simulate CAB buffering in order to tune CAB buffers. The buffer trace is not taken for HALDBs. NOFIX This optional control statement prevents page-fixing. Since a noticeable amount of paging might occur when CAB buffers are not page-fixed, this statement is usually omitted. This option control statement prevents CAB from using the default read-ahead threshold value used by VSAM.

NOVSAMOPT

HSSRCABP control statements

Before you code CAB control statements, you should be familiar with the following general coding rules: v CAB control statements other than the PARTPROC control statement must be provided in groups in the HSSRCABP data set. There must be one group of control statements for each set of data sets to be buffered by CAB. v Each group of CAB control statements must begin with a CABDD statement that identifies (by ddname) a set of data sets to be buffered by CAB. The group ends when the next CABDD statement or the end-of-file is encountered. v A group may contain additional control statements after the CABDD statement. v The first control statement entry must be a keyword that identifies the type of control statement being defined. It is often the name of a CAB parameter. v The keyword must always be followed by a single blank. v The blank is followed by variable data. This variable data is often the value to be assigned to a CAB parameter.

CABDD control statement

This required control statement defines the data sets to be buffered by CAB. It must be the first statement in a group of statements. The CABDD control statement can have one of the following formats:
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 CABDD ddname pattern *HD *HS *PHDMIGRATE *ALL

Position 1

Description Code the CABDD keyword to change the CAB buffering parameters for the set of data sets determined from the value specified in the operand of the statement.

280

Users Guide

This required entry identifies a set of data sets to which the succeeding CAB control statements apply. Code one of the following keywords:

Chapter 15. Tuning buffer handlers

281

Keyword ddname

Description Indicates that the succeeding CAB control statements apply to the data set whose DD name is ddname. Indicates that the succeeding CAB control statements apply to the data sets whose DD names match the wild card string pattern. The pattern is a string of alphanumeric characters, including wild card characters. You can use two kinds of wild card character: an asterisk (*) and a percent (%) symbol. An asterisk is treated as a sequence of 0 to 8 characters; and, a percent symbol is treated as a single character. If two or more asterisks are specified sequentially, only the first asterisk is recognized. You cannot specify asterisks and percent symbols simultaneously. The pattern string must be enclosed by single quotation marks.

'pattern'

*ALL *HD

Indicates that the succeeding CAB control statements apply to all ESDS or OSAM data sets. Indicates that the succeeding CAB control statements apply to all ESDS or OSAM data sets of all HD databases, including PHDAM and PHIDAM databases. Indicates that the succeeding CAB control statements apply to all ESDS data sets of all HISAM databases. Indicates that the succeeding CAB control statements apply to all ESDS or OSAM data sets of all PHIDAM and PHDAM databases.

*HS

*PHD

OCCURRENCE control statement

This optional control statement specifies which HSSR PCBs, in the PSB, are to be buffered by CAB. It is used only when multiple HSSR PCBs refer to the same database. It identifies the HSSR PCB to which the specifications of the control statement group apply. For a database that uses the OSAM for its database data sets, if no OCCURRENCE control statement is entered, HSSR assumes that the set of control statements applies to all HSSR PCBs referring to the data set or data sets identified by the CABDD statement. For a database that uses the VSAM ESDS for its database data sets, CAB buffering can be used for only one PCB, which, by default, is the first PCB referring to the database. BB buffering is used when HSSR buffer handler accesses the database through the rest of the PCBs. This default can be changed by the OCCURRENCE control statement.

282

Users Guide

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 OCCURRENCE n

Position 1 12

Description Code the OCCURRENCE keyword to activate the OCCURRENCE option. This entry specifies that the group of control statements applies to the nth HSSR PCB referring to the data set identified by the CABDD statement.

RANSIZE control statement

This optional control statement denotes the size of a range, which is the number of OSAM blocks or ESDS CIs that are read together in chained mode. RANSIZE affects both the elapsed time and the buffer space. The number of sequential buffers allocated by CAB for each data set of each PCB to which CAB is used is:
RANSIZE x (NBRSRAN + 1)

The default RANSIZE value for each database data set is determined by HSSR buffer handler from the characteristics of the data set, such as the block size or the CI size.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 RANSIZE n

Position 1 9

Description Code the RANSIZE keyword to change the RANSIZE value. Code the numeric value n left-justified with a numeric value from 2 through 255.

Notes: 1. Performance is questionable when CAB buffers OSAM data sets with a RANSIZE smaller than 4. 2. A limited number of CIs can be read by the access method within one single-chained I/O operation. The limit depends on the CI size. When HSSR buffer handler detects that the RANSIZE value causes the use of more than a limited number of CIs for an ESDS database, the buffer handler changes the value of RANSIZE to the allowable maximum. 3. When the RANSIZE default value is overridden, the REFT4 parameterif it is codedmust be adjusted. (See the description of the REFT4 control statement on page 286.)

Chapter 15. Tuning buffer handlers

283

NBRSRAN control statement

This optional control statement specifies the number of whole ranges to be resident in each buffer for look-aside purposes. NBRSRAN affects both the buffer space and the number of successful look-aside operations. It also affects the number of I/Os if a database is not well organized. For each data set of each PCB for which CAB is used (except for the prime data set group of HDAM and PHDAM, as described in OVERFLOW control statement on page 284), CAB allocates the following number of buffers:
RANSIZE x (NBRSRAN + 1)

If the database is well organized, you do not need to change the default value; if the database is disorganized, increasing the NBRSRAN value could increase the benefits achieved through look-aside buffering.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 NBRSRAN n

Position 1 9

Description Code the NBRSRAN keyword to change the NBRSRAN value. Code the numeric value n to be left-justified with a numeric value from 3 through 9999 It is the number of ranges resident in a buffer for look-aside purposes. The default value assigned to NBRSRAN is 8.

NBRDBUF control statement

This optional control statement specifies the number of direct buffersthat is, the number of single blocks or CIs read in direct modethat should be resident in the buffer for look-aside purposes.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 NBRDBUF n

Position 1 9

Description Code the NBRDBUF keyword to change the number of direct buffers. Code the numeric value n from 3 through 255 to be left-justified. The default value assigned to NBRDBUF is twice the number assigned to RANSIZE, which is the number of single blocks or CIs resident in a buffer for look-aside purposes.

OVERFLOW control statement

This optional control statement specifies how the overflow area of the prime data set group of an HDAM database or the overflow area of the prime data set group of each partition of a PHDAM database, should be buffered. The OVERFLOW control statement affects the buffering efficiency for the prime data set group of an HDAM

284

Users Guide

database, or of the prime data set groups of a PHDAM database; especially, it affects both the size of the buffer space and the elapsed time. The same OVERFLOW statement must be specified for each prime data set group of partitions of a PHDAM database.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 OVERFLOW CAB SHR BB

Position 1 10

Description Code the OVERFLOW keyword to change the OVERFLOW option. Code one of the following three keywords: Keyword CAB Description This is the default. CAB specifies that separate CAB buffers are allocated for the root addressable area and the overflow area, respectively. Chained sequential I/O is possible in both areas. The total number of buffers allocated for the first data set group of HDAM is given by:
2 x (RANSIZE x (NBRSRAN + 1) + NBRDBUF)

The total number of buffers allocated for the first data set group of a PHDAM database depends on the PARTPROC statement specified for the database. SHR SHR instructs CAB to use the same buffer for both the root addressable area and the overflow area. Chained sequential I/O is possible in both areas. The number of (shared) buffers allocated for the first data set group of HDAM is:
RANSIZE x (NBRSRAN + 1) + NBRDBUF

The total number of buffers allocated for the first data set group of a PHDAM database depends on the PARTPROC statement specified for the database. BB BB does not allow chained sequential I/O in the HDAM or PHDAM overflow area. If only a small number of I/Os are performed in the overflow area, the OVERFLOW BB option is reasonable. The OVERFLOW BB option specifies that CAB buffers the root addressable area and that BB buffers the overflow area. No chained sequential I/O takes place in the overflow area.
Chapter 15. Tuning buffer handlers

285

The OVERFLOW BB option uses less buffer space than the OVERFLOW CAB option. For HDAM, the total number of buffers allocated is the sum of the following: v For the root addressable area,
RANSIZE x (NBRSRAN + 1) + NBRDBUF

v For the overflow area,

NBRDBUF

The total number of buffers allocated for the root addressable areas and overflow areas of the first data set group of a PHDAM database depends on the PARTPROC control statement specified for the database.

REFT4 control statement

This optional control statement is used as a reference threshold value. The REFT4 threshold value helps determine whether chained sequential I/O or direct I/O should be performed. When the number of referred-to OSAM blocks or ESDS Control Intervals (CIs) is below REFT4, CAB usually performs direct I/O. When the number of referred-to OSAM blocks or ESDS CIs has reached REFT4, CAB usually performs chained sequential I/O. The REFT4 setting helps determine how often direct I/O and chained sequential I/O are performed. If the REFT4 setting is too low, CAB may perform chained sequential I/O in cases where direct I/O is superior. Some of the OSAM blocks or ESDS CIs read in chained sequential mode are not referred to at this time. If the REFT4 setting is too high, CAB may perform direct I/O in cases where chained sequential I/O is superior. CAB reads consecutive OSAM blocks or ESDS CIs individually in direct mode, instead of reading them together in chained sequential mode. Usually, you do not need to code the REFT4 control statement. You should code the control statement only when the default value is not satisfactory. The recommended range of values for REFT4 is between 100% and 200% of RANSIZE. For example, when RANSIZE=8, the recommended range of values for REFT4 is from 8 to 16 inclusive.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 REFT4 n

Position 1 7

Description Code the REFT4 keyword to change the REFT4 threshold. Code the numeric value n to be left-justified. The default value is equal to the RANSIZE value.

INTER control statement

This optional control statement activates the CAB Inter-PCB Look-Aside. (Inter-PCB Look-Aside is a method that enables CAB (or BB) to attempt to find a requested RBA within buffers of other HSSR PCBs.)

286

Users Guide

The INTER control statement must be used to activate this feature. By default, no Inter-PCB Look-Aside is done in CAB. This option has a meaning only when multiple HSSR PCBs refer to the same database.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 INTER YES

Position 1 7

Description Code the INTER keyword to change the INTER option. Code YES to activate the CAB inter-PCB look-Aside.

PARTPROC control statement

For a HALDB, CAB buffers are shared among the data sets in a data set group. As in the unload utilities such as the FABHURG1 or FABHFSU utility, if only one partition is accessed at a time, you do not need to use this control statement.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PARTPROC dbd_name PARTPROC dbd_name S PARTPROC dbd_name R nnnn

Position 1 10

Description Code the PARTPROC keyword to change the PARTPROC option for a HALDB or for all HALDB. This required entry identifies the HALDB or HALDBs to which the PARTPROC option applies. The string must be left-justified. Keyword dbd_name *PHD Description Indicates that the PARTPROC option applies to the HALDB identified by the DBD dbd_name. Indicates that the PARTPROC option applies to all HALDBs.

19

Code one of the following keywords: Keyword S|blank Description The keyword 'S' stands for 'sequential access' and tells CAB to prepare a buffer space that can buffer only one partition for each HALDB specified on the column 10. If this option is specified, the CAB parameters RANSIZE, NBRSRAN, NBRDBUF, OVERFLOW, REFT4, and INTER that are specified for a partition are reset when the processing of the partition starts. This is the default for all HALDBs.
Chapter 15. Tuning buffer handlers

287

The keyword 'R' stands for 'random access' and instructs CAB to prepare the buffer space that can buffer nnnn partitions of the HALDB specified on the column 10. If the number nnnn on column 21 is omitted, nnnn = 2 is assumed. If this keyword is specified, the CAB buffers each data set on the basis of CAB parameters RANSIZE, NBRSRAN, NBRDBUF, OVERFLOW, REFT4, and INTER that are specified for the partition, as long as no more than nnnn partitions are accessed at a time.

21

Specify the maximum number of partitions to be accessed at a time. The default value is 2 when the keyword 'R' is specified in column 19. This parameter can be specified only when the keyword 'R' is specified in column 19. The number nnnn must be 1 to 4 characters long and must be left-justified.

Note: If multiple PARTPROC statements are specified for the same HALDB, the last statement is treated as a valid statement for the HALDB.

288

Users Guide

Tuning aids
The following aids is provided for tuning the buffer handler: v If 'CABSTAT YES' is coded in HSSROPT data set, extensive buffer handler statistics are printed at the end of the job step on the HSSRSTAT data set. See CAB Statistics report on page 147 and Data Set I/O Statistics report on page 145. Once you have tuned the buffer handler, you can remove the CABSTAT control statement to reduce the content of the report. If no CABSTAT control statement is coded, or 'CABSTAT NO' is specified in the HSSROPT data set, only the summary page of the CAB Statistics is printed for each buffer pool. v The FABHBSIM utility enables you to observe the effect that changes to parameters on HSSRCABP control statements have on buffer handler performance. FABHBSIM can be used for simulations of both CAB and BB. Note: FABHBSIM cannot be used for HALDB.

Tuning CAB
The CAB performance can be considered satisfactory when the following conditions are met: v The number of OSAM blocks or ESDS CIs read in chained sequential mode is much greater than the number of blocks or CIs read in direct mode. v The percentage of unreferred-to sequential buffers is below 15 or 20%. v Elapsed time is substantially smaller with CAB than with BB. v The amount of buffer space that is used is acceptable. If you dont get satisfactory results by running your High Performance Unload job with the default CAB parameters, you can attempt tuning.

How to tune CAB

The following steps describe a possible approach to tuning CABs reference pattern analysis logic: 1. Run your application program or the FABHTEST utility on a dedicated system with CAB and with the default values for the CAB parameters. Activate the machine-readable buffer handler trace for future FABHBSIM runs. (This increases the processor time slightly; bear this fact in mind when you compare processor times.) Note: Performance tests with databases that contain fewer than 300,000 segments are not reasonable, because CAB buffer handler has a high initialization overhead. 2. Run the same program with BB on a dedicated system by coding the BUF control statement in the HSSROPT DD. 3. Check the results of both runs. First compare the elapsed time. Note the number of sequential buffers not referred to, and the number of blocks read in chained sequential mode and direct mode. If your database is well organized, CAB should show excellent elapsed time figures. Unless you want to reduce the buffer space, no further tuning is needed. If your database is poorly organized, CAB may show moderate or disappointing results.

Chapter 15. Tuning buffer handlers

289

If the improvements are moderatethat is, the elapsed time of the CAB run is between 65% and 80% of the BB runyou should investigate whether the database reorganization interval is appropriate and whether the free space specifications are appropriate. You can also investigate the increase of the NBRSRAN parameter and the tuning of the REFT4 parameter to decrease a little more the elapsed time. If the results are disappointingthat is, if the elapsed time of the CAB run is not below 80% of the first runthe best thing, probably, is to reorganize the database more frequently to improve the specification of free space. 4. If you decide to rerun with modified CAB parameters, you can use FABHBSIM to compare the HSSRSTAT statistics of the original run with those of the new run. The statistics to be compared are the number of direct I/Os, the number of chained sequential I/Os, the number of sequential buffers note referred to, and the timing statistics.

What you need to know before tuning CAB

This section describes the things you need to know before tuning CAB. Well organized databases: The most crucial CAB performance factor is that a database should be well organized. Such databases allow more chained sequential I/O and result in improved performance for HSSR application programs. Avoiding performance degradation due to inserts: CAB performs best with recently loaded or reorganized databases. The performance degrades when the database becomes older, because segments that have been inserted cannot be stored in the same OSAM block or ESDS CI. This is especially true if the inserted segments of a given database key range (HIDAM and PHIDAM) or RAP range (HDAM and PHDAM) are scattered in multiple blocks or CIs. The performance degradation is encountered not only with CAB, but also with different kinds of processing, including online, and more specifically with almost any kind of sequential database processing. To reduce performance degradation, two solutions can be investigated: v Reorganize the database more frequently. v Specify free space within the database in such a way that the database is better protected from performance degradations. This solution might require more DASD space for the database; however, most jobs including online jobs benefit from the free space specifications. The impact of free space specifications on performance occurs when initially loading or reloading the database. If database load or reload occurs infrequently, you should plan for free space specifications prior to initially loading the database. Here is an example of a free space implementation for a database: v Try to store inserted segments into the same block or CI as the hierarchical neighbor segments by means of standard DBDGEN specifications, which reserve free space within each block or CI. v Segments that cannot be inserted in the same block as the hierarchical neighbors should not be scattered into numerous blocks, but should be grouped by database key range or RAP range into a few blocks. The user achieves this by means of standard DBDGEN specifications that reserve entirely free blocks and by taking care of the IMS HD bit map blocks.

290

Users Guide

Without such a grouping, segments of a given database key range or RAP range that are inserted after database reorganization could be scattered in a number of different blocks. Retrieval of each of these segments could require up to one I/O per segment. To implement these free space specifications, consider the following actions that can be taken: v The FRSPC fspf operand on the DATASET statement of a DBD can be used to specify free space within each block. This free space improves the performance of most programs, including online programs, that access the database. v The FRSPC fbff operand on the DATASET statement of a DBD can be used to leave each nth block entirely free for future segment insertion. Note: For HALDBs, use the HALDB Partition Definition Utility to specify FRSPC parameters. v A dummy segment can be defined in the DBD. This dummy segment must be long enough to achieve the following goal: The IMS bit map blocks should indicate that only entirely free blocks contain enough free space to contain the longest database segment. v The DBDGEN must be performed, and the database must be reloaded. To decide where to store segments inserted after a database reload, the HD space search algorithm used by IMS uses the following criteria: 1. Same block 2. On the same track: any blocks that were originally left entirely free 3. On the same cylinder, then within n cylinders: any blocks that were originally left entirely free 4. Any block at the end of data set, based on the bit map 5. Any blocks that were originally left entirely empty. First, search criterion 1 tries to insert the segment in the same block as its neighbors. If this fails, search criteria 2 and 3 try to group segments of a key range or RAP range into a few blocks of the same track, the same cylinder, or neighbor cylinders. Only if search criteria 1, 2, and 3 fail, scattering can occur during segment insertion. Note: The list of search criteria has been simplified for the sake of demonstration. In reality, the search criteria used by IMS also consider CIs or blocks actually in the IMS buffer pools to reduce the amount of grouping. For a more detailed description of the HD space search algorithm, seeIMS Administration Guide: Database Manager.

Trade-off decisions between elapsed time and buffer space

The RANSIZE parameter has the greatest effect on both elapsed time and buffer space. The number of buffers allocated by CAB to each PCB/data set combination, except for the prime data set group of HDAM, is given by:
(RANSIZE x (NBRSRAN + 1)) + NBRDBUF

Additional CAB buffers of the same number are allocated for the overflow area of the prime data set group of HDAM and PHDAM if 'OVERFLOW CAB', which is the default, is specified. CAB default parameters are:
Chapter 15. Tuning buffer handlers

291

RANSIZE=(the value determined from data set characteristics) NBRSRAN=8 NBRDBUF=RANSIZE x 2 OVERFLOW=CAB REFT4=RANSIZE

The use of these default parameter values should greatly reduce elapsed time. The default values result in the allocation of buffers of RANSIZE x 11 (and additional CAB buffers for the overflow area of the prime data set group of HDAM or PHDAM). Although CAB uses a fair amount of storage for buffer space, it normally uses virtual and real storage for less time than BB. By default, the CAB buffers are page-fixed for better performance, but the page-fixing can be disabled by coding the NOFIX control statement in the HSSROPT DD. In cases where CAB performance is not superior to BB performance (for example, with disorganized databases), use BB rather than CAB. This saves both virtual and real storage.

Size of OSAM blocks and ESDS control intervals

Smaller blocks or CIs are often beneficial to random processing (including online processing). When, during random processing, segments of a database record are accessed, it seldom makes sense to perform I/O for huge blocks or CIs containing much data belonging to many other database records. If, during direct processing, the blocks or CIs are smaller, the data transfer time often decreases. Therefore, the use of DASD string controllers, DASD control units, and channels can drop. The buffer space might also decrease. Larger blocks or CIs are often beneficial to sequential processing since, with conventional buffer handlers, one full DASD rotational delay is lost between each I/O for two consecutive blocks or CIs. Increasing the block size or CI size decreases the number of blocks or CIs and, consequently, the number of lost rotational delays and the elapsed time. Therefore, the user must sometimes make trade-off decisions in favor of random processing or sequential processing. With CAB, this problem can sometimes be solved by using small block sizes or CI sizes for random processing. Sequential processing with CAB does not suffer, since CAB may chain CCWs in order to read many of these smaller blocks together as if they were parts of one single larger block.

SMF EXCP statistics

Statistics from the System Management Facilities (SMF) about the Execute Channel Program (EXCP) can sometimes be confusing. The SMF EXCP statistics for data sets used by HSSR Engine should be used for reference only. "CAB Statistics" does not report the EXCP counts, but does report the number of I/O requests. For VSAM ESDS, one GET macro is used by one I/O request. For OSAM, the READ macro is used and the number of READ macros is: v 1 for direct I/O. v The value of RANSIZE for chained sequential I/O.

292

Users Guide

Examples
This section describes the examples of specifying the following: v HSSRCABP statements for FABHULU jobs v OCCURRENCE control statements for a VSAM ESDS database v multiple CABDD groups These examples are for nonpartitioned databases. For examples of how to specify CAB control statements for PHDAM or PHIDAM databases, see Chapter 7, Processing High Availability Large Databases, on page 103. These examples are not examples of a real production job. They merely demonstrate how HSSRCABP control statements, as well as HSSROPT control statements, can be specified.

Example 1: CAB control statements for FABHULU jobs

The following is an example of how to specify CAB control statements for an HSSR application program running in the ULU region by using the FABHULU cataloged procedure. The FABHURG1 unload utility is used in this example, but the same explanation applies to any other HSSR application program running in the ULU region. In the following JCL, 'CABDD *ALL' is coded in HSSRCABP DD, which means that the CAB parameter values are overridden by the value specified in the succeeding control statements. Assume that the database processed is well organized and not fragmented, and that the set of parameters is selected to reduce the amount of buffer space used by CAB from the default specification and to allocate 19 CAB buffers.
// EXEC FABHULU,MBR=FABHURG1,DBD=HIDOSAM //HSSRCABP DD * CABDD *ALL RANSIZE 4 NBRSRAN 3 NBRDBUF 3 OVERFLOW SHR REFT4 6 /* //HIDOSAMD DD DSN=TESTDS.HIDOSAMD,DISP=SHR //HIDOSAMX DD DSN=TESTDS.HIDOSAMX,DISP=SHR //SYSPRINT DD SYSOUT=A

Example 2: OCCURRENCE control statements for a VSAM ESDS database

In the following FABHDLI job, 'CABDD *ALL' is coded in HSSRCABP DD. This means that, for all databases that are read by HSSR Engine using CAB buffering, the CAB parameter values to be overridden by the value specified in the succeeding control statements. For a database that uses the VSAM ESDS for its database data sets, CAB buffering can be used for only one PCB, which, by default, is the first PCB, in the PSB, that refers to the database; and BB buffering is used when HSSR Engine accesses the database through the rest of the PCBs. This default can be changed by use of the OCCURRENCE control statement.

Chapter 15. Tuning buffer handlers

293

The OCCURRENCE statement in this example specifies that the second PCB in the PSB is to be buffered with CAB. The succeeding statements allocate 23 CAB buffers for the database when it is accessed through the second PCB. The HSSROPT data set contains control statements that affect CAB buffering. The 'HSSRPCB *ALL' statement specifies that all DB PCBs in the PSB HRDHDAMG are HSSR PCBs. The BUTR control statement activates a trace of CAB buffer handler activities; the HSSRBUTR DD statement defines the output data set. The NOVSAMOPT prevents CAB from using the default read-ahead threshold value used by VSAM. The SYSIN data set provides the input to the FABHTEST utility.
// EXEC FABHDLI,MBR=FABHTEST,PSB=HRDHDAMG //SYSIN DD * PCB 2 GN GB /* //HSSROPT DD * HSSRPCB *ALL BUTR NOVSAMOPT /* //HSSRCABP DD * CABDD *ALL OCCURRENCE 2 RANSIZE 4 NBRSRAN 4 NBRDBUF 3 OVERFLOW SHR REFT4 6 /* //ESDSDATA DD DSN=TESTDS.ESDSHDAM,DISP=SHR //SYSPRINT DD SYSOUT=A //HSSRBUTR DD DSN=HPU.HSSRBUTR,UNIT=TAPE,DISP=(,KEEP)

Example 3: Specifying multiple CABDD groups

In this example, assume that the user application program USERAPPL accesses two databases DB1VSAM and DB2OSAM; the HDAM database DB1VSAM over VSAM ESDS has data set groups DB1DSG1 and DB1DSG2; and the HIDAM database DB2OSAM over OSAM has data set groups DB2ROOT, DB2DEP01, and DB2DEP02. In the following JCL, two CABDD groups, 'DB1DSG%' and 'DB2*', are specified in HSSRCABP DD. By using the wild cards in DD names 'DB1DSG%' and 'DB2*', we cause all data sets for DB1VSAM and for DB2OSAM to be selected. The CAB control statements succeeding each CABDD statement specify the CAB parameters for the specified CABDD group.

294

Users Guide

// EXEC FABHDLI,MBR=USERAPPL,PSB=PSBAPPL1 //HSSROPT DD * HSSRPCB *ALL DBSTATS /* //HSSRCABP DD * CABDD DB1DSG% RANSIZE 4 NBRSRAN 10 NBRDBUF 10 REFT4 6 OVERFLOW SHR CABDD DB2* RANSIZE 4 NBRSRAN 20 REFT4 6 /* //DB1DSG1 DD DSN=TESTDS.DB1.DSG1,DISP=SHR //DB1DSG2 DD DSN=TESTDS.DB1.DSG2,DISP=SHR //DB2ROOT DD DSN=TESTDS.DB2.DSROOT,DISP=SHR //DB2DEP01 DD DSN=TESTDS.DB2.DSDEP01,DISP=SHR //DB2DEP02 DD DSN=TESTDS.DB2.DSDEP02,DISP=SHR //DB2INDEX DD DSN=TESTDS.DB2.DSINDEX,DISP=SHR //applout DD SYSOUT=A

Basic Buffer Handler

This section explains the Basic Buffer Handler.

Description
The Basic Buffer Handler (BB) provides ESDS and OSAM data sets with look-aside buffering services similar to those provided by the DL/I buffer handler. BB might yield better performance than the DL/I buffer handler, because HSSR Engine reduces the path length for database calls and uses direct I/O and look-aside buffering methods. However, BB does not provide the immediate-chained sequential I/O or the anticipatory overlapped chained sequential I/O, which are provided by CAB. BB is used for ESDS and OSAM data sets if a BUF control statement is specified, in the HSSROPT data set, for the database. To reduce the path length of an HSSR call, each HSSR PCB and each data set group within each PCB has its own buffers for OSAM and ESDS, which is the same as CAB. If HSSR PCB 1 and HSSR PCB 2 refer to the same database, and look-aside buffering for HSSR PCB 1 is unsuccessful, the buffer handler tries to find the requested data in the BB buffers of HSSR PCB 2. If it finds the data, the buffer of HSSR PCB 2 is copied into a buffer of HSSR PCB 1. Buffers are maintained on a last-referred-to basis. An output statistical report is provided to the user on the HSSRSTAT data set.

Chapter 15. Tuning buffer handlers

295

Control statements that affect performance

This section explains the control statements that affect performance.

HSSROPT control statement

Table 40 shows a brief description of the HSSROPT control statements that you might want to consider using with BB. (For a detailed description, see HSSROPT data set on page 122.)
Table 40. HSSROPT control statements for Basic Buffering Handler Control statements BUF Description If you want to use BB for ESDS and OSAM data sets, you must code this statement for the DBD, and specify the number of BB buffers. This statement is optional. The default number of buffers depends on how the PCB is defined as an HSSR PCB. See BUF control statement on page 296 for the details. BUTR This optional control statement activates a trace of BB buffering activities. The trace is written to the data set defined by the HSSRBUTR DD statement. This data set is used as input to FABHBSIM to simulate BB buffering in order to tune BB buffers. This control statement is not allowed for PHDAM or PHIDAM databases.

BUF control statement

The optional BUF control statement is used to specify a database for which the BB buffer handler is to be used, and to override the default number of buffers for BB. The BB buffer handler allocates a separate buffer pool for each data set group of the database. It also allocates a certain number of buffers to each of these buffer poolseither the default or a specified number. The default number of buffers depends on how the PCB is defined as an HSSR PCB. If an HSSR PCB is defined by use of either an HSSRPCB or an HSSRDBD control statement, and the value to the KEYLEN keyword for the PCB is less than 200, BB allocates six basic buffers for each data set as the default. If the KEYLEN value for the PCB is greater than 200, the number of basic buffers to be allocated is determined as explained in Number of Basic Buffers for an HSSR PCB on page 257.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 BUF dbdname ,nbrbuffers

Position 1

Description Code the BUF keyword to specify a database for which the BB buffer handler is to be used and to override the default number of buffers for BB. Code the 8-byte dbdname to specify the database for which the default number of buffers will be overridden (if the database name is not 8 bytes long, include trailing blanks).

296

Users Guide

13 14

Add a comma (,) to separate the database name from the number of buffers. nbrbuffers is the number of buffers that you want BB to allocate for a buffer pool.

Tuning aid
HSSR Engine provides the following aids for tuning the BB buffer handler: v BB I/O and buffer handler statistics are provided in the HSSRSTAT data set (see Data Set I/O Statistics report on page 145). v The FABHBSIM utility enables you to observe the effect of changes to BUF control statements in the HSSROPT data set.

Tuning BB
There is no formula for calculating the optimum number of ESDS or OSAM buffers, because each database or application has its own characteristics. But take the following into account: v For sequential processing of a recently loaded database, two ESDS or OSAM buffers should be sufficient. v For sequential processing of an older, not well-organized database, additional ESDS or OSAM buffers might improve performance. v When a database is processed at random, allocation of more than two buffers might be beneficial. The nth random I/O operation might find its data in a buffer already filled during an earlier random operation.

Buffering KSDS
By default, HSSR Engine uses "native" VSAM (VSAM with the No Shared Resource Pool Option) to read a KSDS. Native VSAM provides both immediate chained sequential I/O and anticipatory overlapped chained sequential I/O. In batch processing, DL/I uses the Local Shared Resource (LSR) Pool option. This does not provide immediate chained sequential I/O, but provides more efficient look-aside capabilities for random database processing. To improve the performance (through better look-aside buffering) of programs that issue a large number of GU calls to HIDAM or PHIDAM databases, HSSR Engine makes it possible, as an option, to process the primary index of an HIDAM and PHIDAM database to be processed with the LSR option. For an HSSR application program, VSAM provides the following buffering services: v Immediate chained sequential I/O v Anticipatory overlapped chained sequential I/O v Direct I/O v Look-aside buffering

"Native" VSAM
This section explains the "Native" VSAM.

Specifying and tuning the number of buffers

The number of buffers for the processing of the index and data components of the KSDS cluster can be specified separately on the JCL DD statement. The DD statement should be coded as follows:

Chapter 15. Tuning buffer handlers

297

//KSDS DD DSN=IMSVS.VSAM,DISP=SHR, // AMP=(BUFND=8,BUFNI=4)

BUFND is used to specify the buffer number for the data component and BUFNI for the index component of the KSDS cluster. If the AMP parameter is not coded, the HSSR Engine sets the number of the two buffers for NSR as follows: v BUFNI = Number of levels v BUFND = One-fifth of the number of CIs per CA

Tuning aids
HSSR Engine does not provide statistics on VSAM KSDS buffering. Your installation might be able to provide SMF statistics that can be used to determine the optimum number of buffers.

VSAM LSR option for primary index databases

If primary index databases are to be processed with VSAM LSR, specify the LSR option in the HSSROPT data set. For the details of the LSR control statement, see LSR control statement on page 133. Usually, you need not take any other step to use 'LSR YES' option. However, if a VSAM logical error occurs because all VSAM place holders are used in the DLI or DBB region, specify the appropriate STRINGNM parameter on the POOLID control statement or the STRINGMX parameter on the OPTIONS statement in the DFSVSAMP data set. The appropriate number is shown by the following formula: 2x(the number of KSDS data sets that are to be accessed from your application program)+2 Note: This option has no effect if the root segment of an HIDAM or PHIDAM database has no physical twin backward or hierarchical backward pointers. If the PSB has at least one DB PCB that has a PROCOPT allowing database update (PROCOPT=A, R, I, L, or D), this option is canceled internally.

Specifying the number of buffers

The number of buffers in the Local Shared Resource Pools is defined in the DL/I DFSVSAMP data set.

Tuning aids
If the DFSSTAT data set is specified, IMS will print statistics about LSR buffering in it at the end of the job step. HSSR Engine will not print any statistics report on its own.

298

Users Guide

Chapter 16. Using HSSR call test utility

FABHTEST is the HSSR Engine test utility that runs a sequence of HSSR or DL/I calls against an IMS database. FABHTEST is useful for performance testing and for problem determination of HSSR Engine. It can be used to compare the performance of an application program making HSSR calls with the performance of the same program making DL/I database calls against the same database. Topics: v v v v v v v v v Program functions Program structure Typical uses Restrictions Operating instructions on page 300 JCL for the FABHTEST utility on page 300 Input on page 300 OutputFABHTEST SYSPRINT data set on page 306 Examples on page 307

Program functions
FABHTEST issues database calls against IMS databases in the sequence specified by control statements. It issues HSSR calls or DL/I calls through the appropriate language interface. HSSR calls are made unless the HSSR option DBDL1 forces DL/I calls to be issued. The HSSR or DL/I calls acceptable to FABHTEST are a subset of DL/I database calls.

Program structure
FABHTEST runs as an HSSR application program.

Typical uses
FABHTEST can be used to do the following: v Run a sequence of database calls against a database v Help in problem determination v Compare performance of HSSR calls versus DL/I calls v Test performance using CAB

Restrictions
FABHTEST has the following restrictions: v No printout of calls issued against a DL/I database PCB can be obtained. v FABHTEST cannot be run with a DLIBATCH procedure, because it depends on information in the control blocks of HSSR Engine. v The FABHTEST utility cannot process a HALDB by partition. It processes the HALDB as an entire database. v For REPL calls, use PROCOPT=R. Notes:

Copyright IBM Corp. 2000, 2007

299

1. REPL call is supported for the compatibility with DBT HSSR and PO HSSR (see Chapter 13, Compatibility with earlier products, on page 255). 2. REPL calls are not allowed for PHDAM or PHIDAM databases.

Operating instructions
You can run the FABHTEST utility by performing the following tasks: 1. Using either the FABHDLI, FABHDBB, or FABHULU procedure. 2. Coding the SYSIN, HSSROPT, and HSSRCABP control statements. 3. Running FABHTEST as an HSSR application program. 4. Reviewing and analyzing output reports.

JCL for the FABHTEST utility

Since FABHTEST is an HSSR application program, it requires standard FABHX034 JCL. Those DD statements are described in JCL requirements on page 21. The additional JCL requirements for FABHTEST are as shown in Table 41.
Table 41. FABHTEST DD statements DDNAME SYSIN SYSPRINT Use Input Output Format LRECL=80 LRECL=133 Need Required Required

The following list describes the EXEC and DD statements of the JCL to run FABHTEST: EXEC This statement invokes the procedure FABHDLI, FABHDBB, or FABHULU. The format is as follows:
// EXEC FABHDLI,MBR=FABHTEST,PSB= psbname // EXEC FABHDBB,MBR=FABHTEST,PSB=psbname // EXEC FABHULU,MBR=FABHTEST,DBD=dbdname

The PCB referred to by psbname must be declared as an HSSR PCB. (See HSSR PCB requirements on page 84.) SYSIN DD This required data set contains the control statements for FABHTEST. (See FABHTEST SYSIN data set on page 301.) SYSPRINT DD The required output data set contains output created by FABHTEST. The DD statement should be coded as follows:
//SYSPRINT DD SYSOUT=A

Input
FABHTEST uses three data sets as input. This section describes those data sets.

300

Users Guide

FABHTEST SYSIN data set

FABHTEST processes eight types of control statements. Any syntax error within an FABHTEST control statement leads to an error message and an abend with dump.

Function
FABHTEST depends upon the SYSIN data set to provide control statements that specify the sequence of HSSR calls.

Format
This data set contains 80-byte fixed-length records. The control statements can be coded in the input stream or accessed as a member of a partitioned data set.

PCB control statement

Use this optional statement to select the database PCB for the database call.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 PCB pcbnumber dbdname

Position 1 5

Description Code the PCB keyword to identify this as a PCB statement. Code the PCB number left-justified. The first PCB is number 1. If no PCB control statement is provided, FABHTEST uses the first database PCB.

16

Code the dbdname of PCB.

If no dbdname is specified on the PCB control statement, FABHTEST uses the PCB number field. If a dbdname is specified, the first database PCB referring to that DBD is used.

GN and GHN control statement

These statements instruct FABHTEST to issue a specified number of get-next (GN) or get-hold-next (GHN) calls. If no segment name is specified, GN or GHN calls without SSA are issued. If a segment name is specified, GN or GHN calls with an unqualified SSA are issued.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 GN GB GHN GB n seg_name seg_name seg_name

Position 1 5

Description Code the GN or the GHN keyword to identify this as a get-next control statement or a get-hold-next control statement. Code one of the following optional keywords: Keyword Description
Chapter 16. Using HSSR call test utility

301

GB n

FABHTEST issues GN or GHN calls until the end of the database is reached. The number of GN or GHN calls that FABHTEST issues. Code a number containing up to 10 digits, left-justified. Leading zeros are not necessary. FABHTEST issues 1 GN or GHN call.

blank 16

Code one of the following optional keywords: Keyword seg_name blank Description Code the name of a segment. FABHTEST issues GN or GHN calls with an unqualified SSA. FABHTEST issues GN or GHN calls without an SSA.

GNP and GHNP control statement

These statements make FABHTEST issue a specified number of get-next-within-parent (GNP) or get-hold-next-within-parent (GHNP) calls. If no segment name is specified, GNP or GHNP calls without SSA are issued. If a segment name is specified, GNP or GHNP calls with an unqualified SSA are issued.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 GNP GE GHNPGE n seg_name seg_name seg_name

Position 1

Description Code the GNP or the GHNP keyword to identify this as a get-next-in-parent control statement or a get-hold-next-in-parent control statement. Code one of the following optional keywords: Keyword GE Description FABHTEST issues GNP or GHNP calls until the end of the segment occurrence under the current parent. The number of GNP or GHNP calls that FABHTEST issues. Code a number containing up to 10 digits, left-justified. Leading zeros are not necessary. FABHTEST issues 1 GNP or GHNP call.

blank 16

Code one of the following optional keywords: Keyword seg_name blank Description Code the name of a segment. FABHTEST issues GN or GHN calls with an unqualified SSA. FABHTEST issues GN or GHN calls without an SSA.

302

Users Guide

Note: Before specifying the GNP or the GHNP statement, you must establish a valid parentage by specifying a GN, GHN, GNR, GHNR, GU, or GHU statement.

Chapter 16. Using HSSR call test utility

303

GNR and GHNR control statement

These statements instruct FABHTEST to issue a specified number of GN or GHN root calls with unqualified SSAs.
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 GNR GB GHNRGB n

Position 1

Description Code the GNR or the GHNR keyword to identify the get-next-root call control statement or the get-hold-next-root call control statement. Code one of the following optional keywords: Keyword GB n Description FABHTEST issues GNR or GHNR root calls until the end of the database is reached. The number of GNR or GHNR calls that FABHTEST issues. Code a number containing up to 10 digits, left-justified. Leading zeros are not necessary. FABHTEST issues 1 GNR or GHNR call.

blank

GU and GHU control statement

The Get Unique statement instructs FABHTEST to issue GU or GHU calls. The statement can specify: v Whether the GU or GHU should be issued with or without an SSA v The relational operator to be used in the SSA v The key value to be used in the SSA

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 GU nbr GHU nbr = keyvalue..............................................c = keyvalue..............................................c ...............

Position 1 5

Description Code the GU or the GHU keyword to identify the get-unique control statement or the get-hold-unique control statement. This entry lists the number of times the call is to be repeated. Code a number containing up to 10 digits. This value neither requires leading zeros nor has to be aligned. If only one GU or GHU is to be issued, omit this step. Code either a blank or a valid relational operator. SSA relational operators are restricted to =b, b=, EQ, =>, >=, GE (where b represents a single blank).

16

304

Users Guide

If this field is blank, FABHTEST issues GU or GHU calls without SSA. Otherwise, it issues GU or GHU calls with SSA qualified on the key field of the root segment and uses the relational operator provided. 18 Code the root key value. If the key value does not fit in this statement, place a continuation character (c in this example) in column 72. Then complete the key value in the continuation statement. If you continue your key value to the next line, leave columns 14 blank and begin the continuation at column 16. You can continue the statement again if you enter a continuation character in column 72. 72 Enter any nonblank character if a continuation is required. Leave this space blank if the key value is completed.

REPL control statement

The REPL statement instructs FABHTEST to issue a REPL call without SSA. (FABHTEST does not change the content of the segment during a REPL call.)
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 REPL

Position 1 Notes:

Description Code the REPL keyword to identify the replace control statement.

1. REPL call is supported for compatibility with DBT HSSR and PO HSSR (see Chapter 13, Compatibility with earlier products, on page 255). 2. REPL calls are not allowed for PHDAM or PHIDAM databases.

FABHTEST HSSROPT data set

For a complete description of the HSSROPT control statements, see HSSROPT data set on page 122. Any of the HSSROPT options that are appropriate to your task can be used. The CO, TRHC, and TRDB control statements should always be included, unless a performance test is being conducted. Some HSSROPT control statements that might be useful when used with FABHTEST are as follows: CO Compare option, that reissues HSSR calls as DL/I calls.

TRHC Hard-copy tracing option, that gives call data, HSSR control block data, buffer handler data, and CAB control block data. To obtain a printout of all database calls issued against an HSSR PCB, include the control statement. TRDB Specifies the DBDs against which calls are to be traced. Note: Always include the HSSR CO (compare) control statement and the hard-copy trace control statement in this data set, unless you conduct a performance test.

Chapter 16. Using HSSR call test utility

305

FABHTEST HSSRCABP data set

For a complete description of the HSSRCABP control statements, see HSSRCABP control statements on page 277. Any of the HSSRCABP options that are appropriate to your task can be used. Some HSSRCABP control statements that might be useful when used with FABHTEST are as follows: PARTPROC CABDD RANSIZE NBRSRAN NBRDBUF OVERFLOW REFT4 Specifies the processing intent. This statement is valid only for a PHDAM or PHIDAM database. Specifies data sets to which the succeeding CAB control statements applies. Specifies the number of blocks or CIs to be read together in chained mode. Specifies the number of ranges to be buffer-resident. Specifies the number of single blocks or CIs read in direct mode that are to reside in the buffer for look-aside buffering. Enables chained sequential I/O in the HDAM overflow area or in the overflow area of each partition of PHDAM database. Specifies a threshold value used to determine when chained sequential I/O or direct I/O is to be performed.

OutputFABHTEST SYSPRINT data set

In addition to the standard HSSRSTAT and HSSRTRAC data sets (see Chapter 9, Reports and output from HSSR Engine, on page 141), FABHTEST produces the FABHTEST SYSPRINT data set.

Function
This data set contains the FABHTEST Control Statements Report. This printed report contains a printed copy of the input control statements read by FABHTEST from the SYSIN data set (see Figure 58 on page 307).

Format
The data set contains 133-byte fixed-length records. When you code in JCL, your block size must be a multiple of 133.

306

Users Guide

IMS HIGH PERFORMANCE UNLOAD 5655-E06

"FABHTEST CONTROL STATEMENTS" DATE: 10/26/2007 TIME: 8.45.00

PAGE: 1 FABHB15 - V1.R2

.........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 GHU GHNR GHN GU GN 5 GU GNR 4 GHU REPL GHN REPL GN GB GE0000000500

EQ0000001500

Figure 58. FABHTEST Control Statements report

Examples
This section provides two examples showing how to use FABHTEST.

Example 1: Using FABHTEST for problem determination

To do problem determination with FABHTEST, you can use the JCL shown in Figure 59 on page 308. SYSIN control statements request that FABHTEST: v Issue a GU call. The first database PCB is used with the relational operator EQ and the key value provided. v Sequentially read the database referred to by the second PCB, until the end of the database is reached. HSSROPT control statements identify the options to be activated: v A CO control statement activates the Compare option. v A TRHC and a TRDB control statement request HSSR Engine to trace control blocks, call information, and buffer pool information for calls issued against all HSSR PCBs. IMS databases are identified by the TESTHDAM, TESTHIIX, and TESTHIDA DD statements. A SYSPRINT DD defines the FABHTEST output data set.

Chapter 16. Using HSSR call test utility

307

//TEST EXEC FABHDLI,MBR=FABHTEST,PSB=USERPSB //SYSIN DD * GU EQ1045699 PCB 2 GN GB /* //HSSROPT DD * HSSRPCB *ALL CO TRHC CB,CALL,BUF,BUFCB TRDB *ALL /* //TESTHDAM DD DSN=TESTDB.HDAM,DISP=SHR //TESTHIIX DD DSN=TESTDB.INDEX,DISP=SHR //TESTHIDA DD DSN=TESTDB.HIDAM,DISP=SHR //SYSPRINT DD SYSOUT=A Figure 59. FABHTEST JCL for problem determination

Example 2: Using FABHTEST to test performance

To test performance with FABHTEST, you can use the JCL shown in Figure 60. The SYSIN control statement requests FABHTEST to sequentially retrieve the entire database. 'CABSTAT YES' is specified in HSSROPT DD to produce the detailed CAB Statistics report. The TESTDB and TESTIDX DD statements identify an HIDAM database. Code HSSRCABP DD statement to tune CAB buffering parameters. Statistical reports can be analyzed to validate performance.
//TEST EXEC //HSSROPT DD CABSTAT YES /* //SYSIN DD GN GB /* //TESTDB DD //TESTIDX DD //SYSPRINT DD FABHULU,MBR=FABHTEST,DBD=USERDBD * * DSN=TESTDB.HIDAM.OSAM,DISP=SHR DSN=TESTDB.HIDAM.INDEX,DISP=SHR SYSOUT=A

Figure 60. FABHTEST JCL for performance testing

308

Users Guide

Chapter 17. Using the buffer handler simulation utility

FABHBSIM is the buffer handler simulation utility that is used as an aid in tuning the BB and CAB buffer handlers. It enables you to observe the effect of the changes to parameters of the buffer handlers, without actually performing database I/O operations and segment processing. FABHBSIM might help realize significant productivity gains by determining the optimum numbers and sizes of buffers. Note: FABHBSIM does not support the tuning of buffer handlers for a PHDAM or PHIDAM database. Topics: v v v v v v v v v Program functions Typical uses Program structure on page 310 Restrictions on page 310 Operating instructions on page 310 JCL of the FABHBSIM utility on page 310 Input on page 311 Output on page 311 Examples on page 311

Program functions
FABHBSIM provides the following functions: v Simulating a previous run of an High Performance Unload job v Printing standard reports produced by HSSR Engine FABHBSIM simulates database I/O and buffer handling. It produces statistical reports that show the results of the simulation. FABHBSIM reads the HSSRBUTR buffer handler trace data set created during an actual previous run of an High Performance Unload job. This trace contains a record of all HSSR calls issued to an IMS database during the execution of your application program. FABHBSIM allows you to use an HSSR buffer handler other than the one used in the original run. FABHBSIM reissues all of the database calls. CAB or BB processes the HSSR calls, but no actual database I/O is performed. FABHBSIM produces the statistical reports that are normally generated by HSSR Engine. From these reports, you can analyze the effect of parameter changes on buffer handler performance.

Typical uses
FABHBSIM can be used to: v Analyze buffer handler performance v Tune buffer handler parameters v Assist in improving performance of your IMS application programs v Aid in improving productivity of your IMS database

Copyright IBM Corp. 2000, 2007

309

Program structure
FABHBSIM runs as an HSSR application program. It accepts the HSSRBUTR data set as the input and produces output reports. Any of the three cataloged procedures can be used to run FABHBSIM.

Restrictions
FABHBSIM has the following restrictions: v The PSB and DBDs used must be identical with those used in the original run that was traced. Do not modify the PSB or the DBD between the traced run and the execution of FABHBSIM. The database itself can be modified with ISRT, DLET, or REPL, and reorganization activities. v The timing estimates of CAB I/O provided on the CAB Statistics report are not accurate when FABHBSIM is run. v FABHBSIM does not support the tuning of buffer handlers for a PHDAM or a PHIDAM database.

Operating instructions
You can run the FABHBSIM utility by performing the following tasks: 1. Using the FABHDLI, FABHDBB, or FABHULU procedure 2. Coding the HSSROPT and HSSRCABP control statements 3. Running FABHBSIM as an HSSR application program 4. Reviewing and analyzing output reports to tune buffer handler parameters 5. Repeating steps 2 through 4 if further tuning is necessary

JCL of the FABHBSIM utility

Since FABHTEST is an HSSR application program, it requires standard FABHX034 JCL, described in JCL requirements on page 21. The additional JCL requirements for FABHBSIM are shown in Table 42.
Table 42. FABHBSIM DD statements DDNAME SYSUT1 Use Input Format HSSRBUTR data set Need Required

EXEC This statement invokes the procedure FABHDLI, FABHDBB, or FABHULU. The required format is one of the following:
// EXEC FABHDLI,MBR=FABHBSIM,PSB=psbname // EXEC FABHDBB,MBR=FABHBSIM,PSB=psbname // EXEC FABHULU,MBR=FABHBSIM,DBD=dbdname

SYSUT1 DD This required input data set defines the data set for buffer handler trace. You must create the buffer handler trace data set in an earlier run of your High Performance Unload job. It is the data set that was defined by the HSSRBUTR DD statement in the earlier run. Here is an example of the format for this data set:
//SYSUT1 DD DSN=HSSRBUTR,DISP=OLD,UNIT=tape,VOL=SER=xxxxxx

310

Users Guide

Input
FABHBSIM uses data sets of control statements and buffer handler trace information as input. This section describes those data sets.

FABHBSIM HSSROPT data set

For a complete description of the HSSROPT control statements, see HSSROPT data set on page 122. The pertinent HSSROPT option to be used with FABHBSIM is the BUF control statement. It modifies the number of BB buffers. Any of the other HSSROPT options that are appropriate to your task can be used. But the DBDL1 control statement with the *ALL keyword should not be used.

FABHBSIM HSSRCABP data set

For a complete description of the HSSRCABP control statements, see HSSRCABP control statements on page 277. Note: The PARTPROC control statement is not supported, because FABHBSIM does not support PHDAM and PHIDAM databases.

Output
FABHBSIM produces the standard HSSRSTAT data set (see Chapter 9, Reports and output from HSSR Engine, on page 141). This is the primary output from FABHBSIM.

Examples
To use FABHBSIM in simulating buffer handlers and tuning buffers, you may use the JCL shown in Figure 61 on page 312. The CABDD control statement specifies that the succeeding CAB control statements apply to all HD databases. The NBRSRAN control statement specifies that 30 ranges should reside in the buffer for look-aside buffering purposes. (Other HSSRCABP control statements may be inserted as appropriate.) 'CABSTAT YES' in HSSROPT DD requests that HSSR Engine produce detailed CAB Statistics report. The SYSUT1 DD statement defines an input data set, which is the HSSRBUTR data set produced by an earlier run of a High Performance Unload job. The HDAM DD statement defines an IMS database. Statistical reports may be analyzed to tune the CAB buffering parameters.

Chapter 17. Using the buffer handler simulation utility

311

//BSIM EXEC //HSSROPT DD CABSTAT YES /* //HSSRCABP DD CABDD *HD NBRSRAN 30 /* //SYSUT1 DD //HDAM DD

FABHULU,MBR=FABHBSIM,DBD=USERDBD * *

DSN=TESTDS.HSSRBUTR.DATASET,DISP=OLD,UNIT=tape,VOL=SER=yyyyyy DSN=TESTDS.HDAM,DISP=SHR

Figure 61. FABHBSIM JCL for simulating a buffer handler

312

Users Guide

Chapter 18. System programming interfaces

This chapter presents product-sensitive programming interface information. See Programming interface information on page 484 to understand the restrictions associated with this type of material. Product-Sensitive Programming Interface The following system programming interfaces are provided for customizing High Performance Unload or for compatibility with earlier products: v Run-time environment exit (FABHRTEX) v Buffer-handler initialization exit (FABHCEX) v Return code edit exit (FABHRCEX) v Record-formatting exit for FABHURG1 End of Product-Sensitive Programming Interface Topics: v v v v v Run-Time Environment exit (FABHRTEX) Buffer Handler Initialization exit (FABHCEX) on page 314 Return Code Edit exit (FABHRCEX) on page 315 Writing user record-formatting routine on page 317 Product-sensitive macros on page 333

Run-Time Environment exit (FABHRTEX)

Product-Sensitive Programming Interface With High Performance Unload you can develop a run-time environment exit routine, named FABHRTEX, which enables you to do your own initialization and termination processing for your application programs or your exit routines for unload utilities. The run-time environment exit routine is called during the initialization of the High Performance Unload program controller before the application program is called; the routine is called once more after, control is returned from the application program to the program controller. See Figure 1 on page 17. You can use an exit routine that has a different name, by specifying the RTEXIT control card in the HSSROPT data set. Use this control statement if you need to set up a special run-time environment for a special application or for an exit routine for FABHURG1 or FABHFSU. The following information message is issued only if you provide your own run-time environment exit routine:
FABH0826I: RUN TIME ENVIRONMENT EXIT ROUTINE IS BEING INVOKED, MODULE=xxxxxxxx

If the specified exit is not found, abend U4013 occurs and the following message is issued:
FABH0850E LOAD FAILED FOR RTEXIT (xxxxxxxx), CC=yyyy, RC=zz

Copyright IBM Corp. 2000, 2007

313

End of Product-Sensitive Programming Interface The following Product-Sensitive Programming Interface explains the interface to run time environment exit routine. Product-Sensitive Programming Interface Table 43 shows what the registers contain on entry to the routine.
Table 43. Register contents upon entry to a user exit Register 1 14 15 Contents Address of call parameter list Return address to the caller Entry point address of the run-time exit routine

The address of the parameter list is set in register 1; Table 44 shows the parameters passed to the routine.
Table 44. Parameters Word 1 2 Content Pointer to a 4-byte character field containing 'INIT' (for initialization call) or 'TERM' (for termination call) Pointer to an 8-byte character field containing the application program name

When control is returned to the caller, the contents of all registers except register 15 must be restored. Register 15 must contain a return code. The meanings of the return codes are given in Table 45.
Table 45. FABHRTEX return codes Value 0 Not 0 Description Initialization or termination was successful. An error occurred in the run-time environment exit. Error message FABH0827E is issued, and abend U4013 occurs.

Note: A dummy run-time environment exit routine (FABHRTEX) that returns the return code of 0 at both initialization and termination calls is provided. You can code your own FABHRTEX to meet your particular requirements. End of Product-Sensitive Programming Interface

Buffer Handler Initialization exit (FABHCEX)

Product-Sensitive Programming Interface Some users need to reduce the amount of batch processing during peak online periods.

314

Users Guide

You can develop an exit routine named FABHCEX, which can disperse the amount of system resources needed by High Performance Unload jobs over a longer elapsed time. FABHCEX is invoked when the HSSR buffer handler is initialized. It can dynamically allow or disallow the use of CAB. If it detects that the High Performance Unload job step is running during a peak online period, it disallows the use of CAB and enforces the use of BB (regardless of specifications in HSSRCABP data set). The return codes that FABHCEX can set in Register 15 are listed in Table 46.
Table 46. FABHCEX return codes Code 0 not 0 Description Choose the buffer handler according to specifications of the CAB control statements in HSSRCABP. Use BB.

For example, FABHCEX can be used to check the time of day and whether the IMS online system is running. After making these determinations, FABHCEX issues a return code and selects a buffer handler. The conventions for linkage between HSSR Engine and FABHCEX are the standard MVS linkage conventions. No parameters are passed to FABHCEX. The FABHCEX routine must be a load module named FABHCEX, and must be in a program library accessible to HSSR Engine. The program control is transferred to the routine in the addressing mode of the routine. Note: High Performance Unload provides a dummy routine (FABHCEX), which always returns a return code of 0. You can code your own FABHCEX exit routine to meet your particular requirements. End of Product-Sensitive Programming Interface

Return Code Edit exit (FABHRCEX)

You can write a Return Code Edit exit routine (FABHRCEX) to change the return codes of HSSR application programs, including the FABHURG1 and FABHFSU unload utilities. FABHRCEX is called before control is returned from the High Performance Unload program controller (FABH000) to the IMS region controller (DFSRRC00). See Figure 1 on page 17. If you want to use the exit, you must write an exit routine in Assembler, and then assemble and link-edit it as load module FABHRCEX. The library that contains FABHRCEX must be specified in the JOBLIB DD concatenation or the STEPLIB DD concatenation of your High Performance Unload job. The addressing mode of a Retun Code Edit exit routine can be either 24 or 31. The residency mode can be either 24 or ANY. The reusability attribute can be either REUS or RENT.

Chapter 18. System programming interfaces

315

The following information message is issued only if the High Performance Unload program controller can find FABHRCEX in the libraries specified in the JOBLIB or the STEPLIB DD statement, and load it:
FABH0881I applname ENDED WITH RC=xx, WHICH MIGHT BE CHANGED BY FABHRCEX EXIT

If the High Performance Unload program controller fails to load FABHRCEX, abend U4013 occurs and the following error message is issued:
FABH0854E LOAD FAILED FOR FABHRCEX EXIT, CC=xxxx, RC=yy

316

Users Guide

Interface to Return Code Edit exit routine

Table 47 shows what the registers contain on entry to the routine.
Table 47. Register contents upon entry to FABHRCEX Register 1 14 15 Contents Address of call parameter list Return address to the caller Entry point address of the Return Code Edit exit routine

The address of the parameter list is set in register 1; Table 48 shows the parameters passed to the routine.
Table 48. FABHRCEX parameters Word 1 2 Content Pointer to an 8-byte character field containing the application program name Pointer to a 4-byte field containing the return code to be edited

When control is returned to the caller, the contents of all registers except register 15 must be restored.

FABHRCEG sample JCL

FABHRCEG is a sample JCL stream for use in creating a Return Code Edit exit routine. It is provided as a member of the HPS.SHPSSAMP library. FABHRCEG assembles and link-edits the FABHRCEX exit routine in the HPS.SHPSLMD0 load module library.

Writing user record-formatting routine

Product-Sensitive Programming Interface FABHURG1 unload utility ordinarily runs without any user routines. It unloads a database into one of five different formats by invoking one of five standard record-formatting routines. Some installations might wish to perform additional processing or editing during the database unload, or might wish to create a database unload format of their own. To do this, they can provide their own user record-formatting routine or optional user exit routine. These exit routines can be coded in Assembler or COBOL language. End of Product-Sensitive Programming Interface

Logic of FABHURG1
Product-Sensitive Programming Interface Database unload processing is performed by: v Common logic
Chapter 18. System programming interfaces

317

v One user-selectable record-formatting routine, which can be any one of five standard record-formatting routines or a user record-formatting routine v An optional user exit routine End of Product-Sensitive Programming Interface

Common logic
Product-Sensitive Programming Interface This performs the following processes: 1. Provides initialization and termination processing. 2. Controls an optional SYSUT2 output data set containing the database unload output (OPEN, CLOSE, and WRITEs are issued by the common logic). 3. Issues HSSR calls against the PCB you select. 4. Edits a call parameter list for record-formatting routines and optional user exit routines. 5. Calls the selected record-formatting routine. If the record-formatting routine sets a return code other than zero, the next HSSR call is issued. 6. Calls the optional user exit routine. If the routine sets a return code other than zero, the next HSSR call is issued. 7. If a non-DUMMY SYSUT2 DD statement has been provided, issues a PUT to write the record edited by the record-formatting routine and the optional user exit routine. 8. If a non-DUMMY SYSUT3 DD statement has been provided, issues a WRITE macro to write the block edited by the record-formatting routine and optional user exit routine. 9. Issues the next HSSR call. End of Product-Sensitive Programming Interface

Record-formatting routine
Product-Sensitive Programming Interface The record-formatting routine is invoked each time a database segment has been retrieved by the common logic. It is the responsibility of the record-formatting routine to edit output records from the retrieved database segments. FABHURG1 provides five standard record-formatting routines. System programmers can provide their own user record-formatting routines if they want to create a database unload format of their own. After having reached the database end, the common logic invokes the record-formatting routine one last time so that it can do its own termination processing and cleanup processing. You must check whether the call is the last call by checking the status code in the PCB feedback area of the HSSR PCB (see Parameter 4: HSSR PCB on page 322). End of Product-Sensitive Programming Interface

318

Users Guide

Optional user exit routine

Product-Sensitive Programming Interface The optional user exit routine is invoked (after record-formatting processing) each time a database segment that the record-formatting routine does not skip is retrieved. The optional user exit routine can modify or edit the record composed by the record-formatting routine. One possible use of user exit routines by system programmers is to build the logical parents concatenated key. Both record-formatting routines and user exit routines can optionally: v Create their own output data sets (in addition to or instead of SYSUT2). v Issue DL/I calls or HSSR calls against PCBs other than the PCB that is used by the common logic of FABHURG1. v Indicate that the current database segment or database record should not be processed further and that the skipped database segments should not be written to SYSUT2. They can also indicate that the common logic should resume its retrieval at a root with a specifiable key. After having reached the database end, the common logic invokes the optional user exit routine one last time so that it can do its own termination processing and cleanup processing. For example, all opened files can be closed when the last call is issued. You must check whether the call is the last call by checking the status code in the PCB feedback area of the HSSR PCB (see Parameter 4: HSSR PCB on page 322). End of Product-Sensitive Programming Interface

Interface to user record-formatting and optional user exit routines

Product-Sensitive Programming Interface These routines are called, in accordance with standard Assembler and COBOL conventions. On entry, the routines should save the registers; on return, they should restore all registers except Register 15. On entering to the routines, the following registers contain the information given in Table 49.
Table 49. Register contents at entry to routines Register 1 13 14 15 Contents Address of call parameter list Address of callers save area Return address to database unload utility Entry point address into user routine

Upon returning to the common logic, Register 15 must contain a binary return code between 0 and 4. The codes are explained in Table 50 on page 320.

Chapter 18. System programming interfaces

319

Table 50. Exit routine return codes Code 0 1 2 Description Processes this database segment. Stops processing of this database segment and does not write it to SYSUT2. Retrieves the next data-sensitive segment. Stops processing of this database segment and does not write it to SYSUT2. Retrieves the next database root segment. (All remaining segments of the current database record are skipped.) Stops processing of this database segment, and does not write it to SYSUT2. Continues database retrieval with the root whose key is greater than or equal to the key value specified by the user exit routine in call parameter 9 (the key of the next root). If a Data Conversion exit routine is used for the database, the key of the next root must be specified in the application form. 4 Stops the processing of this database segment, and does not write it to SYSUT2. Does not retrieve any further database segments, and stops processing.

If a routine sets a return code 1, the dependents of the current database segment are not skipped by the common logic. Skipping of these dependent segments is the responsibility of the routine. End of Product-Sensitive Programming Interface

Call parameters
This section describes the call parameters for user record-formatting routines or optional user exit routines.

Parameter 1: OUTPUT-AREA
The following sections describe the OUTPUT-AREA for the user record-formatting routine and optional user exit routines. Description of OUTPUT-AREA for user record-formatting routine: Product-Sensitive Programming Interface v OUTPUT-AREA contains (at the offset specified by the OFFS utility control statement) the segment data as returned by the HSSR call. v If a SYSUT2 DD statement has been provided and is not a dummy, OUTPUT-AREA is in the SYSUT2 output buffers. SYSUT2 is a variable-blocked sequential data set. Unless the user record-formatting routine sets a return code that is not zero, the routine should build a variable-length SYSUT2 record in the OUTPUT-AREA, storing the binary record length in the first 2 bytes and binary zeros in the 2 bytes that follow. The SYSUT2 record is written by the common logic. v If no SYSUT2 DD statement (real or dummy) has been provided, all output operations, including open and close, are done by the routine. The routine can use OUTPUT-AREA to build its output records, or it can use its own area to build its output record. In the former case, the overhead of data movement within virtual storage is reduced. In the latter case, it is the responsibility of the routine to develop a method to pass the address of the output record to the optional user exit routine.

320

Users Guide

End of Product-Sensitive Programming Interface Description of OUTPUT-AREA for optional user exit routine: Product-Sensitive Programming Interface OUTPUT-AREA contains the output record as it is built by the record-formatting routine. Some user-developed record-formatting routines can build the output record into areas other than the OUTPUT-AREA. Warning: The header field of the *HD unload format record for HALDB is longer than one for non-HALDB. The offset of the segment data is different between non-HALDB and HALDB. To refer to the segment data, IBM recommends that you use Parameter 2: Database segment (Segment data) than to use Parameter 1: OUTPUT-AREA on page 320. The header field contains the segment name, but it is not recommended that you use it. Instead, refer to the segment name contained in the HSSR PCB, which is pointed to by Parameter 4: HSSR PCB on page 322. Figure 62 provides an example of a part of an exit routine coded in COBOL.
ENVIRONMENT DIVISION. : DATA DIVISION. : WORKING-STORAGE SECTION. : LINKAGE SECTION. 01 OUTPUT-AREA 01 SEGMENT-DATA 01 SEGMENT-PREFIX 01 HSSR-PCB. 02 HPCB-DBDNAME 02 HPCB-SEGLEV 02 HPCB-STATUS 02 HPCB-PROCOPT 02 FILLER 02 HPCB-SEGNAME 02 HPCB-LENKFB 02 HPCB-NUSENS 02 HPCB-KEYFB

PIC X(XXX). PIC X(XX). PIC X(XX). PIC PIC PIC PIC PIC PIC PIC PIC PIC X(08). X(02). X(02). X(04). X(04). X(08). X(04). X(04). X(XX).

PROCEDURE DIVISION USING OUTPUT-AREA,SEGMENT-DATA,SEGMENT-PREFIX,HSSR-PCB : Figure 62. A user exit routine for FABHURG1 in COBOL

End of Product-Sensitive Programming Interface

Parameter 2: Database segment (Segment data)

Product-Sensitive Programming Interface This is the pointer to the database segment as returned by the HSSR call. If a standard record-formatting routine is used, the segment data is after the header

Chapter 18. System programming interfaces

321

field that is pointed to by parameter 1. If a user-developed record-formatting routine that can be specified in the FRMT control statement is used, the segment data is within the OUTPUT-AREA at the offset specified by the OFFS control statement. The user-developed record-formatting routines might modify the database segment. In such a case, the optional user exit routine, if it is used, sees this modified data instead of the database segment as returned by the HSSR call. You need to be careful when you modify the database segment, because there are other segments in the OUTPUT-AREA. If the USEGMAX control statement is specified, the work area for segment editing is reserved after the segment data. The total length of the segment data area plus the work area is the length specified by the USEGMAX statement. If the ULEN or OFFS control statement is specified, the work area that is pointed to by Parameter 1 and whose length is equal to the length specified by the OFFS statement is reserved to be used as your record header. The work area whose length is equal to ULEN minus OFFS is reserved after the segment data. You can use these work areas in editing or expanding the segment data, but if you change the length of the segment data, you must also update the fields in the OUTPUT-AREA that are affected by that change of length. For example, the first two bytes of the OUTPUT-AREA pointed to by Parameter 1 must be updated with the new record length, if the record is written to the SYSUT2 data set. If your segment record header has a segment length field, it must be updated. If the segment itself has fields for segment length or field lengths, they must be updated, too. The exit routine is responsible for updating these fields. If FABHURG1 is run with the DECN option, the segment data for which a Segment Edit/Compression routine is specified is passed to your exit routine in the compressed format. If you want the segment data to be passed to your exit routine in the decompressed format, run FABHURG1 with the DECY option. End of Product-Sensitive Programming Interface

Parameter 3: Segment prefix

Product-Sensitive Programming Interface This parameter contains the segment prefix as it is stored in the database. The user routine should not modify this parameter. Note: During a migration unload, this parameter contains the binary zero for a virtual logical child. End of Product-Sensitive Programming Interface

Parameter 4: HSSR PCB

Product-Sensitive Programming Interface This is the HSSR PCB used by the main logic of FABHURG1 to sequentially retrieve the database. The HSSR PCB contains the segment name, the segment level, the key feedback area, the length of the key feedback area, and the status code. See HSSR PCB feedback information on page 85.

322

Users Guide

The user routine should always test the status code. If the status code is GB, the end of the database has been reached and the user routines should perform their termination processing and cleanup processing, including closing all files opened by the routine. The user routines should not modify the HSSR PCB. End of Product-Sensitive Programming Interface

Parameter 5: HSDB
Product-Sensitive Programming Interface This is the HSSR segment descriptor block that describes the currently retrieved segment type. The user routine should never modify the HSDB. It can, however, use the 4-byte field HSDBUSER. End of Product-Sensitive Programming Interface

Parameter 6: Reserved for system use

The user routine should never refer to or modify this parameter.

Parameter 7: RBA of segment prefix

Product-Sensitive Programming Interface This 4-byte field contains the relative byte address of the segment prefix. The content of this field has a meaning only for HD databases. The user routine should never modify this field. If your IMS environment supports an OSAM database larger than 4 gigabytes, be careful with the RBA. You must check the flag byte SPRBAFLG when you treat an RBA. The flag SPRBAX4G in this flag byte is on if and only if all of the following conditions are satisfied: 1. Your IMS environment supports relative byte addressability for up to 8 gigabytes of data in an OSAM, HDAM, or HIDAM database data set. 2. Your database is an OSAM database. 3. Your database has an even block size. 4. The RBA of the segment prefix is larger than or equal to 4 gigabytes. Thus, if your IMS environment satisfies the first condition, you must check whether the flag SPRBAX4G is on or off. If the flag is on, the value in SPRBA is not the real RBA. In this case, you must move bit 1 of SPRBA to bit position 33 to get the real 33-bit RBA. See the sample code provided in Figure 63 on page 324.

Chapter 18. System programming interfaces

323

LR USING USING L L SR IF LA XR ENDIF DROP STM * WKREAL * PRMPRML PRMAREC PRMASGD PRMASGP PRMAPCB PRMAHSD PRMATCB PRMARBA PRMALEN PRMANXK * SPRBAD SPRBA SPRBAFLG SPRBAX4G SPHALDB SPMACTV DC DSECT DC DC DC DC DC DC DC DC DC DC DSECT DS DS EQU EQU EQU

R5,R1 GET PARAMETER LIST ADDRESS PRMPRML,R5 SPRBAD,R7 R7,PRMARBA R9,SPRBA GET RBA OF SEGMENT PREFIX R8,R8 (TM,SPRBAFLG,SPRBAX4G,O) R8,1 R9,R8 R7 R8,R9,WKREAL GET REAL 33-BIT RBA : 2F0 A(0) A(0) A(0) A(0) A(0) A(0) A(0) A(0) A(0) 4A(0) F XL1 X80 X10 X08 REAL RBA OF SEGMENT PREFIX A(START OF OUTPUT RECORD) A(SEGMENT-DATA) A(SEGMENT-PREFIX) A(HPCB) A(HSDB) A(HTCB) A(RBA OF SEGMENT PREFIX) A(SEGMENT DATA LENGTH) A(KEY OF NEXT ROOT)

RBA OF SEGMENT PREFIX FLAG BYTE RBA >= 4GB HALDB ODD RBA(SGRBA) ON M-V SIDE

Figure 63. RBA of segment prefix

If your IMS environment supports the HALDB Online Reorganization (OLR), you must check whether the SPHALDB flag and the SPMACTV flag, which are shown in the Figure 63, are on. If both of them are on, the value in SPRBA is not the real RBA and the odd RBA indicates that the segment is on the M-V,Y set of the data sets. In this case, you must move bit 1 of SPRBA. Note: During a migration unload, this parameter contains the binary zero for a virtual logical child. End of Product-Sensitive Programming Interface

Parameter 8: Length of segment data

Product-Sensitive Programming Interface This 2-byte binary field contains the length of the segment data returned by the HSSR call. The user routine should never modify this field. End of Product-Sensitive Programming Interface

324

Users Guide

Parameter 9: Key of next root

Product-Sensitive Programming Interface On entering the user routine, the content of this field is unpredictable. If the user routine sets a return code of 3, the routine must store the key value in this field. The key value is used to retrieve the next root segment. If the secondary index is used to retrieve the root segments, specify the value of the search field of the index segment as the key value. With this key value, the common logic then issues a GU call with the "greater than or equal to" operator. Note: If you are using a Data Conversion exit (DFSDBUX1) for the database in your FABHURG1 job, you must specify the next root key in the application form. On the other hand, if you are not using DFSDBUX1 in your FABHURG1 job, you must specify the next root key in the stored form. End of Product-Sensitive Programming Interface

Parameters 1013
Product-Sensitive Programming Interface These parameters are reserved. End of Product-Sensitive Programming Interface

Parameters 14n
Product-Sensitive Programming Interface PCBs in the same sequence as specified during PSBGEN. With the exception of the PCB used by the common logic, these PCBs can be used by user routines to issue HSSR and DL/I calls. End of Product-Sensitive Programming Interface

Special SYSIN control statements for user exits

Product-Sensitive Programming Interface The name of a user record-formatting routine is specified by the FRMT control statement. The name of an optional user exit routine is specified by the EXIT control statement. For these user exit routines, the following special-purpose SYSIN control statements are provided: v ULEN v OFFS v USEGMAX The OFFS and ULEN control statements have meaning only if a user record-formatting routine (specified on the FRMT control statement) is active. These statements specify that the additional space is to be reserved within the area used by FABHURG1 to issue HSSR calls. This additional space can be used by the record-formatting routine to build additional header data in its output records in this area.
Chapter 18. System programming interfaces

325

The USEGMAX control statement has meaning only if one of the standard record formats, *HD, *CS, *F1, or *F2, is used, and if an optional user exit routine (specified on the EXIT control statement) is active. This statement specifies that the additional space is to be reserved within the I/O area used by FABHURG1 to issue HSSR calls. This additional space can then be used by the user exit routine to edit the segment data. See Parameter 2: Database segment (Segment data) on page 321. End of Product-Sensitive Programming Interface

FRMT control statement

Product-Sensitive Programming Interface See FRMT control statement on page 41. End of Product-Sensitive Programming Interface

EXIT control statement

Product-Sensitive Programming Interface

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 EXIT exitname c

Position 1 6 15

Description Code the EXIT keyword to identify the exit routine. The left-justified load module name of the user exit routine. If no EXIT control statement is provided, no user exit routine is invoked. If a Data Conversion exit routine is used, the user exit routine receives the segment data that has been converted from the stored form to the application form. The 1-character entry c indicates whether the inverse conversion (the conversion from the application form to the stored form) is to be done before the segment data edited in the exit routine is written into the output data set. Use one of the following codes: Keyword Y Description Do the conversion. The option 'Y' is valid only for '*HD' unload format. This option is valid only when the option 'DATXEXIT YES' is specified in the HSSROPT data set. N|blank Do not do the conversion. This is the default.

Note: If the EXIT control statement is specified and one or more partitions of PHDAM or PHIDAM are in the HALDB OLR cursor-active status, FABHURG1 ends abnormally.

326

Users Guide

End of Product-Sensitive Programming Interface

Chapter 18. System programming interfaces

327

OFFS control statement

Product-Sensitive Programming Interface

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 OFFS offs

Position 1 6

Description Code the OFFS keyword to identify this as an OFFS statement. Offset of the database segment within an area used to retrieve segments with HSSR calls. The bytes in front of the database segment within this area are reserved for use by the user record-formatting routine. The length specified need not contain leading zeros, nor need it be aligned.

Notes: 1. If a standard record-formatting routine is used, OFFS statements are ignored. 2. The value specified on the OFFS statement should not be greater than the value specified in the ULEN statement. 3. If a SYSUT2 DD statement has been provided, OFFS should be at least 4. These 4 bytes are reserved for the OS record descriptor word. 4. If no OFFS control statement is provided, the default is zero. 5. If you specify a control statement such as MIGRATE or FALLBACK, this statement is ignored. End of Product-Sensitive Programming Interface

ULEN control statement

Product-Sensitive Programming Interface

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 ULEN ulen

Position 1 6

Description Code the ULEN keyword to identify this as a ULEN statement. Specify the maximum number of bytes reserved for the user data, within the HSSR call I/O area, that can be used by the user record-formatting routine. The length of the HSSR call I/O area is the sum of the length of the longest database segment and the

328

Users Guide

length specified on this control statement. The length specified need not contain leading zeros, nor need it be aligned. Notes: 1. If a standard record-formatting routine (for the *HD, *CS, *F1, *F2, or *F3 format) is used, this statement is ignored. 2. If the SYSUT2 DD statement is present, its block size must be large enough to contain the segment data and the user data:
BLKSIZE 4 + max_segment_length + ulen

3. If ULEN is larger than necessary, the blocking of SYSUT2 is not optimal. 4. If the SYSUT2 DD statement is provided, ULEN must be at least 4. These 4 bytes are reserved for the OS record descriptor word, which contains the binary record length followed by binary zeros. 5. If no ULEN control statement is provided, the default is zero. 6. If you specify a control statement such as MIGRATE or FALLBACK, this statement is ignored. End of Product-Sensitive Programming Interface

USEGMAX control statement

Product-Sensitive Programming Interface

0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 USEGMAX usegmax

Position 1 9

Description Code the USEGMAX keyword to identify the statement. Specify the number of bytes to be reserved for the segment data field within the HSSR call I/O area. This reserved space is used by a record-formatting routine for the unload format *HD, *CS, *F1, or *F2. This length must be larger than or equal to the length of the longest database segment. The length of the HSSR call I/O area, which is called the OUTPUT-AREA, is the sum of the length specified by this statement and the length of the record header determined by each format. The length specified need not contain leading zeros, nor need it be aligned.

Notes: 1. If you specified a value less than the length of the longest database segment, the usegmax value is adjusted to the length of the longest segment. The message FABH0276I is issued. 2. If a user record-formatting routine or the standard record format *F3 is specified, the USEGMAX control statement is ignored. The message FABH0276I is issued. 3. If no optional user exit routine is specified, this control statement is ignored. The message FABH0276I is issued.
Chapter 18. System programming interfaces

329

4. If the SYSUT2 DD statement is present, its block size must be large enough to contain the record header and the segment data field expanded by the USEGMAX statement:
BLKSIZE 4 + record_header_length + usegmax

5. If no USEGMAX is specified or if the USEGMAX statement is ignored because of the reason previously stated, the default length (that is, the length of the longest segment in the database) is used as the length of the user data field. 6. If you specify a control statement such as MIGRATE or FALLBACK, you cannot specify this statement. End of Product-Sensitive Programming Interface

Get-by-RBA calls
Product-Sensitive Programming Interface The Get-by-RBA calls can be used by system programmers to cross logical relationships or secondary index relationships implemented with direct pointers. These calls can also be used to build the logical parents concatenated key defined as virtual in the SEGM statement of the DBD. Notes: 1. Get-by-RBA call is supported for compatibility with DBT HSSR and PO HSSR. The use of this call in High Performance Unload is not recommended. 2. Get-by-RBA call for HALDB is not supported. End of Product-Sensitive Programming Interface

Structure
Product-Sensitive Programming Interface Get-by-RBA calls allow retrieval of segments of HIDAM and HDAM databases by their relative byte address. The format of this call is:
CALL ASMHSSR,(GU,PCB,IOAREA,SSA),VL Assembler language CALL CBLHSSR USING GU,PCB,IOAREA,SSA. COBOL CALL PLIHSSR (FOUR,GU,PCB,IOAREA,SSA); PL/I

The SSA contains the 8-byte segment name, followed by *T, the left parenthesis, the 4-byte RBA, and the right parenthesis, as follows:
aaaaaaaa*T(nnnn) | | | | | | | | Four-byte relative byte address | | of segment prefix | | | Command code | Name of segment

330

Users Guide

If the database does not contain a segment prefix of the specified segment type at the specified RBA, HSSR Engine abends. After completion of the call, HSSR call handler edits the requested segment in the IOAREA exactly as it does for the other types of calls (GN, GU, GHN, GHU, REPL). The PCB is also edited normally. However, the part of the key feedback area that ordinarily contains the concatenated key of the physical parent now contains binary zeros. GN calls should be issued with care after a Get-by-RBA call. Starting from the segment retrieval by the RBA call, HSSR Engine proceeds sequentially as far as possible. When it cannot proceed further, it returns a GB status code: v If the segment retrieved by the RBA call is an HIDAM root segment, HSSR Engine proceeds sequentially to the end of the database. v If the segment retrieved by the RBA call is an HDAM root segment, HSSR Engine proceeds sequentially to the last database record chained to the same RAP as the root retrieved by the RBA call. v If the segment retrieved by the RBA call is not a root, the sequential processing stops at a position that depends on pointer options. It is either the last dependent of the last twin (twin pointers) or the last dependent of the last segment on the same hierarchical pointer chain (hierarchical pointers). End of Product-Sensitive Programming Interface

Finding the RBA required by the Get-by-RBA call

Product-Sensitive Programming Interface This section will be more readily useful if you have on hand an assembly listing of the IMS control blocks SDB and PSDB. To get such a listing, use the IMS macro:
IDLI SDBBASE=0,DMBBASE=0

After the successful completion of an HSSR call, three control blocks (HJCB, HSDB, and the HDMB) of HSSR Engine contain information described in the following sections: End of Product-Sensitive Programming Interface HJCB (Job Control Block of HSSR Engine): Product-Sensitive Programming Interface The HJCB is an internal expansion of the HSSR PCB. It has functions similar to the DL/I JCB. It also contains the virtual storage address of the prefix of the segment just retrieved. This address is stored at the label HJCBPFXA. Note: For variable-length split segments, the segment data is not stored after the prefix. End of Product-Sensitive Programming Interface

Chapter 18. System programming interfaces

331

HSDB (Segment Descriptor Block of HSSR Engine): Product-Sensitive Programming Interface The HSDB describes the segment type just retrieved and points to the following IMS control blocks: v Segment descriptor block (SDB) v Physical segment descriptor block (PSDB) Using the HSDB, SDB, and PSDB, you can get an exact and complete description of the segment type just retrieved. This includes an exact description of the segment prefix, which allows the displacement within the segment prefix of any pointers of interest to be computed. End of Product-Sensitive Programming Interface HDMB (Data Management Block of HSSR Engine): Product-Sensitive Programming Interface The HDMB describes the data set group of the segment just retrieved. The HJCB, HSDB, and HDMB can be found as follows: v The field HPCBJCB of the HSSR PCB points to the HJCB. v The field HJCBSDBC of the HJCB points to the HSDB of the segment just retrieved. v The field HSDBHDMB of the HSDB points to the HDMB. Since the layout of these control blocks can change with High Performance Unload releases, the control blocks should be referred to symbolically by using the macros FABHPCB, FABHJCB, FABHSDB, and FABHDMB. The macros generate DSECTs describing the control blocks. The control blocks should never be modified by user routines (except the field HJCBUSER of the HJCB and the field HSDBUSER of the HSDB, which can be freely used). Note: If you plan to use the Get-by-RBA call in an IMS environment that supports an OSAM database larger than 4 gigabytes, pay attention to the RBA that you get from HSSR Engine. You must check the flag byte HDMBAMDA in the HDMB for the database data set that you are processing when you treat an RBA. The flag HDMBOS8G in this flag byte is on if and only if all of the following conditions are satisfied: 1. Your IMS environment supports relative byte addressability for up to 8 gigabytes of data in an OSAM HDAM or HIDAM database data set. This function has been introduced by PN82671. 2. Your database is an OSAM database. 3. Your database has an even block size. If HDMBOS8G is on, the lowest bit of the internal RBA represents the highest bit of the real 33-bit RBA. For example, the internal RBA X'00000001' represents the real RBA X'100000000'. If HDMBOS8G is off, the internal RBA is equal to the real RBA. See IMS APAR PN82671 for more information on this internal representation. The RBA specified on the operand of a Get-by-RBA call must be in the internal format. End of Product-Sensitive Programming Interface

332

Users Guide

Coding and link-editing the routine

Product-Sensitive Programming Interface When you link-edit the routine, consider the following points: v The routine must be link-edited with the REUSE option. v The routine must be link-edited in 31-bit addressing mode (AMODE 31). This is because database buffer pools are allocated above the 16MB line and the address of the segment prefix is set into a parameter list as a 31-bit address. The HDMB and HRAN control blocks are also above the 16MB line. Note: If the routine does not refer to the address of any segment prefix, HDMBs, or HRANs, it can be link-edited as AMODE 24. But the 31-bit addressing mode is recommended, to avoid the addressing mode problems. If the routine is link-edited in 31-bit addressing mode, but performs functions requiring AMODE 24, you should code the residency mode (RMODE) as needed. Before running the function, you must use the "capping" method to dynamically change the addressing mode to AMODE=24; after the function has run you must return to AMODE 31. Figure 64 is a sample code for such "capping":
* Change the addressing mode to AMODE 24 DS 0H L 14,VCT001 BSM 0,14 CNOP 0,4 DC AL4(*+4) DS 0H This is the functional part that requires 24-bit addressing mode. * * Change the addressing mode to AMODE 31 DS 0H L 14,VCT002 BSM 0,14 CNOP 0,4 DC AL4(*+4+X80000000) DS 0H

VCT001 EXT001 *

VCT002 EXT002

Figure 64. Sample code for capping

End of Product-Sensitive Programming Interface

Product-sensitive macros
Product-Sensitive Programming Interface The macros described here are provided for use by system programmers in writing programs that use the services of HSSR Engine. Only the macros identified in this chapter should be used to request or receive the services of HSSR Engine. The product-sensitive macros listed in Table 51 on page 334 are provided in HPS.SHPSMAC0 macro library:

Chapter 18. System programming interfaces

333

Table 51. Product-sensitive macros for system program interfaces Macro name FABHDMB FABHJCB FABHPCB FABHPTR FABHRAN FABHSDB FABHURGR FABHFSUR Description Mapping for HSSR Engine Data Management Block (HDMB) Mapping for HSSR Engine Job Control Block (HJCB) Mapping for HSSR PCB (HPCB) Mapping for HSSR Engine Pointer Block (HPTR) Mapping for HSSR Engine CAB RBA-range description table (HRAN) Mapping for HSSR Engine Segment Descriptor Block (HSDB) Mapping for the format *F1, *F2, or *F3 record that can be produced by the FABHURG1 unload utility Mapping for the format HS, VB, or VN record that can be produced by the FABHFSU unload utility

For compatibility with earlier products, see Chapter 13, Compatibility with earlier products, on page 255. End of Product-Sensitive Programming Interface

334

Users Guide

Chapter 19. Setting site default options

Differences between the default option values of High Performance Unload and those of earlier products might interrupt smooth JCL migration. As a solution, the capability to change the default value for some options is provided. You can do this by replacing the High Performance Unloads default option table (FABHOPT). This chapter describes the product-sensitive programming interface information. See Programming interface information on page 484 to understand the restrictions associated with this type of material. Topics: v v v v v Determining run-time parameters Replacing the HSSR option table (FABHOPT) on page 336 FABHOPTG sample JCL on page 336 Coding the FABHTOPT macro on page 337 Examples of FABHTOPT macro statements on page 339

Determining run-time parameters

Product-Sensitive Programming Interface Figure 65 illustrates how the run-time parameters are determined. The sources that determine the run-time parameters are placed in the order of priority; that is, an option in a higher position in the figure overrides one in a lower position.

Figure 65. How run-time parameters are determined

End of Product-Sensitive Programming Interface

Copyright IBM Corp. 2000, 2007

335

Replacing the HSSR option table (FABHOPT)

Product-Sensitive Programming Interface You can replace the IBM-supplied default option table (FABHOPT) in HPS.SHPSLMD0 load module library with your own table containing options applicable to your site. To do this, the following steps are required: 1. Copy the sample JCL FABHOPTG from the sample library (see FABHOPTG sample JCL on page 336). 2. Code the FABHTOPT macro in the copied JCL (see Coding the FABHTOPT macro on page 337). 3. Submit the JCL to replace the IBM-supplied default option table. Defaults for options listed in Table 52 can be specified by replacing the default option table.
Table 52. Options for which default values can be specified Keyword URG1DEC URG1CHKRC URG1BUFNO Description DEC option for FABHURG1 (unload utility) CHECKREC option for FABHURG1 (unload utility) Related data set SYSIN (for FABHURG1) SYSIN (for FABHURG1)

The default number of buffers to be assigned to the N/A DCBs for the output data sets to store the unloaded records. DEC option for FABHFSU (unload utility) The number of buffers to be assigned to the DCBs for the output data sets to store the unloaded records other than the HS format records. CAB statistics report option LSR option Level of API set Type of PCB list Specifies how the default buffer handler is determined Specifies how the default CAB parameters are determined CARDIN (for FABHFSU) N/A

FSUDEC FSUBUFNO

CABSTAT LSR APISET PCBLIST BUFDEFAULT CABDEFAULT

HSSROPT HSSROPT HSSROPT HSSROPT HSSRCABP HSSRCABP

End of Product-Sensitive Programming Interface

FABHOPTG sample JCL

Product-Sensitive Programming Interface FABHOPTG JCL is a sample JCL for use in creating a user-defined default option table. FABHOPTG JCL is provided as a member of the HPS.SHPSSAMP library. FABHOPTG assembles the user-specified FABHTOPT macro statement and replaces the FABHOPT option table module in the HPS.SHPSLMD0 load module

336

Users Guide

library. End of Product-Sensitive Programming Interface

Coding the FABHTOPT macro

Product-Sensitive Programming Interface The rules for coding the FABHTOPT macro are the same as those for coding macro statements in Assembler language. FABHTOPT must be preceded and followed by at least one blank space, and parameters must be separated by commas.

(label)

FABHTOPT

COMPAT=[HPU|DBT|5787LAC] [,APISET=1|2|3] [,DIAGG=([CB][,BUF])|NOINT|DIAGONLY] [,CABSTAT=YES|NO] [,LSR=YES|NO] [,URG1DEC=YES|NO] [,URG1BUFNO=nnn] [,URG1CHKRC=YES|NO] [,FSUDEC=YES|NO] [,FSUBUFNO=nnn] [,BUFDEFAULT=CAB|BB] [,CABDEFAULT=HPU|DBT] [,PCBLIST=HSSR|IMS]

Keyword COMPAT=

Description This optional keyword specifies the basic setting of FABHTOPT. High Performance Unload provides three basic settings: HPU, DBT, and 5787LAC. The default basic setting is HPU. Table 53 shows the options to be set by the three basic settings:

Table 53. Basic settings of FABHTOPT options COMPAT= Keyword APISET= DIAGG= CABSTAT= LSR= URG1DEC= URG1BUFNO= URG1CHKRC= FSUDEC= FSUBUFNO= BUFDEFAULT= CABDEFAULT= PCBLIST= HPU 1 DIAGONLY NO NO YES defnum * NO YES defnum * CAB HPU HSSR DBT 1 DIAGONLY YES NO YES defnum * NO YES defnum * BB DBT HSSR 5787LAC 1 (CB,BUF) NO NO YES defnum * NO YES defnum * BB DBT HSSR

Chapter 19. Setting site default options

337

Table 53. Basic settings of FABHTOPT options (continued) COMPAT= Keyword HPU DBT 5787LAC

*: The number is determined from the block size of the output data set by each unload utility.

You can use the following keywords to override the values set by the basic settings: APISET= DIAGG= This optional keyword specifies the default for the APISET option in HSSROPT. This optional keyword specifies the default interpretation for the DIAGG statement with its operand left blank, as follows:
//HSSROPT DD * DIAGG /*

CABSTAT= LSR= URG1DEC=

This optional keyword specifies the default for the CABSTAT option in HSSROPT. This optional keyword specifies the default for the LSR option in HSSROPT. This optional keyword specifies the default for the DEC option in SYSIN for the FABHURG1 utility jobs. This optional keyword specifies the default number of buffers to be assigned to the DCBs for the output data sets to store the unloaded records. Specifies a left-justified decimal number from 1 to 255. If this option is not specified, the default number is determined from the block size. The BUFNO= specification in the JCL DD statement is prior to this default number. This optional keyword specifies the default for the CHECKREC option in SYSIN for the FABHURG1 utility jobs. This optional keyword specifies the default for the DEC option in CARDIN for the FABHFSU utility jobs. This optional keyword specifies the default number of buffers to be assigned to the DCBs for the output data set to store the unloaded records other than the HS format records. Specifies a left-justified decimal number from 1 to 255. If this option is not specified, the default number is determined from the block size. The BUFNO= specification in the JCL DD statement is prior to this default number. This optional keyword specifies how the default buffer handler is determined. If BUFDEFAULT=CAB is specified, CAB is used as the default buffer handler for ESDS and OSAM data sets.

URG1BUFNO=

URG1CHKRC=

FSUDEC=

FSUBUFNO=

BUFDEFAULT=

338

Users Guide

If BUFDEFAULT=BB is specified, BB is used as the default buffer handler for all ESDS and OSAM data sets except data sets of PHDAM and PHIDAM. For PHDAM and PHIDAM, the default buffer handler for ESDS and OSAM data sets is always CAB. CABDEFAULT= This optional keyword specifies how the default CAB buffering parameters that can be specified in HSSRCABP data set are to be determined. If CABDEFAULT=HPU is specified, the default CAB parameters are determined automatically from the characteristics of the database data sets. If CABDEFAULT=DBT is specified, the fixed default CAB parameters that are compatible with DBT V2 HSSR are used for ESDS and OSAM data sets. For PHDAM and PHIDAM, the default CAB parameters are always determined from the characteristics of the database data sets. PCBLIST This optional keyword specifies the type of PCB list that is passed to the application program. End of Product-Sensitive Programming Interface

Examples of FABHTOPT macro statements

The following sections provide examples of coding FAHTOPT macro statement.

Example 1
Product-Sensitive Programming Interface The following FABHTOPT macro statement is used to create a user table containing the defaults that are compatible with DBT V2 HSSR:
FABHTOPT COMPAT=DBT

End of Product-Sensitive Programming Interface

Example 2
Product-Sensitive Programming Interface The following FABHTOPT macro statement is used to create a user table containing

Chapter 19. Setting site default options

339

the defaults that are compatible with PO HSSR:

FABHTOPT COMPAT=5787LAC

End of Product-Sensitive Programming Interface

Example 3
Product-Sensitive Programming Interface The following FABHTOPT macro statement is used to create a user table containing the defaults that are compatible with PO HSSR, except that CAB is used as the default buffer handler for ESDS and OSAM data sets, and that the default CAB buffering parameters are determined from the characteristics of database data sets:
FABHTOPT COMPAT=5787LAC,BUFDEFAULT=CAB,CABDEFAULT=HPU

End of Product-Sensitive Programming Interface

340

Users Guide

Part 3. Using Sequential Subset Randomizer

Chapter 20. Introduction . . . . . . . . . . . . . . . . Characteristics of Sequential Subset Randomizer . . . . . . . . Program functions . . . . . . . . . . . . . . . . . . . Physical clustering of all database records . . . . . . . . . Database retrievals . . . . . . . . . . . . . . . . . . Generation of Sequential Subset Randomizer and database . . . Splitting the unloaded data set . . . . . . . . . . . . . . Providing statistical information . . . . . . . . . . . . . Differences between Sequential Subset Randomizer and Sequential Randomizers . . . . . . . . . . . . . . . . . . . . Advantages of Sequential Subset Randomizer . . . . . . . . Advantages of Sequential Randomizers . . . . . . . . . . Differences between Sequential Subset Randomizer and DFSHDC40 Advantages of Sequential Subset Randomizer . . . . . . . . Advantages of DFSHDC40 . . . . . . . . . . . . . . . Typical uses and benefits . . . . . . . . . . . . . . . . Program structure . . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . . . . . Chapter 21. Generation of Sequential Subset Randomizer . Job steps . . . . . . . . . . . . . . . . . . . . Data flow . . . . . . . . . . . . . . . . . . . . JCL requirements . . . . . . . . . . . . . . . . . Cataloged procedure . . . . . . . . . . . . . . . . Input . . . . . . . . . . . . . . . . . . . . . . SYSIN data set . . . . . . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . General rules for macro statements . . . . . . . . . FABITAB macro statement . . . . . . . . . . . . . FABIDEF macro statement . . . . . . . . . . . . . FABIGEN macro statement . . . . . . . . . . . . . END statement . . . . . . . . . . . . . . . . . Example 1: Generating Sequential Subset Randomizer, case 1 Example 2: Generating Sequential Subset Randomizer, case 2 Chapter 22. Splitting the unloaded database data set Job steps . . . . . . . . . . . . . . . . . Data flow . . . . . . . . . . . . . . . . . JCL . . . . . . . . . . . . . . . . . . . Output . . . . . . . . . . . . . . . . . . SYSPRINT data set . . . . . . . . . . . . Function . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . Split Unloaded Data Set Statistics report . . . . HDR data set . . . . . . . . . . . . . . . FKDn data set . . . . . . . . . . . . . . TRL data set . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 343 344 344 345 345 345 346 346 346 346 346 346 347 347 348 349 351 351 351 352 352 352 352 352 353 353 353 355 356 356 356 357 359 359 359 360 361 361 361 362 362 363 363 363 363

Chapter 23. Sequential Subset Statistics . . . . . . . . . . . . . . 367 Job steps . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Data flow . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Copyright IBM Corp. 2000, 2007

341

JCL requirements . . . . . . . InputHSSROPT data set . . . . Function . . . . . . . . . . Format . . . . . . . . . . SSSTATS control statement . . . OutputHSSRSTAT data set . . . Function . . . . . . . . . . Format . . . . . . . . . . Sequential Subset Statistics report Example . . . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

368 369 369 369 369 369 370 370 370 372 373 373 374 374 374 375 375 376 377 377

Chapter 24. Related user tasks . . . . . . . . . . . . . . . . Database design: Defining the subset IDs . . . . . . . . . . . . Application programming . . . . . . . . . . . . . . . . . . . Database administration . . . . . . . . . . . . . . . . . . . Specifying the relative amount of space to each subset . . . . . . Converting databases to HDAM databases randomized with Sequential Subset Randomizer . . . . . . . . . . . . . . . . . . . Converting from a database randomized with DFSHDC40 . . . . Converting from a database randomized with other randomizers . . Converting from a HISAM or HIDAM . . . . . . . . . . . . Monitoring the database . . . . . . . . . . . . . . . . . .

342

Users Guide

Chapter 20. Introduction

The Sequential Subset Randomizer utility is used to implement databases that combine: v Fast random online access provided by HDAM v Fast sequential processing of all database records belonging to one or multiple subsets of database records Sequential Subset Randomizer supports fast sequential processing of database records belonging to a subset by: v Storing all database records of a subset close together in the HDAM root addressable area v Allowing the retrieval of the first database record of a subset With Sequential Subset Randomizer, all database records of subset n are stored before the database records of subset n+1. During sequential database processing, all database records of subset n are retrieved before database records of subset n+1. However, the database records of a subset are neither stored nor retrieved in their logical key sequence. If a database consists of 20 subsets, the sequential retrieval of all root segments with Sequential Subset Randomizer will require one 20th, on the average, of the elapsed time which is required with the standard IMS DFSHDC40 randomizer (hereafter, called DFSHDC40). Topics: v Characteristics of Sequential Subset Randomizer v Program functions on page 344 v Differences between Sequential Subset Randomizer and Sequential Randomizers on page 346 v Differences between Sequential Subset Randomizer and DFSHDC40 on page 346 v Typical uses and benefits on page 347 v Program structure on page 348 v Restrictions on page 349

Characteristics of Sequential Subset Randomizer

The randomizing techniques used by Sequential Subset Randomizer are an extension of the randomizing techniques used by the standard IMS DFSHDC40 randomizer module. Sequential Subset Randomizer maintains (as DFSHDC40 does) the physical RAP sequence of database records through a database reorganization in the following cases: v The number of CIs/blocks within the Root Addressable Area (RAA) is changed. v The CI size or block size is changed. v The number of RAPs per CI/block is changed. v The relative amount of space within the RAA allocated to each subset is changed. A change of these characteristics requires a database reorganization.

Copyright IBM Corp. 2000, 2007

343

With Sequential Subset Randomizer, as with DFSHDC40, if two different databases have database roots with identical keys, the physical RAP sequence of the database roots will be the same in the two databases. As DFSHDC40, Sequential Subset Randomizer supports the formatting of the whole root addressable area through the insertion of a root whose key begins with an X'FF'.

Program functions
Sequential Subset Randomizer can be used to group subsets of database records close together. Therefore, it can speed up the execution of all of the Batch/BMP/MPP/IFP IMS programs and the IMS High Performance Unload utility programs that sequentially scan large HDAM databases in order to process only the database records of subsets.

Physical clustering of all database records

Sequential Subset Randomizer allows physical clustering of all database records belonging to the same subset (if the subsets can be defined as groups of database records having root keys within a common key range). With Sequential Subset Randomizer, the sequential scanning that processes database records of the same subset does not require the scanning of the whole HDAM database. Only the portion of the HDAM database that contains the database records of the subset to be processed needs to be scanned. With Sequential Subset Randomizer, the root addressable area of an HDAM database is conceptually divided into multiple portions. The first portion is used for the database records of the first subset, the second portion is used for the database records of the second subset, and so on. To use Sequential Subset Randomizer, all database records belonging to the same subset must have root keys within one common key range. The common key range must be identified by n bytes of the root key (where n is a number smaller than or equal to the number of bytes within the root key) starting at the fixed position within the root key. These n bytes are called the subset ID. Figure 66 on page 345 shows how a root addressable area is divided by the subset IDs. In this example, the branch IDs are the subset IDs.

344

Users Guide

Root Key

bb ccc Customer Number Branch ID = Subset ID

ZZ

ZZ477 ZZ986 ZZ639 ZZ040

ROOT SEG. AB
AB321 AB001 AB 841 AA711 AA056 AA123

AA (Subset ID)

SEG.

SEG.

ROOT SEG.

SEG.

SEG.

Figure 66. Physical clustering with Sequential Subset Randomizer

Database retrievals
Sequential Subset Randomizer allows retrievals through a qualified GU call (with special root key values in the SSA) of the first database root segment belonging to each subset. Application programs which process all database records of a subset can: v Retrieve the first database record of the subset by using this GU call. v Retrieve the further database records of the subset by using GN calls. v Check if it has finished processing all database records of the subset by testing in the PCB key feedback area (or in the segment I/O area) for a root key value which no longer belongs to the key range of the subset.

Generation of Sequential Subset Randomizer and database

Ordinarily, one Sequential Subset Randomizer is generated for each database to be randomized. However, if multiple databases have the same characteristics (if they have the same subsets, the same relative amount of space to be reserved for each subset, the same offset within the root key of the subset IDs, and so on), one common Sequential Subset Randomizer may be used for these multiple databases.

Splitting the unloaded data set

The database reorganization can be accelerated by splitting an unloaded database data set into multiple data sets with the FABIUNLS utility. The purpose of this splitting is to provide input to the IMS HD Reorganization Reload utility. The split data sets are then sorted in the sequence that allows reloading of large databases in a reasonable amount of time.

Chapter 20. Introduction

345

Providing statistical information

The SS-STATS (Sequential Subset Statistics) routine (FABISTAT) is an exit routine of the High Performance Unloads database unload utilities FABHURG1 and FABHFSU. It provides database administrators with statistical information that is useful in determining how much relative space in the root addressable area needs to be allocated to each subset.

Differences between Sequential Subset Randomizer and Sequential Randomizers

The differences between Sequential Subset Randomizer and other Sequential Randomizers are described in detail. (In this guide, a Sequential Randomizer means a randomizer which randomizes database root segments in the logical sequence of the key value. They may be some of the IMS HD sequential randomizers or the users unique randomizers.)

Advantages of Sequential Subset Randomizer

For databases that do not need to be processed in the logical sequence of the root key values, Sequential Subset Randomizer provides the following advantages over Sequential Randomizers: v The performance of Sequential Subset Randomizer is less affected by a high volume of insertion and deletion activities than that of Sequential Randomizers. With a Sequential Randomizer, the user must often regenerate the Sequential Randomizer and reorganize the databases after inserting a large number of roots. This is often a long process. The database is unavailable to the applications during this time. With Sequential Subset Randomizer, a regeneration and reorganization are not necessary if the insert activities are evenly distributed across the different subsets, and if the HDAM database has been defined with enough free space to absorb the insert activities. v The tables of Sequential Subset Randomizer are smaller than those of the Sequential Randomizers. With huge HDAM databases, the tables of a Sequential Randomizer are often huge, and can often create substantial paging activity, which defeats the advantage of HDAM over HIDAM.

Advantages of Sequential Randomizers

Sequential Randomizers support storing and retrieving of database root segments in the logical sequence of the root key values. Sequential Subset Randomizer does not provide such support.

Differences between Sequential Subset Randomizer and DFSHDC40

The following are the differences between Sequential Subset Randomizer and DFSHDC40:

Advantages of Sequential Subset Randomizer

Sequential Subset Randomizer can be used to group all database records of a subset physically close together, thereby improving the processing time for programs that only process the database records of one or a few subsets. DFSHDC40 does not provide such support.

346

Users Guide

Advantages of DFSHDC40
With databases for which there is no need to physically group database records into subsets, DFSHDC40 has the following advantages over Sequential Subset Randomizer: v DFSHDC40 does not use subsets. Therefore the database administrator does not need to specify the relative amount of space to be reserved for each subset. v With DFSHDC40, there is no need to periodically monitor (and sometimes adapt) the relative amount of space effectively occupied by each subset. Adapting the relative amount of space allocated to each subset requires a reorganization of the database. Reorganization is often a long process and the database is unavailable during the reorganization.

Typical uses and benefits

Sequential Subset Randomizer is designed for the following types of databases: v Customer databases of companies with multiple branch offices. The key of the customer databases usually consists of a branch office ID and a customer number. In this case, each subset consists of the database records of all customers belonging to the same branch office. With Sequential Subset Randomizer, a program that has to process all database records of a branch office does not need to scan the whole database. The database scan can be limited to the part of the HDAM database that contains all database records of that branch office. v Databases of corporations that do business in different geographical areas. For the key of a root segment that contains an ID identifying a geographical area such as county and state, it is possible to define a subset of database records as the group of database records belonging to the same geographical area, county, or state. v Databases of companies that have multiple divisions. For the key of a root segment that contains the division ID, it is possible to define a subset of database records as the group of database records belonging to the same division. Sequential Subset Randomizer performs and benefits the following tasks: v Sequential Subset Randomizer is useful for the implementation of new HDAM databases if applications require fast sequential processing of subsets of database records (but do not require retrieval of the database records of a subset in their logical key sequence). v Sequential Subset Randomizer is useful when converting the following types of existing databases: HDAM databases randomized with DFSHDC40 (or with other nonsequential randomizers) if applications require fast sequential processing of subsets of database records. HISAM databases, HIDAM databases, and HDAM databases randomized with a sequential randomizer, if the retrieval in the logical key sequence is not required within subsets of database records.

Chapter 20. Introduction

347

Program structure
Sequential Subset Randomizer and its tables are generated by means of the SSRGEN process using three macro statements (those are, FABITAB, FABIDEF, and FABIGEN). During this process, the database designer (or the database administrator) identifies the subsets, their key ranges, and the space which must be reserved for each subset in the HDAM root addressable area. Sequential Subset Randomizer includes the following: v A utility program (FABIUNLS), which is used to speed up the database reorganization while converting from databases randomized with DFSHDC40 to databases randomized with Sequential Subset Randomizer. v An exit routine (FABISTAT) of IMS High Performance Unloads database unload utilities (that is, FABHURG1 and FABHFSU), which provides statistics about the number of roots and the total length of database records in each subset. These statistics are called SS-STATS. The SS-STATS can be used to specify the relative amount of space to be reserved within the root addressable area for each subset when you generate Sequential Subset Randomizer next time. Sequential Subset Randomizer complies to the usual IMS conventions for HDAM randomizing routines. Therefore, Sequential Subset Randomizer can be used with the High Performance Unload database unload utilities and with Batch/BMP/MPP/IFP IMS programs. However, the FABIUNLS utility and the SS-STATS exit routine run exclusively in IMS High Performance Unload jobs. Sequential Subset Randomizer can run with multiple IMS versions and releases without re-installing the product as far as the version/release is supported by High Performance Unload. Refer to Software requirements on page 18 for the list of supported IMS versions and releases.

348

Users Guide

Restrictions
The following restrictions are applicable to Sequential Subset Randomizer: v Sequential Subset Randomizer supports a maximum of 1000 subsets. v If the length of a subset ID is not smaller than the length of the root key, Sequential Subset Randomizer does not provide any special support for retrieval of the first root segment of the subset. v If a subset ID does not start in the first position of the key of the root segment, the root addressable area must contain at least as many RAPs as the number of subsets.

Chapter 20. Introduction

349

350

Users Guide

Chapter 21. Generation of Sequential Subset Randomizer

Sequential Subset Randomizer and its tables are generated by means of the process called SSRGEN. A Sequential Subset Randomizer load module is produced by an assembly and link-edit. Topics: Job steps Data flow JCL requirements on page 352 Cataloged procedure on page 352 Input on page 352 Example 1: Generating Sequential Subset Randomizer, case 1 on page 356 v Example 2: Generating Sequential Subset Randomizer, case 2 on page 357 v v v v v v

Job steps
The assembly requires the following macro libraries: v SYS1.MACLIB v HPS.SHPSMAC0 v IMSVS.SDFSMAC Database designer and/or administrators need to provide the following information through macro statements: v The length of the subset IDs (the default is 1) v The relative start position of the subset ID within the root key (the default is 1) v Whether the values for the subset IDs are provided as hexadecimal values or as EBCDIC values (the default is EBCDIC) v Whether the values for the subset IDs are exact values or high-values (the default is exact value) v For each subset: The subset ID value The relative amount of space to be reserved in the root addressable area

Data flow
The general data flow for the generation of Sequential Subset Randomizer is shown in Figure 67.

Macro Statements

A ss e m bl e Li nk - E d i t

S eq u e n t i a l Su b se t Randomizer Randomizer Ta b l e

Figure 67. Data flow of the generation of Sequential Subset Randomizer (SSRGEN)

Copyright IBM Corp. 2000, 2007

351

JCL requirements
To generate Sequential Subset Randomizer, supply an EXEC statement and the appropriate DD statements. Table 54 summarizes the DD statements.
Table 54. DD statements DDNAME SYSLIB SYSIN SYSLMOD Use Input Input Output Format LRECL=80 LRECL=80 Need Required Required Required

The actual JCL requirements are as follows: EXEC The EXEC statement must be in the following format: |
// EXEC FABIRGEN,MBR=randname

SYSLIB DD This statement defines the input macro library data set. SYSIN DD This statement defines the input data set that contains your control statement. SYSLMOD This statement defines the output partitioned data set that contains the load module of the generated Sequential Subset Randomizer.

Cataloged procedure
| | To generate Sequential Subset Randomizer, use the IBM-supplied cataloged procedure FABIRGEN in the HPS.SHPSSAMP sample library. Example 1: Generating Sequential Subset Randomizer, case 1 on page 356 assumes that the IBM-supplied cataloged procedure is used.

Input
All input you must specify to generate Sequential Subset Randomizer is only a SYSIN data set. This section describes the input macro statements that you should provide in the SYSIN data set.

SYSIN data set

This section explains the SYSIN data set.

Function
The SYSIN data set contains the following statements: v FABITAB macro statement v FABIDEF macro statement v FABIGEN macro statement v END statement Note: Macro statements FKDTAB, FKD and FKDGEN can be used instead of FABITAB, FABIDEF, and FABIGEN, respectively. These macro statements are provided only for compatibility. The use of macros prefixed by FABI is recommended.

352

Users Guide

Format
This data set usually resides in the input stream. However, it can be defined either as a sequential data set, or as a member of a partitioned data set. It must contain 80-byte fixed-length records. BLKSIZE, if coded, must be a multiple of 80.

General rules for macro statements

The coding conventions for the macro statements are the same as Assembler coding conventions. The following describes the coding conventions that you must follow in writing macro statements. v The entries must be written in the following order: label, operation, operand, and remarks. v The entries must be contained in the begin column (1) through the end column (71) of the first line and, if needed, may continue in column (16) through column (71) of any continuation lines. v When a macro statement is not completed in the first line, column 72 must be coded with any character. v The entries must be separated from each other by one or more blanks. v If used, a label entry must start in the begin column. v The label and operation entries, each followed by at least one blank, must be contained in the first line of a macro statement. v The operation entry must begin at least one column to the right of the begin column. The name, operation, operand, and remarks entries are described below. Label Entry Operation Entry Operand Entries It is a symbol created by you to identify a macro statement. It is optional. It is the symbolic operation code specifying the macro operation desired. It is mandatory. They contain one or more operands that identify and describe data to be acted upon by the macro instruction. Remarks are used to describe the current macro instruction.

Remarks Entries

FABITAB macro statement

The FABITAB macro statement must be the first statement. The format of the FABITAB macro statement is as follows:
0........1.........2.........3.........4.........5.........6.........7.........8 12345678901234567890123456789012345678901234567890123456789012345678901234567890 Label FABITAB TABNAME=tabname, START=n, BYTES=m, IDTYPE=y, (C/X) VALTYPE=z (E/H)MIGRATE C C C C

Figure 68. FABITAB macro statement

Note: C in column 72 is a continuation character. Label Coding of the label is optional.

Chapter 21. Generation of Sequential Subset Randomizer

353

TABNAME=

This keyword parameter is optional. The value tabname of the keyword parameter is a table name; it is used only for documentation purposes. The table name consists of 18 alphanumeric characters. This keyword parameter specifies where the subset ID starts within the key field of the database root segment. The start position for the first byte of the root key is 1. The default is 1.

START=

BYTES=

This keyword parameter specifies the length of the subset ID. The subset ID must be completely located within the key field of the database root segment. Note: The available values of START=n and BYTES=m parameters are shown in the following algorithm:
n + m key length

The default is 1. IDTYPE= This keyword parameter specifies whether the values for the subset IDs on the FABIDEF macro statements are EBCDIC values (C) or hexadecimal values (X). The default is C. VALTYPE= This keyword parameter specifies whether the values of the subset IDs should be interpreted as exact values (E) or high values (H). The default is E. E When E is specified and a database root segment is inserted with a subset ID which has not been defined with an FABIDEF macro statement, Sequential Subset Randomizer interprets this as an error. Example: v FABIDEF macro statements are used to define subsets with subset ID values A, C, and D. v No FABIDEF macro statement is used to define a subset with a subset ID value B. v Database root segments are inserted with a subset ID value B. v Database root segments are inserted with a subset ID value E. In this example, Sequential Subset Randomizer considers the insertion of database root segments with subset ID values B and E as an error. As a result, all database root segments with a subset ID value B will be randomized to the first RAP of the subset with the subset ID value C (the higher and closest subset ID value). If a lot of database root segments are inserted with a subset ID value B, this will create a long HDAM synonym chain in the first RAP of the subset with the subset ID value C. All database root segments with a subset ID value E will be randomized to the last RAP of the subset with the subset ID value D.

354

Users Guide

When H is specified and a database root segment is inserted with a subset ID which has not been defined with an FABIDEF macro statement, Sequential Subset Randomizer interprets this as a normal situation. Example: v Two consecutive FABIDEF macro statements are used to define subsets with subset ID values of 1000 and 2000. v No FABIDEF macro statement is used to define a subset with a subset ID value 1500. v Database root segments are inserted with a subset ID value 1500. v Database root segments are inserted with a subset ID value 2500. In this example, Sequential Subset Randomizer considers the database root segments with a subset ID value 1500 as being normal database roots belonging to that subset which has a high value subset ID 2000. This subset consists of all database records whose subset ID is between 1000 and 2000 (1000 is excluded). Because Sequential Subset Randomizer does not store the root segments according to their key sequence within a subset, sequential database processing may retrieve a database root with a subset ID 1500 before a database root with subset ID 1400. Sequential Subset Randomizer considers the insertion of database root segments with a subset ID value 2500 as an error. Those segments which have higher subset ID values than the maximum subset ID value (2000) are randomized to the last RAP of the subset with the subset ID value 2000.

FABIDEF macro statement

One FABIDEF macro statement must be provided for each subset. The FABIDEF macro statements must be provided in the ascending sequence of the subset ID values. A maximum of 1000 FABIDEF macro statements can be provided.
1 Label FABIDEF ID=aaaaa,UNITS=nnnn
Figure 69. FABIDEF macro statement

Label ID=

Coding of the Label is optional. This keyword parameter specifies the subset ID value. v If IDTYPE=C has been specified on the FABITAB macro statement, the subset ID value must be specified as an

Chapter 21. Generation of Sequential Subset Randomizer

355

alphanumeric value of length n which has been defined on the BYTES=keyword of the FABITAB macro statement. v If IDTYPE=X has been specified on the FABITAB macro statement, the subset ID value must be specified as a hexadecimal value of length 2n (where n has been defined on the BYTES= keyword of the FABITAB macro statement). Example for coding a hexadecimal subset ID value (BYTES=3 on FABITAB):
ID=F0F403

UNITS=

This keyword parameter specifies the relative amount of space to be reserved in the HDAM root addressable area for the database records of the subset to be defined by this FABIDEF macro statement. The unit can be one of following numbers: v The number of roots per subset v The number of data bytes within all database segments of a subset v The number of RAPs to be reserved for the database records of a subset. The keyword parameter value must be an integer number (without decimal points and commas). Valid values are in the range between 0 and 2 Giga minus 1.

FABIGEN macro statement

The FABIGEN macro statement must be the last macro statement of the FABIRGEN (SSRGEN) source statements preceding the END statement. The FABIGEN macro statement must be coded as follows:

FABIGEN

Figure 70. FABIGEN macro statement

END statement
This END statement specifies the end of the SYSIN data set. The END statement must be coded as follows:

END

Figure 71. END statement

Example 1: Generating Sequential Subset Randomizer, case 1

Figure 72 on page 357 presents typical example for generating Sequential Subset Randomizer.

356

Users Guide

| | | | | | | | | | | | | |

// EXEC FABIRGEN,MBR=SSRRAND //C.SYSIN DD * FABITAB START=1,BYTES=1,VALTYPE=E FABIDEF ID=A,UNITS=450 BASEL FABIDEF ID=B,UNITS=150 BELLINZONA FABIDEF ID=C,UNITS=230 BERN FABIDEF ID=D,UNITS=170 BIEL FABIDEF ID=E,UNITS=110 CHUR .................. FABIDEF ID=Q,UNITS=800 ZURICH FABIGEN END /* //L.SYSLMOD DD DSN=RANDOMIZ.LIB(&MBR),DISP=SHR Figure 72. Example 1: Generating Sequential Subset Randomizer, case 1

In v v v

this example, the FABITAB macro statement specifies that: The subset ID starts at the first position of the root key (START=1). The length of the subset ID is 1 byte (BYTES=1). The values for the subset ids are exact values (VALTYPE=E).

Each FABIDEF macro statement defines a single subset with the following keywords: v ID= keyword defines the value of the subset ID. v UNITS= keyword defines how much relative space should be allocated to the subset. Note: The FABIDEF macro statements must be provided in ascending sequence of the subset ID values.

Example 2: Generating Sequential Subset Randomizer, case 2

Figure 73 presents another typical example for generating Sequential Subset Randomizer. | | | | | | | | | | | | | |
// EXEC FABIRGEN,MBR=SSRRAND //C.SYSIN DD * FABITAB START=3,BYTES=2,VALTYPE=H,IDTYPE=X FABIDEF ID=0020,UNITS=47 San Francisco FABIDEF ID=0030,UNITS=24 San Jose FABIDEF ID=005A,UNITS=62 Los Angeles FABIDEF ID=0088,UNITS=31 San Diego FABIDEF ID=0094,UNITS=3 Los Gatos .................... FABIDEF ID=01FF,UNITS=6 Bakersville FABIGEN END /* //L.SYSLMOD DD DSN=RANDOMIZ.LIB(&MBR),DISP=SHR Figure 73. Example 2: Generating Sequential Subset Randomizer, case 2

In v v v

this example, the FABITAB macro statement specifies that: The subset ID starts at the third position of the Root-Key (START=3). The length of the subset ID is 2 bytes (BYTES=2). The values for the subset IDs are high values (VALTYPE=H).

Chapter 21. Generation of Sequential Subset Randomizer

357

v The values for the subset ID values are provided as hexadecimal values (IDTYPE=X). Each FABIDEF macro statement defines a single subset with the following keywords: v ID= keyword defines the (hexadecimal) values of the subset ID. v UNITS= keyword defines how much relative space should be allocated to the subset. The FABIDEF macro statements must be provided in ascending sequence of the hexadecimal subset ID values. The first FABIDEF macro statement specifies that database roots with subset ID values equal to or lower than X'0020' belong to the first subset. The second FABIDEF macro statement specifies that database roots with subset ID values between X'0020' and X'0030' (X'0020' being excluded) belong to the second subset. The rest of the FABIDEF macro statements define subsets of database roots in the same manner.

358

Users Guide

Chapter 22. Splitting the unloaded database data set

The FABIUNLS utility is used to speed up the database reorganization while converting databases randomized with DFSHDC40 into databases randomized with Sequential Subset Randomizer. FABIUNLS splits an unloaded database data set into multiple data sets as input to the IMS HD Reorganization Reload utility. The split data sets are sorted in the ascending order of subset ID so that a large databases can be reloaded in a reasonable amount of time. Topics: v v v v v Job steps Data flow JCL on page 360 Output on page 361 Example on page 363

Job steps
FABIUNLS takes an unloaded database data set in the HD unload format as input, and creates as output multiple data sets for use as concatenated input to the IMS HD Reorganization Reload utility program. FABIUNLS must be executed in a ULU region with the FABHULU JCL procedure (or with equivalent JCL). The following activities must be performed prior to the execution of FABIUNLS: v The database must be unloaded in the HD unload format. v Sequential Subset Randomizer must be generated for the database. v The DBD source statement must be changed in order to specify the name of the generated Sequential Subset Randomizer, and a DBDGEN must be performed.

Data flow
The general data flow for the FABIUNLS utility program is shown in Figure 74.

Figure 74. Data flow for FABIUNLS

Copyright IBM Corp. 2000, 2007

359

JCL
To execute FABIUNLS, supply an EXEC statement and the appropriate DD statements. Table 55 summarizes the DD statements. The actual JCL requirements are as follows:
Table 55. FABIUNLS DD statements DDNAME STEPLIB DFSVSAMP SYSPRINT SYSUT1 HDR FKDn TRL Use Input Input Output Input Output Output Output same as HDR LRECL=80 LRECL=133 Format Need Required Required Required Required Required Required Required

EXEC This statement invokes the JCL procedure FABHULU and has the following format:
// EXEC FABHULU,MBR=FABIUNLS,DBD=dbdname

The name of the DBD must be provided in place of dbdname. STEPLIB DD The STEPLIB must provide access to the load library which contains Sequential Subset Randomizer and IMS load modules. DFSVSAMP DD This statement is mandatory and must meet to the usual IMS requirements. SYSPRINT DD This DD statement is mandatory and defines a print data set which will contain statistics. The data set can be defined as:
//SYSPRINT DD SYSOUT=A

SYSUT1 DD This DD statement is mandatory and defines the input data set which contains the unloaded database in the HD unload format. The data set can be defined as:
//SYSUT1 DD DSN=unloaded.db,DISP=OLD

HDR DD This DD statement is mandatory and defines an output data set which will contain: v The header record of the HD unload format v The unloaded database records which do not belong to any subset defined during the generation of Sequential Subset Randomizer The data set can be defined as:
//HDR // // DD DSN=unls.hdr,DISP=(,CATLG), UNIT=SYSDA,SPACE=(TRK,(1,1)), DCB=(LRECL=nnnn,BLKSIZE=mmmm,RECFM=VB)

360

Users Guide

Recommended values for the BLKSIZE and LRECL are the same as the BLKSIZE and LRECL of the input data set described by the SYSUT1 DD statement. If it is not possible to meet these recommendations, the following minimum should be observed: v The minimum LRECL must be the larger of these two items: Largest database segment +39 bytes Length of the HD unload header record. v The minimum BLKSIZE must be LRECL+4. FKDn DD There should be one such DD statement for each subset defined during the generation of Sequential Subset Randomizer. The DD names of these data sets should be: FKD1, FKD2, FKD3, ...., FKD9, FKD10, FKD11, and so on. These DD statements are mandatory and define output data sets that will contain the unloaded database segments of the subsets. The FKD1 output data set will contain all unloaded database segments of the first subset, the FKD2 output data set will contain the unloaded database segments of the second subset, and so on. The data sets can be defined as:
//FKDn // // DD DSN=unls.fkdn,DISP=(,CATLG), UNIT=SYSDA,SPACE=(CYL,(m1,m2)), DCB=*.HDR

Enough DASD space must be allocated in order to contain all unloaded database records of the subset. If the Sequential Subset Statistics Report has been produced in the previous FABISTAT run, the statistics can help in determining the amount of DASD space required for each FKDn put data set. Note: For a complete description of the Sequential Subset Statistics Report and FABISTAT, see HDR data set on page 363. TRL DD This DD statement is mandatory and defines an output data set that will contain the trailer record of the HD unload format. The data set can be defined as:
//TRL // // DD DSN=unls.trl,DISP=(,CATLG), UNIT=SYSDA,SPACE=(TRK,(1,1)), DCB=*.HDR

Output
FABIUNLS produces the following four types of output data sets: v SYSPRINT: Statistical reports v HDR: A header record and unloaded database records that do not belong to any subset v FKDn: Unloaded database records v TRL: A trailer record

SYSPRINT data set

This section explains the SYSPRINT data set.

Function
FABIUNLS SYSPRINT data set produces the Split Unloaded Data Set Statistics Report.
Chapter 22. Splitting the unloaded database data set

361

Format
The format is 133-byte fixed-length records. When coded in the JCL, block size must be a multiple of 133. Code your DD statement as follows:
//SYSPRINT DD SYSOUT=A

Split Unloaded Data Set Statistics report

Figure 75 and Figure 76 show examples of the report.

IMS HIGH PERFORMANCE UNLOAD - SSR 5655-E06 DDNAME -----FKD1 FKD2 FKD3 FKD4 FKD5 FKD6 FKD7 FKD8 FKD9 FKD10 NBR OF ROOTS -----------1,354 1,561 2,094 808 2,340 564 1,515 962 1,250 1,735 NBR OF BYTES -----------2,274 2,349 3,225 1,250 3,553 957 2,355 1,658 1,459 2,750

"SPLIT UNLOADED DATA SET STATISTICS" DATE: 10/26/2007 TIME: 11.34.06 SUBSET-ID --------A100 A200 A300 A400 A500 A600 A700 A800 A900 B000

PAGE: 1 FABIUNLS - V1.R2

NBR OF ORPHANS= DBDNAME =SSRHDBD1 RANDOMIZER=SSRANDC1

131

Figure 75. Split Unloaded Data Set Statistics report (IDTYPE=C)

IMS HIGH PERFORMANCE UNLOAD - SSR 5655-E06 DDNAME -----FKD1 FKD2 FKD3 FKD4 FKD5 FKD6 NBR OF ROOTS -----------341 380 493 307 440 648 NBR OF BYTES -----------5,147 6,247 7,371 4,993 6,428 9,756

"SPLIT UNLOADED DATA SET STATISTICS" DATE: 10/26/2007 TIME: 11.42.10 SUBSET-ID --------EED100 22D000 EED200 22D000 EED300 22D000 EED400 22D000 EED500 22D000 EED600 22D000

PAGE: 1 FABIUNLS - V1.R2

NBR OF ORPHANS= DBDNAME =SSRHDBD2 RANDOMIZER=SSRANDX1

Figure 76. Split Unloaded Data Set Statistics report (IDTYPE=X)

Note: When IDTYPE=X is specified on the FABITAB macro statement as input for the generation of Sequential Subset Randomizer, the values in the subset ID fields are described as hexadecimal values using two lines. For example, the subset-ID values for FKD1 are described as follows:
EED.... 22D.... .

These values are X'E2', X'E2', and X'DD'.

362

Users Guide

On the SYSPRINT data set, FABIUNLS prints a table containing one entry for each subset with the following information: v The DD name of the output data set that contains the unloaded database records of the subset (for example, FKD1). v The number of database roots in the subset. v The total number of data bytes in all database segments that belong to the subset. Notes: 1. This number includes database segments of all data set groups. 2. If segments are compressed, this number reflects the data length of the decompressed segments. 3. The length of segment-prefixes is not included in this figure. v The first 83 bytes of the subset ID value printed in EBCDIC or in hexadecimal according to the value of IDTYPE=keyword on the FABITAB macro statement. FABIUNLS also prints how many database roots are orphans (that is, a root segment which does not belong to any subset). If VALTYPE=E is specified on the FABITAB macro statement, a root segment of which subset ID is not equal to any value of ID=keyword on the FABIDEF macro statement becomes an orphan. If VALTYPE=H is specified on the FABITAB macro statement, a root segment of which subset ID is higher than the maximum value of ID=keyword on the FABIDEF macro statement becomes an orphan. The number of orphans should be zero if the SSRGEN specifications (as input for the generation of Sequential Subset Randomizer) have been done correctly.

HDR data set

FABIUNLS HDR data set contains the following: v A header record of the HD unload format v Unloaded database records which do not belong to any subset defined during the generation of Sequential Subset Randomizer

FKDn data set

FABIUNLS FKDn data set contains the unloaded database segments of the subsets. Where n is the order of the generation of the output data sets. That is, the FKD1 data set contains all unloaded database segments of the first subset, the FKD2 data set contains the segments of the second subset, and so on.

TRL data set

FABIUNLS TRL data set contains the trailer record of the HD unload format.

Example
Figure 77 on page 364 shows an example of generating a database with the FABIUNLS utility program.

Chapter 22. Splitting the unloaded database data set

363

| |

//******************************************************* //* SPLIT THE UNLOADED-DB INTO MULTIPLE DATA SETS * //******************************************************* //* //SPLITUNL EXEC FABHULU,MBR=FABIUNLS,DBD=DPHIN02 //STEPLIB DD DSN=HPS.SHPSLMD0,DISP=SHR // DD DSN=IMSVS.SDFSRESL,DISP=SHR // DD DSN=RANDOMIZ.LIB,DISP=SHR //DFSRESLB DD DSN=IMSVS.SDFSRESL,DISP=SHR //DFSVSAMP DD * 4096,8 /* //SYSPRINT DD SYSOUT=A //SYSUT1 DD DSN=UNLOADED.DB,DISP=OLD //HDR DD DSN=DPHIN02E.HDR,DISP=(,CATLG), // VOL=SER=WRK34B,UNIT=SYSDA,SPACE=(TRK,1), // DCB=(RECFM=VB,LRECL=4092,BLKSIZE=4096) //FKD1 DD DSN=DPHIN02E.FKD1,DISP=(,CATLG), // VOL=SER=WRK34B,UNIT=SYSDA,SPACE=(CYL,(40,10)), // DCB=*.HDR //FKD2 DD DSN=DPHIN02E.FKD2,DISP=(,CATLG), // VOL=SER=WRK34C,UNIT=SYSDA,SPACE=(CYL,(40,10)), // DCB=*.HDR ........ ........ ........ //FKD17 DD DSN=DPHIN02E.FKD17,DISP=(,CATLG), // VOL=SER=WRK35A,UNIT=SYSDA,SPACE=(TRK,(1,10)), // DCB=*.HDR //TRL DD DSN=DPHIN02E.TRL,DISP=(,CATLG), // VOL=SER=WRK35B,UNIT=SYSDA,SPACE=(TRK,1), // DCB=*.HDR //* Figure 77. Example of database generation (Part 1 of 2)

364

Users Guide

| |

//***************************************************************** //* DEFINE THE CLUSTER FOR THE DATABASE * //***************************************************************** //* //ALLOCDB EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=A //SYSIN DD * DEFINE CLUSTER (NAME(USER.DB) ..... /* //* //***************************************************************** //* RELOAD THE DATABASE WITH THE SEQUENTIAL SUBSET RANDOMIZER * //***************************************************************** //* //RELOAD EXEC PGM=DFSRRC00,PARM=ULU,DFSURGL0,DPHIN02 //STEPLIB DD DSN=IMSVS.SDFSRESL,DISP=SHR // DD DSN=RANDOMIZ.LIB,DISP=SHR //DFSRESLB DD DSN=IMSVS.SDFSRESL,DISP=SHR //IMS DD DSN=IMSVS.DBDLIB,DISP=SHR //IEFRDER DD DUMMY //DFSVSAMP DD DSN=IMSVS.PROCLIB(DFSVSAMP),DISP=SHR //SYSPRINT DD SYSOUT=A //DFSUINPT DD DSN=DPHIN02E.HDR,DISP=OLD // DD DSN=DPHIN02E.FKD1,DISP=OLD // DD DSN=DPHIN02E.FKD2,DISP=OLD // DD .... // DD .... // DD DSN=DPHIN02E.FKD17,DISP=OLD // DD DSN=DPHIN02E.TRL,DISP=OLD //DB DD DSN=USER.DB,DISP=OLD //SYSUDUMP DD SYSOUT=A Figure 77. Example of database generation (Part 2 of 2)

Note: If the database is involved in logical relations or secondary indexing, additional DD statements are required by IMS for the reload job step.

Chapter 22. Splitting the unloaded database data set

365

366

Users Guide

Chapter 23. Sequential Subset Statistics

The Sequential Subset Statistics (SS-STATS) is provided as an exit routine of the High Performance Unload database unload utilities (that is, FABHURG1 and FABHFSU). The SS-STATS routine (FABISTAT) provides database administrators with statistical information, which is useful in determining how much relative space in the root addressable area needs to be allocated to each subset. For each subset, SS-STATS provides statistics about the number of database roots and about the total length of database segments within the subset. Topics: v v v v v v Job steps Data flow JCL requirements on page 368 InputHSSROPT data set on page 369 OutputHSSRSTAT data set on page 369 Example on page 372

Job steps
The SS-STATS routine (FABISTAT) is activated by specifying an SSSTATS control statement in the HSSROPT control data set of the High Performance Unloads database unload utilities. Sequential Subset Randomizer must be generated before the FABISTAT routine is run.

Data flow
The general data flow for the SS-STATS routine (FABISTAT) is shown in Figure 78 on page 368.

Copyright IBM Corp. 2000, 2007

367

Figure 78. Data flow for the SS-STATS routine

JCL requirements
The additional DD statements required to use the SS-STATS routine are described in Table 56.
Table 56. Additional DD statements DDNAME HSSROPT HSSRSTAT Use Input Output Format LRECL=80 LRECL=133 Need Required Required

To run the IMS High Performance Unload FABHURG1 and FABHFSU utilities, other DD statements are required. For details about the JCL, refer to Part 1, Using High Performance Unload, on page 1. HSSROPT DD This required input data set contains optional control statements such as the SSSTATS control statement. Usually, when the SS-STATS routine is activated, the database should already be an HDAM database using Sequential Subset Randomizer. However, the SS-STATS routine can be activated even if the database is not randomized with Sequential Subset Randomizer, or if it is not an HDAM DB. In this case, the user needs to provide the name of a Sequential Subset Randomizer (which has been generated with an accurate description of the subsets and subset IDs) on the SSSTATS control statement.

368

Users Guide

HSSRSTAT DD This required output data set is used for IMS High Performance Unload to write statistical reports. The reports of the SS-STATS routine are also written to the HSSRSTAT data set.

InputHSSROPT data set

The SS-STATS routine is activated by the HSSROPT data set. This section describes the HSSROPT data set and its control statement. For the other IMS High Performance Unload input data sets, refer to Part 1, Using High Performance Unload, on page 1.

Function
The HSSROPT data set contains optional control statements of IMS High Performance Unload. However, in this chapter, only the SSSTATS control statement that activates the SS-STATS routine is described. For more information, refer to Part 1, Using High Performance Unload, on page 1.

Format
This data set contains 80-byte fixed-length records. The control statements can be coded in the input stream or accessed as a member of a partitioned data set.

SSSTATS control statement

The SS-STATS routine is activated by specifying an SSSTATS control statement in the HSSROPT data set in the format shown in Figure 79.
//HSSROPT DD * SSSTATS randname /*

Figure 79. Activating the SS-STATS routine

The control statement in the HSSROPT data set should be coded as follows: v Columns 17 should contain SSSTATS. v Column 8 should be blank. v Columns 916 should be one of the following: Blank (if the database is an HDAM database using a Sequential Subset Randomizer). If the database is not an HDAM database using a Sequential Subset Randomizer, it should contain the load module name of a Sequential Subset Randomizer which has been generated with an accurate description of the subsets and subset IDs. The load module library containing Sequential Subset Randomizer should be accessible (for example, through a STEPLIB DD statement).

OutputHSSRSTAT data set

When the SS-STATS routine has been activated, High Performance Unload produces an HSSRSTAT data set that contains printed statistical reports.

Chapter 23. Sequential Subset Statistics

369

Function
This data set contains the Sequential Subset Statistics Report when the SS-STATS exit routine has been activated. For information about the other reports that this data set contains, refer to Part 1, Using High Performance Unload, on page 1.

Format
This data set contains 133-byte fixed-length records. When the block size is coded in the JCL, it must be a multiple of 133. Code your DD statement as follows to get the statistics output of the SS-STATS routine:
//HSSRSTAT DD SYSOUT=A

Sequential Subset Statistics report

Figure 80 and Figure 81 on page 371 show an example of Sequential Subset Statistics Report.

IMS HIGH PERFORMANCE UNLOAD - SSR 5655-E06 SUBSET NBR ---------1 2 3 4 5 6 7 8 9 10 NBR OF ROOTS -----------2,026 1,030 0 0 0 1,003 0 0 2,005 1,018 NBR OF BYTES -----------3,500 4,280 0 0 0 1,400 0 0 620 310 SUBSET-ID --------10000 12000 14000 16000 18000 20000 22000 24000 26000 30000

"SEQUENTIAL SUBSET STATISTICS" DATE: 10/26/2007 TIME: 11.26.15

PAGE: 1 FABISTAT - V1.R2

Figure 80. Sequential Subset Statistics report (IDTYPE=C) (Part 1 of 2)

IMS HIGH PERFORMANCE UNLOAD - SSR 5655-E06 SUBSET NBR ---------1 2 3 4 5 6 7 8 9 10 % OF ROOTS ---------28.58 14.30 0.00 0.00 0.00 14.26 0.00 0.00 28.56 14.28 % OF BYTES ---------34.61 42.33 0.00 0.00 0.00 13.84 0.00 0.00 6.13 3.06 SUBSET-ID --------10000 12000 14000 16000 18000 20000 22000 24000 26000 30000

"SEQUENTIAL SUBSET STATISTICS" DATE: 10/26/2007 TIME: 11.26.15

PAGE: 2 FABISTAT - V1.R2

NBR OF ORPHANS= DBDNAME =SSRHDBD3 RANDOMIZER=SSRANDC2

121

Figure 80. Sequential Subset Statistics report (IDTYPE=C) (Part 2 of 2)

370

Users Guide

IMS HIGH PERFORMANCE UNLOAD - SSR 5655-E06 SUBSET NBR ---------1 2 3 4 5 NBR OF ROOTS -----------30 121 19 345 83 NBR OF BYTES -----------15,645 62,990 15,642 179,760 43,226

"SEQUENTIAL SUBSET STATISTICS" DATE: 10/26/2007 TIME: 10.06.31 SUBSET-ID --------EED00000FFFF 22D010000001 EED00000FFFF 22D020000002 EED00000FFFF 22D030000003 EED00000FFFF 22D040000004 EED00000FFFF 22D050000005

PAGE: 1 FABISTAT - V1.R2

Figure 81. Sequential Subset Statistics report (IDTYPE=X) (Part 1 of 2)

IMS HIGH PERFORMANCE UNLOAD - SSR 5655-E06 SUBSET NBR ---------1 2 3 4 5 % OF ROOTS ---------5.02 20.23 3.18 57.69 13.88 % OF BYTES ---------4.93 19.85 4.93 56.66 13.62

"SEQUENTIAL SUBSET STATISTICS" DATE: 10/26/2007 TIME: 10.06.31 SUBSET-ID --------EED00000FFFF 22D010000001 EED00000FFFF 22D020000002 EED00000FFFF 22D030000003 EED00000FFFF 22D040000004 EED00000FFFF 22D050000005

PAGE: 2 FABISTAT - V1.R2

NBR OF ORPHANS= DBDNAME =SSRHDBD4 RANDOMIZER=SSRANDX2

154

Figure 81. Sequential Subset Statistics report (IDTYPE=X) (Part 2 of 2)

Note: When IDTYPE=X is specified on the FABITAB macro statement as input for the generation of Sequential Subset Randomizer, the values in the subset ID fields are described as hexadecimal values using two lines. For example, the subset-ID values for FKD1 are described as follows:
EED.... 22D.... .

These values are X'E2', X'E2', and X'DD'. The SS-STATS routine prints a table containing one table entry for each subset with the following information on the HSSRSTAT data set: v The relative subset number. v The number of database roots in the subset. v The total number of data bytes and prefix bytes in all database segments that belong to the subset. Notes: 1. This number includes only database segments of the first data set group.

Chapter 23. Sequential Subset Statistics

371

2. If segments are compressed, this number reflects the data length of the compressed segments (when stored on DASD). 3. The length of segment prefixes is included in this figure. v The first 83 bytes of the subset ID value printed in EBCDIC or in hexadecimal according to the value of IDTYPE=keyword on the FABITAB macro statement. The SS-STATS routine prints a second table where the number of root segments and the number of data bytes are expressed as the percentage of all databases. The SS-STATS routine also prints how many database roots are orphans. An orphan is a root segment which does not belong to any subset. The number of orphans should be zero, if the SSRGEN specifications (as input for the generation of Sequential Subset Randomizer) have been done correctly.

Example
Figure 82 shows an example of JCL for database unload with SS-STATS.
//UNLOAD EXEC FABHULU,MBR=FABHURG1,DBD=DPANL0 //STEPLIB DD DSN=HPS.SHPSLMD0,DISP=SHR // DD DSN=IMSVS.SDFSRESL,DISP=SHR // DD DSN=RANDOMIZ.LIB,DISP=SHR //DFSVSAMP DD DSN=IMSVS.PROCLIB(DFSVSAMP),DISP=SHR //HSSRCABP DD * CABDD *HD /* //HSSROPT DD * SSSTATS randname /* //HSSRSTAT DD SYSOUT=A //HDAM DD DSN=HDAM.DB,DISP=SHR //SYSPRINT DD SYSOUT=A //SYSUT2 DD DSN=UNLOAD.HDAM.DB,DISP=(,CATLG), // UNIT=TAPE Figure 82. Example of JCL for database unload with SS-STATS

Notes: 1. The STEPLIB DD statement provides access to the load library containing Sequential Subset Randomizer. 2. The SSSTATS control statement in the HSSROPT data set requests the activation of the SS-STATS routine, which prints statistics on the HSSRSTAT data set for each subset. 3. A randomizer load module name is specified on the SSSTATS control statement because the database to be unloaded is not yet randomized with Sequential Subset Randomizer. The specified Sequential Subset Randomizer must have been generated with an exact description of all subsets and subset ID values.

372

Users Guide

Chapter 24. Related user tasks

This chapter describes Sequential Subset Randomizer from the viewpoint of the user tasks. This chapter helps you in doing the following tasks: v Database design, especially when defining the subset IDs v Application programming v Database administration v Monitoring databases Topics: v Database design: Defining the subset IDs v Application programming on page 374 v Database administration on page 374

Database design: Defining the subset IDs

Database designers need to define the subsets and the subset IDs. This is often trivial work in the following case: v The subsets are defined as the database records belonging to a branch office. v The branch office ID is contained at a fixed location of the database root key. In this case, the subset ID is defined as the branch office ID. A subset is the group of database records belonging to the same branch office. The following points should be observed: v The subset ID must be completely embedded within the root key and must start at a fixed location within the root key. The length of the subset ID is fixed and must be smaller than or equal to the length of the root key. v The number of bytes within the subset ID should be smaller than the number of bytes within the root key if the application needs the support of Sequential Subset Randomizer in order to retrieve the first database record of a subset. v For each subset, the user must define a value for the subset ID during the generation of Sequential Subset Randomizer. Sequential Subset Randomizer supports the following two different interpretations of the subset ID values: 1. VALTYPE=E (Value Type=Exact): Sequential Subset Randomizer assumes that all database records belonging to a subset will have the exact value specified during the generation of Sequential Subset Randomizer as a subset ID. 2. VALTYPE=H (Value Type=High): Sequential Subset Randomizer assumes that the value specified during the generation of Sequential Subset Randomizer is a high value. The database records belonging to a subset have subset IDs in the range between two specified subset ID values (between the high value of the preceding subset and the high value of this subset). v The implementation of Sequential Subset Randomizer does not support more than 1000 subsets.

Copyright IBM Corp. 2000, 2007

373

Application programming
This section describes application programming available to system programmers. It is a product-sensitive programming interface. See Programming interface information on page 484 to understand the restrictions associated with this type of material. Product-Sensitive Programming Interface Sequential Subset Randomizer is ineffective for application programs that do not use the physical grouping of database records by subsets. These programs are not affected by a conversion from DFSHDC40 randomizing to Sequential Subset Randomizing (if they are not sensitive to the sequence in which the database records are retrieved during sequential database processing). When an application programmer wants to use the physical clustering of database records, the following should be considered: 1. Retrieval of the first database record of a subset: The first root segment of a subset can be retrieved by a qualified GU call using the following SSA: ROOTNAME(KEY-NAME=>...SID......) SID Subset ID. It must reside at the same position as the subset ID in the root key. When VALTYPE=H was specified during the generation of Sequential Subset Randomizer, the minimum value within the required subset ID must be used for the GU call. Binary zeros.

.....

Note: When orphan root segments exist in the database, they may also be retrieved by the above GU call. In such a case, the succeeding root segments must be processed sequentially until the required subset ID value is encountered. 2. End of the database records of a subset: An application program which sequentially processes a database can detect that it has processed the last database record of a subset. It can be done by detecting a greater subset ID value than the required subset ID value within the root key field (either in the PCB key feedback area or in the I/O area). End of Product-Sensitive Programming Interface

Database administration
This section describes database administration. It includes the following topics: v Specifying the relative amount of space to each subset v Converting databases to HDAM databases randomized with Sequential Subset Randomizer v Monitoring the database

Specifying the relative amount of space to each subset

Database administrators must define how much space should be allocated to each subset. The amount of space to be allocated to each subset is specified as a relative amount of space. It can be expressed as follows: v The number of database roots within the subset

374

Users Guide

v The total length of all database records within the subset v One of the above two values expressed as the percentage of the database totals Database administrators can determine the relative amount of space to be allocated to each subset by activating the SS-STATS routine during sequential processing, or unloading of the whole database. The SS-STATS will show for each subset how much space is occupied by all the database segments of the subset that are stored in the first data set group of the HDAM database. These space statistics are expressed both as the number of bytes and as the percentage of the database totals. It is recommended that database administrators use the percentage for the length of database records (provided by the SS-STATS routine) for the allocation of space to each subset. The usage of percentage makes it easy to follow how and whether the database growth impacts the relative space allocation for each subset.

Converting databases to HDAM databases randomized with Sequential Subset Randomizer

Converting existing databases into the databases randomized with Sequential Subset Randomizer requires a special database reorganization. Note: If the database is involved in logical relationships or secondary relationships, IMS may require the execution of additional reorganization utilities (such as the IMS Database Prereorganization utility, the IMS Database Scan utility, the IMS Database Prefix Resolution utility, and so on) during the database reorganization. The execution of these utilities is not mentioned in this guide, since their execution is a standard IMS activity.

Converting from a database randomized with DFSHDC40

Converting an existing DFSHDC40-HDAM database into an HDAM database randomized with Sequential Subset Randomizer requires the following steps: 1. Generate a temporary Sequential Subset Randomizer. For this temporary Sequential Subset Randomizer, the database administrator does not need to define accurately how much space should be allocated to each subset. However, all other specifications need to be accurate. Note that at this time the DBDGEN should not be changed. This temporary Sequential Subset Randomizer is required so that the SS-STATS routine produces statistics for each subset. The SS-STATS routine finds the description of all subsets (including the values of the subset IDs) in the tables of the temporary Sequential Subset Randomizer to make statistics. 2. Unload the database using FABHURG1 or FABHFSU with the SSSTATS control statement specified (see Figure 82 on page 372 for an example). The database unload will produce the following: v An unloaded database which will be used as input for the reload. v Statistics that describe how much space should be allocated to each subset. These statistics should be used for a second, definitive SSRGEN which will be used during the reload process. It is recommended that you activate the Database Tuning Statistics during this database unload. (See Chapter 10, Using Database Tuning Statistics, on page 167.) The Database Tuning Statistics will show whether the database is well organized and whether the current randomizing is efficient. If the current randomizing is inefficient, the database administrator can take corrective actions before reloading the database. For example, if the root addressable area is too
Chapter 24. Related user tasks

375

crowded, the database administrator can increase the size of the root addressable area. The Database Tuning Statistics can also be compared with the Database Tuning Statistics created at a later time, when the database is randomized with Sequential Subset Randomizer. This can be used to see whether the Sequential Subset randomizing is as efficient as DFSHDC40 randomizing. 3. Generate the final version of Sequential Subset Randomizer. For this second Sequential Subset Randomizer, the database administrator should provide accurate specifications about the relative amount of space to be allocated to each subset. The relative amount of space to be allocated to each subset can be found in the SS-STATS statistics in the previous database unload. If the database administrator knows in advance that some subsets will eventually incur an overproportional increase in data volume, the data administrator can use this knowledge in order to increase the relative amount of space allocated to that subset. This may avoid a later adjustment of Sequential Subset Randomizer tables and an associated database reorganization. 4. Change the DBD Source statements in order to specify the name of the generated Sequential Subset Randomizer as the randomizer. This is a good time to review the current randomizing parameters and make adjustments with existing Database Tuning Statistics or other statistics if necessary. You can review the number of CIs/blocks in the root addressable area, the number of RAPs per CI/block, the CI/block size, the bytes limit, the scan parameter, and the free space specifications. Then the DBDGEN must be performed and the ACBGEN should be performed if necessary. 5. Create sorted input for the database reload. For small databases with less than 10,000 roots, this step is not necessary. For large databases, the input to the reload should be provided in the correct RAP sequence of the new database in order to complete the reload in a reasonable amount of time. For conversions from DFSHDC40 to Sequential Subset Randomizer, the correct sequence for the reload can be created without lengthy sort by executing the FABIUNLS utility (see Figure 77 on page 364 for an example). The FABIUNLS utility splits the unloaded data set into multiple data sets so that one subset becomes one data set. Therefore, the input to the reload will consist of a concatenation of the multiple output data sets of FABIUNLS. 6. Reload the database with the new or modified DBD using Sequential Subset Randomizer. 7. Obtain Database Tuning Statistics to check whether the quality of the randomizing is appropriate. This can be done by unloading a database, activating the Database Tuning Statistics for this unload, and setting the output of the unload to dummy.

Converting from a database randomized with other randomizers

The procedure for converting from other randomizers to Sequential Subset Randomizer is the same as for converting from DFSHDC40. However, step 5 should be done not with the FABIUNLS utility, but with the Physical Sequence Sort for Reload (PSSR) utility of High Performance Load or an equivalent program. The DBD created during the DBDGEN of step 4 should be used for PSSR. For details, refer to the IMS High Performance Load for z/OS Users Guide. Remember that sorting a large number of database records can be time-consuming.

376

Users Guide

Converting from a HISAM or HIDAM

The procedure for converting from a HISAM or HIDAM to Sequential Subset Randomizer is the same as for converting from DFSHDC40. However, step 5 on page 376 should be done not with the FABIUNLS utility, but with the PSSR utility or an equivalent program. The DBD created during the DBDGEN of step 4 on page 376 should be used for PSSR. For details, refer to the IMS High Performance Load for z/OS Users Guide. Remember that sorting a large number of database records can be time-consuming. After conversion from an HISAM or HIDAM, the database records can no longer be retrieved any more in the logical sequence of the root key unless the database administrator defines a secondary index for this purpose. The sequential retrieval of a large number of database records through a secondary index is usually not efficient.

Monitoring the database

An HDAM database randomized with Sequential Subset Randomizer needs to be monitored like any other HDAM database. Database Tuning Statistics should be used to monitor periodically the quality of the randomizing and the need to reorganize a database. For example, if the Database Tuning Statistics for April show that the random retrieval of a database record requires as an average 1.23 I/Os and the Database Tuning Statistics from June of the same year show that this figure has increased to 1.89 I/Os, it would be time to reorganize. As a part of this usual database monitoring, database administrators should observe how the space is occupied by the database records of each subset. This is done by activating the SS-STATS routine during the sequential processing or unloading of the whole database. If the Database Tuning Statistics show a need to reorganize a database, and a database administrator decides to do so, the SS-STATS statistics should be considered in deciding whether also to change the relative amount of space allocated to each subset and regenerate the Sequential Subset Randomizer.

Chapter 24. Related user tasks

377

378

Users Guide

Part 4. Messages and codes

Chapter 25. Abend codes . . . . . . . . . . Abend code U4013 . . . . . . . . . . . . . Trapping abends issued by application programs . . OS PL/I V2 programs . . . . . . . . . . . COBOL or PL/I programs running under Language . . . . . . . . . . . . . . . . . . . . Environment . . . . . . . . . . . . . . . . . . . . . . . . . 381 381 381 381 381

Chapter 26. HSSR snaps . . . . . . . . . . . . . . . . . . . . 383 Chapter 27. Return codes . . . . . . FABHURG1 return codes . . . . . . FABHFSU return codes . . . . . . . FABHPSFS return codes . . . . . . . FABHBSIM and FABHTEST return codes. JCL for IMS HD Reorganization Unload to Chapter 28. Messages Message format . . . Message variables . . FABH messages . . FABI messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . run FABHURG1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 385 385 387 387 387 389 389 389 390 467

Copyright IBM Corp. 2000, 2007

379

380

Users Guide

Chapter 25. Abend codes

This chapter describes the abend codes. Topics: v Abend code U4013 v Trapping abends issued by application programs

Abend code U4013

High Performance Unload uses only one abend code, U4013. A message identifying the problem is always written before this abend code is issued.

Trapping abends issued by application programs

If your HSSR application program is written in COBOL or PL/I language, you can request that most abends that can happen during the processing of your application program be trapped (in other words, you can request that abends be intercepted and hurdled by the high-level language software, and that your application program get back control after an abend). Abends are usually trapped in one of the following ways: v By using the run-time option STAE (for OS PL/I V2 programs) v By using the run-time option TRAP(ON) (for COBOL or PL/I programs running under Language Environment) If you trap abends for your application programs, you will perhaps wish to exclude abends issued by HSSR Engine. This is because the purpose of the ABEND macros that HSSR Engine issues is to result in abendsnot to return to the application program (in this respect, HSSR Engine is similar to IMS).

OS PL/I V2 programs
If you wish to exclude abends in HSSR Engine from trapping for OS PL/I V2 programs, update the IBMBXITA Assembler user exit to include the user abend code of High Performance Unload in the list of user-abend codes that should be percolated. For detailed descriptions of IBMBXITA, refer to OS PL/I V2 Programming Guide, SC26-4307.

COBOL or PL/I programs running under Language Environment

If you wish to exclude abends in HSSR Engine from the trapping for COBOL or PL/I programs running under Language Environment (LE), update the LEs CEEDOPT Assembler module that establishes installation defaults. With the ABPERC= keyword, include the user abend code of High Performance Unload in the list of abend codes that should be percolated. For detailed descriptions of CEEDOPT and of the ABPERC run-time option, refer to z/OS Language Environment Programming Guide. As the Programming Guide explains, you can also request percolation of the abend code of HSSR Engine in: v The CEEUOPT Assembler module v The Assembler user exit CEEBXITA

| |

Copyright IBM Corp. 2000, 2007

381

382

Users Guide

Chapter 26. HSSR snaps

If an unexpected condition is detected while the HSSR PCBs are being initialized, the following actions are taken: v An error message is issued. v A snap to the HSSRSNAP data set is written. v The initialization process is ended and "falls back" to DL/I. (The application program will work with DL/I PCBs, and all calls are processed by DL/I modules.) If the HSSRSNAP DD statement is not specified, High Performance Unload ends abnormally instead of falling back to DL/I. If you do not need the snap but need the fallback processing, supply the following DD statement:
//HSSRSNAP DD DUMMY

Copyright IBM Corp. 2000, 2007

383

384

Users Guide

Chapter 27. Return codes

In this chapter, the return codes issued by the following utilities are summarized: v FABHURG1 v v v v FABHFSU FABHPSFS FABHBSIM FABHTEST

You can change the return codes, except for FABHPSFS, by using FABHRCEX, the Return Code Edit exit routine. For details, see Return Code Edit exit (FABHRCEX) on page 315. Topics: v v v v v FABHURG1 return codes FABHFSU return codes FABHPSFS return codes on page 387 FABHBSIM and FABHTEST return codes on page 387 JCL for IMS HD Reorganization Unload to run FABHURG1 on page 387

FABHURG1 return codes

The FABHURG1 utility issues a return code that is the logical sum of the following return codes: Code 00 01 Meaning Successful completion. One or both of the following conditions were detected: v Some segment types are insensitive. v No segment was retrieved from the database. Some segments have been skipped in accordance with the logic of a users exit routine. A sensitive logical child segment type has a logical parents concatenated key defined as "virtual," but the BLDLPCK control statement is not specified. A database error was detected, and the SKERROR option might have skipped the unloading of one or more database segments.

02 04

08

FABHFSU return codes

FABHFSU issues a return code that is the logical sum of the following return codes: Code 00 01 04 Meaning Successful completion. No segment was retrieved from the database. When you are running in the PSF mode, no segment was retrieved in the current PSF phase. A sequence error was detected in the standard mode. In the PSF mode, this return code means that all the PSF phases were completed, but one or more sequence errors were detected.

Copyright IBM Corp. 2000, 2007

385

08

In the PSF mode, the current PSF phase was completed normally, but other phases are incomplete.

386

Users Guide

FABHPSFS return codes

FABHPSFS issues a return code that is the logical sum of the following return codes: Code 00 01 04 08 Meaning Successful completion. No errors were detected except the STATUS option. No segment was retrieved in all PSF phases. Successful completion of a STATUS option run. Any of the following conditions were detected: a b c d One or more scan phases were not completed. Preceding FABHPSFS has been completed successfully, but the RERUN option was not specified. The FORCE option was specified, but no complete phases were found. Inconsistent DEC options were specified in the scan phases.

FABHBSIM and FABHTEST return codes

FABHBSIM and FABHTEST issue the following code: Code 00 Meaning Successful completion.

JCL for IMS HD Reorganization Unload to run FABHURG1

If FABHURG1 is run by using a JCL that is described in Chapter 14, Using JCL for IMS HD Reorganization Unload to run FABHURG1, on page 269, the FABHURG1 utility issues one of the following return codes: Code 00 04 Meaning Successful completion. Any of the following conditions were detected: 0001 0002 0004 No segment was retrieved from the database. Some segments have been skipped in accordance with the logic of a users exit routine. A sensitive logical child segment type has a logical parents concatenated key defined as virtual., but the BLDLPCK control statement is not specified. A database error was detected, and the SKERROR option might have skipped the unloading of one or more database segments.

0008

HSSR Engine ends abnormally with the user completion code of 4013 for errors to which IMS HD Reorganization Unload utility would return the return code of 8.

Chapter 27. Return codes

387

388

Users Guide

Chapter 28. Messages

This chapter describes the messages issued by High Performance Unload. Topics: v Message format v Message variables

Message format
All the messages have the following format:
FABHnnnnx text

Where: nnnn x Is a four-digit message identification number. Indicates the severity of the message, as follows: I W E Information message Warning message Error message

Message variables
In the message text, you will see lowercase variable names (such as xxx...). The variable names take on values when the message appears and may represent such things as: v The name of a data set v A DD name v A DBD name v A status code v A command keyword v A name or value provided by the user v Text generated by HSSR Engine when an I/O error has occurred The keyword "HSSR" in message texts and in the explanation, system action, and programmer response represents the HSSR Engine unless otherwise stated.

Copyright IBM Corp. 2000, 2007

389

FABH0001E FABH0017W

FABH messages
FABH0001E INVALID CARD TYPE Explanation: A CAB control statement with an incorrect statement type was detected in the HSSRCABP data set. System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. Problem determination: CAB control statements must begin in column 1 with a keyword defining the statement type. FABH0002E INVALID NUMERIC FIELD Explanation: A CAB control statement contains a nonnumeric byte in a field that should be numeric. System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0003E CARD TYPE NOT FOLLOWED BY VALUE Explanation: The statement type on a CAB control statement is not immediately followed by a single blank and the required parameter value. System action: HSSR Engine ends abnormally. Programmer response: Correct the incorrect control statement. FABH0004E PARAMETER IS TOO LONG Explanation: A CAB control statement contains a parameter field that is too long. System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0005E FIRST CARD SHOULD BE A "CABDD" CARD Explanation: The first statement in the HSSRCABP data set is not a CABDD control statement. System action: HSSR Engine ends abnormally. Programmer response: Set the statements of the HSSRCABP data set into the correct sequence. (Each group of CAB control statements must begin with a CABDD control statement.) FABH0011E RANSIZE IS TOO LOW; MINIMUM IS 2 CABDD=xxxxxxxx Explanation: The value of a RANSIZE control statement is lower than the acceptable minimum. xxxxxxxx represents the keyword that was specified on FABH0013E NBRSRAN IS TOO LOW; MINIMUM IS 3 CABDD=xxxxxxxx Explanation: The value of a NBRSRAN control statement is lower than the acceptable minimum. xxxxxxxx represents the keyword that was specified on the CABDD control statement (that is, *ALL, *HD, *HS, or ddname). System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0015E NBRDRAN IS TOO LOW; MINIMUM IS 2 CABDD=xxxxxxxx Explanation: The value of a NBRDRAN control statement is lower than the acceptable minimum. xxxxxxxx represents the keyword that was specified on the CABDD control statement (that is, *ALL, *HD, *HS, or ddname). System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0016E NBRDBUF IS TOO LOW; MINIMUM IS 2 CABDD=xxxxxxxx Explanation: The value of a NBRDBUF control statement is lower than the acceptable minimum. xxxxxxxx represents the keyword that was specified on the CABDD control statement (that is, *ALL, *HD, *HS, or ddname). System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0017W DDNAME NOT FOUND CABDD=ddname Explanation: The ddname specified on a CABDD FABH0012E RANSIZE IS TOO HIGH; MAXIMUM IS 255 CABDD=xxxxxxxx Explanation: The value of a RANSIZE control statement is higher than the acceptable maximum. xxxxxxxx represents the keyword that was specified on the CABDD control statement (that is, *ALL, *HD, *HS, or ddname). System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. the CABDD control statement (that is, *ALL, *HD, *HS, or ddname). System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement.

390

Users Guide

FABH0018E FABH0026E
statement was not found within any DBD referred to by HSSR PCBs. System action: HSSR Engine ignores the CAB control statements that begin with this CABDD statement. Programmer response: Correct the CABDD statement. FABH0018E SPECIFY EITHER "YES" OR "NO" Explanation: HSSR Engine detected an incorrect CAB control statement. System action: HSSR Engine ends abnormally. Programmer response: Correct the CAB control statement. Problem determination: The CAB control statement does not allow a specification other than YES or NO. FABH0019E INVALID OVERFLOW SPECIFICATION Explanation: HSSR Engine detected an incorrect OVERFLOW CAB control statement. System action: HSSR Engine ends abnormally. Programmer response: Correct the CAB control statement. FABH0020E OPEN OF HSSRCABP HAS FAILED Explanation: HSSR Engine could not open the HSSRCABP data set. System action: HSSR Engine ends abnormally. Programmer response: Check whether MVS issued an additional message describing the type of error with more details. Correct the error. FABH0021E NOGO SET BECAUSE OF ERRORS ON CAB CONTROL STATEMENTS Explanation: CAB control statements in the HSSRCABP data set contain errors. The errors are described in detail in other error messages issued by HSSR Engine. System action: HSSR Engine ends abnormally. Programmer response: Correct the errors. FABH0022E NBRSRAN IS TOO HIGH; MAXIMUM IS 9999 CABDD=xxxxxxxx Explanation: The value of a NBRSRAN control statement exceeds the acceptable maximum. xxxxxxxx represents the keyword that was specified on the CABDD control statement (that is, *ALL, *HD, *HS or ddname). System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0023E NBRDBUF IS TOO HIGH; MAXIMUM IS 255 CABDD=xxxxxxxx Explanation: The value of a NBRDBUF control statement exceeds the acceptable maximum. xxxxxxxx represents the keyword that was specified on the CABDD control statement (that is, *ALL, *HD, *HS or ddname). System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0024E REQUESTED BUFFER TOO LARGE; DDNAME=ddname Explanation: The requested size of the buffer for BB or CAB sequential I/O exceeds the acceptable maximum of X'7FFFFFFF' (2,147,483,647) bytes. ddname represents the DD name of the data set for which the storage for buffer was requested at the time of error. System action: HSSR Engine ends abnormally. Programmer response: For CAB, check the RANSIZE and NBRSRAN control statement in the HSSRCABP data set; for BB, check the BUF control statement in the HSSROPT data set. Correct these control statements so that the total amount of buffers requested does not exceed the maximum value of X'7FFFFFFF'. Note that HSSR buffer handler requests the system to acquire the following amount of bytes as the read buffer for ddname:
Buffering Storage size to be requested Type ----------- -------------------------------------------CAB (Block Size of ddname) / (CI Size) x (RANSIZE x (NBRSRAN + 1)) BB (Block Size of ddname) / (CI Size) x BUF

FABH0025E THE SECOND OPERAND OF THE PARTPROC STATEMENT MUST BE EITHER 'S' OR 'R' (DBD: dbdname) Explanation: The second operand of a PARTPROC statement must be either 'S' or 'R'. The string dbdname shows the first operand of the PARTPROC statement in error. System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0026E THE LENGTH OF THE THIRD OPERAND OF THE PARTPROC STATEMENT MUST BE LESS THAN FIVE (DBD: dbdname) Explanation: The length of the third operand of the PARTPROC control statement in HSSRCABP DD is five bytes or more. The length must be less than five bytes. System action: HSSR Engine ends abnormally.
Chapter 28. Messages

391

FABH0027W FABH0034E
Programmer response: Correct the error and rerun the job. FABH0027W THE DBD SPECIFIED ON THE PARTPROC STATEMENT IS NOT FOUND OR IS NOT FOR HALDB (DBD: dbdname) Explanation: The DBD dbdname specified in a PARTPROC control statement is neither a DBD that is referred to from an HSSR PCB, nor a DBD for a HALDB. System action: The PARTPROC statement is ignored, and the processing continues. Programmer response: Check whether the DBD name specified is correct. If not, specify the correct DBD name or remove the statement. FABH0028E INCONSISTENT BUFFER HANDLERS ARE SPECIFIED FOR DSGROUP n OF HALDB dbdname Explanation: Different buffer handlers are specified for partition data sets that belong to the same data set group n. System action: HSSR Engine ends abnormally. Programmer response: Correct the CABDD control statement(s) so that either CAB or BB can be used for all data sets that belong to the same data set group. FABH0029E SYNTAX ERROR IN A PARTPROC STATEMENT: reason Explanation: There is a syntax error in a PARTPROC statement specified in the HSSRCABP data set. The string reason shows the reason for the error. System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0030E: THE THIRD OPERAND OF A PARTPROC STATEMENT IS NOT A NUMERIC (DBD: dbdname) Explanation: The value specified as the third operand for a PARTPROC control statement is not a numeric. The string dbdname shows the first operand of the PARTPROC statement in error. System action: HSSR Engine ends abnormally. Programmer response: Correct the control statement. FABH0031E DDNAME=ddname; DATA REQUEST OUTSIDE OF DATA SET LIMITS Explanation: The CAB buffer handler has received a data request for an OSAM block number or ESDS CI number that is not within the extents of the data set (indicated by ddname). System action: HSSR Engine ends abnormally. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the database processed by HSSR was being updated at that time. FABH0032E BUFFER HANDLER LOGIC ERROR FABH0033E BUFFER HANDLER LOGIC ERROR Explanation: The CAB buffer handler detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See the Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0034E REQUESTED STORAGE FOR DBD=dbdname NOT AVAILABLE WITHIN THE REGION Explanation: The total size of the requested buffers exceeds the acceptable maximum that can be acquired in the region. dbdname indicates the name of the DBD of the database for which the buffer was requested at the time of error. System action: HSSR Engine ends abnormally. Programmer response: Check BUF control statement in the HSSROPT data set and RANSIZE, NBRSRAN and NBRDBUF control statements in the HSSRCABP data set that are specified for the DBD dbdname. Correct these control statements so that the total storage size for the buffers requested for dbdname does not exceed the allowable maximum that can be acquired in the region. Otherwise, change the REGION parameter in the JCL for the job so that the requested storage for the buffer can be acquired. The total size of the buffers for dbdname is calculated by summing up the required size for each DD that refers to dbdname, using the following formula:
Buffering Type Storage size to be requested used for the DD ----------------- -------------------------------------BB (Block or CI size of the DD) x BUF CAB (Block or CI size of the DD) x (RANSIZE x (NBRSRAN + 1) + NBRDBUF)

392

Users Guide

FABH0035E FABH0045E
FABH0035E UNSUPPORTED LEVEL OF IMS IS BEING USED: xxx IMS LEVEL OF THIS RUN Explanation: You are running an IMS batch region controller (DFSRRC00) that is not supported by High Performance Unload (xxx represents the IMS level). System action: HSSR Engine ends abnormally. Programmer response: Run the job with the correct version of IMS. FABH0036E THIRD OPERAND FOR PARTPROC STATEMENT IS NOT ALLOWED IF THE SECOND OPERAND IS 'S' (DBD: dbdname) Explanation: The third operand of a PARTPROC control statement for the database dbdname is specified although the second operand is 'S'. System action: HSSR Engine ends abnormally. Programmer response: Remove the third operand. FABH0037E INCONSISTENT OVERFLOW BUFFERING OPTIONS FOR PHDAM dbdname Explanation: Inconsistent overflow buffering options are specified for the overflow area of each partition of the PHDAM database dbdname. System action: HSSR Engine ends abnormally. Programmer response: Correct OVERFLOW control statements so that the same overflow buffering optionsCAB, SHR, or BBcan be used for all overflow areas. FABH0038E INCONSISTENT PAGEFIX OPTIONS FOR DATA SETS OF DSGROUP n OF HALDB dbdname Explanation: Different pagefix options are specified for partition data sets that belong to the same data set group n. System action: HSSR Engine ends abnormally. Programmer response: Specify the same keyword, either YES or NO, for the pagefix option of BUFFERS control statement so that the same pagefix options can be specified for all partitions. FABH0041E VSAM POINT ERROR DURING SEQUENTIAL ESDS I/O Explanation: VSAM returned an unexpected code to the CAB buffer handler during the execution of a POINT macro. System action: HSSR Engine ends abnormally. FABH0044W WARNING: NUMBER OF VSAM BUFFERS NOT O.K. Explanation: Normally, the CAB buffer handler specifies how many buffers should be used by VSAM. However, CAB detected that its specifications could not be honored by VSAM. System action: HSSR Engine continues processing. However, the performance will suffer. Programmer response: Remove any BUFND, BUFSP, or STRNO specifications from the JCL. Remove through IDCAMS BUFFERSPACE specifications for the ESDS from the catalog. Problem determination: Possible reasons are specifications of VSAM buffering options on JCL (BUFND, BUFSP, STRNO) or through IDCAMS (buffer space). Create a complete catalog listing for the ESDS. FABH0045E VSAM LOGICAL ERROR AFTER POINT MACRO Explanation: VSAM returned an unexpected logical error code to the CAB buffer handler during the execution of a POINT macro. System action: HSSR Engine ends abnormally. Programmer response: Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. Problem determination: If the cause is not clear, collect the dump and contact IBM Software Support. Programmer response: Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. Problem determination: If the cause is not clear, collect the dump and contact IBM Software Support. FABH0042E VSAM GET ERROR DURING SEQUENTIAL ESDS I/O Explanation: VSAM returned an unexpected code to the CAB buffer handler during the execution of a GET macro. System action: HSSR Engine ends abnormally. Programmer response: Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. Problem determination: If the cause is not clear, collect the dump and contact IBM Software Support.

Chapter 28. Messages

393

FABH0046E FABH0057W
FABH0046E VSAM PHYSICAL ERROR Explanation: VSAM returned an unexpected physical error code to the CAB buffer handler. System action: HSSR Engine ends abnormally. Programmer response: Check for I/O error messages issued by VSAM. Try to resolve the physical I/O error. FABH0047E SHOULD NOT OCCUR ERROR AFTER VSAM CHECK MACRO FABH0048E SHOULD NOT OCCUR ERROR AFTER VSAM CHECK MACRO Explanation: VSAM returned an unexpected error code to the CAB buffer handler during the execution of a CHECK macro. System action: HSSR Engine ends abnormally. Programmer response: Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. Problem determination: If the cause is not clear, collect the dump and contact IBM Software Support. FABH0049E VSAM MACRO GENCB BLOCK=RPL FAILED Explanation: VSAM returned an unexpected code to the CAB buffer handler during the execution of a GENCB BLOCK=RPL macro. System action: HSSR Engine ends abnormally. Programmer response: As a temporary bypass, the Basic Buffer Handler can be used instead of CAB. Problem determination: Check whether enough virtual storage was available within the region (MVS). FABH0050E VSAM MACRO MODCB RPL=... FAILED Explanation: VSAM returned an unexpected code to the CAB buffer handler during the execution of a MODCB RPL macro. System action: HSSR Engine ends abnormally. Programmer response: As a temporary bypass, the Basic Buffer Handler can be used instead of CAB. Problem determination: Check whether enough virtual storage was available within the region (MVS). FABH0053E RANSIZE SHOULD BE THE SAME FOR ALL PCBS REFERENCING THE SAME ESDS Explanation: Multiple HSSR PCBs that refer to the same database were specified to be buffered by CAB. This situation is not supported by CAB. FABH0054E NUMBER OF VSAM BUFFERS NOT OK., PLHBFRNO=xxx Explanation: The indicated number of CIs to be read in one sequential read could not be followed by VSAM. The number was specified by the RANSIZE control statement. System action: HSSR Engine ends abnormally. Programmer response: Remove any BUFND, BUFSP, or STRNO specifications from the DD statement for the database. If BUFFERSPACE is specified in the definition of the data set, remove it for the ESDS. Disable the use of VSAM optimization tool if any is used for the job. If the VSAM ESDS attributes cannot be changed, specify the value xxx, shown in the message text, for the RANSIZE statement. However, you may not obtain the maximum buffering performance if the recommended value from PLHBFRNO is much greater or much lower than the users calculated optimum value, if HSSR buffer handler assumes that BUFND, BUFSP, and STRNO are not specified in the JCL, or if BUFFERSPACE is not used when the data set is defined. FABH0055W SPECIFIED NUMBER OF BUFFERS IN A SEQ_BUF FOR DDNAME=ddname NOT OPTIMAL FOR ESDS FABH0056W NUMBER OF BUFFERS IN A SEQ_BUF xxx CHANGE TO yyy Explanation: The number (xxx) of CIs to be read by one sequential read for the data set identified by ddname is too large. The number xxx is the one that was specified by the RANSIZE control statement. The ESDS cannot chain CCWs for that number of CIs in a single start I/O. The maximum number of CIs (yyy) that can be read depends on the CI size and is displayed in message FABH0056W. System action: The processing continues with the maximum number (yyy) of CIs. Programmer response: Specify the value yyy indicated in message FABH0056W for RANSIZE. System action: HSSR Engine ends abnormally. Programmer response: Use the OCCURRENCE control statement to make sure that no more than one HSSR PCB per database is buffered by CAB.

| | | | | |

FABH0057W NUMBER OF VSAM BUFFERS IS OVERRIDDEN: PLHBFRNO=xxx Explanation: Normally, the CAB buffer handler specifies the number of VSAM buffers, however, CAB detected that its specifications could not be used by VSAM.

394

Users Guide

FABH0059E FABH0067E
| System action: HSSR Engine continues processing. | However, the performance will decrease. | | | | | |
Programmer response: If you want to use the CAB buffering optimization, remove any BUFND, BUFSP, or STRNO specifications from the JCL, and remove the IDCAMS BUFFERSPACE specifications for the ESDS from the catalog. If the system-managed buffering is activated in the SMS definition, deactivate it. FABH0059E TRACK NUMBER EXCEEDS 65535 Explanation: The database data set is larger than 65535 tracks on a volume. To read such a large format data set, the level of z/OS must be version 1 release 7 or later. System action: HSSR Engine ends abnormally. Programmer response: Check the level of z/OS. FABH0060E DEVTYPE MACRO FAILED ON DDNAME: ddname RC=rc Explanation: An error was returned by the DEVTYPE macro to get information about the device associated with the DD name ddname. The value rc shows the return code. System action: HSSR Engine issues a user abend. Programmer response: Check whether the DD statement for the specified DD name points to the correct data set. Correct the error, and rerun the job. FABH0061E OPEN FAILED FOR DDNAME: ddname Explanation: An attempt to open the data set identified by ddname failed. System action: HSSR Engine issues a user abend. Programmer response: Correct the error, and rerun the job. Problem determination: Make sure that the DD statement associated with ddname is the correct data set. FABH0062E BLDL MACRO FAILED FOR MEMBER mbrname IN LIBRARY ddname (RC=rc,RSN=rsn) Explanation: The BLDL macro failed for member mbrname in the library that has the DD name ddname. The return code from the macro call was rc, and the reason code was rsn. System action: HSSR Engine issues a user abend. Programmer response: This is likely an internal system error. Contact IBM Software Support. FABH0067E DD: ddname INFORMATION OF DB: dbdname IS NOT FOUND IN DFSMDA MEMBER Explanation: The DD information associated with the DD ddname is not found in the DFSMDA member.
Chapter 28. Messages

FABH0063E BSAM CLOSE HAS FAILED Explanation: The CLOSE macro issued by the CAB buffer handler failed. System action: HSSR Engine ends abnormally. Programmer response: Check whether enough virtual storage was available in the address space. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0064E HDCB NOT FOUND Explanation: HSSR Engine detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: This is likely to be an internal systems error of some kind. Collect the dump and contact IBM Software Support. FABH0065E DDNAME SPECIFIED IN DBD (dbdname) DOES NOT HAVE A CORRESPONDING MATCH WITH A DD STATEMENT Explanation: During the allocation of a database data set, neither an MDA member corresponding to the specified DBD nor a DD statement for the DD name specified in the DBD could be found. System action: HSSR Engine issues a user abend. Programmer response: Either add a DD statement for the database data set or specify (on the IMSDALIB or STEPLIB/JOBLIB) a PDS data set that contains an MDA member for the DBD. FABH0066E INCORRECT DFSMDA MEMBER: xxxxxxxx Explanation: The module xxxxxxxx was loaded as a DFSMDA member, but it does not have a correct DFSMDA format. The eye-catcher MDA is not found in the module. System action: HSSR Engine issues a user abend. Programmer response: Make sure that the correct DFSMDA members exist in the IMSDALIB concatenation or STEPLIB/JOBLIB concatenation. Correct the error, and rerun the job. Problem determination: If a library that contains a member with the name xxxxxxxx is specified in the higher order of the STEPLIB or JOBLIB concatenation, this problem can occur.

395

FABH0068E FABH0083E
HSSR Engine cannot perform the dynamic allocation for the ddname of DB: dbdname. System action: HSSR Engine issues a user abend. Programmer response: Make sure that the DFSMDA member dbdname contains the appropriate information about the DB dbdname. Correct the error, and rerun the job. FABH0068E DYNAMIC ALLOCATION FAILURE OCCURRED FOR DB: dbdname DD: ddname RC=xx RSN=yyyy Explanation: An attempt at dynamic allocation for ddname of dbdname failed. xx is the return code in register 15 and yyyy is the associated hexadecimal reason code from the SVC99 routine. System action: HSSR Engine issues a user abend. Programmer response: Correct the error, and rerun the job. Problem determination: The return code and reason code from the SVC99 routine are explained inMVS Programming: Authorized Assembler Services Guide. FABH0070E UNEXPECTED DEB LAYOUT FABH0071E UNEXPECTED DEB LAYOUT FABH0072E UNEXPECTED DEB LAYOUT Explanation: The MVS DEB control block used by OSAM has an unexpected layout. System action: HSSR Engine ends abnormally. Programmer response: This is likely to be an internal systems error of some kind. Collect the dump and contact IBM Software Support. FABH0073E UNSUCCESSFUL BSAM OPEN BY CAB BUFFER HANDLER Explanation: The CAB buffer handler could not OPEN an OSAM data set with BSAM. System action: HSSR Engine ends abnormally. Programmer response: Check for an error message issued by MVS or by access method service. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0074E INVALID ENTRY INTO BSAM EOV EXIT ROUTINE Explanation: The CAB buffer handler detected an unexpected entry in its own EOV exit routine, used in processing an OSAM data set with BSAM. System action: HSSR Engine ends abnormally. FABH0081I I/O WILL BE PERFORMED Explanation: A FABHBSIM control statement requested that the buffer handler should not bypass database I/O operations. System action: The buffer handlers perform database I/O operations. Programmer response: None. FABH0082I BSIM NORMAL END OF PROCESSING Programmer response: This is likely to be an internal systems error of some kind. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0075E INVALID ENTRY INTO BSAM EODAD ROUTINE Explanation: The CAB buffer handler detected an unexpected entry into its own EODAD exit routine, used in processing an OSAM data set with BSAM. System action: HSSR Engine ends abnormally. Programmer response: This is likely to be an internal systems error of some kind. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0076E text Explanation: HSSR buffer handler encountered an I/O problem when using BSAM to read an OSAM data set. This message text contains bytes 51-127 of the SYNADAF message. System action: HSSR Engine ends abnormally. Programmer response: For this message, seeDFSMS/MVS Macro Instructions for Data Sets. Correct the errors. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct versions of DBDs, PSBs, and ACBs were used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred.

Explanation: Program FABHBSIM reached normal end of processing. System action: The processing continues. Programmer response: None. FABH0083E HSSR ENVIRONMENT IS NOT ESTABLISHED Explanation: The HSSR environment has not been properly established. The reason is probably that program FABHBSIM was not invoked by FABHDLI,

396

Users Guide

FABH0084E FABH0091W
FABHDBB, or FABHULU procedures (or by equivalent JCL). System action: FABHBSIM ends abnormally. Programmer response: Use the FABHDLI, FABHDBB, or FABHULU procedures, or correct the JCL. FABH0084E SYSUT1 COULD NOT BE OPENED Explanation: The SYSUT1 data set containing the buffer handler trace could not be opened. System action: Program FABHBSIM ends abnormally. Programmer response: Correct the JCL. FABH0085E INVALID RECORD TYPE IN SYSUT1 Explanation: Program FABHBSIM found an incorrect record type in the buffer handler trace data set. System action: FABHBSIM ends abnormally. Programmer response: Check whether the correct data set was defined on the SYSUT1 DD statement. FABH0086E PCB-NBR STORED IN SYSUT1 RECORD DOES NOT EXIST IN PSB Explanation: Each record of the SYSUT1 data set contains the number of the PCB that was being used during the traced buffer handler call. The recorded PCB-NBR does not exist in the PSB used for the FABHBSIM run. System action: Program FABHBSIM ends abnormally. Programmer response: Check whether the same PSB was used for the traced run and for the FABHBSIM run. Make sure that the PSB has not changed. FABH0087E PCB-NBR STORED IN SYSUT1 RECORD IS NOT THE NUMBER OF A HSSR PCB Explanation: Each record of the SYSUT1 data set contains the number of the PCB that was being used during the traced buffer handler call. The recorded PCB-NBR is not the number of a HSSR PCB. System action: Program FABHBSIM ends abnormally. Programmer response: Check whether the same PSB was used for the traced run and for the FABHBSIM run. Make sure that the PSB has not changed. FABH0088E BUFFER HANDLER CALL TYPE STORED IN SYSUT1 RECORD IS INVALID Explanation: Program FABHBSIM found an incorrect buffer handler call type in the buffer handler trace data set. System action: FABHBSIM ends abnormally. Programmer response: Check whether the correct data set was defined on the SYSUT1 DD statement. FABH0089E NOT NUMERIC FIELD ON SYSIN CARD Explanation: A FABHBSIM control statement on the SYSIN data set does not contain a numeric value. System action: Program FABHBSIM ends abnormally. Programmer response: Correct the control statement. FABH0090E INVALID HSSRPCB OR HSSRDBD STATEMENT IS SPECIFIED : xxxxx Explanation: The specified HSSRPCB or HSSRDBD control statement is not correct. The keyword "xxxxx" indicates the cause of the error: Keyword Description

NOT NUMERIC A nonnumeric character was specified for the operand of an HSSRPCB statement. TOO MANY PARAMETERS More than 500 pcbnum or dbdname were specified. TOO LARGE PCBNUM pcbnum larger than 500 was specified. MIXED SPECIFICATION Both HSSRPCB and HSSRDBD statements were specified. System action: HSSR Engine ends abnormally. Programmer response: Correct the error in the HSSRPCB or HSSRDBD control statement and rerun the job. FABH0091W UNABLE TO PROCESS THE FOLLOWING PCB AS AN HSSR PCB (REASON: rrrrrrrr) FABH0091W DBD=xxxxxxxx, PCB#=yyyy, PCBNAME=zzzzzzzz Explanation: The PCB that is specified as an HSSR PCB cannot be processed as an HSSR PCB. The string xxxxxxxx shows the name of the DBD that the PCB refers to; the number yyyy shows the PCB number in the PSB; and the string "zzzzzzzz" shows the label, if there is one, of the PCB assigned at PSBGEN. The string "rrrrrrrr" shows the reason for the error as follows: Reason Code IOPCB TPPCB Description The specified PCB is an I/O PCB. The specified PCB is an alternative PCB.
Chapter 28. Messages

397

FABH0092W FABH0106E
GSAMPCB PROCOPT The specified PCB is a GSAM PCB. The PROCOPT parameter on the PCB statement specifies an incorrect code or combination of codes. The codes you can use are G, O, N, T, R, A, P, and E. The specified PCB refers to the DBD that is specified on a DBDL1 control statement. The specified PSB is generated with PROCOPT=R, and the DBD referred by the PCB is generated with the data capture exit routine. The specified PCB does not exist. The specified PCB cannot be processed, for some reason other than the preceding. See the accompanying FABHxxxxx messages issued by HSSR Engine. FABH0101E //CARDIN FILE CONTAINS AN INVALID FSU CONTROL STATEMENT Explanation: Program FABHFSU detected a control statement with an incorrect control statement ID. System action: FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0102E OPEN-ERROR FOR //CARDIN OR //PRNTOUT Explanation: Program FABHFSU cannot open the CARDIN or PRINTOUT data set. System action: FABHFSU ends abnormally. Programmer response: Check for additional error messages issued by the access method. Correct the error. FABH0103E 'DBD' OR 'PSC' CONTROL CARD MISSING IN //CARDIN Explanation: The CARDIN data set should contain either a DBD or a PSC control statement. System action: Program FABHFSU ends abnormally. Programmer response: Provide the required control statement. FABH0104E INVALID NBR OF 'PSB' CONTROL-STATEMENTS IN //CARDIN Explanation: The CARDIN data set should contain 1, 2, or 3 PSB control statements. System action: Program FABHFSU ends abnormally. Programmer response: Provide a correct number of PSB control statements. FABH0105E NOGO-SWITCH SET BECAUSE OF PREVIOUS ERROR IN //CARDIN CONTROL STATEMENTS Explanation: Program FABHFSU detected an error, which is described in a previous error message. System action: FABHFSU ends abnormally. Programmer response: Correct the error. FABH0106E INVALID 'SEQUENCE CHECK OPTION' ON 'DBD' CARD IN //CARDIN Explanation: A DBD control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement.

DBDL1

USREXIT

NOTFOUND OTHER

System action: The processing continues. If the PCB can be processed as a DL/I PCB, it is treated as a DL/I PCB, and all HSSR calls to the PCB are transferred to the DL/I call interface modules. Programmer response: If the database calls should be processed by HSSR Engine, check whether the specified PCB is correct. Otherwise, ignore this message and continue processing by using the DL/I module. You should check the HSSRPCB and HSSRDBD control statements or the KEYLEN value for the PCB. FABH0092W PROCOPT=R IS SPECIFIED ON THE FOLLOWING HSSR PCB: FABH0092W DBD=xxxxxxxx, PCB#=yyyy, PCBNAME=zzzzzzzz Explanation: PROCOPT=R is specified on the PCB specified by the PCB control statement or the PCBNAME control statement in the HPSIN data set of IPR Unload utility. The string xxxxxxxx shows the name of the DBD that the PCB refers to; the number yyyy shows the PCB number in the PSB; and the string zzzzzzzz shows the label, if there is one, of the PCB assigned at PSBGEN. System action: HSSR Engine continues processing. If an HSSR REPL call is issued for the PCB, HSSR Engine ends abnormally. Programmer response: You can ignore the message if you do not issue any HSSR REPL call, but it is recommended that you change the PROCOPT.

398

Users Guide

FABH0107E FABH0118E
FABH0107E INVALID 'SEQUENCE ERROR OPTION' ON 'DBD' CARD IN //CARDIN Explanation: A DBD control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0108E INVALID 'SEQUENCE ERROR PRINT OPTION' ON 'DBD' CARD IN //CARDIN Explanation: A DBD control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0109E 'SEQUENCE ERROR THRESHOLD' FIELD ON 'DBD' CARD IS NOT NUMERIC Explanation: A DBD control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0110E MULTIPLE 'DBD' CONTROL STATEMENTS NOT ALLOWED IN //CARDIN Explanation: More than one DBD control statement was detected. Only one DBD control statement is allowed in the CARDIN data set. System action: Program FABHFSU ends abnormally. Programmer response: Make sure that the CARDIN data set contains a single DBD control statement. FABH0111E INVALID 'POINTER BYPASS OPTION' ON 'DBD' CARD Explanation: A DBD control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0112E FABHFSU CANNOT RUN WITH ACBS Explanation: Program FABHFSU can run either in a DL/I or in an ULU region, but cannot in DBB region. System action: FABHFSU ends abnormally. Programmer response: Modify the JCL in order to run FABHFSU in a DL/I region with PSBs and DBDs (instead of running FABHFSU in a DBB region with ACBs). FABH0113E MULTIPLE 'BLM' CONTROL CARDS ARE NOT SUPPORTED Explanation: More than one BLM control statement was specified. Program FABHFSU supports only one BLM control statement. System action: FABHFSU ends abnormally. Programmer response: Make sure that the CARDIN data set contains only one BLM control statement. FABH0114E MULTIPLE 'ELM' CONTROL CARDS ARE NOT SUPPORTED Explanation: More than one ELM control statement was specified. Program FABHFSU supports only one ELM control statement. System action: FABHFSU ends abnormally. Programmer response: Make sure that the CARDIN data set contains only one ELM control statement. FABH0115E INVALID 'LIMIT VALUE TYPE' ON 'BLM' OR 'ELM' CONTROL CARD Explanation: Either a BLM or an ELM control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0116E 'RBN LIMIT VALUE' NOT NUMERIC OR ZERO ON 'BLM' OR 'ELM' CONTROL CARD Explanation: Either a BLM or an ELM control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0117E 'LL' FIELD NOT NUMERIC OR ZERO ON 'BLM' OR 'ELM' CONTROL CARD Explanation: Either a BLM or an ELM control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0118E 'LL' FIELD GREATER THAN 74 ON 'BLM' OR 'ELM' CONTROL CARD Explanation: Either a BLM or an ELM control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally.
Chapter 28. Messages

399

FABH0119E FABH0129E
Programmer response: Correct the control statement. FABH0119E HEXADECIMAL STRING FOR LIMIT VALUE DOES NOT CONTAIN EVEN NUMBER OF HEXA-CHARACTERS Explanation: Either a BLM or an ELM control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0120E 'PCB NR' FIELD ON THE 'PSB' CONTROL CARD IS NOT NUMERIC Explanation: A PSB control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0121E INVALID FORMAT-NAME ON THE 'PSB' CONTROL CARD Explanation: A PSB control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0122E INVALID 'SEGMENT MODIFICATION OPTION' ON PSB CARD Explanation: A PSB control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0123E INVALID 'CONCATENATED KEY OPTION' ON PSB CARD Explanation: A PSB control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0124E INVALID 'EXIT CONTROL OPTION' ON PSB CARD Explanation: A PSB control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0125E INVALID 'DBR SKIP OPTION' ON PSB CARD Explanation: A PSB control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0126E INVALID 'DATA CONVERSION' OPTION ON PSB CARD Explanation: A PSB control statement contains an error. The error is described in the error message. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0127E 'PSB NAME' FIELD MUST BE SPECIFIED AS '*' WHEN RUNNING IN ULU REGION TYPE Explanation: When running in ULU Region, the name of a PSB must not be specified in the 'PSB NAME' field. When running in ULU Region, specify '*' in the 'PSB NAME' field of the PSB control statement. System action: Program FABHFSU ends abnormally. Programmer response: Either specify '*' in the 'PSB NAME' field of the PSB control statement or run FABHFSU in DL/I region. FABH0128E 'PSB NAME' FIELD MUST SPECIFY THE PSBNAME OF THE //EXEC PARM-FIELD Explanation: Program FABHFSU requires that the name of the PSB coded in the 'PSB NAME' field of the PSB control statement is the same as the name of the PSB specified in the PARM field of the //EXEC JCL statement. System action: FABHFSU ends abnormally. Programmer response: Either specify the PSB name in the 'PSB NAME' field of the PSB control statement or run FABHFSU with the 'PSB*' control statement. See the description of the PSB control statement in CARDIN data set on page 56. FABH0129E PSB HAS NO DB-PCB WITH THE REQUESTED DBDNAME AND/OR REQUESTED RELATIVE NUMBER Explanation: The PSB specified on the PSB control statement in the CARDIN data set has no database PCBs. System action: Program FABHFSU ends abnormally. Programmer response: Correct the PSB control statement.

400

Users Guide

FABH0130E FABH0140E
FABH0130E PCB WITH SPECIFIED 'RELATIVE PCB NUMBER' DOES NOT REFER TO DBD NAMED ON DBD CARD Explanation: The specified PCB on the PSB control statement refers to a dbdname that does not match a dbdname on DBD control statement in the CARDIN data set. System action: Program FABHFSU ends abnormally. Programmer response: Correct the PSB control statement. FABH0131E INVALID 'DEC' OPTION Explanation: A DEC control statement contains an incorrect option. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0132E THERE IS NO JCL DD-STATEMENT FOR THE SPECIFIED 'DDNAME' ON THE 'PSB' CONTROL CARD Explanation: Program FABHFSU detected an incorrect ddname on the PSB control statement in the CARDIN data set or on the JCL DD statement. System action: FABHFSU ends abnormally. Programmer response: Specify correct DDNAME either on the PSB control statement or on the JCL DD statements. FABH0133E 'COn' CONTROL CARD INVALID: NO MATCHING OUTPUT FORMAT Explanation: You have provided a COn (CO1, CO2, or CO3) control statement in the CARDIN data set. Program FABHFSU tried to match these control statements with the first, second, or third PSB control statements. This matching was unsuccessful because the PSB statement was not provided in the CARDIN data set (before the CO control statement). System action: FABHFSU ends abnormally. Programmer response: Correct the CARDIN control statement. FABH0134E THERE IS NO JCL DD-STATEMENT FOR THE SPECIFIED 'DDNAME' ON THE CONTROL CARD Explanation: Program FABHFSU detected an incorrect ddname on the CO control statement of the CARDIN data set or a missing JCL DD statement. System action: FABHFSU ends abnormally. Programmer response: Correct the CO control statement or the JCL DD statement. FABH0135E MULTIPLE 'PSC' CONTROL STATEMENTS NOT ALLOWED Explanation: More than one PSC control statement was specified. Program FABHFSU supports only one PSC control statement. System action: FABHFSU ends abnormally. Programmer response: Make sure that the CARDIN data set contains only one PSC control statement. FABH0136E INVALID //CARDIN CONTROL STATEMENT FOR A PSC OPERATION Explanation: A control statement that is not supported for PSF was provided in the CARDIN data set. System action: Program FABHFSU ends abnormally. Programmer response: Remove the unsupported control statement. FABH0137E 'PSC' AND 'DBD' CONTROL STATEMENTS ARE MUTUALLY EXCLUSIVE Explanation: The PSC and DBD control statements must not be specified in the same FABHFSU run. System action: Program FABHFSU ends abnormally. Programmer response: Run FABHFSU in correct mode. FABH0138E OPEN ERROR FOR //CNTLDD Explanation: Program FABHFSU could not open the CNTLDD data set. System action: FABHFSU ends abnormally. Programmer response: Check for additional error messages issued by the access method. Correct the error. FABH0139E INCORRECT 'PARALLEL SCAN NAME' Explanation: The parallel scan name specified on the PSC control statement is different from the parallel scan name specified on the CTL statement that was used to create the Scan Control Data Set. System action: Program FABHFSU ends abnormally. Programmer response: Correct the PSC control statement. FABH0140E INCORRECT 'DBD NAME' Explanation: The DBD name specified on the PSC control statement is different from the DBD name specified on the DBD control statement that was used to create the Scan Control Data Set. System action: Program FABHFSU ends abnormally.
Chapter 28. Messages

401

FABH0141E FABH0151E
Programmer response: Correct the PSC control statement. FABH0141E 'EXPECTED NUMBER OF SCANS' ON 'PSC' CONTROL CARD IS INVALID Explanation: Program FABHFSU detected an incorrect number of scans specified on a PSC control statement. System action: FABHFSU ends abnormally. Programmer response: Correct the PSC control statement. FABH0142E 'PHASE NUMBER' ON 'PSC' CONTROL CARD INVALID Explanation: Program FABHFSU detected an incorrect phase number specified on a PSC control statement System action: FABHFSU ends abnormally. Programmer response: Correct the PSC control statement. FABH0143E 'POINTER BYPASS OVERRIDE' INVALID Explanation: Program FABHFSU detected an incorrect pointer bypass override specified on a PSC control statement. System action: FABHFSU ends abnormally. Programmer response: Correct the PSC control statement. FABH0144E 'RERUN INDICATOR' INVALID Explanation: Program FABHFSU detected an incorrect rerun indicator specified on a PSC control statement. System action: FABHFSU ends abnormally. Programmer response: Correct the PSC control statement. FABH0145E 'EXPIRATION DATE OVERRIDE' NOT NUMERIC Explanation: Program FABHFSU detected an incorrect expiration date override specified on a PSC control statement. System action: FABHFSU ends abnormally. Programmer response: Correct the PSC control statement. FABH0146E 'PHASE NUMBER' HIGHER THAN 'EXPECTED NUMBER OF SCANS' Explanation: Program FABHFSU detected an incorrect phase number specified on a PSC control statement. System action: FABHFSU ends abnormally. Programmer response: Correct the PSC control statement. FABH0147E UNEXPECTED LAYOUT OF //CNTLDD CONTROL RECORD FABH0148E UNEXPECTED LAYOUT OF //CNTLDD CONTROL RECORD FABH0149E UNEXPECTED LAYOUT OF //CNTLDD CONTROL RECORD Explanation: Program FABHFSU detected an unexpected layout of the CNTLDD data set of the Parallel Scan Facility. System action: FABHFSU ends abnormally. Programmer response: Make sure that the control statements are correct. Problem determination: The reason can be: v A FABHFSU error or a FABHPSFC error v An incompatibility between a High Performance Unload and FSU II v A user error FABH0150E INCORRECT 'EXPECTED NUMBER OF SCANS' Explanation: The expected number of scans specified on the PSC control statement is different from the number of parallel scans specified on the CTL control statement for FABHPSFC, which was used to create the Scan Control Data Set. System action: Program FABHFSU ends abnormally. Programmer response: Correct the PSC control statement or the CTL control statement. FABH0151E COMPARE OPTION IS NOT ALLOWED Explanation: Program FABHFSU detected one of the following errors: v "NO" was specified for the output format of the unloaded data set in the PSB control statement for which the CO (compare) control statement was specified. v A CO control statement is specified for HALDB. System action: FABHFSU ends abnormally.

402

Users Guide

FABH0152I FABH0159W
Programmer response: Remove the CO control statement, or modify the PSB control statement. FABH0152I COMPARE OPTION DEACTIVATED BY SEGMENT EXTENSION OPTION FABH0156E 'DATA CONVERSION' OPTION FOR PSB CONTROL STATEMENT IS NOT ALLOWED Explanation: The 'data conversion' option 'Y' is specified in column 36 of a PSB control statement. However, the Data Conversion exit routine is not called for the database, for one of the following reasons: v 'DATXEXIT NO' option is specified in HSSROPT data set. v DATXEXIT=NO is specified for the database at DBDGEN, and the module DFSDBUX1 was not found in any STEPLIB library. v DATXEXIT=NO is specified for the database at DBDGEN, and the Data Conversion exit set SRCHFLAG to X'FF'. System action: Program FABHFSU ends abnormally. Programmer response: If you need to call the Data Conversion exit routine, you must prepare it in a STEPLIB library and then specify 'DATXEXIT YES' in HSSROPT data set. FABH0157W COMPRESSED SEGMENTS MUST BE DECOMPRESSED BEFORE CONVERSION; DECN IS IGNORED Explanation: You specified the DECN option in the SYSIN data set for your FABHURG1 job. But there is a compressed segment that also needs to be converted by use of the Data Conversion exit routine (DFSDBUX1). You cannot use the DECN option for a database that contains such a segment. System action: HSSR Engine continues its processing with the DECY option. Programmer response: You need to be careful when you use the output data set for reloading, because the output data set contains decompressed segments. FABH0158I COMPARE OPTION DEACTIVATED BY BLDLPCK CONTROL STATEMENT

Explanation: You requested both of the following: v The use of the segment extension option of FABHFSU (by coding "E" in column 32 of the PSB control statement in the CARDIN data set). v The use of the compare option (by providing a CO control statement in the HSSROPT data set). These two options are mutually exclusive. System action: Program FABHFSU ignores the requested "CO" option and continues processing. Programmer response: None. FABH0153E SEGMENT EXTENSION OPTION ONLY VALID WITH HDAM OR HIDAM Explanation: You requested the use of the segment extension option of FABHFSU by coding "E" in column 32 of the PSB control statement of the FABHFSU unload utility. This option is valid only for an HDAM or HIDAM database, including PHDAM and PHIDAM. System action: Program FABHFSU ends abnormally. Programmer response: Remove the "E" option, since you cannot expand segments in your database with an exit routine. FABH0154E 'LENGTH OF EXTENDED AREA' FIELD ON 'PSB' CARD IS NOT NUMERIC Explanation: The value specified in column 41 of the PSB control statement is not numeric. System action: Program FABHFSU ends abnormally. Programmer response: Specify a correct numeric value. FABH0155E 'LENGTH OF EXTENDED AREA' FIELD ON 'PSB' CARD IS TOO HIGH: MAXIMUM IS 32767 Explanation: The value specified in column 41 of the PSB control statement exceeds the acceptable maximum. System action: Program FABHFSU ends abnormally. Programmer response: Specify the smallest length that can hold each of the extended segments.

Explanation: The CO control statement (specified in the CARDIN data set) for HS-format output records is ignored when the BLDLPCK statement is specified. System action: Program FABHFSU ignores the requested CO option and continues processing. Programmer response: Remove the CO control statement or the BLDLPCK control statement from the CARDIN data set. FABH0159W DECY FORCED SINCE KEY COMPRESSION OPTION IS SPECIFIED FOR THE ROOT SEGMENT OF HIDAM DB Explanation: DECN was specified, although the key compression option is specified for the root segment of
Chapter 28. Messages

403

FABH0161E FABH0176E
the HIDAM database to be unloaded in CS format. DECY is assumed. System action: Program FABHURG1 continues processing. Programmer response: If you want to unload an HIDAM database without decompressing segments, use an output record format other than the CS format. Otherwise, you can ignore the message. FABH0161E FABHFSU DOES NOT SUPPORT SECONDARY INDEX PROCESSING Explanation: The name of an index that is not the name of the HIDAM primary index was specified on a DBD control statement System action: Program FABHFSU ends abnormally. Programmer response: Correct the DBD control statement. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0162E 'LIMIT VALUE TYPE' ON BLM/ELM CONTROL STATEMENT INVALID FOR TYPE OF DB-ORG Explanation: A value type that is not valid for the database organization was specified on a BLM/ELM control statement (or on a NPT control statement) System action: Program FABHFSU ends abnormally. Programmer response: Correct the BLM or ELM control statement. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0164E HIGH-KEY IS SPECIFIED ON BLM/ELM CONTROL STATEMENT Explanation: A HIGHKEY value for the partitioned HIDAM database is specified on the BLM or ELM control statement. The HIGHKEY values cannot be specified as the limit value for the BLM or ELM control statement. System action: Program FABHFSU ends abnormally. Programmer response: Modify the BLM or ELM control statement not to use the HIGHKEY value and rerun the job. FABH0165E BLM OR ELM CONTROL STATEMENT IS SPECIFIED FOR A HALDB Explanation: A BLM or ELM control statement is specified for a PHDAM or PHIDAM database. BLM and ELM statements are not allowed for HALDB. System action: Program FABHFSU ends abnormally. Programmer response: Remove the BLM and ELM statements. FABH0170E HSSR ENGINE IS NOT INITIALIZED Explanation: Program FABHFSU was not run in the correct environment. It should be run with the FABHDLI or FABHULU procedure (or with equivalent JCL). System action: FABHFSU ends abnormally. Programmer response: Run FABHFSU using FABHDLI or FABHULU procedure. FABH0171E FABHFSU ENVIRONMENT NOT PROPERLY INITIALIZED Explanation: Program FABHFSU was not run in the correct environment. FABHFSU was renamed, but HSSR Engine does not allow FABHFSU to be renamed. System action: HSSR Engine ends abnormally. Programmer response: Run FABHFSU using FABHDLI or FABHULU procedure. FABH0172E 'LIMIT VALUE TYPE' = 'R' IS ONLY VALID FOR HDAM Explanation: A Limit Value Type or Node Point Value Type 'R' was specified on a BLM control statement or on a NPT control statement. A Value Type 'R' is only supported for HDAM. System action: Program FABHFSU ends abnormally. Programmer response: Correct the control statement. FABH0175E UNEXPECTED PCB STATUSCODE Explanation: An HSSR call that was issued internally by program FABHFSU returned an unexpected status code. System action: FABHFSU ends abnormally. Programmer response: As a temporary bypass, specify DBDL1 control statement in the HSSROPT data set to force DL/I calls to be made by your program. FABH0176E DDN=ddname BLKSIZE OR LRECL IS TOO SMALL Explanation: The block size or record size for the output ddname data set is too small. System action: Program FABHFSU ends abnormally. Programmer response: Specify a block size or record size (LRECL) that is large enough. Record size can be specified only for VB and VN format. If the record size (LRECL) is coded on the JCL statement, it must be less than or equal to the block size minus 4.

404

Users Guide

FABH0177E FABH0187E
FABH0177E DDN=ddname OPEN HAS FAILED Explanation: Program FABHFSU could not open the output ddname data set. System action: FABHFSU ends abnormally. Programmer response: Check for further error messages issued by the access method and correct the error. FABH0180E INVALID SEGMENT LENGTH RETURNED FROM USER EXIT ROUTINE Explanation: A FABHFSU user exit routine changed the length of a database segment. The modified length is larger than the allowed maximum segment length. System action: Program FABHFSU ends abnormally. Programmer response: Correct the user exit routine. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Save the compilation listing of the user exit routine. FABH0181E USER PROGRAMMING ERROR: LENGTH OF CURRENT OUTPUT RECORD IS TOO BIG Explanation: A FABHFSU user exit routine changed the length of the current output record. The modified length is larger than the allowed maximum record length. System action: Program FABHFSU ends abnormally. Programmer response: Correct the user exit routine. FABH0182E INVALID RETURN CODE FROM USER ROUTINE Explanation: A FABHFSU user exit routine has returned an incorrect return code. System action: Program FABHFSU ends abnormally. Programmer response: Correct the user exit routine or specify the DBR Skip option on the PSB control statement. Save the compilation listing of the user exit routine. FABH0183E DDN=ddname: OPEN HAS FAILED Explanation: Program FABHFSU could not open the input ddname data set. A ddname data set created by FSU II was specified, whereas it should be compared with the FABHFSU output data set. System action: FABHFSU ends abnormally. Programmer response: Check for further error messages issued by the access method, and correct the error. FABH0184E DDN=ddname OUTPUT AND INPUT STATISTIC RECORDS ARE NOT EQUAL Explanation: A FABHFSU output data set was compared with an input ddname data set created by FSU II. FABHFSU detected that the statistic records contained in both data sets are not equal. System action: Program FABHFSU ends abnormally. Programmer response: Check whether FABHFSU has been provided with the correct FSU II output data set. Check whether FABHFSU and FSU II have been run under identical conditions (same segment sensitivity, same user exit routines, no database updates between the FSU II execution and the FABHFSU execution). Check whether it is an error of FABHFSU or an error of FSU II. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0185E DDN=ddname OUTPUT AND INPUT RECORDS NOT EQUAL Explanation: A FABHFSU output data set was compared with an input ddname data set created by FSU II. FABHFSU detected at least one record that is not identical in both data sets. System action: Program FABHFSU ends abnormally. Programmer response: Check whether FABHFSU has been provided with the correct FSU II output data set. Check whether FABHFSU and FSU II have been executed under identical conditions (same segment sensitivity, same user exit routines, no database updates between the FSU II execution and the FABHFSU execution). Check whether it is an error of FABHFSU or an error of FSU II. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0186E DDN=ddname CONTAINS TOO MANY RECORDS FABH0187E DDN=ddname CONTAINS TOO FEW RECORDS Explanation: A FABHFSU output data set was compared with an output ddname data set created by FSU II. Program FABHFSU detected that the FSU II output ddname data set does not contain the same number of records as the FABHFSU output data set. System action: FABHFSU ends abnormally. Programmer response: Check whether FABHFSU has been provided with the correct FSU II output data set. Check whether FABHFSU and FSU II have been executed under identical conditions (same segment sensitivity, same user exit routines, no database
Chapter 28. Messages

405

FABH0190E FABH0202E
updates between the FSU II execution and the FABHFSU execution). Check whether it is an error of FABHFSU or an error of FSU II. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0190E DDN=ddname LENGTH OF INPUT AND OUTPUT RECORDS DIFFER Explanation: A FABHFSU output data set was compared with an input ddname data set created by FSU II. FABHFSU detected at least one record that is not identical in both data sets. System action: Program FABHFSU ends abnormally. Programmer response: Check whether FABHFSU has been provided with the correct FSU II output data set. Check whether FABHFSU and FSU II have been executed under identical conditions (same segment sensitivity, same user exit routines, no database updates between the FSU II execution and the FABHFSU execution). Check whether it is an error of FABHFSU or an error of FSU II. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0191E DB ERROR ENCOUNTERED AND "POINTER BYPASS OPTION" NOT ACTIVATED Explanation: HSSR Engine encountered a database error. By default, FABHFSU issues this message and ends abnormally. However, the pointer bypass option can be activated to bypass the abend. System action: HSSR Engine ends abnormally. Programmer response: Check why the database error was encountered. If appropriate, activate the pointer bypass option on the DBD or PSC control statement. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0192E SEQUENCE ERROR THRESHOLD EXHAUSTED Explanation: Program FABHFSU performed sequence-checking of the segment key fields, and detected more sequence errors than specified (or defaulted) on the DBD control statement. System action: HSSR Engine ends abnormally. Programmer response: Check why the DB has so many sequence errors. If appropriate, increase the sequence error threshold value on the DBD control statement. FABH0202E FABHFSU ENCOUNTERED AN UNEXPECTED ERROR Explanation: Program FABHFSU detected an unexpected error. A possible reason could be a change of IMS DBD control blocks. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0193E ROOT-SEGMENT IS NOT SEQUENCED Explanation: Program FABHFSU was requested to retrieve a root segment by key (either on a BLM or NPT control statement or through a return code from a user exit routine). However, the root segment of the database has no defined sequence field. System action: HSSR Engine ends abnormally. Programmer response: Correct the error. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0194E DDN=ddname: DSNAME IS NOT VALID Explanation: The data set name used for the FABHFSU output ddname data set was requested to be checked on a CTL control statement. The data set name that was used did not follow the FABHFSU standard naming convention. System action: Program FABHFSU ends abnormally. Programmer response: Correct the data set name of the output data set DD statement. FABH0195E RETURN CODE 4 FROM HDAM RANDOMIZER, RMOD=xxxxxxxx Explanation: Program FABHFSU received a status code FM because of the return code 4 from the HDAM randomizing module. xxxxxxxx is the name of the HDAM randomizing module. Register 9 contains the address of the key used by the HSSR call. System action: FABHFSU ends abnormally. Programmer response: The randomizer is different from the one for the real database. Use the correct randomizer and rerun the job, if necessary. FABH0201E OPEN ERROR FOR //IMS DD Explanation: Program FABHFSU could not open the IMS DD data set to read the IMS DBD control blocks. System action: FABHFSU ends abnormally. Programmer response: Provide correct DD statements. Check for additional error messages issued by the access method.

406

Users Guide

FABH0203W FABH0221E
System action: FABHFSU ends abnormally. Programmer response: Check whether the FABHFSUI module corresponds to the correct IMS version. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0203W WARNING: SOME SEGMENTS WILL NOT BE DECOMPRESSED Explanation: You requested, by specifying the DECN option on the DEC control statement, that program FABHURG1 or FABHFSU should not decompress compressed segments. The output data sets of FABHURG1 or FABHFSU will contain segments in the compressed format, unless other decompression program (for example, an FABHURG1 or FABHFSU user exit routine) is activated. System action: HSSR Engine continues processing. Programmer response: If you really do not want to decompress the compressed segments, ignore this message. FABH0204W COMPARE OPTION CANNOT BE USED FOR THIS FABHFSU EXECUTION Explanation: HSSR Engine encountered a condition that precludes use of the compare option. System action: HSSR Engine deactivates the compare option. Programmer response: None. FABH0205W COMPARE OPTION CANNOT BE USED FOR THIS FABHURG1 EXECUTION Explanation: HSSR Engine encountered a condition that precludes use of the compare option. System action: HSSR Engine deactivates the compare option. Programmer response: None. FABH0211E ENQ CONFLICT: OTHER JOB CURRENTLY ACTIVE FOR THE SAME PSC PHASE Explanation: The concurrent multiple jobs were started for the same phase of a parallel scan. System action: Program FABHFSU ends abnormally. Programmer response: Correct the error. FABH0212E DATE FOR PSC RUN HAS ALREADY EXPIRED Explanation: Program FABHFSU was started after the expiration date specified on the CTL or on a PSC control statement. System action: FABHFSU ends abnormally. Programmer response: Correct the CTL or PSC control statement. FABH0213E PSC PHASE HAS ALREADY BEEN STARTED Explanation: Program FABHFSU was started multiple times for the same phase. System action: FABHFSU ends abnormally. Programmer response: If appropriate, specify a Rerun Indicator on the PSC control statement. FABH0214E DDN=ddname: BLOCKSIZE SHOULD NOT CHANGE Explanation: Program FABHFSU was run multiple times with different block sizes for the output data set. This is a user error. The block sizes should be the same. System action: FABHFSU ends abnormally. Programmer response: Specify identical block sizes for all executions. FABH0215I ALL SCAN PHASES STARTED

Explanation: All the FABHFSU parallel scan phases were in starting condition. System action: Program FABHFSU continues processing. Programmer response: None. FABH0216E PARTITION DB IS NOT SUPPORTED IN PSF MODE Explanation: The partition database cannot be unloaded in PSF mode. System action: Program FABHFSU ends abnormally. Programmer response: If you want to unload the partitioned database, run FABHFSU in standard mode or use FABHURG1 unload utility. FABH0221E UNEXPECTED LAYOUT OF PSC CONTROL-FILE RECORDS Explanation: Program FABHFSU read from the PSC control data set a record with an unexpected record format. System action: FABHFSU ends abnormally.
Chapter 28. Messages

407

FABH0222E FABH0236E
Programmer response: Be sure that the PSC control data set has been created correctly by FABHPSFC, and that it has been created with the correct DBD version. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0222E UNEXPECTED CONDITION ON PSC CONTROL FILE: PHASE ALREADY COMPLETED Explanation: At job-step termination, program FABHFSU detected that its phase is already marked as "completed" in the PSC control data set. Such an incorrect situation can occur in an uncontrolled multisystem environment. System action: FABHFSU ends abnormally. Programmer response: Do not run the PSF option of FABHFSU in an uncontrolled multisystem environment. Consider using Global Resource Serialization. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0223I ALL SCAN PHASES COMPLETED FABH0231E PCBS CANNOT BE FOUND Explanation: On entry, FABHTEST could not find the PCBs. This was probably caused by FABHTEST not being invoked by the FABHDLI or FABHDBB procedures (or by equivalent JCLs). System action: Program FABHTEST ends abnormally. Programmer response: Use the FABHDLI or FABHDBB procedures. FABH0232E PSB HAS NO DB-PCBS Explanation: The provided PSB has no database PCBs. Therefore, the run of FABHTEST is meaningless. System action: Program FABHTEST ends abnormally. Programmer response: Provide a PSB that refers to a database. FABH0233E SYSIN CANNOT BE OPENED Explanation: The SYSIN data set containing the FABHTEST control statements could not be opened. System action: Program FABHTEST ends abnormally. System messages are issued to describe the problem in more detail. Programmer response: Add a SYSIN DD statement to the appropriate control statements. FABH0234E INVALID TYPE OF CONTROL STATEMENT Explanation: The last control statement read has an incorrect statement type in columns 14. System action: Program FABHTEST ends abnormally. Programmer response: If the abend is unintentional, correct the control statement. Problem determination: Only the following control statement types are permitted: PCB, GU, GN, or GNR. FABH0235E SPECIFIED PCB IS NEITHER A HSSR-PCB NOR A DL/I-DB-PCB Explanation: The PCB specified on the PCB control statement is neither an HSSR PCB nor a DL/I database PCB. System action: Program FABHTEST ends abnormally. Programmer response: Correct the PCB control statement or modify the PSB. FABH0236E SPECIFIED PCB-NUMBER NOT WITHIN PSB Explanation: The PCB number specified on the PCB control statement does not exist within the provided PSB.

Explanation: All the FABHFSU parallel scan phases were completed. System action: Program FABHFSU continues processing. Programmer response: None. FABH0224W NO SEGMENT WAS RETRIEVED Explanation: Program FABHFSU attempted to unload the database, but no segment was retrieved from the database. The database might be empty. System action: FABHFSU normally ends with a return code of 01. Programmer response: Check whether it is acceptable that the input database has no valid segments. If a wrong database data set, or wrong DBD or PSB was specified, specify the proper ones, and rerun the job. FABH0225W NO SEGMENT WAS RETRIEVED IN THE CURRENT PSF PHASE Explanation: Program FABHFSU attempted to unload a portion of a database in this PSF phase, but no segment was retrieved in the phase. System action: FABHFSU normally ends with a return code of 01. Programmer response: Check whether it is acceptable that the portion has no valid segments. If a wrong database data set, or wrong DBD or PSB was specified, specify the proper ones, and rerun the job.

408

Users Guide

FABH0237E FABH0250E
System action: Program FABHTEST ends abnormally. Programmer response: Correct the PCB control statement or modify the PSB. FABH0237E GU WITH SSA NOT POSSIBLE BECAUSE ROOT HAS NO KEY-FIELD Explanation: The last printed GU control statement contains a relational operator in columns 1617. This means that program FABHTEST should issue GU calls with an SSA qualified on the key field of the root segment. However, the root segment has no key fields. System action: FABHTEST ends abnormally. Programmer response: Remove the GU control statement. FABH0238E THE 'NUMBER FIELD' IS NOT NUMERIC Explanation: Positions 514 of the last printed control statement contains a character that is neither numeric nor blank. System action: Program FABHTEST ends abnormally. Programmer response: Correct the control statement. FABH0239E REPL STATEMENT IS NOT SUPPORTED FOR PARTITION DB Explanation: A REPL statement is specified in the SYSIN data set for the FABHTEST utility. REPL statement is not allowed for the FABHTEST utility. System action: Program FABHTEST ends abnormally. Programmer response: Modify the SYSIN statement not to use a REPL statement. FABH0240E UNEXPECTED CONTINUATION STATEMENT Explanation: The last printed statement is a continuation control statement that is not preceded by a control statement containing the continuation indicator in column 72. System action: Program FABHTEST ends abnormally. Programmer response: Remove the offending continuation control statement, or insert a continuation indicator in the preceding control statement. FABH0241E ILLEGAL CONTINUATION; KEY FIELD SHOULD END ON THIS CONTROL STATEMENT Explanation: The last printed control statement contains a continuation indicator in column 72, but the FIELD statement of DBDGEN indicates that the key field of the root is short enough to end on the last printed control statement. System action: Program FABHTEST ends abnormally. Programmer response: Check for the length of the key field of the root segment, and correct the FABHTEST control statements. FABH0242E CONTINUATION CARD IS MISSING Explanation: Program FABHTEST expected a continuation control statement, but received the last printed control statement. System action: FABHTEST ends abnormally. Programmer response: Insert the missing continuation control statement. FABH0243E SYSPRINT CANNOT BE OPENED Explanation: The SYSPRINT data set containing a listing of the FABHTEST control statements could not be opened. System action: Program FABHTEST ends abnormally. System messages will be issued to describe the problem in more detail. Programmer response: Correct the SYSPRINT DD statement. FABH0248W INCORRECT ROOT KEY IN GU-CALL (STATUS CODE FM) Explanation: Program FABHTEST received a status code FM from HSSR call handler because of a return code 4 from the HDAM randomizing module. System action: FABHTEST program continues processing. Programmer response: Check whether the preceding is acceptable. FABH0249E PCB WITH SPECIFIED DBDNAME NOT FOUND Explanation: The last printed PCB control statement contains a DBDNAME that is not referred to by any PCB of the PSB. System action: Program FABHTEST ends abnormally. Programmer response: Correct the PCB control statement or provide another PSB. FABH0250E FABH001 HAS NOT BEEN PROPERLY INITIALIZED Explanation: The HSSR control block HTCB located within the load module FABH001 was not properly initialized by HSSR Engine. System action: HSSR Engine ends abnormally. Programmer response: Execute FABHURG1 with correct JCL.
Chapter 28. Messages

409

FABH0251E FABH0259E
Problem determination: Possible reason for this error: FABHURG1 was not run with JCL equivalent to the procedures FABHDLI, FABHDBB, or FABHULU but with JCL similar to the procedures DLIBATCH or DBBBATCH. FABH0251E SYSPRINT COULD NOT BE OPENED Explanation: Program FABHURG1 could not open the SYSPRINT data set. System action: FABHURG1 ends abnormally. Programmer response: Provide or correct a SYSPRINT DD statement. FABH0252E INVALID STATEMENT WAS DETECTED Explanation: An incorrect control statement type was specified in the FABHURG1 SYSIN data set. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the utility control statement. FABH0253E PCB NUMBER IS NOT POSITIVE Explanation: A FABHURG1 SYSIN data set PCB control statement specified a PCB number that was not positive. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the PCB control statement FABH0254E SPECIFIED HSSR PCB IS NOT FOUND Explanation: A FABHURG1 SYSIN data set PCB control statement specified an HSSR PCB that could not be found. Note that the PCB control statement should refer to HSSR PCBs, never to DL/I PCBs. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the utility control statement or the PSB. FABH0255E NUMERIC FIELD IS NOT NUMERIC Explanation: A FABHURG1 SYSIN data set control statement, in a field defined as numeric, contains nonnumeric information. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the control statement. FABH0256E BLKSIZE OR LRECL OF ddname IS TOO SMALL Explanation: The block size or record size of the ddname data set is too small. For *HD output, the block size is always the maximum device capacity. For other output, the block size or record size is the maximum device capacity unless a block size or record size is coded on the JCL statement. System action: Program FABHURG1 ends abnormally. Programmer response: v If a user record-formatting routine is used, check whether ULEN can be reduced. v If the utility uses the maximum device capacity, check whether ddname can be allocated on a device with more track capacity. v If the utility uses the block size or record size specified on the JCL statement, check whether the block size or record size can be increased or use the default maximum device capacity. v Record size can be specified only for *F1, *F2 and *F3 format. If the record size (LRECL) is coded on the JCL statement, it must be less than or equal to the (block size) minus 4. v If an optional exit routine is used for the FABHURG1 utility, check whether the length specified on the USEGMAX control statement can be reduced. FABH0257E OPEN OF ddname HAS FAILED Explanation: Program FABHURG1 could not open ddname. System action: FABHURG1 ends abnormally. Programmer response: Correct the ddname DD statement. FABH0258E THERE ARE NO HSSR PCBS Explanation: The PSB does not contain an HSSR PCB. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the PSB or remove the HSSROPT DBDL1 control statement. FABH0259E USER PROGRAMMING ERROR: LENGTH OF CURRENT ddname RECORD IS TOO LARGE Explanation: A user record-formatting routine or a user exit routine created a ddname record that is larger than allowed. System action: Program FABHURG1 ends abnormally.

410

Users Guide

FABH0260E FABH0266W
Programmer response: Correct the user routine. Save compilation listings of user routines. FABH0260E INVALID RETURN CODE FROM USER ROUTINE Explanation: A user routine set an incorrect return code. Only the following return codes are valid: 0, 1, 2, 3. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the user routine. Save compilation listings of user routines. FABH0261E OPEN OF SYSUT1 HAS FAILED Explanation: Program FABHURG1 could not open SYSUT1. System action: FABHURG1 ends abnormally. Programmer response: Correct the SYSUT1 DD statement. FABH0262E RECORDS OF ddname ARE NOT EQUAL Explanation: Program FABHURG1 compared its ddname output with the output from the IMS HD Reorganization Unload utility (which was defined by the SYSUT1 DD statement). FABHURG1 detected that these data sets contain records that are not equal. System action: FABHURG1 ends abnormally. In the dump, Register 7 will point to the SYSUT1 record and Register 8 to the ddname record. Programmer response: Run FABHURG1 with the HSSROPT compare option and the HSSROPT hard-copy trace option. Problem determination: v Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. v Check whether the database and DBD have not been updated between the execution of IMS HD Reorganization Unload and the execution of FABHURG1. v Check whether SYSUT1 is created with the IMS HD Reorganization Unload utility without any user exit routine. v Check whether the execution of the IMS HD Reorganization Unload utility is successful. v Save all output of the IMS HD Reorganization Unload utility. FABH0263E SYSUT1 CONTAINS MORE DATA RECORDS THAN ddname FABH0264E SYSUT1 CONTAINS LESS DATA RECORDS THAN ddname Explanation: Program FABHURG1 compared its ddname output with the output of the IMS HD Reorganization Unload utility (which was defined by the SYSUT1 DD statement). FABHURG1 detected that these data sets did not contain the same number of database segments. System action: FABHURG1 ends abnormally. Programmer response: See message FABH0262E for more information, and take an appropriate action. FABH0265W SIZE OF STATISTIC TABLES ARE NOT THE SAME IN SYSUT1 AND ddname Explanation: Program FABHURG1 compared its ddname output with the output of the IMS HD Reorganization Unload utility (which was defined by the SYSUT1 DD statement). FABHURG1 detected that the statistic tables stored in the first and last record do not have the same length. System action: FABHURG1 ends abnormally. Programmer response: Run FABHURG1 with the HSSROPT compare option and the HSSROPT hard-copy trace option. Problem determination: v Check whether the DBD has not been updated between the execution of IMS HD Reorganization Unload and the execution of FABHURG1. v Check whether SYSUT1 is created with the IMS HD Reorganization Unload utility without any user exit routines. v Check whether the execution of the IMS HD Reorganization Unload utility is successful. v Save all output of the IMS HD Reorganization Unload utility. FABH0266W COMPARE OF SYSUT1 AND ddname STOPPED Explanation: Program FABHURG1 compared its ddname output with the output of the IMS HD Reorganization Unload utility. FABHURG1 stopped the compare for one of the following reasons: v Some segments are not sensitive. v A user routine returned a nonzero return code. System action: Since the comparison is no longer possible, FABHURG1 continues its processing without performing the comparison of SYSUT1 and ddname. Programmer response: None.

Chapter 28. Messages

411

FABH0267E FABH0275W
FABH0267E GG STATUS CODE ENCOUNTERED AND SKERROR OPTION WAS NOT ACTIVATED Explanation: HSSR Engine detected a database error and returned a GG status code to program FABHURG1. FABHURG1 can handle this status code only if the SKERROR option has been activated. System action: FABHURG1 ends abnormally. Programmer response: To unload the corrupted database, activate the SKERROR option. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR was being updated at the time when the error occurred. FABH0268W WARNING: NOT ALL SEGMENTS WERE SENSITIVE Explanation: Program FABHURG1 detected that some database segment types were not sensitive. System action: FABHURG1 continues processing. Programmer response: Check whether FABHURG1 uses a PSB with some segment types not defined as sensitive. FABH0269W WARNING: SOME SEGMENTS HAVE BEEN SKIPPED BY USER ROUTINES Explanation: Program FABHURG1 detected that a user routine has set a nonzero return code, indicating that some segment occurrences should be skipped and should not be written to any unload data set. System action: FABHURG1 continues processing. Programmer response: Check whether the user routines should really set a nonzero return code. Save compilation listings of the user routines. FABH0270W WARNING: SOME SEGMENTS HAVE A VIRTUAL LOGICAL PARENT KEY Explanation: Program FABHURG1 detected that a logical child segment has a virtual logical-parentconcatenated-key (LPCK), but the BLDLPCK control statement is not specified. Hence the output will contain blanks instead of the LPCK (unless user routines have performed additional processing). System action: FABHURG1 continues processing. Programmer response: Check whether this is acceptable. If it is not, specify the BLDLPCK control statement. FABH0271W WARNING: SEGMENTS MAY BE MISSING ON UNLOADED OUTPUT BECAUSE OF GG STATUS CODE Explanation: Program FABHURG1 is running with the SKERROR option in order to unload a database that contained database errors. Some segments might be missing on the unloaded output. System action: FABHURG1 continues processing. Programmer response: Check whether the unloaded database version is acceptable to the applications. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0272I DB UNLOAD COMPLETE

Explanation: Program FABHURG1 reached the end of the database and has finished its processing. System action: FABHURG1 continues processing. Programmer response: None. FABH0273I nnn,nnn,nnn DB RECORDS RETRIEVED - DBD=dbdname PART=ddname

Explanation: nnn,nnn,nnn database records have been retrieved from database dbdname. PART=ddname is displayed only for partitioned databases, and in that case, the database records are counted per partition. System action: Program FABHURG1 continues processing. Programmer response: None. Problem determination: None. FABH0274E RETURN CODE 4 FROM HDAM RANDOMIZER, RMOD=xxxxxxxx Explanation: Program FABHURG1 received a status code FM because of the return code 4 from HDAM randomizing module. xxxxxxxx is the name of HDAM randomizing module. Register 9 contains the address of key used by the HSSR call. System action: FABHURG1 ends abnormally. Programmer response: The randomizer is different from the one for the real database. Use the correct randomizer and rerun the job, if necessary. FABH0275W WARNING: NO SEGMENT WAS RETRIEVED Explanation: Program FABHURG1 attempted to unload a database, but no segment was retrieved from the database. The database might be empty.

412

Users Guide

FABH0276I FABH0283E
System action: FABHURG1 normally ends with a return code of 01. Programmer response: Check whether it is acceptable that the input database has no valid segments. If a wrong database data set, or wrong DBD or PSB was specified, specify the proper ones, and rerun the job. FABH0276I USEGMAX STATEMENT IS IGNORED v DATXEXIT=NO is specified for the database at DBDGEN, and the module DFSDBUX1 was not found in any STEPLIB library. v DATXEXIT=NO is specified for the database at DBDGEN, and the Data Conversion exit set SRCHFLAG to X'FF'. System action: Program FABHURG1 ends abnormally. Programmer response: If you need to call a Data Conversion exit routine, you must prepare it in a STEPLIB library and specify 'DATXEXIT YES' in the HSSROPT data set. FABH0280E INVALID 'DATA CONVERSION' OPTION ON EXIT CONTROL STATEMENT Explanation: Program FABHURG1 detected an error in the 'data conversion' option field of the EXIT control statement. System action: FABHURG1 ends abnormally. Programmer response: Correct the error. FABH0281E OUTPUT FORMAT *CS IS NOT SUPPORTED FOR THIS DATABASE: DBD=dbdname Explanation: This message is issued if the *CS format is specified for a SHISAM database or for a secondary index. System action: Program FABHURG1 ends abnormally. Programmer response: Use an unload format other than *CS. FABH0282E [MIGRATION|FALLBACK] UNLOAD IS NOT SUPPORTED IN THIS REGION TYPE Explanation: The migration unload and the fallback unload are not supported in the DLI or the DBB region. You must run these jobs in the ULU region. System action: Program FABHURG1 ends abnormally. Programmer response: Run the job in the ULU region. FABH0283E INVALID PART STATEMENT IS SPECIFIED: reason Explanation: An incorrect PART statement is specified in the SYSIN data set. reason indicates the reason of the error, as follows: reason Description

Explanation: This message is issued in one of the following cases: 1. The length specified on the USEGMAX control statement is less than the length of the longest database segment. 2. No user exit routine is specified. 3. The USEGMAX statement is specified for the *F3 format or for the user record-formatting routine. System action: For each case, the following system action is taken: 1. The length specified on the USEGMAX statement is adjusted to the length of the longest segment. 2. The USEGMAX statement is ignored. 3. The USEGMAX statement is ignored. In any of these cases, program FABHURG1 continues its processing and ends with a return code of 0. Programmer response: If the system action is acceptable for you, remove the USEGMAX statement or modify the value for the USEGMAX control statement for the next run. If the action is not acceptable, check your control statements or the DBD you specified. Then correct the error, and rerun the job. FABH0278I NOT ALL PARTITIONS ARE PROCESSED

Explanation: This message is for information only. This message notifies the user that all partitions are not processed by the job. Only the selected partitions are processed. System action: HSSR Engine continues processing. Programmer response: None. FABH0279E 'DATA CONVERSION' OPTION FOR EXIT CONTROL STATEMENT IS NOT ALLOWED Explanation: The 'data conversion' option 'Y' is specified in column 15 of a EXIT control statement although the Data Conversion exit routine is not called for the database for one of the following reasons: v 'DATXEXIT NO' option is specified in the HSSROPT data set.

Chapter 28. Messages

413

FABH0284E FABH0293E
NON-PARTITIONED DB The PART control statement is specified for a nonpartitioned database. TOO MANY PARAMETERS More than 32 partitions are specified on the PART control statements. DUPLICATION (ddname) The partition DD name ddname is specified more than once. NOT FOUND (ddname) The partition DD name ddname specified on a PART statement was not found in the DBD. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the error and rerun the job. FABH0284E INCORRECT CHECKREC OPTION Explanation: An incorrect CHECKREC option is specified in the SYSIN data set. It must be either YES or NO. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the error. FABH0288E SINGLE PARTITION PROCESSING IS NOT SUPPORTED Explanation: When the entire database processing is requested with no PARTITION control statement of program FABHURG1 or FABHFSU, the DFSHALDB data set for HALDB Single Partition Processing cannot be used. System action: FABHURG1 or FABHFSU ends abnormally. Programmer response: Remove the HALDB control statement on the DFSHALDB DD statement. If you want to unload a partition, specify the PARTITION control statement in the SYSIN data set of FABHURG1 or in the CARDIN data set of FABHFSU. FABH0290E MUTUALLY EXCLUSIVE CONTROL STATEMENTS ARE SPECIFIED: xxxxxxxx AND yyyyyyyy Explanation: The control statements xxxxxxxx and yyyyyyyy are mutually exclusive. System action: Program FABHURG1 ends abnormally. Programmer response: Select only one of these statements, and remove the rest. FABH0291E AN ERROR IS FOUND IN A 'PARTITION' CONTROL STATEMENT: reason Explanation: A PARTITION statement is coded incorrectly. The string reason indicates the reason for the error: reason NON-HALDB Description The PARTITION statement is specified for a database that is not a HALDB.

NAME TOO LONG The value specified as the first operand of the PARTITION statement has more than seven bytes. NUMBER TOO LONG The numeric value specified as the second operand of the PARTITION statement has more than five digits. NUMBER TOO LARGE The numeric value specified as the second operand of the PARTITION statement is greater than 1001. NUMBER IS ZERO The numeric value specified as the second operand of the PARTITION statement is 0. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the error in the PARTITION statement. FABH0292E MIGRATE CONTROL STATEMENT IS SPECIFIED FOR AN UNSUPPORTED DB TYPE Explanation: The MIGRATE control statement cannot be used for this database. For details about the control statement, see Chapter 4. System action: Program FABHURG1 ends abnormally. Programmer response: Check whether the correct DBD was specified. FABH0293E FALLBACK CONTROL STATEMENT IS SPECIFIED FOR NON-HALDB Explanation: The FALLBACK control statement is specified for a database that is not a HALDB. System action: Program FABHURG1 ends abnormally. Programmer response: Check whether the correct DBD was specified.

414

Users Guide

FABH0294E FABH0305E
FABH0294E INVALID UNLOAD FORMAT IS SPECIFIED FOR [MIGRATION|FALLBACK] UNLOAD Explanation: A format other than *HD is specified on the FRMT control statement for the FABHURG1 job, although the migration or fallback unload is designated. System action: Program FABHURG1 ends abnormally. Programmer response: Specify the *HD format, and rerun the job. FABH0295E USEGMAX CONTROL STATEMENT IS SPECIFIED FOR [MIGRATION|FALLBACK] UNLOAD Explanation: The USEGMAX control statement is specified for the FABHURG1 job, although the migration or fallback unload is designated. The USEGMAX control statement is not allowed in migration and fallback unload. System action: Program FABHURG1 ends abnormally. Programmer response: Remove the USEGMAX control statement, and rerun the job. FABH0299I UNLOAD FUNCTION ENDED, HIGHEST RETURN CODE IS xxx (REASON CODE: yyyy) FABH0301E //EXEC PARM-FIELD SHOULD BEGIN WITH NAME OF REGION CONTROLLER FOLLOWED BY '/' Explanation: The PARM field of the EXEC statement does not begin with the name of the region controller followed by a slash. System action: The run-time initializer ends abnormally. Programmer response: Correct the EXEC statement. FABH0302E NAME OF REGION CONTROLLER IN //EXEC PARM-FIELD IS LONGER THAN 8 BYTES Explanation: The PARM field of the EXEC statement does not begin with the name of the region controller followed by a slash. Either the slash is omitted, or the region controller name is more than 8 bytes long. System action: The run-time initializer ends abnormally. Programmer response: Correct the EXEC statement. FABH0303E PGM-NAME HAS NOT BEEN PROVIDED ON //EXEC PARM-FIELD Explanation: The PARM field of the EXEC statement does not contain the name of the application program. System action: The run-time initializer ends abnormally. Programmer response: Correct the EXEC statement. FABH0304E PGM-NAME IN //EXEC PARM-FIELD IS LONGER THAN 8 BYTES Explanation: The PARM field of the EXEC statement contains an application program name that is longer than 8 bytes. System action: The run-time initializer ends abnormally. Programmer response: Correct the EXEC statement. FABH0305E DFSURGU0 ALREADY IN VIRTUAL STORAGE Explanation: In a ULU region type, the run-time initializer identifies the entry point DFSURGU0 as the entry into FABH000. This requires that the module DFSURGU0 is not already in virtual storage at initialization time. This condition was not met during this execution. System action: The run-time initializer ends abnormally. Programmer response: Contact IBM Software Support.
Chapter 28. Messages

Explanation: Program FABHURG1 that had been invoked by using a JCL that is compatible with IMS HD Reorganization Unload utility ended with the decimal return code xxx. For the meaning of hexadecimal reason code yyyy for the return code of 4, see JCL for IMS HD Reorganization Unload to run FABHURG1 on page 387. System action: Program FABHURG1 ends its processing. Programmer response: Check the return code. If the return code is 4, check also the reason code. Check the accompanying FABHxxxxx messages. FABH0300E ERROR IN OPENING SYSIN Explanation: The runtime initializer of High Performance Unload called from the DFSISVI0 exit failed in opening the SYSIN data set. System action: High Performance Unloads runtime initializer ends abnormally. Programmer response: Find the cause of the open error.

415

FABH0306E FABH0315E
FABH0306E UNEXPECTED RETURN CODE FROM IDENTIFY Explanation: In a ULU region type, the run-time initializer issues an IDENTIFY macro. The IDENTIFY failed. This should not occur. System action: The run-time initializer ends abnormally. Programmer response: Contact IBM Software Support. FABH0307E LOAD MODULE FABH000 IS NOT REENTRANT Explanation: FABH000 must be link-edited with the link-editor attribute RENT. This was not the case. System action: The run-time initializer ends abnormally. Programmer response: Contact IBM Software Support. FABH0308E MEMBER NAME DFSURGU0 IS INVALID FOR A JOB RUNNING IN ULU REGION Explanation: The IMS utility DFSURGU0 cannot be executed in a ULU region. System action: The run-time initializer ends abnormally. Programmer response: Instead of executing DFSURGU0 in the ULU region, execute it with normal IMS job control statements. FABH0309E FABH001 IS NOT REUSABLE Explanation: The load module FABH001 must have the link-editor attribute REUS. This was not the case. System action: The run-time initializer ends abnormally. Programmer response: Find out why FABH001 is not reusable (it may be a submodule which is not reusable). If necessary, contact IBM Software Support. FABH0310E MODULE FABH001 IS NOT REUSABLE; PLEASE INFORM YOUR IMSSPECIALISTS Explanation: High Performance Unloads program controller detected an error. One likely cause of the error is that the load module FABH001 does not have the linkage-editor attribute REUS. System action: The job ends abnormally with a dump. Programmer response: Check in the dump if FABH001 is serially reusable. If necessary, relink FABH001 as serially reusable. FABH0311E DYNAMIC ALLOCATION FAILED FOR DD xxxxxxxx: RC=xx RSN=yyyy Explanation: The dynamic allocation for the DD xxxxxxxx failed. The values xx and yyyy are the return code and reason code that are returned from the SVC99 routine. System action: HSSR Engine ends abnormally. Programmer response: If the DD name xxxxxxxx is DFSVSAMP, this may be an internal system error. If so, collect the dump and contact IBM Software Support. FABH0312E DFSVSAMP OPEN FAILURE OCCURRED Explanation: The run-time initializer failed to open the DFSVSAMP data set that the initializer dynamically allocated. System action: The run-time initializer ends abnormally. Programmer response: This may be an internal system error. Collect the dump and contact IBM Software Support. FABH0313E SYNTAX ERROR IN SYSIN CONTROL STATEMENTS Explanation: Both a control statement for IMS HD Reorganization Unload utility (DFSURGU0) and a control statement for program FABHURG1 are specified in the SYSIN data set. You must specify control statements for one, but not both, of these utilities. System action: High Performance Unloads runtime initializer ends abnormally. Programmer response: Correct the SYSIN control statements. FABH0314E HSSR INITIALIZATION FAILED Explanation: HSSR engine detected an error, which is described in the previous error message. System action: HSSR Engine ends abnormally. Programmer response: Remove the cause of the error by referring to the message issued before this message. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0315E [GU/GHU/GN/GHN/GNP/GHNP] CALL SSA-n IS UNSUPPORTED: reason Explanation: The application program issued a call with one or two SSAs. The n-th SSA is not supported by the HSSR call handler. The reason is one of: SEGMENT NAME The segment name is not defined in the HSSR PCB.

416

Users Guide

FABH0316E FABH0324E
SEGMENT LEVEL The SSA for the segment level is not supported. COMMAND CODE The command code is not supported. NON-SEQ FIELD The field is not a sequence key. RELATIONAL OPERATOR The relational operator is not supported. MULTI QUALIFICATION STATEMENTS The multi-qualification statement is not supported. QUALIFIED SSA The qualified SSA for root segment is not supported because the database is HDAM or PHDAM. The unsupported call is printed in the Trace output report in the HSSRTRAC data set. System action: If APISET is 2, HSSR Engine ends abnormally. If APISET is 3, the call and all the succeeding calls to the HSSR PCB are passed to the IMS DL/I call handler to continue the processing instead of ending it abnormally. Programmer response: If APISET is 2, specify APISET 3. If APISET is 3, ignore this message. For details about the call types and command types supported by the HSSR call handler, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0316E ERROR RETURN FROM IGWASYS (RC=xx, RSN=yy) Explanation: HSSR Engine called IGWASYS, but an error return code was returned from IGWASYS. Here, xx is the return code and yy is the reason code. System action: HSSR Engine ends abnormally. Programmer response: See DFSMSdfp Advanced Services and check the meaning of the return code and reason code. FABH0319E GN WITH QUALIFIED SSA CALL IS ISSUED TO THE COMPRESSED ROOT KEY Explanation: The GN call with an SSA qualified on the root key field is issued, however, HSSR Engine cannot compare the compressed key with the given value. System action: HSSR Engine ends abnormally. Programmer response: For HIDAM or PHIDAM database, specify the BYINDEX control statement in HSSROPT, then the root key stored in the index database is used. Otherwise, check whether the correct APISET control statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0320E GB ON PCF OR TWIN-NOT-ROOT Explanation: In HD organizations, HSSR call handler follows the HD chains to find out which is the next segment to be processed. During this process, HSSR call handler "lost itself." System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0321E RBA OUT OF DB-RANGE Explanation: In an HD organization, HSSR call handler found a pointer that points beyond the data set end. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0322E S-C DOES NOT MATCH Explanation: In an HD organization, HSSR call handler checks the segment code of a retrieved segment against the expected segment code. This check was not successful. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0321E for more information, and take an appropriate action. FABH0324E BAD RETURN-CODE FROM BUFFER HANDLER Explanation: HSSR buffer handler encountered an I/O problem. More information can be found in the accompanying SYNADAF message buffer. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0321E for more information, and take an appropriate action.

Chapter 28. Messages

417

FABH0325E FABH0334E
FABH0325E INVALID SEGMENT-CODE IN HISAM Explanation: HSSR call handler checked the segment code of an HISAM database. The segment code is not within the range of defined segment codes. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0321E for more information, and take an appropriate action. FABH0326E BAD RETURN-CODE FROM BUFFER-HANDLER (KSDS) Explanation: While reading an KSDS record, HSSR buffer handler encountered an I/O problem. More information will be found in the accompanying SYNADAF message buffer. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0321E for more information, and take an appropriate action. FABH0327E BAD RETURN-CODE FROM BUFFER-HANDLER (ESDS/OSAM) Explanation: While reading an OSAM block or ESDS CI, HSSR buffer handler encountered an I/O problem. More information will be found in the accompanying SYNADAF message buffer. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0321E for more information, and take an appropriate action. FABH0329E REPLACE CALL WITHOUT PREVIOUS SUCCESSFUL GH CALL Explanation: The application program issued an HSSR Replace call, but it had not previously issued a successful Get Hold call. System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. FABH0330E INVALID CALL-FUNCTION Explanation: The application program issued an HSSR call with a call function that was neither GU, GN, GNP, GHU, GHN, GHNP, REPL, or RBA. System action: HSSR Engine ends abnormally. Programmer response: Correct the error. FABH0331E INVALID PARM-NUMBER IN GN-CALL Explanation: The application program issued an HSSR GN call with an incorrect number of parameters (too few or too many). System action: HSSR Engine ends abnormally. Programmer response: Correct the error. Problem determination: Assembler and COBOL programs should issue GN calls with the following parameters: Function PCB IOAREA SSA (optional) PL/I programs should issue GN calls with the following parameters: Parameter Count Function PCB IOAREA SSA (optional) FABH0332E SEGMENT-NAME IN SSA IS NOT ROOT-NAME Explanation: The application program issued an HSSR GN call with an SSA; the segment name in the SSA is not the name of the root segment. System action: HSSR Engine ends abnormally. Programmer response: Specify APISET 2 or APISET 3. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0333E SEGMENT-NAME IN SSA NOT FOLLOWED BY A BLANK Explanation: The application program issued an HSSR GN call with an SSA; the 8-byte segment name in the SSA is not followed by a blank. System action: HSSR Engine ends abnormally. Programmer response: Specify APISET 2 or APISET 3 in the control statement. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0334E ROOT-SEGMENT IS NOT (DATA-) SENSITIVE Explanation: The application program issued an HSSR GN call to retrieve the next database root segment; however, in the PSBGEN, the root segment is not defined as data-sensitive. System action: HSSR Engine ends abnormally. Programmer response: Modify the PSB or modify the program.

418

Users Guide

FABH0335E FABH0343E
FABH0335E INTERNAL ERROR OCCURRED IN HSSR CALL HANDLER Explanation: HSSR call handler detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination and take an appropriate action. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0336E NO ERROR TEXT AVAILABLE Explanation: HSSR Engine detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination and take an appropriate action. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0337E ADDRESS-LIST OF HSSR CALL-PARAMETERS IS INVALID Explanation: The format of the call-parameter address list used in the HSSR call is incorrect. System action: HSSR Engine ends abnormally. Programmer response: Correct the application program to provide appropriate parameter addresses. Problem determination: This might happen in the following cases: v An Assembler application program provides an incorrect parameter address. v The member of the call parameters is incorrect. Confirm that Register 6 points to the address list of the call parameters. FABH0338E INCORRECT SEGMENT NAME IN SSA Explanation: The application program issued an HSSR GN call with an incorrect segment name in the SSA. The segment name should be the name of a sensitive segment. System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. FABH0339E A DEPENDENT SEGMENT IS NOT (DATA-) SENSITIVE Explanation: The application program issued an HSSR GN call to retrieve the next dependent segment; in the PSBGEN, however, the dependent segment is not defined as data-sensitive. System action: HSSR Engine ends abnormally. Programmer response: Modify the PSB or modify the program. FABH0340E EXECUTION IN AN ONLINE REGION IS NOT SUPPORTED Explanation: An attempt was made to run High Performance Unload in an online region. This is not supported. System action: All HSSR calls fall back to DL/I calls. All HSSR PCBs fall back to DL/I PCBs and all calls issued against these PCBs are processed by DL/I action modules. Programmer response: Correct the region type in the PARM field of the EXEC statement. FABH0341E PST LAYOUT HAS CHANGED Explanation: During the initialization of HSSR Engine, an incorrect DL/I PST layout was detected. System action: All HSSR calls fall back to DL/I calls. All HSSR PCBs fall back to DL/I PCBs, and all calls issued against these PCBs are processed by DL/I action modules. Programmer response: Check whether High Performance Unload supports the active IMS release. FABH0342E LANGUAGE OF PSB IS NOT SUPPORTED Explanation: During the initialization of HSSR Engine, a PSB language flag defining a language other than Assembler, COBOL, or PL/I was detected. System action: All HSSR calls fall back to DL/I calls. All HSSR PCBs and all calls are processed by DL/I action modules. Programmer response: Correct the PSB language statement and rerun the job, if necessary. FABH0343E HSSR INITIALIZATION HAS INTERCEPTED A PGM CHECK Explanation: During the initialization of HSSR Engine, an ESPIE EXIT routine intercepted a program check; the possible cause is an incorrect DL/I control block layout. System action: All HSSR calls fall back to DL/I calls. All HSSR PCBs fall back to DL/I PCBs, and all calls
Chapter 28. Messages

419

FABH0344E FABH0352E
issued against these PCBs are processed by DL/I action modules. Programmer response: Contact IBM Software Support, if necessary. FABH0344E LAYOUT OF PCPARMS AND/OR RCPARMS HAS CHANGED Explanation: During the initialization of HSSR Engine, HSSR detected an unexpected layout of DL/I PCPARMS or RCPARMS control blocks. System action: All HSSR calls fall back to DL/I calls. All HSSR PCBs fall back to DL/I PCBs, and all calls issued against these PCBs are processed by DL/I action modules. Programmer response: Check whether High Performance Unload supports the active IMS release. FABH0346E DB-ACCESS NOT AUTHORIZED BY DBRC Explanation: This message is issued when High Performance Unload is running in ULU region type and when DBRC does not authorize access to the database. Notice that in ULU region types, the requested authorization is for database level sharing with read-integrity. System action: HSSR Engine ends abnormally. Programmer response: Resubmit the job at a time when DBRC can authorize access to the database. If the function of the job step is not an HD unload of the database, make sure that the program owner really wants to have the program executed in a ULU Region type. FABH0347E INVALID PSB OR DBD CONTROL-BLOCKS FOR FABHFSU Explanation: FABH010 detected a problem with a PSB or DBD control block during initialization. System action: HSSR Engine ends abnormally. Programmer response: Make sure correct PSBs and DBDs are used. FABH0348E INTERNAL ERROR OCCURRED IN HSSR CALL ANALYZER Explanation: HSSR call analyzer detected an unexpected error. System action: HSSR Engine ends abnormally. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0349E PSB HAS NO PCBS Explanation: The PSB provided has no PCBs. Therefore, the use of HSSR Engine is meaningless. System action: HSSR Engine ends abnormally. Programmer response: Correct the utility control statement or the PSB.

FABH0350W HSSR CALLS FALL BACK TO DL/I FOR [NAMED DBD|ALL DBDS] BECAUSE OF FOLLOWING PROBLEM IN DBD=dbdname Explanation: During the building of control blocks for the dbdname, HSSR Engine detected an abnormal situation. This situation is described by the next message. System action: All HSSR calls fall back to DL/I calls, either for the named DBD or for all DBDs. The corresponding PCBs fall back to DL/I PCBs. All calls issued against these PCBs are processed by DL/I action modules. Programmer response: If the fallback is done for all DBDs, the problem could be an unexpected layout of DL/I control blocks. See the accompanying messages issued by HSSR Engine. FABH0351W SYSTEM PERFORMANCE WILL SLOW DOWN, PLEASE INFORM YOUR IMS SPECIALISTS Explanation: This is a warning message to the operator. Because of an abnormal situation described in a preceding message, HSSR calls falls back to DL/I. Calls issued by application programs are processed by DL/I action modules instead of HSSR Engine. This might lead to degraded system performance. System action: The processing continues. Programmer response: Inform the IMS specialists. FABH0352E THE FALL BACK IS ABORTED BECAUSE HSSRSNAP DD IS NOT SPECIFIED Explanation: HSSR Engine detected an abnormal situation described in preceding messages, and attempted to issue a SNAP. However, the HSSRSNAP data set could not be opened, and the abnormal situation could not be documented with a SNAP. System action: Instead of issuing a SNAP, HSSR Engine ends abnormally with dump. Programmer response: To prevent an abend and allow the fallback to DL/I, the HSSRSNAP DD statement must be included in the JCL. If the SNAP output is not required, this data set can be defined as dummy.

420

Users Guide

FABH0353E FABH0362E
FABH0353E GET-BY-RBA CALL IS NOT SUPPORTED FOR THE PARTITIONED DB: DBD=xxxxxxxx Explanation: A Get-by-RBA call is issued for a partitioned database. The Get-by-RBA call is not supported for the partitioned database. System action: HSSR Engine ends abnormally. Programmer response: Modify your application program not to use the Get-by-RBA call, and rerun the job. See Get-by-RBA calls on page 330. FABH0354E REPL CALL IS NOT SUPPORTED FOR THE PARTITIONED DB: DBD=xxxxxxxx Explanation: An HSSR REPL call is issued for a partitioned database. The HSSR REPL call is not supported for the partitioned database. System action: HSSR Engine ends abnormally. Programmer response: Modify your application program not to use the HSSR REPL call, or replace the HSSR REPL calls with the DL/I REPL calls. FABH0355E DBRC REQUIRED FOR THIS EXECUTION Explanation: DBRC=N is specified for the job that runs in the ULU region and processes a HALDB. System action: HSSR Engine ends abnormally. Programmer response: Specify DBRC=Y and rerun the job. FABH0356E COMMAND CODE IS NOT SUPPORTED FOR HALDB DB: DBD=dbdname Explanation: A command code was specified in a get call for the HALDB database dbdname. Command codes cannot be used in a get call for HALDB databases. System action: HSSR Engine ends abnormally. Programmer response: Modify your application program so that no HSSR get call with a command code is to be used. FABH0357E UNSUPPORTED RELEASE OF DFP Explanation: The job is running under an unsupported release of MVS/DFP. The DFSMSdfp of DFSMS/MVS Version 1 Release 1 or later is necessary to run a High Performance Unload job. System action: HSSR Engine ends abnormally. Programmer response: Run the job under a DFSMSdfp environment that is supported by High Performance Unload. FABH0358E REPL CALL IS ISSUED FOR THE FOLLOWING HSSR PCB: FABH0358E [DBD=xxxxxxxx|DBD=xxxxxxxx (PARTITIONED)], PCB#=yyyy, PCBNAME=zzzzzzzz Explanation: The application program issues an HSSR REPL call for the HSSR PCB shown in the message. The HSSR REPL call is not supported in the IPR Unloads API function. The string xxxxxxxx shows the name of the DBD that the PCB refers to; the number yyyy shows the PCB number in the PSB; and the string zzzzzzzz shows the label, if there is one, of the PCB assigned at PSBGEN. If the database is partitioned, the string "(PARTITIONED)" is printed after the DBD name. System action: HSSR Engine ends abnormally. Programmer response: If the database is a partitioned database, you cannot issue any HSSR REPL calls for it. If it is not a partitioned database and you want to issue HSSR REPL calls for it, consider running the application program by using the API of High Performance Unload. FABH0360E INVALID STATEMENT IN HSSROPT DD HAS BEEN IGNORED Explanation: An HSSROPT control statement with an incorrect statement type was found. (HSSROPT control statements should begin in column 1 with a keyword defining the control statement.) System action: The incorrect control statement is ignored. Programmer response: Correct the control statement. FABH0361E INVALID KEYWORD ON TRHC STATEMENT WAS DETECTED Explanation: An undefined keyword is specified in the HSSROPT 'TRHC' control statement. System action: The incorrect keyword and the rest of the control statement are ignored. Programmer response: Correct the TRHC control statement. Problem determination: Only the following keywords are allowed: CALL, CB, CBX, BUF, BUFCB, and START=nnn. FABH0362E START KEYWORD ON TRHC STATEMENT SHOULD BE FOLLOWED BY A COMMA OR BLANK Explanation: An incorrect TRHC control statement is specified in the HSSROPT data set. The START=nnn

Chapter 28. Messages

421

FABH0363E FABH0371E
keyword should be followed by either a comma or a blank. System action: The START=nnn keyword and the rest of the control statement are ignored. Programmer response: Correct the TRHC control statement. FABH0363E INVALID START KEYWORD ON TRHC STATEMENT WAS DETECTED Explanation: An incorrect TRHC control statement is specified in the HSSROPT data set. The counter in the keyword START=nnn was either longer than 16 bytes or shorter than 1 byte. System action: The START=nnn keyword and the rest of the control statement are ignored. Programmer response: Correct the TRHC control statement. FABH0364E INVALID TRXC STATEMENT HAS BEEN IGNORED Explanation: An incorrect TRXC control statement is specified in the HSSROPT data set. The following errors are possible: v The number of core trace entries is not followed by a blank. v The length of the field containing the number of entries is longer than 16 bytes. System action: The TRXC control statement is ignored. Programmer response: Correct the TRXC control statement. FABH0365E INVALID BUF STATEMENT HAS BEEN IGNORED Explanation: An incorrect BUF control statement is specified in the HSSROPT data set. The following errors are possible: v The 8-byte DBD name was not followed by a blank or a comma. v The number of buffers was not followed by a blank. v The length of the field containing the buffer number was either longer than 16 bytes or shorter than 1 byte. System action: The BUF control statement is ignored. Programmer response: Correct the BUF control statement. FABH0366E INVALID DBSTATS STATEMENT HAS BEEN IGNORED Explanation: An incorrect DBSTATS control statement is specified in the HSSROPT data set. System action: The incorrect DBSTATS control statement is ignored. Programmer response: Correct the DBSTATS control statement. FABH0368E INVALID RETRY STATEMENT HAS BEEN IGNORED Explanation: An incorrect RETRY control statement is specified in the HSSROPT data set. Bytes 710 should contain KSDS. System action: The incorrect RETRY control statement is ignored. Programmer response: Correct the RETRY control statement. FABH0369E INVALID KEYWORD ON GOTRETRY STATEMENT WAS DETECTED Explanation: An undefined keyword in the GOTRETRY control statement is specified in the HSSROPT data set. Only the following keywords are permitted: NBR= WAIT= System action: The incorrect keyword and the rest of the control statement are ignored. Programmer response: Correct the GOTRETRY control statement. FABH0370E RETRY NUMBER EXCEEDS MAXIMUM VALUE Explanation: An incorrect GOTRETRY control statement is specified in the HSSROPT data set. The number of times that HSSR Engine should reaccess the database is too high; it should not exceed 999. System action: The incorrect NBR= keyword and the rest of the control statement are ignored. Programmer response: Correct the GOTRETRY control statement. FABH0371E WAIT TIME EXCEEDS MAXIMUM VALUE Explanation: An incorrect GOTRETRY control statement is specified in the HSSROPT data set. The number of seconds that HSSR Engine should wait before reaccessing the database is too high; it should not exceed 999 seconds. System action: The incorrect WAIT= keyword and the

422

Users Guide

FABH0372E FABH0381E
rest of the control statement are ignored. Programmer response: Correct the GOTRETRY control statement. FABH0372E NUMERIC FIELD SHOULD BE FOLLOWED BY A COMMA OR BLANK Explanation: An incorrect control statement is specified in the HSSROPT data set. System action: The incorrect numeric field and the rest of the control statement are ignored. Programmer response: Correct the control statement in the HSSROPT data set. FABH0373E NUMERIC FIELD IS TOO LONG Explanation: An incorrect control statement is specified in the HSSROPT data set. System action: The incorrect numeric field and the rest of the control statement are ignored. Programmer response: Correct the control statement in the HSSROPT data set. FABH0374E INVALID SKERROR STATEMENT HAS BEEN IGNORED Explanation: An incorrect SKERROR control statement is specified in the HSSROPT data set. System action: The incorrect statement is ignored. Programmer response: Correct the SKERROR statement. FABH0375E INVALID KEYCHECK STATEMENT HAS BEEN IGNORED Explanation: An incorrect KEYCHECK control statement is specified in the HSSROPT data set. System action: The incorrect statement is ignored. Programmer response: Correct the KEYCHECK statement. FABH0376E INVALID KEYWORD ON DIAGG STATEMENT WAS DETECTED Explanation: An undefined keyword on the DIAGG control statement is specified in the HSSROPT data set. System action: The incorrect keyword and the rest of the control statement are ignored. Programmer response: Correct the DIAGG statement. FABH0377E INVALID CABSTAT CONTROL STATEMENT IS SPECIFIED Explanation: An incorrect operand on the CABSTAT control statement is specified in the HSSROPT data set. The operand must be either "YES" or "NO". System action: The incorrect statement is ignored. Programmer response: Correct the CABSTAT statement. FABH0378W DATXEXIT YES IS IGNORED BECAUSE OF IMS LEVEL Explanation: 'DATXEXIT YES' is specified in the HSSROPT data set, but HSSR Engine is running in an IMS environment, where the Data Conversion exit is not supported. System action: The 'DATXEXIT YES' option is ignored, and processing continues with 'DATXEXIT NO'. Programmer response: Check whether an appropriate IMS load module library is specified for your job. If you do not need to use a Data Conversion exit routine, remove the 'DATXEXIT YES' statement. FABH0379E AN INVALID OPERAND IS SPECIFIED FOR THE PARTINFO CONTROL STATEMENT Explanation: Either an invalid parameter is specified or no parameter is specified for the PARTINFO statement in HSSROPT DD. For the details of the PARTINFO control statement, refer to Chapter 8. System action: The statement is ignored and the processing continues. Programmer response: Correct the error and, if necessary, rerun the job. FABH0380W BUFFER TRACE WILL NOT BE TAKEN FOR HALDB: dbdname Explanation: The buffer trace for the HALDB whose DBD name is indicated in the message will not be taken. System action: HSSR Engine continues processing. Programmer response: If you want to suppress the message, remove the BUTR control statement from the HSSROPT data set. FABH0381E DBD IS NOT A PHYSICAL DBD Explanation: Because of PSBGEN specifications, HSSR Engine tried to build an HSSR PCB referring to a logical DBD. Logical databases are not supported by HSSR Engine. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a
Chapter 28. Messages

423

FABH0382E FABH0388E
DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Change the PCB as follows: Specify the name of the physical DBD, or do not specify the PCB as an HSSR PCB. FABH0382E SEGMENT CODE IN SDBS ARE NOT ASCENDING Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0383E SEGMENTS ARE NOT ALL IN SAME DATABASE Explanation: Because of PSBGEN specifications, HSSR Engine tried to build an HSSR PCB. However, the sensitive segments are not all in the same physical database. HSSR Engine does not support sensitive segments in multiple databases. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Change PSBGEN as follows: Remove the problematic SENSEG statements causing the problem, or do not specify the PCB as an HSSR PCB. FABH0384I PROCSEQ=indexdbd IS SPECIFIED IN PCB#=nnn FABH0385E JCB POINTERS TO SDBS NOT OK Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0386E MORE THAN 10 DATA SET GROUPS NOT SUPPORTED Explanation: Neither IMS nor HSSR Engine supports HD databases with more than 10 data set groups. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Change the PCB as follows: Specify the name of the physical DBD, or do not specify the PCB as an HSSR PCB. FABH0387E DMB POINTERS TO PSDBS OR AMP NOT OK Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0388E UNSUPPORTED DBD: IMS/ESA PARTITION SUPPORT PRODUCT Explanation: Because of PSBGEN specifications, an HSSR PCB was tried to be built. However, the IMS/ESA

Explanation: The secondary index indexdbd is specified by the PROCSEQ= parameter in the PCB. nnn shows the PCB number. HSSR Engine uses the secondary index to retrieve the root segments. System action: HSSR Engine continues the processing. Programmer response: None.

424

Users Guide

FABH0389E FABH0394E
Partition Support Product is not supported by HSSR Engine. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Modify the database organization, or do not specify the PCB as an HSSR PCB. FABH0389E MORE SDBS THAN PSDBS Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0390E LENGTH OF PSDBS NOT OK Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0391E SEGMENT CODE OF PSDBS NOT ASCENDING Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Verify that the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements, and perform the PSBGEN again. FABH0392E SECONDARY LIST OF LP NOT FOUND Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements, and perform the PSBGEN again. FABH0393E SDBPSDB DOES NOT POINT TO PSDB Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements, and perform the PSBGEN again. FABH0394E NUMBER OF DSGS CALCULATED FROM MASTER DMB IS UNEQUAL TO THE NUMBER CALCULATED FROM DMB FOR PARTITION ppppppp Explanation: The number of DSGROUPs calculated from the master DMB of the HALDB for which the partition ppppppp is defined is not equal to the number of DGGROUPs calculated from the partition DMB of the partition. System action: HSSR Engine issues a SNAP for this
Chapter 28. Messages

425

FABH0395E FABH0404E
PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0395E PREFIX SIZE IN PSDB NOT OK Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements, and perform the PSBGEN again. FABH0396E SENSITIVE VIRTUAL LOGICAL CHILD (segmname) IS FOUND IN PCB#=nnnn Explanation: A sensitive virtual logical child segment segmname is found in the HSSR PCB. nnnn shows the PCB number. HSSR Engine does not support sensitive virtual logical child segment. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: If you do not need to retrieve the virtual logical child segment, specify the SKIPVLC YES option in the HSSROPT data set. FABH0397E UNSUPPORTED DATABASE ORG Explanation: Because of PSBGEN specifications, an HSSR PCB was tried to be built. However, the organization of the referred-to DBD is not supported by HSSR Engine. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Modify the database organization, or do not specify the PCB as an HSSR PCB. FABH0398E INDEX DMB NOT FOUND Explanation: Because of PSBGEN specifications, an HSSR PCB referring to a logical DBD was tried to be built. Logical databases are not supported by HSSR Engine. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Change the PCB as follows: Specify the name of the physical DBD, or do not specify the PCB as an HSSR PCB. FABH0400I VIRTUAL LOGICAL CHILD SEGMENT (segmname) IS IGNORED

Explanation: HSSR Engine ignores the virtual logical child segment segmname that is specified in the HSSR PCB. In the DLI or the DBB region, the SKIPVLC YES option is used. In the ULU region, it is always ignored. System action: HSSR Engine continues the processing. Programmer response: If you need the virtual logical child to be retrieved in a user application program, specify the SKIPVLC NO control statement. The PCB will be passed to IMS DL/I and the virtual logical child segment will be retrieved. FABH0403E SEC LIST FOR INDEXED-SEGM NOT FOUND Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0404E PCB WITH FIELD SENSITIVITY NOT SUPPORTED Explanation: Because of PSBGEN specifications, an HSSR PCB for which field sensitivity has been specified was tried to be built. Field sensitivity is not supported by HSSR Engine. System action: HSSR Engine issues a SNAP for this

426

Users Guide

FABH0405E FABH0416E
PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Either remove field sensitivity specifications for this PCB, or do not specify the PCB as an HSSR PCB. FABH0405E INDEX DMB dbdname IS NOT FOUND Explanation: The DMB for the primary or secondary index DBD dbdname cannot be found in the DMB directories. System action: HSSR Engine ends abnormally. Programmer response: Check whether the specified index DBD has the index relationships with the database to be unloaded. FABH0406E INDEX DBD dbdname IS NOT SUPPORTED Explanation: The specified secondary index dbdname is not supported due to one of the following reasons: v The DB organization is not INDEX. v The target DB organization is not HIDAM or HDAM. v The target segment is not the root segment. v The key field is not defined as unique. v The secondary index uses symbolic pointing. System action: HSSR Engine ends abnormally. Programmer response: Change or remove the index DBD name. FABH0407E DMB dbdname IS NOT CORRECT Explanation: HSSR Engine detected an incorrect or unexpected DL/I control block layout in the dbdname DMB. System action: HSSR Engine ends abnormally. Programmer response: Contact IBM Software Support. FABH0411E SEGMENT CODE IN SDB AND HSDB DISAGREE Explanation: One of the following two problems occurred: 1. During PSBGEN, the SENSEG statements were not coded in the same hierarchical sequence as in the DBD. 2. HSSR Engine detected an incorrect or unexpected DL/I control block layout. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is in the same as the DBD; if not, correct the sequence of the SENSEG statements, and perform the PSBGEN again. FABH0412E VIRTUAL PAIRED SEGMENTS NOT SUPPORTED Explanation: Because of PSBGEN specifications, an HSSR PCB containing a sensitive logical child that is virtually paired. Virtually paired segments are not supported by HSSR Engine. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Modify the virtually paired segment to, for example, a physically paired segment, or remove the SENSEG statement of the virtually paired segment from the PCB, or do not specify the PCB as an HSSR PCB. FABH0413E INVALID SEGMENT SENSITIVITY FOR AN HSSR PCB Explanation: Because of PSBGEN specifications, an HSSR PCB was tried to be built. This PCB contains a SENSEG statement whose PROCOPT is neither G nor K. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Modify the PROCOPT field of the SENSEG statement, or do not specify the PCB as an HSSR PCB. FABH0415E SOMETHING WRONG WITH NUMBER OF HPTRS Explanation: HSSR Engine has problems with its own control blocks. System action: HSSR Engine issues a SNAP and falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements, and perform the PSBGEN again. FABH0416E SOMETHING WRONG WITH NUMBER OR LENGTH OF HSDB Explanation: HSSR Engine has problems with its own control blocks. System action: HSSR Engine issues a SNAP and
Chapter 28. Messages

427

FABH0420W FABH0425E
falls back to DL/I for all PCBs. All PCBs are defined as DL/I PCBs and all calls are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0420W WARNING: SEGMENT segname HAS A VIRTUAL LOGICAL PARENT KEY Explanation: The logical parents concatenated key (LPCK) of the segment segname is defined as virtual, but the BLDLPCK control statement is not specified. Note: During retrieval operations, the part of the I/O area that should contain the logical parent key will contain blanks. System action: HSSR Engine continues processing. Programmer response: If the control statements for the pre-reorganization utility specified DBIL for the logical child database, and the database is unloaded by FABHURG1 or FABHFSU, you must specify the BLDLPCK control statement. In other cases, you need not specify BLDLPCK. If you need LPCKs to be built, specify the BLDLPCK control statement and rerun the job. FABH0421E REPLACE PROCOPT NOT SUPPORTED FOR DB-ORGANIZATION OF DB=dbdname Explanation: HSSR Engine supports the replace processing option only for HIDAM and HDAM databases. The database (named dbdname) has another organization. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Modify the PSB and do not define the PCB as an HSSR PCB. FABH0422E REPLACE PROCOPT NOT SUPPORTED FOR BLOCK-LEVEL SHARED DB=dbdname Explanation: HSSR Engine does not support the replace processing option for databases (named dbdname) that are shared at the block level. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Investigate to specify IRLM=N on the JCL procedure in order to run in a database-level sharing environment instead of a FABH0424E REPLACE PROCOPT NOT SUPPORTED FOR INDEX-SOURCE SEGMENT-TYPE=segname Explanation: HSSR Engine does not support the replace processing option for segment types (named segname) that are index-source segments and not root segments. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Check whether the sequence of the SENSEG statements in the PSBGEN is in the same as in the DBD; if not, correct the sequence of the SENSEG statements and perform the PSBGEN again. FABH0425E REPLACE PROCOPT NOT SUPPORTED WITH VIRTUAL LP-KEY, SEGMENT-TYPE=segname Explanation: Because the BLDLPCK control statement is not specified, HSSR Engine cannot perform the replace processing for the segment segname, which is a logical child whose logical parents concatenated key (LPCK) is defined as virtual. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: If you need REPLACE processing for the segment type, specify the BLDLPCK control statement. If you do not need REPLACE processing, modify the PSB; either specify PROCOPT=G on the SENSEG of the named segment type, or do not define the PCB as an HSSR PCB. block-level sharing environment. Otherwise, modify the PSB, and do not define the PCB as an HSSR PCB. FABH0423E REPLACE PROCOPT NOT SUPPORTED FOR PHYSICAL PAIRED SEGMENT=segname Explanation: HSSR Engine does not support the replace processing option for segment types (named segname) that are physically paired logical children. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Modify the PSB. Either specify PROCOPT=G on the SENSEG of the named segment type or do not define the PCB as an HSSR PCB.

428

Users Guide

FABH0426E FABH0451E
FABH0426E OTHER PCBS MAY NOT HAVE AN UPDATE PROCESSING OPTION, SEGMENT-TYPE=segname Explanation: The segment type (named segname) has a replace processing option in an HSSR PCB. This allows update processing options in another HSSR PCB or DL/I PCB of the PSB. System action: HSSR Engine issues a SNAP for this PCB and falls back to DL/I. The PCB is defined as a DL/I PCB, and all calls issued against it are processed by DL/I action modules. Programmer response: Modify the PSB in order to observe the restrictions. FABH0430W DB WILL BE READ BY HSSR WITHOUT READ-INTEGRITY Explanation: The application program is reading a database that is shared at the block level. The PSBGEN processing option specifies an access intent (read or update access intent) requesting full read-integrity. However, HSSR Engine does not have an interface to the IRLM to provide full read-integrity. System action: HSSR Engine continues processing and reads the database without read-integrity. The database is processed with read-only processing intent. Unpredictable results may occur. Programmer response: If the application program requires read-integrity, the database should be shared at the database level (instead of the block level). This will prevent concurrent execution with an updating IMS subsystem. FABH0431W WARNING: RBN VALUE IN DBDGEN (RMNAME=KEYWORD) IS LARGER THAN DB-DATASET SIZE Explanation: The RBN value in the RMNAME keyword is used during DBDGEN to define the size of the HDAM root addressable area. HSSR Engine detected that the size of the root addressable area is larger than the effective size of the database data set (as defined by the high-used-block). This may be due to one of the following two conditions: 1. The High Performance Unload job has been run with a wrong DBD. FABH0451E SKIP-COUNT EXHAUSTED Explanation: HSSR Engine detected more GG status code situations than the number that was specified on the HSSROPT SKERROR control statement. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take the appropriate action. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was
Chapter 28. Messages

addressable area and produce erroneous results. If this is the case, correct the RBN value. FABH0432W THE SIZE OF PRIMARY DATA SET IS LESS THAN THE DEFINED RAA SIZE (partname, hbn) Explanation: HSSR Engine detected a size of the primary data set of the PHDAM partition partname which is less than the size of the root addressable area (RAA). The value hbn shows the number that has been specified as the high block number, which determines the RAA size. (The high block number is specified by use of the HALDB Partition Definition Utility.) System action: HSSR Engine continues processing. Programmer response: Check whether the correct DBD and RECON data sets are specified for the job. FABH0433W RBN VALUE IS LARGER THAN THE SIZE OF THE PARTITION DATA SET (DDNAME: ddname) Explanation: HSSR Engine detected that the RBN value defined in the DBD for the partition data set was larger than the real data set size. ddname indicates the DD name of the partition data set. System action: HSSR Engine continues processing. Programmer response: Check whether the correct DBD is specified. Specify the correct DBD, and rerun the job. FABH0441E STATISTIC PRINTER GOT INVALID CALL Explanation: HSSR Engine detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take the appropriate action. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred.

2. "Normal situation." This message can be issued, even in a normal situation, if the root addressable area has not been completely formatted (for example, if the user has not stored a root segment that is to be randomized to the last cylinder of the root addressable area). System action: HSSR Engine continues processing. Programmer response: Check whether the correct DBD is used. If a wrong DBD is used, HSSR Engine may interpret an overflow block as a block of the root

429

FABH0452W FABH0471E
being updated at the time when the error occurred. FABH0452W HSSR CALL HANDLER RETURNS FIRST GG STATUS CODE Explanation: HSSR call handler returned a GG status code to the calling application program or utility program. This is a warning. System action: The processing continues. Programmer response: See Problem Determination, and take an appropriate action. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0453E UNEXPECTED ENTRY INTO FABH080 Explanation: HSSR Engine detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0457E HSSR DETECTED AN UNEXPECTED ERROR SITUATION Explanation: HSSR Engine detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0461E COMPARE OPTION HAS DETECTED AN INEQUALITY BETWEEN HSSR AND DL1 Explanation: This message is issued when the CO control statement is specified in the HSSROPT data set, and the results of an HSSR call and the corresponding DL/I call are not the same. System action: HSSR Engine ends abnormally. Programmer response: If PROCOPT=R is specified for a VSAM database, make sure VSAM SHAREOPTIONS are defined (2,3) or (3,3). See Problem Determination, and take an appropriate action. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0462E THE PARTITIONS SELECTED BY HSSR AND DL/I ARE UNEQUAL; HSSR-PID=xxxx (NAME: xxxxxxx), DL/I-PID=xxxx (NAME: xxxxxxx) Explanation: This message is issued when the CO control statement is specified in the HSSROPT data set, and HSSR call handler detected a difference between the partition IDs selected by HSSR call handler and DL/I (IMS) in an HSSR call. System action: HSSR Engine ends abnormally. Programmer response: Check the HSSR Engine trace report to see the difference; and contact IBM Software Support. FABH0463E HSSR REACHED THE END OF THE PARTITION ppppppp EARLIER THAN DL/I Explanation: This message is issued when the CO control statement is specified in the HSSROPT data set, and HSSR call handler reaches the end of the partition ppppppp earlier than DL/I detects it. System action: HSSR Engine ends abnormally. Programmer response: Contact IBM Software Support. FABH0465E AN UNSUPPORTED HSSR CALL WAS ISSUED FOR NON-HD DATABASE xxxxxxxx Explanation: An unsupported HSSR call was issued for the non-HD database xxxxxxxx. Only the call types defined by APISET 1 are supported for non-HD databases. Any API set other than APISET 1 can be specified in HSSROPT or in the site default option table, but it is ignored for non-HD databases. System action: HSSR Engine ends abnormally. Programmer response: If you want to use a call that is not supported by HSSR Engine, modify the application program, or use the DBDL1 control statement. FABH0471E OPEN OF DDNAME=HSSRBUTR HAS FAILED Explanation: An HSSROPT BUTR control statement instructed HSSR Engine to activate the machine-readable trace of buffer handler activities. This trace is written on the HSSRBUTR data set. HSSR Engine cannot open this file. System action: HSSR Engine ends abnormally.

430

Users Guide

FABH0473E FABH0484E
Programmer response: Check whether MVS or SAM issued other error messages. Correct the problem. FABH0473E INTERNAL ERROR OCCURRED IN HSSR CALL HANDLER FABH0475E INTERNAL ERROR OCCURRED IN HSSR CALL HANDLER FABH0477E INTERNAL ERROR OCCURRED IN HSSR CALL HANDLER Explanation: HSSR call handler detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0479E INTERNAL ERROR OCCURRED IN HSSR BUFFER HANDLER Explanation: HSSR buffer handler detected an unexpected error. Programmer response: See Problem Determination and take an appropriate action. If necessary, contact IBM Software Support. Problem determination: Check whether the correct DBDs, PSBs, and ACBs are being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0480E INVALID DATABASE ORGANIZATION Explanation: HSSR Engine detected a request for a GU call for a database whose organization is not supported by HSSR. System action: HSSR Engine ends abnormally. Programmer response: See Database organizations supported on page 16 for a list of supported database organizations. Correct the application program and DBD. FABH0481E INVALID PARAMETER NUMBER IN CALL Explanation: The application program issued an HSSR call with an incorrect number of parameters (too few or too many). The HSSR call handler does not support three or more SSAs. The unsupported call is printed in the Trace output report in the HSSRTRAC data set. System action: If APISET is 2, HSSR Engine ends abnormally. If APISET is 3, the call and all the succeeding calls to the HSSR PCB are passed to the IMS DL/I call handler to continue the processing instead of ending it abnormally. Programmer response: If APISET is 2, specify APISET 3 in the control statement. If APISET is 3, ignore this message. Problem determination: The following parameters are required for Assembler and COBOL programs: Call function PCB I/O AREA SSA (optional) The following parameters are required for PL/I programs: PARM count Call function PCB I/O AREA SSA (optional) FABH0482E INCORRECT CALL FUNCTION Explanation: The application program issued an HSSR call with an incorrect call function. Only GU and GN are supported. System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. FABH0483E INCORRECT SEGMENT NAME IN SSA Explanation: The application program issued an HSSR GU call with an incorrect segment name in the SSA. The segment name should be the name of the root segment. (For RBA calls, the segment name should be the name of a sensitive segment.) System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. If there is no error, check whether the correct APISET statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0484E INCORRECT FIELD NAME IN SSA Explanation: The application program issued an HSSR GU call with an incorrect field name in the SSA. The field name should be the name of the key field of the root. System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. If there is no error, check whether the correct APISET statement is specified. For details about the call types
Chapter 28. Messages

431

FABH0485E FABH0491E
and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0485E LEFT PARENTHESIS IN SSA IS MISSING OR AT WRONG POSITION Explanation: The application program issued an HSSR GU call with an incorrect SSA. System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. If there is no error, check whether the correct APISET statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. Problem determination: The 8-byte segment name should be immediately followed by a ( or by *T). GUs with unqualified SSAs are not supported by HSSR call handler; the only supported command code is T. FABH0486E RELATIONAL OPERATOR IN SSA IS INCORRECT Explanation: The application program issued an HSSR GU call with an incorrect relational operator in the SSA. System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. If there is no error, check whether the correct APISET statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. Problem determination: Only the following relational operators are supported: b= =b EQ => >= GE where b represents a required blank. FABH0487E RIGHT PARENTHESIS IN SSA IS MISSING OR AT WRONG POSITION Explanation: The application program issued an HSSR GU call with an incorrect SSA. System action: HSSR Engine ends abnormally. Programmer response: Correct the error. If there is no error, check whether the correct APISET statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. Problem determination: The key value field or the RBA should be immediately followed by the right parenthesis. (Boolean operators are not supported by HSSR Engine.) FABH0488E DB ORG IS NOT HIDAM OR HDAM Explanation: The application program issued an RBA call to a database that is neither HIDAM nor HDAM. RBA calls can be issued only against HIDAM or HDAM databases. System action: HSSR Engine ends abnormally. Programmer response: Correct the program error. FABH0489E UNSUPPORTED COMMAND CODE Explanation: The application program issued a call with a command code that is not supported by HSSR call handler. HSSR call handler supports only the "T" and "NULL" command codes. System action: HSSR Engine ends abnormally. Programmer response: Specify APISET 3. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0490E SEGMENT CODE OF RETRIEVED RBA IS NOT THE SEGMENT CODE OF REQUESTED SEGMENT Explanation: The application program issued an RBA call. The SSA specified a segment name and an RBA. The database does not contain a segment of the specified segment type at the specified RBA. System action: HSSR Engine ends abnormally. Programmer response: Find the reason for this error. (It may be a program error). Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. Activate the compare option and the hard-copy trace option. Re-execute the failing call sequence. FABH0491E REQUESTED RBA NOT IN DATA SET Explanation: The application program issued an RBA call. The SSA specified an RBA. However, the specified RBA is not within the extents of the data set. System action: HSSR Engine ends abnormally. Programmer response: Find the reason for this error. It can be a program error. Problem determination: Check whether the correct

432

Users Guide

FABH0492E FABH0505E
DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. Activate the compare option, the hard-copy trace option, and re-execute the failing call sequence. FABH0492E ROOT HAS NO SEQUENCE FIELD Explanation: The application program issued an HSSR GU call with a qualified SSA for the root segment. HSSR call handler supports only qualification on the sequence field and assumes that the SSA is qualified on the Root Sequence Field. However, during DBDGEN, the root is defined without sequence field. System action: HSSR Engine ends abnormally. Programmer response: Either remove the GU call from the program, or have the DB administrator define a sequence field for the root segment. If there is no error, check whether the correct APISET statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0499E INTERNAL ERROR OCCURRED IN HSSR CALL HANDLER Explanation: HSSR call handler detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0501E DATA SET GROUP NUMBER NOT POSITIVE Explanation: The buffer handler was invoked with an incorrect data set group number. The data set group number should have been positive. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0502E DATA SET GROUP NUMBER DOES NOT EXIST Explanation: The buffer handler was invoked with an incorrect data set group number. The specified data set group number does not exist. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0503E PCB IS NOT SENSITIVE TO ANY SEGMENT OF SPECIFIED DATA SET GROUP Explanation: The buffer handler is invoked with an incorrect data set group number. No segment of the specified data set group is sensitive. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0504E NO OSAM/ESDS IN DATABASE Explanation: The buffer handler was invoked to handle a data set that was not OSAM or ESDS. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. FABH0505E RBA NOT WITHIN SPECIFIED DATA SET Explanation: The buffer handler was invoked with an incorrect RBA. The RBA is not within the extents of the data set. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred.

Chapter 28. Messages

433

FABH0506E FABH0517E
FABH0506E BUFFER HANDLER IO-ERROR Explanation: The buffer handler has encountered an I/O error. Other error messages will describe the problem in detail. System action: HSSR Engine ends abnormally. Programmer response: Check system error messages. FABH0507E INVALID SUBTYPE OF *Z COMMAND CODE Explanation: The internal HSSR call with the *Z command code has an incorrect format. HSSR Engine generates this undocumented call to start retrieval from an HDAM database at a specific relative block number. For example, the FABHFSU BLM control statement might specify retrieval by RBN causing HSSR Engine to generate this command. System action: HSSR Engine ends abnormally. Programmer response: Contact IBM Software Support. FABH0511E POINTER IN INDEX TO ROOT-SEGMENT IS ZERO Explanation: During a call against an HIDAM database, HSSR Engine must retrieve a primary index record in order to locate the root segment. The index pointer record contained zero instead of a root pointer. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0512E INVALID RETURN-CODE FROM BUFFER-HDLR Explanation: HSSR Engine encountered an I/O problem. For more information, see the accompanying SYNADAF message buffer. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0513E SEGMENT-CODE NOT 01 Explanation: HSSR call handler retrieved a root segment whose segment code was not 01. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0515E CANNOT POSITION THE FIRST SEGMENT IN THE DB Explanation: During unloading an HIDAM or PHIDAM DB, HSSR Engine retrieved a primary index record in order to locate the first database position. In this process, HSSR Engine detected an incorrect situation where the delete byte in the index record was not X'5A' nor X'EA' nor X'F2' although the delete byte in the corresponding database record was X'5A', X'EA', or X'F2'. System action: HSSR Engine ends abnormally. Programmer response: Check the delete byte of the first root segment and correct it. Problem determination: None. FABH0516E LAST SEGM IN PRIMARY INDEX DOES NOT POINT TO SEGMENT WITH A KEY OF ALL X'FF'S Explanation: The last pointer segment in the primary index for HIDAM or PHIDAM points to a root segment with a key that is not all X'FF's. The database can be corrupted. System action: HSSR Engine ends abnormally. Programmer response: Check whether the database is corrupted. If it is not, check whether the correct pair of primary index data set and the primary data set was used. Problem determination: None. FABH0517E HSSR CALL HANDLER DETECTED UNEXPECTED ERROR SITUATION Explanation: HSSR call handler detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check

434

Users Guide

FABH0521E FABH0541E
whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0521E POINTER DESCRIBED BY HSDB1-HPTR1 IS NOT A ROOT-TWINPOINTER Explanation: HSSR control blocks contain incorrect information. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options. Execute the failing call sequence with the FABHTEST program. FABH0523E SEGMENT-CODE OF LOCATED SEGMENT NOT 01 Explanation: HSSR call handler retrieved a root segment whose segment code is not 01. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0524E BLM BLOCK-NUMBER NOT WITHIN RAA Explanation: An HDAM segment beyond the root addressable area was tried to be retrieved. System action: HSSR Engine ends abnormally. Programmer response: Correct BLM control statement on the FABHFSU CARDIN data set. FABH0525E RETURN CODE 8 FROM HDAM RANDOMIZER, RMOD=xxxxxxxx Explanation: HSSR Engine received a return code 8 from HDAM randomizing module. xxxxxxxx is the name of HDAM randomizing module. System action: HSSR Engine ends abnormally. Programmer response: Correct the application program or HDAM randomizing module, and rerun the job, if necessary. FABH0526E RETURN CODE 8 FROM RANDOMIZER: DBFxxxxx Explanation: HSSR Engine received the return code of 8 from the randomizing module DBFxxxxx. DBFxxxxx is a randomizing module that has the DEDB randomizer interface. System action: HSSR Engine ends abnormally. Programmer response: Correct the application program or the randomizing module, and rerun the job. FABH0527E INVALID PARTITION NUMBER 'xxxxxxxx' RETURNED FROM THE RANDOMIZER: DBFyyyyy Explanation: HSSR Engine received an incorrect partition number 'xxxxxxxx' from the randomizing module DBFyyyyy. 'xxxxxxxx' indicates the value contained in Register 1 in hexadecimal format. DBFyyyyy is a randomizing module that has the DEDB randomizer interface. System action: HSSR Engine ends abnormally. Programmer response: Correct the application program or the randomizing module, and rerun the job. FABH0528E INVALID RELATIVE RAP NUMBER 'xxxxxxxx' FOR PART#:nnn RETURNED FROM RANDOMIZER: DBFyyyyy Explanation: HSSR Engine received an incorrect relative RAP number 'xxxxxxxx' from the randomizing module DBFyyyyy. 'xxxxxxxx' indicates the value contained in Register 0 in hexadecimal format. DBFyyyyy is a randomizing module that has the DEDB randomizer interface. System action: HSSR Engine ends abnormally. Programmer response: Correct the application program or the randomizing module, and rerun the job. FABH0541E SEGMENT CODE OF ROOT NOT 01 Explanation: HSSR Engine retrieved a root segment whose segment code was not 01. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program.

Chapter 28. Messages

435

FABH0547E FABH0557W
FABH0547E INVALID RETURN CODE FROM BUFFER HANDLER Explanation: HSSR Engine encountered an I/O problem. For more information, see the accompanying SYNADAF message buffer. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0551E INVALID S-C OR D-F IN SPLIT DATA SEGM Explanation: During the processing of a variable length split segment, HSSR Engine encountered an incorrect segment code, or an incorrect delete flag. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0552E INVALID RC FROM BUF HDLR Explanation: HSSR Engine encountered an I/O problem in getting the split up segment data. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate COMPARE option and the hard-copy trace options, and run the failing call sequence with the FABHTEST program. FABH0553E USER COMPRESSION ROUTINE HAS RETURNED A TOO LONG SEGMENT Explanation: A user segment compression/ decompression exit routine has edited a segment longer than the maximum length defined during DBDGEN for that segment type. System action: HSSR Engine ends abnormally. Programmer response: Correct either the DBD or the user compression/decompression exit routine. FABH0554E SEGMENT ssssssss IN DATA BASE dddddddd HAS INVALID VALUE FOR THE LENGTH FIELD Explanation: During the processing of a segment, HSSR Engine encountered a segment for which the length field contained a value that was incorrect. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0555E KEYCHECK OPTION HAS DETECTED A SEQUENCE ERROR; ABEND FOLLOWS Explanation: HSSR Engine detected a sequence error in the segment key fields and issued an abend as specified by the KEYCHECK option. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0556E AN OCCURRENCE OF SEGMENT segmname IN DBD dddddddd OVER THE BLOCK BOUNDARY Explanation: HSSR Engine detects an incorrect occurrence of the segment segmname, which is stored over the block boundary. If it is a fixed-length segment, the segment length which is defined in the DBD dddddddd can be inconsistent with the actual segment. System action: HSSR Engine ends abnormally. Programmer response: Check whether the specified DBD is same as one used for inserting the segment. Problem determination: Register 6 contains the address of the segment data, register 5 contains the segment length which is defined in DBD, and register 7 contains the address of the block boundary. FABH0557W HSSR CALL HANDLER RETURNS FIRST GX STATUS CODE Explanation: HSSR call handler returned a GX status code to the calling application program or utility program because a sequence error was detected. The KEYCHECK option is active. The segment with the incorrect key was returned to the calling programs.

436

Users Guide

FABH0559E FABH0565E
System action: The processing continues. Programmer response: None. FABH0559E INTERNAL ERROR OCCURRED IN HSSR CALL HANDLER Explanation: HSSR call handler detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0560E STATUSCODE=xx ENCOUNTERED DURING INTERNAL ASMTDLI CALL Explanation: In order to build a logical parents concatenated key (LPCK) that is defined as virtual, HSSR internally issued an IMS GU call. But the unexpected status code of xx was returned. This is probably due to either an HSSR Engine or an IMS software error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. If necessary, contact IBM Software Support. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were used. Check whether the database processed by HSSR Engine was being updated by another application program at the time when the error occurred. FABH0561E REPL CALL WITHOUT REPLACE PROCESSING OPTION Explanation: The application program issued an HSSR REPL call. However, during PSBGEN, the PCB or SENSEG was not defined with a PROCOPT=R. System action: HSSR Engine ends abnormally. Programmer response: Correct either the program or the PSBGEN. FABH0562E REPL CALL WITHOUT IOAREA Explanation: The application program issued an HSSR REPL call without providing an IOAREA as a call parameter. System action: HSSR Engine ends abnormally. Programmer response: Correct the program. FABH0563E REPL CALL WITH SSA Explanation: This message is issued when either of the following occurs: v The application program issued an HSSR REPL call with an SSA as call parameter. HSSR Engine supports only REPL calls without an SSA. v The application program issued an HSSR REPL call as an EXEC DLI command. HSSR Engine does not support the REPL command. System action: HSSR Engine ends abnormally. Programmer response: Correct the program. If there is no error, check whether the correct APISET statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0564E STATUSCODE=xx ENCOUNTERED DURING INTERNAL GHU ASMTDLI CALL Explanation: During the processing of a GHU call, HSSR Engine issues internally an IMS GHU call; this internal IMS GHU call has returned an unexpected xx status code that is displayed in the message. System action: HSSR Engine ends abnormally. Programmer response: If the status code is AI, check for an IMS error message that describes the problem in more detail. If PROCOPT=R for a VSAM database, make sure VSAM SHAREOPTIONS are defined (2,3) or (3,3). If the status code is not AI, the problem may be either an HSSR or IMS software error. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0565E STATUSCODE=xx ENCOUNTERED DURING INTERNAL REPL ASMTDLI CALL Explanation: During the processing of a replace call, HSSR Engine issues internally an IMS REPL call; this internal IMS REPL call has returned an unexpected xx status code, which is displayed in the message. This is probably either an HSSR Engine or IMS software error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred.

Chapter 28. Messages

437

FABH0566E FABH0574E
FABH0566E INTERNAL HSSR OR DL1 ERROR DURING PROCESSING OF REPL CALL Explanation: HSSR Engine detected an unexpected error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0567E PCB-FEEDBACK: DBDNAME=dbdname SEGNAME = segname Explanation: This message lists the dbdname and the segment name contained in the PCB feedback area at the moment of an error, which is described by another FABHxxxxx message. System action: HSSR Engine ends abnormally with dump. Programmer response: See the other FABHxxxxx message. FABH0568I FIRST REPL CALL IS BEING ISSUED FOR PCB=xxxxxxxx hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. (See Chapter 29) FABH0572E INTERNAL ERROR --- MODCB FOR KSDS NOT SUCCESSFUL Explanation: During KSDS processing, HSSR buffer handler unsuccessfully issued a VSAM MODCB macro. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. (See Chapter 29.) FABH0573E INTERNAL ERROR --- RPL FOR KSDS NOT INACTIVE Explanation: During KSDS processing, HSSR buffer handler tried to use an RPL that was active for another VSAM request. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. (See Chapter 29.) FABH0574E VSAM LOGICAL ERROR --RPL-FDBK-CODE IS IN R3 Explanation: VSAM signaled to HSSR buffer handler an unexpected logical error after a KSDS GET macro. Use the RPL feedback code in Register 3 to analyze the error in details. System action: HSSR Engine ends abnormally. FABH0570E text Explanation: HSSR Engine encountered an I/O problem on a VSAM KSDS. This message text contains bytes 27 to 127 of the MSGAREA of RPL as described inDFSMS/MVS Macro Instructions for Data Sets. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. (See Chapter 29.)

Explanation: This message informs you that the database (PCB=xxxxxxxx) is being modified by an HSSR REPL call. System action: The processing continues. Programmer response: None. FABH0569E REPL CALL WITHOUT PCB Explanation: The application program issued an HSSR REPL call without providing a PCB name as a call parameter. System action: HSSR Engine ends abnormally. Programmer response: Correct the program.

438

Users Guide

FABH0575E FABH0581E
FABH0575E INTERNAL ERROR --- ENDREQ FAILED Explanation: During KSDS processing, HSSR buffer handler issued an ENDREQ macro, which failed. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. (See Chapter 29.) FABH0576E DDNAME=ddname; DATA REQUEST OUTSIDE OF THE DATASET LIMITS Explanation: The HSSR buffer handler received a request for a block or CI that is outside the currently known extents of the data set (ddname). This problem may occur if the database is physically damaged or if an updating IMS program is concurrently updating the database. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the real data set name on the DD statement for ddname was specified. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. (See Chapter 29.) FABH0577E RETRY OF KSDS I/O OPERATIONS NOT ENABLED Explanation: The HSSR buffer handler detected an error during the reading of a VSAM KSDS. This error might result either from a physically damaged KSDS or from the concurrent execution of an updating IMS program. System action: HSSR Engine ends abnormally. Programmer response: If the problem results from concurrent execution of an updating IMS program, try to resolve the problem by adding a RETRY KSDS control statement to the HSSROPT data set. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database that processed by HSSR Engine was being updated at the time when the error occurred. (See Chapter 29.) FABH0578E UNEXPECTED RETURN CODE FROM ATTACH Explanation: FABH350 attempted to ATTACH module FABH351. The attempt was not successful, and the return code was not zero. System action: HSSR Engine ends abnormally. Programmer response: Examine the dump to determine the contents of Register 4. Problem determination: Register 4 contains the return code from ATTACH that was returned in Register 15. FABH0579E UNEXPECTED RETURN CODE FROM DETACH Explanation: FABH350 attempted to DETACH module FABH351. The attempt was not successful, and the return code was not zero. System action: HSSR Engine ends abnormally. Programmer response: Examine the dump to determine the contents of Register 4. Problem determination: Register 4 contains the return code from DETACH that was returned in Register 15. FABH0581E OPEN OF DBD=dbdname DDN=ddname --- "yyyy" "text" Explanation: The database named dbdname type yyyy (KSDS, ESDS, or OSAM) could not be opened. ddname indicates the DD name of the failing data set. The possible combinations of yyyy and text, and their explanations, are described in detail in Problem Determination. System action: HSSR Engine ends abnormally. Problem determination: Register 0 at the time of the problem contained a VSAM reason code, which is described inDFSMS/MVS Macro Instructions for Data Sets. The contents of Register 0 are found in the dump, within the module FABH001, in the diagnosis area. This area has the following layout: v A 16-byte eye-catcher: 'DIAGNOSIS AREA' v A double word PSW v Sixteen full words, showing the content of Registers 0 to 15. Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program.

Chapter 28. Messages

439

FABH0581E
yyyy ESDS text GENCB BLOCK=RPL FAILED Explanation: A GENCB for an RPL failed. A possible reason is that insufficient virtual storage is available in the address space. Programmer response: See Problem Determination of FABH0581E, and take an appropriate action. Contact IBM Software Support, if necessary. yyyy KEYD text KEYL IN DATASET AND DBD DIFFERS Explanation: The key length of the data set differs from the key length of the DBD, for example, KSDS. This might be caused by a user error such as DD statements referring to the wrong data set, or using the wrong version of a DBD. Programmer response: Correct the DBD or the DD statement. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. For KSDS, print a LISTCAT of the cluster and its components. yyyy KEYD text KEY-POSITION IN DATA SET AND DBD DIFFERS Explanation: The key position of the data set differs from the key position of the DBD. This might be caused by a user error such as DD statements referring to the wrong data set, or using the wrong version of a DBD. Programmer response: Correct the DBD or the DD statement. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. For KSDS, print a LISTCAT of the cluster and its components. yyyy KSDS text OPEN FAILED Explanation: The OPEN macro issued against a KSDS is not successful, perhaps for the following reasons: v The KSDS has the wrong VSAM SHAREOPTIONS, or the data set is allocated by this region with DISP=OLD in the JCL statements. v There might not be enough virtual storage in the address space. Programmer response: Make sure KSDS definition is correct. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. A VSAM error message will also be issued, and will provide additional assistance. yyyy KSDS text SHOWCB FIELD=DDNAME FAILED Explanation: VSAM was asked to retrieve the DD name of a KSDS, but was unsuccessful. Programmer response: See Problem Determination of FABH0581E, and take an appropriate action. Contact IBM Software Support, if necessary. yyyy KSDS text SHOWCB FIELD=ERROR FAILED Explanation: VSAM was asked to retrieve the ACB error field after an OPEN, but was unsuccessful. Programmer response: See Problem Determination of FABH0581E, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: The error message issued by VSAM contains additional information. yyyy KSDS text SHOWCB FIELD=(CINV,... ) FAILED Explanation: VSAM was asked to retrieve the length of the Control Interval, record, and key, and the relative key position of the KSDS. Programmer response: See Problem Determination of FABH0581E, and take an appropriate action. Contact IBM Software Support, if necessary. yyyy KSDS text GENCB BLOCK=ACB FAILED Explanation: VSAM was unable to generate an ACB. This was probably caused by insufficient virtual storage in the address space. Programmer response: See Problem Determination of FABH0581E, and take an appropriate action. Contact IBM Software Support, if necessary. yyyy KSDS text GENCB BLOCK=RPL FAILED Explanation: VSAM was not able to generate an RPL. This was probably caused by insufficient virtual storage in the address space. Programmer response: See Problem Determination of FABH0581E, and take an appropriate action. Contact IBM Software Support, if necessary. yyyy KSDS text MODCB RPL, OPTCD=CNV FAILED Explanation: VSAM was asked to modify an RPL to allow control interval processing in order to allow a VERIFY, but was unsuccessful. Programmer response: See Problem Determination of FABH0581E, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: The error message issued by VSAM contains additional information.

440

Users Guide

FABH0591E
yyyy KSDS text VERIFY FAILED Explanation: HSSR buffer handler issued a VERIFY macro to the KSDS indicated by the message, but it failed. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. The VSAM error message contains additional information. yyyy KSDS text ENDREQ FAILED Explanation: HSSR buffer handler issued an unsuccessful ENDREQ macro. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Register 2 at the time of the abend contains the address of the RPL. The feedback field of the RPL should be inspected to find out what exactly happened. yyyy KSDS text MODCB RPL, OPTCD=(KEY, ...) FAILED Explanation: HSSR buffer handler issued an unsuccessful MODCB macro to switch back from CI processing to key processing. Programmer response: See Problem Determination of FABH0531E, and take an appropriate action. Contact IBM Software Support, if necessary. yyyy KSDS text MODCB RPL, RECLEN...... FAILED Explanation: HSSR buffer handler issued an unsuccessful MODCB macro to attempt to change the size of the input area. Programmer response: See Problem Determination of FABH0531E, and take an appropriate action. Contact IBM Software Support, if necessary. yyyy OSAM text OPEN FAILED Explanation: A (BSAM) OPEN macro issued against an OSAM data set is not successful. Programmer response: See Problem Determination and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check other error messages, and make sure that the OSAM data set does not have more than 16 extents. yyyy OSAM text BLOCKSIZE IN DCB NOT EQ BLOCKSIZE IN DBD Explanation: The block size of the data set differs from the block size of the DBD. This was probably caused by a user error, such as DD statements referring to the wrong data set, or the wrong version of a DBD has been used. Programmer response: Correct the DBD or the DD statement. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. A LISTVTOC of the data set should also be produced. yyyy OSAM text BLOCKSIZE IS NOT A MULTIPLE OF LRECL Explanation: The block size of the data set is not a multiple of the record length. Programmer response: Correct the block size,. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. A LISTVTOC of the data set should also be produced. yyyy OSAM text IMS OPEN PROBLEM Explanation: HSSR Engine issued an internal DL/I call in order to force IMS to open the database. This DL/I call was not successful. Programmer response: Refer to additional error messages issued by IMS or the access method. FABH0591E OPEN OF DBD=dbdname ---- "yyyy" "text" Explanation: The database named dbdname type yyyy (ESDS, KSDS, OSAM, or KEYD) could not be opened. text describes the problem in detail. The possible combinations of yyyy and text, and their explanations are described in detail following the "Problem Determination". System action: HSSR Engine ends abnormally. Problem determination: At the time of the problem, Register 0 contained a VSAM reason code, which is described inDFSMS/MVS Macro Instructions for Data Sets. The contents of Register 0 are found in the dump, in the diagnostic area within the module FABH001. This area has the following layout: v A 16-byte eye-catcher: 'DIAGNOSIS AREA' v A double word PSW v Sixteen full words, showing the content of Registers 0 to 15.
Chapter 28. Messages

441

FABH0591E
Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. yyyy ESDS text LOGICAL RECORD LENGTH IN ACB IS ZERO Explanation: After OPEN, VSAM finds that the logical record length is zero. Programmer response: Correct the logical record length. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. A LISTCAT of the ESDS should also be produced. yyyy ESDS text CONTROL INTERVAL SIZE IN ACB IS ZERO Explanation: After OPEN, VSAM finds that the control interval size is zero. Programmer response: Correct the control interval size. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. A LISTCAT of the ESDS should also be produced. yyyy ESDS text GENCB BLOCK=ACB FAILED Explanation: VSAM could not generate an ACB. This was probably caused by insufficient virtual storage in the address space. Programmer response: Make sure sufficient virtual storage is available. Problem determination: See message FABH0591E. yyyy ESDS text GENCB BLOCK=RPL FAILED Explanation: VSAM could not generate an RPL. This was probably caused by insufficient virtual storage in the address space. Programmer response: Make sure sufficient virtual storage is available. Problem determination: See message FABH0591E. yyyy ESDS text GENCB BLOCK=EXLST FAILED Explanation: VSAM could not generate an exit list. This was probably caused by insufficient virtual storage in the address space. Programmer response: Make sure sufficient virtual storage is available. Problem determination: See message FABH0591E. yyyy ESDS text OPEN FAILED Explanation: The OPEN macro issued against a KSDS was not successful. This was probably caused by: v The ESDS had the wrong VSAM SHAREOPTIONS, or the data set was allocated by this region with DISP=OLD on the JCL statements. v There is not enough virtual storage in the address space. Programmer response: Make sure ESDS is correctly defined. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. The VSAM error message contains additional information. yyyy ESDS text VERIFY FAILED Explanation: HSSR buffer handler issued a VERIFY macro to the KSDS indicated by the message, but it failed. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. The VSAM error message contains additional information. yyyy ESDS text ENDREQ FAILED Explanation: HSSR buffer handler issued an unsuccessful ENDREQ macro. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Register 2 at the time of abend contains the address of the RPL. The feedback field of the RPL should be inspected to find out what exactly happened. yyyy ESDS text SHOWCB FIELD=CINV FAILED Explanation: VSAM could not retrieve the control interval size of the ESDS. Programmer response: See Problem Determination of FABH0591E, and take an appropriate action. Contact IBM Software Support, if necessary.

442

Users Guide

FABH0592E FABH0602E
yyyy ESDS text SHOWCB FIELD=ERROR FAILED Explanation: VSAM could not retrieve the error code. Programmer response: See Problem Determination of FABH0591E, and take an appropriate action. Contact IBM Software Support, if necessary. text ESDS text HSSR-CAB CANNOT READ THE SAME ESDS-DB THROUGH MULTIPLE PCBs Explanation: HSSR buffer handler detected that multiple HSSR PCBs that are referring to the same database should be buffered by CAB. This situation is not supported by CAB. Programmer response: Modify the CAB control statements in such a way that no more than one HSSR PCB per database is buffered by CAB. The OCCURRENCE CAB control statement can be used to achieve this modification. yyyy ESDS text ENDRBA NOT FOUND Explanation: This error might occur if the VSAM control blocks are changing. Programmer response: Rerun program. FABH0592E UNACCEPTABLE VSAM LOGICAL ERROR Explanation: HSSR buffer handler has encountered an unexpected VSAM logical error during open processing of a VSAM ESDS. The problem might have been caused by an HSSR Engine or VSAM software error. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0591E, and take an appropriate action. Contact IBM Software Support, if necessary. FABH0595E STATUSCODE=XX ENCOUNTERED DURING INTERNAL ASMTDLI CALL (segmname) Explanation: FABHURG1, run with the MIGRATE control statement specified, issued a DL/I GU call internally for the virtual logical child segment segmname, but the status code of the call was not blank. System action: HSSR Engine ends abnormally. Programmer response: Check the status code and detect the cause of the error. If the status code is AI, the most likely cause is the absence of the DD statement for the logically related database. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0596E STATUSCODE=XX ENCOUNTERED DURING INTERNAL ASMTDLI CALL (segmname) Explanation: Program FABHURG1, run with the MIGRATE control statement specified, issued a DL/I GU call internally for an occurrence of the physically paired logical child segment segmname, but the status code of the call was not blank. System action: FABHURG1 ends abnormally. Programmer response: Check the status code and detect the cause of the error. If the status code is AI, the most likely cause is the absence of the DD statement for the logically related database. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0597E STATUSCODE=XX ENCOUNTERED DURING INTERNAL ASMTDLI CALL (segmname) Explanation: Program FABHURG1, run with the MIGRATE control statement specified, issued a DL/I GU call internally for an occurrence of the physically paired logical child segment segmname, but the status code of the call was not blank. System action: FABHURG1 ends abnormally. Programmer response: Check the status code and detect the cause of the error. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0598E STATUSCODE=XX ENCOUNTERED DURING INTERNAL ASMTDLI CALL (segmname) Explanation: Program FABHURG1, run with the MIGRATE control statement specified, issued a DL/I GU call internally for an occurrence of the unidirectional logical child segment segmname, but the status code of the call was not blank. System action: FABHURG1 ends abnormally. Programmer response: Check the status code and detect the cause of the error. If the status code is AI, the most likely cause is the absence of the DD statement for the logically related database. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0602E BAD RETURN CODE FROM OSAM MACRO ... PLEASE REFER TO PRECEDING DFS730I MESSAGE Explanation: HSSR buffer handler tried to open an OSAM database data set with the OSAM open functions. The open was not successful. System action: HSSR Engine ends abnormally.

Chapter 28. Messages

443

FABH0603E FABH0623E
Programmer response: Refer to the message DFS730I and read its explanation inIMS Messages and Codes. FABH0603E ddname DD-STATEMENT IS MISSING; UNABLE TO OPEN DATA SET Explanation: HSSR buffer handler tried to open the OSAM database data set with the named ddname. The DD statement is missing or misspelled. System action: HSSR Engine ends abnormally. Programmer response: Correct the DD statement. FABH0604E DATA SET IS NOT INITIALIZED AND IS EMPTY: DB=dbdname, DD=ddname Explanation: The OSAM data set that is specified in the ddname DD statement and that is being used as input for High Performance Unload has not been initialized as a DL/I database and contains no data block. Only the header record is written in output unloaded data sets. System action: HSSR Engine ends abnormally. Programmer response: Make sure that the data set specified in the DD statement is correct. FABH0605E RDJFCB MACRO FAILED ON DDNAME: ddname (RC=xx) Explanation: The RDJFCB macro failed with a return code xx for the data set that was specified for the DDNAME ddname. System action: HSSR Engine ends abnormally. Programmer response: Check the job log messages and other printed output for an indication that some system service has failed. If none can be found, it is likely that High Performance Unload has had an internal logic error. Contact IBM Software Support. FABH0606E OBTAIN MACRO FAILED ON DDNAME: ddname (RC=xx) Explanation: The OBTAIN macro failed with a return code xx for the data set that was specified for the DDNAME ddname. System action: HSSR Engine ends abnormally. Programmer response: Check the job log messages and other printed output for an indication that some system service has failed. If none can be found, it is likely that High Performance Unload has had an internal logic error. Contact IBM Software Support. FABH0611E OPEN OF DBD=dbdname DDN=ddname --- ESDS GEN BLOCK= RPL FAILED Explanation: The ESDS database named dbdname could not be opened. A GENCB for an RPL failed. A possible reason is that insufficient virtual storage is available in the address space. ddname indicates the DD name of the failing data set. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0591E for more information, and take an appropriate action. Contact IBM Software Support, if necessary. FABH0621E PAGE-FIXING HAS FAILED Explanation: HSSR buffer handler tried to fix its own OSAM or ESDS buffers by issuing the IMSAUTH FUNC=PGFIX macro. The IMSAUTH macro set a return code indicating that it could not perform page-fixing. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Register 4 contains the error code returned by IMSAUTH in Register 15. FABH0622E HSSR FAILED IN PARTITION SELECTION; REQUEST=xxxxxx, RC=yy, RSN=zzzzz Explanation: An error occurred in a partition selection request when the IMSs DFSPSEL macro was used. The string xxxxxxx indicates the type of the request; FIRST, NEXT, SELECT, PSET, or PRSET. The value yy shows the return code, and the value zzzzz shows the reason code from the DFSPSEL service.

| | | | | | | | | | |

RSN=4020 means a DB authorization error occurred, because the partition has been authorized to another IMS subsystem or a data set name that is specified in the JCL for the partition is inconsistent with the registration in RECON. For other reason codes, see the explanation of message DFS0832I in IMS Messages and Codes Vol. 2. System action: HSSR Engine ends abnormally. Programmer response: If RSN=4020, issue the /DBD or the /DBR command to the partition before the HP Unload job step, or remove the DD statements for the partition from the JCL. FABH0623E SELECTED PARTITION ppppppp OF DATABASE dddddddd IS NOT AVAILABLE Explanation: The partition ppppppp selected by an HSSR call that was issued for the HALDB dddddddd had not been specified as a partition to be processed.

444

Users Guide

FABH0624E FABH0630E
This message is issued when a user exit routine for FABHURG1 or FABHFSU returns a root sequence key of the segment to be processed next, but the segment is in an inaccessible partition. System action: HSSR Engine ends abnormally. Programmer response: Check whether the partition ppppppp belongs to the set of partitions that are specified by a PARTITION control statement in the SYSIN data set of FABHURG1 or in the CARDIN data set of FABHFSU. If not, correct the PARTITION control statement so that the partition ppppppp can be included. If a HALDB control statement in the DFSHALDB DD statement is defined, remove it. FABH0624E TARGET PARTITION ppppppp IS NOT FOUND Explanation: IMS DFSPSEL macro returned return code 8 and reason code X'8010' for a PSET request. The string ppppppp shows the name of the partition that is not found. System action: HSSR Engine ends abnormally. Programmer response: Check whether the partition ppppppp belongs to the set of partitions that are specified by a PARTITION control statement in the SYSIN data set of FABHURG1 or in the CARDIN data set of FABHFSU; if not, correct the PARTITION control statement so that the partition ppppppp can be included. FABH0625E USER PARTITION SELECTION FAILED (SELECTION TYPE=aaaaaa) Explanation: The partition selection exit got the return code 4 from the routine written for the exit, and the IMS DFSPSEL macro returned return code 8 and reason code X'8051'. The string aaaaaa shows the type of the partition selection request (the value specified for the PART parameter of DFSPSEL) that was issued at the time of the error. System action: HSSR Engine ends abnormally. Programmer response: Check why the partition selection exit routine returned return code 4. FABH0626E PARTITION SELECTION EXIT ROUTINE REQUESTED A PSEUDO ABEND (SELECTION TYPE=aaaaaa, RC=xx) Explanation: The user partition selection exit routine returned the return code xx and the IMS DFSPSEL macro returned return code 16 and the reason code X'10001'. The string aaaaaa shows the type of the partition selection request (the v specified for the PART parameter of DFSPSEL) that was in effect at the time of the error. System action: HSSR Engine ends abnormally. Programmer response: For the explanation of the IMS user abend code of 3499, see IMS Failure Analysis Structure Tables (FAST) for Dump Analysis. The programmer response described in the manual applies also to HSSR Engine. FABH0627E EXIT ROUTINE xxxxxxxx RETURNED RC=03 ALTHOUGH PARTITION AND CO STATEMENTS ARE SPECIFIED Explanation: The user exit routine xxxxxxxx for FABHURG1 returned return code 3 when both the PARTITION and CO control statements are specified. Exit routines are not allowed to return return code 3 when both of these statements are specified. System action: HSSR Engine ends abnormally. Programmer response: Remove the CO or PARTITION statement from the HSSROPT data set. FABH0628E EXIT ROUTINE xxxxxxxx RETURNED RC=16 ALTHOUGH PARTITION AND CO STATEMENTS ARE SPECIFIED Explanation: The user exit routine xxxxxxxx for FABHFSU returned return code 16 when both the PARTITION and CO control statements are specified. Exit routines are not allowed to return return code 16 when both of these statements are specified. System action: HSSR Engine ends abnormally. Programmer response: Remove the CO or PARTITION statement from the HSSROPT data set. FABH0629W PARTITION ppppppp IS SKIPPED BECAUSE OF AN ERROR IN PARTITION SELECTION Explanation: The processing of the HALDB partition ppppppp was skipped because an error occurred when a partition selection request was processed. System action: HSSR Engine continues processing. Programmer response: See the Trace Output Report with Diagnostics for the reason of the error. FABH0630E CANNOT PROCESS THE PARTITION NEXT TO ppppppp BECAUSE OF STATUS CODE 'GG' FROM THE PRIOR DL/I CALL Explanation: This message is issued if a CO statement is specified in the HSSROPT data set and the status code 'GG' was returned at the DL/I call issued earlier for the comparison with an HSSR call. The string ppppppp shows the name of the partition that had been processed before the DL/I call in question was issued. HSSR Engine cannot continue the processing of the database in this case even if PROCOPT=GON or GOT is specified for the PCB.
Chapter 28. Messages

445

FABH0631E FABH0637W
System action: HSSR Engine ends abnormally. Programmer response: To detect the cause of the error, follow the procedure described in Problem Determination. Problem determination: Remove the CO statement and specify a DIAGG statement in HSSROPT data set; then rerun the job to see the diagnostics for the status code 'GG'. If you are running a FABHURG1 or FABHFSU job, it is recommended that you specify the PARTITION statement with ppppppp as the first operand and 2 as the second operand. FABH0631E PROBLEMS WITH DL/I-STAT CALL Explanation: HSSR buffer handler tried to retrieve the VSAM Shared Resource Pool Statistics by issuing an internal DL/I STAT call. DL/I returned an unexpected status code. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. FABH0632E CLOSE FAILED Explanation: After program termination, HSSR Engine is asked to close the DCB/ACB of the databases. The CLOSE macro is unsuccessful. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. The access method error message contains additional information. FABH0633E TARGET PARTITION IS NOT FOUND FOR THE SPECIFIED KEY Explanation: IMS DFSPSEL macro returned return code 8 and the reason code X'8010' for a SELECT request, but no partition corresponding to the key specified in the request was found. System action: HSSR Engine ends abnormally. Programmer response: Check whether the root key specified in the SSA is correct. Diagnosis, Modification, or Tuning Information FABH0637W HSSR CALLS FALL BACK TO DL/I FROM PARTITION=pppppppp (DBD=dddddddd) Explanation: HSSR Engine will pass all of the following DL/I calls to IMS's DL/I call handler from partition pppppppp, because HALDB online reorganization (OLR) is active for this partition. Problem Determination: The key specified in the SSA is at offset X'8AC' from the address pointed to by general register 10. End of Diagnosis, Modification, or Tuning Information FABH0634E ONLINE REORG RUNNING FOR PARTITION=pppppppp (DBD=dddddddd) Explanation: HALDB Online Reorganization (OLR) is currently processing partition pppppppp. HSSR Engine cannot process the partition. System action: HSSR Engine ends abnormally. Programmer response: Rerun after OLR for all partitions are completed. FABH0635W ONLINE REORG ACTIVE FOR PARTITION=pppppppp (DBD=dddddddd) Explanation: HALDB Online Reorganization (OLR) processing for partition pppppppp was stopped prior to the completion of the partition, and the OLR cursor is still active. HSSR Engine will process the partition which is comprised of both the A-J and X data sets as well as the M-V and Y data sets. System action: HSSR Engine continues processing. If one of the options listed below is specified, it is ignored: v BYINDEX, CO, DBSTATS, KEYCHECK, or SKERROR. Programmer response: Refer to the additional messages. FABH0636E UNSUPPORTED OPTION FOR OLR ACTIVE PARTITIONS: option Explanation: The option (option) is specified, but this is one of the following options with which HSSR Engine cannot process the HALDB OLR active partition: v DECN v PARTEXTR v User exit routine v *CS format for PHDAM System action: FABHURG1 or FABHFSU ends abnormally. Programmer response: Remove this option or rerun after OLR for all partitions are completed.

446

Users Guide

FABH0641E FABH0656I
System action: HSSR Engine continues processing. The performance, however, decreases. Programmer response: If you want to use the ignored option, rerun after HALDB OLR for all partitions are completed. FABH0641E VSAM PHYSICAL I/O ERROR Explanation: HSSR buffer handler encountered an I/O problem on an ESDS. The return code and reason code are described inDFSMS/MVS Macro Instructions for Data Sets. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0642E VSAM LOGICAL ERROR; RPL-FDBK-CODE IS IN R3 Explanation: VSAM signaled an unexpected logical error to HSSR buffer handler after an ESDS GET macro. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: The RPL feedback code can be used for a further analysis of the problem. At the time of the dump, Register 3 contains the RPL feedback code. Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0643E SHOWCB OF RPL-FDBK-CODE FAILED Explanation: The VSAM SHOWCB macro issued by HSSR buffer handler failed. System action: HSSR Engine ends abnormally. Programmer response: Contact IBM Software Support, if necessary. FABH0656I MEDIA MANAGER IS USED TO ACCESS DB: dbdname FABH0653E OSAM I/O ERROR, DDNAME=ddname DECB-STATUS=xxx...20 Explanation: HSSR buffer handler encountered an I/O problem when using BSAM to read an OSAM block. ddname is the ddname. xxx...20 is the field DECBSTAT from the DECB used in the I/O operation followed by a description of the error. System action: HSSR Engine ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: For more information, see the description of message DFS0451I inIMS Messages and Codes. Activate the compare and hard-copy trace options, and execute the failing call sequence with the FABHTEST program. Check whether the correct DBDs, PSBs, and ACBs were being used. Check whether the database processed by HSSR Engine was being updated at the time when the error occurred. FABH0654E MEDIA MANAGER function ERROR, RC=rc Explanation: When HSSR Engine issued MMGRSRV to process function (CONNECT, DISCONNECT, or CATREAD) to the data set, an unexpected Media Manager MMGRSRV error occurred. The rc is the return code of Media Manager. For details, see DFSMSdfp Diagnosis Reference. System action: HSSR Engine ends abnormally. Programmer response: Collect the dump and contact IBM Software Support. FABH0655E MEDIA MANAGER I/O ERROR, RC=rc Explanation: When HSSR Engine issued MMGRCALL to get access to the data set, an unexpected Media Manager MMGRCALL error occurred. The rc is the return code of Media Manager. System action: HSSR Engine ends abnormally. Programmer response: Collect the dump and contact IBM Software Support.

Explanation: Media Manager is used to read VSAM data sets of database dbdname because all concatenations of the JOBLIB/STEPLIB are APF-authorized. System action: HSSR Engine continues processing. Programmer response: None.

Chapter 28. Messages

447

FABH0657E FABH0671W
| FABH0657E STEPLIB IS NOT APF-AUTHORIZED | Explanation: APF-authorization is required for this | type of run of the HSSR Engine. | System action: HSSR Engine ends abnormally. | Programmer response: APF-authorize all libraries in | STEPLIB DD concatenation, and rerun the job.
FABH0661E RBA REQUEST BEYOND ORIGINAL DATA SET LIMITS DDNAME=ddname Explanation: The HSSR buffer handler received a request to read a block or CI that is beyond the extents of the data set (ddname). The reason may be that concurrent database updates have extended the data set. System action: HSSR buffer handler tries to get new up-to-date information about the data set extents. If the requested block/CI is no longer beyond the known data set limits, HSSR buffer handler proceeds normally; otherwise HSSR Engine ends abnormally. Programmer response: None. KEYLEN FABH0662E OPEN OF DBD=dbdname DDN=ddname --- ESDS "text" Explanation: HSSR buffer handler tried to access a CI that is beyond the currently known extents of the data set (dbdname). To get up-to-date extent information, HSSR buffer handler is issuing a new VSAM OPEN. The VSAM OPEN is unsuccessful. ddname indicates the DD name of the failing data set. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0591E for more information, and take an appropriate action. FABH0663E RETRYING KSDS I/O OPERATIONS Explanation: The HSSR buffer handler detected an unexpected VSAM logical error code. This might be explained by concurrent database updates. System action: HSSR buffer handler refreshes the KSDS buffers and retries the I/O operation. If the retry is not successful, an abend is issued. If the retry is successful, HSSR Engine proceeds normally. Note that in this case, some database records might have been skipped or retrieved twice. Programmer response: None. System action: HSSR Engine continues processing. FABH0664E OPEN OF DBD=dbdname DDN=ddname --- KSDS "text" Explanation: HSSR buffer handler has encountered an unexpected VSAM logical error and decided to re-OPEN the VSAM KSDS (dbdname) and to retry the I/O operation. However, the re-OPEN is not successful. Programmer response: If the database should be processed by HSSR Engine, check and correct the PCB that defines the database. Otherwise, ignore this message and continue processing by using DL/I modules. Problem determination: Check the PROCOPT or ddname indicates the DD name of the failing data set. System action: HSSR Engine ends abnormally. Programmer response: See message FABH0581 for more information, and take an appropriate action. FABH0671W DB (xxxxxxxx) PCB IS NOT A VALID HSSR PCB, RC=yyyyyyy Explanation: When the first HSSR call is issued to the database, the database (xxxxxxxx) PCB is incorrect as HSSR PCB. If no database PCBs are in the PSB, then xxxxxxxx is blank. The reason code (RC=yyyyyyy) shows an error in the PCG. The program control is transferred to DL/I modules instead of HSSR Engine. It means that the database does not take advantage of HSSR Engine. RC PROCOPT Meaning The PROCOPT parameter on the PCB statement specifies the incorrect code or combination of codes. The codes you can use are G, O, N, T, R, A, P, and E. A value of the KEYLEN parameter on the PCB statement is less than 200. This reason code is returned also when the specified PCB refers to the DBD that is listed on the DBDL1 control statement. An application program issued an HSSR call for the following PCB: v PCB is generated with PROCOPT=R. v And DBD referred to by the PCB is generated with the data capture exit routine.

USREXIT

The reason codes of FABH0671W for the combination of errors are described as follows:
Key length error Yes Yes Yes Yes No No No No PROCOPT error Yes Yes No No No No Yes Yes User exit error Yes No No Yes Yes No Yes No Reason code of FABH0671W RC=PROCOPT RC=PROCOPT RC=KEYLEN RC=USREXIT RC=USREXIT N/A RC=PROCOPT RC=PROCOPT

448

Users Guide

FABH0672E FABH0680E
KEYLEN parameter in the PCB. If the reason code is "KEYLEN" and the specified PCB does not refer to any DBDs that are listed on the DBDL1 control statement, the PCB can be specified as an HSSR PCB using the HSSRPCB control statement or through the HSSRDBD control statement. FABH0672E INVALID NUMBER OF PARAMETERS FOR PLIHSSR CALL Explanation: The HSSR PL/I language interface detected an incorrect number of parameters for PLIHSSR call. System action: HSSR Engine ends abnormally with dump. Programmer response: Check and correct the PLIHSSR call statement in your PL/I application program and rerun. If there is no error, check whether the correct APISET statement is specified. For details about the call types and command types that APISET supports, see DL/I calls supported by each API set on page 90 or EXEC DLI commands supported by each API set on page 91. FABH0673E INCORRECT PCB ADDRESS WAS PASSED BY APPLICATION PROGRAM Explanation: HSSR Engine detected an incorrect PCB address internally. This message was issued because of the incorrect PCB address passed by application program or an internal error in HSSR Engine. System action: HSSR Engine ends abnormally. Programmer response: Check the PCB parameter or other parameters. If there is no error in DL/I call statement, contact IBM Software Support. FABH0674E ERROR FOUND IN HSSR CALL STATEMENT, INVALID xxxxxx Explanation: The HSSR language interface detected an error in the HSSR call statement described in xxxxxx. xxxxxx is one of the following: PARAMETER COUNT: v If APISET is 1, the parameter count must be 3 or 4. v If APISET is 2, the count must be from 3 to 5. v If APISET is 3, the count must be from 3 to 18, inclusive. PCB ADDRESS: PCB address is incorrect. NUMBER OF PARAMETERS: v If APISET is 1, the number of parameters must be 3 or 4. v If APISET is 2, the number must be from 3 to 5. v If APISET is 3, the number must be from 3 to 18, inclusive. System action: HSSR Engine ends abnormally. Programmer response: Specify APISET 2 or APISET 3 in the control statement. FABH0675E ROOT SEGMENT POSITION IS NOT ESTABLISHED Explanation: Two or more SSAs are specified and the first is a qualified SSA, but the root segment position has not been established yet by the preceding call. This call is not supported by the HSSR call handler. The unsupported call is printed in the Trace output report in the HSSRTRAC data set. System action: If APISET is 2, HSSR Engine ends abnormally. If APISET is 3, the call and all the succeeding calls to the HSSR PCB are passed to the IMS DL/I call handler to continue the processing instead of ending it abnormally. Programmer response: If APISET is 2, specify APISET 3 in the control statement. If APISET is 3, ignore this message.

| FABH0678E INCORRECT HPIO CONTROL | STATEMENT IS SPECIFIED | Explanation: An incorrect operand on the HPIO | control statement is specified in the HSSROPT data set. | The operand must be either YES or NO. | System action: The incorrect statement is ignored. | Programmer response: Correct the HPIO statement.
FABH0679E INCORRECT SKIPVLC CONTROL STATEMENT IS SPECIFIED Explanation: An incorrect operand on the SKIPVLC control statement is specified in the HSSROPT data set. The operand must be either YES or NO. System action: The incorrect statement is ignored. Programmer response: Correct the SKIPVLC statement. FABH0680E FABHKEYX CANNOT PROCESS THE COMPRESSED ROOT KEY Explanation: The FABHKEYX exit routine cannot process the compressed root key. It must be decompressed. System action: Program FABHURG1 ends abnormally. Programmer response: If you want to use the FABHKEYX exit for this database, specify the DECY control statement.

Chapter 28. Messages

449

FABH0681E FABH0690E
FABH0681E INCORRECT APISET CONTROL STATEMENT IS SPECIFIED Explanation: An incorrect operand or no operand is specified for the APISET control statement in the HSSROPT data set. The operand must be 1, 2, or 3. System action: The statement is ignored and the system or site default is used. Programmer response: Correct the APISET control statement. FABH0682E xxxxxxxx CANNOT BE SPECIFIED WHEN APISET 3 IS SELECTED Explanation: The control statement xxxxxxxx is not supported for APISET 3. System action: HSSR Engine ends abnormally. Programmer response: Remove the control statement xxxxxxxx or specify APISET 1 or 2. FABH0683E INCORRECT PCBLIST CONTROL STATEMENT IS SPECIFIED Explanation: An incorrect operand or no operand is specified for the PCBLIST control statement in the HSSROPT data set. The operand must be HSSR or IMS. System action: The statement is ignored and the system or site default is used. Programmer response: Correct the PCBLIST control statement. FABH0684I DD=ddname01 HIGHKEY=KeyString SEGMENT=segname1 n,nnn,nnn,nnn OCCURRENCES *TOTAL n,nnn,nnn,nnn OCCURRENCES FABH0686E HIGH KEY VALUES ARE NOT SPECIFIED IN ASCENDING ORDER Explanation: The FABHKEYX exit routine detected the high key values that are specified in the FABHKEYX data set are not in ascending order. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the statements. FABH0687E OPEN FAILED FOR DDNAME: ddname Explanation: An attempt to open the data set that is identified by ddname failed. System action: Program FABHURG1 ends abnormally. Programmer response: Make sure that the DD statement associated with ddname is the correct data set. FABH0688E BLKSIZE OR LRECL OF ddname IS TOO SMALL Explanation: The block size or record size of the ddname data set is too small. The block size is always the maximum device capacity. System action: Program FABHURG1 ends abnormally. Programmer response: v If the utility uses the maximum device capacity, check whether ddname can be allocated on a device with more track capacity. v If the utility uses the block size specified on the JCL statement, check whether the block size or the record size can be increased or use the default maximum device capacity. v Record size can not be specified. FABH0689E MIGRATE CONTROL STATEMENT IS NOT SPECIFIED Explanation: For a non-HALDB, the FABHKEYX exit routine requires to specify the MIGRATE control statement together. System action: Program FABHURG1 ends abnormally. Programmer response: Add the MIGRATE control statement. FABH0690E ROOT SEGMENT HAS NO SEQUENCE-FIELD Explanation: The FABHKEYX exit routine cannot process this HDAM database because no sequence field is defined in the root segment of the HDAM database.

Explanation: The FABHKEYX exit routine used the specified DD name ddname01 and the high key value KeyString. The indicated number of segment records were written to this unload file. System action: Program FABHURG1 continues processing. Programmer response: None. FABH0685E INCORRECT STATEMENT IS FOUND IN FABHKEYX DATA SET Explanation: The FABHKEYX exit routine detected an incorrect statement that is specified in the FABHKEYX data set. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the statement.

450

Users Guide

FABH0691E FABH0704E
System action: Program FABHURG1 ends abnormally. Programmer response: Remove the FABHKEYX exit routine from the EXIT control statement. FABH0691E STATUS CODE=xx RETURNED ON AN INTERNAL DL/I CALL Explanation: If APISET 3 is specified in HSSROPT data set, HSSR Engine can issue a DL/I GU call internally. This message indicates that the status code xx is returned for one such DL/I call. System action: HSSR Engine ends abnormally. Programmer response: Check the status code and detect the cause of the error. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0692E ERROR RETURN CODE xx IN RESPONSE TO A DL/I REQUEST ON DDNAME ddname FOR FUNCTION yy Explanation: HSSR Engine issued an internal DL/I call to read database data set (ddname). Code yy is the content of PSTFNCTN, and code xx is the content of PSTRTCDE; both values are in hexadecimal. System action: HSSR Engine ends abnormally. Programmer response: Check the return code and detect the cause of the error. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0693E STATUS CODE=xx RETURNED ON AN INTERNAL DL/I CALL Explanation: If APISET 3 is specified in HSSROPT data set, HSSR Engine can issue a DL/I call internally. This message indicates that the status code xx is returned for one such DL/I call. System action: HSSR Engine ends abnormally. Programmer response: Check the status code and detect the cause of the error. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0695I DL/I CALLS TO HSSR PCB (PCB#=nnnn) ARE PASSED TO IMS DL/I FABH0700E FIRST CONTROL STATEMENT ID IS NOT MAP Explanation: In the FABHPSFM step, the first control statement ID is not MAP. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0701E DBDNAME IS MISSING OR HAS IMBEDDED BLANKS Explanation: A DBD name was not specified or it contains blank characters in the MAP control statement. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0702E INDEX DBDNAME HAS IMBEDDED BLANKS Explanation: An Index DBD name contains blank characters in the MAP control statement. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0703E THIS SEGMENT ENTRY IS NOT ROOT SEGMENT Explanation: Program FABHPSFM checked the segment code of the database and found that the segment code of the first segment type is not for root segment. System action: FABHPSFM ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Problem determination: Check whether the right version of DBD was being used. Check whether the database processed by HSSR Engine was being updated. FABH0704E NO FIELD IS PRESENT IN DBD Explanation: The number of segment fields is zero in the DBD being used. System action: Program FABHPSFM ends abnormally. Programmer response: See message FABH0703E for more information, and take an appropriate action.

Explanation: HSSR application program issued a DL/I call that is not fully supported by HSSR Engine. This call and the succeeding calls to the HSSR PCB are passed to the IMS DL/I call handler, because APISET 3 is specified. System action: The processing continues. The performance, however, decreases. Programmer response: If you want the database calls to be fully processed by HSSR Engine, use call type supported by APISET 2.

Chapter 28. Messages

451

FABH0705E FABH0717E
FABH0705E KEY FIELD IS NOT FOUND IN DBD Explanation: There is not any sequence field in the DBD member being used. System action: Program FABHPSFM ends abnormally. Programmer response: See message FABH0703E for more information, and take an appropriate action. FABH0708E KEY TYPE IS NOT C, X, OR BLANK Explanation: The specified key type in the MAP control statement is not valid. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0709E SELECT KEY OPTION IS NOT A, D, E, N, V, Y, OR BLANK Explanation: The specified select key option in the MAP control statement is not correct. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0710E RELATIVE BLOCK IS MISSING OR HAS IMBEDDED BLANKS Explanation: A relative block was not specified or it contains blank characters in the MAP control statement. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0711E DELTA IS MISSING OR HAS IMBEDDED BLANKS Explanation: A search delta was not specified or it contains blank characters in the MAP control statement. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0712E INVALID INDEX DBD NAME Explanation: An index DBD name was specified in the MAP control statement, but this DBD is not an index DBD. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the control statement. FABH0716E INDEX FIELD NAME IS NOT FOUND IN BASE DBD FIELD TABLE Explanation: An index field name in the index DBD was not found in the base DBD field table. System action: Program FABHPSFM ends abnormally with dump. Programmer response: See message FABH0714E for more information, and take an appropriate action. FABH0717E INDEX FIELD IS NOT AN XFLD IN BASE DBD Explanation: An index field for an index DBD was not defined as XFLD in the base DBD. System action: Program FABHPSFM ends abnormally with dump. Programmer response: See message FABH0714E for more information, and take an appropriate action. FABH0714E INDEX TARGET SEGMENT IS NOT A ROOT SEGMENT Explanation: The target segment of the index database is not a root segment. System action: Program FABHPSFM ends abnormally. Programmer response: See Problem Determination, and take an appropriate action. Problem determination: Check whether the right version of DBD was being used. Check the DBDGEN statements of this DBD. FABH0715E NO HIDAM INDEX DBD NAME IS SPECIFIED Explanation: The DBD name of the HIDAM database was specified but an index DBD name was not specified. System action: Program FABHPSFM ends abnormally. Programmer response: Specify the index DBD name in the MAP control statement. FABH0713E END CONTROL STATEMENT IS MISSING OR OUT OF PLACE Explanation: The END control statement is missing or out of place. System action: Program FABHPSFM ends abnormally. Programmer response: Add or replace the END control statement.

452

Users Guide

FABH0719E FABH0729E
FABH0719E FIRST VSAM INDEX RECORD POINTER IS ZERO Explanation: A VSAM index record is retrieved by GET macro, and the RBA of this record is zero. System action: Program FABHPSFM ends abnormally with dump. Programmer response: See Problem Determination, and take an appropriate action. FABH0723I INDEX DBD LRECL IS NOT ACTUAL LRECL

Explanation: The logical record length of the Index DBD differs from the logical record length of the actual data set. System action: Program FABHPSFM continues processing. Programmer response: Correct the DBD or the DD statement. FABH0724E VSAM DATABASE I/O FAILURE Explanation: The return code was not zero when OPEN or SHOWCB macro was issued for VSAM ESDS. System action: Program FABHPSFM ends abnormally with dump. Programmer response: Make sure VSAM ESDS is correctly defined. Problem determination: See message FABH0721E. FABH0725E VSAM INDEX I/O FAILURE

| Problem determination: Check the VSAM KSDS data | set. Check if the versions of both IMS and z/OS are | supported by High Performance Unload.
FABH0720E DBD IS NOT HIDAM OR HDAM Explanation: Parallel Scan Facility supports only HIDAM and HDAM databases. System action: Program FABHPSFM ends abnormally. Programmer response: Specify the DBD name of HIDAM or HDAM. FABH0721E VSAM INDEX FAILURE ON OPEN, SHOWCB OR MODCB Explanation: Return code was not zero when OPEN, SHOWCB, or MODCB macro was issued for VSAM KSDS. System action: Program FABHPSFM ends abnormally with dump. Programmer response: Make sure VSAM KSDS is correctly defined. Problem determination: Check whether the VSAM

Explanation: The return code was not zero when GET macro was issued for VSAM KSDS. System action: Program FABHPSFM ends abnormally with dump. Programmer response: See message FABH0721E for more information, and take an appropriate action. FABH0727I DBD BLOCK SIZE IS NOT ACTUAL BLOCK SIZE

| DD statement is correct. Check whether the versions of | both IMS and z/OS are supported by High Performance | Unload.
FABH0722E FIND FAILED FOR MEMBER xxxxxxxx IN DBDLIB - R15:yy - R0:zz Explanation: A FIND macro failed for the DBD member xxxxxxxx in the DBD library (IMS DD in the JCL). yy is a return code and zz is a reason code from the FIND macro. If the return code is 4 and the reason code is 0, this message shows that DBD xxxxxxxx was not found in the DBD library on your IMS DD statement. Refer to the description of FIND macro for other cases. System action: Program FABHPSFM ends abnormally. Programmer response: Correct the error and rerun the Job.

Explanation: This message is issued when either one of the following occurs: v The block size specified in the DBD is not equal to the one that is specified on the DD statement in your JCL. v The block size specified in the DBD is not equal to the one that is held in the VTOC. System action: Program FABHPSFM continues processing, using the block size specified in the VTOC, or block size specified in your JCL if the BLKSIZE parameter is coded in the DCB parameter. Programmer response: Correct the DBD or the DD statement. FABH0729E FABHPSFM INTERNAL ERROR Explanation: Program FABHPSFM detected an unexpected error. System action: FABHPSFM ends abnormally with dump. Programmer response: See Problem Determination,
Chapter 28. Messages

453

FABH0730I FABH0746E
and take an appropriate action. FABH0741E DBDNAME IS MISSING OR HAS IMBEDDED BLANKS Explanation: A DBD name was not specified, or it contains blank characters in the DBD control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0742E INDEX DBDNAME HAS IMBEDDED BLANKS Explanation: An index DBD name contains blank characters in the DBD control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0743E SEQUENCE CHECK OPTION IS NOT Y, N, OR BLANK Explanation: The sequence check option in the DBD control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0744E SEQUENCE ERROR PRINT OPTION IS NOT Y, N, OR BLANK Explanation: The sequence error print option in the DBD control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0745E SEQUENCE ERROR OPTION IS NOT A, B, OR BLANK Explanation: The sequence error option in the DBD control statement is not A, B, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0746E SEQUENCE ERROR THRESHOLD IS NOT NUMERIC Explanation: The value of the sequence error threshold in the DBD control statement is not numeric. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statements.

| | |

Problem determination: Check whether the right version of DBD was being used. Check whether the versions of both IMS and z/OS are supported by High Performance Unload. FABH0730I NO MULTIPLE EXTENTS - USE SELECT KEY OPTION

Explanation: The primary data set group has no extent. System action: Program FABHPSFM closes the data set and ends the job step. Programmer response: Correct the select key option in the MAP control statement. FABH0734I INDEX RECORD POINTER IS ZERO

Explanation: Program FABHPSFM retrieved the index records and found that the record pointer is zero. System action: FABHPSFM continues processing. Programmer response: None FABH0735I NO MULTIPLE VOLUMES - USE OTHER SELECT KEY OPTIONS

Explanation: The primary data set group was allocated within one volume. System action: Program FABHPSFM closes the data set and ends the job step. Programmer response: Correct the select key option in the MAP control statement. FABH0736E GETMAIN FAILURE Explanation: This was caused by insufficient virtual storage in the address space. System action: HSSR Engine ends abnormally with dump. Programmer response: Make sure sufficient virtual storage is available. FABH0740E FIRST CONTROL STATEMENT ID IS NOT DBD Explanation: In the FABHPSFC step, the first control statement ID is not DBD. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement.

454

Users Guide

FABH0747E FABH0759E
FABH0747E INVALID OPTION FIELD IS USED Explanation: Columns 26 and 27 in the DBD control statement are not blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. Problem determination: Any entry cannot be allowed in columns 26 and 27 of the DBD control statement This field must be blank. FABH0748E PSB NAME IS MISSING OR HAS IMBEDDED BLANKS Explanation: A PSB name was not specified correctly in the PSB control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0749E PCB NUMBER IS NOT NUMERIC Explanation: The relative PCB number in the PSB control statement is not numeric. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0750E OUTPUT FORMAT IS NOT SPECIFIED Explanation: The format of output data set to be created was not specified in the PSB control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0751E DDNAME IS MISSING OR HAS IMBEDDED BLANKS Explanation: A DD name was not specified, or it contains blank characters in the PSB control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0752E EXIT ROUTING NAME HAS IMBEDDED BLANKS Explanation: The name of the exit routine contains blank characters in the PSB control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0756E DBR SKIP OPTION IS NOT Y, N, OR BLANK Explanation: The DBR skip option in the PSB control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0758E END CONTROL STATEMENT IS MISSING OR OUT OF PLACE Explanation: The END control statement is missing or it is out of place. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0759E NO PSB CONTROL STATEMENT IS PRESENT Explanation: The PSB control statement is not specified. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0753E SEGMENT MODIFICATION OPTION IS NOT Y, N, OR BLANK Explanation: The segment modification option in the PSB control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0754E CONCATENATED KEY OPTION IS NOT Y, N, OR BLANK Explanation: The concatenated key option in the PSB control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0755E EXIT ROUTINE CONTROL OPTION IS NOT Y, N, OR BLANK Explanation: The exit routine control option in the PSB control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement.

Chapter 28. Messages

455

FABH0760E FABH0772E
FABH0760E SCAN CONTROL DATA SET RECFM IS NOT VB Explanation: The record format of the Scan Control Data Set is not VB. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the record format of the Scan Control data set. FABH0761E FIND FAILED FOR MEMBER xxxxxxxx IN DBDLIB - R15:yy - R0:zz Explanation: A FIND macro failed for the DBD member xxxxxxxx in the DBD library (IMS DD in the JCL). yy is a return code and zz is a reason code from FIND macro. If the return code is 4 and the reason code is 0, this message shows that DBD xxxxxxxx was not found in the DBD library on your IMS DD statement. Refer to the description of FIND macro for other cases. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the error and rerun the Job. FABH0765E INVALID OPTION FIELD IS USED Explanation: Column 30 in the DBD control statement is not blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. Problem determination: Any entry cannot be allows in column 30 of the DBD control statement. This field must be blank. FABH0766E INCORRECT CONTROL STATEMENT PLACEMENT Explanation: The sequence of control statements is not valid. The CTL control statement does not follow the DBD control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0767E PARALLEL SCAN NAME IS INVALID Explanation: The parallel scan name was not specified correctly in the CTL control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the parallel scan name. FABH0768E SCAN CONTROL DATA SET EXPIRATION DATE IS NOT VALID Explanation: The expiration date of the Scan Control data set was not specified correctly in the CTL control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0769E NUMBER OF PARALLEL SCANS IS NOT VALID Explanation: The total number of parallel scan phases was not specified correctly in the CTL control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0770E DSN SEQUENCE OFFSET IN NOT VALID Explanation: The DSN sequence offset option was not specified correctly in the CTL control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0771E FABHPSFC INTERNAL ERROR Explanation: Program FABHPSFC detected an unexpected error. System action: FABHPSFC ends abnormally with dump. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary.

| | |

Problem determination: Check whether the correct DBDs and PSBs were being used. Check whether the versions of both IMS and z/OS are supported by High Performance Unload. FABH0772E FABHPSFC INTERNAL ERROR Explanation: Program FABHPSFC detected an unexpected error. System action: FABHPSFC ends abnormally with dump. Programmer response: See Problem Determination, and take an appropriate action. Contact IBM Software Support, if necessary. Problem determination: Check whether the correct DBDs and PSBs were being used. Check whether the database processed by FABHPSFC was being updated.

456

Users Guide

FABH0773E FABH0783E
FABH0773E PHASE COUNT AND NODE POINT ARE MISMATCH Explanation: Program FABHPSFC detected an unexpected error. System action: FABHPSFC ends abnormally. Programmer response: See message FABH0772E for more information and take an appropriate action. FABH0774E LIMIT FIELD IS NOT NUMERIC Explanation: The specified node point value in the NPT control statement is not numeric. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0775E SPECIFIED KEY IS TOO LONG OR ZERO LENGTH Explanation: The key value specified with the node point value in the NPT control statement is too long or zero length. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0776E NODE POINT VALUE TYPE IS NOT R, C, OR X Explanation: The node point value type in the NPT control statement is not R, C, or X. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0777E INVALID OPTION FIELD IS USED Explanation: Columns 31 to 38 in the DBD control statement are not blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. Problem determination: Any entry cannot be allowed in columns 31 to 38 of the DBD control statement. This field must be blank. FABH0778E POINTER BYPASS OPTION IS NOT 1, 2, OR BLANK Explanation: The specified pointer bypass option in the DBD control statement is not 1, 2, or blank. System action: Program FABHPSFC ends abnormally.
Chapter 28. Messages

Programmer response: Correct the control statement. FABH0779E INCORRECT CONTROL STATEMENT PLACEMENT Explanation: The specified sequence of control statements is not valid. The NPT control statement does not follow the CTL control statement. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0780E FABHPSFC INTERNAL ERROR Explanation: Program FABHPSFC detected an unexpected error. System action: FABHPSFC ends abnormally with dump. Problem determination: See message FABH0771E. FABH0781E DBD IS NOT HIDAM OR HDAM Explanation: Parallel Scan Facility supports only HIDAM and HDAM databases. System action: Program FABHPSFC ends abnormally. Programmer response: Specify the DBD name of HIDAM or HDAM. FABH0782E SEGMENT TABLE BUILD ERROR Explanation: Program FABHPSFC built the segment table and the segment table extension, and detected an internal error. System action: FABHPSFC ends abnormally with dump. Programmer response: See message FABH0772E for more information, and take an appropriate action. FABH0783E INVALID OPTION FIELD IS USED Explanation: Column 36 in the PSB control statement is not blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. Problem determination: Any entry cannot be allowed in column 36 of the PSB control statement. This field must be blank.

457

FABH0784E FABH0794E
FABH0784E NUMBER OF PARALLEL SCANS IS NOT EQUAL NUMBER OF NPT PLUS ONE Explanation: The total number of scan phases specified with the CTL control statement is not equal to the number of the NPT control statements plus one. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0785E DSN CHECK OPTION IS NOT Y, N, OR BLANK Explanation: The specified DSN check option in the CTL control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0786E WTO OPTION IS NOT Y, N, OR BLANK Explanation: The specified WTO option in the CTL control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0787E INCONSISTENT TYPES OF NODE POINT VALUE Explanation: Program FABHPSFC detected an unexpected error. System action: FABHPSFC ends abnormally. Programmer response: See message FABH0772E for more information, and take an appropriate action. Contact IBM Software Support, if necessary. FABH0788E HDAM RELATIVE BLOCK NUMBER IS SPECIFIED BEYOND RAA Explanation: The HDAM relative block number is specified out-of-read addressable area. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the node point value in the NPT control statement. FABH0789E HDAM RELATIVE BLOCK NUMBER IS NOT IN ASCENDING SEQUENCE Explanation: The HDAM relative block number is not in ascending order. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the node point value in the NPT control statement. FABH0790E HDAM RELATIVE BLOCK NUMBER IS ZERO OR NEGATIVE Explanation: The HDAM relative block number is zero or a negative value. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the node point value in the NPT control statement. FABH0791E NODE POINT VALUE TYPE C OR X IS NOT VALID FOR HDAM Explanation: The specified node point value type in the NPT control statement is not valid for an HDAM database. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement. FABH0792E NODE POINT KEY IS NOT IN ASCENDING SEQUENCE Explanation: The node point key specified with the node point value type C or X is not in ascending order. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the node point value in the NPT control statement. FABH0793E BLOCK SIZE IS TOO SMALL FOR CONTROL SCAN PHASES Explanation: The block size of the Scan Control data set is too small to build control records for all scan phases. System action: Program FABHPSFC ends abnormally. Programmer response: Create the new Scan Control data set. FABH0794E SEPARATE HEADER OPTION IS NOT Y, N, OR BLANK Explanation: The specified separate header option in the CTL control statement is not Y, N, or blank. System action: Program FABHPSFC ends abnormally. Programmer response: Correct the control statement.

458

Users Guide

FABH0795E FABH0812E
FABH0795E GETMAIN FAILURE Explanation: Virtual storage in the address space was insufficient. System action: Program FABHPSFC ends abnormally with dump. Programmer response: Make sure sufficient virtual storage is available. FABH0800E FIRST CONTROL STATEMENT ID IS NOT SUM Explanation: In FABHPSFS step, the first control statement ID is not SUM. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the control statement. FABH0801E DBDNAME IS NOT VALID Explanation: A DBD name was not specified correctly in the SUM control statement. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the control statement. FABH0802E SCAN NAME IS NOT VALID Explanation: The specified parallel scan name in the SUM control statement is not valid. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the control statement. FABH0803E SUM OPTION IS NOT STATUS, RERUN, OR FORCE Explanation: The acceptable option keyword RERUN, STATUS, or FORCE is not specified in the SUM control statement. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the control statement. FABH0804E HEADER/TRAILER RE-CREATE OPTION IS NOT Y, N, H, T, OR BLANK Explanation: The specified header/trailer re-create option is not Y, N, H, T, or blank in the SUM control statement. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the control statement. FABH0810E HEADER/TRAILER DATA SET RECFM IS NOT VB Explanation: The record format of the header or trailer data set is not VB. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the record format of the header or trailer data set. FABH0811E TRAILER DATA SET RECFM IS NOT VB Explanation: The record format of the trailer data set is not VB. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the record format of the trailer data set. FABH0812E FIND FAILED FOR MEMBER xxxxxxxx IN DBDLIB - R15:yy - R0:zz Explanation: A FIND macro failed for the DBD member xxxxxxxx in the DBD library (IMS DD in the JCL). yy is a return code and zz is a reason code from FIND macro. If the return code is 4 and the reason code is 0, this message shows that DBD xxxxxxxx was not found in the DBD library on your IMS DD statement.
Chapter 28. Messages

FABH0806E END CONTROL STATEMENT IS MISSING OR OUT OF PLACE Explanation: The END control statement is missing or is out of place. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the control statement. FABH0807E DBD IS NOT HIDAM OR HDAM Explanation: Parallel Scan Facility supports only HIDAM and HDAM databases. System action: Program FABHPSFS ends abnormally. Programmer response: Specify the DBD name of HIDAM or HDAM. FABH0808E INVALID SEGMENT WAS FOUND Explanation: Program FABHPSFS detected an unexpected segment. System action: FABHPSFS ends abnormally with dump. Programmer response: See message FABH0772E for more information, and take an appropriate action.

459

FABH0813E FABH0822E
Refer to the description of FIND macro for other cases. System action: Program FABHPSFS ends abnormally. Programmer response: Correct the error and rerun the Job. FABH0813E END CONTROL STATEMENT IN SCAN CONTROL DATA SET IS NOT FOUND Explanation: The END control statement in the Scan Control data set cannot be found, or it is incorrect. System action: Program FABHPSFS ends abnormally with dump. Problem determination: Check the result of the previous FABHPSFC step and the FABHFSU parallel scan steps. FABH0814E SEGMENT NAME IS MISMATCH Explanation: Program FABHPSFS built segment tables and updated them from statistics records, but detected that the segment name was not a match. System action: FABHPSFS ends abnormally with dump. Programmer response: See message FABH0772E for more information, and take an appropriate action. FABH0815E READ JFCB FAILURE Explanation: Program FABHPSFM issued RDJFCB command but did not complete successfully. System action: FABHPSFM ends abnormally with dump. Programmer response: See message FABH0772E for more information, and take an appropriate action. FABH0816E HEADER/TRAILER DSN IS NOT VALID Explanation: DSN of the header or trailer data set is not valid. System action: Program FABHPSFS ends abnormally with dump. Programmer response: Correct the control statement. FABH0817I TRAILER PREVIOUSLY CREATED - NO RERUN OPTION SPECIFIED FABH0818E FABHPSFS INTERNAL ERROR Explanation: Program FABHPSFS detected an unexpected error. System action: FABHPSFS ends abnormally with dump. Programmer response: See message FABH0772E for more information, and take an appropriate action. FABH0819E SCAN NAME IS MISMATCH ON SCAN CONTROL DATA SET Explanation: The specified parallel scan name in the SUM control statement is not equal to the scan name in the Scan Control data set. System action: Program FABHPSFS ends abnormally. Programmer response: Check whether the Scan Control data set is the correct one. Correct the DD statement of the Scan Control data set or correct the control statement. FABH0820E DBD NAME IS MISMATCH ON SCAN CONTROL DATA SET Explanation: The specified DBD name in the SUM control statement is not equal to the DBD name in the Scan Control data set. System action: Program FABHPSFS ends abnormally. Programmer response: See message FABH0819E for more information, and take an appropriate action. FABH0821E SCAN CONTROL DATA SET OPEN FAILURE Explanation: The Scan Control data set open failure occurred. System action: Program FABHPSFS ends abnormally with dump. Programmer response: See Problem Determination, and take an appropriate action.

| |

Problem determination: Check whether the DD statement is correct. Check if the versions of both IMS and z/OS are supported by High Performance Unload. FABH0822E HEADER DATA SET OPEN FAILURE Explanation: The header data set open failure occurred. System action: Program FABHPSFS ends abnormally with dump. Problem determination: See message FABH0821E.

Explanation: The trailer data set was already created but the RERUN option was not specified in the SUM control statement. System action: Program FABHPSFS continues processing. Programmer response: None.

460

Users Guide

FABH0823E FABH0833E
FABH0823E TRAILER DATA SET OPEN FAILURE Explanation: The trailer data set open failure occurred. System action: Program FABHPSFS ends abnormally with dump. Programmer response: See message FABH0821E for more information, and take an appropriate action. FABH0824E GETMAIN FAILURE Explanation: This was caused by insufficient virtual storage in the address space. System action: Program FABHPSFS ends abnormally with dump. Programmer response: Make sure sufficient virtual storage is available. FABH0825I FORCE OPTION REJECTED - A STARTED PHASE INCOMPLETE Programmer response: Check whether it is acceptable that the input database has no valid segments. If a wrong database data set or a wrong DBD or PSB was specified, specify the proper ones, and rerun the job. FABH0829W INCONSISTENT DEC OPTIONS WERE SPECIFIED IN SCAN PHASES Explanation: The segment decompression option "DEC" specified in the CARDIN data set of FABHFSU in each scan phase was not consistent. System action: Program FABHPSFS continues processing. Programmer response: The unloaded data sets created by these scan phases cannot be used to load the database. The DEC option specified in each scan phase must be consistent if you want to use the created data sets for reloading. FABH0830E FIRST PCB IS NOT A VALID HSSR PCB Explanation: Program FABHLDBR detected that the first PCB in the PSB was not a valid HSSR PCB. System action: FABHLDBR ends abnormally. Programmer response: Refer to HSSR PCB requirements on page 84, and correct the error. FABH0831E AN INVALID STATEMENT IS FOUND IN SYSIN DATA SET Explanation: An incorrect control statement type was detected in the FABHLDBR SYSIN data set. System action: Program FABHLDBR ends abnormally. Programmer response: Correct the control statement. FABH0832E NON-POSITIVE NUMBER IS SPECIFIED FOR xxxxxxxx CONTROL STATEMENT Explanation: A nonpositive numeric value is specified for the operand of the xxxxxxxx control statement in the SYSIN data set of the FABHLDBR utility. System action: Program FABHLDBR ends abnormally. Programmer response: Correct the control statement. FABH0833E THE OPERAND OF xxxxxxxx CONTROL STATEMENT IS NOT NUMERIC Explanation: A nonnumeric value is specified for the operand of the xxxxxxxx control statement in the SYSIN data set of the FABHLDBR utility. System action: Program FABHLDBR ends abnormally.

Explanation: The FORCE option was specified in the SUM control statement, but the phase process specified by the DD statement was not completed. System action: Program FABHPSFS continues processing. Programmer response: None. FABH0826I RUN TIME ENVIRONMENT EXIT ROUTINE IS BEING INVOKED, MODULE=xxxxxxxx

Explanation: The run time exit routine whose name is xxxxxxxx is invoked. System action: HSSR Engine continues processing. Programmer response: None. FABH0827E ERROR OCCURRED IN RTEXIT, MODULE=xxxxxxxx, FUNC=yyyy, RC=zz Explanation: HSSR Engine detected a nonzero return code zz from the run time environment exit routine xxxxxxxx. System action: HSSR Engine ends abnormally. Programmer response: Determine the reason for the nonzero return code from the run time exit routine. Run the job again after correcting the problem, if necessary. FABH0828W NO SEGMENT WAS RETRIEVED Explanation: No segment was retrieved in all PSF phases. System action: Program FABHPSFS normally ends with a return code of 01.

Chapter 28. Messages

461

FABH0834E FABH0844E
Programmer response: Correct the control statement. FABH0834E OPEN OF SYSUT1 HAS FAILED Explanation: Program FABHLDBR could not open SYSUT1. System action: FABHLDBR ends abnormally. Programmer response: Correct the SYSUT1 DD statement. FABH0835E INVALID PARAMETER IS FOUND IN AN LOUT CONTROL STATEMENT Explanation: An undefined parameter was detected in the LOUT control statement. Or, the value specified by the LENGTH= or IO= parameter of the LOUT control statement was incorrect. System action: The incorrect LOUT parameter and any parameters that follow it on the same control statement, are ignored. Programmer response: Correct the LOUT control statement. FABH0836E A NON-NUMERIC VALUE IS SPECIFIED IN HSSRLDEF DATA SET Explanation: A record that contains a nonnumeric value is found in the HSSRLDEF data set. System action: The incorrect record is ignored. Programmer response: Correct the incorrect record. FABH0837E A NUMERIC FIELD IS TOO LONG IN HSSRLDEF DATA SET Explanation: A numeric value that is too long is specified in the HSSRLDEF data set. System action: The record that has the incorrect numeric field is ignored. Programmer response: Correct the statement that contains the incorrect field. FABH0838E LENGTH-DEFINITIONS IN HSSRLDEF ARE NOT IN ASCENDING SEQUENCE Explanation: The numeric values in the HSSRLDEF data set were not in ascending sequence. System action: The incorrect numeric field is ignored. Programmer response: Correct the statement that contains the incorrect field, so that the values will be in ascending sequence. FABH0840E FABHEXTR FAILED TO OPEN HSSREXTR DATA SET Explanation: FABHEXTR could not open the HSSREXTR data set. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the HSSREXTR DD statement. FABH0841E INVALID STATEMENT IS FOUND IN HSSREXTR DATA SET Explanation: An incorrect control statement was specified in the HSSREXTR data set. System action: Program FABHURG1 ends abnormally. Programmer response: Remove or correct the control statement. FABH0842E NUMERIC FIELD IS NOT NUMERIC Explanation: A nonnumeric value was specified for a numeric field in a control statement in the HSSREXTR data set. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the control statement. FABH0843E NUMBER OF DB RECORDS TO BE EXTRACTED IS [NOT POSITIVE|TOO LARGE] Explanation: The EXTR or PARTEXTR control statement specified a numeric value that was not positive or was too large. System action: Program FABHURG1 ends abnormally. Programmer response: Correct the control statement. FABH0844E NEITHER EXTR NOR PARTEXTR IS SPECIFIED Explanation: Neither the EXTR control statement nor the PARTEXTR control statement is specified in the HSSREXTR data set. One or the other must be specified. System action: Program FABHURG1 ends abnormally. Programmer response: Specify either EXTR or PARTEXTR.

462

Users Guide

FABH0845E FABH0853E
FABH0845E DATABASE IS EMPTY Explanation: Program FABHEXTR detected that FABHURG1 reached the end of a database, but no segment was retrieved. The database might be empty. System action: FABHURG1 ends abnormally. Programmer response: Check whether the correct DBD and database data set are specified. FABH0846E TOO MANY DB RECORDS ARE SKIPPED Explanation: Program FABHEXTR skipped too many database records and reached the end of the database without retrieving any segments. The unloaded data set will be empty. System action: Program FABHURG1 ends abnormally. Programmer response: Check whether a correct DBD and database data set are specified. If the database specification is correct, check whether the value specified on the SKIP control statement in the HSSREXTR data set is less than the total number of database records in the database. FABH0847E xxxxxxxx IS SPECIFIED FOR NON-HALDB Explanation: xxxxxxxx control statement is specified for a database that is not a HALDB. System action: Program FABHURG1 ends abnormally. Programmer response: Check whether the correct DBD was specified. FABH0848E DUPLICATE STATEMENTS: xxxxxxxx Explanation: The control statement xxxxxxxx is specified more than once. System action: Program FABHURG1 ends abnormally. Programmer response: Remove unnecessary statements, and rerun the job. FABH0849E MUTUALLY EXCLUSIVE CONTROL STATEMENTS ARE SPECIFIED: xxxxxxxx AND yyyyyyyy Explanation: The control statements xxxxxxxx and yyyyyyyy are mutually exclusive. System action: Program FABHURG1 ends abnormally. Programmer response: Select only one of these statements, and remove the other. FABH0850E LOAD FAILED FOR RTEXIT (xxxxxxxx), CC=yyyy, RC=zz Explanation: A LOAD error occurred when HSSR Engine tried to load the run-time exit routine xxxxxxxx. As a result, the ERRET routine received the control. yyyy indicates the system completion code at time of error, and zz indicates the error reason code for the LOAD request. System action: HSSR Engine ends abnormally. Programmer response: Check the system completion code and the error reason code. If you find the reason for the error, correct it and rerun the job. FABH0851E LOAD FAILED FOR APPL PGM (xxxxxxxx), CC=yyyy, RC=zz Explanation: A LOAD error occurred when HSSR Engine tried to load the application program xxxxxxxx. As a result, the ERRET routine received the control. yyyy indicates the system completion code at time of error, and zz indicates the error reason code for the LOAD request. System action: HSSR Engine ends abnormally. Programmer response: Check the system completion code and the error reason code. If you find the reason for the error, correct it and rerun the job. FABH0852E LOAD FAILED FOR MODULE DFSDBUX1 Explanation: The user specified DATXEXIT=YES at DBDGEN time, but DFSDBUX1 is not found in any STEPLIB library. At execution time, while processing a DBD requiring the exit, HSSR determined that the exit could not be loaded, and issued the message. System action: HSSR Engine ends abnormally. Programmer response: If the user exit (DFSDBUX1) is required for the job, make sure that DFSDBUX1 is placed into a STEPLIB library, and rerun the job. If you do not need DFSDBUX1 for this job, but need it for another application, specify 'DATXEXIT NO' in the HSSROPT data set for the job. If you do not need DFSDBUX1 at all for the database you are processing, remove the DATXEXIT=YES from DBDGEN. FABH0853E IMODULE ERROR (rc) function COMPRESSION EXIT (xxxxxxxx) Explanation: An IMODULE function (LOADING or DELETING) error occurred when HSSR Engine tried to load or delete the segment edit/compression routine xxxxxxxx. rc is the error return code from IMODULE. For the meanings of the return codes, read about IMODULE return codes in IMS Messages and Codes. System action: HSSR Engine ends abnormally.

Chapter 28. Messages

463

FABH0854E FABH0873I
Programmer response: Check the error return code. If you find the reason for the error, correct it and rerun the job. FABH0854E LOAD FAILED FOR FABHRCEX EXIT, CC=xxxx, RC=yy Explanation: A LOAD error occurred when HSSR Engine tried to load the Return Code Edit exit routine (FABHRCEX). As a result, the ERRET routine received control. xxxx is the system completion code at time of error, and yy is the error reason code for the LOAD request. System action: HSSR Engine ends abnormally. Programmer response: Check the system completion code and the error reason code. If you find the reason for the error, correct it and rerun the job. FABH0860E X'FF' IS SET IN SRCHFLAG BY DFSDBUX1 Explanation: The user specified DATXEXIT=YES at DBDGEN time, but the Data Conversion exit set SRCHFLAG to X'FF'. System action: HSSR Engine ends abnormally. Programmer response: If you do not need DFSDBUX1 for this HSSR job, but need it for another application, specify 'DATXEXIT NO' in the HSSROPT data set for the HSSR job. If you need DFSDBUX1 for the database you are processing, define table entries for the database in the translation table of the Data Conversion exit routine. FABH0861I DBDGEN REQUIRED FOR DATABASE xxxxxxxx TO SET DATXEXIT INDICATOR System action: HSSR Engine ends abnormally. Programmer response: Check whether the correct Data Conversion exit routine is used. If a conditional exit routine is specified for the database you are processing, check also whether the correct one is used. If you cannot determine the cause of the problem, record the message and contact IBM Software Support. FABH0870E LOAD FAILED FOR IDCAMS Explanation: A LOAD error occurred when HSSR Engine tried to load the IDCAMS module. System action: HSSR Engine ends abnormally. Programmer response: Make sure that the IDCAMS module is available on your JOB, and also that it exists in the LPA list, LINK list, or STEPLIB or JOBLIB path. FABH0871E LISTCAT FAILED FOR DATA SET dsname (dbdname, partname, ddname), RC=rc Explanation: An error occurred when the LISTCAT command of the program IDCAMS was run for data set dsname. Value rc shows the return code from program IDCAMS. System action: HSSR Engine ends abnormally. Programmer response: See DFSMS Access Method Services for Catalogs and check the meaning of the return code. Correct the error, and rerun the job. If the cause is not clear, collect the dump and contact IBM Software Support. FABH0872I DATA SET dsname IS NOT CATALOGED (DDN=ddname)

Explanation: While HSSR Engine was processing the first HSSR call for a database whose DATXEXIT=YES flag is not on, the Data Conversion exit routine (DFSDBUX1) was called and the routine returned to HSSR Engine without SRCHFLAG set to X'FF'. This indicates that the Data Conversion exit routine was required for this database. HSSR Engine dynamically sets the DATXEXIT=YES flag on and continues processing for this database, but issues this message to warn the user that a DBDGEN with DATXEXIT=YES needs to be done for this database. System action: HSSR Engine continues processing. Programmer response: The database administrator needs to be notified that a DBDGEN is required for this database. FABH0862E NON-ZERO RC (xx) RETURNED FROM CONV EXIT Explanation: Non-zero return code xx is returned from the Data Conversion exit routine (DFSDBUX1).

Explanation: The data set specified is not cataloged. The string ddname shows the DD name with which the data set is associated by the partition definition. System action: HSSR Engine continues processing. Programmer response: See the explanation and the programmer response of the succeeding message FABH0873I. FABH0873I PARTITION partname OF HALDB dbdname WILL NOT BE PROCESSED

Explanation: This message is preceded by one or several number of FABH0872I messages. HSSR will not process the partition partname of HALDB dbdname because one or several number of data sets defined for partition partname are not cataloged. System action: HSSR Engine continues processing. Programmer response: If the partition needs to be processed, you must catalog all data sets for partition partname.

464

Users Guide

FABH0881I FABH2008E
FABH0881I applname ENDED WITH RC=xx, WHICH MIGHT BE CHANGED BY FABHRCEX EXIT Programmer response: Correct the error. FABH2003E INVALID CABSTAT= PARAMETER IS SPECIFIED Explanation: The value of the CABSTAT= keyword parameter is incorrect. It must be either YES or NO. System action: The assembly of the option table ends with a return code of 8. The option table is not replaced. Programmer response: Correct the error. FABH2004E INVALID LSR= PARAMETER IS SPECIFIED Explanation: The value of the LSR= keyword parameter is incorrect. It must be either YES or NO. System action: The assembly of the option table ends with a return code of 8. The option table is not replaced. Programmer response: Correct the error. FABH2005E INVALID URG1DEC= PARAMETER IS SPECIFIED Explanation: The value of the URG1DEC= keyword parameter is incorrect. It must be either YES or NO. System action: The assembly of the option table ends with a return code of 8. The option table is not replaced. Programmer response: Correct the error. FABH2006E INVALID FSUDEC= PARAMETER SPECIFIED Explanation: The value of the FSUDEC= keyword parameter is incorrect. It must be either YES or NO. System action: The assembly of the option table ends with a return code of 8. The option table is not replaced. Programmer response: Correct the error. FABH2001E INVALID COMPAT= PARAMETER IS SPECIFIED Explanation: The value of the COMPAT= keyword parameter is incorrect. It must be one of HPU, DBT, and 5787LAC. System action: The assembly of the option table ends with a return code of 8. The option table is not replaced. Programmer response: Correct the error. FABH2002E INVALID DIAGG= PARAMETER IS SPECIFIED Explanation: The value of the DIAGG= keyword parameter is incorrect. It must be DIAGONLY, CB, BUF, or NOINT. System action: The assembly of the option table ends with a return code of 8. The option table is not replaced. FABH2007E DUPLICATED FABHTOPT STATEMENTS ARE FOUND Explanation: The FABHTOPT statement was specified more than once. Only one FABHTOPT statement is allowed. System action: The assembly of the option table ends with a return code of 12. The option table is not replaced. Programmer response: Correct the error. FABH2008E INVALID BUFDEFAULT= PARAMETER IS SPECIFIED Explanation: The value of the BUFDEFAULT= keyword parameter is incorrect. It must be either CAB or BB.
Chapter 28. Messages

Explanation: The HSSR application program applname ended with a return code of xx, but the return code has been processed and might be edited by the user specified Return Code Edit exit routine (FABHRCEX). If the return code is changed by the routine, you will see a code other than xx at the completion of High Performance Unload job step. System action: HSSR Engine continues processing. Programmer response: If the original return code xx is not zero, check the meaning of the return code by referring to Chapter 27, Return codes, on page 385. FABH1000I DFSISVI0 EXIT IS CALLED BUT FABHURG1 CANNOT BE INVOKED

Explanation: This message notifies the user that the IMS exit DFSISVI0 is called but FABHURG1 unload utility cannot be invoked because of the error indicated in the prior message. System action: IMS continues the processing and DFSURGU0 will be invoked. Programmer response: None. FABH1001I DFSISVI0 EXIT IS CALLED AND FABHURG1 IS BEING INVOKED

Explanation: This message notifies the user that the IMS exit DFSISVI0 is called, and FABHURG1 unload utility will be invoked by IMS batch region controller as the unload program. System action: IMS continues processing. Unload function is provided by the FABHURG1 unload utility. Programmer response: None.

465

FABH2009E FABH2014E
System action: The assembly of the option table ends with return code 8. The option table is not replaced. Programmer response: Correct the error. FABH2009E INVALID CABDEFAULT= PARAMETER IS SPECIFIED Explanation: The value of the CABDEFAULT= keyword parameter is incorrect. It must be either HPU or DBT. System action: The assembly of the option table ends with return code 8. The option table is not replaced. Programmer response: Correct the error. FABH2010E INCORRECT APISET= PARAMETER IS SPECIFIED Explanation: The value of the APISET= keyword parameter is incorrect. It must be 1, 2, or 3. System action: The assembly of the option table ends with return code 8. The option table is not replaced. Programmer response: Correct the error. FABH2011E INCORRECT PCBLIST= PARAMETER IS SPECIFIED Explanation: The value specified for the PCBLIST= keyword parameter is incorrect. It must be HSSR or IMS. System action: The assembly of the option table ends with return code 8. The option table is not replaced. Programmer response: Correct the error. FABH2012E INCORRECT URG1BUFNO= PARAMETER IS SPECIFIED Explanation: The value specified for the URG1BUFNO= keyword parameter is incorrect. It must be 1 to 255. System action: The assembly of the option table ends with return code 8. The option table is not replaced. Programmer response: Correct the error. FABH2013E INCORRECT FSUBUFNO= PARAMETER IS SPECIFIED Explanation: The value specified for the FSUBUFNO= keyword parameter is incorrect. It must be 1 to 255. System action: The assembly of the option table ends with return code 8. The option table is not replaced. Programmer response: Correct the error. FABH2014E INCORRECT URG1CHKRC= PARAMETER IS SPECIFIED Explanation: The value specified for the URG1CHKRC= keyword parameter is incorrect. It must be either YES or NO. System action: The assembly of the option table ends with return code 8. The option table is not replaced. Programmer response: Correct the error.

466

Users Guide

FABI0001E FABI0011E

FABI messages
FABI0001E IDTYPE= PARAMETER IS NEITHER C NOR X Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0007E DBNBYTES= PARAMETER IS TOO LONG

Explanation: The value of the IDTYPE= keyword parameter should be either C or X. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0002E VALTYPE= PARAMETER IS NEITHER E NOR H

Explanation: The value of the DBNBYTES= keyword parameter cannot be greater than 8. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0008E DBNBYTES= PARAMETER CANNOT BE ZERO

Explanation: The value of the VALTYPE= keyword parameter should be either E or H. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0003E BYTES= PARAMETER IS NOT NUMERIC

Explanation: The value of the DBNBYTES= keyword parameter cannot be 0. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0009E DBNSTART= PARAMETER IS NOT NUMERIC

Explanation: The value of the BYTES= keyword parameter should be numeric. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0004E START= PARAMETER IS NOT NUMERIC

Explanation: The value of the DBNSTART= keyword parameter should be a number. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0010E DBNSTART= PARAMETER CANNOT BE ZERO

Explanation: The value of the START= keyword parameter should be numeric. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0005E START= PARAMETER CANNOT BE ZERO

Explanation: The value of the START= keyword parameter should be a number greater than zero. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0006E DBNBYTES= PARAMETER IS NOT NUMERIC

Explanation: The value of the DBNSTART= keyword parameter cannot be zero. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0011E DBNSTART= PARAMETER IS TOO LONG

Explanation: The value of the DBNBYTES= keyword parameter should be numeric. System action: The generation of the randomizer will not be successful. The return code is 12.

Explanation: The value of the DBNSTART= keyword parameter cannot be greater than 8. System action: The generation of the randomizer will
Chapter 28. Messages

467

FABI0021E FABI0035E
not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0021E DBNAME= KEYWORD MISSING ON FABIDBN MACRO Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0031E ID= KEYWORD MISSING ON FABIDEF MACRO

Explanation: The DBNAME= macro is missing on the FABIDBN macro. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0022E DBNAME= LONGER THAN DBNBYTES OF FABITAB MACRO

Explanation: The mandatory ID= keyword parameter is missing on the FABIDEF macro. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0032E LENGTH OF ID= PARAMETER NOT EQUAL TO THE BYTES= VALUE ON THE FABITAB MACRO

Explanation: The length of DBNAME= parameter value should not exceed the length specified on the DBNBYTES= parameter of the FABITAB macro. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0023E SPLIT= KEYWORD MISSING ON FABIDBN MACRO

Explanation: The length of the ID= parameter value on the FABIDEF macro is not equal to the value specified on the BYTES= parameter of the FABITAB macro. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0033E FABIDEF MACROS NOT IN ASCENDING ID-SEQUENCE

Explanation: The FABIDEF macros must be provided in the ascending sequence of the ID= parameter values. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0034E ID= PARAMETER NOT A VALID HEXADECIMAL VALUE

Explanation: The SPLIT= keyword parameter is missing on the FABIDBN macro. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0024E SPLIT= KEYWORD NOT NUMERIC

Explanation: The value of the ID= parameter is not a valid hexadecimal value. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0035E FABIDEF MACROS NOT IN ASCENDING HEX ID-SEQUENCE

Explanation: The value of the SPLIT= keyword parameter should be numeric. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0025E SPLIT= KEYWORD CANNOT BE ZERO

Explanation: The FABIDEF macros must be provided in the ascending sequence of the hexadecimal values of the ID= parameters. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error.

Explanation: The value of the SPLIT= keyword parameter should not be zero. System action: The generation of the randomizer will not be successful. The return code is 12.

468

Users Guide

FABI0036E FABI0104E
FABI0036E UNITS= KEYWORD MISSING ON FABIDEF MACRO not be successful. The return code is 12. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0051E NO SUCCESSFUL FABIDEF MACRO

Explanation: The mandatory UNITS= keyword was not specified on the FABIDEF macro. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0037E VALUE OF UNITS= PARAMETER NOT NUMERIC

Explanation: Any correct FABIDEF macro was not specified by the user. System action: The generation of the randomizer will not be successful. The return code is 8. Programmer response: Correct the error. FABI0101E DATABASE IS NOT AN HDAM DATABASE WITH THE SS-RANDOMIZER

Explanation: The UNITS= parameter must specify a numeric value. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0041E NO CORRECT FABIDEF MACRO

Explanation: The FABIUNLS utility can only be used to split an unloaded DB, if the database is an HDAM database using a Sequential Subset Randomizer. System action: The FABIUNLS utility will issue an abend. Programmer response: Correct the error. FABI0102E PROBLEMS WITH TABLE OF SS-RANDOMIZER

Explanation: Any correct FABIDEF macro was not provided by the user before the FABIGEN macro. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0042E NO CORRECT FABISPL MACRO

Explanation: The FABISPL macro is not for the use of users. System action: The generation of the randomizer will not be successful. The return code is 8. Programmer response: This parameter is not supported by the IMS High Performance Unload Sequential Subset Randomizer utility. FABI0043E NUMBER OF FABIDEF MACROS IS EXCESSIVE

Explanation: The FABIUNLS utility detected an unexpected situation while trying to analyze the control blocks of Sequential Subset Randomizer. System action: The FABIUNLS utility will issue an abend. Programmer response: Save the dump, the JES log, the DBDGEN output, and the output of the randomizer generation. Then contact IBM Software Support. FABI0103E xxxxxxxxx COULD NOT BE OPENED

Explanation: More FABIDEF macros than currently supported were specified by the user. At the time this manual was written, a maximum of 1000 FABIDEF macros was supported. System action: The generation of the randomizer will not be successful. The return code is 12. Programmer response: Correct the error. FABI0044E SPLIT-NUMBER FOR DB xxxxxxxx(n) IS HIGHER THAN THE NUMBER OF DB-SPLITS DEFINED BY FABISPL MACRO

Explanation: The FABIUNLS utility could not open the indicated xxxxxxxxx data set (such as the HDR, TRL, FKDx, SYSPRINT, or SYSUT1 data set). System action: The FABIUNLS utility will issue an abend. Programmer response: Check for other error messages that describe reasons for the problems with opening the data sets. FABI0104E SYSUT1 DOES NOT BEGIN WITH A HEADER RECORD

Explanation: The FABIUNLS utility detected that the SYSUT1 data set does not start with a header record. System action: The FABIUNLS utility will issue an abend. Programmer response: Provide a proper SYSUT1
Chapter 28. Messages

Explanation: The FABISPL macro is not for the use of users. System action: The generation of the randomizer will

469

FABI0105E FABI0122I
data set. The SYSUT1 data set should contain a database unloaded in the format of the IMS HD Unload Utility. FABI0105E SYSUT1 DOES NOT END WITH A TRAILER RECORD FABI0112E THE NUMBER OF RAPS DEFINED DURING DBDGEN IS TOO SMALL

Explanation: The FABIUNLS utility detected that the SYSUT1 data set does not end with a trailer record. System action: The FABIUNLS utility will issue an abend. Programmer response: Provide a proper SYSUT1 data set. The SYSUT1 data set should contain a database unloaded in the format of the IMS HD Unload Utility. FABI0106E HEADER OR TRAILER RECORD MISSING ON SYSUT1

Explanation: The number of RAPs defined during the DBDGEN is too small. If the subset ID does not start at the first position of the root key, the number of RAPs must be at least equal to the number of subsets defined during the generation of Sequential Subset Randomizer. System action: Sequential Subset Randomizer will request either an abend (batch region) or a pseudo-abend (online region). Programmer response: Increase, in the DBDGEN specifications, either the number of RAPs per block/CI or the number of blocks/CIs located in the root addressable area. FABI0113E THERE IS AN INCONSISTENCY BETWEEN DBDGEN AND SEQUENTIAL SUBSET RANDOMIZER GENERATION

Explanation: The FABIUNLS utility detected that a header record or trailer record was missing in the SYSUT1 data set. System action: The FABIUNLS utility will issue an abend. Programmer response: Provide a proper SYSUT1 data set. The SYSUT1 data set should contain a database unloaded in the format of the IMS HD Unload Utility. FABI0107E ROOT SEGMENT HAS NO SEQUENCE-FIELD

Explanation: There is an inconsistency between: v The length of the root key field (as defined during DBDGEN) v The length and start position of the subset ID (as defined during the generation of Sequential Subset Randomizer) within the root key field. Notice that the subset ID must be completely within the root key field. System action: Sequential Subset Randomizer will request either an abend (batch region) or a pseudo abend (online region). Programmer response: Resolve the inconsistency between DBDGEN and Sequential Subset Randomizer generation. FABI0121E FABISTAT INTERNAL ERROR

Explanation: The FABIUNLS utility detected that the root segment of the unloaded database has no sequence field. Root segments without a sequence field are not supported by Sequential Subset Randomizer. System action: The FABIUNLS utility will issue an abend. Programmer response: If the root segment has no sequence-field, then a randomizer other than Sequential Subset Randomizer should be used. FABI0111E BINARY SEARCH IMPLEMENTED IN SEQUENTIAL SUBSET RANDOMIZER FAILED

Explanation: The binary search implemented in the FABISTAT failed. A root segment that is required by application program was not found in the range of this segments subset. System action: The FABISTAT will issue an abend. Programmer response: Contact IBM Software Support. FABI0122I SEQUENTIAL SUBSET STATISTICS WAS NOT CREATED

Explanation: The binary search implemented in Sequential Subset Randomizer failed. System action: Sequential Subset Randomizer will request either an abend (batch region) or a pseudo-abend (online region). Programmer response: Save the dump, the JES log, the DBDGEN output, and the output of the randomizer generation. Problem determination: Contact IBM Software Support.

Explanation: The FABISTAT exit routine did not created a Sequential Subset Statistics, because there is no statistics record. System action: None. Programmer response: Confirm that the correct name of randomizer was specified on the HSSROPT

470

Users Guide

SSSTATS control statement or the DBDGEN source statement.

Chapter 28. Messages

471

472

Users Guide

Part 5. Diagnosing problems

Chapter 29. Standard procedure for problem determination Chapter 30. Diagnostics Aid . . . . Running the Diagnostics Aid with JCL . Load Module/Macro APAR Status report Load Module APAR Status report. . Macro APAR Status report . . . . Messages and codes . . . . . . . Return codes . . . . . . . . . Abend codes . . . . . . . . . Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 477 477 478 478 479 479 479 479

Copyright IBM Corp. 2000, 2007

473

474

Users Guide

Chapter 29. Standard procedure for problem determination

A problem is determined by using procedures for identifying a failing hardware unit or program and determining which is responsible for the problem. Problem determination information is included, as appropriate, with the messages listed throughout this manual. In most cases, one or more numbers (for example, 4, 6) appear after the heading "Problem Determination" for a given message. These numbers are cross-references to the numbered items which are the actions to be taken by the user, listed below. Before you start the following problem determination activity, run the Diagnostics Aid utility (FABHDIAG) first to see the maintenance level of the product. For details, see Chapter 30, Diagnostics Aid, on page 477. The standard actions for problem determination actions are as follows: 1. Save the input associated with the job. 2. Save the JCL listing and a log of all MVS console messages. 3. Save the SYSUDUMP or SYSABEND dump. 4. 5. 6. 7. 8. 9. Save the HSSRSNAP output. Save the HSSRTRAC output. Save the PSBGEN and DBDGEN assembly listings. N/A N/A Activate the compare and hard-copy trace options, and run the failing call sequence with FABHTEST utility. Notes: a. Running the failing call sequence with FABHTEST (instead of the application program) eliminates the possibility that the application program will destroy code or control blocks of High Performance Unload. b. The compare option will check whether HSSR Engine returns the same PCB feedback and I/O area as DL/I would have returned. c. The hard-copy trace option provides a trace of HSSR Engine activities and control blocks. This trace can be used by the system programmer to find out why HSSR Engine made the error. d. The trace option should be activated by issuing the START keyword at a point before the error occurred. e. The TRHC control statement requests that call information, buffer handler information, control blocks (CB), and buffer control blocks (BUFCB) be traced. A TRDB control statement must be included. Make sure that the correct versions of DBDs, PSBs, and ACBs are being used. Contact IBM Software Support. Check whether the database that was processed by HSSR Engine was being updated at the time of the error. At the time of the problem, Register 0 contained a VSAM reason code, which is described in the chapter VSAM Macro Return and Reason Codes of DFSMS/MVS Macro Instructions for Data Sets. The content of the general

10. 11. 12. 13.

Copyright IBM Corp. 2000, 2007

475

registers 0 through 15 can be found in the dump, within the module FABH001, in the diagnosis area. This area has the following layout: v A 16-byte eye-catcher: 'DIAGNOSIS AREA' v A double-word PSW v Sixteen full-words, showing the content of registers 0 through 15 14. Save the SYSPRINT output. 15. Try to bypass the problem temporarily by using the Basic Buffer handler instead of CAB.

476

Users Guide

Chapter 30. Diagnostics Aid

If you have a problem that you think is not a user error, you should run the Diagnostics Aid (FABHDIAG), obtain the Load Module/Macro APAR Status Report, attach it to the other diagnostic documents (such as job dump list or I/O of the utility), and report the error to IBM. The Diagnostics Aid generates a Load Module/Macro APAR Status Report. This report shows the latest APAR fixes applied to each module and macro. The Diagnostics Aid is not applicable for any other versions or releases. Topics: v Running the Diagnostics Aid with JCL v Load Module/Macro APAR Status report v Messages and codes on page 479

Running the Diagnostics Aid with JCL

To run the Diagnostics Aid (FABHDIAG), supply an EXEC statement and a DD statement that defines the output data set. EXEC This statement must be in the following form:
//stepname EXEC PGM=FABHDIAG

SHPSLMD DD This statement defines the library containing the load modules (usually HPS.SHPSLMD0) for which you have a problem. The Load Module APAR Status Report is not generated if this DD statement is not provided or if DD DUMMY is specified. It is always recommended that you specify this DD statement. SHPSMAC DD This statement defines the library containing the provided macros (usually HPS.SHPSMAC0) for which you have a problem. The Macro APAR Status Report is not generated if this DD statement is not provided or if DD DUMMY is specified. SYSPRINT DD This output data set contains the Load Module/Macro APAR Status Report. The data set contains 133-byte, fixed-length records. It can reside on a tape, direct access device, or printer; or it can be routed through the output stream. If BLKSIZE is coded in the DD statement, it must be a multiple of 133. However, it is recommended that you use:
//SYSPRINT DD SYSOUT=A

Load Module/Macro APAR Status report

The Diagnostics Aid generates the following two reports for the maintenance by IBM: v Load Module APAR Status report v Macro APAR Status report

Copyright IBM Corp. 2000, 2007

477

Load Module APAR Status report

This report contains the following information: MODULE LIBRARY This includes the data set names specified in the SHPSLMD DD statement. If more than 30 data sets are concatenated, only the first 30 data sets are listed. MODULE NAME This is the name of the load module member or the alias. ALIAS-OF This is the name of the original member of the alias. If the module name is not an alias, this field is left blank. CSECT NAME This is the name of the included CSECT in the module. The CSECT names are reported in the included order in the module. APAR NUMBER This is the latest APAR number applied to the module represented by the CSECT name. If no APAR is applied, NONE is shown. APAR FIX-DATE This is the date when the modification was prepared for the module represented by the CSECT name. If no APAR is applied, N/A is shown. Notes: 1. If the CSECT name does not start with FAB, HPS, or the program structure of the CSECT does not conform to the High Performance Unload module standard to identify the APAR number and the APAR fixed date, the fields APAR NUMBER and APAR FIX-DATE are filled with asterisks (*). 2. If the load module is a member of the PDSE library, the following statement is shown on the report line and the job completes with a return code of 4.
** IT CAN NOT BE ANALYZED DUE TO PDSE LIBRARY MEMBER **

3. If the load macro fails for a utility member, the following statement is shown on the report line and the job completes with a return code of 8.
** IT CAN NOT BE ANALYZED DUE TO LOAD FAILED MEMBER **

Macro APAR Status report

This report contains the following information: MACRO LIBRARY This includes the data set names specified in the SHPSMAC DD statement. If more than 30 data sets are concatenated, only the first 30 data sets are listed. MACRO NAME This is the name of the macro member or the alias. ALIAS-OF This is the name of the original member of the alias. If the macro name is not an alias, this field is left blank. APAR NUMBER This is the latest APAR number applied to the macro. If no APAR is applied, NONE is shown.

478

Users Guide

FABU1001I FABU1006W
APAR FIX-DATE This is the date when the modification was prepared for the macro. If no APAR is applied, N/A is shown. Note: If the macro source statement structure does not conform to the High Performance Unload macro standard to identify the APAR number and the APAR fixed date, the fields APAR NUMBER and APAR FIX-DATE are filled with asterisks (*).

Messages and codes

This section explains the messages and codes of FABHDIAG.

Return codes
FABHDIAG contains the following return codes: 0 4 8 Successful completion of the program. Warning messages were issued, but the requested operation was completed. Error messages were issued, but the request operation was completed.

Abend codes
All 36xx abend codes are accompanied by an FABU36xx message. Refer to the appropriate message for problem determination.

Messages
FABU1001I DIAG ENDED NORMALLY generated by Diagnostic Aid to determine the nature and the cause of the detected errors. Correct the problem and rerun the job. FABU1005W SHPSLMD DD STATEMENT NOT FOUND FABU1005W SHPSMAC DD STATEMENT NOT FOUND Explanation: Diagnostic Aid could not find the SHPSLMD/SHPSMAC DD statement. System action: Diagnostic Aid sets an end-of-job return code of 4 and continues processing. Diagnostic Aid does not generate a report for the load module or the macro. Programmer response: If you intended to specify the indicated DD statement, correct the error and rerun the job. FABU1006W DUPLICATE member name IN LIBRARY DDNAME ddname Explanation: Diagnostic Aid found a duplicated member in the concatenated libraries. System action: Diagnostic Aid uses the member which is first found in the concatenated libraries.
Chapter 30. Diagnostics Aid

Explanation: This message is generated when Diagnostic Aid has been completed successfully. System action: Diagnostic Aid completes the job successfully with a return code of 0. Programmer response: None. FABU1002W DIAG ENDED WITH WARNINGS Explanation: This message is generated when trivial error conditions are encountered by Diagnostic Aid. System action: Diagnostic Aid ends with a return code of 4. Programmer response: Refer to other messages generated by Diagnostic Aid to determine the nature and the cause of the detected errors. Correct the problem and rerun the job. FABU1003E DIAG ENDED WITH ERRORS Explanation: This message is generated when severe error conditions are encountered by Diagnostic Aid. System action: Diagnostic Aid ends with a return code of 8. Programmer response: Refer to other messages

479

FABU1007W FABU3605E
Diagnostic Aid sets an end-of-job return code of 4 and continues processing. Programmer response: Ensure which libraries have correct module/macro libraries. Correct the error and rerun the job if necessary. FABU1007W DUMMY SPECIFIED FOR SHPSLMD DD STATEMENT FABU1007W DUMMY SPECIFIED FOR SHPSMAC DD STATEMENT Explanation: DUMMY was specified for the SHPSLMD/SHPSMAC DD statement. System action: Diagnostic Aid sets an end-of-job return code of 4 and continues processing. Diagnostic Aid does not generate a report for the load module or the macro. Programmer response: If you did not intend to specify the dummy DD statement, correct the error and rerun the job. FABU1008W NO MODULE MEMBERS FOUND IN DDNAME SHPSLMD FABU1008W NO MACRO MEMBERS FOUND IN DDNAME SHPSMAC Explanation: Diagnostic Aid could not find any utility modules or macros members from the DD ddname data set. System action: Diagnostic Aid sets an end-of-job return code of 4 and continues processing. Programmer response: Ensure that the libraries have correct utility module or macro libraries. Correct the error and rerun the job. FABU2001E LOAD FAILED FOR DDNAME ddname MODULE member Explanation: Diagnostic Aid could not load a member name from ddname. System action: Diagnostic Aid sets an end-of-job return code of 8 and continues processing. Programmer response: Ensure that the member indicated exists in the data set specified for the indicated ddname. Correct the error and rerun the job. FABU3600E OPEN FAILED FOR DDNAME ddname Explanation: The named DCB could not be opened. System action: Diagnostic Aid ends with an abend code of U3600. Programmer response: Ensure that a ddname DD statement exists, and that it specifies the correct DD FABU3605E DELETE FAILED FOR MODULE member Explanation: Diagnostic Aid could not delete a member name. System action: Diagnostic Aid ends with an abend code of U3605. parameter. Correct any errors and rerun the job. FABU3601E GET FAILED FOR DDNAME ddname Explanation: The GET failed for a directory from the DD ddname data set. System action: Diagnostic Aid ends with an abend code of U3601. Programmer response: Refer to the MVS system message and its programmer response. Correct the error and rerun Diagnostic Aid. If the error persists, contact IBM Software Support. FABU3602E READ FAILED FOR DDNAME ddname MEMBER member Explanation: The READ failed for a member from the DD ddname data set. System action: Diagnostic Aid ends with an abend code of U3602. Programmer response: Refer to the MVS system message and its programmer response. Correct the error and rerun Diagnostic Aid. If the error persists, contact IBM Software Support. FABU3603E BLDL FAILED FOR DDNAME ddname MEMBER member Explanation: The member was not found when the BLDL macro searched the PDS directory for the ddname. System action: Diagnostic Aid ends with an abend code of U3603. Programmer response: Ensure that the member indicated exists in the data set specified for the indicated ddname. Correct the error and rerun the job. If the error persists, contact IBM Software Support. FABU3604E LOAD FAILED FOR DDNAME ddname MODULE member Explanation: Diagnostic Aid could not load the member name from the ddname. System action: Diagnostic Aid ends with an abend code of U3604. Programmer response: Refer to the MVS system message and its programmer response. Correct the error and rerun Diagnostic Aid. If the error persists, contact IBM Software Support.

480

Users Guide

FABU3606E FABU3612E
Programmer response: Contact IBM Software Support. FABU3606E PUT FAILED FOR SYSPRINT Explanation: Diagnostic Aid could not put report data in SYSPRINT. System action: Diagnostic Aid ends with an abend code of U3606. Programmer response: Refer to the MVS system message and its programmer response. Correct the error and rerun Diagnostic Aid. If the error persists, contact IBM Software Support. FABU3607E OPEN FAILED FOR SYSPRINT Explanation: SYSPRINT DCB could not be opened. System action: Diagnostic Aid ends with an abend code of U3607. Programmer response: Ensure that a ddname SYSPRINT DD statement exists, and that it specifies the correct DD parameter. Correct any errors and rerun the job. FABU3608E FIND FAILED FOR DDNAME ddname MEMBER member Explanation: The FIND failed for a member from DDNAME ddname data set. System action: Diagnostic Aid ends with an abend code of U3608. Programmer response: Ensure that the member indicated exists in the data set specified for the indicated ddname. Correct the error and rerun the job. If the error persists, contact IBM Software Support. FABU3609E DEVTYPE FAILED FOR DDNAME ddname Explanation: The DEVTYPE failed for a DDNAME ddname data set. System action: Diagnostic Aid ends with an abend code of U3609. Programmer response: Contact IBM Software Support. FABU3610E RDJFCB FAILED FOR DDNAME ddname Explanation: The READJFCB failed for a DDNAME ddname data set. System action: Diagnostic Aid ends with an abend code of U3610. Programmer response: Contact IBM Software Support.
Chapter 30. Diagnostics Aid

FABU3611E GETMAIN FAILED. INSUFFICIENT STORAGE TO RUN THE JOB Explanation: Work space for Diagnostic Aid could not be obtained. System action: Diagnostic Aid ends with an abend code of U3611. Programmer response: Increase the region size and rerun the job. FABU3612E TOO MANY MODULE MEMBERS DETECTED IN DDNAME SFABMOD FABU3612E TOO MANY MACRO MEMBERS DETECTED IN DDNAME SHPSMAC Explanation: There are too many utility members in the SFABMOD/SHPSMAC DD data set. System action: Diagnostic Aid ends with an abend code of U3612. Programmer response: Specify the correct data set for the indicated DD statement and rerun the job.

481

482

Users Guide

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

483

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation J46A/G4 555 Bailey Avenue San Jose, CA 95141-1003 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Programming interface information

This book documents general-use programming interface and associated guidance information, product-sensitive programming interface and associated guidance information, and diagnosis, modification, or tuning information provided by IMS. General-use programming interface enable the customer to write programs that obtain the services of IMS. General-use programming interface and associated guidance information is identified where it occurs, either by an introductory statement to a chapter or section or by the following marking: General-Use Programming Interface General-use programming interface... End of General-Use Programming Interface Product-sensitive programming interface enable the customer installation to perform tasks such as diagnosing, modifying, monitoring, repairing, tailoring, or tuning of IMS. The 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 details of 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, either by an introductory statement to a chapter or

484

Users Guide

section or by the following marking: Product-Sensitive Programming Interface Product-sensitive programming interface and associated guidance information... End of Product-Sensitive Programming Interface Diagnosis, modification, or tuning information is provided to help the customer diagnose, modify, or tune High Performance Unload. Attention: Do not use this diagnosis, modification, or tuning information as a programming interface. Diagnosis, modification, or tuning information is identified where it occurs, either by an introductory statement to a chapter or section or by the following marking: Diagnosis, Modification, or Tuning Information Diagnosis, modification, or tuning information... End of Diagnosis, Modification, or Tuning Information

Trademarks and service marks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both: v AIX v COBOL/370 v DB2 v DFSMSdfp v DFSMS/MVS v IBM v IMS v IMS/ESA v Language Environment v MVS v MVS/DFP v MVS/ESA v OS/390 v Redbooks v VSE/ESA v z/OS v z/VM 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. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.
Notices

485

486

Users Guide

Index Special characters

*HD 282 *PHD 282 calls DL/I 299 formats 258 Assembler applications 258 COBOL applications 258 PL/I applications 259 Get-by-RBA 330 GN or GHN 301 GNR or GHNR 304 GU or GHU 304 HSSR 299 REPL 305 CARDIN 223, 224, 225 data set 56, 335 data set (FABHPSFC) 231 data set (FABHPSFM) 226 data set (FABHPSFS) 238 DD 55, 223, 224, 225 CARDIN (FABHFSU in PSF mode) DEC 62 END 66 GOT 63 PSC 237 CARDIN (FABHFSU) BLM/ESM 65 CO 260 CON 261, 267 DBD 57, 249 DEC 62 DECN 51, 63, 262 DECY 63 END 66 GOT 63 PARTITION 63, 109 PSB 58 SEGSTAT 64, 109 CARDIN (FABHPSFC) CTL 232 END 234 NPT 233 PSB 234 CARDIN (FABHPSFM) END 228 MAP 226 CARDIN (FABHPSFS) END 240 SUM 239 CARDIN data set (FABHFSU) 55, 56 CARDIN data set (FABHPSFC) 224 CARDIN data set (FABHPSFM) 223 CARDIN data set (FABHPSFS) 225 CBLHSSR 258, 259 chained anticipatory buffer (CAB) 33, 275, 309 description 275 Chained Anticipatory Buffer Handler (CAB) 275 Chained Anticipatory Buffering 23 CAB 121 CNTLDD 224, 225

A
accessibility 20 APISET control statement 123 application programming HSSR Engine 83 Sequential Subset Randomizer 374 ASMHSSR 258

B
basic buffer (BB) 295 description 295 Basic Buffer Handler (BB) 275, 295 BB 275, 296 BLDLPCK 23, 30, 34, 39, 93, 121, 251, 258 control statement 102, 385 BUFDEFAULT 338 =BB 338 =CAB 338 buffer handler BB 275 CAB 22, 275 initialization exit 314 tuning 275

C
CAB 23, 275 CABSTAT 122 default values of buffering parameters 256 how to tune 289 inter-PCB look-aside 286 statistics 125, 289 Statistics report 147 tuning 289 CAB buffering 279 CAB control statements 279 for FABHULU jobs 293 CABDD 277, 293 *ALL 293 control statement 280 groups 293, 294 multiple 293 specifying multiple 294 statement 280 CABDEFAULT =DBT 339 =HPU 339 CABSTAT 289 NO 289 YES 147, 150, 289
Copyright IBM Corp. 2000, 2007

487

CNTLDD (continued) DD 224, 225 CNTLDD data set (FABHPSFC) 224 compatibility HSSR V2 Branch Office Randomizer 369 control statements FABHFSU BLM/ELM 65 CO 260 CON 267 DBD 57 DEC 62 END 66 GOT 63 PARTITION 63 PSB 58 PSC 237 SEGSTAT 64 FABHPSFC CTL 232 DBD 231 END 234 NPT 233 PSB 234 FABHPSFM END 228 MAP 226 FABHPSFS END 240 SUM 239 FABHTEST GN, GHN 301 GNR, GHNR 304 GU, GHU 304 PCB 301 REPL 305 FABHURG1 CHECKREC 44 DEC 42 EXIT 326 FALLBACK 45, 118 FRMT 41 MIGRATE 44 OFFS 328 PARTITION 43, 105 PCB 41 SEGSTAT 43, 105 ULEN 328 USEGMAX 329 HSSRCABP CABDD 280 INTER 286 NBRDBUF 284 NBRSRAN 284 OCCURRENCE 282 OVERFLOW 284 PARTPROC 287 RANSIZE 283 REFT4 286 HSSROPT 122, 123 BLDLPCK 123

control statements (continued) HSSROPT (continued) BUF 296, 311 BUTR 124 BYINDEX 125 CABSTAT 125 CALLSTAT 126 CO 126, 305 DATXEXIT 129 DBDL1 127 DBSTATS 127 GOTRETRY 130 HSSRDBD 130 HSSRPCB 131 KEYCHECK 132 LOUT 133 LSR 133 NOFIX 134 NOVSAMOPT 134 PARTINFO 135 RETRY 136 RTEXIT 136 SKERROR 137 SKIPVLC 138 TRDB 138, 305 TRHC 139, 305 TRXC 140

D
Data Conversion exit DFSDBUX1 129 routine 129 data definition statements (DD) FABHBSIM SYSUT1 310 FABHFSU 55 FABHPSFC 224 FABHPSFM 223 FABHPSFS 225 FABHTEST SYSIN 300 SYSPRINT 300 FABHURG1 39 HSSR 22 data flow FABIUNLS 359 generation of Sequential Subset Randomizer (SSRGEN) 351 SS-STATS (FABISTAT) 367, 368 data sets CARDIN 56, 335 CARDIN (FABHFSU) 55, 56 CARDIN (FABHPSFC) 224, 231 CARDIN (FABHPSFM 223 CARDIN (FABHPSFM) 226 CARDIN (FABHPSFS) 225, 238 CNTLDD (FABHPSFC) 224 DDITV02 95 DDOTV02 95 DFSSTAT 298

488

Users Guide

data sets (continued) DFSVSAMP 23, 298 extensions 97 HSSRBUTR 24, 141, 166 HSSRCABP 22, 45, 67, 280, 306, 311, 335 HSSREXTR (FABHEXTR) 216 HSSRLDEF 168, 170 HSSRLOUT 141, 166, 171 HSSROPT 22, 45, 67, 121, 122, 168, 173, 305, 311, 335, 369 HSSRSNAP 24, 141, 165 HSSRSTAT 24, 141, 170, 311, 369 HSSRTRAC 24, 141, 151, 175 IEFRDER 24 IMSDALIB 24 new extents of 97 PRNTOUT 67 PRNTOUT (FABHFSU) 55, 67 PRNTOUT (FABHPSFC) 224, 234 PRNTOUT (FABHPSFM) 223, 228 PRNTOUT (FABHPSFS) 225, 240 SYSIN 40, 173, 301, 335 SYSPRINT (FABHTEST) 300, 306 SYSPRINT (FABHURG1) 39, 46 SYSUT1 (FABHBSIM) 310 SYSUT1 (FABHURG1) 39 SYSUT2 (FABHURG1) 39 SYSUT3 (FABHURG1) 39 database administration 374 converting 347, 375 design 373 monitoring 377 physical clustering 344 retrievals 345 database level sharing 99 database tuning statistics 375 DB Tuning Statistics 167 description of 177 DB2 18, 94, 263, 266 DBSTATS control statement 127, 167, 168 DD CARDIN 55, 223, 224, 225 CNTLDD 224, 225 data set 95 DDITV02 95 DDOTV02 95 DFSHALDB 102 DFSVSAMP 23, 45, 133, 258 HSSRBUTR 24 HSSRCABP 22 HSSRLDEF 23, 168 HSSRLOUT 24, 168 HSSROPT 22, 168, 172, 368 HSSRSNAP 24 HSSRSTAT 24, 168, 369 HSSRTRAC 24, 173 IMSDALIB 24 PRNTOUT 55, 223, 224, 225 RECONx 24

DD (continued) SYSIN 39, 172, 300 SYSPRINT 39, 300 SYSUDUMP 226 SYSUT1 39, 172, 310 SYSUT3 39 DDITV02 95 DDOTV02 95 DEC control statement 42, 62 DFSHALDB 102 HALDB control statement 102 DFSHDC40 343, 346, 347, 359, 375, 376, 377 DFSISVI0 exit 269 DFSSTAT data set 298 DFSURGU0 269 control statement 270 JCL compatibility 269 DFSISVI0 exit 269 DFSURGU1 data set 269 DFSURGU2 data set 270 return codes 387 STEPLIB data set 269 SYSIN data set 269 SYSPRINT data set 269 DFSURGU1 data set 269 DFSURGU2 data set 270 DFSVSAMP consideration on 116 data set 23, 298 DD 23, 45, 133, 258 diagnostics aid 477 disability 20 DL/I call 16, 89, 91, 139 using the Application Interface Block (AIB) interface 93 DSNMTV01 95

E
END statement 356 example FABIUNLS 363 generating Sequential Subset Randomizer (SSRGEN) 356 SS-STATS (FABISTAT) 372 EXEC DLI command 16, 89, 91, 136, 139 DL/I interface block (DIB) 86 exit routine FABHKEYX 116

F
FABH000 95 FABHBSIM execution steps 310 JCL 310 FABHCEX 314 FABHDB2 95, 266 FABHEXTR 213 FABHFSU 49, 219, 348, 367, 368, 375
Index

489

FABHFSU (continued) control statements 66, 237 JCL 54 output formats 51 HS 51 PHD 103 UL 30, 51, 103 VB 53 VN 54 Pointer Bypass option 250 reports 67 Sequence Check option 250 unloading a corrupted database 249 using the Pointer Bypass option 249 FABHKEYX data set 116 exit routine 116 FABHLDBR utility 171 printing long database records with 171 FABHOPT macro FSUBUFNO= 336 URG1BUFNO= 336 FABHOPT option table 336 FABHOPTG sample JCL 336 FABHPSFC 223 control statements 231 JCL 223 FABHPSFM 223 control statements 226 JCL 223 FABHPSFS 231 control statements 239 FABHRCEX 313, 385 FABHRTEX 313 FABHTEST control statements 301 execution steps 300 JCL 300 performance testing 308 problem determination 307 report 306 FABHTOPT macro 337 APISET= 337 BUFDEFAULT= 337 CABDEFAULT= 337 CABSTAT= 337 COMPAT= 337 DIAGG= 337 FSUDEC= 337 LSR= 337 PCBLIST= 337 URGIDEC= 337 FABHURG1 33, 348, 367, 368, 375 control statements 41 fallback unload 105, 115 JCL 38 logic 317 migration unload 105, 115 output formats 35 *CS Format 38 *F1 Format 35

FABHURG1 (continued) output formats (continued) *F2 Format 36 *F3 Format 37 *HD Format 30, 35, 103 *PHD Format 103 reports 46 SKERROR option 250 user exit routine (FABHEXTR) 213 FABHURGU1 EXIT FABHKEYX 116 FABIDEF macro statement 355 FABIGEN macro statement 356 FABISTAT 367 See SS-STATS FABITAB macro statement 353 FABIUNLS 348, 359 data flow 359 examples 363 JCL 360 job steps 359 output 361 FALLBACK 115, 328, 329, 330 control statement 45 fallback unload 115, 118 example of 118 FABHFSU 119 from HALDB 29 partitioned secondary indexes 34, 119 FKDn data set 361, 363 FSU II 267

G
generation of Sequential Subset Randomizer 345, 348, 351 data flow 351 example 356 input 352 JCL 352 JCL procedure 352 job steps 351 macro statements 353 Get-by-RBA calls 330

H
HALDB 15, 22, 23, 28, 33, 63, 70, 103, 275, 279 buffering statistics 147 CAB buffer sharing for 279 Get-by-RBA call 330 Online Reorganization (OLR) 31 PARTINFO ACC 135 PARTINFO DEF 135 partition 47 Partition Definition report 107, 108, 110, 112, 135, 142 Partition Definition utility 103, 291 Partitions Accessed report 108, 112, 135, 143 random access to 114

490

Users Guide

HALDB (continued) restrictions for processing 118 sequential access for 113 unload in PSF mode 119 HALDB control statement 102 HALDB Partition Definition report 142 PARTINFO DEF 135 HALDB Partitions Accessed report 143 PARTINFO ACC 135 HALDB Single Partition Processing 102 DFSHALDB DD 102 HALDB control statement 102 hardware requirements 18 HDAM 74, 275, 290 GOTRETRY control statement 130 lack of IRLM 99 modifying segments in user exits 74 partitioned 16 secondary index 32, 57, 125 SKERROR control statement 137 SKERROR option 249 SKIPVLC control statement 138 support of the processing options GON and GOT 98 HDMB 332 HDMBOS8G 332 HDR data set 360, 363 HIDAM 11, 275 a large number of GU calls to 297 BYINDEX control statement 125 GOTRETRY control statement 130 lack of IRLM 99 LSR control statement 133 modifying segments in user exits 74 NOFIX 134 NOVSAMOPT 134 PARTINFO 135 partitioned 16 RETRY 136 RTEXIT 136 secondary index 32, 57, 125 SKERROR 137 SKERROR option 249 SKIPVLC 138 support of the processing options GON and GOT 98 TRDB 138 TRHC 139 TRXC 140 High Availability Large Database 15, 103 High Speed Sequential Retrieval (HSSR) 11 See HSSR Engine HISAM 275 overflow area 275 SKERROR control statement 137 SKIPVLC control statement 138 HJCB 331 HSDB 332 HSSR application program 17, 21, 25, 27, 93, 96, 103, 112, 276 buffering functions available to 275

HSSR application program (continued) coding JCL for your 112 DB2 DL/I Batch interface 94 FABHFSU 49, 50 FABHURG1 33 improved performance for 290 run in a block-level sharing environment 97 written in COBOL or PL/I language 381 HSSR buffer handler 97, 100, 101, 275, 276, 279, 282, 283 control blocks of 153 direct 276 FABHBSIM 309 FABHCEX 315 invalidates buffers 98 simulation utility 124, 166 HSSR call 16, 89, 91, 136, 139, 258, 299, 309 API 11 CO 122 data capture exit routine 93 DB Call Statistics Report 143 DBDL1 122 explicit 258 functions 15 router 16 status codes 86 test utility 299 trace 309 using 299 using the Application Interface Block (AIB) interface 93 HSSR call handler 331 BLDLPCK 123 HSSR Engine xxi, 11, 16, 27, 98, 129, 275 abends issued by 381 buffer handler component of 121 call analyzer and call handler components of 121 CHKP and XRST calls 96 considerations for block level sharing 99 control statements for 40, 56 Data Conversion exit 129 database-sharing 97 DB Tuning Statistics report 167 DIAGG option 250 diagnostic information 128 GOTRETRY control statement 130 hard-copy tracing option of 139 HSSRCABP 40, 56 HSSRLOUT data set 171 HSSROPT 40, 56 KEYCHECK GG option 250 lack of IRLM 99 list of HSSROPT control statements for 121 LRU algorithms 169 mapping macros of control blocks 261 product-sensitive control block 261 reports and output produced by 121, 141 RETRY control statement 136 RTEXIT control statement 136 SKERROR option 249, 250 snapshot of control blocks of 165
Index

491

HSSR Engine (continued) specifying options for 121 SS-STATS statistics of 207 support of the processing options GON and GOT 98 test utility 299 trace function provided by 121 HSSR PCB 16, 25, 41, 89, 127 AIB interface 93 DL/I calls for 89 FABHPCB 334 FABHURG1 41 field sensitivity for 93 HSSRDBD 121, 130 HSSRPCB 121, 131 KEYLEN 257 number of basic buffers for 257 parameter 4: HSSR PCB 322 SKERROR control statement 137 SKIPVLC control statement 138 specifying through KEYLEN 257 XRST call 96 HSSR V2 Branch Office Randomizer compatibility 369 HSSRBUTR 21 data set 24, 166 DD 24 HSSRCABP 21, 67 CABDD 280 control statement 277, 280 data set 16, 22, 45, 67, 121, 277, 280, 306, 311, 335 data set (FABHBSIM) 311 data set (FABHTEST) 306 DD 22 FABHBSIM 311 FABHTEST 306 INTER 286 NBRDBUF 284 NBRSCAN 284 OCCURRENCE 282 OVERFLOW 284 PARTPROC 112, 287 RANSIZE 283 REFT4 286 HSSRDBD control statement 130 HSSREXTR (FABHEXTR exit routine) 216 EXTR 214, 216 PARTEXTR 214, 216, 217 SKIP 216 HSSREXTR control statements 216 HSSRLDEF 21, 168 data set 21, 168, 170 DD 23, 168 HSSRLOUT 21, 168 data set 21, 166, 171 DD 24, 168 HSSROPT 21, 23, 67, 105, 168, 172, 368 APISET 23, 90, 121, 123 APISET 1 90, 123, 152 APISET 2 23, 90, 123, 152

HSSROPT (continued) APISET (continued) APISET 3 23, 90, 123, 124, 127, 128, 137, 152, 158 BLDLPCK 123 BUTR 124 BYINDEX 125 CABSTAT 125 CALLSTAT 105, 109, 112, 126 CO 126 control statements 121, 122 HDSTATS and NOSAMEOPT 256 Control Statements report 141 data set 16, 45, 67, 121, 122, 167, 168, 173, 305, 311, 335, 369 DATXEXIT 129 DBDL1 127 DBSTATS 127 DD 22, 168, 172, 368 DIAGG 128 FABHBSIM 311 FABHTEST 305 GOTRETRY 130 HDSTATS 256 HSSRDBD 130 HSSRPCB 131 KEYCHECK 132 LOUT 133 LSR 133, 298 overview of 121 PARTINFO 105, 109, 112 PCBLIST 122, 135 HSSR 85, 135 IMS 136 syntax of 122 TRHC 139 TRXC 140 HSSROPT (BB) BUF 296 BUTR 296 HSSROPT (CAB) BUTR 280 NOFIX 280 NOVSAMOPT 280 HSSROPT (DB Tuning Statistics) DBSTATS 168 LOUT 169 HSSROPT data set 22, 122, 168, 368, 369 HSSROPT data set (FABHBSIM) 311 HSSROPT data set (FABHTEST) 305 HSSROPT data set (FABHURG1) 45 HSSRPCB 131 *ALL 294 HSSRSNAP 21 data set 24, 165 DD 24 HSSRSTAT 21, 168, 368 data set 17, 141, 170, 306, 311, 369 DD 24, 168, 369 HSSRTRAC 21 data set 24, 151, 175, 306

492

Users Guide

HSSRTRAC (continued) DD 24, 173

I
I/O Anticipatory (overlapped) chained sequential 276 Immediate (non-overlapped) chained sequential 276 IEFRDER data set 24 IMS Version 10 11 Version 8 11 Version 9 11 IMS HD Reorganization Unload (DFSURGU0) DFSURGU0 269 IMSDALIB 24 input generation of Sequential Subset Randomizer 352 SS-STATS (FABISTAT) 369 INTER 278 control statement 286 Inter-PCB look-aside buffering 276 between CAB buffer and BB buffer 276 introduction 11, 343

LPCK (continued) physical 124 virtual 75, 124, 251 LSR control statement 133

M
MBR= 95 message retrieval tool, LookAt xxiii messages 389 format 389 methods for accessing xxiii variables 389 MIGRATE 328, 329, 330 control statement 44 migration unload 23, 30, 44, 115, 116, 324 example of 116 FABHFSU 119 HDAM or HIDAM databases 115 HISAM databases 34, 115, 119 parameter 3: segment prefix 322 parameter 7: RBA of segment prefix 323 secondary indexes 34, 115, 119 sequence error 156 to HALDB 29, 30 exit routine FABHKEYX 116 monitoring the database 377

J
JCL FABHBSIM 310 FABHOPTG 336 FABHTEST 300 FABIUNLS 360 sample 336 SS-STATS (FABISTAT) 368 job control language See JCL job steps 367 FABIUNLS 359 generation of Sequential Subset Randomizer (SSRGEN) 351 SS-STATS (FABISTAT) 367

N
NBRDBUF 278 control statement 284 NBRSCAN 278 control statement 284 nonsequential randomizer 347

O
OCCURRENCE 277 control statement 282 orphans 363, 372, 374 output FABHBSIM 311 FABHFSU 245 FABHTEST 306 FABHURG1 46 FABIUNLS 361 HSSR 141 SS-STATS 369 OUTPUT-AREA 320 OVERFLOW 278 control statement 284 PPHDAM 278

K
keyboard shortcuts 20

L
logical parents concatenated key 30, 34, 75, 93, 123 LPCK 50 virtual 258 logical relationship 375 Look-aside buffering 276 LOUT control statement 169 LPCK 30, 34, 73, 75, 93, 123 area 73 building 102 defined as virtual 30

P
Parallel Scan Facility (PSF) 219, 245 execution steps 221 PARTINFO ACC 143
Index

493

PARTINFO (continued) control statement 135 DEF 107, 110, 142 DEF,ACC 108, 112 Partition Definition report 122 Partitions Accessed report 122 PARTITION control statement 43 partitioned secondary index 103 PARTPROC 279 control statement 287 random access 288 sequential access 287 PCB 345 PCB feedback interpreting 85 status code in 257 PCBLIST control statement 135 PHDAM 16, 60, 65, 114, 115, 219, 275, 290, 291, 339 BLM/ELM control statements 65 CO control statement 260 database 33, 113 FABHBSIM 309 GOTRETRY control statement 130 HALDB Buffering Statistics Report for 148 lack of IRLM 99 modifying segments in user exits 74 OVERFLOW 306 overflow area of each partition of 306 partitioned hierarchical direct access method 103 PARTPROC 306 PROCOPT=R 258 Randomizing Statistics report 178 REPL call 258, 300 SKERROR control statement 137 SKERROR option 249 SKIPVLC control statement 138 support of the processing options GON and GOT 98 Using Database Tuning Statistics 167 PHIDAM 16, 28, 57, 65, 115, 219, 275, 290, 339 a large number of GU calls to 297 BLM/ELM control statements 65 BYINDEX control statement 125 CO control statement 260 database 33 FABHBSIM 309 GOTRETRY control statement 130 lack of IRLM 99 LSR control statement 133 modifying segments in user exits 74 partitioned hierarchical indexed direct access method 103 PARTPROC 306 PROCOPT=R 258 REPL call 258, 300 SKERROR control statement 137 SKERROR option 249 SKIPVLC control statement 138

PHIDAM (continued) support of the processing options GON and GOT 98 Using Database Tuning Statistics 167 PLIHSSR 258, 259 PN82671 332 preface xxi prerequisite knowledge 19 PRNTOUT 223, 224, 225 data set (FABHFSU) 67 data set (FABHPSFC) 234 data set (FABHPSFM) 228 data set (FABHPSFS) 240 DD 55, 223, 224, 225 PROC See generation of Sequential Subset Randomizer, JCL procedure processing environment 18 PROG 95 program functions 344 program structure 348 PSINDEX 103

R
randomizing HDAM or PHDAM 28 RANSIZE 277 control statement 283 RECONx data set 24 DD 24 record formatting routine 318 Reference pattern analysis 276 REFT 278 REFT4 control statement 286 reports CAB Statistics 147 Data Set I/O Statistics 145 DB Call Statistics 143 DB Record Length Distribution 145 DB Statistics 145 FABHFSU Control Specifications 68 FABHFSU Control Statements 67 FABHFSU PSF Control Statements 228, 235, 241 FABHFSU PSF Extent Mapping 228 FABHFSU PSF Scan Control Data Set 235 FABHFSU PSF Summary 241 FABHFSU Segment Statistics 69 FABHTEST Control Statements 306 FABHURG1 Segment Statistics 46 FABHURG1 Unload Parameters 46 HSSROPT Control Statements 141 Randomizing Statistics 145 Sequential Subset Statistics 370 Split Unloaded Data Set Statistics 361 Trace Output 152 Trace Output for Diagnostics 155 restrictions 349 Return Code Edit exit routine 313, 385

494

Users Guide

return codes FABHBSIM utility 387 FABHFSU utility 385 FABHTEST utility 387 FABHURG1 utility 385 RTEXIT 313 run-time environment exit routine 313

S
sample exit routines 79 FABHOPTG 336 FABHRCEG 317 HPS.SHPSSAMP 25, 79, 317 HPSUXAA0 79 HPSUXCA0 79 HPSUXPA0 79 JCL 336 JCL for creating a database unload extract 217 JCL for the FABHLDBR utility 175 library 79 performing the fallback unload using FABHURG1 118 performing the migration unload using FABHURG1 115 Scan Control data set 231 screen readers and magnifiers 20 secondary index 32 DLI and DBB region 32 PCB PROCSEQ= parameter 32 ULU region BYINDEX control statement of HSSROPT 125 DBD control statement of FABHFSU 57 sequential randomizer 346, 347 Sequential Subset Statistics report 370 snaps 383 software requirements 18 Split Unloaded Data Set Statistics report 361 splitting the unloaded data set 345, 359 SPRBA 323 SPRBAFLG 323 SPRBAX4G 323 SS-STATS 346, 348, 367, 375 activation 369 data flow 367, 368 example 372 input 369 JCL 368 output 369 routine 367, 368 SSM= 95 SSRGEN 348 See generation of Sequential Subset Randomizer SSSTATS control statement 367, 368, 369 subset ID 344, 349, 373 SYSIN data set 40, 173, 301, 335 DD 39, 172, 300 FABHTEST 301

SYSIN (FABHLDBR) IO 174 LENGTH 173 NBR 173 ROOT-ONLY 174 SYSIN (FABHTEST) GHN 301 GHNR 304 GHU 304 GN 301 GNR 304 GU 304 PCB 301 REPL 305 SYSIN (FABHURG1) CHECKREC 44 DEC 42 EXIT 326 FALLBACK 45, 118 FRMT 41, 326 MIGRATE 44, 115 OFFS 328 PARTITION 43, 105, 217 PCB 40 SEGSTAT 43, 105 ULEN 328 USEGMAX 329 SYSIN data set 40 SYSIN data set (FABHTEST) 300, 301 GHN 301 GHNP 302 GHNR 304 GHU 304 GN 301 GNP 302 GNR 304 GU 304 PCB 301 REPL 305 SYSIN data set (FABHURG1) 39 CHECKREC 40 DEC 40 DECN 30, 35, 43, 48, 262 DECY 43 FALLBACK 40 FRMT 40 MIGRATE 40 PARTITION 40, 107 PCB 40 SEGSTAT 40 SYSPRINT data set 361 FABHTEST 300, 306 FABHURG1 39, 46 DD 39, 300 SYSUDUMP data set (FABHPSFC) 224 data set (FABHPSFM) 223 data set (FABHPSFS) 226 DD 226 SYSUT1 310
Index

495

SYSUT1 (continued) data set (FABHBSIM) data set (FABHURG1) DD 39, 172, 310 SYSUT2 data set (FABHURG1) DD 39 SYSUT2 39 SYSUT3 data set (FABHURG1) DD 39

310 39

39

39

T
TRL data set 361, 363 typical uses and benefits 347

U
unload fallback 33 migration 33 user tasks 373

V
VSAM SHAREOPTIONS (1,3) 101 (2,3) 101 (3,3) 101 100

W
wild card 114, 294

496

Users Guide

Program Number: 5655-E06

Printed in USA

SC27-0936-06