PH36220: Diagnose overlapping columns in COLUMN MAPS involving LEGACY TABLES

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• Customer is performing (CONVERT) processing Column Maps (CMs)in
  which the destination table is a LEGACY TABLE (LT).
  The LT has been defined based on a COBOL copybook with fields
  which REDEFINE other fields.
  Customer has specified a number of CM PROCEDURES for the
  LT columns which share, or overlap, the same storage location
  because of the REDEFINES clause.
  When one CM PROC sets the destination column then other CM PROCs
  may not be aware of the value overlapping and change the same
  storage location causing the original destination column value
  to be lost or corrupted.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All Optim customers processing Legacy Tables *
  *                 (LTs).                                       *
  ****************************************************************
  * PROBLEM DESCRIPTION: This APAR enhances the processing of    *
  *                      the Optim Legacy Tables (LTs).          *
  ****************************************************************
  Non-DB2 data sources have their data model defined in Optim's
  Legacy Tables (LTs).
  Such LTs may be contain overlapping, or REDEFINing, columns
  (fields). Such condition is not always obvious or readily
  visible to the user. Especially when using a Column Map (CM)
  changes may be made to one destination column which will affect
  other columns redefining the same storage location.
  

Problem conclusion

• Optim processing will be enhanced as follows:
  
  1. A "Legacy Table Memory Map" will be produced for all
     processes in which a LT is the destination and a CM is being
     used.
     The report will include the following information:
     o Column (Field) Level from the LT and the LT column name.
     o When the Column name differs from the originating Field
       name (ignoring the '_' for '-' substitution) then the
       original Field name will be listed underneath the Column
       name.
     o When the Column is actually an Instance of an array of
       fields then the generated Instance name will be listed.
       This is the name passed on to CM PROCEDURE and User EXITs
       as the destination column name.
     o The value of the Field's offset in the row/record and data
       length (in bytes or characters) will follow. Note that
       overlapping/REDEFINEd Columns/Fields will in general have
       the same, or overlapping, offset.
     o If the Column/Field has been explicitly REDEFINed on
       another Column then such Column/Field name will follow.
     o When the Column is actually an Instance of an array of
       fields then the Array Element/Instance number will be
       listed. The Array elements are counted relative to 1 and
       a maximum of 12 elements will be listed.
     o Fields/columns with specified "Occurs" values will have
       such values shown in the report, along with the
       "Depending on" value, when present.
  
  2. The following informational message will be issued in the
     Summary and Process reports when an LT contains any
     overlapping Columns/Fields:
  
  Information: CM <map name>  for Table <table name>
               has column(s) redefining storage location(s).
               CM value assignments to such columns will affect
               all columns sharing the same storage location in
               the Destination Table.
               Inspect the LT Memory Map below for details.
  
  3. The following informational message will be issued in the
     Summary and Process reports when an LT contains any
     overlapping Columns/Fields and CM PROCEDUREs have been used
     on such:
  
  Information: CM <map name>  for Table <table name>
               has columns for which a CM PROC has been specified
               to provide the column's value.
               Some of these columns overlap, or REDEFINE, other
               columns with CM PROCs.
               Because of that, special attention needs to be
               given to proper setting of these value(s).
  
               Column                           Instance
                                                     Offset Length
               ---------------------------------------------------
  
               ZGWJTSSN_JOINT_LIFE_SSN
                                                         32      5
               ZPRTPSSE_PART_SSN
                                                         32      5
               ZPART_BENEF_SOCSECNO        ZPART_BENEF_SOCSECNO_7
                                                         32      5
  
     The above list will show groups of affected columns. Since a
     CM PROCEDURE is required to set the value of its destination
     column, it is the user's responsibility to make sure that
     CM PROCEDUREs do not corrupt destination column values with
     overlapping storage locations.
  
  4. Users will now be able to notify Optim that a CM PROCEDURE
     has its destination column's value already set, by the virtue
     of another CM PROCEDURE setting the value of an overlapping
     column, without actually calling any of the optim.target.
     setcolumnvalue() or optim.target.setcolumnfrombytes()
     functions.
     Instead, a call to the new function
     optim.target.columnisset() will alert Optim that the
     destination column's value has already been set. For example:
  
  if IsValidTabKey(tabName,colName) then
      -- do we have interest in this data?
     maskColum()                       -- yes, mask the value
     optim.target.setcolumnfrombytes(colName,keyDat)
      -- set the destination
  else
     optim.print("retain org value")
     -- not interested in this type of data,
     -- already set by another PROC
     optim.target.columnisset()
     -- set the destination value state
  end
  
  The following publications will be updated by this APAR:
  Optim Common Elements, Column Maps, Working with column map
  expressions and procedures using Lua functions, List of Column
  functions. The following two functions will be added:
  
  optim.target.iscolumnset(): Returns TRUE value if the (current)
  CM PROC has already set the value of the (current) destination
  column for the current row by invoking
  optim.target.setcolumnvalue() or
  optim.target.setcolumnfrombytes().
  Any arguments specified on the call will be ignored.
  
  optim.target.columnisset(): Sets the state of the current
  destination column as having a value already assigned, without
  actually calling any of the optim.target.setcolumnvalue() or
  optim.target.setcolumnfrombytes() functions. This function can
  be used while processing Legacy Tables, especially columns which
  may overlap with other columns in storage. A CM PROCEDURE may
  determine that the location in storage has been already
  processed, and the value set, by another CM PROCEDURE. Without
  using the columnisset() function, Optim would report an error if
  the CM PROCEDURE decided not to set the destination column value
  using optim.target.setcolumnvalue() or
  optim.target.setcolumnfrombytes().
  Any arguments specified on the call will be ignored.
  

Temporary fix

Comments

APAR Information

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

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

Modules/Macros

• FOPCRDB  FOPCXLIB FOPIDMTB FOPMCOLP FOPMMCMR FOPMMJBS FOPMMUNU
  FOPMMUTL FOPPDENG FOPPDJPN FOPPDLA  FOPRS10  FOPZFMMN
  

Fix information

• Fixed component name

  OPTIM MOVE FOR

• Fixed component ID

  5655V0700

Applicable component levels

• RB70 PSY UI75207

     UP21/05/06 P F105  

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.