 Using the Library Manager

The ISaGRAF libraries provide a standard interface between automation development and the software or hardware capabilities of the ISaGRAF target system. There is one library for each type of interface. The ISaGRAF Workbench Library Manager is dedicated to the hardware supplier, or to the software engineer. He uses the library manager to describe the IsaGRAF programming interface of the objects he creates.

Managing library elements

I/O Configurations

I/O Complex equipments

I/O Boards

Functions and blocks written in IEC languages

"C" Functions and function blocks

Conversion functions

Archiving library elements

The ISaGRAF Workbench Library Manager shows the elements of one of the ISaGRAF libraries. In the left area of the window is the list of the elements of the selected library. In the right area is the technical note (user manual) of the element currently selected on the elements list. The menus of the library manager contain the commands to create, define or modify elements of the active library. The "File / Other library" command allows the selection of one of the ISaGRAF libraries. The combo box on the left of the toolbar can also be used to select a library:


Managing library elements

Use the commands of the "File" menu to create elements and work on existing ones in the open library

Creating a new element

Working on existing elements

Setting password protection

Compiling functions and function blocks

Technical notes

Parameters

Source code


Creating a new element

The "New" command of the "File" menu creates a new element into the selected library. The name of the new element is entered, based on the following naming rules:

•	the maximum length of a name is 8 characters

•	the first character must be a letter

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

•	the naming of a library element is case insensitive.

A text comment is associated to each library element. This comment is entered while creating the element. When a new element is created, the following must be entered:

•	its definition for an I/O configuration,

•	its parameters for an I/O board,

•	its user interface for a function or function block.

When a "C" conversion, "C" function or "C" function block is created, a complete frame of its source code is automatically generated.


Working on existing elements

The "File / Rename" command allows the user to change the name or the comment of the element selected from the list of elements. The "File / Copy" command allows the user to copy the element highlighted in the active library on another element in the same library. If the destination element already exists, all its contents are overwritten. If the destination element does not exist, it is automatically created. The "File / Delete" command removes the currently selected element from the active library. The following components of the element are handled by "Rename", "Copy" and "Delete" commands:

•	technical note

•	complete definition for an I/O configuration

•	parameters for an I/O board or complex equipment

•	interface definition for a function or function block

•	source code for function and function block written in IEC language

•	source code for a C conversion, a function or a function block

if the element is a "C" conversion, "C" function or "C" function block, its name is not automatically updated in the attached source code by a "Rename" or "Copy" command.

if the element is a function written in IEC language, the return parameter name is not changed by a "Rename" or "Copy" command.


Setting password protection

The "File / Set password" command enables the user to define password protection for the selected element in the open library. Refer to the "Password protection" section, at the end of the first part in this manual for further information about password levels and data protection. Passwords are only relative to the selected element. They have no influence on other elements of ISaGRAF libraries.


Compiling functions and function blocks

When the library of functions or function blocks written in IEC languages is selected, the "Verify (compile)" command of the "File" menu is used to check the syntax of the selected element and create its object code. Functions and blocks written in IEC languages have to be compiled without errors before they can be used in ISaGRAF projects. This command has no effect if another library is selected.


Technical notes

The "Edit / Technical note" command allows the user to enter the technical note of the element selected in the active library. The technical note is entered with the ISaGRAF text editor. The technical note of an element is its user guide. It will be consulted by the user of the element during its integration in an ISaGRAF project. The technical note on how to use the element should contain the description of its main function, the detailed explanation of its programming interface and parameters, and its context and limits.

The "Tools / Standard note format" command allows the user to define a standard text format for all the elements of the currently selected library. When editing the technical note for a new element, this format is used as a main frame. This allows the user to optimize technical note editing.


Parameters

The parameters of an element describe the interface between the computer operations provided by the element and the use of the element in an ISaGRAF application. Parameters have a different meaning for each type of library element.

The parameters of an I/O configuration define the complete set of I/O boards of the configuration, and default variable names used for I/O channels. The parameters of an I/O board or complex equipment define the physical and logical configuration of the board. The parameters of a function or function block define the interface of the element, according to ST language function calling conventions. There is no parameter for a conversion function because it uses a standard pre-defined interface.


Source code

The ISaGRAF Workbench allows the programmer to manage the source code of a library conversion, function or function block. The source code of a function or a block written in IEC language is a text or a diagram described with the language attached to the function. The source code of "C" components ("C" functions, "C" function blocks and conversion functions) is divided in two separate files: a source header that contains the exact definition of the interface, according to the element's parameter definition and a source code file that contains the element's operation implementation.

The ISaGRAF workbench generates the source code file when a new library element is created. It also creates and updates the source header, based on the parameters definition. The programmer can use the ISaGRAF text editor to complete the source code file.


I/O Configurations

The ISaGRAF I/O configuration library provides an easy way to initialize new ISaGRAF projects with pre-defined I/O configuration. An I/O configuration defines:

•	a set of I/O boards

•	default values for I/O boards parameters

•	default names for I/O channels

