$FDef: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (misc formatting)
m (minor word change)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
<p>
<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 described below in [[#The ZFIELD image|The ZFIELD image]]. Unlike <var>$Dscr</var>, which <var>$FDef</var> supplants, the attributes are displayed in a readable fashion without parsing. <var>$FDef</var> works only for files (not groups). </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==
==Syntax==
Line 6: Line 8:
The format for the <var>$FDef</var> function is:
The format for the <var>$FDef</var> function is:
</p>
</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>, fieldname)
<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>
</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>
<p>
Where:</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>
<ul>
<li>%<var class="term">image</var>:<var class="term">item</var> is the image item to which <var>$FDef</var> returns the data. </li>
 
<li><var class="term">filename</var> is a %variable or a literal name of the file. A file synonym name can also be used. When <var class="term">filename</var>=<var class="term">groupname</var> the <var>$FDef</var> function assumes that the name passed is a file name, not a group name. </li>
   
   
<li><var class="term">location</var> is the name of the remote node where the file is located. </li>
<tr><th>location</th>
<td>The name of the remote node where the file is located. </td></tr>
   
   
<li><var class="term">fieldname</var> is a %variable or a literal name of the field to be described. </li>
<tr><th>fieldname</th>
</ul>
<td>A %variable or a literal name of the field to be described. </td></tr>
<p>
</table>
If the field specified in the <var>$FDef</var> argument is not defined in the opened file specified by filename, <var>$FDef</var> returns a <code>U</code> (undefined) in the second image item (<code>DEFER.Y_N</code>). If the file is not open, a <code>U</code> is returned in the second (<code>DEFER.Y_N</code>) image item, and an <code>N</code> is returned in the third (<code>FRV.Y_N</code>) image item.</p>
<p>
<code>FIELD.CODE</code>, which is returned in the 21st 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>
<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>


==The ZFIELD image==
==Usage notes==
<p>
<ul>
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 for $FDEF and $LSTFLD|ZFIELD image for $FDEF and $LSTFLD]], below), is provided by the <var class="product">Model&nbsp;204</var> installation software.  
<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>
<p class="note"><b>Note:</b> When using ZFIELD, be aware that <var>$FDef</var> output maps to the ZFIELD image. Therefore, do not change the order of the image items in ZFIELD. </p>
<p>
<p>
The location of ZFIELD for your site is listed in this table: </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>
<table>
<tr class="head">
<th>If your site runs under...</th>
<th>Then the ZFIELD image is stored in...</th>
</tr>


<tr>
<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>
<td>z/OS</td>
<td>The JCL library</td>
</tr>


<tr>
<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.
<td>z/VM</td>
<p>
<td>On the 193 MAINT204 disk</td>
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>
</tr>
</ul>


<tr>
==Example==
<td>z/VSE</td>
<p>
<td>The JCL library</td>
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>
</tr>
</table>
 
===Example===
<p>
<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. This procedure maps the <var>$FDef</var> output to the ZFIELD image (shown in the following section). Therefore, if the field is <var>KEY</var>, then the <code>KEY.Y_N</code> image item contains a <code>Y</code>.  
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>
<p class="code">PROCEDURE DISPFLD
<p class="code">PROCEDURE DISPFLD
Line 100: Line 86:
</p>
</p>


