$StatD

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