SirAud invocation: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
m (minor)
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==SirAud Soul==
==SirAud SOUL==
As of version 7.5 of Model 204, SirAud can be invoked from a standard Model 204 job - batch or online - by invoking a Rocket-provided Soul procedure. In RKTools Version 7.5 the Soul procedures live in the SIRIUS file; as of RKTools 7.7 the procedures line in M204PROC. M204PROC is used in the following examples, but if you're running RKTools 7.5, you should substitute SIRIUS.
As of version 7.5 of Model&nbsp;204, SirAud can be invoked from a standard Model&nbsp;204 job, batch or Online, by including a Rocket-provided SOUL procedure. In RKTools version 7.5, the SOUL procedures reside in the <code>SIRIUS</code> file; as of RKTools 7.7, the procedures reside in the <code>M204PROC</code> file. <code>M204PROC</code> is used in the examples below; substitute <code>SIRIUS</code> if using RKTools 7.5.


The program for running SirAud is <code>SIRAUDREPORT</code>; it accepts report parameters in XML format only, and operates on a JOURNAL data set that <em>is not</em> the active journal for the job. The command for invoking SirAud from Soul looks like this:
<code>SIRAUDREPORT</code> is the program that runs SirAud. It accepts report parameters in XML format only, and it operates on a <code>JOURNAL</code> data set that <em>is not</em> the active journal for the job (SirAud <em>cannot</em> analyze the currently active journal).  


<p class="code">[IN [FILE|GROUP] xxxxxxxx] INCLUDE SIRAUDREPORT -                          
===Invoking SirAud from SOUL===
                  [parms=DDNAME | FILE:PROCEDURENAME] -                    
The command for invoking SirAud from SOUL has this form:
                  {[journal=DDNAME] |                                      
 
                  [journalextract=DDNAME|FILE:PROCEDURENAME]] -            
<p class="syntax">[IN [FILE|GROUP] <span class="term">fgname</span>] INCLUDE SIRAUDREPORT                         -  
                  [outfile=SIRAUDO] [RAWXML|RAWXMLONLY]                    
    [PARMS= {<span class="term">ddname</span> | <span class="term">procfile</span>:<span class="term">procname</span>} ]                             -  
    [JOURNAL=<span class="term">ddname</span>] | [JOURNALEXTRACT= {<span class="term">ddname</span> | <span class="term">procfile</span>:<span class="term">procname</span>} ] -  
    [OUTFILE=<span class="term">ddname</span>] [RAWXML|RAWXMLONLY]
</p>
</p>
   
   
                                           
Where:
Input: parms    - Parms are either in an external file specified by        
 
                  DDNAME, or are in a procedure in a M204 procfile.        
<table class="thJustBold">
                  Either way, the input must be in XML format as described
<tr><th>PARMS</th>
                  below.                                                  
<td>Specifies the location of the SirAud report input parameters; either of these:  
                                                                           
<ul>
      journal  - specifies the dd name of a journal file to analyze      
<li>In an external file specified by DD name. </li>
                                                                           
 
      journalExtract -                                                     
<li>In a procedure in a Model&nbsp;204 procedure file. </li>
                  specifies a file containing XML data already extracted  
</ul>
                  from a model 204 journal. Input is either a dd name,     
<p>
                  or a procedure containing the XML extract, specified     
