SirTune Report Generator configuration: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
m (page content merged into "SirTune report generation" page)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<!--Page automatically generated by CMSTOWIK EXEC and will be
#REDIRECT [[SirTune report generation#Report configuration]]
** automatically replaced ** -- any manual edits will be lost.
You've been warned.  ..  (Page built by JAL at the SIRIUS VM; file: FUNPGNEW SYSUT2) -->
<!-- Page name: Sirtune Report Generator configuration -->
<p></p>
An optional DD card allows the reporting run to be customized.
For <var class="product">SirTune</var> 7.2, using the SIRTUNEREPORT &ul. program to generate
reports, this DD card is named <code>TUNERPTI</code>.
For <var class="product">SirTune</var> versions 6.9 and older, using the SIRTUNER module,
the DD card is named <code>SIRTUNEI</code>.
<p></p>
This input card must have fixed format, and it must
use report configuration parameters specified in
either of the
following types of input format to define the
characteristics of the reporting run:
<ul>
<li>Control-card statements
<p></p>
Report configuration parameters are specified in a set of statements
(only one per line).
There are no line continuations, and a line beginning
with an asterisk character (<code>*</code>) is treated as a comment (that is,
ignored).
<p></p>
The individual statements are described in [[#cardcfg|Configuration parameters]].
<p></p>
<p></p>
An example of control-card statement input follows:
<p class="code"><nowiki>  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
</nowiki></p>
<li>XML document format (must be <var class="product">SirTune</var> 7.2 or later)
<p></p>
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>
<p></p>
Here is an XML version of the control-card example above:
<p class="code"><nowiki>  <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>
</nowiki></p>
</ul>
 
<div id="cardcfg"></div>
==Configuration parameters==
<!--Caution: <div> above-->
 
<p></p>
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 that was the only control-card option
prior to <var class="product">SirTune</var> version 7.2, 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]].
<p></p>
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></p>
Names are case-sensitive and these name abbreviations are not permitted
in XML-formatted input.
<li>Optional statement keywords are enclosed in brackets (<code>[</code><code>]</code>),
and alternatives are separated with a vertical line (<code>|</code>).
</ul>
 
<div id="charper"></div>
===CHARACTERSPERLINE or CPL===
<!--Caution: <div> above-->
 
<p></p>
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:
<p class="code"><nowiki>CHARACTERSPERLINE 80
 
CPL 80
</nowiki></p>
Valid line-width values are integers between 78 and 256.
If a value outside this range is specified, CPL is set to 132.
<p></p>
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]].
 
<div id="comp31"></div>
===comp31===
<!--Caution: <div> above-->
 
