Appendix A - Values of rb_response with Windows 95, Windows NT and MS-DOS. Appendix B - Error Messages of the SEND/RECEIVE Functions

Transcription

1 SIMATIC NET SEND/RECEIVE Programming Interface Manual 1 Introduction to the SEND/RECEIVE Programming Interface 2 Communication with SIMATIC S5 Programmable Controllers 3 Communication with SIMATIC S7 Programmable Controllers 4 Communication with PCs/Workstations 5 SEND/RECEIVE Request Block 6 Description of the SEND/RECEIVE Job Types 7 How to Compile a Program Appendix A - Values of rb_response with Windows 95, Windows NT and MS-DOS Appendix B - Error Messages of the SEND/RECEIVE Functions Glossary C79000-G8976-C097 Release 6 SIMATIC NET is a trademark of Siemens Siemens Aktiengesellschaft

2 Wir haben den Inhalt der Druckschrift auf Übereinstimmung mit der beschriebenen Hard- und Software geprüft. Dennoch können Abweichungen nicht ausgeschlossen werden, so daß wir für die vollständige Übereinstimmung keine Gewähr übernehmen. The Angaben in der Druckschrift werden jedoch regelmäßig überprüft. Notwendige Korrekturen sind in den nachfolgenden Auflagen enthalten. Für Verbesserungsvorschläge sind wir dankbar. Technische Änderungen vorbehalten. Weitergabe sowie Vervielfältigung dieser Unterlage, Verwertung und Mitteilung ihres Inhalts nicht gestattet, soweit nicht ausdrücklich zugestanden. Zuwiderhandlungen verpflichten zu Schadenersatz. Alle Rechte vorbehalten, insbesondere für den Fall der Patenterteilung oder GM-Eintragung. C79000-G8976-C097 Copyright Siemens AG 1998 to 2000 All Rights Reserved We have checked the contents of this manual for agreement with the hardware described. Since deviations cannot be precluded entirely, we cannot guarantee full agreement. However, the data in this manual are reviewed regularly and any necessary corrections included in subsequent editions. Suggestions for improvement are welcome. Technical data subject to change. The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility or design, are reserved. C79000-G8976-C097 Copyright Siemens AG 1998 to 2000 All Rights Reserved Nous avons vérifié la conformité du contenu du présent manuel avec le matériel et le logiciel qui y sont décrits. Or, des divergences n'étant pas exclues, nous ne pouvons pas nous porter garants pour la conformité intégrale. Si l'usage du manuel devait révéler des erreurs, nous en tiendrons compte et apporterons les corrections nécessaires dès la prochaine édition. Veuillez nous faire part de vos suggestions. Nous nous réservons le droit de modifier les caractéristiques techniques. Toute communication ou reproduction de ce support d'informations, toute exploitation ou communication de son contenu sont interdites, sauf autorisation expresse. Tout manquement à cette règle est illicite et expose son auteur au versement de dommages et intérêts. Tous nos droits sont réservés, notamment pour le cas de la délivrance d'un brevet ou celui de l'enregistrement d'un modèle d'utilité. C79000-G8976-C097 Copyright Siemens AG 1998 to 2000 All Rights Reserved Siemens Aktiengesellschaft Elektronikwerk Karlsruhe Printed in the Federal Republic of Germany

3 SIMATIC NET SEND/RECEIVE Programming Interface Manual C79000-B8976-C082/07

4 Note We point out that the contents of this instruction manual shall not become a part of or modify any prior or existing agreement, commitment or legal relationship. The Purchase Agreement contains the complete and exclusive obligation of Siemens. Any statements contained in this documentation do not create new warranties or restrict the existing warranty. We would further point out that, for reasons of clarity, this instruction manual cannot deal with every possible problem arising from the use of this device. Should you require further information or if any special problems arise which are not sufficiently dealt with in the instruction manual, please contact your local Siemens representative. General WARNING!! This device is electrically operated. In operation, certain parts of this device carry hazardous voltages. Non-observance of the safety instructions can result in severe personal injury or property damage. Only qualified personnel should work on or around this equipment after becoming thoroughly familiar with all warnings, safety notes and maintenance procedures contained herein. The successful and safe operation of this equipment is dependent on proper handling, installation, operation, and maintenance. Qualified Personnel Qualified personnel as referred to in this instruction manual or in the warning notes is defined as persons who are familiar with the installation, assembly, startup, and operation of this product and who possess the relevant qualification for their work, e.g.: training in or authorization for connecting up, grounding or labeling circuits and devices or systems in accordance with current standards in safety technology; training in or authorization for the maintenance and use of suitable safety equipment in accordance with current standards in safety technology; First Aid qualification.

5 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface The SEND/RECEIVE Programming Interface The SIMATIC S5/S7 system components communicate with each other via the SEND/RECEIVE communications protocol. The SEND/RECEIVE programming interface has been developed to provide programming device/pc user programs with access to SIMATIC S5/S7 system components. Its C programming interface allows you simple and flexible access to the data of S5/S7 system components. This volume describes the SEND/RECEIVE protocol and its programming. 5

