Contents

___________________________________________________________________________

Section Page

1 Introduction 5

1.1 Introduction 5

1.2 Installation 6
1.2-1 Target machine 6
1.2-2 PL7 SDKC product contents 6
1.2-3 Installation procedure 7

2 Methodology for creating and using an EF in PL7 9

2.1 Creation 11
2.1-1 The EF family 11
2.1-2 The EF class 11
2.1-3 The EF 12

2.2 Generating the family in debug mode 13

2.3 Installing/Uninstalling in the PL7 library for debugging 13

2.4 Creating an application using the new EFs 13

2.5 Testing each EF in PL7 14

2.6 Generating the family in release mode 14

3 Managing the EF using PL7 SDKC 15

3.1 Creation 15
3.1-1 The EF family 15
3.1-2 The EF class 17
3.1-3 The EF 19

3.2 Generating the family in debug mode 24

___________________________________________________________________________
1
 Contents
___________________________________________________________________________

Section Page

3.3 Generating the family in release mode 25

3.4 Installing/Uninstalling in the PL7 library 26

4 Testing the EF using the debugging tool 27

4.1 Accessing EF debugging 27

4.1-1 Selecting the family of the EF to be tested 27
4.1-2 Opening the EF debug screen 27

4.2 Presentation of the tool 29

4.3 Debugging EFs 30

4.3-1 Inserting and removing breakpoints 30
4.3-2 Mixing C code and assembly language 31
4.3-3 Registers 31
4.3-4 Local variables 32

5 Additional SDKC functions 35

5.1 Setting the tool parameters 35

5.2 Modifying a family 36

5.3 Importing/Exporting 37
5.3-1 Class 37
5.3-2 C Source 38

5.4 Archiving/Restoring a family 40

5.4-1 Archiving 40
5.4-2 Restoring 41

___________________________________________________________________________
2
 Contents
___________________________________________________________________________

Section Page

6 The EF code 43

6.1 Rules for implementing EFs 43

6.1-1 C Language 43
6.1-2 Managing family and EF versions 46
6.1-3 Managing the size of the stack 47

6.2 List of reserved words 48

7 System functions 51

8 Appendix 73

8.1 Example 73
8.1-1 Defining the EF 73
8.1-2 Generating a diskette and installing the family 78

___________________________________________________________________________
3
 Contents
___________________________________________________________________________

Section Page

___________________________________________________________________________
4
 Introduction1
Section
1 Introduction
1.1 Introduction

An EF (Elementary Function) is a function, designed to fulfil a certain task in the user

program.

As it will in due course form part of the PL7 library, like the manufacturer functions, it can
be used in an identical way :
• accessible in all languages
• display via the PL7 library tool
• classified in families/functions

The development kit in "C" language (PL7 option) is designed to implement the entire
development cycle of an EF family :
• management of an EF family (creation, modification)
• development of each EF in “C” language
• individual debugging of an EF in the target PLC (TSX 37 or TSX 57)
• generation of an installable form containing the new EF family to be installed in the PL7
library, as well as its installation procedure on a user station.

Users of this product will be systems developers and therefore will necessarily be
familiar with :
• “C” language for development,
• PL7 (Micro and Junior) and their languages for debugging.

The access key (*) supplied with the kit, makes it possible to manage 5 families
(up to 25500 functions per family) in the form of 5 different codes.

This manual comprises the following sections :

• Section 1 "Introduction"
• Section 2 "Methodology for creating and using an EF in PL7"
• Section 3 "Managing the EF using PL7SDKC"
• Section 4 "Testing the EF using the debugging tool"
• Section 5 "Additional SDKC functions"
• Section 6 "EF code"
• Section 7 "System functions"
• Section 8 "Appendix"

(*) On page 8 of this manual, write the number of the access key marked on the
box in which your product was delivered.

___________________________________________________________________________
5
 Introduction

1.2 Installation

1.2-1 Target machine

The SDK C operates on :

• IBM PC or compatible microcomputer
• FTX terminal : FTX 417/40 or (FTX 517xx)

The minimum configuration is as follows :

• 386 microprocessor at 25 Mhz
• 8 Mb of RAM
• 20 Mb available on disk
• VGA monitor
• COM serial port available (COM1 to COM4) for connecting to the PLC
• Windows version 3.1 or above or Win95 operating system
• PL7 Micro or PL7 Junior V1.5 minimum

The typical machine configuration is as follows :

• microprocessor 486 DX at 33 Mhz
• 16 Mb of RAM

1.2-2 PL7 SDKC product contents

The product which you have just received comprises :

• installation diskettes (see the procedure on the following page)
• this manual
• a Visual C++ 4.0 software pack (supplied for reasons to do with MICROSOFT
licensing). This software must not be installed on the development station. It contains
the tools for generating and editing links used to compile the EF. These tools are
already incorporated on the installation diskettes of the PL7 SDKC product.

___________________________________________________________________________
6
 Introduction

1.2-3 Installation procedure

The PL7 SDKC product should be installed on a development station, on which PL7
Micro or PL7 Junior has already been installed.

