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

48 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n CR CC AK Connection Request Meaning Connect Confirm - positive acknowledgment after establish connection request Acknowledge incoming data 48

49 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Problems during Connection Establishment, Example 1 Description The communication partner does not exist or does not respond. (The situation in which an S5 PLC does not send an AWAIT_CONN_REQ_TRAN cannot occur, since this is done when the S5 PLC is turned on.) Flowchart; PC as Initiator The diagram below shows the sequence of an attempted but failed connection establishment; initiator is the PC. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_CONN_REQ CR-TPDU timed repetition CR-TPDU SEND_CONN_REQ return rb_response = loc_timeout Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning CR Connection Request 49

50 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Problems during Connection Establishment, Example 2 Description Although the Ethernet/IP address has been entered correctly in the request block by the user program and was specified correctly during CP configuration, TSAP addresses are wrong. The transport system of the S5 PLC therefore rejects connection establishment. Flowchart; PC as Initiator The diagram below shows the sequence of an attempted but failed connection establishment; initiator is the PC. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_CONN_REQ SEND_CONN_REQ return rb_response = conn_reject CR-TPDU DR-TPDU Parameters of transp. conn. Job type: RECEIVE Read/write: N Act/pass: P Priority: 2 HDB types 50

51 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Flowchart; S5 PLC as Initiator The diagram below shows an attempted but failed connection establishment; initiator is the S5 PLC. S5 PLC LAN cable PC S5-CPU progr. CP conf. TS TS UP HDB types Parameters of transp. conn. Job type: SEND Read/write: N Act/pass: P Priority: 2 CR-TPDU DR-TPDU AWAIT_CON_REQ_TRAN Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n Meaning CR DR Connection Request Disconnect Request - request to terminate connection and log off or negative acknowledgment of a connect request 51

52 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 2.5 Phase 3: Data Exchange Introduction After a connection has been established between a PC and an S5 PLC, data exchange can start. Description Apart from the three universal variants of data exchange, two other variants are described. They support data exchange specifically with an S5 PLC. Variants for Data Exchange The following five variants are available for data exchange: Variant 1: Normal Data Exchange Variant 2: Expedited Data Exchange* Variant 3: Normal data exchange with segmented transmission (data distributed over several send jobs). Variant 4: Data Exchange with the WRITE Job type Variant 5: Data Exchange with the READ Job type * ISO transport only, not TCP/IP 52

53 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Data Exchange Variant 1, Normal Data Exchange Description Normal Data Exchange is the standard job for transferring data. Flowchart: PC-S5 Connection The diagram below shows the sequence of a variant 1 data exchange (normal data exchange) on a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_EOM_DATA SEND_EOM_DATA return DT-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 53

54 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Flowchart; S5-PC Connection The diagram below shows the sequence of a variant 1 data exchange (normal data exchange) on an S5-PC connection. S5 PLC LAN cable PC S5-CPU progr. CP conf. TS TS UP HDB types Parameters of transp. conn. RECEIVE_DATA SEND-DIR and at least one SEND-ALL Job type: SEND Read/write: N Act/pass: P Priority: 2 DT-TPDU AK-TPDU RECEIVE_DATA return Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n Meaning DT AK Data exchange Acknowledge incoming data 54

55 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Data Exchange Variant 2, Expedited Data Exchange Description Expedited Data Exchange is used to transfer small amounts of data quickly. This job is only supported by ISO Transport and not by TCP/IP. Sample Flowchart; PC-S5 Connection The diagram below shows the sequence of a variant 2 data exchange (expedited data exchange) on a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_EXP_DATA SEND_EXP_DATA return ED-TPDU EA-TPDU Parameters of transp. conn. Job type: RECEIVE Read/write: N Act/pass: P Priority: 0 or 1 HDB types RECEIVE-DIR 55

56 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Flowchart; S5-PC Connection The diagram below shows the sequence of a variant 2 data exchange (expedited data exchange) on an S5-PC connection. S5 PLC LAN cable PC S5-CPU progr. CP conf. TS TS UP HDB types Parameters of transp. conn. RECEIVE_EXP_DATA SEND-DIR Job type: SEND Read/write: N Act/pass: P Priority: 0 or 1 ED-TPDU EA-TPDU RECEIVE_EXP_DATA return Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n Meaning ED EA Expedited Date Exchange Expedited Data Acknowledge for incoming data 56

57 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Data Exchange - Variant 3, Normal Data Exchange with Segmented Transmission Description The difference between "normal data exchange with segmented transmission" (variant 3) and "normal data exchange" (variant 1) is that the SEND_EOM_DATA job can be preceded by several SEND_DATA jobs; this variant is therefore known as segmented transmission. Data exchange with variant 3 (normal data exchange with segmented transmission), is used if the amount of data to be exchanged cannot be transmitted by the SEND_EOM_DATA job. Complete Flowchart: PC-S5 Connection The diagram below shows the sequence of a variant 3 data exchange (normal data exchange with segmented transmission) on a PC-S5 connection. Apart from the representation of the necessary jobs, the chart contains a "segmented transmission" sub-sequence which can be repeated any number of times. The "segmented transmission" sub-sequence is described in detail on the following page. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. "Segmented transmission" sub-sequence "Segmented transmission" sub-sequence SEND_EOM_DATA SEND_EOM_DATA return DT-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 57

58 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 "Segmented Transmission" Sub-sequence; PC-S5 Connection The diagram below shows the sub-sequence of a variant 3 data exchange (normal data exchange with segmented transmission) on a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_DATA SEND_DATA return DT-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 Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n Meaning DT AK Data exchange Acknowledge incoming data 58

59 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Complete Flowchart: S5-PC Connection The diagram below shows the variant 3 data exchange (normal data exchange with segmented transmission) on an S5-PC connection. Apart from the presentation of the necessary jobs, the flowchart contains a "segmented transmission" sub-sequence which may be repeated any number of times. The "segmented transmission" sub-sequence is described in detail on the following page. 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 RECEIVE_DATA "Segmented transmission" sub-sequence RECEIVE_DATA return RECEIVE_DATA "Segmented transmission" sub-sequence DT-TPDU AK-TPDU RECEIVE_DATA return rb_response = ok_eom_resp Note After a sub-sequence of "segmented transmission", a "RECEIVE_DATA Return is always possible if the receiving transport system (TS) does not have enough buffer space. In this case, a further RECEIVE_DATA job must be transmitted. 59

60 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 "Segmented Transmission" Sub-sequence; S5-PC Connection The diagram below shows the sub-sequence in a variant 3 data exchange (normal data exchange with segmented transmission) on an S5-PC connection. 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 DT-TPDU AK-TPDU Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviation Meaning DT AK Data exchange Acknowledge incoming data 60

61 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Data Exchange Variant 4, Data Exchange with the WRITE Job type Description The data exchange variant 4 (data exchange with the WRITE job type) differs from data exchange variant 1 (normal data exchange) in that destination parameters in the data buffer "user data 2" are also transferred with SEND_EOM_DATA, so that the receiving S5-PLC communications processor writes directly to the CPU of the S5-PLC. Objects such as inputs and outputs, data blocks, flags and counters can therefore be written to directly. Flowchart: PC-S5 Connection The following diagram illustrates the sequence of the data exchange variant 4 (data exchange with the WRITE job type) on a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_EOM_DATA with destination parameters SEND_EOM_DATA return RECEIVE_DATA RECEIVE_DATA return DT-TPDU AK-TPDU DT-TPDU AK-TPDU Parameters of transp. conn. Job type: RECEIVE Read/write: J Act/pass: P Priority: 2 HDB types RECEIVE-ALL Flowchart: S5-PC Connection Objects such as inputs and outputs, data blocks, flags and counters exist only in the S5 PLC, not in the PC. An S5-PC data exchange with the WRITE job type is therefore of no practical use. 61

62 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviatio n Meaning DT AK Data exchange Acknowledge incoming data 62

63 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Structure of the Destination Parameters for Sending The following diagram shows the structure of the data buffer "user data 2 used for data exchange with the WRITE job type (SEND_EOM_DATA with destination parameters) in memory when sending. The structure of the destination parameters for the WRITE job type can be found in the shipped sample file "S5.H. Value to be Entered Description Byte S System ID 1 (BYTE) 5 System ID 2 (BYTE) 16 Length of the header (BYTE) 1 ID of the opcode (BYTE) 3 Length of the opcode (BYTE) 3 Opcodes (BYTE) 3 ORG field (BYTE) 8 Length of the ORG field (BYTE) ORG ID (BYTE) Explanation, see below DB number (BYTE) Explanation, see below Start address (WORD) High byte, low byte Length (WORD) High byte, low byte FFH Empty field (BYTE) 14 2 Length of the empty field (BYTE) 15 63

64 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Explanation ORG ID The values to be entered for the ORG ID can be seen in the following table. Value to be Entered ORG ID Meaning 1 DB Data block 2 FY Flag byte 3 IB Input byte 4 QB Output byte 5 PB Peripheral byte 6 CB Counter cell 7 TB Timer cell 8 RS RS word (system area) 9 AS Absolute start address AH DX Extended data block (S5-135 U) 10H DE Data block in external memory (S5-150 U) 11H QB Source data from or destination data in peripheral modules in the extended peripheral I/O area (S5-150U) Explanation DB number The DB number is only entered when the DB will be written; otherwise 0. 64

