PK04911: HP UNLOAD API SHOULD ALLOW GN CALL WITH A QUALIFIED SSA ON ROOT IN APISET=1

Obtain the fix for this APAR.

APAR status

• Closed as program error.

Error description

• In APISET=3, HP Unload API passes the GN calls with a qualified
  SSA on root segment to IMS DL/I. This causes a performance
  problem in a customer system.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of IBM IMS High Performance        *
  *                 Unload for OS/390 Release 1 (FMID=H1IN110)   *
  ****************************************************************
  * PROBLEM DESCRIPTION: If APISET 3 is specified, HP Unload API *
  *                      passes the GN calls with a qualified    *
  *                      SSA on the root segment to IMS DL/I     *
  *                      call handler. This caused a performance *
  *                      problem in a customer system.           *
  ****************************************************************
  * RECOMMENDATION: Apply the maintenance for this APAR.         *
  ****************************************************************
  To improve the performance of the application program,
  the GN call with a qualified SSA on root segment should be
  processed by HSSR Engine without passing it to the IMS DL/I
  call handler.
  

Problem conclusion

• The following call types are added to APISET 1.
  
   - 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.
  
     If the performance is not satisfactory, try
     the BYINDEX control statement in the HSSROPT data set.
  
  If APISET 2 or APISET 3 is specified, these call types are
  processed by HSSR Engine.
  
  ========================
  = DOCUMENTATION CHANGE =
  ========================
  IMS High Performance Unload for OS/390 User's Guide
  (SC27093603) should be changed as follows:
  
  ================================================================
  1.0       Using High Performance Unload
  1.6       Application Programming Interface
  1.6.2     Preparing and Running Application Program
  1.6.2.3   Coding 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 DL/I, depending on the type of the call and the API set
   specified.
  
  |If APISET 1 (default) or 2 is specified and an unsupported
  |call is issued against an HSSR PCB, HSSR Engine ends
  |abnormally. In this case, to be processed by DL/I,
  |you can specify APISET 3 or remove the PCB from the list
  |of HSSR PCBs which is specified by the HSSRPCB
  |or the HSSRDBD control statement.
  
   You can specify an API set by making it the site default or
   by including an APISET control statement in the HSSROPT data
   set.  For details, see "APISET Control Statement"
   and "Setting Site Default Options".
  
  ================================================================
  1.6.2.3.1 Call Types Supported by Each API Set
  
   High Performance Unload supports three API sets. APISET 1 is
   the system default. Table 12 shows the DL/I call types
   supported by each API set, and their effects with and without
   segment search arguments (SSAs):
  
   Table 12. DL/I Call Types Supported by Each API Set
  ---------------------------------------------------------------
   APISET 1
     The following call types are supported:
     - GU and GHU calls without SSA: the first root segment of
       the database is retrieved.
     - 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)
     - GN and GHN calls without SSAs.
     - GN and GHN calls with an unqualified SSA that contains
       the name of a root segment type.
  |  - 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.
  |      Note: If the performance is not satisfactory, try
  |      the BYINDEX control statement in the HSSROPT data set.
     - GNP and GHNP calls without SSAs.
  
   APISET 2
     The following call types are supported for HD and
     partitioned HD databases in addition to the call types
     supported in APISET 1:
     - GN and GHN calls with an unqualified SSA that contains
       the name of a dependent segment type.
     - GNP and GHNP calls with an unqualified SSA that contains
       the name of a dependent segment type.
  
   APISET 3
  (The following sentence is deleted. )
  >  Calls of types GU, GHU, GN, GHN, GNP, and GNHP are
  >  all supported.
  
  |  The fully supported call types are the same as those
  |  in APISET 2. Once an unsupported call is issued
  |  for an HD database or a partitioned HD database,
  |  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.
  ---------------------------------------------------------------
  
  ================================================================
  1.6.2.3.2 EXEC DLI Command Types Supported by Each API Set
  
   High Performance Unload supports three API sets. APISET 1 is
   the system default. Table 13 shows the EXEC DLI Command types
   supported by each API set, and their effects with and without
   SEGMENT options:
  
   Table 13. EXEC DLI Command Types Supported by each API Set
  ---------------------------------------------------------------
   APISET 1
     The following command types are supported:
     - GU command with a SEGMENT option and a WHERE option
  |    qualified on the root sequence key.
  |    In the WHERE option, 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)
     - GN command without SEGMENT options.
     - GN command with a SEGMENT option that contains the name of
       a root segment type.
  |  - GN command with a SEGMENT option and a WHERE option
  |    qualified on the root sequence key.
  |    In the WHERE option, any one of the following
  |    relational operator is available:
  |      - equal-to (=b,b=,or EQ)
  |      - greater-than-or-equal-to (>=,=>, or GE)
  |      - greater-than (>b,b>, or GT)
  |    This is not supported for HDAM or PHDAM database.
  |      Note: If the performance is not satisfactory, try
  |      the BYINDEX control statement in the HSSROPT data set.
     - GNP command without SEGMENT options.
  
   APISET 2
     The following command types are supported for HD and
     partitioned HD  databases in addition to the command types
     supported in APISET 1:
     - GN command with a SEGMENT option that contains the name
       of a dependent segment type.
     - GNP command with a SEGMENT option that contains the name
       of a dependent segment type.
  
   APISET 3
  (The following sentence is deleted.)
  >  Commands of types GU, GN, GNP, and RETRIEVE are all
  >  supported.
  
  |  The fully supported command types are the same as those
  |  in APISET 2. Once the unsupported command is issued
  |  for an HD database or a partitioned HD database,
  |  the command and all the succeeding commands 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 "PCB Feedback Information".
    For a complete description of the commands, options, and
    layout of the DIB and qualified commands, see IMS Application
    Programming: EXEC DLI commands.
  
  ================================================================
    1.6.2.3.3 Structure of the Application Program
  
    The application program has the same structure as the
    DLIBATCH application program.
    You can also issue a DL/I call for a DL/I PCB, other than
    HSSR calls, in your application program.
    DL/I calls for DL/I PCBs are processed by IMS, not by HSSR
    Engine.
  
  (The following sentence is deleted.)
  > If an unsupported call is issued against an HSSR PCB,
  > HSSR Engine ends abnormally.
  
  ================================================================
  4.0       Messages and Codes
  4.4       Messages
  4.4.2     Message Variables
  4.4.2.1   FABH Messages
  
  (In this section, FABH0319E is added.)
  ----------------------------------------------------------------
  | 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 "Call Types Supported by Each API
  | Set" or "EXEC DLI Command Types Supported by Each API Set".
  ----------------------------------------------------------------
  
  ===================== End of Doc-Change ========================
  

Temporary fix

Comments

• ×**** PE05/06/15 FIX IN ERROR. SEE APAR PK07157  FOR DESCRIPTION
  

APAR Information

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

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

  UK03891

Modules/Macros

•    FABHGDL7 FABHGDL8 FABHGDL9 FABHGND  FABHGSA
  FABHGSP  FABHJCB  FABHJCB0 FABH002  FABH100  FABH110  FABH500
  

Fix information

• Fixed component name

  IMS HIGHPERF UN

• Fixed component ID

  5655E0600

Applicable component levels

• R110 PSY UK03891

     UP05/05/28 P F505

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.