IT37231: DSMBINDMC FAILS DSM_RC_TL_NOACG (186) OR DSM_RC_TL_NOBCG (184) IF NO ARCHIVE OR BACKUP COPYGROUP IN DEFAULT MGMTCLASS

APAR status

• Closed as documentation error.

Error description

• The IBM Spectrum Protect API client uses a sequence of
  2 distinct methods of associating files to a mgmtclass:
  
  1. Before sending a file, the application must first call the
  function dsmBindMC, which associates the file to a mgmtclass,
  based on include statements in an 'inclexcl' list.
  
  2. Next the application can directly specify a mgmtclass name
  in the mcNameP parameter of the dsmSendObj function, which
  overrides the result from dsmBindMC.
  
  In the manual "Using the Application Programming Interface"
  the documentation of the functions dsmBindMC and dsmSendObj
  must be enhanced:
  
  Application programmers must be made aware the whole
  function sequence is interrupted if the chronologically first
  function dsmBindMC cannot determine any mgmtclass,
  even if the result is not needed when the intention is
  to set the mcNameP parameter of the dsmSendObj function.
  
  dsmBindMC fails if 2 conditions are met:
  1. A matching and valid include statement does not exist,
     and
  2. the default mgmtclass does not have any archive copygroup,
     respectively backup copygroup.
  This failure in dsmBindMC is reported as
  dsmrc = 186 = DSM_RC_TL_NOACG for archives or
  dsmrc = 184 = DSM_RC_TL_NOBCG for backups.
  
  Any application that leverages the mcNameP parameter can be
  affected by this failure mechanism. The following applications
  are known to make use of the mcNameP parameter for archiving:
  
  IBM Db2
      when processing the archive mgmtclass which is specified in
      'db cfg' as the parameter LOGARCHMETH1/2 = TSM:ARCHIVE_CLASS
  
  IBM Spectrum Protect for Enterprise Resource Planning
    Data Protection for SAP HANA
    Data Protection for SAP for DB2
    Data Protection for SAP for Oracle
      when processing the parameters
      BRBACKUPMGTCLASS and BRARCHIVEMGTCLASS
  
  This failure can be prevented by either
  specifying a matching include statement with a valid mgmtclass,
  or by defining a copygroup to the default mgmtclass.
  The resulting mgmtclass binding by dsmBindMC has no effect,
  if the mcNameP parameter of the dsmSendObj function is used
  subsequently.
  
  The return codes DSM_RC_TL_NOACG (186) and DSM_RC_TL_NOBCG (184)
  must be added to the table "Return codes for dsmBindMC"
  
  The return code DSM_RC_TL_NOBCG (184) must be added
  to the table "Return codes for dsmSendObj"
  
  Customer/Support diagnostics
  ----------------------------
  Despite a valid mgmtclass in LOGARCHMETH1/2 = TSM:ARCHIVE_CLASS,
  a failed dsmBindMC can cause the following error message in the
  db2diag.log file:
  
  2021-06-01-19.51.40.789516+180 E1068135307A386    LEVEL: Error
  PID     : 14418062             TID : 1            PROC : db2vend
  INSTANCE: db2opq              NODE : 000
  HOSTNAME: abcxyz
  EDUID   : 1
  FUNCTION: DB2 UDB, database utilities,
            sqluvInitTSMWriteAndArchive, probe:295
  DATA #?1 : TSM RC, PD_DB2_TYPE_TSM_RC, 4 bytes
  TSM RC=0x000000BA=186 -- see TSM API Reference for meaning.
  
  dsierror.log:
  ANS1104E The management class for this file does not have a
    valid archive copy group. This file will not be archived.
  or
  ANS1105E The management class for this file does not have a
    valid backup copy group. This file will not be backed up.
  
  Product versions affected: All 7.1 and 8.1 versions of the
                             IBM Spectrum Protect Manual
                             "Using the Application Programming
                             Interface"
             Initial impact: Low
        Additional keywords: TS005697776 management class abort
  

Local fix

• Specify a matching include statement with a valid mgmtclass,
  or define a copygroup to the default mgmtclass.
  

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * IBM Spectrum Protect Application Programming Interface       *
  * versions 7.1 and 8.1 Installation and User's Guide           *
  *                                                              *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * See "ERROR DESCRIPTION"                                      *
  ****************************************************************
  * RECOMMENDATION:                                              *
  * This issue is projected to be fixed in the IBM Spectrum      *
  * Protect API Documentation versions 8.1.13. Note that this is *
  * subject to change at the discretion of IBM.                  *
  ****************************************************************
  

Problem conclusion

• The return codes DSM_RC_TL_NOACG (186) and DSM_RC_TL_NOBCG (184)
  is added to the table "Return codes for dsmBindMC"
  The return code DSM_RC_TL_NOBCG (184) is added to the table
  "Return codes for dsmSendObj"
  
  Updated document links:
  https://www.ibm.com/docs/en/spectrum-protect/8.1.13?topic=calls-
  dsmbindmc
  https://www.ibm.com/docs/en/spectrum-protect/8.1.13?topic=calls-
  dsmsendobj
  

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:

Fix information

Applicable component levels