65 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Structure of the Destination Parameters when Receiving The diagram below shows the structure of the data buffer "user data 2 used for data exchange with the WRITE job type (SEND_EOM_DATA- Return with destination parameters) in memory when receiving. The structure of the destination parameters for the WRITE job type can be found in the shipped sample file "S5.H. Value to be Entered Description Byte S System ID 1 (BYTE) 5 System ID 2 (BYTE) 16 Length of the header (BYTE) 1 ID of the opcode (BYTE) 3 Length of the opcode (BYTE) 4 Opcodes (BYTE) 0FH Acknowledgment field (BYTE) 3 Length of the acknowledgment field (BYTE) FFH Error number (BYTE) Empty field (BYTE) 7 Length of the empty field (BYTE) free (BYTE) free (DWORD)

66 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Data Exchange Variant 5, Data Exchange with the READ Job type Description Data exchange variant 5 (data exchange with the READ job type) differs from data exchange variant 1 (normal data exchange) in that source parameters in the data buffer "user data 2" are sent with the SEND_EOM_DATA send job so that the receiving S5-PLC communications processor reads directly from the CPU of the S5-PLC and returns the data. Objects such as inputs and outputs, data blocks, flags and counters can therefore be read out directly. Flowchart: PC-S5 Connection The following diagram shows the sequence of data exchange variant 5 (data exchange with the READ job type) on a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_EOM_DATA with source parameters SEND_EOM_DATA return RECEIVE_DATA RECEIVE_DATA return DT-TPDU AK-TPDU DT-TPDU AK-TPDU Parameters of transp. conn. Job type: FETCH Read/write: J Act/pass: P Priority: 2 HDB types SEND-ALL Flowchart: S5-PC Connection Objects such as data blocks, flags, counters and inputs/outputs exist only in the S5 PLC, not in the PC. An S5-PC connection would therefore be of no practical value. 66

67 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviatio n Meaning DT AK Data exchange Acknowledge incoming data 67

68 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Structure of the Source Parameters when Sending The following diagram shows the structure of the data buffer user data 2 used for data exchange with the READ job type (SEND_EOM_DATA with source parameters) in memory when sending. The structure of the destination parameters for the READ job type can also be found in the shipped sample file "S5.H. Value to be Entered Description Byte S System ID 1 (BYTE) 5 System ID 2 (BYTE) 16 Length of the header (BYTE) 1 ID of the opcode (BYTE) 3 Length of the opcode (BYTE) 5 Opcodes (BYTE) 3 ORG field (BYTE) 8 Length of the ORG field (BYTE) ORG ID (BYTE) Explanation, see below DB number (BYTE) Explanation, see below Start address (WORD) High byte, low byte Length (WORD) High byte, low byte FFH Empty field (BYTE) 14 2 Length of the empty field (BYTE) 15 68

69 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Explanation ORG ID The values to be entered for the ORG ID can be seen in the following table. Value to be Entered ORG ID Meaning 1 DB Data block 2 FY Flag byte 3 IB Input byte 4 QB Output byte 5 PB Peripheral byte 6 CB Counter cell 7 TB Timer cell 8 RS RS word (system area) 9 AS Absolute start address AH DX Extended data block (S5-135 U) 10H DE Data block in external memory (S5-150 U) 11H QB Source data from or destination data in peripheral modules in the extended peripheral I/O area (S5-150U) Explanation DB number The DB number is only entered when the DB will be written; otherwise 0. 69

70 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Structure of the Destination Parameters when Receiving The diagram below shows the structure of the data buffer "user data 2 used for data exchange with the READ job type (SEND_EOM_DATA- Return with destination parameters) in memory when receiving. The structure of the destination parameters for the READ job type can also be found in the shipped sample file "S5.H. Value to be Entered Description Byte S System ID 1 (BYTE) 5 System ID 2 (BYTE) 16 Length of the header (BYTE) 1 ID of the opcode (BYTE) 3 Length of the opcode (BYTE) 6 Opcodes (BYTE) FH Acknowledgment field (BYTE) 6 3 Length of the acknowledgment field (BYTE) Error number (BYTE) Explanation, see below 7 8 FFH Empty field (BYTE) 9 7 Length of the empty field (BYTE) free (BYTE) free (DWORD)

71 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Problems During Data Exchange, Example 1 Description The receiving communication station breaks down or does not respond during a data exchange. Where the Example Applies This example applies to variant 1 (normal data exchange) and variant 3 (normal data exchange with segmented transmission). Sample Flowchart; PC-S5 Connection The diagram below shows the sequence of an aborted variant 1 (normal data exchange) based on the example of a PC-S5 connection. If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_EOM_DATA SEND_EOM_DATA return rb_response = rem_abort DT-TPDU timed repetition DT-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 Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviatio n Meaning DT Data exchange 71

72 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Problems during Data Exchange, Example 2 Description The receiving communication station breaks down or does not respond during "expedited data exchange". Where the Example Applies This example only applies to variant 2 data exchange (expedited data exchange). Sample Flowchart; PC-S5 Connection The diagram below shows the sequence of an aborted variant 2 (expedited data exchange) based on the example of a PC-S5 connection If the SEND_EXP_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_EXP_DATA SEND_EXP_DATA return rb_response = rem_abort ED-TPDU timed repetition ED-TPDU Parameters of transp. conn. Job type: RECEIVE Read/write: N Act/pass: P Priority: 0 or 1 HDB types RECEIVE- DIR Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviatio n Meaning ED Expedited Data Exchange 72

73 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 2.6 Phase 4: Connection Termination and Logoff Introduction A communication connection is normally terminated by connection termination and logoff. Description The main characteristic of connection termination and logoff are that they can be initiated at any time by any communication partner. Note Layer 4 of the ISO 7-layer model does not provide a connection termination that saves data already sent but still on the way. As soon as a CLOSE_REQUEST job has been transmitted, the connection is terminated and all the data in the communication buffers is discarded. Request blocks still pending are returned to the user program with rb_response = rem_abort. Sample Flowchart; PC-S5 Connection The diagram below shows the sequence of connection termination and logoff on a PC-S5 connection. PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. CLOSE_REQ DR-TPDU DC-TPDU Parameters of transp. conn. Job type: any Read/write: Act/pass: HDB types CLOSE_REQ return Priority: 73

74 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Flowchart; S5-PC Connection The diagram below shows the sequence of connection termination and logoff on an S5-PC connection. S5 PLC LAN cable PC S5-CPU progr. CP conf. TS TS UP HDB types RESET Parameters of transp. conn. Job type: any Read/write: Act/pass: DR-TPDU DC-TPDU AWAIT_CLOSE Priority: AWAIT_CLOSE return Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n DR DC Meaning Disconnect Request - request to terminate connection and log off or negative acknowledgment of a connect request Disconnect Confirm - positive acknowledgment of a connection termination and logoff request 74

75 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 2.7 Aborted Communication Description Any communication can be interrupted by spontaneous connection termination and logoff. This type of termination is shown here based on the example of a variant 1 data exchange (normal data exchange) with a rem_abort. Where the Example Applies This example applies (with only minor adaptations) to all types of communication described in this chapter. Sample Flowchart; PC-S5 Connection The diagram below shows the sequence of an aborted data exchange as described above based on the example of a PC-S5 connection. If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. The CLOSE can be initiated, for example, by a Reset job to the relevant connection (job number). PC LAN cable S5 PLC UP TS TS CP conf. S5-CPU progr. SEND_EOM_DATA SEND_EOM_DATA return rb_response = rem_abort DT-TPDU DR-TPDU DC-TPDU CLOSE Parameters of transp. conn. Job type: any Read/write: Act/pass: Priority: HDB types RESET 75

76 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Flowchart; S5-PC Connection The diagram below shows the sequence of an aborted data exchange based on the example of an S5-PC connection. If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. 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 DT-TPDU DR-TPDU DC-TPDU RECEIVE_DATA CLOSE_REQ RECEIVE_DATA return rb_response = rem_abort CLOSE_REQ return rb_response = O. K. Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n Meaning DT DR DC Data exchange Disconnect Request - request to terminate connection and log off or negative acknowledgment of a connect request Disconnect Confirm - positive acknowledgment of a connection termination and logoff request 76

77 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 3 Communication with SIMATIC S7 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. The configuration described is a PC link to an S7 programmable controller. Contents of Chapter General Notes on the Description in this Chapter General Outline of Communication Procedures 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 Normal Data Exchange Aborted Data Exchange, Example Phase 4: Connection Termination and Logoff Aborted Communication in General

78 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 3.1 General Notes on the Description in this Chapter Presentation of Information This chapter assumes a simple network architecture to describe the communication between a PC and a SIMATIC S7 programmable controller (S7 PLC). Network Architecture The following diagram describes the network architecture of a PC-S7 or S7-PC connection. It can be extended to include several connections to further communication partners. PC with SOFTNET IE or CP 1413 SIMATIC S7 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 S7 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 S7 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 78

79 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 3.2 General Outline of Communication Procedures Introduction This chapter provides a general description of communication between a PC and an S7 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 79

80 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. 80

81 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 seven 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_EOM_DATA RECEIVE_DATA Connection termination and logoff AWAIT_CLOSE CLOSE_REQ 81

82 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 S7 PLC handles communication in the CPU by data handling blocks FC5 (SEND) and FC6 (RECEIVE), 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:PC-S7 Connection The following diagram shows a general example of the schematic layout of a flowchart for a PC-S7 connection. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. Job Parameters of transp. conn. Act/pass: P Function block FC6 (RECEIVE) TPDU Job return 82

83 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. S7 PLC TS Transport System - Each communication partner has a transport system (layer 4 of the ISO 7-layer model) as communication program. CP conf. S7-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 S7 PLC. Data function blocks (FCs), which establish the connection between the S7-CPU and the CP, have to be run in an S7 PLC. The required FCs are listed in the charts. 83

