$TkStat: Difference between revisions
Jump to navigation
Jump to search
(Automatically generated page update) |
mNo edit summary |
||
| Line 6: | Line 6: | ||
This function allows retrieval of a specific task's statistics into a string. | This function allows retrieval of a specific task's statistics into a string. | ||
The $TkStat function accepts two argument and returns a string made up of an error code and returned statistics. | The <var>$TkStat</var> function accepts two argument and returns a string made up of an error code and returned statistics. | ||
==Syntax== | |||
<p class="syntax"><span class="term">%string</span> = <span class="literal">$TkStat</span>(<span class="term">stat_list</span>, <span class="term">task_num</span>) | |||
</p> | |||
===Syntax terms=== | |||
<table> | |||
<tr><th>%string</th> | |||
<td>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.</td></tr> | |||
<tr><th>stat_list</th> | |||
< | <td>A string of blank-delimited words indicating the statistics to be returned. The length of each returned statistic is always a multiple of 4 bytes. This facilitates the use of <var>$StatD</var> with the returned string. | ||
</p> | <p> | ||
< | For more information about available statistics, see the <var class="book">[http://sirius-software.com/maint/download/monr.pdf SirMon User's Guide]</var>.</p> </td></tr> | ||
The data | <tr><th>task_num</th> | ||
<td>The task number of the task for which data is to be returned. The maintask is always task number 0. Other tasks are only available for Onlines running the MP/204 feature.</td></tr> | |||
</table> | |||
<p class="code"> | ===Return codes=== | ||
<p class="code"> -5 - Required parameter not specified | |||
-12 - Invalid parameter (argument 2 > NMPSUBS) | |||
-13 - STAT not linked in | |||
-14 - Result string would be longer than 255 bytes | |||
</p> | </p> | ||
The following program displays some totals for subtask 1 | ==Usage notes== | ||
<ul> | |||
<li>The data returned by $TkStat is binary with the first 4 bytes containing an error code. If the error code is negative, only 4 bytes are returned. If the error code is positive, it contains a number of milliseconds since the online region was brought up. This provides a convenient number for calculating rates for the statistics. When a positive error code is returned the next 10 bytes contain blanks followed by 2 bytes of binary 0. This means that the actual data starts at offset 16 (byte number 17) in the result string. | |||
</ul> | |||
==Example== | |||
The following program displays some totals for subtask 1: | |||
<p class="code"> B | <p class="code">B | ||
%DATA IS STRING LEN 255 | |||
%DATA = $TkStat('CPU STDEQ LKWAIT', 1) | |||
IF $LEN(%DATA) = 4 THEN | |||
PRINT '$TKSTAT ERROR... RC = ' WITH $UNBIN(%DATA) | |||
STOP | |||
END IF | |||
PRINT 'CPU = ' WITH $UNBIN( $SUBSTR(%DATA, 17, 4) ) | |||
PRINT 'STDEQ = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) ) | |||
PRINT 'LKWAIT = ' WITH $UNBIN( $SUBSTR(%DATA, 25, 4) ) | |||
END | |||
</p> | </p> | ||
| Line 51: | Line 62: | ||
<li>[[Sirius $Functions]] | <li>[[Sirius $Functions]] | ||
</ul> | </ul> | ||
[[Category:$Functions|$TkStat]] | [[Category:$Functions|$TkStat]] | ||
Revision as of 22:47, 24 July 2013
Retrieve task's statistics into string
Note: Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $TkStat function.
This function allows retrieval of a specific task's statistics into a string.
The $TkStat function accepts two argument and returns a string made up of an error code and returned statistics.
Syntax
%string = $TkStat(stat_list, task_num)
Syntax terms
| %string | 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_list | A string of blank-delimited words indicating the statistics to be returned. The length of each returned statistic is always a multiple of 4 bytes. This facilitates the use of $StatD with the returned string.
For more information about available statistics, see the SirMon User's Guide. |
| task_num | The task number of the task for which data is to be returned. The maintask is always task number 0. Other tasks are only available for Onlines running the MP/204 feature. |
Return codes
-5 - Required parameter not specified -12 - Invalid parameter (argument 2 > NMPSUBS) -13 - STAT not linked in -14 - Result string would be longer than 255 bytes
Usage notes
- The data returned by $TkStat is binary with the first 4 bytes containing an error code. If the error code is negative, only 4 bytes are returned. If the error code is positive, it contains a number of milliseconds since the online region was brought up. This provides a convenient number for calculating rates for the statistics. When a positive error code is returned the next 10 bytes contain blanks followed by 2 bytes of binary 0. This means that the actual data starts at offset 16 (byte number 17) in the result string.
Example
The following program displays some totals for subtask 1:
B %DATA IS STRING LEN 255 %DATA = $TkStat('CPU STDEQ LKWAIT', 1) IF $LEN(%DATA) = 4 THEN PRINT '$TKSTAT ERROR... RC = ' WITH $UNBIN(%DATA) STOP END IF PRINT 'CPU = ' WITH $UNBIN( $SUBSTR(%DATA, 17, 4) ) PRINT 'STDEQ = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) ) PRINT 'LKWAIT = ' WITH $UNBIN( $SUBSTR(%DATA, 25, 4) ) END