OA67164: NEW FUNCTION - SLIP TEND Monitoring

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• New Function
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * Users at HBB77D0 and HBB77E0 only                            *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * New Function: SLIP TEND detection                            *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  IBM has announced the elimination of transactional execution
  facilities from future processors.
  Clients and vendors need to identify the use of transactional
  memory instructions, to help focus efforts for
  removal/replacement of such transactional usage.
  Keyword CTXREMOVAL/K E9175/K
  

Problem conclusion

Temporary fix

Comments

• This support adds a run-time migration solution that will allow
  clients and vendors to identify the use of transactional
  execution instructions.
  The solution involves setting a SLIP trap on PER events for
  transaction execution completion (TEND) instructions. The SLIP
  action invokes a program that gathers run-time information
  about what is issuing the TEND instructions, and a usage report
  details the usage of transactional execution. This is similar
  to what was done for Zero Address Detection (ZAD).
  
  Documentation changes for APAR OA67164
  The following messages will now include the indicated inserts.
  
  z/OS MVS System Messages, Vol 7 (IEB-IEE) SA38-0674-60
  Topic: IEE Messages
  Subtopic: IEE735I
    IEE735I hh.mm.ss. SLIP DISPLAY idr text
                           . . .
    In the first line of the message text:
                           . . .
    type
      The type of SLIP trap:
                           . . .
      PER-SAS
      PER storage alteration by STORA (SAS) trap.
  |   PER-TEND
  |   PER transaction execution completion (TEND) trap.
                           . . .
  Subtopic: IEE836D
  IEE836D SLIP {ID=xxxx|COMMAND} ERROR - keywd - err , COL nnn.
  ENTER 1 KEYWORD, NULL LINE, OR CANCEL.
                    . . .
     err
     A description of the error.
     Is one of the following:
                    . . .
     KEYWORDS MUTUALLY EXCL
  |  INVALID WITH TEND
     INVALID WITH ZAD
  
  The following publication will be updated as follows to add or
  change the flagged information in the indicated existing
  topics-
  
  z/OS MVS System Commands (SA38-0666-60)
  
  Subtopic: SLIP command
  Subtopic: Syntax
                          . . .
  
  
  |  SLIP SET,TEND[,options],END Command for a Transaction End
  |    detection PER trap
     SLIP SET,ZAD[,options],END Command for ...
                          . . .
  
  | If you specify IF, SBT, SA, SAS, SK, TEND,
      or ZAD, it must immediately follow SET.
  
  Subtopic: SLIP command
  Subtopic: Setting a SLIP trap
  Subtopic: Setting effective SLIP PER traps
  | - SLIP Transaction End Detection (TEND)
    - SLIP zero address detection (ZAD)
  
  **New Subtopic: SLIP Transaction End Detection (TEND)
  | A Transaction End (TEND) event is a PER program interrupt
  | caused by execution of the TEND instruction that represents
  | the end of a constrained transaction (begun with the TBEGINC
  | instruction) or a non-constrained transaction (begun with the
  | TBEGIN instruction) when the PSW PER bit is on and
  | Transaction End detection is enabled. You enable Transaction
  | End detection by a SLIP PER trap of type TEND. A TEND trap
  | can help to detect uses of TBEGINC (and TBEGIN) so that you
  | can mitigate those uses in preparation for the removal of
  | the constrained transaction facility. All instruction ranges
  | are monitored for TEND events.
  |
  | It is in the best interest of the installation to limit TEND
  | events monitored to specific address spaces and jobs for
  | which PER is active. To minimize performance impacts, avoid
  | unnecessary matching of the TEND trap. Limit the address
  | spaces and jobs that SLIP monitors by using the
  | ASID and JOBNAME keywords.
  |
  | You can limit the TEND events that match your SLIP
  | traps by using other SLIP filtering keywords. You can use
  | this functionality on all machines that support the
  | transaction execution facility. This functionality will not
  | be available on machines that will not support the
  | transaction execution facility.
  |
  | A TEND trap must be used with caution. Due to normal system
  | processing, many expected TEND events in IBM modules will
  | occur. These represent instances that will be mitigated in
  | the future. They do not represent problems and are not
  | defects.  Due to these expected TEND events, there can be
  | noticeable system overhead when using a generalized TEND
  | trap. For this reason, you might choose to use a TEND trap on
  | a test system rather than a production system, assuming that
  | the test system can tolerate the higher system overhead from
  | a SLIP PER trap.
  |
  | To reduce the number of items reported upon, use filtering
  | keywords with a TEND trap. Filtering does not avoid the PER
  | interrupt due to the TEND instruction. Performance of the
  | system can be negatively impacted due to the PER interrupt
  | processing.
  |
  | The following methods use filtering:
  |
  | Limit the address range of the instruction that causes the
  | TEND interrupt, by using the ADDRESS, NUCMOD, LPAMOD/LPAEP or
  | PVTMOD/PVTEP keywords.
  |
  | Limit the address ranges by using IGNORE TEND traps that
  | specify the ADDRESS keyword, so that matches occur only
  | within your modules. For example, if you have two address
  | ranges to monitor for TEND events you could use IGNORE TEND
  | traps to filter out everything else.
  |
  | As a specific example, to monitor addresses 10000000-20000000
  | and 30000000-40000000, you could set IGNORE TEND traps for
  | addresses 0-FFFFFFF, 20000001-2FFFFFFF and 40000001-7FFFFFFF.
  | The non-IGNORE trap only matches if the event occurs outside
  | of the three IGNORE ranges, which in turn is within the two
  | ranges that you are focusing on.
  |
  | Note: When setting IGNORE traps, you must follow the
  | documented protocol for setting them after setting the
  | non-IGNORE trap, and enable the non-IGNORE trap only after
  | the IGNORE traps are enabled.
  |
  | Use other filtering keywords, such as DATA, when appropriate.
  |
  | Many of the IBM uses of TEND are within the nucleus. You
  | could set an IGNORE TEND trap that specifies NUCMOD=* to
  | filter a match on any TEND that occurs within the nucleus.
  |
  | The following user actions are common responses to a TEND
  | slip trap match. Ensure that your filtering keywords only
  | match events within your product code.
  |   1. Collecting data and getting a report of all TEND events
  |   2. Taking an SVC Dump or
  |   3. creating a GTF record upon a specific TEND event if the
  |      report could not identify the module
  |
  | Even a properly limited trap can still collect many TEND
  | events. As with any PER trap, the PRCNTLIM keyword limits the
  | amount of system processing that the trap can use. If that
  | amount is exceeded, SLIP automatically disables the trap. If
  | using the default or a lower PRCNTLIM value resulted in SLIP
  | automatically disabling the trap, and your system can
  | tolerate the additional overhead, you can try a higher
  | PRCNTLIM value.  If the SLIP still automatically disables the
  | trap, then you cannot use a SLIP TEND trap to collect that
  | particular event on that system.
  |
  | When testing, look for TEND events only within your own
  | product code. If you see a TEND event that is outside of your
  | product code, it should not be considered an error and thus,
  | you should not report it, unless the owning product has
  | identified that it expects there to be no such events with
  | that products code.
  |
  | If your product code only runs in a limited set of address
  | spaces or jobs, you can limit the address spaces or jobs in
  | which PER events can occur.
  |
  | To collect data and get a report of the TEND events, complete
  | the following steps:
  |
  | 1. Set up a procedure named IEAVTSZR, as shown in Figure 1
  |    [in the Zero Address Detection section of this
  |    publication].
  |
  | 2. START IEAVTSZR, which initializes an area to record the
  |    information.
  |
  | 3. Run SETPROG LPA,ADD,DSN=SYS1.LINKLIB,MOD=IEAVTSZE,FIXED.
  |    Alternatively, you could use the FIX system parameter
  |    with an IEAFIXxx parmlib member to complete this step
  |    during IPL.
  |
  | 4. Issue a SLIP system command similar to the following,
  |    which sets a SLIP trap named TEN1: SLIP SET,TEND,A=AEXIT,
  |    AEXIT=IEAVTSZE,ID=TEN1,PL=50,JOBNAME=TENDJOB*,OK,END.
  |    Although A=AEXIT and the AEXIT keyword are not otherwise
  |    documented this specific use is permitted. You can change
  |    the PL value, use a different ID and add other SLIP
  |    filtering or limiting keywords prior to END, when setting
  |    the SLIP trap.
  |
  | 5. Run your programs.
  |
  | 6. Run START IEAVTSZR. In this instance, the command writes
  |    a report for all TEND events to SYSPRINT, and then resets
  |    to continue.
  |
  | 7. If necessary, run additional iterations of the running
  |    programs and the START IEAVTSZR command.
  |
  | 8. Run START IEAVTSZR,OP=FREE. You can skip this step if you
  |    are doing an IPL.
  |
  | To the extent possible, the report identifies where the event
  | occurred (by address and by module name, if available), how
  | many times the event occurred, and the instruction that was
  | issued. This facilitates locating the particular module and
  | instance.
  |
  | You can add further modifiers to your SLIP trap to avoid
  | reporting additional events or to identify particular events
  | upon which to report, using LPAMOD, NUCMOD, ASID and ADDRESS,
  | for example. The TEND events will still occur but SLIP
  | filtering will apply and only a matching event will be shown
  | in the report.
  
  Subtopic: SLIP command
  Subtopic: Setting a SLIP trap
  Subtopic: Structure of a SLIP SET command
  
  | A Transaction End detection trap set by this command:
  | SLIP SET,TEND[,options],END
    A zero address detection trap set by this command:
    SLIP SET,ZAD[,options],END
  
  Subtopic: Types of SLIP SET parameters
                                     . . .
    Event parameters: Indicate the event to be monitored and
  | trapped.               SA         SBT         TEND  ZAD
                                            . . .
  **New Subtopic: Syntax for a Transaction End detection
  | SLIP SET PER command
  | Use the SLIP SET,TEND command to set a PER Transaction End
  | detection trap. For additional details, see SLIP Transaction
  | End detection (TEND).
  |
  | The following considerations apply:
  |
  | - Only one PER trap with an action other than IGNORE can be
  |   eligible for checking at any one time.
  |
  | - If you specify only one value in the ACTION parameter, you
  |   do not need to enclose it in parentheses.
  |
  | There is no need to report to IBM service personnel the
  | SLIP TEND events that occur within IBM code. They are to
  | be treated as expected and valid.
  |
  | SLIP SET,TEND
  |    [,ADDRESS=(start[,end]) ]
  |    |,LPAEP=(name[,start[,end]])
  |    |,LPAMOD=(name[,start[,end]])
  |    |,NUCEP=(name[,start[,end]])
  |    |,NUCMOD=(name[,start[,end]])
  |    |,PVTEP=(name[,start[,end]])
  |    |,PVTMOD=(name[,start[,end]])
  |    [,ASID=(asid[,asid]...)]
  |    [,DATA=(comparison[,comparison]...)]
  |    [,JOBNAME={userid | jobname}]
  |    [,JSPGM=name]
  |    [,MODE= (mode[,mode]...[,ANY | EVERY])]
  |    [,PSWASC=(mode[,mode]...)]
  |    [,ACTION=
  |        [(IGNORE[,RECOVERY])]                    ]
  |         [(RECOVERY[,STOPGTF])[,options]         ]
  |         [(STDUMP[,STOPGTF])[,options]           ]
  |         [(STOPGTF)[,options]                    ]
  |         [(STRACE[,STOPGTF])[,options]           ]
  |         [(SVCD [,STOPGTF])[,options]  ]
  |         [(SYNCSVCD[,STOPGTF])[,options]         ]
  |         [(TRACE[,STOPGTF])[,options] ]
  |         [(TRDUMP[,STOPGTF])[,options]]
  |         [(WAIT[,STOPGTF])[,options]  ]
  |         [(CMD[,STOPGTF])[,options]   ]
  |     [,ENABLE | ,DISABLE]
  |     [,IDGROUP=idgroup]
  |     [,MATCHLIM=m
  |      |,MATCHLIM=1     for ACTION=SVCD or ACTION=SYNCSVCD
  |      |,MATCHLIM=50    for ACTION=STDUMP or ACTION=STRACE ]
  |     [,PRCNTLIM=p | ,PRCNTLIM=10]
  |     [,DEBUG]
  |     [,ID=trapid]
  |     [,OK]
  |    ,END
  
  Subtopic: SLIP SET parameters
    ACTION=IGNORE
                                                . . .
    For PER traps, the IGNORE trap must be the same type (IF, SA,
  | SAS, SBT, SK, TEND or ZAD) as the more general trap
                            . . .
    ACTION=STDUMP
                            . . .
    * The following parameters require less SLIP processing to
  | find a matching trap for an SA, SAS, SK, TEND or ZAD trap:
  
    ACTION=STRACE
    When the trap matches for a PER event, writes at least one
    SLIP system trace record.
                                                . . .
    * The following parameters require less SLIP processing to
  | find a matching trap for an SA, SAS, SK, TEND or ZAD trap:
  
                             . . .
    LPAEP=name
                             . . .
  | For a TEND PER trap, LPAEP indicates that the transaction
  | execution end must be caused by an instruction within the
  | specified range.
    For a ZAD PER trap, LPAEP indicates that the zero address
    detection must be caused by an instruction within the
    specified range.
  
    LPAMOD=name
                         . . .
  | For a TEND PER trap, LPAMOD indicates that the transaction
  | execution end must be caused by an instruction within the
  | specified range.
    For a ZAD PER trap, LPAMOD indicates that the zero address
    detection must be caused by an instruction within the
    specified range.
  
    NUCEP=name
                         . . .
  | For a TEND PER trap, NUCMOD or NUCEP indicates that the
  | transaction execution end must be caused by an instruction
  | within the specified range.
    For a ZAD PER trap, NUCMOD or NUCEP indicates that the zero
    address detection must be caused by an instruction within
    the specified range.
  
    PVTEP=name
                         . . .
  | For a TEND PER trap, PVTEP indicates that the transaction
  | execution end must be caused by an instruction within the
  | specified range.
    For a ZAD PER trap, PVTEP indicates that the zero address
    detection must be caused by an instruction within the
    specified range.
  
    PVTMOD=name
                         . . .
  | For a TEND PER trap, PVTMOD indicates that the transaction
  | execution end must be caused by an instruction within the
  | specified range.
    For a ZAD PER trap, PVTMOD indicates that the zero address
    detection must be caused by an instruction within the
    specified range.
                         . . .
    RANGE=start
                         . . .
    RANGE is not valid for error event traps. . . . storage key
    alteration PER trap. RANGE is not valid for a
  | ZAD or TEND PER trap.
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UJ96983 UJ96989

Modules/Macros

• IEECB943 IEECB946 IEAVEPCO IEECB945 IEAVTSL2 IEAVTSLP IEAVTSL1
  IEECB905 IEAVTSZE IEECB907 IEAVTGLB IEECB909 IEAVTSLB IEAVTPVT
  IEAVTSLD IHASHDR  IEAVTSIG IEECB940
  

Fix information

• Fixed component name

  SLIP/PER

• Fixed component ID

  5752SCSLP

Applicable component levels

• R7D0 PSY UJ96989

     UP25/04/23 P F504  

• R7E0 PSY UJ96983

     UP25/04/23 P F504  

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.