Enterprise PL/I for z/OS and OS/390

IBM

Diagnosis Guide
Version 3 Release 2.0

GC27-1459-01

Enterprise PL/I for z/OS and OS/390

IBM

Diagnosis Guide
Version 3 Release 2.0

GC27-1459-01

Note!
Before using this information and the product it supports, be sure to read the general information under Notices on page 33.

Fourth Edition (September 2002)

This edition applies to Version 3 Release 2 of Enterprise PL/I for z/OS and OS/390, 5655-H31, and to any subsequent releases until
otherwise indicated in new editions or technical newsletters. Make sure you are using the correct edition for the level of the product.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the
address below.
A form for readers' comments is provided at the back of this publication. If the form has been removed, address your comments to:
IBM Corporation, Department HHX/H1
555 Bailey Ave
San Jose, CA, 95141-1099
United States of America
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes
appropriate without incurring any obligation to you.
International Business Machines Corporation 1998,2002. All rights reserved.

Contents
About this book . . . . .
Who this book is for . . . .
Using your documentation

Part 1. Determining the problem

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1. Compiler overview . . . .

Function of the Enterprise PL/I compiler
Processing a PL/I program . . . . . . . .
Compiling . . . . . . . . . . . . . . . . . .
Preprocessing stage . . . . . . . . . .
Compiling stage . . . . . . . . . . . .
Link-editing . . . . . . . . . . . . . . . . .
Running . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2. Compile-time problem determination chart

Part 2. Describing the problem

. . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 3. Introduction to Diagnosis Keywords

Keyword Usage . . . . . . . . . . . . . . . . . . . . .
Using the Problem Identification Worksheet . . . . .
Diagnosis Procedure . . . . . . . . . . . . . . . . . .

16

. . . . . . . . . . . . . . . . . . . . . . . . .

17

. . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23

. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . .

24

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

25

Chapter 11. Problem identification worksheet

Copyright IBM Corp. 1991, 2002

11

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

Chapter 10. Using the keyword string to search for corrections

Part 3. Reporting the problem

18
19
19
20
20
21
22

Chapter 8. System-type keyword

Chapter 9. Modifier keyword

2
2
2
3
3
4
4
4

. . . . . . . . . . . . . . . .

Chapter 6. Type-of-failure keyword

Abnormal termination . . . . . . . . . .
Message problems . . . . . . . . . . .
No response from the compiler . . . .
PL/I documentation problems . . . . .
Output problems . . . . . . . . . . . . .
Performance problems . . . . . . . . .
Chapter 7. Module keyword

12
13
14
14

Chapter 4. Component identification keyword

Chapter 5. Release-level keyword

v
v
v

. . . . . .

26

. . . . . . . . . . . . . . . . .

27

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29

iii

Chapter 12. Preparing an APAR

Opening a PMR . . . . . . . . . . .
Initiating an APAR . . . . . . . . . .
Materials to submit . . . . . . . .
Notices . .
Trademarks

. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Bibliography . . . . . . . . . . . . . . .
Enterprise PL/I publications . . . . . . .
PL/I for MVS & VM . . . . . . . . . . . .
z/OS Language Environment . . . . . .
CICS Transaction Server . . . . . . . . .
DB2 UDB for OS/390 and z/OS . . . . .
DFSORT . . . . . . . . . . . . . . . . .
IMS/ESA . . . . . . . . . . . . . . . . .
z/OS MVS . . . . . . . . . . . . . . . . .
z/OS UNIX System Services . . . . . . .
z/OS TSO/E . . . . . . . . . . . . . . . .
z/Architecture . . . . . . . . . . . . . . .
Unicode and character representation
Index

iv

Enterprise PL/I Diagnosis Guide

30
30
30
31
33
34

. . . . . . . . . . . . . . . . . . . . . . .

35
35
35
35
35
35
35
35
35
35
35
36
36

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

37

. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .

About this book

This book tells you how to diagnose failures in the IBM Enterprise PL/I for OS/390
compiler only. Because PL/I uses OS/390 Language Environment as its run-time
environment, and uses certain run-time routines during compilation, consult
dcit.Language Environment Diagnosis Guide or OS/390 Language Environment
Debugging Guide and Run-Time Messages to diagnose product failures you
encounter in the run-time environment.
The book assumes that you have already determined that the suspected failure is
not a user error; that is, it was not caused by incorrect usage of PL/I or by an error
in the logic of the application program. In the cases where a user error is the
cause of the problem, consult Enterprise PL/I for z/OS and OS/390 Programming
Guide or PL/I Language Reference for more information.
This book helps you determine if a correction for a product failure similar to yours
has been previously documented. If the problem has not been previously reported,
Chapter 12, Preparing an APAR on page 30 explains how to prepare an
Authorized Program Analysis Report (APAR).
Most of the information in this book is to be used across operating systems.
Information that is unique to an operating system is identified as such.

Who this book is for

This book is for system programmers, application programmers, and IBM support
personnel who are involved in PL/I product diagnosis. Prerequisite knowledge for
using this book is:

A general understanding of your operating system

Some knowledge of the PL/I language and options

Using your documentation

The publications provided with Enterprise PL/I are designed to help you program
with PL/I. The publications provided with Language Environment are designed to
help you manage your run-time environment for applications generated with
Enterprise PL/I. Each publication helps you perform a different task.
The following tables show you how to use the publications you receive with
Enterprise PL/I and Language Environment. You'll want to know information about
both your compiler and run-time environment. For the complete titles and order
numbers of these and other related publications, see Bibliography on page 35.

Copyright IBM Corp. 1991, 2002

PL/I information
Table 1. How to use Enterprise PL/I publications
To...

Use...

Evaluate Enterprise PL/I

Fact Sheet

Understand warranty information

Licensed Programming Specifications

Plan for and install Enterprise PL/I

Enterprise PL/I Program Directory

Understand compiler and run-time changes and

adapt programs to Enterprise PL/I and Language
Environment

Compiler and Run-Time Migration Guide

Prepare and test your programs and get details on

compiler options

Programming Guide

Get details on PL/I syntax and specifications of

language elements

Language Reference

Diagnose compiler problems and report them to IBM

Diagnosis Guide

Get details on compile-time messages

Compile-Time Messages and Codes

Language Environment information

Table 2. How to use OS/390 Language Environment publications

vi

To...

Use...

Evaluate Language Environment

Concepts Guide

Plan for Language Environment

Concepts Guide
Run-Time Migration Guide

Install Language Environment on OS/390

OS/390 Program Directory

Customize Language Environment on OS/390

Customization

Understand Language Environment program models

and concepts

Concepts Guide
Programming Guide

Find syntax for Language Environment run-time

options and callable services

Programming Reference

Develop applications that run with Language

Environment

Programming Guide and your language

Programming Guide

Debug applications that run with Language

Environment, get details on run-time messages,
diagnose problems with Language Environment

Debugging Guide and Run-Time Messages

Develop interlanguage communication (ILC)

applications

Writing Interlanguage Applications

Migrate applications to Language Environment

Run-Time Migration Guide and the migration

guide for each Language Environment-enabled
language

Enterprise PL/I Diagnosis Guide

Part 1. Determining the problem

Chapter 1. Compiler overview . . . .
Function of the Enterprise PL/I compiler
Processing a PL/I program . . . . . . . .
Compiling . . . . . . . . . . . . . . . . . .
Preprocessing stage . . . . . . . . . .
Compiling stage . . . . . . . . . . . .
Link-editing . . . . . . . . . . . . . . . . .
Running . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2. Compile-time problem determination chart

