 Using the graphic debugger

ISaGRAF includes a complete graphic and symbolic debugger. The "Debug" command of the program management window runs the debugger to control the application downloaded in the target PLC. In this mode, the debugger communicates with the target system via hardware link. The "Simulate" command of the program management window simultaneously runs the debugger and a complete target simulator. This enables the user to test his application when the target's I/O system is not yet complete. The debugger window contains the commands to control the entire application.

The debugger window

Controlling the application

Options

"Write" commands

On line modification

DDE exchanges

When the debugger starts, and if the application in the target PLC is the same as the one on the workbench, it automatically opens the program management window, in debug mode. Commands of this window may be used to open other ISaGRAF windows (graphic and text editors, dictionary, lists of variables, I/O connection...). All windows opened during a debug session operate in "debug mode", meaning that the editing command is disabled. Displayed program components (steps, transitions, variables...) are shown with their current run time status or value. Double clicking on an object changes its status or value in the target application.

When running the debugger in simulation mode, communication with the ISaGRAF target system is stopped. The debugger only communicates with the simulator window. Because the target system does not exist in this mode, the "download", "stop" or "activate" commands are not available on the debugger menu.


The debugger window

The debugger window only contains information about the complete application status. It is linked to other ISaGRAF windows creating a complete interactive debug system. Detected run time errors are displayed in the bottom area of the debugger window. Commands from the "Options" menu are used to hide, show or clear the list of errors.

The control panel (area under the debugger menu) shows the global status of the target application, and information about the execution cycle timing. The list of possible target status is as follows:

Logging:	Debugger establishes communication with the target system.

Disconnected:	Debugger cannot communicate with the target system. Ensure connection cable and communication parameters are valid.

No application:	Connection is OK, but no ISaGRAF application currently exists in the target system. Download an application.

Application active:	Connection is OK and an active application exists in the target system. Debugger is now establishing the communications with this application, if it is the same as the one on the Workbench..

RUN:	Target application is in "Real Time" mode.

STOP:	Target application is in "Cycle to Cycle" mode.

BreakPoint:	Target application is in "Cycle to Cycle" mode, because a breakpoint is encountered.

Fatal Error:	Target application failed because a serious error occurred.

Information on the run time cycle timing is as follows:

Allowed:	programmed timing.

Current:	exact timing of the last complete execution cycle.

Maximum:	maximum timing detected since the application started.

Overflow:	number of execution cycles detected with a timing greater than the allowed timing.

All time values are given in milli-seconds. Time values are not displayed when debugger is used in simulation mode.


Controlling the application

The "File" and "Control" menus contain the commands for the installation and the control of the currently edited ISaGRAF application on the ISaGRAF target system.

Note:	Some of these commands are not available during simulation, because the application processed by the simulator is automatically installed by the ISaGRAF Workbench.

Stop the target application

Activate the target application

Download the application

Display version number

On line modification

Real Time mode

Cycle to Cycle mode

Execute one cycle

The cycle timing

Remove all breakpoints

Unlock I/O variables


Stop the target application

The "File / Stop application" command stops the execution of the application currently active in the ISaGRAF target system.


Activate the target application

The "File / Start application" command runs the application existing in the target system. When an application is downloaded, it is automatically started, so that the "Start" command does not have to be used. The "Start" command is typically used after a "Stop" command.

Note:	the target application must be stopped (inactive) before it is possible to download a new application.


Download the application

The "File / Download" command is used to download the application code in the target system. Select the type of code to be downloaded, according to the target system processor and the application options.


Display version number

The "File / Get version number" command is used to display complete identification of both Workbench and target applications. The Workbench application is the one currently open on the ISaGRAF Workbench. The target application is the one executed in the target ISaGRAF PLC. The following items are displayed:

VERSION:	This is the version number of the application code. This number has been calculated by the code generator.

DATE:	This item shows the date and time when the code has been built.

CRC:	This is a checksum calculated with the contents of the table of symbols. This number has been calculated by the code generator. This value depends on the contents of the dictionary of variables.

Note:	The "Get version number" command is also available during simulation. In real debug mode, this command cannot be used if the target PLC is not connected.


On line modification

