 Using the text editor

This chapter only describes features and commands of the ISaGRAF text editor, particularly when used to enter the source code of ST and IL programs.

Editing commands

Options

Commands of the "Tools" menu

Calling other ISaGRAF tools

Parameters of the program

Other commands of the "File" menu

Updating the program diary

Selecting a variable from dictionary

Debugging ST and IL programs

The ISaGRAF text editor is also used to enter the project descriptor, edit diary files, technical notes (on line documentation) for library elements, and each time a text document has to be entered by the user.

Defining resources


Editing commands

The commands of the "Edit" menu are used to work on the edited text. Most of these commands act on the characters currently selected in the diagram, or perform an action at the current location of the caret.

 	Cut and paste

Find and replace

Go to line

Insert symbol from dictionary

Insert file


 	Cut and paste

The DEL key can be used to remove the selected text. Use "Edit / Undo" command to restore elements after a DEL command. The "Cut", "Copy", "Paste" commands of the "Edit" menu are used to move or copy text in the program, or to insert pieces of texts copied in the clipboard by other applications.


Find and replace

The "Edit / Find" and "Edit / Replace" menu commands are used to find and replace texts in the program. Any character string can be found. Research can be performed upward or backward, starting at the current location of the caret. It does not "loops" when the limits of the program are reached.


Go to line

The "Edit / Go to line" command is used to move the caret to a specific line number. This can be very useful to have access to a line with an error detected by the ISaGRAF compiler in an ST or IL program, and referenced by a line number.


Insert symbol from dictionary

Use the "Edit / Insert variable" command to insert at the caret position the symbol of a variable or object declared in the project dictionary. Symbol is selected through the common variable selection box described in chapter "More about program editors" in this document.


Insert file

The "Edit / Insert file" command inserts the whole contents of a file at the current location of the caret. Note that only pure ASCII text files can be handled by this command.


Options

The commands of the "Options" menu are used to display or hide editor toolbars, and select the character font. The selected character font will be used for any text editing in all ISaGRAF Workbench.

When used to enter the source code of an ST / IL program, the "Options / Show keywords" command is used to show or hide a toolbox that groups the most common keywords of ST or IL language. Click on a button in the toolbar to insert the corresponding keyword or operator at the current location of the caret.


Calling other ISaGRAF tools

Verify (compile) the program

 	Simulate or debug the application

Editing the dictionary of variables


Verify (compile) the program

The "File / Verify" command runs the ISaGRAF code generator to verify the programming syntax of the currently edited program. In case of SFC language, both level 1 and 2 are checked. When syntax verification is complete, the code generator window must be closed to continue work on the program. If there is only one program in the application (the edited one) the application code is generated if no syntax error is detected. The "Options / Compiling options" command is used to set compiling and optimizing parameters. Refer to chapter "Using the code generator" in this document for further information about compiling and code generation.


 	Simulate or debug the application

The "File / Simulate" and "File / Debug" commands run the ISaGRAF graphic debugger either in simulation or real connected mode, and re-opens the edited SFC program in debug mode. Used in debug mode, no modification can be entered in the program.


Editing the dictionary of variables

The "File / Dictionary" command is used to edit the dictionary of variables for the current application and the current program. It also contains the entry points to edit the user defined words. The local declarations or defined words relate to the currently edited program.


Parameters of the program

When the edited program is a function, a function block or a sub-program, the "File / Parameters" command is used to define its calling and return parameters. This command has no effect if the edited program is an SFC or top level program from section Begin or End.

Sub-programs, functions or function blocks may have up to 32 parameters (input or output). A function or sub-program 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.


Other commands of the "File" menu

The following commands are available in the "File" menu of all program editors:

Open another program

Printing the program


Open another program

The "File / Open" command allows the user to close the currently edited program and start editing another program of the current project with the same language. This function cannot be used to edit a program written in another language. The new selected program replaces the current one in the editing window.


Printing the program

The "File / Print" command outputs the edited program on printer. When editing an ST or IL program, this command runs the project document generator to print the program.

For graphic programs (SFC, FBD and Quick LD) You can also use the "Edit / Copy drawing" command to copy in the clipboard the drawing of the chart in metafile format, so that it can be pasted in other applications such as word processors. For SFC programs, only the level 1 information (chart, numbering and level 1 comments) appear on the copied metafile.


Updating the program diary

The diary file attached to the edited program may be manually entered using the "File / Diary" command. The diary file is automatically updated with syntax checking output messages each time the program is compiled. Compiling outputs are completed with the compiling date / time stamp.

If the "Update diary" mode is selected in the "Options" menu of program editors, the "Diary" dialog box is opened each time the program is saved on disk.

If OK button is pressed, the entered text note is then stored at the end of the diary file with current date / time stamp. This feature is very useful for maintenance of complete programs, as it provides useful help about the program life cycle.


Selecting a variable from dictionary

 When editing a text program (ST or IL) the "Edit / Insert variable" allows the selection of a declared variable name to be inserted at the current position of the caret. When editing LD or FBD programs, variable selection is required for the description of contacts coils, block I/O parameters or FBD variable boxes. In both cases, the "Select" dialog box is open to select a declared variable.

