Mustgather: Read first for problems encountered with Enterprise COBOL for z/OS

Answer

Gathering General Information

Gathering Problem-Specific Information

. Compiler Problem - What to Gather?

. Run-time Problem - What to Gather?

General Hints and Tips

. Find z/OS Version & PTF Level

. Find COBOL Compiler Version & PTF Level

. Find COBOL Runtime Version & PTF Level

. How to Create a SYSMDUMP

. How to Search for Known Problems

Submitting Information to IBM Support

What is a Mustgather document and how does it help me?

---

Gathering General Information

General information is information that is needed for any reported problem:

• Action you were attempting at the time of the failure.
• Was a temporary fix applied?
• z/OS operating system version, release and PTF level. This information can be obtained through SMP/E.
• Compiler version, release, and modification level. Click here for information about how to obtain this information.
• Compiler PTF level. This information can be obtained through SMP/E.
• Subsystem (CICS, DB2, IMS, WAS) version, release, modification, and PTF levels, if applicable.
• A contact phone number and email address.

Gathering Problem-Specific Information

From the list below, select the type of problem that best describes the problem you are experiencing:

Compiler Problem - What to Gather?

Run-time Problem - What to Gather?

Compiler Problem - What to Gather?

Gather the following documentation for compiler problems before calling IBM support:

• Listings for the application program(s) involved. Please use the LIST, MAP and NOOFFSET compiler options. Please remove any suppress directives for COPY statements.
• If you are using the CICS compiler option, provide the CICS version, release, modification level, and PTF level. The PTF level information can be obtained through SMP/E.
• If you are using the SQL compiler option, provide the DB2 version, release, modification level, and PTF level. The PTF level information can be obtained through SMP/E.
• Source code for the program being compiled with all COPY files. If you are using Enterprise COBOL V3R4 or later, you should instead use the MDECK compiler option to create merged source code output (SYSMDECK). For more information about the MDECK compiler option, refer to Chapter 17 of the Enterprise COBOL for z/OS Programming Guide at http://www-306.ibm.com/software/awdtools/cobol/zos/library/.

Normally, the MDECK(COMPILE) option can be used to create the SYSMDECK source file.
However, for programs that fail to compile prior to generating the SYSMDECK file, the MDECK(NOCOMPILE) option can be used instead to create the SYSMDECK file and will skip the compile altogether.
Add the following DD to the compile JCL:
//SYSMDECK DD DSN=my.dataset.name,
//  DISP=(NEW,CATLG),
//  SPACE=(TRK,(99),RLSE),UNIT=SYSDA,
//  DCB=(LRECL=80,RECFM=FB,BLKSIZE=0)  

• References to the product's documentation if you believe that the compiler is not working as designed.

Run-time Problem - What to Gather?

Gather the following documentation for run-time problems before calling IBM support:

• Listings for the application programs involved. The program must be compiled with the LIST, MAP, NOOFFSET compiler options to be usable by IBM.
• A small, reproducible test case (if possible).
• The z/OS level.
• The COBOL run-time release and PTF level. Click here for information about how to obtain this information.
• Provide a JOBLOG if available.

• If your application abended, include the following:
• SYSMDUMP: For additional information on how to request a dump, refer to http://pic.dhe.ibm.com/infocenter/zos/v2r1/topic/com.ibm.zos.v2r1.ceea100/gsd.htm
• For program checks (S0Cx), you can add the following DD to the execution JCL to generate a SYSMDUMP:

//CEEOPTS DD *
 TERMTHDACT(UAIMM),TRAP(ON,NOSPIE),DYNDUMP(yourhlq,FORCE,TDUMP)
