View source for $StatLD

{{DISPLAYTITLE:$StatLD}}
<span class="pageSubtitle">Calculate differences and rates for statistics $lists</span>

<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $StatLD function is the [[UserStatistics class]].</p>

This function allows calculation of differences and rates for statistics $lists. These statistics $lists must be in a format identical to $lists produced by <var>$CfStatL</var>, <var>$FiStatL</var>, <var>$TkStatL</var>, <var>$SsStatL</var>, <var>$UsStatL</var>, and <var>$JpStatL</var>. 

The <var>$StatLD</var> function accepts six arguments and returns a numeric error code. 


==Syntax==
<p class="syntax"><span class="term">%result</span> = <span class="literal">$StatLD</span>(<span class="term">list1_id</span>, <span class="term">list2_id</span>, <span class="term">list3_id</span>, <span class="term">action_list</span>, <span class="term">divisor</span>, <span class="term">prelen</span>)
</p>

===Syntax terms===
<table>
<tr><th>%result</th> 
<td>Either 0 or a negative error code.</td></tr>

<tr><th>list1_id</th>
<td>The identifier of a $list where each item contains an EBCDIC identifier in bytes 1-10, a binary number in bytes 11-12, and data in bytes 13 to the end of the $list item. </td></tr>

<tr><th>list2_id</th>
<td>The identifier of a $list where each item contains an EBCDIC identifier in bytes 1-10, a binary number in bytes 11-12, and data in bytes 13 to the end of the $list item. </td></tr>

<tr><th>list3_id</th>
<td>The identifier of an output $list. The contents of this $list are deleted and replaced by the differences between the <var class="term">list1_id</var> $list and the <var class="term">list2_id</var> $list. </td></tr>

<tr><th>action_list</th>
<td>A control string containing blank-delimited tokens describing the action to be performed for each 4-byte chunk of the input $list items. The available actions are:
<ul>
<li>'N' - Number. Simply copy 4 bytes from the <var class="term">list2_id</var> argument. </li>

<li>'D' - Difference. Calculate binary difference between 4 bytes in <var class="term">list2_id</var> and <var class="term">list1_id</var>. </li>
 
<li>'R' - Rate. Calculate binary difference between 4 bytes in argument 2 and argument 1, multiply by 1,000,000, then divide by the <var class="term">divisor</var> argument.  </li>
</ul></td></tr>

<tr><th>divisor</th>
<td>A number to be used as a divisor in calculating rates. This optional argument is required if there is an <code>R</code> in the <var class="term">action_list</var> argument. This would ordinarily be the elapsed time between calculation of the <var class="term">list1_id</var> argument and the <var class="term">list2_id</var> argument.</td></tr>

<tr><th>pre_len</th>
<td>A number of characters at the beginning of the output list (parameter 3) reserved for the name of the monitored entity.  Should be set to 30 when monitoring Janus ports, and to 10 (the default) for all other entities.
</table>

==Usage notes==
<ul>
<li>The data returned into the output $list by <var>$StatLD</var> is binary, with the first 12 bytes matching the first 12 bytes of an item in the second $list that matches one in the first list. Any item in the second $list that has the high order bit of byte 11 on (set to flag exclusion by a selection criterion on <var>$FistatL</var>, <var>$TkstatL</var>, <var>$SsStatL</var>, or <var>$UsStatL</var>) is excluded from the new $list. The actual difference data starts at offset 12 (byte number 13) in the result $list items.
</ul>

===Return codes===
<p class="code"> -3 - CCATEMP is full (if LISTFC <var>$SirParm</var> parameter not set)
 -5 - Required parameter not specified
 -6 - Invalid $list identifier
-12 - Invalid control string
-13 - Invalid rate divisor
-14 - Invalid length $list item
</p>

==Examples==
<ol>
<li>The following program displays every user's CPU usage as a rate over one second interval and as a total over the whole run.

<p class="code">Begin
%i is float
%list1 is float
%list2 is float
%list3 is float
%time1 is float
%time2 is float
%rc is float
%data is string len 255
 
%list1 = $ListNew
%list2 = $ListNew
%list3 = $ListNew
 
%time1 = $UsStatL(%list1, 'IODEV CPU')
Pause 1
%time2 = $UsStatL(%list2, 'IODEV CPU')
%rc = $StatLD(%list1, %list2, %list3, 'N N', %time2 - %time1)
 
For %i from 1 to $ListCnt(%list3)
   %data = $ListInf(%list3, %i)
   Text
      userid = { $substr(%data,1,10) } -
      usernum = { $unbin($substr(%data,11,2)) } -
      iodev = { $unbin($substr(%data,13,4)) } -
      cpu total = { $unbin($substr(%data,17,4)) }
   End Text
End For
End
</p></li>

<li>The statistics collection functions (<var>$FiStatL</var>, <var>$SSStatL</var>, etc.) have a parameter that lets you subset the list of entities to be viewed. But those functions always return the full list of entities. To view the subsetted list, the collected statistics need to be run through <var>$StatLD</var>. This example demonstrates the technique:

<p class="code">begin                                         
%al1   is float                               
%al2   is float                               
%al3   is float                               
%error is float                               
%rc    is float                               
%z     is float                               
                                              
%an       is string len 20 array (20)         
%file     is string len 20                    
%restrict is string len 20                    
%file     = 'SIRLOCAL'                        
                                              
%al1 = $listNew                               
%al2 = $listNew                               
%al3 = $listNew                               
%restrict  = 'FILE=' with %file               
%rc        = $ssstatl(%al1,'STATUS',%RESTRICT)
%rc        = $ssstatl(%al2,'STATUS',%RESTRICT)
%rc        = $STATLD(%al1,%al2,%al3,'N N')    
for %z from 1 to $listCnt(%al3)               
   %an(%z) = $deBlank($listInf(%al3,%Z,1,10)) 
   printText {%an(%z)}                        
end for                                       
%al1 = $listDel                               
%al2 = $listDel                               
%al3 = $listDel                               
end
</p>
<p>
The example shows a set of subsystem statistics collected by <var>$SsStatL</var>, limited to only those subsystems with file <code>SIRLOCAL</code> open. The statistics are collected twice, into lists <code>%al1</code> and <code>%al2</code>, and then run through <var>$StatLD</var> to produce list <code>%al3</code>. $List <code>%al3</code> shows the selected subset. </p></li>
</ol>

==Products authorizing {{PAGENAMEE}}== 
<ul>
<li>[[SirMon]] 
</ul>

[[Category:$Functions|$StatLD]]