When a new ISaGRAF project is created with a library I/O configuration, the corresponding I/O connection is automatically set, and the I/O variables corresponding to channel names are automatically declared in the project dictionary.

 The definition of an I/O configuration is made with the ISaGRAF I/O Connection tool (the same tool used within a project). Refer to the "I/O Connection" section in this manual for further information about how to use this tool. When inserting a new I/O board in the configuration, all the channels of the new board are declared with standard default names. The standard default name of an I/O channel has the following format:

<direction><type><slot_number>_<channel_number>

The first character indicates the direction of the I/O channel:

"I"	input channel

"Q"	output channel

The second character indicates the type of the I/O channel:

"X"	boolean

"D"	analog

"M"	message

Below are examples of a standard I/O channel names:

IX0_7	boolean input - board #0 - channel #7

QD2_4	integer output - board #2 - channel #4

The "Connect I/O channels" command of the I/O Connection Editor is used to modify the default name attached to an I/O channel.


I/O complex equipments

 All the channels of a single board have the same type (boolean, analog or message) and direction (input or output). A complex I/O equipment represents an I/O device with channels of different types or directions. A complex I/O equipment is represented as a list of single I/O boards. It uses only one slot in the I/O connection rack list.

 To define a complex I/O equipment, the user has to define the list of single boards which define the I/O equipment. He also has to enter the detailed parameters of each single board. The list of single I/O boards is entered through a dialog box.

Pressing the "Append" button allows the user to add a single board at the end of the current list. The "Insert" button is used to insert a new single board before the one currently selected in the list. The "Delete" button removes the selected single board from the list. The "Rename" and "Parameters" button are used to change the name and the parameters of the selected single board. Refer to the following section for a complete explanation of single board parameters. A complex I/O equipment can group up to 16 single I/O boards. The name of a single board (within an I/O equipment) cannot exceed 8 characters.


I/O boards

The ISaGRAF I/O board library defines a standard interface between the application variables and the target hardware. During the description of the application, all the I/O variables are connected to the channels of the target I/O boards. An ISaGRAF I/O board is defined by a name and an "OEM key code" that identifies its supplier. Other I/O board parameters describe the I/O board topology (number of channels, channel direction and type), and its hardware or software configuration.

I/O board parameters

The OEM parameters


I/O board parameters

There are two different types of parameters for an I/O board: common parameters which are defined for any ISaGRAF library board, and OEM parameters which are specific to the board implementation, provided by the hardware supplier. Common parameters are entered in the upper part of the I/O board parameters definition box. These parameters (plus the I/O board name) identify the ISaGRAF standard I/O board interface.

The "OEM key code" is a simple number that defines the hardware supplier. All the boards defined by the same supplier must have the same OEM key code. The OEM key code is a 16 bit unsigned word, entered in an hexadecimal format. The reserved OEM key code for CJ International is "1".

Main parameters define the topology of the I/O board. The number of channels defines the number of available channels on the board. The type of the board is the type of the variables that may be connected on the channels of the board. The direction defines whether variables connected on the board are input or output variables.

Note:	I/O variables of different types or directions cannot be grouped on the same ISaGRAF I/O board. This feature should require a complex I/O equipment.


The OEM parameters

The OEM parameters are entered in the lower part of the I/O board parameters definition box. These parameters are defined by the I/O board hardware supplier and are specific to the board. There are at most 16 OEM parameters for a board. A board may have no OEM parameters. The ISaGRAF library manager allows the hardware supplier to define the identification and the format of each parameter, and the way the automation programmer enters it.

The box on the left contains the list of the OEM parameters. Each parameter is identified by a name and a logical number, from 0 to 15. The area on the right contains the detailed description of the parameter selected on the list. A parameter is selected in the list in order to access to its complete description. Pressing the "Clear" button resets the parameter description, and removes it from the parameters list. Warning: this command cannot be "undone".

The name of a parameter is used to identify the corresponding input field during the I/O board connection if the field must be defined by the automation operator. The name of a parameter must conform to the following rules:

•	the maximum length of a name is 16 characters

•	the first character must be a letter

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

The type of a parameter defines the internal format of the parameter, and its input format during application I/O connection. Below is the list of available internal formats:

word	unsigned 16 bit word

long	unsigned 32 bit word

word hexa	unsigned 16 bit word

long hexa	unsigned 32 bit word

boolean	unsigned 16 bit word (only lowest bit is used)

character	unsigned 16 bit word (only lowest byte is used)

string	array of 16 bytes containing a null-terminated string

float	single precision 32 bit floating value

Below are available input formats:

word	unsigned decimal word

long	decimal long word

word hexa	unsigned hexadecimal word

long hexa	unsigned hexadecimal long word

boolean	"true" or "false"

character	single character

string	ascii string (15 characters max)

float	single precision floating value

The "access" box is used to define how the parameter can be accessed by the end user. If the "User defined" option is set, the parameter is shown as an input field during the I/O board connection. The OEM parameter default value is used as a default for the parameter editing. If the "Hidden" option is set, the parameter is a constant and does not appear in the I/O board connection box. The OEM parameter default value defines the value of the constant parameter. The "Read only" option indicates that the parameter is visible for the user, but cannot be modified. Its default value is used as a constant value.


