IBM Support

II14250: DIFFERENCES IN IDCAMS LISTCAT LEVEL PROCESSING IN Z/OS 1.8 AND LATER RELEASES

Subscribe to this APAR

By subscribing, you receive periodic emails alerting you to the status of the APAR, along with a link to the fix after it becomes available. You can track this item individually or track all items by product.

Notify me when this APAR changes.

Notify me when an APAR for this component changes.

 

APAR status

  • INTRAN

Error description

  • IDCAMS LISTCAT processing in z/OS 1.8 and higher releases has
    been enhanced to provide better runtime performance and more
    diagnostic information. PTFs for OA22542 (UA47501, UA47502 and
    UA47503) should be considered mandatory maintenance as they
    roll up a number of corrections to IDCAMS LISTCAT processing.
    to IDCAMS LISTCAT processing.
    -------------------------------------------------------------
    .
    z/OS AMS LISTCAT does not support toleration, change controls,
    or guarantees being provided by formally defined IBM
    interfaces (API). z/OS AMS LISTCAT output format and contents
    may change as a result of service and new function support.
    IBM is not committed to maintain similarities in LISTCAT
    format between releases, SPEs, and service for automation.
    LISTCAT does not provide the documentation requirements,
    announcements, toleration support needed by a LISTCAT parsing
    application.  IBM recommends applications should use formal
    Application Programing Interfaces API.  Applications based on
    parsing LISTCAT output can aviod disruptions in LISTCAT
    changes by migrating to IBM Catalog Search Interface CSI.
    CSI can be invoked from Assembler, High level programs, & REXX.
    Note: LISTCAT only LISTs CATalog information.
    .
    AMS LISTCAT displays objects which are returned from Catalog:
    In z/OS V1R8, LISTCAT was modified to use the Catalog Search
    Interface (CSI).
    The objects returned from CSI are defined by the CSI interface
    and may produce different results than the prior generic
    LOCATE interface rules.  Results may differ in the return and
    condition codes or number of objects being returned by Catalog.
    .
    Review information for the Catalog Search Interface (CSI) in
    the z/OS DFSMS Managing Catalogs and HLASM Programmer's Guide
    to assist in determining expected results and differences.
    .
    Catalog provides filters preventing the listing of an object
    when using generic LOCATE. These filters may differ and
    not apply to CSI returned objects, values, and rules.
    IBM will review marketing change requests for the inclusion or
    exclusion of CSI provided objects by AMS LISTCAT.  IBM is not
    committing to maintain toleration of LISTCAT formats between
    releases, SPEs, and service.
    .
    IBM recommends applications processing LISTCAT output be
    migrated to IBM supported APIs or tools.
    To ease the migration of applications, a fallback APAR OA20472
    is provided in z/OS V1R8 and V1R9 for obtaining LISTCAT results
    as in prior releases.  Companion APAR OA22078 provides
    toleration support in z/OS V1R7 when utilizing fallback
    support in a PLEX running mixed releases including z/OS V1R7.
    .
    Fallback introduces a new entry point PGM=IDCNOGFL.  For
    migration ease, this entry point will remain in all future
    releases allowing a one time conversion.  PGM=IDCNOGFL will
    not be documented beyond associated APARs. In a future release
    to be determined, IDCNOGFL invocation will change to the newer
    CSI interface producing the same results as PGM=IDCAMS.
    Migration plans should be established to migrate applications
    dependant on prior LISTCAT formats to IBM supported solutions.
    .
    If there is a continued need for prior generic locate results,
    please contact IBM as described in z/OS DFSMS Introduction,
    copied below.
    ---
    z/OS V1R8 V1R9 DFSMS Introduction (copied March 14 2008).
    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 Mail
    Station P300 2455 South Road Poughkeepsie, NY 12601-5400 USA
    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.
    ---
    Another option is a STEPLIB to a z/OS V1R7 version of IDCAMS.
    z/OS V1R7 version of IDCAMS may not recognize features or
    satisfy requirements of later releases.  Proper tests are
    required before accepting STEPLIB as a solution for each
    release STEPLIB will be used.  STEPLIB usage should be added
    to future release migration and test plans until a proper
    replacement solution is provided.
    .
    For extreme outage related to automated program dependancy on
    LISTCAT output, please open a PMR providing IBM a description
    of the outage and impact, requesting temporary relief.  The
    following questions will help assess the impact. Please include
    additional impact statements as needed to help clarify the
    relief needed.  Suggested Impact Questions:
     o Description of the impact, outage, scope
     o How are the jobs critical to your business?
     o Description of any time limitations and impact results
     o How many jobs are affected?
     o Description of SYSTEM and PLEX dependancies
     o additional info to help understand your particular
       requirements.
    .
    LISTCAT provides catalog information in human readable
    format.  Provided an availability of the PGM=IDCNOGFL fallback
    option, IBM requests all sev1 and sev2 APARs reporting errors
    in the new LISTCAT results should include the above impact
    statements for improved reviews and relief.
    .
    IBM may request the use of fallback support as relief for an
    error in the new CSI interface until a proper solution can be
    provided via a field fix or release offering.  If fallback
    support does not provide needed relief, please provide the
    above impact statements to IBM service who will forward your
    request for review.  For automated applications which are
    exposed to errors discovered in the new interface, IBM
    recommends utilizing the fallback APAR and migrating the
    application to an IBM supported solution.
    .
    --------------------------------------------------------------
      If you run an IDCAMS LISTCAT CAT(your.catalog.name) ALL or a
    LISTCAT LEVEL and there are catalog entries that indicate the
    data set is on a sms managed volume if the data set does not
    actually exist on the volume you will receive the following
    messages:
    IDC3014I CATALOG ERROR
    IDC3009I ** VSAM CATALOG RETURN CODE IS 50- REASON CODE IS
             IGG0CLE0-6
    IDC1566I ** your.deleted.dataset NOT LISTED
      and the LISTCAT will end with a condition code of 4. In prior
    releases, you would receive what information is available from
    the catalog and the LISTCAT would end with a condition code of 0
      If you have catalog entries that indicate the data set is not
    on a sms managed volume and the data set does not exist, you
    will continue to receive the information that is available from
    the catalog entry.
                                                                   .
      There are also some differences in how IDCAMS LISTCAT LEVEL
    processing works for GDG's and ALIASes. These changes make
    IDCAMS and ISPF option 3.4 more compatible.
      To illustrate these changes we will use the following
    data set names:
      SAMPLE.GDG
      SAMPLE.GDG.G0001V00
      SAMPLE.GDG.G0002V00
      Which are cataloged in catalog sample.catalog
      SAMPLE1.DATA.SET
      SAMPLE1.DATA.SET.TWO
      SAMPLE1              <= ALIAS
      which are cataloged in catalog sample.catalog.two
      In z/OS 1.8 if you run IDCAMS LISTCAT LEVEL(SAMPLE.GDG) you
    will receive the output below:
    GDG BASE ------ SAMPLE.GDG
         IN-CAT --- SAMPLE.CATALOG
                                                                   .
    NONVSAM ------- SAMPLE.GDG.G0001V00
         IN-CAT --- SAMPLE.CATALOG
                                                                   .
    NONVSAM ------- SAMPLE.GDG.G0002V00
         IN-CAT --- SAMPLE.CATALOG
      In prior releases the GDG BASE entry was not listed.
                                                                   .
      In z/OS 1.8 if you run IDCAMS LISTCAT LEVEL(SAMPLE1) you
    will receive the output below:
    NONVSAM ------- SAMPLE1.DATA.SET
                                                                   .
         IN-CAT --- SAMPLE.CATALOG.TWO
                                                                   .
    NONVSAM ------- SAMPLE1.DATA.SET.TWO
         IN-CAT --- SAMPLE.CATALOG.TWO
                                                                   .
    ALIAS --------- SAMPLE1
         IN-CAT --- YOUR.MASTER.CATALOG
      In prior releases the ALIAS entry was not listed.
    
    As a part of the above changes and the changes documented in
    the manual z/OS V1R8.0 DFSMS Using the New Functions the output
    listing from the IDCAMS LISTCAT command in z/OS 1.8 has been
    changed to include the additional header line per page as
    follows:
    (Pre z/OS 1.8)
    The output has following header line always after 17
    entries:
      IDCAMS  SYSTEM SERVICES   TIME: 10:08:42   09/28/06  PAGE 2310
    
    .
    (z/OS 1.8)
    The 1.8 output has following header lines always after 16
    entries:
      IDCAMS  SYSTEM SERVICES   TIME: 10:13:49   09/28/06  PAGE 2461
    .
                   LISTING FROM CATALOG -- SYS1.USER.CATALOG
    .
    This change might increase the number of lines or pages produced
    by IDCAMS LISTCAT commands. This is to be expected in z/OS 1.8
    and higher releases.
    .
    LISTCAT LEVEL processing in z/OS 1.8 and higher releases
    includes the following line:
       IN-CAT --- your.catalog.name
    In previous releases this line did not occur if the CATALOG
    parameter was specified on the LISTCAT LEVEL command.
    .
    If you wish to see these enhancements under TSO, you will need
    to set your TSO PROFILE to NOPREFIX. If your TSO PROFILE is
    PREFIX, then you will receive output as in previous releases.
    .
    Generation data sets GDS are now returned by Catalog in
    time sequence order.
    .
      When doing a listcat level that will include GDG's, the GDG
    and GDS's are processed as one entry and the order they are
    returned in is the order the GDS's were added to the GDG. On
    releases prior to 1.8 they were processed one entry at a time.
    One of the factors that determines how entries are returned is
    scratch value for the GDG. If GDS's are rolled off and scratched
    then they should be in ascending sequence for the GDG. If GDS's
    are rolled off and remain as non vsam data sets they may appear
    before or after the GDS's that are active for a GDG.
       If your use of GDG's is all by relative processing (i.e.
    (+1), (0), (-2) then they will be returned in the order they
    were created which should be ascending sequence.
       Use of absolute processing, deleting GDS's in the of the GDG,
    renaming GDS's may casue GDS's to returned in order other than
    ascending sequence.
    
       If your applications do have a dependency on the order that
    GDS's are returned in, then those applications will need to be
    updated to remove that dependency.
    .
        This may take time to accomplish. There are several means
    available to have LISTCAT LEVEL return GDS's in generation
    number order. These are as follows:
    .
    1. Add EXPIRATION(9999) to the LISTCAT LEVEL command
    2. Add CREATION(0) to the LISTCAT LEVEL command
    3. If running under TSO, Use TSO PROFILE PREFIX(value)
       Note that it does not matter what the value is, only that the
       TSO PREFIX is set.
    4. After application of PTFs for OA20472, change your JCL from
    //STEP01 EXEC PGM=IDCAMS to //STEP01 EXEC PGM=IDCNOGFL
       Or change applications that invoke IDCAMS to invoke the entry
       point IDCNOGFL, rather than IDCAMS.
    .
       Note that with any of the above options the performance
    enhancements and constraints removal in z/OS 1.8 will not be
    in effect.
    .
       The use of option 4 should be considered a temporary solution
    for the issue of GDS's being returned in an order other than
    generation number order. This option was provided to ease the
    migration to z/OS 1.8 and higher releases and is currently
    intended to be removed in a future release. To help ease
    migration the PTFs for apar OA22078 will provide the new entry
    point IDCNOGFL on z/OS 1.6 and z/OS 1.7. Preview announcements
    and product announcements for z/OS future releases will include
    this as a statement of direction. Removal of this option will be
    included in release and migration guides.
    .
    LISTCAT LIST CATalog formats returned Cataloged objects without
    interpretation.  To determine a system determined data set
    attribute such as a time stamp may require additional resources
    such as VTOC DSCBs not queried or formated by LISTCAT.  Compare
    the results of interpretive products such as TSO to see system
    determined data set attributes such as security and timestamps.
    Also see DFSMS Using Data Sets and z/OS Network File System
    publications for additional information regarding system
    determined attributes.
    .
    In addition to differences in returned Catalog objects, the
    new Catalog interface may also return codes associated with
    the new interface.  LISTCAT is also a conduit for Catalog
    errors, and may result in a change in the JCL COND CODE by
    design.  Migration plans should include tests which exercise
    each JCL condition code path which are dependant on LISTCAT
    results.
    .
    See infor apar II14517 for more on listcat level processing
    
    CATKEYS: CATINFO IDCLISTC CATNEW
    

Local fix

Problem summary

Problem conclusion

Temporary fix

Comments

APAR Information

  • APAR number

    II14250

  • Reported component name

    V2 LIB INFO ITE

  • Reported component ID

    INFOV2LIB

  • Reported release

    001

  • Status

    INTRAN

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt

  • Submitted date

    2007-01-05

  • Closed date

  • Last modified date

    2013-01-24

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

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

Fix information

Applicable component levels

[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG19N","label":"APARs - OS\/390 environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"001","Edition":"","Line of Business":{"code":"","label":""}},{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG19M","label":"APARs - z\/OS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"001","Edition":"","Line of Business":{"code":"","label":""}},{"Business Unit":{"code":null,"label":null},"Product":{"code":"SG19O","label":"APARs - MVS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"001","Edition":"","Line of Business":{"code":"","label":""}},{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SSSN3L","label":"z\/OS Communications Server"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"001","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]

Document Information

Modified date:
24 January 2013