SirTune report generation

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:

Subsystem	Procfile	Procedure name	Resolution
TOOLSYS	GENFILE	BOP.PROD.L	default
SIRJUNK	JUNKPROC	P.JUNK.PROC	1000
BIGSYS	TESTFILE	P.BARTLIST	500
BIGSYS	PROCX	EXPER.TEMP.P	200
SIRJUNK	TESTFILE	P.BARTLIST	1000
SIRJUNK	PROCX	EXPER.TEMP.P	1000
BIGSYS	TESTFILE	EXPER.TEMP.P	500
SIRJUNK	TESTFILE	EXPER.TEMP.P	1000

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

• SirTune introduction
• SirTune data collection under MVS
• SirTune data collection under CMS
• SirTune data collection statements
• SirTune MODIFY and SMSG commands
• SirTune report generation
• SirTune reports
• SirTune user states
• SirTune and Model 204 quad types
• SirTune statement wildcards
• SirTune date processing