The input parameters must be in XML format, as described in [[#Specifying report parameters|Specifying report parameters]], below. </p></td></tr>
                  as procedure name separated by a colon form the file     
 
                  in which it resides.                                     
<tr><th>JOURNAL</th>
                                                                           
<td>The DD name of a journal file to analyze. </td></tr>     
      outfile  - the dd name of a sequential file to hold the output     
 
                  of this report run. If no outfile is specified, the     
<tr><th>JOURNALEXTRACT</th>
                  report goes to standard output, which could be the       
<td>A file containing XML data already extracted from a Model&nbsp;204 journal. The file is specified by its DD name or as a procedure that contains the XML extract. If a procedure, use a colon (<tt>:</tt>) to separate the procedure name from the file in which it resides. </td></tr>
                  terminal, a USE file, a USE procedure or CCAPRINT.       
                                                                           
      rawXml or - Output destination for the SirAud reports. If rawxml     
      rawXmlOnly  is specified, both the rawxml and the report are saved   
                  in the specified file. If rawXmlOnly is specified, only 
                  the extracted XML is saved.                             
                                                                           
parms and parmfile are mutually exclusive, as are journal and journalExtract.
                                                                           
Input parameters:                                                          
                                                                           
  allpr  / nopr    - produce either all or no reports.                     
  filerp / nofilerp - produce/suppress the file report                     
  perfrp / noperfrp - produce/suppress the performance report                             
  procrp / noprocrp - produce/suppress the procedures report                             
  subrp  / nosubrp  - produce/suppress the subsystem report                               
  utblrp / noutblrp - produce/suppress the detailed utable report                         
  utblsm / noutblsm - produce/suppress the summary utable report                         
                                                                                         
  The default report selection is 'allpr' - all reports are produced.                     
  If all reports are suppressed, the output will consist of the environment               
  reports and a summary of the Model 204 parameters from the selected journal             
                                                                                         
  from - starting date/time for journal analysis. Defaults to start of journal           
  to  - ending date/time for journal analysis. Defaults to end of journal               
                                                                                         
  Maxblk                                                                                 
  Skipblk                                                                                 
  top                                                                                     
                                                                                         
input parameters are formatted as an XML doc, like this:                                 
                                                                                         
<SiraudInput top="10" from="3681504000010" to="3681849599990" Maxblk="10000" Skipblk="2">
  <report type="allpr"/>                                                                 
  <report type="noutblrp"/>                                                              
  <report type="noutblsm"/>                                                              
  <reportFormat linesPerPage="55"/>                                                     
</SiraudInput>                                                                           
                                                                                         
As with all XML documents, the content of the SiraudInput XML document is                 
HIGHLY CASE SENSITIVE. In general, if a parameter isn't found, it's regarded             
as missing. If the case is incorrect it will not be found.   


So, for example, you could run SirAud by executing the following commands in the CCAIN of a batch job or at the command line from inside a Model 204 region:
<tr><th>OUTFILE</th>
<td>The DD name of a sequential file to hold the output of this report run. If no outfile is specified, the report goes to standard output, which could be the terminal, a <var>USE</var> file, a <var>USE</var> procedure, or CCAPRINT. </td></tr>
 
<tr><th nowrap>RAWXML | RAWXMLONLY</th>
<td>Output destination for the SirAud reports. If <var>RAWXML</var> is specified, both the raw XML and the report are saved in the specified file. If <var>RAWXMLONLY</var> is specified, only the extracted XML is saved. </td></tr>
</table>
 
===Examples===
<ol>
<li>You might run SirAud by executing the following commands in the CCAIN of a batch job or at the command line inside a Model&nbsp;204 region:


<p class="code">IN FILE M204PROC INCLUDE SIRAUDREPORT PARMS=SIRAUDI JOURNAL=MYJRNL</p>
<p class="code">IN FILE M204PROC INCLUDE SIRAUDREPORT PARMS=SIRAUDI JOURNAL=MYJRNL</p>


In this example the XML-formatted parameters are in an external file (or DD Card) named SIRAUDI, and the journal to analyze is allocated to the job as MYJRNL.
In this example the XML-formatted parameters are in an external file (or DD Card) named <code>SIRAUDI</code>, and the journal to analyze is allocated to the job as <code>MYJRNL</code>. </li>


A more detailed set of commands might look like this:
<li>A more detailed set of commands might look like this:


<p class="code"> FREE EXTJRNL                                                                                            
<p class="code">FREE EXTJRNL              
ALLOCATE EXTJRNL WITH OLD SEQUENTIAL SCOPE=SYSTEM DSN=ULSPFDAB.V77.SIRAUD.CCAJRNL VOLUME=SRS100                                                                                                                    
ALLOCATE EXTJRNL WITH OLD SEQUENTIAL SCOPE=SYSTEM DSN=ULSPFDAB.V77.SIRAUD.CCAJRNL  
PUSHUTABLE LVTBL 1000+ LQTBL 4000                                                                        
VOLUME=SRS100 PUSHUTABLE LVTBL 1000+ LQTBL 4000
R MAXREP31 1024 MAXREP64 4096                                                                                          
R MAXREP31 1024 MAXREP64 4096
OPEN FILE ALANPROC                                                                                       


OPEN FILE M204PROC                                                                                        
OPEN FILE ALANPROC
                                                                                                     
OPEN FILE M204PROC                          
IN M204PROC INCLUDE SIRAUDREPORT PARMS=PARMPROC:SIRAUD_REPORT_PARMS JOURNAL=EXTJRNL RAWXML    
IN M204PROC     -
INCLUDE SIRAUDREPORT PARMS=PARMPROC:SIRAUD_REPORT_PARMS JOURNAL=EXTJRNL RAWXML  
</p>
</p>


In the above example a journal file is allocated as EXTJRNL and report parameters are retrieved from the procedure SIRAUD_REPORT_PARMS in file PARMPROC. Note that SIRAUDREPORT does not do any UTABLE or parameter setting.
In the above example, a journal file is allocated as <code>EXTJRNL</code>, and report parameters are retrieved from the procedure <code>SIRAUD_REPORT_PARMS</code> in file <code>PARMPROC</code>.
 
<p class="note"><b>Note:</b> <code>SIRAUDREPORT</code> does no <var>UTABLE</var> or <var>RESET</var> parameter setting. </p></li>
</ol>
 
===Specifying report parameters===
These are the <code>SIRAUDREPORT</code> program input (<code>SiraudInput</code>) parameters: 
 
<table class="thJustBold">
<tr><th>allpr | nopr </th>
<td>Produce all or no reports. The default is <var>allpr</var>, which produces all [[SirAud#SirAud reports|these reports]].
<p>
If you specify <var>nopr</var>, all reports are suppressed, and the output consists of the environment report (system settings in force in the Online), a summary of the Model&nbsp;204 parameters from the selected journal, and the interval report (statistics per each 15-minute segment of the Online run). </p></td></tr>
 
<tr><th>filerp | nofilerp</th>
<td>Produce/suppress the [[SirAud report contents#FILEREPT|file report]]. </td></tr>
 
<tr><th>perfrp | noperfrp</th>
<td>Produce/suppress the [[SirAud report contents#PERFREPT|performance report]]. </td></tr>
 
<tr><th>procrp | noprocrp</th>
<td>Produce/suppress the [[SirAud report contents#PROCREPT|procedures report]]. </td></tr>
 
<tr><th>subrp | nosubrp</th>
<td>Produce/suppress the [[SirAud report contents#SUBREPT|subsystem report]]. </td></tr>
 
<tr><th>utblrp | noutblrp</th>
<td>Produce/suppress the [[SirAud report contents#UTBLREPT|detailed UTABLE report]]. </td></tr>
 
<tr><th nowrap>utblsm | noutblsm</th>
<td>Produce/suppress the [[SirAud report contents#UTBLSUMM|summary UTABLE report]]. </td></tr>
 
<tr><th>from</th>
<td>Starting date/time for journal analysis. Defaults to start of journal.
<p>
The format is a 13-digit number as output by <var>[[$Sir_Date2NM]]</var>, like this: </p>
<p class="code">%from = $sir_date2nm('09-12-13 00:42:00:11', 'MM-DD-YY HH:MI:SS:XX').</p></td></tr>
 
<tr><th>to</th>
<td>Ending date/time for journal analysis. Defaults to end of journal.
<p>
The format is a 13-digit number as output by <var>$Sir_Date2NM</var>, like this: </p>
<p class="code">%to = $sir_date2nm('09-12-13 12:42:00:00', 'MM-DD-YY HH:MI:SS:XX'). </p></td></tr>
 
<tr><th>Maxblk</th>
<td>Maximum number of journal blocks to process. Defaults to all blocks.</td></tr>
 
<tr><th>Skipblk</th>
<td>Number of initial journal blocks to omit from processing. Defaults to zero. It can be useful to skip some initial journal blocks if the Model&nbsp;204 job has some initialization processes that you'd like to exclude from the analysis.</td></tr>       
 
<tr><th>top</th>
<td>Number of procedures to analyze in the procedure report. These are the "top" resource-consuming procedures found in the journal. </td></tr>
</table>
 
Input parameters are formatted as an XML document, like this:
<p class="code"><SiraudInput top="10" from="3681504000010" to="3681849599990" Maxblk="10000" Skipblk="2">
  <report type="allpr"/>
  <report type="noutblrp"/>
  <report type="noutblsm"/>
  <reportFormat linesPerPage="55"/>
</SiraudInput> </p>


                             
<p class="note"><b>Note:</b> As with all XML documents, the content of the <code>SiraudInput</code> XML document is <b>highly case-sensitive</b>. In general, if a parameter is not found, it is regarded as missing. If the case is incorrect, it will not be found.</p>


==Standalone SirAud (SirAud version 1.05)==
==Standalone SirAud (SirAud version 1.05)==

Latest revision as of 22:52, 1 June 2017

SirAud SOUL

As of version 7.5 of Model 204, SirAud can be invoked from a standard Model 204 job, batch or Online, by including a Rocket-provided SOUL procedure. In RKTools version 7.5, the SOUL procedures reside in the SIRIUS file; as of RKTools 7.7, the procedures reside in the M204PROC file. M204PROC is used in the examples below; substitute SIRIUS if using RKTools 7.5.

SIRAUDREPORT is the program that runs SirAud. It accepts report parameters in XML format only, and it operates on a JOURNAL data set that is not the active journal for the job (SirAud cannot analyze the currently active journal).

Invoking SirAud from SOUL

The command for invoking SirAud from SOUL has this form:

[IN [FILE|GROUP] fgname] INCLUDE SIRAUDREPORT - [PARMS= {ddname | procfile:procname} ] - [JOURNAL=ddname] | [JOURNALEXTRACT= {ddname | procfile:procname} ] - [OUTFILE=ddname] [RAWXML|RAWXMLONLY]

Where:

PARMS Specifies the location of the SirAud report input parameters; either of these:
  • In an external file specified by DD name.
  • In a procedure in a Model 204 procedure file.

The input parameters must be in XML format, as described in Specifying report parameters, below.

JOURNAL The DD name of a journal file to analyze.
JOURNALEXTRACT A file containing XML data already extracted from a Model 204 journal. The file is specified by its DD name or as a procedure that contains the XML extract. If a procedure, use a colon (:) to separate the procedure name from the file in which it resides.
OUTFILE The DD name of a sequential file to hold the output of this report run. If no outfile is specified, the report goes to standard output, which could be the terminal, a USE file, a USE procedure, or CCAPRINT.
RAWXML | RAWXMLONLY Output destination for the SirAud reports. If RAWXML is specified, both the raw XML and the report are saved in the specified file. If RAWXMLONLY is specified, only the extracted XML is saved.

Examples

  1. You might run SirAud by executing the following commands in the CCAIN of a batch job or at the command line inside a Model 204 region:

    IN FILE M204PROC INCLUDE SIRAUDREPORT PARMS=SIRAUDI JOURNAL=MYJRNL

    In this example the XML-formatted parameters are in an external file (or DD Card) named SIRAUDI, and the journal to analyze is allocated to the job as MYJRNL.
  2. A more detailed set of commands might look like this:

    FREE EXTJRNL ALLOCATE EXTJRNL WITH OLD SEQUENTIAL SCOPE=SYSTEM DSN=ULSPFDAB.V77.SIRAUD.CCAJRNL VOLUME=SRS100 PUSHUTABLE LVTBL 1000+ LQTBL 4000 R MAXREP31 1024 MAXREP64 4096 OPEN FILE ALANPROC OPEN FILE M204PROC IN M204PROC - INCLUDE SIRAUDREPORT PARMS=PARMPROC:SIRAUD_REPORT_PARMS JOURNAL=EXTJRNL RAWXML

    In the above example, a journal file is allocated as EXTJRNL, and report parameters are retrieved from the procedure SIRAUD_REPORT_PARMS in file PARMPROC.

    Note: SIRAUDREPORT does no UTABLE or RESET parameter setting.

Specifying report parameters

These are the SIRAUDREPORT program input (SiraudInput) parameters:

allpr | nopr Produce all or no reports. The default is allpr, which produces all these reports.

If you specify nopr, all reports are suppressed, and the output consists of the environment report (system settings in force in the Online), a summary of the Model 204 parameters from the selected journal, and the interval report (statistics per each 15-minute segment of the Online run).

filerp | nofilerp Produce/suppress the file report.
perfrp | noperfrp Produce/suppress the performance report.
procrp | noprocrp Produce/suppress the procedures report.
subrp | nosubrp Produce/suppress the subsystem report.
utblrp | noutblrp Produce/suppress the detailed UTABLE report.
utblsm | noutblsm Produce/suppress the summary UTABLE report.
from Starting date/time for journal analysis. Defaults to start of journal.

The format is a 13-digit number as output by $Sir_Date2NM, like this:

%from = $sir_date2nm('09-12-13 00:42:00:11', 'MM-DD-YY HH:MI:SS:XX').

to Ending date/time for journal analysis. Defaults to end of journal.

The format is a 13-digit number as output by $Sir_Date2NM, like this:

%to = $sir_date2nm('09-12-13 12:42:00:00', 'MM-DD-YY HH:MI:SS:XX').

Maxblk Maximum number of journal blocks to process. Defaults to all blocks.
Skipblk Number of initial journal blocks to omit from processing. Defaults to zero. It can be useful to skip some initial journal blocks if the Model 204 job has some initialization processes that you'd like to exclude from the analysis.
top Number of procedures to analyze in the procedure report. These are the "top" resource-consuming procedures found in the journal.

Input parameters are formatted as an XML document, like this:

<SiraudInput top="10" from="3681504000010" to="3681849599990" Maxblk="10000" Skipblk="2"> <report type="allpr"/> <report type="noutblrp"/> <report type="noutblsm"/> <reportFormat linesPerPage="55"/> </SiraudInput>

Note: As with all XML documents, the content of the SiraudInput XML document is highly case-sensitive. In general, if a parameter is not found, it is regarded as missing. If the case is incorrect, it will not be found.

Standalone SirAud (SirAud version 1.05)

Prior to RKTools 7.5, SirAud could only be invoked via the standalone SIRAUD program. As of late 2016 this approach is deprecated, but will still work.

Running SirAud under MVS

The following JCL will run SirAud under MVS:

//SIRAUDJ JOB (0),MSGCLASS=A,CLASS=A,NOTIFY=ME //SIRAUD EXEC PGM=SIRAUD,PARM='NFILES=10' //STEPLIB DD DSN=SIRAUD.LOAD,DISP=SHR //JOURNAL DD DSN=M204.CCAJRNL,DISP=SHR //SYSPRINT DD SYSOUT=A //* Omit following if reports selected by PARM: //PERFREPT DD SYSOUT=A //FILEREPT DD SYSOUT=A //PROCREPT DD SYSOUT=A //SUBREPT DD SYSOUT=A //UTBLREPT DD SYSOUT=A //UTBLSUMM DD SYSOUT=A //

Note: If you use any of the report selection parameters, omit the various report DD statements, excepting SYSPRINT. See ALLPR and NOPR for a discussion of the report selection parameters.

Running SirAud under CMS

A simple SIRAUD EXEC is provided to run SirAud. You must first issue a FILEDEF command for the JOURNAL file. You may want to insert a JOURNAL FILEDEF to identify the Model 204 journal file, or you may want to issue EXEC SIRAUD from a "wrapper" that contains the FILEDEF command for JOURNAL.

SirAud parameters are specified as options to the SIRAUD EXEC or as SYSIN file records (see SYSIN). Unlike the MVS JCL PARM= field, you do not specify an equal sign (=) between a parameter and the value you are specifying. For example:

SIRAUD (NFILES 10 NOSUBREPT

If you do not want to use the SIRAUD EXEC that is distributed with the product, SirAud must be invoked by the Model 204 CMS interface, because it uses the CMS interface's QSAM/BSAM simulation. The program name of SirAud as distributed is SIRAUD.

Note: Because SirAud uses the Model 204 CMS interface, any file can be on an OS format minidisk.

See also