Once the diskette has been inserted into the drive, proceed with installation by means
of the following steps :
• Windows 3.1 : From the file manager, select the File-Run command, type a:\setup,
press enter.
Windows 95 : Open the Windows explorer, select drive (A) then double-click on
setup.exe or in Run from the Start Menu, type a:\setup then click on OK.
• Register your name and organization
• Select the installation language
• Enter the no. (your product's access key) marked on the delivery box (*). This key
is used to access the five family codes assigned to the product. Installation cannot
proceed if the number of this access key is incorrectly entered.
• Once installation is complete, simply double-click on the icon in the MODICON-
TELEMECANIQUE group to access PL7 SDKC.

(*) We strongly recommend making a note of the number of the access key on the
space provided on the following page.

___________________________________________________________________________
7
 Introduction

Space reserved for recording your products' access key numbers

1 ........................................................................

2 ........................................................................

3 ........................................................................

4 ........................................................................

5 ........................................................................

6 ........................................................................

7 ........................................................................

8 ........................................................................

9 ........................................................................

___________________________________________________________________________
8
 Methodology for creating and using an EF in PL72
Section
2 Methodology for creating and using an EF in PL7

The diagram below outlines the development cycle.

PL7 SDKC
Generate family
in Debug mode
error no error

▼
Development station

▼
▼
Develop Install the family on
the family ▼ the development station

Generate family
error in release mode

▼
no error
PL7 Micro/Junior
▼

Debug
an EF ▼

EF family
+
Setup.exe
User station

PL7 Micro/Junior
▼

EF
library

The object of the following sections is to present the various screens which appear
during this development cycle.

___________________________________________________________________________
9
 Methodology for creating and using an EF in PL7

Clicking on the PL7 SDKC icon displays the following initial screen :

10

The left-hand side of this screen, which is empty the first time the kit is used, will be filled
with names of EF families, as they are created (Current and/or Archived).
A family consists of one or more classes, which themselves consist of one or more EFs
as shown by the diagram below :

Family name

Class1

EF1
EF2

Class2

EF1
EF2
EF3

A family is made up of 100 Classes maximum and 255 EFs per class. The class is an
entity which is only used while developing the family and which will not be displayed in
the PL7 Library tool.
The version, filled in when the description of the family is defined, is as displayed in the
PL7 Library tool.

___________________________________________________________________________
10
 Methodology for creating and using an EF in PL7

2.1 Creation

2.1-1 The EF family

It is possible to create a family by selecting the Create function from the Family menu.
Five families can be created. They correspond to five codes supplied by the product.

- The Description tab

contains the family
characteristics.

- The Datasheet tab

is used to record
additional information
about the family.

2.1-2 The EF class

Once the family has been validated, by selecting the Create Class function from the
Utilities menu, it is possible to create one of the classes authorized by the family (1 to
100).

- The Description tab

contains the class
characteristics.

- The Class.h tab is

used to define
constants, types or
structures common to
all the EF in the class.

___________________________________________________________________________
11
 Methodology for creating and using an EF in PL7

2.1-3 The EF

At the end of creation, the name of the class appears on the left-hand side of the screen,
and an EF can then be created by selecting the function Create EF from the Utilities
menu. 255 EFs can be created per class (1 to 255).

12

• The Description tab contains the EF characteristics.

• The Interface tab can be used to enter the EF call parameters.
• The Source .C tab is used to write the EF C code.
• The Source .H tab is used to define constants, types or structures specific to the EF.

___________________________________________________________________________
12
 Methodology for creating and using an EF in PL7

2.2 Generating the family in debug mode

Generation is performed on the whole family, but it is possible to request partial or total
generation.

Once the family has been developed, it is advisable, at first, to generate it by selecting
the Generate Debug function from the Family menu. This then makes it possible to test
one of the EF of the family.
Generate means compile and then edit the links with the debug options of each EF of
this family.

Once generation is complete, a log file summarizing the errors and warnings (resul.log)
is created (see section 3.1-3), and the user should return to the .C or .H source screens
of any EF(s) which may be causing a problem.

2.3 Installing/Uninstalling in the PL7 library for debugging

Once the family has been generated without any errors (compilation or link editing), it
is possible to launch the Install function from the Family menu so that it can be entered
in the PL7 library.

The family which is being edited can be removed from the PL7 library. To do this, launch
the Uninstall function from the Family menu.

This installation/uninstallation is only possible if PL7 (Micro or Junior) is not

running (active elements in memory).

2.4 Creating an application using the new EFs

Once the family has been installed, PL7 (Micro or Junior) should be launched.
The user should test the new EF(s), by developing an application which calls them, and
then transferring this application to the PLC.

Since this application is designed to test behavior, it is advisable to include only one copy
of each EF to be tested.

___________________________________________________________________________
13
 Methodology for creating and using an EF in PL7

2.5 Testing each EF in PL7

To test the EF in the application, select Debug EF from the Application menu of PL7
(Micro or Junior).
It is then possible to insert breakpoints, proceed step by step, display local variables or
registers, etc.
If the tests are not conclusive, the user should return to the EF development environment
to review the process and restart the cycle described above.

2.6 Generating the family in release mode

Once all the tests on all the EF in the family have proved conclusive, it is then possible
to generate this family, for use, by selecting the Generate Release function from the
Family menu.
14 This action makes it possible to create an installation medium for the selected family
(diskette, local or networked hard disk directory, etc). This medium can then be
broadcast.

___________________________________________________________________________
14
 Managing the EF usingSection
PL7 SDKC3
3 Managing the EF using PL7 SDKC
3.1 Creation

3.1-1 The EF family

Create opens the

Family area defined by Used to manage
the "Description" tab for updating of the family
data entry Entry of the family name by entering a VV.RR (*)
(24 characters) type number

A family
number will
be assigned
automatically
(any of the 5
possible)

Integer beginning
at 1. This is used
In family display mode, to manage
this will display the updates which
created and/or archived would make the
families in the list (see texts (family
section 5.4) datasheet and
comments)
incompatible

(*) The value of VV (version) or RR (release) must be between 0 and 99 inclusive.

___________________________________________________________________________
15
 Managing the EF using PL7 SDKC

Clicking on the "Datasheet" tab opens the following area :

The family is validated by this button, but

only if all the fields in the "Description" tab
have been filled in correctly

This area where text can be entered (optional), is used to note down the main data
concerning the family.
This datasheet can, for example, be used to enter log data on the versions of the family.
This datasheet only appears in PL7 if there is a conflict in versions between a family in
the library and the same family in the application.

It is possible to delete a family using the Delete command from the Utilities menu. When
a family is deleted, its contents (class(es) and EF(s)) are also deleted.

___________________________________________________________________________
16
 Managing the EF using PL7 SDKC

3.1-2 The EF class

Create Class opens the

Class fields for data entry
and enters information in Reminder of the
the area defined by the parameters defined for
"Description" tab the family (read-only)

Used to enter the name of the Number between 1 Used to manage

class being created (16 and 100 inclusive updates to the
alphanumerical characters + the used to ensure the class by entering
underscore character) uniqueness of the a VV.RR (*) format
class developed. It is number
filled in automatically

(*) The value of VV (version) or RR (release) must be between 0 and 99 inclusive.

Classes which belong to the same family must, without fail, have different names and
codes.
It is only possible to exit from the description tab once all the fields have been filled in.
This action confirms the parameters entered.

It is possible to delete a class using the Delete command from the Utilities menu. When
a class is deleted, the EF(s) which it comprises are also deleted.

___________________________________________________________________________
17
 Managing the EF using PL7 SDKC

The "Import class" and "Export class" functions in the Utilities menu are used to import
a class from another family and export a class to another family (see section 5.3).

Clicking on the "Class.h" tab opens the following area :

Toggle button (Normal size/Full screen)

reduces/enlarges the entry window

This area is used to enter the ( .h) interface file source code common to all the EFs in
the class. This file is used to create for example special types or constants which will be
reused in the C sources of all the EFs in the class.
This file should be ≤ 64 Kbytes.

___________________________________________________________________________
18
 Managing the EF using PL7 SDKC

3.1-3 The EF
Create EF opens the
EF fields for data entry
and enters information
in the area defined by
the "Description" tab

Reminder of
the param-
eters defined
for the family
and the class
(read-only)

The EF type
is a proce-
dure

Number
between 1
Used to and 100
Used to enter
enter a text Used to define the size inclusive
the name of
commentary of the stack. Its default used to
the EF being
on the EF value is 512 bytes and ensure the
created (16
containing it is used to store the uniqueness
alphanumerical
a maximum EF parameters, local of the EF
characters + the
of 80 variables, and the developed.
underscore
characters parameters and It is filled in
character)
variables of the automatically
functions which it calls
(see section 6.1-3)

EFs developed and installed in library mode must, without fail, have different names. Be
careful not to use PL7 key words as names (see section 6.2).
It is only possible to exit from the description tab once all the fields have been filled in.
This action confirms the parameters entered.

It is possible to delete an EF using the Delete command from the Utilities menu.

___________________________________________________________________________
19
 Managing the EF using PL7 SDKC

Clicking on the "Interface" tab opens the following area, comprising three zones which
are used to enter the EF formal parameters.
These formal parameters are those for inputs, outputs, and I/O.

These function call parameters are divided into three fields :

• the name, which contains a maximum of four characters (no spaces),
• the parameter type : Inputs, Outputs and I/O. One of the following must be selected :
BOOL, EBOOL, WORD, DWORD, STRING, AR_D, AR_W and AR_X (to check the
meaning of all of these types, see section 6.1 and the PL7 manual).
• the comment, which contains a maximum of 80 characters.

Example :

Reminder of the name of the

class and EF concerned

Buttons used to
change the order
of the parameters
in the selected
grid

At the formal parameters level, there is a maximum of 7 inputs, 7 outputs and 17 I/O.
It is possible to delete one or more parameter lines by selecting the line and clicking on
the corresponding number. Type Ctrl+x on the keyboard (Ctrl+v repastes what has been
cut).

For the correspondence between PL7 types defined in this tab and C types present in
the function header, see the table in section 6.1.

___________________________________________________________________________
20
 Managing the EF using PL7 SDKC

Clicking on the ".C Source" tab opens the following area :

Toggle button (Normal size/

Full screen) reduces/enlarges These buttons are used to import
the entry window or export a C file

This tab accesses C code editing. The user can use his own editor if he wishes or if the
C file is greater than 64 K, using export and import.

As with other standard tools on the market, comments containing special key words are
generated.
When PL7 SDKC creates the function header for the first time, the key words
PL7SDK_BEGIN_FUNCTION_NAME and PL7SDK_END_FUNCTION_NAME are
inserted automatically.

On exiting this tab, or when modifying the interface in the previous tab, PL7 SDKC
automatically generates this header, which ensures consistency between the declared
interface and the interface in the code.

Using the Edit menu, the current functions are offered by EditText (cut, copy, paste, find,
replace).
Other functions are available, such as :
• Selecting by double-clicking
• Displaying the line number corresponding to the present position of the cursor, in the
Status Bar.

___________________________________________________________________________
21
 Managing the EF using PL7 SDKC

To inform the user of errors resulting from the C source compilation, the source code line
containing the error is indicated.
A file giving the results of the compilation is generated. It can be accessed by the View
generation results command in the Family menu and provides information on any errors.

Definition of the EF interface automatically generates the prototype of the latter in the
FILE MAINxxyy.C where xx is the class code and yy the EF code. The user can export
the source if he wishes, work on it, and then re-import it.
There is no subsequent check on any manual modifications made to the EF main
function interface. If the user modifies the interface, these modifications will be ignored.
The interface is automatically regenerated from the interface tab.
If the file is too large to be displayed this will be indicated. However, the function
prototype will still be generated automatically.

• the user works with the editor supplied, and reaches the limit of 64K for the current
EF.
At that moment the following message is displayed :

«Your file is too large to be edited using PL7SDKC. Please export it, then re-import
it».

• the user prefers to work with his "favorite" editor.

This is possible; work is made easier by exporting one file at a time. Use the following
procedure :

create your EF,

create your interface then enter the code tab,
export the C file,
work in your editor then save, without changing the name,
import into PL7 SDKC.

___________________________________________________________________________
22
 Managing the EF using PL7 SDKC

Clicking on the ".H Source" tab opens the following area :

T o g g l e
button (Nor-
mal size/Full
screen)
reduces/
enlarges the
e n t r y
window

This area is used to define constants, types or structures specific to the EF.
This file must be ≤ 64 Kbytes.

___________________________________________________________________________
23
 Managing the EF using PL7 SDKC

3.2 Generating the family in debug mode

Once the creation phase is complete, it is possible to proceed to generation of the family
in debug mode. To do this, select Generate all Debug from the Family menu as shown
in the screen below.

The role of this generation is to activate the various software tools used to obtain a new
family (all classes) and to check data consistency along the whole generation string.

If there is a problem, a screen indicating the nature of the error(s) to be corrected opens,
so that generation can be relaunched.

Partial generation (Generate from the Family menu) can save time if the family has
several classes and the modifications only affect one class. In this case, the
unmodified classes are not regenerated.

It is possible to monitor the generation process from the information line at the bottom
of the screen. Once generation is complete, the message "x error(s), y warning(s)" is
displayed and an audio beep emitted.
A "Generated in Debug mode" status followed by a generation date is written in the family
description zone, and this family can then be installed in the library.

Information about the generation can be accessed by opening the results file (View
generation results from the Family menu).

___________________________________________________________________________
24
 Managing the EF using PL7 SDKC

3.3 Generating the family in release mode

The last phase is to proceed to generation of the family in release mode (code size
minimized). To do this, select Generate all Release from the Family menu as shown in
the screen below.

The role of this generation is to activate the various software tools used to obtain a new
family (all classes) and to create the corresponding files.

Partial generation (Generate from the Family menu) can save time if the family has
several classes and the modifications only affect one class. In this case, the
unmodified classes are not regenerated.

It is possible to monitor the generation process from the information line at the bottom
of the screen. Once generation is complete, the message "x error(s), y warning(s)" is
displayed and an audio beep emitted.
A "Generated in Release mode" status followed by a generation date is written in the
family description zone.

Information about the generation can be accessed by opening the results file (View
generation results from the Family menu).

Once generation is complete, the necessary elements (files) are automatically copied
into the medium selected for broadcasting (diskette, network disk, etc). This space is
part of the parameters defined in the tool customization menu (see section 5.1)

___________________________________________________________________________
25
 Managing the EF using PL7 SDKC

3.4 Installing/Uninstalling in the PL7 library

It is possible to install a family generated in debug or release mode on the development

station, but only families generated in debug mode can be debugged in PL7.
To perform this installation, select Install from the Family menu.

If the code of the family to be installed already exists in the library, a dialog box opens

If the family is new and intended to replace an old one, click on "Overwrite".

If an error is made, or the user is unsure, it is possible to cancel installation in the library
by selecting Quit.

When installation is complete, the message "The family has been installed in the library"
appears and installation is effective.

It is possible to uninstall a family from the PL7 library. It is necessary to select the
Uninstall command from the Family menu when a family is being edited.
___________________________________________________________________________
26
 Section
Testing the EF using the debugging tool4
4 Testing the EF using the debugging tool
4.1 Accessing EF debugging

4.1-1 Selecting the family of the EF to be tested

As described in the previous section, the EFs of families generated in debug mode can
be debugged, one at a time, in PL7 Micro and Junior.
Once PL7 is launched and the program containing the EF to be tested loaded into the
PLC, the Debug EF command in the Application menu opens the following screen which
is used to select the development directory (dvt_ef, by default), then the family
containing the EF.

The name of the family (generated in debug mode) and its code number appear

Used to search
for the drive and
the development
directory

Summary of
information
about the
family

Once the family containing the EF to be tested has been found, clicking on OK opens
the EF debug environment, described in the next paragraph.

4.1-2 Opening the EF debug screen

This screen is made up of two parts :

• A command part with seven buttons,
• A part containing information about the test
___________________________________________________________________________
27
 Testing the EF using the debugging tool

Opening the screen adds a "Debug EF" menu to the PL7 menu bar.

Selecting the EF command from the Debug EF menu, or clicking on the button
(2nd button from the left), opens the screen used to select the EF to be tested.

In our example, there is only one EF in the family (the "MAX_TABW" EF which we wish
to test), the code of the class to which it belongs, its EF code, its name and its comment
appear.
Clicking on OK opens a screen which gives the C source of the EF (see section 4.3-1).

Depending on the complexity of the EF, it may take several seconds to access this
screen.

___________________________________________________________________________
28
 Testing the EF using the debugging tool

4.2 Presentation of the tool

The tool commands are

accessed from a scrolling
menu and/or by buttons.
All the commands are
described below :

(1st button from the

left) : is used to exit
the EF debug tool.

(3rd button from the

left) : is used to insert/
remove a breakpoint.

(4th button from the left) or the Go command from the Debug EF menu is used
to relaunch the PLC from the breakpoint or current step.

(5th button from the left) or the Step Into command from the Debug EF menu :
is used to go inside a function (if the function is present in the C source of the EF).

(6th button from the left) or the Step Over command from the Debug EF menu:
is used to skip a function (step over).

(7th button from the left) or the Step Out command from the Debug EF menu :
is used to exit a C function comprising a EF.

• the Registers command in the Debug EF menu is used to display a list of all the
registers used by the CPU µprocessor (see section 4.3-3).
• the Local variables command in the Debug EF menu is used to display a list of
variables used locally (see section 4.3-4).
• the Mix C/Asm command in the Debug EF menu is used to change from a presentation
in C language to a presentation in C language and in assembly language.
• the Breakpoints command from the Debug EF menu is used to display a screen giving
information on the position of breakpoints.
• the Step to Cursor command from the Debug EF menu is used to relaunch the PLC,
from the step where it is stopped back to the cursor.
___________________________________________________________________________
29
 Testing the EF using the debugging tool

4.3 Debugging EFs

Following the procedure described above (see section 4.2-1), the C source code of the
EF is displayed on-screen and debugging can begin.
It will be possible, using the tool commands and buttons, to perform all the usual debug
operations, namely :
• Insert and remove breakpoints,
• Proceed step by step,
• Scroll through part of the program,
• Go inside a function,
• Analyze using the lists of registers and local variables,
• Edit the EF in C code and assembly language, to meet the needs of a more precise
analysis of part of the program which could cause problems.

4.3-1 Inserting and removing breakpoints

Select a line by pointing the cursor at it, then press the button to insert a
breakpoint on this line. The same button is used to remove a breakpoint. Up to 7
breakpoints can be inserted simultaneously.
A breakpoint is indicated by a blue line. It is thus possible to insert or remove all the
breakpoints desired.
If the PLC is running and if the program moves to one of the breakpoints, the line in
question becomes yellow.
Using the , , buttons, it is easy to enter/exit from a function or skip a
function.

Extract of the EF C
source code with two
breakpoints (one blue
line, one yellow line)

___________________________________________________________________________
30
 Testing the EF using the debugging tool

4.3-2 Mixing C code and assembly language

The Mix C/Asm command from the Debug EF menu is used to change from a
presentation in C language to a presentation in C language and in assembly
language.

4.3-3 Registers

The Registers command in the Debug EF menu is used to display a list of all the registers
used by the CPU µprocessor, as well as the contents of the execution stack which
contains the local variables and the parameters of the function in which the program has
stopped.

___________________________________________________________________________
31
 Testing the EF using the debugging tool

4.3-4 Local variables

The Local variables command from the Debug EF menu is used to display a list of the
local variables and parameters of the function in which the program has stopped.

All the numerical values displayed in this screen are expressed in hexadecimal
format.

The syntax used to define the types of local variables and parameters is described
below :
+: the "plus" sign indicates that the object on the line can be expanded.
- : the "minus" sign indicates that the object on the line can be shrunk.
{...} : indicates that the corresponding object is a structure.
[] : indicates that the corresponding object is a table.
0xabcd:0xabcd : indicates that the corresponding object is a pointer. By expanding
it, the type of object pointed to will appear.
%xxxxxxxx : where x takes the value 0 or 1, this indicates that the
corresponding object is a bit field.

___________________________________________________________________________
32
 Testing the EF using the debugging tool

To exit at the end of an EF debug session, use either the tool button, or the usual
commands for exiting a Windows screen.

If a problem arises during an EF test, and it was not possible to close the debug
EF tool, the application will have to be reloaded into the PLC before restarting a
session.

___________________________________________________________________________
33
 Testing the EF using the debugging tool

___________________________________________________________________________
34
 Additional SDKC functions5
Section
5 Additional SDKC functions
5.1 Setting the tool parameters
The Customize command in the Utilities menu opens the following window. Here,
parameters can be set for a number of working directories which assist operation of the
tool.

Directory where EF family files

(by default) will be placed

Directory (by default) where files

used to install an EF family will be
placed

Working disk (C:\) where the

program creates/deletes its
temporary working files

Directory (by default) where

the imported/exported class
files will be placed

Directory (by default) where the C

language source files, due to be
imported/exported, will be placed

The arrows located to the right of each field open a dialog box where another disk/
directory can be selected for that field.

___________________________________________________________________________
35
 Additional SDKC functions

5.2 Modifying a family

Once a family name and version number have been associated with a family code, the
only way to change the parameter(s) is to select the family (shown in reverse video) and
then select Modify from the Family menu.

This action opens the "Name" and "Version" fields, where data can be entered.

This step could prove useful, for example, if the version number of a family needed
changing after being updated.

Clicking on "Confirm" takes this modification into account and opens the family, so that
a class/EF can be created/viewed (see section 3.1.2, section 3.1.3).

___________________________________________________________________________
36
 Additional SDKC functions

5.3 Importing/Exporting

5.3-1 Class

When a family is open, two commands in the Utilities menu are used to import and/or
export class(es) into/from this family.

Exporting a class consists of copying the class into the appropriate directory defined
when customizing the tool (see section 5.1).

Example : "Program" family, "Class1" class :

(the "import-export class" directory is : C:\SDKCWTMP\IMPCLASS by default)

When the "Class1" class of this family is exported, a file called " CLASSE01.EXP",
containing all the intrinsic elements of this class, is copied into the directory.
Once export is complete, the message : The "Class1" class was successfully exported
to "C:\SDKCWTMP\IMPCLASS\CLASSE01.EXP" indicates that the operation is
complete.

Caution : The "CLASSE01.EXP" file overwrites any existing "CLASSE01.EXP"

and no warning message appears.

The group of two numbers at the end of the file name "CLASSE01" indicates the code
for the class in hexadecimal format (code 1 class, in this example).
"Import-Export class" files are distinguished by the suffix .EXP.

Importing a class consists of opening the following screen,

which displays the contents of the "Import-export class" directory referred to earlier, and
choosing the file corresponding to the class you wish to import into a family.
___________________________________________________________________________
37
 Additional SDKC functions

Example : If you wish to import a class1 into the "Program" family

Select the " CLASSE01.EXP" file, which contains all the intrinsic elements of this class,
and click on OK.

There are two possible scenarios :

• No code 1 class existed in this family, clicking on OK causes a copy to be made, and
the code 1 class and its EF appear on the left of the screen.
• A code 1 class already existed in the "Program" family, clicking on OK brings up the
following message :

Yes will import the new class (all the intrinsic elements of this class) and will
overwrite the old class with the same code (all the intrinsic elements of that
class).
No cancels the import instruction and reverts to the initial situation.

5.3-2 C Source

From the "C Source" tab of an EF, two buttons can be used to import and/or export the
C Source code from another EF.

Exporting the C Source of an EF consists of copying the code into the appropriate
directory defined when customizing the tool (see section 5.1).

Example : "Program" family, "Class1" class, EF "MAX_TABW" :

(the C source "import-export directory" is : C:\SDKCWTMP\IMPSRC by default)

When the content of the C Source tab of the "MAX_TABW" EF is exported, this code is
copied into a file "MAIN0101.C" in the directory.
Once export is complete, the message : The "MAIN0101.C" source file has been copied
to "C:\SDKCWTMP\IMPSRC\MAIN0101.C", indicates that the operation is complete.

Caution : The "MAIN0101.C" file overwrites any existing "MAIN0101.C" and no

warning message appears.
___________________________________________________________________________
38
 Additional SDKC functions

The two groups of two numbers at the end of the file name "MAIN0101" indicate the class
code followed by the EF code (code 1 class, code 1 EF, in this example). These codes
are expressed in hexadecimal format.
"Import-Export C Source" files are distinguished by the suffix .C.

This type of MAINxxxx.C file can be opened by a commercial C editor (more sophisticated).

Once the C file exceeds the limits of the edit zone (64 Kbytes), this type of editor must
be used.

Importing the C Source of an EF consists of opening the following screen,

which displays the contents of the "Import-export C sources" directory referred to earlier,
and choosing the file corresponding to the C Source code you wish to import into the EF.

Example : If you wish to import the C Source contained in the file "MAIN0102.C"

Select this file and click on OK. This brings up the following message :

OK imports the new C Source code and overwrites the old one.
Cancel reverts to the initial situation.

___________________________________________________________________________
39
 Additional SDKC functions

5.4 Archiving/Restoring a family

5.4-1 Archiving

Once a family has been created, and its class(es) and EF(s) have been created and their
parameters set, it is advisable to archive it.
This operation is performed by activating the Archive command in the Family menu, as
indicated on the following screen :

Depending on which is selected, these boxes can

display normal and/or archived families on the left of
the screen

Once the family has been archived, if archive display is selected, the archive appears
on the left-hand side of the screen. When the archive is selected, a screen appears
which contains the main characteristics of the archived family.
A zone opens where comments about the archive can be entered ; these comments will
be extremely useful if the archive is ever retrieved.

Entry zone for comments

(4 lines maximum)

___________________________________________________________________________
40
 Additional SDKC functions

5.4-2 Restoring

The object of the "Restore" function is to replace a given family with a previously
archived one. This function is performed by activating the Restore command on the
Family menu, as indicated on the following screen :

As the restore operation overwrites the current family, a confirmation message

appears :

OK restores the family. Cancel reverts to the initial situation.

When executing the Archive/Restore functions, the files created or manipulated are to
be found in the directory defined in the customization screen (see section 5.1) under the
item : General directory of EF families (C:\DVT_EF by default). These files are called,
respectively :
• CRD_xxxx.yyy : for the family datasheet
• CAT_xxxx.yyy : for information about the family
• FAM_xxxx.yyy : for the complete archive
where xxxx corresponds to the family code in hexadecimal format, and yyy to the archive
number.
___________________________________________________________________________
41
 Additional SDKC functions

___________________________________________________________________________
42
 The EF code6
Section
6 The EF code
6.1 Rules for implementing EFs

6.1-1 C Language

No. 1 Static variables must not be defined in an EF.

No. 2 Unions must not be defined in a structure. They should have been defined
earlier, outside the structure.
No. 3 If a pointer is used as a parameter or local function variable, it must be declared
as a far pointer.
Example : int far* pVariableLocale
No. 4 A bit field must not be defined with length 0.
No. 5 The C language "switch" instruction must not be used in the code for an EF.
No. 6 Floating point numbers must not be used in an EF.
No. 7 The types of formal parameter for an EF are specific to the PL7 languages (refer
to the PL7 Micro or Junior documentation), and these are automatically converted
in the C function header as shown below :

PL7 formal Input Output Input/Output

parameter parameter parameter parameter

BOOL short adrNFBIT adrNFBIT

EBOOL adrFBIT adrFBIT adrFBIT

WORD short adrSCAL adrSCAL

DWORD long adrSCAL adrSCAL

STRING adrTABLE adrTABLE adrTABLE

AR_X adrTABLE adrTABLE adrTABLE

AR_W adrTABLE adrTABLE adrTABLE

AR_D adrTABLE adrTABLE adrTABLE

No. 8 The types and constants shown on the next page are an extract from the
CSTSYST.H file, which is included automatically at the beginning of each C
source describing an EF.

___________________________________________________________________________
43
 The EF code

//Definition of constants

// Status values listed in the directory

#define STATUS_OK
#define OUT_OF_BOUNDS
#define NULL_RW_SIZE
#define CLOCK_UNAVAILABLE
#define CLOCK_NOT_SUPPORTED
#define INVALID_LENGTH

#define NIL
#define NILL
#define INVALID_ADDRESS
#define NULL_FPTR

// Possible types of action on forceable bit strings (wr_bits)

#define DATA_WRITE // Write data field
#define RVALUE_WRITE // Write fallback value field (TSX57
only)
#define RVALID_WRITE // Write fallback value validation
// field (TSX57 only)
#define DEFAULT_WRITE // Write fault (TSX57 only)
#define UNFORCE_ALL // Unforce bits globally

