$StatLD: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(28 intermediate revisions by 4 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Calculate differences and rates for statistics $lists</span>
<span class="pageSubtitle">Calculate differences and rates for statistics $lists</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $StatLD function.</p>
<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 $CFStatL, $FiStatL, $TkStatL, $SsStatL, $UsStatL and $JPStatL.  
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 $StatLD function accepts six arguments and returns a numeric error code.  
The <var>$StatLD</var> function accepts six arguments and returns a numeric error code.  


The first argument is 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.


The second argument is 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.
==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>


The third argument is the identifier of an output $list. The contents of this $list are deleted and replaced by the differences between the argument 1 $list and the argument 2 $list.  
===Syntax terms===
<table>
<tr><th>%result</th>
<td>Either 0 or a negative error code.</td></tr>


The fourth argument is 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
<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>
<ul>
<li>'N' - stands for number. Simply copy 4 bytes from argument 2.
<li>'N' - Number. Simply copy 4 bytes from the <var class="term">list2_id</var> argument. </li>
<li>'D' - stands for difference. Calculate binary difference between 4 bytes in argument 2 and argument 1.
<li>'R' - stands for rate. Calculate binary difference between 4 bytes in argument 2 and argument 1, multiply by 1,000,000 and then divide by argument 4. The fifth argument is required if an R is included in the control string.
</ul>


The fifth argument is a number to be used as a divisor in calculating rates. This is an optional argument but is required if there is an 'R' in the control string (argument 4). This would ordinarily be the elapsed time between calculation of the first argument and the second.
<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>


The sixth argument is 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 10 (the default) for all other entities.
<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>


==Syntax==
<tr><th>pre_len</th>
<p class="syntax"><section begin="syntax" />%RESULT = $StatLD(list1_id, list2_id, list3_id, -
<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.
action_list, divisor, prelen)
</table>
<section end="syntax" /></p>
<p class="caption">$StatLD Function
</p>
<p class="caption">%RESULT is either 0 or a negative error code.</p>


The data returned into the output $list by $StatLD 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 $FISTATL, $TKSTATL, $SsStatL or $UsStatL) is excluded from the new $list. The actual difference data starts at offset 12 (byte number 13) in the result $list items.
==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>


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


The following program displays every user's CPU usage as a rate over one second interval and as a total over the whole run.
==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
<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
   
   
%i is float
%list1 = $ListNew
%list1 is float
%list2 = $ListNew
%list2 is float
%list3 = $ListNew
%list3 is float
%time1 is float
%time2 is float
%rc is float
%data is string len 255
   
   
%list1 = $ListNew
%time1 = $UsStatL(%list1, 'IODEV CPU')
%list2 = $ListNew
Pause 1
%list3 = $ListNew
%time2 = $UsStatL(%list2, 'IODEV CPU')
%rc = $StatLD(%list1, %list2, %list3, 'N N', %time2 - %time1)
   
   
%time1 = $UsStatL(%list1, 'IODEV CPU')
For %i from 1 to $ListCnt(%list3)
Pause 1
  %data = $ListInf(%list3, %i)
%time2 = $UsStatL(%list2, 'IODEV CPU')
  Text
%rc = $StatLD(%list1, %list2, %list3, 'N N', %time2 - %time1)
      userid = { $substr(%data,1,10) } -
      usernum = { $unbin($substr(%data,11,2)) } -
For %i from 1 to $ListCnt(%list3)
      iodev = { $unbin($substr(%data,13,4)) } -
    %data = $ListInf(%list3, %i)
      cpu total = { $unbin($substr(%data,17,4)) }
    Text
  End Text
      userid = { $substr(%data,1,10) } -
End For
      usernum = { $unbin($substr(%data,11,2)) } -
End
      iodev = { $unbin($substr(%data,13,4)) } -
</p></li>
      cpu total = { $unbin($substr(%data,17,4)) }
 
    End Text
<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:
End For
 
   
<p class="code">begin                                       
End
%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>
<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>


<ul class="smallAndTightList">
==Products authorizing {{PAGENAMEE}}==
<li>[[SirMon]]
<ul>
<li>[[SirMon]]  
</ul>
</ul>
<p class="caption">Products authorizing $StatLD
</p>


[[Category:$Functions|$StatLD]]
[[Category:$Functions|$StatLD]]

Latest revision as of 23:28, 20 September 2018

Calculate differences and rates for statistics $lists

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $StatLD function is the UserStatistics class.

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

The $StatLD function accepts six arguments and returns a numeric error code.


Syntax

%result = $StatLD(list1_id, list2_id, list3_id, action_list, divisor, prelen)

Syntax terms

%result Either 0 or a negative error code.
list1_id 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.
list2_id 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.
list3_id The identifier of an output $list. The contents of this $list are deleted and replaced by the differences between the list1_id $list and the list2_id $list.
action_list 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:
  • 'N' - Number. Simply copy 4 bytes from the list2_id argument.
  • 'D' - Difference. Calculate binary difference between 4 bytes in list2_id and list1_id.
  • 'R' - Rate. Calculate binary difference between 4 bytes in argument 2 and argument 1, multiply by 1,000,000, then divide by the divisor argument.
divisor A number to be used as a divisor in calculating rates. This optional argument is required if there is an R in the action_list argument. This would ordinarily be the elapsed time between calculation of the list1_id argument and the list2_id argument.
pre_len 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.

Usage notes

  • The data returned into the output $list by $StatLD 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 $FistatL, $TkstatL, $SsStatL, or $UsStatL) is excluded from the new $list. The actual difference data starts at offset 12 (byte number 13) in the result $list items.

Return codes

-3 - CCATEMP is full (if LISTFC $SirParm 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

Examples

  1. The following program displays every user's CPU usage as a rate over one second interval and as a total over the whole run.

    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

  2. The statistics collection functions ($FiStatL, $SSStatL, 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 $StatLD. This example demonstrates the technique:

    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

    The example shows a set of subsystem statistics collected by $SsStatL, limited to only those subsystems with file SIRLOCAL open. The statistics are collected twice, into lists %al1 and %al2, and then run through $StatLD to produce list %al3. $List %al3 shows the selected subset.

Products authorizing $StatLD