Copyright IBM Corp. 1991, 2002

. . . . . . . . . . . . .

2
2
2
3
3
4
4
4
6

Chapter 1. Compiler overview

This chapter includes an overview of the Enterprise PL/I for z/OS and OS/390
(Enterprise PL/I) compiler and its place in the processing of a PL/I program.

Function of the Enterprise PL/I compiler

The Enterprise PL/I compiler analyzes source programs written in the PL/I language
and translates these source statements into a series of machine instructions that
form an object module. The compiler operates as a problem-state program under
the operating system.

Processing a PL/I program

Figure 1 and Figure 2 on page 3 show the process through which a PL/I program
passes from compilation to use.

Figure 1. Compile-time tasks

Copyright IBM Corp. 1991, 2002

Figure 2. Run-time tasks

There are four stages in the process:

1. Writing: Coding the program and preparing it for the computer.
2. Compiling: Translating the program into machine instructions (that is, creating
an object module).
3. Link-editing: Producing a load module from the object module. This includes
linking the compiled code with run-time library modules, and possibly with other
compiled programs. It also includes resolving the addresses within the code.
4. Running: Executing the load module.
The process is not necessarily a continuous one. The program can, for example,
be kept in a compiled or link-edited form before it is run, and also be run a number
of times once compiled.

Compiling
Compiling is the process of translating a PL/I program into machine instructions.
This is done by associating PL/I statements with addresses in storage and
translating executable PL/I statements into a series of machine instructions.

Preprocessing stage
The compiler receives the source program either directly or through a preprocessor
stage (see Figure 1 on page 2). The preprocessor can modify source statements
in the program or insert additional source statements in the program before
compilation begins. You invoke the preprocessor by specifying the compile-time
option MACRO. If the compiler detects an error or the possibility of an error during
the preprocessor stage, it prints a message on the pages following the input listing.
Thus, there are two sets of messages: one for the preprocessor and one for the
compiler. Details of preprocessor and compile-time messages are given in
Enterprise PL/I Compile-Time Messages and Codes.

Chapter 1. Compiler overview

Compiling stage
Under the control of the OPTIMIZE compile-time option, the compiler optimizes
code by automatically altering the sequence of statements or operations, creating a
more efficient object program. Some compile-time options useful in determining
problems are shown in Table 3. For more information about these options, see
Enterprise PL/I for z/OS and OS/390 Programming Guide.
Table 3. Compile-time options helpful in determining problems
Documentation needed

Compile-time option to use

Source listing

SOURCE

Cross-reference listing

XREF

Attribute table

ATTRIBUTES

Aggregate table

AGGREGATE

Storage table

STORAGE

Compile-time options

OPTIONS

Object listing

LIST

Statement in error

GONUMBER

Diagnostic message list

FLAG(I)

Margins of source list

MARGINI

Preprocessor information

INSOURCE
MDECK
MACRO

Block and do-group statement listing

NEST

Debugging information about compiled code

TEST
GONUMBER

Link-editing
Link-editing links the compiler-generated object code with external modules
requested by the compiled program. These are run-time library routines and
possibly modules produced by other compilations. As well as linking the external
modules, the linkage editor also resolves addresses within the object module. See
OS/390 Language Environment Programming Guide for a detailed discussion of
link-editing.

Running
The PL/I compiler produces code that requires a special arrangement of control
blocks and registers to run correctly. This arrangement of control blocks and
registers is the run-time environment. Execution consequently is a three-stage
process:
1. Set up the environment. (The run-time initialization routines handle this.)
2. Run the program.
3. Complete the job after the run. (This consists of closing any files left open and
returning control either to the supervisor or to a calling module. The
termination routines handle this.)

Enterprise PL/I Diagnosis Guide

See OS/390 Language Environment Programming Guide for a detailed discussion

of how to run your PL/I program.

Chapter 1. Compiler overview

Chapter 2. Compile-time problem determination chart

This chapter contains the compile-time problem determination chart.
If you have already made a preliminary diagnosis of your problem and are familiar
with PL/I, you can use the chart index in Table 4 to find the information you need.
Table 4. Compile-time problem determination index
Compile-time
subject covered
Abend or program check
Message
Loop
Wait
Unusual or unexpected output
Performance

Block
number
26
28
32
34
35
37

If you are just beginning your problem diagnosis, start by using the chart in
Table 5. Begin with Block 1 and answer the question or perform the action
specified, go to the block indicated by the answer. Some blocks describe an action
to be performed and also direct you to the next block.
Table 5 (Page 1 of 5). Compile-time problem determination chart
Block
Number

Question

Answer

Go to
Block

Is this a compile-time failure or a run-time failure?

Compiletime

Run-time

See OS/390
Lannguage
Environment
Debugging and
Run-Time
Messages
Guide.

Note: The compiler requires access to Language Environment during

compilation. If the needed run-time routines are not available during
compilation, compiler message IBM0995I is issued. Errors occurring in
these run-time library routines are always intercepted by the compiler
and reported using an associated compiler message. If your compiler
message includes a run-time message number, you need to use this
chart and refer to OS/390 Language Environment Debugging Guide and
Run-Time Messages.
2

Is this a U-level message?

Yes
No

8
3

Is this a problem relating to a message?

Yes
No

8
4

Is this a loop?

Yes
No

8
5

Is this a wait?

Yes
No

8
6

Does the compilation result in some type of unusual or unexpected

output?

Yes
No

8
7

Is this a performance problem?

Yes
No

8
24

Has the program ever compiled before?

Yes
No

9
11

Copyright IBM Corp. 1991, 2002

Table 5 (Page 2 of 5). Compile-time problem determination chart

Block
Number

Question

Answer

Go to
Block

Has anything in the environment changed? (Source changes, release

level, maintenance fixes, compile-time options, and so on.)

Yes
No

12
10

10

Is the entry from:

Yes
Yes
Yes
Yes
Yes
Yes

26
28
32
34
35
37

U-level message
Message other than U-level
Loop
Wait
Unusual or unexpected output
Performance
Note: If you are here via the environment changed route, follow the
major symptom code being experienced.
11

Make sure PL/I coding rules were followed. Check and correct any
statements causing E- or S-level messages. Check and correct any
source statements causing W- or I-level messages that might relate to
the problem. If you are using the OPTIMIZE(TIME) or OPTIMIZE(2)
compile option, recompile using NOOPTIMIZE. Is the problem
circumvented?

Yes
No

41
10

12

Has the source code of the program changed? (This includes

compile-time options.)

Yes
No

15
13

13

Was any maintenance applied? (PTFs, fixes)

Yes
No

17
14

14

Has the release level changed?

Yes
No

18
25

15

Check and correct any source statements causing E or S-level

messages. Check and correct any source statements causing W- or
I-level messages that might relate to the problem. Check and correct
any compile-time options causing messages to be issued. Be critical of
source changes. Is the problem solved?

Yes
No

END
16

Note: If the problem is solved, but you feel the message was
generated in error, follow the NO path.
16

If you are using the OPTIMIZE(TIME) or OPTIMIZE(2) compile-time

option, recompile using NOOPTIMIZE. Is the problem circumvented?

Yes
No

41
10

17