6 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Contents Note The table of contents shown below contains only first and second order titles to improve clarity. Each chapter therefore contains a detailed table of contents on the first page of the chapter. 1 Introduction to the SEND/RECEIVE Programming Interface Advantages of the SEND/RECEIVE Programming Interface SEND/RECEIVE Programming Interface under Windows 95 and Windows NT in the Single Device Mode SEND/RECEIVE Programming Interface under Windows 95 and Windows NT in the Multi-Device Mode The Trace under Windows 95 and Windows NT SEND/RECEIVE Programming Interface under MS-DOS Communication with SIMATIC S5 Programmable Controllers General Notes on the Description in this Chapter General Sequence of Communication Phase 1: Logon Phase 2: Connection Establishment - Description Phase 3: Data Exchange Phase 4: Connection Termination and Logoff Aborted Communication Communication with SIMATIC S7 Programmable Controllers General Notes on the Description in this Chapter General Outline of Communication Procedures Phase 1: Logon Phase 2: Connection Establishment - Description Phase 3: Data Exchange Phase 4: Connection Termination and Logoff Aborted Communication in General Communication with PCs/Workstations General Notes on the Description in this Chapter General Outline of Communication Procedures Phase 1: Logon Phase 2: Connection Termination Phase 3: Data Exchange Phase 4: Connection Termination and Logoff Aborted Communication in General

7 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 5 SEND/RECEIVE Request Block General Notes on the Request Block Description of the SEND/RECEIVE Request Block Request Block Header Variable Field open_reference Variable Field Variable Field Transport Address Buffer User Data Buffer Variable Field User Data Buffers 2 and Description of the SEND/RECEIVE Job Types Overview Logon OPEN_REQUEST Connection Establishment SEND_CONNECT_REQUEST (active) Connection Establishment AWAIT_CONNECT_REQUEST (passive) Connection Establishment AWAIT_CONNECT_REQUEST_USER (passive) Connection Establishment ACCEPT_CONNECT_REQUEST (passive) Data Exchange SEND_DATA and SEND_EOM_DATA Data Exchange RECEIVE_DATA Data Exchange SEND_EXPEDITED_DATA Data Exchange RECEIVE_EXPEDITED_DATA Connection Termination CLOSE_REQ Connection Termination AWAIT_CLOSE How to Compile a Program Procedure when Compiling Requirements with a SIMATIC S5 PLC Requirements with a SIMATIC S7 PLC Appendix A - Values of rb_response with Windows 95, Windows NT and MS-DOS Appendix B - Error Messages of the SEND/RECEIVE Functions Glossary

8 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Notes 8

9 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 1 Introduction to the SEND/RECEIVE Programming Interface This chapter deals with the following topics: the advantages of the SEND/RECEIVE programming interface, how the SEND/RECEIVE Programming Interface operates in the single and multidevice modes how the sample and SEND/RECEIVE functions work which support is available to programmers in addition to the manual, how user programs use the SEND/RECEIVE programming interface what is involved in job handling with SOFTNET Industrial Ethernet Contents of Chapter Advantages of the SEND/RECEIVE Programming Interface SEND/RECEIVE Programming Interface under Windows 95 and Windows NT in the Single Device Mode SEND/RECEIVE SetSR( ) Function SEND/RECEIVE Call_Ina( ) Function SEND/RECEIVE ResetSR( ) Function Signaling SEND/RECEIVE Programming Interface under Windows 95 and Windows NT in the Multi-Device Mode SEND/RECEIVE SRMD_Set( ) Function SEND/RECEIVE Function SRMD_Request( ) SEND/RECEIVE Function SRMD_Reset( ) Signaling The Trace under Windows 95 and Windows NT The SEND/RECEIVE SR_Trace Function Parameters of the Trace Parameter SR_Trace_Target Parameter SR_Trace_Depth Parameter SR_Trace_Select SEND/RECEIVE Programming Interface under MS-DOS SEND/RECEIVE Call_Ina( ) Function

10 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 1.1 Advantages of the SEND/RECEIVE Programming Interface Access to SIMATIC S5 The SEND/RECEIVE programming interface allows you to set up communication between your PC and SIMATIC programmable controllers, primarily with SIMATIC S5 PLCs. Programmer Support To familiarize programmers with the SEND/RECEIVE programming interface, support software is also shipped with the documentation: sample programs, and a job library Sample Programs Sample programs are included. These are written in the "C" programming language. They allow you to see how the interface operates. With suitable adaptation, you can even use parts of the sample programs in your own programs. Job Library The job library for function jobs of the SEND/RECEIVE interface can also be very helpful. It is written in "C" and is also shipped with the documentation. For C programmers, this means: the job library can be integrated directly into your own software; the jobs contained in the library can be used directly as described in the sample programs. Apart from the theoretical explanation in the manual, the handling of data structures (request block) is illustrated in a practical context by sample programs and function jobs. Independent of the Transport Protocol You can choose between the ISO Transport protocol and the TCP/IP protocol. The choice of transport protocol does not affect the SEND/RECEIVE programming interface. Multi-Device Mode With the SEND/RECEIVE programming interface, the "Multi-Device mode is possible. This means that one or more user programs (applications) can address one or more network cards in the local PC at the same time. Each network card can also be addressed via one or more "access points of the application". 10