The "File / Update application" command enables the user to achieve "on line modification" of the running target application. This command is detailed in further sections of this chapter. It is not available when the debugger is used in simulation mode.


Real Time mode

The "Control / Real time" command is not available when no application is active. It sets the target application in normal "real time" mode: Normal mode: the execution cycles are triggered by the programmed cycle timing.


Cycle to Cycle mode

The "Control / Cycle to cycle" command is not available when no application is active. It sets the target application in normal "cycle to cycle" mode: In this mode, cycles are executed one by one, according to the "Execute one cycle" commands made by the user from the debugger menu.


Execute one cycle

When target is in cycle to cycle mode, the "Control / Execute one cycle" command runs the execution of one cycle.


The cycle timing

The "Control / Change cycle timing" command enables the user to modify the programmed cycle timing. This time is titled as "Allowed" in the debugger control bar window. The "Cycle to cycle" mode should be set before modifying the cycle timing. The cycle timing is entered as an integer number in milli-seconds.


Remove all breakpoints

The "Control / Clear all breakpoints" command removes all the breakpoints currently installed (encountered or still active) in the whole application. Existing breakpoints are not automatically removed when the debugger window is closed.


Unlock I/O variables

The "Control / Unlock all IO variables" command unlocks all the I/O variables currently locked in the application. When an I/O variable is locked, no input or output status change is made to the corresponding I/O device. Variables attached to the I/O can still be written by the application or by the debugger. Currently locked I/O variables are not automatically unlocked when the debugger window is closed.


Options

The "Options" menu contains the options to control the information displayed in the debugger window.

The communication parameters

Display options


The communication parameters

The communication timing parameters can be adjusted when the debugger is active. Only communication time-outs can be set here. Other communication parameters (baud rate, parity...) must be set from the "Debug" menu of the Program Management window.

The "Communication time-out" is the time left for the target system to begin the answer to one workbench request. The "Cyclic refresh duration" is the time period required for the "read" requests to be sent by the debugger in order to refresh data in the opened windows.

All the time values are displayed and entered as integer numbers in milli-seconds. The communication timing parameters cannot be set when the debugger is used in simulation mode.


Display options

The "Show cycle timing" option enables the user to hide or show the cycle timing values in the debugger control bar. When this option is set, all the cycle timing components (allowed, current, maximum, overflows) are displayed and refreshed. Disabling this option reduces the debugger communication burden.

When the "Show errors" option is set, detected run time errors are listed in the bottom area of the debugger window. When this option is disabled, the error list is closed. Removing this option reduces the debugger display and communication burden. The "Options / Clear errors" command clears the list of run-time errors currently displayed in the debugger window.

The "Options / minimize window" command reduces the size of the debugger window so that it is shown as a small, always on top, panel containing only the application status and graphic buttons for most commonly used commands.


"Write" commands

The ISaGRAF symbolic debugger offers many commands to change the value or status of the application components. Selecting the component to be changed is done by double clicking on its name or its drawing in an editing window, when the debugger window is opened.

Variables

SFC objects


Variables

A variable status is changed by double clicking on its name in one of the following windows:

•	Dictionary

•	Lists of variables or time diagrams

•	LD or FBD Programs

•	I/O connection

The following commands are offered in the debug dialog box:

•	Write the variable to a new value

•	Lock the variable (for I/O variables only)

•	Unlock the variable (for locked I/O variables only)

•	Start or stop a timer variable (set automatic refresh mode)

Symbolic values used to represent boolean FALSE and TRUE values are the strings defined for that specific boolean variable in the dictionary. The analog value specified for a "Write" command must be entered in an integer or real format, according to the variable definition in the dictionary. The string specified for a "Write" command for a message cannot be longer than the message capacity attached to that specific variable in the dictionary.


SFC objects

To observe a control operation on an SFC program while debugging the application, commands of the "File" menu are used in the Program Management window. The SFC program must be selected from the list of programs. The following commands are available:

Start SFC program:	Enables the selected program by putting an SFC token into each of its initial step.

Kill SFC program:	Kills the selected program by removing all its existing tokens.

Freeze SFC program:	Suspends the execution of the selected program.