84 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 3.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. On the S7 side, logon is performed after 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-S7 connection. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. Parameters of Function block transp. conn. OPEN_REQ Act/pass: any OPEN_REQ return 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. 84

85 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 3.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 S7 PLC or vice versa, it must be defined which of the communication partners is to establish the connection. The user program is then written in accordance with this definition and the S7 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 A connection to be established between a PC and the CP of an S7 PLC or vice versa is mainly determined by the way in which the CP is configured in the S7 PLC. Reason: The communication of the CP in the S7 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 question of who establishes the connection is decided by the active/passive entry in the connection configuration. For more detailed information, refer to the manual "NCM S7 for Industrial Ethernet. 85

86 SEND/RECEIVE Programming Interface C79000-G8976-C097/ 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-S7 connection; the initiator of the connection establishment is the PC. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. SEND_CONN_REQ SEND_CONN_REQ return CR-TPDU CC-TPDU AK-TPDU Parameters of transp. conn. Act/pass: P Function block Flowchart; S7 as Initiator The diagram below shows the sequence of connection establishment for an S7-PC connection; the initiator of connection establishment is the S7 PLC. S7 PLC LAN cable PC S7-CPU progr. CP conf. TS TS UP Function block Parameters of transp. conn. Act/pass: O CR-TPDU CC-TPDU AWAIT_CONN_REQ_TRAN AK-TPDU AWAIT_CONN_REQ_TRAN return 86

87 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviatio n CR CC AK Connection Request Meaning Connect Confirm - positive acknowledgment after establish connection request Acknowledge incoming data 87

88 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Problems during Connection Establishment, Example 1 Description The communication partner does not exist or does not respond. (The situation in which an S7 PLC does not transmit an AWAIT_CONN_REQ_TRAN does not occur, since this is sent when the S7 PLC is turned on.) Flowchart; PC as Initiator The diagram below shows the sequence of an attempted but failed connection establishment; initiator is the PC. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. SEND_CONN_REQ CR-TPDU timed repetition CR-TPDU SEND_CONN_REQ return rb_response = loc_timeout Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning CR Connection Request 88

89 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Problems during Connection Establishment, Example 2 Description Although the Ethernet/IP address has been entered correctly in the request block by the user program and was specified correctly during CP configuration, TSAP addresses are wrong. The transport system of the S7 PLC therefore rejects connection establishment. Flowchart; PC as Initiator The diagram below shows the sequence of an attempted but failed connection establishment; initiator is the PC. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. SEND_CONN_REQ CR-TPDU DR-TPDU Parameters of transp. conn. Act/pass: P Function block SEND_CONN_REQ return rb_response = conn_reject 89

90 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Flowchart; S7 PLC as Initiator The diagram below shows an attempted but failed connection establishment; initiator is the S7 PLC. S7 PLC LAN cable PC S7-CPU progr. CP conf. TS TS UP Function block Parameters of transp. conn. Act/pass: O CR-TPDU AWAIT_CON_REQ_TRAN DR-TPDU Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviation Meaning CR DR Connection Request Disconnect Request - request to terminate connection and log off or negative acknowledgment of a connect request 90

91 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 3.5 Phase 3: Data Exchange Introduction After a connection has been established between a PC and an S7 PLC, data exchange can start. Description For communication with an S7 PLC, only "normal data exchange is supported. 91

92 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Normal Data Exchange Description Normal Data Exchange is the standard job for transferring data. Flowchart: PC-S7 Connection The diagram below shows the sequence of a "normal data exchange" on a PC-S7 connection. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. SEND_EOM_DATA DT-TPDU AK-TPDU Parameters of transp. conn. Act/pass: any Function block FC6 (RECEIVE) SEND_EOM_DATA return 92

93 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Flowchart; S7-PC Connection The diagram below shows the sequence of a variant 1 data exchange (normal data exchange) on an S7-PC connection. S7 PLC LAN cable PC S7-CPU progr. CP conf. TS TS UP Function block FC5 (SEND) Parameters of transp. conn. Act/pass: any DT-TPDU RECEIVE_DATA AK-TPDU RECEIVE_DATA return rb_response = ok_eom_resp Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviation Meaning DT AK Data exchange Acknowledge incoming data 93

94 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Aborted Data Exchange, Example Description The receiving communication station breaks down or does not respond during a data exchange. PC-S7 Connection The diagram below shows the sequence of an aborted data exchange using the example of a PC-S7 connection. If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. SEND_EOM_DATA SEND_EOM_DATA return rb_response = rem_abort DT-TPDU timed repetition DT-TPDU Parameters of transp. conn. Act/pass: any Function block FC6 (RECEIVE) Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning DT Data exchange 94

95 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 3.6 Phase 4: Connection Termination and Logoff Introduction A communication connection is normally terminated by connection termination and logoff. Description The main characteristic of connection termination and logoff are that they can be initiated at any time by any communication partner. Note Layer 4 of the ISO 7-layer model does not provide a connection termination that saves data already sent but still on the way. As soon as a CLOSE_REQUEST job has been transmitted, the connection is terminated and all the data in the communication buffers is discarded. Request blocks still pending are returned to the user program with rb_response = rem_abort. PC-S7 Connection The diagram below shows the sequence of connection termination and logoff on a PC-S7 connection. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. CLOSE_REQ DR-TPDU DC-TPDU Parameters of transp. conn. Act/pass: any Function block CLOSE_REQ return 95

96 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Flowchart; S7-PC Connection The diagram below shows the sequence of connection termination and logoff on an S7-PC connection. S7 PLC LAN cable PC S7-CPU progr. CP conf. TS TS UP A connection termination controlled by the S7 program is not possible! Parameters of transp. conn. Act/pass: any DR-TPDU DC-TPDU AWAIT_CLOSE AWAIT_CLOSE return Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviation DR DC Meaning Disconnect Request - request to terminate connection and log off or negative acknowledgment of a connect request Disconnect Confirm - positive acknowledgment of a connection termination and logoff request 96

97 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 3.7 Aborted Communication in General Description Any communication can be interrupted by spontaneous connection termination and logoff. This type of termination is shown here using the example "Normal data exchange" with a rem_abort. Where the Example Applies This example applies (with only minor adaptations) to all types of communication described in this chapter. PC-S7 Connection The diagram below shows the sequence of an aborted data exchange as described above based on the example of a PC-S7 connection. If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. The CLOSE can be initiated, for example, when the S7-CP is switched from Run to Stop and back to Run again. PC LAN cable S7 PLC UP TS TS CP conf. S7-CPU progr. SEND_EOM_DATA SEND_EOM_DATA return rb_response = rem_abort DT-TPDU DR-TPDU DC-TPDU CLOSE Parameters of transp. conn. Act/pass: any A connection termination controlled by the S7 program is not possible! 97

98 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Flowchart; S7-PC Connection The diagram below shows the sequence of an aborted data exchange based on the example of an S7-PC connection. If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. S7 PLC LAN cable PC S7-CPU progr. CP conf. TS TS UP Function block FC5 (SEND) Parameters of transp. conn. Act/pass: any DT-TPDU RECEIVE_DATA CLOSE_REQ DR-TPDU RECEIVE_DATA return rb_response = rem_abort DC-TPDU CLOSE_REQ return rb_response = O. K. Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviation Meaning DT DR DC Data exchange Disconnect Request - request to terminate connection and log off or negative acknowledgment of a connect request Disconnect Confirm - positive acknowledgment of a connection termination and logoff request 98

99 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 4 Communication with PCs/Workstations 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. The configuration described is a PC link to a PC/workstation. Contents of Chapter General Notes on the Description in this Chapter General Outline of Communication Procedures Phases of Data Communication Jobs of Data Communication Flowcharts in General Phase 1: Logon Phase 2: Connection Termination 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 Problems during Data Exchange, Example Problems during Data Exchange, Example Phase 4: Connection Termination and Logoff Aborted Communication in General

100 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 4.1 General Notes on the Description in this Chapter Presentation of Information This chapter assumes a simple network architecture to describe the communication between a PC and a PC/workstation. Network Architecture The following diagram describes the network architecture of a PC-PC/workstation connection. It can be extended to include several connections to further communication partners. PC with SOFTNET IE or CP 1413 PC/workstation with SOFTNET IE or CP 1413 LAN cable Explanation of Terms The table below explains the terms used in the diagram. Term PC/works tation LAN cable The PC or workstation contains: Description the user program, the communications software a network interface card with an appropriate driver 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. 100

101 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 4.2 General Outline of Communication Procedures Introduction This chapter describes communications between a PC and a PC/workstation in general. 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 Structure of a Phase 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. 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 101

102 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Phases of Data Communication Description The phases of communication represent a chronological structure. Each communication is divided into four phases. Each phase is selfcontained appearing only once during the communication. Phases of Data Communication The table below shows the general sequence of communication. 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. 102

103 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 103

104 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. 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:Flowchart The following diagram shows a general example of the schematic structure of a flowchart for a PC-PC/workstation connection. PC LAN cable PC UP TS TS UP Job Job TPDU Job return Job return 104

105 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Explanation of the Terms Used in the Chart The following table 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 to the transport system using an interrupt (Call_Ina( )). 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. The 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. 105

106 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 4.3 Phase 1: Logon Introduction The effect of the logon is to provide the resources necessary for communication, for example buffers. Description Logon is implemented by the "OPEN_REQ" job. Once completed, the connection can be established. No messages are transmitted on the LAN cable during logon. Flowchart The diagram below shows the general logon sequence. PC LAN cable PC UP TS TS UP OPEN_REQ OPEN_REQ return OPEN_REQ OPEN_REQ return Example of a Call Failure during Logon The logon for a connection can be rejected for several reasons, for example: 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. 106