11 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 1.2 SEND/RECEIVE Programming Interface under Windows 95 and Windows NT in the Single Device Mode Software Components The SEND/RECEIVE programming interface package includes SEND/RECEIVE functions and sample programs and sample functions. Integration of the Software Components The sample programs and the sample and SEND/RECEIVE functions handle the basic tasks of communication. They are part of the product and can be integrated into the user software if the task to be performed is appropriate. The Single Device Mode In the single device mode, the single device functions are used. The user can communicate using only one access point of the application per user program. SEND/RECEIVE Functions In the single device mode of the SEND/RECEIVE programming interface under Windows 95 and Windows NT, there are the following SEND/RECEIVE functions: SetSR( ) Call_Ina( ) ResetSR( ) These are parts of the SEND/RECEIVE function library (S7_SR.DLL). Following Sections The remainder of this section shows first a graphical overview of the software components followed by a description of the operation of the components. 11

12 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 SEND/RECEIVE Programming Interface in the Single Device Mode The schematic below illustrates the functions of the SEND/RECEIVE programming interface under Windows 95 and Windows NT in the single device mode. Sample programs e.g. SRSample SEND/RECEIVE function SetSR( ) Further sample functions Sample functions INA_CONNECT INA_LISTEN INA_CLOSE INA_OPEN INA_RECEIV INA_SEND Request blocks SEND/RECEIVE function Call_Ina( ) Message ISO protocol 8073 or TCP/IP with RFC 1006 Sample programs Transport protocol e.g. SRSample Message Receive thread of SEND/RECEIVE Message SEND/RECEIVE function ResetSR( ) 12

13 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Dynamic Sequence The following table describes the individual phases of a function sequence used to call communications job. Stage Procedure 1 Calling the SEND/RECEIVE function SetSR( ) transfers an "access point of the application" initializes signaling. 2 A sample program calls a sample function. 3 This sample function fills the request block with job data. 4 Afterwards, the sample function calls the SEND/RECEIVE Call_Ina( ) function. In so doing, the request block is transferred to Call_Ina( ). 5 The SEND/RECEIVE Call_Ina( ) function transfers the request block to the communications software. 6 The transport protocol handles the job. Here, the Windows sample program can be continued, for example, to send further jobs. 7 When the job has been processed, this is reported to the SEND/RECEIVE message thread. 8 The SEND/RECEIVE receive thread signals completion of the job with a message to the sample program. The request block is returned. 9 The SEND/RECEIVE function ResetSR( ) closes the "access point of the application" used in this call. 13

14 SEND/RECEIVE Programming Interface C79000-G8976-C097/ SEND/RECEIVE SetSR( ) Function Description With the SEND/RECEIVE SetSR( ) function, the user program initializes the "access point of the application" and at the same time selects the corresponding network card. How Signaling Works The SEND/RECEIVE SetSR( ) function must be called before the first Call_Ina( ) function. You can check the available "access points of the application" in the configuration menu. To release the connection to the initialized "access point of the application" again, the ResetSR( ) function must be called. Restriction The SEND/RECEIVE SetSR( ) function must not be called more than once per user program. This means that a user program in the single device mode can use only one "access point of the application". Syntax int SetSR (LPSTR SRAccessPoint, HWND SRwnd, UINT SRmsg) Meaning of the Parameter The parameters of the SEND/RECEIVE SetSR( ) function have the following meaning: Parameter Type Description SRAccessPoint LPSTR "Access point of the application" for the selected CP. SRwnd HWND A handle to the window of the user program in which the messages of the SEND/RECEIVE programming interface are managed. SRmsg UINT ID of messages received by the user program via the SEND/RECEIVE programming interface. SRmsg must be greater than WM_USER (Windows constant). Return Value If the SEND/RECEIVE SetSR( ) function call was successful, 0 is returned, otherwise, the return value is -1. If an error occurred, the precise cause of the error can be queried with the GetLastError( ) function. The error constants are described in Appendix B - Error Messages of the SEND/RECEIVE Functions. 14

15 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface SEND/RECEIVE Call_Ina( ) Function Description All functions must call the SEND/RECEIVE Call_Ina( ) function after they have filled in the request block. The Call_Ina function passes the communications job on. How Signaling Works Before the Call_Ina( ) function is called, the request block must be filled with job-specific data. Then a pointer to the request block is transferred to the SEND/RECEIVE Call_Ina( ) function by the calling function. Chapters 5 and 6 contain detailed information on the SEND/RECEIVE request block. Syntax int Call_Ina(RB * rb) Meaning of the Parameter The parameter of the SEND/RECEIVE Call_Ina( ) function has the following meaning: Parameter Type Description rb RB * Pointer to the user-defined request block. Return Value If the SEND/RECEIVE Call_Ina( ) function call was successful, 0 is returned, otherwise the return value is -1. If an error occurred, the precise cause of the error can be queried with the GetLastError( ) function. The error constants are described in Appendix B - Error Messages of the SEND/RECEIVE Functions. 15

16 SEND/RECEIVE Programming Interface C79000-G8976-C097/ SEND/RECEIVE ResetSR( ) Function Description The SEND/RECEIVE ResetSR( ) function closes the "access point of the application" that was initialized with the SetSR( ) function. Syntax int ResetSR(void) Return Value If the SEND/RECEIVE ResetSR( ) function call was successful, 0 is returned, otherwise -1. If an error occurred, the precise cause of the error can be queried with the GetLastError( ) function. The error constants are described in Appendix B - Error Messages of the SEND/RECEIVE Functions. 16