Are the fixes or PTFs installed correctly? In other words, were there any
system messages while installing and link-editing? Search early warning
microfiche or INFO/ACCESS, or ask the IBM Support Center Level 1 to
search RETAIN for possible PTF errors in the form PExxxxx.

Yes
No

19
20

18

Ensure that the release has been installed correctly. (Search early
warning microfiche or INFO/ACCESS, or ask the IBM Support Center
Level 1 to search RETAIN for any PTFs and errors applicable to this
release. Search for PTF errors in the form: PExxxxx.) Were there any
SMP error messages or system messages while installing the release?

Yes
No

19
21

19

Search early warning microfiche, INFO/ACCESS (Level 1), or have the

IBM Support Center search RETAIN. Information about conducting a
search is in Chapter 10, Using the keyword string to search for
corrections on page 26.

Yes
22

No
10

Any hits?

Chapter 2. Compile-time problem determination chart

Table 5 (Page 3 of 5). Compile-time problem determination chart

Block
Number

Question

Answer

Go to
Block

20

Reinstall the PTF or fix and test. Is the problem solved?

Yes
No

END
23

21

Reinstall the release level correctly, plus any PTFs or fixes that apply,
and test. Is the problem solved?

Yes
No

END
23

22

Apply applicable fixes from RETAIN and test. Is the problem solved?

Yes
No

END
23

23

Have the symptoms changed?

Yes
No

2
10

24

Something was probably overlooked. A failure occurred, and it was one

of the previously mentioned items.

41

Review the compiler output again. If the problem does not fit any of the
stated symptoms, go to Block 41.
25

Something was probably changed. Carefully determine what has

changed with regard to this program. Is it:
Yes

15

Maintenance? This includes all APAR and PTF fixes to PL/I, fixes to
Language Environment that relate to PL/I, and fixes to the operating
system that relate to the problem.

Yes

17

Release-level changes? This includes changes in the release level of

PL/I, Language Environment, or the operating system.

Yes

18

None of the above?

Yes

41

Source code changes? This includes changes to the compile-time

options, to INCLUDE files, and to different compile-time messages from
the last time the program was successful.

26

Compiler abends and program checks produce one of following internal

compiler error messages: IBM1994S, IBM1995S, IBM1996S, or
IBM1997S.

27

IBM1994S Internal Compiler Error: storage header has been

overwritten
IBM1995S Internal Compiler Error: storage tail has been overwritten
IBM1996S Internal Compiler Error: free amount free request size
does not match allocated size allocated size.
IBM1997S Internal Compiler Error: no WHEN clause satisfied within
module name.
IBM1998S Internal Compiler Error: protection exception in module
name
Note: Details of compiler error numbers and any recommended
programmer actions are in Enterprise PL/I Compile-Time Messages and
Codes. If the actions described do not solve the problem, go to Block
27.
27

Search early warning microfiche, INFO/ACCESS (Level 1), or have the

IBM Support Center search RETAIN using the component ID 5655H31,
the error number from the message, and the phase ID from the
message. Information about conducting a search is in Chapter 10,
Using the keyword string to search for corrections on page 26.
Any hits?

Enterprise PL/I Diagnosis Guide

Yes
No

39
41

Table 5 (Page 4 of 5). Compile-time problem determination chart

Block
Number

Question

Answer

Go to
Block

28

Is this an E- or S-level diagnostic message?

Yes
No

29
30

29

Look up the message in Enterprise PL/I Compile-Time Messages and

Codes. These messages indicate the compiler-detected error conditions
in the source statements. Compilation can be complete, but the object
program might not run correctly.

Yes
No

30
END

Check and correct any statements in error. Rerun the program.

Does the message still occur?
30

If you are using the OPTIMIZE(TIME) or OPTIMIZE(2) compile-time

option, recompile with NOOPTIMIZE. Is the problem circumvented?

Yes
No

41
31

31

Search early warning microfiche, INFO/ACCESS or have the IBM

Support Center search RETAIN using component ID 5655H31 and
MSGIBMxxxxI. Information about doing your search is in Chapter 10,
Using the keyword string to search for corrections on page 26.

Yes
No

39
41

Yes
No

41
33

Yes
No

39
41

Any hits?
32

If a loop appears to occur, use a system-trace facility or instruction-step

mode to capture all, or at least part, of the loop addresses. Then cancel
the job with a dump.
Find the current phase in the dump as follows:

Register 13 points to the communications area (XCOMM).

To check, look at the field at offset '90'X from register 13. This
field contains the first source input record. If register 13 was
corrupted, search for this field to locate XCOMM.

The current phase name is at offset '4AB'X from the beginning of
XCOMM. This field contains two letters. Adding IBMX before these
two letters gives you the name of the current phase.

The phase start address is at offset '434'X from XCOMM.
If you are using the OPTIMIZE compile-time option, recompile using
NOOPTIMIZE. Phase IBMXIE can appear to be in a loop if a large
number of BYNAME assignments occur or if the source assigns to a
large PICTURE statement. Phase IBMXIK can appear to be in a loop
while sorting data names for the XREF table. Give the compiler a little
more time. Other loops are caused by:

Using a colon instead of a semicolon

Not enough storage

Not enough time
Is the problem circumvented?

33

Search early warning microfiche, INFO/ACCESS, or have the IBM

Support Center search RETAIN using:

Component ID 5655H31

LOOP and module names in which loop occurs
Information about doing your search is in Chapter 10, Using the
keyword string to search for corrections on page 26.
Any hits?

Chapter 2. Compile-time problem determination chart

Table 5 (Page 5 of 5). Compile-time problem determination chart

Block
Number

Question

34

The only wait states the compiler issues are for I/O. Investigate wait
states from the system control viewpoint:

Answer

Go to
Block
41

Check to see that the region running PL/I is not waiting for a
resource owned by another region.

See if there are any system messages.
If you still suspect the PL/I compiler is causing the wait state, go to
Block 41.
35

Be sure all appropriate compile-time options are specified. If you are

using the OPTIMIZE(TIME) or OPTIMIZE(2) compile-time option,
recompile with NOOPTIMIZE. Is the problem circumvented?

Yes
No

41
36

36

Search early warning microfiche, INFO/ACCESS (Level 1), or have the

IBM Support Center search RETAIN using component ID 5655H31 and
INCORROUT (a word describing what output is incorrect). Information
about doing your search is in Chapter 10, Using the keyword string to
search for corrections on page 26.

Yes
No

39
41

Yes
No

41
38

Yes
No

39
41

Any hits?
37

Performance problems usually show up after some environment change;

if not a maintenance change, perhaps a source code or compile-time
option change. Review these items.
If you are using the OPTIMIZE(TIME) or OPTIMIZE(2) compile-time
option, recompile with NOOPTIMIZE. Is the problem circumvented?

38

Search early warning microfiche, INFO/ACCESS (Level 1), or have the

IBM Support Center search RETAIN using component ID 5655H31.
Information about doing your search is in Chapter 10, Using the
keyword string to search for corrections on page 26.
Any hits?

39

Apply the fixes or circumvention found in RETAIN, and test. Is the

problem solved?

Yes
No

END
40

40

Do the symptoms change?

Yes
No

2
41

41

Contact the IBM Support Center for assistance. Have available the
following documentation:

Compile listing with LIST, SOURCE, and XREF compile-time options
in effect

The TSO command sequence or the JCL used to run the job

Dump (if applicable)

Preprocessor input (if applicable)

List of applied fixes

10

Enterprise PL/I Diagnosis Guide

