$LstFld: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (misc cleanup)
m (loopvar length is 16 like in ZFIELD)
 
Line 1: Line 1:
<p>
<p>
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>
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>
<p>
<var>$LstFld</var> works only for files (not groups). </p>
<var>$LstFld</var> works only for files (not groups). </p>
Line 46: Line 46:


<tr><th>loopvar</th>
<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.  
<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>
<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>
Line 52: Line 55:
==Locating the ZFIELD image==
==Locating the ZFIELD image==
<p>
<p>
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>
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>
<p>
<p>
The size of the name field for the ZFIELD image is 255 bytes. </p>
The size of the name field for the ZFIELD image is 255 bytes. </p>

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