The "Scope" selection box is used to select between global and local variables. The selection box on the right allows the selection of the data type. Small icons beside the type selection box are button that can be used as shortcuts to select most current data types:

Boolean

Integer / Real

Timer

Message

To select a variable, click on its name in the list. Its name and comment are then displayed on the top of the list. Then press the "OK" button to confirm its selection. It is also possible to directly enter a variable name in the edit control without using the list.


Defining resources

The "Resources" command of the "Options" menu allows the user to define resources. A resource is any user defined data (network configuration, hardware setting...) of any format (file, list of values) which has to be merged with the generated code, in order to be downloaded with it in the target PLC. Such data is not directly operated by the ISaGRAF kernel, and is commonly dedicated to other software installed on the target PLC. Refer to your hardware manual for further information about available resources.

The resource definition file

Language reference

Example

Resource compiling

Implementation


The resource definition file

The resources are defined in a "Resource definition file" stored with other files of the ISaGRAF project. This is a pure ASCII text file, processed by the ISaGRAF Resource Compiler. This compiler is automatically run when the application code is built. This section explains the syntax of this file. The resource definition file uses lexical rules of the ST language. Comments, beginning with "(*" and ending with "*)" characters can be inserted anywhere in the text. Strings are delimited by single apostrophes. Refer to the second part of this manual for more explanations about the lexical formats used to enter numerical values.


Language reference

Below is the list of keywords and statements used in a resource definition file.

ULONGDATA

VARLIST

BINARYFILE

TEXTFILE

TARGET

ANYTARGET

FROM

TO


ULONGDATA

Meaning:	Specifies a resource which is a list of integer values. Values are stored in target code as unsigned 32 bit integers. Values are stored in the order specified in the resource definition file. Values must be separated by comas. The name of the resource cannot exceed 15 characters.

Syntax:	ULONGDATA '<resource_name>'

BEGIN

...target_selection...

...list of values...

END

Example:	ULongData 'MYDATA'

Begin

...

0, -1, 100_000,	(* decimal *)

16#A0B1, 2#1011_0101	(* hexadecimal, binary *)

End


VARLIST

Meaning:	Specifies a resource which is a list of variable addresses. Variables are identified by their name in the resource definition file. Variable addresses are stored in target code as unsigned 16 bit integers. Addresses are stored in the order specified in the resource definition file. Variables must be separated by comas. The name of the resource cannot exceed 15 characters.

Syntax:	VARLIST '<resource_name>'

BEGIN

...target_selection...

...list of variable names...

END

Example:	VarList 'LIST'

Begin

...

Var100, MyParameter, Command, Alarm

End


BINARYFILE

Meaning:	Specifies a Binary File resource. The source data is stored  in an MS-DOS file. The target resource definition is completed with a target pathname. End of line characters are not converted by the ISaGRAF Resource Compiler. The name of the resource cannot exceed 15 characters.

Syntax:	BINARYFILE '<resource_name>'

BEGIN

...target selection...

FROM '<source_pathname>'

TO '<destination_pathname>'

END

Example:	BinaryFile 'MYFILE'

Begin

...

From 'c:\user\config.bin'

To '/dd/user/appl/config.dat'

End


TEXTFILE

Meaning:	Specifies a Text File resource. The source data is stored in an ASCII file. The target resource definition is completed with a target pathname. End of line characters are converted by the ISaGRAF Resource Compiler according to the target host system conventions. The name of the resource cannot exceed 15 characters.

Syntax:	TEXTFILE '<resource_name>'

BEGIN

...target selection...

FROM '<source_pathname>'

TO '<destination_pathname>'

END

Example:	TextFile 'MYFILE'

Begin

...

From 'c:\user\config.bin'

To '/dd/user/appl/config.dat'

End


TARGET

Meaning:	Specifies the name of a target code that has to include the resource. Refer to the preceding section (compiler options) for further information about handled targets. The "Target" statement can appear more than once in the same resource block, in order to select several targets. This statement cannot be used if the "AnyTarget" statement is specified.

Syntax:	TARGET '<target_name>'

Example:	BinaryFile 'MYFILE'

Begin

Target 'ISA86M'

Target 'ISA68M'

...

End


ANYTARGET

Meaning:	Specifies that the resource must be merged to all the target codes built by the Code Generator. The ISaGRAF Code Generator can produce several target codes during the same "Make" command. This statement cannot be used if one or several "Target" statements are specified.

Syntax:	ANYTARGET

Example:	ULongData 'MYDATA'

Begin

AnyTarget

...

End


FROM

Meaning:	Specifies the source pathname (on the PC where the ISaGRAF Workbench is installed) of a BinaryFile or TextFile resource. The characters used to isolate the components of the pathname (drive, directory, prefix, suffix) must conform to the MS-DOS system conventions.

Syntax:	FROM '<target pathname>'