17 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Signaling Purpose The signaling procedure helps to avoid the user program having to wait for job processing to be completed. How Signaling Works With the SEND/RECEIVE SetSR( ) function, the function parameters SRwnd and SRmsg are transferred to the SEND/RECEIVE programming interface. These parameters are used for signaling in a Windows environment. Signaling in the User Program The user program transmits a job by calling the Call_Ina( ) function. After the job has been processed, the relevant PostMessage( ) (Windows function) is transferred by the SEND/RECEIVE programming interface to the calling user program. Implementation in the User Program The SEND/RECEIVE function library "S7_SR.DLL is either loaded automatically when the user program starts or using the Windows function "LoadLibrary( ). A receive thread is also generated. If a SEND/RECEIVE job is processed by the user program, the following takes place in the receive thread: It receives a message It reads the result buffer It passes on a message indicating the end of the SEND/RECEIVE job to the user program using SRwnd as the window handle and SRmsg as the message ID. How the PostMessage( ) Function Works The SEND/RECEIVE programming interface transfers the following parameters to the PostMessage( ) function: PostMessage(SRwnd, SRmsg, rb_user, RB * rb) Using the rb_user and RB * rb parameters, a message can be uniquely assigned to a previously transmitted job. 17

18 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 1.3 SEND/RECEIVE Programming Interface under Windows 95 and Windows NT in the Multi-Device Mode Software Components The SEND/RECEIVE programming interface package includes SEND/RECEIVE functions and sample programs and sample functions. Integration of the Software Components Sample programs and SEND/RECEIVE and sample functions perform basic communication tasks. They are part of the product and can be integrated into the user software if the task to be performed is appropriate. The Multi-Device Mode In the multi-device mode, the multi-device functions are used. The user can communicate via more than one "access point of the application" per user program. SEND/RECEIVE Functions In the Multi-Device mode of the SEND/RECEIVE programming interface under Windows 95 and Windows NT, the following SEND/RECEIVE functions are available: SRMD_Set( ) SRMD_Request( ) SRMD_Reset( ) These are parts of the SEND/RECEIVE function library (S7_SR.DLL). Following Sections The remainder of this section shows first a graphical overview of the software components followed by a description of the operation of the components. 18

19 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface SEND/RECEIVE Programming Interface in the Multi-Device Mode The schematic below illustrates the functions of the SEND/RECEIVE programming interface under Windows 95 and Windows NT in the multi-device mode. Sample programs e.g. SRSample SEND/RECEIVE function SRMD_Set( ) Further sample programs Sample functions INA_CONNECT INA_LISTEN INA_CLOSE INA_OPEN INA_RECEIV INA_SEND Request blocks SEND/RECEIVE function SRMD_Request( ) Message ISO protocol 8073 or TCP/IP with RFC 1006 Sample programs Transport protocol e.g. SRSample Message Receive thread of SEND/RECEIVE Message SEND/RECEIVE function SRMD_Reset( ) 19

20 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Dynamic Sequence The following table describes the individual phases of a function sequence used to call communications job. Stage Procedure 1 With the SEND/RECEIVE SRMD_Set( ) function call, an "access point of the application" is transferred and signaling initialized. 2 A sample program calls a sample function. 3 This sample function fills the request block with job data. 4 The sample function then calls the SEND/RECEIVE SRMD_Request( ) function. At the same time, the request block is transferred to SRMD_Request( ). 5 The SEND/RECEIVE function SRMD_Request( ) transfers the request block to the communications software. 6 The transport protocol handles the job. Here, the Windows sample program can be continued, for example, to send further jobs. 7 When the job has been processed, this is reported to the SEND/RECEIVE message thread. 8 The SEND/RECEIVE receive thread signals completion of the job with a message to the sample program. The request block is returned. 9 The SEND/RECEIVE function SRMD_Request( ) closes the "access point of the application" used. 20

21 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface SEND/RECEIVE SRMD_Set( ) Function Description With the SEND/RECEIVE function SRMD_Set( ), the user program initializes the "access point of the application" and at the same time selects the corresponding network card. How Signaling Works The SEND/RECEIVE SRMD_Set( ) function must be called before the first SRMD_Request( ) call. You can check the available "access points of the application" in the configuration menu. To release the connection to the initialized "access point of the application" again, the SRMD_Reset( ) function must be called. This means that a user program in the multi-device mode can use more than one "access point of the application". Restriction The maximum number of "access points of the application" on the computer is 32. Syntax int SRMD_Set (LPSTR SRAccessPoint, HWND SRwnd, UINT SRmsg) Meaning of the Parameter The parameters of the SEND/RECEIVE function SRMD_Set( ) have the following meaning: Parameter Type Description SRAccessPoint LPSTR "Access point of the application" for the selected CP. SRwnd HWND A handle to the window of the user program in which the messages of the SEND/RECEIVE programming interface are managed. SRmsg UINT ID of messages received by the user program via the SEND/RECEIVE programming interface. SRmsg must be greater than WM_USER (Windows constant). 21