===ZFIELD image for $FDEF and $LSTFLD===
<p>
The following image can be used by the <var>$FDef</var> and <var>$LstFld</var> functions. 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>
<p class="code">IMAGE ZFIELD
NAME                IS STRING LEN 255
DEFER.Y_N            IS STRING LEN 1
FRV.Y_N              IS STRING LEN 1
KEY.Y_N              IS STRING LEN 1
MANY.VALUED.Y_N      IS STRING LEN 1
CODED.Y_N            IS STRING LEN 1
STRING.Y_N          IS STRING LEN 1
NUMERIC.RANGE.Y_N    IS STRING LEN 1
INVISIBLE.Y_N        IS STRING LEN 1
SECURED.Y_N          IS STRING LEN 1
UPDATE.IN.PLACE.Y_N  IS STRING LEN 1
OCCURS.Y_N          IS STRING LEN 1
FLOAT.Y_N            IS STRING LEN 1
ORD.NUM.Y_N          IS STRING LEN 1
ORD.CHAR.Y_N        IS STRING LEN 1
PURE.DBCS.Y_N        IS STRING LEN 1
MIXED.DBCS.Y_N      IS STRING LEN 1
UNIQUE.Y_N          IS STRING LEN 1
OCCURS.ONCE.Y_N      IS STRING LEN 1
CLOB.Y_N            IS STRING LEN 1
BLOB.Y_N            IS STRING LEN 1
FUTURE.EXPANSION    IS STRING LEN 34
FIELD.CODE          IS BINARY LEN 4 UNSIGNED
ORDERED.Y_N          IS STRING LEN 1
LENGTH              IS BINARY LEN 1 UNSIGNED
LEVEL                IS BINARY LEN 1 UNSIGNED
LRESERVE            IS BINARY LEN 1 UNSIGNED
NRESERVE            IS BINARY LEN 1 UNSIGNED
SPLITPCT            IS BINARY LEN 1 UNSIGNED
NO.OF.IMMEDIATES    IS BINARY LEN 1 UNSIGNED
OCCURS              IS BINARY LEN 1 UNSIGNED
PAD.CHAR            IS STRING LEN 1
FDEF                IS STRING LEN 67 AT DEFER.Y_N
BIN1                IS BINARY LEN 4 UNSIGNED
BIN2                IS BINARY LEN 4 UNSIGNED
BIN3                IS BINARY LEN 4 UNSIGNED
BIN4                IS BINARY LEN 4 UNSIGNED
LOOPVAR              IS STRING LEN 16 AT BIN1
END IMAGE
</p>
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Latest revision as of 18:10, 15 June 2018

The $FDef function lets you access the attributes of a field from within a Model 204 procedure. $FDef maps the attributes of a field, whose values can then be read via an image similar to the ZFIELD image. Unlike $Dscr, which $FDef supplants, the attributes are displayed in a readable fashion without parsing.

$FDef works for files only (not for groups).

Syntax

The format for the $FDef function is:

%image:item = $FDef([File] filename [At location], fieldname)

%image:item The image item to which $FDef returns the data.
filename A %variable or a literal name of the file. A file synonym name can also be used.

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

location The name of the remote node where the file is located.
fieldname A %variable or a literal name of the field to be described.

Usage notes

  • An image is required by the $FDef and $LstFld functions. The ZFIELD image, which can give you complete field attribute information (see ZFIELD image details), is provided by the Model 204 installation software.

    If you write your own image, be aware that $FDef maps to the locations of the image items, rather than the names.

  • If the field specified in the $FDef argument is not defined in the opened file specified by filename, $FDef returns a U (undefined) in the second ZFIELD image item (DEFER.Y_N). If the file is not open, a U is returned in the DEFER.Y_N image item, and an N is returned in the third image item (FRV.Y_N).
  • The FIELD.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.

    The FIELD.CODE returned in the ZFIELD image is the same as that which appears in CCAJRNL RECTYPE=6 entries. This information is valuable for Technical Support in case you need to run REGENERATE but cannot because you are missing one or more CCAJRNL data sets since your last DUMP of the file.

Example

In the following example, you provide a field name and Model 204 displays output that indicates if the field is KEY or preallocated. If the field is preallocated, Model 204 also displays the number of occurrences and the length of the field.

This procedure maps the $FDef output to the ZFIELD image. Therefore, if the field is KEY, then the KEY.Y_N image item contains a Y.

PROCEDURE DISPFLD OPEN DAILY OPENC VEHICLES XXXX BEGIN %FIELD IS STRING LEN 50 %FIELD = $READ('ENTER FIELDNAME') * * * include the ZFIELD proc and prepare the ZFIELD image * * * INCLUDE ZFIELD PREPARE IMAGE ZFIELD * * * use the FDEF image item in ZFIELD to check the fieldname * * * %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

The following is the output produced by the procedure DISPFLD for the field DEDUCTIBLE:

INCLUDE DISPFLD ??ENTER FIELD NAME DEDUCTIBLE DEDUCTIBLE IS KEY DEDUCTIBLE IS PREALLOCATED WITH 1 VALUES THE LENGTH OF DEDUCTIBLE IS 3