$View: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
m (add info re $Stat and UserStatistics class)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<p>The $VIEW function returns:</p>
<p>
The <var>$View</var> function returns:</p>
<ul>
<ul>
<li>The value of a parameter (system, file, or user) to the request</li>
<li>The value of a parameter (system, file, or user) to the request.</li>
 
<li>File parameters.
<p>While <var>$View</var> works for all viewable parameters in local context, it does not work for some file parameters in remote context.</p>
</li>
</li>
<li>File parameters</li>
 
<p>While $VIEW works for all viewable parameters in local context, it does not work for some file parameters in remote context.</p>
<li>The size and use of journal and checkpoint streams.</li>
</li>
</ul><br />
<li>Size and use of journal and checkpoint streams</li>
 
</li>
==Syntax to view a parameter value==
</ul>
<p>
<b>Syntax to view a parameter value</b>
The format of the <var>$View</var> function to view parameter values is: </p>
<p>The format of the $VIEW function to view parameter values is: </p>
<p class="syntax"><span class="term">%string</span> = $View(<span class="term">parameter</span>[, <span class="term">name</span>])  
<p class="code">$VIEW(parameter[,name])  
</p>
</p>
<p>where:</p>
<p>Where:</p>
<ul>
<ul>
<li>parameter is a character string that represents the name of a viewable <var class="product">Model&nbsp;204</var> parameter or other information. For example:</li>
<li><var class="term">parameter</var> is a character string that represents the name of a viewable <var class="product">Model&nbsp;204</var> parameter or other information. For example:
<p class="code">$VIEW('ERASE')  
<p class="code">$view('ERASE')  
</p>
</p>
<p>returns a value of @ if the ERASE parameter is set to the character @. If the parameter name is invalid or the user is not authorized to display parameter values for the file, a null string is returned.</p>
<p>
returns a value of <code>@</code> if the <var>ERASE</var> parameter is set to the character <code>@</code>. If the parameter name is invalid or the user is not authorized to display parameter values for the file, a null string is returned.</p>
</li>
</li>
<li>name overrides the default file or group context for the function. The format for this argument is:</li>
<p class="code">[[FILE | [PERM | TEMP] GROUP] name | $CURFILE


| $UPDATE] [AT location]
<li><var class="term">name</var> overrides the default file or group context for the function. The format for this argument is:
<p class="syntax">[[FILE | [PERM | TEMP] GROUP] <span class="term">name</span> | $Curfile | $Update] [AT <span class="term">location</span>]
</p>
</p>
<p>If this argument is omitted or null, the default context is the context of the statement containing the function. Thus, a default context is required for this function.</p>
<p>
<p>You can specify $CURFILE as the name argument in place of a file/group name. </p>
If this argument is omitted or null, the default context is the context of the statement containing the function. Thus, a default context is required for this function.</p>
<p>
You can specify <var>[[$Curfile]]</var> as the <span class="term">name</span> argument in place of a file/group name. </p>
</li>
</li>
</ul>
</ul>
<b>Viewing file-specific information</b>
 
