RenameDBField function

Syntax

RenameDBField(Field.NewFieldName, Field.OldFieldName [, FixRefsOnly])

Description

Use the RenameDBField function to modify a field definition to have a new name. This function also cleans up most references, such as in PeopleCode programs and on records so they now use the new name.

Note:

Because using this function changes records that are used to build application tables, you must rebuild (alter) the specified project before these changes can be used.

Parameters

Parameter	Description
NewFieldName	Specify the new field name to be used. This name must be prefixed by the reserved word Field.
OldFieldName	Specify the name of the field to be changed. This name must be prefixed by the reserved word Field.
FixRefsOnly	Specify to rename all references of OldFieldName to NewFieldName whether or not NewFieldName exists or not. This parameter takes a Boolean value. The default value is False. For example, suppose a company renames a field PROJECT to MYPROJECT. Then they receive a patch which has records, pages, code, and so on that references Field.PROJECT. In this case you could set this parameter to True, rename MYPROJECT to PROJECT, and have all the references to the field PROJECT redirect to the field MYPROJECT even if neither field exists in the database, nor if only one exists. Note: Using this parameter is a completely free-form path to renaming references. Be aware that the system won't work if pages and records are not eventually pointing to a valid field.

Parameter

Description

NewFieldName

Specify the new field name to be used. This name must be prefixed by the reserved word Field.

OldFieldName

Specify the name of the field to be changed. This name must be prefixed by the reserved word Field.

FixRefsOnly

Specify to rename all references of OldFieldName to NewFieldName whether or not NewFieldName exists or not. This parameter takes a Boolean value. The default value is False.

For example, suppose a company renames a field PROJECT to MYPROJECT. Then they receive a patch which has records, pages, code, and so on that references Field.PROJECT. In this case you could set this parameter to True, rename MYPROJECT to PROJECT, and have all the references to the field PROJECT redirect to the field MYPROJECT even if neither field exists in the database, nor if only one exists.

Note: Using this parameter is a completely free-form path to renaming references. Be aware that the system won't work if pages and records are not eventually pointing to a valid field.

Returns

A constant value. The values are:

Value	Description
%MDA_Success	Bulk operation completed successfully.
%MDA_Failure	Bulk operation did not complete successfully.
%MDA_FieldNotFound	The field specified by OldFieldName wasn't found in the specified project or page list.
%MDA_Duplicate	The field specified by NewFieldName already exists.

Example

&ret = RenameDBField(Field.OrgId, Field.DeptId, True);  
If (&ret = %MDA_Success) Then 
    MessageBox(0, "Metadata Fn Status", 0, 0, "RenameDBField succeeded"); 
Else 
    MessageBox(0, "Metadata Fn Status", 0, 0, "RenameDBField failed"); 
End-If;

The following example de-references the field name for the function.

&oldcf = "CF1"; 
&newcf = "XYZ_STORE_ID"; 
&new = "FIELD." | &newcf; 
&old = "FIELD." | &oldcf; 
&ret = RenameDBField(@(&new), @(&old)); 
If (&ret = 0) Then 
   MessageBox(0, "RenameDBField", 0, 0, "Succeeded"); 
Else 
   MessageBox(0, "RenameDBField", 0, 0, "Failed"); 
End-If;

Considerations Using this Function

In SQL associated with records of type view, the field name is not changed. You must fix those by hand.

This function is intended for use during configuration time only, before active runtime usage is initiated. Using this function during active runtime is not supported. Changes to data definitions are not recognized on currently loaded component. In general, changes aren't recognized until the component is reloaded.

This operation is time consuming.

WARNING:

These operations take place in a separate transaction from the page's save status: the initiation of any of these operations immediately changes the definitions, even if the page is subsequently cancelled.