Logix5000 Controllers Add-On Instructions

Catalog Numbers 1756 ControlLogix, 1756 GuardLogix, 1768 CompactLogix,

1768 Compact GuardLogix, 1769 CompactLogix, 1789 SoftLogix,
PowerFlex with DriveLogix
Programming Manual
Important User Information
Solid state equipment has operational characteristics differing from those of electromechanical equipment. Safety Guidelines
for the Application, Installation and Maintenance of Solid State Controls (publication SGI-1.1 available from your local Rockwell
Automation sales office or online at http://www.rockwellautomation.com/literature/) describes some important differences
between solid state equipment and hard-wired electromechanical devices. Because of this difference, and also because of the
wide variety of uses for solid state equipment, all persons responsible for applying this equipment must satisfy themselves that
each intended application of this equipment is acceptable.
In no event will Rockwell Automation, Inc. be responsible or liable for indirect or consequential damages resulting from the use
or application of this equipment.
The examples and diagrams in this manual are included solely for illustrative purposes. Because of the many variables and
requirements associated with any particular installation, Rockwell Automation, Inc. cannot assume responsibility or liability for
actual use based on the examples and diagrams.
No patent liability is assumed by Rockwell Automation, Inc. with respect to use of information, circuits, equipment, or software
described in this manual.
Reproduction of the contents of this manual, in whole or in part, without written permission of Rockwell Automation, Inc., is
prohibited.
Throughout this manual, when necessary, we use notes to make you aware of safety considerations.
Allen-Bradley, Rockwell Automation, TechConnect, Logix5000, ControlLogix, GuardLogix, CompactLogix, SoftLogix, FlexLogix, PowerFlex 700S, and DriveLogix are trademarks of Rockwell
Automation, Inc.
Trademarks not belonging to Rockwell Automation are property of their respective companies.
WARNING
Identifies information about practices or circumstances that can cause an explosion in a hazardous environment,
which may lead to personal injury or death, property damage, or economic loss.
IMPORTANT Identifies information that is critical for successful application and understanding of the product.
ATTENTION
Identifies information about practices or circumstances that can lead to personal injury or death, property damage,
or economic loss. Attentions help you identify a hazard, avoid a hazard, and recognize the consequence
SHOCK HAZARD
Labels may be on or inside the equipment, for example, a drive or motor, to alert people that dangerous voltage may
be present.
BURN HAZARD
Labels may be on or inside the equipment, for example, a drive or motor, to alert people that surfaces may reach
dangerous temperatures.
3Publication 1756-PM010C-EN-P - October 2009 3
Summary of Changes
The information below summarizes the changes to this manual since
the last publication.
To help you find new and updated information in this release of the
manual, we have included change bars as shown to the right of this
paragraph.
The Designing Add-On Instructions chapter was divided into two
chapters, Designing Add-On Instructions and Defining Add-On
Instructions, and some of the content was restructured.
Information on high-integrity Add-On Instructions and safety Add-On
Instructions was added throughout the manual as well as the changes
listed in this table.
Topic Page
Table of terms 10
New Signature Tab for High-integrity and Safety Add-On Instructions 16
Restrictions for Safety Add-On Instructions 19
Changing the Language Type of the Logic Routine 21
Additional Classes Supported by GSV and SSV Instructions 26
Create an Alias Parameter for a Local Tag 28, 38
Designating an InOut Parameter as a Constant 31
Defining External Access for Tags 31
Updates to Arguments Following Parameter Edits 41
Copying Parameter or Local Tag Default Values 43
Change the Class of an Add-On Instruction 54
Updates to Applying Source Protection procedure 58
Generate an Add-On Instruction Signature 60
Updated Information on Copying and Pasting Add-On Instructions 86
Updated Information on Exporting Add-On Instructions 89
Updated Information on Importing Add-On Instructions 92
Updated Information on Updating Add-On Instructions via Import 95
4 Publication 1756-PM010C-EN-P - October 2009
Summary of Changes
Notes:
5Publication 1756-PM010C-EN-P - October 2009 5
Table of Contents
Preface
Purpose of This Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Additional Resources for Safety Applications . . . . . . . . . . . . . 9
Understanding Terminology . . . . . . . . . . . . . . . . . . . . . . . . 10
Chapter 1
Designing Add-On Instructions Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
About Add-On Instructions . . . . . . . . . . . . . . . . . . . . . . . . . 11
Components of an Add-On Instruction. . . . . . . . . . . . . . . . . 13
General Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Local Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Logic Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Optional Scan Mode Routines. . . . . . . . . . . . . . . . . . . . . 16
Instruction Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Signature History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Considerations for Add-On Instructions . . . . . . . . . . . . . . . . 18
Instruction Functionality. . . . . . . . . . . . . . . . . . . . . . . . . 18
Encapsulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Safety Add-On Instructions. . . . . . . . . . . . . . . . . . . . . . . 19
Instruction Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Safety Instruction Signature . . . . . . . . . . . . . . . . . . . . . . 21
Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . 21
Transitional Instructions . . . . . . . . . . . . . . . . . . . . . . . . . 21
Instruction Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Runtime Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Nesting Add-On Instructions. . . . . . . . . . . . . . . . . . . . . . 22
Routines Versus Add-On Instructions . . . . . . . . . . . . . . . 23
Programmatic Access to Data . . . . . . . . . . . . . . . . . . . . . 24
Unavailable Instructions within Add-On Instructions . . . . 25
Using GSV and SSV Instructions . . . . . . . . . . . . . . . . . . . 26
Considerations When Creating Parameters . . . . . . . . . . . . . . 27
Passing Arguments to Parameters by Reference or by
Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Selecting a Data Type for a Parameter . . . . . . . . . . . . . . 27
Creating an Alias Parameter for a Local Tag . . . . . . . . . . 28
Using a Single Dimension Array as an InOut Parameter . . 28
Determining Which Parameters to Make Visible or
Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using Standard and Safety Tags . . . . . . . . . . . . . . . . . . . 30
Data Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6 Publication 1756-PM010C-EN-P - October 2009
Table of Contents
Planning Your Add-On Instruction Design . . . . . . . . . . . . . . 32
Intended Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Source Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Nesting - Reuse Instructions . . . . . . . . . . . . . . . . . . . . . . 33
Local Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . 33
Scan Mode Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Help Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Chapter 2
Defining Add-On Instructions Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Create an Add-On Instruction . . . . . . . . . . . . . . . . . . . . . . . 35
Create Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Create Local Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Edit Parameters and Local Tags . . . . . . . . . . . . . . . . . . . . . . 41
Updates to Arguments Following Parameter Edits. . . . . . . . . 41
Copying Parameter or Local Tag Default Values . . . . . . . . . . 43
Create Logic for the Add-On Instruction. . . . . . . . . . . . . . . . 44
Execution Considerations for Add-On Instructions. . . . . . 45
Optimizing Performance. . . . . . . . . . . . . . . . . . . . . . . . . 45
Defining Operation in Different Scan Modes . . . . . . . . . . . . 45
Enabling Scan Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Prescan Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Postscan Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
EnableInFalse Routine . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using the EnableIn and EnableOut Parameters . . . . . . . . . . . 52
EnableIn Parameter and Ladder Diagram . . . . . . . . . . . . 53
EnableIn Parameter and Function Blocks . . . . . . . . . . . . 53
EnableIn Parameter and Structured Text . . . . . . . . . . . . . 53
Change the Class of an Add-On Instruction . . . . . . . . . . . . . 54
Testing the Add-On Instruction . . . . . . . . . . . . . . . . . . . . . . 54
Before You Test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Test the Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Monitor Logic with Data Context Views . . . . . . . . . . . . . 55
Verifying Individual Scan Modes. . . . . . . . . . . . . . . . . . . 56
Defining Source Protection for an Add-On Instruction . . . . . 57
Enable the Source Protection Feature . . . . . . . . . . . . . . . 57
Apply Source Protection. . . . . . . . . . . . . . . . . . . . . . . . . 58
Observe Source Protection . . . . . . . . . . . . . . . . . . . . . . . 60
Publication 1756-PM010C-EN-P - October 2009 7
Table of Contents
Generate an Add-On Instruction Signature . . . . . . . . . . . . . . 60
Generate, Remove, or Copy an Instruction Signature. . . . 60
Create a Signature History Entry . . . . . . . . . . . . . . . . . . . 61
Generate a Safety Instruction Signature. . . . . . . . . . . . . . 62
Viewing and Printing the Instruction Signature . . . . . . . . 62
Creating Instruction Help. . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Write Clear Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . 63
Document an Add-On Instruction. . . . . . . . . . . . . . . . . . 64
Language Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Motor Starter Instruction Example . . . . . . . . . . . . . . . . . . . . 68
Simulation Instruction Example . . . . . . . . . . . . . . . . . . . . . . 70
Ladder Diagram Configuration . . . . . . . . . . . . . . . . . . . . 72
Function Block Diagram Configuration . . . . . . . . . . . . . . 73
Structured Text Configuration. . . . . . . . . . . . . . . . . . . . . 73
Chapter 3
Using Add-On Instructions Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Accessing Add-On Instructions . . . . . . . . . . . . . . . . . . . . . . 75
Use the Add Element Dialog Box. . . . . . . . . . . . . . . . . . . . . 76
Include an Add-On Instruction in a Routine . . . . . . . . . . . . . 77
Tips for Using an Add-On Instruction . . . . . . . . . . . . . . . . . 79
Programmatically Access a Parameter. . . . . . . . . . . . . . . . . . 79
Using the Jog Command in Ladder Diagram . . . . . . . . . . 80
Using the Jog Command In Function Block Diagram. . . . 81
Using the Jog Command in Structured Text. . . . . . . . . . . 82
Monitor the Value of a Parameter . . . . . . . . . . . . . . . . . . . . 82
View Logic and Monitor with Data Context . . . . . . . . . . . . . 83
Determine if the Add-On Instruction is Source Protected . . . 85
Copy an Add-On Instruction . . . . . . . . . . . . . . . . . . . . . . . . 86
Store Your Add-On Instructions . . . . . . . . . . . . . . . . . . . . . . 87
Chapter 4
Import and Export Add-On
Instructions
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Creating an Export File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Export to Separate Files . . . . . . . . . . . . . . . . . . . . . . . . . 90
Export to a Single File . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Importing an Add-On Instruction. . . . . . . . . . . . . . . . . . . . . 92
Import Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Import Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Update an Add-On Instruction to a Newer Revision via
Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Index
8 Publication 1756-PM010C-EN-P - October 2009
Table of Contents
9Publication 1756-PM010C-EN-P - October 2009 9
Preface
Purpose of This Manual
This manual shows how to design, configure, and program Add-On
Instructions. This manual is one of a set of related manuals that show
common procedures for programming and operating Logix5000
controllers. For a complete list of common procedures manuals, see
the Logix5000 Controllers Common Procedures Programming Manual,
publication 1756-PM001.
The term Logix5000 controller refers to any controller that is based on
the Logix5000 operating system, including the following:
CompactLogix and Compact GuardLogix controllers
ControlLogix and GuardLogix controllers
DriveLogix controllers
FlexLogix controllers
SoftLogix5800 controllers
Additional Resources for
Safety Applications
With the addition of safety Add-On Instructions in RSLogix 5000
software, version 18, you can use Add-On Instructions in GuardLogix
and Compact GuardLogix safety-related functions. This manual
provides information about safety Add-On Instructions.
For detailed information on safety application requirements, the safety
task signature, and configuring and operating safety controllers, refer
to these publications:
GuardLogix Systems Safety Reference Manual, publication
1756-RM093
Compact GuardLogix Controllers User Manual, publication
1768-UM002
GuardLogix Controllers User Manual, publication 1756-UM020
GuardLogix Safety Application Instruction Set Reference Manual,
publication 1756-RM095
10 Publication 1756-PM010C-EN-P - October 2009
Preface
Understanding Terminology
This table defines some of the terms used in this manual when
describing how parameters and arguments are used in Add-On
Instructions.
Term Definition
Argument An argument is assigned to a parameter of an Add-On Instruction
instance. An argument contains the specification of the data used by
an instruction in a user program. An argument can contain the
following:
A simple tag (for example, L101)
A literal value (for example, 5)
A tag structure reference (for example, Recipe.Temperature)
A direct array reference (for example, Buffer[1])
An indirect array reference (for example, Buffer[Index+1])
A combination (for example, Buffer[Index+1].Delay)
Parameter Parameters are created in the Add-On Instruction definition. When
an Add-On Instruction is used in application code, arguments must
be assigned to each required parameter of the Add-On Instruction.
InOut parameter An InOut parameter defines data that can be used as both input and
output data during the execution of the instruction. Because InOut
parameters are always passed by reference, their values can change
from external sources during the execution of the Add-On Instruction.
Input parameter For an Add-On Instruction, an Input parameter defines the data that
is passed by value into the executing instruction. Because Input
parameters are always passed by value, their values cannot change
from external sources during the execution of the Add-On Instruction.
Output parameter For an Add-On Instruction, an Output parameter defines the data that
is produced as a direct result of executing the instruction. Because
Output parameters are always passed by value, their values cannot
change from external sources during the execution of the Add-On
Instruction.
Passed by
reference
When an argument is passed to a parameter by reference, the logic
directly reads or writes the value that the tag uses in controller
memory. Because the Add-On Instruction is acting on the same tag
memory as the argument, other code or HMI interaction that changes
the arguments value can change the value while the Add-On
Instruction is executing.
Passed by value When an argument is passed to a parameter by value, the value is
copied in or out of the parameter when the Add-On Instruction
executes. The value of the argument does not change from external
code or HMI interaction outside of the Add-On Instruction itself.
11Publication 1756-PM010C-EN-P - October 2009 11
Chapter 1
Designing Add-On Instructions
Introduction
Add-On Instructions are available beginning with RSLogix 5000
software, version 16. Add-On Instructions are custom instructions that
you design and create. Beginning in RSLogix 5000 software, version
18, high integrity and safety Add-On Instructions are available.
About Add-On Instructions
With Add-On Instructions, you can create new instructions for sets of
commonly-used logic, provide a common interface to this logic, and
provide documentation for the instruction.
Add-On Instructions are intended to be used to encapsulate
commonly used functions or device control. They are not intended to
be a high-level hierarchical design tool. Programs with routines are
better suited to contain code for the area or unit levels of your
application.
These are some benefits to using Add-On Instructions:
Reuse code
You can use Add-On Instructions to promote consistency
between projects by reusing commonly-used control
algorithms.
If you have an algorithm that will be used multiple times in
the same project or across multiple projects, it may make
sense to incorporate that code inside an Add-On Instruction
to make it modular and easier to reuse.
Provide an easier to understand interface
You can place complicated algorithms inside of an Add-On
Instruction, and then provide an easier to understand
interface by making only essential parameters visible or
required.
You can reduce documentation development time through
automatically generating instruction help.
Topic Page
About Add-On Instructions 11
Components of an Add-On Instruction 13
Considerations for Add-On Instructions 18
Considerations When Creating Parameters 27
Planning Your Add-On Instruction Design 32
12 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Protect intellectual property
You can place your proprietary code inside of an Add-On
Instruction, then use Source Protection to prevent others from
viewing or changing your code.
Simplify maintenance
You can simplify code maintenance because Add-On
Instruction logic, monitored in RSLogix 5000 software,
animates with tag values relative to that specific instance of
the Add-On Instruction.
Track revisions, and easily confirm instruction functionality with
high-integrity Add-On Instructions
You can add an instruction signature to your Add-On
Instruction, which generates a unique identifier and prevents
the instruction from being edited without resulting in a
change to the signature.
An Add-On-Instruction can be used across multiple projects. You can
define the instructions, the instructions can be provided to you by
someone else, or they can be copied from another project.
Once defined in a project, they behave similarly to the built-in
instructions already available in RSLogix 5000 software. They appear
on the instruction toolbar and in the instruction browser for easy
access, just like built-in RSLogix 5000 software instructions.
Like standard Add-On Instructions, safety Add-On Instructions let you
encapsulate commonly-used safety logic into a single instruction,
making it modular and easier to reuse. In addition to the instruction
signature used for high-integrity Add-On Instructions, safety Add-On
Instructions feature a SIL 3 safety instruction signature for use in
safety-related functions up to and including SIL 3.
Refer to the GuardLogix Controller Systems Safety Reference Manual,
publication 1756-RM093, for details on certifying safety Add-On
Instructions and using them in SIL 3 safety applications.
Publication 1756-PM010C-EN-P - October 2009 13
Designing Add-On Instructions Chapter 1
Components of an Add-On
Instruction
Add-On Instructions are made up of the following parts.
General Information
The General tab contains the information you enter when you first
create the instruction. You can use this tab to update that information.
The description, revision, revision note, and vendor information is
copied into the custom help for the instruction. The revision is not
automatically managed by the software. You are responsible for
defining how it is used and when it is updated.
Class information for safety controller projects appears on the General
tab as well. The class can be standard or safety. Safety Add-On
Instructions must meet requirements specific to safety applications.
See Safety Add-On Instructions on page 19 for more information.
14 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Parameters
The parameters define the instruction interface; that is, how the
instruction appears when used. The parameter order defines the order
that the parameters appear on the instruction call.
Local Tags
The Local Tags tab defines tags that are used by the logic within the
Add-On Instruction and are not visible outside the instruction. Other
Add-On Instructions or programs in the project cannot access these
tags.
The only way to make a local tag or one of its members accessible
from outside the instruction is by defining an alias parameter.
See Creating an Alias Parameter for a Local Tag on page 28.
Publication 1756-PM010C-EN-P - October 2009 15
Designing Add-On Instructions Chapter 1
Data Type
Parameters and local tags are used to define the data type that is used
when executing the instruction. The software builds the associated
data type. The software orders the members of the data type that
correspond to the parameters in the order that the parameters are
defined. Local tags are added as hidden members.
Logic Routine
The logic routine of the Add-On Instruction defines the primary
functionality of the instruction. It is the code that executes whenever
the instruction is called. Shown below is the interface of an Add-On
Instruction and its primary logic routine that defines what the
instruction does.
16 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Optional Scan Mode Routines
You can define additional routines for Scan mode behavior.
Instruction Signature
The instruction signature consists of an ID number that identifies the
contents of the Add-On Instruction and a timestamp that identifies the
specific date and time at which the instruction signature was
generated or a signature history entry was made (whichever came
last).
Once generated, the instruction signature seals the Add-On
Instruction, preventing it from being edited while the signature is in
place.
Publication 1756-PM010C-EN-P - October 2009 17
Designing Add-On Instructions Chapter 1
In addition, when a sealed safety Add-On Instruction is downloaded
for the first time, a SIL 3 safety instruction signature is automatically
generated. The safety instruction signature is an ID number that
identifies the execution characteristics of the safety Add-On
Instruction.
Signature History
The signature history provides a record of signatures for future
reference. A signature history entry consists of the name of the user,
the instruction signature, the timestamp value, and a user-defined
description. Up to six history entries can be stored. If a seventh entry
is made, the oldest entry is automatically deleted.
Change History
The Change History tab displays the creation and latest edit
information that is tracked by the software. The By fields show who
made the change based on the Windows user name at the time of the
change.
18 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Help
The name, revision, description, and parameter definitions are used to
automatically build the Instruction Help. Use the Extended
Description Text to provide additional Help documentation for the
Add-On Instruction. The Instruction Help Preview shows how your
instruction will appear in the various languages, based on parameters
defined as required or visible.
Considerations for Add-On
Instructions
When deciding whether to develop an Add-On Instruction, consider
the following aspects.
Instruction Functionality
Complex instructions tend to be highly application specific and not
reusable, or require extensive configuration support code. As with the
built-in instructions, Add-On Instructions need to do one thing, do it
well, and support modular coding. Consider how the instruction will
be used and manage interface complexity for the end user or
application.
Add-On Instructions are best at providing a specific type of
functionality or device control.
Publication 1756-PM010C-EN-P - October 2009 19
Designing Add-On Instructions Chapter 1
Encapsulation
Add-On Instructions are designed to fully encapsulate the code and
data associated with the instruction. The logic inside an Add-On
Instruction uses only the parameters and local tags defined by the
instruction definition. There is no direct programmatic access to
controller or program scope tags. This lets the Add-On Instruction be
a standalone component that can execute in any application that calls
it by using the parameters interface. It can be validated once and then
locked to prevent edits.
Safety Add-On Instructions
Safety Add-On Instructions are used in the safety task of GuardLogix
safety controllers. Create a safety Add-On Instruction if you need to
use your instruction in a safety application. Safety Add-On Instructions
are subject to a number of restrictions. These restrictions, enforced by
RSLogix 5000 software and all GuardLogix controllers, are listed here
for informational purposes only.
They may use only safety-approved instructions and data types.
All parameters and local tags used in a safety Add-On Instruction
must also be safety class.
Safety Add-On Instructions use relay ladder logic only and can
be called in safety routines only, which are currently restricted to
ladder logic.
Safety Add-On Instructions may be referenced by other safety
Add-On Instructions, but not by standard Add-On Instructions.
Safety Add-On instructions cannot be created, edited, or
imported when a safety project is safety-locked or has a safety
task signature.
Refer to the GuardLogix Controller Systems Safety Reference Manual,
publication 1756-RM093, for information on how to certify a safety
Add-On Instruction as well as details on requirements for safety
applications, the safety task signature, and a list of approved
instructions and data types.
20 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Instruction Signature
The instruction signature, available for both standard and safety
controllers, lets you quickly determine if the Add-On Instruction has
been modified. Each Add-On Instruction has its own instruction
signature on the Add-On Instruction definition. The instruction
signature is required when an Add-On Instruction is used in SIL 3
safety-related functions, and may be required for regulated industries.
Use it when your application calls for a higher level of integrity.
Once generated, the instruction signature seals the Add-On
Instruction, preventing it from being edited until the signature is
removed. This includes rung comments, tag descriptions, and any
instruction documentation that was created. When an instruction is
sealed, you can perform only these actions:
Copy the instruction signature
Create or copy a signature history entry
Create instances of the Add-On Instruction
Download the instruction
Remove the instruction signature
Print reports
The instruction signature does not prevent referenced Add-On
Instructions or User-defined Data Types from being modified.
Changes to the parameters of a referenced Add-On Instruction or to
the members of a referenced User-defined Data Type can cause the
instruction signature to become invalid. These changes include:
adding, deleting, or moving parameters, local tags, or members
in referenced User-defined Data Types.
changing the name, data type, or display style of parameters,
local tags, or members in referenced User-defined Data Types.
If you want to enable language switching or source protection on an
Add-On Instruction that will be sealed with an instruction signature,
you need to import the translated information or apply source
protection before generating the signature. You must have the source
key to generate a signature or to create a signature history entry for a
source-protected Add-On Instruction that has an instruction signature.
See Defining Source Protection for an Add-On Instruction on page 57
for more information on source protecting your Add-On Instruction.
Publication 1756-PM010C-EN-P - October 2009 21
Designing Add-On Instructions Chapter 1
Safety Instruction Signature
When a sealed safety Add-On Instruction is downloaded for the first
time, a SIL 3 safety instruction signature is automatically generated.
For details on how to certify a safety Add-On Instruction, refer to the
GuardLogix Controller Systems Safety Reference Manual, publication
1756-RM093.
Programming Languages
Select the programming language based on the type of application
you are developing. Ladder Diagram, Function Block Diagram, and
Structured Text can be used for Add-On Instruction logic.
Each of the programming languages supported in RSLogix 5000
software is targeted for different types of applications and
programming styles. In general, Ladder Diagram executes simple
boolean logic, timers, and counters the fastest. Function Block
Diagrams and Structured Text may be more efficient if you take
advantage of the more advanced process and drives instructions
available in those languages.
You cannot compare execution times for the same Add-On Instruction
written in different programming languages. There are fundamental
differences on how the different languages execute and are compiled.
Transitional Instructions
Some instructions execute (or retrigger) only when rung-condition-in
toggles from false to true. These are transitional-relay ladder
instructions. When used in an Add-On Instruction, these instructions
will not detect the rung-in transition to the false state. When the
EnableIn bit is false, the Add-On Instruction logic routine no longer
executes, thus the transitional instruction does not detect the transition
to the false state. Extra conditional logic is required to handle
triggering of transitional instructions contained in an Add-On
Instruction.
TIP
You can change the programming language after you create the
Add-On Instruction by clicking Change Type on the General tab
of the Add-On Instruction Definition Editor. However, any
existing logic will be lost.
22 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Some examples of transitional instructions include: ONS, MSG, PXRQ,
SRT, some of the ASCII instructions, and some of the Motion
instructions.
Instruction Size
Add-On Instructions have one primary logic routine that defines the
behavior of the instruction when executed. This logic routine is like
any other routine in the project and has no additional restrictions in
length. The total number of Input parameters plus Output parameters
plus local tags can be up to 512. There are no limits on the number of
InOut parameters. The maximum data instance supported (which
includes Inputs, Outputs, and local tags) is two megabytes. The data
type size is displayed on the bottom of the Parameters and Local Tags
tab in the Add-On Instruction Definition.
Runtime Editing
Add-On Instructions can only be edited offline. If the intended
functionality needs to be changed in a running controller, consider
carefully if an Add-On Instruction is suitable.
Nesting Add-On Instructions
Add-On Instructions can call other Add-On Instructions in their
routines. This provides the ability to design more modular code by
creating simpler instructions that can be used to build more complex
functionality by nesting instructions. The instructions can be nested to
seven levels deep.
TIP
The EnableInFalse routine can be used to provide the
conditioning required to retrigger transitional instructions
contained in an Add-On Instruction. However, this method will
not work for calls to this Add-On Instruction contained in a
Structured Text routine, since EnableIn is always true for calls
in Structured Text.
Publication 1756-PM010C-EN-P - October 2009 23
Designing Add-On Instructions Chapter 1
Add-On Instructions cannot call other routines via a JSR instruction.
You must use nested instructions if you need complex functionality
consisting of multiple routines.
Routines Versus Add-On Instructions
You can write your code in three basic ways: to run in-line as a main
routine, to use subroutine calls, or as Add-On Instructions. The
following table summarizes the advantages and disadvantages of each.
TIP
To nest Add-On Instructions, both the nested instruction and the
instruction that calls it must be of the same class type or the
calling instruction will not verify. That is, standard Add-On
Instructions may call only standard Add-On Instructions and
safety Add-On Instructions may call only safety Add-On
Instructions.
Advantages and Disadvantages of Routines and Add-On Instructions
Aspect Main Routine Subroutine Add-On Instruction
Accessibility N/A Within program (multiple copies,
one for each program)
Anywhere in controller (single copy for the entire
project)
Parameters N/A Pass by value Pass by value via Input and Output parameters
or by reference via InOut parameters
Numeric parameters N/A No conversion, user must manage Automatic data type conversion for Input and
Output parameters
Parameters data types N/A Atomic, arrays, structures Atomic for any parameter
Arrays and structures must be InOut parameters
Parameter checking N/A None, user must manage Verification checks that correct type of argument
has been provided for a parameter
Data encapsulation N/A All data at program or controller
scope (accessible to anything)
Local data is isolated (only accessible within
instruction)
Monitor/debug In-line code with
its data
Mixed data from multiple calls,
which complicates debugging
Single calling instance data, which simplifies
debugging
Supported programming
languages
FBD, LD, SFC, ST FBD, LD, SFC, ST FBD, LD, ST
Callable from N/A FBD, LD, SFC, ST FBD, LD, SFC via ST, ST
Protection Locked and view
only
Locked and view only Locked and view only
Documentation Routine, rung,
textbox, line
Routine, rung, textbox, line Instruction, revision information, vendor, rung,
textbox, line, extended help
24 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Programmatic Access to Data
Input and Output parameters and local tags are used to define an
instruction-defined data type. Each parameter or local tag has a
member in the data type, although local tag members are hidden from
external use. Each call to an Add-On Instruction uses a tag of this data
type to provide the data instance for the instruction's execution.
The parameters of an Add-On Instruction are directly accessible in the
controller's programming via this instruction-defined tag within the
normal tag-scoping rules.
Local tags are not accessible programmatically through this tag. This
has impact on the usage of the Add-On Instruction. If a structured
(including UDTs), array, or nested Add-On Instruction type is used as
a local tag (not InOut parameters), then they are not programmatically
available outside the Add-On Instruction definition.
Execution performance Fastest JSR/SBR/RTN instructions add
overhead
All data is copied
Indexed reference impact
Call is more efficient
InOut parameters are passed by reference, which
is faster than copying data for many types
Parameter references are automatically offset
from passed-in instruction tag location
Memory use Most used Very compact Compact call requires more memory than a
subroutine call
All references need an additional word
Edit Online/offline Online/offline Offline only
Import/export Entire routine,
including tags and
instruction
definitions to L5X
Entire routine, including tags and
instruction definitions to L5X
Full instruction definition including routines and
tags to L5X
Instruction signature N/A N/A 32-bit signature value seals the instruction to
prevent modification and provide high integrity
Advantages and Disadvantages of Routines and Add-On Instructions
Aspect Main Routine Subroutine Add-On Instruction
TIP
You can access a local tag via an alias parameter.
See Creating an Alias Parameter for a Local Tag on page 28.
Publication 1756-PM010C-EN-P - October 2009 25
Designing Add-On Instructions Chapter 1
Unavailable Instructions within Add-On Instructions
Most built-in instructions can be used within Add-On Instructions. The
following instructions cannot be used.
Safety application instructions, such as Safety Mat (SMAT), may be
used in safety Add-On Instructions only. For detailed information on
safety application instructions, refer to the GuardLogix Safety
Application Instruction Set Safety Reference Manual, publication
1756-RM095.
In addition, the following instructions may be used in an Add-On
Instruction, but the data instances must be passed as InOut
parameters.
ALMA (Analog Alarm)
ALMD (Digital Alarm)
All Motion Instructions
MSG (Message)
Unavailable Instruction Description
BRK Break
EOT End of Transition
EVENT Event Task Trigger
FOR For (For/Next Loop)
IOT Immediate Output
JSR Jump to Subroutine
JXR Jump to External Routine
MAOC Motion Arm Output Cam
PATT Attach to Equipment Phase
PCLF Equipment Phase Clear Failure
PCMD Equipment Phase Command
PDET Detach from Equipment Phase
POVR Equipment Phase Override Command
RET Return
SBR Subroutine
SFP SFC Pause
SFR SFC Reset
26 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Using GSV and SSV Instructions
When using GSV and SSV instructions inside an Add-On Instruction,
the following classes are supported:
When you enter a GSV or SSV instruction, RSLogix 5000 software
displays the object classes, object names, and attribute names for each
instruction. This table lists the attributes for the
AddOnInstructionDefinition class.
For more information on using GSV and SSV instructions, refer to the
Logix5000 Controllers General Instructions Reference Manual,
publication 1756-RM003.
AddOnInstructionDefinition
(1)(2)
(1) GSV-only. SSV instructions will not verify.
MotionGroup
Axis
Program
(2)
(2) The classes that represent programming components - Task, Program, Routine,
AddOnInstructionDefinition - support only this as the Instance Name.
Controller
Routine
(2)
Controller Device Redundancy
CoordinateSystem Safety
CST Serial Port
DF1
Task
(2)
Fault Log Wall Clock Time
Message
AddOnInstructionDefinition Attributes
Attribute Name Data Type Attribute Description
MajorRevision DINT Major revision number of the Add-On Instruction
MinorRevision DINT Minor revision number of the Add-On Instruction
Name String Name of the Add-On Instruction
RevisionExtendedText String Text describing the revision of the Add-On
Instruction
Vendor String Vendor that created the Add-On Instruction
LastEditDate LINT Date and time stamp of the last edit to an Add-On
Instruction
SignatureID DINT 32-bit instruction signature value
SafetySignatureID DINT 32-bit safety instruction signature value
Publication 1756-PM010C-EN-P - October 2009 27
Designing Add-On Instructions Chapter 1
Considerations When
Creating Parameters
Consider the following information when you are creating parameters.
Passing Arguments to Parameters by Reference or by Value
The following information will help you understand the differences
between passing argument tags to parameters by reference or by
value.
Selecting a Data Type for a Parameter
The Logix5000 controllers perform DINT (32 bit) and REAL (32 bit)
math operations, which causes DINT data types to execute faster than
other integer data types. Data conversion rules of SINT to INT to DINT
are applied automatically, and can add overhead. Whenever possible,
use DINT data types for the Add-On Instruction Input and Output
parameters.
Aspect By Value (Input or Output) By Reference (InOut)
Value Synchronous - the argument's value
does not change during Add-On
Instruction execution.
Asynchronous- the argument's
value may change during
Add-On Instruction execution.
Any access by the instruction's
logic directly reads or writes the
passed tag's value.
Performance Argument values are copied in and
out of the parameters of the Add-On
Instruction. This takes more time to
execute a call to the instruction.
Parameters access argument
tags directly by reference, which
leads to faster execution of
instruction calls.
Memory usage Most amount. Least amount.
Parameter data
types supported
Atomic (SINT, DINT, INT, REAL,
BOOL).
Atomic, arrays, and structures.
28 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Creating an Alias Parameter for a Local Tag
Alias parameters simplify connecting local tags to an Input or Output
tag that is commonly used in the Add-On Instructions application
without requiring that manual code be created to make the
association. Aliases can be used to define an Input or Output
parameter with direct access to a local tag or its member. Changing
the value of an alias parameter changes the data of the local tag or
local tag member it represents and vice versa.
Alias parameters are subject to these restrictions:
Alias parameters must be either Input or Output parameters.
You can only create an alias parameter for a local tag or its
member.
Only one Input and one Output parameter may be mapped to
the same local tag or the same member of a local tag.
Only BOOL, SINT, INT, DINT, and REAL data types may be
used.
Alias parameters may not be constants.
The External Access type of an alias parameter matches the
External Access type of the local tag to which it is mapped.
For information on constants and External Access, see Data
Access Control on page 31.
Using a Single Dimension Array as an InOut Parameter
The InOut parameter can be defined to be a single dimension array.
When specifying the size of this array, consider that the user of your
array can either:
pass an array tag that is the same size as your definition.
pass an array tag that is larger than your definition.
When developing your logic, use the Size instruction to determine the
actual size of the referenced array to accommodate this flexibility.
TIP
When you monitor an array InOut parameter inside of the logic
routine, the parameter definition is used to determine the size
of the array. For example, assume you have defined an InOut
parameter to be a 10-element array of DINTs and the end user
passes in an array of 100 DINTs. Then if you open the Add-On
Instruction logic, select the appropriate context for that call,
and monitor the array parameter, only 10 elements will be
displayed.
Publication 1756-PM010C-EN-P - October 2009 29
Designing Add-On Instructions Chapter 1
Determining Which Parameters to Make Visible or Required
To help be sure that specific data is passed into the Add-On
Instruction, you can use required parameters. A required parameter
must be passed an argument for a call to the instruction to verify. In
Ladder Diagram and Structured Text, this is done by specifying an
argument tag for these parameters. In a Function Block Diagram,
required Input and Output parameters must be wired, and InOut
parameters must have an argument tag. If a required parameter does
not have an argument associated, as described above, then the routine
containing the call to the Add-On Instruction will not verify.
For Output parameters, making a parameter visible is useful if you do
not usually need to pass the parameter value out to an argument, but
you do want to display its value prominently for troubleshooting.
Required parameters are always visible, and InOut parameters are
always required and visible. All Input and Output parameters,
regardless of being marked as required or visible, can be
programmatically accessed as a member of the instruction's tag.
Simulation Instruction in Function Block
Simulation Instruction in Ladder
Required Input
Parameter
Visible
(non-required)
Input Parameter
Visible (non-required) Boolean
Output Parameter
InOut Parameter
Visible (non-required)
Output Parameter
If you want a pin that is displayed in Function Block, but wiring to it is optional, set it as Visible.
Visible
(non-required)
Input Parameter
Visible
(non-required)
Output Parameter
Required Input
Parameter
Visible (non-required) Boolean
Output Parameter
InOut Parameter
If you want the parameters value displayed on the instruction face in Ladder, set the parameter
as visible.
An Output parameter of the BOOL tag type that is not required, but visible, will show as a status
flag on the right side of the block in Ladder. This can be used for status flags like DN or ER.
30 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
This table explains the effects of the Required and Visible parameter
settings on the display of the instruction.
Input, Output, and InOut Required and Visible Settings
If you have a parameter for which the user must specify a tag as its
source for input or its destination as output, and you do not want this
to be optional, set the parameter as required. Any required parameters
are automatically set to visible.
The Visible setting is always set to visible for InOut parameters. All
InOut parameters are required.
Using Standard and Safety Tags
When creating a safety Add-On Instruction, follow these guidelines for
standard and safety tags:
Standard tags may not be used as Input, Output, or InOut
parameters of a safety Add-On Instruction.
Safety tags may be used as Input parameters for standard
Add-On Instructions.
Parameter
Type
Is the
Parameter
Required?
Is the
Parameter
Visible?
Ladder Diagram Function Block Diagram Structured Text
Does the
Value
display?
Does the
Argument
display?
Do You
Need to
Connect the
Parameter?
Does the
Argument
display?
Can You Change
Change the
Visibility
Setting Within
the Function
Block?
Does the
Argument
display?
Input Y Y Y Y Y N/A N Y
Input N Y Y N N N/A Y N
Input N N N N N N/A Y N
Output Y Y Y Y Y N/A N Y
Output N Y Y N N N/A Y N
Output N N N N N N/A Y N
InOut Y Y N Y N/A Y N Y
TIP
When you are using your Add-On Instructions, the Visible
setting may be overridden in Function Block Diagram routines if
the parameter is not required or already wired. Overriding the
visibility at the instruction call does not affect this definition
configuration.
Publication 1756-PM010C-EN-P - October 2009 31
Designing Add-On Instructions Chapter 1
Data Access Control
In RSLogix 5000 software, version 18 and later, you can prevent
programmatic modification of InOut parameters by designating them
as constants. You can also configure the type of access you will allow
external devices, such as an HMI, to have to your tag and parameter
data. You can control access to tag data changes with RSLogix 5000
software by configuring FactoryTalk security.
Constant Values
InOut parameters may be designated as constant value tags to prevent
their data from being modified by controller logic. If the logic of an
Add-On Instruction contains a write operation to a constant value
parameter, the Add-On Instruction will not verify in the Add-On
Instruction definition context.
External Access
External Access defines the level of access that is allowed for external
devices, such as an HMI, to see or modify tag values.
Add-On Instruction Parameters and Tags External Access Options
Local tag
Read/Write
Read Only
None
Input parameter
Output parameter
EnableIn parameter
Read Only
EnableOut parameter
InOut parameter N/A
32 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Planning Your Add-On
Instruction Design
Take time to plan your instruction design. Advance planning can
identify issues that need to be addressed. When defining the
requirements of an instruction, you are also determining the interface.
Keep the following aspects in mind when defining your instruction
requirements and creating your Add-On Instruction.
Intended Behavior
What is the purpose for creating the Add-On Instruction?
What problem is it expected to solve?
How is it intended to function?
Do you need to higher level of integrity on your Add-On
Instruction?
If so, you can generate an instruction signature as a means to
verify that your Add-On Instruction has not been modified.
Do you need to use safety application instructions and certify
your safety Add-On Instruction to SIL-3 integrity?
For details on how to certify a safety Add-On Instruction, refer to
the GuardLogix Controller Systems Safety Reference Manual,
publication 1756-RM093.
Parameters
What data needs to be passed to the instruction?
What information needs to be accessible outside of the
instruction?
Will alias parameters need to be defined for data from local tags
that needs to be accessible from outside the Add-On Instruction?
How will the parameters display? The order of the parameters
defines the appearance of instruction.
Which parameters should be required or visible?
Naming Conventions
The instruction name will be used as the mnemonic for your
instruction. Although the name can be up to 40 characters long, you
will typically want to use shorter, more manageable names.
Publication 1756-PM010C-EN-P - October 2009 33
Designing Add-On Instructions Chapter 1
Source Protection
What type of source protection needs to be defined, if any?
Who will have access to the source key?
Will you need to manage source protection and an instruction
signature?
Source protection can be used to provide read-only access of
the Add-On Instruction or to completely lock or hide the
Add-On Instruction and local tags.
Source protection must be applied prior to generating an
instruction signature.
Nesting - Reuse Instructions
Are there other Add-On Instructions that you can reuse?
Do you need to design your instructions to share common code?
Local Tags
What data is needed for your logic to execute but is not public?
Identify local tags you might use in your instruction. Local tags
are useful for items such as intermediate calculation values that
you do not want to expose to users of your instruction.
Do you want to create an alias parameter to provide outside
access to a local tag?
Programming Languages
What language do you want to use to program your instruction?
The primary logic of your instruction will consist of a single
routine of code. Determine which RSLogix 5000 software
programming language to use based on the use and type of
application. Safety Add-On Instructions are restricted to Ladder
Diagram.
If execution time and memory usage are critical factors, refer to
the Logix5000 Controllers Execution Time and Memory Use
Reference Manual, publication 1756-RM087.
34 Publication 1756-PM010C-EN-P - October 2009
Chapter 1 Designing Add-On Instructions
Scan Mode Routines
Do you need to provide Scan mode routines?
You can optionally define the scan behavior of the instruction in
different Scan modes. This lets you define unique initialization
behaviors on controller startup (Program -> Run), SFC step
postscan, or EnableIn False condition.
In what language do Scan mode routines need to be written?
Test
How will you test the operation of your Add-On Instruction
before commissioning it?
What possible unexpected inputs could the instruction receive,
and how will the instruction handle these cases?
Help Documentation
What information needs to be in the instruction help?
When you are creating an instruction, you have the opportunity
to enter information into various description fields. You will also
need to develop information on how to use the instruction and
how it operates.
35Publication 1756-PM010C-EN-P - October 2009 35
Chapter 2
Defining Add-On Instructions
Introduction
Create an Add-On
Instruction
Follow these steps to create a new Add-On Instruction.
1. Open a new or existing project.
2. Right-click the Add-On Instructions folder in the Controller
Organizer and choose New Add-On Instruction.
Topic Page
Create an Add-On Instruction 35
Create Parameters 37
Create Local Tags 39
Edit Parameters and Local Tags 41
Updates to Arguments Following Parameter Edits 41
Copying Parameter or Local Tag Default Values 43
Create Logic for the Add-On Instruction 44
Defining Operation in Different Scan Modes 45
Enabling Scan Modes 47
Using the EnableIn and EnableOut Parameters 52
Change the Class of an Add-On Instruction 54
Testing the Add-On Instruction 54
Defining Source Protection for an Add-On Instruction 57
Generate an Add-On Instruction Signature 60
Creating Instruction Help 63
Motor Starter Instruction Example 68
Simulation Instruction Example 70
36 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
3. Type a unique name for the new instruction.
The name can be up to 40 characters long. It must start with a
letter or underscore and must contain only letters, numbers, or
underscores. The name must not match the name of a built-in
instruction or an existing Add-On Instruction.
4. Type a description for the new instruction, maximum 512
characters.
5. For safety projects, choose a class, either Standard or Safety.
The Class field is available on the New Add-On Instruction
dialog box for safety controller projects.
6. Choose a programming language for Add-On Instruction logic.
The language Type defaults to Ladder Diagram for safety
Add-On Instructions.
7. Assign a Revision level for the instruction.
8. Write a Revision note, if necessary.
9. Add information about the Vendor, if necessary.
10. Click OK to create the instruction.
Publication 1756-PM010C-EN-P - October 2009 37
Defining Add-On Instructions Chapter 2
Create Parameters
Use the Add-On Instruction Definition Editor to create the parameters
for your instructions. Follow these steps to define the parameters for
your instruction.
1. In the Controller Organizer, right-click an Add-On Instruction
and choose Open Definition.
2. Click the Parameters tab and enter a name for a parameter.
3. Define the Usage, based on the type of parameter: Input,
Output, InOut.
4. Select a data type, with the following options based on the
parameter usage:
An Input parameter is passed by value into the Add-On
Instruction and must be a SINT, INT, DINT, REAL, or BOOL
data type.
An Output parameter is passed by value out of the Add-On
Instruction and must be a SINT, INT, DINT, REAL, or BOOL
data type.
An InOut parameter is passed by reference into the Add-On
Instruction and can be any data type including structures and
arrays.
TIP
An instruction with only Input parameters, except
EnableOut, is treated as an input instruction in a
Ladder diagram and is displayed left-justified. The
EnableOut parameter is used for the rung-out
condition.
TIP
REAL data types are not permitted in safety Add-On
Instructions.
38 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
5. If this parameter is intended as an alias for an existing local tag,
click the Alias For pull-down menu to choose the local tag or its
member.
6. Set the default values.
Default values are loaded from the Add-On Instruction definition
into the tag of the Add-On Instruction data type when it is
created, and anytime a new Input or Output parameter is added
to the Add-On Instruction.
7. Set the display style.
8. Check the box to make the parameter required or visible, as
desired.
See Determining Which Parameters to Make Visible or Required
on page 29.
If you decide to make the parameter required, it will also be
visible.
9. Type a description, maximum 512 characters.
This description appears in the instructions help.
10. Select an External Access type for Input or Output parameters.
11. Check the Constant box for InOut parameters you want to
designate as constant values.
12. Repeat for additional parameters.
TIP
You can also designate a parameter as an alias for a
local tag by using the Tag Editor.
See Edit Parameters and Local Tags on page 41.
TIP
Check the box at the bottom of the Add-On Instruction
Definition Editor to Copy all default values of
parameters and local tags whose values were modified
to all tags of this instruction type if you want to update
existing invocations of the instruction to the new default
values.
For details on copying default values, see Copying
Parameter or Local Tag Default Values on page 43.
TIP
You can also create parameters by using the Tag Editor, New
Parameter or Local Tag dialog box, or by right-clicking a tag
name in the logic of your routine.
Publication 1756-PM010C-EN-P - October 2009 39
Defining Add-On Instructions Chapter 2
The order that you create the parameters is how they will appear in
the data type and on the instruction face. To rearrange the order on
the Parameter tab of the Add-On Instruction Definition Editor, select
the parameter row and click Move Up or Move Down.
Add-On Instruction Definition Editor Parameters Tab
Create Local Tags
Use the Add-On Instruction Definition Editor to create the local tags
for your instructions. Local tags contain data that will be used by your
Add-On Instruction but that you do not want exposed to the user of
your instruction. Local tags do not appear in the data structure for an
Add-On Instruction because they are hidden members.
Follow these steps to define the local tags for your instruction.
1. In the Controller Organizer, right-click an instruction and choose
Open Definition.
TIP
You can access local tag values from an HMI by specifying the
name of the local tag as a member in an Add-On Instruction
type tag. For example, the Motor_Starter v1.0 instruction,
shown in step 2, has a tag called CheckAuxContact. This tag
can be referenced by an HMI via
instancetag.CheckAuxContact, where instancetag is the tag
used to call the instruction.
40 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
2. Click the Local Tags tab and type a name for a new tag and
select a data type.
You cannot use these data types for local tags -
ALARM_ANALOG, ALARM_DIGITAL, MESSAGE, or any Motion
data types, for example Axis or MOTION_GROUP. To use these
type of tags in your Add-On Instruction, define an InOut
Parameter. Local tags also are limited to single dimension arrays,
the same as User-Defined Data Types.
3. Set the default values.
Default values are loaded from the Add-On Instruction definition
into the tag of the Add-On Instruction data type when it is
created or any time a new tag is added to the Add-On
Instruction.
4. Set the display style.
5. Type a description, a maximum of 512 characters.
TIP
Refer to the GuardLogix Controller Systems Safety
Reference Manual, publication 1756-RM093, for a list
of data types supported for safety instructions.
TIP
Check the box at the bottom of the Add-On Instruction
Definition Editor to Copy all default values of
parameters and local tags whose values were modified
to all tags of this instruction type if you want to update
existing invocations of the instruction to the new default
values.
For details on copying default values, see Copying
Parameter or Local Tag Default Values on page 43.
Publication 1756-PM010C-EN-P - October 2009 41
Defining Add-On Instructions Chapter 2
6. Repeat for additional local tags.
Edit Parameters and Local
Tags
You can also add and edit parameters and local tags on the Edit Tags
tab, shown below.
Updates to Arguments
Following Parameter Edits
If you edit an Add-On Instruction by adding, deleting, renaming,
reordering, or changing the status or usage type of one or more
parameters, RSLogix 5000 software, version 18 and later, automatically
updates the arguments on calls to the instruction.
TIP
When you create a local tag from the Local Tags tab, the
External Access setting defaults to None. You can edit the
External Access setting by using the Tag Editor.
See Edit Parameters and Local Tags on page 41.
ATTENTION
Source-protected routines and other source-protected Add-On
Instructions that use the edited Add-On Instruction are not
automatically updated if the source key is unavailable. The
Add-On Instruction or routine may still verify, but the resulting
operation may not be as intended.
It is your responsibility to know where Add-On Instructions are
used in logic when you make edits to existing Add-On
Instructions.
42 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
A confirmation dialog box shows you the impacts of the edits and lets
you review the pending changes before confirming or rejecting them.
An asterisk identifies parameters with changes pending.
Existing arguments are reset to the parameters they were
originally associated with.
Newly added parameters are inserted with a ? in the argument
field, except for Structured Text, where the field is blank.
Unknown parameters are created for arguments where
associated parameters have been deleted.
To accomplish this update, RSLogix 5000 software tracks the changes
made to the Add-On Instruction parameters from the original
instruction to the final version. In contrast, the import and paste
processes compare only parameter names to associate arguments with
parameters. Therefore, if two different parameters have the same
name, but different operational definitions, importing or pasting may
impact the behavior of the instruction.
Publication 1756-PM010C-EN-P - October 2009 43
Defining Add-On Instructions Chapter 2
Copying Parameter or Local
Tag Default Values
In RSLogix 5000 software, version 18 or later, you can choose to copy
parameter or local tag default values to all tags of the Add-On
Instruction data type or just to specific tags. You can do so only when
you are offline.
If you modify the default values of a parameter or local tag by using
the Add-On Instruction Definition Editor, you can choose to copy the
modified values to all of the tags of the Add-On Instruction data type
by checking Copy all default values of parameters and local tags.
You can also click the copy default values icon to copy default values
to all tags the Add-On Instruction data type. The icon appears on the
watch pane (as a context menu), data monitor, and logic editor when
the Data Context is the Add-On Instructions definition.
If you want to select which specific tags and values to copy, click the
pull-down arrow of the copy default values icon and choose Copy
Specified Values.
ATTENTION
Values cannot be modified when the instance tags are part of a
source-protected Add-On Instruction or you do not have
sufficient permission to make edits.
44 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
The Copy Default values dialog box shows the current default values
for the parameters and local tags, and the instance tags where the
Add-On Instruction is used or referenced.
Check the boxes to select which values to copy to which tags, and
click OK.
Create Logic for the Add-On
Instruction
Follow these steps to enter logic into your project.
1. In the Controller Organizer, expand the Add-On Instructions
folder.
2. Expand the instruction and double-click the logic routine to
open.
3. Edit your logic by using the available language editors.
Publication 1756-PM010C-EN-P - October 2009 45
Defining Add-On Instructions Chapter 2
Execution Considerations for Add-On Instructions
An Add-On Instruction is executed just like any other routine
belonging to a particular program. Because another task can preempt
a program containing an Add-On Instruction that is being executed,
an Add-On Instruction may be interrupted prior to completing its
execution. In standard programs, you can use the User Interrupt
Disable/Enable (UID/UIE) instructions to block a task switch if you
want to be sure the Add-On Instruction executes uninterrupted before
switching to another task.
Optimizing Performance
The performance depends on the structuring, configuration, and the
amount of code in an Add-On Instruction. You can pass large amounts
of data through a structure by using an InOut parameter. The size of
data referenced by an InOut parameter does not impact scan time and
there is no difference between passing a user-defined type tag or an
atomic tag because it is passed by reference.
When a rung condition is false, any calls to an Add-On Instruction are
still processed even though the logic routine is not executed. The scan
time can be affected when many instances of an Add-On Instruction
are executed false. Be sure to provide instructions in your
documentation if an Add-On Instruction can be skipped when the
rung condition is false.
Defining Operation in
Different Scan Modes
To provide Add-On Instructions with the same flexibility as built-in
instructions, optional Scan mode routines can be configured to fully
define the behavior of the instruction. Scan mode routines do not
initially exist for Add-On Instructions. You can create them depending
upon the requirements of your instruction.
TIP
UID and UIE instructions are not supported in the safety task of
GuardLogix projects.
46 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Like all built-in instructions in the controller, Add-On Instructions
support the following four controller Scan modes.
The default behavior for executing an Add-On Instruction with no
optional scan routines created may be sufficient for the intended
operation of the instruction. If you do not define an optional Scan
Mode, the following default behavior of an Add-On Instruction
occurs.
Scan Mode Types
Scan Mode Description
True The instruction is scanned as the result of a true rung condition or the
EnableIn parameter is set True.
False The instruction is scanned as the result of a false rung condition or the
EnableIn parameter is set False. Instructions in the controller may or may
not have logic that executes only when that instruction is scanned false.
Prescan Occurs when the controller either powers up in Run mode or transitions
from Program to Run. Instructions in the controller may or may not have
logic that executes only when that instruction is executed in Prescan
mode.
Postscan
(1)
(1) Postscan mode routines cannot be created for safety Add-On Instructions because safety instructions do not
support SFC.
Occurs as a result of an Action in an Sequential Function Chart (SFC)
routine becoming inactive if SFCs are configured for Automatic Reset.
Instructions in the controller may or may not have logic that executes
only when that instruction is executed in Postscan mode.
Default Instruction Behavior
Scan Mode Result
True Executes the main logic routine of the Add-On Instruction.
False Does not execute any logic for the Add-On Instruction and does not write
any outputs. Input parameters are passed values.
Prescan Executes the main logic routine of the Add-On Instruction in Prescan
mode. Any required Input and Output parameters' values are passed.
Postscan Executes the main logic routine of the Add-On Instruction in Postscan
mode.
Publication 1756-PM010C-EN-P - October 2009 47
Defining Add-On Instructions Chapter 2
For each Scan mode, you can define a routine that is programmed
specifically for that Scan mode and can be configured to execute in
that mode.
Enabling Scan Modes
The Scan Modes tab in the Instruction Definition Editor lets you create
and enable execution of the routines for the three Scan modes:
Prescan, Postscan, and EnableInFalse.
Prescan Routine
When the controller transitions from Program mode to Run mode or
when the controller powers up in Run mode, all logic within the
controller is executed in Prescan mode. During this scan, each
instruction may initialize itself and some instructions also initialize any
tags they may reference. For most instructions, Prescan mode is
synonymous with scanning false. For example, an OTE instruction
clears its output bit when executed during Prescan mode. For others,
special initialization may be done, such as an ONS instruction setting
its storage bit during Prescan mode. During Prescan mode, all
instructions evaluate false so conditional logic does not execute.
The optional Prescan routine for an Add-On Instruction provides a
way for an Add-On Instruction to define additional behavior for
Prescan mode. When a Prescan routine is defined and enabled, the
Prescan routine executes normally after the primary logic routine
executes in Prescan mode. This is useful when you want to initialize
tag values to some known or predefined state prior to execution. For
example, setting a PID instruction to Manual mode with a 0% output
prior to its first execution or to initialize some coefficient values in
your Add-On Instruction.
User-programmed Routines for Specific Scan Modes
Scan Mode Result
True The main logic routine for the Add-On Instruction executes (not optional).
False The EnableIn False routine executes normally in place of the main logic
when a scan false of the instruction occurs. Any required (or wired in
FBD) Input and Output parameters' values are passed.
Prescan The Prescan routine executes normally after a prescan execution of the
main logic routine. Any required Input and Output parameters' values are
passed.
Postscan The Postscan routine executes normally after a postscan execution of the
main logic routine.
48 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
When an Add-On Instruction executes in Prescan mode, any required
parameters have their data passed.
Values are passed to Input parameters from their arguments in
the instruction call.
Values are passed out of Output parameters to their arguments
defined in the instruction call.
These values are passed even when the rung condition is false in
Ladder Diagram or when the instruction call is in a false conditional
statement in Structured Text. When Function Block Diagram routines
execute, the data values are copied to all wired inputs and from all
wired outputs, whether or not the parameters are required.
Follow these steps to create a Prescan routine.
1. In the Controller Organizer, right-click an instruction and choose
Open Definition.
2. Click the Scan Modes tab.
3. Click New for Prescan Routine.
Publication 1756-PM010C-EN-P - October 2009 49
Defining Add-On Instructions Chapter 2
4. From the Type pull-down menu on the New Scan Mode Routine
dialog box, choose the type of programming language: Ladder
Diagram, Function Block, or Structured Text.
5. Type a description of the Prescan behavior.
6. Click OK to create the routine and return to the Scan Modes tab.
7. Define if the prescan routine executes (or not) by checking or
clearing Execute Prescan routine after the logic routine is
prescanned.
The Prescan routine can now be edited like any other routine.
Postscan Routine
Postscan mode occurs only for logic in a Sequential Function Chart
Action when the Action becomes inactive and the SFC language is
configured for Automatic Reset (which is not the default option for
SFC). When an SFC Action becomes inactive, then the logic in the
Action is executed one more time in Postscan mode. This mode is
similar to Prescan in that most instructions simply execute as if they
have a false condition. It is possible for an instruction to have different
behavior during Postscan mode than it has during Prescan mode.
When an Add-On Instruction is called by logic in an SFC Action or a
call resides in a routine called by a JSR from an SFC Action, and the
Automatic Reset option is set, the Add-On Instruction executes in
Postscan mode. The primary logic routine of the Add-On Instruction
executes in Postscan mode. Then if it is defined and enabled, the
Postscan routine for the Add-On Instruction executes. This could be
useful in resetting internal states, status values, or de-energizing
instruction outputs automatically when the action is finished.
TIP
Because safety Add-On Instructions cannot be called from an
SFC Action, this option is disabled for safety Add-On
Instructions.
50 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Follow these steps to create a postscan routine.
1. In the Controller Organizer, right-click an instruction and choose
Open Definition.
2. Click the Scan Modes tab.
3. Click New for Postscan Routine.
4. From the Type pull-down menu on the New Scan Mode Routine
dialog box, choose the type of programming language: Ladder
Diagram, Function Block, or Structured Text.
5. Type a description of the postscan behavior.
6. Click OK to create the routine and return to the Scan Modes tab.
7. Define if the postscan routine executes (or not) by checking or
clearing Execute Postscan routine after the logic routine is
postscanned.
The Postscan routine can now be edited like any other routine.
Publication 1756-PM010C-EN-P - October 2009 51
Defining Add-On Instructions Chapter 2
EnableInFalse Routine
When defined and enabled for an Add-On Instruction, the
EnableInFalse routine executes when the rung condition is false or if
the EnableIn parameter of the Add-On Instruction is false (0). This is
useful primarily for scan false logic, when used as an output
instruction in a Ladder routine. A common use of scan false is the
setting of OTEs to the de-energized state when the preceding rung
conditions are false. An Add-On Instruction can use the EnableInFalse
capability to let you define behavior for the False conditions.
When the Add-On Instruction is executed in the false condition and
has an EnableInFalse routine defined and enabled, any required
parameters have their data passed.
Values are passed to Input parameters from their arguments in
the instruction call.
Values are passed out of Output parameters from their
arguments in the instruction call.
If the EnableInFalse routine is not enabled, the only action performed
for the Add-On Instruction in the false condition is that the values are
passed to any required Input parameters in ladder logic.
Follow these steps to create an EnableInFalse routine.
1. Right-click the instruction and choose Open Definition.
2. Click the Scan Modes tab.
3. Click New on EnableInFalse routine.
52 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
4. From the Type pull-down menu on the New Scan Mode Routine
dialog box, choose the type of programming language: Ladder,
Function Block, or Structured Text.
5. Type a description of the EnableInFalse behavior.
6. Click OK to add an EnableInFalse routine to the Add-On
Instruction definition.
7. Define if EnableIn False routine executes (or not) by checking
or clearing Execute EnableInFalse routine.
The EnableInFalse routine can now be edited like any other routine.
Using the EnableIn and
EnableOut Parameters
The EnableIn and EnableOut parameters that appear by default in
every Add-On Instruction have behaviors that conform to the three
language environments: Ladder Diagram, Function Block Diagram,
and Structured Text.
To execute the primary logic routine in any of the language
environments, the EnableIn parameter must be True (1). In general,
the EnableIn parameter should not be referenced by the primary logic
routine within the instruction definition. The EnableOut parameter
will, by default, follow the state of the EnableIn parameter but can be
overridden by user logic to force the state of this Parameter.
If the EnableIn parameter of the instruction is False (0), the logic
routine is not executed and the EnableOut parameter is set False (0).
If an EnableInFalse routine is included in the instruction definition
and it is enabled, the EnableInFalse routine will be executed.
TIP
If EnableIn is False, then EnableOut cannot be made True in an
EnableIn False routine.
Publication 1756-PM010C-EN-P - October 2009 53
Defining Add-On Instructions Chapter 2
EnableIn Parameter and Ladder Diagram
In the ladder diagram environment, the EnableIn parameter reflects
the rung state on entry to the instruction. If the rung state preceding
the instruction is True (1), the EnableIn parameter will be True and
the primary logic routine of the instruction will be executed. Likewise,
if the rung state preceding the instruction is False (0), the EnableIn
parameter will be False and the primary logic routine will not be
executed.
EnableIn Parameter and Function Blocks
In the function block environment, the EnableIn parameter can be
manipulated by the user through its pin connection. If no connection
is made, the EnableIn parameter is set True (1) when the instruction
begins to execute and the primary logic routine of the instruction will
be executed. If a wired connection to this parameter is False (0), the
primary logic routine of the instruction will not execute. Another
reference writing to the EnableIn parameter, such as a Ladder Diagram
rung or a Structured Text assignment, will have no influence on the
state of this parameter. Only a wired connection to this parameters
input pin can force it to be False (0).
EnableIn Parameter and Structured Text
In the Structured Text environment, the EnableIn parameter is always
set True (1) by default. The user cannot influence the state of the
EnableIn parameter in a Structured Text call to the instruction.
Because EnableIn is always True (1) in Structured Text, the
EnableInFalse routine will never execute for an instruction call in
Structured Text.
TIP
An instruction with only Input parameters, except EnableOut, is
treated as an input instruction (left-justified) in a Ladder
Diagram. The EnableOut parameter is used for the rung-out
condition.
54 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Change the Class of an
Add-On Instruction
You can change the class of a safety Add-On Instruction so that it can
be used in a standard task or standard controller. You can change the
class in a safety project if the instruction does not have an instruction
signature, you are offline, the application does not have a safety task
signature, and is not safety-locked.
You can also change the class from standard to safety so that the
Add-On Instruction can be used in the safety task.
Changing the class of an Add-On Instruction results in the same class
change being applied to the routines, parameters, and local tags of the
Add-On Instruction. The change does not affect nested Add-On
Instructions or existing instances of the Add-On Instruction.
If any parameters or tags become unverified due to the change of
class, they are identified on the Parameters and Local Tags tabs of the
Add-On Instruction Editor.
If any of the restrictions for safety Add-On Instructions are violated by
changing the class from standard to safety, one of the following errors
is displayed and the change does not succeed:
Routines must be of Ladder Diagram type.
Safety Add-On Instructions do not support the Postscan routine.
One or more parameters or local tags have an invalid data type
for a safety Add-On Instruction.
You must edit the parameter, tag, or routine types before the class
change can be made.
Testing the Add-On
Instruction
You need to test and troubleshoot the logic of an instruction to get it
working.
TIP
If the safety controller project contains safety Add-On
Instructions, you must remove them from the project or change
their class to standard before changing to a standard controller
type.
TIP
When a fault occurs in an Add-On Instruction routine, a fault log
is created that contains extended information useful for
troubleshooting.
Publication 1756-PM010C-EN-P - October 2009 55
Defining Add-On Instructions Chapter 2
Before You Test
Before you start to test an Add-On Instruction, do the following.
1. Open a project to debug offline.
2. Add the Add-On Instruction to the project, if it is not already
there.
Test the Flow
1. Add a call to the instruction in a routine in the open project.
2. Assign any arguments to required parameters for your call.
3. Download the project.
Monitor Logic with Data Context Views
You can simplify the online monitoring and troubleshooting of your
Add-On Instruction by using Data Context views. The Data Context
selector lets you select a specific call to the Add-On Instruction that
defines the calling instance and arguments whose values are used to
visualize the logic for the Add-On Instruction.
TIP
Add-On Instructions can only be created or modified when
offline. You can add, delete, or modify tag arguments in
calls to Add-On Instructions while editing online, but you
cannot edit arguments inside the Add-On Instruction while
online.
TIP
When troubleshooting an Add-On Instruction, use a
non-arrayed instance tag for the call to the instruction.
This lets you monitor and troubleshoot the instruction's
logic routine with a data context. Variable indexed arrays
cannot be used to monitor the logic inside an Add-On
Instruction.
56 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Follow these steps to monitor the logic.
1. Go into Run mode.
2. Right-click the instruction call and choose Open Instruction
Logic.
The logic routine opens with animated logic for the specific calling
instance.
Verifying Individual Scan Modes
The most straightforward method to verify Scan mode operation is to
execute the instruction first with the Scan mode routine disabled, then
again with it enabled. Then you can determine whether the Scan
mode routine performed as expected.
Instruction Description
True This is simply the execution of the main logic routine.
False In a ladder logic target routine, this entails placing an XIC before an
instance of the instruction and evaluating instruction results when the XIC
is false.
In a Function Block target routine, this entails executing an instance of the
instruction with the EnableIn parameter set to zero (0).
Prescan Place the controller in Program mode, then place it in Run mode.
Postscan With the controller configured for SFC Automatic Reset, place an instance
of the instruction into the Action of an SFC. Run the SFC such that this
Action is executed and the SFC proceeds beyond the step that is
associated with this Action.
Publication 1756-PM010C-EN-P - October 2009 57
Defining Add-On Instructions Chapter 2
Defining Source Protection
for an Add-On Instruction
You can apply source protection to your Add-On Instruction to
protect your intellectual property or prevent unintended edits of a
validated source.
With source protection you can limit a user of your Add-On
Instruction to read-only access or prevent access to the internal logic
or local tags used by the instruction. You can protect the use and
modification of your instructions with a source key file when you
distribute them.
You have two options when using source protection.
Source Protected
Users without the source key cannot view any routine or local
tags, or make any edits to the Add-On Instruction. Choose this
option if you want to protect the source definition of an Add-On
Instruction from the view of a user. This may be due to the
proprietary nature of the algorithms or for strict revision control.
Source Protected with Viewable Option
Users without the source key can view all components of the
Add-On Instruction including its logic and local tags, but are
prevented from making any edits to the instruction.
Enable the Source Protection Feature
If source protection is unavailable and not listed in your menus, you
can enable it by using the RS5KSrcPtc.exe tool on your installation CD.
If it is the first time the source protection has been configured, a
dialog box appears asking to configure a source key file location.
1. Enter the location of (or browse to) where the source key is
kept, it may or may not exist yet.
2. Click OK.
TIP
Apply source protection before generating an instruction
signature for your Add-On Instruction definition. You will need
the source key to create a signature history entry.
When source protection is enabled, you can still copy the
instruction signature or signature history, if they exist.
58 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Apply Source Protection
To source protect your Add-On Instruction follow these steps.
1. In RSLogix 5000 software, choose Tools > Security > Configure
Source Protection, to access the source configuration dialog box.
2. Click Specify to identify the location for the sk.dat Source Key
File.
3. Click OK in both dialog boxes to accept.
4. Click Yes to confirm creation of the sk.dat Key File.
5. Expand the Add-On Instructions folder to view the instructions
available to apply source protection.
All routines and Add-On Instruction definitions in the project are
listed.
6. Select the Add-On Instruction you want to protect and click
Protect.
Publication 1756-PM010C-EN-P - October 2009 59
Defining Add-On Instructions Chapter 2
7. On the Source Key Entry dialog box, enter the individual source
key for this component.
These source keys follow the conventions for routine source
keys which are defined in the online help.
8. If you want to allow users to be able to see the logic and local
tags, check Allow viewing of component(s).
The Source Protection Configuration should now resemble the
following dialog box.
9. Click Close.
10. Save the project.
IMPORTANT
If you want to observe the source protection settings, before
you click Close, you must first do one of the following:
click Clear
click Disable Ability to Configure Source Protection
remove the sk.dat file from the personal computer so that
the source key is no longer present.
IMPORTANT
If you export a source-protected Add-On Instruction and want
the exported contents encrypted, you must first remove,
rename, or move the source key file (sk.dat). This causes the
exported Add-On Instructions to be encrypted.
60 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Observe Source Protection
If you want to observe how source protection works, follow these
steps.
1. Rename the sk.dat file to some other name.
2. Start RSLogix 5000 software and open the project.
There is now no valid key file available to this RSLogix 5000
project.
3. Review how the instruction appears in the Add-On Instructions
folder.
Now the protected Add-On Instruction definition's routines and
tag folder are not shown if fully protected, and the definition
cannot be edited.
Generate an Add-On
Instruction Signature
The Signature tab of the Add-On Instruction Definition Editor lets you
manage the instruction signature, create signature history entries, and
view the safety instruction signature, if it exists. Instruction signatures
are applied to the definition of the Add-On Instruction. All instances
of that Add-On Instruction are sealed when the signature is applied.
Generate, Remove, or Copy an Instruction Signature
On the Signature tab of the Add-On Instruction Definition Editor, click
Generate to create an instruction signature or Remove to delete the
instruction signature.
You must be offline to generate or remove an instruction signature.
Both actions change the Last Edited Date.
TIP
When the source key is available, the Add-On Instruction
behaves the same as if it were not source protected.
IMPORTANT
If you remove an instruction signature when the Add-On
Instruction also has a safety instruction signature, the safety
instruction signature is also deleted.
Publication 1756-PM010C-EN-P - October 2009 61
Defining Add-On Instructions Chapter 2
You can click Copy to copy the instruction signature and the safety
instruction signature, if it exists, to the clipboard to facilitate
record-keeping.
Create a Signature History Entry
The signature history provides a record of signatures for future
reference. A signature history entry consists of the name of the user,
the instruction signature, the timestamp value, and a user-defined
description. You can only create a signature history if an instruction
signature exists and you are offline. Creating a signature history
changes the Last Edited Date, which becomes the timestamp shown in
the history entry. Up to six history entries may be stored.
Follow these steps to create a signature history entry.
1. On the Signature tab of the Add-On Instruction Definition
Editor, click Add to History.
2. Type a description, up to 512 characters long, for the entry.
3. Click OK.
To delete the signature history, click Clear Signature History while the
instruction does not have an instruction signature. You must be offline
to delete the Signature History.
IMPORTANT
If an invalid instruction signature is detected during
verification, an error message indicates that the signature is
invalid. You must remove the instruction signature, review the
Add-On Instruction, and generate a new instruction signature.
TIP
To facilitate record-keeping, you can copy the entire signature
history to the clipboard by selecting all the rows in the
signature history and choosing Copy from the Edit menu. The
data is copied in tab separated value (TSV) format.
62 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Generate a Safety Instruction Signature
When a sealed safety Add-On Instruction is downloaded for the first
time, a SIL 3 safety instruction signature is automatically generated.
Once created, the safety instruction signature is compared at every
download.
If RSLogix 5000 software detects an invalid safety instruction signature
value, it generates a new safety instruction signature value in the
offline project and displays a warning indicating that the safety
instruction signature was changed. The safety instruction signature is
deleted if the instruction signature is removed.
Viewing and Printing the Instruction Signature
When the instruction signature has been generated, RSLogix 5000
software displays the instruction with the blue seal icon in the
Controller Organizer, on the Add-On Instruction title bar, and in the
Logic Editor.
IMPORTANT
After testing the safety Add-On Instruction and verifying its
functionality, you must record the instruction signature, the
safety instruction signature and the timestamp value. Recording
these values will help you determine if the instruction
functionality has changed.
Refer to the GuardLogix Controller Systems Safety Reference
manual, publication 1756-RM093, for details on safety
application requirements.
TIP
When an instruction is sealed, the instruction signature is displayed on the
faceplate of the instruction in the Ladder Diagram Editor and the Function Block
Diagram Editor.
You can turn off the display of the instruction signature in the Workstation
Options dialog box of RSLogix 5000 software.
Ladder Diagram Function Block Diagram
Publication 1756-PM010C-EN-P - October 2009 63
Defining Add-On Instructions Chapter 2
You can also view the instruction signature and the safety instruction
signature on the Quick View pane of the Controller Organizer and on
the Signature tab of the Instruction Definition Editor dialog box.
The Add-On Instruction name, revision, instruction signature, safety
instruction signature, and timestamp are printed on the Add-On
Instruction Signature Listing report. You can also choose to include
the instruction signature, safety instruction signature, and signature
history on the Add-On Instruction report by clicking Print Options on
the Generate Report dialog box.
Creating Instruction Help
Custom instruction help is generated automatically as you are creating
your Add-On Instructions. RSLogix 5000 software automatically builds
help for your Add-On Instructions by using the instructions
description, revision note, and parameter descriptions. By creating
meaningful descriptions, you can help the users of your instruction.
In addition, you can add your own custom text to the help by using
the extended description field. You can provide additional help
documentation by entering it on the Help tab of the Add-On
Instruction Definition Editor. The instruction help is available in the
instruction browser and from any call to the instruction in a language
editor by pressing F1.
Write Clear Descriptions
When writing your descriptions keep the following in mind:
Use short sentences and simple language.
Be brief and direct when you write.
Include simple examples.
Proofread your entries.
64 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
This is an example of the Extended Description Text field in the Help
tab of the Add-On Instruction Definition Editor. This area lets you
create directions on how to use and troubleshoot your instruction.
The Instruction Help Preview window shows how your text will look
as generated instruction help.
Document an Add-On Instruction
Follow these steps to create custom help for an instruction.
1. Right-click an Add-On Instruction and choose Open Definition.
2. On the General tab, enter a description and a revision note for
the Add-On Instruction to explain the purpose of the instruction.
3. Click the Parameters tab and enter a meaningful description for
each Parameter.
TIP
When you are entering your text into the Extended Description
Text field, you can use returns and tabs in the field to format the
text, and if you copy and paste text into the field tabs are
preserved.
Publication 1756-PM010C-EN-P - October 2009 65
Defining Add-On Instructions Chapter 2
4. Right-click each routine located below the Add-On Instruction in
the Controller Organizer and choose Properties.
5. Enter a description for execution of each routine.
a. For the logic routine, describe execution of the instruction
when EnableIn is true.
b. For the EnableInFalse routine (if one exists), describe actions
that will take place when EnableIn is false, such as any
outputs that get cleared.
c. For the Prescan routine (if one exists), briefly describe actions
that will take place during the Prescan routine, such as
initialization of any parameters.
d. For the Postscan routine (if one exists), briefly describe
actions that will take place during the Postscan routine, such
as initialization of any parameters resetting any internal state
of the instruction.
6. Click the Help tab of the Add-On Instruction Definition Editor
and enter additional information in the Extended Description
field.
The extended description can include the following information:
Additional parameter information
Description of how the instruction executes
Change history notes
66 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
7. Review the Help format in the preview window.
This is an example of the RSLogix 5000
software generated help for the instruction.
This information is gathered from the
definition descriptions that you complete
when defining an instruction.
Publication 1756-PM010C-EN-P - October 2009 67
Defining Add-On Instructions Chapter 2
Language Switching
With RSLogix 5000 software, version 17 and later, you have the option
to display project documentation, such as tag descriptions and rung
comments in any supported localized language. You can store project
documentation for multiple languages in a single project file rather
than in language-specific project files. You define all the localized
languages that the project will support and set the current, default,
and optional custom localized language. The software uses the default
language if the current language's content is blank for a particular
component of the project. However, you can use a custom language
to tailor documentation to a specific type of project file user.
Enter the localized descriptions in your RSLogix 5000 project, either
when programming in that language or by using the import/export
utility to translate the documentation offline and then import it back
into the project. Once you enable language switching in RSLogix 5000
software, you can dynamically switch between languages as you use
the software.
Project documentation that supports multiple translations within a
project includes:
component descriptions in tags, routines, programs,
user-defined data types, and Add-On Instructions.
equipment phases.
trends.
controllers.
alarm messages (in ALARM_ANALOG and ALARM_DIGITAL
configuration).
tasks.
property descriptions for modules in the Controller Organizer.
rung comments, SFC text boxes, and FBD text boxes.
If you want to allow language switching on an Add-On Instruction
that is sealed with an instruction signature, you must enter the
localized documentation into your Add-On Instruction before
generating the signature. Because the signature history is created after
the instruction signature is generated, the signature history is not
translatable. If the translated information already exists when you
generate the Add-On Instruction signature, you can switch the
language while keeping the signature intact because the switch does
not alter the instruction definition, it only changes the language that is
displayed.
For more information on enabling a project to support multiple
translations of project documentation, refer to the online help.
68 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Motor Starter Instruction
Example
The Motor_Starter Add-On Instruction starts and stops a motor.
If the stop pushbutton is closed and the start pushbutton is pressed
then:
the motor gets the command to run.
the instruction seals in the command, so the motor keeps
running even after you release the start pushbutton.
If the stop pushbutton is pressed (opened), then the motor stops.
Motor Starter Example Definition Editor General Tab
Motor Starter Example Definition Editor Parameter Tab
Publication 1756-PM010C-EN-P - October 2009 69
Defining Add-On Instructions Chapter 2
Motor Starter Example Ladder Logic
The following diagrams show the Motor Starter instruction called in
three different programming languages.
Motor Starter Ladder Diagram
70 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Motor Starter Function Block Diagram
Motor Starter Structured Text
Motor_Starter(Motor_Starter_ST, Stop_PB, Start_PB, Motor_Out_ST);
Simulation Instruction
Example
The Simulation_DT_1st Add-On Instruction adds a dead time and a
first-order lag to an input variable.
Simulation Example Definition Editor General Tab
Publication 1756-PM010C-EN-P - October 2009 71
Defining Add-On Instructions Chapter 2
Simulation Example Definition Editor Parameter Tab
Simulation Example Logic
72 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Ladder Diagram Configuration
In this example, the instruction simulates a deadtime and lag (first
order) process.
The Simulation_DT_1st instruction reads the control variable from the
PID instruction. The PID instruction reads the SimOutput Parameter of
the Simulation_DT_1st instruction.
The Simulation_DT_1st
instruction reads the control
variable from the PID
instruction.
The PID instruction reads the
SimOutput Parameter of the
Simulation_DT_1st instruction.
Sim_DT_LD.SimOutput
Simulation_DT_1st tag SimOutput Parameter
Publication 1756-PM010C-EN-P - October 2009 73
Defining Add-On Instructions Chapter 2
Function Block Diagram Configuration
The PIDE instruction sends the control variable to the
Simulation_DT_1st instruction. The Simulation_DT_1st instruction
calculates an output and sends it to the PIDE instruction as the
process variable
Structured Text Configuration
The PIDE instruction sends the control
variable to the Simulation_DT_1st instruction.
The Simulation_DT_1st instruction
calculates an output and sends it to the
PIDE instruction as the process variable.
Simulation_DT_1st( Sim_DT_ST, My_PIDE_ST.CVEU, DT_Array_ST );
My_PIDE_ST.PV := Sim_DT_ST.SimOutput;
PIDE(My_PIDE_ST );
The Simulation_DT_1st instruction
reads the control variable from the
PIDE instruction and calculates an
output.
The output goes to the process
variable of the PIDE instruction.
Sim_DT_ST . SimOutput
Simulation_DT_1st tag
dot
SimOutput Parameter
74 Publication 1756-PM010C-EN-P - October 2009
Chapter 2 Defining Add-On Instructions
Notes:
75Publication 1756-PM010C-EN-P - October 2009 75
Chapter 3
Using Add-On Instructions
Introduction
Add-On Instructions are used in your routines like any built-in
instructions. You add calls to your instruction and then define the
arguments for any parameters.
Accessing Add-On
Instructions
The Add-On Instruction can be used in any one of the Ladder
Diagram, Function Block, or Structured Text languages (including
Structured Text within Sequential Function Chart actions). The
appearance of the instruction conforms to the language in which it is
placed.
The Add-On Instructions in the project can be accessed from any of
the normal instruction selection tools.
The instruction toolbar has an Add-On tab that lists all of the currently
available Add-On Instructions in the project.
Topic Page
Accessing Add-On Instructions 75
Use the Add Element Dialog Box 76
Include an Add-On Instruction in a Routine 77
Tips for Using an Add-On Instruction 79
Programmatically Access a Parameter 79
Monitor the Value of a Parameter 82
View Logic and Monitor with Data Context 83
Determine if the Add-On Instruction is Source Protected 85
Copy an Add-On Instruction 86
Store Your Add-On Instructions 87
IMPORTANT
Safety Add-On Instructions can be used only in safety routines,
which are currently restricted to ladder logic. Safety Add-On
Instructions are shown in the Language Element Toolbar only
when the routine is a safety routine.
76 Publication 1756-PM010C-EN-P - October 2009
Chapter 3 Using Add-On Instructions
Use the Add Element Dialog
Box
Follow these instructions to access the Add (language) Element dialog
box.
1. Press Alt + Insert anywhere in the editor or by right-clicking the
logic in the Editor.
2. Locate the Add-On Instruction you want to add to your routine.
Publication 1756-PM010C-EN-P - October 2009 77
Using Add-On Instructions Chapter 3
3. Select the Add-On Instruction and click OK.
Use to display the instruction help for any
instruction in the browser.
Include an Add-On
Instruction in a Routine
Follow this procedure when you want to use an Add-On Instruction in
one of your routines.
1. Open the Add-On Instruction folder in the Controller Organizer
and view the listed instructions.
If the instruction you want to use is not listed, you need to do
one of the following:
Create the instruction in your project.
Copy and paste an instruction into your project.
Get the file for an exported instruction definition and then
import the instruction into your current project.
2. Open the routine that will use the instruction.
3. Click the Add-On tab on the instruction toolbar.
4. Click the desired Add-On Instruction, for example Simulation,
and drag the instruction from the toolbar into the routine.
5. Define arguments for each Parameter on the instruction call.
78 Publication 1756-PM010C-EN-P - October 2009
Chapter 3 Using Add-On Instructions
The instruction appears as follows in each of the languages.
Parameter With Description
Single question mark This is a required InOut parameter. Enter a tag.
Single and double question marks This is a required Input or Output parameter. Enter a
tag.
Double question marks This is not a required parameter. You can either:
leave as is and use the default value.
enter a different value if its an Input
parameter.
Item Description
Nub on the end of pin This is a required Input or Output parameter.
You must wire the pin to an IREF, OREF, connector,
or another block to verify.
Single question mark This is a required InOut parameter. Enter a tag.
No nub on the end of pin This is not a required parameter.
You can either:
leave as is and use the default value.
enter a different value if its an Input
parameter.
Ladder Diagram
Function Block Diagram
Nub
Publication 1756-PM010C-EN-P - October 2009 79
Using Add-On Instructions Chapter 3
The instruction expects arguments for required parameters as
listed in the instruction tooltip.
Tips for Using an Add-On
Instruction
This table describes programming tips for you to reference when
using Add-On Instructions.
Programmatically Access a
Parameter
Follow these procedures for any language when you want to access a
an Add-On Instruction parameter that isn't available on the instruction
face by default.
TIP
For help with an instruction, select the instruction and then
press F1. In Structured Text, make sure the cursor is in the
blue instruction name.
Structured Text
Topic Description
Instruction Help Use the instruction help to determine how to use the instruction in
your code.
Ladder Rungs In a ladder rung, consider if the instruction should be executed on a
false rung condition. It may improve scan time to not execute it.
Data Types A data type defined with the Add-On Instruction is used for the tag
that provides context for the execution from your code. A tag must
be defined of this Add-On Instruction-defined type on the call to the
instruction.
Indexed Tag You can use an indirect array indexed tag for the Instruction
instance. One drawback is that you cannot monitor the Add-On
Instruction by using this as a data context.
Passing Data Input and Output parameters are passed by value.
InOut parameters are passed by reference.
80 Publication 1756-PM010C-EN-P - October 2009
Chapter 3 Using Add-On Instructions
The following procedures demonstrate how to use the Jog parameter
of the Motor Starter Add-On Instructions.
Using the Jog Command in Ladder Diagram
The first rung sets the Jog bit of Motor_Starter_LD = Jog_PB.
Motor_Starter_LD . Jog
Motor_Starter tag
dot
Jog Parameter
Use another instruction, an assignment, or an expression to read or write to the tag name
of the parameter. Use this format for the tag name of the parameter.
Add_On_Tag.Parameter
Where Is
Add_On_Tag An instance tag defined by the Add On data type.
Parameter Name of the parameter.
Publication 1756-PM010C-EN-P - October 2009 81
Using Add-On Instructions Chapter 3
Using the Jog Command In Function Block Diagram
Any parameter can be made visible or invisible except those defined
as required. Required parameters are always visible. If the parameter
is required, you will see it checked in the Properties dialog box.
1. Click Properties for the instruction.
2. Check the Vis checkbox of the Jog parameter to use it in your
diagram.
3. Click OK.
4. Wire to the pin for the parameter.
82 Publication 1756-PM010C-EN-P - October 2009
Chapter 3 Using Add-On Instructions
Using the Jog Command in Structured Text
Monitor the Value of a
Parameter
Follow this procedure when you want to see or change a parameter
value of an Add-On Instruction.
1. Open the Properties of the instruction based on what language
you are using.
a. For either a Function Block or Ladder Diagram, click
Properties for the instruction.
b. For Structured Text, right-click the instruction name and
choose Properties.
Motor_Starter_ST.Jog := Jog_PB;
Motor_Starter(Motor_Starter_ST, Stop_PB, Start_PB, Motor_Out_ST);
The assignment sets the Jog bit of
Motor_Starter_ST = Jog_PB.
Motor_Starter_ST . Jog
Motor_Starter tag
dot
Jog Parameter
Motor_Starter(Motor_Starter_ST,
Stop_PB,Start_PB,Motor_Out_ST);
Publication 1756-PM010C-EN-P - October 2009 83
Using Add-On Instructions Chapter 3
2. Monitor the value of the parameters and change any if needed.
3. Type a new value for each parameter as needed.
4. Click Apply and when finished, OK.
View Logic and Monitor
with Data Context
Follow this procedure when you want to view the logic of an Add-On
Instruction and monitor data values with the logic.
1. Right-click the instruction call in any routine.
Motor_Starter(Motor_Starter_ST,St
op_PB,Start_PB,Motor_Out_ST);
84 Publication 1756-PM010C-EN-P - October 2009
Chapter 3 Using Add-On Instructions
2. Choose Open Instruction Logic.
The Language Editor opens with the Add-On Instruction's logic
routine and with data values from the instruction call.
As you view the logic you can:
identify the instruction call whose tags are being used for data.
see the logic as it executes (when online).
see Parameter and Local Tag values.
change local tag and parameter values for the data instance
selected.
Data Context identifies the instruction call
(by its instance tag) being used for data.
See Parameters and Local
Tag values.
Change Local Tag and Parameter
values for that data context.
Publication 1756-PM010C-EN-P - October 2009 85
Using Add-On Instructions Chapter 3
To edit the logic of the Add-On Instruction, you must select the
instruction <definition> in Data Context.
You can't edit the instruction logic:
online.
when the logic is in the context of an instruction call.
if the instruction is source-protected.
if the instruction is sealed with an instruction signature.
Determine if the Add-On
Instruction is Source
Protected
An Add-On Instruction may be source protected so you cannot view
the logic. Follow these steps to see if an Add-On Instruction is source
protected.
1. Select the Add-On Instruction in the Controller Organizer.
The Add-On Instruction cannot be expanded when fully
protected.
2. Look in the Quick View pane for Source Protection.
If the Source Protection attribute isnt listed, then the instruction
isnt protected.
86 Publication 1756-PM010C-EN-P - October 2009
Chapter 3 Using Add-On Instructions
Copy an Add-On Instruction
You can copy an Add-On Instruction into your project when it exists
in another RSLogix 5000 project. After you copy the Add-On
Instruction, you can use the instruction as is or rename it, modify it,
and then use it in your programs.
Follow these steps to copy the Add-On Instruction.
1. Open the RSLogix 5000 project that contains the Add-On
Instruction.
2. Find the instruction in the Add-On Instructions folder.
3. Right-click the instruction and choose Copy.
IMPORTANT
Use caution when copying and pasting components between
different versions of RSLogix 5000 programming software.
RSLogix 5000 software only supports pasting to the same
version or newer version of RSLogix 5000 software. Pasting to
an earlier version of RSLogix 5000 software is not supported.
When pasting to an earlier version, the paste action may
succeed, but the results may not be as expected.
TIP
When copying and pasting Add-On Instructions, consider these
guidelines:
You cannot paste a safety Add-On Instruction into a
standard routine.
You cannot paste a safety Add-On Instruction into a safety
project that has been safety-locked or one that has a safety
task signature.
You cannot copy and paste a safety Add-On Instruction
while online.
Publication 1756-PM010C-EN-P - October 2009 87
Using Add-On Instructions Chapter 3
4. Go to the other project where you want to paste the instruction.
5. Right-click the Add-On Instructions folder and choose Paste.
Store Your Add-On
Instructions
There are two ways to store a group of Add-On Instructions together.
One is to save your Add-On Instructions in a project file. Another is to
create an L5X export file, as described in Chapter 4.
Follow these steps to store your instructions by saving them in a
project file.
1. Identify what instructions you want to store.
2. Place them in a project file called something like
MyInstructions.ACD.
3. Open other projects in additional instances of RSLogix 5000
software and use copy and paste or drag and drop to move a
copy of the instruction from MyInstructions.ACD to another
project.
If any of these instructions reference the same Add-On Instruction or
User-Defined Data Type, there is only one shared copy in the project
file. When an Add-On Instruction is copied to another project, it also
copies any instruction it references to the target project.
88 Publication 1756-PM010C-EN-P - October 2009
Chapter 3 Using Add-On Instructions
Notes:
89Publication 1756-PM010C-EN-P - October 2009 89
Chapter 4
Import and Export Add-On Instructions
Introduction
Creating an Export File
When you choose to export an Add-On Instruction, the exported
Add-On Instruction includes all of its parameters, local tags, and
routines. These will be imported with the Add-On Instruction
automatically.
Optionally, you can include any nested Add-On Instructions or
User-Defined Data Types that are referenced by the exported Add-On
Instruction. Referenced Add-On Instructions and data types are
exported to the L5X file if you check Include all referenced Add-On
Instructions and User-Defined Types during the export.
Add-On Instruction definition references may also be exported when
a program, routine, set of rungs, or User-Defined Data Type is
exported.
In deciding how to manage your Add-On Instruction definitions in
export files, you need to consider your goals in storing the definitions.
Topic Page
Creating an Export File 89
Importing an Add-On Instruction 92
Update an Add-On Instruction to a Newer Revision via Import 95
TIP
If an Add-On Instruction uses Message (MSG) instruction and
InOut parameters of type MESSAGE, you may wish to export a
rung containing the Add-On Instruction to include the MESSAGE
tags. This captures the message configuration data, such as type
and path.
If Then
You want to store many Add-On Instructions that share a set of
common Add-On Instructions or User-Defined Data Types in a
common location
Export to separate
files as described on
page 90.
You want to distribute an Add-On Instruction as one file
Export to a single file
as described on page
91.
You want to manage each Add-On Instruction as a standalone
instruction
You want to preserve the instruction signature on your Add-On
Instruction
TIP
Add-On Instructions with instruction signatures are encrypted
upon export to prevent modifications to the export file.
90 Publication 1756-PM010C-EN-P - October 2009
Chapter 4 Import and Export Add-On Instructions
Export to Separate Files
If you want to store many Add-On Instructions that share a set of
common Add-On Instructions or User-Defined Data Types in a
common location, you may want to choose to export each Add-On
Instruction and User-Defined Data Types to separate files without
including references.
Follow these steps to export to separate files.
1. Right-click the Add-On Instruction in the Controller Organizer,
and choose Export Add-On Instruction.
2. Select the common location to store the L5X file.
3. Type a name for the file.
4. Clear Include referenced Add-On Instructions and User-Defined
Types.
5. Click Export.
6. Follow the above steps to individually export the other shared
Add-On Instructions and User-Defined Data Types.
Using export in this way lets you manage the shared Add-On
Instruction and User-Defined Data Types independently of the
Add-On Instructions that reference them. One advantage of this is the
ability to update the shared component without having to regenerate
all the export files for the instructions that reference it. That is, it is
only stored in one file instead of in every file whose instruction
references it. This can help with the maintenance of the instructions as
you only have to update one export file.
Publication 1756-PM010C-EN-P - October 2009 91
Import and Export Add-On Instructions Chapter 4
To use Add-On Instructions that have been exported in a separate file,
without references, you must first import any User-Defined Data
Types of Add-On Instructions that the exported instruction references
before the import of the referencing instruction can be successful. To
do this, work from the bottom up. Import the lowest-level
User-Defined Data Types and any User-Defined Data Types that
reference them. Then, import the lowest-level Add-On Instructions,
followed by any Add-On Instructions that reference those low-level
Add-On Instructions. Once all of the items it references are in place,
the import of the Add-On Instruction will succeed.
Export to a Single File
If you manage each Add-On Instruction as a standalone, you may
want to export the instruction and any referenced Add-On Instructions
or User-Defined Data Types into one export file. By including any
referenced Add-On Instructions or User-Defined Data Types, you also
make it easier to preserve the instruction signature of an Add-On
Instruction.
Follow these steps to export to a single file and include any
referenced items.
1. Right-click Add-On Instruction in Controller Organizer and
choose Export Add-On Instruction.
2. Choose the location to store the L5X file.
92 Publication 1756-PM010C-EN-P - October 2009
Chapter 4 Import and Export Add-On Instructions
3. Type a name for the file.
4. Check Include referenced Add-On Instructions and
User-Defined Types.
5. Click Export.
This exports the selected Add-On Instruction and all the referenced
instructions into the same export file. This file can be used to
distribute an Add-On Instruction. When the exported Add-On
Instruction is imported into the project, the referenced instructions are
imported as well in one step.
Importing an Add-On
Instruction
You can import an Add-On Instruction that was exported from
another RSLogix 5000 project. When importing an Add-On Instruction,
the parameters, local tags, and routines are imported as part of the
Add-On Instruction. Once the project has the Add-On Instruction, you
can use it in your programs.
Import Considerations
ATTENTION
Editing an L5K or L5X File
The EditedDate attribute of an Add-On Instruction must be
updated if the Add-On Instruction is modified by editing an L5K
or L5X file. If RSLogix 5000 software detects edits to the
Add-On Instruction, but the Edited Date attribute is the same,
the Add-On Instruction will not be imported.
Publication 1756-PM010C-EN-P - October 2009 93
Import and Export Add-On Instructions Chapter 4
When importing Add-On Instructions directly or as references,
consider these guidelines.
Considerations when Importing an Add-On Instruction
Topic Consideration
Tag Data Imported tags that reference an Add-On Instruction in the import file may be affected if the Add-On
Instruction is not imported as well. In this case, the imported tags data may be converted if the existing
Add-On Instructions data structure is different and tag data may be lost.
If an existing Add-On Instruction is overwritten, project tag data may be converted if the Add-On Instructions
data structure is different and tag data may be lost.
See Import Configuration on page 94 for more information.
Logic Imported logic that references the Add-On Instruction in the import file may be affected if the Add-On
Instruction is not imported. If an existing Add-On Instruction is used for the imported logic reference and the
parameter list of the Add-On Instruction in the project is different, the project may not verify or it may verify
but not work as expected.
If an existing Add-On Instruction is overwritten, logic in the project that references the Add-On Instruction
may be affected. The project may not verify or may verify but not work as expected.
See Import Configuration on page 94 for more information.
Add-On Instructions While
Online
An Add-On Instruction cannot be overwritten during import while online with the controller, though a new
Add-On Instruction may be created while online.
Final Name Change If the Final Name of an Add-On Instruction is modified during import configuration, the edit date of the
imported Add-On Instruction will be updated. In addition, all logic, tags, User-Defined Data Types, and other
Add-On Instructions in the import file that reference the Add-On Instruction will be updated to reference the
new name. As a result, the edit date of any Add-On Instruction that references the Add-On Instruction will be
updated.
Add-On Instructions that have been sealed with an instruction signature cannot be renamed during import.
User-Defined Data Types Add-On Instructions cannot overwrite User-Defined Data Types. Add-On Instructions and User-Defined Data
Types must have unique names.
Instruction Signature If you import an Add-On Instruction with an instruction signature into a project where referenced Add-On
Instructions or User-Defined Data Types are not available, you may need to remove the signature.
You can overwrite an Add-On Instruction that has an instruction signature by importing a different Add-On
Instruction with the same name into an existing routine. Add-On Instructions that have been sealed with an
instruction signature cannot be renamed during import.
Safety Add-On
Instructions
You cannot import a safety Add-On Instruction into a standard task.
You cannot import a safety Add-On Instruction into a safety project that has been safety-locked or one that
has a safety task signature.
You cannot import a safety Add-On Instruction while online.
Class, instruction signature, signature history, and safety instruction signature, if it exists, remain intact when
an Add-On Instruction with an instruction signature is imported.
IMPORTANT
Importing an Add-On Instruction created in version 18 or later of RSLogix 5000 software into an older
project that does not support Add-On Instruction signatures causes the Add-On Instruction to lose attribute
data and the instruction may no longer verify.
94 Publication 1756-PM010C-EN-P - October 2009
Chapter 4 Import and Export Add-On Instructions
Import Configuration
When you select a file to import, the Import Configuration dialog box
lets you choose how the Add-On Instruction and referenced
components are imported.
If there are no issues, you can simply click OK to complete the
import.
If your Add-On Instruction collides with one already in the project,
you can:
rename it, by typing a new, unique name in the Final Name
field.
choose Overwrite from the Operation pull-down menu.
choose Use Existing from the Operation pull-down menu.
The Collision Details button lets you view the Property Compare tab,
which shows the differences between the two instructions, and the
Project References tab, which shows where the existing Add-On
Instruction is used.
The component collides with a
definition already in the project.
Click Add-On Instructions to
see the Configure Add-On
Instruction References view.
If any referenced instruction
definitions collide, the
References folder is flagged.
TIP
You can only rename an Add-On Instruction if it has not
been sealed with an instruction signature.
To rename an Add-On Instruction that has been
source-protected, you need the source key.
Publication 1756-PM010C-EN-P - October 2009 95
Import and Export Add-On Instructions Chapter 4
Update an Add-On
Instruction to a Newer
Revision via Import
When you need to update an instruction to a newer revision, you can
import it from an L5X file or copy it from an existing project. You
must be offline to update an Add-On Instruction.
Follow these steps to update an Add-On Instruction to a newer
revision by importing it.
1. Right-click the Add-On Instruction folder and choose Import
Add-On Instruction.
2. Select the file with the Add-On Instruction and click Import.
96 Publication 1756-PM010C-EN-P - October 2009
Chapter 4 Import and Export Add-On Instructions
3. Review the Import Configuration dialog box, and from the
Operations pull-down menu, choose Overwrite.
4. Click Collision Details to see any differences in the Add-On
Instructions and to view where the Add-On Instruction is used.
The Property Compare tab shows the differences between the
instructions, in this case, the Revision, Edited Date, and Software
Revision.
Choose Overwrite.
Publication 1756-PM010C-EN-P - October 2009 97
Import and Export Add-On Instructions Chapter 4
The Project References tab shows where the existing Add-On
Instruction is used.
For more information on updates to arguments, see Updates to
Arguments Following Parameter Edits on page 41.
5. Click Close and then OK to complete the operation.
TIP
The Compare dialog box only compares metadata for
each instruction definition, such as description, revision,
or edited date. For effective revision control, enter a
detailed revision note.
IMPORTANT
Check each routine where your Add-On Instruction is
used to make sure that your existing program code will
work correctly with the new version of the instruction.
98 Publication 1756-PM010C-EN-P - October 2009
Chapter 4 Import and Export Add-On Instructions
Notes:
Publication 1756-PM010C-EN-P - October 2009 99
Index
A
access
Add-On Instructions 75
Add Element dialog box 76
Add-On Instruction Definition Editor 37
alias
parameter 28, 38
array 28
C
Change History tab 17
changing class 54
class 13
changing 54
collision
import 94, 96
compare instructions 96
constant value tags 31
copy
Add-On Instruction 86
default values 43
instruction signature 60
safety Add-On Instruction 86
safety instruction signature 61
signature history 61
Copy Default Values dialog box 44
create
Add-On Instruction 35
alias parameter 38
EnableInFalse routine 51
instruction help 64
instruction signature 60
local tags 39
logic 44
parameters 37
postscan routine 50
prescan routine 48
signature history 61
D
data access 24
data access control 31
data context views 55
data types
alias 28
parameters 27, 37
size 22
tags 40
default values 38, 40
copy 43
delete
safety instruction signature 62
E
Edit Tags tab 41
EnableIn parameter 52
Function Block Diagram 53
ladder diagram 53
structured text 53
EnableInFalse routine 51
create 51
EnableOut parameter 52
export 89-92
external access 31
F
Function Block Diagram
instruction example 78
G
General tab 13
generate
instruction signature 60
GSV 26
H
help
create 64
example 66
Help tab 18
I
import 92-97
Import Configuration dialog box 96
instruction
size 22
toolbar 75
instruction signature
changing 20
copy 60
definition 16
generate 60
language switching 20, 67
remove 60
restricted actions 16, 20
source protection 20
100 Publication 1756-PM010C-EN-P - October 2009
Index
L
Ladder Diagram
instruction example 78
language switching 67
instruction signature 20
Last Edit Date 61
local tags
create 39
external access 41
planning 33
Local Tags tab 14
create tags 40
logic 44
execution 45
M
monitor
data values 83
parameter values 82
move
parameter 39
N
naming conventions 32, 36
nesting 22
data access 24
planning 33
O
object classes 26
P
parameter
alignment 41-42
parameters
alias 28
create 37
EnableIn 52
EnableOut 52
monitor 82
move 39
planning 32
reorder 39
required 29
visible 29, 30
Parameters tab 14
create a parameter 37
passing arguments 27
performance 45
planning 32
postscan routine 49
create 50
prescan routine 47
create 48
programming language
choosing 21
planning 33
programming tips 79
Project References tab 97
Property Compare tab 96
R
remove
instruction signature 60
reorder parameters 39
required parameters 29
routine
EnableInFalse 51
postscan 49
prescan 47
S
safety
class 13
restrictions 19
tags 30
safety Add-On Instruction
copy 86
import 93
safety application instructions
restrictions 25
safety instruction signature 17, 21
copy 61
create 62
delete 62
invalid 62
view 63
safety task signature 19, 54, 86, 93
additional resources 9
Scan Mode tab 16
scan modes 45-52
planning 34
verify 56
Scan Modes tab 47
SFC Action 49
signature history 17, 61
Signature tab 16
SIL 3 21
Publication 1756-PM010C-EN-P - October 2009 101
Index
source protection
applying 57-59
enabling 57
instruction signature 20
operation 60
options 57
planning 33
Quick View pane 85
SSV 26
standard
class 13
tags 30
store your instructions 87
Structured Text
instruction example 79
T
tags
create local tags 39
standard and safety 30
test 54
planning 34
transitional instructions 21
translation
See language switching.
U
unavailable instructions 25
update Add-On Instruction revision 95
V
visible
parameters 29, 30
102 Publication 1756-PM010C-EN-P - October 2009
Index
Publication 1756-PM010C-EN-P - October 2009 104
Supersedes Publication 1756-PM010B-EN-P - July 2008 Copyright 2009 Rockwell Automation, Inc. All rights reserved. Printed in the U.S.A.
Rockwell Automation Support
Rockwell Automation provides technical information on the Web to assist you in using its products. At
http://www.rockwellautomation.com/support/, you can find technical manuals, a knowledge base of FAQs, technical and
application notes, sample code and links to software service packs, and a MySupport feature that you can customize to make the
best use of these tools.
For an additional level of technical phone support for installation, configuration, and troubleshooting, we offer TechConnect
support programs. For more information, contact your local distributor or Rockwell Automation representative, or visit
http://www.rockwellautomation.com/support/.
Installation Assistance
If you experience an anomoly within the first 24 hours of installation, review the information that's contained in this manual.
You can contact Customer Support for initial help in getting your product up and running.
New Product Satisfaction Return
Rockwell Automation tests all of its products to ensure that they are fully operational when shipped from the manufacturing
facility. However, if your product is not functioning and needs to be returned, follow these procedures.
Documentation Feedback
Your comments will help us serve your documentation needs better. If you have any suggestions on how to improve this
document, complete this form, publication RA-DU002, available at http://www.rockwellautomation.com/literature/.
United States or Canada 1.440.646.3434
Outside United States or
Canada
Use the Worldwide Locator at http://www.rockwellautomation.com/support/americas/phone_en.html,
or contact your local Rockwell Automation representative.
United States Contact your distributor. You must provide a Customer Support case number (call the phone number
above to obtain one) to your distributor to complete the return process.
Outside United States Please contact your local Rockwell Automation representative for the return procedure.