107 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 4.4 Phase 2: Connection Termination Introduction After logging on, the connection must also be established before data exchange is possible. Description During configuration of a connection from a PC to another PC/workstation, the user must decide which communication partner will establish the connection. When the user program is written, this must be taken into account. 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. The connection is accepted by the transport system of the communication partner, not its user program. Flowchart The diagram below shows the connection establishment sequence. PC LAN cable PC UP TS TS UP AWAIT_CONN_REQ_TRAN SEND_CONN_REQ CR-TPDU CC-TPDU AK-TPDU SEND_CONN_REQ return AWAIT_CONN_REQ_TRAN return 107

108 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning CR CC AK Connection Request Connect Confirm - positive acknowledgment after establish connection request Acknowledge incoming data 108

109 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Problems during Connection Establishment, Example 1 Description The communication partner does not exist, does not respond or has not sent an AWAIT_CONN_REQ_TRAN. Flowchart The diagram below shows the sequence of a failed attempt to establish a connection. PC LAN cable PC UP TS TS UP SEND_CONN_REQ CR-TPDU timed repetition CR-TPDU SEND_CONN_REQ return rb_response = loc_timeout Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning CR Connection Request 109

110 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Problems during Connection Establishment, Example 2 Description Although the Ethernet/IP address has been entered correctly in the request block by the user program and was specified correctly during CP configuration, TSAP addresses are wrong. The transport system of the communication partner therefore rejects the request for connection establishment. Flowchart The diagram below shows the sequence of a failed attempt to establish a connection. PC LAN cable PC UP TS TS UP SEND_CONN_REQ CR-TPDU DR-TPDU SEND_CONN_REQ return rb_response = conn_reject Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning CR DR Connection Request Disconnect Request - request to terminate connection and log off or negative acknowledgment of a connect request 110

111 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 4.5 Phase 3: Data Exchange Introduction After a connection to a PC/workstation has been established, data exchange can start. Variants for Data Exchange The following three variants are available for data exchange: Variant 1: Normal Data Exchange Variant 2: Expedited Data Exchange* Variant 3: Normal data exchange with segmented transmission (data distributed over several send jobs). * ISO transport only, not TCP/IP 111

112 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Data Exchange Variant 1, Normal Data Exchange Description Normal Data Exchange is the standard job for transferring data. Flowchart The following diagram shows the sequence of a variant 1 data exchange (normal data exchange). PC LAN cable PC UP TS TS UP RECEIVE_DATA SEND_EOM_DATA DT-TPDU AK-TPDU SEND_EOM_DATA return RECEIVE_DATA return Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning DT AK Data exchange Acknowledge incoming data 112

113 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Data Exchange Variant 2, Expedited Data Exchange Description Expedited Data Exchange is used to transfer small amounts of data quickly. This job is only supported by ISO Transport and not by TCP/IP. Flowchart The following diagram shows the sequence of a variant 2 data exchange (expedited data exchange). PC LAN cable PC UP TS TS UP RECEIVE_EXP_DATA SEND_EXP_DATA ED-TPDU EA-TPDU SEND_EXP_DATA return RECEIVE_EXP_DATA return Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation ED EA Expedited Date Exchange Meaning Expedited Data Acknowledge for incoming data 113

114 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Data Exchange - Variant 3, Normal Data Exchange with Segmented Transmission Description The difference between "normal data exchange with segmented transmission" (variant 3) and "normal data exchange" (variant 1) is that the SEND_EOM_DATA job can be preceded by several SEND_DATA jobs; this variant is therefore known as segmented transmission. Data exchange with variant 3 (normal data exchange with segmented transmission), is used if the amount of data to be exchanged cannot be transmitted by the SEND_EOM_DATA job. Complete Flowchart: PC-S5 Connection The diagram below shows the sequence of a variant 3 data exchange (normal data exchange with segmented transmission). Apart from the representation of the necessary jobs, the chart contains a "segmented transmission" sub-sequence which can be repeated any number of times. The "segmented transmission" sub-sequence is described in detail on the following page. PC LAN cable PC UP TS TS UP RECEIVE_DATA "Segmented transmission" sub-sequence RECEIVE_DATA return RECEIVE_DATA "Segmented transmission" sub-sequence SEND_EOM_DATA DT-TPDU AK-TPDU SEND_EOM_DATA return RECEIVE_DATA return 114

115 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Note After a sub-sequence of "segmented transmission", a "RECEIVE_DATA Return is always possible if the receiving transport system (TS) does not have enough buffer space. In this case, a further RECEIVE_DATA job must be transmitted. "Segmented Data Transmission" Sub-sequence The following diagram shows the sub-sequence of a variant 3 data exchange (normal data exchange with segmented transmission). PC LAN cable PC UP TS TS UP SEND_DATA DT-TPDU AK-TPDU SEND_DATA return Abbreviations The following table explains the TPDU abbreviations used in the diagrams above. Abbreviation Meaning DT AK Data exchange Acknowledge incoming data 115

116 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Problems during Data Exchange, Example 1 Description The receiving communication station breaks down or does not respond during a data exchange. Where the Example Applies This example applies to variant 1 (normal data exchange) and variant 3 (normal data exchange with segmented transmission). Flowchart The diagram below shows an aborted variant 1 (normal data exchange). If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. PC LAN cable PC UP TS TS UP SEND_EOM_DATA DT-TPDU timed repetition DT-TPDU SEND_EOM_DATA return rb_response = rem_abort Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning DT Data exchange 116

117 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Problems during Data Exchange, Example 2 Description The receiving communication station breaks down or does not respond during "expedited data exchange". Where the Example Applies This example only applies to variant 2 data exchange (expedited data exchange). Flowchart The diagram below shows an aborted variant 2 (expedited data exchange). If the SEND_EXP_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. PC LAN cable PC UP TS TS UP SEND_EXP_DATA ED-TPDU timed repetition ED-TPDU SEND_EXP_DATA return rb_response = rem_abort Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation ED Expedited Data Exchange Meaning 117

118 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 4.6 Phase 4: Connection Termination and Logoff Introduction A communication connection is normally terminated by connection termination and logoff. Description The main characteristic of connection termination and logoff are that they can be initiated at any time by any communication partner. Note At layer 4 of the ISO 7-layer model, data sent but still in transit cannot be saved when there is a connection termination and logoff. As soon as a CLOSE_REQUEST job has been transmitted, the connection is terminated and all the data in the communication buffers is discarded. Request blocks still pending are returned to the user program with rb_response = rem_abort. Flowchart The diagram below shows the sequence of connection termination and logoff. PC LAN cable PC UP TS TS UP AWAIT_CLOSE CLOSE_REQ DR-TPDU DC-TPDU CLOSE_REQ return AWAIT_CLOSE return 118

119 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation DR DC Meaning Disconnect Request - connection termination and logoff Disconnect Confirm - positive acknowledgment of a connection termination and logoff request 119

120 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 4.7 Aborted Communication in General Description Any communication can be interrupted by spontaneous connection termination and logoff. This type of termination is illustrated here based on the example of a variant 1 data exchange (normal data exchange). Where the Example Applies This example applies (with only minor adaptations) to all types of communication described in this chapter. Flowchart The diagram below shows the sequence of an aborted data exchange. If the SEND_EOM_DATA job is acknowledged by rb_response = rem_abort, the connection no longer exists. PC LAN cable PC UP TS TS UP RECEIVE_DATA SEND_EOM_DATA DT-TPDU DR-TPDU RECEIVE_DATA return rb_response = rem_abort DC-TPDU SEND_EOM_DATA return CLOSE_REQ return rb_response = rem_abort rb_response = O. K. 120

121 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Abbreviations The table below explains the TPDU abbreviations used in the diagram above. Abbreviation Meaning DT DR DC Data exchange Disconnect Request - connection termination and logoff Disconnect Confirm - positive acknowledgment of a connection termination and logoff request 121

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

123 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 5 SEND/RECEIVE Request Block The request block is a data area in which the parameters necessary for a job are stored. With request blocks, only the structure of the data area is fixed. This allows any programming language to access a request block and activate the SEND/RECEIVE functions. This chapter describes the structure of the request block with its static and dynamic parts. Contents of Chapter General Notes on the Request Block Description of the SEND/RECEIVE Request Block Request Block Header Meaning of the Memory Locations in the Request Block Header Variable Field open_reference Variable Field Meaning of the Memory Locations in Variable Field Variable Field Transport Address Buffer Meaning of the Memory Locations in the "Transport Address Buffer" Variable Field User Data Buffer Variable Field Meaning of the Memory Locations in Variable Field User Data Buffers 2 and

124 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 (Empty page) 124

125 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 5.1 General Notes on the Request Block Introduction A request block is used to exchange data between the user program and the communications software. Job-Related Data This section describes the request block in general. You will find jobrelated request block data in the next section with the corresponding job. Representation of the Request Block Data Request block data are represented in the "Intel format" (the least significant byte has the lowest address). All the structures of the request block are also described in the include file SR.H. Identifiers in the Request Block The following table shows the meaning of the data types listed. Data Types Meaning BYTE WORD DWORD POINTER 8-bit unsigned 16-bit unsigned 32-bit unsigned Pointer to a data field 125