Restart SFC program:	Restarts a suspended (frozen) program.

For child programs, these commands correspond to the "GSTART", "GKILL", "GFREEZE" and "GRST" functions in the programming language.

A control operation can be seen in an SFC step when debugging the application by double clicking on its graphic representation in the SFC editing window. The following commands are available in the debug dialog box:

•	Install a breakpoint on the step activation

•	Install a breakpoint on the step de-activation

•	Clear breakpoint added to the step

Note:	Activation and de-activation breakpoints cannot be added to the same step.

A control operation can be seen in an SFC transition when debugging the application by double clicking on its graphic representation in the SFC editing window. The following commands are proposed in a debug dialog box:

•	Add a breakpoint on the transition clearing

•	Clear a breakpoint added to the transition

•	Manually clear the transition (move or add tokens)

Conditional clearing: a token is created on the steps following the transition. The tokens existing in the preceding steps are removed. Unconditional clearing: a token is created on the steps following the transition. The tokens existing in the preceding steps are not removed.


On line modification

The "On line modification" feature enables the user to modify the application while the process is running. This is sometimes necessary for chemical processes where any interruption may jeopardize production or safety. This function should be used very carefully.  ISaGRAF may not be able to detect all possible conflicts generated by user defined operations as a result of these on-line changes.

Code sequences

Variables

Inputs and outputs

Run time operations

Memory requirements

Limitations

Operations


Code sequences

As ISaGRAF offers many possibilities for access to variables, programs or I/O boards from the debugger, the "On line modification" function described here applies only to the code sequences modification. A sequence of code is a complete set of ST, IL, LD or FBD instructions executed in a row. In a "beginning of cycle" or "end of cycle" program, a code sequence is the entire list of instructions written in the program. In an SFC program, a code sequence is the Level 2 programming of one step or transition. The "On line modification" consists of replacing one or more code sequences, without stopping the PLC execution cycle. As the control of the SFC tokens is very critical, it is not possible to modify an SFC structure, to add, renumber or remove a step, a transition or an SFC program.


Variables

As the variable data base is a very critical part of the application, it can be accessed at any time by other processes (on multitasking PLC). It is also possible to modify variable values from the debugger. Therefore, ISaGRAF does not allow the user to add, rename or remove a variable on line. Anyway, it is possible to modify the way a variable is used in the application. It is also possible to reserve "unused" internal or I/O variables in the first version of the application, so that future modifications can make use of them.

They are different styles of variables in ISaGRAF target data base. Limitations act on all of them:

- Declared variables

They are the ones declared using the ISaGRAF dictionary. They cannot be changed and cannot be renamed for on line change. It is recommended that some extra variables are declared and initialized in the application even if not used today. Such extra variables will enable future modifications to work on without changing the application data checksum.

- Instances of function blocks

Each instance of "C" or IEC written function block corresponds to data stored in ISaGRAF target real-time data base. When function block instances are added or removed, On Line change is no more possible. So it is better to work in ST with FB instances declared in dictionary, rather than adding blocks (that will correspond to new automatically declared instances) in Quick LD or FBD diagrams. Also, any modification in the definition of available function blocks in the ISaGRAF library will lead to an impossible On Line change.

- Steps

Each SFC step corresponds to a piece of data where are stored SFC step dynamic attributes (its activity time and flag). Adding or removing SFC steps change the application data base and is denied for On Line change.

- Hidden variables allocated by compilers

The ISaGRAF Compiler generates "hidden" temporary variables to solve complex expressions. In some case, the change of an expression may lead to a different set of non visible temporary variables, and that leads to an impossible On Line change. To avoid this situation, you can add the following entries in ISA.INI file, in order to force a minimum number of temporary variables to be allocated for each program, even if not used for the compiling of the first application version. Values given here are examples:

[DEBUG]

MNTVboo=8	; for booleans

MNTVana=4	; for integers and reals

MNTVtmr=4	; for timers

MNTVmsg=2	; for messages

When such a setting is written in ISA.INI, the compiler outputs a warning message if a new compiling of the application leads to a greater number of allocated temporary variables.


Inputs and outputs