22 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Return Value If the SEND/RECEIVE SRMD_Set( ) function call was successful, values >= 0 are returned, otherwise values < 0. Return Value Meaning >= 0 Handle to the transferred "access point of the application" < 0 If an error occurred, the precise cause of the error can be queried with the GetLastError( ) function. The error constants are described in "Appendix B - Error Messages of the SEND/RECEIVE Functions. 22

23 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface SEND/RECEIVE Function SRMD_Request( ) Description After the request block has had data entered, all functions must call the SEND/RECEIVE SRMD_Request( ) function. The Call_Ina function passes the communications job on. How Signaling Works Before the SRMD_Request( ) function is called, the request block must be filled with job-specific data. The SEND/RECEIVE SRMD_Request( ) function is transferred a pointer to the request block by the calling function. Chapters 5 and 6 contain detailed information on the SEND/RECEIVE request block. Syntax int SRMD_Request(int hsraccesspoint, RB * rb) Meaning of the Parameter The parameter of the SEND/RECEIVE SRMD_Request( ) FUNCTION has the following meaning: Parameter Type Description hsraccesspoint INT Handle to the transferred "access point of the application"; return value of SRMD_Set( ) rb RB * Pointer to the user-defined request block. Return Value If the SEND/RECEIVE function SRMD_Request( ) was successful, 0 is returned, otherwise -1. If an error occurred, the precise cause of the error can be queried with the GetLastError( ) function. The error constants are described in Appendix B - Error Messages of the SEND/RECEIVE Functions. 23

24 SEND/RECEIVE Programming Interface C79000-G8976-C097/ SEND/RECEIVE Function SRMD_Reset( ) Description The SEND/RECEIVE function SRMD_Reset( ) closes the "access point of the application" named in the transferred parameter. Syntax int SRMD_Reset(hSRAccessPoint) Meaning of the Parameter The parameter of the SEND/RECEIVE SRMD_Reset( ) FUNCTION has the following meaning: Parameter Type Description hsraccesspoint INT Handle to the "access point of the application"; return value of SRMD_Set( ) Return Value If the SEND/RECEIVE function SRMD_Reset( ) was successful, 0 is returned, otherwise -1. If an error occurred, the precise cause of the error can be queried with the GetLastError( ) function. The error constants are described in Appendix B - Error Messages of the SEND/RECEIVE Functions. 24

25 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Signaling Purpose The signaling procedure helps to avoid the user program having to wait for job processing to be completed. How Signaling Works With the SEND/RECEIVE SRMD_Set( ) function, the function parameters SRwnd and SRmsg are transferred to the SEND/RECEIVE programming interface. These parameters are used for signaling in a Windows environment. Signaling in the User Program The user program transmits a job by calling the SRMD_Request( ) function. After the job has been processed, the relevant PostMessage( ) (Windows function) is transferred by the SEND/RECEIVE programming interface to the calling user program. Implementation in the User Program The SEND/RECEIVE function library (S7_SR.DLL) is loaded automatically when the user program is started. A receive thread is also generated. If a SEND/RECEIVE job is processed by the user program, the following takes place in the receive thread: It receives a message It reads the result buffer It passes on a message indicating the end of the SEND/RECEIVE job to the user program using SRwnd as the window handle and SRmsg as the message ID. How the PostMessage( ) Function Works The SEND/RECEIVE programming interface transfers the following parameters to the PostMessage( ) function: PostMessage(SRwnd, SRmsg, rb_user, RB * rb) Using the rb_user and RB * rb parameters, a message can be uniquely assigned to a previously transmitted job. 25

26 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 1.4 The Trace under Windows 95 and Windows NT What is Meant by Trace? Under Windows 95 and Windows NT, the trace is a simple and nevertheless effective aid to debugging the SR library. During operation, the SR library writes important data to the trace file. The content of the trace file is used as a log of all actions executed by the SR library. allows the sequence of events to be checked both for the application and for the library itself. allows simple debugging and checking of the data and parameters on the SEND/RECEIVE programming interface. Uses of the Trace When active, the trace writes data and events to the trace file. It can be adapted to a wide range of situations and applications: You can select any name for the trace file. The parameter SR_Trace_Target specifies whether or not a new trace file should be created or an old one used. The parameter SR_Trace_Depth can be set for all trace types: Trace active only for negative events Trace of all SEND/RECEIVE functions Trace dump of the transferred request blocks With the parameter SR_Trace_Select, you can select the events to be logged. You can also write to the trace file yourself. Such entries can be used to save important data for checking and to check the running of the program. Time Requirements The trace and writing data to the trace file slows down the application. 26

27 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface The SEND/RECEIVE SR_Trace Function Description With this call, any entries can be made in the trace file. This makes it possible to save important data so that they can be checked, to check the running of the program and to synchronize it with the trace entries. Requirements Under Windows NT, the parameters can only be modified if you have administrator rights. Syntax int SR_Trace(char 5format[, argument]...) Meaning of the Parameter The parameter of the trace function SR_Trace has the following meaning: Parameter Type Description format[, argument]... CHAR 5 Formatted string with the user message to be entered in the trace file. In one trace line, the current time, a process ID (PID) and thread ID (TID) are output before the actual trace information. The syntax corresponds to the C function printf( ). Return Value If the SEND/RECEIVE function SR_Trace( ) was successful, 0 is returned, otherwise -1. If an error occurred, the precise cause of the error can be queried with the GetLastError( ) function. The error constants are described in Appendix B - Error Messages of the SEND/RECEIVE Functions. 27