#define GAMME_TSX37 4
#define REFCAT_TSX37_10 1
#define REFCAT_TSX37_21 2
#define REFCAT_TSX37_22 3

#define GAMME_TSX57 5
#define REFCAT_TSX57_10 1
#define REFCAT_TSX57_20 2

//Definition of types
#define BOOL short
#define BYTE unsigned char
#define WORD unsigned short
#define DWORD unsigned long

//Definition of structures
typedef struct {
void __near *off; // Offset
unsigned short sel; // Selector number
}PTR_LOG;

___________________________________________________________________________
44
 The EF code

typedef struct {
unsigned short selecteur;
unsigned short offset;
} adrSCAL;

typedef struct {
unsigned short selecteur;
unsigned short offset;
unsigned short taille; // Size of table or string
} adrTABLE;

typedef struct {
unsigned short selecteur;
unsigned short offset;
} adrFBIT;

typedef struct {
unsigned short selecteur;
unsigned short offset;
unsigned short rang; // discrete value : 0..15
} adrNFBIT;

typedef struct {
unsigned char gamme; // Processor range
unsigned char version; // OS version present in the
processor
unsigned char codecat; // Catalog reference code for
the CPU model
unsigned char unused;
} PROC_IDENT;

typedef struct {
unsigned char reserved ;
unsigned char Second ;
unsigned char Minut ;
unsigned char Hour ;
unsigned char DayMonth ;
unsigned char Month ;
unsigned char Year ;
unsigned char Century ;
unsigned char DayWeek ;
} DATE_TIME ;

