|
|
| (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]]
| |