SirTune report generation: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (remove preceding blanks)
m (typos)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
__NOTOC__
<var class="product">SirTune</var> reports are generated from jobs that invoke the <code>SIRTUNEREPORT</code> SOUL program (which in turn calls the <var>[[SirTuneReport (Dataset function)|SirTuneReport]]</var> method of the <var>Dataset</var> class).
 
In addition, as of RKTools 7.7, the [[RKTools installation#RKWeb (Model 204 Tools on the Web)|RKWeb]] browser interface is equipped to invoke and display <code>SIRTUNEREPORT</code> results. Using RKWeb for SirTune reports requires the same set up of input and output files described on this page.
 
==Report programs==
The report generation portion of <var class="product">SirTune</var> consists
The report generation portion of <var class="product">SirTune</var> consists
of two <var class="product">SOUL</var> programs which are distributed in the <var class="product">[[RKTools]]</var> <code>SIRIUS</code> file (prior to RKTools version 7.7) or the <code>M204PROC</code> file (as of RKTools 7.7).
of two <var class="product">SOUL</var> programs which are distributed in the <var class="product">[[RKTools]]</var> <code>SIRIUS</code> file (prior to RKTools version 7.7) or the <code>M204PROC</code> file (as of RKTools 7.7).
Line 15: Line 19:
A few <var>[[UTABLE command|UTABLE]]</var> and environmental settings are executed at the top of SIRTUNEREPORT. These can be adjusted for performance or functional reasons at the client site.
A few <var>[[UTABLE command|UTABLE]]</var> and environmental settings are executed at the top of SIRTUNEREPORT. These can be adjusted for performance or functional reasons at the client site.


==Report files==
SIRTUNEREPORT requires two input files, and it accepts an optional output
SIRTUNEREPORT requires two input files, and it accepts an optional output
file. These files, described below, may be specified as DD cards or ALLOCATE statements on the job running SIRTUNEREPORT:
file. These files, described below, may be specified as DD cards or ALLOCATE statements on the job running SIRTUNEREPORT:
Line 22: Line 27:
<td>Input cards that specify the <var class="product">SirTune</var> reports and other run characteristics.
<td>Input cards that specify the <var class="product">SirTune</var> reports and other run characteristics.
<p>
<p>
This file may contain older style input, with REPORT, RANGE, RESOLUTION, and other statements, or it may contain newer-style input in XML format. If old-style card images are input, a subroutine in SIRTUNEREPORT converts them to XML. For detailed information about this input, see [[SirTune Report Generator configuration]]. </p>
This file may contain older style input, with REPORT, RANGE, RESOLUTION, and other statements, or it may contain newer-style input in XML format. If old-style card images are input, a subroutine in SIRTUNEREPORT converts them to XML. For detailed information about this input, see [[#Report configuration|Report configuration]]. </p>
<p>
<p>
TUNERPTI is a required file. </p>
TUNERPTI is a required file. </p>
Line 37: Line 42:
Sample data sets from multiple runs may be concatenated. In fact, sample data sets from multiple runs may even be concatenated sequentially into a single data set (with IEBGENER under MVS, or COPYFILE or an equivalent under CMS) and provided as a single data set to SIRTUNEREPORT.</p>
Sample data sets from multiple runs may be concatenated. In fact, sample data sets from multiple runs may even be concatenated sequentially into a single data set (with IEBGENER under MVS, or COPYFILE or an equivalent under CMS) and provided as a single data set to SIRTUNEREPORT.</p>
<p>
<p>
When multiple sample data sets are concatenated in any way, the <code>DATASET</code> statement ([[SirTune Report Generator configuration#dsetlst|DATaset list]]) must be provided in TUNERPTI to have TUNERPTR use any but the first sample data set in the concatenation.</p></td></tr>
When multiple sample data sets are concatenated in any way, the <code>DATASET</code> statement ([[SirTune report generation#dsetlst|DATaset list]]) must be provided in TUNERPTI to have TUNERPTR use any but the first sample data set in the concatenation.</p></td></tr>


<tr><th>TUNERPTO</th>
<tr><th>TUNERPTO</th>
<td>This is the output file for the SIRTUNEREPORT reports.  
<td>This is the output file for the SIRTUNEREPORT reports.  
<p>
<p>
The SOUL code is currently set to output 72 characters per line, so a fixed or fixed-block file with 80-character records is recommended. </p>
The SOUL code is currently set to output 72 characters per line, so a fixed or fixed-block file with 80-character records is recommended. The output width for report lines is set by the [[SirTune report generation#CHARACTERSPERLINE or CPL|CPL statement]] in the TUNERPTI file. If CPL is not set, the output width defaults to 132 characters. </p>
<p>
<p>
TUNERPTO is an optional file. If it is not present, report output is redirected to standard output; generally, [[CCAPRINT data set|CCAPRINT]].</p></td></tr>
TUNERPTO is an optional file. If it is not present, report output is redirected to standard output; generally, [[CCAPRINT data set|CCAPRINT]].</p></td></tr>
Line 51: Line 56:
The names are chosen to differentiate them from the SIRTUNE<i>x</i> names used during <var class="product">SirTune</var> data collection.
The names are chosen to differentiate them from the SIRTUNE<i>x</i> names used during <var class="product">SirTune</var> data collection.


Generally, SIRTUNEREPORT is run as a standalone batch job, though
==Report job==
it is perfectly acceptable, if perhaps a little resource-intensive, to dynamically allocate the TUNERPT<i>x</i> files and run it from inside an Online.
Generally, <code>SIRTUNEREPORT</code> is run as a standalone batch job, though it is perfectly acceptable, if perhaps a little resource-intensive, to dynamically allocate the TUNERPT<i>x</i> files and run it from inside an Online.
 
A basic TUNERPTR job under z/OS looks like this:


A basic TUNERPTR job under MVS would look like this:
====get non-BATCH204 example!! ====
<p class="code">//TUNE JOB (0,0),CLASS=A,MSGCLASS=X
<p class="code">//TUNE JOB (0,0),CLASS=A,MSGCLASS=X
//TUNERPT  EXEC PGM=BATCH204,REGION=4096K,
//TUNERPT  EXEC PGM=BATCH204,REGION=4096K,
Line 68: Line 73:
//CCAPRINT DD SYSOUT=*,OUTLIM=50000
//CCAPRINT DD SYSOUT=*,OUTLIM=50000
//CCAIN    DD *
//CCAIN    DD *
NFILES=5,NDCBS=5,NDIR=5,MAXBUF=50,NGROUP=5,NORQS=4,LIBUFF=132,    X
NFILES=5,NDCBS=5,NDIR=5,MAXBUF=50,NGROUP=5,NORQS=4,               X
LOBUFF=320,LPDLST=2400,LQTBL=1350,LSTBL=2000,LNTBL=1200
LQTBL=4000,LSTBL=30000,LNTBL=1200,LVTBL=3000
LOGON me
LOGON me
<i>mepassword</i>
<i>mepassword</i>
Line 78: Line 83:
</p>
</p>


Under CMS, a similar Batch204 EXEC can be used to invoke SIRTUNEREPORT.
Notes:
<ul>
<li>For RKTools 7.7 or higher, the <code>SIRIUS</code> file is replaced with the <code>M204PROC</code> file. </li>


====get non-BATCH204 example!! ====
<li>For an Online job instead of batch, the same SirTune files are allocated: TUNERPTI (report input parameters), TUNERPTD (reporting data), and an optional TUNERPTO (output destination replacing the screen default). The <code>OPEN</code> and <code>INCLUDE</code> commands do not change. </li>


Compatibility notes:
<li>Under CMS, a similar Batch204 EXEC can be used to invoke <code>SIRTUNEREPORT</code>. </li>
</ul>
 
==Report configuration==
To customize a <var class="product">SirTune</var> reporting run, you use the DD card named <code>TUNERPTI</code> to specify configuration parameters. These parameters define the characteristics of the reporting run. The card  must have fixed format, but it can use either of the following types of input format:  
<ul>
<ul>
<li>As of release 7.2 of the Sirius mods, <var class="product">SirTune</var> reports can only be generated
<li>Control-card statements
using a SOUL program invoking a call to the <var>[[SirTuneReport (Dataset function)|SirTuneReport]]</var> method of the <var>Dataset</var> class, as implemented in the <code>SIRTUNEREPORT</code> SOUL program described
<li>XML document format
in [[SirTune Report Generator configuration]] and [[SirTune reports]].</li>
</ul>


<li>Due to format changes in the sample data set, only releases 1.6 and later of SIRTUNER can process a SirTune version 7.0 and later sample data set.</li>
===Using control-card statements===
<p>
You can specify report configuration parameters in a set of statements
(only one per line). There are no line continuations, and a line beginning
with an asterisk character (<tt>*</tt>) is treated as a comment (that is, ignored). </p>
<p>
The individual statements are described in [[#cardcfg|Configuration parameters]]. </p>
<p>
An example of control-card statement input follows:</p>
<p class="code">RANGE 9:30 12:30
RESOLUTION 50
REPORT CFRROOT
REPORT STATE CFRBANY WHAT
MAXD 10
REPORT STATE RUNG QUAD
REPORT STATE RUNG EVALI EVAL CHUNK 32
REPORT STATE RUNG CHUNK 4 CHUNK 400 CHUNK 4000
REPORT CSECT TOTAL CHUNK 512 CHUNK 64
</p>


<li>Due to format changes in the sample data set in SirTune version 1.5, earlier releases of SIRTUNER cannot process a SirTune 1.5 or higher sample data set.</li>
===Using XML document format===
<p>
XML-document report parameters are case-sensitive XML elements or attributes contained in a <code>SirtuneInput</code> document node. </p>
<p>
Most of the parameters represented as single control-card statements
(as described above) are available in XML, but they are represented in lowercase or mixed-case,
and some are individual elements while others are attributes of elements.
The details about the coding location of each parameter are in [[#xmlrpti|Using XML input for report configuration]]. </p>
<p>
Unlike the control-card input format, where multiple variations on a
report can be specified on a single line, in XML format each
<code><report></code> element specifies exactly one report. </p>
<p>
Here is an XML version of the control-card example above: </p>
<p class="code"><SirtuneInput maxDelay="10" top="100" title="ULSPFPRO">
  <range start="9:30" end="12:30"/>
  <resolution value="50"/>
  <reportFormat>
    <title>Sirtune Reports for ULSPFPRO</title>
    <charactersPerLine>78</charactersPerLine>
    <linesPerPage>55</linesPerPage>
    <tableOfContents>top</tableOfContents>
  </reportFormat>
  <report type="cfrroot"/>
  <report type="what" state="crfbany"/>
  <report type="quad" state="rung"/>
  <report type="evali" state="rung"/>
  <report type="eval" state="rung"/>
  <report type="eval" state="rung" chunk="32"/>
  <report type="eval" state="rung" chunk="4">
  <report type="eval" state="rung" chunk="400">
  <report type="eval" state="rung" chunk="4000">
  <report type="csect" chunk="total"/>
  <report type="csect" chunk="512"/>
  <report type="csect" chunk="64"/>
</SirtuneInput> </p>
 
==<b id="cardcfg"></b>Configuration parameters==
The following subsections describe the individual parameters you can use to configure a <var class="product">SirTune</var> report.
Most of the parameter names and descriptions refer to the
control-card statement format, although pertinent XML format information is also provided.
For more information about using XML for the control-card input,
see [[#xmlrpti|Using XML input for report configuration]].
Where applicable, the titles of the following subsections also show how to specify the parameter in control-card statement form:
<ul>
<li>The minimum allowable abbreviation for each statement is indicated with
uppercase characters, while optional characters are indicated with lowercase.
<p>
Names are case-sensitive, and these name abbreviations are not permitted,
in XML-formatted input. </p></li>
 
<li>Optional statement keywords are enclosed in brackets (<tt>[</tt><tt>]</tt>), and alternatives are separated with a vertical line (<tt>|</tt>). </li>
</ul>
</ul>


<div id="repsmvs"></div>
===<b id="charper"></b>CHARACTERSPERLINE or CPL===
==Generating reports prior to Sirius Mods 7.2: MVS==
This statement determines the width of an output report line.
<!--Caution: <div> above-->
For example, either of the following statements sets the report output width to 80 characters:
<p class="code">CHARACTERSPERLINE 80
CPL 80 </p>
 
Valid line-width values are integers between 78 and 256.
If a value outside this range is specified, CPL is set to 132.
If you are using XML input to TUNERPTI, the <code><cpl></code>
or <code><charactersPerLine></code> element specifies the line width.
For more information about this, see [[#repfmt|<reportFormat>:  Controlling report format]].
 
===<b id="comp31"></b>COMP31===
<p class="note"><b>Note:</b> This parameter can only be specified when using XML input to TUNERPTI, and it is valid only for <var class="product">Model&nbsp;204</var> V6R3 and later.
COMP31 indicates the maximum compilation-table size for a procedure that is to be stored in 31-bit storage.
Above this size, compilations are moved to 64-bit storage. The default value is X'1FFFF', or 131,071.
COMP31 is specified as an attribute on the <code>SirtuneInput</code> element (see [[#xmlrpti|Using XML input for report configuration]]). For example:
<p class="code"><SirtuneInput maxDelay="10" comp31="200000">
</p>
 
The size of a saved compilation table for a procedure is the
size of the procedure in [[QTBL]] bytes, divided by the minimum QTBL chunk size, times 20:
<p class="code">(QTBLsize/QTBLchunk)*20
</p>
<p>
If a procedure's QTBL is 20,000 bytes and the smallest chunk size
requested in a report is 200, this procedure will require <code>(20,000/200)*20</code>,
or 2,000 bytes. More common are procedure sizes of around 800,000 bytes, with a chunk size of 4, theoretically requiring <code>(800,000/4)*20</code>, or 4,000,000 bytes.
This is actually an upper bound, as you never get more than one chunk per line, and few lines of code generate only 4 bytes of QTBL. More typical is about 40 bytes per chunk (even with a chunk size of 4), which produces a compiled table of 200,000.</p>
<p>
There is no reason to set COMP31 unless your site is running out of
31-bit storage under <var class="product">Model&nbsp;204</var> V6R3 or later.
Prior to V6R3, <var class="product">Model&nbsp;204</var> did not support 64-bit storage, so comp31 has no effect.
</p>
<p class="note"><b>Note:</b> The <var>[[CURREP31 parameter|CURREP31]]</var>, <var>[[CURREP64 parameter|CURREP64]]</var>, <var>[[HGHREP31 parameter|HGHREP31]]</var>, and <var>[[HGHREP64 parameter|HGHREP64]]</var>
system parameters indicate the current and greatest amounts of
31-bit and 64-bit virtual storage used for a report.
The <var>[[MAXREP31 parameter|MAXREP31]]</var> and <var>[[MAXREP64 parameter|MAXREP64]]</var> parameters indicate the maximum amount allowed.
</p>
 
===<b id="dsetlst"></b>DATaset list===
<p class="note"><b>Note:</b> This parameter is deprecated. If it is specified as an input parameter, it is ignored. </p>
<p>
<p>
For pre-7.2 versions of the <var class="product">Sirius Mods</var>,
The DATASET statement indicates which sample data sets that make up SIRTUNED are to be included in the report. A separate <code>INFO</code> report is produced for each data set selected, and all samples from the selected data sets are combined to produce composite
the report generation portion of <var class="product">SirTune</var> consists of a single load module called <code>SIRTUNER</code>.
results for other reports. Data sets are processed in order: if a data set is selected and causes some TUNR error message, reporting ends without proceeding to other data sets. </p>
To have SIRTUNER generate a report for a particular ONLINE job, code JCL that invokes SIRTUNER with appropriate DD cards. </p>
<p>
<p class="note"><b>Note:</b> Due to format changes in the sample data set, only releases 1.6 and later of SIRTUNER can process a <var class="product">SirTune</var> version 7.0 and later sample data set.
If the DATASET statement is not specified,
only the first sample data set is included in the report.
This is true even if multiple sample data sets were physically concatenated into a single data set with IEBGENER or COPYFILE before being passed to the reporting module.
</p>
</p>
<p class="note"><b>Note:</b> Due to format changes in the sample data set in <var class="product">SirTune</var> version 1.5, earlier releases of SIRTUNER cannot process a <var class="product">SirTune</var> 1.5 or higher sample data set.
<p>
The <var class="term">list</var> value is a list of data set numbers or ranges of numbers.
For example, the following indicates that data sets 1 through 4 are to be used:</p>
<p class="code">DATASET 1-4
</p>
</p>
<p>
<p>
The DD names used by SIRTUNER are: </p>
The following indicates that data sets 2, 4, and 5 through 6 are to be used:</p>
<p class="code">DATASET 2 5-6 4
</p>
<p>
More than one DATASET statement can appear in SIRTUNEI, and
their effect is cumulative, so:</p>
<p class="code">DATASET 2
DATASET 4-6 </p>
<p>
Is the same as:</p>
<p class="code">DATASET 2 4-6 </p>
<p>
If an asterisk (<code>*</code>) character appears after a DATASET statement, all data sets are used in the report. Thus the following:</p>
<p class="code">DATASET 1 3-5 8 *
</p>
<p>
is the same as:</p>
<p class="code">DATASET * </p>
<p>
since in both cases, all data sets are used in the report. </p>
<p>
There is no harm in specifying data set numbers greater than the number
of sample data sets in SIRTUNED, though of course, these data set numbers
will not be included in the report.</p>
<p>
RANGE, SKIP, and FOR statements operate individually on each component
sample data set in a concatenation. For example, suppose SIRTUNED
consists of three concatenated sample data sets collected over the following dates and times:</p>
 
<table class="thJustBold">
<tr><th>Dataset 1</th>
<td>January 5 at 5:30 AM through January 8 at 11:00 PM</td></tr>
 
<tr><th>Dataset 2</th>
<td>January 10 at 1:00 PM through January 15 at 10:00 PM</td></tr>
 
<tr><th>Dataset 3</th>
<td>January 11 at 5:00 AM through January 14 at 10:00 PM</td></tr>
</table>
 
In this example, data sets <code>2</code> and <code>3</code> are
associated with two different Onlines that run concurrently.
The SIRTUNEI statements:
<p class="code">RANGE 11:00 12:00 SKIP 3 FOR 2
DATASET 1-3 </p>
result in the range of 11:00 AM to 12:00 noon being used on the
following days for each data set:
<table class="thJustBold">
<table class="thJustBold">
<tr><th>SIRTUNED</th>
<tr><th>Dataset 1</th>
<td>This DD should point to a sample data set generated by <var class="product">SirTune</var>. It corresponds to the SIRTUNED DD for the data collection part of <var class="product">SirTune</var>.
<td>January 8</td></tr>
 
<tr><th>Dataset 2</th>
<td>January 14-15</td></tr>
 
<tr><th>Dataset 3</th>
<td>January 14-15</td></tr>
</table>
<p>
To determine the time ranges and characteristics of each individual
data set in a concatenation, simply run a report against the concatenated
SIRTUNED with the following commands in SIRTUNEI:</p>
<p class="code">REPORT NODEFAULT
REPORT INFO
</p>
<p>
It should be possible to produce most <var class="product">SirTune</var> reports with any concatenation of data sets. There are certain reports, however, that require all sample data sets
to have been produced with some consistency among the Onlines. These reports are:</p>
 
<table class="thJustBold">
<tr><th>CSECT?</th>
<td>The <var class="product">Model 204</var> load modules must be identical among runs (except for ZAPs or Early Warnings).</td></tr>
 
<tr><th>STATE ???? QUAD</th>
<td>The <var class="product">Model&nbsp;204</var> load modules must be from the same release and must have run with identical $function tables.</td></tr>
 
<tr><th>SERVIO</th>
<td>The OnlineS must have run with identical numbers of server data sets (CCASERVR, CCASERV1, etc.).</td></tr>
 
<tr><th nowrap>STATE RUNGM/RUNGS</th>
<td>The Onlines must have all run with <var>[[NMPSUBS parameter|NMPSUBS]]</var> greater than 0 (the [[MP/204]] feature is turned on).</td></tr>
</table>
<p>
Even though all other reports are allowed for concatenated sample data sets, use caution when interpreting the results.
It is up to you interpret how changes between runs could affect the results.
These changes might include:</p>
<ul>
<li>SOUL code changes </li>
<li>Changes in <var class="product">Model&nbsp;204</var> parameters </li>
<li>Changes in the <var class="product">Model&nbsp;204</var> load module </li>
<li>Changes in <var class="product">SirTune</var> parameters </li>
<li>Number of samples collected in each sample data set </li>
</ul>
In general, it is unlikely that concatenating data sets collected in
different environments or many months apart will produce meaningful reports.
<p>
Suppose, under MVS, the SIRTUNER or SIRTUNEREPORT job logically concatenates five sample data sets associated with the five weekdays as follows:</p>
<p class="code"><nowiki>//SIRTUNED DD  DSN=SIRTUNE.SAMPLE.MON,DISP=SHR
//        DD  DSN=SIRTUNE.SAMPLE.TUE,DISP=SHR
//        DD  DSN=SIRTUNE.SAMPLE.WED,DISP=SHR
//        DD  DSN=SIRTUNE.SAMPLE.THU,DISP=SHR
//        DD  DSN=SIRTUNE.SAMPLE.FRI,DISP=SHR
</nowiki></p>
<p>
To produce a report for Tuesday and Wednesday, specify the following input statements:</p>
<p class="code">DATASET 2 3 </p>
 
===<b id="lineper"></b>LINESPERPAGE or LPP===
<p>
This statement determines the page length for report output.
Any integer value is valid.</p>
<p>
A header is printed at the top of each page.
If 0, the default, is specified, no paging is performed, and headers are
output at the beginning of each report.</p>
<p>
For example, either of the following statements sets report page length to 55 lines:</p>
<p class="code">LINESPERPAGE 55
LPP 55
</p>
When 55 lines have been printed, SIRTUNEREPORT prints a new header
and resets the line counter to 0.
<p>
If you are using XML input to TUNERPTI, the <code><lpp></code>
or <code><linesPerPage></code> element specifies the report page length.
For more information about this, see [[#repfmt|<reportFormat>:  Controlling report format]].</p>
 
===<b id="mapcore"></b>MAPcore===
<p class="note"><b>Note:</b> This parameter is deprecated. If it is specified as an input parameter, it is ignored. </p>
<p>
When used in a CSECT breakdown report, this statement allows analysis of instructions outside the loaded <var class="product">Model&nbsp;204</var> module.</p>
 
===MAXDelay max_msec===
<p>
This statement makes it possible to change the criterion used by the reporting module to determine if a sample should be discarded.</p>
<p>
When the delay between the time a sample was supposed to be collected and the time it actually was collected is greater than <var class="term">max_msec</var> milliseconds,
the sample is assumed to be biased and hence discarded.
The default for <var class="term">max_msec</var> is 10, which means that any sample that is delayed by more than 10 milliseconds from its intended time is discarded.</p>
<p>
If it is felt that reports are biased, with I/O producing instructions
appearing unbelievably frequently in the RUNG state (obviously, this is very subjective), it might be worth reducing <code>MAXDELAY</code> to 1 with the following statement:</p>
<p class="code">MAXDELAY 1
</p>
If there was indeed a bias, one would expect after this change
to see more samples discarded and the percentages for the RUNG state to change for certain procedures and chunks of procedures.
<p>
If, on the other hand, <var class="product">SirTune</var> was running in an environment where the Online was getting relatively slow service from the operating system, almost all samples might be discarded by the reporting module.
In this situation, it might be worth increasing MAXDELAY to accept more samples, with the understanding that this might introduce biases in the reported data.</p>
<p>
To increase MAXDELAY to 1000 milliseconds (1 second), enter this statement:</p>
<p class="code">MAXDELAY 1000
</p>
Generally, setting MAXDELAY greater than 100 is likely to produce severe biases in Sirtune reports.
 
===<b id="mixed"></b>MIXed===
<p class="note"><b>Note:</b> This parameter is deprecated. If it is specified as an input parameter, it is ignored. </p>
<p>
This statement indicates that the reporting module should issue
all reports in mixed case. The default is to issue messages in mixed
case, except on Japanese operating systems.
On these systems, the default is to issue all messages in
uppercase only. This option should be used on Japanese operating systems when mixed case messages are desired.</p>
 
===<b id="mpvirt"></b>MPVirt===
<p class="note"><b>Note:</b> This parameter is deprecated. If it is specified as an input parameter, it is ignored. </p>
<p>
This statement has meaning only if generating a report for
data collected in an Online running [[MP/204]].
It indicates that a running user is considered to be running in parallel if it is in virtual or logical parallel mode, whether or not it is
actually running in an offload subtask.
By default, the <var class="product">SirTune</var> reports only
consider a user to be running in parallel if it is actually
running on an offload subtask.</p>
<p>
The MPVIRT statement is useful for estimating the "offloadability" of SOUL code in systems that are not busy enough to force all offloadable code into a subtask.</p>
<p class="note"><b>Note:</b> MPVIRT only has an effect on reports that are
specific to states RUNGM or RUNGS.
</p>
<p>
It is not possible to split the reports in a run of <var class="product">SirTune</var> so that some are generated
with MPVIRT set and others are not.
If MPVIRT appears anywhere in the input stream,
all reports from that reporting run are generated using
the MPVIRT option, whether the REPORT statements appear before or after the MPVIRT statement.</p>
 
===<b id="noseq"></b>NOSeq===
<p class="note"><b>Note:</b> This parameter is deprecated. If it is specified as an input parameter, it is ignored.
<p>
This statement indicates that the reporting module should not consider
characters in columns 73 through 80 of SIRTUNEI as part of
its input. If the input file has <code>RECFM=F</code> and <code>LRECL=80</code>, the reporting module
ordinarily assumes that characters in columns 73 through 80 are
sequence numbers and ignores them.
If the input stream has any other format, the reporting module
considers all characters in the input record as part of the control
statements.</p>
 
===<b id="rangest"></b>RANge start_time end_time [FOR for_num] [SKIP skip_num]===
This statement makes it possible to limit the reports to a subset
of the collected sample data.
This is useful for solving performance problems that have different
characteristics during different times of the day.
<p>
<var class="term">start_time</var> and <var class="term">end_time</var> can have the format HH, HH:MM, or HH:MM:SS, where HH represents an hour of the day, MM represents minutes, and SS represents seconds.
The maximum allowable time is 24 or 24:00 or 24:00:00, which corresponds to midnight. </p>
<p>
For example, the following statement indicates that only sample data collected in the first 1 PM to 3 PM range in the run should be used to generate the reports:</p>
<p class="code">RANGE 13 15
</p>
<p>
When using XML format, RANGE is specified in lowercase as a
child element of the document element, with "start", "end",
"skip", and "for" as optional attributes:</p>
<p class="code"><SirtuneInput top="50">
  <range start="13" end="15">
</p>
<p>
If the run came up in the middle of the specified range, the time from the start of the run to the end of the range is considered the first range.
In the preceding example, if the run came up at 2:30 PM, the first range would extend from 2:30 PM to 3 PM.
The following example indicates that only sample data collected in the first 11:30 AM to 1:30 PM
range in the run should be used to generate the reports:</p>
<p class="code">RANGE 11:30 13:30 </p>
<p>
This example indicates that only sample data collected in the first
30 seconds before 12 noon through 50 seconds after 1 PM
range in the run should be used to generate the reports:</p>
<p class="code">RANGE 11:59:30 13:00:50 </p>
<p>
If <var class="term">start_time</var> is greater than <var class="term">end_time</var>, the times are assumed to wrap.
For example. the following statement indicates that only sample data collected in the first 11:00 PM to 1:00 AM range in the run should be used to generate the reports:</p>
<p class="code">RANGE 23:00 1:00 </p>
<p>
If sample data for a run was collected over more than 24 hours, a
range might occur more than once in the sample data set.
Ordinarily, only the first range is included in the reports.
To include a specific number of occurrences of the indicated range, the <code>FOR</code> clause should be included on the RANGE statement, followed by <var class="term">for_num</var>,
where <var class="term">for_num</var> can be either a whole number or an asterisk (<code>*</code>).
A whole number indicates the number of occurrences of the range are to be included in the report. An asterisk indicates that all occurrences of the range are to be included in the report.</p>
<p>
For example, the following statement indicates that the first 5 9:30 AM to 11:30 AM ranges are to be included in the reports:</p>
<p class="code">RANGE 9:30 11:30 FOR 5 </p>
<p>
The data in these ranges are combined to produce a single
set of reports. The following statement
indicates that all 10 AM to 3 PM ranges are to be included in the report:</p>
<p class="code">RANGE 10 15 FOR * </p>
<p>
To exclude the first occurrence or occurrences of the indicated range
from the reports, include the SKIP clause on the RANGE statement, followed
by <var class="term">skip_num</var> (where <var class="term">skip_num</var> must be a non-negative integer
indicating the number of occurrences of the indicated range to skip).
For example, to indicate that the second 10 AM to 12 noon range is to be included in the reports:</p>
<p class="code">RANGE 10 12 SKIP 1 </p>
<p>
<p>
Sample data sets from multiple runs may be concatenated. In fact, sample data sets from multiple runs may even be concatenated sequentially into a single data set (with IEBGENER or an equivalent) and provided as a single data set to SIRTUNER.</p>  
To indicate that the third, fourth, and fifth 1:30 PM to 3:30 PM ranges are to be included in the reports:</p>
<p class="code">RANGE 13:30 15:30 SKIP 2 FOR 3 </p>
<p>
<p>
When multiple sample data sets are concatenated in any way, the [[SirTune Report Generator configuration#dsetlst|DATASET statement]] must be provided in SIRTUNEI to have SIRTUNER use any but the first sample data set in the concatenation. </p></td></tr>
While multiple RANGE statements may be specified
only the last one is used when specified as control cards.
Conversely, only the first one is used when specified in XML input
Thus:</p>
<p class="code">RANGE 9:30 11:30
RANGE 13:30 15:30 </p>
<p>
is functionally equivalent to:</p>
<p class="code">RANGE 13:30 15:30 </p>


<tr><th>SIRTUNEO</th><td>This DD is the data set that should receive SIRTUNER error messages or reports. It must have an LRECL greater than or equal to 80.</td></tr>
The position of RANGE statements relative to other statements is irrelevant.


<tr><th>SIRTUNEI</th>
===<b id="report"></b>REPort  report_desc | NODEFAULT===
<td>This optional DD contains SIRTUNER statements that alter the SIRTUNER defaults. These statements allow control over which reports are produced and the time interval over which sample data is to be summarized. For a list of available statements, see [[SirTune Report Generator configuration]].
This statement either requests a specified report or reports, or it
indicates that the default reports are not to be generated (<code>REPORT NODEFAULT</code>). The actual reports that can be requested are listed in [[SirTune reports]].
<p>
If <code>REPORT NODEFAULT</code> is specified, it must be the first REPORT statement in the input stream (if input is XML formatted, the position of <code>REPORT NODEFAULT</code> is not critical).</p>
<p>
The default reports produced by SIRTUNEI are the ones
that are produced by the following statements:</p>
<p class="code">REPORT INFO
REPORT SUMMARY
REPORT STATE RUNG WHAT EVAL CHUNK 4000
REPORT STATE RUNG EVAL CHUNK 400 CHUNK 4 </p>
<p>
In XML format, these default reports are specified like this:</p>
<p class="code"><SirtuneInput maxDelay="10" top="50">
  <report type="info">
  <report type="state">
  <report type="waittype">
  <report type="what" state="rung">
  <report type="eval" state="rung">
  <report type="eval" state="rung" chunk="4000">
  <report type="eval" state="rung" chunk="400">
  <report type="eval" state="rung" chunk="4">
</SirtuneInput> </p>
For more information about XML formatting for an individual report,
see [[#indrpt|<report>: Specifying individual reports]].
 
===<b id="resolu"></b>RESolution res_num [PROC pname] [FILE fname] [SUBSYS sname]===
This statement makes it possible to reduce the reporting module's
virtual storage utilization at the cost of reducing
the resolution possible in producing procedure chunk reports.
This statement should be of interest only to users
for whom virtual and real storage use is a major concern.
 
<p class="note"><b>Note:</b> The <var>CURREP31</var>, <var>CURREP64</var>, <var>HGHREP31</var>, and <var>HGHREP64</var>
Model&nbsp;204 system parameters indicate the current and greatest amounts of 31-bit and 64-bit virtual storage used for a report.
The <var>MAXREP31</var> and <var>MAXREP64</var> parameters indicate the maximum amount allowed.</p>
<p>
Storage use by the reporting module is directly
related to the total number of chunks for all procedures
for which compilation information is saved.
The number of chunks required for each such procedure
is inversely related to its minimum resolution.
Thus by increasing the minimum resolution for a procedure, it is possible to decrease the amount of virtual storage used for that procedure.
The default resolution for all procedures is 4.</p>
<p>
The <var class="term">res_num</var> value specifies the minimum chunk resolution in QTBL bytes for all or the indicated procedures.
For a discussion of chunks and resolution, see [[SirTune reports#repst|REPORT STATE state_name activity]].</p>
<p>
If not followed by any other keywords, this statement sets the default minimum resolution for all procedures. For example, this sets the default minimum resolution for all procedures to 100:</p>
<p class="code">RESOLUTION 100
</p>
<p>
There can be an unlimited number of this kind of RESOLUTION
statements, but only the last one is used to set the default minimum
resolution when the input stream is formatted as control cards.
When XML input is used, only the first RESOLUTION statement is used.
Thus:</p>
<p class="code">RESOLUTION 50
RESOLUTION 100
RESOLUTION 150 </p>
<p>
is functionally equivalent to:</p>
<p class="code">RESOLUTION 150 </p>
<p>
Likewise, this XML input:</p>
<p class="code"><resolution value="150">
<resolution value="100">
<resolution value="50"> </p>
<p>
is functionally equivalent to:</p>
<p class="code"><resolution value="150"> </p>
<p>
<var class="term">res_num</var> may optionally be followed by one or more
keywords (PROC, FILE, or SUBSYS), with each keyword followed by a
resolution that applies only to procedures that meet the keyword's criterion.
For example, this statement indicates that a resolution of 1000 should be used for all procedures in subsystem <code>HOHO</code>:</p>
<p class="code">RESOLUTION 1000 SUBSYS HOHO </p>
<p>
Using XML input, the keywords are the same except in lowercase:</p>
<p class="code"><resolution value="1000" subsys="HOHO"> </p>
<p>
This statement indicates that a resolution of 500 should be used for all procedures in procedure file <code>PROCA</code>:</p>
<p class="code">RESOLUTION 500 FILE PROCA </p>
<p>
Or, in XML mode:</p>
<p class="code"><resolution value="500" file="PROCA"> </p>
<p>
The following indicates that a resolution of 700 should be used for the procedure named <code>PRE-PROC.A</code>:</p>
<p class="code">RESOLUTION 700 PROC PRE-PROC.A </p>
<p>
Wildcards can also be used.
To indicate that a resolution of 100 should be used for any procedure
whose name begins with <code>PRE-</code>, you can specify:</p>
<p class="code">RESOLUTION 100 PROC PRE-* </p>
<p>
The following statement indicates that a resolution of 300 should be used for any procedure in a subsystem whose name ends with <code>XREF</code>:</p>
<p class="code">RESOLUTION 300 SUBSYS *XREF
</p>
For more details on the use of wildcards, see [[SirTune statement wildcards]].
<p>
More than one condition can be specified on a single RESOLUTION
statement, in which case the resolution specified applies only to
procedures that match all the keyword criteria.
For example, the following statement sets a resolution of 1000 for any procedure whose name ends in <code>TEST</code> <i>and</i> is in a procedure file whose name begins with <code>SIR</code>:</p>
<p class="code">RESOLUTION 1000 FILE SIR* PROC *TEST
</p>
In XML mode, the previous statement is:
<p class="code"><resolution value="1000" file="SIR*" proc="*TEST">
</p>
<p>
<p>
SIRTUNEI can have any format (RECFM=F or RECFM=V). </p></td></tr>
An unlimited number of qualified RESOLUTION statements may
appear in the report configuration input.
If more than one does occur in the input stream,
each procedure for which compilation data is encountered
is compared against each RESOLUTION statement, in the order in which they appear.
As soon as a match is found, the resolution is set for the procedure, and no more RESOLUTION statements are scanned.</p>
<p>
Thus, if SIRTUNEI contains:</p>
<p class="code">RESOLUTION 1000 SUBSYS SIR*
RESOLUTION 500 FILE TEST*
RESOLUTION 200 PROC *TEMP* </p>
<p>
any procedure in a subsystem whose name begins with <code>SIR</code> would
have a resolution of 1000, even if it ran out of a procedure
file whose name begins with <code>TEST</code>, or if the procedure name contains the characters <code>T E M P</code>.</p>
<p>
The resolution used for specific procedures
with the resolution statements in the preceding example are listed below:</p>
<table>
<tr class="head"><th>Subsystem</th><th>Procfile</th><th>Procedure name</th><th>Resolution</th></tr>
 
<tr><td>TOOLSYS</td><td>GENFILE</td><td>BOP.PROD.L</td><td>default</td></tr>
 
<tr><td>SIRJUNK</td><td>JUNKPROC</td><td>P.JUNK.PROC</td><td>1000</td></tr>
 
<tr><td>BIGSYS</td><td>TESTFILE</td><td>P.BARTLIST</td><td>500</td></tr>
 
<tr><td>BIGSYS</td><td>PROCX</td><td>EXPER.TEMP.P</td><td>200</td></tr>
 
<tr><td>SIRJUNK</td><td>TESTFILE</td><td>P.BARTLIST</td><td>1000</td></tr>
 
<tr><td>SIRJUNK</td><td>PROCX</td><td>EXPER.TEMP.P</td><td>1000</td></tr>
 
<tr><td>BIGSYS</td><td>TESTFILE</td><td>EXPER.TEMP.P</td><td>500</td></tr>
 
<tr><td>SIRJUNK</td><td>TESTFILE</td><td>EXPER.TEMP.P</td><td>1000</td></tr>
</table>
</table>


The suggested use of the RESOLUTION command is that
the default is left at <code>4</code> and that resolution is set
to a high value for procedures that are known to be compiled
but are not likely to show much activity.
If one or more of these procedures shows up on a CHUNK report
at a resolution smaller than that set by the RESOLUTION
commands for the procedures, do either of the following to explicitly set the resolution at a lower value for the procedures that appear on the CHUNK report:
<ul>
<li>Modify the RESOLUTION command.</li>
<li>Add extra RESOLUTION commands.</li>
</ul>
<p>
For example, suppose the following statement
is specified, and a procedure named <code>PRE.JUNK.PROC</code> in
subsystem <code>TEST</code> appears on a report for chunk size 100:</p>
<p class="code">RESOLUTION 400 SUBSYS TEST </p>
<p>
<p>
The following is an example of JCL used to generate a
Since the minimum chunk size that SIRTUNER or SIRTUNEREPORT
report with SIRTUNER:</p>
can use for procedures in subsystem <code>TEST</code> is 400 (because of the RESOLUTION statement), the report with chunk size 100 is comparing chunks of size approximately 100 with a
<p class="code"><nowiki>//TUNER    JOB  (0),CLASS=C,MSGCLASS=A
chunk of size 400 in <code>PRE.JUNK.PROC</code>. Thus, a much larger segment of
//SIRTUNER EXEC PGM=SIRTUNER,REGION=8M
code is being totalled for <code>PRE.JUNK.PROC</code> than other procedures on this report, making this procedure look more important than it really is.</p>
//STEPLIB  DD  DSN=SIRIUS.LOAD,DISP=SHR
<p>
//SIRTUNEI DD  *
To correct this situation, you can do either of these: </p>
REPORT STATE WDISK EVAL
<ul>
/*
<li>Remove the RESOLUTION statement from SIRTUNEI or TUNERPTI and lose its virtual storage savings benefits. </li>
//SIRTUNED DD  DSN=SIRTUNE.SAMPLE.DATA,DISP=SHR
//SIRTUNEO DD  SYSOUT=*
//
</nowiki></p>


<div id="repscms"></div>
<li>Add another RESOLUTION statement to override the subsystem wide
==Generating reports prior to Sirius Mods 7.2: CMS==
RESOLUTION statement for the specific procedure in question. </li>
<!--Caution: <div> above-->
</ul>
<p>
<p>
For pre-7.2 versions of the Sirius Mods, the report generation portion of <var class="product">SirTune</var> consists of a single load module: <code>SIRTUNER</code>.
The following sequence would accomplish this:</p>
To have SIRTUNER generate a report for a particular
<p class="code">RESOLUTION 4 SUBSYS TEST PROC PRE.JUNK.PROC
ONLINE job, code an EXEC that invokes SIRTUNER
RESOLUTION 400 SUBSYS TEST </p>
with appropriate FILEDEF commands.</p>  


<p class="note"><b>Note:</b> Due to format changes in the sample data set, only releases 1.6 and later of SIRTUNER can process a <var class="product">SirTune</var> version 7.0 and later sample data set.
===<b id="titlest"></b>TITle title_string===
This command makes it possible to specify a title to appear
on the top line of each page of the <var class="product">SirTune</var> report.
The default for <var class="term">title_string</var> is <code>SIRTUNE</code>.
<p>
TITLE makes it easy to distinguish the output from multiple SIRTUNER reports. The title string can be made up of an arbitrary number of characters, including blanks. Only the first 62 characters of
<var class="term">title_string</var> are used to generate the title. </p>
<p>
An example of a valid TITLE statement follows:</p>
<p class="code">TITLE Production run after first round of changes
</p>
</p>
<p class="note"><b>Note:</b> Due to format changes in the sample data set in <var class="product">SirTune</var> version 1.5, earlier releases of SIRTUNER cannot process a <var class="product">SirTune</var> 1.5 or higher sample data set.
<p>
If using XML input, you can specify the title as a child element of the document node, like this:</p>
<p class="code"><SirtuneInput>
  <title>Sirtune June 16, 2010 for THX1138</title>
  ...
</p>
</p>
<p>
<p>
SIRTUNER can run under CMS or CMS/XA.
Or you can specify the title as a child element of the <code>reportFormat</code> node, like this:</p>
Under CMS/XA, most of the storage used by SIRTUNER is "above the line," so virtual storage constraints should not be an issue.</p>  
<p class="code"><SirtuneInput>
  <reportFormat>
    <title>Sirtune June 16, 2010 for THX1138</title>
  </reportFormat
  ...
</p>
 
If specified in both places, the child element of <code>reportFormat</code> will override the child element of the document node.
The reporting module only pays attention to the first title
specified in either location in the input document.
 
===<b id="topnum"></b>TOP num_top===
This statement specifies the number of top entities to be displayed on any report that ranks
multiple entities. The default for <var class="term">num_top</var> is 50. This default can be overridden by a [[SirTune reports#toparm|TOP]] keyword on a REPORT statement.
<p>
<p>
The DD names used by SIRTUNER are:</p>  
For example, if you want to report on the top 100 procedures
or chunks of procedures on all reports, place this statement
in the input stream:</p>
<p class="code">TOP 100
</p>
<p>
Or, with XML input, enter <code>top</code> as an attribute on the document node:</p>
<p class="code"><SirtuneInput top="100"> </p>
<p>
Generally, it is not profitable to look at anything
past the top 50 entities in any report, since less than
2% of resource usage can be attributed to any entity not
in the top 50. It is generally not worth optimizing
something that accounts for so little resource usage.</p>


<table class="thJustBold">
===<b id="tabcont"></b>TABLEOFCONTENTS or TOC===
<tr><th>SIRTUNED</th>
This statement determines whether a table of contents is produced
<td>This DD should point to a sample data set generated by <var class="product">SirTune</var>. It corresponds to the SIRTUNED DD for the data collection part of <var class="product">SirTune</var>.
and where it is placed in the report. Although <code>TWOPASS</code> can still be used to specify the table of contents placement, the TABLEOFCONTENTS statement provides more control.
<p>
<p>
Sample data sets from multiple runs may be concatenated. In fact, sample data sets from multiple runs can be concatenated sequentially into a single data set (with COPYFILE or an equivalent) and provided as a single data set to SIRTUNER.</p>  
Valid values for TABLEOFCONTENTS are <code>TOP</code>, <code>BOTTOM</code>
and <code>NONE</code>. By default, the table of contents is placed at the end of the report. </p>
 
If you are using XML input to TUNERPTI, the <code><toc></code>
or <code><tableOfContents></code> element specifies characteristics of the table of contents.
For more information, see [[#repfmt|<reportFormat>:  Controlling report format]].
 
===<b id="twopass"></b>TWOpass===
This statement indicates that the reporting module should place
the table of contents for the output report at the start of the
report rather than at the end. By default, the table of contents is placed at the end of the report.
 
<p class="note">This parameter is misnamed: the reporting module no longer needs to make two passes of the data, regardless of where the table of contents is positioned. </p>
 
If you are using XML input to TUNERPTI, the <code><toc></code>
or <code><tableOfContents></code> element
specifies characteristics of the table of contents.
See [[#repfmt|<reportFormat>:  Controlling report format]].
 
===UPper===
<p class="note"><b>Note:</b> This parameter is deprecated. If it is specified as an input parameter, it is ignored.
</p>
This statement indicates that the reporting module should issue
all messages in uppercase only. The default is to issue messages in mixed
case, except on Japanese operating systems, where the default is
to issue messages in uppercase only.
 
This option should be used on systems where mixed-case messages
might not be displayed correctly on terminals or printers.
 
==<b id="xmlrpti"></b>Using XML input for report configuration==
It is recommended that the control parameters
described in [[#cardcfg|Configuration parameters]] be
formatted as an XML document in TUNERPTI. As shown in the example that follows, this XML document is characterized by:
<ul>
<li>A root node, <code><SirtuneInput></code>, whose attributes are report parameters.</li>
 
<li>Optional sub-elements ("child" elements) for other parameters, including <code><reportFormat></code>, which provides output formatting.</li>
 
<li>A <code><report></code> element for each report, specified with appropriate
attributes as described in [[#report|REPort report_desc | NODEFAULT]].</li>
</ul>
 
A sample TUNERPTI input document follows.
The entire set of TUNERPTI XML document element and attribute options
is shown in [[#templt|A template for the XML input]].
<p class="code"><SirtuneInput maxDelay="10" top="100">
  <title>ULSPFPRO on Sirius</title>
  <reportFormat>
    <linesPerPage>55</linesPerPage>
    <charactersPerLine>78</charactersPerLine>
    <tableOfContents>top</tableOfContents>
  </reportFormat>
  <report type="info"/>
  <report type="waittype"/>
  <report type="state"/>
  <report type="sysparm"/>
  <report type="csect" top="100"/>
  <report type="csect" chunk="64" top="100"/>
  <report type="csect" chunk="4" top="100"/>
  <report type="csect" task="maintask" top="100"/>
  <report type="csect" chunk="64" task="maintask" top="100"/>
  <report type="eval" chunk="400" state="wchkpo"/>
  <report type="eval" chunk="4" state="wchkpo"/>
  <report type="eval" state="wbuff"/>
  <report type="eval" chunk="400" state="wbuff"/>
  <report type="eval" chunk="4" state="wbuff"/>
  <report type="whatc"/>
  <report type="whatc" chunk="64"/>
  <report type="servuse" chunk="10000"/>
  <report type="servio"/>
</SirtuneInput>
</p>
 
===<b id="genlfor"></b>General notes on TUNERPTI formatting===
The following notes further describe the format of a TUNERPTI XML document
like the example above.
<ul>
<li>As with all XML, the element and attribute names in a TUNERPTI XML
document are case sensitive. "SirtuneInput" is <b>not</b> validly entered as "SirTuneInPut" or as any other combination of uppercase and lowercase
letters except "SirtuneInput". Element and attribute <i>values</i> are case-insensitive.
<p>
<p>
When multiple sample data sets are concatenated in any way, the [[SirTune Report Generator configuration#dsetlst|DATASET statement]] must be specified in SIRTUNEI to have SIRTUNER use any but the first sample data set in the concatenation.</p></td></tr>
A few of the parameter names are in mixed case, but for ease of coding,
most elements and attributes are restricted to lowercase characters.</p></li>


<tr><th>SIRTUNEO</th>
<li>While multiple reports can be specified on a single line in the
<td>This DD is the data set that should receive SIRTUNER error message or reports. It must have an LRECL greater than or equal to 80.</td></tr>
older control card format, each <code><report></code> element in the XML
input represents a single report.</li>


<tr><th>SIRTUNEI</th>
<li>The configuration parameters <code>top</code>, <code>maxDelay</code>, and
<td>This optional DD contains SIRTUNER statements that alter the SIRTUNER defaults. These statements allow control over which reports are produced and the time interval over which sample data is to be summarized. For a list of available statements, see [[SirTune Report Generator configuration]].
<code>comp31</code> are specified as attributes of the <code><SirtuneInput></code>
document element.
<p>
<p>
SIRTUNEI must have fixed format, that is, <code>RECFM=F</code> or <code>RECFM=FB</code>.</p></td></tr>
The configuration parameters <code>title</code>, <code>range</code>, and
</table>
<code>resolution</code> are specified as sub-elements of
<code><SirtuneInput></code>, and their values are element content.
</p>
<p><code>title</code> can alternately be specified as a sub-element
of <code><reportFormat></code>.</p></li>
 
<li>Parameters affecting the report layout are specified as sub-elements of the <code><reportFormat></code> element.</li>
 
<li>While the old-style card-image input format will continue to be
supported, newer features are only available via XML input. Features such as user-specified characters-per-line and lines-per-page are already available only when using XML input to TUNERPTI.</li>
</ul>
 
===<b id="templt"></b>A template for the XML input===
This is a fully-qualified template for the TUNERPTI input XML document.
It shows the document format and its possible XML elements, attributes, and content.
 
Square brackets (<tt>[ ]</tt>) enclose values you supply.
The type, format, or explicit set of valid options for these values is indicated within the brackets. [[#mainxml|Guidelines for the three main XML elements]] provides additional details.
<p class="code"><SirtuneInput top="[integer]"
              maxDelay="[integer]"
              comp31="[integer]">
 
  <range start="[HH|HH:MM|HH:MM:SS]"
          end="[HH|HH:MM|HH:MM:SS]"
          for="[integer]"
          skip="[integer]" />
 
  <resolution value="[integer]"
            subsys="[subsysname]"
              file="[filename]"
              proc="[procname]" />
 
  <title>[62-character title]</title>
 
  <reportFormat>
    <title>[62-character title]</title>
    <charactersPerLine>[integer]</charactersPerLine>
    <linesPerPage>[integer]</linesPerPage>
    <tableOfContents>[top|bottom|none]</tableOfContents>
  </reportFormat>
 
  <report type="[cfroot|csect|csectm|csects|diskio|info|
                  quad|quadcm|quadcs|servio|servuse|state|
                  summary|sysparm|whatc|whatcm|whatcs|
                  waittype|nodefault]"
          top="[integer]"
          chunk="[total|table|integer]"
          task="[subtask|maintask]"
 
<b>&lt;!--if a REPORT STATE, the following are the "type"--></b>
<b>&lt;!--and "state" attribute options--></b>
          type="[what|comp|load|eval|evali|quad|chunk|
                  ifjob|ifcomp|ifjcomp|iffunc|ifchunk]"
          <b>&lt;!--"state" options include primary states:-></b>
          state="[blkin|blkiu|blkon|blkou|redy|rung|rungm|
                  rungs|swpgi|swpgobn|swpgobu|swpgow|wpst|
                  wtsv|
          <b>&lt;!--composite states:-></b>
                  all|alli|alln|blk|blki|blkn|blko|blku|
                  oservn|oservu|oservw|redyr|runbl|swpg|
                  swpgo|swpgob|
          <b>&lt;!--wait types:-></b>
                  wmisc|wdisk|wusero|wuseri|woperi|wdumpo|
                  wdumpi|wenque|wbuff|wpst|wifam|wsleep|
                  wjrnlo|wchkpo|wwrite|warbmo|wchkpr|wdisk|
                  wdead|wvsami|wlogin|wcfrex|wcfrsh|wvtbuf|
                  wconvi|wconvo|wsctyi|ws$wai|wn$wai|wuldb2|
                  wcfr|wlog|
          <b>&lt;!--critical file resources:-></b>
                  cfrhany|cfrhdir|cfrhind|cfrhexs|cfrhrec|
                  cfrbany|cfrbdir|cfrbind|cfrbexs|cfrbrec]">
</SirtuneInput> </p>
 
===<b id="mainxml"></b>Guidelines for the three main XML elements===
This section shows how to assemble the principal elements of the
XML format supported as control input to <var class="product">SirTune</var>.
 
====<b id="stinput"></b><SirtuneInput>:  Document root element====
The root element (which is the outermost element) of the input XML document is <code><SirtuneInput></code>. The optional report parameters <code>maxDelay</code>, <code>top</code>, and <code>comp31</code> are entered as attributes of this element:
<p class="code"><SirtuneInput maxDelay="10" top="100" comp31="200000">
</p>
 
====<b id="repfmt"></b><reportFormat>:  Controlling report format====
This element is optional; if specified, it must be a child of the document
element. <code><reportFormat></code> contains child elements
that control the formatting of report output. Specifically, you can define the number of lines per page and characters per line, and the position of the table of contents.
For example:
<p class="code"><reportFormat>
  <linesPerPage>0</linesPerPage>
  <charactersPerLine>72</charactersPerLine>
  <tableOfContents>Bottom</tableOfContents>
</reportFormat></p>
<ul>
<li><code><linesPerPage></code> accepts integer values, 0 or greater.
When the reporting module reaches <code>linesPerPage</code> output lines,
a new header is printed and a new page is begun.
A 0 setting turns off paging; in that case, a header line is produced at the beginning of the report only.</li>
 
<li><code><charactersPerLine></code> accepts integer values 40 or larger.
A non-numeric value or a value lower than 40 is converted to 40.
The default value is 78.
<p>
<p>
The following sample EXEC can be used to generate a report with SIRTUNER:</p>  
If the report needs to print a line longer than <code>charactersPerLine</code>,
<p class="code"><nowiki>/* */
the line wraps at <code>charactersPerLine+1</code>.</p></li>
address command
"FILEDEF SIRTUNEI DISK SIRTUNER INPUT A"
"FILEDEF SIRTUNEO DISK SIRTUNER LISTING A"
"FILEDEF SIRTUNED DISK PRODONLN DATA W",
  "(LRECL 512 BLOCK 4000 RECFM VB"


"SIRTUNER"
<li><code><tableOfContents></code> (or its synonym <code><toc></code>) can
be set to <code>Top</code>, <code>Bottom</code>, or <code>None</code>,
specifying the location of the table of contents of the <var class="product">SirTune</var> report.
The default location is the bottom of the report.</li>
</ul>


exit rc
====<b id="indrpt"></b><report>:  Specifying individual reports====
</nowiki></p>
Each report is specified as a single, self-terminating, child element
of <code><SirtuneInput></code>. Report details are specified as attributes of the <code><report></code> element:
<p class="code"><SirtuneInput>
  <report type="csect" chunk="64" task="maintask" top="100"/>
</SirtuneInput>
</p>
All <code><report></code> elements are self-terminating.
All reports except STATE reports are formatted as in the above example:
the report type is specified on the <code>type</code> attribute, and
any sub-parameters are specified (in lowercase) as attributes of
the <code><report></code> element. Report details and sub-parameters are described in [[SirTune reports]].
<p>
STATE reports ([[SirTune reports#repst|REPORT STATE state_name activity]]) are specified with an activity as the <code>type</code> attribute and the user state as
the <code>state</code> attribute, as shown in the following example:</p>
<p class="code"><SirtuneInput>
  <report type="quad" state="cfrbexs"/>
  <report type="eval" state="cfrbany"/>
  <report type="eval" chunk="4" state="rungm"/>
  <report type="evali" state="rung"/>
  <report type="evali" state="rungm"/>
  <report type="comp" state="rung"/>
</SirtuneInput> </p>
<p>
Valid <code>type</code> activity values and <code>state</code> values
are discussed or referred to in [[SirTune reports#repst|REPORT STATE state_name activity]], and they are also summarized in [[#templt|A template for the XML input]]. </p>
<p>
The order in which attributes are specified in the <code><report></code> element is not important.</p>


==See also==
==See also==

Latest revision as of 19:45, 8 August 2017

SirTune reports are generated from jobs that invoke the SIRTUNEREPORT SOUL program (which in turn calls the SirTuneReport method of the Dataset class).

In addition, as of RKTools 7.7, the RKWeb browser interface is equipped to invoke and display SIRTUNEREPORT results. Using RKWeb for SirTune reports requires the same set up of input and output files described on this page.

Report programs

The report generation portion of SirTune consists of two SOUL programs which are distributed in the RKTools SIRIUS file (prior to RKTools version 7.7) or the M204PROC file (as of RKTools 7.7).

The SOUL reporting programs of SirTune are:

SIRTUNEREPORT The "outer" SirTune report program.
SHARED_REPORT Report methods used by SIRTUNEREPORT.

To run SIRTUNEREPORT from a procedure file other than SIRIUS or M204PROC, move both these procedures to the new file, and update the single INCLUDE statement in SIRTUNEREPORT. A few UTABLE and environmental settings are executed at the top of SIRTUNEREPORT. These can be adjusted for performance or functional reasons at the client site.

Report files

SIRTUNEREPORT requires two input files, and it accepts an optional output file. These files, described below, may be specified as DD cards or ALLOCATE statements on the job running SIRTUNEREPORT:

TUNERPTI Input cards that specify the SirTune reports and other run characteristics.

This file may contain older style input, with REPORT, RANGE, RESOLUTION, and other statements, or it may contain newer-style input in XML format. If old-style card images are input, a subroutine in SIRTUNEREPORT converts them to XML. For detailed information about this input, see Report configuration.

TUNERPTI is a required file.

The file format of TUNERPTI is not critical: Since input lines should be shorter than 80 characters, a fixed 80-character file works fine.

TUNERPTD This is the input data to SIRTUNEREPORT.

TUNERPTD is a required file.

This is the same file as SIRTUNED in the SirTune data collection run.

Sample data sets from multiple runs may be concatenated. In fact, sample data sets from multiple runs may even be concatenated sequentially into a single data set (with IEBGENER under MVS, or COPYFILE or an equivalent under CMS) and provided as a single data set to SIRTUNEREPORT.

When multiple sample data sets are concatenated in any way, the DATASET statement (DATaset list) must be provided in TUNERPTI to have TUNERPTR use any but the first sample data set in the concatenation.

TUNERPTO This is the output file for the SIRTUNEREPORT reports.

The SOUL code is currently set to output 72 characters per line, so a fixed or fixed-block file with 80-character records is recommended. The output width for report lines is set by the CPL statement in the TUNERPTI file. If CPL is not set, the output width defaults to 132 characters.

TUNERPTO is an optional file. If it is not present, report output is redirected to standard output; generally, CCAPRINT.

The names of these files are hard-coded in SIRTUNEREPORT, but they may be changed if you run SIRTUNEREPORT from another procedure file and decide to customize it. The names are chosen to differentiate them from the SIRTUNEx names used during SirTune data collection.

Report job

Generally, SIRTUNEREPORT is run as a standalone batch job, though it is perfectly acceptable, if perhaps a little resource-intensive, to dynamically allocate the TUNERPTx files and run it from inside an Online.

A basic TUNERPTR job under z/OS looks like this:

//TUNE JOB (0,0),CLASS=A,MSGCLASS=X //TUNERPT EXEC PGM=BATCH204,REGION=4096K, // PARM='SYSOPT=134,LIBUFF=1000,LOBUFF=1000',TIME=250 //CCASTAT DD DSN=M204.CCASTAT,DISP=SHR //CCATEMP DD DSN=M204.TEMP1,DISP=SHR //CCAJRNL DD DSN=M204.CCAJRNL,DISP=SHR //SIRIUS DD DSN=ULSPF700.SIRIUS,DISP=SHR //TUNERPTI DD DSN=SIRTUNER.REPORT.INPUT,DISP=SHR //TUNERPTD DD DSN=SIRTUNER.DATA.INPUT,DISP=SHR //TUNERPTO DD DSN=SIRTUNER.REPORT.OUTPUT,DISP=SHR //CCAPRINT DD SYSOUT=*,OUTLIM=50000 //CCAIN DD * NFILES=5,NDCBS=5,NDIR=5,MAXBUF=50,NGROUP=5,NORQS=4, X LQTBL=4000,LSTBL=30000,LNTBL=1200,LVTBL=3000 LOGON me mepassword O SIRIUS INCLUDE SIRTUNEREPORT /* //

Notes:

  • For RKTools 7.7 or higher, the SIRIUS file is replaced with the M204PROC file.
  • For an Online job instead of batch, the same SirTune files are allocated: TUNERPTI (report input parameters), TUNERPTD (reporting data), and an optional TUNERPTO (output destination replacing the screen default). The OPEN and INCLUDE commands do not change.
  • Under CMS, a similar Batch204 EXEC can be used to invoke SIRTUNEREPORT.

Report configuration

To customize a SirTune reporting run, you use the DD card named TUNERPTI to specify configuration parameters. These parameters define the characteristics of the reporting run. The card must have fixed format, but it can use either of the following types of input format:

  • Control-card statements
  • XML document format

Using control-card statements

You can specify report configuration parameters in a set of statements (only one per line). There are no line continuations, and a line beginning with an asterisk character (*) is treated as a comment (that is, ignored).

The individual statements are described in Configuration parameters.

An example of control-card statement input follows:

RANGE 9:30 12:30 RESOLUTION 50 REPORT CFRROOT REPORT STATE CFRBANY WHAT MAXD 10 REPORT STATE RUNG QUAD REPORT STATE RUNG EVALI EVAL CHUNK 32 REPORT STATE RUNG CHUNK 4 CHUNK 400 CHUNK 4000 REPORT CSECT TOTAL CHUNK 512 CHUNK 64

Using XML document format

XML-document report parameters are case-sensitive XML elements or attributes contained in a SirtuneInput document node.

Most of the parameters represented as single control-card statements (as described above) are available in XML, but they are represented in lowercase or mixed-case, and some are individual elements while others are attributes of elements. The details about the coding location of each parameter are in Using XML input for report configuration.

Unlike the control-card input format, where multiple variations on a report can be specified on a single line, in XML format each <report> element specifies exactly one report.

Here is an XML version of the control-card example above:

<SirtuneInput maxDelay="10" top="100" title="ULSPFPRO"> <range start="9:30" end="12:30"/> <resolution value="50"/> <reportFormat> <title>Sirtune Reports for ULSPFPRO</title> <charactersPerLine>78</charactersPerLine> <linesPerPage>55</linesPerPage> <tableOfContents>top</tableOfContents> </reportFormat> <report type="cfrroot"/> <report type="what" state="crfbany"/> <report type="quad" state="rung"/> <report type="evali" state="rung"/> <report type="eval" state="rung"/> <report type="eval" state="rung" chunk="32"/> <report type="eval" state="rung" chunk="4"> <report type="eval" state="rung" chunk="400"> <report type="eval" state="rung" chunk="4000"> <report type="csect" chunk="total"/> <report type="csect" chunk="512"/> <report type="csect" chunk="64"/> </SirtuneInput>

Configuration parameters

The following subsections describe the individual parameters you can use to configure a SirTune report. Most of the parameter names and descriptions refer to the control-card statement format, although pertinent XML format information is also provided. For more information about using XML for the control-card input, see Using XML input for report configuration.

Where applicable, the titles of the following subsections also show how to specify the parameter in control-card statement form:

  • The minimum allowable abbreviation for each statement is indicated with uppercase characters, while optional characters are indicated with lowercase.

    Names are case-sensitive, and these name abbreviations are not permitted, in XML-formatted input.

  • Optional statement keywords are enclosed in brackets ([]), and alternatives are separated with a vertical line (|).

CHARACTERSPERLINE or CPL

This statement determines the width of an output report line. For example, either of the following statements sets the report output width to 80 characters:

CHARACTERSPERLINE 80 CPL 80

Valid line-width values are integers between 78 and 256. If a value outside this range is specified, CPL is set to 132.

If you are using XML input to TUNERPTI, the <cpl> or <charactersPerLine> element specifies the line width. For more information about this, see <reportFormat>: Controlling report format.

COMP31

Note: This parameter can only be specified when using XML input to TUNERPTI, and it is valid only for Model 204 V6R3 and later. COMP31 indicates the maximum compilation-table size for a procedure that is to be stored in 31-bit storage. Above this size, compilations are moved to 64-bit storage. The default value is X'1FFFF', or 131,071. COMP31 is specified as an attribute on the SirtuneInput element (see Using XML input for report configuration). For example:

<SirtuneInput maxDelay="10" comp31="200000">

The size of a saved compilation table for a procedure is the size of the procedure in QTBL bytes, divided by the minimum QTBL chunk size, times 20:

(QTBLsize/QTBLchunk)*20

If a procedure's QTBL is 20,000 bytes and the smallest chunk size requested in a report is 200, this procedure will require (20,000/200)*20, or 2,000 bytes. More common are procedure sizes of around 800,000 bytes, with a chunk size of 4, theoretically requiring (800,000/4)*20, or 4,000,000 bytes. This is actually an upper bound, as you never get more than one chunk per line, and few lines of code generate only 4 bytes of QTBL. More typical is about 40 bytes per chunk (even with a chunk size of 4), which produces a compiled table of 200,000.

There is no reason to set COMP31 unless your site is running out of 31-bit storage under Model 204 V6R3 or later. Prior to V6R3, Model 204 did not support 64-bit storage, so comp31 has no effect.

Note: The CURREP31, CURREP64, HGHREP31, and HGHREP64 system parameters indicate the current and greatest amounts of 31-bit and 64-bit virtual storage used for a report. The MAXREP31 and MAXREP64 parameters indicate the maximum amount allowed.

DATaset list

Note: This parameter is deprecated. If it is specified as an input parameter, it is ignored.

The DATASET statement indicates which sample data sets that make up SIRTUNED are to be included in the report. A separate INFO report is produced for each data set selected, and all samples from the selected data sets are combined to produce composite results for other reports. Data sets are processed in order: if a data set is selected and causes some TUNR error message, reporting ends without proceeding to other data sets.

If the DATASET statement is not specified, only the first sample data set is included in the report. This is true even if multiple sample data sets were physically concatenated into a single data set with IEBGENER or COPYFILE before being passed to the reporting module.

The list value is a list of data set numbers or ranges of numbers. For example, the following indicates that data sets 1 through 4 are to be used:

DATASET 1-4

The following indicates that data sets 2, 4, and 5 through 6 are to be used:

DATASET 2 5-6 4

More than one DATASET statement can appear in SIRTUNEI, and their effect is cumulative, so:

DATASET 2 DATASET 4-6

Is the same as:

DATASET 2 4-6

If an asterisk (*) character appears after a DATASET statement, all data sets are used in the report. Thus the following:

DATASET 1 3-5 8 *

is the same as:

DATASET *

since in both cases, all data sets are used in the report.

There is no harm in specifying data set numbers greater than the number of sample data sets in SIRTUNED, though of course, these data set numbers will not be included in the report.

RANGE, SKIP, and FOR statements operate individually on each component sample data set in a concatenation. For example, suppose SIRTUNED consists of three concatenated sample data sets collected over the following dates and times:

Dataset 1 January 5 at 5:30 AM through January 8 at 11:00 PM
Dataset 2 January 10 at 1:00 PM through January 15 at 10:00 PM
Dataset 3 January 11 at 5:00 AM through January 14 at 10:00 PM

In this example, data sets 2 and 3 are associated with two different Onlines that run concurrently. The SIRTUNEI statements:

RANGE 11:00 12:00 SKIP 3 FOR 2 DATASET 1-3

result in the range of 11:00 AM to 12:00 noon being used on the following days for each data set:

Dataset 1 January 8
Dataset 2 January 14-15
Dataset 3 January 14-15

To determine the time ranges and characteristics of each individual data set in a concatenation, simply run a report against the concatenated SIRTUNED with the following commands in SIRTUNEI:

REPORT NODEFAULT REPORT INFO

It should be possible to produce most SirTune reports with any concatenation of data sets. There are certain reports, however, that require all sample data sets to have been produced with some consistency among the Onlines. These reports are:

CSECT? The Model 204 load modules must be identical among runs (except for ZAPs or Early Warnings).
STATE ???? QUAD The Model 204 load modules must be from the same release and must have run with identical $function tables.
SERVIO The OnlineS must have run with identical numbers of server data sets (CCASERVR, CCASERV1, etc.).
STATE RUNGM/RUNGS The Onlines must have all run with NMPSUBS greater than 0 (the MP/204 feature is turned on).

Even though all other reports are allowed for concatenated sample data sets, use caution when interpreting the results. It is up to you interpret how changes between runs could affect the results. These changes might include:

  • SOUL code changes
  • Changes in Model 204 parameters
  • Changes in the Model 204 load module
  • Changes in SirTune parameters
  • Number of samples collected in each sample data set

In general, it is unlikely that concatenating data sets collected in different environments or many months apart will produce meaningful reports.

Suppose, under MVS, the SIRTUNER or SIRTUNEREPORT job logically concatenates five sample data sets associated with the five weekdays as follows:

//SIRTUNED DD DSN=SIRTUNE.SAMPLE.MON,DISP=SHR // DD DSN=SIRTUNE.SAMPLE.TUE,DISP=SHR // DD DSN=SIRTUNE.SAMPLE.WED,DISP=SHR // DD DSN=SIRTUNE.SAMPLE.THU,DISP=SHR // DD DSN=SIRTUNE.SAMPLE.FRI,DISP=SHR

To produce a report for Tuesday and Wednesday, specify the following input statements:

DATASET 2 3

LINESPERPAGE or LPP

This statement determines the page length for report output. Any integer value is valid.

A header is printed at the top of each page. If 0, the default, is specified, no paging is performed, and headers are output at the beginning of each report.

For example, either of the following statements sets report page length to 55 lines:

LINESPERPAGE 55 LPP 55

When 55 lines have been printed, SIRTUNEREPORT prints a new header and resets the line counter to 0.

If you are using XML input to TUNERPTI, the <lpp> or <linesPerPage> element specifies the report page length. For more information about this, see <reportFormat>: Controlling report format.

MAPcore

Note: This parameter is deprecated. If it is specified as an input parameter, it is ignored.

When used in a CSECT breakdown report, this statement allows analysis of instructions outside the loaded Model 204 module.

MAXDelay max_msec

This statement makes it possible to change the criterion used by the reporting module to determine if a sample should be discarded.

When the delay between the time a sample was supposed to be collected and the time it actually was collected is greater than max_msec milliseconds, the sample is assumed to be biased and hence discarded. The default for max_msec is 10, which means that any sample that is delayed by more than 10 milliseconds from its intended time is discarded.

If it is felt that reports are biased, with I/O producing instructions appearing unbelievably frequently in the RUNG state (obviously, this is very subjective), it might be worth reducing MAXDELAY to 1 with the following statement:

MAXDELAY 1

If there was indeed a bias, one would expect after this change to see more samples discarded and the percentages for the RUNG state to change for certain procedures and chunks of procedures.

If, on the other hand, SirTune was running in an environment where the Online was getting relatively slow service from the operating system, almost all samples might be discarded by the reporting module. In this situation, it might be worth increasing MAXDELAY to accept more samples, with the understanding that this might introduce biases in the reported data.

To increase MAXDELAY to 1000 milliseconds (1 second), enter this statement:

MAXDELAY 1000

Generally, setting MAXDELAY greater than 100 is likely to produce severe biases in Sirtune reports.

MIXed

Note: This parameter is deprecated. If it is specified as an input parameter, it is ignored.

This statement indicates that the reporting module should issue all reports in mixed case. The default is to issue messages in mixed case, except on Japanese operating systems. On these systems, the default is to issue all messages in uppercase only. This option should be used on Japanese operating systems when mixed case messages are desired.

MPVirt

Note: This parameter is deprecated. If it is specified as an input parameter, it is ignored.

This statement has meaning only if generating a report for data collected in an Online running MP/204. It indicates that a running user is considered to be running in parallel if it is in virtual or logical parallel mode, whether or not it is actually running in an offload subtask. By default, the SirTune reports only consider a user to be running in parallel if it is actually running on an offload subtask.

The MPVIRT statement is useful for estimating the "offloadability" of SOUL code in systems that are not busy enough to force all offloadable code into a subtask.

Note: MPVIRT only has an effect on reports that are specific to states RUNGM or RUNGS.

It is not possible to split the reports in a run of SirTune so that some are generated with MPVIRT set and others are not. If MPVIRT appears anywhere in the input stream, all reports from that reporting run are generated using the MPVIRT option, whether the REPORT statements appear before or after the MPVIRT statement.

NOSeq

Note: This parameter is deprecated. If it is specified as an input parameter, it is ignored.

This statement indicates that the reporting module should not consider characters in columns 73 through 80 of SIRTUNEI as part of its input. If the input file has RECFM=F and LRECL=80, the reporting module ordinarily assumes that characters in columns 73 through 80 are sequence numbers and ignores them. If the input stream has any other format, the reporting module considers all characters in the input record as part of the control statements.

RANge start_time end_time [FOR for_num] [SKIP skip_num]

This statement makes it possible to limit the reports to a subset of the collected sample data. This is useful for solving performance problems that have different characteristics during different times of the day.

start_time and end_time can have the format HH, HH:MM, or HH:MM:SS, where HH represents an hour of the day, MM represents minutes, and SS represents seconds. The maximum allowable time is 24 or 24:00 or 24:00:00, which corresponds to midnight.

For example, the following statement indicates that only sample data collected in the first 1 PM to 3 PM range in the run should be used to generate the reports:

RANGE 13 15

When using XML format, RANGE is specified in lowercase as a child element of the document element, with "start", "end", "skip", and "for" as optional attributes:

<SirtuneInput top="50"> <range start="13" end="15">

If the run came up in the middle of the specified range, the time from the start of the run to the end of the range is considered the first range. In the preceding example, if the run came up at 2:30 PM, the first range would extend from 2:30 PM to 3 PM. The following example indicates that only sample data collected in the first 11:30 AM to 1:30 PM range in the run should be used to generate the reports:

RANGE 11:30 13:30

This example indicates that only sample data collected in the first 30 seconds before 12 noon through 50 seconds after 1 PM range in the run should be used to generate the reports:

RANGE 11:59:30 13:00:50

If start_time is greater than end_time, the times are assumed to wrap. For example. the following statement indicates that only sample data collected in the first 11:00 PM to 1:00 AM range in the run should be used to generate the reports:

RANGE 23:00 1:00

If sample data for a run was collected over more than 24 hours, a range might occur more than once in the sample data set. Ordinarily, only the first range is included in the reports. To include a specific number of occurrences of the indicated range, the FOR clause should be included on the RANGE statement, followed by for_num, where for_num can be either a whole number or an asterisk (*). A whole number indicates the number of occurrences of the range are to be included in the report. An asterisk indicates that all occurrences of the range are to be included in the report.

For example, the following statement indicates that the first 5 9:30 AM to 11:30 AM ranges are to be included in the reports:

RANGE 9:30 11:30 FOR 5

The data in these ranges are combined to produce a single set of reports. The following statement indicates that all 10 AM to 3 PM ranges are to be included in the report:

RANGE 10 15 FOR *

To exclude the first occurrence or occurrences of the indicated range from the reports, include the SKIP clause on the RANGE statement, followed by skip_num (where skip_num must be a non-negative integer indicating the number of occurrences of the indicated range to skip). For example, to indicate that the second 10 AM to 12 noon range is to be included in the reports:

RANGE 10 12 SKIP 1

To indicate that the third, fourth, and fifth 1:30 PM to 3:30 PM ranges are to be included in the reports:

RANGE 13:30 15:30 SKIP 2 FOR 3

While multiple RANGE statements may be specified only the last one is used when specified as control cards. Conversely, only the first one is used when specified in XML input Thus:

RANGE 9:30 11:30 RANGE 13:30 15:30

is functionally equivalent to:

RANGE 13:30 15:30

The position of RANGE statements relative to other statements is irrelevant.

REPort report_desc | NODEFAULT

This statement either requests a specified report or reports, or it indicates that the default reports are not to be generated (REPORT NODEFAULT). The actual reports that can be requested are listed in SirTune reports.

If REPORT NODEFAULT is specified, it must be the first REPORT statement in the input stream (if input is XML formatted, the position of REPORT NODEFAULT is not critical).

The default reports produced by SIRTUNEI are the ones that are produced by the following statements:

REPORT INFO REPORT SUMMARY REPORT STATE RUNG WHAT EVAL CHUNK 4000 REPORT STATE RUNG EVAL CHUNK 400 CHUNK 4

In XML format, these default reports are specified like this:

<SirtuneInput maxDelay="10" top="50"> <report type="info"> <report type="state"> <report type="waittype"> <report type="what" state="rung"> <report type="eval" state="rung"> <report type="eval" state="rung" chunk="4000"> <report type="eval" state="rung" chunk="400"> <report type="eval" state="rung" chunk="4"> </SirtuneInput>

For more information about XML formatting for an individual report, see <report>: Specifying individual reports.

RESolution res_num [PROC pname] [FILE fname] [SUBSYS sname]

This statement makes it possible to reduce the reporting module's virtual storage utilization at the cost of reducing the resolution possible in producing procedure chunk reports. This statement should be of interest only to users for whom virtual and real storage use is a major concern.

Note: The CURREP31, CURREP64, HGHREP31, and HGHREP64 Model 204 system parameters indicate the current and greatest amounts of 31-bit and 64-bit virtual storage used for a report. The MAXREP31 and MAXREP64 parameters indicate the maximum amount allowed.

Storage use by the reporting module is directly related to the total number of chunks for all procedures for which compilation information is saved. The number of chunks required for each such procedure is inversely related to its minimum resolution. Thus by increasing the minimum resolution for a procedure, it is possible to decrease the amount of virtual storage used for that procedure. The default resolution for all procedures is 4.

The res_num value specifies the minimum chunk resolution in QTBL bytes for all or the indicated procedures. For a discussion of chunks and resolution, see REPORT STATE state_name activity.

If not followed by any other keywords, this statement sets the default minimum resolution for all procedures. For example, this sets the default minimum resolution for all procedures to 100:

RESOLUTION 100

There can be an unlimited number of this kind of RESOLUTION statements, but only the last one is used to set the default minimum resolution when the input stream is formatted as control cards. When XML input is used, only the first RESOLUTION statement is used. Thus:

RESOLUTION 50 RESOLUTION 100 RESOLUTION 150

is functionally equivalent to:

RESOLUTION 150

Likewise, this XML input:

<resolution value="150"> <resolution value="100"> <resolution value="50">

is functionally equivalent to:

<resolution value="150">

res_num may optionally be followed by one or more keywords (PROC, FILE, or SUBSYS), with each keyword followed by a resolution that applies only to procedures that meet the keyword's criterion. For example, this statement indicates that a resolution of 1000 should be used for all procedures in subsystem HOHO:

RESOLUTION 1000 SUBSYS HOHO

Using XML input, the keywords are the same except in lowercase:

<resolution value="1000" subsys="HOHO">

This statement indicates that a resolution of 500 should be used for all procedures in procedure file PROCA:

RESOLUTION 500 FILE PROCA

Or, in XML mode:

<resolution value="500" file="PROCA">

The following indicates that a resolution of 700 should be used for the procedure named PRE-PROC.A:

RESOLUTION 700 PROC PRE-PROC.A

Wildcards can also be used. To indicate that a resolution of 100 should be used for any procedure whose name begins with PRE-, you can specify:

RESOLUTION 100 PROC PRE-*

The following statement indicates that a resolution of 300 should be used for any procedure in a subsystem whose name ends with XREF:

RESOLUTION 300 SUBSYS *XREF

For more details on the use of wildcards, see SirTune statement wildcards.

More than one condition can be specified on a single RESOLUTION statement, in which case the resolution specified applies only to procedures that match all the keyword criteria. For example, the following statement sets a resolution of 1000 for any procedure whose name ends in TEST and is in a procedure file whose name begins with SIR:

RESOLUTION 1000 FILE SIR* PROC *TEST

In XML mode, the previous statement is:

<resolution value="1000" file="SIR*" proc="*TEST">

An unlimited number of qualified RESOLUTION statements may appear in the report configuration input. If more than one does occur in the input stream, each procedure for which compilation data is encountered is compared against each RESOLUTION statement, in the order in which they appear. As soon as a match is found, the resolution is set for the procedure, and no more RESOLUTION statements are scanned.

Thus, if SIRTUNEI contains:

RESOLUTION 1000 SUBSYS SIR* RESOLUTION 500 FILE TEST* RESOLUTION 200 PROC *TEMP*

any procedure in a subsystem whose name begins with SIR would have a resolution of 1000, even if it ran out of a procedure file whose name begins with TEST, or if the procedure name contains the characters T E M P.

The resolution used for specific procedures with the resolution statements in the preceding example are listed below:

SubsystemProcfileProcedure nameResolution
TOOLSYSGENFILEBOP.PROD.Ldefault
SIRJUNKJUNKPROCP.JUNK.PROC1000
BIGSYSTESTFILEP.BARTLIST500
BIGSYSPROCXEXPER.TEMP.P200
SIRJUNKTESTFILEP.BARTLIST1000
SIRJUNKPROCXEXPER.TEMP.P1000
BIGSYSTESTFILEEXPER.TEMP.P500
SIRJUNKTESTFILEEXPER.TEMP.P1000

The suggested use of the RESOLUTION command is that the default is left at 4 and that resolution is set to a high value for procedures that are known to be compiled but are not likely to show much activity. If one or more of these procedures shows up on a CHUNK report at a resolution smaller than that set by the RESOLUTION commands for the procedures, do either of the following to explicitly set the resolution at a lower value for the procedures that appear on the CHUNK report:

  • Modify the RESOLUTION command.
  • Add extra RESOLUTION commands.

For example, suppose the following statement is specified, and a procedure named PRE.JUNK.PROC in subsystem TEST appears on a report for chunk size 100:

RESOLUTION 400 SUBSYS TEST

Since the minimum chunk size that SIRTUNER or SIRTUNEREPORT can use for procedures in subsystem TEST is 400 (because of the RESOLUTION statement), the report with chunk size 100 is comparing chunks of size approximately 100 with a chunk of size 400 in PRE.JUNK.PROC. Thus, a much larger segment of code is being totalled for PRE.JUNK.PROC than other procedures on this report, making this procedure look more important than it really is.

To correct this situation, you can do either of these:

  • Remove the RESOLUTION statement from SIRTUNEI or TUNERPTI and lose its virtual storage savings benefits.
  • Add another RESOLUTION statement to override the subsystem wide RESOLUTION statement for the specific procedure in question.

The following sequence would accomplish this:

RESOLUTION 4 SUBSYS TEST PROC PRE.JUNK.PROC RESOLUTION 400 SUBSYS TEST

TITle title_string

This command makes it possible to specify a title to appear on the top line of each page of the SirTune report. The default for title_string is SIRTUNE.

TITLE makes it easy to distinguish the output from multiple SIRTUNER reports. The title string can be made up of an arbitrary number of characters, including blanks. Only the first 62 characters of title_string are used to generate the title.

An example of a valid TITLE statement follows:

TITLE Production run after first round of changes

If using XML input, you can specify the title as a child element of the document node, like this:

<SirtuneInput> <title>Sirtune June 16, 2010 for THX1138</title> ...

Or you can specify the title as a child element of the reportFormat node, like this:

<SirtuneInput> <reportFormat> <title>Sirtune June 16, 2010 for THX1138</title> </reportFormat ...

If specified in both places, the child element of reportFormat will override the child element of the document node. The reporting module only pays attention to the first title specified in either location in the input document.

TOP num_top

This statement specifies the number of top entities to be displayed on any report that ranks multiple entities. The default for num_top is 50. This default can be overridden by a TOP keyword on a REPORT statement.

For example, if you want to report on the top 100 procedures or chunks of procedures on all reports, place this statement in the input stream:

TOP 100

Or, with XML input, enter top as an attribute on the document node:

<SirtuneInput top="100">

Generally, it is not profitable to look at anything past the top 50 entities in any report, since less than 2% of resource usage can be attributed to any entity not in the top 50. It is generally not worth optimizing something that accounts for so little resource usage.

TABLEOFCONTENTS or TOC

This statement determines whether a table of contents is produced and where it is placed in the report. Although TWOPASS can still be used to specify the table of contents placement, the TABLEOFCONTENTS statement provides more control.

Valid values for TABLEOFCONTENTS are TOP, BOTTOM and NONE. By default, the table of contents is placed at the end of the report.

If you are using XML input to TUNERPTI, the <toc> or <tableOfContents> element specifies characteristics of the table of contents. For more information, see <reportFormat>: Controlling report format.

TWOpass

This statement indicates that the reporting module should place the table of contents for the output report at the start of the report rather than at the end. By default, the table of contents is placed at the end of the report.

This parameter is misnamed: the reporting module no longer needs to make two passes of the data, regardless of where the table of contents is positioned.

If you are using XML input to TUNERPTI, the <toc> or <tableOfContents> element specifies characteristics of the table of contents. See <reportFormat>: Controlling report format.

UPper

Note: This parameter is deprecated. If it is specified as an input parameter, it is ignored.

This statement indicates that the reporting module should issue all messages in uppercase only. The default is to issue messages in mixed case, except on Japanese operating systems, where the default is to issue messages in uppercase only.

This option should be used on systems where mixed-case messages might not be displayed correctly on terminals or printers.

Using XML input for report configuration

It is recommended that the control parameters described in Configuration parameters be formatted as an XML document in TUNERPTI. As shown in the example that follows, this XML document is characterized by:

  • A root node, <SirtuneInput>, whose attributes are report parameters.
  • Optional sub-elements ("child" elements) for other parameters, including <reportFormat>, which provides output formatting.
  • A <report> element for each report, specified with appropriate attributes as described in REPort report_desc | NODEFAULT.

A sample TUNERPTI input document follows. The entire set of TUNERPTI XML document element and attribute options is shown in A template for the XML input.

<SirtuneInput maxDelay="10" top="100"> <title>ULSPFPRO on Sirius</title> <reportFormat> <linesPerPage>55</linesPerPage> <charactersPerLine>78</charactersPerLine> <tableOfContents>top</tableOfContents> </reportFormat> <report type="info"/> <report type="waittype"/> <report type="state"/> <report type="sysparm"/> <report type="csect" top="100"/> <report type="csect" chunk="64" top="100"/> <report type="csect" chunk="4" top="100"/> <report type="csect" task="maintask" top="100"/> <report type="csect" chunk="64" task="maintask" top="100"/> <report type="eval" chunk="400" state="wchkpo"/> <report type="eval" chunk="4" state="wchkpo"/> <report type="eval" state="wbuff"/> <report type="eval" chunk="400" state="wbuff"/> <report type="eval" chunk="4" state="wbuff"/> <report type="whatc"/> <report type="whatc" chunk="64"/> <report type="servuse" chunk="10000"/> <report type="servio"/> </SirtuneInput>

General notes on TUNERPTI formatting

The following notes further describe the format of a TUNERPTI XML document like the example above.

  • As with all XML, the element and attribute names in a TUNERPTI XML document are case sensitive. "SirtuneInput" is not validly entered as "SirTuneInPut" or as any other combination of uppercase and lowercase letters except "SirtuneInput". Element and attribute values are case-insensitive.

    A few of the parameter names are in mixed case, but for ease of coding, most elements and attributes are restricted to lowercase characters.

  • While multiple reports can be specified on a single line in the older control card format, each <report> element in the XML input represents a single report.
  • The configuration parameters top, maxDelay, and comp31 are specified as attributes of the <SirtuneInput> document element.

    The configuration parameters title, range, and resolution are specified as sub-elements of <SirtuneInput>, and their values are element content.

    title can alternately be specified as a sub-element of <reportFormat>.

  • Parameters affecting the report layout are specified as sub-elements of the <reportFormat> element.
  • While the old-style card-image input format will continue to be supported, newer features are only available via XML input. Features such as user-specified characters-per-line and lines-per-page are already available only when using XML input to TUNERPTI.

A template for the XML input

This is a fully-qualified template for the TUNERPTI input XML document. It shows the document format and its possible XML elements, attributes, and content.

Square brackets ([ ]) enclose values you supply. The type, format, or explicit set of valid options for these values is indicated within the brackets. Guidelines for the three main XML elements provides additional details.

<SirtuneInput top="[integer]" maxDelay="[integer]" comp31="[integer]"> <range start="[HH|HH:MM|HH:MM:SS]" end="[HH|HH:MM|HH:MM:SS]" for="[integer]" skip="[integer]" /> <resolution value="[integer]" subsys="[subsysname]" file="[filename]" proc="[procname]" /> <title>[62-character title]</title> <reportFormat> <title>[62-character title]</title> <charactersPerLine>[integer]</charactersPerLine> <linesPerPage>[integer]</linesPerPage> <tableOfContents>[top|bottom|none]</tableOfContents> </reportFormat> <report type="[cfroot|csect|csectm|csects|diskio|info| quad|quadcm|quadcs|servio|servuse|state| summary|sysparm|whatc|whatcm|whatcs| waittype|nodefault]" top="[integer]" chunk="[total|table|integer]" task="[subtask|maintask]" <!--if a REPORT STATE, the following are the "type"--> <!--and "state" attribute options--> type="[what|comp|load|eval|evali|quad|chunk| ifjob|ifcomp|ifjcomp|iffunc|ifchunk]" <!--"state" options include primary states:-> state="[blkin|blkiu|blkon|blkou|redy|rung|rungm| rungs|swpgi|swpgobn|swpgobu|swpgow|wpst| wtsv| <!--composite states:-> all|alli|alln|blk|blki|blkn|blko|blku| oservn|oservu|oservw|redyr|runbl|swpg| swpgo|swpgob| <!--wait types:-> wmisc|wdisk|wusero|wuseri|woperi|wdumpo| wdumpi|wenque|wbuff|wpst|wifam|wsleep| wjrnlo|wchkpo|wwrite|warbmo|wchkpr|wdisk| wdead|wvsami|wlogin|wcfrex|wcfrsh|wvtbuf| wconvi|wconvo|wsctyi|ws$wai|wn$wai|wuldb2| wcfr|wlog| <!--critical file resources:-> cfrhany|cfrhdir|cfrhind|cfrhexs|cfrhrec| cfrbany|cfrbdir|cfrbind|cfrbexs|cfrbrec]"> </SirtuneInput>

Guidelines for the three main XML elements

This section shows how to assemble the principal elements of the XML format supported as control input to SirTune.

<SirtuneInput>: Document root element

The root element (which is the outermost element) of the input XML document is <SirtuneInput>. The optional report parameters maxDelay, top, and comp31 are entered as attributes of this element:

<SirtuneInput maxDelay="10" top="100" comp31="200000">

<reportFormat>: Controlling report format

This element is optional; if specified, it must be a child of the document element. <reportFormat> contains child elements that control the formatting of report output. Specifically, you can define the number of lines per page and characters per line, and the position of the table of contents. For example:

<reportFormat> <linesPerPage>0</linesPerPage> <charactersPerLine>72</charactersPerLine> <tableOfContents>Bottom</tableOfContents> </reportFormat>

  • <linesPerPage> accepts integer values, 0 or greater. When the reporting module reaches linesPerPage output lines, a new header is printed and a new page is begun. A 0 setting turns off paging; in that case, a header line is produced at the beginning of the report only.
  • <charactersPerLine> accepts integer values 40 or larger. A non-numeric value or a value lower than 40 is converted to 40. The default value is 78.

    If the report needs to print a line longer than charactersPerLine, the line wraps at charactersPerLine+1.

  • <tableOfContents> (or its synonym <toc>) can be set to Top, Bottom, or None, specifying the location of the table of contents of the SirTune report. The default location is the bottom of the report.

<report>: Specifying individual reports

Each report is specified as a single, self-terminating, child element of <SirtuneInput>. Report details are specified as attributes of the <report> element:

<SirtuneInput> <report type="csect" chunk="64" task="maintask" top="100"/> </SirtuneInput>

All <report> elements are self-terminating. All reports except STATE reports are formatted as in the above example: the report type is specified on the type attribute, and any sub-parameters are specified (in lowercase) as attributes of the <report> element. Report details and sub-parameters are described in SirTune reports.

STATE reports (REPORT STATE state_name activity) are specified with an activity as the type attribute and the user state as the state attribute, as shown in the following example:

<SirtuneInput> <report type="quad" state="cfrbexs"/> <report type="eval" state="cfrbany"/> <report type="eval" chunk="4" state="rungm"/> <report type="evali" state="rung"/> <report type="evali" state="rungm"/> <report type="comp" state="rung"/> </SirtuneInput>

Valid type activity values and state values are discussed or referred to in REPORT STATE state_name activity, and they are also summarized in A template for the XML input.

The order in which attributes are specified in the <report> element is not important.

See also