126 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 5.2 Description of the SEND/RECEIVE Request Block Request Block Structure Request blocks are divided into two areas: Header Location of variable fields Header The header of the request block is a field with the same structure for all jobs. Location of Variable Fields The location of variable fields contains one of three possible variable fields. Variable Fields There are three types of variable fields: Open_reference field Variable field 1 Variable field 2. Variable fields contain job-specific data. From variable fields 1 and 2, POINTERs point to data fields. Data Fields A total of 4 data fields are linked to variable fields 1 and 2 by POIN- TERs. These are the data fields: Transport address buffer, User data 1, User data 2 User data 3 126

127 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Representation of the Request Block The following diagram shows the request block structure. Request block Variable fields Data buffer Header Location for variable fields open_referece Variable field 1 Transport adr. buffer User data 1 Variable field 2 User data 2 User data 3 127

128 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 5.3 Request Block Header Description The request block header is the beginning of the request block and has the same structure for all jobs. It contains parameters that are necessary for all jobs. Function The header block contains information about the type of job and the way it will be handled. The job type is specified by rb_opcode. The header also contains information about the length of the entire request block. Structure The following diagram represents the request block structure in memory. Parameter Name rb_res (DWORD) rb_length (BYTE) rb_user (WORD) rb_resp_port (BYTE) rb_callback (DWORD) rb_susys (BYTE) rb_opcode (BYTE) rb_response (WORD) Byte

129 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Meaning of the Memory Locations in the Request Block Header Introduction This section describes the memory locations of the request block header. All memory locations are input parameters except the rb_response memory location which is an input and output parameter. rb_res This memory area is provided for job handling by the software and must not be used by the user program. rb_length The length of the entire request block (in other words header field and variable field) is entered in this field. The entry must be made by the user program, which must know the length of the request block. In this chapter, the rb_length entry is specified separately for each job type. rb_user The entry in the rb_user field (User Id) can be used freely by the user program to identify request blocks. This entry is returned unchanged. rb_resp_port The user program must enter 0FFH in this field. rb_callback Windows 95 and Windows NT No callback routine is used under Windows 95 and Windows NT. The value 0 must always be entered in this parameter. Signaling under Windows 95 and Windows NT is described in Sections and MS-DOS In this field, you can enter the address of your own function (callback routine). Callback routines are called when the job is completed and are used only for signaling. They must not contain MS-DOS calls and must not trigger the communications software (Call_Ina( )). The sample programs include an example of a callback routine. If you do not want to use callback routines, enter 0 (zero) in this field. 129

130 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 rb_susys This parameter specifies that layer 4 in the ISO/OSI reference model handles the job. The following value is entered : 40H - Transport Layer 4 Service. The parameter must be entered in the user program. rb_opcode This byte describes the type of job. Every job has its own opcode. The next chapter describes the opcode for each type of job. The parameter must be entered in the user program. rb_response Input Before a job can be transmitted, the rb_response memory location must be reset (REQ_WAITING). Output These two bytes contain a result code describing success or failure of the job. This result code can also be used to identify and eliminate faults. 130

131 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 5.4 Variable Field open_reference Function This field is necessary for logging on a connection. Structure The following diagram shows the structure of the open_reference variable field in memory. Parameter Name open_reference (WORD) Byte 0 1 Meaning of the Memory Location open_reference Every time OPEN_REQ is called, the communications software assigns a reference in this memory location for the connection opened. Use of the Reference The communications software requires the reference for all jobs using variable field 1 or variable field 2. Using the reference, the jobs are assigned to the required connection. The entry is made by the user program in the variable field used. Refer to the table below for the parameter names: Variable Field Parameter Name 1 conn_reference 2 vc_reference 131

132 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 5.5 Variable Field 1 Function This field is necessary to establish a connection. Structure The diagram below shows the structure of variable field 1 in memory. Parameter Name conn_iso_reason_code (BYTE) conn_rfu (4 BYTE) conn_ack_delay_estimate (WORD) conn_ta (POINTER) conn_persistence_count (WORD) conn_abort_timeout (WORD) conn_reference (WORD) conn_class (BYTE) conn_negot_options (WORD) conn_buffer_ptr (POINTER) conn_buffer_length (WORD) Byte Parameter rb_length in the Request Block Header If the variable field 1 is used, the parameter rb_length in the request block header has the value 42 or 2AH. 132

133 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Meaning of the Memory Locations in Variable Field 1 Introduction This section describes the memory locations of variable field 1. conn_iso_reason_ code This return code can be used to evaluate errors. The list below contains all possible output codes with their respective meanings. Code Description 0 Standard return value when a function is executed successfully; 0 also means: Reason not specified see ISO transport protocol Occupied TSAP addressed. 2 Wrong or non-existent TSAP addressed. 3 Unknown address. 80H 81H 82H 83H 84H 85H 87H 88H 8AH C0H C1H C2H The system addressed has initiated a normal connection termination with logoff. The communication system addressed was busy when connection establishment was attempted. No agreement on the connection parameters (Negot_options) has been reached. Reference was assigned twice by transmitting system. Reference not available. Error in protocol. Too many references. Connection establishment rejected in this network connection. Wrong header or parameter length. Connection establishment was denied Connection not established despite several attempts Connection terminated locally conn_rfu This memory area is intended for job handling by the software, it is not used by the user program. 133

134 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 conn_ack_delay_ estimate Two bytes always returning a value of 0. conn_ta Pointer to the transport address buffer. conn_persistence_ count Number of attempts made to establish a connection, before connection establishment is aborted. Two values have a special meaning here: 0 = default setting (see below) FFFFH = infinite Default setting The default setting of the "conn_persistence_count parameter depends on: the transport system used the transport protocol Transport System Transport Protocol Default Setting SOFTNET Industrial Ethernet SOFTNET Industrial Ethernet ISO TCP/IP 32 connection attempts 5 connection attempts CP 1613 ISO 32 connection attempts CP 1613 TCP/IP 5 connection attempts 134

135 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface conn_abort_ timeout The period of time the system waits for the addressed system to respond. If this time is exceeded, a new attempt is started. This procedure is repeated until it is possible to establish a connection or until the number of permitted attempts has been exceeded. The wait time is the entered value in units of 51 ms; Two values have a special meaning here: 0 = standard setting, and FFFFH = infinite Default setting The default setting of the "conn_abort_timeout parameter depends on: the transport system used the transport protocol Transport System Transport Protocol Default Setting SOFTNET Industrial Ethernet SOFTNET Industrial Ethernet ISO TCP/IP 64 s 10 s CP 1613 ISO 64 s CP 1613 TCP/IP 10 s conn_reference The reference of the connection is entered here. The reference identifies the connection. It is returned by the communications software with the acknowledgment of the logon job OPEN_REQ in the variable field "open_reference. conn_class This memory location always has the value

136 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 conn_negot_ options These settings allow several service classifications to be made. The following table explains the settings that change the basic setting 0000H. 16-Bit Hexadecimal Format XXX?H XX?XH X?XXH?XXXH Possible Settings of the "?" Placeholder 0 = Normal format 7 bits 2 = Extended format 31 bits 0 or 4 = ISO 8073 class 4 with either setting 0 = No expedited service possible, with checksum 1 = Expedited service is possible, with checksum 2 = No expedited service possible, without checksum 3 = Expedited service is possible, without checksum 8 = Setting above is used conn_buffer_ptr The entry in the conn_buffer_ptr memory location is a pointer to the user data 1 variable field, which may be used for received data. If you do not want to receive data, this pointer must be set to zero. conn_buffer_length This entry refers to the length of the buffer to be transmitted. The length can be set to a value from 0 to 32 bytes. 136

137 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 5.6 Variable Field Transport Address Buffer Function Structure The "transport address buffer" variable field is mandatory for connection establishment. The following figure illustrates the structure of the transport address buffer variable field in memory. Parameter Name loc_nsap_id_len (BYTE) loc_tsap_id_len (BYTE) loc_tsap_id (8 BYTE) rem_net_addr_len (BYTE) afi (BYTE) subnet (WORD) host_id (6 BYTE) lsap_id (BYTE) rem_net_nsap (BYTE) rem_tsap_id_len (BYTE) rem_tsap_id (8 BYTE) Byte

138 SEND/RECEIVE Programming Interface C79000-G8976-C097/ Meaning of the Memory Locations in the "Transport Address Buffer" Variable Field Introduction This section describes the memory locations of the transport address buffer variable field. loc_nsap_id_len This memory location always has the value 0. loc_tsap_id_len Length of local TSAP-ID; maximum length 8 bytes. loc_tsap_id These memory locations contain the local TSAP-ID. rem_net_addr_len This memory location always has the value 0BH (11). afi This memory location always has the value 49H (73). subnet This memory location always has the value 0. host_id ISO Transport The information in these memory locations is the Ethernet address of the communication partner with a maximum length of 6 bytes; it must be entered in hexadecimal. TCP/IP The information in these memory locations is the IP address of the communication partner and has a length of 6 bytes, the last 2 bytes of which must contain zeros; it must be entered in hexadecimal. lsap_id This memory location always has the value FEH (254). rem_net_nsap This memory location always has the value 0. rem_tsap_id_len Length of the TSAP-ID of the communication partner; maximum length 8 bytes. rem_tsap_id These memory locations contain the TSAP-ID of the communication partner. 138

139 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 5.7 User Data Buffer 1 Function This data buffer can be used by the user program to transmit or receive data during connection establishment. The structure of these memory locations is not fixed. Size Maximum 64 bytes 139

