SirTune data collection statements: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (more conversion cleanup)
m (misc cleanup)
Line 4: Line 4:
<!-- Page name: Sirtune configuration statements for the Data Collector -->
<!-- Page name: Sirtune configuration statements for the Data Collector -->


An optional DD card (or FILEDEF under CMS) called SIRTUNEI allows
An optional DD card (or FILEDEF under CMS) called <code>SIRTUNEI</code> allows users to specify characteristics of the reporting run and to customize which reports are requested and how they are ordered.
users to specify characteristics of the reporting run and to customize which reports
are requested and how they are ordered.


The configuration statements take the form of control cards.
The configuration statements take the form of control cards.
Line 25: Line 23:
<!--Caution: <div> above-->
<!--Caution: <div> above-->


This statement specifies that <var class="product">SirTune</var> should collect compilation
This statement specifies that <var class="product">SirTune</var> should collect compilation data for all procedures; it is the inverse of the <code>[[#precomp|PRECOMP]]</code> statement.
data for all procedures; it is the inverse of the PRECOMP statement
([[#allcomp|ALLComp]]).


The default for a single user run (NUSERS = 1) is that <var class="product">SirTune</var> collects
The default for a single user run (<code>NUSERS=1</code>) is that <var class="product">SirTune</var> collects compilation data for all procedures.
compilation data for all procedures.
The default for a multi-user run (<code>NUSERS>1</code>)
The default for a multi-user run (NUSERS > 1)
is that <var class="product">SirTune</var> collects compilation data only for precompiled procedures.
is that <var class="product">SirTune</var> collects compilation data only for pre-compiled procedures.
It is unnecessary to specify <code>ALLCOMP</code> in a single-user run since it is the default.
It is unnecessary to specify ALLCOMP in a single-user run since it is the default.


If ALLCOMP is not used explicitly in a multi-user run, or if it is overridden
If ALLCOMP is not used explicitly in a multi-user run, or if it is overridden by the PRECOMP statement in a single-user run,
by the PRECOMP statement in a single-user run,
the report generator can produce line-by-line breakdowns
the report generator can produce line-by-line breakdowns
for pre-compiled APSY procedures only.
for precompiled [[Application Subsystem development|Application Subsystem]] (APSY) procedures only.
Using the ALLCOMP statement makes it possible for the
Using the ALLCOMP statement makes it possible for the
reporting module to provide line-by-line breakdowns for all
reporting module to provide line-by-line breakdowns for all
Line 44: Line 38:


Specifying the ALLCOMP statement can significantly increase the
Specifying the ALLCOMP statement can significantly increase the
size of the sample dataset, and in extreme cases, it can adversely
size of the sample data set, and in extreme cases, it can adversely
affect the performance of an ONLINE.
affect the performance of an Online.
Because of this, it is
Because of this, it is generally recommended that you use only the ALLCOMP option
generally recommended that you use only the ALLCOMP option
when running <var class="product">SirTune</var> against a single-user batch job, or when running
when running <var class="product">SirTune</var> against a single-user batch job, or when running
multi-user jobs that do a lot of processing in non-APSY or
multi-user jobs that do a lot of processing in non-APSY or
non-pre-compiled procedures.
non-precompiled procedures.
<p class="note"><b>Note:</b> <var class="product">SirTune</var> cannot provide line-by-line breakdowns
<p class="note"><b>Note:</b> <var class="product">SirTune</var> cannot provide line-by-line breakdowns for SOUL programs not contained in procedures, including inline procedures in CCAIN, IODEV3, or BATCH2 input streams, or those entered at a terminal without use of the editor.
for User Language programs not contained in procedures, including in-line procedures in CCAIN, IODEV3, or BATCH2 input streams, or those entered at a terminal without use of the editor.
</p>
</p>


==AUTHorize userid1 [userid2] ...==
==AUTHorize userid1 [userid2] ...==
This statement specifies the userids from whom <var class="product">SirTune</var> should accept
This statement specifies the user IDs from whom <var class="product">SirTune</var> should accept
MODIFY commands (under MVS) or SMSG commands (under CMS).
<code>MODIFY</code> commands (under MVS) or <code>SMSG</code> commands (under CMS).
The default is that MODIFY or SMSG commands to <var class="product">SirTune</var> are
The default is that MODIFY or SMSG commands to <var class="product">SirTune</var> are not accepted from any user ID.
not accepted from any userid.


Since MVS provides no information about the user issuing a MODIFY
Since MVS provides no information about the user issuing a MODIFY
statement, the only AUTHORIZE statement that makes any sense under MVS
statement, the only <code>AUTHORIZE</code> statement that makes any sense under MVS
is:
is:
<p class="code"><nowiki>AUTHORIZE *
<p class="code"><nowiki>AUTHORIZE *
</nowiki></p>
</nowiki></p>
This indicates that <var class="product">SirTune</var> will accept MODIFY commands from any user
This indicates that <var class="product">SirTune</var> will accept MODIFY commands from any user that has the privilege to issue a MODIFY command (either an operator at a console or a user in SDSF).
that has the privilege
to issue a MODIFY command (either an operator at a console or
a user in SDSF).


Under CMS, an arbitrary number of userids can be specified, and
Under CMS, an arbitrary number of user IDs can be specified, and
the userids can contain wildcard characters.
the IDs can contain wildcard characters.
For example:
For example:
<p class="code"><nowiki>AUTHORIZE BART HOMER*
<p class="code"><nowiki>AUTHORIZE BART HOMER*
</nowiki></p>
</nowiki></p>
The statement above indicates that <var class="product">SirTune</var> should accept SMSG commands from
The statement above indicates that <var class="product">SirTune</var> should accept SMSG commands from
userid <code>BART</code> and from any userid that starts with the characters
user ID <code>BART</code> and from any user ID that starts with the characters <code>H O M E R</code>.
<code>H O M E R</code>.
For more information on wildcards, see [[SirTune statement wildcards]].
For more information on wildcards, see [[SirTune statement wildcards]].


SIRTUNEI can contain an arbitrary number of AUTHORIZE statements.
SIRTUNEI can contain an arbitrary number of AUTHORIZE statements.
The AUTHORIZE statements are cumulative, so the userids specified
The AUTHORIZE statements are cumulative, so the user IDs specified
on an AUTHORIZE statement are added to the list of userids specified
on an AUTHORIZE statement are added to the list of user IDs specified
by all previous AUTHORIZE statements.
by all previous AUTHORIZE statements.
<p></p>
 
For more information on the commands that can be issued via MODIFY
For more information on the commands that can be issued via MODIFY
or SMSG by authorized users, see [[SirTune MODIFY and SMSG commands]].
or SMSG by authorized users, see [[SirTune MODIFY and SMSG commands]].
Line 91: Line 78:
==CMSout vmid [ddname]==
==CMSout vmid [ddname]==
This statement has meaning only under CMS.
This statement has meaning only under CMS.
It specifies the userid
It specifies the user ID of the virtual machine (<var class="term">vmid</var>) running the SIRTUNED load module, and
of the virtual machine (<i>vmid</i>) running the SIRTUNED load module, and
it specifies the DD name (<var class="term">ddname</var>) that virtual machine is to
it specifies the DD name (<i>ddname</i>) that virtual machine is to
use for the sample dataset.
use for the sample dataset.
The default for <i>vmid</i> is <code>SIRTUNED</code>, and the default
The default for <var class="term">vmid</var> is <code>SIRTUNED</code>, and the default
for <i>ddname</i> is the userid of the virtual machine running <var class="product">SirTune</var>.
for <var class="term">ddname</var> is the user ID of the virtual machine running <var class="product">SirTune</var>.


For example, this statement
For example, this statement
indicates that there is a SIRTUNED service machine with userid
indicates that there is a SIRTUNED service machine with user ID
<code>HOHO</code> that should use DD name <code>MARGE</code> for the sample dataset:
<code>HOHO</code> that should use DD name <code>MARGE</code> for the sample dataset:
<p class="code"><nowiki>CMSOUT HOHO MARGE
<p class="code">CMSOUT HOHO MARGE
</nowiki></p>
</p>


The CMSOUT statement makes it possible to run multiple SIRTUNED
The <code>CMSOUT</code> statement makes it possible to run multiple SIRTUNED service machines, because it allows <var class="product">SirTune</var> in each <var class="product">Model 204</var> service machine to indicate the user ID of its SIRTUNED service machine. This is not a generally recommended mode of operation,
service machines, because it allows <var class="product">SirTune</var> in each <var class="product">Model 204</var> service machine to indicate the userid of its SIRTUNED service machine.
This is not a generally recommended mode of operation,
however, because of the extra overhead of running multiple virtual machines.
however, because of the extra overhead of running multiple virtual machines.


Line 116: Line 100:
data collected by <var class="product">SirTune</var>.
data collected by <var class="product">SirTune</var>.
While collecting extra data
While collecting extra data
increases the size of the sample dataset, it also makes it
increases the size of the sample data set, it also makes it
possible to produce extended reports.
possible to produce extended reports.


The default for COLLECT in multi-user runs is <code>COLLECT RUNG</code>,
The default for <code>COLLECT</code> in multi-user runs is <code>COLLECT RUNG</code>, which means that data is only collecting for running users (users consuming CPU), and no extra data is collected.
which means that data is only collecting for running users (users consuming CPU),
The default for COLLECT in single-user runs is <code>COLLECT ALLN BLKU DISKIO</code>, which means that the only user for which data is not collected is waiting PSTs.
and no extra data is collected.
The default for COLLECT in single-user runs is <code>COLLECT ALLN BLKU DISKIO</code>,
which means that the only user for which data is not collected is
waiting PSTs.
Data is always collected for
Data is always collected for
running users, regardless of the COLLECT statements in SIRTUNEI.
running users, regardless of the COLLECT statements in SIRTUNEI.


<i>state</i> is a list of one or more blank-delimited user states.
<var class="term">state</var> is a list of one or more blank-delimited user states.
<var class="product">SirTune</var> will collect sample data for a user
<var class="product">SirTune</var> will collect sample data for a user
in any of the states indicated by COLLECT statements at the
in any of the states indicated by COLLECT statements at the
Line 135: Line 115:
For example, if the following is specified, <var class="product">SirTune</var> will collect sample data for any user that is swapping into or out of a server at the instant a
For example, if the following is specified, <var class="product">SirTune</var> will collect sample data for any user that is swapping into or out of a server at the instant a
sample is collected:
sample is collected:
<p class="code"><nowiki>COLLECT SWPG
<p class="code">COLLECT SWPG
</nowiki></p>
</p>


To be able to produce a report for a particular state, data must
To be able to produce a report for a particular state, data must
be collected for that state with <var class="product">SirTune</var>.
be collected for that state with <var class="product">SirTune</var>.
For example, if you want to produce a report for STATE SWPG, you can ensure
For example, if you want to produce a report for <code>STATE SWPG</code>, you can ensure
the appropriate data will be collected by <var class="product">SirTune</var> by placing
the appropriate data will be collected by <var class="product">SirTune</var> by placing
this statement in SIRTUNEI:
this statement in SIRTUNEI:
<p class="code"><nowiki>COLLECT SWPG
<p class="code">COLLECT SWPG
</nowiki></p>
</p>
For a discussion of available states and their
For a discussion of available states and their meanings, see [[SirTune user states]].
meanings, see [[SirTune user states]].


In addition to requesting that sample data be collected for users
In addition to requesting that sample data be collected for users
in specific states, it is also possible to request extra data to
in specific states, it is also possible to request extra data to
isolate the cause of certain wait types.
isolate the cause of certain wait types.
The only valid values for <i>extra_data</i> are <code>DISKIO</code>
The only valid values for <var class="term">extra_data</var> are <code>DISKIO</code> and/or <code>CFR</code>.
and/or <code>CFR</code>.


Specifying <code>DISKIO</code> as a parameter on a COLLECT statement
Specifying <code>DISKIO</code> as a parameter on a COLLECT statement
Line 158: Line 136:
This data allows the reporting module to produce the DISKIO reports.
This data allows the reporting module to produce the DISKIO reports.
These reports allow breakdowns
These reports allow breakdowns
of waits on <var class="product">Model 204</var> disk I/O by file, table, and groups of pages within tables.
of waits on <var class="product">Model&nbsp;204</var> disk I/O by file, table, and groups of pages within tables.


Specifying <code>DISKIO</code> on a collect statement implies the BLKIN parameter.
Specifying <code>DISKIO</code> on a collect statement implies the <code>BLKIN</code> parameter.
That is, this statement:
That is, this statement:
<p class="code"><nowiki>COLLECT DISKIO BLKIN
<p class="code"><nowiki>COLLECT DISKIO BLKIN
Line 175: Line 153:


The CFR data allows the reporting module
The CFR data allows the reporting module
to produce the CFRROOT, STATE CFRH???, and STATE CFRB??? reports.
to produce the <code>CFRROOT</code>, <code>STATE CFRH???</code>, and <code>STATE CFRB???</code> reports.
These reports allow breakdowns of:
These reports allow breakdowns of:
<ul>
<ul>
Line 182: Line 160:
</ul>
</ul>


Since critical file resources are
Since critical file resources are used to provide multi-user concurrency control, the CFR parameter is meaningless in a single-user run.
used to provide multi-user concurrency control, the CFR parameter is
meaningless in a single-user run.


COLLECT statements are cumulative.
COLLECT statements are cumulative.
That is, this sequence:
That is, this sequence:
<p class="code"><nowiki>COLLECT SWPGI
<p class="code">COLLECT SWPGI
COLLECT BLKIN
COLLECT BLKIN
COLLECT BLKON
COLLECT BLKON
</nowiki></p>
</p>
is functionally equivalent to this:
is functionally equivalent to this:
<p class="code"><nowiki>COLLECT SWPGI BLKIN BLKON
<p class="code">COLLECT SWPGI BLKIN BLKON
</nowiki></p>
</p>
and it results in data being collected for all users in state SWPGI, BLKIN, or
and it results in data being collected for all users in state SWPGI, BLKIN, or BLKON.
BLKON.
There is no limit to the number of COLLECT statements in SIRTUNEI.
There is no limit to the number of COLLECT statements in SIRTUNEI.


Line 203: Line 178:
That is, if the following is the first COLLECT statement
That is, if the following is the first COLLECT statement
in SIRTUNEI for a single-user run:
in SIRTUNEI for a single-user run:
<p class="code"><nowiki>COLLECT RUNG
<p class="code">COLLECT RUNG
</nowiki></p>
</p>
it would turn off data collection for
it would turn off data collection for all other user states in the single-user default and for DISKIO data.
all other user states in the single-dser default and for DISKIO data.


==EXClude [start_time end_time] [days_of_week]==
==EXClude [start_time end_time] [days_of_week]==
This statement makes it possible to limit the times
This statement makes it possible to limit the times
in which sample data is collected.
in which sample data is collected.
Note that compilation data is
Note that compilation data is always collected, whether or not sample data is being collected.
always collected, whether or not sample data is being collected.


<i>start_time</i> and <i>end_time</i> can have the format
<var class="term">start_time</var> and <var class="term">end_time</var> can have the format
HH, HH:MM, or HH:MM:SS, where HH represents an hour of the day, MM
HH, HH:MM, or HH:MM:SS, where HH represents an hour of the day, MM
represents minutes, and SS represents seconds.
represents minutes, and SS represents seconds.
Line 223: Line 196:
indicates that no sample data should be collected from midnight through
indicates that no sample data should be collected from midnight through
8 AM every day of the week:
8 AM every day of the week:
<p class="code"><nowiki>EXCLUDE 0 8
<p class="code">EXCLUDE 0 8
</nowiki></p>
</p>


The following indicates that no sample data should be collected from 11:30 AM
The following indicates that no sample data should be collected from 11:30 AM through 1:30 PM every day of the week:
through 1:30 PM every day of the week:
<p class="code">EXCLUDE 11:30 13:30
<p class="code"><nowiki>EXCLUDE 11:30 13:30
</p>
</nowiki></p>


The following indicates that no sample data should be collected from 30 seconds
The following indicates that no sample data should be collected from 30 seconds before 12 noon through 50 seconds after 1 PM every day of the week:
before 12 noon through 50 seconds after 1 PM every day of the week:
<p class="code">EXCLUDE 11:59:30 13:00:50
<p class="code"><nowiki>EXCLUDE 11:59:30 13:00:50
</p>
</nowiki></p>


If <i>start_time</i> is greater than <i>end_time</i>, the times are assumed to wrap.
If <var class="term">start_time</var> is greater than <var class="term">end_time</var>, the times are assumed to wrap.
For example, the following
For example, the following means that no sample data should be collected between 11 PM and 1 AM:
means that no sample data should be collected between 11 PM and 1 AM:
<p class="code"><nowiki>EXCLUDE 23:00 1:00
<p class="code"><nowiki>EXCLUDE 23:00 1:00
</nowiki></p>
</nowiki></p>


<i>days_of_week</i> is a blank-delimited list of days of the week.
<var class="term">days_of_week</var> is a blank-delimited list of days of the week.
The following are valid days of the week, with the
The following are valid days of the week, with the
minimum abbreviations in uppercase:
minimum abbreviations in uppercase:
<ul>
<ul>
<li>SUNday
<li>SUNday</li>
<li>MONday
<li>MONday</li>
<li>TUEsday
<li>TUEsday</li>
<li>WEDnesday
<li>WEDnesday</li>
<li>THUrsday
<li>THUrsday</li>
<li>FRIday
<li>FRIday</li>
<li>SATurday
<li>SATurday</li>
</ul>
</ul>


For example, the following indicates that no sample data should be collected all day Sundays and Saturdays:
For example, the following indicates that no sample data should be collected all day Sundays and Saturdays:
<p class="code"><nowiki>EXCLUDE SUNDAY SAT
<p class="code">EXCLUDE SUNDAY SAT
</nowiki></p>
</p>


The following indicates that no sample data should be collected from 6:30 PM through
The following indicates that no sample data should be collected from 6:30 PM through midnight on Mondays through Fridays:
midnight on Mondays through Fridays:
<p class="code">EXCLUDE 18:30 24:00 MOND TUES WEDN THU FRIDAY
<p class="code"><nowiki>EXCLUDE 18:30 24:00 MOND TUES WEDN THU FRIDAY
</p>
</nowiki></p>


In addition to the days of the week, the following groupings are
In addition to the days of the week, the following groupings are
also available in a <i>days_of_week</i> list:
also available in a <var class="term">days_of_week</var> list:
<ul>
<ul>
<li>WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday
<li>WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday</li>
<li>WEEKEnd = Saturday, Sunday
<li>WEEKEnd = Saturday, Sunday</li>
<li>ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
<li>ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday</li>
</ul>
</ul>


Line 275: Line 244:
indicates that no sample data should be collected all day Saturday through
indicates that no sample data should be collected all day Saturday through
Sunday:
Sunday:
<p class="code"><nowiki>EXCLUDE WEEKE
<p class="code">EXCLUDE WEEKE
</nowiki></p>
</p>


The following
The following indicates that no sample data should be collected on any day of the week:
indicates that no sample data should be collected on any day of
<p class="code">EXCLUDE ALL
the week:
</p>
<p class="code"><nowiki>EXCLUDE ALL
</nowiki></p>


The following
The following indicates that no sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:
indicates that no sample data should be collected between 10 AM and 12 noon
<p class="code">EXCLUDE 10 12 WEEKEND MONDAY
on Sunday, Saturday, and Monday:
</p>
<p class="code"><nowiki>EXCLUDE 10 12 WEEKEND MONDAY
</nowiki></p>


The following
The following
indicates that no sample data should be collected between 11 PM and midnight
indicates that no sample data should be collected between 11 PM and midnight on all days of the week:
on all days of the week:
<p class="code">EXCLUDE 23:00 24:00 ALL
<p class="code"><nowiki>EXCLUDE 23:00 24:00 ALL
</p>
</nowiki></p>


Note that the statement above is identical to this:
Note that the statement above is identical to this:
<p class="code"><nowiki>EXCLUDE 23:00 24:00
<p class="code">EXCLUDE 23:00 24:00
</nowiki></p>
</p>


If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is
If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is
collected as if INCLUDE ALL had been specified.
collected as if <code>INCLUDE ALL</code> had been specified.


The order of INCLUDE
The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important:
and EXCLUDE statements in SIRTUNEI is important:
If the first INCLUDE or EXCLUDE statement in SIRTUNEI is <code>EXCLUDE</code>, it is treated as if it
If the first INCLUDE
or EXCLUDE statement in SIRTUNEI is <code>EXCLUDE</code>, it is treated as if it
were preceded by an <code>INCLUDE ALL</code>.
were preceded by an <code>INCLUDE ALL</code>.
That is, data will only not be collected over
That is, data will only not be collected over
Line 313: Line 275:
For example,
For example,
if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:
if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:
<p class="code"><nowiki>EXCLUDE 0 9
<p class="code">EXCLUDE 0 9
</nowiki></p>
</p>
sample data will be collected between 9 AM and midnight every day of
sample data will be collected between 9 AM and midnight every day of
the week.
the week.
No data will be collected at other times.
No data will be collected at other times.
If SIRTUNEI contains the following sequence,
If SIRTUNEI contains the following sequence,
data should be collected on Monday, Tuesday, Wednesday, Thursday, Friday, and
data should be collected on Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday:
Saturday:
<p class="code">EXCLUDE WEEKEND
<p class="code"><nowiki>EXCLUDE WEEKEND
INCLUDE SATURDAY
INCLUDE SATURDAY
</nowiki></p>
</p>


If SIRTUNEI contains the following sequence,
If SIRTUNEI contains the following sequence,
data should be collected on every weekday from 8 AM to 5 PM and on Fridays
data should be collected on every weekday from 8 AM to 5 PM and on Fridays
from 10 PM to midnight:
from 10 PM to midnight:
<p class="code"><nowiki>EXCLUDE WEEKEND
<p class="code">EXCLUDE WEEKEND
EXCLUDE 0 8
EXCLUDE 0 8
EXCLUDE 17 24
EXCLUDE 17 24
INCLUDE 22 24 FRIDAY
INCLUDE 22 24 FRIDAY
</nowiki></p>
</p>


Note that there is no harm in EXCLUDE'ing a range
Note that there is no harm in including a range
that has already been excluded.
that has already been excluded.
For example, the following
For example, the following
<p class="code"><nowiki>EXCLUDE 0:00 7:00
<p class="code">EXCLUDE 0:00 7:00
EXCLUDE 4:00 10:00
EXCLUDE 4:00 10:00
</nowiki></p>
</p>
is the same as
is the same as
<p class="code"><nowiki>INCLUDE 0:00 10:00
<p class="code">INCLUDE 0:00 10:00
</nowiki></p>
</p>


The INCLUDE/EXCLUDE statements are only honored if sampling is set
The INCLUDE/EXCLUDE statements are only honored if sampling is set
to AUTO (automatic) mode, either by default or via a SAMPLE statement or
to <code>AUTO</code> (automatic) mode, either by default or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command.
a MODIFY or SMSG SAMPLE command.
When sampling is in manual mode, INCLUDE/EXCLUDE statements have no effect.
When sampling is in manual mode, INCLUDE/EXCLUDE statements have no effect.


Line 352: Line 312:
collecting data for time intervals in which there is nothing interesting
collecting data for time intervals in which there is nothing interesting
likely to be happening, that is, periods of low activity.
likely to be happening, that is, periods of low activity.
The only
The only real cost of this is the disk space and the minor amount of CPU
real cost of this is the disk space and the minor amount of CPU
consumed collecting this sample data.
consumed collecting this sample data.


Line 369: Line 328:
always collected, whether or not sample data is being collected.
always collected, whether or not sample data is being collected.


<i>start_time</i> and <i>end_time</i> can have the format
<var class="term">start_time</var> and <var class="term">end_time</var> can have the format
HH, HH:MM, or HH:MM:SS where HH represents an hour of the day, MM
HH, HH:MM, or HH:MM:SS where HH represents an hour of the day, MM
represents minutes, and SS represents seconds.
represents minutes, and SS represents seconds.
Line 415: Line 374:
For example,
For example,
indicates that sample data should be collected all day Mondays and Tuesdays:
indicates that sample data should be collected all day Mondays and Tuesdays:
<p class="code"><nowiki>INCLUDE MONDAY TUE
<p class="code">INCLUDE MONDAY TUE
</nowiki></p>
</p>


The following
The following
indicates that sample data should be collected from 8:45 AM through
indicates that sample data should be collected from 8:45 AM through
5:45 PM on Mondays through Fridays:
5:45 PM on Mondays through Fridays:
<p class="code"><nowiki>INCLUDE 8:45 17:45 MOND TUES WEDN THU FRIDAY
<p class="code">INCLUDE 8:45 17:45 MOND TUES WEDN THU FRIDAY
</nowiki></p>
</p>


In addition to the days of the week, the following groupings are
In addition to the days of the week, the following groupings are
also available in a <i>days_of_week</i> list:
also available in a <var class="term">days_of_week</var> list:
<ul>
<ul>
<li>WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday
<li>WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday </li>
<li>WEEKEnd = Saturday, Sunday
<li>WEEKEnd = Saturday, Sunday </li>
<li>ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
<li>ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday </li>
</ul>
</ul>


Line 435: Line 394:
indicates that sample data should be collected all day Monday through
indicates that sample data should be collected all day Monday through
Friday:
Friday:
<p class="code"><nowiki>INCLUDE WEEKD
<p class="code">INCLUDE WEEKD
</nowiki></p>
</p>


The following
The following
indicates that sample data should be collected all day on every day of
indicates that sample data should be collected all day on every day of
the week:
the week:
<p class="code"><nowiki>INCLUDE ALL
<p class="code">INCLUDE ALL
</nowiki></p>
</p>


The following indicates that sample data should be collected between 10 AM and 12 noon
The following indicates that sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:
on Sunday, Saturday, and Monday:
<p class="code">INCLUDE 10 12 WEEKEND MONDAY
<p class="code"><nowiki>INCLUDE 10 12 WEEKEND MONDAY
</p>
</nowiki></p>


The following
The following
indicates that sample data should be collected between 11 PM and midnight
indicates that sample data should be collected between 11 PM and midnight
on all days of the week:
on all days of the week:
<p class="code"><nowiki>INCLUDE 23:00 24:00 ALL
<p class="code">INCLUDE 23:00 24:00 ALL
</nowiki></p>
</p>


Note that the above statement is identical to this:
Note that the above statement is identical to this:
<p class="code"><nowiki>INCLUDE 23:00 24:00
<p class="code">INCLUDE 23:00 24:00
</nowiki></p>
</p>


If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is
If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is
Line 463: Line 421:


The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important:
The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important:
If the first INCLUDE
If the first INCLUDE or EXCLUDE statement in SIRTUNEI is <code>INCLUDE</code>, it is treated as if it
or EXCLUDE statement in SIRTUNEI is <code>INCLUDE</code>, it is treated as if it
were preceded by an <code>EXCLUDE ALL</code> (that is, data will only be
were preceded by an <code>EXCLUDE ALL</code> (that is, data will only be
collected over intervals explicitly indicated by INCLUDE statements).
collected over intervals explicitly indicated by INCLUDE statements).
Line 487: Line 444:
Data should be collected on Tuesdays from 8 AM to 11 AM, 12 noon to 1 PM,
Data should be collected on Tuesdays from 8 AM to 11 AM, 12 noon to 1 PM,
and 2 PM to 5 PM.
and 2 PM to 5 PM.
<blockquote class="note"><b>Note:</b> There is no harm in INCLUDE'ing a range that has already been included.
<blockquote class="note"><b>Note:</b> There is no harm in INCLUDE'ing a range that has already been included. For example, the following range
For example, the following range
<p class="code"><nowiki>INCLUDE 9:00 13:00
<p class="code"><nowiki>INCLUDE 9:00 13:00
INCLUDE 12:00 17:00
INCLUDE 12:00 17:00
Line 498: Line 454:


The INCLUDE/EXCLUDE statements are only honored if sampling is set
The INCLUDE/EXCLUDE statements are only honored if sampling is set
to AUTO (automatic) mode, either by default, or via a SAMPLE statement or
to <code>AUTO</code> (automatic) mode, either by default, or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command.
a MODIFY or SMSG SAMPLE command.
When sampling is in manual mode,
When sampling is in manual mode,
INCLUDE/EXCLUDE statements have no effect.
INCLUDE/EXCLUDE statements have no effect.
Line 513: Line 468:
10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply
10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply
put the following statements into SIRTUNEI:
put the following statements into SIRTUNEI:
<p class="code"><nowiki>INCLUDE 10 11:30 WEEKDAY
<p class="code">INCLUDE 10 11:30 WEEKDAY
INCLUDE 1:30 4 WEEKDAY
INCLUDE 1:30 4 WEEKDAY
</nowiki></p>
</p>


==INTerval num_sec==
==INTerval num_sec==
This statement is used to set the sampling rate,
This statement is used to set the sampling rate,
thus making it possible to limit the amount of sample data collected.
thus making it possible to limit the amount of sample data collected.
The default for <i>num_sec</i> is 1, which
The default for <var class="term">num_sec</var> is 1, which
means that sample data is collected at one-second intervals.
means that sample data is collected at one-second intervals.


The values specified for <i>num_sec</i> have a maximum
The values specified for <i>num_sec</i> have a maximum
resolution of 1/100 of a second so that:
resolution of 1/100 of a second so that:
<p class="code"><nowiki>INTERVAL 3.1415929
<p class="code">INTERVAL 3.1415929
</nowiki></p>
</p>


Is identical to:
Is identical to:
<p class="code">INTERVAL 3.14
<p class="code">INTERVAL 3.14
</p>
</p>
This also means that the lowest legal value for <i>num_sec</i> is 0.01.
This also means that the lowest legal value for <var class="term">num_sec</var> is 0.01.


The objective in setting the sampling interval should be to
The objective in setting the sampling interval should be to
Line 561: Line 516:
If it is specified as an input parameter, it is ignored.
If it is specified as an input parameter, it is ignored.


This statement indicates that <var class="product">SirTune</var> should issue all messages
This statement indicates that <var class="product">SirTune</var> should issue all messages in mixed-case.
in mixed-case.
The default is to issue messages in mixed-case except on Japanese
The default is to issue messages in mixed-case except on Japanese
operating systems.
operating systems.
Line 570: Line 524:


==NOSeq==
==NOSeq==
 
This statement indicates that <var class="product">SirTune</var> should not consider characters in columns 73 through 80 of SIRTUNEI as part of
This statement indicates that <var class="product">SirTune</var> should not consider
characters in columns 73 through 80 of SIRTUNEI as part of
its input.
its input.
If SIRTUNEI has RECFM=F and LRECL=80, <var class="product">SirTune</var>
If SIRTUNEI has <code>RECFM=F</code> and <code>LRECL=80</code>, <var class="product">SirTune</var> ordinarily assumes that characters in columns 73 through 80 are
ordinarily assumes that characters in columns 73 through 80 are
sequence numbers, and therefore it ignores them.
sequence numbers, and therefore it ignores them.
If SIRTUNEI has any
If SIRTUNEI has any
Line 582: Line 533:


==PGM pgm_name==
==PGM pgm_name==
Effective in version 1.5 of <var class="product">SirTune</var> and lower, this statement is ignored
Effective in version 1.5 of <var class="product">SirTune</var> and lower, <i>this statement is ignored in versions after 1.5</i>.
in versions after 1.5.


The PGM statement makes it possible to specify the name
The PGM statement makes it possible to specify the name
of the <var class="product">Model 204</var> ONLINE load module to be loaded by the SIRTUNE module.
of the <var class="product">Model 204</var> ONLINE load module to be loaded by the SIRTUNE module.
The default for <i>pgm_name</i> is <code>ONLINE</code>
The default for <var class="term">pgm_name</var> is <code>ONLINE</code>
under MVS, and it is <code>M204ONLN</code> under CMS.
under MVS, and it is <code>M204ONLN</code> under CMS.


Line 596: Line 546:
</nowiki></p>
</nowiki></p>


If the name of the load
If the name of the load module for which SIRTUNE is to collect data is <code>ONLINE22</code>, put the following statement into SIRTUNEI:
module for which SIRTUNE is to collect data is ONLINE22,
put the following statement into SIRTUNEI:
<p class="code">PGM ONLINE22
<p class="code">PGM ONLINE22
</p>
</p>
Line 606: Line 554:
<!--Caution: <div> above-->
<!--Caution: <div> above-->


This statement specifies that <var class="product">SirTune</var> should only collect compilation
This statement specifies that <var class="product">SirTune</var> should only collect compilation data for precompiled APSY procedures;
data for pre-compiled APSY procedures;
it is the inverse of the <code>[[#allcomp|ALLComp]]</code> statement.
it is the inverse of the ALLCOMP command ([[#allcomp|ALLComp]]).


The default for a single-user run (NUSERS = 1) is that <var class="product">SirTune</var> collects
The default for a single-user run (<code>NUSERS=1</code>) is that <var class="product">SirTune</var> collects
compilation data for all procedures.
compilation data for all procedures.
The default for a multi-user run (NUSERS > 1)
The default for a multi-user run (<code>NUSERS>1</code>)
is that <var class="product">SirTune</var> collects compilation data only for pre-compiled procedures.
is that <var class="product">SirTune</var> collects compilation data only for precompiled procedures.
It is unnecessary to specify PRECOMP in a multi-user run, since it is the default.
It is unnecessary to specify <code>PRECOMP</code> in a multi-user run, since it is the default.


When PRECOMP is in effect, either because of an explicit PRECOMP statement
When PRECOMP is in effect, either because of an explicit PRECOMP statement
or as the result of multi-user run defaults, the reporting module
or as the result of multi-user run defaults, the reporting module
can produce line-by-line breakdowns for pre-compiled APSY procedures only.
can produce line-by-line breakdowns for precompiled APSY procedures only.


==SAMPle  ON | OFF | AUTO==
==SAMPle  ON | OFF | AUTO==
This statement places <var class="product">SirTune</var> in manual sampling mode.
This statement places <var class="product">SirTune</var> in manual sampling mode.
In this mode, <var class="product">SirTune</var> ignores INCLUDE and EXCLUDE statements
In this mode, <var class="product">SirTune</var> ignores INCLUDE and EXCLUDE statements until a <code>SAMPLE AUTO</code> command is issued via a MODIFY or SMSG command issued by an authorized user.
until a <code>SAMPLE AUTO</code> command is issued via a MODIFY
The default for this statement is <code>SAMPLE AUTO</code>, which places
or SMSG command issued by an authorized user.
The default for this statement is SAMPLE AUTO, which places
<var class="product">SirTune</var> under the control of INCLUDE and EXCLUDE statements.
<var class="product">SirTune</var> under the control of INCLUDE and EXCLUDE statements.


Line 640: Line 585:
<p class="code">SAMPLE ON
<p class="code">SAMPLE ON
</p>
</p>
<p class="note"><b>Note:</b> If SAMPLE OFF is specified in SIRTUNEI and there are no
<p class="note"><b>Note:</b> If <code>SAMPLE OFF</code> is specified in SIRTUNEI and there are no
AUTHORIZE statements in SIRTUNEI, it will be impossible to
AUTHORIZE statements in SIRTUNEI, it will be impossible to
collect any sample data for the course of the run, because no
collect any sample data for the course of the run, because no
user will have the authority to issue the MODIFY or SMSG SAMPLE
user will have the authority to issue the MODIFY or SMSG SAMPLE
command to set sampling to ON or to AUTO.
command to set sampling to <code>ON</code> or to <code>AUTO</code>.
</p>
</p>


==UPper==
==UPper==
This statement indicates that <var class="product">SirTune</var> should issue all messages
This statement indicates that <var class="product">SirTune</var> should issue all messages in uppercase only.
in uppercase only.
The default is to issue messages in mixed-case, except on Japanese
The default is to issue messages in mixed-case, except on Japanese
operating systems.
operating systems. On these systems the default is to issue all messages in uppercase only.
On these systems the default is to issue all messages in
uppercase only.


This option should be used on systems where mixed-case messages
This option should be used on systems where mixed-case messages

Revision as of 01:09, 5 November 2015


An optional DD card (or FILEDEF under CMS) called SIRTUNEI allows users to specify characteristics of the reporting run and to customize which reports are requested and how they are ordered.

The configuration statements take the form of control cards. There can be only one SirTune configuration statement per line, there are no line continuations, and a line beginning with an asterisk character (*) is treated as a comment and ignored.

Available SirTune configuration statements are described in the subsections that follow. The minimum abbreviation allowed for each statement is indicated with uppercase characters, while optional characters are indicated with lowercase. Optional statement parameters are enclosed in brackets ([]). Alternatives are separated with a vertical bar (|).

ALLComp

This statement specifies that SirTune should collect compilation data for all procedures; it is the inverse of the PRECOMP statement.

The default for a single user run (NUSERS=1) is that SirTune collects compilation data for all procedures. The default for a multi-user run (NUSERS>1) is that SirTune collects compilation data only for precompiled procedures. It is unnecessary to specify ALLCOMP in a single-user run since it is the default.

If ALLCOMP is not used explicitly in a multi-user run, or if it is overridden by the PRECOMP statement in a single-user run, the report generator can produce line-by-line breakdowns for precompiled Application Subsystem (APSY) procedures only. Using the ALLCOMP statement makes it possible for the reporting module to provide line-by-line breakdowns for all User Language procedures executed in the job.

Specifying the ALLCOMP statement can significantly increase the size of the sample data set, and in extreme cases, it can adversely affect the performance of an Online. Because of this, it is generally recommended that you use only the ALLCOMP option when running SirTune against a single-user batch job, or when running multi-user jobs that do a lot of processing in non-APSY or non-precompiled procedures.

Note: SirTune cannot provide line-by-line breakdowns for SOUL programs not contained in procedures, including inline procedures in CCAIN, IODEV3, or BATCH2 input streams, or those entered at a terminal without use of the editor.

AUTHorize userid1 [userid2] ...

This statement specifies the user IDs from whom SirTune should accept MODIFY commands (under MVS) or SMSG commands (under CMS). The default is that MODIFY or SMSG commands to SirTune are not accepted from any user ID.

Since MVS provides no information about the user issuing a MODIFY statement, the only AUTHORIZE statement that makes any sense under MVS is:

AUTHORIZE *

This indicates that SirTune will accept MODIFY commands from any user that has the privilege to issue a MODIFY command (either an operator at a console or a user in SDSF).

Under CMS, an arbitrary number of user IDs can be specified, and the IDs can contain wildcard characters. For example:

AUTHORIZE BART HOMER*

The statement above indicates that SirTune should accept SMSG commands from user ID BART and from any user ID that starts with the characters H O M E R. For more information on wildcards, see SirTune statement wildcards.

SIRTUNEI can contain an arbitrary number of AUTHORIZE statements. The AUTHORIZE statements are cumulative, so the user IDs specified on an AUTHORIZE statement are added to the list of user IDs specified by all previous AUTHORIZE statements.

For more information on the commands that can be issued via MODIFY or SMSG by authorized users, see SirTune MODIFY and SMSG commands.

CMSout vmid [ddname]

This statement has meaning only under CMS. It specifies the user ID of the virtual machine (vmid) running the SIRTUNED load module, and it specifies the DD name (ddname) that virtual machine is to use for the sample dataset. The default for vmid is SIRTUNED, and the default for ddname is the user ID of the virtual machine running SirTune.

For example, this statement indicates that there is a SIRTUNED service machine with user ID HOHO that should use DD name MARGE for the sample dataset:

CMSOUT HOHO MARGE

The CMSOUT statement makes it possible to run multiple SIRTUNED service machines, because it allows SirTune in each Model 204 service machine to indicate the user ID of its SIRTUNED service machine. This is not a generally recommended mode of operation, however, because of the extra overhead of running multiple virtual machines.

COLLect state [extra_data]

This statement makes it possible to increase the quantity of data collected by SirTune. While collecting extra data increases the size of the sample data set, it also makes it possible to produce extended reports.

The default for COLLECT in multi-user runs is COLLECT RUNG, which means that data is only collecting for running users (users consuming CPU), and no extra data is collected. The default for COLLECT in single-user runs is COLLECT ALLN BLKU DISKIO, which means that the only user for which data is not collected is waiting PSTs. Data is always collected for running users, regardless of the COLLECT statements in SIRTUNEI.

state is a list of one or more blank-delimited user states. SirTune will collect sample data for a user in any of the states indicated by COLLECT statements at the moment a sample is collected.

For example, if the following is specified, SirTune will collect sample data for any user that is swapping into or out of a server at the instant a sample is collected:

COLLECT SWPG

To be able to produce a report for a particular state, data must be collected for that state with SirTune. For example, if you want to produce a report for STATE SWPG, you can ensure the appropriate data will be collected by SirTune by placing this statement in SIRTUNEI:

COLLECT SWPG

For a discussion of available states and their meanings, see SirTune user states.

In addition to requesting that sample data be collected for users in specific states, it is also possible to request extra data to isolate the cause of certain wait types. The only valid values for extra_data are DISKIO and/or CFR.

Specifying DISKIO as a parameter on a COLLECT statement indicates that SirTune should collect data for every wait on Model 204 disk I/O. This data allows the reporting module to produce the DISKIO reports. These reports allow breakdowns of waits on Model 204 disk I/O by file, table, and groups of pages within tables.

Specifying DISKIO on a collect statement implies the BLKIN parameter. That is, this statement:

COLLECT DISKIO BLKIN

is functionally equivalent to this:

COLLECT DISKIO

Specifying CFR as a parameter on a COLLECT statement indicates that SirTune should collect data for users with "Critical File Resource" activity. Critical file resources are used to provide concurrency control among updating and retrieving operations on the same file. Contention on critical file resources can exacerbate performance problems, sometimes dramatically.

The CFR data allows the reporting module to produce the CFRROOT, STATE CFRH???, and STATE CFRB??? reports. These reports allow breakdowns of:

  • The root causes of critical file resource waits
  • Activities that result in the holding of critical file resources

Since critical file resources are used to provide multi-user concurrency control, the CFR parameter is meaningless in a single-user run.

COLLECT statements are cumulative. That is, this sequence:

COLLECT SWPGI COLLECT BLKIN COLLECT BLKON

is functionally equivalent to this:

COLLECT SWPGI BLKIN BLKON

and it results in data being collected for all users in state SWPGI, BLKIN, or BLKON. There is no limit to the number of COLLECT statements in SIRTUNEI.

The first COLLECT statement in SIRTUNEI for a single-user run is treated as an override to the single-user default. That is, if the following is the first COLLECT statement in SIRTUNEI for a single-user run:

COLLECT RUNG

it would turn off data collection for all other user states in the single-user default and for DISKIO data.

EXClude [start_time end_time] [days_of_week]

This statement makes it possible to limit the times in which sample data is collected. Note that compilation data is always collected, whether or not sample data is being collected.

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 indicates that no sample data should be collected from midnight through 8 AM every day of the week:

EXCLUDE 0 8

The following indicates that no sample data should be collected from 11:30 AM through 1:30 PM every day of the week:

EXCLUDE 11:30 13:30

The following indicates that no sample data should be collected from 30 seconds before 12 noon through 50 seconds after 1 PM every day of the week:

EXCLUDE 11:59:30 13:00:50

If start_time is greater than end_time, the times are assumed to wrap. For example, the following means that no sample data should be collected between 11 PM and 1 AM:

EXCLUDE 23:00 1:00

days_of_week is a blank-delimited list of days of the week. The following are valid days of the week, with the minimum abbreviations in uppercase:

  • SUNday
  • MONday
  • TUEsday
  • WEDnesday
  • THUrsday
  • FRIday
  • SATurday

For example, the following indicates that no sample data should be collected all day Sundays and Saturdays:

EXCLUDE SUNDAY SAT

The following indicates that no sample data should be collected from 6:30 PM through midnight on Mondays through Fridays:

EXCLUDE 18:30 24:00 MOND TUES WEDN THU FRIDAY

In addition to the days of the week, the following groupings are also available in a days_of_week list:

  • WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday
  • WEEKEnd = Saturday, Sunday
  • ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

For example, the following indicates that no sample data should be collected all day Saturday through Sunday:

EXCLUDE WEEKE

The following indicates that no sample data should be collected on any day of the week:

EXCLUDE ALL

The following indicates that no sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:

EXCLUDE 10 12 WEEKEND MONDAY

The following indicates that no sample data should be collected between 11 PM and midnight on all days of the week:

EXCLUDE 23:00 24:00 ALL

Note that the statement above is identical to this:

EXCLUDE 23:00 24:00

If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is collected as if INCLUDE ALL had been specified.

The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important: If the first INCLUDE or EXCLUDE statement in SIRTUNEI is EXCLUDE, it is treated as if it were preceded by an INCLUDE ALL. That is, data will only not be collected over intervals explicitly indicated by EXCLUDE statements.

For example, if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:

EXCLUDE 0 9

sample data will be collected between 9 AM and midnight every day of the week. No data will be collected at other times. If SIRTUNEI contains the following sequence, data should be collected on Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday:

EXCLUDE WEEKEND INCLUDE SATURDAY

If SIRTUNEI contains the following sequence, data should be collected on every weekday from 8 AM to 5 PM and on Fridays from 10 PM to midnight:

EXCLUDE WEEKEND EXCLUDE 0 8 EXCLUDE 17 24 INCLUDE 22 24 FRIDAY

Note that there is no harm in including a range that has already been excluded. For example, the following

EXCLUDE 0:00 7:00 EXCLUDE 4:00 10:00

is the same as

INCLUDE 0:00 10:00

The INCLUDE/EXCLUDE statements are only honored if sampling is set to AUTO (automatic) mode, either by default or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command. When sampling is in manual mode, INCLUDE/EXCLUDE statements have no effect.

Generally, you should use the INCLUDE/EXCLUDE statements to avoid collecting data for time intervals in which there is nothing interesting likely to be happening, that is, periods of low activity. The only real cost of this is the disk space and the minor amount of CPU consumed collecting this sample data.

If you are only interested in collecting data at peak hours, say 10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply put the following in SIRTUNEI:

INCLUDE 10 5 WEEKDAY EXCLUDE 11:30 13:30

INClude [start_time end_time] [days_of_week]

This statement makes it possible to limit the times in which sample data is collected. Note that compilation data is always collected, whether or not sample data is being collected.

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 indicates that sample data should be collected from 8 AM through 6 PM every day of the week:

INCLUDE 8 18

The following indicates that sample data should be collected from 8:30 AM through 5:30 PM every day of the week:

INCLUDE 8:30 17:30

The following indicates that sample data should be collected from 10 seconds before 9 AM through 10 seconds after 5 PM every day of the week:

INCLUDE 8:59:50 17:00:10

If start_time is greater than end_time, the times are assumed to wrap. For example, the following means that sample data should be collected between 11 PM and 1 AM:

INCLUDE 23:00 1:00

days_of_week is a blank-delimited list of days of the week. The following are valid days of the week, with the minimum abbreviations in uppercase:

  • SUNday
  • MONday
  • TUEsday
  • WEDnesday
  • THUrsday
  • FRIday
  • SATurday

For example, indicates that sample data should be collected all day Mondays and Tuesdays:

INCLUDE MONDAY TUE

The following indicates that sample data should be collected from 8:45 AM through 5:45 PM on Mondays through Fridays:

INCLUDE 8:45 17:45 MOND TUES WEDN THU FRIDAY

In addition to the days of the week, the following groupings are also available in a days_of_week list:

  • WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday
  • WEEKEnd = Saturday, Sunday
  • ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

For example, the following indicates that sample data should be collected all day Monday through Friday:

INCLUDE WEEKD

The following indicates that sample data should be collected all day on every day of the week:

INCLUDE ALL

The following indicates that sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:

INCLUDE 10 12 WEEKEND MONDAY

The following indicates that sample data should be collected between 11 PM and midnight on all days of the week:

INCLUDE 23:00 24:00 ALL

Note that the above statement is identical to this:

INCLUDE 23:00 24:00

If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is collected as if INCLUDE ALL had been specified.

The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important: If the first INCLUDE or EXCLUDE statement in SIRTUNEI is INCLUDE, it is treated as if it were preceded by an EXCLUDE ALL (that is, data will only be collected over intervals explicitly indicated by INCLUDE statements).

For example, if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:

INCLUDE 9 17

sample data should be collected between 9 AM and 5 PM every day of the week. No data should be collected at other times. If SIRTUNEI contains the following sequence:

INCLUDE WEEKDAY EXCLUDE TUESDAY THURSDAY

Data should be collected on Monday, Wednesday, and Friday. If SIRTUNEI contains the following sequence:

INCLUDE 8 17 TUESDAY EXCLUDE 11 14 INCLUDE 12 13 TUESDAY

Data should be collected on Tuesdays from 8 AM to 11 AM, 12 noon to 1 PM, and 2 PM to 5 PM.

Note: There is no harm in INCLUDE'ing a range that has already been included. For example, the following range

INCLUDE 9:00 13:00 INCLUDE 12:00 17:00

is the same as

INCLUDE 9:00 17:00

The INCLUDE/EXCLUDE statements are only honored if sampling is set to AUTO (automatic) mode, either by default, or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command. When sampling is in manual mode, INCLUDE/EXCLUDE statements have no effect.

Generally, you should use the INCLUDE/EXCLUDE statements to avoid collecting data for time intervals in which there is nothing interesting likely to be happening, that is, periods of low activity. The only real cost of collecting data in periods of low activity is wasted disk space and a minor amount of CPU consumed collecting the sample data.

If you are only interested in collecting data at peak hours, say 10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply put the following statements into SIRTUNEI:

INCLUDE 10 11:30 WEEKDAY INCLUDE 1:30 4 WEEKDAY

INTerval num_sec

This statement is used to set the sampling rate, thus making it possible to limit the amount of sample data collected. The default for num_sec is 1, which means that sample data is collected at one-second intervals.

The values specified for num_sec have a maximum resolution of 1/100 of a second so that:

INTERVAL 3.1415929

Is identical to:

INTERVAL 3.14

This also means that the lowest legal value for num_sec is 0.01.

The objective in setting the sampling interval should be to collect sufficient data to produce statistically significant results, without collecting unnecessarily huge amounts of data. Setting the sampling interval extremely low can also produce biased results. Generally, sampling intervals greater than 0.1 seconds should avoid any biasing problems.

A reasonable rule of thumb is that 10,000 samples are sufficient to produce accurate reports. Thus to collect data on a batch job that generally takes half an hour to complete, samples should be collected every 1800/10000 seconds. To accomplish this, place the following statement into SIRTUNEI:

INTERVAL 0.18

If data is to be collected over 8 hours of a production ONLINE run, the default sampling interval of 1 second would result in 8*3600 or 28,800 samples being collected. In this case, it would not be unreasonable to place the following statement into SIRTUNEI to reduce the number of samples collected to 14,400:

INTERVAL 2

MIXed

Status: This parameter is deprecated as of Version 7.2. If it is specified as an input parameter, it is ignored.

This statement indicates that SirTune should issue all messages 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.

NOSeq

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

PGM pgm_name

Effective in version 1.5 of SirTune and lower, this statement is ignored in versions after 1.5.

The PGM statement makes it possible to specify the name of the Model 204 ONLINE load module to be loaded by the SIRTUNE module. The default for pgm_name is ONLINE under MVS, and it is M204ONLN under CMS.

Thus, if SIRTUNE is to collect data for a job that should be run with BATCH204, put the following statement into SIRTUNEI:

get non-BATCH204 example

PGM BATCH204

If the name of the load module for which SIRTUNE is to collect data is ONLINE22, put the following statement into SIRTUNEI:

PGM ONLINE22

PREComp

This statement specifies that SirTune should only collect compilation data for precompiled APSY procedures; it is the inverse of the ALLComp statement.

The default for a single-user run (NUSERS=1) is that SirTune collects compilation data for all procedures. The default for a multi-user run (NUSERS>1) is that SirTune collects compilation data only for precompiled procedures. It is unnecessary to specify PRECOMP in a multi-user run, since it is the default.

When PRECOMP is in effect, either because of an explicit PRECOMP statement or as the result of multi-user run defaults, the reporting module can produce line-by-line breakdowns for precompiled APSY procedures only.

SAMPle ON | OFF | AUTO

This statement places SirTune in manual sampling mode. In this mode, SirTune ignores INCLUDE and EXCLUDE statements until a SAMPLE AUTO command is issued via a MODIFY or SMSG command issued by an authorized user. The default for this statement is SAMPLE AUTO, which places SirTune under the control of INCLUDE and EXCLUDE statements.

For example, to have SirTune come up so that no sample data is collected until a user issues a (MODIFY or SMSG) SAMPLE command to turn sampling off or to put sampling in AUTO mode, simply place the following statement into SIRTUNEI:

SAMPLE OFF

To have SirTune come up so that sample data is collected until a user issues a MODIFY or SMSG SAMPLE command, place the following statement into SIRTUNEI:

SAMPLE ON

Note: If SAMPLE OFF is specified in SIRTUNEI and there are no AUTHORIZE statements in SIRTUNEI, it will be impossible to collect any sample data for the course of the run, because no user will have the authority to issue the MODIFY or SMSG SAMPLE command to set sampling to ON or to AUTO.

UPper

This statement indicates that SirTune should issue all messages in uppercase only. 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 systems where mixed-case messages might not be displayed correctly on terminals or printers.

See also