/*

- If running under IMS, provide the CEEOPTS override to the IMS region.
- DYNDUMP is ignored by CICS. (Instructions for generating a SYSMDUMP in
CICS can be found below.)
- Do not include the SYSMDUMP DD.
- The DYNDUMP assures that any setting of the customer's for this option is overridden.
- The FORCE will dump even in the presence of other dump DDs like SYSUDUMP.
- “yourhlq” will be used to form the initial part (HLQ) of the dump dataset name and can
be up to 26 characters in length. The HLQ should be one that the job has ALTER
authority to create.
- The name of the dump dataset can be found in the job's JESMSGLG and looks like:
+CEE3798I ATTEMPTING TO TAKE A DUMP FOR {abend} TO DATA SET:
          {dsn-prefix}.Dddd.Thhmmsss.{jobname}
If there are multiple instances, usually the first one is desired by IBM.

• For non-program checks (i.e. abends) in batch or for a CICS U4038, you should use the following to generate the SYSMDUMP:

//SYSMDUMP DD DSN=yourhlq.SYSMDUMP,DISP=(NEW,CATLG),
//            UNIT=SYSDA,SPACE=(CYL,(250,250),RLSE),
//            DCB=(LRECL=4160,RECFM=FBS,BLKSIZE=4160)
//CEEOPTS DD *
 TERMTHDACT(UADUMP) ABTERMENC(ABEND) TRAP(ON,SPIE)
/*
If either the SYSABEND or SYSUDUMP DD names are in the failing step, comment them out as they compete against the SYSMDUMP DD.

• To turn off competing software, you may need to add one or more of the following DDs:

//IDIOFF   DD  DUMMY   IBM FAULT ANALYZER OFF
//ABNLIGNR DD  DUMMY   ABEND-AID OFF              
//ESPYIBM  DD  DUMMY   EYE-SPY OFF                
//CAOESTOP DD  DUMMY   CA-OPT II & CA-SYMDUMP OFF        
//DMBENAN  DD  DUMMY   DUMPMASTER OFF        
//PSPOFF   DD  DUMMY   SOFTWORKS PERFORMANCE ESSENTIAL OFF
• If your environment includes a CICS region, include a SYSMDUMP that includes CICS region information. To create a SYSMDUMP that includes full CICS region/trace details, you must specify the following settings:
  • For CETR, all domains defined as ‘1’ except for ‘AP’ which is defined ‘1-2’.
  • Trace Table Size must be set at a minimum of 12 megabytes.
• If requested, create a CICS auxiliary trace. For information on using CICS traces, click here.
• If possible, determine if the abend is in IBM code or in your application code.



Back to top

General Hints and Tips

• z/OS Operating System Version, Release and PTF Level: This information can be obtained through SMP/E.

• COBOL Compiler Version & PTF Level: The compiler listing page header provides information about the version, release, and modification level of the compiler that was used to compile your program. For example:

5655-EC6 IBM Enterprise COBOL for z/OS 6.1.0 P171018 indicates Version 6 Release 1 Modification 0 and the compiler code (PTF) was built on 2017/10/18.
5655-G53 IBM(R) Enterprise COBOL for z/OS V3R4M1 indicates Version 3 Release 4 Modification 1. (The compiler code build date is not available in this version's message.)

• COBOL Runtime Version & PTF Level: The COBOL run-time library release and PTF level information is determined by viewing the CEEDUMP dataset. Version information is included at the top of the CEEDUMP. The run-time library for COBOL is shipped with the operating system. Identifying the z/OS operating system version identifies the COBOL run-time library version. The PTF level of each COBOL run-time module is in the service column of the trace back section of the CEEDUMP.

If a CEEDUMP is not available, then the following method can be used as an alternative for the COBOL V5+ runtime:
View member *.SCEERUN(IGZXLPKA) and search for string "PROPERTY OF IBM".
It should look like this:
PROPERTY OF IBM <yyyymmddhhmmssVVRRMM>..<APAR>
For example:
PROPERTY OF IBM   20171012112114020200..PI87862  
Add that line into the PMR.
• Secondly, determine if there is an old version of a run-time library (OS/VS COBOL or VS COBOL II). If you are experiencing a run-time problem, you can view the JCL to determine if an old version of a run-time library is ahead of Language Environment (LE) in the concatenation. Check the STEPLIB, JOBLIB, and LNKLST. Some examples of old run-time library names are COBLIB, VSCLLIB and COB2LIB.

• Search For Known Problems: The following locations can be searched for problem information:
• Search for known problems on Google, using search text "texttosearch SITE:IBM.COM".
• Search for known problems on the Enterprise COBOL V5+ Fixlist webpage.
• Search the Enterprise COBOL documentation in the Knowledge Center at https://www.ibm.com/support/knowledgecenter/SS6SG3/entcobol_family_welcome.html .
• Review Preventive Service Planning buckets if you are installing or migrating Enterprise COBOL for z/OS.

Submitting Information to IBM Support

After a Problem Management Record (PMR) is open, you can submit diagnostic MustGather data to IBM using one of the following methods:

• FTP diagnostic data to IBM. For instructions, click here.
• If FTP is not possible, email diagnostic data to techsupport@ecurep.ibm.com. You must add PMR xxxxx bbb ccc in the subject line of your email. xxxxx is your PMR number, bbb is your branch office, and ccc is your IBM country code. Click here for more details.

Update your Problem Management Record (PMR) to indicate that data has been sent. You can update your PMR, or open a new PMR, in one of two ways:

• Online: Go to the Submit and track problems page on the IBM Software Support site (www.ibm.com/software/support/probsub.html) or IBMLink to open an Electronic Technical Response (ETR). Enter your information into the appropriate problem submission tool.
• By phone: Call 1-800-IBMSERV (1-800-426-7378) in the United States or, from other countries, go to the contacts page of the IBM Software Support Handbook on the Web (techsupport.services.ibm.com/guides/contacts.html) and click the name of your geographic region.

What is a Mustgather document and how does it help me?

MustGather documents aid in problem determination and save time resolving Problem Management Records (PMRs). These documents are located on the product support sites and contain specific instructions about what documentation to gather for specific problems. You can find available MustGather documents by searching on the word MustGather on the Support Portal Web pages:

http://www.ibm.com/support/entry/portal/Overview

Collecting MustGather data early, even before opening the PMR, helps IBM® Support quickly determine if:

1. Symptoms match known problems (rediscovery).


2. There is a non-defect problem that can be identified and resolved.


3. There is a defect that identifies a workaround to reduce severity.


4. Locating root cause can speed development of a code fix.