140 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 5.8 Variable Field 2 Function This variable field is required for data exchange. Structure The following diagram shows the structure of variable field 2 in memory. Parameter Name vc_iso_reason_code (BYTE) vc_rfu (15 BYTE) Byte to vc_reference (WORD) vc_conn_class (BYTE) vc_buf_len (WORD) vc_num_blks (BYTE) vc_buf0_ptr (POINTER) vc_buf0_length (WORD) vc_buf1_ptr (POINTER) vc_buf1_length (WORD) Length of the Request Block If variable field 2 is used, the parameter rb_length in the request block header has the value 50 or 32H. 140

141 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Meaning of the Memory Locations in Variable Field 2 Introduction This section describes the memory locations of variable field 2. vc_iso_reason_ code This return code can be used to evaluate errors. The following table lists all output codes possible with their respective reason. Code Meaning 0 Standard return value upon successful completion of function; 0 also means: "Reason not specified see ISO transport protocol Occupied TSAP addressed. 2 Wrong or non-existent TSAP addressed. 3 Unknown address. 80H 81H 82H 83H 84H 85H 87H 88H 8AH The system addressed has initiated a normal connection termination with logoff. The communication system addressed was busy when connection establishment was attempted. No agreement on the connection parameters (Negot_options) has been reached. Reference was assigned twice by transmitting system. Reference not available. Error in protocol. Too many references. Connection establishment rejected in this network connection. Wrong header or parameter length. vc_rfu This memory location is reserved for internal use. vc_reference The reference of the connection is entered here. The reference identifies the connection. It is returned by the communications software with the acknowledgment of the logon job OPEN_REQ in the variable field "open_reference. 141

142 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 vc_conn_class always 0. vc_buf_len The vc_buf_len parameter is only relevant when data are received and contains the number of received bytes. vc_num_blks 0 = no data buffer is used 1 = only the "user data 2" data buffer (vc_buf0_ptr) is used 2 = the "user data 3" data buffer (vc_buf1_ptr) is used in addition vc_buf0_ptr Pointer to a contiguous memory area (user data 2). If you do not want to receive data, this pointer must be set to zero. The two memory areas to which the pointers vc_buf0_ptr and vc_buf1_ptr point must not exceed a maximum length of 4096 bytes together. vc_buf0_length This entry refers to the length of the buffer contents to be transmitted. The length can be chosen from a range of 0 to 4096 bytes. vc_buf1_ptr Pointer to a contiguous memory area (user data 3). If you do not want to receive data, this pointer must be set to zero. The two memory areas to which the pointers vc_buf0_ptr and vc_buf1_ptr point must not exceed a maximum length of 4096 bytes together. vc_buf1_length This entry refers to the length of the buffer contents to be transmitted. The length can be chosen from a range of 0 to 4096 bytes. 142

143 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 5.9 User Data Buffers 2 and 3 Function During data transmission, data for the communication partner are entered here in a structure preset by the communication partner. When received, the data of the communication partner are entered in the "user data 2" and "user data 3" variable fields. Length of the Variable Fields The sum of the lengths of variable fields "user data 2" and "user data 3" must not exceed 4096 bytes. 143

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

145 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6 Description of the SEND/RECEIVE Job Types The preceding chapters explained jobs within the general context of communications and describe data exchange in the request block. This chapter describes the entries in the request block structure for each individual job. Contents of Chapter 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

146 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 6.1 Overview Opcode Every job is defined by a unique opcode. Every Opcode is assigned a variable field type. Assignment List The following table shows all services with the phases assigned to them. Phase Job Type Opcode Logon OPEN_REQ 0 Connection establishment SEND_CONN_REQ 1 AWAIT_CONN_REQ_TR AN AWAIT_CONN_REQ_US ER ACCEPT_CONN_REQ Data exchange SEND_DATA 5 SEND_EOM_DATA 6 SEND_EXP_DATA* 9 RECEIVE_DATA 7 RECEIVE_EXP_DATA* 0AH Connection termination CLOSE_REQ AWAIT_CLOSE 0CH 0DH The Next Sections The following sections describe the contents of request block memory locations in relation to individual jobs. * ISO transport only, not TCP/IP 146

147 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.2 Logon OPEN_REQUEST Function OPEN_REQ The OPEN_REQ job is used to log on a connection between the communication card and user program. Several connections can be established at the same time so that communication with several partners is possible later.a reference uniquely identifying this connection is returned after logon. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 18 rb_opcode 0 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Meaning 1 ok_resp Successful logon. 4 no_resources Failed connection establishment. There are not enough resources to establish a further connection. The maximum number of permitted connections has been reached. Variable Field to be Used open_reference variable field Output Parameters in open_reference The table below contains the reference (identification) of the job in the open_reference variable field. Parameter Name Input (I)/ Output (O) Job-Dependent Values open_reference A Description see Chapter 5 147

148 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 6.3 Connection Establishment SEND_CONNECT_REQUEST (active) Function SEND_CONN_REQ After logon, a connection must be established to allow communication between two devices. There are two options: active and passive connection establishment. The SEND_CONNECT_REQUEST job initiates an active connection establishment. A CR-TPDU is transmitted to the waiting partner. The partner is then asked to confirm the connection. CR-TPDU is repeated a certain number of times. If the partner does not respond, the attempt to establish a connection is aborted. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 42 rb_opcode 1 148

149 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 1 ok_resp Successfully completed connection establishment. 6 unknown_ reference 7 ok_closed_ resp The reference transferred to the job for identification is wrong. Check whether the reference has been transferred correctly. The attempted connection establishment was terminated by the system while waiting for a response (CLOSE). 16 loc_timeout The job was aborted, since there was no response and the maximum number of attempts has already been reached. 20 dup_req An attempt was made to establish a second connection with the same reference. 22 conn_reject The connection establishment was rejected by the communication partner. 24 negot_failed Negotiation of the connection parameters with the partner failed. 26 illegal_ address Incorrect local or destination address. 149

150 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 1 Input/Output Parameters of Variable Field 1 The following table contains the input/output parameters of variable field 1 as well as possible standard values: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values conn_iso_reason_code (BYTE) conn_ack_delay_estimate (WORD) conn_ta (POINTER, DWORD) conn_persistence_count (WORD) conn_abort_timeout (WORD) conn_reference (WORD) conn_class (BYTE) conn_negot_options (WORD) conn_buffer_ptr (POINTER, DWORD) conn_buffer_length (WORD) O Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 150

151 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.4 Connection Establishment AWAIT_CONNECT_REQUEST (passive) Function AWAIT_CONN_REQ_TRAN After logon, a connection must be established to allow communication between two devices. There are two options: active and passive connection establishment. The AWAIT_CONNECT_REQUEST job initiates a passive connection establishment. The system waits for an attempt by another partner to establish the connection to the local system. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 42 rb_opcode 2 151

152 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 1 ok_resp Successfully completed connection establishment. 6 unknown_ reference The reference transferred to the job for identification is wrong. 7 ok_closed_ resp Check whether the reference has been transferred correctly. The wait for an attempt to establish a connection was aborted by the user program. 12 illegal_req Illegal service classification, the attempt to establish a connection was aborted. 14 rem_abort The remote system aborted the connection in the establishment phase. 16 loc_timeout The job was aborted, since there was no response and the maximum number of attempts has already been reached. 20 dup_req An attempt was made to establish a connection with a reference, although a connection with this reference already exists. 26 illegal_ address 28 network_ error Incorrect local or destination address. Error in network layer. NSAP address not accessible. 152

153 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Variable Field to be Used Variable field 1 Input/Output Parameters of Variable Field 1 The following table contains the input/output parameters of variable field 1 as well as possible standard values: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values conn_iso_reason_code (BYTE) conn_ack_delay_estimate (WORD) conn_ta (POINTER, DWORD) conn_abort_timeout (WORD) conn_reference (WORD) conn_class (BYTE) conn_negot_options (WORD) conn_buffer_ptr (POINTER, DWORD) conn_buffer_length (WORD) O Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 I Description see Chapter 5 O Description see Chapter 5 153

154 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Further Information about Passive Connection Establishment Connections can be established in three different modes: Fully specified connection establishment The local user program writes data into the loc_tsap_id, rem_tsap_id and host_id memory locations. This enables you to identify your communication partner accurately. Partly specified connection establishment The local user program writes data into the loc_tsap_id and rem_tsap_id memory locations. host_id memory locations contain zeros. You can therefore communicate with partners without knowing their Ethernet/IP address. Unspecified connection establishment The local user program writes zeros into the loc_tsap_id, rem_tsap_id and host_id memory locations. This allows you to communicate with partners, whose addresses are completely unknown to you. After receipt of the CR-TPDU, the received connection data are compared with the data in the loc_tsap_id, rem_tsap_id and host_id memory locations. The comparison first searches for a fully specified connection establishment, then for a partly specified connection establishment and, finally, for an unspecified connection establishment. If connection establishment is successful in the "partly specified" and "unspecified" modes, the memory locations of the transport address buffer are overwritten with the current values. 154

155 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.5 Connection Establishment AWAIT_CONNECT_REQUEST_USER (passive) Function AWAIT_CONN_REQ_USER After logon, a connection must be established to allow communication between two devices. There are two options: active and passive connection establishment. The AWAIT_CONNECT_REQUEST_USER job initiates a passive connection establishment. The local user program must now accept or reject the connection establishment attempt. The connection is accepted with the ACCEPT_CONN_REQ job. The connection is rejected with the CLOSE_REQ job. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 42 rb_opcode 3 155