___________________________________________________________________________
45
 The EF code

typedef struct {
unsigned Run : 1; /* 1 if run */
unsigned AppliExec : 1; /* 1 if compatibility index between
appli and processor ok */
unsigned CartMemDetect :1; /* 1 if mem. cart. detected */
unsigned Reservation : 1; /* 1 if reservation applied */
unsigned BrkptSet : 1; /* 1 if brkpt set */
unsigned AppliFailure : 1; /* 1 if appli «halted» */
unsigned PartialRun : 1; /* 1 if partial run */
unsigned CartFlashErase : 1; /* 1 if the FEPROM mem. cart. */
/* is being erased */
unsigned UserMemProtect : 1; /* 1 if the application memory */
/* is write-protected */
unsigned Reserved : 7; /* reserved bits */
} PROC_INDIC ;

6.1-2 Managing family and EF versions

A version number (VV.RR format) is allocated to an EF family and to each class in the
family.
A text information compatibility index is allocated to an EF family. If the family versions
in the library and an application are inconsistent, this indicator can be used to determine
the validity of help information associated with the EFs (general comment, name and
comment for its parameters) which make up the family.

No. 9 For a family already installed in the library, any modification within a class
must without fail involve upgrading its version number (the index and/or the
release index), as well as the version number of the family to which it belongs.
Adhering to this rule is compulsory in order to be able to update existing PL7
applications which contain EFs of the class in an older version.
Caution : the version number of a family does not necessarily correspond to the
highest version number associated with the classes it contains.
Example : a version 2.1 family F, consisting of classes C1, C2 and C3 which are
versions 1.0, 2.1 and 1.0 respectively.
If class C1 develops from 1.0 to 1.1, the version of family F should change from
2.1 to 2.2 at minimum.

