$StatD: Difference between revisions

Latest revision as of 23:28, 20 September 2018

Calculate differences and rates for statistics strings

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

This function allows calculation of differences and rates for statistics strings. These statistics strings must be in a format identical to strings produced by $FISTAT, $SYSTAT, $TKSTAT, $SsStat, and $UsStat.

The $StatD function accepts four arguments and returns a string made up of an error code and returned statistics.

Syntax

%string = $StatD(stat_string1, stat_string2, ctl_string, [divisor])

Syntax terms

%string	The returned string consists of binary data, the first 4 bytes of which is an error code. If the error code is negative, `%string` will only be 4 bytes long.
stat_string1	This string 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 string.
stat_string2	This string 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 string. For differences to be calculated, bytes 1-12 must match bytes 1-12 of the `stat_string1` argument.
ctl_string	This control string contains blank-delimited tokens describing the action to be performed for each 4 byte chunk of the input strings. The available actions are: 'N' - stands for number. Simply copy 4 bytes from argument 2. 'D' - stands for difference. Calculate binary difference between 4 bytes in argument 2 and argument 1. '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. Argument 4 is required if an R is included in the control string.
divisor	This a number to be used as a divisor in calculating rates. This optional argument is required if there is an 'R' in the `ctl_string` argument. This would ordinarily be the elapsed time between calculation of the `stat_string1` and the `stat_string2` argument.

Return codes

-5 - Required parameter not specified -12 - Invalid control string -13 - Invalid rate divisor -14 - Invalid length input string -15 - First 12 bytes don't match in input

Usage notes

The data returned by $StatD is binary with the first 4 bytes containing an error code. If the error code is negative, only 4 bytes are returned. If the differences were successfully calculated, the first 4 bytes are set to binary 0. When a zero error code is returned, the next 12 bytes contain a copy of the first 12 bytes of argument 1 and 2. This means that the actual data starts at offset 16 (byte number 17) in the result string.

Example

The following program displays system CPU as a rate and difference over a one second interval and as a total over the whole run:

Begin %data is string len 255 %data1 is string len 255 %data2 is string len 255 %data1 = $SyStat('CPU SVIO DNSCACHE DNSRTIMO'):subString(5) pause 1 %data2 = $SyStat('CPU SVIO DNSCACHE DNSRTIMO'):subString(5) %data = $statD( %data1, %data2, 'R R N N', 1000) Text %data Return Code = {$UnBin($subStr(%data,1,4))} CPU = {$UnBin($SUBSTR(%data,17,4))} SVIO = {$UnBin($SUBSTR(%data,21,4))} DNSCACHE = {$UnBin($SUBSTR(%data,25,4))} DNSRTIMO = {$UnBin($SUBSTR(%data,29,4))} end Text End

Products authorizing $StatD

SirMon

@@ Line 2: / Line 2: @@
 <span class="pageSubtitle">Calculate differences and rates for statistics strings</span>
-<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is currently no OO equivalent for the $StatD function.</p>
+<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $StatD function is the [[UserStatistics class]].</p>
-This function allows calculation of differences and rates for statistics strings. These statistics strings must be in a format identical to strings produced by $FISTAT, $SYSTAT, $TKSTAT, $SsStat and $UsStat.
+This function allows calculation of differences and rates for statistics strings. These statistics strings must be in a format identical to strings produced by <var>$FISTAT</var>, <var>$SYSTAT</var>, <var>$TKSTAT</var>, <var>$SsStat</var>, and <var>$UsStat</var>.
-The $StatD function accepts four arguments and returns a string made up of an error code and returned statistics.
+The <var>$StatD</var> function accepts four arguments and returns a string made up of an error code and returned statistics.
-The first argument is a string containing an EBCDIC identifier in bytes 1-10, a binary number in bytes 11-12 and data in bytes 13 to the end of the string.
-The second argument is a string containing an EBCDIC identifier in bytes 1-10, a binary number in bytes 11-12 and data in bytes 13 to the end of the string. For differences to be calculated, bytes 1-12 must match bytes 1-12 of the first argument.
-The third argument is a control string containing blank delimited tokens describing the action to be performed for each 4 byte chunk of the input strings. The available actions are
+==Syntax==
+<p class="syntax"><span class="term">%string</span> = <span class="literal">$StatD</span>(<span class="term">stat_string1</span>, <span class="term">stat_string2</span>, <span class="term">ctl_string</span>, [<span class="term">divisor</span>])
+</p>
+===Syntax terms===
+<table>
+<tr><th>%string</th>
+<td>The returned string consists of binary data, the first 4 bytes of which is an error code. If the error code is negative, <var class="term">%string</var> will only be 4 bytes long.</td></tr>
+<tr><th>stat_string1</th>
+<td>This string 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 string. </td></tr>
+<tr><th>stat_string2</th>
+<td>This string 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 string. For differences to be calculated, bytes 1-12 must match bytes 1-12 of the <var class="term">stat_string1</var> argument. </td></tr>
+<tr><th>ctl_string</th>
+<td>This control string contains blank-delimited tokens describing the action to be performed for each 4 byte chunk of the input strings. The available actions are:
 <ul>
 <li>'N' - stands for number. Simply copy 4 bytes from argument 2.
 <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. Argument 4 is required if an R is included in the control string.