28 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Parameters of the Trace Adapting the Trace The trace can be adapted to a wide variety of applications by modifying the trace parameters. The trace parameters for adapting the trace to your requirements are described below. The parameters can be set with a utility; Name: "Setting the PG/PC Interface. Parameters of the Trace The running of the trace is controlled by parameters. Names of the Trace Parameters SR_Trace_Filename SR_Trace_MaxLines SR_Trace_MaxFiles SR_Trace_Target SR_Trace_Depth SR_Trace_Select The meaning of the parameters is described in the following sections. The values of the constants described here are contained in the file SR_TRACE.H. SR_Trace_ Filename The name of the trace file and path are entered in this parameter. Default: SRTRACE.TXT in the current working directory. SR_Trace_ MaxLines The maximum number of lines in the trace file is specified in this parameter. Once the maximum number of lines is reached, a new trace file is opened. Default: SR_Trace_ MaxFiles The maximum number of trace files is specified in this parameter. If the maximum number of files is reached, recording starts again in the first trace file. This means that the last (SR_Trace_MaxFiles - 1) files are always available. Default: 2 28

29 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Further Parameters The remaining parameters require more detailed description: SR_Trace_Target SR_Trace_Depth SR_Trace_Select These parameters are described in separate sections. 29

30 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Parameter SR_Trace_Target Description The target for the trace is specified in this parameter. The following values can be set: Parameter Values TRACE_TARGET_NEW_FILE TRACE_TARGET_OLD_FILE Description The trace entries are written to a file. The file is created. Any old entries in this file are deleted. The trace entries are written to a file. An existing file remains unchanged subsequent trace entries are appended to the older entries. Default TRACE_TARGET_NEW_FILE 30

31 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Parameter SR_Trace_Depth Description The trace depth is set in this parameter. The following values can be set: Parameter Values TRACE_DEPTH_OFF TRACE_DEPTH_USER TRACE_DEPTH_ERROR TRACE_DEPTH_INFO TRACE_DEPTH_BUF_SR Trace deactivated. Description With this value, only the strings specified the user program with the SR_Trace( ) function are entered. This setting means that trace entries are made only after negative events or events. With this value, all SEND/RECEIVE functions with their transfer parameters and return values are logged. With this value, a trace dump of the transferred request blocks is also entered. Default TRACE_DEPTH_OFF 31

32 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Parameter SR_Trace_Select Description With the parameter SR_Trace_Select, the events to be logged can be selected. By ORing the parameter values, you can combine various trace selections. Example: TRACE_SELECT_SEND TRACE_SELECT_RECV The following values can be set: Parameter Values TRACE_SELECT_INIT TRACE_SELECT_SEND TRACE_SELECT_RECV TRACE_SELECT_ALL Description The trace is activated when the SetSR( ) or SRMD_Set( ) function is called. The trace logs all SEND jobs sent to the local transport system (underlying interface). The trace logs all RECEIVE jobs received from the local transport system (underlying interface). The trace is activated for all the parameter values described above. Default TRACE_SELECT_ALL 32

33 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 1.5 SEND/RECEIVE Programming Interface under MS-DOS Software Components The SEND/RECEIVE programming interface package includes a SEND/RECEIVE function and sample programs and functions. Integration of the Software Components Sample programs and sample functions perform the basic communications tasks. They are part of the product and can be integrated into the user software if the task to be performed is appropriate. SEND/RECEIVE Function Under MS-DOS there is a SEND/RECEIVE function: Call_Ina( ) This is part of the SEND/RECEIVE function library. Following Sections The remainder of this section shows first a graphical overview of the software components followed by a description of the operation of the components. 33

34 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Illustration of the SEND/RECEIVE Programming Interface The diagram below shows the principle of operation of the SEND/RECEIVE programming interface UNSIG16. Sample programs FETCH4 H1RECV Further sample programs Sample functions INA_CONNECT INA_LISTEN INA_CLOSE Request blocks Sample functions INA_OPEN INA_RECEIV INA_SEND Request blocks SEND/RECEIVE function Call_Ina( ) Interrupt ISO protocol 8073 Transport protocol 34

35 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Dynamic Sequence The following table describes the individual phases of a function sequence used to call communications job. Stage Procedure 1 A sample program calls a sample function. 2 This sample function fills the request block with job data. 3 Afterwards, the sample function calls the SEND/RECEIVE Call_Ina( ) function. In so doing, the request block is transferred to Call_Ina( ). 4 The SEND/RECEIVE Call_Ina( ) function passes the request block to the communications software by interrupt. 5 The transport protocol handles the job. 6 When the job has been processed and the interrupt terminated, the calling sample program is continued. 7 Depending on the job type, the results are now in a request block or the job is still being processed (in the event of asynchronous processing). 8 With asynchronous jobs, the sample program can establish when the asynchronous job is completed and data in the request block become effective by scanning a component in the request block (rb_response). 35

