$StatLD

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

• SirMon