___________________________________________________________________________
46
 The EF code

No. 10 A new EF family version must still be completely compatible with the
previous version :

• no EF must disappear from the family,

• an EF must not change its call interface (a new EF must be created, with
a different name if the prototype is to change, and the old EF must be
retained).

No. 11 The "text information compatibility index" of an EF family must be incremented

if (and only if) this family is updated in such a way that the existing help
information is no longer relevant.

Note : during the EF debug phase, it is advisable to assign version numbers to classes
and families starting from 0.01, in order to subsequently be able to assign version 1.0
to the marketed product.

6.1-3 Managing the size of the stack

It is the user's responsibility to manage the size reserved for the EF execution stack. It
is important to make an accurate calculation, as :
• if it is too small, the PLC will show an error.
• if it is too large, there is that much less space for the PLC data memory.
To calculate the size, add together the sizes of :
• the EF parameters and local variables,
• the parameters and local variables of the functions which it calls, by examining the
longest call tree.

___________________________________________________________________________
47
 The EF code

6.2 List of reserved words

The words in the following list (arranged in columns, in alphabetical order) are or will be
used by PL7, and must not be used as EF names :

ABS CALL_COIL DSORT_ARW FIND

ACCEPT CANCEL DT FIND_EQ
ACOS CASE DTS FIND_EQD
ACTION CD DWORD FIND_EQW
ACTIVATE_PULSE CHART D_BIT FIND_GTD
ACTIVE_TIME CH_M E FIND_GTW
ADD CLK EBOOL FIND_LTD
ADDRESS CLOSE ELSE FIND_LTW
ADD_DT CLOSED_CONTACT ELSIF FOR
ADD_TOD COIL EMPTY FROM
ADR COMMAND EMPTY_LINE FUNC
AND COMMENTS END FUNCTION
ANDF COMP4 ENDC FUNCTION_BLOCK
ANDN COMPCH ENDCN F_B
ANDR CONCAT END_ACTION F_EDGE
AND_ARX CONF END_BLK F_TRIG
ANY CONFIGURATION END_BLOCK GE
ANY_BIT CONSTANT END_CASE GET
ANY_DATE CONTROL_LEDS END_COMMENTS GET_MSG
ANY_INT COPY_BIT END_CONFIGURATION GET_VALUE
ANY_NUM COS END_FOR GLOBAL_COMMENT
ANY_REAL CTD END_FUNCTION GR7
ARRAY CTU END_FUNCTION_BLOCK GRAY_TO_INT
AR_D CTUD END_IF GT
AR_F CU END_MACRO_STEP GTI
AR_W D END_PAGE
AR_X H
DATE END_PHRASE HALT
ASIN DATE_AND_TIME END_PROG
ASK HALT_COIL
DAT_FMT END_PROGRAM HASH_COIL
ASK_MSG DAY_OF_WEEK END_REPEAT
ASK_VALUE H_COMPARE
DA_TYPE END_RESOURCE H_LINK
ASSIGN_KEYS DEACTIVATE_PULSE END_RUNG
AT DEC END_STEP I
ATAN DELETE END_STRUCT IF
AUX DELTA_D END_TRANSITION IL
BCD_TO_INT DELTA_DT END_TYPE IN
BIT_D DELTA_TOD END_VAR INC
BIT_W DINT END_WHILE INCJUMP
BLK DINT_TO_REAL EQ INDEX_CH
BLOCK DINT_TO_STRING EQUAL INFO
BODY DISPLAY_ALRM ERR INITIAL_STEP
BOOL DISPLAY_GRP EVT INIT_BUTTONS
BOTTOM DISPLAY_MSG EXCHG INPUT
BTI DIV EXCH_DATA INPUT_CHAR
BTR DMOVE EXIT INSERT
BY DO EXP INT
BYTE DOWN EXPT INTERVAL
DRUM INT_TO_BCD
C F INT_TO_REAL
DS FALSE
CAL DSHL_RBIT INT_TO_STRING
CALC FAST ITB
DSHRZ_C FBD
CALCN DSHR_RBIT ITS
FE
CALL DSORT_ARD FIFO JMP
___________________________________________________________________________
48
 The EF code