-</ul>
+</ul> </td></tr>
-The fourth 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 3). This would ordinarily be the elapsed time between calculation of the first argument and the second.
+<tr><th>divisor</th>
+<td>This 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">ctl_string</var> argument. This would ordinarily be the elapsed time between calculation of the <var class="term">stat_string1</var> and the <var class="term">stat_string2</var> argument.</td></tr>
+</table>
-==Syntax==
+===Return codes===
-<p class="syntax"><section begin="syntax" />%STRING = $StatD(stat_string1, stat_string2, -
+<p class="code"> -5 - Required parameter not specified
- ctl_string, divisor)
+-12 - Invalid control string
-<section end="syntax" /></p>
+-13 - Invalid rate divisor
-<p class="caption">$StatD Function
+-14 - Invalid length input string
+-15 - First 12 bytes don't match in input
 </p>
-<p class="caption">%STRING is made up of binary data, the first 4 bytes of which is an error code. If the error code is negative %STRING will only be 4 bytes long.</p>
-The data returned by $StatD is binary with the first 4 bytes containing an error code. If the error code is negative, only 4 bytes are returned. If the differences were successfully calculated, the first 4 bytes are set to binary 0. When a zero error code is returned the next 12 bytes contain a copy of the first 12 bytes of argument 1 and 2. This means that the actual data starts at offset 16 (byte number 17) in the result string.
+==Usage notes==
+<ul>
+<li>The data returned by <var>$StatD</var> is binary with the first 4 bytes containing an error code. If the error code is negative, only 4 bytes are returned. If the differences were successfully calculated, the first 4 bytes are set to binary 0. When a zero error code is returned, the next 12 bytes contain a copy of the first 12 bytes of argument 1 and 2. This means that the actual data starts at offset 16 (byte number 17) in the result string.
+</ul>
-<p class="code">
-  -5 - Required parameter not specified
- -12 - Invalid control string
- -13 - Invalid rate divisor
- -14 - Invalid length input string
- -15 - First 12 bytes don't match in input
-</p>
-<p class="caption">$StatD return codes
-</p>
-The following program displays system CPU as a rate and difference over a one second interval and as a total over the whole run.
+==Example==
+The following program displays system CPU as a rate and difference over a one second interval and as a total over the whole run:
-<p class="code">
- Begin
-   %data  is string len 255
-   %data1 is string len 255
-   %data2 is string len 255
-   %data1 = $SyStat('CPU SVIO DNSCACHE DNSRTIMO'):subString(5)
-   pause 1
-   %data2 = $SyStat('CPU SVIO DNSCACHE DNSRTIMO'):subString(5)
-   %data = $statD( %data1, %data2, 'R R N N', 1000)
-   Text
-    %data
-    Return Code = {$UnBin($subStr(%data,1,4))}
-    CPU         = {$UnBin($SUBSTR(%data,17,4))}
-    SVIO        = {$UnBin($SUBSTR(%data,21,4))}
-    DNSCACHE    = {$UnBin($SUBSTR(%data,25,4))}
-    DNSRTIMO    = {$UnBin($SUBSTR(%data,29,4))}
-   end Text
- End
+<p class="code">Begin
+%data  is string len 255
+%data1 is string len 255
+%data2 is string len 255
+%data1 = $SyStat('CPU SVIO DNSCACHE DNSRTIMO'):subString(5)
+pause 1
+%data2 = $SyStat('CPU SVIO DNSCACHE DNSRTIMO'):subString(5)
+%data = $statD( %data1, %data2, 'R R N N', 1000)
+Text
+ %data
+ Return Code = {$UnBin($subStr(%data,1,4))}
+ CPU         = {$UnBin($SUBSTR(%data,17,4))}
+ SVIO        = {$UnBin($SUBSTR(%data,21,4))}
+ DNSCACHE    = {$UnBin($SUBSTR(%data,25,4))}
+ DNSRTIMO    = {$UnBin($SUBSTR(%data,29,4))}
+end Text
+End
 </p>
+==Products authorizing {{PAGENAMEE}}==
 <ul class="smallAndTightList">
 <li>[[SirMon]]
 </ul>
-<p class="caption">Products authorizing $StatD
-</p>
 [[Category:$Functions|$StatD]]