Specifying type-of-failure keywords

The type-of-failure keyword identifies the type of program problem. The possibilities are:

ABENDx

Abnormal end of PSF. See Using ABENDx.

LOOP

Uncontrolled program looping. See Using LOOP.

WAIT

Unexpected program suspension. See Using WAIT.

MSGx

An error signaled by or associated with messages. See Using MSGx.

INCORROUT

Incorrect or missing output unrelated to a message. See Using INCORROUT.

PERFM

Performance degradation. Use this keyword only when no other keyword seems applicable. See Using PERFM.

DOC

Documentation problem. See Using DOC.

Select the keyword that best describes the problem. If you are not certain which of two keywords to use, use the one listed first in the list.

Using ABENDx

Use the ABENDx keyword when the host system, PSF, or any program that services PSF ends abnormally. If the abnormal end was forced by the host system or by the operator because of a prolonged wait state or an endless loop, do not use this keyword. In these situations, see the keyword descriptions of Using LOOP and Using WAIT.

To specify the ABENDx keyword:

1. Replace the x in the ABENDx keyword with the ABEND code (in a dump, the last 3 hexadecimal numerals in the system completion code). For example, if the system completion code is 0C4, use ABEND0C4. If the code is 024, 027, or 0A6 (0A6 applies to the Page Printer Communication Component, [PPCC]), indicating that PSF ended abnormally, add RC and the reason code: in a dump, the last 4 hexadecimal numerals in register 15 at the time of the error. Thus, if the system completion code is 024, and register 15 reads 000194, use ABEND024 RC0194.

   The format of the keyword string might now be:

   5655M3201 ABEND024 RC0194

   where the first keyword is the component ID number, the second is the type of error, and the third is the reason code.

2. Determine which module failed. See Specifying module keywords.

Using LOOP

If a PSF program suspends activity for no clear reason, PSF might be in either a loop or a wait state. An example of a loop is a page of output that repeats endlessly. Use the LOOP keyword if part of PSF seems to go into an endless loop. For an endlessly repeated message, first use the MSGx keyword to conduct the search (see Using MSGx). If no match is found, use the LOOP keyword. If an intentional loop is used to wait for a resource, use the WAIT keyword (see Using WAIT) rather than the LOOP keyword.

To determine whether PSF is in a loop:

1. Run the job again and request a storage dump. Whenever possible, the dump should contain the z/OS® system trace table and the PSF internal trace table (see TRACE parameter on the PRINTDEV statement). For details about how to include the PSF internal trace table, see Using the PSF diagnostic tools.
2. Check the dump for the z/OS system internal trace table, the PSF internal trace table, or both. If the trace tables are not contained in the dump and you are unable to determine whether the problem is a wait or a loop, but you can re-create the problem, do these:
   1. Start the PSF internal trace. See TRACE parameter on the PRINTDEV statement.
   2. Redefine the trace table size to be as large as feasible.

   For details, see Using the PSF diagnostic tools.

3. Run the job again and use the z/OS system DUMP command to request a dump, as described in the system commands publication for your operating system. Ensure that the SDATA operand of the command contains RGN (region). If the job is not in a loop, see Using WAIT.
4. Add the LOOP keyword to the string. The format of the keyword string might now be:

   5655M3201 LOOP

   where the first keyword is the component ID and the second specifies the type of problem.
5. Determine which module contains the problem. See Specifying module keywords.

Using WAIT

Use the WAIT keyword when the host system, PSF, or a program that services PSF suspends activity without issuing a message. Do not use this keyword if the wait occurs after an abnormal end, as the result of an unanswered message, or because of an endless loop in PSF; instead, use the ABEND or LOOP keywords (see Using ABENDx or Using LOOP).

To determine if PSF is in a wait state:

1. Use the z/OS system DUMP command to request a dump, as described in the system commands publication for your operating system. Ensure that the SDATA operand of the command contains RGN (region) and that the dump contains the z/OS system trace table and the PSF internal trace table (see TRACE parameter on the PRINTDEV statement). For details about how to include the PSF internal trace table, see Using the PSF diagnostic tools.
2. Inspect the dump to see whether the wait bit is on in the program status word (PSW).
3. If the wait bit is on in the PSW, add the WAIT keyword to the string. The format of the keyword string might now be:

   5655M3201 WAIT

4. Identify the module that contains the problem. See Specifying module keywords.

Using MSGx

Use the MSGx keyword when one of these happens:

• A message is issued when it should not have been.
• A message is not issued when it should have been.
• A message contains data that is not valid or missing data.
• The corrective action suggested in PSF for z/OS: Messages and Codes does not correct the problem.

A set of 7 or 8 characters in the form "APSnnns" or "APSnnnns" identifies each PSF message. APS identifies the component; nnn or nnnn identifies the message serial number; and s identifies the message type.

To specify the MSGx keyword:

1. Replace the x in the MSGx keyword with the message identifier. For example, if the message identifier is APS022I, the MSG keyword is:

   MSGAPS022I

2. Identify the module that detected the reason for the message. See Message-to-module cross-reference.
3. Add the module name to the keyword string. If more than one module can issue the message, you might be able to isolate the issuing module by comparing the message context with the module functions.

   For example, message APS120I indicates an input record or resource that is not valid, and both the message variables and the associated messages show the type of input or resource. This message can be issued by any of these modules: APRENVAZ, APRCS2AZ, APRCP2AZ, APRCF2AZ, and APRFDPAZ.

   Note:

   The module that issued the message is not necessarily the module that contains the problem.

   The format of the keyword string might now be:

   5655M3201 MSGAPS052I APSPPGDS

   Or, if the reason for the message can be detected by more than one module:

   5655M3201 MSGAPS120I APRENVAZ
   5655M3201 MSGAPS120I APRCS2AZ

