PK13859: HPIC PROVIDES RETURN CODE HANDLING

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• HPIC provides return code handling. By this APAR, the USER
  can change the Return code for HPIC
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All IMS High Performance Image Copy for z/OS *
  *                 Version 3 Release 2 users ( FMID=H1J0320 )   *
  ****************************************************************
  * PROBLEM DESCRIPTION: HPIC provides new input data set        *
  *                      HPSRETCD and new keyword RETCDDSN= in   *
  *                      order to specify return code freely.    *
  ****************************************************************
  * RECOMMENDATION: Apply the maintenance for this APAR.         *
  ****************************************************************
  New input data set HPSRETCD is provided for specifying the
  return code to the High Performance Image Copy JCL.
  
  .  //HPSRETCD  DD  *
  .  (HPIC)
  .  T2ERROR=xx,DBERROR=yy,PROCERROR=zz,IOERROR=aa,EMPTYIDX=bb
  .  /*
  
  This data set can be specified keyword that handles
  the following return code of:
  - HPPC T2 ERROR to T2ERROR=.
  - HPPC database errors to DBERROR=.
  - HPPC Space Monitor warning to SPMNWARN=.
  - HPPC space monitor error to SPMNERROR=.
  - ICDS put error for one of the dual ICs of to IOERROR=.
  - Compression routine warning to COMPWARN=.
  - Image Copy process for empty index to EMPTYIDX=.
  - Concurrent Image Copy process for index to INDEXCIC=.
  - Find fail for input ICDS to ICDSNOTF=.
  - Timestamp error to TMSERROR=.
  - Failure in loading HPPC or DEDBPC module for HASH
    to PCLOADER=.
  - DEDB Pointer Checker error to DEDBPCER=.
  The return codes must be two-digit number.
  
  A new report, HPSRETCD Statements report, is generated
  in the ICEPRINT data set, when HPSRETCD data set is specified.
  
  New keyword RETCDDSN= is provided for ICEIN GLOBAL statement.
  +--------------------------------------------------------------+
  |APAR PK12823 is required to be applied to IMS High Performance|
  |Pointer Checker for z/OS Version 2 Release 1 ( FMID=HPC2210 ).|
  +--------------------------------------------------------------+
  

Problem conclusion

Temporary fix

Comments

• A new module FABJRETM has been created. This module provides
  two functions as follows:
  - calling FABJRETC to analyze HPSRETCD statement and create
    return code table.
  - changing return code as specified in HPSRETCD statement.
  
  A new module FABJRETC, FABJRETS, FABJRETP, and FABJRETD
  have been created. These modules analyze HPSRETCD statement and
  create return code table.
  
  A new macro FABJRETT has been created. This macro provides a
  mapping of return code table.
  
  FABJMAIN, FABJDMPN, FABJDPSN, FABJCRC0, FABJCRC1, FABJRDB7,
  FABJRDB8, and FABJRDB9 has been modified to call new module
  FABJRETM.
  
  FABJPARM, FABJPRM2, FABJSTMD, FABJSTMP, FABJTGEN, and FABJBLKD
  have been modified to support the new keyword RETCDDSN= .
  
  FABJDALC has been modified to allocate HPSRETCD data set
  dynamically.
  
  FABJMSGC has been modified to add new message.
  
  FABUITCT has been modified to increase TCT version number.
  
  The following modules have been reassembled.
    FABJACQG  FABJATRC  FABJCMDB  FABJCTCV  FABJCZCV  FABJDALO
    FABJDALS  FABJDBCM  FABJDBC1  FABJDBD7  FABJDBD8  FABJDBD9
    FABJDBF0  FABJDBLK  FABJDBR7  FABJDBR8  FABJDBR9  FABJDCTL
    FABJDEMP  FABJDMP0  FABJDMP7  FABJDMP8  FABJDMP9  FABJDOPN
    FABJDPS7  FABJDPS8  FABJDPS9  FABJDPUT  FABJDREQ  FABJDRQS
    FABJICDD  FABJINT1  FABJINT2  FABJIPRC  FABJMAS1  FABJMDP7
    FABJMDP8  FABJMDP9  FABJMRGE  FABJNTFC  FABJORC7  FABJORC8
    FABJORC9  FABJRCH7  FABJRCH8  FABJRCH9  FABJRPT0  FABJSAS2
    FABJTERM  FABJUIC1  FABJXLIM  FABJDBDN  FABJDBRC  FABJMDPN
    FABJORCN  FABJRCHK
  
  ========================
  = DOCUMENTATION CHANGE =
  ========================
  IMS High Performance Image Copy for z/OS Version 3 Release 2
  User's Guide SC18-7617-01 ( SC18761701 ) should be changed as
  follows:
  
  2.2.1 FABJMAIN JCL
  Add Following DD statements in this section
    Table 1. DD statements of the FABJMAIN JCL
    +------------+--------+--------------+----------------------+
    |DDNAME      | Use    | Format       | Required of Optional |
    +------------+--------+--------------+----------------------+
    |HPSRETCD    | Input  | LRECL=80     | Optional             |
    +------------+--------+--------------+----------------------+
  
    Table 3. DD statements of HD Pointer Checker
    (HDPC=Y is specified)
    +------------+--------+--------------+----------------------+
    |DDNAME      | Use    | Format       | Required of Optional |
    +------------+--------+--------------+----------------------+
    | SPMNIN     | Input  | LRECL=80     | Optional             |
    +------------+--------+--------------+----------------------+
    | SPMNSPDT   | Input/ | Fixed Record | Optional             |
    |            | Output | Length       |                      |
    +------------+--------+--------------+----------------------+
  
   HPSRETCD DD
   This optional input data set contains the user-specified
   control statements that define the return code of
   the High Performance Image Copy process.
  
  2.2.1.1 Function-Unique DD Statements for the HPIC Image Copy
          Function
  Add following DD statements in this section:
   SPMNIN  DD
   This optional input data set contains the control statements.
   for Space Monitor of IMS High Performance Pointer Checker.
   For more details, see IMS High Performance Pointer Checker
   for z/OS, Version 2 Release 1, User's Guide Volume 2
   (SC18-7258)
  
   SPMNSPDT DD
   This optional input/output sequential data set is the
   Space Monitor of graph record data set.
   For more details, see IMS High Performance Pointer Checker
   for z/OS, Version 2 Release 1, User's Guide Volume 2
   (SC18-7258)
  
  2.3.4.1 GLOBAL Statement
  Add following keywords in following section
      RETCDDSN=
  
  2.3.5 ICEIN Keywords
  Add following sub section in following section
    2.3.5.xx RETCDDSN=
    The RETCDDSN keyword specifies the data set name which
    contains the HPSRETCD control statements.
    If you specify this keyword, HPIC attempts to allocate
    the data set dynamically.
    +---------------------------------------------------------+
    | RETCDDSN=data set name|data set name(member name)       |
    +---------------------------------------------------------+
    where:
     data set name
       Specifies the data set name which contains the HPSRETCD
       control statements.
  
     member name
       If you specify the HPSRETCD control statements in
       partitioned data set member, you must specify the member
       name.
  
    HPIC considers the data set as sequential file, unless you
    specify member name to this keyword.
  
    This keyword can be used in the following control statements:
        GLOBAL
  
  2.3 Input
  Add the following new section for 2.3.7
  
  2.3.x   HPSRETCD data set
   This section explains the HPSRETCD data set.
  
  2.3.x.1 Function
   The HPSRETCD data set contains your specification of the
   return code that is returned by High Performance Image Copy.
  
   2.3.x.2 Format
   This control data set usually resides in the input stream.
   However, it can also be defined 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.
   This data set should contain (HPIC) statements.
  
   Sample control statement format in the HPSRETCD data set
    //HPSRETCD  DD  *
    (HDPC)
      T2ERROR=12,DBERROR=16,
      IOERROR=24,EMPTYIDX=28
  
    Note:  On the control statement, code uppercase alphabetical
           characters, numerical characters, and the following
           special characters:
              asterisk       *
              comma          ,
              equal sign     =
              parenthesis    ( )
  
  2.3.x.3 Control Statement Syntax
   The following describes the coding conventions that you must
   follow in writing control statements in the HPSRETCD data
   set:
  
   - An (HPIC) control statement must be coded in the first
     line of the HPSRETCD data set, and optional parameters must
     be coded in the second or later lines.
   - The (HPIC) control statement and option parameters must be
     coded within column 2 and column 72.
   - When more than one option parameter is coded, they must be
     separated by commas.
     No blanks are allowed between the option parameters and the
     commas, or within the option parameters.
     Option parameters can be continued onto one or more
     following control statement records.
   - Option parameters are not positional parameters;
     they can be specified in any order of sequence.
     A null value is not allowed for any option parameter.
   - Comments can follow the last option parameter on each
     control statement record separated by at least one blank.
   - A comment line must begin with an asterisk in column 1.
   - The only control statement name that can be used within
     round brackets is HPIC, as in (HPIC).
  
   2.3.x.4 The (HPIC) Statement
   The (HPIC) statement specifies the options for return codes.
   There must be only one (HPIC) statement, and it must be the
   first control statement in the HPSRETCD data set.
  
   The (HPIC) statement contains optional parameters, which
   are specified by the following keywords:
    (HPIC)
     _                   _
    |    T2ERROR=nn|2     |
    |   ,DBERROR=nn|4     |
    |   ,SPMNWARN=nn|4    |
    |   ,SPMNERROR=nn|8   |
    |   ,IOERROR=nn|8     |
    |   ,COMPWARN=nn|0    |
    |   ,EMPTYIDX=nn|8    |
    |   ,INDEXCIC=nn|0    |
    |   ,ICDSNOTF=nn|8    |
    |   ,TMSERROR=nn|8    |
    |   ,PCLOADER=nn|4    |
    |   ,DEDBPCER=nn|2    |
    |_                   _|
  
    T2ERROR=
       Specify the return code when the T2 (unknown data) error
       is detected. nn is 0 to 99. The default value is 2.
    DBERROR=
       Specify the return code when a database error is detected.
       nn is 0 to 99. The default value is 4.
    SPMNWARN=
       If space monitor detects warning return code 4,
       HPIC returns the return code specified by this parameter.
       nn is 0 to 99. The default value is 4.
    SPMNERROR=
       If space monitor detects warning return code 8,
       HPIC returns the return code specified by this parameter.
       nn is 0 to 99. The default value is 8.
  
    T2ERROR, DBERROR, SPMNWARN and SPMNERROR are effective when
    HPIC runs with HD Pointer Checker which has applied APAR
    PK12823.
  
    IOERROR=
      If the I/O error is detected in either the primary or the
      secondary image copy process and HPIC can continue that
      process, HPIC returns the return code specified by this
      parameter. nn is 0 to 99. The default value is 8.
    COMPWARN=
      If a warning of compression routine is detected, HPIC
      returns the return code specified by this parameter.
      nn is 0 to 99. The default value is 0.
    EMPTYIDX=
      If HPIC finds empty index databases in processing Image
      Copy function, HPIC returns the return code specified by
      this parameter. nn is 0 to 99. The default value is 0.
    INDEXCIC=
      If HPIC attempts to process Concurrent Image Copy of index
      databases, HPIC returns the return code specified by this
      parameter. nn is 0 to 99. The default value is 0.
    ICDSNOTF=
      If HPIC can not find a valid input ICDS in processing
      Recovery function and Create Image Copy function,
      HPIC returns the return code specified by this parameter.
      nn is 0 to 99. The default value is 8.
    TMSERROR=
      In processing Recovery function and Create Image Copy
      function, if timestamp of input ICDS is different from
      DBRC record, HPIC returns the return code specified by this
      parameter. nn is 0 to 99. The default value is 8.
    PCLOADER=
      If HPIC fails in loading HP Pointer Checker module, HPIC
      returns the return code specified by this parameter.
      nn is 0 to 99. The default value is 4.
    DEDBPCER=nn
      If HPIC detects DEDB Pointer Checker error return,
      HPIC returns the return code specified by this parameter.
      nn is 0 to 99. The default value is 2.
  
    If multiple conditions for nonzero return code occur,
    HPIC returns the highest return code.
  
  3.2.2 Input
  Add following keyword in this section:
   - RETCDDSN
  

APAR Information

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

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

  UK08612

Modules/Macros

• FABJACQG FABJATRC FABJBLKD FABJCMDB FABJCRC0
  FABJCRC1 FABJCTCV FABJCZCV FABJDALC FABJDALO FABJDALS FABJDBCM
  FABJDBC1 FABJDBDN FABJDBD7 FABJDBD8 FABJDBD9 FABJDBF0 FABJDBLK
  FABJDBRC FABJDBR7 FABJDBR8 FABJDBR9 FABJDCTL FABJDEMP FABJDMPN
  FABJDMP0 FABJDMP7 FABJDMP8 FABJDMP9 FABJDOPN FABJDPSN FABJDPS7
  FABJDPS8 FABJDPS9 FABJDPUT FABJDREQ FABJDRQS FABJICDD FABJINT1
  FABJINT2 FABJIPRC FABJLINK FABJMAIN FABJMAS1 FABJMDPN FABJMDP7
  FABJMDP8 FABJMDP9 FABJMRGE FABJMSGC FABJNTFC FABJORCN FABJORC7
  FABJORC8 FABJORC9 FABJPARM FABJPRM2 FABJRCHK FABJRCH7 FABJRCH8
  FABJRCH9 FABJRDB7 FABJRDB8 FABJRDB9 FABJRETC FABJRETD FABJRETM
  FABJRETP FABJRETS FABJRETT FABJRPT0 FABJSAS2 FABJSTMD FABJSTMP
  FABJTERM FABJTGEN FABJUIC1 FABJXLIM FABUHXD2 FABUITCT H1J0320J
  

Fix information

• Fixed component name

  IMS HP IMAGE CO

• Fixed component ID

  5655K9600

Applicable component levels

• R320 PSY UK08612

     UP05/11/01 P F510

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.