RTIBIND and the IBM Run Time Instrumentation Profiler

This topic includes the following sections:

Overview

The IBM® Run Time Instrumentation (RTI) Profiler is a performance analysis tool to collect and report on the execution-time CPU performance characteristics of your batch z/OS® and CICS® applications.

The RTIBIND option controls whether to rebind your modules with the RTI program modules to enable the RTI performance profiling reports to be generated when the program runs.

All the Language Environment® CSECTs in your application can be bound with the RTI program modules to enable profiling to get a complete picture of overall CPU performance. This includes programs compiled by the IBM COBOL, C/C++, and PL/I compilers as well as COBOL programs optimized by ABO. The time spent in any LE library routines is also collected and reported.

Read syntax diagramSkip visual syntax diagramRTIBIND= N | NOI | INO | OUTA | ALL
Default:

RTIBIND=N | NO

Usage:

When RTIBIND=N | NO is specified, ABO optimizes any eligible CSECTs as usual, and does not rebind any of the input program modules with the RTI program modules.

When RTIBIND=I | IN is specified, ABO does not perform any optimizations, but only rebinds all the input program modules with the RTI program modules (that is, rebind the modules specified by the BOPT IN= directive).

When RTIBIND=O | OUT is specified, ABO optimizes any eligible CSECTs as usual, and rebinds any input program modules that have at least one eligible CSECT optimized with the RTI program modules (that is, rebind the modules optimized and placed in the location specified by the BOPT OUT= directive).

When RTIBIND=A | ALL is specified, ABO optimizes any eligible CSECTs as usual, and rebinds these optimized modules plus any input modules that are not optimized, with the RTI program modules (that is, rebind the union of all the modules specified by BOPT IN= and OUT= directives).

Note: To enable the RTI profiling for CICS multi-program applications, it is recommended to rebind as many programs of this application as needed with RTI program modules. In the CICS environment, RTI controls concurrent and subsequent runs of multiple programs that are rebound with RTI by profiling one program at a time. If a particular RTI Profiler-enabled program module executes at various times during the application run, then by default, only up to three profiling reports are generated for that program. However, the limit of profiling reports generated per program is adjustable, see RTIS transaction for more information. You can recreate the profiling reports for the same program again which will overwrite an existing one after a one-minute RTI-silence time interval. The one-minute silence means no RTI rebound program execution for one minute.

Capturing profiling results during z/OS batch program execution

Before using the RTI Profiler-enabled modules, you must allocate a PDS or PDSE data set in order to hold the profiling results. The RTI Profiler generated report is stored into a member of this data set. In the following JCL examples, this data set is named hlq.SYSPROFD.

The following table shows the recommended allocation parameters for hlq.SYSPROFD.

Table 1. Recommended allocation parameters
Data sets Recommended allocation parameters
hlq.SYSPROFD (as a PDS) 
Space units : CYLINDER
Primary quantity : 10
Secondary quantity : 10
Directory blocks : 10
Record format : FB
Record length : 80
Block size : 27920
Data set name type PDS
hlq.SYSPROFD (as a PDSE) 
Space units : CYLINDER
Primary quantity: 10
Secondary quantity : 10
Directory blocks : 10
Record format : FB
Record length : 80
Block size : 27920
Data set name type LIBRARY

In addition, when running the application containing the JCL rebound modules there are two modifications required to your run step JCL in order to collect the profile.

In your existing JCL for executing your program:
  • Add the ABO installation location, for example hlqboz.SBOZMOD1, to the existing STEPLIB. This change is not required if your ABO installation library is in the LNKLST.
  • Add the DDNAME SYSPROFD as the location to receive the profiling results. If no SYSPROFD DD card is provided, then a new sequential data set will be allocated with the following name format: userid.BOZRTI.SYSPROFD.pgmname. If a data set with this name already exists, then it will be overwritten."
Below is a JCL example for this step:
 //GO EXEC PGM=pgmname
 //STEPLIB DD DSN=hlq.OUT.LOAD.RTI,DISP=SHR        <- the RTI rebound modules from ABO 
 //        DD DSN=hlqboz.SBOZMOD1,DISP=SHR         <- add ABO install location 
 //SYSPROFD DD DSN=hlq.SYSPROFD(pgmname),DISP=SHR  <- add SYSPROFD DD

When program execution completes, the profiling results are contained in hlq.SYSPROFD(pgmname).

If SYSPROFD is not added in the execution step, the message BOZR001I SYSPROFD: userid.BOZRTI.SYSPROFD.pgmname is generated to the job log, but the execution step continues.

If the program is very short running, then the profiling results file specified by SYSPROFD may be incomplete, and will not be usable for performance investigations. In this case the following message will be displayed in the profiling results file: 
No profiling data available due to short execution time
Choose programs for profiling that run for at least 5 CPU seconds to obtain valid profiling results.

Capturing profiling results during CICS application program execution

Before using the RTI Profiler-enabled modules, the CICS startup JCL must be updated by placing the ABO load library in DFHRPL concatenation.

