PK01994: NEW EXIT FOR FABHURG1 TO DISTRIBUTE UNLOAD RECORDS BY KEY VALUES

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• FABHURG1 provides an IBM-provided exit routine to distribute the
  unload records to multiple unload files.  This exit is used for
  migration to HALDB.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of IBM IMS High Performance        *
  *                 Unload for OS/390 Release 1 (FMID=H1IN110)   *
  ****************************************************************
  * PROBLEM DESCRIPTION: This APAR provides a new exit           *
  *                      (FABHKEYX) for FABHURG1 unload utility. *
  *                      This exit routine distributes           *
  *                      the unload records for migration to     *
  *                      HALDB  into multiple unload files       *
  *                      by the root key values.                 *
  ****************************************************************
  * RECOMMENDATION: Apply the maintenance for this APAR.         *
  ****************************************************************
  This APAR provides a new IBM-provided exit routine FABHKEYX.
  For the detail of this routine, see the below documentation
  change.
  

Problem conclusion

Temporary fix

Comments

• ========================
  = DOCUMENTATION CHANGE =
  ========================
  IMS High Performance Unload for OS/390 User's Guide
  (SC27093603) should be added the following description
  of this new function.
  
  ================================================================
  1.7        Processing High Availability Large Databases
  1.7.5      Migration Unload and Fallback Unload
  1.7.5.1    Migration Unload
  1.7.5.4    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: The control statement 'EXIT FABHKEYX' cannot be specified
  with the 'DECN' control statement.
  ================================================================
  1.7.5.4.1    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.
  
  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 Description
  1-8  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 C'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
              C'AAAAAAAAAAAA'
  
    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 X'FF's up to the defined root key
    length.
  
  ================================================================
  1.7.5.4.2   Example of Migration Unload with FABHKEYX Exit
  
  The following is an example JCL to distribute the unload records
  for migraion to HALDB to three 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 C'2999999'
   ULFPART2 C'5999999'
   ULFPART3 C'9999999'
   ULFPART4 X'FF'
   //ULFPART1   DD DSN=MIGDS1.MIGULDS.ULFPART1, ...
   //ULFPART2   DD DSN=MIGDS2.MIGULDS.ULFPART2, ...
   //ULFPART3   DD DSN=MIGDS3.MIGULDS.ULFPART3, ...
   //ULFPART4   DD DSN=MIGDS3.MIGULDS.ULFPART4, ...
  
  Note:
  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 X'FF' for the last DD name
  in the FABHKEYX data set not to throw segments away.
  ================================================================
  4.0        Messages and Codes
  4.4        Messages
  4.4.2      Message Variables
  4.4.2.1    FABH Messages
  
  FABH0684I DD=ddname01  HIGHKEY=KeyString
              SEGMENT=segname1   n,nnn,nnn,nnn OCCURRENCES
              *TOTAL             n,nnn,nnn,nnn OCCURRENCES
  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: 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: FABHURG1 ends abnormally.
  Programmer Response: Correct the statement.
  
  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:  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: 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: FABHURG1 ends abnormally.
  Programmer Response:
  - If the utility uses the maximum device capacity, check whether
    ddname can be allocated on a device with more track capacity.
  - 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.
  - 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:  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 deined in the root
  segment of the HDAM database.
  System Action:  FABHURG1 ends abnormally.
  Programmer Response: Remove the FABHKEYX exit routine from
  the EXIT control statement.
  ===================== End of Doc-Change ========================
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UK01769

Modules/Macros

•    FABHKEYX FABHLINK H1IN110J
  

Fix information

• Fixed component name

  IMS HIGHPERF UN

• Fixed component ID

  5655E0600

Applicable component levels

• R110 PSY UK01769

     UP05/03/25 P F503

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.