$FiStat: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (clarify return value)
m (clarify return value)
Line 13: Line 13:
<table>
<table>
<tr><th>%string</th>  
<tr><th>%string</th>  
<td>A string containing binary data. If the string is exactly four bytes, it contains an [[#Return codes|error code]].  
<td>A string of data. If the string is exactly four bytes, it contains a binary [[#Return codes|error code]].  
<p>
<p>
Otherwise, the first four bytes contain the number of milliseconds that the Online has been up. This provides a convenient number for calculating rates for the statistics. </p>
Otherwise, the first four bytes contain the binary number of milliseconds that the Online has been up. This provides a convenient number for calculating rates for the statistics. </p>
<p>
<p>
The next ten bytes contain the blank-padded file name, then follows two bytes containing the binary file number. This means that the actual data starts at offset 16 (byte number 17) in the result string.</p></td></tr>
The next ten bytes contain the blank-padded file name, then follows two bytes containing the binary file number. This means that the actual data starts at offset 16 (byte number 17) in the result string.</p></td></tr>
Line 27: Line 27:


===Return codes===
===Return codes===
<p class="code"> -5 - Required parameter not specified
<p class="code"> -5   Required parameter not specified
-12 - Invalid parameter (argument 2 > NUSERS, or invalid name in stat_list)  
-12   Invalid parameter (argument 2 > NUSERS, or invalid name in stat_list)  
-13 - STAT not linked in
-13   STAT not linked in
-14 - Result string would be longer than 255 bytes
-14   Result string would be longer than 255 bytes
-15 - File no longer open
-15   File no longer open
</p>
</p>



Revision as of 21:54, 3 October 2016

Retrieve file's statistics into string

Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $FiStat function.

This function allows retrieval of a specific file's statistics into a string.

Syntax

%string = $FiStat(stat_list, file_num)

Syntax terms

%string A string of data. If the string is exactly four bytes, it contains a binary error code.

Otherwise, the first four bytes contain the binary number of milliseconds that the Online has been up. This provides a convenient number for calculating rates for the statistics.

The next ten bytes contain the blank-padded file name, then follows two bytes containing the binary file number. This means that the actual data starts at offset 16 (byte number 17) in the result string.

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 four bytes. This facilitates the use of $StatD with the returned string. For more information about available statistics, see File statistics displayed in SirMon.
file_num The file number of the file for which data is to be returned.

Return codes

-5 Required parameter not specified -12 Invalid parameter (argument 2 > NUSERS, or invalid name in stat_list) -13 STAT not linked in -14 Result string would be longer than 255 bytes -15 File no longer open

Example

The following program displays some totals for file 0 (always CCATEMP).

Begin %data IS STRING LEN 255 %data = $FiStat('DKIO CFRCONF CFRQUEU', 0) IF $Len(%data) = 4 THEN PRINT '$FISTAT ERROR... RC = ' WITH $Unbin(%data) STOP END IF PRINT 'FILENAME = ' WITH $Substr(%data, 5, 10) PRINT 'DKIO = ' WITH $Unbin( $Substr(%data, 17, 4) ) PRINT 'CFRCONF = ' WITH $Unbin( $Substr(%data, 21, 4) ) PRINT 'CFRQUEU = ' WITH $Unbin( $Substr(%data, 25, 4) ) End

Products authorizing $FiStat