<p></p>
Status: This parameter is new for Version 7.2.
It can only be specified
when using XML input to TUNERPTI, and it is only valid for <var class="product">Model 204</var> V6R3
and later.
<p></p>
comp31 indicates the maximum
size of compilation table for a procedure that will 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.
<p></p>
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"><nowiki><SirtuneInput maxDelay="10" comp31="200000">
</nowiki></p>
<p></p>
<p></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"><nowiki>(QTBLsize/QTBLchunk)*20
</nowiki></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 (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.</p>
<p>
There is no reason to set comp31 unless your site is running out of
31-bit storage under <var class="product">Model 204</var> V6R3 or later.
Prior to V6R3, <var class="product">Model 204</var> did not support 64-bit storage, so comp31
has no effect.</p>
<p class="note"><b>Note:</b> 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.
For more information, see [[List of Model 204 parameters]].
</p>
 
<div id="dsetlst"></div>
===DATaset list===
<!--Caution: <div> above-->
 
Status: This parameter is deprecated as of Version 7.2.
If it is specified as an input parameter, it is ignored.
<p>
This statement indicates which sample datasets that make up SIRTUNED
are to be included in the report. A separate <code>INFO</code> report is produced for each dataset selected, and all samples from the selected datasets are combined to produce composite
results for other reports. Datasets are processed in order: if a dataset is selected and causes some TUNR error message, reporting ends without proceeding to other datasets.
</p>
<p>
If the DATASET statement is not specified,
only the first sample dataset is included in the report.
This is true even if multiple sample datasets were physically concatenated into a single
dataset with IEBGENER or COPYFILE before being passed to the reporting module.
</p>
<p>
The <i>list</i> value is a list of dataset numbers or ranges of numbers.
For example, the following indicates that datasets 1 through 4 are to be used:</p>
<p class="code"><nowiki>DATASET 1-4
</nowiki></p>
<p>
The following indicates that datasets 2, 4, and 5 through 6 are to be used:</p>
<p class="code"><nowiki>DATASET 2 5-6 4
</nowiki></p>
<p>
More than one DATASET statement can appear in SIRTUNEI, and
their effect is cumulative, so:</p>
<p class="code"><nowiki>DATASET 2
DATASET 4-6
</nowiki></p>
<p>
is the same as:</p>
<p class="code"><nowiki>DATASET 2 4-6
</nowiki></p>
<p>
If an asterisk (<code>*</code>) character appears after a DATASET statement,
all datasets are used in the report. Thus the following:</p>
<p class="code"><nowiki>DATASET 1 3-5 8 *
</nowiki></p>
<p>
is the same as:</p>
<p class="code"><nowiki>DATASET *
</nowiki></p>
<p>since in both cases, all datasets are used in the report.
</p>
<p>
There is no harm in specifying dataset numbers greater than the number
of sample datasets in SIRTUNED, though of course, these dataset numbers
will not be included in the report.</p>
<p>
RANGE, SKIP, and FOR statements operate individually on each component
sample dataset in a concatenation. For example, suppose SIRTUNED
consists of three concatenated sample datasets 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, datasets <code>2</code> and <code>3</code> are
associated with two different Onlines that run concurrently.
The SIRTUNEI statements:
<p class="code"><nowiki>RANGE 11:00 12:00 SKIP 3 FOR 2
DATASET 1-3
</nowiki></p>
would result in the range of 11:00 AM to 12:00 noon being used on the
following days for each dataset:
<table class="thJustBold">
<tr><th>Dataset 1</th><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
dataset in a concatenation, simply run a report against the concatenated
SIRTUNED with the following commands in SIRTUNEI:</p>
<p class="code"><nowiki>REPORT NODEFAULT
REPORT INFO
</nowiki></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 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 datasets (CCASERVR, CCASERV1, etc.).</td></tr>
 
<tr><th>STATE RUNGM/RUNGS</th><td>The OnlineS must have all run with NMPSUBS greater than 0 (the MP 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>User Language code changes
<li>Changes in <var class="product">Model 204</var> parameters
<li>Changes in the <var class="product">Model 204</var> load module
<li>Changes in <var class="product">SirTune</var> parameters
<li>Number of samples collected in each sample data set
</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 datasets associated with the 5 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 simply code
the following input statements:</p>
<p class="code"><nowiki>DATASET 2 3
</nowiki></p>
 
<div id="lineper"></div>
===LINESPERPAGE or LPP===
<!--Caution: <div> above-->
 
<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>
 
<div id="mapcore"></div>
===MAPcore===
<!--Caution: <div> above-->
 
Status: This parameter is deprecated as of Version 7.2.
If it is specified as an input parameter, it is ignored.
<p>
When used in a CSECT breakdown report,
this statement allows analysis of instructions outside the loaded <var class="product">Model 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 <i>max_msec</i> milliseconds,
the sample is assumed to be biased and hence discarded.
The default for <i>max_msec</i> is 10, which means that any sample
that was delayed by more than 10 milliseconds from its intended time
will be 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 MAXDELAY to 1 with
the following statement:</p>
<p class="code"><nowiki>MAXDELAY 1
</nowiki></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.
 
<div id="mixed"></div>
===MIXed===
<!--Caution: <div> above-->
 
Status: This parameter is deprecated as of Version 7.2.
If it is specified as an input parameter, it is ignored.
<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 message in
uppercase only. This option should be used on Japanese operating systems when
mixed case messages are desired.</p>
 
<div id="mpvirt"></div>
===MPVirt===
<!--Caution: <div> above-->
 
Status: This parameter is deprecated as of Version 7.2.
If it is specified as an input parameter, it is ignored.
<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 User Language 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>
 
<div id="noseq"></div>
===NOSeq===
<!--Caution: <div> above-->
 
Status: This parameter is deprecated as of Version 7.2.
If it is specified as an input parameter, it is ignored.
<p>
This statement indicates that 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.</p>
 
<div id="rangest"></div>
===RANge start_time end_time [FOR for_num] [SKIP skip_num]===
<!--Caution: <div> above-->
 
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>
<i>start_time</i> and <i>end_time</i> 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:</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 <i>start_time</i> is greater than <i>end_time</i>
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 dataset.
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 <i>for_num</i>,
where <i>for_num</i> 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 <i>skip_num</i> (where <i>skip_num</i> 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>
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>
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"><nowiki>RANGE 9:30 11:30
RANGE 13:30 15:30
</nowiki></p>
<p>
is functionally equivalent to:</p>
<p class="code"><nowiki>RANGE 13:30 15:30
</nowiki></p>
 
The position of RANGE statements relative to other statements is
irrelevant.
 
<div id="report"></div>
===REPort  report_desc | NODEFAULT===
<!--Caution: <div> above-->
 
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]].
<p>
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).</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"><nowiki><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>
</nowiki></p>
<p></p>
For more information about XML formatting for an individual report,
see [[#indrpt|<report>:  Specifying individual reports]].
 
<div id="resolu"></div>
===RESolution res_num [PROC pname ] [FILE fname ] [SUBSYS sname ]===
<!--Caution: <div> above-->
 
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 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.
For more information, see [[List of Model 204 parameters]].
</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 <i>res_num</i> 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"><nowiki>RESOLUTION 100
</nowiki></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"><nowiki><resolution value="150">
<resolution value="100">
<resolution value="50">
</nowiki></p>
<p>
is functionally equivalent to:</p>
<p class="code"><nowiki><resolution value="150">
</nowiki></p>
<p>
<i>res_num</i> 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:</p>
<p class="code"><nowiki>RESOLUTION 1000 SUBSYS HOHO
</nowiki></p>
<p>
Using XML input, the keywords are the same except in lowercase:</p>
<p class="code"><nowiki><resolution value="1000" subsys="HOHO">
</nowiki></p>
<p>
This statement indicates that a resolution of 500 should be used for all procedures
in procedure file PROCA:</p>
<p class="code"><nowiki>RESOLUTION 500 FILE PROCA
</nowiki></p>
<p>
Or, in XML mode:</p>
<p class="code"><nowiki><resolution value="500" file="PROCA">
</nowiki></p>
<p>
The following
indicates that a resolution of 700 should be used for the procedure named
PRE-PROC.A:</p>
<p class="code"><nowiki>RESOLUTION 700 PROC PRE-PROC.A
</nowiki></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"><nowiki>RESOLUTION 100 PROC PRE-*
</nowiki></p>
<p>
The following statement indicates that a resolution of 300 should be used for any procedure
in a subsystem whose name ends with XREF:</p>
<p class="code"><nowiki>RESOLUTION 300 SUBSYS *XREF
</nowiki></p>
For more details on the use of wildcards, see [[Wildcard Strings in <var class="product">SirTune</var> and SIRTUNER Statements]].
<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"><nowiki>RESOLUTION 1000 FILE SIR* PROC *TEST
</nowiki></p>
In XML mode, the previous statement is:
<p class="code"><nowiki><resolution value="1000" file="SIR*" proc="*TEST">
</nowiki></p>
<p>
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"><nowiki>RESOLUTION 1000 SUBSYS SIR*
RESOLUTION 500 FILE TEST*
RESOLUTION 200 PROC *TEMP*
</nowiki></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>
 
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:
<ul>
<li>Modify the RESOLUTION command.</li>
<li>Add extra RESOLUTION commands.</li>
to explicitly set the resolution at a lower value for
the procedures that appear on the CHUNK report.</li>
</ul>
 
<p>
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:</p>
<p class="code"><nowiki>RESOLUTION 400 SUBSYS TEST
</nowiki></p>
<p>
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.</p>
<p>
To correct this situation, you can either remove the RESOLUTION
statement from SIRTUNEI or TUNERPTI and lose its virtual storage savings benefits,
or you can add another RESOLUTION statement to override the subsystem wide
RESOLUTION statement for the specific procedure in question.
The following sequence would accomplish this.</p>
<p class="code"><nowiki>RESOLUTION 4 SUBSYS TEST PROC PRE.JUNK.PROC
RESOLUTION 400 SUBSYS TEST
</nowiki></p>
 
<div id="titlest"></div>
===TITle title_string===
<!--Caution: <div> above-->
 
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 <i>title_string</i> 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
<i>title_string</i> are used to generate the title.
</p>
<p>
An example of a valid TITLE statement follows:</p>
<p class="code"><nowiki>TITLE Production run after first round of changes
</nowiki></p>
<p>
When using XML input in version 7.2 and later, you can specify
the title as either a child element of the document node, like this:</p>
<p class="code"><nowiki><SirtuneInput>
  <title>Sirtune June 16, 2010 for THX1138</title>
  ...
</nowiki></p>
<p>
Or you can specify it as a child element of the reportFormat node, like this:</p>
<p class="code"><nowiki><SirtuneInput>
  <reportFormat>
    <title>Sirtune June 16, 2010 for THX1138</title>
  </reportFormat
  ...
</nowiki></p>
 
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.
 
<div id="topnum"></div>
===TOP num_top===
<!--Caution: <div> above-->
 
This statement specifies the number of top entities to be displayed on any report that ranks
multiple entities. The default for <i>num_top</i> is 50. This default can be overridden by a TOP keyword on a REPORT statement ([[SirTune reports#toparm|The TOP parameter]]).
 
<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 in 7.2 and later, 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>
 
<div id="tabcont"></div>
===TABLEOFCONTENTS or TOC===
<!--Caution: <div> above-->
 
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.
<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]].
 
<div id="twopass"></div>
===TWOpass===
<!--Caution: <div> above-->
 
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.
 
As of version 7.2, 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 <code><toc></code>
or <code><tableOfContents></code> element
specifies characteristics of the table of contents.
See [[#repfmt|<reportFormat>:  Controlling report format]].
 
===UPper===
<p>
Status: This parameter is deprecated as of Version 7.2.
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.
 
<div id="xmlrpti"></div>
==Using XML input for report configuration==
<!--Caution: <div> above-->
 
As of version 7.2, 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 not available prior to version 7.2.</li>
 
<li>A <code><report></code> element for each report, specified with appropriate
attributes as described in [[#report|REPort report_desc | NODEFAULT]].</li>
</ul>
<p></p>
<p></p>
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"><nowiki><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>
</nowiki></p>
 
<div id="genlfor"></div>
===General notes on TUNERPTI formatting===
<!--Caution: <div> above-->
 
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>
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>
 
<li>While multiple reports can be specified on a single line in the
older control card format, each <code><report></code> element in the XML
input represents a single report.</li>
 
<li>The configuration parameters <code>top</code>, <code>maxDelay</code>, and
<code>comp31</code> are specified as attributes of the <code><SirtuneInput></code>
document element.
<p>
The configuration parameters <code>title</code>, <code>range</code>, and
<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 after version 7.2, 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>
 
<div id="templt"></div>
===A template for the XML input===
<!--Caution: <div> above-->
 
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 (<code>[ ]</code>) 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"><nowiki><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><!--if a REPORT STATE, the following are the "type"--></b>
<b><!--and "state" attribute options--></b>
          type="[what|comp|load|eval|evali|quad|chunk|
                  ifjob|ifcomp|ifjcomp|iffunc|ifchunk]"
          <b><!--"state" options include primary states:-></b>
          state="[blkin|blkiu|blkon|blkou|redy|rung|rungm|
                  rungs|swpgi|swpgobn|swpgobu|swpgow|wpst|
                  wtsv|
          <b><!--composite states:-></b>
                  all|alli|alln|blk|blki|blkn|blko|blku|
                  oservn|oservu|oservw|redyr|runbl|swpg|
                  swpgo|swpgob|
          <b><!--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><!--critical file resources:-></b>
                  cfrhany|cfrhdir|cfrhind|cfrhexs|cfrhrec|
                  cfrbany|cfrbdir|cfrbind|cfrbexs|cfrbrec]">
</SirtuneInput>
</nowiki></p>
 
<div id="mainxml"></div>
===Guidelines for the three main XML elements===
<!--Caution: <div> above-->
 
This section shows how to assemble the principal elements of the
XML format supported as control input to <var class="product">SirTune</var> Version 7.2 and later.
 
<div id="stinput"></div>
====<SirtuneInput>:  Document root element====
<!--Caution: <div> above-->
 
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"><nowiki><SirtuneInput maxDelay="10" top="100" comp31="200000">
</nowiki></p>
 
<div id="repfmt"></div>
====<reportFormat>:  Controlling report format====
<!--Caution: <div> above-->
 
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"><nowiki><reportFormat>
  <linesPerPage>0</linesPerPage>
  <charactersPerLine>72</charactersPerLine>
  <tableOfContents>Bottom</tableOfContents>
</reportFormat>
</nowiki></p>
<ul>
<li><code><linesPerPage></code> 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.</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>
If the report needs to print a line longer than charactersPerLine,
the line wraps at charactersPerLine+1.</p></li>
 
<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>
 
<div id="indrpt"></div>
====<report>:  Specifying individual reports====
<!--Caution: <div> above-->
 
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"><nowiki><SirtuneInput>
  <report type="csect" chunk="64" task="maintask" top="100"/>
</SirtuneInput>
</nowiki></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"><nowiki><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>
</nowiki></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>
The order in which attributes are specified in the <report> element is
not important.</p>
 
==See also==
{{Template:SirTune topic list}}
 
[[Category: SirTune]]

Latest revision as of 19:57, 8 August 2017