JMPC NB_ACTIVE_STEPS PLC RS

JMPCN NB_ACTIVE_TIME POST RTB
JUMP NB_BLOCKS PRESET RTC
JUMP_COIL NB_COMMON_WORDS PRINT RTS
L NB_CONSTANT_WORDS PRINT_CHAR RUNG
LAD NB_CPT PRIO0 R_EDGE
LANGUAGE NB_DRUM PRIO1 R_TRIG
LANGUAGE NB_INTERNAL_BITS PRIORITY S
LD NB_INTERNAL_WORDS PRL S1
LDF NB_MACRO_STEPS PROG SAVE_PARAM
LDN NB_MONO PROGRAM SCHEDULE
LDR NB_PAGES PROG_LANGUAGE SD
THE NB_REG PROG_LANGUAGE SEARCH
LEFT NB_TIMER PT SEL
LEN NB_TM PTC SEMA
LIFO NB_TRANSITIONS PUT SEND
LIMIT NE PV SENDER
LINT NIL PWM SEND_ALARM
LIST NO P_CONTACT SEND_MBX_ALARM
LIT NON_STORED Q SEND_MBX_MSG
LN NOP QUERY SEND_MSG
LOCATION NOT SEND_REQ
NOT_ARX R
LOG R1 SEND_TLG
LREAL NOT_COIL SERVO
NOT_READABLE RCV_TLG
LT RE SET
LWORD NO_GR7 SET_COIL
NO_PERIOD READ
M READ_EVT_UTW SFC
N_CONTACT SHIFT
MACRO_STEP READ_ONLY
MAIN O READ_PARAM SHL
MASKEVT OCCUR READ_STS SHOW_ALARM
MAST OCCUR_ARD READ_VAR SHOW_MSG
MAX OCCUR_ARW READ_WRITE SHOW_PAGE
MAX_ARD OF REAL SHR
MAX_ARW ON REAL_TO_DINT SHRZ
MAX_PAGES OPEN REAL_TO_INT SIN
MAX_STEP OPEN_CONTACT REAL_TO_STRING SINGLE
MCR OPERATE REG SINT
MCR_COIL OR REM SL
MCS ORF REPEAT SLCWORD
MCS_COIL ORN REPLACE SMOVE
MID ORR RESET SOFT_CONFIGURATION
MIN OR_ARX RESET_COIL SORT
MIN_ARD OTHERS RESOURCE SORT_ARD
MIN_ARW OUT RESTORE_PARAM SORT_ARW
MOD OUTIN_CHAR RET SQRT
MONO OUTPUT RETAIN SR
MOVE OUT_BLK RETC ST
MPP P RETCN STANDARD
MPS P0 RETURN START
MRD P1 RET_COIL STD
MS PAGE RIGHT STEP
MUL PAGE_COMMENT ROL STI
MUX PANEL_CMD ROL_ARD STN
M_CH PERIOD ROL_ARW STOP
M_MACRO_STEP PHRASE ROR STR
PHRASE_COMMENT ROR_ARD STRING
N STRING_TO_DINT
N1 PID ROR_ARW
PID_MMI RRTC STRING_TO_INT
NAME STRING_TO_REAL
___________________________________________________________________________
49
 The EF code

STRUCT WORD
SUB WRITE
SUB_DT WRITE_CMD
SUB_TOD WRITE_PARAM
SUM WRITE_VAR
SU_TYPE WRTC
S_T_AND_LINK WSHL_RBIT
S_T_OR_LINK WSHRZ_C
T WSHR_RBIT
TAN W_BIT
TASK XM
TASKS XM_MONO
THEN XM_MULTI
TIME XOR
TIMER XORF
TIME_OF_DAY XORN
TMAX XORR
TMOVE XOR_ARX
TO YES
TOD
TOF
TOFF
TON
TOP
TP
TRANSITION
TRANS_TIME
TRUE
TRUNC
TYPE
TYPES
T_S_AND_LINK
T_S_OR_LINK
U
UDINT
UINT
ULINT
UNMASKEVT
UNTIL
UP
USINT
USORT_ARD
USORT_ARW
UTIN_CHAR
VAR
VAR_ACCESS
VAR_EXTERNAL
VAR_GLOBAL
VAR_INPUT
VAR_IN_OUT
VAR_OUTPUT
VERSION
V_COMPARE
V_LINK
W
WHILE
WITH
___________________________________________________________________________
50
 System functions7
Section
7 System functions

System functions present in the PLC CPU can be called within the body of an EF.
They are as follows :

• rd_sysbit : read a system bit %Si

• wr_sysbit : write a system bit %Si
• rd_sysword : read a system word %SWi
• wr_sysword : write a system word %SWi
• rd_bit_attrib : read a bit from the forceable memory
• rd_bits : read several consecutive bits in the forceable memory
• wr_bits : write several consecutive bits in the forceable memory
• rd_16bits : read the value of 16 consecutive bits in the forceable memory
• wr_16bits : write the value of 16 consecutive bits in the forceable memory
• rd_1bit : read the value of a bit in the forceable memory
• wr_1bit : write the value of a bit in the forceable memory
• phy_ptr_init : convert a logic address to a physical address
• date_and_time : read the current PLC date and time
• cnt_100ms : read the value of an internal counter with a rate of 100 ms
• cnt_10ms : read the value of an internal counter with a rate of 10 ms
• proc_type : read the processor type
• proc_indic : read memory configuration data

Note : As it is possible, using these functions, to write to the PLC memory, the user
should take certain access precautions.
Example : Once a table has become an EF parameter, be careful not to access words
outside this table. This can be checked by testing the length of the table.

The following pages describe these functions, their parameters and the types used, with
the help of examples.

___________________________________________________________________________
51
 System functions

value = rd_sysbit ( sysbit_range , status )

unsigned short value

unsigned short sysbit_range
unsigned short far * status

Description
Reads system bit %Si identified by its number.
The consistency of the bit number is checked.

Input parameters
sysbit_range : Logical address of the bit to be read.
status : Far pointer on the system status word.

Feedback
When the status is STATUS_OK, the bit value is entered in the least significant bit ;
Bits numbers 1..15 are set to zero.
A bit number outside these limits produces the status value OUT_OF_BOUNDS.

Examples
//Reading system bit %S4

unsigned short Value;

unsigned short far Status;
Value = rd_sysbit (4,(unsigned short far *) & Status);

___________________________________________________________________________
52
 System functions

status = wr_sysbit ( sysbit_range , value )

unsigned short status

unsigned short sysbit_range
unsigned short value

Description
Writes system bit %Si identified by its number.
The consistency of the bit number is checked.

Input parameters
sysbit_range : Logical address of the bit to be written.
value : Value to be written ; only the least significant bit is taken into
account.