If your original application modules are in the data set concatenated under DFHRPL, then place the data set containing the RTI Profiler-enabled modules before the data set containing the original modules.

See the following example fragment of the CICS region startup JCL:
//DFHRPL           DD DSN=CICS.TS550.SEYULOAD,DISP=SHR
//                 DD DSN=CICS.TS550.SDFHLOAD,DISP=SHR
//                 DD DSN=CICS.TS550.SDFHLIC,DISP=SHR
//                 DD DSN=hlqboz.SBOZMOD1,DISP=SHR              <- add ABO install location
//                 DD DSN=hlq.OUT.LOAD.RTI,DISP=SHR             <- add RTI Profiler-enabled modules
//                 DD DSN=hlq.ORIG.LOAD,DISP=SHR                <- original application modules 
//SYSPROFD         DD DSN=hlq.SYSPROFD (pgmname)DISP=SHR        <- optional
If your original application modules are in the data set listed under the CICS library resource definition, as shown in the following example,
DEFINE LIBRARY(libname1)
  RANKING(55)
  STATUS(ENABLED)
  DSNAME01(hlq.ORIG.LOAD)     <- original application modules are in library libname1
  GROUP(LIBS)
you have two options to define your RTI Profiler-enabled data set using CICS library resource:
  1. Place the name of data set that contains the RTI Profiler-enabled modules of the application into the CICS library resource definition with a lower ranking, as shown in the below example fragment of the CSD definitions: 
    DEFINE LIBRARY(libname2)
  RANKING(45)
  STATUS(ENABLED)
  DSNAME01(hlq.OUT.LOAD.RTI)  <- add data set with RTI rebound modules in lower ranked library libname2
  GROUP(LIBS)
DEFINE LIBRARY(libname1)
  RANKING(55)             
  STATUS(ENABLED)
  DSNAME01(hlq.ORIG.LOAD)     <- original application modules are in library libname1
  GROUP(LIBS)
  2. If Option 1 is unsuitable for you due to the number of libraries allowed on the same CICS region limitations or other library resource restrictions applicable in your installation, proceed with this option.
    Place the data set name containing the RTI Profiler-enabled modules of the application in the same CICS library resource definition but placed above the data set with the original modules, as shown in the below example fragment of the CSD definitions:
    DEFINE LIBRARY(libname1)
  RANKING(55)             
  STATUS(ENABLED)
  DSNAME01(hlq.OUT.LOAD.RTI)  <- add data set with RTI rebound modules in front of original
  DSNAME02(hlq.ORIG.LOAD)     <- original application modules are in library libname1
  GROUP(LIBS)
Option 1 is recommended because it allows you to set the status of the library containing RTI Profiler-enabled modules to disable and stop the RTI Profiler activity at any time during your application run.
For example, you can do this by issuing the command from the CICS terminal:
CEMT SET LIBRARY(libname2) DISABLED
When using Option 2 configuration you cannot stop profiling using the above CICS terminal command.
You can optionally add DDNAME SYSPROFD in your CICS startup JCL, then follow the instructions for hlq.SYSPROFD data set allocation in Capturing profiling results during z/OS batch program execution. If no SYSPROFD DD card is provided, then a new sequential data set will be allocated with the following name format:
userid.BOZRTI.SYSPROFD.pgmname.LOG#nnn
If a data set with this name already exists, then it will be overwritten.
The nnn corresponds with the report number generated for the program named pgmname. For the first run of RTI Profiler-enabled pgmname program, the suffix of the report will be LOG#001. For each subsequent run of the same program, the corresponding report name suffix will be increased by 1. The default maximum number of reports per program is 3, but this limit is adjustable. For more information, see RTIS transaction. For each dynamically allocated RTI report file, the corresponding job log message is as follows:
BOZR001I SYSPROFD: userid.BOZRTI.SYSPROFD.pgmname.LOG#nnn
To support RTI in your CICS region, you must add the following CSD definitions:
DEFINE PROGRAM(BOZRIDT) GROUP(BOZRTI1) LANGUAGE(ASSEMBLER)
DEFINE PROGRAM(BOZTRUE) GROUP(BOZRTI1) LANGUAGE(ASSEMBLER) RELOAD(NO)
DEFINE PROGRAM(BOZGLUE) GROUP(BOZRTI1) LANGUAGE(ASSEMBLER) RELOAD(NO)
DEFINE TRANSACTION(RTI) GROUP(BOZRTI1) PROGRAM(BOZRIDT)
DEFINE PROGRAM(BOZSETRT) GROUP(BOZRTI1) LANGUAGE(ASSEMBLER)
DEFINE TRANSACTION(RTIS) GROUP(BOZRTI1) PROGRAM(BOZSETRT)
DEFINE TSMODEL(BOZRTI1) GROUP(BOZRTI1) PREFIX(BOZRTIQ.) EXPIRYINTMIN(9)
DEFINE TSMODEL(BOZRTI2) GROUP(BOZRTI1) PREFIX(BOZRTIQ@BOZRTIQ.) SECURITY(NO)
ADD GROUP(BOZRTI1) LIST(listname)  <- put your list name here
Notes:
  1. The following keywords in the above definitions: BOZRIDT, BOZTRUE, BOZGLUE, RTI, BOZSETRT, BOZRTIQ@, and BOZRTIQ. are reserved. You can optionally change the name of group BOZRTI1, the TS models BOZRTI1/BOZRTI2, and transaction RTIS, if needed.
  2. An RTI program bound into your CICS COBOL modules owns and maintains the CICS TS queues named BOZRTIQ@BOZRTIQ.. The first queue permanently allocates 10 bytes of temporary storage. The second type of queue has * to mask the individual program name and allocates 1 byte of storage per RTI Profiler-enabled program. RTI automatically deletes all queues of that second type after the 1-minute RTI-silence time interval is due.
  3. To secure RTI profiling and RTIS transaction usage by CICS users, consider setting SECURITY (YES) with TS model BOZRTI2 and maintaining the TS queue BOZRTIQ@BOZRTIQ. resource security profile as needed.