Part 2. Describing the problem

Chapter 3. Introduction to Diagnosis Keywords
Keyword Usage . . . . . . . . . . . . . . . . . . . . .
Using the Problem Identification Worksheet . . . . .
Diagnosis Procedure . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

12
13
14
14

. . . . . . . . . . . . . . . . .

16

. . . . . . . . . . . . . . . . . . . . . . . . .

17

Chapter 4. Component identification keyword

Chapter 5. Release-level keyword

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23

Chapter 8. System-type keyword

Chapter 9. Modifier keyword

. . . . . . . . . . . . . . . .

18
19
19
20
20
21
22

Chapter 6. Type-of-failure keyword

Abnormal termination . . . . . . . . . .
Message problems . . . . . . . . . . .
No response from the compiler . . . .
PL/I documentation problems . . . . .
Output problems . . . . . . . . . . . . .
Performance problems . . . . . . . . .
Chapter 7. Module keyword

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . .

24

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

25

Chapter 10. Using the keyword string to search for corrections

Chapter 11. Problem identification worksheet

Copyright IBM Corp. 1991, 2002

. . . . . .

26

. . . . . . . . . . . . . . . . .

27

11

Chapter 3. Introduction to Diagnosis Keywords

Failures in the Enterprise PL/I compiler can be described through the use of
diagnosis keywords. A diagnosis keyword is a word or abbreviation used to
describe one aspect of a product failure. You can use a set of keywords called a
keyword string to describe the failure in detail. Use the procedures in this section
to construct a keyword string that describes what you currently know about the
compiler failure. Table 6 lists the books that discuss problems other than compiler
failures.
Table 6. References for Other Failure Information
Type of failure

Source of information

User compile-time problems

See the Enterprise PL/I for z/OS and OS/390

Programming Guide

User run-time problems

See the OS/390 Language Environment

Debugging Guide and Run-Time Messages or
the OS/390 Language Environment
Programming Guide

Language Environment for OS/390 & VM

run-time product failures

See the Language Environment Diagnosis

Guide

After it is constructed, the keyword string is used as a search argument against an

IBM software support database, such as the Software Support Facility (SSF). The
database contains keyword and text information describing all current problems
reported through Authorized Program Analysis Reports (APARs) and associated
program temporary fixes (PTFs). IBM Support Center personnel have access to
the software support database and are responsible for storing and retrieving the
information. Using the keyword string, they search the database to retrieve records
that describe similar known problems.
If you have IBMLink or some other electronic link with IBM Service, you can do
your own search for previously recorded product failures before calling the IBM
Support Center.
If the keyword string search produces a match in the software support database,
the search might yield a more complete description of the problem and possibly
identify a correction or circumvention. Such a search might yield several matches
to previously reported problems. Thus, you should review each error description
carefully to determine if the problem description in the database matches the
failure.
If a match is not found, use the keyword string you have constructed to describe
the failure when you contact the IBM Support Center for assistance and when you
submit an APAR. Keywords are intended to ensure that identical program errors
are described with identical keyword strings. Spelling the keywords exactly as they
are presented in this book is especially important for a successful match.

12

Copyright IBM Corp. 1991, 2002

Keyword Usage
Depending upon the PL/I failure, a keyword string can contain some or all of the
following items:

Component identification
Release level
Type of failure
Name of the module that failed
Name of the system you were operating under at the time of failure
One or more modifier keywords, depending on the type of failure

In building a keyword string, the first keyword usually identifies the failing
component. The component identification for Enterprise PL/I should be the
compiler identifier. A search of the software support database with this single
keyword would locate all problems reported for the compiler. Each additional
keyword added to the keyword string narrows the scope of the search argument
and helps to eliminate unnecessary examination of problem descriptions that have
similar, but not matching, characteristics. In some cases, a correction for a product
failure might be located with less than a full string of keywords. If circumstances
make it difficult to follow the instructions for selecting a particular keyword, omit that
keyword to avoid incorrectly identifying the problem. In general, if you contact IBM,
you are asked to identify your problem with a full set of keywords, as described
here.
Follow the steps in the keyword procedures until you are directed to use the
keyword string in a search argument.
Figure 3 on page 14 shows the keyword string generation process for each type of
failure.

Chapter 3. Introduction to Diagnosis Keywords

13


Component ID
Keyword

(5655H31)

Release-Level
Keywords

(R31 - MVS)

Type of ! Failure Keyword

!
!
!
!
!
!

Abnormal
No
Performance Incorrect
Message Documentation
Termination Response Problem
Output
Problem Error

(IBM1994S)

(IBM1995S)

(IBM1996S)
(LOOP)
(PERFM)
(INCORROUT) (MSGxxxx) (DOC)

Module

Keyword

System Type

Keyword

Modifier

Keyword

Figure 3. Enterprise PL/I Problem Identification Using Keywords

Using the Problem Identification Worksheet

You can use Chapter 11, Problem identification worksheet on page 27 to help
you construct and record a keyword string. As you identify the keywords
associated with your software problem, just record them in the spaces provided.

Diagnosis Procedure
This procedure is designed to gather the diagnostic information required for
developing a keyword string to search the software support database. It describes
options that you can specify to obtain all the available diagnostic information. You
need this information to discuss the problem with your IBM support representative if
your search against the database fails to locate a fix for your problem.

14

Enterprise PL/I Diagnosis Guide

Use the following procedure only if the problem is occurring at compile time. If the
problem is in the Language Environment for OS/390 & VM product, refer to the
Language Environment Diagnosis Guide for diagnostic information.
1. Locate the source of the problem:
a. Determine if the program has been changed since it was last compiled
successfully. If it has, examine the changes. If the error is occurring in the
changed code, note the change that caused the error. If possible, retain
copies of both the original and the changed programs in case you need to
submit an APAR.
b. Determine if the operating system environment has been changed. If it
has, examine the changes. If the error cannot be resolved by examination
of the changes, have a description of the changes available when you call
the IBM Support Center.
c. Determine if PL/I maintenance has been applied. If it has, determine if the
error was due to a particular PTF and call the IBM Support Center with this
information.
2. Correct all problems diagnosed by error messages. Ensure that any messages
previously generated do not affect the current problem. Be sure to pay
attention to warning messages (W-level messages). Message prefixes identify
the system or subsystem that issued the error:

Enterprise PL/I compiler messages are prefixed by IBM. The compiler also
issues certain messages prefixed by IKJ and DMS.

For messages other than these, consult the appropriate system or
subsystem messages book.
3. After you have explored and identified the failure, consider writing a small test
case that recreates the problem. This test case should help you to:

Pinpoint the problem

Distinguish between an error in the application program and an error in PL/I

Choose keywords that best describe the error
4. In addition to the options originally specified, specify the compile-time options
described in Table 3 on page 4 and recompile the program.
These options produce maximum diagnostic information, which helps you
diagnose product errors. See the Enterprise PL/I for z/OS and OS/390
Programming Guide for more information on how to use these options.
5. If the error symptoms change, return to step 2.
6. Record the sequence of events that led to the error condition. This information
can be useful in developing a keyword string, and is needed if an APAR is
required.
7. Begin developing the keyword string. Start with the procedures in Chapter 4,
Component identification keyword on page 16.

Chapter 3. Introduction to Diagnosis Keywords

15

Chapter 4. Component identification keyword

