$LstFld: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Mlarocca moved page $LSTFLD to $LstFld: Lower case change)
m (loopvar length is 16 like in ZFIELD)
 
(7 intermediate revisions by 3 users not shown)
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. That image must be or match the [[#Locating the ZFIELD image|ZFIELD image described below]]. </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, a string of length 16, matches the loop variable of the ZFIELD image. The argument value must be an image item that is at its proper location (as defined in ZFIELD) in the <var class="term">imagename </var> image.
<p>
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>
<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>
The <var>$LstFld</var> function references the format of the [[ZFIELD image]], which is provided with the <var class="product">Model&nbsp;204</var> installation. The ZFIELD image describes 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 65:
<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>The 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 81:
</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
<b></b>*
<b></b>*
<b></b>* include ZFIELD IMAGE as defined for $FDEF     *
<b></b>* include ZFIELD IMAGE as defined for $FDef     *
<b></b>*
<b></b>*
PRINT 'DFIELDS STARTS'
PRINT 'DFIELDS STARTS'
Line 92: Line 110:
END PROCEDURE
END PROCEDURE
</p>
</p>
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Latest revision as of 16:32, 3 July 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. That image must be or match the ZFIELD image described below.

$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, a string of length 16, matches the loop variable of the ZFIELD image. The argument value must be an image item that is at its proper location (as defined in ZFIELD) in the imagename 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

The $LstFld function references the format of the ZFIELD image, which is provided with the Model 204 installation. The ZFIELD image describes 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=116479"