36 SEND/RECEIVE Programming Interface C79000-G8976-C097/ SEND/RECEIVE Call_Ina( ) Function Description All functions must call the SEND/RECEIVE Call_Ina( ) function after they have filled in the request block. The Call_Ina function passes the communications job on. A pointer is also transferred to the request block header and process interrupt 5B is initiated. How Signaling Works Before the Call_Ina( ) function is called, the request block must be filled with job-specific data. Then a pointer to the request block is transferred to the SEND/RECEIVE Call_Ina( ) function by the calling function. Chapters 5 and 6 contain detailed information on the SEND/RECEIVE request block. Syntax UNSIG16 Call_Ina(RB * rb) Meaning of the Parameter The parameter of the SEND/RECEIVE Call_Ina( ) function has the following meaning: Parameter Type Description rb RB * Pointer to the user-defined request block. Return Value If the SEND/RECEIVE Call_Ina( ) function call was successful, E_OK is returned, otherwise the return value is E_FATAL. 36

37 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 2 Communication with SIMATIC S5 Programmable Controllers With the help of flowcharts, this chapter describes the sequence required in the user program in a PC to transmit jobs to the communications software. In the configuration described, a PC is connected to an S5 programmable controller. Contents of Chapter General Notes on the Description in this Chapter General Sequence of Communication Phases of Data Communication Jobs of Data Communication Flowcharts in General Phase 1: Logon Phase 2: Connection Establishment - Description Connection Establishment - Implementation Problems during Connection Establishment, Example Problems during Connection Establishment, Example Phase 3: Data Exchange Data Exchange Variant 1, Normal Data Exchange Data Exchange Variant 2, Expedited Data Exchange Data Exchange - Variant 3, Normal Data Exchange with Segmented Transmission Data Exchange Variant 4, Data Exchange with the WRITE Job type Data Exchange Variant 5, Data Exchange with the READ Job type Problems During Data Exchange, Example Problems during Data Exchange, Example Phase 4: Connection Termination and Logoff Aborted Communication

38 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 2.1 General Notes on the Description in this Chapter Presentation of Information The description in this chapter is based on a simple network architecture for communication between a PC and a SIMATIC S5 programmable controller (S5 PLC). Network Architecture The following diagram describes the network architecture of a PC-S5 or S5-PC connection. It can be extended to include several connections to further communication partners. PC with SOFTNET IE or CP 1413 SIMATIC S5 PLC with communications processor LAN cable Explanation of Terms The table below explains the terms used in the diagram. Term Description PC The PC contains: the user program, the communications software a network interface card with an appropriate driver LAN cable S5 PLC The LAN cable is the physical connection between the different communication partners. For this network architecture, an Industrial Ethernet network with bus components is assumed. The S5 PLC needs a communications processor (CP) for communication. The CP handles the communication tasks to relieve the programmable controller. This chapter primarily describes the following CP parameters for configuring a communication connection: Job type: SEND or RECEIVE Priority: 2 38

39 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 2.2 General Sequence of Communication Introduction This chapter provides a general description of communication between a PC and an S5 PLC, and vice versa. The terms used in this description are explained below. Phases The sequence of communication is divided up into chronological phases. Every phase is a self-contained unit and handles jobs. Jobs Jobs are functions in the software package. Flowcharts Flowcharts describe the chronological sequence within a phase or phase variant. They show jobs and the resulting presentation of the messages transmitted via the LAN cable. Structure of a Phase The following diagram shows the way a phase is structured and described in this chapter. Several jobs can be assigned to one phase. Job Phase Example: connection establ. Job Job Phase Example: Normal data exchange Normal data exchange with segmented transmission Job Phase Example: Connection termination 39

40 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Phases of Data Communication Description The phases of data communication represent a chronological structure. Each data communication is divided into four self-contained phases that occur only once during communication. Phases of Data Communication The table below shows the general sequence of communication for one connection. Phase Name of the Phase 1 Logon 2 Connection establishment 3 Data exchange 4 Connection termination and logoff Note The data exchange phase can take any length of time. Any amount of data can be transmitted. It ends with the start of the connection termination and logoff phase. Several Connections The phase sequence illustrated above applies to one connection. If several connections are established, the sequence shown is run through for every single connection. 40

41 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Jobs of Data Communication Description Jobs are functions implemented in the communications software. The user program uses them to handle the individual phases of communication. A total of ten jobs are available. Job Types The following list shows which jobs are transmitted in the individual phases. Logon OPEN_REQ Connection establishment AWAIT_CONN_REQ_TRAN SEND_CONN_REQ Data exchange SEND_DATA SEND_EOM_DATA SEND_EXP_DATA* RECEIVE_DATA RECEIVE_EXP_DATA* Connection termination and logoff AWAIT_CLOSE CLOSE_REQ * ISO transport only, not TCP/IP 41

42 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Flowcharts in General Description Flowcharts describe the chronological sequence of a phase. They show the job types and the representation of the messages transmitted. The S5 PLC handles communication in the CPU by data handling blocks (HDB types), and by an appropriate parameter assignment in the related CP. Flowchart Structure The left side of the chart shows the initiating communication partner, the right side shows the receiving communication partner. Both communication partners are physically connected via a "LAN cable". The chart shows the presentation of the messages under this heading. The time axis runs from top to bottom. The chronological sequence shows the order in which jobs must be transmitted and which messages are transmitted via the LAN cable. Example:Sample Flowchart; PC-S5 Connection The following diagram shows a general example of the schematic layout of a flowchart for a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. Job Parameters of transp. conn. Job type: HDB types TPDU Read/write: Act/pass: Job return Priority: 42

