$StatLD: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
mNo edit summary
Line 4: Line 4:
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $StatLD function is the [[UserStatistics class]].</p>
<p class="warn"><b>Note: </b>Most Sirius $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>


<ul>
<tr><th>list2_id</th>
<li>'N' - stands for number. Simply copy 4 bytes from argument 2.
<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>
<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.
<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> argument $list and the <var class="term">list2_id</var> $list. </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>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' - stands for number. Simply copy 4 bytes from the <var class="term">list2_id</var> argument.
<li>'D' - stands for difference. Calculate binary difference between 4 bytes in <var class="term">list2_id</var> and <var class="term">list1_id</var>.
<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 <var class="term">divisor</var>argument is required if an R is included in the control string.
</ul></td></tr>


==Syntax==
<tr><th>divisor</th>
<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>, -
<td>A number to be used as a divisor in calculating rates. This optional argument is required if there is an 'R' 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>
<span class="term">action_list</span>, <span class="term">divisor</span>, <span class="term">prelen</span>)
</p>


<p>
<tr><th>pre_len</th>
<var class="term">%result</var> is either 0 or a negative error code.</p>
<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>


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.
==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===
===Return codes===
<p class="code"> -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
Line 86: Line 97:
<li>[[SirMon]]
<li>[[SirMon]]
</ul>
</ul>
<p>
 
</p>


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

Revision as of 20:38, 24 July 2013

Calculate differences and rates for statistics $lists

Note: Most Sirius $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 argument $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' - stands for number. Simply copy 4 bytes from the list2_id argument.
  • 'D' - stands for difference. Calculate binary difference between 4 bytes in list2_id and list1_id.
  • '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 divisorargument is required if an R is included in the control string.
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

Example

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

Products authorizing $StatLD