View source for $FDef

<p>
The <var>$FDef</var> function lets you access the attributes of a field from within a <var class="product">Model&nbsp;204</var> procedure. <var>$FDef</var> maps the attributes of a field, whose values can then be read via an image similar to the [[ZFIELD image]]. Unlike <var>$Dscr</var>, which <var>$FDef</var> supplants, the attributes are displayed in a readable fashion without parsing. </p>
<p>
<var>$FDef</var> works for files only (not for groups). </p>

==Syntax==
<p>
The format for the <var>$FDef</var> function is:
</p>
<p class="syntax">%<span class="term">image</span>:<span class="term">item</span> = $FDef(<var>[</var>File<var>]</var> <span class="term">filename</span> <var>[</var>At <span class="term">location</span><var>]</var>, <span class="term">fieldname</span>)
</p>
<table>
<tr><th>%image:item</th>
<td>The image item to which <var>$FDef</var> returns the data. </td></tr>

<tr><th>filename</th>
<td>A %variable or a literal name of the file. A file synonym name can also be used. 
<p>
If <var class="term">filename</var> is the name of a group, the <var>$FDef</var> function assumes that the name passed is a file name, not a group name. </p></td></tr>
 
<tr><th>location</th>
<td>The name of the remote node where the file is located. </td></tr>
 
<tr><th>fieldname</th>
<td>A %variable or a literal name of the field to be described. </td></tr>
</table>

==Usage notes==
<ul>
<li>An image is required by the <var>$FDef</var> and <var>$LstFld</var> functions. The ZFIELD image, which can give you complete field attribute information (see [[ZFIELD image#Image definition|ZFIELD image details]]), is provided by the <var class="product">Model&nbsp;204</var> installation software. 
<p>
If you write your own image, be aware that <var>$FDef</var> maps to the locations of the image items, rather than the names. </p></li>

<li>If the field specified in the <var>$FDef</var> argument is not defined in the opened file specified by <var class="term">filename</var>, <var>$FDef</var> returns a <code>U</code> (undefined) in the second ZFIELD image item (<code>DEFER.Y_N</code>). If the file is not open, a <code>U</code> is returned in the <code>DEFER.Y_N</code> image item, and an <code>N</code> is returned in the third image item (<code>FRV.Y_N</code>). </li>

<li>The <code>FIELD.CODE</code> image item is unique for each field within a file. However, this value cannot remain constant for any one field over time, and it cannot be the same for the same field name in different files. Field names do not always hash to the same field codes because of deleted fields and hash collisions. 
<p>
The <code>FIELD.CODE</code> returned in the ZFIELD image is the same as that which appears in CCAJRNL <code>RECTYPE=6</code> entries. This information is valuable for Technical Support in case you need to run <var>REGENERATE</var> but cannot because you are missing one or more CCAJRNL data sets since your last <var>DUMP</var> of the file. </p></li>
</ul>

==Example==
<p>
In the following example, you provide a field name and <var class="product">Model&nbsp;204</var> displays output that indicates if the field is <var>KEY</var> or preallocated. If the field is preallocated, <var class="product">Model&nbsp;204</var> also displays the number of occurrences and the length of the field. </p>
<p>
This procedure maps the <var>$FDef</var> output to the ZFIELD image. Therefore, if the field is <var>KEY</var>, then the <code>KEY.Y_N</code> image item contains a <code>Y</code>. 
</p>
<p class="code">PROCEDURE DISPFLD
OPEN DAILY
OPENC VEHICLES
XXXX
BEGIN
%FIELD IS STRING LEN 50
%FIELD = $READ('ENTER FIELDNAME') 
<b></b>*                                                           *
<b></b>* include the ZFIELD proc and prepare the ZFIELD image      *
<b></b>*                                                           *
INCLUDE ZFIELD
PREPARE IMAGE ZFIELD
<b></b>*                                                           *
<b></b>* use the FDEF image item in ZFIELD to check the fieldname  *
<b></b>*                                                           *
%ZFIELD:FDEF = $FDEF('VEHICLES',%FIELD) 
IF %ZFIELD:KEY.Y_N = 'Y' THEN
   PRINT %FIELD ' IS KEY'
ELSE 
   PRINT %FIELD ' IS NOT A KEY FIELD'
END IF
IF %ZFIELD:OCCURS > '0' THEN
   PRINT %FIELD ' IS PREALLOCATED, WITH ' -
      %ZFIELD:OCCURS ' VALUES'
   PRINT 'THE LENGTH OF ' %FIELD ' IS ' %ZFIELD:LENGTH
ELSE 
   PRINT %FIELD ' IS NOT PREALLOCATED'
END IF
END
</p>
<p>
The following is the output produced by the procedure <code>DISPFLD</code> for the field <code>DEDUCTIBLE</code>: </p>
<p class="output">INCLUDE DISPFLD

??ENTER FIELD NAME
DEDUCTIBLE
DEDUCTIBLE IS KEY
DEDUCTIBLE IS PREALLOCATED WITH 1 VALUES
THE LENGTH OF DEDUCTIBLE IS 3
</p>

[[Category:SOUL $functions]]