$LstFld: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
m (misc cleanup)
Line 1: Line 1:
<p>The $LSTFLD function returns field names in alphabetical order and the field description for each field in a file into an image. $LSTFLD requires that you have an image prepared with which <var class="product">Model&nbsp;204</var> can create the field description. $LSTFLD works only for files (not groups).</p>
<p>
<b>Syntax</b>
The <var>$LstFld</var> function returns to an [[Images|image]] the field names (in alphabetical order) and the field descriptions of each field in a file. <var>$LstFld</var> requires a prepared image into which <var class="product">Model&nbsp;204</var> can store the field description. </p>
<p>The format for the $LSTFLD function is:</p>
<p>
<p class="code">%variable = $LSTFLD(<var>[</var>FILE<var>]</var> filename
<var>$LstFld</var> works only for files (not groups). </p>


<var>[</var>AT location<var>]</var>,imagename,loopvar)
==Syntax==
<p>
The format for the <var>$LstFld</var> function is:
</p>
</p>
<p>where:</p>
<p class="syntax"><span class="term">%rc</span> = $LstFld(<span class="squareb">[</span>FILE<span class="squareb">]</span> <span class="term">filename</span> <span class="squareb">[</span>AT <span class="term">location</span><span class="squareb">]</span>,<span class="term">imagename</span>,<span class="term">loopvar</span>)
<ul>
</p>
<li>%variable is the %variable in which the return codes are stored. The return codes are:</li>
<table>
<tr><th>%rc</th>
<td>A numeric %variable to receive a return code. The return codes are:
<table>
<table>
<tr class="head">
<tr class="head">
<th>Setting</th>
<th>Setting</th>
<th>Meaning</th>
<th>Meaning</th></tr>
</tr>
 
<tr>
<tr><td align="right">0</td>
<td align="right">0</td>
<td>Success</td></tr>
<td>Success</td>
 
</tr>
<tr><td>1</td>
<tr>
<td>End of field list reached</td></tr>
<td align="right">1</td>
 
<td>End of field list reached</td>
<tr><td>2</td>
</tr>
<td>Requested file not available, or is not open, or is not initialized </td></tr>
<tr>
 
<td align="right">2</td>
<tr><td>3</td>
<td>Requested file not available, or is not open, or is not initialized</td>
<td>VTBL full or sort not available </td></tr>
</tr>
 
<tr>
<tr><td>4</td>
<td align="right">3</td>
<td>Error occurred during function processing </td></tr>
<td>VTBL full or sort not available</td>
</table>
</tr>
</td></tr>
<tr>
 
<td align="right">4</td>
<tr><th>filename </th>
<td>Error occurred during function processing</td>
<td>This required argument is the name of the file that contains the fields. A file synonym name can also be used.
</tr>
<p>
If you specify a null argument for the file location (<var>At</var> phrase),  <var class="product">Model&nbsp;204</var> uses the reference context (at compile time) of the statement that calls the function. </p>
<p>
If <var class="term">filename</var> is the name of a group, <var>$LstFld</var> assumes that the name passed is a file name, not a group name. </p></td></tr>
 
<tr><th>imagename </th>
<td>This required argument is the name of the image to which the information is returned. </td></tr>
 
<tr><th>loopvar</th>
<td>This required argument is the loop variable of the image. You must initialize the loop variable (as in the sample image shown with the <var>$FDef</var> function) before invoking <var>$LstFld</var>. The value returned in <var class="term">loopvar</var> is used the next time <var>$LstFld</var> is invoked to retrieve subsequent field names.
<p class="note"><b>Note:</b> Changing any of the loop control information in the <var>$LstFld</var> loop variable after the image is initialized is not allowed; it might cause the run to snap. </p></td></tr>
</table>
</table>
</li>
 
