$FiStat: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (→‎Return codes: misc formatting)
m (link repair)
Line 9: Line 9:


==Syntax==
==Syntax==
<p class="syntax"><span class="term">%STRING</span> = <span class="literal">$FiStat</span>(<span class="term">stat_list</span>, <span class="term">file_num</span>)
<p class="syntax"><span class="term">%string</span> = <span class="literal">$FiStat</span>(<span class="term">stat_list</span>, <span class="term">file_num</span>)
</p>
</p>
<p>%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 first argument is 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 [[$StatD]] with the returned string. For more information on available statistics, see the <var class="product">[http://sirius-software.com/maint/download/monr.pdf SirMon User's Guide]</var>.


The second argument is the file number of the file for which data is to be returned.
===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 is only 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. For more information about available statistics, see <var class="product">[[File statistics displayed in SirMon]]</var>. </td></tr>
 
<tr><th>file_num</th>
<td>The file number of the file for which data is to be returned.</td></tr>
</table>
 
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>This function is only available to sites that own the Sirius Functions or have a site-license for all M204 products.</li>
<li>This function is only available to sites that own the Sirius Functions or have a site-license for all M204 products.</li>


<li>The data returned by <var>$FiStat</var> is binary, the first 4 bytes of which contain a return code. If the return code is negative, only 4 bytes are returned. If the return code is positive, it contains a number of milliseconds that the online has been up. This provides a convenient number for calculating rates for the statistics. </li>
<li>The data returned by <var>$FiStat</var> is binary, the first 4 bytes of which contain a return code. If the return code is negative, only 4 bytes are returned. If the return code is positive, it contains a number of milliseconds that the online has been up. This provides a convenient number for calculating rates for the statistics.  
 
<p>
With a positive return code, the next 10 bytes contain the blank-padded file name, followed by 2 bytes that contain the binary file number. This means that the actual data starts at offset 16 (byte number 17) in the result string.
With a positive return code, the next 10 bytes contain the blank-padded file name, followed by 2 bytes that contain the binary file number. This means that the actual data starts at offset 16 (byte number 17) in the result string.</p></li>
</ul>
</ul>



Revision as of 19:11, 13 September 2016

Retrieve file's statistics into string

Note: Most Sirius $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.

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

Syntax

%string = $FiStat(stat_list, file_num)

Syntax terms

%string Binary data, the first 4 bytes of which is an error code. If the error code is negative, %string is only 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 File statistics displayed in SirMon.
file_num The file number of the file for which data is to be returned.

Usage notes

  • This function is only available to sites that own the Sirius Functions or have a site-license for all M204 products.
  • The data returned by $FiStat is binary, the first 4 bytes of which contain a return code. If the return code is negative, only 4 bytes are returned. If the return code is positive, it contains a number of milliseconds that the online has been up. This provides a convenient number for calculating rates for the statistics.

    With a positive return code, the next 10 bytes contain the blank-padded file name, followed by 2 bytes that contain the binary file number. This means that the actual data starts at offset 16 (byte number 17) in the result string.

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).

B %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