156 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 5 ok_decide_ req_resp 6 unknown_ reference 7 ok_closed_ resp Due to the connection options specified, the connection can be established. The local transport layer waits for the rejection or acceptance by the user. The connection reference specified by the user is invalid. The local user closed the connection during the connection establishment phase. 12 illegal_request Invalid service on this connection or invalid parameters. 20 dup_req A job is already being processed for this connection or the connection is already established. 26 illegal_ address An invalid local or remote transport address was specified or the network_address_length exceeds the configured maximum address length or the local or remote TSAP_ID_length exceeds the configured maximum TSAP-ID length. 28 network_error An error occurred in the network layer. 156

157 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface Variable Field to be Used Variable field 1 Input/Output Parameters of Variable Field 1 The following table contains the input/output parameters of variable field 1 as well as possible standard values: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values conn_iso_reason_code (BYTE) conn_ack_delay_estimate (WORD) conn_ta (POINTER, DWORD) conn_abort_timeout (WORD) conn_reference (WORD) conn_class (BYTE) conn_negot_options (WORD) conn_buffer_ptr (POINTER, DWORD) conn_buffer_length (WORD) O Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 I Description see Chapter 5 O Description see Chapter 5 157

158 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Further Information about Passive Connection Establishment Connections can be established in three different modes: Fully specified connection establishment The local user program writes data into the loc_tsap_id, rem_tsap_id and host_id memory locations. This enables you to identify your communication partner accurately. Partly specified connection establishment The local user program writes data into the loc_tsap_id and rem_tsap_id memory locations. host_id memory locations contain zeros. You can therefore communicate with partners without knowing their Ethernet/IP address. Unspecified connection establishment The local user program writes zeros into the loc_tsap_id, rem_tsap_id and host_id memory locations. This allows you to communicate with partners, whose addresses are completely unknown to you. After receipt of the CR-TPDU, the received connection data are compared with the data in the loc_tsap_id, rem_tsap_id and host_id memory locations. The comparison first searches for a fully specified connection establishment, then for a partly specified connection establishment and, finally, for an unspecified connection establishment. If connection establishment is successful in the "partly specified" and "unspecified" modes, the memory locations of the transport address buffer are overwritten with the current values. 158

159 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.6 Connection Establishment ACCEPT_CONNECT_REQUEST (passive) Function ACCEPT_CONN_REQ This job is directly related to the AWAIT_CONN_REQ_USER job. With ACCEPT_CONN_REQ, the user accepts the connection establishment request of the partner. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 42 rb_opcode 4 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 1 ok_resp The connection was established. 6 unknown_ reference 7 ok_closed_ resp 10 buffer_too_ long The connection reference specified by the user is invalid. The local user closed the connection during the connection establishment phase. The user data length exceeds the maximum permitted size. 14 rem_abort The job was accepted by the local transport layer but the remote transport layer aborted connection establishment. 16 loc_timeout The job was aborted due to a timeout. 20 dup_req A job is already being processed for this connection or the connection is already established. 159

160 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 1 Input/Output Parameters of Variable Field 1 The following table contains the input/output parameters of variable field 1 as well as possible standard values: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values conn_iso_reason_code (BYTE) conn_ack_delay_estimate (WORD) conn_ta (POINTER, DWORD) conn_abort_timeout (WORD) conn_reference (WORD) conn_class (BYTE) conn_negot_options (WORD) conn_buffer_ptr (POINTER, DWORD) conn_buffer_length (WORD) O Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 I Description see Chapter 5 O Description see Chapter 5 160

161 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.7 Data Exchange SEND_DATA and SEND_EOM_DATA Function SEND_DATA and SEND_EOM_DATA As soon as a connection has been established, data can be transmitted.the SEND_DATA job initiates segmented data transmission. Segments are of limited length. However, several segments can be transmitted one after the other. The last segment must, however, be transmitted with the SEND_EOM_DATA job. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 50 rb_opcode for SEND_DATA for SEND_EOM_DATA 5 6 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 1 ok_resp Data exchange successfully completed. 4 no_resources Failed data exchange due to lack of resources. 6 unknown_ reference The reference transferred to the job for identification is wrong. Check whether the memory type of the reference is correct and whether the reference has been transferred correctly. 12 illegal_req The connection has been closed or is already terminated. 14 rem_abort The connection was aborted by the transport system during the transmission phase. 16 loc_timeout The job was aborted because no reply was received and the maximum number of attempts has been reached. 161

162 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 2 Input/Output Parameters of Variable Field 2 The table below contains the input/output parameters of variable field 2: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values vc_iso_reason_code (BYTE) vc_reference (WORD) vc_conn_class (BYTE) vc_buf_len (WORD) vc_num_blks (BYTE) vc_buf0_ptr (POINTER, WORD) vc_buf0_length (WORD) vc_buf1_ptr (POINTER, WORD) vc_buf1_length (WORD) O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 162

163 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.8 Data Exchange RECEIVE_DATA Function RECEIVE_DATA This job allows you to provide the user program with received data in the "user data 2" and "user data 3" variable fields. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 50 rb_opcode 7 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 1 ok_resp Data received successfully. 3 ok_eom_resp An EOM (End Of Message) was indicated by the transport system. The data in the buffer are the last for this TSDU (Transport Service Data Unit). 4 no_resources Failed data exchange due to lack of resources. 6 unknown_ reference 7 ok_closed_ resp The reference transferred to the job for identification is wrong. Check whether the memory type of the reference is correct and whether the reference has been transferred correctly. The attempted connection establishment was terminated by the system while waiting for a response (CLOSE). 14 rem_abort The remote system aborted the connection during data exchange. 16 loc_timeout The job was aborted because no reply was received and the maximum number of attempts has been reached. 163

164 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 2 Input/Output Parameters of Variable Field 2 The table below contains the input/output parameters of variable field 2: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values vc_iso_reason_code (BYTE) vc_reference (WORD) vc_conn_class (BYTE) vc_buf_len (WORD) vc_num_blks (BYTE) vc_buf0_ptr (POINTER, WORD) vc_buf0_length (WORD) vc_buf1_ptr (POINTER, WORD) vc_buf1_length (WORD) O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 164

165 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.9 Data Exchange SEND_EXPEDITED_DATA Function SEND_EXP_DATA This job is used to transmit data of a length between 1 and 16 bytes with highest priority. This means that this data transmission takes precedence over all other transmission data. This job is only supported by ISO Transport and not by TCP/IP. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 50 rb_opcode 9 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 1 ok_resp Transfer of expedited data successful. 4 no_resources Data exchange was not successful. No free memory found. 6 unknown_ reference 8 buffer_too_ short 10 buffer_too_ long The reference transferred to the job for identification is wrong. Check whether the reference has been transferred correctly. Buffer empty. Either vc_num_blks = 0 or vc_buf0_length and vc_buf1_length are both 0 The memory location transmitted is too long or vc_num_blks is greater than 1. The connection was aborted. 12 illegal_req Either no "EXPEDITED-DATA" job is possible or the connection addressed is just being terminated or has already been terminated. 14 rem_abort The connection was aborted by the remote system. 16 loc_timeout The job was aborted because no reply was received and the maximum number of attempts has been reached. 165

166 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 2 Input/Output Parameters of Variable Field 2 The table below contains the input/output parameters of variable field 2: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values vc_iso_reason_code (BYTE) vc_reference (WORD) vc_num_blks (BYTE) vc_buf0_ptr (POINTER, WORD) vc_buf0_length (WORD) O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 166

167 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.10 Data Exchange RECEIVE_EXPEDITED_DATA Function RECEIVE_EXP_DATA This job is used to receive data of a length between 1 and 16 bytes with highest priority. Highest priority means that this data transmission takes precedence over all other data received. This job is only supported by ISO Transport and not by TCP/IP. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 50 rb_opcode 10 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 3 ok_eom_resp An EOM (End Of Message) was indicated by the transport system. The data in the buffer are the last for this ED-TPDU (Transport Service Data Unit) 4 no_resources Couldn t find any free memory location. 6 unknown_ reference 8 buffer_too_ short The reference transferred to the job for identification is wrong. Check whether the memory type of the reference is correct and whether the reference has been transferred correctly. The length of the first memory buffer provided with the job is less than 16 bytes. 12 illegal_req Expedited services are not possible. 14 rem_abort The connection was aborted by the remote system. 16 loc_timeout The job was aborted because no reply was received and the maximum number of attempts has been reached. 167

168 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 2 Input/Output Parameters of Variable Field 2 The table below contains the input/output parameters of variable field 2: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values vc_iso_reason_code (BYTE) vc_reference (WORD) vc_conn_class (BYTE) vc_buf_len (WORD) vc_num_blks (BYTE) vc_buf0_ptr (POINTER, WORD) vc_buf0_length (WORD) O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 168

169 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.11 Connection Termination CLOSE_REQ Function CLOSE_REQ This job is used by the local system to close a connection actively. The connection to be closed is identified by its reference. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 50 rb_opcode 12 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 6 unknown_ reference 7 ok_closed_ resp 10 buffer_too_ long 11 ok_reject_ conn_resp The reference transferred to the job for identification is wrong. Check whether the memory type of the reference is correct and whether the reference has been transferred correctly. Connection termination confirmed. A data field longer than 64 bytes was transferred. Correct rejection of an attempt to establish a connection. 16 loc_timeout The job was aborted because no reply was received and the maximum number of attempts has been reached. 169

170 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 2 Input/Output Parameters of Variable Field 2 The table below contains the input/output parameters of variable field 2: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values vc_iso_reason_code (BYTE) vc_reference (WORD) vc_num_blks (BYTE) vc_buf0_ptr (POINTER, WORD) vc_buf0_length (WORD) vc_buf1_ptr (POINTER, WORD) vc_buf1_length (WORD) I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 I Description see Chapter 5 170

