- Service, Support
Contents
1. int ret sighold SIGUSR1 result tf write 1 TF CONF ASYNC 0 0 0 TF FALSE opb ptr sigrelse SIGUSR1 sighold SIGUSR1 ret tf getfds amp fds amp nfds sigrelse SIGUSR1 if ret gt 0 ret poll fds nfds timeout if ret gt 0 sighold SIGUSRI ret tf receive 0 1 pb rcv rcv rslt sigrelse SIGUSR1 18 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 tf init and configuration file stf conf dat tf close path tf report tf ustatus req msg exch and msg write The ff init call receives most of the settings of the configuration file stf conf dat as return parameters the DIM structure The configuration file differs in the following aspects from the description in the TF manual Name in Difference compared Explanations stf conf dat with TF manual With other products this name specifies the transport channel of the CP card and indicates the file descriptor assigned to this channel in the parameter scp fd of the structure DIM PARAM SCP Device Is not supported model name Is not supported Planned for future versions Definition of Additional function This additional function means that the the structure of the names of application application associations in the application is association independent of system considerations and can be freely selected The function of the TF call close pat2. gt In SOFTNET TF UNIX the range is restricted since the underlying APM protocol stack uses part of it for its local management The application must make sure that the job identifier orderid does not exceed a value between 0 and 65535 gt With a local confirmation to the application the TF NET UNIX library confirms that an unconfirmed TF service was transferred to the communications module and that this will be handled by the module alone gt The SOFTNET TF UNIX library does not return a local confirmation to the application An unconfirmed service is accepted by the library and 23 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 passed on to the underlying APM protocol stack To make sure that the data are sent tf receive with wait timeout 0 polling should be called after each call for an unconfirmed service If this call is not made the flow control at the transport layer may hold up data The receive call detects the end of a possible bottleneck in transmission and transfers the data of the relevant service Querying the Time With the tim read TF service a client application can request the value of tim_read the time gt In SOFTNET TF UNIX it is not possible to request the local time The time can only be provided by a remote server from which it is read out 24 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 2 4 Parameter Assignment This section describes the values that can be
3. 00 Definition via endpoints The active application relation A_Active is configured Content of stf_conf dat A_Active loc_TNS_Name rem_TNS_Name Content of TNS local endpoint loc_TNS_Name TSEL LANSBKA X 0102030103202020 USERIPRV 00 USER2PRV 01 USER3PRV 00 Content of TNS remote endpoint rem TNS Name TA LANSBKA 080006011111 X 0301030201202020 USER1PR 00 USER2PR 01 USER3PR 00 39 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 4 Error Diagnostics The following sections describe the tools and logging mechanisms for diagnosing error groups The errors that can occur when using SOFTNET TF applications can be divided into two groups as follows Communication Errors Programming Errors The main causes and effects of communication problems are as follows gt Application associations cannot be established The most common causes are problems with the underlying transport system for example transport name service not started Individual application associations cannot be established The cause is usually in the configuration or the limit values of the transport system for example maximum number of connections have been exceeded Application associations break down during operation These problems can be caused by longer network failures incorrect response of the partner or by the application not calling tf_receive often enough Problems during the data exchange between appl
4. 281 246 Fax 0921 281 444 D sseldorf Lahnweg 10 Postfach 11 15 40002 D sseldorf AUT FG15 Hr Kreienmeier Tel 0211 399 1412 Fax 0211 399 1848 Berlin Schwarzer Weg 3 14532 Kleinmachnow Berlin AUT P11 Hr Schulze Tel 030 3993 3001 Fax 030 3993 2582 Bielefeld Schweriner StraBe 1 Postfach 78 20 33605 Bielefeld AUT Hr Klein Tel 0521 291 518 Fax 0521 291 506 Essen KruppstraBe 16 Postfach 10 33 63 45128 Essen AUT P14 Hr Ender Tel 0201 816 2925 Fax 0201 816 2344 Frankfurt a Main R delh Landstr 5 9 Postfach 11 17 33 60 052 Frankfurt AUT VG 21P Hr Wasel Tel 069 797 3825 Fax 069 797 3442 54 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 55 SOFTNET TF UNIX User Manual V2 0 Hamburg Lindenplatz 2 Postfach 10 56 09 20038 Hamburg AUT P11 Hr Becker Ullmann Tel 040 2889 2931 Fax 040 2889 3209 Hannover Hildesheimer StraBe 7 Postfach 53 29 30876 Laatzen AUT S22 Hr Weidmann Tel 0511 877 2448 Fax 0511 877 2113 Update B89058 01 2 0 Regensburg HornstraBe 10 Postfach 10 09 45 93009 Regensburg AUT P S12 Hr Bauer Tel 0941 4602 226 Fax 0941 4602 236 Saarbr cken Martin Luther StraBe 25 Postfach 10 28 42 66123 Saarbr cken AUT VG P Hr Laufer Tel 0681 386 2479 Fax 0681 386 2111 K ln Franz Geuer StraBe 10 Postfach 30 11 66 50781 K ln
5. AUT FG10 Hr Boxberg Tel 0221 576 3724 Fax 0221 576 2795 Chemnitz Bornaer Str 205 Postfach 400 546 3 09114 Chemnitz AUT P21 Hr Mehner Tel 0371 474 3512 Fax 0341 210 3525 Stuttgart Weissacher StraBe 11 Postfach 10 60 26 70499 Stuttgart AUT A12 Hr Schrickel Tel 0711 137 2028 Fax 0711 137 2684 W rzburg Andreas Grieser StraBe 30 Postfach 32 80 97042 W rzburg AUT Hr Tasch Tel 0931 6101 376 Fax 0931 6101 542 Mannheim DynamostraBe 4 Postfach 20 24 68028 Mannheim AUT Hr Kopplin Tel 0621 456 2851 Fax 0621 456 2545 N rnberg Von der Tann StraBe 30 90327 Nurnberg AUT A13 Hr Glas Tel 0911 654 3587 Fax 0911 654 7384 56 M nchen Richard StrauB StraBe 76 80286 M nchen AUT P13 Hr Wildung Tel 089 9221 4060 Fax 089 9221 4399 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Austria Switzerland Belgium Denmark Finland France Greece Siemens AG SiemensstraBe 88 92 Postfach 83 A 1211 Vienna AUT 1 Hr Capek Tel 00431 2501 3779 Fax 00431 2501 3940 Siemens AG Schweiz FreilagerstraBe 28 40 Postfach CH 8047 Z rich VHM 1 Hr St dler Tel 00411 495 5534 Fax 00411 495 3185 Siemens S A Charleroiseteenweg B 1060 Brussels VP4 Mr Van Overstraeten Tel 00322 536 2643 Fax 00322 536 2387 Siemens A S Borupvangg 3 DK 2750
6. Gulden Alpharetta GA 59 0061 3 420 7218 0027 11 407 4815 00886 2 705 4888 001 404 740 3959 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 Mr Crew 60
7. TCP IP the CLNP uses the LLI DLPI interface not in the Ethernet but rather in the ISO 802 3 mode parallel operation of both protocols via the same hardware interface is possible The background process tp4d creates the STREAM for the communications protocol consisting of CLNP and TP4 Based on the configuration file netconfig it also sets communications parameters that are independent of the particular connection netconfig contains the protocol profile for SINEC that is matched to the protocol conventions of SINEC AP and must not be modified Relevant components Module Function tp4d TP4 daemon tp4stat Provides statistical information Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 2 Creating Applications 2 1 Installation How to install SOFTNET TF UNIX is described in detail in the product information for the operating system you use When installing SOFTNET TF UNIX follow the instructions in the product information Parallel operation Parallel operation of SOFTNET TF UNIX and other SIMATIC NET UNIX of SOFTNET products is possible If you intend to run these packages simultaneously TF UNIX and other only install the CMX and CCP TP4 packages once SIMATIC NET UNIX products is possible 2 2 Programming Environment The SINEC Technological Functions TF are provided as C calls in the object library ibstf so The special definitions for the SINEC Technological Functions are located in header files tha
8. TSEL element Transport address of the remote application TA element Initiative for establishing application association USER2PR element Type of application association USER1PR element 36 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 TNSname TSEL lantype tsel TA subnet id lantype USER1PR nn USER2PR nn USER3PR logical TNS name Name must match the entry in stf_conf dat maximum of 30 ASCII characters local logon of the application association Network layer lantype and local Transport selector tsel mandatory Parameter must be set Possible values antype LANSBKA Null Internet protocol Possible values for tsel Aftsap tsap 8 characters ASCII coded Xtsap tsap 8 octets hex coded adr tsel Transport address of the remote application local Ethernet card subnet id Network layer lantype Ethernet address of the partner system addr and transport selector tse of the partner application Possible values antype LANSBKA Null Internet protocol Possible values adr Ethernet address hex exactly 6 octets Possible values for tsel Aftsap tsap 8 characters ASCII coded Xtsap tsap 8 octets hex coded Type of application association Possible values nn 00 static connection 01 dynamic connection Triggered by the application Initiative When initializing an applicat
9. call result tf receive wait timeout num mess pb rcv rcv_rsit 28 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Event Return Values of ff receive If auto rsp conc TRUE a CONCLUDE request was confirmed internally result pb rcv tf service pb rcv r STF OK CONCL STF OK If auto rsp conc FALSE a CONCLUDE is waiting for confirmation result pb rcv tf service pb rcv r E RECVE STP RECV CONCL E SFCONCL STP RECV result network If auto dom serv TRUE the TF call STF_OK tf download was executed internally pb rcv tf service REQ DLOAD after a download request from the pb rcv r STF_OK network If auto dom serv TRUE the TF call result STF OK tf_upload was executed internally pb_rcv gt tf_service REQ_UPLOAD after an upload request from the pb rcv r STF_OK If auto dom serv FALSE a download request from the network is waiting to be processed result pb rcv tf service pb rcv r E RECVE STP RECV REQ_DLOAD E_SFLOAD_REQ STP_RECV If auto dom serv FALSE an upload request from the network is waiting to be processed result pb rcv tf service pb rcv r E RECVE STP RECV REQ UPLOAD E SFUPLOAD REQ STP RECV The response of the static connections is controlled using the following parameters in the configuration file Name in stf conf
10. d e t x D file The CMX calls for logging on and off the TS application with CMX and for establishing and terminating the connection are processed The CMX calls for data exchange and flow control are processed The CMX calls for handling events are processed 42 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Example of Activating and Evaluating the CMX Library Trace SINEC APM Logging t In addition to logging the error messages the t_error calls are processed explicitly Error messages are always logged even if this option is not specified V The CMX calls their arguments the options and the user data are processed in detail The extent of processing depends on the options specified for CMXTRACE X The calls and their arguments are processed without options and user data D This option selects detailed processing with additional information about system calls file Name of one or more files containing trace entries to be processed Example of a configuration for activating the CMX library trace csh setenv CMXTRACE SD p 0 r 64 f sh CMXTRACE SD p 0 r 64 f export CMXTRACE Example of a configuration for editing the trace files Dv CMXLa lt pid gt gt file name It is advisable to redirect the data to a file otherwise they are output to stdout CMX error codes and a brief description can be found in the CMX header file usr i
11. init function with the DIM_PARAM structure Parameter in DIM_PARAM Name in stf_conf dat max_server_id max_server_id Range of Values 01013 3 Meaning Maximum number of server IDs that can be logged on Relationship to the TF User Interface Maximum value of parameter num_server with tf put mod ref max appl rel max appl max mess recv max mess max down doad max up load max upload The internal default stf conf dat file max_download is shown 1 to 255 10 1 to 32 766 1 0 to 32 766 1 0 to 32 766 1 Maximum number of application relations that can be logged on Maximum number of messages that can be received per tf receive With the domain services maximum number of possible parallel download procedures for application With the domain services maximum number of possible parallel upload procedures for in brackets Maximum value of parameter num appl with tf get path ref Maximum value of parameter num mess for tf receive application if the entry does not exist in the The configuration file stf_conf dat also contains parameters whose values are not indicated in the DIM PARAM structure These parameters are explained in the table on the following page 26 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Name in Range of Meaning Relationship to the stf_conf dat Value
12. Ballerup IP 321 Mr Saugstrup Tel 0045 4477 4441 Fax 0045 4477 4016 Siemens Oy Majurinkatu 6 SF 02601 Espoo TRI TD Mr Peltola Tel 003580 5105 3636 Fax 003580 5105 3656 Siemens S A 39 47 Boulevard Ornano F 93527 Saint Denis Cedex 2 AUT 5 Mr Weisdorfer Tel 00331 4922 3913 Fax 00331 4922 3951 Siemens A E Artemidos 8 GR 151 10 57 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 Amaroussio Athen Department AUT Mr Antoniou Tel 00301 6864 515 Fax 00301 6864 556 58 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 UK Italy Netherlands Norway Spain Outside Europe AUS RSA TAI USA Siemens pic Princess Road Manchester M20 8UR Energy amp Automation Mr A Roworth Tel 00461 446 5233 Fax 00461 446 5232 Siemens S p A Via Lazzaroni 3 20124 Milano A522 Mr Vigo Tel 00392 6676 2764 Fax 00392 6676 2820 Siemens Nederland N V Prinsesbeatrixlaan 26 NL 2595 Al Den Haag APS Mr Penris Tel 003170 333 3515 Fax 003170 333 3496 Siemens A S Ostre Aker vei 90 Linderud Boks 10 Veitwet N 0518 Oslo Dept Industrie K7 Mr A Eggen Tel 004722 63 409 Siemens S A Ronda de Europa 5 E 28760 Tres Cantos Madrid AUT 1 Mr Toledano Tel 00341 803 1200 Fax 00341 803 2271 Richmond Victoria Mr Gough Johannesburg Mr Hillermann Taipai Mr
13. TF user interface lt APM APM interface lt CMX Communication manager UNIX access to communications layer 4 addressing using logical names lt 4 Transport provider with connectionless network The following diagram is an overview of the product structure of SOFTNET TF UNIX Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 N tns file li i RFC1006 folder UNIX TCP IP RFC1006 2 gt Hardware Layer 2 board Figure 1 2 SOFTNET TF UNIX Architecture SINEC TF AP The SINEC TF AP software package provides the SINEC TF library that is based on the SINEC APM library The SINEC TF library contains the coding for the SINEC Technological Functions that you can use via the SINEC TF user interface a C language programming interface The SINEC TF library accesses the configuration file stf_conf dat that contains not only the general settings but also the assignment of the application association names to the connection end points You should bear in mind that the end points are logical names in the TNS directory and that the real addresses must be assigned to the names using the tnsxcom tool configuration Relevant components SOFTNET TF UNIX User Manual V2 0 Module usr lib TFAP_V2 5 libstf so ust lib TFAP_V2 5 libtfap so usr include TFAP_V2 5 stf_new h usr include TFAP_V2 5 stf h usr include TFAP_V2 5 stf1 h usr include
14. an application initiates writing to a declared data area Both TF calls can be triggered as unconfirmed services SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 TF Calls tf put mod ref and tf del mod ref TF call tf get path ref TF Call Parameter retry flag To ensure the transfer of the data tf receive with wait timeout 0 must be called whenever these services are called If this call is not made data can be held back due to the flow control at the transport layer The tf receive TF call detects the end of a possible bottleneck in transmission and transfers the data of the relevant service Using the parameter global server id server in the configuration file stf conf dat it is possible to log on all implemented server IDs using tf put mod ref or to log them off with tf del mod ref To do this the name used by the parameter must be supplied to the TF function call in the object description The name must be exactly 6 ASCII characters long Since the maximum send credit for asynchronous calls is not restricted by the TF library the user can define it to suit the situation For this reason the job parameter field APPL PATH of the TF function call tf get path ref always returns the value 0 in the parameter usr snd crd The retry flag parameter decides whether a TF call is repeated automatically or is not repeated by the underlying sub system The repetition of a job is not permitted with the TF
15. assigned and their effects on the TF user interface When programming it is advisable to take into account all the possible settings to avoid the need for program changes during installation and startup The configuration parameters are defined in the files stf_conf dat and apmconf data Configuration File stf_conf dat For each SOFTNET TF application there must be a configuration file stf_conf dat The environment variable TF_PATH is valid for the configuration file stf conf dat If this is not defined the configuration file is expected in the currently active folder Example The configuration file was renamed stf_conf app 1 and is defined in the folder usr config TF PATHz usr config stf conf appl1 The configuration file stf conf dat consists of 2 parts Definition of the Application Associations The application associations are defined in the second part of the stf conf dat file The entries for this are described in section 3 3 Configuring Application Associations gt Configuration data for the libstf so library Using the configuration data it is possible to adapt the ibstf so library for special purposes The configuration data are read during the initialization in the TF call init Based on the parameters the libstf so library requests memory dynamically 25 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 The following parameters in the configuration file are returned to the user during the
16. dat Range of Values Default Meaning 29 t retry 0 65535 100s Wait time in seconds from the beginning of a failed connection establishment to the next attempt t recovery 0 65535 10s Wait time in seconds after closedown abort until the next connection establishment attempt retry count 0 4 3 500000 Maximum number of connection establishment retries 10 following an abort close SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 Example Content of an stf_conf dat File Configuration File apmconf data auto_rsp_conc TRUE default FALSE global_server_id xxxxxx default no default auto_dom_serv TRUE default FALSE shareable FALSE default TRUE max_server_id n default 3 max appl rel default 10 max mess recv n default 1 max down load n default 1 max up load n default 1 For each SOFTNET TF application there must be a configuration file apmconf data for the separate package SINEC APM The environment variable APM_PATH is valid for the configuration file apmconf data If this is not defined the configuration file is expected in the currently active folder Example The configuration file was renamed conf applt and is defined in the folder usr config PATH usr config apm conf appl1 Using the configuration file it is possible to adapt the APM library for us
17. deleted gt Call the TNS compiler tnsxcom u ASCIIfile This call must be made as a superuser gt Check that entries have been deleted tnsxcom D ASCllfile This call does not need to be made as a superuser Outputting the The current address information of all existing TNS entries can be written Address to an ASCII file using the following command Information of All insxprop gt ASClifile TNS Entries tnsxprop gt ASCIIfile Where ASCIIfile any file name 33 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 3 2 Configuration Data from stf conf dat For each SOFTNET TF UNIX application there must be a configuration file stf_conf dat Apart from the configuration parameters see section 2 4 Parameter Assignment this also contains the definition of the application associations 3 3 Configuring Application Associations An application association is the communications path between two applications located on remote systems The applications reference the application associations using names in the TF call If get path ref on the TF user interface This section describes the assignment of address information of an application association to the name of the application association within an application The assignment takes two steps gt In the configuration file stf conf dat each referenced application association name of the application is assigned logical names of the Tran
18. library retry flag TF FALSE 20 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Variable Services A pointer to the C structure OBJ_VAR is transferred to the TF calls of the variable service either directly or indirectly via pointers to the C structures OBP_ACC and VAR DEF The element v real pir of the structure OBJ VAR is a pointer to the real data of the variable that is normally defined as a C variable The TF calls which evaluate or modify the real data of the variable assume a certain format byte alignment for the C variable The C variable structures used for the definition of real data of TF variables must not be parenthesized with pragma pack Adaltlonal Error The following error messages are in addition to those listed in the user Messages manual High Word Low Word Error Description 9500 0052 A500 0052 The job is not permitted in this status Check whether the connection still exists using tf_state_path 9500 000B Job number of the transmitted job is higher than the maximum permitted job number assigned in the parameters for the receiver 9500 000C The application association is terminated there is no longer a connection The connection must be re established with tf initiate 9500 000D The connection cannot be terminated since an asynchronous job is still active A conclude async was triggered but there is still an asynchronous job to be completed 9500 0A01 Invalid con
19. the structure APPL PATH component usr snd crd returns the value 0 to the application as the current send credit The application can define the send credit freely gt In TF NET UNIX automatic job repetition is possible retry flag TF TRUE gt SOFTNET TF UNIX does not support automatic job repetition regardless of how the retry flag is defined If the asynchronous mode is used for a confirmed job the application is continued immediately gt In TF NET UNIX a confirmation to the application indicates whether or not the message was transferred to the communications module To receive the confirmation of the job the tf_receive call must be programmed in the application If the monitoring time for the job elapses before the confirmation is received this application is informed with a local acknowledgment gt In SOFTNET TF UNIX the application does not receive any information as to whether the message was transferred to the underlying APM protocol stack Timeouts for asynchronous jobs are not monitored at the TF level in other words the ord_timeout parameter transferred in the function call is ignored The application does not therefore receive any information if a job could not be completed within the time The relationship between an asynchronous job and a received confirmation can be recognized by the application based on the job identifier orderid gt In TF NET UNIX the orderid can use the entire range of values
20. SIEMENS SIMATIC NET SOFTNET TF UNIX User Manual V2 0 June 1999 Update C79000 B8976 C058 01 Note We would point out that the contents of this product documentation 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 obligations of Siemens Any statement contained in this documentation do not create new warranties or restrict the existing warranty We would further point out that for reasons of clarity these operating instructions 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 operating instructions please contact your local Siemens representative General This device is electrically operated In operation certain parts of this device carry a dangerously high voltage WARNING Failure to heed warnings may result serious physical injury and or material damage Only appropriately qualified personnel may operate this equipment or work in its vicinity Personnel must be thoroughly familiar with all warnings and maintenance measures in accordance with these operating instructions Correct and safe operation of this equipment requires proper transport storage and assembly as well as careful operator control and maintenance Personnel qualification requirements Qual
21. TFAP_V2 5 stf_func h usr include TFAP V2 5 stf prty h usr bin tping usr bin tfping usr stf stf conf dat usr example TFAP V2 5 client c usr example TFAP_V2 5 server c usr example TFAP V2 5 objtyp h usr example TFAP V2 5 Makefile usr example TFAP_V2 5 stf_conf dat usr example TFAP_V2 5 apmconf data usr example TFAP_V2 5 tns_example Update B89058 01 2 0 Function TF library TF AP converter library Definition of the TF interface Definition Part 1 of the TF user interface Definition Part 2 of the TF user interface Definition of the function selection External declaration of the TF function calls Test program to test transport connections Test program to test application associations TF configuration file Example Client application variable services Example Server application variable services Example Variable definition and object description Example Makefile for applications Example Configuration file for TF library Example Configuration file for APM library Example TNS entry to match stf_conf data Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 SINEC APM CMX The SINEC APM software package provides the SINEC APM library that is based on the CMX library SINEC APM contains the protocol handler for the SINEC AP protocol SINEC AP is a Siemens protocol definition with optimized protocol syntax that can be compared with layers 5 7a of th
22. TING UP APPLICATIONS 32 3 1 The Transport Name Service RR RR 32 3 2 Configuration Data from stf_conf dat eseessessssnssonsonsonsnnennsnnssnssonsnnsonsnnssnsnnsnnnsnssnnsonsnnsnnne 34 3 3 Configuring Application Associations rssnssnssessnssnrsonsnnsonsnnsnnsnnsnnssonsnnsonsnnssnsnnssnssnnsnnsonsnnsnnn 34 4 ERROR 40 5 SAMPLE PROGRAMS Lansert 48 6 PIGS e EE 49 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 1 Introduction to SOFTNET TF UNIX In industrial production there are numerous hardware platforms with a wide variety of properties for example numeric controls robot controls programmable logic controllers production controllers etc These devices are networked with powerful network components and suitable communications hardware and software SOFTNET TF UNIX provides the TF programming interface for UNIX computer systems You will find a detailed description of the basic ideas and concepts of the TF programming interface in the TF Programming Interface manual If you are a first time user we strongly recommend that you read this section of the documentation SOFTNET Architecture SOFTNET TF UNIX consists of a total of four software packages lt TFAP25 Softnet
23. ble services X X 5 Requests for load services are only supported from the network side A TF call exists for each service of the service groups that causes a request to be sent The server functions are provided by the ibstf so library automatically To achieve this local TF calls exist to log on the server services and to make the server objects for example variables known to libstf so Further local TF calls are used for initialization for connection and status management Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 2 3 1 Operating Modes The TF calls on the client side bring about the transfer of a request that is received as an indication by the server After it has been processed the server replies with a response that is received by the client as a confirmation The parameter mode in the TF call decides whether the application that sent TF call waits for the confirmation mode CONF SYNC synchronous mode The application waits until the confirmation is received mode CONF_ASYNC asynchronous mode The TF call is returned to the application immediately after the indication has been sent The reception of the confirmation must be checked at a later point in time using the TF call tf receive Synchronous In the synchronous mode the application waits for the confirmation from Mode the server During this waiting time the application is blocked and cannot handle events on the network If you use the synchron
24. cter gt When using the hexadecimal format for the transport selector an even number of a maximum 16 hexadecimal digits can be used Hexadecimal numbers are made up of the numbers 0 to 9 and the letter a to for Ato Configuration Samples Configuring using Keywords The static active application relation OS00001 is configured Content of stf_conf dat ekkel Response of static connections valid for all application relations A Ck kk Ck k kk CkCk Kk Ck kk Ck Ck Kk I 22 2 2 22 2 22 2 2 222 2222 22 2 2 22 2 2 t retry 100 100 s wait time between establishment attempts t recovery 10 10 s wait time after connection abort retry_count 500000 Give up after 5000000 attempts KKK A RK AR A RR ARR RR RR Definition lst application relation KKK KKK HRK KKK K R KKK KKK KKK K R 22 2 22 2 2 22 2 2 222 222 2 22 2 KKK KR Type AP appl assoc name 0500001 appl type static con mode active e k e e k e 2 e e 2 2 22 2 2 2 2 2 22 2 2 222 2 22 2 22 2 2 A I A 222 2 A 2 22 2 2 Further connections x RR RIK RR KR e KKK A kk Ck Ck kk 22 2 2 22 2 2 22 2 22 2 2 22 2 2 222 2 22 2 22 2 2 22 2 2 22 207 38 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Content of TNS 0 00001 LANSBKA 080006011111 X 0301030201202020 TSEL LANSBKA X 0102030103202020 USERIPR 00 USER2PR 01 USER3PR
25. e B89058 01 2 0 CCP TP4 The CCP TP4 software package provides the protocol implementations of the transport layer 4 and network layer 3 layers according to the 7 layer ISO OSI reference model Internally it uses interfaces such as LLI DLPI and TLI XTI that were defined by AT amp T Some of these interfaces were included in the Xopen standard and are available for almost all UNIX systems CCP TP4 consists of the STREAMS multiplexers TP4 Transport Provider Class 4 and CLNP ConnectionLess Network Protocol and the background process tpd4 TP4 contains the protocol implementation for the transport layer class 4 Since TP 4 is implemented as a STREAMS multiplexer it is linked into the UNIX kernel as a separate entity As its upper access it has the Transport Provider Interface and can therefore be addressed via the standard interfaces available in the UNIX system TLI Transport Layer Interface XTI Xopen Transport Interface TP4 uses the network provider CLNP via the NPI Network Provider Interface CLNP is also a STREAMS multiplexer It contains the protocol implementation of the network layer of which SOFTNET TF Unix uses the inactive mode The CLNP accesses the network via the LLI Logical Link Provider Interface DLPI Data Link Provider Interface the layer 2 access to the network cards of the system The Ethernet interfaces existing in the system are also addressed via the LLI DLPI interface Although in contrast to
26. e ISO OSI reference model The library accesses the configuration file apm conf dat in which various settings such as timeout values etc can be made Relevant components Module Function usr lib libapm so APM library us lib libut so Utility library usr lib Ibrlog so usr lib libtpdu so Logging library File access module with TPDU interface usr bin ro log on usr bin ro log off APM logging on APM logging off usr apm apmconf data APM configuration file The CMX communications manager contains the CMX library The library provides calls for layer 4 communication in which the stations can be addressed using logical names During operation the logical names are assigned real addresses T selector MAC address and communication takes place based on the TLI XTI interface The assignment of the logical names to the real addresses is handled by the background process tnsxd in the TNS directory Transport Name Service The assignment can be made during installation and startup by the user editing an ASCII file tns file that is then transferred to the tnsxcom tool tnsxcom runs a syntax and consistency check and enters the assignments in the TNS directory Relevant components Module Function usr lib libcmx so CMX library tnsxd TNS daemon tnsxcom TNS compiler tnsxchk Check TNS directory cmxl Trace evaluation of CMX Activated using the environment variable CMXTRACE SOFTNET TF UNIX User Manual V2 0 Updat
27. e form of PICS Protocol Information Conformance Statements The following conventions are used Means that a client and server module is implemented Means only a client module is implemented nO x Means only a server module is implemented 5 Means that the function is not approved in this version Means further details in a PICS must be taken into account No segmentation 49 SOFTNET TF UNIX User Manual V2 0 PICS 1 General Update B89058 01 2 0 PICS 1 Vendor name SIEMENS AG Model name SOFTNET TF UNIX Revision V2 5A09 Device version number Operating system Abstract syntax Transfer syntax PROTID Version number Calling user yes or no Called user yes or no List of standardized names Companion standards Abstract syntax Version number 50 Solaris V2 4 V2 6 HP UX V10 10 V10 20 SCO UNIX V5 0 V5 0 4 Yes Yes None Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 PICS 2 PICS 2 TF Services Variable services Read Write Report Get variable attributes xO xXx Domain management Initiate up download Up download segment Terminate up download Request upload sequence Upload segment Request upload sequence response Request download sequence Request upload sequence Load domain content Store domain content Delete domain content Get domain attributes Program invocation management Create PI De
28. entry Initiative When Initializing an Application Association active The local application has the initiative for connection establishment USER2PR 01 must be set in the TNS entry active The local application waits for connection establishment USER2PR 00 must be set in the TNS entry Per application association there is a separate TNS entry for the local and for the remote end point or there is one entry for both end points Using the parameters of the local end point the application logs on at its local communications system with get path ref With the parameters of the remote end points either a ff initiate is executed or the arrival of an INITIATE request is expected from the partner in receiver 35 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 Structure of the TNS Entries in the ASCII File Definition using end points as the following format lt Appl assocname gt lt local_endpoint gt lt remote_endpoint gt lt Appl assocname gt Name of the application association tf get path ref lt lokalerEndpunkt gt Name for the TNS entry of the local end point The TNS entry must be a TSEL element and the elements USER1PR and USER2PR lt remote_endpoint gt Name for the TNS entry for the remote end point The TNS entry must contain a TA element and the USER1PR and USER2PR elements The TNS entries contain the following address information Logon of the local application association
29. er specific purposes The parameters are read during the initialization in the APM function call ap init and the library is adapted dynamically Some of the parameters of the configuration file must be matched to the parameters of the TF configuration file stf conf dat The configuration file contains the following parameters 30 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Name in Range of Meaning Relationship to the TF User apmconf data Values Interface assoc_limit 1 255 Number of permitted must be set to 1 for SOFTNET 1 applications per process TF applications appl limit 1 255 Number of connections per Must be matched to the 16 process definition in the configuration stf_conf dat parameter max appl ref time limit 0 32767 Monitoring time of an Monitoring time of a TF call asynchronous job Acknowledgments arriving 60 later are automatically discarded try limit 0 32767 Repetitions per job 0 means SOFTNET TF does not 0 no repetition support automatic repetitions of a TF call open interface 0 1 Definition of the interface SOFTNET TF requires the 1 0 IROS interface open interface 1 open interface pdu length 512 10248 Length of the APM PDU SOFTNET TF works with a 4096 default PDU length of 4096 Bytes num cont 20 32767 Number of available containers The number must be matched 200 to the maximum possible number of pending asynchronous TF jobs The default value
30. essage from tfping T_CONF received after lt time gt seconds Connection to remote system established The connection request was confirmed with Connect Confirm by the partner This proves that the transport system is functioning and that the parameters of the transport layer are correctly set toing terminates the connection again with DISCONNECT and logs off at the transport system Connection request rejected Message from tfping T DISIN received after lt time gt seconds returned code lt error number gt lt error description gt The connection request was rejected with Disconnect by the partner Communication via the transport system is functioning If a transport connection to this partner is required parameters must be adapted to the transport layer No reaction Message from tfping T_DISIN received after lt timeout gt seconds returned code lt error no gt Connection cannot be set up because partner does not respond to CONRQ Possible causes include There is not partner in the network with this network address or the partner is not operational partner is configured so that it does not react to incorrect transport layer parameters for example TSAP The functionality of the transport system can be checked using a LAN analyzer The transport system is functioning when the LAN analyzer records the appropriate connect request PDU The CMX error codes reason and a short de
31. h differs from the description in the TF manual This call causes the unconditional termination of an application association regardless of its status After calling tf close path the status of the application association identified by the parameter applref corresponds to the status terminated An application association must then be established again depending on the application using tf open or initiate If the status of an application association is queried with the TF call If state path and if it supplies the interim statuses E4V ESTABLISH or E4V RECOVERY it is possible to return to the status EAV DOWN with the TF call tf close path and to then re establish the application association If the server side does not respond to an indication the client side can also terminate the application association with close path and then establish it again Using the TF call tf report a server application can report the contents of one or more of its variables and with the TF call tf ustatus the logical and physical status of its virtual device to the client side without receiving an acknowledgment After each TF call for an unacknowledged service it is advisable to call tf receive This ensures that no problems occur with the flow control on the transport layer when there is a lot of traffic on the network The TF call reg msg exch can be used for a bi directional transfer of data With the TF call msg write
32. he header files contain the type declarations of the data types used in the TF function calls The header file stf h must be included in all modules of the application that use the TF function calls The file stf h contains the include instruction for stf1 h Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Compiler Options The service groups can be deselected using the following compiler options NO_GEN no administrative and general services NO_SER no serial transfer NO_TIM no time services NO_VAR no variable services NO_DOM no domain services NO PI no program invocation services The modules assigned to the service groups are not linked to the application The following switch instructs the compiler to make a prototype check of the TF calls during translation TF PROTO Check the prototypes based on the function prototypes specified in the header file stf_prty h This header file must be included in the C source files of the application using the include instruction Linking the The TF AP library libstf so contains all the calls of the user interface as Applications separate modules Each application links the library modules automatically into the executable program Library Function dynamic 1 static libstf so libstf a TF library libtfap so libtfap a TF AP librar libapm so libapm a APM library libut so libut a APM utility librar librlog so librlog a APM logging library libtpdu s
33. his is the file stf conf dat Example tfping d stf conf dat Functions Using the application association names the program attempts to establish an application association to the corresponding partners using if initiate If an application association is defined as active in the TNS entry tfping establishes the association with tf initiate reads the identity of the partner vendor device type and revision using if identify and then terminates the application association again If tfping recognizes a passive application association in the initiate it executes the server functions of the TF services initiate tf identify and tf conclude In the tf receive the program waits for the partner to establish the application association if appropriate to read out the identity and then to terminate the association again 46 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 The tfping program terminates itself automatically as soon as all the application associations have been closed The program can be aborted with the DEL key for example when the partner does not react Possible errors when logging on an application association The application association name is not entered in the stf_conf dat configuration file gt tf_get_path_ref indicates the result Fatal_Error and tfping is terminated Possible errors when initiating an application association The partner does not exist for e
34. ication association name is mandatory Format in since this indicates the end of the name If more than one blank is stf conf dat necessary at the end of an application association name these must be inserted between the last character of the connection and the colon 34 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 AP Connections Using Keywords Application Association Names by Defining End Points An application association is defined using the following keywords Type appl_assoc_name type con_mode lt Appl BezName gt lt static dynamic gt lt active passive gt AP Type of connection is always AP Application association name lt Appl assocname gt logical TNS name static dynamic Type of application connection Possible values static dynamic active passive Possible values active passive Name of the application association tf get path ref is also the logical TNS name The corresponding TNS entry must contain a TSEL and a TA element Type of application association static If the application association is active establishment is triggered automatically in ff get path only layer 4 connections USER1PR 00 must be set in the TNS entry dynamic With active application associations the establishment must be triggered by the user with If initiate or tf open path USER1PR 01 must be set in the TNS
35. ications The cause is usually an incorrect response on the partner or that tf_receive is not called often enough Common programming errors are as follows gt gt Incorrect parameters are transferred to the TF functions for example the parameter app refto a non existent application association The values for the parameter ord_timeout have been selected too low in the synchronous mode In the asynchronous mode the object descriptions are changed before the service is completed Rare external events errors exceptional situations have not been taken into account For example server services may be logged on that cannot be handled The TF function receive is not called often enough 40 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Troubleshooting in Communication CCP TP4 Transport The STREAM that forms the protocol stack is maintained by the to4d System background process Using the UNIX command ps you can check whether the tp4d process is active The fp4stat command is also available with which you can fetch and analyze statistical information from the transport system Transport Name In the TNS the background process tnsxd manages the address Service TNS information of the applications involved in communication as TNS entries in the TNS directory With the UNIX command ps you can check whether the tnsxd process is active The existing TNS entries of the TNS directory can be read int
36. ified personnel as referred to in the operating instructions or in the warning notes are defined as persons who are familiar with the installation assembly startup and operation of this product and who possess the relevant qualifications 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 Contents 1 INTRODUCTION TO SOFTNET TF UNIX ecce 4 2 CREATING APPLICATIONSG u 2a 9 2 1 Installation resserensenvnrenenvensnnensenennensenensnvennensvennsvennenssnennsvennevennennsvennevennennsvennsvennenn avnevnsvevnsvesnee 9 2 2 Programming Environment c sessvesverevevenennennvenennennvenenneeneenennnensenennvenenneeneenennnennenenneennennennennenee ev 9 2 3 The SINEC TF User Interface C Programming 14 2 3 1 Operating Modes o een ce te ertt 15 2 3 2 Supplements to the Manual SINEC TF User 17 2 3 3 Porting TF NET UNIX Applications to SOFTNET TF UNIX sees 22 2 4 Parameter Assignment ssssssonssonssonssossonssonsnonsonnsnnssnnssnnssnnnnnnennnssnnsssnssnssonssonssnnsnnnsnnssnnsnnnene 25 3 INSTALLING AND STAR
37. ion relation Possible values nn 01 active initiative by loc application 00 passive initiative by remote application Content is not relevant for SOFTNET TF must however have 00 entered to ensure consistency 37 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 subnet_id When using the OSI transport protocol SOFTNET TF UNIX supports operation with more than one Ethernet board This parameter is used to address the Ethernet board used in active connection establishment to the remote SOFTNET TF UNIX application Caution The lt subnet_id gt parameter depends on the particular operating system Please refer to the SIMATIC NET UNIX product information for the operating system you are using to check the correct value The following format is mandatory for lt subnet_id gt X lt string gt lt string gt character string with exactly 4 hexadecimal digits Restrictions Affecting Names in the TNS Entries gt The logical name of a TNS entry can be a maximum of 30 characters long It must start with a letter or the underscore character the remaining 29 characters can be letters underscores or numbers gt The transport selectors can be either in ASCII format when preceded by an A or in hexadecimal format when preceded by an X gt When using the ASCII format a maximum of 8 characters are possible for the transport selector Permitted characters are letters numbers or the underscore chara
38. lete Start t Stop PI a Resume PI Reset PI Get PI attributes VMD services Status Unsolicited Status Get name list Identify Get capability list XXX Application association management Initiate Conclude Abort Time functions Request time C X X Serial transfer Read byte string Write byte string Transparent data exchange 51 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 PICS 3 Data PICS 3 Types a boolean X b bitstring X Basic data C integer X types d unsigned X octet string X f visible string X 9 floating point X arrays X structures X Named all scopes defined variable by TF Unnamed variable Nesting level 2 Hierarchiestufen nesting Number of alternative accesses 16 number of alternative accesses in a job List of variables 16 number of variables in a job Relationship Object description to re access description in job Td complexity of access definitions in the protocol see above 52 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 PICS 4 Value Ranges PICS 4 Range for floating point values s See appendix A in the TF User Interface manual Range for floating point exponent s See appendix A in the TF User Interface manual Range for floating point s See appendix A in the TF User Interface manual Range for integers s See appendix A in
39. ll length are logged The options s and S exclude each other The calls with additional information about system calls are logged in detail This option is only available in addition to s or S The decimal digit fac determines the buffer factor The amount of buffering is determined according to fac BUFSIZ where BUFSIZ is determined by lt stdio h gt If you specify fac 0 each trace entry is written to the file immediately with no buffering fac 0 8 Default fac 1 The decimal number wrap specifies that after wrap BUFSIZ bytes BUFSIZ according to lt stdio h gt logging continues in the second temporary file lt directory gt CMXMa lt pid gt This second file handles the trace in exactly the same way as CMXLa lt pid gt After wrap BUFSIZ bytes the trace switches between the two files Following this switch over the content of the file is overwritten Default wrap 128 The trace files are written to the specified directory Default directory usr tmp or var tmp cmxl reads the entries generated by the trace from the temporary file processes the entries according to the selected options and outputs the result to stdout The following options specify which trace entries from the file are processed It is possible to specify more than one of the values described below per cmxl call Only the options v and x exclude each other If no options are specified cdex is used as the default c
40. ly within a C procedure and the procedure is exited before the tf_receive call Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 2 3 2 Supplements to the Manual SINEC TF User Interface Non Approved Services Transfer Parameters Status Bits and Error Messages New TF Call tf_getfds The TF domain and program invocation services are not approved for this version of SOFTNET TF UNIX Inthe TF manual all the transfer parameters status messages and error messages are preceded by the TF prefix for example TF E INIT When using the header file stf_new h the transfer parameters the status messages and error messages can be evaluated as described in the TF manual If you use the header file stf h the prefix TF must be omitted when using transfer parameters or when evaluating status and error messages for example E_INIT The tf getfds call returns the file descriptors occupied by the technological functions These can be used in the poll system call This allows user programs to wait for further external events in addition to communications events If the system call poll detects events in file descriptors of TF must then be called with wait timeout 0 Remember that the tf_receive call can return with the status message no event occurred The file descriptors occupied by TF must be queried before each poll call since they can change dynamically int tf getfds struct pollfd
41. must be consistent within a system It is managed by the background process tnsxd as TNS entries in the TNS directories Each TNS entry is assigned a logical TNS name that must be unique within the computer system The TNS entries are created using the TNS compiler tnsxcom The address information is edited in an ASCII file that is transferred to the TNS compiler as a parameter gt Call the TNS compiler to create TNS entries tnsxcom u ASCIIfile This call must be made as a superuser gt Check the newly created entries tnsxcom D ASCllfile This call does not need to be made as a superuser If you need to change the address information of existing TNS entries follow the procedure below gt Read the current TNS entries into an ASCII file 32 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 tnsxcom D ASCllfile This call does not need to be made as a superuser gt Modify the address information in the ASCII file Refer to the structure of TNS entries gt Update the TNS entries by calling the TNS compiler tnsxcom u ASCIIfile This call must be made as a superuser gt Check the modifications made tnsxcom D ASCllfile This call does not need to be made as a superuser Deleting Existing You delete an existing TNS entry as follows TNS Entries gt Generate an ASCII file with the following entry TNSname DEL Where TNSname the TNS entry to be
42. nclude cmx h The SINEC APM protocol underlying SINEC TF includes a dynamic logging system The logging system consists of basic logging and a section that allows dynamic change of the logging levels at any time The user has the choice between the highest logging level log all level 1 or no logging do not log level 4 A file must contain the required logging level To support the dynamic logging system the user must define an environment variable containing the path and file name of a global logging level file The process specific logging level file is used to change the level for a particular process during operation For this there are commands available that generate the global logging level file when the first call is made With the example configurations the library trace can be switched on and data can then be analyzed 43 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 For more detailed information refer to the SINEC APM user manual see References The global logging level file roslog that contains the default logging level is required in the tmp directory This file is generated when the start or stop command is first called ROS LLFILE tmp roslog The logging system is activated by the following call ro log on lt parameter gt Parameter 1 level high Everything is logged function calls of the user interface and internal calls of the SINEC APM 2 level medium Logging of in
43. nection reference 9500 0A41 Logon at the server failed 9500 0 43 No connection established to the server 9500 FF9D Temporary error on the underlying APM lack of containers The number of available containers parameter in apmconf data is inadequate for initiated asynchronous jobs Fetch the acknowledgments with tf receive and then repeat the job 21 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 2 3 3 Porting TF NET UNIX Applications to SOFTNET TF UNIX To ensure problem free porting of applications that already use TF NET UNIX as the communication medium to SOFTNET TF UNIX read the following information carefully TF Services Static Dynamic Application Associations gt gt The asynchronous TF function calls of the local administrative services group tf_aopen_path tf_aclose_path are not supported by SOFTNET TF UNIX The asynchronous TF function calls of the VMD services group tf_unso_stat are also not supported by SOFTNET TF UNIX When you change from TF NET UNIX to SOFTNET TF UNIX you can use the synchronous TF function calls tf open path tf close path tf state path tf ustatus These functions are also executed by the library when there are still asynchronous jobs active on other application associations The required response of the connection can be implemented by using the function tf astate path and working with statically configured connection
44. o libtpdu a APM file access librar libcmx so libcmx a CMX library libsocket so libsocket a Socket librar libnsl so libnsl a Socket utility library 1 In HP Unix the names of the dynamic libraries have the extension sl SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 Example of an Application The example is based on an application consisting of two modules This application activated the prototype check It does not support domain and PI services Excerpt from module 1 prog c include lt stf_new h gt include lt stf_func h gt include lt stf_prty h gt main argc int result result tf Excerpt from module 2 prog 1 c include lt stf h gt f include lt stf_prty h gt int function 1 int result result tf_ Excerpt from the makefile SOFTNET 1 makefile oy TF_OPT DNO_DOM DNO_ PI DTF_PROTO TFAP_INCL usr include TFAP_V2 5 TFAP_LIBS L usr lib TFAP V2 5 Istf Itfap lapm lut Irlog Itpdu Icmx Isocket Insl SINEC_OPT TF_OPT I TFAP_INCL APPLICATION prog c prog1 c prog APPLICATION TFAP LIBS CC SINEC_OPT prog APPLICATION V TFAP_LIBS ee ELSES ELE ELE EEE ERAN a SERENE XTRA RE AREA RAAAS HE The L switch in the link instruction means that the linker searches for the libraries specified with the option L in a further file directory in additi
45. o the ASCII file with the name ASCIIfile using the command tnsxcom D ASCllfile and checked with the command tnsxcom s ASCIIfile CMX Library Trace The trace of the CMX library is controlled by the environment variable CMXTRACE By supplying the environment variable with a value the trace is activated and the scope of the information to be collected is specified The trace entries of a process are collected as compact binary data in a dynamically created buffer and periodically written to temporary files These binary files are edited separately with the cmxl tool The binary files are saved in the directory usr tmp The file names consist of the prefix CMXLa or CMXMa and the process identification number pid cmxl reads the entries generated by the trace from the temporary file The scope of the analysis is decided by the options selected for cmxl CMXTRACE The options specified in CMXTRACE control the trace The options s S Controlling the and D determine what is logged The options p r control the buffering and Trace wrap writing of the file s S D p fac r wrap f directory 41 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 cmxl How the Trace Trace p fac wrap f directory The CMX calls their arguments the options and user data are logged normally The calls their arguments the contents of any options the user data in their fu
46. on can be terminated by a disconnect on any application association acknowledgment if a synchronous active job is The synchronous job is terminated with result E CONN LOST in other words the local application association is closed down The connection must be re established and the interrupted job may have to be repeated The synchronous job is terminated with result E CONN LOST At this point in time the application has no information about which application association was interrupted The status of the application associations must be checked the connection re established and if necessary the interrupted job repeated TRUE While a synchronous job application must fetch any is active indications temporarily stored jobs following each received in the meantime synchronous job with tf receive It must are stored temporarily then evaluate the jobs and react to The TF library does not them accordingly With each acknowledge these tf receive the fetched job is indications negatively acknowledged FALSE The TF library automatically acknowledges incoming jobs with negative If the entry does not exist the underscored default values apply a If the parameter global_server_id does not exist only the values for the parameters described in the manual for opb ptr server id can be used for tf put mod ref 919 following table shows how the events are recognized in the TF
47. on to Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 the standard directories This is necessary since the TF libraries are not located in a standard directory 13 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 2 3 SINEC TF User Interface C Programming Interface The TF user interface is defined without reference to a particular system and is described in detail in the SINEC TF User Interface manual The following sections provide a general overview and contain additional information for specific systems not included in the manual Range of Functions SOFTNET TF functionality is compatible with MMS layer 7 complying with MAP 3 0 provided the application is restricted to the open services open services MMS compatibility Nine service groups are defined in MMS These services operate according to the client server principle The server provides a service requested by the client When it requires a service the client sends a request to the server The server replies to the indication with a response The server can also send an unconfirmed request to the client SOFTNET TF supports the following service groups Name in MMS Name in the manual Client Server standard Environment And Application association X X General Management management VMD Support VMD services X X Domain Management Domain services X Program Invocation Program invocation services X Management Variable Access Varia
48. ous mode remember the following points lt TF calls can only be sent in the synchronous mode when asynchronous TF calls are being processed This means that no confirmations from the server can be received from the network lt lt n the synchronous mode the parameter store ind in sync mode that is set in the configuration file stf conf dat can be used to control the way in which the TF library responds to confirmed indications It is possible to specify whether indications arriving during a synchronous TF call are acknowledged negatively or are stored temporarily for later processing The maximum number of temporarily stored indications is determined by the parameter max mess recv that is set in the configuration file stf conf dat lt During a synchronous TF call unconfirmed indications are stored temporarily until the next tf receive call The maximum number of temporarily stored indications is determined by the parameter max mess recv that is set in the configuration file stf conf dat The waiting time until the end of the synchronous TF call is determined by the reaction time of the server SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 Asynchronous Mode In the synchronous mode the user can specify a maximum waiting time until the confirmation is received from the server using the parameter ord_timeout The ord_timeout parameter must be set higher than the timeout values of the transport system This is necessar
49. puts into and outputs out of user interfaces function calls 3 level low Only errors are logged By activating the logging two logging files are created and written to alternately These logging files are created in the tmp directory under the names humba L1 lt pid gt and humba L2 lt pid gt pid process identification Both files are ASCII files and can be analyzed directly using an editor Enter the following to terminate the logging function ro_log_off This command does not require a value for the logging level This command automatically writes logging level 4 no logging into the logging level file Testing the Communication at the transport layer can be checked with the tping Transport program The program uses the transport name service tping tping ro tnsname1 p tnsname2 Parameter otnsname global name for the TNS entry for the logon at the local transport system if the parameter is not specified the default fping applies p tnsname2 TNS entry with which it is attempted to establish a transport connection if the parameter is not specified tnsname1 is used 44 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 The program logs on at the local transport system with the TNS entry tnsname1 and attempts to establish a transport connection with the TNS entry tnsname2 Three reactions to the connection request are possible gt Connection request accepted M
50. quests from the network shareable TRUE DOMAIN can be used by Parameter that is transferred to the more than one server during startup and that can be PROGRAM overwritten by the call INVOCATION tf_download FALSE can only be Parameter that is transferred to the used by one PROGRAM INVOCATION server during startup and that can be overwritten by the call tf download If the entry does not exist the underscored default values apply If the parameter global server id does not exist only the values for the parameters opb_ptr gt server_idcan be used for tf put mod ref The following table shows how the events are recognized the call result tf receive wait timeout num mess pb rcv rcv rsit 27 SOFTNET TF UNIX User Manual V2 0 Name in stf conf dat with va spec Update B89058 01 2 0 Range of Meaning Relationship to the Values TF User Interface FALSE Variable value s and type description are transferred to the client Only the variable value and not the type description is transferred to the client This setting is only relevant with the TF call tf read This setting is only relevant with the TF call tf read ignore disc in sync mode store ind in _ sync mode TRUE FALSE A synchronous job can only be terminated by a disconnect on the local application association A synchronous job on an application associati
51. s The TF domain and program invocation services are not approved for this version of SOFTNET TF UNIX In contrast to TF NET UNIX in SOFTNET TF UNIX the transport connections for the static application association are not established when the communication module starts up but rather connection establishment is triggered with the function tf get path ref This means that after tf get path ref the system waits in the tf receive function for connection establishment before data can be sent With SOFTNET TF UNIX only layer 4 connections can be established statically For reasons of compatibility to earlier versions of SOFTNET TF UNIX layer 7 connections must be established as dynamic application associations with tf initiate In dynamic application 22 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 Job Repetitions Asynchronous Jobs orderid Unconfirmed Jobs associations the application alone is responsible for managing the application relations establishment termination and maintenance gt In TF NET UNIX a send credit limits the maximum number of jobs per application association sent by a client and not yet confirmed The application is informed of the send credit defined in the database using the TF function tf get path ref in the structure APPL PATH component usr snd crd gt In SOFTNET TF UNIX there is no restriction of the send credit For this reason the TF function tf get path ref in
52. s TF User Interface auto_rsp_conc global_server_id Exactly 6 ASCII characte rs Automatic call for If rsp conclude with parameter conclude TRUE in ff receiver The application can decide whether or not to confirm or reject a CONCLUDE request Logon or logoff of all the implemented server IDs depending on the setting max server id The application recognizes in the If receive that a CONCLUDE request was confirmed In the ff receive the application is informed that a CONCLUDE request was received that must be responded to with 553 This name must be used as the parameter opb_ptr gt server_id with tf_put_mod_ref or tf del mod ref auto dom serv TRUE Automatic call for In the tf_receive the file server tf upload or application recognizes that the tf download when tf_download or tf_upload was receiving the upload or executed internally due to a download download requests from jor upload request from the the network network The application must run the resulting routines for example tf_receive just as if it had issued the TF calls itself FALSE The application can In the tf_receive the application decide whether it calls is informed that a download or upload tf or request was received from the tf download when it network and must be replied to with receives the upload or tf download or tf upload download re
53. s poll fds int nfds Parameter poll fds In poll fds the caller transfers pointer containing a pointer to a structure pollfds The function enters the currently occupied file descriptors in this structure and returns its address to the caller nfds Pointer to an integer variable in which the function indicates the number of occupied file descriptors Return 0 Callis OK The file descriptors have not changed since the last call 1 Callis OK The file descriptors have changed since the last call 1 Error occurred If necessary repeat the TF call SOFTNET TF UNIX User Manual V2 0 Signal Processing Update B89058 01 2 0 If it is not necessary to wait for additional events the return values of If get fds can be transferred directly to the system call poll Example struct pollfds fds int nfds int timeout 5000 5 seconds if tf getfds amp fds amp nfds gt 0 ret poll fds nfds timeout For a detailed description of the system call poll please refer to the UNIX Programmer s Reference Manual Internally the TF library uses the C libraries provided by the UNIX operating system and it is not guaranteed that they can be called recursively For this reason when using signals you should protect the TF calls from interruptions and must use only the UNIX system call poll in waiting situations Example struct pollfds fds int nfds int timeout 5000 5 sec
54. s are indicated in brackets 31 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 3 Installing and Starting Up Applications General SOFTNET TF applications use the C interface to the SINEC Technological Functions TF user interface for communication with remote systems for example programmable controllers To achieve this the application must link the libraries libstf so and libtfap so The response of certain functions of the libstf so library and their response on the TF user interface can be controlled using parameters of the configuration filestf_conf dat see section 2 4 Parameter Assignment On the TF user interface the application uses freely selectable names for the application associations to address partner applications The assignment of the actual address parameters of the partner applications to the application associations is then made while the program is running The application association names are defined in the configuration file stf conf dat The definitions referred to entries of TNS Transport Name Service In the TNS the logical names are assigned the communication addresses local and remote t selector remote Ethernet address etc 3 1 The Transport Name Service TNS Transport Name Service TNS Creating the TNS Entries Modifying Existing TNS Entries Within the transport name service SOFTNET TF manages the address information of the communications stations This information
55. scription can be found in the CMX header file usr include cmx h Errors can be investigated in greater detail with the CMX trace tool 45 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 Testing the Application Associations tfping Using the tfping program it is possible to check whether application associations are correctly configured and whether they can be established to a partner The program uses the configuration file stf_conf dat in the local directory to decode the application association name It provides the following three modes tfping v tfping d filename v tfping TNS name1 TNS name2 TNS name3 v Parameter v Display extended monitor output without Interactive mode TNS names Selective test batch d filename Complete test gt Interactive The program is called without parameters It prompts the name of the application association to be tested Several names must be separated by commas gt Batch The names of the application associations are supplied to the program as parameters when it is called The names must also be separated by commas here Example tfping Aname 1 Aname 2 Aname n Complete test The program is supplied with a configuration file as a parameter It checks all the application association names of the configuration file If no file name is specified the file specified by the environment variable TF PATH is processed Normally t
56. sport Names Services TNS gt The address information of applications between which there is an application association is stored using the logical TNS names The address information is stored with the tnsxcom tool As its input the tool uses a readable file in which the TNS entries can be edited Application The application names must be defined in the sif conf dat These are the Association Names same names that the application transfers in the TF call tf get path ref in stf_conf dat The application association names can be defined using 2 methods 1 Definition as AP connection using key words This allows the application association to be defined as static and also allows it to be distinguished from a redundant application association 2 By assigning the connection end points The application association names are assigned TNS entries as local and remote connection end points using logical TNS names Due to the conversion in the configuration file stf_conf dat the application association names can be selected freely regardless of the logical TNS names of other applications This method supports only dynamic connections at layer 7 connections established with INITIATE These are provided only to assure compatibility with previous versions and should not be used any longer with new applications Application Application association names can contain blanks For this reason Association Name the colon following the appl
57. t the application must include in the source file using the include instruction The services of the SINEC Technological Functions can be divided into several groups The application can deselect certain service groups using compiler options Header Files The following header files are relevant and are inserted into the C source files of the application using the include instruction stf_new h stf_func h stf_prty h Compatibility With stf h Old Applications stf1 h The header file contains the type declarations of the data types used in the TF function calls This must be included in all the modules of an application that use the TF function calls The status and error messages conform to the messages described in the TF manual The content of the header file is irrelevant when using the TF user interface Depending on the compiler options the pointer to the TF server functions is set in this header file This file contains C code and must be included in one module of the application This header file contains the prototypes of the TF calls It must be included in all modules of the application that are translated with the compiler option TF PROTO These two header files are intended for old applications that must be ported These two header files were replaced by stf new h The status and error messages do not conform to the messages described in the TF manual SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 T
58. the TF User Interface manual Range for unsigned s See appendix A in the TF User Interface manual Maximum length BIT_STRING Maximum length OCTET_STRING Maximum length VISIBLE_STRING TF address 0 lt data resv lt 2 31 1 0 lt data_resv lt 2 31 1 can be negative 0 lt data_resv lt 2 31 1 can be negative Max job management time Capability list of the virtual device 2 31 1 milliseconds Not used 53 SOFTNET TF UNIX User Manual V2 0 7 Who to Contact Contacts for Technical Questions Update B89058 01 2 0 If you have questions about using this product please call our SIMATIC NET hotline in Nuremberg Siemens AG Customer Support Telephone 49 911 895 7000 Telefax 49 911 895 7001 The following list shows you who to contact in your area Germany Aachen Postfach 12 85 52013 Aachen Hr G rgens Tel 0241 451 252 Fax 0241 451 398 Augsburg Werner von Siemens Str 6 Postfach 10 23 49 86135 Augsburg AUT Hr Gleichfeld Tel 0821 2595 371 Fax 0821 2595 412 Braunschweig AckerstraBe 20 Postfach 33 47 38023 Braunschweig AUT P12 Hr Reupke Tel 0531 7012 436 Fax 0531 7012 400 Bremen Contrescarpe 72 Postfach 10 78 27 28078 Bremen AUT P12 Hr Kroll Tel 0421 364 2431 Fax 0421 364 2842 Bayreuth Postfach 10 10 51 Weiherstr 25 95410 Bayreuth AUT 51 Hr H ttl Tel 0921
59. xample a partner application has not been started the cable is not plugged in the CPU CP of the PLC are in the STOP mode ff initiate indicates the result Abort and tfping is terminated Note If the remote system is configured as being active and only establishes a level 4 connection once no message is output 47 SOFTNET TF UNIX User Manual V2 0 Update B89058 01 2 0 5 Sample Programs The programming examples are in the directory usr example TFAP V2 5 With the example programs and the supplied configuration files you can run simple client server communication locally on your computer The example programs consist of the following files client c Client module server c Server module objtyp c Object description of the variables With the supplied makefile you can translate the programs and link them to the libraries This produces the runnable programs client and server To initialize the communication system the directory also contains the two configuration files stf conf dat apmconf data These configuration files have been adapted to the two example programs and do not need to be modified The tns example file contains an example TNS entry This must be adapted to the partner system With the TNS command tnsxcom u ins example you transfer the TNS entry to the TS directory 48 Update B89058 01 2 0 SOFTNET TF UNIX User Manual V2 0 6 PICS The range of services of the TF Library is described in th
60. y so that the application receives correct error messages and can react accordingly TF call ord_timeout tf_initiate 70 sec tf_conclude 70 sec all other TF calls 70 sec In the asynchronous mode the TF call is returned immediately to the application once the indication has been sent In the asynchronous mode the call parameter ord_timeout therefore has no significance The application can use the waiting time until the confirmations are received from the server for other purposes Several asynchronous jobs can be active at the same time Per application association however only as many jobs are permitted as allowed by the current send credit The application can specify the send credit for each application association itself by supplying the component usr snd crd of the structure APPL PATH of the TF call tf_get_path_ref To recognize the end of an asynchronous job the application must call tf_receive This TF call blocks the application until the specified number of messages num mess is received or the maximum waiting time wait timeout expires The application transfers parameter fields to the TF calls using pointers These parameter fields are accessed again in the tf_receive call when the confirmation is received This means that the parameter fields must exist during the entire processing of an asynchronous job and must not be modified Undefined statuses result in particular when a parameter field was defined local
Download Pdf Manuals
Related Search