This procedure shows what to specify as the component identification keyword.
The component identification keyword is usually the first keyword placed in the
search argument string. It comes from the PL/I compiler program number and
identifies the area within the software support database that contains APARs for
PL/I.
At minimum, you need to use a type-of-failure keyword as a search argument along
with the component identification keyword. If you search using only the component
identifier keyword, you receive a full listing of all the APARs affecting PL/I.
1. Use 5655H3100 as the component identification keyword. This number is the
Enterprise PL/I compiler product identifier, 5655H31, with 00 appended.
2. If service tapes have been applied to the licensed program, note the tape level
of the last service tape applied. See your system programmer for the current
service level of your PL/I compiler. Although the service tape level is not used
in the keyword string, you might find it useful when reviewing APARs selected
during the keyword search.
3. Continue the diagnostic procedure with Chapter 5, Release-level keyword on
page 17.

16

Copyright IBM Corp. 1991, 2002

Chapter 5. Release-level keyword

Use the following procedure to identify the specific release level of PL/I under which
you were operating when the failure occurred.
1. Locate the version, release, and modification level line at the top of the first
page of your latest compiler output listing for the failing program. The heading
line contains the current product identification data in the following format:
5655-H31 IBM Enterprise PL/I for z/OS v.r.m
where:
v
r
m

Specifies the current version

Specifies the current release
Specifies the current modification number

The date and time of compilation and the page number are also found on the
heading line. The heading line for Version 3.1.0 of Enterprise PL/I would be as
follows:
5655-H31 IBM Enterprise PL/I for z/OS V3.R1.M
2. Specify the release-level keyword, using the format: R31
The following is an example of a partial keyword string, consisting of the
component identification and the MVS release-level keyword.
5655H31 R31
3. Continue the diagnostic procedure with Chapter 6, Type-of-failure keyword on
page 18.

Copyright IBM Corp. 1991, 2002

17

Chapter 6. Type-of-failure keyword

Various types of failure specific to the compiler might occur in the PL/I licensed
program. Table 7 lists the books that discuss problems other than compiler
failures.
Table 7. References for other failure information
Type of failure

Source of information

User compile-time problems

See Enterprise PL/I for z/OS and OS/390

Programming Guide

User run-time problems

See OS/390 Language Environment

Debugging Guide and Run-Time Messages or
OS/390 Language Environment Programming
Guide

Language Environment run-time product

failures

See Language Environment Diagnosis Guide

Read Table 8 and select the type of failure that best describes the problem with
the compiler. Then go to the associated keyword procedure listed in this table for
instructions on how to complete the keyword string for that type of failure. If more
than one of the keywords in the following table describes the problem you are
experiencing, use the keyword that appears first in the table.
Table 8 (Page 1 of 2). Types of PL/I failures
Type of failure

Symptom

Procedure

Abnormal termination

The compiler has terminated

abnormally, issuing one of five
internal compiler messages:

See Abnormal termination

on page 19.

IBM1994S
IBM1995S
IBM1996S
IBM1997S
IBM1998S

18

Message problems

The compiler issues an

inappropriate or invalid error
message.

See Message problems on

page 19.

No response from the

compiler

Either an unexpected program

suspension has occurred; no
response has been received in
interactive mode; the job has
not completed in batch mode;
or an ABENDX22 has
occurred.

See No response from the

compiler on page 20.

PL/I documentation
problems

Information in one of the PL/I

publications or soft copy
documents is incorrect or
missing.

See PL/I documentation

problems on page 20.

Output problems

The output from the compiler is

missing or invalid.

See Output problems on

page 21.

Copyright IBM Corp. 1991, 2002

Table 8 (Page 2 of 2). Types of PL/I failures

Type of failure

Symptom

Procedure

Performance problems

The performance of a PL/I

compilation is degraded.

See Performance
problems on page 22.

Abnormal termination
The compiler can terminate abnormally with either a system or user abend. When
abends occur in the compiler, the compiler traps these abends and generally issues
one of the following messages:

IBM0001I

IBM0230I

IBM0970I
Check the error and restriction codes associated with the message received. For a
list of the error and restriction codes, see Enterprise PL/I Compile-Time Messages
and Codes.
Ensure that all other problems have been fixed and search the database to
determine if the problem is already known. If you determine that this is a new
problem, call IBM with the message information received.
Note: If you receive an ABENDx22, see No response from the compiler on
page 20.

Message problems
Before using this procedure, verify that you have received a compiler message.
The PL/I compiler issues messages prefixed with IBM. Messages with other
prefixes are issued by the Language Environment run-time environment or by
operating systems or subsystems and access methods, and should not be
addressed as PL/I product problems. See the Enterprise PL/I Compile-Time
Messages and Codes for Enterprise PL/I messages.
Use this procedure for any one of the following conditions:

A message is issued under a set of conditions that should not have caused it to
be issued.

A message contains invalid data or is missing data.
Use the following procedure to construct the MSGx keyword:
1. For example, if you received message number IBM1994S, replace the x in
MSGx with IBM1994S, as shown in the following example:
5655H31 R31 MSGIBM1994S
2. Proceed with Chapter 8, System-type keyword on page 24.

Chapter 6. Type-of-failure keyword

19

No response from the compiler

Use this keyword procedure for any of the following conditions:

The compiler seems to be doing nothing or is doing something repetitively.

A terminal response is not received in interactive mode after invoking the
compiler.

The compiler does not reach completion in batch mode.

The last two digits of a system abend code
If the problem looks like a WAIT state and the compiler is not waiting for input from
the terminal or console, it is probably a system problem. In that case, follow your
local procedures for resolution. Otherwise, perform the following LOOP procedure.
1. If you are running in batch mode under OS/390 and the error is a system
abend with abend code x22 (indicating not enough time), increase the time
allotment and rerun the compiler. If the problem is still unresolved, your set of
keywords, so far, would look something like this:
5655H31 R31 LOOP
2. Continue with Chapter 7, Module keyword on page 23.

PL/I documentation problems

Use this procedure when you notice a problem caused by incorrect or missing
information in one of the published documents or the soft copy PL/I documents.
1. Locate the page or pages in the document (or the online panel for a soft copy
document) where the problem occurs and prepare a description of the error
and the problem it caused. This information is required for APAR preparation if
no similar problem is found in the software support database.
2. Decide whether the documentation problem is severe enough to cause lost
time for other users.

If the problem is not severe, submit a Reader's Comments Form (RCF)
attached to the back of the publication in question. As an option, you can
fax the RCF to IBM using the fax number printed on the RCF. If the RCF
is missing, send a note to the address shown on the edition notice for this
book. Include the problem description you have developed, along with your
name and return address, so that IBM can respond to your comments.

If the problem is severe enough to cause lost time for other users, continue
creating your keyword string to determine whether IBM has a record of the
problem. Should this be a new problem, you will be asked to submit a
severity-3 or -4 documentation (DOC) APAR.
3. Use the order number on the cover of the document along with the DOC
keyword as your type-of-failure keyword, but omit the hyphens. Leave a single
space between DOC and the document number. If the number following the
last hyphen has only one digit, it must be preceded by a zero. For example, if
the order number is SC26-9453-00 (PL/I Language Reference), use
SC26945300. Your keyword string would look something like this:
5655H31 R31 DOC SC269453

20

Enterprise PL/I Diagnosis Guide

4. Search the IBM software support database to determine if this documentation

