User-defined function best practices

When designing the UDF, there are some questions that need to be considered.


Learn how to keep track of the massive programming efforts by using agile software development techniques.Modern automation controllers continue to expand with options and opportunities for the programmer. One of those improvements is the ability to develop User-defined functions (UDF), or add-on instructions in the Rockwell Automation ecosystem. These improve portability, consistency, and code security, all of which add to the kit of the automation programmer. Like all tools they can be used properly or abused; who hasn’t pried the lid off of a can of paint with a ‘screwdriver’? I’d like to take a moment and discuss some of the options and opportunities that these constructs offer and some of the Best Practices that should be employed.

These constructs are often confused with a Sub-Routine. Quite often an introduction will begin that way. It is important to keep in mind that they are not, “quite”. A better analogy would come from Object Oriented (OO) Programming, they are an Object or Class. These are elements that are expected to be completely self-contained, working with information from outside but not totally dependent upon it.

When designing the UDF consider the desired functionality in the broader sense, there are some questions that need to be considered…

  • What happens if the preceding rung logic or enable is False?
  • What happens on pre-scan (that execution period just before the controller goes to Run)?
  • How are internal variables initialized?
  • How are internal Timers or other time sensitive elements handled?

These questions don’t exist or have the same implications for a subroutine. In a subroutine the data required inside the routine must come from the outside and everything inside the routine is considered “fair game” for modification. The UDF doesn’t follow the same rules.

Let’s begin by looking at some of the concepts associated with UDF’s and see what they require and how some of these can and should be employed.

Data into and out of the UDF is handled in two ways, pass by value (ByVal) and pass by reference (ByRef). These are broken down as follows (I’ll use Rockwell nomenclature for the moment

  • Pass By Value: Input and Output
  • Pass By Reference: InOut

The ByRef parameter exchange is exactly as expected, the pointer to the data specified is applied to a local name and all of that data is exposed to the UDF. The benefit here is that the UDF can modify the data in the supplied data, the bad news is - the UDF can modify the data. Planning for this must be considered.

One of the biggest mistakes that’s made with ByRef data is to create a huge User-Defined Type (UDT) and put everything into that; this is typical of the subroutine method. Including things such as one-shot bits, internal timers, counters, and working registers/arrays. Nothing stops the programmer from doing this but the real question is “Does this data need to be exposed?” Temporary and working variables have no value outside of the routine, therefore, as good form, don’t put them there. These types of elements are best suited to internal / local variables that actually have a name that means something, versus the obscure names that always seem to creep up “WorkingBits”.

The ByVal data parameters are exactly as stated, a value is copied from outside of the UDF to internal / local variables, and vice-versa, for use. The simpler of the two parameter types is the Output. This parameter is designed to be calculated inside the UDF and made available for use outside of the UDF. Every time the block is scanned the output will be recalculated and made available. If the programmer wants to use the result(s) then they do so as needed.

The other parameter type, Input, the converse of the Output but with some interesting twists. The Input parameters are copied from the variables or registers indicated and available for use in the block. This is the straight-forward use of these parameters. The twist that exist with Input parameters is that they do not have to have an outside variable assigned to them. These variables can exist as exposed, internal registers.

This opens Input parameters to be employed in other ways. The parameters can themselves be used directly as specific instance variables. Input parameters have the property of a Default value which is available outside the UDF as well as inside. In one stroke it is possible to create ‘Configuration’ parameters for the instance of the UDF; combining UDT type qualities with the UDF. This means that if the timer Setpoint is 30 seconds, that can be defined as an Input and visible to the UDF as well as the “outside world”. This is behavior is just like an object property in OO programming.

The final items that need to be discussed are those elements that were excluded from the “Bucket” structure:  Internal Variables. These variables, of whatever type is required, need to be declared as part of the UDF itself. It is at this point that the UDF diverges from the sub-routine model in automation controllers. Each time a UDF is used in code memory space is reserved for the internal bits & registers, the distinction is that they are not visible for use; only parameters are exposed.

The last thing that has to be considered when dealing with UDF’s and their internal data elements is initialization and what happens when the block is NOT being scanned. Typically, there are extra states available for those. It is the requirement of the programmer to set these up themselves. Assuming that the block will always be scanned is not practical and ‘sloppy’. It’s kinda like going to your mothers for dinner and then not helping to clean the table and do the dishes afterwards. Be courteous to those that follow after you.

It should be apparent that the ideas and concepts raised here just scratch the surface of the capability of the User Defined Function capabilities. The most important point to all of this is that these are very powerful tools for the programmer’s kit, they just need to be thought out ahead of time. These can add to the safety and security of your code base, they can also help to spaghettify your code.

This post was written by Jeff Monforton. Jeff is a senior engineer at MAVERICK Technologies, a leading automation solutions provider offering industrial automation, strategic manufacturing, and enterprise integration services for the process industries. MAVERICK delivers expertise and consulting in a wide variety of areas including industrial automation controls, distributed control systems, manufacturing execution systems, operational strategy, business process optimization and more. MAVERICK Technologies is a CFE Media content partner.

MAVERICK Technologies is a CSIA member as of 3/20/2015

No comments
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by...
The System Integrator Giants program lists the top 100 system integrators among companies listed in CFE Media's Global System Integrator Database.
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
This eGuide illustrates solutions, applications and benefits of machine vision systems.
Learn how to increase device reliability in harsh environments and decrease unplanned system downtime.
This eGuide contains a series of articles and videos that considers theoretical and practical; immediate needs and a look into the future.
Additive manufacturing benefits; HMI and sensor tips; System integrator advice; Innovations from the industry
Robotic safety, collaboration, standards; DCS migration tips; IT/OT convergence; 2017 Control Engineering Salary and Career Survey
Integrated mobility; Artificial intelligence; Predictive motion control; Sensors and control system inputs; Asset Management; Cybersecurity
Featured articles highlight technologies that enable the Industrial Internet of Things, IIoT-related products and strategies to get data more easily to the user.
This article collection contains several articles on how automation and controls are helping human-machine interface (HMI) hardware and software advance.
This digital report will explore several aspects of how IIoT will transform manufacturing in the coming years.

Find and connect with the most suitable service provider for your unique application. Start searching the Global System Integrator Database Now!

Infrastructure for natural gas expansion; Artificial lift methods; Disruptive technology and fugitive gas emissions
Mobility as the means to offshore innovation; Preventing another Deepwater Horizon; ROVs as subsea robots; SCADA and the radio spectrum
Future of oil and gas projects; Reservoir models; The importance of SCADA to oil and gas
Automation Engineer; Wood Group
System Integrator; Cross Integrated Systems Group
Jose S. Vasquez, Jr.
Fire & Life Safety Engineer; Technip USA Inc.
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
click me