PI48647: New dump recording interfaces are provided so that user can determine whether a dump has been taken for an active condition.

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• New Function APAR
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: Users of Language Environment that want to   *
  *                 make use of the new SYSDUMP information      *
  *                 recording service.                           *
  ****************************************************************
  * PROBLEM DESCRIPTION: New interfaces are provided to record   *
  *                      the dataset name of a dump so that      *
  *                      users can determine whether a dump has  *
  *                      been taken for an active condition.     *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  Language Environment provides new interfaces for recording the
  dataset name of a dump that has been gathered for a condition.
  Such information would allow Language Environment, compilers,
  Java, IBM Fault Analyzer etc. to share the knowledge of any
  gathered data for an active condition.
  

Problem conclusion

Temporary fix

Comments

• Language Environment now provides a piece of data in the
  Condition Information Control Block (CIB) that records the
  information of a taken SYSDUMP. Each condition handler can
  check this field to know if a dump had already been taken.
  Also a new callable service is provided to record the
  information into the new field after taking a dump.
  
  The following publications must be updated.
  ================================================================
  z/OS Language Environment Debugging Guide (GA32-0908-xx)
  
  In Chapter 3 Using Language Environment debugging facilities,
  section Language Environment dump service CEE3DMP, subsection
  Debugging with specific sections of the Language Environment
  dump, paragraph Condition information block, the CIB mapping
  is modified, adding in the following new field.
  +068 +-------------------------------------------------------+
       | Address of recorded dump dataset name                 |
       |                                                       |
  +06C +-------------------------------------------------------+
       .  (reserved -- 36 bytes)                               .
  
  Address of recorded dump dataset name:
  If this address is not 0, then it points to a 44-byte
  fixed-length character string. If the length of the data set
  name is less than 44, the character string is EBCDIC-encoded
  and is padded by blanks.
  
  In Chapter 12 Using Language Environment AMode 64 debugging
  facilities, section Language Environment dumps, a subsection
  named Debugging with specific sections of the Language
  Environment dump is added.
  
  Condition Information Block
  
  Figure 1 shows the condition information block. The Language
  Environment condition manager creates a condition information
  block (CIB) for each condition encountered in the Language
  Environment environment. The CIB holds data required by the
  condition handling facilities and pointers to locations of
  other data. The address of the current CIB is located in the
  CAA.
       .                                                       .
       .                                                       .
  +0A8 +-------------------------------------------------------+
       | Address of recorded dump dataset name                 |
       |                                                       |
  +0B0 +-------------------------------------------------------+
       . (reserved)                                            .
  
  Address of recorded dump dataset name:
  If this address is not 0, then it points to a 44-byte
  fixed-length character string. If the length of the data set
  name is less than 44, the character string is EBCDIC-encoded
  and is padded by blanks.
  
  
  z/OS Language Environment Programming Reference (SA38-0683-xx)
  In Chapter 5 - Callable services, CEERCDM is added.
  
  CEERCDM - Record information for the active condition
  -----------------------------------------------------
  
  CEERCDM records information for an active condition so that the
  information can be retrieved from the condition information
  block (CIB). Use this service only during condition handling.
  
  +--- Syntax --------------------------------------------------+
  |                                                             |
  |  CEERCDM  (  function_code  ,  information  ,  fc  )        |
  |     INT4        *function_code;                             |
  |     POINTER      information;                               |
  |     FEED_BACK   *fc;                                        |
  |                                                             |
  +-------------------------------------------------------------+
  
  function_code (input)
      A fullword integer that contains the function code of the
      following value:
      1   Record the dataset name of a dump for an active
          condition.
  
  information (input)
      The information to be recorded. When the function_code is
      1, the information is a halfword length-prefixed EBCDIC
      character string that is expected to be the dataset name
      of a dump for an active condition. Language Environment
      will validate that the length is positive and it does not
      exceed 44.
  
  fc (output)
      A 12-byte feedback code, optional in some languages, that
      indicates the result of this service. If you choose to omit
      this parameter, refer to Invoking callable services for the
      appropriate syntax to indicate that the feedback code was
      omitted.
  
      The following symbolic conditions can result from this
      service:
  
      Code    Severity   Message number  Message text
      CEE000  0          _               The service completed
                                         successfully.
      CEE3LA  3          3754            Incorrect parameters
                                         detected.
      CEE35S  3          3260            No condition was active
                                         when a call to a
                                         condition management
                                         routine was made.
  
  Usage notes
  
  1.   After the condition handling functions return control to
  your application, the CIB that represents the condition is no
  longer valid and the recorded information is no longer
  accessible.
  2.    If CEERCDM is called more than once for the same
  condition, the information of the last call is recorded.
  3.    Because the CIB is used only for synchronous signals,
  you should not use CEERCDM in signal catchers that are driven
  for asynchronous signals.
  
  Examples
  
  #include <stdio.h>
  #include <leawi.h>
  #include <stdlib.h>
  #include <string.h>
  #include <ceeedcct.h>
  
  #ifdef __cplusplus
      extern "C" {
   #endif
      void handler(_FEEDBACK *,_INT4 *,_INT4 *,_FEEDBACK *);
   #ifdef __cplusplus
      }
  #endif
  
  int main() {
  
    _FEEDBACK fc;
    _ENTRY routine;
    _INT4 token;
    int x,y,z;
  
    token = 99;
    routine.address = (_POINTER)&handler;
    routine.nesting = NULL;
  
    CEEHDLR(&routine,&token,&fc);
    if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
      printf("CEEHDLR failed with message number %d\n",
             fc.tok_msgno);
      exit(2999);
    }
    x = 5;
    y = 0;
    z = x / y;
  }
  
  void handler(_FEEDBACK *fc, _INT4 *token, _INT4 *result,
               _FEEDBACK *newfc) {
  
     _FEEDBACK lfc;
     _INT4 funcode;
     _VSTRING  info;
     char *ds_name = "XXXX.YYYY";
  
     info.length = strlen(ds_name);
     memcpy(info.string, ds_name, info.length);
     funcode = 1;
     CEERCDM(&funcode, &info, &lfc);
     if ( _FBCHECK ( lfc , CEE000 ) != 0 ) {
       printf("CEERCDM failed with message number %d\n",
              lfc.tok_msgno);
       exit(2999);
     }
  
     *result = 10;
  }
  
  
  z/OS Language Environment Runtime Messages (SA38-0686-xx)
  
  In Chapter 1. Language Environment runtime messages, CEE3754S
  is expanded as below.
  
  Explanation:
  If this message was returned by CEEGTJS or __le_ceegtjs(), one
  or more of the following may be true:
  * The function_code is not valid.
  * A wild card character ('*' or '?') was found in the input
    symbol_name.
  * The output parameter symbol_value or value_length is not
    valid. An addressing exception occurred while storing the
    symbol value or value length into these fields. Make sure the
    symbol_value is a valid 255-byte fixed-length string.
  If this message was returned by CEERCDM or __le_record_dump(),
    one or more of the following may be true:
  * The function_code is not valid.
  * The function_code is 1, and the length of the character
    string in the input information is either not positive or
    greater than 44.
  Programmer response: Correct the parameter and try again.
  System action:  The function has not been performed.
  Symbolic feedback code:  CEE3LA
  
  
  z/OS XL C/C++ Runtime Library Reference (SC14-7314-xx)
  
  In Chapter 3. Library functions, add following section.
  
  __le_record_dump() - Record information for the active condition
  ----------------------------------------------------------------
  
  Standards
  Standards / Extensions      C or C++        Dependencies
  Language Environment        both            AMODE 64
  
  Format
  
  #include <__le_api.h>
  
  int __le_record_dump(int function_code, void *information);
  
  General description
  __le_record_dump() records information of an active condition
  so that the information can be retrieved from the condition
  information block (CIB). Use this function only during
  condition handling.
  
  Parameter description
  function_code
      A fullword integer that contains the function code of the
      following value:
      1     Record the dataset name of a dump for the active
            condition.
  
  information
      The information to be recorded. When the function_code is 1,
      the information is a halfword length-prefixed EBCDIC
      character string, which is expected to be the dataset name
      of a dump for the active condition. Language Environment
      will validate that the length is positive and it does not
      exceed 44.
  
  Returned Value
      If successful, __le_record_dump() returns 0.
      If unsuccessful, __le_record_dump() returns nonzero and
      sets errno to one of the following values:
      EMVSERR     No active CIB is available.
      EINVAL      Incorrect parameters detected.
  
  Usage notes
  1. After the condition handling functions return control to
  your application, the CIB that represents the condition is no
  longer valid and the recorded information is no longer
  accessible.
  2. If __le_record_dump() is called more than once for the
  same condition, the information of the last call is recorded.
  3. This function is valid when called while a Language
  Environment exception handler is running.
  4. Because the CIB is used only for synchronous signals, you
  should not use __le_record_dump() in signal catchers that are
  driven for asynchronous signals.
  

APAR Information

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

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

  UI36024 UI36025

Modules/Macros

• CEEBALCI CEECIB   CEEERRI3 CEEIBMAW CEEIBMCI
  CEEIGZCI CEEOLEO  CEEOLVD  CEEOXVEC CEERCDM  CELHCINT CELHCPRD
  CELHS001 CELHXVEC CELHXVET CELHZV03 CELQAWI  CELQINC  CELQRCDM
  CELQRRI3 CELQS003 CELQXVEC CELQXVEO CELQXVET CEL4RCDM EDCERNO2
  EDC4H0A2 EDC4H014 EDC4007A EDC40072 EDC4022F HLE77A0J HLE7790J
  

Fix information

• Fixed component name

  LE FOR MVS & VM

• Fixed component ID

  568819801

Applicable component levels

• R7A0 PSY UI36024

     UP16/03/30 P F603

• R790 PSY UI36025

     UP16/03/30 P F603

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.