 Using the dictionary editor

The ISaGRAF dictionary is an editing tool for the declaration of the internal variables, I/O variables, function block instances, and "defined words" of the application. The dictionary groups together the declared variables and function block instances of the application, and the words defined as constant strings.

Basics

The dictionary main window

Managing variables

Description of objects

Quick declaration

Modbus SCADA addressing map

Exchanging information with other applications

Link to other ISaGRAF tools

Setting individual protections


Basics

Variables, function blocks and defined words must be declared in the dictionary before using them in source code. Variables and defined words can be used with any of the automation languages: SFC, FBD, LD, ST and IL. Function blocks used in FBD language do not have to be declared, because the ISaGRAF FBD and Quick LD editors automatically declare the instances of the used blocks.

Variables

Defined words

Function block instances

Network addresses


Variables

The variables are sorted according to their range and type. Only variables of the same type and the same range can be entered on the same input grid. These are basic ranges for variables:

 GLOBAL	can be used by any program of the current project

 LOCAL	can be used by only one program

These are basic types of variables:

 BOOLEAN	true/false binary values

 ANALOG	real or integer values

 TIMER	time values

 MESSAGE	character strings

A variable is identified by a name, a comment, an attribute, a network address and other specific fields. Here are the basic variable attributes:

INTERNAL	memory variable

INPUT	variable linked to an input device

OUTPUT	variable linked to an output device

CONSTANT	read only internal variable (with initial value)

Note:	Timers are always internal variables. Input and Output variables always have the GLOBAL range.


Defined words

A defined word is an alias that can be used in any language to replace a text string. The replaced text can be a variable name, a constant expression or a complex expression. Defined words are sorted according to their range. Only defined words of the same type and the same range can be entered on the same input grid. Here are basic ranges:

 COMMON	can be used by any program of any project

 GLOBAL	can be used by any program of the current project

 LOCAL	can be used by only one program

A defined word is identified by a name, a well defined block of ST text equivalence and a free comment.


Function block instances

The instances of the function blocks used in the ST and IL languages must be declared in the dictionary. Because a function block has internal "hidden" data, each copy of a function block must be identified. The following example shows the function block "R_TRIG" (rising edge detection) defined in the library, used for edge detection on different variables. Each copy of the block must be identified by a unique name. Naming the type of block and definition of its parameters is made by using the library manager:

Block name:	R_TRIG

Parameters:	Input=CLK

Output=Q

Naming the instances is made by using the dictionary editor:

Instance name:	TRIG_B1	Block name:	R_TRIG

Instance name:	TRIG_B2	Block name:	R_TRIG

The declared instances may be used in ST programs:

TRIG_B1 (b1);

edge_b1 := TRIG_B1.Q;	(* b1 variable edge detection *)

TRIG_B2 (b2);

edge_b2 := TRIG_B2.Q;	(* b2 variable edge detection *)

Declared function block instances may be GLOBAL (known by any program in the project), or LOCAL to one program. Function blocks used in FBD or LD languages do not have to be declared, because the ISaGRAF FBD editor automatically declares the instances of the used blocks.

(* the function blocks always have the name of the block defined in the library. The ISaGRAF FBD and Quick LD editors automatically declare an instance each time a block is inserted in the diagram *)

Function block instances automatically declared by the FBD and Quick LD editors are always LOCAL to the edited program.


Network addresses

Network addresses are optional. A variable with a non-zero network address can be spied by an external system (for example a process visualization system) at run time. More generally, the network address provides an identifying mechanism for each run time communication system that cannot handle symbolic names. A network address may be entered for each variable, during its complete description, when the variable is created or modified.


The dictionary main window

The dictionary editing window shows a list of variables with same type and range. The type and range of edited variables is always displayed in the title bar.

The editing window shows only main fields of variable description: name, attribute and network address, and text comment. The full description of the selected variable is always displayed in the status bar.

Use the following buttons in the toolbar to select the range of variable to be edited:

COMMON	can be used by any program of any project

GLOBAL	can be used by any program of the current project

LOCAL	can be used by only one program

Use the "Tab" control displayed with title bar to select the type of object to be edited:

Use the text input field on the left of the toolbar to search for a variable prefix name. In this case, research is processed on the entire list, from the beginning, based on the current selection. The "Edit / Find" command is also available to search a text string in variable names and comments, and to move the selection to this variable. Search is always case insensitive.


Managing variables