problem has already been reported. If, after searching the database, you do
not find a matching description, return here to continue. To search the
database, turn to Chapter 10, Using the keyword string to search for
corrections on page 26.
5. In case several levels of the document exist, you can use two asterisks
appended to the document number to search for all problems reported for the
document rather than only those for a specific release of the document. Use a
format similar to the following:
5655H31 R31 DOC SC269453DD
6. Go to Chapter 10, Using the keyword string to search for corrections on
page 26.

Output problems
Use this procedure when the output appears to be incorrect or missing, but the
compiler terminated normally. If the data or records were repeated endlessly,
follow the steps under No response from the compiler on page 20 instead of this
Output problems procedure to create your keyword string.
1. Use INCORROUT as your type-of-failure keyword.
2. Select a modifier keyword from the following table to describe the type of error
in the output. For more information on the use of modifier keywords, see the
section Chapter 9, Modifier keyword on page 25.
Table 9. Incorrect output modifier keywords
Modifier keyword

Type of incorrect output

DUPLICATE

Some data or records were duplicated, but were not

repeated endlessly.

INVALID

The output that appeared was not as expected; that is, the
output was bad or incorrect.

MISSING

Some expected output was missing.

3. Select another modifier keyword from the following table to describe the portion
of the output in which the error occurred.
Table 10. Output error location keywords
Modifier keyword

Portion of output in error

LIST

Assembler language expansion of source listing, global

tables, literal pools, static storage map

SOURCE

Source listing

XREF

Cross-reference listing

For example, if you think that the compiler has given an incorrect
cross-reference listing, your keyword string so far would look something like
this:
5655H31 R31 INCORROUT INVALID XREF

Chapter 6. Type-of-failure keyword

21

4. Continue the diagnostic procedure with Chapter 8, System-type keyword on

page 24.

Performance problems
Most performance problems can be related to system tuning and should be handled
by system engineers and system programmers. You might want to contact your
IBM system engineer who can use ASKQ to retrieve recommendations for
improving product performance.
Use the following keyword procedure when the performance problem could not be
corrected by system tuning and performance is significantly below explicitly stated
expectations.
1. Use PERFM as your type-of-failure keyword. For example, your keyword string
for performance problems might look like this:
5655H31 R31 PERFM
2. Continue the diagnostic procedure with Chapter 8, System-type keyword on
page 24.

22

Enterprise PL/I Diagnosis Guide

Chapter 7. Module keyword

The following procedure demonstrates how you build a module keyword.
In messages, module names are shown as:
PHASE xx
To construct a module name from this type of message, you append IBMX to the
phase as shown in the example below.
IBMXEA
Continue the diagnostic procedure with Chapter 8, System-type keyword on
page 24.

Copyright IBM Corp. 1991, 2002

23

Chapter 8. System-type keyword

Since you were operating under OS/390 when the Enterprise PL/I compiler failed,
use OS390 as your system-type keyword. Your keyword search might look like
this:
5655H31 R31 MSGIBM23S OS39
Now continue the diagnostic procedure with Chapter 9, Modifier keyword on
page 25.

24

Copyright IBM Corp. 1991, 2002

Chapter 9. Modifier keyword

This procedure helps you determine what type of keyword (modifier or source
language) you should add to your keyword string. Use this procedure to locate the
point of compiler failure or the keyword you were using when the failure occurred.
Table 11 lists the books that discuss problems other than compiler failures.
Table 11. References for other failure information
Type of failure

Source of information

User compile-time problems

See Enterprise PL/I for z/OS and OS/390

Programming Guide

User run-time problems

See OS/390 Language Environment

Debugging Guide and Run-Time Messages or
OS/390 Language Environment Programming
Guide

Language Environment run-time product

failures

See Language Environment Diagnosis Guide

One or more modifier keywords can be used in the same keyword string to define
the compiler problem. Additional modifiers help to make the search argument more
specific. Use the capitalized spelling of the modifier in the keyword string. The
various types of modifier keywords include:

Compile-time options
Select from your compiler listing those compile-time options that you consider
significant to the type of failure. See the Enterprise PL/I for z/OS and OS/390
Programming Guide for a list of the compile-time options. The option name
itself (in full or abbreviated format) is the keyword.
If the compiler failure appears to be correlated with any particular compiler
option or options, such as XREF, use those options as additional modifier
keywords, as in this example:
5655H31 R31 MSGIBM23I XREF

Message IDs
If you receive a compile-time message, you can use the ID as an additional
modifier. For example, assume that you received this message:
IBM23I

COMPILER ERROR  DURING PHASE EA

You could then use IBM1995S as an additional modifier.

PL/I language keywords
If the compiler failure is peculiar to a PL/I language keyword, use the language
keyword as a modifier keyword. For example, if the source of failure was the
PL/I language keyword SELECT, your keyword string would look something like
this:
5655H31 R31 MSGIBM23I SELECT
Continue the diagnostic procedure with Chapter 10, Using the keyword string to
search for corrections on page 26.

Copyright IBM Corp. 1991, 2002

25

Chapter 10. Using the keyword string to search for

corrections
This chapter explains how to use the keyword string as a search argument against
a software support database. The search can be performed by calling an IBM
Support Center or using your electronic link with IBM, if available.
Your search will be more successful if you follow these rules:

Use only the keywords given in this book.

Spell keywords the way they are spelled in this book. Any variation in spelling
can result in an unsuccessful search.

Include all the appropriate keywords in any discussion with IBM support
personnel or in an APAR.
In order to search the support database, you should perform the following steps:
1. Search the software support database, using the full set of keywords you have
developed. For example, consider the following keyword string:
5655H31 R31 MSGIBM23I IBMDEA OS39
Note: You can use a wildcard (*) when you use the module name as part of
your search argument.
2. If the search produces a list of APARs, continue with step 3; otherwise, go to
step 6.
3. When your search is complete, eliminate from the list of possible APAR fixes
those that have already been applied to your system.
4. Compare each of the remaining closed APAR descriptions with the current
failure symptoms.
5. If a match is found, apply the PTF to your system and exit this procedure.
6. If the search did not produce a list of APARs, or an APAR description matching
the current failure is not found, broaden the search, using the following
techniques:
a. Omit the release-level keyword (for example, R310) from the search
argument, thereby broadening the search to include similar failures on other
release levels.
b. Drop one keyword from the right end of the search argument string. The
diagnostic procedures directed you to construct the keyword string with the
most significant keywords listed first. By dropping a keyword from the right,
you eliminate the least significant keyword, thereby broadening your search
while maintaining the relevancy of your search argument string. Perform
the search against the software support database, using your shortened
search argument string. Repeat this step as necessary.
7. If a match is not found using the preceding techniques, go to Chapter 12,
Preparing an APAR on page 30.

26

Copyright IBM Corp. 1991, 2002

Chapter 11. Problem identification worksheet

Record the keywords associated with your software problem as you identify them.
Component Identification:

_________________________

Release Level:

_________________________

Type of Failure:

_________________________

Module:

_________________________

System Type:

_________________________

Modifiers:

_________________________
_________________________
_________________________

Note: Some keywords might not be applicable to all problems.

Copyright IBM Corp. 1991, 2002

27

28

Enterprise PL/I Diagnosis Guide

Part 3. Reporting the problem

Chapter 12. Preparing an APAR
Opening a PMR . . . . . . . . . . .
Initiating an APAR . . . . . . . . . .
Materials to submit . . . . . . . .
Original source information .
PL/I compiler . . . . . . . . . .
Compile listing . . . . . . . . .
JCL listing . . . . . . . . . . .
Applied fixes . . . . . . . . . .

