Application description
09/2014
Sample applications for
SIMATIC BATCH COM API
http://support.automation.siemens.com/WW/view/en/92344632
Warranty and liability
Warranty and liability
Note
The Application Examples are not binding and do not claim to be complete
regarding the circuits shown, equipping and any eventuality. The Application
Examples do not represent customer-specific solutions. They are only intended
to provide support for typical applications. You are responsible for ensuring that
the described products are used correctly. These application examples do not
relieve you of the responsibility to use safe practices in application, installation,
operation and maintenance. When using these Application Examples, you
recognize that we cannot be made liable for any damage/claims beyond the
liability clause described. We reserve the right to make changes to these
Application Examples at any time without prior notice.
If there are any deviations between the recommendations provided in these
application examples and other Siemens publications – e.g. Catalogs – the
contents of the other documents have priority.
We do not accept any liability for the information contained in this document.
Siemens AG 2014 All rights reserved
Any claims against us – based on whatever legal reason – resulting from the use of
the examples, information, programs, engineering and performance data etc.,
described in this Application Example shall be excluded. Such an exclusion shall
not apply in the case of mandatory liability, e.g. under the German Product Liability
Act (“Produkthaftungsgesetz”), in case of intent, gross negligence, or injury of life,
body or health, guarantee for the quality of a product, fraudulent concealment of a
deficiency or breach of a condition which goes to the root of the contract
(“wesentliche Vertragspflichten”). The damages for a breach of a substantial
contractual obligation are, however, limited to the foreseeable damage, typical for
the type of contract, except in the event of intent or gross negligence or injury to
life, body or health. The above provisions do not imply a change of the burden of
proof to your detriment.
Any form of duplication or distribution of these Application Examples or excerpts
hereof is prohibited without the expressed consent of Siemens Industry Sector.
Security
information
Siemens provides products and solutions with industrial security functions that
support the secure operation of plants, solutions, machines, equipment and/or
networks. They are important components in a holistic industrial security
concept. With this in mind, Siemens’ products and solutions undergo continuous
development. Siemens recommends strongly that you regularly check for
product updates.
For the secure operation of Siemens products and solutions, it is necessary to
take suitable preventive action (e.g. cell protection concept) and integrate each
component into a holistic, state-of-the-art industrial security concept. Third-party
products that may be in use should also be considered. For more information
about industrial security, visit http://www.siemens.com/industrialsecurity.
To stay informed about product updates as they occur, sign up for a productspecific newsletter. For more information, visit
http://support.automation.siemens.com.
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
2
Table of contents
Table of contents
Warranty and liability ............................................................................................... 2
1
Preface ............................................................................................................ 4
2
VB 6.0 sample application.............................................................................. 5
2.1
2.2
2.3
3
C++ sample application ................................................................................ 10
3.1
3.2
3.3
About the source code of the sample ............................................... 10
What does the notification sample application do? ........................... 10
How to use the notification sample application ................................. 11
C# sample application .................................................................................. 13
Siemens AG 2014 All rights reserved
4
The sample source code.................................................................... 5
How to use the sample application ..................................................... 6
Tab pages in sample application ........................................................ 9
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
3
1 Preface
1
Preface
This documentation provides the user with sample applications with which he/she
can access data on SIMATIC BATCH System via function calls to COM API. The
samples show you how to use the COM API Interfaces. The sample applications
mainly focus on the description of the procedure for accessing data, not on creating
and describing the sample applications.
Used technologies
The sample applications are written in Visual Basic 6.0, C++ and C#
programming language.
SIMATIC BATCH COM API uses XML for input and output parameters.
Functional scope
Reading and writing data from/to SIMATIC BATCH System
Notifications on objects: API and SIS events
Controlling batches with archiving
Restriction
Siemens AG 2014 All rights reserved
To limit the scope of this document, it does not include a complete description of:
Programming languages
SIMATIC BATCH COM API
(see main documentation SIMATIC BATCH COM API)
SIMATIC BATCH system
SIMATIC PCS 7
Required knowledge
Basic knowledge of VB 6.0, C++ and C# is required to understand the functional
description.
Reference to Service & Support
This entry originates from the internet application portal of the A&D Service and
Support. The following link takes you directly to the download page of this
document:
http://support.automation.siemens.com
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
4
2 VB 6.0 sample application
2
VB 6.0 sample application
The sample software shows, how to use the COM API interface. You may also use
the sample applications to verify that the COM API interface runs in your
environment.
2.1
The sample source code
The source code is provided only as a supplement to the documentation and
demonstrates the use of the COM API interface. The source contains comments.
Siemens AG 2014 All rights reserved
NOTE
This sample application is not supported by Siemens AG as a fully functional
program. It is provided because we believe it may be useful to you. The sample
application is considered a sample code. We regret that Siemens is unable to
provide support or assistance in the event of specific problems using the sample
application.
The sample code does not have any implemented error handling or a user safety
prompt. Although we have created the sample code carefully, we cannot guarantee
a problem free usage. Therefore, we cannot accept any liabilities. You are free to
use the sample applications and/or modify the source code or use the source code
or parts of it in your programs. There is no licensing fee or restrictions for the usage
of the sample source code.
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
5
2 VB 6.0 sample application
2.2
How to use the sample application
The sample application requires a running SIMATIC BATCH System.
All API-functions return values. Errors are displayed in the "XML-output" window
below.
Siemens AG 2014 All rights reserved
VB 6.0 sample application, tab 1
1. Start: Initialize the COM API interface with the "Init" button. The session handle
will be displayed.
2. Shut down COM API: To close the COM API session, press the "Exit" button.
Then shut down the application with exit button from the menu bar.
3. Browse functions: Use the browse buttons on the left side of the combo
boxes to navigate inside the project. Use the combo boxes to choose or edit
the field. The content of the fields are used as input for other browse functions.
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
6
2 VB 6.0 sample application
4. Tab pages: Use the numbered tabs on top to open each single page with
functions.
5. Notification: After a click on "Advise2Pcell" all API-notifications will be listed in
the "notification" window.
Siemens AG 2014 All rights reserved
VB 6.0 sample application, tab 2
6. Functions: To use the functions, select or edit the parameters and press the
appropriate buttons.
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
7
2 VB 6.0 sample application
7. Open message files: Click on view menu and then on "Select file". Activate
the checkbox "Show MsgFiles" and select a message to open.
Figure 2-1: Select XML file
Siemens AG 2014 All rights reserved
8. Set batch state: Start batch with button "SetBatchState/-Ex".
9. Select batch state: Select a target state for batch from the combo box.
10. Create batch: Create the batch in the selected order.
11. Batch name, description and size: Insert the data for the batch.
12. Tree view for XML-Input, -Output and notifications: The logged XML
requests, responses and notifications can also be displayed as tree views.
Figure 2-2: XML Tree view
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
8
2 VB 6.0 sample application
2.3
Tab pages in sample application
All functions are partitioned into the following tab pages. At all tab pages have a
field with XML-Output, -Input and notifications.
Table 2-1
Siemens AG 2014 All rights reserved
Tab page
number
Generic term
Description / available functions
1
Project, Process Cell, Unit Class
and Unit
Initialize, set user, get projects, get process cell, get
unit classes, get technical units
2
Recipe and formula
Get, set, delete and create data related to master
recipes, libraries, and formulas
3
Order category, order and batch
Get, set, delete and create data related to order
categories, orders and batches
4
Material and quality
Get, set, delete and create data related to materials
and qualities
5
Notification and filter
Disable notification/object bits for API-notification
6
Allocation parameter
Get and set data related to allocations and
parameters
7
Common functions
Not object type related functions. Example:
"GetObjectData" and "GetErrorText"
8
Sequence Interception System
Connection to SIS-notification
9
Log book and print
Get log book objects and print objects
10
Command Manager
API command Manager interface
11
Audit trail
Apply user or other user rights for API-calls. Use for
multi user systems with API as server
12
Historical SIS events
SIS-event recovery
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
9
3 C++ sample application
3
C++ sample application
The sample code demonstrates how to use the COM API interface for notifications.
3.1
About the source code of the sample
The source code is provided only as a supplement to the documentation and
demonstrates the use of the COM API interface. The source contains comments.
Siemens AG 2014 All rights reserved
NOTE
This sample application is not supported by Siemens AG as a fully functional
program. It is provided because we believe it may be useful to you. The sample
application is considered a sample code. We regret that Siemens is unable to
provide support or assistance in the event of specific problems using the sample
application.
The sample code does not have any implemented error handling or a user safety
prompt. Although we have tested the sample code carefully, we cannot guarantee
a problem-free usage. Therefore, we cannot accept any liabilities. The sample
code is limited due to error handling and user confirmation dialogs. It is not
possible to claim that this is completely free of side effects. Though the sample
code is carefully tested, we can not guarantee that it will never bring any harm by
proper or improper use in your system. That's why any liability for damage of any
kind is hereby denied. You are free to use the application sample and/or modify the
source code or use the source code or parts of it in your programs. There is no
licensing fee or restrictions for the usage of the sample source code.
3.2
What does the notification sample application do?
The COM API notifies the client application about changes in the SIMATIC BATCH
system. The tool enables you to see the content of the incoming notification.
Notifications can be filtered according to the notification - or object type.
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
10
3 C++ sample application
3.3
How to use the notification sample application
1. In the start dialog box you select the SIMATIC BATCH project and press OK.
Figure 3-1: Notification filter
2. The notification window opens. From now, every operation in COM API will
create an incoming notification, which is displayed as one line in the window.
Siemens AG 2014 All rights reserved
Figure 3-2: C++ sample application
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
11
3 C++ sample application
3. You can open a filter dialog by clicking the "Filter" button. In the filter dialog you
may filter notification or object types. If nothing is selected, all notifications will
be received and displayed.
Siemens AG 2014 All rights reserved
Figure 3-3: Notification filter
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
12
4 C# sample application
4
C# sample application
The sample software shows, how to use the COM API interface. The source code
is C# and the fuctionality is the same as with VB V6.0. Layout and arrangement
have been updated.
Siemens AG 2014 All rights reserved
Figure 4-1: C# INIT tab
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
13
4 C# sample application
Siemens AG 2014 All rights reserved
Figure 4-2: C# ORDER and BATCH tab
NOTE
This sample application is not supported by Siemens AG as a fully functional
program. It is provided because we believe it may be useful to you. The sample
application is considered as sample code. We regret that Siemens is unable to
provide support or assistance in the event of specific problems using the sample
application.
Sample applications for SIMATIC BATCH COM API
Entry-ID: 92344632, V1.0, 09/2014
14