The available "Files" menu commands work on the entire selected class of variables, function block instances or defined words. Use the "Other" command to select the type and range of objects to be edited.

Printing variables

Creating new variables

Modifying existing variables

 	Cut and paste

Sorting variables

Setting network addresses

Importing boolean "true/false" strings


Printing variables

Use the "Files / Print" command to print the currently edited list of variables or defined words, on a standard Windows™ printer device. Printing is made using the ISaGRAF document generator. The printout includes the complete description of each variable or defined word of the currently edited type.


Creating new variables

The "Edit / New" command allows the user to create new variables, function block instances or defined words for the selected range and type. New variables are inserted just before the variable currently pointed to by the selection bar. When this command is run, an input box is opened to enter the variable description. When the description is complete, pressing the "Store" button puts it onto the list. The input box is automatically re-opened, so the user can enter other variables with the same "Edit" command. Pressing the "Cancel" button of the dialog box breaks the variable creation process.


Modifying existing variables

The "Edit" command of the "Edit" menu allows the user to modify the description of the variable currently pointed at by the selection bar. When this command is run, an input box is opened to modify the variable description. When description is complete, pressing the "Store" button enables modification. The user also can press "Next" and "Previous" buttons to extend the modification command to adjoining variables. Pressing the "Cancel" button closes the dialog box without storing any modification.


 	Cut and paste

The ISaGRAF dictionary editing tool enables multiple-line selection. Many commands are available to work on the currently edited list of variables. Below are available "Edit" menu commands:

COPY	Copy the selected group of variables to the dictionary clipboard

CUT	Copy the selected group of variables and remove it from the edited list

CLEAR	Remove the selected group of variables from the edited list

PASTE	Insert the dictionary clipboard before the selected variable

Copy/Cut/Paste functions can be used from one list of variables to another. They cannot be used between list of different object types.


Sorting variables

The "Tools / Sort" command sorts the variables or defined words of the currently edited list. The sorting order is given by the attributes of the variables:

•	first the internal variables

•	then the input variables

•	finally the output variables

Variables with the same attribute are sorted into alphabetical order. Defined words are always sorted into alphabetical order.


Setting network addresses

Network addresses are optional. A variable with a non-zero network address can be spied by an external system (for example a process visualization system) at run time. A network address may be entered for each variable, during its complete description, when the variable is created or modified. The "Tools / Renumber addresses" command allows the user to set up network addresses of an entire group of variables. When this command is run, it acts on the group of variables currently selected on the list. Entering a hexadecimal basis address (address for the first variable of the group) results in network addresses of the variables of the group being set with consecutive addresses. Entering a null basis address resets to zero the network address of all the selected variables.


Importing boolean "true/false" strings

When editing defined words, the "Tools / Import true/false definitions" allows the user to automatically define as language keywords the strings attached to boolean variables to represent TRUE and FALSE states. Such strings are normally defined for debug formatting. They have to be specified as defined words if they are to be used in programs. This command searches for boolean true/false strings in the declarations with the same range as the one currently selected for the editing of the defined words.


Description of objects

A complete description must be entered for each variable, function block instance, or defined word. Description fields are different for each type of object. The following fields are common for any type of variables:

Name	Name of the variable: first character must be a letter, following characters must be letters, digits or '_'.

Network address	Hexadecimal network address (optional). When this field is non-zero, the variable can be spied by external systems at run time.

Comment	Free comment for variable description.

Retain	This option indicates that the variable must be saved on backup memory.

These are other description fields for a boolean variable:

Attribute	Specifies an internal, constant, input or output variable.

"False" string	String used for false value at debug time.

"True" string	String used for true value at debug time.

Set to true at init	The initial value is TRUE if this option is checked, otherwise the initial value is FALSE.

These are other description fields for an integer or real variable:

Attribute	Specifies an internal, constant, input or output variable.

Format	Specifies an integer or real (floating) variable. Display format used during debug can be selected.

Unit string	String used to identify the physical unit at debug time.

Conversion	Name of the conversion table or conversion function attached to the variable (for input or output variables only)

Initial value	Initial value of the variable (must have the same format as the variable). If not specified, the initial value is 0.

These are other description fields for a timer variable:

Attribute	Specifies an internal or constant variable.

Initial value	Initial value of the variable (time value).  If not specified, the initial value is time#0s.

These are other description fields for a message variable:

Attribute	Specifies an internal, constant, input or output variable.

Maximum Length	Specifies the maximum number of characters that can be stored in the message.

