$FiStatL: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
No edit summary
 
(7 intermediate revisions by 2 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Retrieve set of files' statistics into list</span>
<span class="pageSubtitle">Retrieve set of files' statistics into list</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $FiStatL function.</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $FiStatL function.</p>


This function allows retrieval of statistics for a set of files into a $list.  
This function allows retrieval of statistics for a set of files into a $list. <var>$FiStatL</var> accepts three arguments and returns a numeric error code.  


The <var>$FiStatL</var> function accepts three arguments and returns a numeric error code.
==Syntax==
<p class="syntax"><span class="term">%result</span> = <span class="literal">$FiStatL</span>(<span class="term">list_identifier</span>, <span class="term">stat_list</span>, <span class="term">criterion</span>)
</p>


The first argument is the identifier of the $list that is to receive the results. The current contents of the $list are deleted and replaced with the requested statistics. The format of each $list item is:
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th>%result</th>
<td>A positive number that is the milliseconds since the Online was brought up, or it is a negative [[#Return codes|return code]].</td></tr>
 
<tr><th>list_identifier</th>
<td>The identifier of the $list that is to receive the results. The current contents of the $list are deleted and replaced with the requested statistics. The format of each $list item is:
<table class="thJustBold">
<tr><th>Byte 1-10</th>
<tr><th>Byte 1-10</th>
<td>Blank padded file name</td></tr>
<td>Blank padded file name</td></tr>
Line 17: Line 25:
<td>Returned statistics
<td>Returned statistics
</td></tr></table>
</td></tr></table>
</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>[[$StatLD]]</var> with the returned $list. For more information on available statistics, see [[File statistics displayed in SirMon]]. </td></tr>
<tr><th>criterion</th>
<td>A selection criterion that indicates which files, of all those that are currently open (by some user or by some subsystem), are to be included in the output $list. The following criteria are allowed:
<table class="thJustBold">
<tr><th>FILE=<i>fid</i></th>
<td>Include only files with filenames matching <var class="term">fid</var> (wildcards allowed).</td></tr>


<tr><th>SUBSYS=<i>subsysid</i></th>
<td>include only files opened by subsystem <var class="term">subsysid</var>. Wildcards are allowed.</td></tr>


The second 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 $StatLD [[$StatLD]] with the returned $list. For more information on available statistics, see the <var class="product">[http://sirius-software.com/maint/download/monr.pdf SirMon User's Guide]</var>.
<tr><th>USER=<i>usernum</i></th>
<td>include only files opened by user <var class="term">usernum</var>.
</td></tr>
</table>


The third argument is a selection criterion that indicates which files, of all those that are currently open (by some user or by some subsystem), are to be included in the output $list. The following criteria are allowed:
Actually, all files are always included in the output $list, but the excluded files have the high order bit of their file numbers turned on. This tells <var>$StatLD</var> to exclude the files from the difference $list.</td></tr>
<table class="syntaxTable">
</table>
<tr><th>FILE=fid</th>
<td>include only files with filenames matching '''fid''' (wildcards allowed).</td></tr>
<tr><th>SUBSYS=subsysid</th>
<td>include only files opened by subsystem '''subsysid'''. Wildcards are allowed.</td></tr>
<tr><th>USER=usernum</th>
<td>include only files opened by user '''usernum'''.
</td></tr></table>
Actually, all files are always included in the output $list, but the excluded files have the high order bit of their file numbers turned on. This tells $StatLD to exclude the files from the difference $list.


==Syntax==
===Return codes===
<p class="syntax"><span class="term">%result</span> = <span class="literal">$FiStatL</span>(<span class="term">list_identifier, stat_list, criterion)
<p class="code"> -3 - CCATEMP is full
</p>
-5 - Required parameter not specified
<p>%result is either a positive number which is the milliseconds since the online was brought up, or it is a negative error code.</p>
-6 - Invalid $list identifier
<p class="code">  
-12 - Invalid name in stat_list
  -3 - CCATEMP is full
-13 - STAT not linked in
  -5 - Required parameter not specified
-16 - Invalid selection criterion
  -6 - Invalid $list identifier
-12 - Invalid name in stat_list
-13 - STAT not linked in
-16 - Invalid selection criterion
</p>
<p class="caption">$FiStatL return codes
</p>
</p>


==Example==
The following program displays some statistics for all files.
The following program displays some statistics for all files.
<p class="code"> B
<p class="code">B
%DATA IS STRING LEN 255
%DATA IS STRING LEN 255
%LIST = $ListNew
%LIST = $ListNew
   
   
%DATA = $FiStatL(%LIST, 'DKIO CFRCONF CFRQUEU')
%DATA = $FiStatL(%LIST, 'DKIO CFRCONF CFRQUEU')
IF %DATA < 0 THEN
IF %DATA < 0 THEN
PRINT '$FISTATL ERROR... RC = ' WITH %DATA
PRINT '$FISTATL ERROR... RC = ' WITH %DATA
STOP
STOP
END IF
END IF
   
   
FOR %I FROM 1 TO $ListCnt(%LIST)
FOR %I FROM 1 TO $ListCnt(%LIST)
%DATA = $ListInf(%LIST, %I)
%DATA = $ListInf(%LIST, %I)
PRINT 'FILENAME = ' WITH $SUBSTR(%DATA, 1, 10)
PRINT 'FILENAME = ' WITH $SUBSTR(%DATA, 1, 10)
PRINT 'DKIO = ' WITH $UNBIN( $SUBSTR(%DATA, 13, 4) )
PRINT 'DKIO = ' WITH $UNBIN( $SUBSTR(%DATA, 13, 4) )
PRINT 'CFRCONF = ' WITH $UNBIN( $SUBSTR(%DATA, 17, 4) )
PRINT 'CFRCONF = ' WITH $UNBIN( $SUBSTR(%DATA, 17, 4) )
PRINT 'CFRQUEU = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) )
PRINT 'CFRQUEU = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) )
PRINT
PRINT
END FOR
END FOR
   
   
END
END
</p>
</p>
==<b id="auth"></b>Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<li>[[List of $functions|Sirius functions]]</li>
<li>[[SirMon]]</li>
</ul>


[[Category:$Functions|$FiStatL]]
[[Category:$Functions|$FiStatL]]

Latest revision as of 15:02, 4 December 2018

Retrieve set of files' statistics into list

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

This function allows retrieval of statistics for a set of files into a $list. $FiStatL accepts three arguments and returns a numeric error code.

Syntax

%result = $FiStatL(list_identifier, stat_list, criterion)

Syntax terms

%result A positive number that is the milliseconds since the Online was brought up, or it is a negative return code.
list_identifier The identifier of the $list that is to receive the results. The current contents of the $list are deleted and replaced with the requested statistics. The format of each $list item is:
Byte 1-10 Blank padded file name
Byte 11-12 Binary file number
Byte 13- Returned statistics
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 $StatLD with the returned $list. For more information on available statistics, see File statistics displayed in SirMon.
criterion A selection criterion that indicates which files, of all those that are currently open (by some user or by some subsystem), are to be included in the output $list. The following criteria are allowed:
FILE=fid Include only files with filenames matching fid (wildcards allowed).
SUBSYS=subsysid include only files opened by subsystem subsysid. Wildcards are allowed.
USER=usernum include only files opened by user usernum.
Actually, all files are always included in the output $list, but the excluded files have the high order bit of their file numbers turned on. This tells $StatLD to exclude the files from the difference $list.

Return codes

-3 - CCATEMP is full -5 - Required parameter not specified -6 - Invalid $list identifier -12 - Invalid name in stat_list -13 - STAT not linked in -16 - Invalid selection criterion

Example

The following program displays some statistics for all files.

B %DATA IS STRING LEN 255 %LIST = $ListNew %DATA = $FiStatL(%LIST, 'DKIO CFRCONF CFRQUEU') IF %DATA < 0 THEN PRINT '$FISTATL ERROR... RC = ' WITH %DATA STOP END IF FOR %I FROM 1 TO $ListCnt(%LIST) %DATA = $ListInf(%LIST, %I) PRINT 'FILENAME = ' WITH $SUBSTR(%DATA, 1, 10) PRINT 'DKIO = ' WITH $UNBIN( $SUBSTR(%DATA, 13, 4) ) PRINT 'CFRCONF = ' WITH $UNBIN( $SUBSTR(%DATA, 17, 4) ) PRINT 'CFRQUEU = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) ) PRINT END FOR END

Products authorizing $FiStatL

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$FiStatL&oldid=117029"