Managing fields manually: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (link repair)
 
(25 intermediate revisions by 7 users not shown)
Line 1: Line 1:
==Overview==
==Overview==
<p>This chapter describes the [[REDEFINE command|REDEFINE]], [[DELETE command: Field|DELETE]], and [[RENAME FIELD command|RENAME]] commands, which allow you to redefine many field attributes, to delete a field's description and all its occurrences in the data, and to rename fields. For the complete syntax and description of these commands, please follow the links.</p>
<p>
<p>'''Note''' that new fields and Repeating Field Groups may may be added by the file manager at any time (although some attributes may not be assigned to these new fields (such as the [[#Field Design (File Management)#Preallocated Fields|OCCurs attribute]] to preallocate a field) once data has been added to the file. See [[Field Design (File Management)|Field Design]] for more details.)</p> 
This page describes the <var>[[REDEFINE command|REDEFINE]]</var>, <var>[[DELETE command: Field|DELETE]]</var>, and <var>[[RENAME FIELD command|RENAME]]</var> commands, which allow you to redefine many field attributes, to delete a field's description and all its occurrences in the data, and to rename fields. For the complete syntax and description of these commands, please follow the links.</p>


<p>After creating a file and adding fields, you can perform the following field management tasks:</p>
<p class="note">'''Note:''' New fields and Repeating Field Groups may may be added by the file manager at any time (although some attributes may not be assigned to these new fields (such as the [[Field design#Preallocated fields (OCCURS attribute)|OCCurs attribute]] to preallocate a field) once data has been added to the file. See [[Field design]] for more details.)</p> 
 
<p>
After creating a file and adding fields, you can perform the following field management tasks:</p>
<ul>
<ul>
<li>Redefine fields</li>
<li>Redefine fields</li>
Line 9: Line 12:
<li>Deleting fields</li>
<li>Deleting fields</li>
<li>Renaming fields</li>
<li>Renaming fields</li>
<li>Reclaiming space in files</li>
</ul>
</ul>


<p>The operative word is 'can', which does not always mean that you should. If you have a large file, and are performing actions which cause Table B to be read in its entirety (the DELETE of a number of fields, or REDEFINING fields to be indexed for example) you should consider whether it may be more efficient to [[File Reorganization and Table Compaction|reorganize]] the file.</p>
<p>
The operative word is "can," which does not always mean that you should. If you have a large file and are performing actions that cause Table B to be read in its entirety (the <var>DELETE</var> of a number of fields, or <var>REDEFINE</var> of fields to be indexed, for example), consider whether it may be more efficient to [[File reorganization and table compaction|reorganize]] the file.</p>


==Redefining fields==
==Redefining fields==
<p>The REDEFINE command and the IFRFLD Host Language Interface function allow you to alter a field definition without requiring that the file be reinitialized, with exceptions noted below.</p>
<p>
The <var>REDEFINE</var> command and the <var>IFRFLD</var> Host Language Interface function allow you to alter a field definition without requiring that the file be reinitialized, with exceptions noted below.</p>


<p>The format of REDEFINE is:</p>
<p>The format of <var>REDEFINE</var> is:</p>
<b>Syntax</b>
<b>Syntax</b>
<p class="code">REDEFINE [FIELD] {<var class="term">field_desc</var> [<var class="term">field_desc</var> ...] |
<p class="syntax">REDEFINE <span class="squareb">[</span>FIELD<span class="squareb">]</span> <span class="squareb">{</span><span class="term">field_desc</span> <span class="squareb">[</span><span class="term">field_desc</span> ...<span class="squareb">]</span> <span class="squareb">|</span> <span class="term">fieldname</span> WITH <span class="term">attribute</span> <span class="squareb">[</span><span class="term">attribute</span> ...<span class="squareb">]</span><span class="squareb">}</span>
 
  <var class="term">fieldname</var> WITH <var class="term">attribute</var> [<var class="term">attribute</var> ...]}
</p>
</p>
<p>where:</p>
<p>
<p>field_desc takes the form:</p>
Where:</p>
<p class="code"><var class="term">fieldname</var> [(<var class="term">attribute</var> [,[<var class="term">attribute</var> ...]])]
<p>
<var class="term">field_desc</var> takes the form:</p>
<p class="syntax"><span class="term">fieldname</span> <span class="squareb">[</span>(<span class="term">attribute</span> <span class="squareb">[</span>,<span class="squareb">[</span><span class="term">attribute</span> ...<span class="squareb">]</span>)<span class="squareb">]</span><span class="squareb">]</span>
</p>
</p>
<ul>
<ul>
<li>fieldname is the name of a field in the open <var class="product">Model&nbsp;204</var> file.</li>
<li><var class="term">fieldname</var> is the name of a field in the open <var class="product">Model&nbsp;204</var> file.</li>
<li>attribute is one of the attributes listed in [[#Redefining fields|Redefining fields]]. In the REDEFINE command, you need to specify only the attributes being changed for the field.</li>
 
<li><var class="term">attribute</var> is one of the attributes listed in the [[REDEFINE command#Syntax|REDEFINE command description]]. In the <var>REDEFINE</var> command, you need to specify only the attributes being changed for the field.</li>
</ul>
</ul>
<b>Example</b>
<b>Example</b>
<p>The following command changes two attributes of the previously defined CUSTID field:</p>
<p>
<p>Before:</p>
The following command changes two attributes of the previously defined CUSTID field:</p>
<p>
Before:</p>
<p class="code">DEFINE FIELD CUSTID WITH FRV KEY
<p class="code">DEFINE FIELD CUSTID WITH FRV KEY
</p>
</p>
<p>After:</p>
<p>
After:</p>
<p class="code">REDEFINE FIELD CUSTID WITH NON-FRV NON-KEY ORDERED CHAR
<p class="code">REDEFINE FIELD CUSTID WITH NON-FRV NON-KEY ORDERED CHAR
</p>
</p>
<p>Not all the field attributes that can be specified in the DEFINE command can be changed by a REDEFINE command. [[#Redefining fields|Redefining fields]] summarizes the supported options.</p>
 
====Field attributes and the REDEFINE command====
<p>
Not all the field attributes that can be specified in the <var>DEFINE</var> command can be changed by a <var>REDEFINE</var> command. The following table summarizes the options.</p>
<p>
See [[Field design]] for a full discussion of the classifications and attributes.</p>
 
<table>
<table>
<caption>Field attributes with the REDEFINE command</caption>
<caption>Field attributes and the REDEFINE command</caption>
<tr class="head">
<tr class="head">
<th>Field description attribute</th>
<th>Field classification</th>
<th>Abbreviation</th>
<th>Attributes</th>
<th>Allowed?</th>
<th>Notes</th>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>Indexing options</td>
<p>KEY</p>
<td nowrap>ORD CHAR or ORD NUM
<p>NON-KEY</p>
<p>KEY or NKEY</p>
<p>FRV or NFRV</p>
<p>RANGE or NRANGE</p>
</td>
</td>
<td rowspan="2">
<td>Yes</td>
<p>-</p>
<td>Model 204 adds (or removes) entries to the index when these are redefined. If the index fills up, Model 204 displays an error message and the redefine fails.
<p>NKEY</p>
<p>
If TBO is enabed, the field is restored to its original status.<br>
If TBO is disabled (FOPT=X'02') and the redefine fails, the file will be broken.</p>
<p>
Also, see limitation for INVISIBLE fields, [[#Redefining the index on INVISIBLE fields|below]].</p>
</td>
</td>
</tr>
</tr>
<tr>
<tr>
<td>Data type</td>
<td>All</td>
<td>No</td>
<td></td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td rowspan=2>Data content</td>
<p>[NUMERIC] RANGE</p>
<td nowrap> a) FV or MV
<p>NON-RANGE</p>
<p>b) UP or UE</p>
<p>c) DV</p>
<p>d) ONE, EXONE, or REPT</p>
<p>e) DEF or NDEF</p>
</td>
</td>
<td rowspan="2">
<td>Yes</td>
<p>NR</p>
<td>a) Only valid for COD or FRV fields
<p>NNR</p>
<p>b) Not allowed with INVISIBLE fields</p>
<p>c) ONE or EXONE fields only </p>
</td>
</td>
</tr>
</tr>
<tr>
<tr>
</tr>
<td>COD or NCOD
<tr>
<p>OCC</p>
<td rowspan="2">
<p>LEN</p>
<p>ORDERED</p>
<p>PAD</p>
<p>NON-ORDERED</p>
<p>SD or SN</p>
</td>
<td rowspan="2">
<p>ORD</p>
<p>NORD</p>
</td>
</td>
<td>No</td>
<td></td>
</tr>
</tr>
<tr>
<tr>
<td>Concatenated fields</td>
<td>All</td>
<td>No</td>
<td></td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<p>FRV</p>
<p>NON-FRV</p>
</td>
<td rowspan="2">
<p>-</p>
<p>NFRV</p>
</td>
</tr>
<tr>
<tr>
<td>Automatic fields</td>
<td>All</td>
<td>No</td>
<td></td>
</tr>
</tr>
<tr>
<tr>
<td rowspan="2">
<td>Field and content constraints</td>  
<p>DEFERRABLE</p>
<td>All</td>
<p>NON-DEFERRABLE</p>
<td>Yes</td>
</td>
<td>See limitations on UNIQUE, [[#Redefining UNIQUE fields|below]].<br>
<td rowspan="2">
The redefinitions do not validate existing occurrences, so if you have a field containing 9999 and then set INTLE to 1000, no error will occur.
<p>DEF</p>
<p>NDEF</p>
</td>
</tr>
<tr>
</tr>
<tr>
<td rowspan="2">
<p>FEW-VALUED</p>
<p>MANY-VALUED</p>
</td>
<td rowspan="2">
<p>FV</p>
<p>MV</p>
</td>
</tr>
<tr>
</tr>
<tr>
<td rowspan="2">
<p>UPDATE IN PLACE</p>
<p>UPDATE AT END</p>
</td>
<td rowspan="2">
<p>UP</p>
<p>UE</p>
</td>
</tr>
<tr>
</tr>
<tr>
<td>LEVEL k</td>
<td>LVL k</td>
</tr>
<tr>
<td rowspan="2">
<p>UNIQUE</p>
<p>NON-UNIQUE</p>
</td>
<td rowspan="2">
<p>UNIQ</p>
<p>NUNIQ</p>
</td>
</td>
</tr>
</tr>
<tr>
<tr>
<td>Repeating Field Group</td>
<td>FIELDGROUP attribute</td>
<td>No</td>
<td>Fields may not be redefined into or out of a field group.</td>
</tr>
</tr>
</table>
</table>
<p>Field attributes are introduced in [[ Field Design (File Management)|Field Design]] .</p>
<p>Changing a field's security level to 0 desecures the field. Refer to <b>See Field-level security</b> for more information.</p>
<p class="note"><b>Note:</b> Redefining fields will take a substantial amount of CPU time. When a KEY, NUMERIC RANGE, or ORDERED attribute is changed for a VISIBLE field, <var class="product">Model&nbsp;204</var> must modify the index entries that correspond to each occurrence of the field in Table B.  </p>
<p>When a field is redefined to add an indexed attribute, every record containing that field will have its index entry in Table C or D updated.</p>
===Restrictions:===
<p>Fields may not be redefined to or from [[#Field Design (File Management)#Preallocated Fields|OCCurs]].</p>


<p>Fields may not be redefined in to or out of a [[#Field Design (File Management)#FIELDGROUP attribute|Repeating Field Group]].</p>  
<p>
Changing a field's security level to 0 desecures the field. Refer to [[Model 204 security features#Field-level security|Field-level security]] for more information.</p>


<p>Fields may not be redefined to or from [[#Field Design (File Management)#BLOB CLOB or MINLOBE attributes|a large object]].</p>  
<p class="note"><b>Note:</b> Redefining fields may take a substantial amount of CPU time. When a <var>KEY</var>, <var>NUMERIC RANGE</var>, or <var>ORDERED</var> attribute is changed for a <var>VISIBLE</var> field, <var class="product">Model&nbsp;204</var> must modify the index entries that correspond to each occurrence of the field in Table B.  </p>
<p>
When a field is redefined to add an indexed attribute, every record containing that field will have its index entry in Table C or D updated.</p>


<p>For any of these situations, the file must be reinitialized.</p>
===Redefining UNIQUE fields===
<p>
<var>UNIQUE</var> fields must be <var>ORDERED</var>. A field can be redefined as <var>UNIQUE</var> only if there are no non-unique values for that field in the file. </p>


<p>In addition:</p>
===Redefining the index on INVISIBLE fields===
<p>
If an <var>INVISIBLE</var> field is redefined to change or add an indexing attribute, such as <var>KEY</var>, <var>ORD CHAR</var>, or <var>ORD NUM</var>, only values of the field added to the file after the redefinition are recorded in the index. Values of the field existing before the redefinition cannot be generated into the indexes.</p>
<p>
You cannot use the <var>REDEFINE</var> command to add a new index to a field with the <var>INVISIBLE</var> attribute that is in a file that has been used (that is, the value of its <var>[[MSTRADD parameter|MSTRADD]]</var> parameter/statistic is nonzero). For an invisible field, the <var>REDEFINE</var> command cannot specify the <var>KEY</var>, <var>ORD CHAR</var>, or <var>ORD NUM</var> attributes nor the <var>NUMERIC RANGE</var> attribute, unless the field was originally defined with that attribute.</p>
<p>
If an <var>INVISIBLE</var> field is redefined to be <var>FRV</var>, only values of the field added to the file after the redefinition are recorded in Table A. Values of the field existing before the redefinition cannot be generated into Table A.  </p>


===Redefining UNIQUE fields===
<p>UNIQUE fields must be ORDERED. A field can be redefined as UNIQUE only if there are no nonunique values for that field in the file. </p>
===Redefining KEY, NUMERIC RANGE, ORDERED, or FRV fields===
<p><var class="product">Model&nbsp;204</var> adds entries to the index when the KEY, NUMERIC RANGE, ORDERED, or FRV fields are redefined. If the index fills up, <var class="product">Model&nbsp;204</var> displays an error message and the redefine fails. If TBO is enabed, the field is restored to its original status. If TBO is disabled (FOPT=x'02') and the redefine fails, the file will be broken.</p>
===Redefining INVISIBLE fields===
<p>If an INVISIBLE field is redefined to change or add an indexing attribute, such as KEY, ORD CHAR, or ORD NUM, only values of the field added to the file after the redefinition are recorded in the index. Values of the field existing before the redefinition cannot be generated into the indexes.</p>
<p>You cannot use the REDEFINE command to add a new index to a field with the INVISIBLE attribute that is in a file that has been used, so that MSTRADD statistic value parameter is set to nonzero. For an invisible field the REDEFINE command cannot specify the KEY, ORD CHAR, and ORD NUM attribute nor the NUMERIC RANGE attribute, unless the field was originally defined with that attribute.</p>
<p>If an INVISIBLE field is redefined to be FRV, only values of the field added to the file after the redefinition are recorded in Table A. Values of the field existing before the redefinition cannot be generated into Table A.  </p>
===Redefining NUMERIC RANGE fields===
===Redefining NUMERIC RANGE fields===
<p><var class="product">Model&nbsp;204</var> does not allow fields that have the NUMERIC RANGE attribute to occur more than once in a record, and it does not permit the addition of subsequent occurrences to a record for NUMERIC RANGE fields. If a field is redefined to NUMERIC RANGE and <var class="product">Model&nbsp;204</var> detects that it is multiply occurring, any redefinition stops. If TBO is enabed, the field is restored to its original status. If TBO is disabled (FOPT=x'02') and the redefine fails, the file will be broken.     </p>
<p>
<var class="product">Model&nbsp;204</var> does not allow fields that have the <var>NUMERIC RANGE</var> attribute to occur more than once in a record, and it does not permit the addition of subsequent occurrences to a record for <var>NUMERIC RANGE</var> fields. If a field is redefined to <var>NUMERIC RANGE</var> and <var class="product">Model&nbsp;204</var> detects that it is multiply occurring, any redefinition stops. If TBO is enabed, the field is restored to its original status. If TBO is disabled (FOPT=X'02') and the redefine fails, the file will be broken. </p>
 
===Redefining fields with security levels===
===Redefining fields with security levels===
<p>If a field that is being redefined has a security level defined for it (see <b>See</b>), you must have a field security level that permits some type of access.</p>
<p>
If a field that is being redefined has a security level defined for it (see [[Model 204 security features]]), you must have a field security level that permits some type of access.</p>


==Monitoring field retrievals==
==Monitoring field retrievals==
<p>If you do not know if a field will be used in retrievals, you can define it during the development process
<p>
as NON-ORDERED, NON-KEY and NON-RANGE. Then, monitor the use of the field in FIND statements using information
If you do not know if a field will be used in retrievals, you can define it during the development process
written to the journal data set and redefine it as needed. </p>
as <var>NON-ORDERED</var>, <var>NON-KEY</var>, and <var>NON-RANGE</var>. Then, monitor the use of the field in <var>FIND</var> statements using information
<p>Whenever such a field is used in a retrieval, an MS line is written to the journal
written to the journal data set, and redefine it as needed. </p>
<p>
Whenever such a field is used in a retrieval, an MS line is written to the journal
with the message:</p>
with the message:</p>


<p class="code">*** M204.0179: TABLE B SEARCH IMPLIED FOR FIELD =<var class="term">fieldname</var></p>
<p class="code">*** M204.0179: TABLE B SEARCH IMPLIED FOR FIELD = <var class="term">fieldname</var></p>


<p>This message indicates that a direct search of the data set might be required.
<p>
This message indicates that a direct search of the data set might be required.
It does not indicate whether the search was actually performed or how many
It does not indicate whether the search was actually performed or how many
records were searched (which depends on the results of any inverted
records were searched (which depends on the results of any inverted
conditions in the FIND statement... in other words, you may have excluded all records  
conditions in the <var>FIND</var> statement; in other words, you may have excluded all records  
from the search before needing to do a scan).</p>
from the search before needing to do a scan).</p>
<p>The DIRRCD statistic provides a count of the total number of Table B records
<p>
searched directly by FIND. DIRRCD appears in the journal and is accumulated
The DIRRCD statistic provides a count of the total number of Table B records
searched directly by <var>FIND</var>. DIRRCD appears in the journal and is accumulated
by file, by user, by request, and for the entire system. DIRRCD also can be
by file, by user, by request, and for the entire system. DIRRCD also can be
displayed by the [[TIME command]].</p>
displayed by the <var>[[TIME command|TIME]]</var> command.</p>
 
<p>
<p>This technique should be done with care, and probably only in development and  
This technique should be done with care, and probably only in development and  
testing, as requests where DIRRCD exceed the [[MBSCAN parameter]] will either produce
testing, because requests for which DIRRCD exceeds the <var>[[MBSCAN parameter|MBSCAN]]</var> parameter value produce a continuation prompt, or if running under an Application Subsystem, are cancelled.</p>
a continuation prompt, or if running under an Application Subsystem, be cancelled.</p>


==Deleting fields==
==Deleting fields==
<p>Use the DELETE FIELD command and the IFDELF Host Language Interface function to delete a field definition and all occurrences of data and indices for that field for every record in the file. The command is issued in the form: </p>
<p>
Use the <var>[[DELETE command: Field|DELETE FIELD]]</var> command and the <var>IFDELF</var> Host Language Interface function to delete a field definition and all occurrences of data and indices for that field for every record in the file. The command is issued in the form: </p>
<b>Syntax</b>
<b>Syntax</b>
<p class="code">DELETE FIELD <var class="term">fieldname</var>
<p class="syntax">DELETE FIELD <span class="term">fieldname</span>
</p>
</p>
<p>where:</p>
<p>
<p>fieldname is the name assigned when the field was defined. </p>
Where:</p>
<p>A DELETE FIELD command cannot be used to delete record security fields or sort and hash key fields. If the field being deleted is in a file that has record security, you must have record security override privileges (see <b>See [[#Security#Record security|record security]] </b>). If the field has a security level defined for it, you must have a field-level security level that permits update access.</p>
<p>
<p>Other uses of the DELETE command are discussed in the [[:Category:Commands|Commands category]], specifically:</p>
<var class="term">fieldname</var> is the name assigned when the field was defined. </p>
* [[DELETE command: Procedure|procedures]]
<p>
* [[DELETE command: Permanent group|permanent groups]]
A <var>DELETE FIELD</var> command cannot be used to delete record security fields or sort and hash key fields. If the field being deleted is in a file that has record security, you must have record security override privileges (see [[Model 204 security features#Record security|record security]]). If the field has a security level defined for it, you must have a field-level security level that permits update access.</p>
* [[DELETE command: Temporary group|temporary groups]]
<p>
Other uses of the <var>DELETE</var> command are accessible via the [[:Category:Commands|Commands category]], specifically for:</p>
<ul>
<li>[[DELETE command: Procedure|Procedures]]
<li>[[DELETE command: Permanent group|Permanent groups]]
<li>[[DELETE command: Temporary group|Temporary groups]]
</ul>
 
===DELETE FIELD with date-time stamp fields===
<p>
The <var>DELETE FIELD</var> command is prohibited for the DTSFN field in a file when the <var>FOPT</var> X'10' bit is set.</p>


<b>DELETE FIELD with date-time stamp fields</b>
<p>The DELETE FIELD command is prohibited for the DTSFN field in a file when the FOPT=X'10' is set.</p>
==Renaming fields==
==Renaming fields==
<p>The RENAME command and the IFNFLD Host Language Interface function allow you to rename a field. The command is issued in the form:</p>
<p>
The <var>[[RENAME FIELD command|RENAME]]</var> command and the <var>IFNFLD</var> Host Language Interface function allow you to rename a field. The command is issued in the form:</p>
<b>Syntax</b>
<b>Syntax</b>
<p class="code">RENAME FIELD <var class="term">oldname</var>,<var class="term">newname</var>
<p class="syntax">RENAME FIELD <span class="term">oldname</span>,<span class="term">newname</span>
</p>
</p>
<p>where:</p>
<p>
<p>oldname is the current name of the field.</p>
Where:</p>
<p>newname is the name that you want to assign.      </p>
<ul>
<p>This command is not executed if the old field name does not exist or if the new name cannot be added to the internal file dictionary, either because it already exists or because there is not enough space. </p>
<li><var class="term">oldname</var> is the current name of the field.</li>
<p>Note</p>
<li><var class="term">newname</var> is the name that you want to assign.      </li>
<p>If a TABLE C FULL condition occurs during the renaming of a KEY or NUMERIC RANGE field, the file is left in a broken state. This happens even if the file is a transaction back out file. To prevent this condition, issue a TABLEC command to check for available space and/or back up the file before renaming a field. </p>
</ul>
<p>Record security fields and sort and hash key fields can be renamed. If a field that is being renamed has a security level defined for it (see <b>See Field-level security</b>"), you must have a field security level that permits some type of access.</p>
<p>
<p>The RENAME command cannot be used to rename an INVISIBLE field. If you do want to rename an INVISIBLE field, delete all occurrences of the old field and then add them to the record under the new name.   </p>
This command is not executed if the old field name does not exist or if the new name cannot be added to the internal file dictionary, either because it already exists or because there is not enough space. </p>
<p>&nbsp;</p>
<p class="note"><b>Note:</b>
[[Category:File manager]]
If a TABLE C FULL condition occurs during the renaming of a <var>KEY</var> or <var>NUMERIC RANGE</var> field, the file is left in a broken state. This happens even if the file is a transaction back out file. To prevent this condition, issue a <var>TABLEC</var> command to check for available space, or back up the file before renaming a field, or do both of these. </p>
[[Category:File management]]
<p>
Record security fields and sort and hash key fields can be renamed. If a field that is being renamed has a security level defined for it (see [[Model 204 security features#Field-level security|Field-level security]]), you must have a field security level that permits some type of access.</p>
<p>
The <var>RENAME</var> command cannot be used to rename an <var>INVISIBLE</var> field. If you do want to rename an <var>INVISIBLE</var> field, delete all occurrences of the old field and then add them to the record under the new name. </p>
<p>
Because of this danger, and because, on larger files the scan of Table B to change the field identifier may be lengthy (and, if renaming multiple fields are done one per pass), you may want to consider [[File reorganization and table compaction|reorganizing the file]] to rename fields.</p>
 
[[Category:Model 204 files]]

Latest revision as of 21:21, 7 April 2017

Overview

This page describes the REDEFINE, DELETE, and RENAME commands, which allow you to redefine many field attributes, to delete a field's description and all its occurrences in the data, and to rename fields. For the complete syntax and description of these commands, please follow the links.

Note: New fields and Repeating Field Groups may may be added by the file manager at any time (although some attributes may not be assigned to these new fields (such as the OCCurs attribute to preallocate a field) once data has been added to the file. See Field design for more details.)

After creating a file and adding fields, you can perform the following field management tasks:

  • Redefine fields
  • Monitor field retrievals
  • Deleting fields
  • Renaming fields

The operative word is "can," which does not always mean that you should. If you have a large file and are performing actions that cause Table B to be read in its entirety (the DELETE of a number of fields, or REDEFINE of fields to be indexed, for example), consider whether it may be more efficient to reorganize the file.

Redefining fields

The REDEFINE command and the IFRFLD Host Language Interface function allow you to alter a field definition without requiring that the file be reinitialized, with exceptions noted below.

The format of REDEFINE is:

Syntax

REDEFINE [FIELD] {field_desc [field_desc ...] | fieldname WITH attribute [attribute ...]}

Where:

field_desc takes the form:

fieldname [(attribute [,[attribute ...])]]

  • fieldname is the name of a field in the open Model 204 file.
  • attribute is one of the attributes listed in the REDEFINE command description. In the REDEFINE command, you need to specify only the attributes being changed for the field.

Example

The following command changes two attributes of the previously defined CUSTID field:

Before:

DEFINE FIELD CUSTID WITH FRV KEY

After:

REDEFINE FIELD CUSTID WITH NON-FRV NON-KEY ORDERED CHAR

Field attributes and the REDEFINE command

Not all the field attributes that can be specified in the DEFINE command can be changed by a REDEFINE command. The following table summarizes the options.

See Field design for a full discussion of the classifications and attributes.

Field attributes and the REDEFINE command
Field classification Attributes Allowed? Notes
Indexing options ORD CHAR or ORD NUM

KEY or NKEY

FRV or NFRV

RANGE or NRANGE

Yes Model 204 adds (or removes) entries to the index when these are redefined. If the index fills up, Model 204 displays an error message and the redefine fails.

If TBO is enabed, the field is restored to its original status.
If TBO is disabled (FOPT=X'02') and the redefine fails, the file will be broken.

Also, see limitation for INVISIBLE fields, below.

Data type All No
Data content a) FV or MV

b) UP or UE

c) DV

d) ONE, EXONE, or REPT

e) DEF or NDEF

Yes a) Only valid for COD or FRV fields

b) Not allowed with INVISIBLE fields

c) ONE or EXONE fields only

COD or NCOD

OCC

LEN

PAD

SD or SN

No
Concatenated fields All No
Automatic fields All No
Field and content constraints All Yes See limitations on UNIQUE, below.

The redefinitions do not validate existing occurrences, so if you have a field containing 9999 and then set INTLE to 1000, no error will occur.

Repeating Field Group FIELDGROUP attribute No Fields may not be redefined into or out of a field group.

Changing a field's security level to 0 desecures the field. Refer to Field-level security for more information.

Note: Redefining fields may take a substantial amount of CPU time. When a KEY, NUMERIC RANGE, or ORDERED attribute is changed for a VISIBLE field, Model 204 must modify the index entries that correspond to each occurrence of the field in Table B.

When a field is redefined to add an indexed attribute, every record containing that field will have its index entry in Table C or D updated.

Redefining UNIQUE fields

UNIQUE fields must be ORDERED. A field can be redefined as UNIQUE only if there are no non-unique values for that field in the file.

Redefining the index on INVISIBLE fields

If an INVISIBLE field is redefined to change or add an indexing attribute, such as KEY, ORD CHAR, or ORD NUM, only values of the field added to the file after the redefinition are recorded in the index. Values of the field existing before the redefinition cannot be generated into the indexes.

You cannot use the REDEFINE command to add a new index to a field with the INVISIBLE attribute that is in a file that has been used (that is, the value of its MSTRADD parameter/statistic is nonzero). For an invisible field, the REDEFINE command cannot specify the KEY, ORD CHAR, or ORD NUM attributes nor the NUMERIC RANGE attribute, unless the field was originally defined with that attribute.

If an INVISIBLE field is redefined to be FRV, only values of the field added to the file after the redefinition are recorded in Table A. Values of the field existing before the redefinition cannot be generated into Table A.

Redefining NUMERIC RANGE fields

Model 204 does not allow fields that have the NUMERIC RANGE attribute to occur more than once in a record, and it does not permit the addition of subsequent occurrences to a record for NUMERIC RANGE fields. If a field is redefined to NUMERIC RANGE and Model 204 detects that it is multiply occurring, any redefinition stops. If TBO is enabed, the field is restored to its original status. If TBO is disabled (FOPT=X'02') and the redefine fails, the file will be broken.

Redefining fields with security levels

If a field that is being redefined has a security level defined for it (see Model 204 security features), you must have a field security level that permits some type of access.

Monitoring field retrievals

If you do not know if a field will be used in retrievals, you can define it during the development process as NON-ORDERED, NON-KEY, and NON-RANGE. Then, monitor the use of the field in FIND statements using information written to the journal data set, and redefine it as needed.

Whenever such a field is used in a retrieval, an MS line is written to the journal with the message:

*** M204.0179: TABLE B SEARCH IMPLIED FOR FIELD = fieldname

This message indicates that a direct search of the data set might be required. It does not indicate whether the search was actually performed or how many records were searched (which depends on the results of any inverted conditions in the FIND statement; in other words, you may have excluded all records from the search before needing to do a scan).

The DIRRCD statistic provides a count of the total number of Table B records searched directly by FIND. DIRRCD appears in the journal and is accumulated by file, by user, by request, and for the entire system. DIRRCD also can be displayed by the TIME command.

This technique should be done with care, and probably only in development and testing, because requests for which DIRRCD exceeds the MBSCAN parameter value produce a continuation prompt, or if running under an Application Subsystem, are cancelled.

Deleting fields

Use the DELETE FIELD command and the IFDELF Host Language Interface function to delete a field definition and all occurrences of data and indices for that field for every record in the file. The command is issued in the form:

Syntax

DELETE FIELD fieldname

Where:

fieldname is the name assigned when the field was defined.

A DELETE FIELD command cannot be used to delete record security fields or sort and hash key fields. If the field being deleted is in a file that has record security, you must have record security override privileges (see record security). If the field has a security level defined for it, you must have a field-level security level that permits update access.

Other uses of the DELETE command are accessible via the Commands category, specifically for:

DELETE FIELD with date-time stamp fields

The DELETE FIELD command is prohibited for the DTSFN field in a file when the FOPT X'10' bit is set.

Renaming fields

The RENAME command and the IFNFLD Host Language Interface function allow you to rename a field. The command is issued in the form:

Syntax

RENAME FIELD oldname,newname

Where:

  • oldname is the current name of the field.
  • newname is the name that you want to assign.

This command is not executed if the old field name does not exist or if the new name cannot be added to the internal file dictionary, either because it already exists or because there is not enough space.

Note: If a TABLE C FULL condition occurs during the renaming of a KEY or NUMERIC RANGE field, the file is left in a broken state. This happens even if the file is a transaction back out file. To prevent this condition, issue a TABLEC command to check for available space, or back up the file before renaming a field, or do both of these.

Record security fields and sort and hash key fields can be renamed. If a field that is being renamed has a security level defined for it (see Field-level security), you must have a field security level that permits some type of access.

The RENAME command cannot be used to rename an INVISIBLE field. If you do want to rename an INVISIBLE field, delete all occurrences of the old field and then add them to the record under the new name.

Because of this danger, and because, on larger files the scan of Table B to change the field identifier may be lengthy (and, if renaming multiple fields are done one per pass), you may want to consider reorganizing the file to rename fields.