<p>In addition to viewable parameters, the following file-specific information can also be viewed with $VIEW:</p>
==Viewing file-specific information==
<p>
In addition to viewable parameters, the following file-specific information can also be viewed with <var>$View</var>:</p>
<table>
<table>
<tr class="head">
<tr class="head">
<th>Name used with $VIEW</th>
<th>Name used with $View</th>
<th>Description</th>
<th>Description</th>
</tr>
</tr>
<tr>
<tr>
<td>DTSLBOPR</td>
<td>DTSLBOPR</td>
Line 43: Line 51:
</td>
</td>
</tr>
</tr>
<tr>
<tr>
<td>DTSLCHKP</td>
<td>DTSLCHKP</td>
<td>Date and time of last checkpoint rolled back to. Will be blank if the file has also been rolled forward.</td>
<td>Date and time of last checkpoint rolled back to (blank if file has also been rolled forward)</td>
</tr>
</tr>
<tr>
<tr>
<td>DTSLRCVY</td>
<td>DTSLRCVY</td>
<td>Date and time of last recovery</td>
<td>Date and time of last recovery</td>
</tr>
</tr>
<tr>
<tr>
<td>DTSLUPDT</td>
<td>DTSLUPDT</td>
<td>Date and time of last update</td>
<td>Date and time of last update</td>
</tr>
</tr>
<tr>
<tr>
<td>DTSLDKWR</td>
<td>DTSLDKWR</td>
<td>Date and time of last DKWR</td>
<td>Date and time of last DKWR</td>
</tr>
</tr>
<tr>
<tr>
<td>DTSLRFWD</td>
<td>DTSLRFWD</td>
<td>Date and time of last roll forward</td>
<td>Date and time of last roll forward</td>
</tr>
</tr>
<tr>
<tr>
<td>FIWHEN</td>
<td>FIWHEN</td>
<td>Date and time FISTAT was reset</td>
<td>Date and time FISTAT was reset</td>
</tr>
</tr>
<tr>
<tr>
<td>FIWHO</td>
<td>FIWHO</td>
Line 72: Line 87:
</tr>
</tr>
</table>
</table>
<p>For example:</p>
<p>
<p class="code">$VIEW ('FIWHEN')
For example:</p>
</p>
<p class="code">$View ('FIWHEN')</p>
<p>returns:</p>
<p>
<p class="code">FIWHEN  94.257 SEP 14 16.40.45. DATE AND TIME FISTAT WAS RESET
The result is:</p>
</p>
<p class="output">FIWHEN  94.257 SEP 14 16.40.45. DATE AND TIME FISTAT WAS RESET</p>
<b>Syntax for viewing statistics fields</b>
 
<p>The first argument is the category, SLSTATS, SYSSTATS, or USRSTATS. The second argument is the name of the Statistic field to return. See the Rocket <var class="product">Model&nbsp;204</var> System Managers Guide for the name of the statistics fields.</p>
==Syntax for viewing statistics fields==
<p class="code">$VIEW(category, field-to-return)
<p class="syntax"><span class="term">%string</span> = $View(<span class="term">category</span>, <span class="term">field-to-return</span>)</p>
</p>
<p>Where: </p>
<p>Where the following categories and fields are valid: </p>
<ul>
<li><var class="term">category</var> is <var>SLSTATS</var>, <var>SYSSTATS</var>, or <var>USRSTATS</var>. </li>
 