Initial value	Initial value of the variable (length cannot exceed the capacity of the message).  If not specified, the initial value is the empty string.

These are the description fields for a defined word:

Name	Name used in ST source files: first character must be a letter, following characters must be letters, digits or '_'.

Define	String according to ST syntax, that replaces the defined word during compiling. Example: Name = PI - Equivalence = 3.14159

Comment	Free comment for defined equivalence

These are the description fields for a function block instance:

Name	Name of the instance, used in ST source files: first character must be a letter, following characters must be letters, digits or '_'.

Type	Name of the corresponding function block in the library.

Comment	Free comment for the function block instance.


Exchanging information with other applications

The ISaGRAF dictionary editing tool offers import/export functions in order to exchange information with other applications, such as word processors, spreadsheets, data base managers... These commands are grouped in the "Tools" menu. The "Export text" command builds a pure ASCII text description of the fields describing a set of edited objects, and stores this text either in the Windows clipboard or in a file. Such information is typically used by another application. The "Import text" command imports variable declaration description fields, described in pure ASCII text format, stored either in the Windows clipboard or in a file, and updates the currently edited list with imported fields. Such information is typically produced by another application.

Exporting data

Importing data

Available text formats

Keywords


Exporting data

The "Export" dialog box appears when the "Export text" command is run. It enables the user to control the export mechanism.

Checking the "Complete list" choice indicates that the complete edited list has to be exported. The current selection is ignored in this case. Checking the "Selected variables" choice indicates that only highlighted variables will be exported.

If the "Clipboard" option is checked, the exported information is stored, in pure ASCII text format, in the Windows clipboard. The text is then available for "paste" commands in other applications. If the "File" option is checked, the exported text is stored in an ASCII file. The complete pathname of this file has to be entered. The "Browse" command may be used to find an existing pathname.

Then the user chooses a format for the exported text. The available formats are described in further sections. Pressing the "OK" button runs the export function. Pressing the "Cancel" button closes the dialog box and escapes from the export command.

All the fields of the selected objects are stored in the exported text, in the standard declaration order. The first line of the exported text contains the name of the fields. Each object is described on one line of text. The "end of line" separator is the standard MS-DOS sequence "0d-0a". The names used to identify the fields in the first exported line may be changed, by pressing the "Keyword" button. This command is described in further sections.


Importing data

The "Import" dialog box appears when the "Import text" command is run. It enables the user to control the import mechanism.

If the "Clipboard" option is checked, the imported information is taken from the Windows clipboard, in pure ASCII text format. If the "File" option is checked, the exported text is read in an ASCII file. The complete pathname of this file has to be entered. The "Browse" command may be used to find an existing pathname.

The import function automatically recognizes the format (separators) used in the imported text. The available formats are described in further sections. Pressing the "OK" button runs the import function. Pressing the "Cancel" button closes the dialog box and escapes from the import command. The names used to identify the fields in the first imported line may be changed, by pressing the "Keyword" button. This command is described in further sections.

The first line of the text must contain the name of the fields, according to the order used in the following lines. Each object must be described on one line of text. The "end of line" separator is the standard MS-DOS sequence "0d-0a". Fields can appear in any order. If some fields are missing, they are automatically filled in the imported object description by default values. If an imported object already exists in the edited list, the user has to confirm that it will be overwritten. The object description is then updated with imported fields. If some fields are missing, they are not updated in the object description.


Available text formats

Below is the list of available formats for export command. The import command automatically recognizes these formats.

•	tab separators

Description:	Fields are separated by tab characters.

Example:	Name	Attribute	Comment

level	internal	internal calculated water level

alrm1	output	main alarm output

•	comma separators

Description:	Fields are separated by commas.

Example:	Name,Attribute,Comment

level,internal,internal calculated water level

alrm1,output,main alarm output

•	semicolon separators

Description:	Fields are separated by semicolons.

Example:	Name;Attribute;Comment

level;internal;internal calculated water level

alrm1;output;main alarm output

•	commas and quotes

Description:	Fields are separated by commas.

Each field is written between quotes.

Example:	"Name","Attribute","Comment"

"level","internal","internal calculated water level"

"alrm1","output","main alarm output"


Keywords

The names used to identify the fields in the first imported or exported line may be changed, by pressing the "Keyword" button. The window shows the list of object fields, and the associated keywords. To modify a keyword, the user must select a field in the list and press the "Modify" button. Pressing the "Default" button restores the original list of keywords. Naming the keywords must conform to the following rules:

•	the name cannot exceed 16 characters

•	the first character must be a letter

•	the following characters can be letters, digits or '_' character

•	the same name cannot be used for different keywords

Below are the standard keywords found in ISaGRAF:

Object name	Name

Text comment	Comment

Network address	Address

Attributes (internal, input, output)	Attribute

Boolean 'False' string	False

Boolean 'True' string	True

Analog format (real or integer)	Format

Analog unit string	Unit

Analog conversion name	Conversion

Message maximum length	MaxLength

Function block library type	Library

Defined word equivalence	Equivalence

Internal attribute	Internal

Input attribute	Input

Output attribute	Output

Constant attribute	Constant

Real analog format	Real

Integer analog format	Integer


Link to other ISaGRAF tools

The "Tools" menu contains commands to run other useful ISaGRAF tools for variable management:

The "I/O connection" command enables the user to run the ISaGRAF I/O connection editor for the open project. If the I/O variable currently selected in the Dictionary editing window is already connected, the corresponding I/O board is displayed when the I/O connection window is opened.

The "Conversion tables" command runs the Conversion Table editor in a dialog box. Tables can be assigned to real or integer I/O variables in the dictionary.

The "cross references" command runs the Cross Reference editor for the open project.


Quick declaration

The "Tools / Quick declaration" command enables you to declare several variables at the same time. Variables created by quick declaration are named using a numbering convention. For that, you have to define:

- the index (number) of the first and the last variables,

- the text to be added before and after the number in variable symbols

- the number of digits used to express the number in variable symbols.

Additionally, you can spcify basic attributes of created variables (internal, input or output...), plus some properties depending on the variable type ("Retain" attribute, integer or real format, message string maximum length).

You always need to define a text to be inserted before variable number, as a variable symbol cannot start with a digit. When the "number of digits" is set to "Auto", ISaGRAF formats the variable number on the minimum needed number of digits. When number of digits is specified, ISaGRAF formats all numbers to the specified length by adding leading '0' characters. Setting a fixed number of digits for variable numbers can be very useful to prevent bad lexicographic sorting. Below are some example.

Example 1: This setting for quick declaration:

will create the three following variables:

Var9xx      Var10xx      Var11xx

Example 2: This setting for quick declaration:

will create 100 variables with names from MyVar001 to MyVar100


Modbus SCADA addressing map

ISaGRAF "network addresses" are often used to establish a link between ISaGRAF system and a SCADA based on Modbus communication. In that case, the SCADA is a Modbus master and ISaGRAF target acts as a Modbus slave. Network addresses are used to create a virtual Modbus map for all ISaGRAF variables that must be controlled from the SCADA. The "Tools / Modbus SCADA addressing map" is a powerful to quickly create a Modbus virtual map with variables of the application.

The mapping tools shows two lists. The upper one is a segment (4096 locations) of the Modbus map, showing mapped variables (the ones having a network address). The lower list shows unmapped variables (without network address defined). The "0" address cannot be used to map a variable.

Use the "Map" and "Remove" commands of the "Edit" menu to move a variable from one list to another, and thus build the map. Same actions can be performed by double clicking on a variable symbol in a list, to send it to the other list. At any moment, you can use the "Segment" drop down list to view another segment of the map.

The commands of the "Options" menu can be used at any moment to display addresses either in decimal or in hexadecimal.

The "Edit / Find" commands is used to search for a declared variable, whether it is already mapped or not.


Setting individual protections

The ISaGRAF workbench provides a complete data protection system based on hierarchized passwords. Variable declaration can be globally protected by a password. Additionaly, ISaGRAF enables you to set individual protection to any declared variable. This assumes that:

- passwords are already defined in the password definition system (use the "Project / Set password" command of the Project Management window) so that protection levels are available for individual protection.

- you use protection levels with higher priority for individual protection compared to global variable protection.

When a variable has individual protection, a small icon is draw close to its name in the variable list of Dictionary window:

Use the "Set protection" and "Remove protection" commands of the "Edit" menu to set or remove an individual protection for selected variable. Both commands ask you to enter a valid password so that a protection level can be attached to the variable. Then, each time you want to change a variable having individual protection you must enter a password with sufficient priority level.

Warning: if a variable is protected with a level, and the corresponding password is removed from protection system, and if no higher level password is defined, the variable cannot be changed anymore unless a new password with sufficient level is defined.