Before you start--preliminary checks

Before you go further into looking for the cause of the problem, run through the following preliminary checks. These checks might highlight a simple cause or, at least, narrow the range of possible causes.

As you go through the questions, make a note of anything that might be relevant to the problem. Even if the observations you record do not at first suggest a cause, they could be useful to you later if you need to carry out systematic problem determination.

  1. Has the CICS® system run successfully before?

    If the CICS system has not run successfully before, it is possible that you have not yet set it up correctly. You can check that CICS installed correctly by running batch or online verification procedures. See CICS Transaction Server for z/OS® Installation Guide for more information. If you have verified that CICS installed successfully, check the appropriate migration guide for any possible impacts to your system. The migration guides available are.....

    If you are currently migrating to CICS Transaction Server for z/OS, Version 3 Release 1, ensure that you are aware of all the changes that have been made for this release. For details of these, see the CICS Transaction Server for z/OS Migration from CICS TS Version 2.3.

  2. Are there any messages explaining the failure?

    If a transaction abends, and the task terminates abnormally, CICS sends a message reporting the fact to the CSMT log (or your site replacement). If you find a message there, it might immediately suggest a reason for the failure.

    Were there any unusual messages associated with CICS start up, or while the system was running before the error occurred? These might indicate some system problem that prevented your transaction from running successfully.

    If you see any messages that you do not understand, you can use the CICS messages transaction, CMAC, for online message information. If you do not have access to a CICS system to run the CMAC transaction, look in CICS Messages and Codes for an explanation. A suggested course of action that you can take to resolve the problem might also be included with the explanation.

  3. Can you reproduce the error?

    1. Can you identify any application that is always in the system when the problem occurs?
      • Check for application coding errors.
      • Check that you have defined sufficient resource for the application, such as VSAM file strings. Typically, if you had not defined sufficient resources, you would find that the problem is related to the number of users of the application.
    2. Are you using exit programming interface (XPI) calls? If so, be sure to observe the XPI protocols and restrictions exactly. For programming information about the XPI, see the CICS Customization Guide.

      The exit programming interface enables you to invoke a domain and enter its environment directly; using it incorrectly can cause severe CICS system problems. Here are some particular points for your attention:

      • Are the input parameters correct? If their format is not valid, they are rejected by the called domain, and an exception trace is made. If their values are acceptable to the domain but inappropriate for the system, they could cause unpredictable effects.
      • Be aware that you cannot use some XPI calls within some of the user exits. If you do, the results can be unpredictable, and can cause CICS to stall or abend. The CICS Customization Guide tells you which exits can use X calls and which cannot.

    3. Consider your CICS system definition parameters if the problem is not related to any particular application. Poorly defined parameters may be the cause of problems in your system. You can find guidance about setting up your CICS system in the CICS System Definition Guide.
    4. Does the problem seem to be related to system loading? If so, the system might be running near its maximum capacity, or it might be in need of tuning. For guidance about dealing with this sort of problem, see the CICS Performance Guide.
  4. Does the failure occur at specific times of day?

    If the failure occurs at specific times of day, it could be dependent on system loading. Typically, peak system loading is at mid-morning and mid-afternoon, so those are the times when load-dependent failures are most likely to happen. If your CICS network extends across more than one time zone, peak system loading might seem to you to occur at some other time of day.

  5. Is the failure intermittent?

    If an error is intermittent, particularly if it does not show the same symptoms, the problem might be more difficult to resolve. An intermittent failure can be caused by a "random" storage overlay. Furthermore, the transaction that caused the error might have been deleted from the system long before the symptoms are seen.

    A method you can use to investigate random overlays is described in Dealing with storage violations.

  6. Have any changes been made since the last successful run?

    Service

    1. Have you applied a PTF to CICS?
    2. Did it install successfully or did you get an error message during installation? If you installed it successfully, check with IBM® for any PTF error.
    3. Have any patches applied to any other program affected the way CICS interfaces with the program?

    Hardware

    1. Have you changed your hardware?

    Software

    1. Have you changed your software?
    2. If you have installed a new or modified application, check for error messages in the output from the following:
      • Translator
      • Compiler
      • Assembler
      • Linkage editor

    Administration

    1. Have you changed your initialization procedure, for example by JCL, CICS system initialization or override parameters, or VTAM® CONFIG/LIST?
    2. Has CICS generated any error messages during initialization?
    3. Have you installed any resource definitions defined using CEDA?

      If the definitions were made but not installed when CICS was last terminated, they might not have been preserved over the termination and subsequent start up. In general, changes made to the CSD but not installed are not visible when the CICS system is warm started. However, if the change was in a group in the GRPLIST specified on a cold start, it is effectively installed during startup. (Changes which have been installed are not visible after a cold start unless they were made to a group in the GRPLIST.)

      If START=AUTO was specified in the system initialization table, or as an override, you need to examine the job log to find out how the CICS system last came up.

      For detailed guidance about the ways in which resources can be defined and installed, see the CICS Resource Definition Guide.

  7. Are specific parts of the network affected by the problem?

    1. Can you identify specific parts of the network that the problem affects? If you can, look for any explanatory message from the access method. Even if no message has been sent to the console, you might find one in the CSNE log.
    2. Have you made any network-related changes?
    3. If the problem affects a single terminal, are your terminal definitions correct? Consider both the TERMINAL definition, and the TYPETERM definition it uses.

    4. If the problem affects a number of terminals, can you identify a factor that is common to all of them? For example:
      • Do they use the same TYPETERM definition? If so, it is likely that there is an error in that TYPETERM definition.
      • Is the whole network affected? If so, CICS has probably stalled. See What to do if CICS has stalled for advice about dealing with CICS system stalls.
  8. Has the application run successfully before?

    1. Have any changes been made to the application since it last ran successfully?

      Examine the new or modified part of the application.

    2. Have you used RDO to create or alter a transaction, program, or map set? You must install these definitions before the resources are available to the running CICS region.
    3. If you changed any maps, have you created both a new phase (TYPE=MAP) and a new DSECT (TYPE=DSECT), and then recompiled every program using the new DSECT? Use the CEMT commands:
            CEMT SET PROGRAM(mapset) NEWCOPY
            CEMT SET PROGRAM(all programs) NEWCOPY

      (See CICS Supplied Transactions for guidance about the CEMT transaction.)

    4. Have all the functions of the application been fully exercised before?

      Establish what the program was doing when the error occurred, and check the source code in that part of the program.

      If a program has been run successfully on many previous occasions, examine the contents of any records, screen data, and files that were being processed when the error occurred. They may contain some unusual data value that causes a rarely used path in the program to be invoked.

    5. Check that the application successfully retrieved the records that it required at the time of the error.
    6. Check that all fields within the records at the time of the error contain data in a format acceptable to the program. Use CICS dump to do this.

      If you can reproduce the problem in a test system, you can use programming language debug tools and the CEDF transaction to check the data and solve the problem.

  9. The application has not run successfully before

    If your application has not yet run successfully, examine it carefully to see if you can find any errors.

    1. Check the output from the translator, the compiler, and the linkage editor, for any reported errors.

      If your application fails to translate, compile or assemble, or link-edit cleanly into the correct phase library, it will also fail to run if you attempt to invoke it.

    2. Check the coding logic of the application. Do the symptoms of the failure indicate the function that is failing and, therefore, the piece of code in error?
    3. The following is a list of some programming errors commonly found in applications:
      • CICS areas are addressed incorrectly.
      • The rules for quasi-reentrancy are not followed.
      • Transient data is managed incorrectly.
      • File resources are not released.
      • Storage is corrupted by the program.
      • Return codes from CICS requests are ignored.

Related concepts
General changes to CICS externals
The user exit programming interface (XPI)
Global user exit programs
Analyzing the performance of a CICS system
Dealing with storage violations
What is resource definition?
CEMT -- Master Terminal
Related tasks
Specifying CICS system initialization parameters
What to do if CICS has stalled
Related references
CICS DFH Message Identifiers
[[ Contents Previous Page | Next Page Index ]]