<li><var class="term">field-to-return</var> is the name of the statistic field to return. See [[Using system statistics#Description of statistics|Description of statistics]] for the names of the statistics fields.</li>
</ul>
 
<p>
The following categories and fields are valid:</p>
<table>
<table>
<caption>Valid categories and fields with $VIEW</caption>
<caption>Valid categories and fields with $View</caption>
<tr class="head">
<tr class="head">
<th>
<th>Category</th>
Category</th>
<th>Statistics field to return</th>
<th>Statistics field-to-return</th>
<th>Equivalent-to or returns-value-of</th>
<th>
<th>Remarks</th>
Equivalent-to or returns-value-of</th>
</tr>
</tr>
<tr>
<tr>
<td>'SLSTATS'</td>
<td>SLSTATS</td>
<td>'USERID'</td>
<td>USERID</td>
<td>[[$Userid]]</td>
<td><var>[[$Userid]]</var></td>
<td>Padded with blank spaces to 10 bytes</td>
</tr>
</tr>
<tr>
<tr>
<td>'SLSTATS'</td>
<td>SLSTATS</td>
<td>'ACCOUNT'</td>
<td>ACCOUNT</td>
<td>[[$Account]]</td>
<td><var>[[$Account]]</var></td>
<td>Padded to 10 bytes</td>
</tr>
</tr>
<tr>
<tr>
<td>'SLSTATS'</td>
<td>SLSTATS</td>
<td>'SUBSYSTEM'</td>
<td>SUBSYSTEM</td>
<td>$SUBSYS with no argument</td>
<td><var>$Subsys</var> with no argument</td>
<td>Padded to 10 bytes</td>
</tr>
</tr>
<tr>
<tr>
<td>'SLSTATS'</td>
<td>SLSTATS</td>
<td>'LAST'</td>
<td>LAST</td>
<td>LAST=field</td>
<td>LAST=field</td>
<td>EVAL etc.</td>
</tr>
</tr>
<tr>
<tr>
<td>'SLSTATS'</td>
<td>SLSTATS</td>
<td>'PROC-FILE'</td>
<td>PROC-FILE</td>
<td>Current procedure file</td>
<td>Current procedure file</td>
<td>Padded to 8 bytes</td>
</tr>
</tr>
<tr>
<tr>
<td>'SLSTATS'</td>
<td>SLSTATS</td>
<td>'PROC'</td>
<td>PROC</td>
<td>Current procedure </td>
<td>Current procedure</td>
<td>Variable length, or truncated to 21 bytes</td>
</tr>
</tr>
<tr>
<tr>
<td>'SLSTATS'</td>
<td>SLSTATS</td>
<td>'sl statistics name'</td>
<td>since-last statistics name</td>
<td>Statistics field</td>
<td>Statistics field</td>
<td>&nbsp;</td>
</tr>
</tr>
<tr>
<tr>
<td>'SYSSTATS'</td>
<td>SYSSTATS</td>
<td>'system stat name'</td>
<td>system stat name</td>
<td>Statistics field</td>
<td>Statistics field</td>
<td>&nbsp;</td>
</tr>
</tr>
<tr>
<tr>
<td>'SYSSTATS'</td>
<td>SYSSTATS</td>
<td>'DKBM stat name'</td>
<td>DKBM stat name</td>
<td>Statistics field</td>
<td>Statistics field</td>
<td>&nbsp;</td>
</tr>
</tr>
<tr>
<tr>
<td>'USRSTATS'</td>
<td>USRSTATS</td>
<td>'user stat name'</td>
<td>user stat name</td>
<td>Statistics field</td>
<td>Statistics field</td>
<td>&nbsp;</td>
</tr>
</tr>
<tr>
<tr>
<td>'USRSTATS'</td>
<td>USRSTATS</td>
<td>'conflict ctr name'</td>
<td>conflict ctr name</td>
<td>Statistics field</td>
<td>Statistics field</td>
<td>&nbsp;</td>
</tr>
</tr>
</table>
</table>
<b>Usage</b>
 
<p>The time related Since Last statistics fields, CNCT, CPU, SCHDCPU, and STCPU, are not valid during evaluation time.</p>
===Usage===
<p>Specifying an invalid statistics field name returns a null value with the message:</p>
<ul>
<p class="code">M204.1463: INVALID PARAMETER: fieldname
<li>In some cases (for example, CPU time), calculating the value of a statistic is a somewhat expensive operation, so <var>$View</var> does not force an update of its value.
</p>
<p>
<b>Syntax to view the size and use of journal and checkpoint streams</b>
Since the <var>$Stat</var> function <i>does</i> update statistics when it is issued, you might try calling <var>$Stat</var> prior to invoking <var>$View</var>.</p>
<p>The format of $VIEW for the use and size of journal and checkpoint streams is:</p>
<p>
<p class="code">$VIEW('CCAJRNL'|'CCAJLOG'|'CHKPOINT'|'CHKPNTS')
In addition, the [[UserStatistics class]] allows collection of all user statistics at once, and it has methods for calculating differences between before and after snapshots and for converting statistics to XML or to audit-trail-style <code><i>stat</i>=<i>value</i></code> format. Like <var>$Stat</var>, a <var>UserStatistics</var> constructor forces updating of all the relevant statistics.</p></li>
</p>
 
<p>Specify the following:</p>
<li>The time-related Since Last statistics fields, CNCT, CPU, SCHDCPU, and STCPU, are not valid during evaluation time.
<p class="code">%STRING = $VIEW('CCAJRNL'|'CCAJLOG'|'CHKPOINT'|'CHKPNTS')
<p>
</p>
Specifying an invalid statistics field name returns a null value with the message:</p>
<p>$VIEW returns a string that describes the usage of the specified stream with the following character format:</p>
<p class="code">M204.1463: INVALID PARAMETER: <i>fieldname</i></p>
</li>
</ul>
 
==Syntax to view the size and use of journal and checkpoint streams==
<p>
The format of <var>$View</var> for the use and size of journal and checkpoint streams is:</p>
<p class="syntax"><span class="term">%string</span> = $View('CCAJRNL'|'CCAJLOG'|'CHKPOINT'|'CHKPNTS')</p>
<p>
<var>$View</var> returns a string that describes the usage of the specified stream with the following character format:</p>
<table>
<table>
<tr>
<tr class="head">
<td>Describes </td>
<td>Describes</td>
<td>LENGTH </td>
<td>LENGTH</td>
<td>Displays</td>
<td>Displays</td>
</tr>
</tr>
<tr>
<tr>
<td>In use DDNAME</td>
<td>In use DDNAME</td>
Line 172: Line 225:
<td>Alphanumeric characters</td>
<td>Alphanumeric characters</td>
</tr>
</tr>
<tr>
<tr>
<td>Percentage used </td>
<td>Percentage used </td>
Line 177: Line 231:
<td>Integer with percentage sign</td>
<td>Integer with percentage sign</td>
</tr>
</tr>
<tr>
<tr>
<td>Maximum size </td>
<td>Maximum size </td>
Line 182: Line 237:
<td>Number of tracks</td>
<td>Number of tracks</td>
</tr>
</tr>
<tr>
<tr>
<td>Current size </td>
<td>Current size </td>
Line 187: Line 243:
<td>Number of tracks</td>
<td>Number of tracks</td>
</tr>
</tr>
<tr>
<tr>
<td>Unused spaces </td>
<td>Unused spaces </td>
Line 192: Line 249:
<td>Number of tracks</td>
<td>Number of tracks</td>
</tr>
</tr>
<tr>
<tr>
<td>VOLSER </td>
<td>VOLSER </td>
Line 197: Line 255:
<td>Alphanumeric characters</td>
<td>Alphanumeric characters</td>
</tr>
</tr>
<tr>
<tr>
<td>Separating back slash </td>
<td>Separating back slash </td>
Line 202: Line 261:
<td>A back slash</td>
<td>A back slash</td>
</tr>
</tr>
<tr>
<tr>
<td>Data set name</td>
<td>Data set name</td>
Line 207: Line 267:
<td>Data set name</td>
<td>Data set name</td>
</tr>
</tr>
<tr>
<tr>
<td>Separating back slash</td>
<td>Separating back slash</td>
Line 212: Line 273:
<td>A back slash</td>
<td>A back slash</td>
</tr>
</tr>
<tr>
<tr>
<td>Generation number </td>
<td>Generation number </td>
Line 218: Line 280:
</tr>
</tr>
</table>
</table>
<p>You must ensure that the %variable being used to hold the requested information is defined as STRING LEN 80 or greater, for example:</p>
<p>
<p class="code">%STRING IS STRING LEN 80
You must ensure that the %variable being used to hold the requested information is defined as <code>STRING LEN 80</code> or greater. For example:</p>
 
<p class="code">BEGIN
BEGIN
%STRING IS STRING LEN 80
%STRING = $VIEW('CCAJRNL')
%STRING = $VIEW('CCAJRNL')
PRINT %STRING
PRINT %STRING
END
END</p>


CCAJRNL  0%  37  0  0SU000\OHIO1.ONLINE.JOURNAL
This returns:
<p class="output">CCAJRNL  0%  37  0  0SU000\OHIO1.ONLINE.JOURNAL
</p>
</p>
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Latest revision as of 22:10, 25 January 2016

The $View function returns:

  • The value of a parameter (system, file, or user) to the request.
  • File parameters.

    While $View works for all viewable parameters in local context, it does not work for some file parameters in remote context.

  • The size and use of journal and checkpoint streams.


Syntax to view a parameter value

The format of the $View function to view parameter values is:

%string = $View(parameter[, name])

Where:

  • parameter is a character string that represents the name of a viewable Model 204 parameter or other information. For example:

    $view('ERASE')

    returns a value of @ if the ERASE parameter is set to the character @. If the parameter name is invalid or the user is not authorized to display parameter values for the file, a null string is returned.

  • name overrides the default file or group context for the function. The format for this argument is:

    [[FILE | [PERM | TEMP] GROUP] name | $Curfile | $Update] [AT location]

    If this argument is omitted or null, the default context is the context of the statement containing the function. Thus, a default context is required for this function.

    You can specify $Curfile as the name argument in place of a file/group name.

Viewing file-specific information

In addition to viewable parameters, the following file-specific information can also be viewed with $View:

Name used with $View Description
DTSLBOPR

Date and time transaction was backed out during roll forward (for TBO files)

Date and time partial transaction was applied during roll forward (for non-TBO files)

DTSLCHKP Date and time of last checkpoint rolled back to (blank if file has also been rolled forward)
DTSLRCVY Date and time of last recovery
DTSLUPDT Date and time of last update
DTSLDKWR Date and time of last DKWR
DTSLRFWD Date and time of last roll forward
FIWHEN Date and time FISTAT was reset
FIWHO Terminal ID that reset FISTAT

For example:

$View ('FIWHEN')

The result is:

FIWHEN 94.257 SEP 14 16.40.45. DATE AND TIME FISTAT WAS RESET

Syntax for viewing statistics fields

%string = $View(category, field-to-return)

Where:

  • category is SLSTATS, SYSSTATS, or USRSTATS.
  • field-to-return is the name of the statistic field to return. See Description of statistics for the names of the statistics fields.

The following categories and fields are valid:

Valid categories and fields with $View
Category Statistics field to return Equivalent-to or returns-value-of Remarks
SLSTATS USERID $Userid Padded with blank spaces to 10 bytes
SLSTATS ACCOUNT $Account Padded to 10 bytes
SLSTATS SUBSYSTEM $Subsys with no argument Padded to 10 bytes
SLSTATS LAST LAST=field EVAL etc.
SLSTATS PROC-FILE Current procedure file Padded to 8 bytes
SLSTATS PROC Current procedure Variable length, or truncated to 21 bytes
SLSTATS since-last statistics name Statistics field  
SYSSTATS system stat name Statistics field  
SYSSTATS DKBM stat name Statistics field  
USRSTATS user stat name Statistics field  
USRSTATS conflict ctr name Statistics field  

Usage

  • In some cases (for example, CPU time), calculating the value of a statistic is a somewhat expensive operation, so $View does not force an update of its value.

    Since the $Stat function does update statistics when it is issued, you might try calling $Stat prior to invoking $View.

    In addition, the UserStatistics class allows collection of all user statistics at once, and it has methods for calculating differences between before and after snapshots and for converting statistics to XML or to audit-trail-style stat=value format. Like $Stat, a UserStatistics constructor forces updating of all the relevant statistics.

  • The time-related Since Last statistics fields, CNCT, CPU, SCHDCPU, and STCPU, are not valid during evaluation time.

    Specifying an invalid statistics field name returns a null value with the message:

    M204.1463: INVALID PARAMETER: fieldname

Syntax to view the size and use of journal and checkpoint streams

The format of $View for the use and size of journal and checkpoint streams is:

%string = $View('CCAJRNL'|'CCAJLOG'|'CHKPOINT'|'CHKPNTS')

$View returns a string that describes the usage of the specified stream with the following character format:

Describes LENGTH Displays
In use DDNAME 8 Alphanumeric characters
Percentage used 4 Integer with percentage sign
Maximum size 9 Number of tracks
Current size 9 Number of tracks
Unused spaces 2 Number of tracks
VOLSER 6 Alphanumeric characters
Separating back slash 1 A back slash
Data set name Variable Data set name
Separating back slash 1 A back slash
Generation number Variable Generation number with a leading plus sign

You must ensure that the %variable being used to hold the requested information is defined as STRING LEN 80 or greater. For example:

BEGIN %STRING IS STRING LEN 80 %STRING = $VIEW('CCAJRNL') PRINT %STRING END

This returns:

CCAJRNL 0% 37 0 0SU000\OHIO1.ONLINE.JOURNAL