System z Platform Test

Error injector tool

INJERROR:  A tool to inject errors into coupling facility structures

To help in testing recovery from coupling facility problems, we are making available our coupling facility structure error injector tool, INJERROR. The INJERROR tool injects an error into a CF structure to simulate damage to the structure. If there are two instances of a structure allocated (for instance, during a rebuild or when the structure is in the duplex-established phase), the tool allows you to specify which instance(s) of the structure you want to affect. (See z/OS MVS Programming: Sysplex Services Guide (SA22-7617) for more information about coupling facility structures.) Note that this tool only works with genuine IBM coupling facilities and not with OEM coupling facilities.

Attention:  This tool should only be used on test systems. Although the tool provides a way to simulate a coupling facility structure failure, the element that owns the structure (for example, IRLM or JES2) cannot distinguish the simulated error from a real error and, thus, reacts to the simulation as though it is an actual failure. This may not be desirable in a production environment.

 

Note:  This tool is provided on an  as is basis only. Service support for this tool should not be assumed and none is implied. However, you may use the Contact link to the left to provide us with feedback.

Obtaining and installing the INJERROR tool

This tool consists of one MVS load module named INJERROR, which must be included in an APF-authorized library in the LNKLST xx concatenation. We supply the tool here as a sample linkage editor job with the object code imbedded as instream data.

Steps to obtain and install the INJERROR tool

  1. Click here to download the sample job (BIN, 12KB) and follow your Web browser's instructions to save the binary file on your workstation.
  2. Use a binary file transfer utility (such as FTP) to place the job in a PDS member on your z/OS system.
  3. Edit the member and modify the JOB and SYSLMOD DD statements as appropriate for your system.
  4. Execute the job to create the INJERROR load module.
 

Using the INJERROR tool

We've found that the easiest way to use this tool is to invoke it as a started task procedure.

Creating the INJERROR startup procedure
Create a new proclib member named INJERROR containing the following JCL statements:

//PILOT    PROC STRNAME=IEFAUTOS
//         EXEC PGM=INJERROR,PARM='&STRNAME'

The latest version of INJERROR also supports specification of the SYSPRINT DD JCL statement in the startup procedure. The SYSPRINT DD statement allows you to direct the output messages from the INJERROR tool. If you do not specify a SYSPRINT DD statement, output messages are issued to the console as WTO messages, as in prior versions of the tool. Also, the "INJERROR: PROCESSING COMPLETE" message is only issued to the console as a WTO message; it is not issued to SYSPRINT.

Note:  The INJERROR tool automatically forces the size of the output to LRECL=132, BLKSIZE=132. Therefore, if you specify a SYSPRINT data set that has a BLKSIZE other than 132, executing the tool will force the BLKSIZE to be 132.

Example:  The following sample procedure directs SYSPRINT output to a data set:

//PILOT    PROC STRNAME=IEFAUTOS
//         EXEC PGM=INJERROR,PARM='&STRNAME'
//SYSPRINT DD   DSN=INJERROR.OUTPUT,UNIT=uuuu,VOL=SER=vvvvvv,DISP=SHR

Example:  The following sample procedure directs SYSPRINT output to SYSOUT:

//PILOT    PROC STRNAME=IEFAUTOS
//         EXEC PGM=INJERROR,PARM='&STRNAME'
//SYSPRINT DD   SYSOUT=x

Invoking the INJERROR startup procedure
To invoke the INJERROR tool, issue the MVS START command using the following syntax:

START INJERROR,PARM='strname[,xxx]'

where:

strname
      specifies the name of the CF structure into which you want to inject an error
 

xxx
      specifies which instance of a CF structure to affect (only applies to structures that have more than one active instance), as follows: OLD inject an error into the old instance of the structure NEWinject an error into the new instance of the structure BOTHinject an error into both instances of the structure
If neither OLD, NEW, nor BOTH is specified for a structure that has multiple active instances, then, by default, the tool injects an error into the old instance.
 

Be sure to include the quotes around the parameter list as shown above.

 

INJERROR messages

The INJERROR tool displays messages to indicate its release level and processing status.

Example:  The tool displays the following messages when you specify a CF structure that has only one active instance and you do not specify the xxx parameter:

*INJERROR: PROCESSING STARTED - VERSION 3.5 - 08/09/11
*INJERROR: INPUT RECEIVED - STR=strname,STRTYPE=N/A
*INJERROR: STR FAILURE INITIATED AGAINST STR=strname,STRTYPE=N/A
*INJERROR: PROCESSING COMPLETE

Example:  The tool displays the following messages when you specify a CF structure that has multiple active instances and you specify OLD or NEW for the xxx parameter:

*INJERROR: PROCESSING STARTED - VERSION 3.5 - 08/09/11
*INJERROR: INPUT RECEIVED - STR=strname, STRTYPE=xxx
*INJERROR: STR FAILURE INITIATED AGAINST STR=strname, STRTYPE=xxx
*INJERROR: PROCESSING COMPLETE

Example:  If you specify the OLD or NEW parameter but the structure has only one active instance, the tool displays the following message:

*INJERROR: STR NOT IN REBUILD BUT OLD,NEW OR BOTH SPECIFIED

Message reference
The following is the complete list of messages that INJERROR can issue. (Note that some messages contain text or formatting that differs slightly from earlier versions the tool.)


INJERROR: PROCESSING STARTED - VERSION n.n - mm/dd/yy
      Indicates that INJERROR processing has begun and gives the version and date of the executing module. The latest version of INJERROR is 3.5.
 


INJERROR: INPUT RECEIVED - STR= strname, STRTYPE= xxx
      Echoes the parameters that were specified when INJERROR was invoked.
 


INJERROR: STRTYPE INDICATES WHICH INSTANCE OF THE STRUCTURE TO FAIL DURING THE REBUILD PROCESS
      This is an informational message to describe the function of the STRTYPE parameter.
 


INJERROR: STR NOT IN REBUILD BUT OLD,NEW OR BOTH SPECIFIED
      Indicates that the user specified a particular CF structure instance (STRTYPE= xxx) to fail, but the specified CF structure is not currently in a rebuild state.
 


INJERROR: A STRNAME MUST BE SPECIFIED
      Indicates a syntax error in the specification of the CF structure name; the name of the CF structure has been omitted (for example: S INJERROR,STRNAME= ). Specify a valid CF structure name for the STRNAME= parameter.
 


INJERROR: STR NOT FOUND
      Indicates that the specified CF structure could not be found. Verify that the correct CF structure name was specified for the STRNAME= parameter.
 


INJERROR: IXLMG RC= xxxxxxxx RSN= xxxxxxxx
      Indicates the actual return code (RC) and reason code (RSN) from the IXLMG service. The codes are given in hexadecimal format. INJERROR uses the IXLMG service to gather information about the specified CF structure. If the IXLMG service returns a warning or error, this message indicates the return code and reason code.
 


INJERROR: IXLMG FAILED WITH A SEVERE ERROR
      Accompanies the previous message about a failure in the IXLMG service when the return code or reason code is not one that INJERROR recognizes.
 


INJERROR: STR strname DOES NOT EXIST
      Accompanies the message about a failure in the IXLMG service when the specified CF structure is not allocated in a coupling facility within the sysplex.
 


INJERROR: SPECIFIED STRUCTURE NAME DOES NOT EXIST
      Accompanies the message about a failure in the IXLMG service when the specified CF structure is not allocated in a coupling facility within the sysplex.
 


INJERROR: SPECIFIED STRUCTURE IS ALREADY FAILED
      Indicates that the specified CF structure into which an error is to be injected is already in a failed state.
 


INJERROR: STR FAILURE INITIATED AGAINST STR= strname, STRTYPE=N/A
      Indicates that INJERROR processing has begun for the specified CF structure, which has only one active instance. In this case, STRTYPE is not applicable (N/A).
 


INJERROR: STR FAILURE INITIATED AGAINST STR= strname, STRTYPE= xxx
      Indicates that INJERROR processing has begun for the specified CF structure, which has more than one active instance. The value of STRTYPE can be NEW or OLD.
 


INJERROR: STR FAILURE INITIATED FOR STR= strname-BOTH
      Indicates that INJERROR processing has begun for both active instances of the specified CF structure.
 


INJERROR: PROCESSING COMPLETE
      Indicates that INJERROR processing has successfully completed. Note that this message is always issued to the console, even if the INJERROR procedure directs SYSPRINT output elsewhere.