Copyright IBM Corp. 1991, 2002

. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . .

30
30
30
31
31
32
32
32
32

29

Chapter 12. Preparing an APAR

Before proceeding to prepare an APAR, make sure that:

You have followed the diagnosis procedure.

You have eliminated user errors as a source for the problem.

The keyword search was unsuccessful.
Open a Problem Management Record (PMR) when these steps have failed to
resolve your problem.

Opening a PMR
If you have IBMLink or some other connection to IBM databases, you can open a
PMR yourself; otherwise, you can call the IBM Support Center and request that
they open the PMR for you.
The PMR is used to document your problem and to record the work done on the
problem by members of the IBM Support Center or the IBM Change Team. After
analyzing the problem, the Support Center might recommend that an APAR be
initiated.

Initiating an APAR
In order to initiate an APAR, you need to complete the following steps.
1. Contact the IBM Support Center for assistance. Be prepared to supply the
following information:

Customer number and security code

PMR number

Operating system

Operating system release level

Current Enterprise PL/I maintenance level (PTF list and list of APAR fixes
applied)

Current Language Environment release level and PTF list

The various keyword strings used to search the software support database

Processor number (model and serial)
2. From the following list, you might be asked to include the applicable Enterprise
PL/I environmental information with your APAR:

Job control statements.

Compiler listings, including:

Source listing
Compiled listing
Storage map
Cross-reference listing

Use LIST, SOURCE, XREF, and other options pertinent to the problem.

30

Copyright IBM Corp. 1991, 2002


Machine-readable copy of the program causing the problem, including all

copy members required by the program.

A dump on tape, if available, or if the use of the DUMP option was
requested by an IBM representative.

The compiler on tape if requested by an IBM representative.

Hard copy of the job control language (JCL) procedure for unloading the
submitted machine-readable tape.

Any other data that can help in recreating the problem.
Any listings supplied must be from the Enterprise PL/I compilation version that
failed.

Materials to submit
Table 12 describes how to produce documentation required for submission with the
APAR. Additional requirements are explained after the table. Many of these
materials might already have been produced in their required format during the
formulation of the keyword string (see Diagnosis Procedure on page 14).
Table 12. Summary of requirements for submitting an APAR
Materials

When required

Original source or failing test case

Always

JCL

OS/390

PL/I compiler

Only when requested

Compile listing

Always

JCL listing

OS/390

Applied PTFs and fixes

Always, or specify no fixes applied

Note: If you supply machine-readable material on a tape reel, describe how you
created the tape.

Original source information

You must supply source information in one of the following forms:

Your original source in machine-readable format

A small test case that IBM can use to recreate the problem
Note: If you do not supply one of these forms, IBM programming service might
return your APAR, requesting that you supply source information.
If you send machine-readable source, submit the information on an unlabeled tape.
Along with the tape, send a hard copy listing of how you created the tape.
Carefully pack and clearly identify machine-readable information. Make sure the
APAR number is on the tape, so that IBM can identify it if it is separated from the
rest of the material you submit with the APAR.
Depending on the options and conditions you have, the source of machine-readable
code differs. These sources appear in Table 13 on page 32. Also, the
machine-readable source should have no %NOPRINT statements, unless they
relate to the problem.

Chapter 12. Preparing an APAR

31

Table 13. Machine-readable sources

Options and
conditions

Machine-readable source

NOINCLUDE
NOMACRO

The source is the data set assigned to SYSIN for the

compile step.

INCLUDE
MACRO
Preprocessor failure

The source is the data set assigned to SYSIN for the

compile step and the source statement library or libraries
referred to by %INCLUDE statements in the program.

INCLUDE
MACRO

The source is the SYSPUNCH data set the compiler

produces when the MDECK compile-time option is in effect.

PL/I compiler
You do not need to send this unless IBM specifically asks you for it. IBM
programming service needs it only if they cannot recreate your problem using
programming service's own compiler.

Compile listing
If you think you have a compiler failure, all listings that you supply must relate to a
specific run of the compiler. Do not send information that is derived from separate
compilations or runs. These can mislead the programming support personnel at
IBM.
With your APAR, always send the listing which results from the compilation of the
original source. Compile the program with the compile-time options listed in
Table 3 on page 4 unless you must use the opposite option to show the failure or
unless the option masks the failure.

JCL listing
In OS/390, you must provide listings of job control statements that you use to run
the program. If you have problems with a batch job, show any cataloged
procedures you use in expanded form by specifying MSGLEVEL=(1,1) in the JOB
statement.

Applied fixes
Also supply with your APAR a list of any program temporary fixes (PTFs) and local
fixes you applied to either the compiler or the library. If you applied no fixes,
indicate this specifically with your APAR.

32

Enterprise PL/I Diagnosis Guide

Notices
This information was developed for products and
services offered in the U.S.A. IBM may not offer the
products, services, or features discussed in this
document in other countries. Consult your local IBM
representative for information on the products and
services currently available in your area. Any reference
to an IBM product, program, or service is not intended
to state or imply that only that IBM product, program, or
service may be used. Any functionally equivalent
product, program, or service that does not infringe any
IBM intellectual property right may be used instead.
However, it is the user s responsibility to evaluate and
verify the operation of any non-IBM product, program,
or service.
IBM may have patents or pending patent applications
covering subject matter described in this document.
The furnishing of this document does not give you any
license to these patents. You can send license
inquiries, in writing, to:
IBM Corporation
J74/G4
555 Bailey Avenue
San Jose, CA 95141-1099
U.S.A.
For license inquiries regarding double-byte (DBCS)
information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing,
to:
IBM World Trade Asia Corporation

Copyright IBM Corp. 1991, 2002

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United
Kingdom or any other country where such provisions
are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVID

PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITH
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR
FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this
statement may not apply to you.
This information could include technical inaccuracies or
typographical errors.
Changes are periodically made to the information
herein; these changes will be incorporated in new
editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or
the program(s) described in this publication at any time
without notice.
Any references in this publication to non-IBM Web sites
are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites.
The materials at those Web sites are not part of the
materials for this IBM product and use of those Web
sites is at your own risk.

33

Java and all Java-based trademarks are trademarks of

Sun Microsystems, Inc. in the United States and other
countries.

Trademarks
The following terms are trademarks of International
Business Machines Corporation in the United States, or
other countries, or both:
AIX
CICS
CICS/ESA
DB2
DFSMS
DFSORT
IBM
IMS
IMS/ESA

Language Environment
MVS
OpenEdition
OS/390
RACF
System/390
VisualAge
z/OS

Intel is a registered trademark of Intel Corporation in the

United States and other countries.

34

Enterprise PL/I Diagnosis Guide

Microsoft, Windows, and Windows NT are trademarks

of Microsoft Corporation in the United States and other
countries.
Pentium is a registered trademark of Intel Corporation in
the United States and other countries.
Unicode is a trademark of the Unicode Consortium.
UNIX is a registered trademark of The Open Group in
the United States and other countries.
Other company, product or service names may be the
trademarks or service marks of others.
If you are viewing this information in softcopy, the
photographs and color illustrations may not appear.

Bibliography
Enterprise PL/I publications
Programming Guide, SC27-1457
Language Reference, SC27-1460
Messages and Codes, SC27-1461
Diagnosis Guide, GC27-1459
Compiler and Run-Time Migration Guide,
GC27-1458