Feedback
The bit write report.
This is STATUS_OK when the write operation is accepted by the system.
A bit number outside these limits produces the status value OUT_OF_BOUNDS.

Examples
//Writing value 0 in system bit %S10

unsigned short Status;

unsigned short Value;
Status = wr_sysbit (10,0);

___________________________________________________________________________
53
 System functions

value = rd_sysword ( sysword_range , status )

unsigned short value

unsigned short sysword_range
unsigned short far * status

Description
Reads system word %SWi identified by its number.
The consistency of the word number is checked.

Input parameters
sysword_range : Logical address of the word to be read.
status : Far pointer on the system status word.

Feedback
When the status is STATUS_OK, the word value is entered in the function feedback
value.
A word number outside these limits produces the status value OUT_OF_BOUNDS.

Examples
//Reading system word %SW48 (event number)

unsigned short Value;

unsigned short far Status;
Value = rd_sysword (48,(unsigned short far *) & Status);

___________________________________________________________________________
54
 System functions

status = wr_sysword ( sysword_range , value )

unsigned short status

unsigned short sysword_range
unsigned short value

Description
Writes system word %SWi identified by its number.
The consistency of the word number is checked.

Input parameters
sysword_range : Logical address of the word to be written.
value : Value to be written.

Feedback
STATUS_OK when the write operation is successful.
A word number outside these limits produces the status value OUT_OF_BOUNDS.

Examples
//Writing value 10 in system word %SW48

unsigned short Status;

unsigned short Value;
Status = wr_sysword (48,10);

___________________________________________________________________________
55
 System functions

value = rd_bit_attrib ( address )

unsigned char value

adrFBIT address

Description
Reads a bit from the forceable memory identified by its address. The bits in the forceable
memory are : %Si, %Mi, %Xi, %Ii.j and %Qi.j.

Input parameters
address : Address of the bit to be read, type adrFBIT (see section 6.1-1).

Feedback
The attributes of the referenced bit, conforming to the structure of the forceable bit
memory.

TSX37 forceable bit : 3 significant bits

bit2 bit1 bit0

F H V

V : Value
H : Historic
F : Forcing

TSX57 forceable bit : 8 significant bits

bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0

Def. VR ER R r.F. F H V

V : Value
H : Historic
F : Forcing (local)
r.F. : Remote forcing
R. : Fallback value
ER : Fallback state only significant for I/O bits
VR : Fallback validation (Ii,j ; Qi,j)
Def. : Fault

___________________________________________________________________________
56
 System functions

Examples

//Reading the attributes of the bit corresponding to input 1 of slot 2

void far pascal FUNCTION(adrFBIT BitAddress)
{
unsigned char Valeur;
:
:
Valeur = rd_bit_attrib(AdresseBit);
:
:
}

___________________________________________________________________________
57
 System functions

value = rd_bits ( address , number , status )

unsigned long value

adrFBIT address
unsigned short number
unsigned short far * status

Description
Reads several consecutive bits in the forceable memory.

Input parameters
address : Address of the first bit to be read, type adrFBIT (see section 6.1-1).
number : Number of bits to be read, the length cannot exceed 32 bits.
status : Far pointer on the system status word.

Feedback
The value of the referenced bit string.
The function will not perform any processing if the number of bits requested is greater
than 32.
status is then INVALID_LENGTH.

Examples

//Reading 17 consecutive bits starting at %M1 which has become a parameter

void far pascal FUNCTION(adrFBIT FirstBit)
{
unsigned short far status;
unsigned long Valeur;
:
:
Valeur = rd_bits(PremierBit,17,(unsigned short far *) & Status);
:
:
}

___________________________________________________________________________
58
 System functions

status = wr_bits ( address , number , value , type )

unsigned short status

adrFBIT address
unsigned short number
unsigned long value
unsigned short type

Description
Writes consecutive bits of the forceable memory ; the function can be used to write up
to 32 bits located at the address provided on input.

Input parameters
address : Address of the first forceable bit to be written, type adrFBIT (see section
6.1-1).
number : Number of bits to be written ; this value must not exceed 32.
value : Values to be written to a double word.
type : Type of write operation to perform :
00h : DATA_WRITE : update values
04h : RVALUE_WRITE : write the fallback value
06h : RVALID_WRITE : write the fallback validation field
07h : DEFAULT_WRITE : write the fault to specified values
08h : global unforcing of bits (UNFORCE_ALL) : the «value» parameter is
not therefore significant

Feedback
The write report : STATUS_OK if the operation is successful.
The function will not perform any processing if the number of bits to be written is greater
than 32.
The function then returns INVALID_LENGTH.
The system returns UNAVAILABLE_SERVICE if it does not recognize the type of action
to be performed.

___________________________________________________________________________
59
 System functions

Examples
void far pascal FUNCTION(adrFBIT BitAddress)
{
unsigned short Status;
:
:
Status = wr_bits (AdresseBit,17,0x194AC,DATA_WRITE);
:
:
}

___________________________________________________________________________
60
 System functions

value = rd_16bits ( address )

unsigned short value

adrFBIT address

Description
Reads the value (data bit) of 16 consecutive bits in the forceable bit memory.
The EF using this utility must ensure the validity of the address which has become a
parameter ; the system does not check that the address refers to the PLC forceable bit
space, nor that the 16 bits are in this space.

Input parameters
address : Address of the first bit to be read, type adrFBIT (see section 6.1-1).

Feedback
The value of the referenced bit string.

Examples
void far pascal FUNCTION(adrFBIT BitAddress)
{
unsigned short Valeur;
:
:
Valeur = rd_16bits (AdresseBit);
:
:
}

___________________________________________________________________________
61
 System functions

wr_16bits ( address , value )

adrFBIT address
unsigned short value

Description
Writes the value of 16 consecutive bits of the forceable memory.
As the system does not perform any checks, the EF using this utility must ensure the
validity of the 16-bit address which has become a parameter.

Input parameters
address : Address of the first forceable bit to be written, type adrFBIT (see section
6.1-1).
value : Values to be written to a word.

Feedback
None

Examples
void far pascal FUNCTION(adrFBIT BitAddress)
{
:
:
wr_16bits (AdresseBit,0xAFC1);
:
:
}

___________________________________________________________________________
62
 System functions

value = rd_1bit ( address )

unsigned short value

adrFBIT address

Description
Reads the value (data bit) of a forceable bit.
The EF using this utility must ensure the validity of the address which has become a
parameter ; the system does not check that this is included in the PLC forceable bit
space.

Input parameters
address : Address of the bit to be read, type adrFBIT (see section 6.1-1).

Feedback
The value of the referenced bit (0 or 1).

Examples
void far pascal FUNCTION(adrFBIT BitAddress)
{
unsigned short Valeur;
:
:
Valeur = rd_1bit (AdresseBit);
:
:
}

___________________________________________________________________________
63
 System functions

wr_1bit ( address , value )

adrFBIT address
unsigned short value

Description
Writes the value of a forceable bit.
As the system does not perform any checks, the EF using this utility must ensure the
validity of the address of the bit which has become a parameter.

Input parameters
address : Address of the forceable bit to be written, type adrFBIT (see section
6.1-1).
value : Values to be written to a word : this is 0 or 1.

Feedback
None

Examples
void far pascal FUNCTION(adrFBIT BitAddress)
{
:
:
wr_1bit (AdresseBit,0);
:
:
}

___________________________________________________________________________
64
 System functions

result = phy_ptr_init ( sel_off )

void far* result

PTR_LOG sel_off

Description
This function determines a physical address from a logical reference in the format
selector : offset .

Input parameters
address : Logical address, type PTR_LOG, to be converted to a 32-bit physical
pointer (see section 6.1-1).

Feedback
The far pointer corresponding to the logical address provided on input.
In the event of failure (logical address not valid for this configuration), the function returns
INVALID_ADDRESS.

Examples
//Converting a logical address type adrTABLE to a physical address
void far* CalculAdrPhy(adrTABLE far* pwTable)
{
PTR_LOG SLog;
SLog.sel = pwTable->selecteur;
SLog.off = (unsigned short near *)pwTable->offset;
return(phy_ptr_init(SLog));
}

