Managing fields manually

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:

• Procedures
• Permanent groups
• Temporary groups

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.