PL/I for MVS & VM

Installation and Customization under MVS,
SC26-3119
Language Reference, SC26-3114
Compile-Time Messages and Codes, SC26-3229
Diagnosis Guide, SC26-3149
Migration Guide, SC26-3118
Programming Guide, SC26-3113
Reference Summary, SX26-3821

Messages and Codes, GC26-9940

SQL Reference, SC26-9944

DFSORT
Application Programming Guide, SC33-4035
Installation and Customization, SC33-4034

IMS/ESA
Application Programming: Database Manager,
SC26-8015
Application Programming: Database Manager
Summary, SC26-8037
Application Programming: Design Guide,
SC26-8016
Application Programming: Transaction Manager,
SC26-8017

z/OS Language Environment

Concepts Guide, SA22-7567
Debugging Guide, GA22-7560
Run-Time Messages, SA22-7566
Customization, SA22-7564

Application Programming: Transaction Manager

Summary, SC26-8038
Application Programming: EXEC DL/I Commands
for CICS and IMS, SC26-8018
Application Programming: EXEC DL/I Commands
for CICS and IMS Summary, SC26-8036

Programming Guide, SA22-7561

Programming Reference, SA22-7562
Run-Time Migration Guide, GA22-7565
Writing Interlanguage Communication Applications,
SA22-7563

z/OS MVS
JCL Reference, SA22-7597
JCL User's Guide, SA22-7598
System Commands, SA22-7627

CICS Transaction Server

Application Programming Guide, SC33-1687
Application Programming Reference, SC33-1688
Customization Guide, SC33-1683
External Interfaces Guide, SC33-1944

z/OS UNIX System Services

UNIX System Services Command Reference,
SA22-7802
UNIX System Services Programming: Assembler
Callable Services Reference, SA22-7803
UNIX System Services User's Guide, SA22-7801

DB2 UDB for OS/390 and z/OS

Administration Guide, SC26-9931

z/OS TSO/E

An Introduction to DB2 for OS/390, SC26-9937

Command Reference, SA22-7782

Application Programming and SQL Guide,

SC26-9933

User's Guide, SA22-7794

Command Reference, SC26-9934

Copyright IBM Corp. 1991, 2002

35

z/Architecture
Principles of Operation, SA22-7832

Unicode and character

representation
OS/390 Support for Unicode: Using Conversion
Services, SC33-7050

36

Enterprise PL/I Diagnosis Guide

Index
A

abnormal termination, procedure for 19

APAR (Authorized Program Analysis Report)
See Authorized Program Analysis Report (APAR)
applied fixes 32
Authorized Program Analysis Report (APAR)
initiating 30
materials to submit
applied fixes 32
compile listing 32
JCL listing 32
original source information 31
PL/I compiler 32
summary of 31
preparing 30

IBM prefix 19
INCORROUT keyword

C
compile listing 32
compile-time
function 2
options
used to determine problems 4
overview 2
problem determination chart 6
problem determination index 6
compiler
function 2
options
used to determine problems 4
overview 2
problem determination chart 6
problem determination index 6
compiling
definition of 3
PL/I program 3
compiling stage 4
component identification keyword 16

J
JCL listing

32

K
keyword
component identification 16
modifier 25
module 23
release-level 17
system-type 24
type-of-failure 18
keyword string
definition of 12
using to search for corrections
keyword usage 13

26

L
Language Environment library
link-editing, PL/I program 4
LOOP keyword 20

vi

M
message problems, procedure for
modifier keyword
description of 25
incorrect output 21
output error location 21
module keyword 23
MSGx keyword 19

19

N
no compiler response, procedure for

D
diagnosis keywords
definition of 12
introduction to 12
diagnosis procedure 14
DOC keyword 20
documentation problems, procedure for

E
Enterprise PL/I library

21

vi

Copyright IBM Corp. 1991, 2002

20

O
original source information 31
output problems, procedure for 21
20

P
PERFM keyword 22
performance problems, procedure for
PL/I compiler 32

22

37

PL/I failures
abnormal termination 19
documentation problems 20
message problems 19
no compiler response 20
output problems 21
performance problems 22
table of 18
PL/I program
compiling 3
link-editing 4
processing 2
running 4
PMR (Problem Management Record)
See Problem Management Record (PMR)
preprocessing stage 3
problem determination chart 6
problem determination index 6
problem identification worksheet
example of 27
using 14
Problem Management Record (PMR), opening
processing, PL/I program 2

30

R
release-level keyword 17
running, PL/I program 4

S
search for corrections, using the keyword string
service tapes 16
submitting APAR materials 31
system-type keyword 24

T
type-of-failure keyword
description of 18
DOC 20
INCORROUT 21
LOOP 20
MSGx 19
PERFM 22

W
worksheet, problem identification
example of 27
using 14

38

Enterprise PL/I Diagnosis Guide

26

We'd Like to Hear from You

Enterprise PL/I for z/OS and OS/390
Diagnosis Guide
Version 3 Release 2.0
Publication No. GC27-1459-01
Please use one of the following ways to send us your comments about this book:

MailUse the Readers' Comments form on the next page. If you are sending the form
from a country other than the United States, give it to your local IBM branch office or
IBM representative for mailing.

FaxUse the Readers' Comments form on the next page and fax it to this U.S. number:
800-426-7773.

Electronic mailUse one of the following network IDs:
Internet: [email protected]
Be sure to include the following with your comments:
Title and publication number of this book
Your name, address, and telephone number if you would like a reply
Your comments should pertain only to the information in this book and the way the
information is presented. To request additional publications, or to comment on other IBM
information or the function of IBM products, please give your comments to your IBM
representative or to your IBM authorized remarketer.
IBM may use or distribute your comments without obligation.

Readers' Comments
Enterprise PL/I for z/OS and OS/390
Diagnosis Guide
Version 3 Release 2.0
Publication No. GC27-1459-01
How satisfied are you with the information in this book?

Technically accurate
Complete
Easy to find
Easy to understand
Well organized
Applicable to your tasks
Grammatically correct and consistent
Graphically well designed
Overall satisfaction

Very
Satisfied

Satisfied

Neutral

Dissatisfied

Very
Dissatisfied



















































May we contact you to discuss your comments? Yes No

Would you like to receive our response by E-Mail?

Your E-mail address

Name

Company or Organization

Phone No.

Address

Readers' Comments
GC27-1459-01

IBM

Fold and Tape

Please do not staple

Cut or Fold
Along Line

Fold and Tape

NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES

BUSINESS REPLY MAIL

FIRST-CLASS MAIL

PERMIT NO. 40

ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

IBM Corporation
Department HHX/H3
555 Bailey Ave
San Jose, CA 95141-1099

Fold and Tape

GC27-1459-01

Please do not staple

Fold and Tape

Cut or Fold
Along Line

IBM

Program Number: 5655-H31

Printed in the United States of America
on recycled paper containing 10%
recovered post-consumer fiber.

Enterprise PL/I for z/OS and OS/390 Library

SC27-1456
SC27-1457
GC27-1458
GC27-1459
SC27-1460
SC27-1461

GC27-1459-1

Licensed Program Specifications

Programming Guide
Compiler and Run-Time Migration Guide
Diagnosis Guide
Language Reference
Compile-Time Messages and Codes

Spine information:

IBM

Enterprise PL/I for z/OS and OS/390

Diagnosis Guide

Version 3 Release 2.0