<li>filename (required) is the name of the file that contains the fields. A file synonym name can also be used. If you do not enter a location, specifying a null argument, <var class="product">Model&nbsp;204</var> uses the reference context (at compile time) of the statement which calls the function. When filename=groupname the $LSTFLD function assumes that the name passed is a file name, not a group name.</li>
==Locating the ZFIELD image==
</li>
<p>
<li>imagename (required) is the name of the image where the information is to return.</li>
An image is required by the <var>$LstFld</var> function. The [[ZFIELD image]], provided with the <var class="product">Model&nbsp;204</var> installation, can give you complete field attribute information (as described in [[$FDef#$FDef|$FDef]]). </p>
</li>
<p>
<li>loopvar (required) is the loop variable of the image. You must initialize the loop variable (as in the sample image shown with the $FDef function) before invoking $LSTFLD. The value returned in loopvar is used the next time $LSTFLD is invoked to retrieve subsequent field names. </li>
The size of the name field for the ZFIELD image is 255 bytes. </p>
</li>
<p>
</ul>
The location of ZFIELD for your site is shown below: </p>
<b>Note</b>
<p>Like $LSTPROC, changing any of the loop control information in the $LSTFLD loop variable after the image is initialized is not allowed and might cause the run to snap.</p>
<b>Locating the ZFIELD image</b>
<p>An image is required by the $FDef and $LSTFLD functions. The [[ZFIELD image]] is provided with the <var class="product">Model&nbsp;204</var> installation. It can give you complete field attribute information; see the discussion on [[$FDef#$FDef|$FDef]]. The size of the name field for the ZFIELD image is 255 bytes. The location of ZFIELD for your site is listed in this table:     </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 52: Line 62:
<th>Storage location of the ZFIELD image</th>
<th>Storage location of the ZFIELD image</th>
</tr>
</tr>
<tr>
<tr>
<td>z/OS</td>
<td>z/OS</td>
<td>V7.5 and later: The distributed macro library <br>Pre-V7.5: The distributed JCL library </td>
<td>V7.5 and later: The distributed macro library <br>Pre-V7.5: The distributed JCL library </td>
</tr>
</tr>
<tr>
<tr>
<td>z/VM</td>
<td>z/VM</td>
<td>On the 193 MAINT204 disk as an EXEC</td>
<td>On the 193 MAINT204 disk as an EXEC</td>
</tr>
</tr>
<tr>
<tr>
<td>z/VSE</td>
<td>z/VSE</td>
Line 65: Line 78:
</tr>
</tr>
</table>
</table>
<b>Example</b>
 
<p>In this example, the procedure DFIELDS displays the name and definition of each field in the file specified by %FILE.</p>
==Example==
<p>
In this example, the procedure <code>DFIELDS</code> displays the name and definition of each field in the file specified by <code>%FILE</code>. </p>
<p class="code">PROCEDURE DFIELDS
<p class="code">PROCEDURE DFIELDS
BEGIN
BEGIN
Line 92: Line 107:
END PROCEDURE
END PROCEDURE
</p>
</p>
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Revision as of 18:09, 15 June 2018

The $LstFld function returns to an image the field names (in alphabetical order) and the field descriptions of each field in a file. $LstFld requires a prepared image into which Model 204 can store the field description.

$LstFld works only for files (not groups).

Syntax

The format for the $LstFld function is:

%rc = $LstFld([FILE] filename [AT location],imagename,loopvar)

%rc A numeric %variable to receive a return code. The return codes are:
Setting Meaning
0 Success
1 End of field list reached
2 Requested file not available, or is not open, or is not initialized
3 VTBL full or sort not available
4 Error occurred during function processing
filename This required argument is the name of the file that contains the fields. A file synonym name can also be used.

If you specify a null argument for the file location (At phrase), Model 204 uses the reference context (at compile time) of the statement that calls the function.

If filename is the name of a group, $LstFld assumes that the name passed is a file name, not a group name.

imagename This required argument is the name of the image to which the information is returned.
loopvar This required argument is the loop variable of the image. You must initialize the loop variable (as in the sample image shown with the $FDef function) before invoking $LstFld. The value returned in loopvar is used the next time $LstFld is invoked to retrieve subsequent field names.

Note: Changing any of the loop control information in the $LstFld loop variable after the image is initialized is not allowed; it might cause the run to snap.

Locating the ZFIELD image

An image is required by the $LstFld function. The ZFIELD image, provided with the Model 204 installation, can give you complete field attribute information (as described in $FDef).

The size of the name field for the ZFIELD image is 255 bytes.

The location of ZFIELD for your site is shown below:

Operating system Storage location of the ZFIELD image
z/OS V7.5 and later: The distributed macro library
Pre-V7.5: The distributed JCL library
z/VM On the 193 MAINT204 disk as an EXEC
z/VSE The JCL library

Example

In this example, the procedure DFIELDS displays the name and definition of each field in the file specified by %FILE.

PROCEDURE DFIELDS BEGIN * * include ZFIELD IMAGE as defined for $FDef * * PRINT 'DFIELDS STARTS' %FILE = '??FILE' NP PREPARE ZFIELD %ZFIELD:BIN1 = 0 %ZFIELD:BIN2 = 0 %ZFIELD:BIN3 = 0 %ZFIELD:BIN4 = 0 %X = 0 REPEAT WHILE %X = 0 %X = $LSTFLD(%FILE,'ZFIELD',%ZFIELD:LOOPVAR) IF %X = 0 THEN PRINT %ZFIELD:NAME PRINT %ZFIELD:FDEF END IF END REPEAT PRINT '-- END OF FIELDS RC=' %X END END PROCEDURE

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