Manual MPI IE

s
Preface, Contents
SIMATIC
PRODAVE MPI/IE V6.2
Introduction
1
Installation
2
Functions in PRODAVE
MPI/IE V6.2
3
Glossary, Index
Manual
01/2012
A5E03681152-01
Safety Guidelines
This manual contains notices you have to observe in order to ensure your personal safety, as well as to
prevent damage to property. The notices referring to your personal safety are highlighted in the manual
by a safety alert symbol, notices referring to property damage only have no safety alert symbol. The
notices shown below are graded according to the degree of danger.
Danger
!
indicates that death or severe personal injury will result if proper precautions are not taken.
!
indicates that death or severe personal injury may result if proper precautions are not taken.
!
Warning
Caution
with a safety alert symbol indicates that minor personal injury can result if proper precautions are not
taken.
Caution
without a safety alert symbol indicates that property damage can result if proper precautions are not
taken.
Notice
indicates that an unintended result or situation can occur if the corresponding notice is not taken into
account.
If more than one degree of danger is present, the warning notice representing the highest degree of
danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a
warning relating to property damage.
Qualified Personnel
The device/system may only be set up and used in conjunction with this documentation. Commissioning
and operation of a device/system may only be performed by qualified personnel. Within the context of
the safety notices in this documentation qualified persons are defined as persons who are authorized to
commission, ground and label devices, systems and circuits in accordance with established safety
practices and standards.
Prescribed Usage
Note the following:
!
Warning
This device and its components may only be used for the applications described in the catalog or the
technical description, and only in connection with devices or components from other manufacturers
which have been approved or recommended by Siemens.
Correct, reliable operation of the product requires proper transport, storage, positioning and assembly
as well as careful operation and maintenance.
Trademarks
All names identified by ® are registered trademarks of the Siemens AG.
The remaining trademarks in this publication may be trademarks whose use by third parties for their
own purposes could violate the rights of the owner.
Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and
software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency.
However, the information in this publication is reviewed regularly and any necessary corrections are
included in subsequent editions.
Siemens AG
Industry Automation
Postfach 4848
90026 NÜRNBERG
GERMANY
A5E03681152-01
01/2012
Copyright © Siemens AG 2012
Technical data subject to change
Preface
Purpose of the Manual
This manual gives you a complete overview of the PRODAVE MPI/IE V6.2
functions.
This manual is intended for those responsible for configuring, commissioning, and
servicing automation systems.
Required Basic Knowledge
You require a general knowledge in the field of automation engineering to be able
to understand this manual.
In addition, you should know how to use computers or devices with similar
functions (e.g programming devices) under Windows XP or Vista operating
systems.
Where is this Manual valid?
This manual is valid for the software package PRODAVE MPI/IE V6.2.
PRODAVE MPI/IE V6.1
A5E03681152-01
3
Preface
Further Support
If you have any technical questions, please get in touch with your Siemens
representative or agent responsible.
You will find your contact person at:
http://www.siemens.com/automation/partner
You will find a guide to the technical documentation offered for the individual
SIMATIC Products and Systems here at:
http://www.siemens.com/simatic-tech-doku-portal
The online catalog and order system is found under:
http://mall.automation.siemens.com/
Training Centers
Siemens offers a number of training courses to familiarize you with the SIMATIC
S7 automation system. Please contact your regional training center or our central
training center in D 90327 Nuremberg, Germany for details:
Internet: http://www.sitrain.com
4
PRODAVE MPI/IE V6.1
A5E03681152-01
Preface
Technical Support
You can reach the Technical Support for all Industry Automation and Drive
Technology products
• Via the Web formula for the Support Request
http://www.siemens.com/automation/support-request
Additional information about our Technical Support can be found on the Internet
pages http://www.siemens.com/automation/service
Service & Support on the Internet
In addition to our documentation, we offer our Know-how online on the internet at:
http://www.siemens.com/automation/service&support
where you will find the following:
• The newsletter, which constantly provides you with up-to-date information on
your products.
• The right documents via our Search function in Product Support.
• A forum, where users and experts from all over the world exchange their
experiences.
• Your local representative for Industry Automation and Drive Technology.
• Information on field service, repairs, spare parts and Consulting.
PRODAVE MPI/IE V6.1
A5E03681152-01
5
Preface
6
PRODAVE MPI/IE V6.1
A5E03681152-01
Contents
Preface
3
Contents
7
1
Introduction
9
2
Installation
11
2.1
2.1.1
2.1.2
2.1.3
2.2
2.2.1
2.2.2
2.2.3
2.3
2.3.1
3
Automation License Manager............................................................................ 11
User Rights through the Automation License Manager..................................... 11
Installing the Automation License Manager....................................................... 13
Guidelines for Handling License Keys............................................................... 14
Installing PRODAVE MPI/IE V6.2...................................................................... 15
Installation Procedure ........................................................................................ 16
Setting the PG/PC Interface .............................................................................. 18
Installing V6.2 over V6.x .................................................................................... 20
Uninstalling PRODAVE MPI/IE V6.2 ................................................................. 20
Uninstalling PRODAVE MPI/IE V6.2 ................................................................. 20
Functions in PRODAVE MPI/IE V6.2
3.1
3.1.1
3.1.2
3.1.3
3.1.4
3.1.5
3.1.6
3.1.7
3.1.8
3.1.9
3.1.10
3.1.11
3.1.12
3.1.13
3.1.14
3.1.15
3.1.16
3.1.17
3.1.18
3.1.19
3.1.20
3.1.21
3.1.22
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
21
Basic Functions ................................................................................................. 24
LoadConnection_ex6......................................................................................... 24
UnloadConnection_ex6 ..................................................................................... 27
SetActiveConnection_ex6 ................................................................................. 28
SetPassword_ex6.............................................................................................. 29
UnSetPassword_ex6 ......................................................................................... 30
as_info_ex6 ....................................................................................................... 31
as_zustand_ex6................................................................................................. 33
db_buch_ex6 ..................................................................................................... 35
db_read_ex6...................................................................................................... 36
db_write_ex6 ..................................................................................................... 38
bst_read_diag_ex6 ............................................................................................ 40
bst_read_stat_ex6 ............................................................................................. 42
bst_read_ex6 ..................................................................................................... 44
read_diag_buf_ex6 ............................................................................................ 48
field_read_ex6 ................................................................................................... 50
field_write_ex6................................................................................................... 52
szl_read_ex6 ..................................................................................................... 53
get_pb_lifelist_ex6 ............................................................................................. 55
get_ie_lifelist_ex6 .............................................................................................. 57
defrag_ex6......................................................................................................... 59
mb_setbit_ex6 ................................................................................................... 60
mb_bittest_ex6 .................................................................................................. 61
Functions for Data Transfer to S7-200 .............................................................. 62
as200_as_info_ex6............................................................................................ 62
as200_as_zustand_ex6..................................................................................... 64
as200_field_read_ex6 ....................................................................................... 65
as200_field_write_ex6 ....................................................................................... 67
as200_mb_setbit_ex6........................................................................................ 69
PRODAVE MPI/IE V6.1
A5E03681152-01
7
Contents
3.2.6
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6
3.3.7
3.3.8
3.3.9
3.3.10
3.3.11
3.3.12
3.3.13
3.3.14
3.3.15
3.4
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.4.6
3.5
as200_mb_bittest_ex6....................................................................................... 70
Convenience Functions ..................................................................................... 72
GetErrorMessage_ex6....................................................................................... 72
kg_2_float_ex6 .................................................................................................. 75
float_2_kg_ex6 .................................................................................................. 76
gp_2_float_ex6 .................................................................................................. 77
float_2_gp_ex6 .................................................................................................. 78
testbit_ex6 ......................................................................................................... 79
byte_2_bool_ex6 ............................................................................................... 80
bool_2_byte_ex6 ............................................................................................... 81
kf_2_integer_ex6, kf_2_long_ex6...................................................................... 82
swab_buffer_ex6 ............................................................................................... 83
copy_buffer_ex6 ................................................................................................ 84
ushort_2_bcd_ex6, ulong_2_bcd_ex6............................................................... 85
bcd_2_ushort_ex6, bcd_2_ulong_ex6............................................................... 87
GetLoadedConnections_ex6 ............................................................................. 89
GetPduSize_ex6................................................................................................ 90
TeleService Functions ....................................................................................... 91
ts_dial_ex6......................................................................................................... 91
ts_hang_up_dial_ex6......................................................................................... 93
ts_set_ringindicator_ex6.................................................................................... 94
ts_read_info_ex6 ............................................................................................... 95
ts_hang_up_ring_ex6 ........................................................................................ 96
ts_get_modem_name_ex6 ................................................................................ 97
Data Structures.................................................................................................. 98
Glossary
99
Index
103
8
PRODAVE MPI/IE V6.1
A5E03681152-01
1
Introduction
PRODAVE MPI/IE V6.2 provides functions which can be combined with a user
application. The tools are combined in the development environments of the C and
Basic programming languages.
With these functions PRODAVE MPI/IE V6.2 establishes the process data
communication via MPI-Profibus or Ethernet communication of the SIMATIC AS
between automation system and PG/PC. During communication PRODAVE MPI/IE
V6.2 accesses functions of the S7DOS component. The parameters are assigned
to the interfaces using the "Set PG/PC interface" of the S7DOS.
The following major extensions to the functions have been incorporated in
PRODAVE MPI/IE V6.2:
•
Support for the operating system MS Windows 7 (32 bit and 64 bit).
•
A new function for reading the PDU size.
All SIMATIC automation systems are supported:
•
S7 400
•
S7 300
•
S7 200
PRODAVE MPI/IE V6.2 only supports the following operating systems: MS
Windows XP Professional, MS Windows Vista 32, and MS Windows 7. Also the
respective up-to-date service packs are also supported.
The services via industrial Ethernet receive clearance only for MS Windows XP,
MS Windows Vista 32 and MS Windows 7 !
PRODAVE MPI/IE V6.2 supports neither Fast-User-Switching nor terminal-server
operation!
PRODAVE MPI/IE V6.1
A5E03681152-01
9
Introduction
10
PRODAVE MPI/IE V6.1
A5E03681152-01
2
Installation
2.1
Automation License Manager
2.1.1
User Rights through the Automation License Manager
Automation License Manager
A product-specific license key (user rights) is required which is installed by
PRODAVE MPI/IE V6.2 with the Automation License Manager from V6.0 on.
Automation License Manager is a software product of Siemens AG. It is a global
system toolused to handle license keys (technical license representatives.)
You can find the Automation License Manager:
•
On the installation device for the respective software product requiring a
license key or
•
On a separate installation device as well as
•
As a download from the Internet page of A&D Customer Support at Siemens
AG.
Automation License Manager provides an integrated Online Help system. You can
call this help after installation context-sensitive by pressing F1, or by selecting the
Help > Help on License Manager command. This online help contains detailed
information on the functionality and operation of the Automation License Manager.
Licenses
Licenses are required to use PRODAVE MPI/IE V6.2 program packages whose
legal use is protected by licenses. A license gives the user a legal right to use the
product. Evidence of this right is provided by the following:
•
The CoL (Certificate of License) and
•
The license key
PRODAVE MPI/IE V6.1
A5E03681152-01
11
Installation
Certificate of License (CoL)
The "Certificate of License" that is included with a product is the legal evidence that
a right to use this product exists. This product may only be used by the owner of
the Certificate of License (CoL) or by those persons authorized to do so by the
owner.
License keys
The license key is the technical representation (an electronic "license stamp") of a
license to use software.
SIEMENS AG issues a license key for all software protected by legal license
agreement. When the computer has been started, such software can only be used
in accordance with the applicable license and terms of use after the presence of a
valid license key has been verified.
Notes
You can use PRODAVE MPI/IE V6.2 without a license key to familiarize
yourself with the user interface and functions.
•
•
However, a license is required and necessary for full, unrestricted use in
accordance with the license agreement.
•
If you have not installed the license key, you will be prompted to do so at
regular intervals.
License keys can be stored and transferred among various types of storage
devices as follows:
•
On license key diskettes
•
On the local hard disk
•
On network hard disk
If software products for which no license is available are installed, you can then
determine which license key is needed and order it as required.
For further information on handling license keys, please refer to the Automation
License Manager Online Help.
12
PRODAVE MPI/IE V6.1
A5E03681152-01
Installation
Licenses
Siemens AG distinguishes between the following user-oriented license types for its
software products. The behavior of the software is controlled by different license
keys for these license types. The type of use is derived from the relevant
Certificate of License.
License Type
Description
Single License
The software can be used on any single computer desired for an unlimited
amount of time.
Floating License
The software can be used on a computer network ("remote use") for an
unlimited amount of time.
Trial License
The software can be used subject to the following restrictions:
Upgrade License
2.1.2
•
A period of validity of up to a maximum of 14 days,
•
A total number of operating days after the day of first use,
•
A use for tests and validation (exemption from liability).
An upgrade may require a specific system state:
•
An upgrade license can be used to convert an "Old"Version x to a Version
>x+... license.
•
An upgrade may be necessary due to an increase in the volume of data
being handled in the given system.
Installing the Automation License Manager
The Automation License Manager is installed by means of an MSI setup process.
The installation software for the Automation License Manager is included on the
PRODAVE MPI/IE V6.2 product CD
You can install the Automation License Manager at the same time you install
PRODAVE MPI/IE V6.2 or at a later time.
Notes
•
For detailed information on how to install the Automation License Manager,
please refer to the current "Readme.rtf" file.
•
The online help for the Automation License Manager contains all the
information you need on the function and handling of license keys.
PRODAVE MPI/IE V6.1
A5E03681152-01
13
Installation
Subsequent Installation of License Keys
If you start the PRODAVE MPI/IE V6.2 software and no license keys are in place,
you will receive a message to that effect.
Notes
•
You can use PRODAVE MPI/IE V6.2 without a license key to familiarize
yourself with the user interface and functions.
•
However, a license is required and necessary for full, unrestricted use in
accordance with the license agreement.
•
If you have not installed the license key, you will be prompted to do so at
regular intervals.
You can subsequently install license keys in the following ways:
•
Install license keys from diskettes
•
Install license keys downloaded from the Internet. In this case, the license keys
must be ordered first.
•
Use floating license keys available in a network
For detailed information on installing license keys, refer to the online help for the
Automation License Manager. To access this help context-sensitively, press F1 or
select the Help > Help on License Manager menu command.
Notes
•
In Windows XP/Vista32/7, license keys will only be operational if they are
installed on a local hard disk and have write-access status.
•
2.1.3
!
Floating licenses can also be used within a network ("remote" use).
Guidelines for Handling License Keys
Caution
Please note the information on handling license keys that is available in the online
help on the Automation License Manager and also in the PRODAVE MPI/IE V6.2
Readme.wri file on the installation CD-ROM. If you do not follow these guidelines,
the license keys may be irretrievably lost.
You can open the Automation License Manager Online Help context-sensitively by
pressing F1, or by selecting the Help > Help on Automation License Manager
command.
This help section contains all the information you need on the function and
handling of license keys.
14
PRODAVE MPI/IE V6.1
A5E03681152-01
Installation
2.2
Installing PRODAVE MPI/IE V6.2
PRODAVE MPI/IE V6.2 contains a Setup program that performs an automatic
installation.On-screen input requests take you through the entire installation
procedure step-by-step. Execute Setup using the standard Windows XP/Vista32/7
software installation procedure.
The major stages in the installation are:
•
Copying the data to your programming device
•
Configuration of communication drivers,
•
Installing the license keys (if desired).
Installation Requirements
•
Operating system
Microsoft Windows XP, Windows Vista32, Windows 7.
•
Basic hardware:
Programming device or PC with:
-
Pentium Processor (for Microsoft Windows XP, P333, for Windows
Vista32, x32 processor with 1GHz), for Windows 7 processor with 1.6 GHz.
-
RAM Memory extension: for Windows XP 512MB, for Windows Vista32
1024MB, for Windows 7 2048MB.
-
Color monitor, keyboard and mouse, all of which are supported by
Microsoft Windows.
A programming device (PG) is a PC with a special compact design for industrial
use. It is fully equipped for programming SIMATIC PLCs.
•
•
Hard disk space:
Refer to the "README.RTF" file for information on required hard disk space.
MPI interface optional):
An MPI interface is only required to interconnect the PG/PC and the PLC if
you want to use it for communication with the PLC under PRODAVE MPI/IE
V6.2.
In this case you require:
-
A PC adapter and a zero modem cable (RS232), which are connected to
the communications interface of your device, or
-
An MPI module (for example, CP 5611) that is installed in your device.
PGs are supplied with a pre-installed MPI interface.
Notes
Refer to the information on PRODAVE MPI/IE V6.2 . in the "README.RTF" file
You can find the Readme file in the start menu:
XP: Start > SIMATIC > Information > English
Vista/7: Start > Siemens Automation > SIMATIC > Product Notes > English
PRODAVE MPI/IE V6.1
A5E03681152-01
15
Installation
2.2.1
Installation Procedure
Preparations
The operating system must be started before you can start your software
installation.
•
You do not require an external storage medium if the installable PRODAVE
MPI/IE V6.2 software is already stored on the hard disk of the PG.
•
To run Setup from CD-ROM, place the CD-ROM into the CD-ROM drive of
your PC.
Starting the Installation Program
To install the software, proceed as follows:
1. Insert the CD-ROM and double click on the file "SETUP.EXE".
2. Follow the on-screen step-by-step instructions of the installation program.
The program guides you through all steps of the installation. You can go to the next
step or return to the previous step.
During installation, the dialog boxes prompt you to make your choice from the
displayed options. The following notes will help you to quickly and easily find the
right answers.
Selecting the Installation Options
You have three options:
16
•
PRODAVE MPI 5.6: all the functions of version 5.6. Please check the current
product information for the hard disk space required.
•
PRODAVE MPI/IE V6.2: all the functions of version V6.2. Please check the
current product information for the hard disk space required.
•
PRODAVE MPI 5.6 and PRODAVE MPI/IE V6.2: all the functions of versions
5.6 and V6.2. Please check the current product information for the hard disk
space required.
PRODAVE MPI/IE V6.1
A5E03681152-01
Installation
Installing License Keys
During setup, the program checks to see whether a corresponding license key is
installed on the hard disk. If no valid license key is found, a message stating that
the software can be used only with a license key is displayed. If you want, you can
install the license key immediately or continue setup and then install the key later.
If you want to install the license key now, insert the authorization data medium
when prompted to do so.
PG/PC Interface Settings
If no SIMATIC product has been installed yet, a dialog box is displayed during
installation where you can assign parameters to the programming device/PC
interface. You will find more information on it in "Setting the PG/PC Interface."
Setup errors
Setup may be aborted due to the following errors:
•
If an initialization error occurs immediately after the start of setup, it is more
than likely setup was not started under Windows.
•
Insufficient hard disk space: Minimum free hard disk space required for a
standard software installation is 50 Mbytes, regardless of the scope of your
installation.
•
Bad CD-ROM: If the CD is faulty, please contact your local Siemens
representative.
•
Operator error: Restart setup and follow the instructions carefully.
After the Installation has been Completed…
An on-screen message reports the successful installation.
If any changes were made to system files during the installation, you are prompted
to restart Windows. After restarting (warm start) you can use PRODAVE MPI/IE
V6.2.
Several entries in the start menu, a directory in the "Program Files" folder and a
current PRODAVE DLL in the Windows system directory are available after a
successful installation.
PRODAVE MPI/IE V6.1
A5E03681152-01
17
Installation
2.2.2
Setting the PG/PC Interface
You configure the communication between the PG/PC and the PLC with the
settings entered here. If no SIMATIC product has been installed yet, a dialog box is
displayed during installation for setting the PG/PC interface. You can also open this
dialog box after installation, by calling the program "Setting PG/PC Interface" in the
control panel. This enables you to modify the interface parameters at a later time,
independently of the installation.
When working with MS Windows 7 you therefor need the classical view of the
control panel.
Basic Procedure
To operate an interface, you will require the following:
•
Configurations in the operating system
•
A suitable interface configuration
If you are using a PC with an MPI card or communications processors (CP), you
should check the interrupt and address assignments in the Windows "Control
Panel" to ensure that there are no interrupt conflicts and that no address areas
overlap.
As of Windows 2000, the ISA component MPI-ISA card is no longer supported and
therefore no longer offered for installation.
In order to make it easier to assign parameters to the programming device/PC
interface, a dialog box will display a selection list of default basic parameter sets
(interface configurations).
Assigning Parameters to the PG/PC Interface
Procedure (details to be found in the Online Help):
Double-click on "Setting PG/PC Interface" in the "Control Panel" of Windows.
1. Set the "Access Point of Application" to "S7ONLINE."
2. In the list "Interface parameter set used", select the required interface
parameter set. If the required interface parameter set is not displayed, you
must first install a module or protocol via the "Select" button. The interface
parameter set is then generated automatically. On plug-and-play systems, you
cannot install plug and play CPs manually (CP 5611 and CP 5512). They are
integrated automatically in "Setting PG/PC Interface" after you have installed
the hardware in your PG/PC.
-
18
If you select an interface with automatic bus parameter recognition
(e. g. CP 5611 (Auto)), then you can connect the PG and/or the PC to MPI
and/or PROFIBUS without having to set bus parameters. If the
transmission rate is < 187.5 Kbps, there may be a delay of up to one
minute while the bus parameters are read.
Requirement for automatic recognition: Masters who broadcast bus
parameters cyclically are connected to the bus. All new MPI components
PRODAVE MPI/IE V6.1
A5E03681152-01
Installation
do this; for PROFIBUS subnets the cyclic broadcast of bus parameters
must be enabled (default PROFIBUS network setting).
-
If you select an interface which does not automatically recognize the
bus parameters, you can display the properties and adapt them to match
the subnet.
Changes will also be necessary if conflicts with other settings arise (for example,
interrupt or address assignments). In this case, make the appropriate changes with
the hardware recognition and Control Panel in Windows (see below).
!
Caution
Do not remove any "TCP/IP" parameters from your interface configuration.
This could cause malfunctioning of other applications.
Checking the Interrupt and Address Assignments
If you use a PC with an MPI card, you should always check whether the default
interrupt and the default address area are free and, if necessary select a free
interrupt and/or address area.
Windows XP
In Windows XP you can
•
display the resources under Start > All Programs > Accessories > System >
System Programs > System Information > Hardware Resources.
•
modify the resources under Control Panel > My Computer > Properties >
Device Manager > SIMATIC NET > CP-Name > Properties > Change
Resources.
Windows Vista32
Under Windows Vista32 you can
•
display the resources under START > All Programs > Accessories > System
Tools > System Information > Hardware Resources.
•
modify the resources under Control Panel > Device Manager > SIMATIC
NET > CP Name > Properties > Resources.
Windows 7
Under Windows 7 you can
•
display the resources under START > All Programs > Accessories > System
Tools > System Information.
•
modify the resources under Control Panel > My Computer > Properties >
Device Manager > SIMATIC NET > CP-Name > Properties > Change
Resources.
PRODAVE MPI/IE V6.1
A5E03681152-01
19
Installation
2.2.3
Installing V6.2 over V6.x
If you install PRODAVE MPI/IE V6.2 over an existing PRODAVE MPI/IE V6.x, the
file Prodave6.dll is replaced in the Windows directory. The directory "v6.x" in the
Prodave directory persists with all source code examples and the old dll file V6.x.
PRODAVE MPI/IE V6.2 is installed parallel to the v6.x directory in the directory
"V6.2".
2.3
Uninstalling PRODAVE MPI/IE V6.2
2.3.1
Uninstalling PRODAVE MPI/IE V6.2
Use the standard Windows method to uninstall PRODAVE MPI/IE V6.2:
1. Open the "Control Panel" in Windows, then double-click "Software" or
"Program" or similar to open the software setup dialog box.
2. Select the PRODAVE MPI/IE V6.2 entry in the displayed list of installed
software. Click the button to "Remove" the software.
3. If the "Remove free file" dialog box appears, click "No" if you are uncertain.
20
PRODAVE MPI/IE V6.1
A5E03681152-01
3
Functions in PRODAVE MPI/IE V6.2
The following table shows a list of all the functions:
Version
PRODAVE
MPI/IE V6.2
Library
PRODAVE6.DLL
Header
PRODAVE6.H
Description
Basic Functions
LoadConnection_ex6
x
MPI/Profibus, ISO or TCP/IP Protocol
UnloadConnection_ex6
x
MPI/Profibus, ISO or TCP/IP Protocol
SetActiveConnection_ex6
x
MPI/Profibus, ISO or TCP/IP Protocol
SetPassword_ex6
x
Sets the password for a connection
UnSetPassword_ex6
x
Resets the password
Functions for Data Communication Traffic to the S7 300/400
as_info_ex6
x
Reads different diagnostic data
as_zustand_ex6
x
Reads the AS state (RUN or STOP)
db_buch_ex6
x
Reads in a list of data blocks
db_read_ex6
x
Reads data from a data block
db_write_ex6
x
Writes data to a data block
bst_read_ex6
x
Reads out the"Advanced" block code
bst_read_diag_ex6
x
"Advanced" block lists/header
information
bst_read_stat_ex6
x
"Advanced" block lists/header
information
read_diag_buf_ex6
x
Reads out the "Advanced" diagnostic
buffer
field_read_ex6
x
Reads a number of data
field_write_ex6
x
Writes a number of data
szl_read_ex6
x
Reads the SSLs from the AS
get_pb_lifelist
x
Provides a LifeList of the connected
MPI/Profibus subnet
get_ie_lifelist
x
Provides a LifeList of the connected
Ethernet subnet
PRODAVE MPI/IE V6.1
A5E03681152-01
21
Functions in PRODAVE MPI/IE V6.2
mb_setbit_ex6
x
Sets a bit
mb_bittest_ex6
x
Checks a bit in a memory byte
Functions for Data Communication Traffic to the S7 200
as200_as_info_ex6
x
Reads different diagnostic data
as200_as_zustand_ex6
x
Reads the AS state (RUN or STOP)
as200_field_read_ex6
x
Reads a number of data
as200_field_write_ex6
x
Writes a number of data
as200_mb_setbit_ex6
x
Sets a bit
as200_mb_bittest_ex6
x
Checks a bit in a memory byte
Convenience Functions
GetErrorMessage_ex6
x
Provides the error text for an error
number
kg_2_float_ex6
x
Converts an S5 floating point value to
float
float_2_kg_ex6
x
Converts float to an S5 floating point
value
gp_2_float_ex6
x
Converts an S7 floating point value to
float
float_2_gp_ex6
x
Converts float to an S7 floating point
value
testbit_ex6
x
byte_2_bool_ex6
x
Converts a byte to eight boolean
values
bool_2_byte_ex6
x
Converts eight boolean values to a
byte
kf_2_integer_ex6
x
Swaps the high and low bytes of a
16 bit value
kf_2_long_ex6
x
extended by double words
swab_buffer_ex6
x
Swaps the high and low bytes of a
32 bit value
copy_buffer_ex6
x
Swaps the high and low bytes of a
buffer
ushort_2_bcd_ex6
x
bcd_2_ushort_ex6
x
ulong_2_bcd_ex6
x
bcd_2_ulong_ex6
x
GetLoadedConnections_ex6 x
22
Returns a list of all open and closed
connections
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
GetPduSize_ex6
x
Returns the maximum PDU size for
communication with the connected
CPU
TeleService Functions
ts_dial_ex6
x
ts_hang_up_dial_ex6
x
ts_set_ringindicator_ex6
x
ts_read_info_ex6
x
ts_hang_up_ring_ex6
x
ts_get_modem_name_ex6
x
Functions
All the functions listed are described from the PRODAVE MPI/IE V6.2 user view.
Nevertheless, you must also add the WINAPI call convention / load tool to each
function.
int WINAPI load_tool (char chConNo, …).
The old PRODAVE MPI 5.6 Libraries (W95_S7.DLL, KOMFORT.DLL) and the new
PRODAVE MPI/IE V6.2 Library (PRODAVE6.LIB) can be used parallel in a user
program.
There should be no problems when using programs created for PRODAVE MPI/IE
V6.0 with PRODAVE MPI/IE V6.2.
Parallel operation of the older versions V6.x and V6.2 is not supported.
You can continue to use old Prodave V5.6 programs. It is not, however, possible to
interlace the two versions, i.e. it is not possible to create a connection to the AS
with an old function and then to read data with a new function and vice versa. The
connection and the reading or writing of the data must take place homogeneously,
with the same Prodave Version.
PRODAVE MPI/IE V6.1
A5E03681152-01
23
Functions in PRODAVE MPI/IE V6.2
3.1
Basic Functions
3.1.1
LoadConnection_ex6
The basic LoadConnection_ex6 function initializes the adapter, checks if the
driver is loaded, initializes the addresses that have been assigned parameters and
activates the selected interface.
LoadConnection_ex6 is used to set up a transport connection via MPI/PB- or IP
addresses (TCP/IP protocol)
int LoadConnection_ex6 (int ConNr, char* pAccessPoint, int ConTableLen,
CON_TABLE_TYPE * pConTable);
Parameters
ConNr
[in] Number of the connection (max. 64 connections).
pAccessPoint
[in] access point (zero-terminated) of the driver used, e.g. "S7ONLINE" for the MPI
driver or 0 (default).
ConTableLen
[in] length of the connection structure provided by the user in bytes
pConTable
[in] pointer to address structure of the user
#pragma pack(1)
typedef union {
unsigned char Mpi;
// MPI/PB station address (2)
unsigned char Ip[4];
// IP address (192.168.0.1)
unsigned char Mac[6];
// MAC address (08-00-06-01-AA-BB)
} CON_ADR_TYPE;
typedef struct {
CON_ADR_TYPE Adr;
// connection address
unsigned char AdrType;
// Type of address: MPI/PB (1), IP (2), MAC (3)
unsigned char SlotNr;
// Slot number
unsigned char RackNr;
// Rack number
} CON_TABLE_TYPE;
#pragma pack(1)
24
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Return Values
If there were no errors, the function supplies 0 as the return value.
If an error occurs, the error number is returned; this can be evaluated in
accordance with the error table (see GetErrorMessage_ex6).
After eliminating the cause of the error LoadConnection_ex6 has to be executed
again in order to create a connection to the AS.
Call example
A new entry in the connection table is prepared for each connection.
int RetValue = 0;
unsigned short ConNr= 0;
//First connection
(0 ... 63)
char AccessPoint[] = {"S7ONLINE"};
//Default access point S7ONLINE
CON_TABLE_TYPE
ConTable[MAX_CONNECTION+1] = {0};
//Connection table
CON_TABLE_TYPE * pConTable =
&ConTable[ConNr];
//Pointer on connection structure
unsigned short ConTableLen =
sizeof(CON_TABLE_TYPE);
//Length of the connection structure
pConTable[ConNr].Adr.Ip[0] = 192;
//Default IP address (192.168.0.1)
pConTable[ConNr].Adr.Ip[1] = 168;
pConTable[ConNr].Adr.Ip[2] = 0;
pConTable[ConNr].Adr.Ip[3] = 1;
pConTable[ConNr].AdrType = 2;
//Address type = IP
pConTable[ConNr].SlotNr = 2
//Slot number = 2
pConTable[ConNr].RackNr = 0;
//Rack number = 0
RetValue = LoadConnection_ex6 (ConNr, &AccessPoint, ConTableLen, pConTable);
Attention
Please observe that the number of real connections can differ from the 64
possible connections. This depends on the installed software packages and uesed
communication media.
For example, for PROFIBUS connections only 28 connections to different CPUs
can be established at the same time. Connection 29 is acknowlegded with an
error:
0x4104: Online: No resources on the driver available.
If connection errors take place during operation, you must close the connection
and reload it.
PRODAVE MPI/IE V6.1
A5E03681152-01
25
Functions in PRODAVE MPI/IE V6.2
Requirements
V6.2 Load_Connection_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
UnloadConnection_ex6, SetActiveConnection_ex6,
GetLoadedConnections_ex6
26
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.2
UnloadConnection_ex6
The basic UnloadConnection_ex6 deinitialises the connections and the adapter
and must be called up before exiting the application.
int UnloadConnection_ex6 (unsigned short ConNr);
Parameters
ConNr
[in] Number of the connection, which was assigned with LoadConnection_ex6.
Return Values
If there were no errors, the function supplies 0 as the return value or an error
message is given which can be evaluated in accordance with the error table (see
GetErrorMessage_ex6).
If the currently active connection has been closed, an (error) warning is returned.
Call example
Has to be called for each connection.
int RetValue = 0;
unsigned short ConNr = 0;
//(0 ... 63)
RetVal = UnloadConnection_ex6 (ConNr);
Requirements
V6.2 Unload_Connection_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
LoadConnection_ex6, SetActiveConnection_ex6,
GetLoadedConnections_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
27
Functions in PRODAVE MPI/IE V6.2
3.1.3
SetActiveConnection_ex6
The basic SetActiveConnection_ex6 function activates the connection of the
PG/PC over which the subsequent data exchange will take place.
int SetActiveConnection_ex6 (unsigned short ConNr);
Parameters
ConNr
[in] Number of a connection assigned with LoadConnection_ex6, which is to be
activated.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned short ConNr = 7;
//(0 ... 63)
RetVal = SetActiveConnection_ex6(ConNr);
Requirements
V6.2 SetActiveConnection_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
LoadConnection_ex6, UnloadConnection_ex6, GetLoadedConnections_ex6
28
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.4
SetPassword_ex6
The SetPassword_ex6 function sets a password for a specific connection with a
CPU.
int SetPassword_ex6 (unsigned short ConNr, unsigned char * Password);
Parameters
ConNr
[in]
Connection number
Password
[in]
Pointer to an UCHAR string, length 8
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
If a CPU was saved with a password, a password is required in order to perform
changes to the state of the CPU. For this purpose the SetPassword_ex6 must be
called after LoadConnection_ex6.
int RetValue = 0;
unsigned char passw[8];
//Passwort (muss exakt 8 Bytes lang sein)
unsigned short ConNr= 13;
//Verbindungsnummer
RetValue = SetPassword_ex6 (ConNr, &passw[0]);
Requirements
V6.2 SetPassword_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
As_zustand_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
29
Functions in PRODAVE MPI/IE V6.2
3.1.5
UnSetPassword_ex6
The UnSetPassword_ex6 function removes the password for a specific
connection with a CPU.
int UnSetPassword_ex6 (unsigned short ConNr);
Parameters
ConNr
[in]
Connection number
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned short ConNr= 13;
//Connection number
RetValue = UnSetPassword_ex6 (ConNr);
Requirements
V6.2 UnSetPassword_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
As_zustand_ex6
30
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.6
as_info_ex6
The as_info_ex6 function reads out the release version of the AS software and the
PG interface module as well as the MLFB number of the AS and files it as a zeroterminated ASCII string in the transfer buffer of the PG/PC.
int as_info_ex6 (unsigned long BufLen, AS_INFO_TYPE * pInfoBuffer,
unsigned long * pDatLen);
Parameters
BufLen
[in] Length of the transfer buffer provided by the user in bytes.
pInfoBuffer
[out] pointer to transfer buffer with the AS information to be delivered:
typedef struct {
unsigned char Plcas[4];
// release version of the hardware
unsigned char Pgas[2];
// Release version of the hardware
char Mlfb[20];
// MLFB of the connected AS.
} AS_INFO_TYPE;
pDatLen
[out] pointer to the length if the data delivered in the buffer in bytes. If the "Transfer
buffer provided too small for data" error occurs, the required size of the buffer is
given here.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Some AS cannot output the MLFB or the release version of the FW and HW. If this
is the case, the MLFB if it had been possible to read it, is written in pInfoBuffer and
a corresponding error message is issued.
PRODAVE MPI/IE V6.1
A5E03681152-01
31
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
AS_INFO_TYPE Buffer;
//Create transfer buffer
AS_INFO_TYPE * pInfoBuffer = &Buffer;
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Transfer buffer length
unsigned long DatLen;
//Data length
RetValue = as_info_ex6 (BufLen, pInfoBuffer, &DatLen);
Requirements
V6.2 as_info_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as_zustand_ex6
32
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.7
as_zustand_ex6
The as_zustand_ex6 function reads the operating state (OS) and files the dta in a
storage area of the PG/PC.
int as_zustand_ex6 (unsigned char * pState);
Parameters
pState
[out] transfer buffer with the AS states to be supplied (length required 1 byte)
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned char State;
//Transfer bytes for the AS state to be
delivered
RetValue = as_zustand_ex6 (&State);
PRODAVE MPI/IE V6.1
A5E03681152-01
33
Functions in PRODAVE MPI/IE V6.2
"Current operating state (OS)" (values in Hex)
OM ID
Meaning
00
Configuration in RUN (EVAL at R-KiR)
01
STOP (update)
02
STOP (memory reset)
03
STOP (self-initialization)
04
STOP (internal)
05
Startup (cold restart)
06
Startup (warm restart)
07
Startup (hot restart)
08
RUN (simple)
09
RUN (redundant)
0A
HALT
Bx
COUPLE
Cx
UPDATE
0D
Defect
Ex
TEST
FX
NOPOWER
Requirements
V6.2 as_zustand_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as_info_ex6
34
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.8
db_buch_ex6
The db_buch_ex6 function displays which data blocks are available in the AS.
int db_buch_ex6 (unsigned long BufLen, unsigned short * pBuchBuffer,
unsigned long * pDatLen);
Parameters
BufLen
[in]
Length of the transfer buffer the user provided in bytes.
pBuchBuffer
[out] pointer on transfer buffer for the data blocks already read. The numbers of the
data blocks present are written as word values (block number can be 9) in the
buffer array.
pDatLen
[out] pointer to the length of the data delivered in the buffer in bytes. If the "Transfer
buffer provided too small for data" error occurs, the required size of the buffer is
given here.
If pDatLen has the value 0 no data blocks were found.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned short Buffer[MAX_BUFFER];
//Transfer buffer
unsigned short * pBuchBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Transfer buffer length
unsigned long DatLen;
//Data length
RetValue = db_buch_ex6 (BufLen, pBuchBuffer, &DatLen);
Requirements
V6.2 db_buch_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
35
Functions in PRODAVE MPI/IE V6.2
3.1.9
db_read_ex6
The db_read_ex6 reads out a number of bytes from a data block in AS and
transfers them into a storage area (buffer) of the PG/PC.
It is possible to read out data byte-by-byte/word-by-word/double word-by-word
(pAmount = 1) or block-by-block (pAmount > 1) with db_read_ex6.
int db_read_ex6 (unsigned short BlkNr, unsigned char DatType, unsigned
short StartNr, unsigned long * pAmount, unsigned long BufLen, unsigned
char * pReadBuffer, unsigned long * pDatLen)
Parameters
BlkNr
[in] Number of the data block
DatType
[in] Type of data to be read:
0x02 = BYTE, 0x04 = WORD, 0x06 = DWORD default: DatType = 0x02
StartNo
[in] Start number of the first byte / word / double word to be read
pAmount
[in] Amount of bytes / data words/ double words to be read
BufLen
[in] Length of the transfer buffer provided by the user in bytes.
pReadBuffer
[out] pointer on transfer buffer with the bytes / words / double words already read
pDatLen
[out] pointer to the length of the data delivered in the buffer in bytes.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
If the data block does not exist, this is shown by a return value = error number.
If more data are to be read than is present in the data block, the data actually read
are written in pReadBuffer; the number (in bytes) of the data actually read is written
in pDatLen and an error message "block limit exceeded" is returned.
36
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
unsigned short blkNr = 0;
//Block number = 0
unsigned char DatType = 0x04;
//Data type = word
unsigned short StartNr = 2;
//First word to be read = 2
int Amount = 6;
[in] Amount of words to be read = 6
Unsigned char buffer[MAX_BUFFER];
//Transfer buffer
unsigned char * pReadBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Transfer buffer length
unsigned long DatLen;
//Data length
RetValue = db_read_ex6 (BlkNr, DatType, StartNr, &Amount, BufLen, pReadBuffer,
&DatLen);
unsigned short * wBuffer = (unsigned short
*)Buffer;
//Word-by-word access
unsigned long * dwBuffer = (unsigned long
*)Buffer;
//Double word-by-word access
Performance tip:
The function field_read_ex6 is most suitable for reading only a small amount of
bytes (<< PDU size [240/480/960]-bytes).
Attention!
When accessing a data block the data words in the buffer are not filed according
to Intel notation (little endian, low byte on low address, high byte on higher
address), but in STEP5/STEP7 Notation (Motorola big endian, high byte on lower
address, low byte on higher address). If the data are to be further processed,
attention must be paid to this. The kf_2_integer_ex6, kf_2_long_ex6 and
swab_buffer_ex6 functions are available for swapping bytes.
Requirements
V6.2 db_read_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
db_write_ex6, kf_2_integer, kf_2_long_ex6, swab_buffer_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
37
Functions in PRODAVE MPI/IE V6.2
3.1.10
db_write_ex6
The db_write_ex6 writes a number of bytes that are located in a defined storage
area (buffer) in the PG/PC into a data block in the AS.
It is possible to read out data byte-by-byte/word-by-word/double word-by-word
(pAmount = 1) or block-by-block (pAmount > 1) with db_write_ex6.
int db_write_ex6 (unsigned short BlkNr, unsigned char DatType, unsigned
short StartNr, unsigned long * pAmount, unsigned long BufLen, unsigned
char * pWriteBuffer);
Parameters
BlkNr
[in] Number of the data block
DatType
[in] Type of data to be written:
0x02 = BYTE, 0x04 = WORD, 0x06 = DWORD default: DatType = 0x02
StartNr
[in] Start number of the first byte / word / double word to be written
pAmount
[in/out] The number of the bytes / words / double words to be written
BufLen
[in] Length of the transfer buffer provided by the user in bytes.
pWriteBuffer
[in] pointer on transfer buffer with the bytes / words / double words already written
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
If the data block does not exist, this is shown by a return value = error number.
If more data are to be written than are present in the data block, the data actually
read are written in pReadBuffer; the number (in bytes) of the data actually read is
written in pAmount and an error message "Block limit exceeded" is returned.
If the error "Zuwenig Speicher vorhanden" is returned when writing a block you
should call the "defrag_ex6" function in order to defragment the memory in the
CPU.
38
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
unsigned short BlkNr = 0;
//Block number = 0
unsigned char DatType = 0x04;
//Data type = word
unsigned short StartNr = 2;
//First word to be written = 2
int Amount = 6;
//Number of words to be written = 6
unsigned char pWriteBuffer [MAX_BUFFER];
//Transfer buffer
unsigned char *pBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Transfer buffer length
RetValue = db_write_ex6 (BlkNr, DatType, StartNr, &Amount, BufLen, pWriteBuffer);
unsigned short * wBuffer = (unsigned short
*)Buffer;
// Word-by-word access
unsigned long * dwBuffer = (unsigned long
*)Buffer;
// Double word-by-word access
Performance-Tipp:
The function field_write_ex6 is most suitable for writing only a small amount of
bytes (<< PDU size [240/480/960]-bytes).
Requirements
V6.2 db_write_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
db_read_ex6, kf_2_integer, kf_2_long_ex6, swab_buffer_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
39
Functions in PRODAVE MPI/IE V6.2
3.1.11
bst_read_diag_ex6
The bst_read_diag_ex6 function reads block lists and header information for the
diagnosis.
The information is transferred as a structure containing the blocks that are present
and the time stamp of each block making it possible to recognize changed blocks
(online/offline comparison).
int bst_read_diag_ex6 (int BlkType, unsigned short StartNr, unsigned long *
pAmount, unsigned long BufLen, BST_DIAG_TYPE * pDiagBuffer, unsigned
long * pDatLen);
If all blocks are to be read, StartNr and pAmount must be set to = 0. After
executing the function pAmount shows the number of blocks that have been read.
If the block with the start number (StartNr) is not found, the next higher block is
used as the starting block.
Parameters
BlkType
[in] Type of block to be read:
BlkType: 0x08 = OB, 0x0a = DB, 0x0c = FC, 0x0e = FB default: BlkTyp = 0x0a
StartNr
[in] Start number of the first block to be read
Amount
[in/out] Amount of blocks to be read
BufLen
[in] Length of the transfer buffer provided by the user in bytes.
pDiagBuffer
[out] Pointer on transfer buffer for the data blocks already read.
typedef struct {
unsigned short BlkNr;
// Block number
struct tm BlkTimestamp;
// Time stamp of the block number
} BST_DIAG_TYPE;
pDatLen
[out] pointer to the length of the data delivered in the buffer in bytes. If the "Transfer
buffer provided too small for data" error occurs, the required size of the buffer is
given here.
40
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
If more data are to be read than are present in the AS, only the diagnosis
information actually read is written in pDiagBuffer; the number of blocks read is
written in pAmount and an error message "Block limit exceeded" is returned.
Call examples
int RetValue = 0;
int BlkType = 0x0a;
//Block type = DB
unsigned short StartNr = 2;
//First block to be read = 2
int Amount = 4;
//Amount of blocks to be read = 4
BST_DIAG_TYPE Buffer[MAX_BLK];
//Transfer buffer array with block lists
BST_DIAG_TYPE *pDiagBuffer =
&Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Transfer buffer length
unsigned long DatLen;
//Data length
RetValue = bst_read_diag_ex6 (BlkType, StartNr, &Amount, BufLen, pDiagBuffer,
&DatLen);
Requirements
V6.2 bst_read_diag_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
bst_read_stat_ex6, bst_read_ex6, read_diag_buf_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
41
Functions in PRODAVE MPI/IE V6.2
3.1.12
bst_read_stat_ex6
The bst_read_stat_ex6 function reads block lists and header information for the
status displays (OBs/FCs/FBs/DBs).
int bst_read_stat_ex6 (int BlkType, unsigned long BufLen, BST_STAT_TYPE
* pStatBuffer, unsigned long * pDatLen);
Parameters
BlkType
[in] Type of the block to be read
BlkType: 0x08 = OB, 0x0a = DB, 0x0c = FC, 0x0e = FB default: BlkTyp = 0x0a
BufLen
[in] Length of the transfer buffer provided by the user in bytes.
pStatBuffer
[out] Transfer buffer for the data already read.
typedef struct {
unsigned short BlkType;
// Block type
unsigned short BlkNumber;
// Block number
char BlkName[8];
// Block name
unsigned char BlkVersion;
// Block version
unsigned long BlkLength;
// Block length
struct tm BlkTimestamp1;
// Time stamp 1 of the block number
struct tm BlkTimestamp2;
// Time stamp 2 of the block number
unsigned char blkSecurity[4];
// Block password and protection level
} BST_STAT_TYPE;
pDatLen
[out] pointer to the length of the data delivered in the buffer in bytes. If the "Transfer
buffer provided too small for data" error occurs, the required size of the buffer is
given here.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error number is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
42
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
int BlkType = 0x0a;
//Block type = DB
BST_STAT_TYPE Buffer[MAX_BLK];
//Transfer buffer for the data already
read.
BST_STAT_TYPE * pStatBuffer = &Buffer;
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Transfer buffer length
unsigned long DatLen;
//Data length
RetValue = bst_read_stat_ex6 (BlkType, BufLen, pStatBuffer, &DatLen);
Requirements
V6.2 bst_read_stat_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
bst_read_diag_ex6, bst_read_ex6, read_diag_buf_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
43
Functions in PRODAVE MPI/IE V6.2
3.1.13
bst_read_ex6
The bst_read_ex6 function reads a block into a buffer. "Code" blocks are read in
completely (header and data), in the case of OBs and DBs only the header is read.
int bst_read_ex6 (int BlkType, unsigned short blkNr, unsigned long BufLen,
unsigned char * pReadBuffer, unsigned long * pDatLen);
Parameter
BlkType
[in] Type of block to be read:
BlkType: 0x08 = OB, 0x0a = DB, 0x0c = FC, 0x0e = FB default: BlkTyp = 0x0a
BlkNr
[in] Block number of the block to be read
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pReadBuffer
[out] Pointer on transfer buffer for read data
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes. In event of error,
"Transfer buffer supplied too small for data" is returned and required buffer size
given.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Know-how protected blocks cannot be read. In this case, an appropriate error code
is returned.
44
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Block
Byte
Name
0
2
Programming language
Block type
4
Block number
6
Attributes
8
Block length (total)
System version number
PG block header
10
12
Length of section 1 (L1) MC5 length
14
16
Length of section 2 (L2) SSB length
18
20
Length of section 3 (L3) ADDINFO length
22
24
Length of dyn. local data
26
tm Timestamp 1
62
tm Timestamp 2
98
Block security
100
102
Producer name
110
Block family name
118
Block name
126
Version (release no.)
128
Checksum
130
CPU type
134
Signature
136
reserved
138
Section 1 (MC5 code)
138+L1
Section 2 (SSB data)
138+L1+L2
Section 3 (ADDINFO data)
PRODAVE MPI/IE V6.1
A5E03681152-01
reserved
Header extension
45
Functions in PRODAVE MPI/IE V6.2
Header of read block:
typedef struct {
unsigned char ProgLang;
// Programing language
unsigned char BlkType;
// Block type
unsigned short BlkNumber;
// Block number
unsigned char Attribute[8];
// Attributes
unsigned char BlkVersion;
// Block version
unsigned long BlkLength;
// Block length
unsigned long Length[3];
// Data length
unsigned char DynLen;
// Length of dyn. local data
struct tm BlkTimestamp1;
// Time stamp 1 of the block number
struct tm BlkTimestamp2;
// Time stamp 2 of the block number
unsigned char blkSecurity[4];
// Block level of protection
unsigned char ProducerName[8];
// Producer name
unsigned char BlkFamName[8];
// Block family name
unsigned char BlkName[8];
// Block name
unsigned char Version;
// This is a user version and
has nothing to do with block version
.
unsigned short chckSum;
// Check sum
unsigned long CPUType;
// CPU type
unsigned short signature;
// Signature
} BST_HEADER_TYPE;
46
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
int BlkType = 0x0a;
//Block type = DB
unsigned short blkNr = 34;
//Block number 34
BST_HEADER_TYPE
Buffer[MAX_BUFFER];
//Transfer buffer read data
BST_HEADER_TYPE *pReadBuffer =
&Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Transfer buffer length
unsigned long DatLen;
//Data length
RetValue = bst_read_ex6 (BlkType, blkNr, BufLen, &Buffer[0], &DatLen);
Requirements
V6.2 bst_read_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
bst_read_diag_ 60, bst_read_stat_ex6, read_diag_buf_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
47
Functions in PRODAVE MPI/IE V6.2
3.1.14
read_diag_buf_ex6
The function read_diag_buf_ex6 reads data from the diagnostic buffer and SSLs
in order to gain specific information about the status of the CPU.
int read_diag_buf_ex6 (unsigned long BufLen, unsigned char * pDiagBuffer,
unsigned long * pDatLen);
Parameters
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pDiagBuffer
[out] Pointer on transfer buffer for read data
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes. In event of error,
"Transfer buffer supplied too small for data" is returned and required buffer size
given.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Notes
The maximum deliverable number of available queries can be dependent on
operating mode (product-specific definition). For example, a CPU can only return
all information when in STOP operating mode.
In RUN operating mode, only a product-specific subset can be returned.
Example of a diagnosis entry
typedef struct {
unsigned short EventID;
// EventID
unsigned char EventInfo[20];
// Information about event
unsigned char Timestamp[8];
// Time stamp of event
} DIAG_BUFFER_TYPE;
48
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
Unsigned char Buffer[MAX_BUFFER];
//Transfer buffer read data
(DIAG_BUFFER_TYPE) &Buffer[0];
//Place structure over buffer
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
unsigned long DatLen;
//Data length
RetValue = read_diag_buf_ex6 (BufLen, pDiagBuffer, &DatLen);
Requirements
V6.2 read_diag_buf_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
bst_read_diag_ex6, bst_read_stat_ex6, bst_read_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
49
Functions in PRODAVE MPI/IE V6.2
3.1.15
field_read_ex6
The function field_read_ex6 reads a number of bytes or words from a data area of
the AS and transfers them to a PG/PC transfer buffer.
int field_read_ex6 (char FieldType, unsigned short BlkNr, unsigned short
StartNr, unsigned long Amount, unsigned long BufLen, unsigned char *
pBuffer, unsigned long * pDatLen);
Parameters
FieldType
[in] Value types as ASCII characters: Data byte (d/D), input byte (e/E), output byte
(a/A), memory byte (m/M), timer word (t/T), counter word (z/Z)
BlkNr
[in] Block number (only required for data blocks), default = 0
StartNr
[in] Start number of the first byte or word to be read
Amount
[in] Amount of bytes or words to be read
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Transfer buffer for the read bytes or words
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes. In event of error,
"Transfer buffer supplied too small for data" is returned and required buffer size
given.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
50
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
char FieldType = ’D’
//Value type = data byte (D)
unsigned short blkNr = 0;
//Block number = 0
unsigned short StartNr = 2;
//First word to be read = 2
int Amount = 6;
//Number of words to be read = 6
unsigned char Buffer[MAX_BUFFER];
//Transfer buffer
unsigned char *pBuffer = Buffer;
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
unsigned long DatLen;
//Data length
RetValue = field_read_ex6 (FieldType, BlkNr, StartNr, Amount, BufLen, pBuffer, &DatLen);
unsigned short * wBuffer = (unsigned short
*)Buffer;
//Word by word access
Requirements
V6.2 field_read_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
field_write_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
51
Functions in PRODAVE MPI/IE V6.2
3.1.16
field_write_ex6
The function field_write_ex6 writes a number of bytes or words from a PG/PC
transfer buffer into a data area of the AS.
int field_write_ex6 (char FieldType, unsigned short BlkNr, unsigned short
StartNr, unsigned long Amount, unsigned long BufLen, unsigned char *
pBuffer);
Parameters
FieldType
[in] Value types as ASCII characters: Data byte (d/D), input byte (e/E), output byte
(a/A), memory byte (m/M), timer word (t/T), counter word (z/Z)
BlkNr
[in] Block number (only required for data blocks), default = 0
StartNr
[in] Start number of the first byte or word to be written.
Amount
[in] Amount of bytes or words to be written
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[in] Pointer on transfer buffer for the bytes or words to be written
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
char FieldType = ’D’
//Value type = data byte (D)
unsigned short blkNr = 0;
//Block number = 0
unsigned short StartNr = 2;
//First word to be written = 2
int Amount = 6;
//Number of words to be written = 6
unsigned char Buffer[MAX_BUFFER];
//Transfer buffer
unsigned char *pBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
RetValue = field_write_ex6 (FieldType, BlkNr, StartNr, Amount, BufLen, pBuffer);
unsigned short * wBuffer = (unsigned short
*)Buffer;
52
//Word by word access
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Requirements
V6.2 field_write_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
field_read_ex6
3.1.17
szl_read_ex6
The function szl_read_ex6 reads out the delivered SSL of an AS and transfers it to
a storage area (buffer) of the PG/PC.
int szl_read_ex6 (unsigned short SzlId, unsigned short SzlIndex, unsigned
long BufLen, unsigned char * pBuffer, unsigned long * pDatLen);
Parameters
SzlId
[in] Number of the SSL to be read
SzlIndex
[in] Index of the SSL to be read
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Pointer on transfer buffer for the read bytes
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
PRODAVE MPI/IE V6.1
A5E03681152-01
53
Functions in PRODAVE MPI/IE V6.2
Call examples
Int RetVal = 0;
USHORT szlId = 0;
USHORT szlIndex = 0;
ULONG DatLen = 0;
//Length of returned data
unsigned char Buffer[MAX_BUFFER];
//Transfer buffer
unsigned char *pBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
RetVal = szl_read_ex6(szlId, szlIndex, BufLen, pBuffer, &DatLen);
Requirements
V6.2 szl_read_ex6
54
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.18
get_pb_lifelist_ex6
The function get_pb_lifelist_ex6 returns a list of devices with the device
type/status (see StationState) which are in the same bus as the programming
device.
int get_pb_lifelist_ex6 (unsigned long BufLen, unsigned char * pBuffer,
unsigned long * pDatLen);
Parameters
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Pointer on transfer buffer for the read bytes (fixed size = 127 bytes)
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes. In event of error,
"Transfer buffer supplied too small for data" is returned and required buffer size
given.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
Int RetVal = 0;
ULONG DatLen = 0;
//Length of returned data
unsigned char Buffer[127] = {0xff};
//Transfer buffer (max. 127 stations)
unsigned char *pBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
RetVal = get_pb_lifelist_ex6(BufLen, pBuffer, &DatLen);
Attention!
In order to execute the function successfully, you need a fully functional physical
conntection to an MPI/Profibus net.
get_pb_lifelist_ex6 is a connectionless function, i.e. an opened connection is not
necessary.
PRODAVE MPI/IE V6.1
A5E03681152-01
55
Functions in PRODAVE MPI/IE V6.2
StationState
0x00 = STATION_PASSIVE
(Slave)
0x10 = STATION_NON_EXISTANT
0x20 = STATION_ACTIVE_READY
(Master)
0x30 = STATION_ACTIVE
(Master)
Requirements
V6.2 get_pb_lifelist_ex6
56
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.19
get_ie_lifelist_ex6
The function get_ie_lifelist_ex6 returns a list of the devices (with miscellaneous
device properties) which are in the same subnet as the programming device.
int get_ie_lifelist_ex6 (unsigned long BufLen, unsigned char * pBuffer,
unsigned long * pDatLen);
Parameters
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Pointer on transfer buffer for the bytes or words to be written
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes. In event of error,
"Transfer buffer supplied too small for data" is returned and required buffer size
given.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
Int RetVal = 0;
ULONG DatLen = 0;
//Length of returned data
unsigned char Buffer[65536];
//Transfer buffer
unsigned char *pBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
RetVal = get_ie_lifelist_ex6(BufLen, pBuffer, &DatLen);
Attention!
•
In order to execute the function successfully, you need a fully functional
physical conntection to the Ethernet.
•
get_ie_lifelist_ex6 is a connectionless function, i.e. an opened connection is
not necessary.
•
Some devices do not supply an IP address and/or their name.
PRODAVE MPI/IE V6.1
A5E03681152-01
57
Functions in PRODAVE MPI/IE V6.2
Structure of the buffer (station list)
Number of found stations
Station 1
Station 2
…
Station n
Station
Byte 0
Byte 1
Byte 2
Byte 3
Byte 4
Byte 5
Byte 0
Byte 1
Byte 2
Byte 3
Length of type
Res1
Byte 1
…
…
Byte 18
Byte 19
Res2
TypeOfStation
LengthName
Byte 0
Byte 1
…
…
Byte 254
IP address
LengthType
Byte 0
Length of name
MAC address
StationName
Res3
Requirements
V6.2 get_ie_lifelist_ex6
58
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.20
defrag_ex6
The function defrag_ex6 defragments and compresses all blocks in the CPU
memory in order to establish coherent memory for new blocks.
int defrag_ex6 ();
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call example
int RetVal = defrag_ex6();
Attention
You should only execute this function if the CPU is in STOP.
Requirements
V6.2 defrag_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
59
Functions in PRODAVE MPI/IE V6.2
3.1.21
mb_setbit_ex6
The function mb_setbit_ex6 sets a bit memory in the AS to 1 or 0. It is not
checked if the memory bit exists in the currently used AS.
int mb_setbit_ex6 (unsigned short MbNr, unsigned short BitNr, unsigned
char Value);
Parameters
MbNr
[in] Number of the memory byte
BitNr
[in] Bit number in memory bytes
Value
[in] Value to be set (0/1)
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0 = 0;
unsigned short MbNr = 2;
// Memory byte number 2
unsigned short BitNr = 4;
// Bit number 4
unsigned char Value = 1;
// Value to be set = 1
RetValue = mb_setbit_ex6 (MbNr, BitNr, Value);
Requirements
V6.2 mb_setbit_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
mb_bittest_ex6
60
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.1.22
mb_bittest_ex6
The function mb_bittest_ex6 checks a bit in a given memory byte for a given value
and returns the state of the given bit into a transfer buffer.
int mb_bittest_ex6 (unsigned short MbNr, unsigned short BitNr, int * pValue);
Parameters
MbNr
[in] Number of the memory byte
BitNr
[in] Bit number in memory bytes
pValue
[out] Pointer on transfer byte with the tested bit value
Value == TRUE
Bit set or 1
Value == FALSE
Bit not set (or 0)
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned short MbNr = 2;
//Memory byte number 2
unsigned short BitNr = 4;
//Bit number 4
int Value;
//Transfer byte for the bit value to be tested
RetValue = mb_bittest_ex6 (MbNr, BitNr, &Value);
Requirements
V6.2 mb_bittest_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
mb_setbit_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
61
Functions in PRODAVE MPI/IE V6.2
3.2
Functions for Data Transfer to S7-200
3.2.1
as200_as_info_ex6
Die Function as200_as_info_ex6 reads the AS software release and the PG
interface module, as well as the PLC type of the AS and sets these in ASCII string
format in the PG/PC’s transfer buffer.
int as200_as_info_ex6 (unsigned long BufLen, AS200_INFO_TYPE * pBuffer,
unsigned long * pDatLen);
Parameters
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Pointer on transfer buffer containing AS information to be delivered.
typedef struct {
unsigned char Firmware[4];
// FW release version
unsigned char ASIC[4];
ASIC release version
char Mlfb[16];
// MLFB of connected AS
} AS200_INFO_TYPE;
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes. In event of error,
"Transfer buffer supplied too small for data" is returned and required buffer size
given.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
AS200_INFO_TYPE Buffer;
//Create transfer buffer
AS200_INFO_TYPE * pBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
unsigned long DatLen;
//Data length
RetValue = as200_as_info_ex6 (BufLen, pBuffer, &DatLen);
62
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Requirements
V6.2 as200_as_info_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as200_as_zustand_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
63
Functions in PRODAVE MPI/IE V6.2
3.2.2
as200_as_zustand_ex6
Die Function as200_as_zustand_ex6 reads the AS state (RUN or STOP) from the
AS and stores the data in a storage area on the PG/PC.
int as200_as_zustand_ex6 (unsigned char * pState);
Parameters
pState
[out] Transfer buffer with AS states to be delivered (required length 1 byte)
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned char State;
//Transfer byte for the AS state
RetValue = as200_as_zustand_ex6 (&State);
Current Operating Mode (values in hex)
OM ID
Meaning
00
STOP
01
RUN
Requirements
V6.2 as200_as_zustand_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as200_as_info_ex6
64
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.2.3
as200_field_read_ex6
The function as200_field_read_ex6 reads a number of bytes or words from a data
area of the AS and transfers them to a PG/PC transfer buffer.
int as200_field_read_ex6 (char FieldType, unsigned short BlkNr, unsigned
short StartNr, unsigned long Amount, unsigned long BufLen, unsigned char *
pBuffer, unsigned long * pDatLen);
Parameters
FieldType
[in] Value types as ASCII characters: Input byte (e/E), output byte (a/A), memory
byte (m/M), special memory byte (s/S), variable storage byte (v/V), timer value
(t/T), counter value (z/Z)
BlkNr
[in] Block number (only required for data blocks), default = 0
StartNr
[in] Start number of the first byte or word to be read
Amount
[in] Amount of bytes or words to be read
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Transfer buffer for the read bytes or words
pDatLen
[out] Pointer on length of data delivered to the buffer in bytes. In event of error,
"Transfer buffer supplied too small for data" is returned and required buffer size
given.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
PRODAVE MPI/IE V6.1
A5E03681152-01
65
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
char FieldType = 0x45
//Value type = input byte (E)
unsigned short blkNr = 0;
//Block number = 0
unsigned short StartNr = 2;
//First word to be read = 2
int Amount = 6;
//Number of words to be read = 6
unsigned char Buffer[MAX_BUFFER];
//Transfer buffer
unsigned char *pBuffer = &Buffer[0];
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
unsigned long DatLen;
//Data length
RetValue = as200_field_read_ex6 (FieldType, BlkNr, StartNr, Amount, BufLen, pBuffer,
&DatLen);
Requirements
V6.2 as200_field_read_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as200_field_write_ex6
66
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.2.4
as200_field_write_ex6
The function as200_field_write_ex6 writes a number of bytes or words from a
PG/PC transfer buffer into a data area of the AS.
int as200_field_write_ex6(char FieldType, unsigned short BlkNr, unsigned
short StartNr, unsigned long Amount, unsigned long BufLen, unsigned char *
pBuffer);
Parameters
FieldType
[in] Value types as ASCII characters: Input byte (e/E), output byte (a/A), memory
byte (m/M), special memory byte (s/S), variable storage byte (v/V), timer value
(t/T), counter value (z/Z)
BlkNr
[in] Block number (only required for data blocks), default = 0
StartNr
[in] Start number of the first byte or word to be written.
Amount
[in] Amount of bytes or words to be written
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[in] Pointer on transfer buffer for the bytes or words to be written
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
PRODAVE MPI/IE V6.1
A5E03681152-01
67
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
char FieldType = 0x45
//Value type = input byte (E)
unsigned short blkNr = 0;
//Block number = 0
unsigned short StartNr = 2;
//First word to be written = 2
int Amount = 6;
//Number of words to be written = 6
unsigned char Buffer[MAX_BUFFER];
//Transfer buffer
unsigned char *pBuffer = Buffer;
//Transfer buffer address
unsigned long BufLen = sizeof(Buffer);
//Length of transfer buffer
RetValue = as200_field_write_ex6 (FieldType, BlkNr, StartNr, Amount, BufLen, pBuffer);
Requirements
V6.2 as200_field_write_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as200_field_read_ex6
68
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.2.5
as200_mb_setbit_ex6
The function as200_mb_setbit_ex6 sets a bit memory in the AS at 1 or 0. It is not
checked if the memory bit exists in the currently used AS.
int as200_mb_setbit_ex6 (unsigned short MbNr, unsigned short BitNr,
unsigned char Value);
Parameter
MbNr
[in] Number of the memory byte
BitNr
[in] Bit number in memory bytes
Value
[in] Value to be set (0/1)
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned short MbNr = 2;
//Memory byte number 2
unsigned short BitNr = 4;
//Bit number 4
unsigned char Value = 1;
//Value to be set = 1
RetValue = as200_mb_setbit_ex6 (MbNr, BitNr, Value);
Requirements
V6.2 as200_mb_setbit_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as200_mb_bittest_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
69
Functions in PRODAVE MPI/IE V6.2
3.2.6
as200_mb_bittest_ex6
The function as200_mb_bittest_ex6 checks a bit in a given memory byte and
returns the state of the given bit into a transfer buffer.
int as200_mb_bittest_ex6 (unsigned short MbNr, unsigned short BitNr, int *
pValue);
Parameters
MbNr
[in] Number of the memory byte
BitNr
[in] Bit number in memory bytes
pValue
[out] Pointer on transfer byte with the tested bit value
Value == TRUE
Bit set or 1
Value == FALSE
Bit is not set (or 0)
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message is given which can be evaluated in accordance with the error table
(see GetErrorMessage_ex6).
Call examples
int RetValue = 0;
unsigned short MbNr = 2;
//Memory byte number 2
unsigned short BitNr = 4;
//Bit number 4
int Value;
//Transfer byte for the bit value to be tested
RetValue = as200_mb_bittest_ex6 (MbNr, BitNr, &Value);
70
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Requirements
V6.2 as200_mb_bittest_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
as200_mb_setbit_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
71
Functions in PRODAVE MPI/IE V6.2
3.3
Convenience Functions
3.3.1
GetErrorMessage_ex6
The function GetErrorMessage_ex6 returns the error text corresponding to an
error number as a zero-terminated character string.
int GetErrorMessage_ex6 (int ErrorNr, unsigned long BufLen, unsigned char
* pBuffer);
Parameters
ErrorNr
[in] Fehlernummer
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Pointer on transfer buffer with the error text
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise the
function returns one of the following values:
72
0x7070
File ERROR.DAT is not available or cannot be opened.
0x7071
Too many error texts in the file ERROR.DAT
0x7072
Error while reading the file ERROR.DAT
0x7073
No error text available for this error number.
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
Call examples
int RetValue = 0;
int ErrorNr = 0x303;
//Block boundary exceeded, correct the
number
unsigned char Buffer[MAX_BUFFER];
//Transfer buffer for error text
unsigned long BufLen = sizeof(Buffer);
//Buffer length
unsigned char *pBuffer = &Buffer[0];
//Transfer buffer address
RetValue = GetErrorMessage_ex6 (ErrorNr, BufLen, pBuffer);
ERROR.DAT should not contain more than 512 error texts. The error text may not
exceed 200 characters.
When transferring the error number 0 the file name in "Buffer" may contain the
error text file to be transferred (e.g. an English or German language error text file).
If no valid file name is available or a NULL (ZERO) pointer is transferred, the
ERROR.DAT file in the current directory will be read. For this reason, it should be
ensured that the ERROR.DAT file exists and is placed in the same directory as the
program.
The ERROR.DAT file will be read when function GetErrorMessage_ex6 is called
for the first time and the text will be stored in a field.
It is recommended to call function GetErrorMessage_ex6 with error_no = 0 shortly
after the program begins in order to load the ERROR.DAT file. This ensures that
execution times for subsequent calls to the function are more or less constant.
Structure of the error text file
[Error number as ASCII Hex]: [Error text]
PRODAVE MPI/IE V6.1
A5E03681152-01
73
Functions in PRODAVE MPI/IE V6.2
Example for error texts in ERROR.DAT:
0x00E1:
Too many open channels
0x00E9:
sin_serv.exe not started
0x00CE:
Module not found
0x00CF:
Driver not loaded
0x00CA:
No resources available
0x00F1:
No global DOS memory available
0x0101:
Connection not established / assigned parameters
0x010a:
Negative acknowledgement received / timeout error
0x010c:
File does not exist or is blocked
0x0201:
Interface given is incorrect
0x0202:
Maximum number of interfaces exceeded
0x0203:
Toolbox already installed
0x0204:
Toolbox already installed with other connections
0x0205:
Toolbox not installed
0x0206:
Handle cannot be set
0x0207:
Data segment cannot be blocked
...
...
0xFFFE:
unknown error FFFE hex
0xFFFF
Timeout error. Check interface
Requirements
V6.2 GetErrorMessage_ex6
74
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.2
kg_2_float_ex6
The function kg_2_float_ex6 converts an S5 floating point value into a float type
value (IEEE format).
int kg_2_float_ex6 (unsigned long kg, float * pieee);
Parameters
kg
[in] S5 floating point value
pieee
[out] Counter on float value
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise 1.
Call examples
int RetValue = 0;
unsigned long kg = S5_FLOAT_VALUE;
float ieee;
//The IEEE floating point value will be
delivered into ieee
RetValue = kg_2_float_ex6 (kg, &ieee);
Requirements
V6.2 kg_2_float_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
float_2_kg_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
75
Functions in PRODAVE MPI/IE V6.2
3.3.3
float_2_kg_ex6
The function float_2_kg_ex6 converts a value of type float (IEEE format) into a S5
floating point value.
int float_2_kg_ex6 (float ieee, unsigned long * pkg);
Parameters
ieee
[in] Float value
pkg
[out] Pointer on S5 floating point value
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise 1.
Call examples
int RetValue = 0;
float ieee = FLOAT_VALUE;
unsigned long kg;
//The S5 floating point value will be
delivered to kg
RetValue = float_2_kg_ex6 (ieee, &kg);
Requirements
V6.2 float_2_kg_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
kg_2_float_ex6
76
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.4
gp_2_float_ex6
The function gp_2_float_ex6 converts an S7 floating point value into a value of
type float (IEEE format).
int gp_2_float_ex6 (unsigned long kg, float * pieee);
Parameters
gp
[in] S7 floating point value
pieee
[out] Counter on float value
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise 1.
Call examples
unsigned long gp = S7_FLOAT_VALUE;
float ieee;
//The IEEE floating point value will
be delivered into ieee
gp_2_float_ex6 (gp, &ieee);
Requirements
V6.2 gp_2_float_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
float_2_gp_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
77
Functions in PRODAVE MPI/IE V6.2
3.3.5
float_2_gp_ex6
The function float_2_gp_ex6 converts a value of type float (IEEE format) into a S7
floating point value.
int float_2_gp_ex6 (float ieee, unsigned long * pgp);
Parameters
ieee
[in] Float value
pgp
[out] Pointer on S7 floating point value
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise 1.
Call examples
float ieee = FLOAT_VALUE;
unsigned long gp;
//The S7 floating point value will be
delivered to gp
float_2_gp_ex6 (ieee, &gp);
Requirements
V6.2 float_2_gp_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
gp_2_float_ex6
78
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.6
testbit_ex6
The function testbit_ex6 checks if a given bit is set in a byte variable The byte
variable and bit number are transferred to the function by way of parameters.
int testbit_ex6 (char Value, int BitNr);
Parameters
Value
[in] Value of byte variable
BitNr
[in] Bit to be tested in byte variable
Return Values
Return value TRUE:
Bit is set (or 1)
Return value FALSE:
Bit is not set (or 0)
Call examples
none
Requirements
V6.2 testbit_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
79
Functions in PRODAVE MPI/IE V6.2
3.3.7
byte_2_bool_ex6
The function byte_2_bool_ex6 converts a byte into 8 logical values (PC
representation).
void byte_2_bool_ex6 (unsigned char Value, int * pBuffer);
Parameters
Value
[in] Byte value
pBuffer
[out] pointer on buffer with 8 converted logical values
Return Values
none
Call examples
The transferred pointer should point to an unsigned char field with the following
structure:
Buffer[0]
Buffer[1]
Buffer[2]
Buffer[3]
Buffer[4]
Buffer[5]
Buffer[6]
Buffer[7]
bit 0
bit 1
bit 2
bit 3
bit 4
bit 5
bit 6
bit 7
#define SIZE_BOOL_BYTE 8
int Buffer[SIZE_BOOL_BYTE];
//Buffer for 8 logical values
unsigned char Value = 1;
byte_2_bool_ex6 (Value, Buffer);
//TRUE will be delivered in Buffer[0], FALSE in
BUFFER[1]-[7].
Requirements
V6.2 byte_2_bool_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
bool_2_byte_ex6
80
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.8
bool_2_byte_ex6
The function bool_2_byte_ex6 converts 8 logical values (PC representation) into a
byte.
unsigned char bool_2_byte_ex6 (int * pBuffer);
Parameter
pBuffer
[in] Pointer on buffer with 8 logical values
Return Values
Converted byte value
Call examples
The transferred pointer should point to an unsigned char field with the following
structure:
Buffer[0]
Buffer[1]
Buffer[2]
Buffer[3]
Buffer[4]
Buffer[5]
Buffer[6]
Buffer[7]
bit 0
bit 1
bit 2
bit 3
bit 4
bit 5
bit 6
bit 7
unsigned char RetValue;
#define SIZE_BOOL_BYTE 8
int Buffer[SIZE_BOOL_BYTE] = {0};
//Buffer for 8 logical values
Buffer[0] = TRUE ;
RetValue = bool_2_byte_ex6 (Buffer);
//RetValue has a value of 1
Requirements
V6.2 bool_2_byte_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
byte_2_bool_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
81
Functions in PRODAVE MPI/IE V6.2
3.3.9
kf_2_integer_ex6, kf_2_long_ex6
The functions swap the high and low bytes of a given value.
kf_2_integer_ex6 swaps the high byte with the low byte of a 16-bit value.
kf_2_long_ex6 puts the 4 bytes of a 32 bit value in reversed order.
unsigned short kf_2_integer_ex6 (unsigned short wValue);
unsigned long kf_2_long_ex6 (unsigned long dwValue);
Parameters
wValue
[in] 16-bit values
dwValue
[in] 32-bit values
Return Values
kf_integer_ex6 delivers a 16-bit value with swapped bytes.
kf_long_ex6 delivers a 32-bit value with swapped bytes.
Call examples
Example: (Double word)
0
1
2
3
2
1
0
…swap…
3
Requirements
V6.2 kf_2_integer_ex6,
kf_2_long_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
swab_buffer_ex6
82
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.10
swab_buffer_ex6
The function swab_buffer_ex6 swaps the high and low bytes of words in a given
buffer.
void swab_buffer_ex6 (unsigned char * pBuffer, unsigned long Amount);
Parameters
pBuffer
[in/out] Pointer on the buffer in which the bytes are to be swapped
Amount
[in] Number of bytes to be swapped (even number)
Return Values
none
Call examples
The standard C function void_swab(char * src, char * dest, int n) will be called
internally.
a
b
c
x
…swap…
b
a
d
d
c
y
y
x
Requirements
V6.2 swab_buffer_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
kf_2_integer_ex6, kf_2_long_ex6, copy_buffer_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
83
Functions in PRODAVE MPI/IE V6.2
3.3.11
copy_buffer_ex6
The function copy_buffer_ex6 copies a number of bytes from one buffer into
another.
void copy_buffer_ex6 (unsigned char * pTargetBuffer, unsigned char *
pSourceBuffer, unsigned long Amount);
Parameters
pTargetBuffer
[out] Pointer on the buffer in which the bytes are to be copied
pSourceBuffer
[in] Pointer on the buffer from which the bytes are to be fetched.
Amount
[in] Amount of bytes to be copied
Return Values
none
Call examples
The standard C function void *memcpy(char * dest, char * src, size_t count) will
be called internally.
Requirements
V6.2 copy_buffer_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
swab_buffer_ex6
84
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.12
ushort_2_bcd_ex6, ulong_2_bcd_ex6
The functions are conversion routines that convert a number of binary values into
BCD values.
ushort_2_bcd_ex6 converts 16-bit values (words).
ulong_2_bcd_ex6 converts 32-bit values (double words).
void ushort_2_bcd_ex6 (unsigned short * pwValues, unsigned long Amount,
int InBytechange, int OutBytechange);
void ulong_2_bcd_ex6 (unsigned long * pdwValues, unsigned long Amount,
int InBytechange, int OutBytechange);
Parameters
pwValues
[in] Pointer on 16-bit binary values
pdwValues
[in] Pointer on 32-bit binary values
Amount
[in] Amount of values
InBytechange
[in] TRUE or FALSE (for example, 01, 00 is then interpreted as 256 or as 1)
OutBytechange
[in] TRUE or FALSE
Return Values
After calling the function, pwValues points to 16-Bit BCD values, pdwValuese to
32-bit BCD values.
Call examples
The function can be used, for example, to set counters or provide time functions.
If the parameter 'InBytechange' is set (1) then the high and low bytes will be
swapped before the conversion to BCD values. If the parameter ‘OutBytechange’ is
set, the high and low bytes will be swapped after the conversion.
If neither of the ByteChange arguments is set, then no high-low conversion will
take place.
The available value range for 16-bit BCD values is 0 to 999.
The available value range for 32-bit BCD values is 0 to 9 999 999.
PRODAVE MPI/IE V6.1
A5E03681152-01
85
Functions in PRODAVE MPI/IE V6.2
Requirements
V6.2 ushort_2_bcd_ex6,
ulong_2_bcd_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
bcd_2_ushort_ex6, bcd_2_ulong_ex6
86
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.13
bcd_2_ushort_ex6, bcd_2_ulong_ex6
The functions are conversion routines that convert a number of BCD values into
binary values.
bcd_2_ushort_ex6 converts 16-bit values (words).
bcd_2_ulong converts 32-bit values (double words).
void bcd_2_ushort_ex6 (unsigned short * pwValues, unsigned long Amount,
int InBytechange, int OutBytechange);
void bcd_2_ulong_ex6 (unsigned long * pdwValues, unsigned long Amount,
int InBytechange, int OutBytechange);
Parameters
pwValues
[in/out] Pointer on 16-bit BCD values
pdwValues
[in/out] Pointer on 32-bit BCD values
Amount
[in] Amount of values
InBytechange
[in] TRUE or FALSE
OutBytechange
[in] TRUE or FALSE
Return Values
After calling the function, pwValues points to 16-bit binary values, pdwValuese to
32-bit binary values.
Call examples
The function can be used, for example, to set counters or provide time functions.
If the parameter 'InBytechange' is set (1) then the high and low bytes will be
swapped before the conversion to binary values. If the parameter ‘OutBytechange’
is set, the high and low bytes will be swapped after the conversion.
If neither of the ByteChange arguments is set, then no high-low conversion will
take place.
The available value range for 16-bit BCD values is 0 to 999.
The available value range for 32-bit BCD values is 0 to 9 999 999.
PRODAVE MPI/IE V6.1
A5E03681152-01
87
Functions in PRODAVE MPI/IE V6.2
Requirements
V6.2 bcd_2_ushort_ex6,
bcd_2_ulong_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
ushort_2_bcd_ex6, ulong_2_bcd_ex6
88
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.3.14
GetLoadedConnections_ex6
Fills an array with 64 Boolean values The user receives information as to which of
the 64 connection numbers (ConNr) are already occupied and which connections
are already installed.
void GetLoadedConnections_ex6(unsigned long BufLen, int *pBuffer)
Parameters
BufLen
[in] Length of the transfer buffer specified by the user in bytes
pBuffer
[out] Pointer on an array with Boolean values
Return Values
none
Call examples
none
Requirements
V6.2 GetLoadedConnections_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
See also:
LoadConnection_ex6, UnloadConnection_ex6
PRODAVE MPI/IE V6.1
A5E03681152-01
89
Functions in PRODAVE MPI/IE V6.2
3.3.15
GetPduSize_ex6
Returns the maximum PDU size for communication with the connected CPU.
int GetPduSize_ex6(unsigned short ConNr)
Parameters
ConNr
[in] Number of the connection for which the PDU size is to be returned.
Return Values
If there were no errors, the function supplies the PDU size as the return value,
otherwise 0.
Call Examples
none
Requirements
V6.2 GetPduSize_ex6
90
Windows:
XP, Vista32, Windows7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.4
TeleService Functions
3.4.1
ts_dial_ex6
The function ts_dial_ex6 calls a remote station via modem and creates a
connection to the TS adapter.
int ts_dial_ex6 (char * cModemName, char * cStandort, char * cTelNo, char *
cUserName, char * cPassword, HANDLE WindowHandle, unsigned int
Message, WPARAM wParam, char * Res1);
Parameters
cModemName
[in] Name of modem to be used, configurable in Control Panel / Phone and Modem
Options / Dialing Rules.
cStandort
[in] Name of modem location, configurable in Control Panel / Phone and Modem
Options / Dialing Rules.
cTelNo
[in] Telephone number to be called by connected modem.
cUserName
[in] The user name is entered here as set up in TS adapter's parameters.
cPassword
[in] The password is given here as set up in TS adapter’s parameters.
WindowHandle
[in] A window handle can be given here.
Message
[in] Message to be sent to window in the event of successful connection or expired
timeout.
wParam
[in] Parameters for the message.
Res1
[in] Reserved for future expansions, must currently be preset to NULL (ZERO).
PRODAVE MPI/IE V6.1
A5E03681152-01
91
Functions in PRODAVE MPI/IE V6.2
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message which can be evaluated in accordance with the error table (see
GetErrorMessage).
Note
When function ts_dial_ex6 is called asynchronously, no error number will be
generated in the event of error. In this case, inform the user and allow him/her to
decide whether the function should be called again or if more detailed error
information is required. For detailed information, please use synchronous call.
Call examples
none
Requirements
V6.2 ts_dial_ex6
92
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.4.2
ts_hang_up_dial_ex6
The function ts_hang_up_dial_ex6 interrupts the current connection or a currently
running asynchronous dial operation.
int ts_hang_up_dial_ex6 (void);
Parameters
none
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message which can be evaluated in accordance with the error table (see
GetErrorMessage).
Call examples
none
Requirements
V6.2 ts_hang_up_dial_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
93
Functions in PRODAVE MPI/IE V6.2
3.4.3
ts_set_ringindicator_ex6
The function ts_set_ringindicator_ex6 initializes the low-frequency system for call
acceptance, connection set-up and announcement (ring indication).
int ts_set_ringindicator_ex6 (char * ModemName, char * NumberOfRings,
HANDLE WindowHandle, unsigned int Message, WPARAM wParam, char *
Res1);
Parameters
ModemName
[in] Name of modem to be used for purpose of ring indication, configurable in
Control Panel / Modems.
NumberOfRings
[in] Number of rings until modem picks up.
WindowHandle
[in] A window handle can be given here.
Message
[in] Message to be sent to window in the event of successful connection or expired
timeout.
wParam
[in] Parameters for the message.
Res1
[in] Reserved for future expansions, must currently be preset to NULL (ZERO).
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message which can be evaluated in accordance with the error table (see
GetErrorMessage).
Call examples
none
Requirements
V6.2
ts_set_ringindicator_ex6
94
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.4.4
ts_read_info_ex6
The function ts_read_about_ex6 delivers information about the alarming station.
int ts_read_info_ex6 (void * IventId, unsigned char * MpiAdr);
Parameters
IventId
[in] Pointer on a 16-byte long field. Information about the alarming station is
entered here.
MpiAdr
[in] Pointer on a byte. The MPI address of the alarm-triggering station is entered
here.
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message which can be evaluated in accordance with the error table (see
GetErrorMessage).
Call examples
none
Requirements
V6.2 ts_read_info_ex6
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
95
Functions in PRODAVE MPI/IE V6.2
3.4.5
ts_hang_up_ring_ex6
The function ts_hang_up_ring_ex6 interrupts the connection made by the TSAdapter.
int ts_hang_up_ring_ex6 (void);
Parameters
none
Return Values
If there were no errors, the function supplies 0 as the return value, otherwise an
error message which can be evaluated in accordance with the error table (see
GetErrorMessage).
Call examples
none
Requirements
V6.2 ts_hang_up_ring_ex6
96
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
PRODAVE MPI/IE V6.1
A5E03681152-01
Functions in PRODAVE MPI/IE V6.2
3.4.6
ts_get_modem_name_ex6
The function ts_get_modem_name_ex6 delivers the names of all system
recognized modems.
The function has to be called repeatedly for all modems until the return value
0x4502 is given. The ModemId must be incremented by one per call (start value =
0).
int ts_get_modem_name_ex6 (int ModemId, char * Buffer, int * BufferLen);
Parameters
ModemId
[in] Modem ID
0 ... n
Buffer
[out] Pointer on the buffer for modem names
BufferLen
[in/out] Pointer on the length of the buffer; contains the actual length of the string
with the modem name after the call.
Attention!
BufferLen must be selected large enough for the expected modem name before
the function is called.
Return Values
Attention!
RetVal == 0
A modem with the specified ModemId exists.
The buffer containts the modem name.
RetVal !=
0x4502
RetVal == 0x4502
No modem with the specified ModemId exists.
No further modems exist.
If there were no errors, the function supplies 0 as the return value, otherwise an
error message which can be evaluated in accordance with the error table (see
GetErrorMessage).
Call examples
none
PRODAVE MPI/IE V6.1
A5E03681152-01
97
Functions in PRODAVE MPI/IE V6.2
Requirements
V6.2 ts_get_modem_name_ex6
3.5
Windows:
XP, Vista32, 7
Header:
PRODAVE6.H
Library:
PRODAVE6.DLL
Data Structures
Prodave defines the following structures:
98
Name
Size
Explanation
TS_USERID:
16 bytes
CON_ADR_TYPE
6 bytes
Address type (MPI/PB, IP, MAC)
CON_TABLE_TYPE
9 bytes
Connection type with address information
AS_INFO_TYPE
26 bytes
Information structure with MLFB and version
information
AS200_INFO_TYPE
48 bytes
Information structure with MLFB and version
information
BST_DIAG_TYPE
40 bytes
Structure with block number and time stamp
DIAG_BUFFER_TYPE 20 bytes
Diagnostic buffer
BST_STAT_TYPE
96 bytes
Structure with block informationen
BST_HEADER_TYPE
140 bytes
Header of a block
IE_NODE
290 bytes
Devicee information of an IE station
struct tm
36 bytes
Structure by Microsoft (used only)
PRODAVE MPI/IE V6.1
A5E03681152-01
Glossary
Bit Memory (M)
A memory area in the system memory of a SIMATIC S7 CPU. This area can be
accessed using write or read access (bit, byte, word, and double word). The bit
memory area can be used by the user to store interim results.
Central Processing Unit (CPU)
The CPU is the central module in the programmable control system in which the
user program is stored and processed. It consists of an operating system,
processing unit, and communication interfaces.
Data Block (DB)
Data blocks are blocks which contain data and parameters with which the user
program works. In contrast to all other types of blocks, they contain no logic
instructions.
ERROR SEARCH Mode
This is an operating state of the standby CPU in an H system where the CPU
executes a complete self-test. At the same time, the master CPU is in RUN mode.
Function (FC)
According to the International Electrotechnical Commission's IEC 1131-3 standard,
functions are logic blocks without static data. A function allows you to pass
parameters in the user program, which means they are suitable for programming
complex functions that are required frequently, for example, calculations. Note: As
there is no memory available, the calculated values must be processed
immediately following the FC call.
Function Block (FB)
According to the International Electrotechnical Commission's IEC 1131-3 standard,
function blocks are logic blocks that reference an instance data block, meaning
they have static data. As function blocks have a 'memory' in the form of the
associated instance data block, its parameters (outputs, for example) can be
accessed at any time and any point in the user program.
PRODAVE MPI/IE V6.1
A5E03681152-01
99
Glossary
HOLD Mode
The HOLD state is reached from the RUN mode via a request from the
programming device. Special test functions are possible in this mode.
Logic Block
In SIMATIC S7, a logic block is a block that contains part of the STEP 7 user
program. The other type of block is a data block which contains only data. Logic
blocks are: Organization blocks (OB), function blocks (FB), functions (FC), system
function blocks (SFB) and system functions (SFC).
Multi Point Interface (MPI)
The multipoint interface is the programming device interface in SIMATIC S7/M7. It
allows a number of programmable modules, text displays, and operator panels to
be accessed from a central point.
The nodes on the MPI can communicate with each other.
Offline
When offline, no data link between the programming device and the programmable
logic controller exists.
Online
When online, a data link between the programming device and the programmable
logic controller exists.
Organization Block (OB)
Organization blocks form the interface between the S7 CPU operating system and
the user program. The sequence in which the user program should be processed is
laid down in the organization blocks.
PLC (AS)
A PLC is a programmable logic controller which consists of a central rack, a CPU,
and other I/O modules.
Point-to-Point Interface (PPI)
For the Point-to-Point interface, the communication processor is the interface
between a programmable logic controller and a communication partner.
Program Data Unit (PDU)
Describes the maximum size of a data package which can be recieved or sent by
the programming device. Usual sizes: 240/480/960 bytes.
100
PRODAVE MPI/IE V6.1
A5E03681152-01
Glossary
Programming Device (PG)
Personal computer in special industry-suitable and compact form. A PG is
completely equipped to configure SIMATIC automation systems.
RUN Mode
In the RUN state the user program is processed and the process image is updated
cyclically. In addition, all digital outputs are enabled.
STARTUP Mode
The CPU goes through the STARTUP state during the transition from the STOP
mode to the RUN mode. This mode can be set:
•
By using the mode selector
•
Following power-on
•
By an operation on the programming device.
A distinction is made between the STARTUP types cold restart, warm restart, and
hot restart.
STOP Mode
The following events place the CPU in the STOP state:
•
Moving the mode selector to the STOP position
•
An internal error in the CPU
•
An operation on the programming device
All modules are switched to a safe state.
In S7: The user program is not processed in STOP mode. Certain programming
functions and operator interface functions are, however, possible.
In M7: User programs can still be processed in STOP mode
System Data Block (SDB)
System data blocks are data areas in the CPU which contain the system settings
and module parameters. The system data blocks are generated and modified by
the STEP 7 Basic software.
System Function (SFC)
A system function (SFC) is a function integrated in the S7 CPU operating system
which can be called like a function in the user program when required.
System Function Block (SFB)
A system function block (SFB) is a function block integrated in the S7 CPU
operating system which can be called like a function block in the user program
when required.
PRODAVE MPI/IE V6.1
A5E03681152-01
101
Glossary
UPDATE Mode
The standby CPU of an H system reaches the UPDATE state when the H system
is in the update system mode. The master CPU updates the dynamic data of the
standby CPU
102
PRODAVE MPI/IE V6.1
A5E03681152-01
Index
A
as_info_ex6 34
as_zustand_ex6 36
as200_as_info_ex6 68
as200_as_zustand_ex6 70
as200_field_read_ex6 71
as200_field_write_ex6 73
as200_mb_bittest_ex6 76
as200_mb_setbit_ex6 75
Assigning Parameters to the PG/PC Interface
18
Automation License Manager 11
B
bcd_2_ulong _ex6 93
bcd_2_ushort_ex6 93
bool_2_byte_ex6 87
bst_read_diag_ex6 44
bst_read_ex6 48
bst_read_stat_ex6 46
byte_2_bool_ex6 86
C
Certificate of License 12
Checking the Address assignment 18
Checking the Interrupt Assignment 19
copy_buffer_ex6 90
D
db_buch_ex6 38
db_read_ex6 40
db_write_ex6 42
defrag_ex6 64
F
field_read_ex6 54
field_write_ex6 56
Flash memory file system 16
float_2_gp_ex6 84
float_2_kg_ex6 82
G
get_ie_lifelist_ex6 62
get_pb_lifelist_ex6 60
GetErrorMessage_ex6 78
GetLoadedConnections_ex6 95
PRODAVE MPI/IE V6.1
A5E03681152-01
GetPduSize_ex6 96
gp_2_float_ex6 83
Guidelines for Handling License Keys 14
I
Installation Procedure 16
Installation Requirements 15
Installing PRODAVE MPI/IE V6.2 15, 16
K
kf_2_integer_ex6 88
kf_2_long_ex6 88
kg_2_float_ex6 81
L
License Key 14
License types
Floating License 13
Single License 13
Trial License 13
Upgrade License 13
License Types
Enterprise License 11
Upgrade License 11
LoadConnection_ex6 27
M
mb_bittest_ex6 66
mb_setbit_ex6 65
MPI card in the PG/PC 18
MPI interface 15
MPI Interface 15
MPI-ISA-Card (Auto) 18
P
PG/PC Interface 18
Parameter Assignment 18
PRODAVE MPI/IE V6.2
Errors during Installation 17
Installation 15
Uninstalling 21
R
read_diag_buf_ex6 52
103
Index
S
SetActiveConnection_ex6 31
SetPassword_ex6 32
Setting
PG/PCInterface 18
Setup errors 16
swab_buffer_ex6 89
szl_read_ex6 58
T
testbit_ex6 85
ts_dial_ex6 97
ts_get_modem_name_ex6 103
ts_hang_up_dial_ex6 99
104
ts_hang_up_ring_ex6 102
ts_read_info_ex6 101
ts_set_ringindicator_ex6 100
U
ulong_2_bcd_ex6 91
Uninstalling
PRODAVE MPI/IE V6.2 21
User rights 14
UnloadConnection_ex6 30
UnSetPassword_ex6 33
User Rights Through The Automation License
Manager 11
ushort_2_bcd_ex6 91
PRODAVE MPI/IE V6.1
A5E03681152-01