Example:	BinaryFile 'MYFILE'

Begin

...

From 'c:\user\config.dat'

To '/dd/user/appl/config.dat'

End


TO

Meaning:	Specifies the destination pathname (on the target system) of a BinaryFile or TextFile resource. The characters used to isolate the components of the pathname (drive, directory, prefix, suffix) must conform to the target host system conventions.

Syntax:	TO '<target pathname>'

Example:	TextFile 'MYFILE'

Begin

...

From 'c:\user\config.dat'

To '/dd/user/appl/config.dat'

End


Example

Below is a complete example of a resource definition file:

(* resource definition file *)

ULongData 'DATA1'	(* list of values *)

Begin

   Target 'ISA86M'	(* for this target only *)

   1, 0, 16#1A2B3C4D, +1, -1	(* numerical values *)

End

VarList 'VLIST1'	(* list of variables *)

Begin

   Target 'ISA86M'	(* for this target only *)

   Valve1, StateX, Command, Alrm1	(* variable names *)

End

BinaryFile 'FILE1'	(* binary file resource *)

Begin

   AnyTarget	(* dedicated to all targets *)

   From 'c:\user\updatef.bin'	(* source file on PC *)

   To 'updatef.cfg'	(* target file on PLC *)

End

TextFile 'FILE2'	(* text file resource *)

Begin

   Target 'ISA68M'

   From 'c:\nw\nwbd.txt'	(* source file on PC *)

   To '/nw/dat/nwbd'	(* target file on PLC *)

End


Resource compiling

If resources have been entered in resource definition file, a dialog box appears at the end of ISaGRAF code generation. Press the "Start compile" button to run resource compiler. Output messages and errors will be displayed in the main control. Press "Exit" to avoid resource compiling. In this case, resources will not be added to the ISaGRAF code.


Implementation

The number of resources, the size of data rows and files are not limited by ISaGRAF. Resources are stored at the end of the generated code, with a resource directory. Below is the format (using C notations) of the resource directory format:

__RESOURCE:

{

  long nbres;	/* number of defined resources */

  {

    char name[16];	/* resource name */

    long type;	/* resource data type */

    long size;	/* exact size of data block */

    uint32 data;

    uint32 path_offset;	/* points to a string */

  } /*nb of records */

}

Below are the possible values of the "type" field:

1 = binary file

2 = text file

3 = ulong data (path_offset field is not used in this case)

4 = variable list (path_offset field is not used in this case)

For text files, end of line characters are translated by the resource compiler, according to the target system conventions. All pointers are 32 bit offsets from the address of the corresponding structure. All resource names and pathnames are NULL terminated strings. Pathnames and data follow the resource directory.


Commands of the "Tools" menu

The following commands are available in the Tools menu. They are used to display information in a small text list at the bottom of the editor window:

Show compiler output	display in output window error messages from the last compiling

(for ST/IL program only)

Find in text	find occurrences of a text in whole text

and list them in the output window

Hide output window	close the output list window

When error messages or occurrences are displayed in the output window, double click on a line to directly set visible selection at the corresponding location.


Debugging ST and IL programs

During simulation or On Line debugging of ST and IL program, no modification can be entered in the program text.

IL	For IL programs, instructions are formatted in a list view. Current value of a variable used in an instruction is displayed on the same line. You can double click on an instruction to change the value of the corresponding variable.

ST	For ST programs, a Spy List window is embedded in the editor window. You can resize views by dragging with the mouse the separation line between them.

Saving list on hard disk

 	Inserting variables in the list

Changing the selected variable

Dump display

For each variable of the list, ISaGRAF displays its name, its current value and its comment text. Columns can be resized by dragging separation lines with mouse in the list title bar.


Saving list on hard disk

The "File / Save list" command save the lists of variables on the disk, under the same name as the edited program. This list will be automatically re-loaded each time ST or IL program is open in debug mode. This list can also be freely open and modified using the Spy List tool run by the "Spy / Spy list" command of the debugger window.


 	Inserting variables in the list

 The "Edit / Insert variable" command inserts another variable in the list. The variable name is selected in the list of objects defined in the project dictionary. This way the user does not have to manually enter the identifier. The variable is inserted before the variable currently selected in the list. The list cannot contain more than 32 variables. The same variable cannot appear more than once in the same list.

 When the name of a variable is highlighted in ST text, press this button in the toolbar or run the "Edit / Spy selection" command to directly send the variable to embedded spy list.


Changing the selected variable

The "Edit / Change variable" command replaces the selected variable by another variable. You can also use the "Cut variable" command to remove the selected variable from the list.


Dump display

At any time, you can swap viewing mode between list and "Dump" view. Press the "zoom" button in toolbar or use "Options / Dump" command to swap viewing mode.

In "Dump" mode, only one variable value is displayed. Its value is displayed in numerical/symbolic format at the top of the window, and is also displayed in binary "dump" format. This mode allows you to spy hexadecimal value of each byte in the variable value.

"Dump" display is very useful for spying and understanding message strings containing non printable characters.