//Example of an EF for adding 2 words

void far pascal ADDITION(short A, short B, adrSCAL Result)
{
PTR_LOG SLog;
void far* pSomme;
SLog.sel = Result.selecteur;
SLog.off = (unsigned short near *)Resultat.offset;
pSomme = phy_ptr_init(SLog);
*pSomme = A+B;
}

___________________________________________________________________________
65
 System functions

status = date_and_time ( date_ptr )

unsigned short status

DATE_TIME far * date_ptr

Description
Reads the current PLC date and time.
The data is coded in BCD on 9 usable bytes (ie. 18 digits), in the format below.
Leap years can be handled.

D. / wk. Year Month Day Hour Minute Second reserved

[ 01..07 ] [ 0000...9999 ] [ 01...12 ] [ 01...31 ] [ 00...23 ] [ 00...59 ] [ 00...59 ] 00

x x x x x x x x x x x x x x x x x x

byte 8 byte 7&6 ............ ............ byte 2 byte 1 byte 0

Word 3 Word 2 Word 1 Word 0

Key : x is a digit = [ 0..9 ]

D./wk. is the day of the week = 01 : Monday
02 : Tuesday
03 : Wednesday
04 : Thursday
05 : Friday
06 : Saturday
07 : Sunday

Input parameters
date_ptr : A far pointer on the current date and time copy zone (9 bytes). The
DATA_TIME type is described in section 6.1-1

Feedback
The function returns CLOCK_UNAVAILABLE if it has not been able to update the result
zone (difficulty in accessing the realtime clock).
If the operation is successful (the date and time fields are filled in correctly), the status
is STATUS_OK.
The PLC responds with CLOCK_NOT_SUPPORTED if it has no realtime clock.

___________________________________________________________________________
66
 System functions

Examples

DATE_TIME Buffer;
Status = date_and_time(&Buffer);

___________________________________________________________________________
67
 System functions

value = cnt_100ms ( void )

unsigned long value

Description
The system reads the value of an internal counter with a timebase of 100ms.

Input parameters
None

Feedback
The value of the counter, which has the following characteristics :
• unsigned value, from 0 to 4 294 967 295
• reset to zero on cold restart and when system bit %S0 is set to 1
• not incremented during power outages

___________________________________________________________________________
68
 System functions

value = cnt_10ms ( void )

unsigned long value

Description
System counter with a timebase of 10ms.

Input parameters
None

Feedback
The value of the counter, which has the following characteristics :
• unsigned value, from 0 to 4 294 967 295
• reset to zero on cold restart only
• not incremented during power outages

___________________________________________________________________________
69
 System functions

info = proc_type ( void )

PROC_IDENT info

Description
Identifies the type of processor executing the application.

Input parameters
None

Feedback
A structure type PROC_IDENT (see section 6.1-1) containing various identification
data :
• the processor range on one byte :
04h : TSX37
05h : TSX57
• the SMART software version on the processor, on one byte :
- on the high order 4-bit byte, the version number
- on the low order 4-bit byte, the revision number (release)
• the CPU model catalog reference code on one word :
01h : REFCAT_TSX37_10
02h : REFCAT_TSX37_21
03h : REFCAT_TSX37_22
01h : REFCAT_TSX57_10
02h : REFCAT_TSX57_20

Examples

PROC_IDENT Info;
Info = proc_type( );

___________________________________________________________________________
70
 System functions

info = proc_indic ( void )

PROC_INDIC info

Description
Information about the application memory configuration in the PLC.

Input parameters
None

Feedback
A structure type PROC_INDIC (see section 6.1-1) containing information about :
• the PLC status :
- in Run, reserved, in Breakpoint stop, in Halt, in partial Run.
• the validity of the application
• the presence of a memory cartridge (if applicable)
• the type of application memory : non modifiable / modifiable

Examples

PROC_INDIC Info;
Info = proc_indic( );

___________________________________________________________________________
71
 System functions

___________________________________________________________________________
72
 Appendix8
Section
8 Appendix
8.1 Example

8.1-1 Defining the EF

The following example gives the procedure to follow in order to create an EF which will
extract the maximum value from a word table.

"Program" family definition screen (see section 3.1-1)

"Class1" class definition screen (see section 3.1-2)

___________________________________________________________________________
73
 Appendix

"MAX_TABW" EF definition screen (see section 3.1-3)

"MAX_TABW" EF Interface tab screen (see section 3.1-3)

___________________________________________________________________________
74
 Appendix

"MAX_TABW" EF .C Source tab screen (see section 3.1-3)

The part above the dotted line is the common part of the C source code, and is
automatically inserted by the tool.
The part below the dotted line represents the body of C source code, entered or imported
by the user (only the beginning is visible on this screen, the whole code is described on
the next two pages).

"MAX_TABW" EF .H Source tab screen (see section 3.1-3)

___________________________________________________________________________
75
 Appendix

EF C source code

//PL7SDK_BEGIN_FUNCTION_NAME
// do not modify the generated function prototype please
// The main EF Function must be the first in this file
#include <Cstsyst.h>

Header
#include <Fctsyst.h>
#include <C:\ASAWTEMP\SDKC\CLASSE01.H>
#include <C:\ASAWTEMP\SDKC\MAIN0101.H>
void far pascal MAX_TABW(
adrTABLE TAB,
adrSCAL MAX)
//PL7SDK_END_FUNCTION_NAME
{
adrTABLE far *pwTable=&TAB; /* table logical address structure pointer*/
short far *pcPhyTable; /* word table physical address pointer*/
short Resultat= TABLEVIDEMAX_ARW; /* init function result */
short TailleTab;
short I;
short far* pResultat;
PTR_LOG SLog;

SLog.sel = MAX.selecteur;
SLog.off = (unsigned short near *)MAX.offset;
pResultat = phy_ptr_init(SLog);

/* calculate the physical address of the input table and the size of the table*/
pcPhyTable = CalculAdrPhy(pwTable);
TailleTab = LimTableOk(pwTable);

/* if address is incorrect
or if the length of the table is zero
or if the length of the table is greater than LGMAXTBWORD)
increase S20 and set result ‡ TABLEVIDE (done on init)*/
if (((DWORD)pcPhyTable == NILL)||(TailleTab == 0))
{
SetS20();
}
/* if not */
else
{
/* search */
Resultat=*pcPhyTable;
for (I=PREMELEMENT;I<TailleTab;I++)
___________________________________________________________________________
76
 Appendix

{
if (*pcPhyTable>Resultat)
{
Resultat=*pcPhyTable;
}
pcPhyTable++;
}
}
/* fsi*/
*pResultat= Resultat;
}

//check the limits of a 32 Kb table

short LimTableOk(adrTABLE far *pwTable)
{
short Resultat = FALSE;
if ((pwTable->taille < LGMAXTBWORD)&&(pwTable->taille>0))
{
Resultat = pwTable->taille;
}
return(Resultat);
}

void far * CalculAdrPhy(adrTABLE far * pwTable)

{
PTR_LOG SLog;
// retrieve parameter identification parameters
SLog.sel= pwTable->selecteur;
SLog.off= (unsigned short near *)pwTable->offset;

// calculate the physical addresses of the parameters

return( phy_ptr_init (SLog));
}

// Setting system bit %S20 on parameter pointer fault

void SetS20 ( )
{
WORD Sysbit,Value,Status;
Sysbit =20;
Value = 1;
Status = wr_sysbit (Sysbit, Value); // call smart
}

___________________________________________________________________________
77
 Appendix

8.1-2 Generating a diskette and installing the family

To generate the installation diskette, first select Customize from the Utilities menu, to
set the parameters for the destination path.

Field for entering the drive where

files used for installing an EF family
will be placed

Generate Release will copy the files required to install the family in the PL7 library onto
the diskette in drive A:.

On the client station, insert the diskette in the drive, launch the SETUP.EXE file and
follow the installation procedure.

___________________________________________________________________________
78