171 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 6.12 Connection Termination AWAIT_CLOSE Function AWAIT_CLOSE With this job, the local user program ensures that it is immediately informed of a connection termination. Header Settings The necessary settings for the parameters entered in the request block header (RB) are shown in the following table: RB Header Parameter Setting rb_length 50 rb_opcode 13 Header Return Value The following values can be returned in the rb_response field of the request block header: Return Value Constant Explanation 6 unknown_ reference 7 ok_closed_ resp The reference transferred to the job for identification is wrong. Check whether the memory type of the reference is correct and whether the reference has been transferred correctly. The connection is aborted by the local system. 14 rem_abort The connection was aborted by the remote system. 16 loc_timeout The job was aborted because no reply was received and the maximum number of attempts has been reached. 20 dup_req Another AWAIT_CLOSE job has already been initiated on the same connection. 171

172 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 Variable Field to be Used Variable field 2 Input/Output Parameters of Variable Field 2 The table below contains the input/output parameters of variable field 2: Input parameters must be entered by the user program. Output parameters are returned by the system after execution of the job. Parameter Name Input (I)/ Output Output (O) Job-Dependent Values vc_iso_reason_code (BYTE) vc_reference (WORD) vc_buf_len (WORD) vc_buf0_ptr (POINTER, WORD) vc_buf0_length (WORD) vc_buf1_ptr (POINTER, WORD) vc_buf1_length (WORD) I / O Description see Chapter 5 I Description see Chapter 5 O Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 I Description see Chapter 5 I / O Description see Chapter 5 172

173 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 7 How to Compile a Program This chapter describes the compilation and installation of a program based on an example. Available software tools and necessary settings are described. This chapter deals with the following topics: Compilation requirements SIMATIC S5 requirements SIMATIC S7 requirements Contents of Chapter Procedure when Compiling Requirements with a SIMATIC S5 PLC Requirements with a SIMATIC S7 PLC

174 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 7.1 Procedure when Compiling The Program The program can be written in a language of your choice. Remember the following points: the user program must include a request block structure; jobs must be structured in accordance with the description in this manual; communication functions must be processed according to the phase scheme described in the communication examples. Jobs are passed on the communications software by the SEND/RECEIVE function Call_Ina( ) or SRMD_Request( ); see Job Library, Sample Programs and in this Manual "Introduction to the SEND/RECEIVE Programming Interface. Selecting the Compiler Depending on the operating system, the following compilers were used for the sample programs contained in the software packages of the SEND/RECEIVE programming interface: Operating System Compiler MS-DOS MS Visual C++ Version 1.5 Windows 95 and Windows NT MS Visual C++ Version >

175 C79000-G8976-C097/6 SEND/RECEIVE Programming Interface 7.2 Requirements with a SIMATIC S5 PLC The Program The STEP 5 program requires HDB communication. The manual accompanying the SIMATIC describes these data handling blocks in detail. Hardware The SIMATIC S5 PLC requires a CP 1430 or CP 143 communications processor to attach to Industrial Ethernet. Parameter Assignment The SIMATIC S5 PLC must be assigned parameters for communication with a PC/PG using the COM 1430 or COM 143 configuration software as applicable. Parameter settings must not conflict. For details of assigning parameters to the communications processor, refer to its manual. 175

176 SEND/RECEIVE Programming Interface C79000-G8976-C097/6 7.3 Requirements with a SIMATIC S7 PLC The Program The STEP 7 program requires communication with functions (FCs). For a detailed description of these blocks, refer to the manual "NCM S7 for Industrial Ethernet. Hardware The SIMATIC S7 PLC requires a communications processor: CP (S7-400, ISO protocol) CP (S7-300, ISO protocol) CP TCP (S7-400, TCP/IP protocol) CP TCP (S7-300, TCP/IP protocol) Parameter Assignment The SIMATIC S7 PLC must be assigned parameters for communication with PC/PG by means of the appropriate NCM S7 for Industrial Ethernet configuration software. Parameter settings must not conflict. For details of assigning parameters to the communications processor, refer to its manual. 176

177 C79000-G8976-C097/6 Appendix A Appendix A - Values of rb_response with Windows 95, Windows NT and MS-DOS Input Value The table below shows the input values of rb_response. Input Value of rb_response Constant Description FFH REQ_WAITING The REQ_WAITING constant contains the reset value. Return Value The table below shows the return values of rb_response when a job was successful. Return Value of rb_response Constant Description 1 OK_RESP Logon successful 3 OK_EOM_RESP An EOM (End Of Message) was indicated by the transport system. The data in the buffer are the last for this TSDU (Transport Service Data Unit). 7 OK_CLOSED_RESP Connection termination confirmed 11 OK_REJECT_CONN_RESP Correct rejection of an attempt to establish a connection 177

178 Appendix A C79000-G8976-C097/6 Return Value The table below shows the return values of rb_response if an error occurred. Return Value of rb_response Constant Description 2 INVALID_REQ The job cannot be executed at the present time. 4 NO_RESOURCES Failed connection establishment. There are not enough resources to establish a further connection. The maximum number of permitted connections has been reached. 6 UNKNOWN_REFERENCE The reference transferred to the job for identification is wrong. Check whether the memory type of the reference is correct and whether the reference has been transferred correctly. 8 BUFFER_TOO_SHORT The length of the first memory buffer provided with the job is less than 16 bytes. 10 BUFFER_TOO_LONG A data block greater than 64 bytes has been transmitted. 12 ILLEGAL_REQ Illegal service classification, the attempt to establish a connection has been aborted. 14 REM_ABORT The remote system has aborted the connection. 16 LOC_TIMEOUT The job was aborted because no reply was received and the maximum number of attempts has been reached. 18 UNKNOWN_CONN_CLASS Conn_class does not equal DUP_REQ An attempt has been made to establish/termination a second connection with the same reference. 22 CONN_REJECT The connection establishment was rejected by the communication partner. 24 NEGOT_FAILED Negotiation of the connection parameters with the partner failed. 26 ILLEGAL_ADDRESS Local or destination address wrong. 28 NETWORK_ERROR Error in network layer. NSAP address not accessible. 178

179 C79000-G8976-C097/6 Appendix B Appendix B - Error Messages of the SEND/RECEIVE Functions Description With the SEND/RECEIVE functions, the return value has the value -1 if an error occurred. The cause of the error can be queried with the GetLastError( ) function. The following error messages are possible: Value Constant Description 0 SR_OK No error 202 SR_RESOURCE DPRAM memory request not functioning. 204 SR_SCP_NOCONFIG Access point of the application not found 205 SR_ILLEGAL Invalid job, perhaps protocol error 206 SR_PARAM Incorrect mode 207 SR_DEV An OPEN was already sent to this device. Exclusive access to a device necessary. 210 SR_MEM DPRAM occupied 215 SR_NOMES No message for the process has arrived. 216 SR_SCP_USERMEM Receive buffer too small 234 SR_EPROTECT Licensing error 245 SR_ILLEGAL_SUBSYSTEM Incorrect subsystem 246 SR_ILLEGAL_OPCODE Illegal opcode 247 SR_BUFFER_TOO_SHORT Buffer too short 248 SR_BUFFER_1_TOO_SHORT Buffer 1 too short 249 SR_ILLEGAL_PROTOCOL_ SEQUENCE Wrong job sequence 298 SR_E_RESOURCES No more resources too many connections established or too many "access points of the application open or too many jobs sent 302 SR_E_PAR_ERR Request block structure wrong 1001 SR_BUFFER_TOO_LONG Buffer too long 1002 SR_ERR_ATTACH Error starting the SEND/RECEIVE function library S7_SR.DLL (DLL_ATTACH) 1003 SR_ERR_PARAM Incorrect rb- parameter 1004 SR_ERR_SINEC Error sending a restart request to driver 1005 SR_INVALID_BUF Incorrect buffer entry 1006 SR_INVALID_OPCODE Invalid Opcode 179

180 Appendix B C79000-G8976-C097/6 Value Constant Description 1007 SR_NO_RESOURCE No more resources available 1008 SR_NO_SCP_HANDLE No handle to interface 1009 SR_NO_THREAD No receive thread 1010 SR_NO_WINDOW No window in receive thread 1011 SR_SCP_HANDLE Handle to interface exists already (must not occur more than once) 1012 SR_TIMEOUT An internal timeout occurred 1013 SR_ERR_ACCESSPOINT Invalid access point of the application 180

181 C79000-G8976-C097/6 Glossary Glossary CP Communications Processor - Communication module for installation in computers or programmable controllers. Driver Software used to exchange data between applications and the CP. Network Networks consist of one or more linked subnets with any number of nodes. Several networks can exist together. There is a common node table for each subnet. ODI Open Data Interface - interface by Novell. PCMCIA PC card standard for compact PC expansion boards. PROFIBUS Process Field Bus - network for the cell and field area in the mid performance range primarily intended for an industrial environment complying with EN , Volume 2, PROFIBUS. Protocol Formal set of conventions for data exchange. Such a protocol decides both the formats of messages and the data flow during data exchange. S5 PLC A programmable (logic) controller belonging to the Siemens SIMATIC S5 product family. Service Services provided by a communications protocol. SIMATIC NET Siemens Network and Communication - Product name for networks and network components from Siemens. SINEC -> SIMATIC NET SINEC L2 -> PROFIBUS System TSAP The entire electrical equipment. Includes the following: programmable controller, operator control and monitoring devices, bus systems, field devices, drives, supply lines. Transport Service Access Point - layer 4 access point (address) 181

182 Glossary C79000-G8976-C097/6 182