As the ISaGRAF I/O system is very open, required modifications should be implemented by the OEM, using specific features of the corresponding hardware. The ISaGRAF system does not allow the user to add, connect or remove an I/O variable, or to modify the description of an I/O board on line. Operations such as modifying board parameters and locking I/O channels are available using standard OEM features and the "OPERATE" function.


Run time operations

Modifying a running application consists of the following operations:

•	modify the application source code on the workbench

•	generate the new application code

•	download the new application code using "update" command instead of "download"

•	switch from the old application to the new one, in between PLC execution cycles using the "Realize update" command.

This procedure guarantees that the target PLC always has a complete and reliable running application, and enables the user to control the timing of the sample operations in a very safe and efficient way. It also enables the user to modify the project as often as possible. Regardless to the process itself, the "On line modification" is essentially the same as a normal "stop, start and download" set of commands. The only differences are that no variable state is lost, and the switching time is very short (usually 1 or 2 cycle duration). During the switch, no variable is modified, and all internal, input or output variables keeps the same value before and after the application modification. During the switch, no action is performed, and SFC tokens are not moved.


Memory requirements

In order to support the "On line modification" capability, the target PLC must have free memory space to enable the storage of the modified version of the application code. Both versions of the application code have to be stored in PLC memory during the switch operation.


Limitations

As described before, only modifications to code sequences are allowed. Variable definition, application parameters and I/O connections cannot be modified. When downloading a modified version of the application, ISaGRAF makes a comparison between the modified application and the running one, in order to detect any unsafe change. If the switch seems dangerous or impossible, a download error is generated. One of the safeguards performed by ISaGRAF is to compare the symbol table checksum, so that any variable, program, or SFC element name change is detected. If a step is active when the switch occurs, its non stored (N) actions are lost. The new step activation actions are not executed. Actions executed at the de-activation of the step are the ones carried over in the new application code. If a transition is valid when the switch occurs, its receptivity equation is updated. The new downloaded application code is not backed up on the PLC. The backup is the version which was previously downloaded with standard download commands.


Operations

To update the code of a running application, the following operations have to be performed:

•	Before making any change on a running application, it is highly recommended to make a copy of the current project under another name. The modifications may be performed on the copies.

•	Before editing any program, the user should check that the "update diary" option of the editing tools is set, to ease future program maintenance.

•	When one or more sequences have been modified (without modifying SFC structures and program hierarchy), the code of the new application must be generated on the workbench before downloading.

•	Using the debugger, from within the old project, the user must connect the target PLC and perform any operation which can make the application update faster or more safety.

•	Using the debugger, from inside the new project, the user must connect the target PLC. If the application name is changed, the target data base cannot be accessed. The user must run the "File / Update" command.

•	The modified application is downloaded by selecting the "update later" option. This may slightly slow down the PLC during transfer.

•	When download is complete, the user can run the "File / Realize update" command to enable the switch at the most adequate moment. The switch will have a 1 or 2 cycle duration.

•	When the switch has been correctly performed, the programs of the modified running application are displayed. If not, the existing running application remains as is.


DDE exchanges

The ISaGRAF debugger includes a DDE (Dynamic Data Exchange) server. An advise loop can be installed between the ISaGRAF debugger and other applications, in order to dynamically display the current value of variables in non-ISaGRAF applications.

Only "advise" and "poke" transactions are supported by the ISaGRAF debugger DDE server. You can use "request" transaction only for variables already spied in an advise loop. Other DDE services such as "execute" are not available. When an advise loop is established on a variable, the value of this variable is updated in the client application each time it changes. Variables of any type can be spied. The identification of the dynamic link includes the following names:

Service name:	"ISaGRAF"

Topic name:	Name of the ISaGRAF project

Item name:	Name of the variable

If the variable is local to a program, its name must be followed by the name of its father program, written between parentheses, with the following syntax:

variable_name(program_name)

The ISaGRAF debugger DDE server is dedicated to the ISaGRAF application currently spied by the debugger. Up to 256 variables can be spied by the ISaGRAF server. The DDE server may be used when the ISaGRAF debugger runs in either connected or simulation mode. The refresh duration is the one established for communication between the debugger and the ISaGRAF target system or simulator.