Refactoring Variables and FB Types

This topic contains the following sections:

General Information

Refactoring means modifying (improving) the structure of existing source code while preserving its functional behavior.

PLCnext Engineer supports refactoring by providing a mechanism for the automatic and consistent modification of object (variable, FB instance, etc.) properties. Consistent means that the properties to be replaced are considered throughout the solution: in each variables table, Data List, at each code location and within the HMI application. This way, an object can, for example, be renamed with a single step without any functional impact on the code.

The 'Refactoring' context menu command is available if exactly one object is selected in the following editors:

Variables table (local declarations of a POU)
Data List (global IEC 61131-3 declarations)
Code editors (variables and FB calls)
CROSS REFERENCES

Specifics when refactoring safety-related data

The impact that refactoring (safety-related) variables/instances has on the safety-related application is solely your responsibility as the solution developer. Therefore, the following must be observed before refactoring safety-related variables or instance names.

WARNING

Unintended machine operation

Make certain that suitable organizational measures (according to applicable sector standards) have been taken to avoid hazardous situations if the application logic functions in an unintended or incorrect after the refactoring.

In the 'Refactoring' window, carefully check all occurrences of affected safety-related variables/instance name before you perform the refactoring as described in step 5 below.

Verify the impact of refactored variables.

Validate the overall safety-related function with regard to the refactored variables/instance names and thoroughly test the application.

Refactoring function block instances

There are several levels for refactoring and updating function block instances and their types:

Instance refactoring - Refactoring a specific instance of an FB (as described in the procedure below). The procedure is executed with the 'Refactoring' context menu command of an FB instance.
FB type updating - Updating all FB instances of the same type in all graphical worksheets in the project without changing the FB type itself and the related type of the instance variable in the variables table (can only be executed for an FB selected in the graphical worksheet). Useful when, for example, new inputs or outputs have been added to an FB.
The procedure is executed with the 'Refactor / Update FB Type' context menu command of an FB instance in a graphical worksheet.
FB type refactoring - Changing the type of FB instances in all graphical worksheets in the project and the corresponding related type of the instance variables in the variables table (can only be executed for an FB selected in the graphical worksheet). Useful when, for example, the FB prototype has changed.
The procedure is executed with the 'Refactor / Update FB Type' context menu command of an FB instance in a graphical worksheet.

Further Info
See the topic "Refactoring/Updating FB Types" for details.

Refactoring procedure

If required: First rebuild the project manually ('Project > Rebuild') after adding a variable. (The 'Refactoring' command is only available after rebuilding the project or the cross references are up to date.)
In the editor, right-click the object to be modified and select the 'Refactoring' command from the context menu.
In the Cross Function Area, the REFACTORING window is opened. The window lists all locations where the respective object is used in your project : declarations, code accesses and usages in the HMI application.
Double-clicking a location in the list opens the respective editor (data list, code etc.) with the object highlighted.
In the first grid row, under the 'New Values' group, enter or select a new name, type or comment (all other properties are read-only).
The 'Type' field provides a list of the data types and FB types (FB names) available in your project. When selecting another type, ensure that the new type matches the type of the defined type.
If the FB instance name will be changed, the corresponding instance variable will be renamed too if there exists exactly one variable with the old name and no variable with the new name.
If a function block type will be changed, the corresponding type of the instance variable in the associated variables table will be modified too.
Specify the locations, where the properties are to be replaced by the new values.
: the new values will replace all existing values when executing the refactoring command.
: location will be kept unchanged.
The window toolbar provides two icons for deselecting or selecting all locations.
Make sure...
- you have followed the instructions in the hazard message above this procedure, and
- your selection does not result in a code error due to inconsistencies
before you apply the refactoring in this step.
1. Click the icon on the toolbar to apply the refactoring to the selected locations.
2. Click the icon on the toolbar to refresh the content of the REFACTORING window.

After the refactoring process is completed...

Check the MESSAGES window for any errors that result from using the refactoring command.
Validate and thoroughly test the application with regard to the refactored variables/instance names.

Window toolbar

Icon / Command 1

Refreshes the list of locations.

Replaces/updates the existing values at the selected locations by the new values entered under the 'New Values' group. The list is automatically updated after refactoring is completed.
Depending on how the REFACTORING window is opened, specific columns under the 'New values' group are enabled to enter a new value.

If the REFACTORING window is called via the context menu command 'Refactoring' (instance refactoring mode), the 'Name', 'Type', and 'Comment' can be specified.

If the REFACTORING window is called via the context menu command 'Refactor/Update FB type' (FB type update / refactoring mode), only the 'Type' value can be specified.

Selects (activates) all locations listed in the window.

Deselects (deactivates) all locations listed in the window.

Icon / Command	1
	Refreshes the list of locations.
	Replaces/updates the existing values at the selected locations by the new values entered under the 'New Values' group. The list is automatically updated after refactoring is completed. Depending on how the REFACTORING window is opened, specific columns under the 'New values' group are enabled to enter a new value. If the REFACTORING window is called via the context menu command 'Refactoring' (instance refactoring mode), the 'Name', 'Type', and 'Comment' can be specified. If the REFACTORING window is called via the context menu command 'Refactor/Update FB type' (FB type update / refactoring mode), only the 'Type' value can be specified.
	Selects (activates) all locations listed in the window.
	Deselects (deactivates) all locations listed in the window.

Double-clicking a location in the list opens the respective editor (data list, code etc.) with the object highlighted.