4. Select the correct environment keyword. See Specifying environment and printer keywords.

Using INCORROUT

Use the INCORROUT keyword when the output is not received or is not what you expected. Do not use this keyword for output that is repeated endlessly; instead, use the LOOP keyword (see Using LOOP).

To specify the INCORROUT keyword:

1. Ensure that the output is really incorrect, not just undesirable in appearance.
2. Add the INCORROUT keyword to the string. The format of the keyword string might now be:

   5655M3201 INCORROUT

3. Use modifier keywords, in the following order, to describe the incorrect output:
   1. Select one modifier keyword from Table 1 to describe the document in which the incorrect output occurred.

      Table 1. Modifier keywords: Description of document

      Modifier Keyword	Document
      LINE	The document consisted of one or more line format pages, optionally including structured fields.
      COMPOSED	The document consisted of one or more composed-text pages, such as the output from DCF or OGL. XML input produces composed-text pages.
      MIXED	The document consisted of both line-format and composed-text pages.

   2. Select one or more modifier keywords from Table 2 to describe the part that is incorrect. For example, if the incorrect output involves a page segment in an overlay, specify OVERLAY SEGMENT.

      Table 2. Modifier keywords: Description of incorrect part

      Modifier Keyword	Incorrect Part
      BIN	You did not get the bin number you specified.
      DBLFONT	You did not get the double-byte font you specified.
      DOCUMENT	You did not get the document as you specified it.
      DUPLEX	You did not get the simplex or duplex printing you specified.
      EXIT	You did not get the user exits you requested.
      SNGLFONT	You did not get the single-byte font you specified.
      GROUP	You did not get the correct number of identical copies of a form.
      IMAGE	You did not get the image you specified, the image was not in the orientation or position you specified, a scaling (double dot) error occurred, or the image was not repeated correctly.
      MARGIN	The side, top, or bottom margin is not what you specified.
      MOD	Data was not correctly added to or suppressed in selected copies of certain pages of the data set.
      OVERLAY	You did not get the electronic overlay you specified, the overlay was not in the orientation or position you specified, or part of the overlay (to be described by using one or more additional keywords) was wrong.
      PAGE	You did not get the page as you specified it.
      RULE	The position, direction, length, or weight of one or more rules is not what you specified.
      SEGMENT	You did not get the page segment you specified, or you did not get the orientation or position you specified.
      TEXT	The content, position, line spacing, or orientation of the text is not what you specified.

   3. Select one or more modifier keywords from Table 3 to describe what is wrong with the incorrect part.

      Table 3. Modifier keywords: Description of how the part is incorrect

      Modifier Keyword	How Part is Incorrect
      CONTENT	The content of the part was wrong.
      DIRECTION	The rule direction was wrong.
      EXTRA	An extra part was included in the output.
      LENGTH	The rule length was wrong.
      LINESPACE	The line spacing for a document, a page, or a text string was wrong.
      MISSING	The part was missing from the output.
      ORIENT	The orientation of the part was wrong.
      POSITION	The position of the part was wrong.
      REPEAT	The repetition of text or image cells was wrong.
      SCALE	A scaling (double dot) error in an image occurred.
      SIZE	The size of the part was wrong.
      WEIGHT	The rule weight was wrong.

   The format of the keyword string that describes the case of extra, identical copies of one or more sheets of data would be:

   5655M3201 INCORROUT LINE GROUP EXTRA

4. Narrow the search if you want by defining the incorrect output more precisely. These are a few examples of INCORROUT strings:
   • In a composed-text page, the text in an included page segment was not in the expected orientation:

     5655M3201 INCORROUT COMPOSED SEGMENT TEXT ORIENT

   • On a line data page, an image specified as double-dot was printed in the normal size:

     5655M3201 INCORROUT LINE IMAGE SCALE

   • On a line data page, an overlay that was specified was not printed:

     5655M3201 INCORROUT LINE OVERLAY MISSING

5. Select the correct environment keyword. See Specifying environment and printer keywords.

Using PERFM

Use the PERFM keyword when part of PSF performs below your expectations and the performance problem cannot be corrected by system tuning. Use this keyword only when no other keyword seems applicable. Ensure that the application programs, the JCL, and the data set definitions have been thoroughly examined.

The speed with which a job is processed can be affected by the number and complexity of the resources used. Also, if you are running a 3800 printer under compatibility mode and then switch to all-points-addressable (APA) mode, you might note a difference in performance. This difference is not necessarily caused by a performance problem.

To specify the PERFM keyword:

1. Add the PERFM keyword to the string. The format of the keyword string might now be:

   5655M3201 PERFM

2. Select the correct environment keyword. See Specifying environment and printer keywords.

Using DOC

Use the DOC keyword when a programming problem seems to have been caused because information in a PSF publication is vague, incorrect, or missing.

To specify the DOC keyword:

1. After the DOC keyword, skip one space and add the order number of the publication. Do not use hyphens; that is, rather than G550-0428-04, type G550042803. The format of the keyword string might now be:

   5655M3201 DOC G550042803

2. If you find too many matches, add keywords unique to the documentation error you suspect. For example, add MSGx as a keyword if you are looking for a particular message because you suspect its contents are incorrect or unclear, or because it is not documented in PSF for z/OS: Messages and Codes.
3. If the search is unsuccessful, replace the suffix numerals in the order number ("01" in Step 1) with two asterisks, and search again. By including the asterisks, you are requesting a search for document errors in all the editions of a publication.