Functions and blocks written in IEC languages

ISaGRAF handles a library of functions and function blocks written in IEC languages. The available languages to describe such a function or block are FBD (Function Block Diagram), LD (Ladder Diagram), ST (Structured Text) or IL (Instruction list). Note that LD and FBD languages can be mixed in the same diagram. SFC language (Sequential Function Chart) cannot be used to describe a function or a block in library. The language attached to a library element is selected when the function is created, and cannot be changed later.

Compiling

Entering source code

Dictionary of local variables

Defining the interface


Compiling

Functions and blocks defined in the library must be compiled (verified) before they can be used within an ISaGRAF project. Nothing else has to be changed on the Library side concerning functions and blocks. Elements of the library will automatically appear in box selection menu when using the LD/FBD graphic editor within a project.

A function defined in the library can call other functions of the library. However, the ISaGRAF system does not support recursivity in function calling. A function block written in IEC language cannot call other function blocks (neither in IEC nor in "C" language).


Entering source code

The source code of a library function or function block is entered using standard ISaGRAF tools: graphic editor for LD or FBD programs, text editor for ST or IL programs. Refer to the corresponding sections in this manual for more information about these tools. The ISaGRAF Code Generator can be directly called from the graphic or text editing window, to compile the source code of a library function or block.


Dictionary of local variables

A library function or function block can have local variables, and local defined words. To access the variable declaration, the user must run the commands of the "Dictionary" command of the "File" menu, in the editor window, while editing the source code of the function.

A library function or function block cannot access a global variable or function block instance. Local variables of a function should be initialized in the function body.

Local variables of a function block written in IEC language are copied (instanced) each time the block is used in a project. Local variables of an instance keep their values from one call to the other.


Defining the interface

Functions or function blocks may have up to 32 parameters (input or output). A function always has one (and only one) return parameter, which must have the same name as the function, in order to conform with ST language writing conventions.

The list in the upper left side of the window shows the parameters, in the order of the calling model: first the calling parameters, last the return parameters. The lower part of the window shows the detailed description of the parameter currently selected in the list. Any of the ISaGRAF data types may be used for a parameter. The return parameters must be located after calling parameters in the list. Naming parameters must conform to the following rules:

•	the length of the name cannot exceed 16 characters

•	the first character must be a letter

•	the following characters must be letters, digits or underscore character

•	naming is case insensitive

The "Insert" command is used to insert a new parameter before the selected parameter. The "Delete" command is used to erase the selected parameter. The "Arrange" command automatically rearranges (sorts) the parameters, so that the return parameters are put at the end of the list.


"C" Functions and function blocks

The "C" functions and function blocks are computer functions called from the automation application, according to the ST language function calling interface.

Functions are synchronous processes. The ISaGRAF target application is suspended during the function execution. Function blocks associate operations and static hidden data. For example, a "counter" function block represents the counting operation, as well as the counting result. Functions and function blocks may be used to complete the standard automation language capabilities, or to access system resources.

 The parameters definition box is used to define the name and the type of each calling or return parameter of the function or function block. The "Edit" menu commands are used to define the parameters of the selected function or function block. A function can have up to 31 calling parameters, and always has one return parameter. A function block can have up to 32 parameters, with any mix of call and return parameters. Below is the correspondence between ISaGRAF types and "C" types:

BOOLEAN	unsigned long	unsigned 32 bit word: 1=true / 0=false

ANALOG	long	signed integer 32 bit word

REAL	float	single precision floating value

TIMER	unsigned long	unsigned integer 32 bit word (unit is 1 ms)

MESSAGE	char *	character string.

When a message value is passed onto a "C" function or function block, it cannot contain null characters. The string passed to the "C" code is null-terminated.

Refer to the ISaGRAF Target User's Guide for further information on how to manage the "C" source code of a function or a function block, and how to integrate a new element in the ISaGRAF target system.


Conversion functions

A conversion function is a "C" function called by the ISaGRAF I/O manager each time the analog variables using this conversion are input to or output from the project.

The function creates the relationship between the electrical value of the variable (read on the input sensor or sent to the output device) and its physical value (used in the application expressions). The function is therefore divided into two parts: input conversion and output conversion. The ISaGRAF library manager allows the user to control the "C" source code of a conversion function.

A conversion can be used for an integer or real analog variable. This implies that the conversion function interface is always defined by floating values. The interface is the same for any conversion function. The "C" definition of this interface is made in the "TACN0DEF.H" definition file.

Refer to the ISaGRAF Target User's Guide for further information on how to manage the "C" source code of a conversion function, and how to integrate a new element in the ISaGRAF target system.


Archiving library elements

The "Tools / Archive" menu command runs the ISaGRAF archive manager to save or restore library elements. You first need to select a library before running the "Archive command". The archive manager shows list of elements for only one library at a time.