Understanding the RTI Profiler results

The output of the RTI Profiler is a text file containing details per compiled or optimized module and CSECT where the program is spending its time while running. There is a high-level summary provided as well as a breakdown of timing samples down to the offsets within each CSECT. For more detailed information, see Run Time Instrumentation report.

In conjunction with the corresponding compiler or ABO listing files for the programs being profiled, the RTI Profiler output can help determine specific parts of your program, down to the machine instruction, where there can be opportunities for improving application CPU performance.

An IBM support or development representative can also request the RTIBIND option be used and an RTI Profiler be collected, and its output sent to IBM along with other artifacts (example: listing files) from the original compilation or optimization of your programs to aid in performance investigations.

RTI Profiler capabilities and restrictions

The RTI Profiler is best suited for in-depth CPU profiling of LE enabled batch and CICS applications, but does not provide other system-level performance metrics such as wait times, I/O performance, or DASD usage.

The RTI Profiler can be used on all LE enabled batch applications including IMS batch and batch programs that interact with Db2®. Running non-LE programs that have been rebound with the RTI program modules is not supported and the result is unpredictable.

The RTI Profiler is not supported for any IMS applications that are part of a non-batch IMS environment.

The RTI Profiler can be used on all LE enabled CICS applications.

The RTI Profiler will not work if your z/OS operating system is running on z/VM®. If run on z/VM guest, the message RISTART: AUTH REQUEST FAILED is output to the job log.

The RTI Profiler does not provide CSECT level details for modules in LPA or that are managed by LLA. Profiling sample information will only be reported at the module level for these cases.

If you require more complete and full featured application profiling, you can use a profiling tool such as IBM Application Performance Analyzer for z/OS.

Notes:
  1. SCAN=Y takes precedence over the RTIBIND option settings. Specifying SCAN=Y disables rebinding with the RTI program modules and optimization of any eligible CSECTs regardless of the RTIBIND option.
  2. When processing a module originally linked with the AMODE 24 or RMODE 24 option and then processed by ABO with the RTIBIND=I | O | A option, the warning message BOZ1490W is expected. The BOZ1490W message reflects an AMODE/RMODE conflict due to rebinding with the AMODE 31 RTI modules. The message has no impact on the original module execution. The program will still run correctly in the original AMODE 24 or RMODE 24 mode.
  3. The RTIBIND option is the most convenient way to enable modules for RTI profiling. However, if you require more low-level control of the rebinding process, see Manual RTI rebinding instructions.
  4. If the program to be profiled was compiled using VS COBOL II or an ABO optimized VS COBOL II compiled program, an extra step might be needed to rebind the module to replace the bootstrap routine IGZEBST with the current version from LE. If you do not see any profiling output at the SYSPROFD location after using RTIBIND and attempting to profile VS COBOL II or an ABO optimized VS COBOL II compiled program, follow the steps below to replace the IGZEBST routine before using RTIBIND (or before following the manual rebinding steps) to enable the module for RTI profiling.
    //LKED EXEC PGM=IEWL,PARM=’options’ <- original link options
//SYSLIB DD DSN=hlqcee.SCEELKED,DISP=SHR
// DD DSN=hlqcee.SCEELKEX,DISP=SHR
//LOAD DD DISP=SHR,DSN=&LOAD   <- original module that will be linked with new IGZEBST
//SYSLMOD DD DISP=SHR,DSN=&SYSLMOD(pgmname)  <- output module location
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
  INCLUDE SYSLIB(IGZEBST)      <- new bootstrap to include from CEE
  INCLUDE LOAD(pgmname)        <- original member from LOAD to link new parts into
  REPLACE -IMMED,IGZEBST       <- bootstrap member to replace
  ENTRY pgmname
  NAME pgmname(R)
//*
  5. If the program to be profiled is called by an assembler module that is linked with AMODE 24, the assembler module must be rebound by using RTIBIND=I|IN or A|ALL.