43 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Explanation of the Terms Used in the Chart The table below explains the terms used in the diagram above. Term Description PC UP User program - The user program provides a request block with data and then initiates a job (Call_Ina( )) to the transport system (TS). Job Job return TS A job is a function that the user program must process in conjunction with the transport system at the time indicated. Every job is provided with a parameter set called the request block (job list). Every job is acknowledged after execution. Success or failure of the job is signaled in the rb_response parameter of the request block. Transport System - Each communication partner has a transport system (layer 4 of the ISO 7-layer model) as communication program. LAN cable TPDU Transport Protocol Data Unit - Representation of a message by the transport system (layer 4) of the sender to the transport system (layer 4) of the receiver. S5 PLC TS Transport System - Each communication partner has a transport system (layer 4 of the ISO 7-layer model) as communication program. CP conf. S5-CPU progr. A communications processor must be configured before communication. The "Transport connection parameters" dialog contains the parameters relevant for communication between a PC and an S5 PLC. Data handling blocks (HDB type), which establish the connection between the S5-CPU and the CP, have to be run in an S5 PLC. The HDB types necessary are listed in the charts. 43

44 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 2.3 Phase 1: Logon Introduction The effect of logon is that the resources necessary for communication, for example buffers, are provided. Description Logon is performed from the PC side by the "OPEN_REQ" job. Once completed, the connection can be established. At the S5 end, logon is follows the PC and CPU startup on condition that the CP has already been configured. No messages are transmitted on the LAN cable during logon. Flowchart The following diagram shows a general example of the schematic layout of a flowchart for a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. Parameters of transp. conn. HDB types OPEN_REQ Job type: OPEN_REQ return Read/write: Act/pass: Priority: Example of a Call Failure during Logon Logon with regard to a connection may be rejected for several reasons, e.g.: resources exhausted or request block entries incorrect Representation of a Failed Call A failed call during logon is represented by the rb_response ok_response parameter in the request block returned. 44

45 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 2.4 Phase 2: Connection Establishment - Description Introduction After logging on, the connection must also be established before data exchange is possible. Description When configuring a communication connection from a PC to an S5 PLC or vice versa, it must be defined which of the communication stations is to establish the connection. The user program is then written in accordance with this definition and the S5 PLC configured accordingly. Among other things, one result of establishing a connection is that memory areas in the transport system are made ready for the expected data exchange. Restriction The establishment of a connection between a PC and the CP of an S5 PLC or vice versa is mainly determined by the way in which the CP is configured in the S5 PLC. Reason: The communication of the CP in the S5 PLC can only be influenced by the variants in the corresponding configuration program. In contrast, the type and sequence of jobs can be freely selected in the PC user program. Who Establishes the Connection? The first current job type in the CP of the S5 PLC specified during configuration of the connection decides who establishes the connection. If the first CP job type is a job of the SEND type, the CP will be the initiator of the connection establishment (active connection establishment). If the first CP job type is a job of the RECEIVE type, the PC will initiate the connection establishment (passive connection establishment). For details see the manual for the CP used in the S5 PLC. 45

46 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Example of Duplex Connection Establishment The following diagram shows the establishment of a duplex communication connection between a PC and an S5 PLC. If a duplex connection is to be established, two jobs per TSAP must be configured for the CP of the S5 PLC. The PC establishes the connection. For this purpose, it transmits a SEND_CONN_REQ job. This corresponds to the RECEIVE job type as the first job for the communication connection in the configuration of the CP. A SEND job must be configured as the second job. This allows the S5 PLC to send and receive on one TSAP. PC UP Communication connection Jobs 1 S5 PLC CP configuration SEND_CONN_REQ 2 Parameters of transp. conn. Job type: SEND Read/write: N Act/pass: P Priority: 2 Parameters of transp. conn. Job type: RECEIVE Read/write: N Act/pass: P Priority: 2 46

47 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Connection Establishment - Implementation Description Following the general description of connection establishment in the last section, this section describes the establishment of a simplex connection. Flowchart; PC as Initiator The diagram below shows the sequence of connection establishment for a PC-S5 connection; the initiator of the connection establishment is the PC. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_CONN_REQ SEND_CONN_REQ return CR-TPDU CC-TPDU AK-TPDU Parameters of transp. conn. Job type: RECEIVE Read/write: N Act/pass: P Priority: 2 HDB types RECEIVE DIR and at least one RECEIVE- ALL Flowchart; S5 as Initiator The diagram below shows the sequence of connection establishment for an S5-PC connection; the initiator of connection establishment is the S5 PLC. S5 PLC LAN cable PC S5-CPU progr. CP conf. TS TS UP HDB types SEND DIR and at least one SEND-ALL Parameters of transp. conn. Job type: SEND Read/write: N Act/pass: P Priority: 2 CR-TPDU CC-TPDU AK-TPDU AWAIT_CONN_REQ_TRAN AWAIT_CONN_REQ_TRAN return 47