SIMOTION. SIMOTION IT SIMOTION IT Virtual Machine and Servlets. Preface. Fundamental safety instructions 1. Introduction 2. Software installation 3

Transcription

1 Preface Fundamental safety instructions 1 SIMOTION SIMOTION IT SIMOTION IT Virtual Machine and Servlets Introduction 2 Software installation 3 Software programming 4 Programming Manual Valid as of Version /2014

2 Legal information Warning notice system This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger. DANGER indicates that death or severe personal injury will result if proper precautions are not taken. WARNING indicates that death or severe personal injury may result if proper precautions are not taken. CAUTION indicates that minor personal injury can result if proper precautions are not taken. NOTICE indicates that property damage can result if proper precautions are not taken. If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage. Qualified Personnel The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems. Proper use of Siemens products Note the following: Trademarks WARNING Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed. All names identified by are registered trademarks of Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner. Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions. Siemens AG Industry Sector Postfach NÜRNBERG GERMANY P 04/2014 Subject to change Copyright Siemens AG All rights reserved

3 Preface SIMOTION Documentation An overview of the SIMOTION documentation can be found in the SIMOTION Documentation Overview document. This documentation is included as electronic documentation in the scope of delivery of SIMOTION SCOUT. It comprises ten documentation packages. The following documentation packages are available for SIMOTION V4.4: SIMOTION Engineering System Handling SIMOTION System and Function Descriptions SIMOTION Service and Diagnostics SIMOTION IT SIMOTION Programming SIMOTION Programming - References SIMOTION C SIMOTION P SIMOTION D SIMOTION Supplementary Documentation Hotline and Internet addresses Additional information Click the following link to find information on the the following topics: Ordering documentation / overview of documentation Additional links to download documents Using documentation online (find and search manuals/information) Please send any questions about the technical documentation (e.g. suggestions for improvement, corrections) to the following address: [email protected] My Documentation Manager Click the following link for information on how to compile documentation individually on the basis of Siemens content and how to adapt it for the purpose of your own machine documentation: Programming Manual, 04/2014 3

4 Preface Training Click the following link for information on SITRAIN - Siemens training courses for automation products, systems and solutions: FAQs Frequently Asked Questions can be found in SIMOTION Utilities & Applications, which are included in the scope of delivery of SIMOTION SCOUT, and in the Service&Support pages in Product Support: Technical support Country-specific telephone numbers for technical support are provided on the Internet under Contact: 4 Programming Manual, 04/2014

5 Table of contents Preface Fundamental safety instructions General safety instructions Industrial security Introduction Overview of SIMOTION IT SIMOTION IT Virtual Machine SIMOTION IT Servlets Software installation SIMOTION IT Virtual Machine SIMOTION IT Servlets Software programming Scope of delivery Supported Java packages Default directories SIMOTION.JAR Restrictions and special features Overview Number of threads Network functions File system Synchronization with the PLC Effects on the target system and user programs Connecting to SIMOTION SCOUT Debugging Java programs SIMOTION API Overview Variable access Browsing variables Reading variable properties Accessing drive data Accessing target system functions Calling system functions Using persistent data (NVRAM) Logging Creating user programs Configuration files AUTOSTART configuration (JINVOKE.XML) JamaicaVM configuration (VMCONFIG.INI)...47 Programming Manual, 04/2014 5

6 Table of contents Transferring user programs to the target system Diagnostics buffer entry Output file JCONSOLE.TXT Interactive InvocationManager interface Overview The InvocationManager protocol Commands job/task requests Sample requests Sample programs Format of logging outputs Restarting the JamaicaVM SIMOTION IT Servlets Scope of functions implemented Scope of delivery Implementing the servlet API Creating user servlets Configuration file (JSERVER.XML) Sample servlet and configuration Restart of the servlet container...68 Index Programming Manual, 04/2014

7 Fundamental safety instructions General safety instructions WARNING Risk of death if the safety instructions and remaining risks are not carefully observed If the safety instructions and residual risks are not observed in the associated hardware documentation, accidents involving severe injuries or death can occur. Observe the safety instructions given in the hardware documentation. Consider the residual risks for the risk evaluation. WARNING Danger to life or malfunctions of the machine as a result of incorrect or changed parameterization As a result of incorrect or changed parameterization, machines can malfunction, which in turn can lead to injuries or death. Protect the parameterization (parameter assignments) against unauthorized access. Respond to possible malfunctions by applying suitable measures (e.g. EMERGENCY STOP or EMERGENCY OFF). Programming Manual, 04/2014 7

8 Fundamental safety instructions 1.2 Industrial security 1.2 Industrial security Note Industrial security Siemens provides products and solutions with industrial security functions that support the secure operation of plants, solutions, machines, equipment and/or networks. They are important components in a holistic industrial security concept. With this in mind, Siemens products and solutions undergo continuous development. Siemens recommends strongly that you regularly check for product updates. For the secure operation of Siemens products and solutions, it is necessary to take suitable preventive action (e.g. cell protection concept) and integrate each component into a holistic, state-of-the-art industrial security concept. Third-party products that may be in use should also be considered. For more information about industrial security, visit To stay informed about product updates as they occur, sign up for a product-specific newsletter. For more information, visit WARNING Danger as a result of unsafe operating states resulting from software manipulation Software manipulation (e.g. by viruses, Trojan horses, malware, worms) can cause unsafe operating states to develop in your installation which can lead to death, severe injuries and/ or material damage. Keep the software up to date. Information and newsletters can be found at: Incorporate the automation and drive components into a state-of-the-art, integrated industrial security concept for the installation or machine. For more detailed information, go to: Make sure that you include all installed products into the integrated industrial security concept. 8 Programming Manual, 04/2014

9 Introduction Overview of SIMOTION IT Overview of SIMOTION IT manuals The "SIMOTION IT Ethernet-based HMI and diagnostic functions" are described in three manuals (IT = Information Technology): SIMOTION IT Diagnostics and Configuration This manual describes the direct diagnosis of SIMOTION devices. Access is by means of a standard browser (e.g. Firefox) via the IP address of the SIMOTION device. You can use the standard diagnostic pages or your own HTML pages for access. See the manual SIMOTION IT Diagnostics and Configuration. SIMOTION IT Programming and Web Services This manual describes the creation of user-defined web pages and access to the diagnostic functions via the two web services provided by SIMOTION IT. A web service enables users to create their own client applications in any programming language. These applications then communicate with the SIMOTION device using web technologies. The SOAP (Simple Object Access Protocol) communication protocol is used for transferring commands. The manual includes information on programming such clients, as well as a description of the SIMOTION IT web services (OPC XML-DA, Trace via SOAP TVS) via which data and operating states of the controller can be accessed and the variable trace functions can be used. See manual SIMOTION IT Programming and Web Services. This manual describes the Java-based function packages. The Jamaica Virtual Machine (JamaicaVM) is a runtime environment for Java applications on the SIMOTION device. It is an implementation of the "Java Virtual Machine Specification." The Servlets section of the manual describes the use of servlets in a SIMOTION device. See also PDF in the Internet: SIMOTION IT Diagnostics and Configuration ( support.automation.siemens.com/ww/view/de/ /0/en) PDF in the Internet: SIMOTION IT Programming and Web Services ( support.automation.siemens.com/ww/view/de/ /0/en) Programming Manual, 04/2014 9

10 Introduction 2.2 SIMOTION IT Virtual Machine 2.2 SIMOTION IT Virtual Machine The Jamaica Virtual Machine (JamaicaVM) is an implementation of the "Java Virtual Machine Specification", and is a runtime system for executing Java applications. This document describes how the SIMOTION-integrated JamaicaVM is parameterized, and how a Java user program is commissioned. It also contains essential information on how to use the SIMOTION API, which contains classes for data access and logging. More detailed information about the SIMOTION API exists in HTML format. The SIMOTION-integrated JamaicaVM will only be started automatically if the configuration file VMCONFIG.INI is on the target system (see also VMCONFIG.INI (Page 47) and Installation (Page 13)). The Java main program ("InvocationManager"), which is also contained in the SIMOTION API, is executed by default. The InvocationManager reads the settings from the relevant configuration file and then starts the Java user programs (see VMCONFIG.INI (Page 47)). The InvocationManager can also open a TCP socket interface, which can be used to load and execute user programs interactively (see Interactive InvocationManager interface (Page 54)). Program and system variables of the target system, for example, can be accessed in the user programs. Network support (DatagramSocket, ServerSocket, Socket, ) and file functions are also available. 10 Programming Manual, 04/2014

11 Introduction 2.3 SIMOTION IT Servlets 2.3 SIMOTION IT Servlets SIMOTION IT Servlets are the implementation of a servlet container. Servlets are programs written in Java, which extend the capabilities of servers that communicate via a request/response protocol. Theoretically, they are not bound to a server protocol (HTTP), but they are usually used only in conjunction with HTTP/web servers. The Web container provides the runtime environment for Web applications with its servlets, and it can run on a different machine to the Web server (load distribution, safety/redundancy). In a SIMOTION context, servlets run in SIMOTION IT Virtual Machine (implementation of a Java runtime environment) and are, therefore, afforded the option of using the SIMOTION API (giving access to SIMOTION RT, NVRAM, and logging objects). The following are described in the relevant chapters Implemented scope of functions (Page 60) Parameterization of the servlet container (Page 61) Start-up of a servlet using an example (Page 66). Figure 2-1 Servlet command sequence Programming Manual, 04/

12

13 Software installation SIMOTION IT Virtual Machine The JamaicaVM is only started if configuration file VMCONFIG.INI is available on the target system. A configuration file that contains the directory settings specified in the recommendations referred to above, and which can be used to activate the JamaicaVM, is included in the SIMOTION IT Virtual Machine scope of delivery. To make special settings in the configuration file, see also: JamaicaVM configuration (VMCONFIG.INI). (Page 47) Configuration file VMCONFIG.INI and Java library SIMOTION.JAR contain the InvocationManager and the API for data access and logging. These must be stored on the target system. The default setting dictates that the Java library is expected to be in the root directory of drive B: However, the root directory can also be set differently if required (see BOOTCLASSPATH (Page 47)). User programs must be zipped into a Java library (JAR or ZIP file) and stored in the current working directory of the target system. On the target system, the default current working directory is the root directory of drive B:, but this can be changed if required (see CURRENTDIR (Page 47)). To start a user program automatically, all you need to do is enter the relevant information in configuration file JINVOKE.XML. This configuration file must also be stored in the current working directory of the target system. Programming Manual, 04/

14 Software installation 3.2 SIMOTION IT Servlets 3.2 SIMOTION IT Servlets Installation and configuration of SIMOTION IT Virtual Machine is a requirement for SIMOTION servlets. To operate SIMOTION servlets, Java libraries svltapi.jar and svltimpl.jar must be stored on the target system. In the case of an empty CF card, these Java libraries must be stored in the following directory as of SIMOTION V4.1 SP4 /SIEMENS/SIMOTION The configuration files supplied assume that the SIMOTION Java system libraries are located in this directory. meaning that Java library svltapi.jar, which contains the standard servlet API, needs to be incorporated into the JamaicaVM path. The most straightforward way of doing this is to expand the setting for the BOOTCLASSPATH accordingly in VMCONFIG.INI: BOOTCLASSPATH= b:/siemens/simotion/simotion.jar;b:/siemens/simotion/svltapi.jar Note In SIMOTION IT Virtual Machine, the semicolon must always be specified as a CLASSPATH separator. To start the servlet container automatically, you need to insert the following line in JINVOKE.XML: <AUTOSTART LIBRARY="B:/SIEMENS/SIMOTION/SVLTIMPL.JAR" CLASSNAME="com.siemens.ad.SIMOTION.servlets.ServletContainer"/> User servlets must be zipped into a Java library (JAR or ZIP file) and stored in the current working directory of the target system. To load a user servlet, all you need to do is enter the relevant information in configuration file JSERVER.XML. This configuration file must also be stored in the current working directory of the target system. Note The software/libraries are available on the U&A DVD at \VOL2\AddOn\4_Accessories\SIMOTION_IT\5_SIMOTION_VM 14 Programming Manual, 04/2014

15 Scope of delivery The following files are integral parts of SIMOTION IT Virtual Machine: File name SIMOTION.JAR SIMOTION_DOC.ZIP SIMOTION_DEMO.ZIP JINVOKE.XML VMCONFIG.INI Jam1.st nanoxml.jar simotion_systemclasses.jar Description Java library containing the SIMOTION API and the default main program (InvocationManager). Online SIMOTION API documentation (HTML format). Java source code for sample programs and tools. Sample AUTOSTART configuration file JamaicaVM configuration file Sample ST program that defines and exports ST program variables. Java library that is required to start the InvocationManager program on a development computer. Java library that can be used as a reference for compilation on a development computer Supported Java packages In principle, the following packages from JDK 6 are supported by the JamaicaVM integrated in SIMOTION. java.io java.lang java.lang.reflect java.math java.net java.text java.util java.util.jar java.util.zip Additional Java libraries can be integrated into the user code by importing. Programming Manual, 04/

16 4.1.3 Default directories SIMOTION V4.1. SP4 includes some important new features in terms of both the directories recommended for SIMOTION IT Virtual Machine and the Java programs based on these. In particular, specific default directories for Java program files and Java data files are recommended so that the new CPU update feature can be used for SIMOTION IT Virtual Machine as well. All of the configuration files and sample programs supplied with SIMOTION V4.1. SP4 and higher are compatible with these new features. The recommended default directories are specified as follows: Default directory for Java program files and SIMOTION IT Virtual Machine configuration file JINVOKE.XML: /USER/SIMOTION/HMI/JAVA/PROG/ Default directory for Java data files: /USER/SIMOTION/HMI/JAVA/FSROOT/ For reasons of compatibility, the default values for the relevant settings have not been changed, meaning that you can continue to use existing configurations/installations. However, these recommended default directories are used for the relevant settings in the configuration files supplied. In particular, the /USER/SIMOTION/HMI/JAVA/PROG/ directory is set as a value for CURRENTDIR in the VMCONFIG.INI file supplied; CURRENTDIR denotes the current working directory and is, therefore, the default directory for Java program files, for example SIMOTION.JAR As of SIMOTION V4.1 SP4, the Java library SIMOTION.JAR must be stored in the following directory: /SIEMENS/SIMOTION The configuration files supplied assume that the SIMOTION Java system libraries are located in this directory. Since old SIMOTION Java system libraries can, in principle, be used in newer versions of SIMOTION (without the additional features of these newer versions, of course), it is also possible to continue using existing configurations/installations without making any changes to them. However, in such cases it is strongly recommended that you adapt the configuration of SIMOTION IT Virtual Machine too, so that the /SIEMENS/SIMOTION directory is used for these Java libraries (see BOOTCLASSPATH (Page 47)). Only in environments that are adapted in this way is it possible to automatically use the SIMOTION Java libraries that are compatible with the relevant firmware version during the course of a CPU update. 16 Programming Manual, 04/2014

17 4.1.5 Restrictions and special features Overview Limited resources (memory) and special implementations (file system, network) result in some restrictions and special features being present on the target system. These are described in the section that follows Number of threads The required number of Java user threads can be set (see SIMOTIONVM_NUMUSERTHREADS (Page 47)). If user programs request more threads than are actually available, an error message is written to the output file (see Output file JCONSOLE.TXT (Page 52)) Network functions No name service is available on the target system. For this reason, only the "raw" IP addresses can be used and not symbolic host names. Examples: instead of r1014.erlf.siemens.de. Especially also instead of localhost. The get-/setsotimeout functions, for the socket functions' time watchdog, are not implemented. Consequently, it is not possible to apply a timeout to the process of receiving data via a socket connection, for example File system The file system on the target system has the following features: All file names with the exception of the target file when renaming files must contain a drive letter (usually A: or B:). A slash (/) is used as a file separator. No distinction is made between upper- and lower-case letters. However, to write independent user programs from the platform, the file names must not be specially initialized for the target system (e.g. B:/DEMO/MYFILE.TXT). Instead, a file name should be created dynamically (e.g. from the current working directory, the separator to be used, and the actual file name). It is possible, for example, to test programs on a development computer this way. Example: // Retrieve the current working directory String currdir = System.getProperty("user.home"); // Compile the file name File f; Programming Manual, 04/

18 f = new file(currdir, "DEMO" + File.separator + "MYFILE.TXT"); The get-/setlastmodified functions, for handling file time stamps, are not implemented Synchronization with the PLC The JamaicaVM continues running even when the PLC is in the STOP state. It is possible to synchronize with the control section by accessing the current operating state of the PLC. However, no special notifications are given if the operating state changes Effects on the target system and user programs It goes without saying that using the JamaicaVM will have consequences for the entire system. Depending on the application case, approx. 3 MB of RAM are required to operate the JamaicaVM. This may make it impossible to load any larger user programs. As of SIMOTION V4.1 SP1, the memory required for the JamaicaVM is no longer provided by the USER memory, which means that operating the JamaicaVM no longer creates a drain on the memory resources available for user programs. The individual Java threads are tied to their corresponding SIMOTION tasks on a round-robin level. This means that any other SIMOTION tasks on this level will have correspondingly less computing time Connecting to SIMOTION SCOUT The JamaicaVM is not connected to SIMOTION SCOUT. SIMOTION SCOUT merely indicates a missing license or a serious error when the JamaicaVM starts up by means of a corresponding entry in the diagnostics buffer Debugging Java programs With SIMOTION V4.2 and higher, remote debugging of Java programs is possible on the target system. A network connection is always used for communication between the debugger and JamaicaVM. The target system is configured as standard as the debugging server. For this purpose, the JamaicaVM must be made to open a remote debugging port by means of parameterization. To connect with a debugger, a network connection to the target system is thus necessary. In addition, the debugger must be activated by means of the relevant specifications in VMCONFIG.INI. Eclipse or also jdb (the Java debugger of Sun Microsystems Inc.) can be used, for example, as the debugger frontend. Example of connecting with the jdb, specifying the IP address and port number: jdb -connect com.sun.jdi.socketattach:hostname= ,port= Programming Manual, 04/2014

19 For the setting of breakpoints to function correctly, it is extremely important that the Java application loaded in the target system and the Java source files used match precisely. The Java source files are used for determining breakpoints. If, for example, a Java source file that has been changed in relation to the Java application loaded in the target system is used by mistake, it can happen that the debugger simply does not stop at the breakpoint. This behavior arises because the relevant line number in the Java source file within the loaded Java application does not describe an executable program line. However, the SIMOTION API can be operated in simulation mode for the software development phase. In this way, the application can be tested and debugged on the development computer as an initial step (basic program execution). See DATA_ACCESS element (Page 46) Debugging with Eclipse Figure 4-1 Example of remote debugging settings in Eclipse See also VMCONFIG.INI (Page 47) Programming Manual, 04/

20 4.1.6 SIMOTION API Overview The SIMOTION API contains Java classes. These allow you to: Access runtime system variables, including the option of marshalling (variable values can be set on the basis of byte arrays and written to byte arrays) Call system functions of a technology object (TO) Access the parameters, parameter description, and error buffer of a drive Output logging information Variable access Overview Relevant Java package: com.siemens.ad.simotion.da The "object server" (RTObjectServer), acting as the central class, and classes for the typesafe representation of variables are available for the purpose of accessing data on the runtime system. There is a corresponding Java class for each ST standard data type (RTVariableBOOL, etc.). The variable provider of the runtime system supports the conversion of elementary data types to strings and vice versa. This means, all variables of the runtime system can also be accessed using a "string" variable. Table 4-1 Mapping elementary data types to variable classes ST standard data type BOOL SINT USINT, BYTE INT UINT, WORD DINT UDINT, DWORD REAL LREAL TIME DATE TIME_OF_DAY (abbreviation: TOD) DATE_AND_TIME (abbreviation: DT) STRING Any ST standard data type Java variable class RTVariableBOOL RTVariableSINT RTVariableUSINT RTVariableINT RTVariableUINT RTVariableDINT RTVariableUDINT RTVariableREAL RTVariableLREAL RTVariableSTRING RTVariableSTRING RTVariableSTRING RTVariableSTRING RTVariableSTRING RTVariableANY 20 Programming Manual, 04/2014

21 Regardless of this, any Java RTVariable (except for RTVariableANY) can provide its value in Java string format, or set it according to a specified string. RTVariableANY is a special case. This type of variable can be used to read the native data type and content of a runtime system variable (but only in the form of "raw bytes"). However, the runtime system variable must be of one of the elementary data types listed in the table above. After an RTVariableANY variable has been successfully read, a corresponding typesafe variable can be created using the object server. The object server has the following tasks: Creating variables Reading/writing variables or variable groups Deleting variables Browsing variables Reading variable properties The variables have the following tasks: Storing the variable value Type-safe reading/setting of the variable value Converting the variable value from/to string format Converting the variable value from/to byte array format (marshaling) Accessing the configuration data of a TO Accessing the configuration data of a TO enables you to configure an axis, or even to determine the logical base address of the drive assigned to the axis. Please note that there are several types of configuration data: Active configuration (current value) Configuration that may have changed but is not yet active (next value) It is possible to access both the currently active configuration and the configuration that is not yet active. In SIMOTION SCOUT, these data sets are referred to as "current value" and "next value" respectively. The specified variable name is used to determine which data set is to be accessed (see also Variable names (Page 22)). The parameters that are available depend on the TO type and, in the case of an axis, for example, on the type of axis. In addition to this, specific parameter settings demonstrate interdependencies (these are implemented in the SCOUT by integrating the test routines created during generation). There is no special support for access via Java in this case. Please also note the various options for changing configuration data: Download (can no longer be changed) Restart (the TO must be restarted to make the change effective) Immediate (the change is effective immediately). Programming Manual, 04/

22 Reading the variable properties allows you to determine whether a configuration variable can be changed, and whether it will be necessary to restart the TO following a change (see also Reading variable properties (Page 24)). Variable names No distinction is made between upper- and lower-case letters when it comes to variable names. They consist of a prefix and the name of the variable itself. For device system variables, the prefix is "var/". For variables from a source (ST/MCC/LAD/ FBD), the prefix is "unit/". Only the variables declared in the interface are available. When accessing system or configuration variables of a TO, the following rules apply: The prefix for TO system variables is: to/<toname>. The prefix for TO configuration variables is: cfg/<to-name>. When accessing the current configuration variables, activeconfigdata must also be specified after the TO name. For accessing the configuration to be adopted, which is designated in SIMOTION SCOUT as the Next value, setconfigdata must be specified after the TO name. Table 4-2 Accessible variables (variable name structure and example): Variable type Variable name structure Example Device system variables var/ var/userdata.user1 TO system variables to/<toname>.<variable> to/axis_1.basicmotion.position TO configuration variables cfg/<toname>.activeconfigdata.<variable> cfg/ axis_1.activeconfigdata.modulo.state TO configuration variables cfg/<toname>.setconfigdata.<variable> cfg/axis_1.setconfigdata.modulo.state Global device variables glob/ <Variable> Glob/myGlobalVar1 IO variables io/_direct.<variable> io/_image.<variable> io/_quality.<variable> io/_direct.myout1 io/_image.myout1 io/_quality.myout1 Program interface variables unit/<unitname>.<variable> unit/awp01.ug_stringvar1 Access to I/O variables has been possible since Version V4.2. Access to the diagnostics buffer is currently not possible. Access to SIMOTION variables // Create the object server RTObjectServer myserver = RTObjectServer.createRTObjectServer(); RTVariableUDINT myvar = zero; // Create an RTVariable to access a SIMOTION variable myvar = myserver.creatertvariableudint( "unit/delay.ug_udruntimedelay" ); 22 Programming Manual, 04/2014

23 // Read the variables (the SIMOTION variable value is retrieved in the // RTVariable). myserver.read( myvar ); // Read the variable value long myvalue = myvar.getvalue(); // Convert to string format // Any RTVariable can supply its value in string format String: myvalueasstring = myvar.getasstring(); // Marshalling Byte [] mybuffer = new byte[20]; int myindex = 2; boolean basbigendian = true; // Any RTVariable can write its value to a byte array //(beginning with the index specified); option of // Big or Little Endian format myvar.getvalue( mybuffer, myindex, basbigendian ); // Delete the RTVariable // Important for re-enabling the // management information created within the variable providers. myserver.delete( myvar ); It is also possible to access a group of RTVariables simultaneously: RTVariable [] myvars = new RTVariable[2]; myvars[0] = myserver.creatertvariableudint( "unit/delay.ug_udruntimedelay" ); myvars[1] = myserver.creatertvariablereal( "unit/delay.ug_rvalue" ); myserver.read( myvars ); Example: Using RTVariableANY // Create the object server RTObjectServer myserver = RTObjectServer.createRTObjectServer(); RTVariableANY v = zero; String mystringvalue = ""; try // Use RTVariableANY v = myserver.creatertvariableany("to/axis_1.error" ); Programming Manual, 04/

24 // Read the variables (reads type) myserver.read( v ); // Information about the data type read short vdatatype = v.getdatatype(); // Use the information read to create a // typesafe variable RTVariable v2 = myserver.creatertvariable( v ); // Read the variables (reads value) myserver.read( v2 ); // Following this, a value can be assigned to the variables // in string form. v2.setfromstring(mystringvalue); } catch( DataAccessException e ) } Browsing variables The object server offers the option of browsing variables. Browsing means that all the variable names will be listed starting from a particular level (as specified by a search pattern). Browsing is particularly worthwhile in applications where it is necessary to determine dynamically which technology objects are present in the runtime environment, so that these can subsequently be accessed (e.g. for the purpose of reading out the error variable of each technology object). Example: Browsing variables // Use the RTObjectServer to list all // technology objects String [] vtos = mserver.listvariables( "to/*" ); Reading variable properties The readproperties function is available for the purpose of reading variable properties. Reading variable properties is particularly worthwhile in generic applications. It enables you to determine during runtime whether a variable may only contain special values of an enumeration, for example. For this kind of enumeration variable, a list containing all the permitted values (the enumeration itself) is also provided in the variable properties. This can then be used, for example, to construct a drop-down list box containing these values. In the case of configuration variables, the "effectiveness" of a value change is also indicated in the variable properties. In other words, a program can establish whether a value can ever be changed during runtime, and whether it will be necessary to restart the technology object following a value change. 24 Programming Manual, 04/2014

25 The readproperties function delivers the variable properties in an object within the RTProperties class. The RTProperties class has the following tasks: Defining the names for the individual properties Currently, the following property names have been defined in RTProperties: DATA_TYPE Data type VALUE Current value ACCESS_RIGHTS Access rights ENUMERATION_TYPE Enumeration type ENUMERATION_INFO The enumeration itself (if enumeration type) EFFECTIVENESS Effectiveness Not all properties are available for all variables. For instance, ST program variables do not have the EFFECTIVENESS property. Please also note that enumeration variables of an ST program are mapped internally as straightforward DINT variables, meaning that the list of permitted values is not available for these ST program enumeration variables. The variable properties also contain the current value for the variable at hand. However, particularly where cyclic access to the variable value is concerned, a corresponding RTVariable should be used for reasons of performance. Example: Reading variable properties // Use the RTObjectServer to read the properties of // the "var/tracestate[0].fctgenstate" variable RTProperties myproperties = mserver.readproperties("var/tracestate[0].fctgenstate" ); // Retrieve the enumeration type String senum = myproperties.getproperty( RTProperties.ENUMERATION_TYPE ); // Establish whether the variable may only contain values // of an enumeration if( "enumerated".equals( senum ) ) // Continue by, for example, retrieving the enumeration itself, // i.e. ENUMERATION_INFO... } Programming Manual, 04/

26 Accessing drive data Relevant Java package: com.siemens.ad.simotion.sys The RTDrive class is available for accessing the drive data of a runtime system. Each drive is identified by its logical base address, which must be specified when creating an RTDrive object. The RTDrive class has the following tasks: Reading/writing drive parameters Reading the description of drive parameters Reading the error memory of a drive The RTDriveParameter class is used to access the drive parameters themselves. This class stores information on which parameter is to be accessed (parameter number; parameter index for array parameter where applicable), and transports the actual parameter values. A Java double is always used for setting/reading the value within an RTDriveParameter object, which makes it easy to create generic applications (regardless of the actual data type of a parameter, its value can be easily read and displayed, e.g. for diagnostic purposes). If an application requires type-safe values (e.g. for calculations), these values can easily be converted to the right data type: byte vvalue = (byte)param.getvalue(); The RTDriveParameter class has the following tasks: Storing the information on the parameter that is to be accessed Storing the parameter value Storing the data type of the parameter Reading/setting the parameter value The parameter data type can only be detected following the first successful access procedure (read access or write access). If the parameter has not yet been accessed, the stored data type corresponds to the value RTDatatypes.DT_UNKNOWN. The RTDriveParameterDescription class is used to determine drive parameter properties. Reading drive parameter properties allows you to determine, for example, the actual data type, or information on whether you are dealing with an array parameter or not (incl. the array length). The RTDriveParameterDescription class has the following tasks: Storing information about the drive parameter Reading parameter information If any errors occur when accessing drive parameters, the special exception DriveAccessFailedException will be triggered. The DriveAccessFailedException class has the following tasks: 26 Programming Manual, 04/2014

27 Storing the parameter numbers Storing the error code of the access function Storing the parameter-specific error code This information can be read out from the relevant exception object when a DriveAccessFailedException occurs. Refer to the SIMOTION documentation (e.g. SIMOTION SCOUT online help) for the meanings of the error codes. Example: Accessing drive data Try // Example of a logical base address of a drive, // depends on the SIMOTION project configuration. int vlogdriveaddress = 256; // Create the RTDrive object RTDrive vdrive = new RTDrive( vlogdriveaddress ); // Example of a parameter number; describes the: // "Drive state" parameter of a SINAMICS G110 long vparameternumber = 2; // Create the parameter RTDriveParameter vparameter = new RTDriveParameter( vparameternumber ); // Read the parameter vdrive.read( vparameter ); // Check the "Drive ready" state of the drive if( (int)vparameter.getvalue() == 1 )... } } catch( DriveAccessFailedException e ) // Access to parameter failed... } catch( DataAccessException e ) // Another error, // e.g. BadArgumentException } Programming Manual, 04/

28 Accessing target system functions Overview Relevant Java package: com.siemens.ad.simotion.sys The RTDevice class is available for accessing target system functions. The RTDevice class has the following tasks: Reading/setting the current operating mode Copying actual data to RAM Copying RAM to ROM Unzipping a SIMOTION archive file (e.g. project archive) Restarting the target system Reading version information When target system functions are called, in addition to purely technical causes of errors (such as a "System function failed" call), other causes of errors such as "Function cannot be executed in current state" are possible. So that errors occurring as a result of purely technical problems can be distinguished from others, special exceptions of type DeviceFunctionFailedException are triggered in these cases. The DeviceFunctionFailedException class does not have any other tasks, nor does it transport any other special information apart from, of course, the error message, which is as detailed as possible and is included in all exceptions. The majority of situations causing errors can be determined. An example is when there is not enough space on the memory medium for copying from RAM to ROM: Device function failed with result: DISK_FULL If it is not possible to set the operating state due to the setting of the mode switch on the target system: Device function failed with result: NOT_ALLOWED However, the exact cause of an error cannot be determined in all situations. For example, it is not possible to distinguish between a situation where copying from RAM to ROM cannot be executed because the target system is not in the STOP mode, and one where the SCOUT or an ST program has already initiated the function at the same time. In this kind of case, the DeviceFunctionFailedException would only contain general information: Device Function execution failed. Accessing the target system operating state The getoperatingstate/setoperatingstate functions are available for reading/ setting purposes. The operating state of the target system is returned as a string in this way. When writing, the operating state must also be transferred as a string. 28 Programming Manual, 04/2014

29 The operating states that are currently supported are: RUN STOPU STOP SERVICE Comment: When the current operating state is being read, values that deviate from the currently supported operating states may be provided. The reason for this is that the system adopts various interim states during the course of changing its operating state. The SERVICE target system operating state is not currently supported for writing operations. The target system's state selector switch is crucial when it comes to selecting the target system operating state. The program cannot set the operating state if the target system operating state is STOP. Refer to the SIMOTION SCOUT documentation for the exact meanings of the individual operating states. Example: Accessing the target system operating state In the following example, the current operating state is queried. If the target system is not in STOP, it will be stopped. try // Create object for accessing RTDevice vdevice = RTDevice.createRTDevice(); // Query the current operating state String: vcurrentstate = vdevice.getoperatingstate(); // If the target system is not // in the STOP operating state... if(!rtdevice.stop.equals( vcurrentstate ) ) //... Stop vdevice.setoperatingstate( RTDevice.STOP ); } // If the program gets to this point, // the target system is in the STOP state } catch( DataAccessException e ) // Access to operating state failed } Programming Manual, 04/

30 Copying actual data to RAM/from RAM to ROM The copyactualtoram/copyramtorom functions are available for the purpose of "copying actual data to RAM"/"copying from RAM to ROM". Example: Copying actual data to RAM/from RAM to ROM In the example below, the actual data is copied to RAM first, and then from RAM to ROM. try // Create object for accessing RTDevice vdevice = RTDevice.createRTDevice(); // Copy actual data... vdevice.copyactualtoram(); // Copy from RAM to ROM... vdevice.copyramtorom(); } catch( DeviceFunctionFailedException e ) // Function could not be executed, // e.g. Device function failed with result: DISK_FULL } catch( DataAccessException e ) // Another error has occurred } Unzipping a SIMOTION archive file (e.g. project archive) The unpackarchive function is available for unzipping a SIMOTION archive file. This system function can be used to unzip a SIMOTION archive file, such as a user project that has been properly stored using SIMOTION SCOUT. It must be noted that the target system must be in the STOP operating state to allow unzipping of the archive file. Following successful unzipping, both the temporary work directory and the archive file are deleted by the system function. The modified data does not become active until the target system is restarted. Restarting the target system The restart function is available for restarting the target system. This function restarts (resets) the target system. It is necessary to restart the target system once a user project has been successfully unzipped, for example. 30 Programming Manual, 04/2014

31 Example: Unzipping a user project and restarting the target system In the example below, the user project archive file is unzipped, and the target system is then restarted so that the new user project can be activated. File myprjfile = new file( System.getProperty("user.dir"), "MYPROJ.ZIP" ); // Create work directory // This is necessary because the system function removes the // specified work directory after unzipping of the archive file File workdir = new File( System.getProperty("java.io.tmpdir"), "JVM_PRJUPD" ); if(!workdir.isdirectory() ) if(!workdir.mkdir() ) // Creation of work directory has failed return; } } try // Create object for accessing RTDevice vdevice = RTDevice.createRTDevice(); // Unzip the archive file vdevice.unpackarchive( workdir.getcanonicalpath(), myprjfile.getcanonicalpath() ); try // Caution: If successful, it will not be possible to undo this call! vdevice.restart (); } catch( OperationFailedException e ) // Restart failed... } } catch( Exception e ) // Unzipping the archive has failed; // there may not be a correct SIMOTION user project archive } Programming Manual, 04/

32 Reading version information The getfirmwareversion/getdriveversion functions are available for the purpose of reading version information. The getfirmwareversion function provides the version number of the SIMOTION firmware. The getdriveversion function provides the version number of the integrated drive. On target systems without an integrated drive, a corresponding exception will be triggered. Example: Reading version information In the example below, the version numbers of the SIMOTION firmware and the integrated drive are read. The firmware version number is read first, as the access to the integrated drive that follows may trigger an exception (on target systems without an integrated drive). String v1 = "n/a"; String v2 = "n/a"; try // Create object for accessing RTDevice vdevice = RTDevice.createRTDevice(); short [] v; v = vdevice.getfirmwareversion(); v1 = "V " + v[0] + "." + v[1]+ "." + v[2]+ "." + v[3]; v = vdevice.getdriveversion(); v2 = "V " + v[0] + "." + v[1]+ "." + v[2]+ "." + v[3]; } catch( OperationFailedException e ) // Reading of the version failed; // possibly target system without integrated drive } Additional functions The following additional functions are available: getname copyfile The getname function provides the name assigned to the target system within the SIMOTION user project. The copyfile function copies an existing file with the aid of the relevant file system function. Particularly in the case of large files, using this function may represent a much faster option than using a straightforward file copying function implemented in Java. 32 Programming Manual, 04/2014

33 Calling system functions Overview Relevant Java package: com.siemens.ad.simotion.sys The RTSystemFunctions class is available for the purpose of calling system functions of a technology object (TO). The RTSystemFunctions class has the following tasks: Creating a command ID Calling the system functions of a TO Reading the type UID of a TO Creating a command ID Most system functions expect a command ID as a parameter. The getcommandid method provides an object from the RTCommandId class as a return value. Please note that a command ID consists of two values (internally): ld_low and ld_high. If the method used to call a system function is the one that expects the input parameters to be received in the form of an object[], the two values must be transferred separately (ld_low first). The RTCommandId class has the following tasks: Storing a unique command ID Reading the two internal command ID values, so that they can be specified as parameters for calling a system function Calling the system functions of a technology object The callsystemfunction method is a general function that can be used to call a system function of a TO. The method receives the name of the TO as a parameter, the name of the system function to be called, the input parameters of the system function, and dummies for the output parameters of the system function called (incl. the number of output parameters). The current system function can always be found by specifying the function name. If a new version of SIMOTION includes any changes to the signature or semantics of a system function, this must be taken into account in the user program. Currently, it is possible to call the following system functions: _move _getstateofaxiscommand _getaxiserrornumberstate _stopemergency Programming Manual, 04/

34 _stop _enableqfaxis _resetaxis _resetaxiserror _disableaxis _disableqfaxis _continue _getaxiserrorstate _enableaxis _pos _homing _ getipconfig _ setipconfig Important note: Please note that, for the majority of system functions, the name of the TO for which the system function is to be executed must be specified again within the input parameters. The object is usually the first input parameter of a system function. Here, please note that this parameter describes another TO, which may not even be available. However, this is not a mistake. Possible consequences of this may be the execution of functions for another TO, or error situations such as Function not found" (if this parameter describes an existing TO that is not supported by the system function on account of the TO type), or even "TO not found". Two versions of the callsystemfunction method are available. Since various parameter types must be transported, and the number and sequence of the input parameters also depends on the system function that has actually been called, each input parameter is passed as either a straightforward Object[] or an ArrayList, depending on the version. The java.lang.long and java.lang.string object types are supported by both versions as input parameter types. Numerical parameters must be stored in a long object, with floating-point numbers converted accordingly (doubletolongbits method of java.lang.double). TO names should be passed as string-format parameters. The method that expects the input parameters in ArrayList format is more user-friendly; as well as this, it supports java.lang.double and RTCommandId parameters. However, due to the type monitoring that is necessary during runtime and the parameter conversions, it is considerably slower than the version that expects the input parameters in Object[] format. A command ID is required for executing system functions. This command ID must be created anew for each call, and passed in the input parameters accordingly. Refer to the SIMOTION documentation (e.g. SIMOTION SCOUT online help) for the number and sequence of input parameters in a system function. Precisely this number of input parameters must be stored in the passed parameter container (Array or ArrayList), in precisely this sequence. In other words, the container with the input parameters must not contain any additional elements. 34 Programming Manual, 04/2014

35 This method provides the call result in the form of a return value (ErrorCodes.RT_ERR_IS_OK if it was possible to execute the system function call; otherwise, one of the predefined ErrorCodes). Here, potential errors include, in particular: ErrorCodes.RT_ERR_SYSFCT_TO_NOT_FOUND: The TO could not be found. A project that contains the TO with the specified name must be loaded on the target system. ErrorCodes. RT_ERR_SYSFCT_FCT_NOT_FOUND: The function could not be found. For example, a straightforward speed-controlled axis does not support the "_pos" system function. ErrorCodes. RT_ERR_SYSFCT_MISSING_INPUT_PARAM: Too few input parameters were specified. ErrorCodes. RT_ERR_SYSFCT_CANT_WRITE_OUTPUT_PARAM: The dummy array for the output parameters of the system function is too small. The actual return value of the system function is always located in the output parameters of the system function. An Object[] must be specified as a dummy for the output parameters. The length of the array must at least equal the number of output parameters of the actual system function, so that all output parameters can be accommodated. The individual array elements do not, however, have to be initialized. Once the system function has been successfully called, an object corresponding to each output parameter is created; here, only the java.lang.long and java.lang.string object types are supported. Refer to the SIMOTION documentation (e.g. SIMOTION SCOUT online help) for the number and sequence of output parameters in a system function. Reading the type UID of a technology object Currently, the actual type of a TO (drive axis, position axis, synchronized axis, etc.) can be queried. The RTUID class has the following tasks: Storing a unique UID for the runtime system Predefining recognized type UIDs (e.g. RTUID.POS_AXIS), in order to compare them to a read type UID. The comparison method equals must be used to carry out a comparison with one of the UIDs predefined in RTUID. Example: Calling a technology object system function In the example below, the system function "resetaxiserror" is called for the TO named "Axis_1". // Create object for accessing system functions RTSystemFunctions vsystemfunctions = new RTSystemFunctions(); // The name of the TO String vname = "Axis_1"; Programming Manual, 04/

36 // ArrayList for the input parameters ArrayList vparamsin = new ArrayList(); // TO name (name of the axis) vparamsin.add( vtoname ); // errorresetmode - ALL_ERRORS vparamsin.add( new long( 10 ) ); // errornumber - n/a because ResetMode == ALL_ERRORS vparamsin.add( new long( 0 ) ); // nextcommand - IMMEDIATELY vparamsin.add( new long( 60 ) ); // commandid vparamsin.add( vsystemfunctions.getcommandid() ); // Array as dummy for the output parameter Object [] vparamsout = new object[1]; // Dummy for the number of output parameters int [] vnumparamsout = new int[1]; // Call system function short callresult = vsystemfunctions.callsystemfunction ( vname, "_resetaxiserror", vparamsin, vparamsout, vnumparamsout ); // If the system function call has been successfully executed and // the function result has been stored in the output parameter array if( callresult == ErrorCodes.RT_ERR_IS_OK && vnumparamsout[0] == 1 ) // Can the actual function result be retrieved and // evaluated. int fctresult = (int)((long)vparamsout[0]).longvalue(); if( fctresult == 0 ) // All executed without errors } else // Error code as per description for _resetaxiserror } } else 36 Programming Manual, 04/2014

37 } // System function call unsuccessful // Error code is one of the predefined // ErrorCodes Example: Querying the actual type of a TO In the example below, the actual type of the "Axis_1" TO is determined. // Create object for accessing system functions RTSystemFunctions vsystemfunctions = new RTSystemFunctions(); // The name of the TO String vname = "Axis_1"; // Read type UID RTUID vid = vsystemfunctions.gettypeuid( vname ); if( RTUID.POS_AXIS.equals( vid ) ) // Position axis recognized, // _pos system function could be used... } Using persistent data (NVRAM) Overview Relevant Java package: com.siemens.ad.simotion.da The RTNVRAMData class is available for the purpose of using persistent data. The RTNVRAMData class has the following tasks: Creating/opening areas within the NVRAM Reading/writing areas within the NVRAM Querying whether NVRAM areas are valid/setting valid areas Closing/deleting areas within the NVRAM Persistent memory areas are identified by a name. A non-existent memory area must be created and an existing memory area must be opened. The data can then be read (though, in the case of newly created memory areas, only after data has been initialized by means of writing), or written. Programming Manual, 04/

38 Where cyclic access is concerned, from a performance standpoint it is better to keep the memory area open, rather than reopening it before and closing it after each access procedure. Data exchange takes place via a byte array; a start index (within both the persistent memory area and the transferred byte array) and length can be specified. Only one instance of each persistent memory area can be opened at a time, so the latest point at which memory areas must be closed is on exiting of the user program (or when another user program needs to open the same persistent memory area). Persistent memory areas that are no longer required can also be deleted. A straightforward internal marking procedure has been implemented in order to support recognition of inconsistencies within the stored data. This stores information regarding whether the most recent write operation was completed successfully. This marking procedure applies across the entire data area. For each write operation, the data is marked as "invalid" immediately before it is actually written to the NVRAM, and is then reset to "valid immediately after the data has been written. If the most recent write operation was not completed successfully, the data area is marked as invalid. If the data has not been written in its entirety (e.g. there was a power failure during the write operation), an attempt to read the data area triggers the special exception NVRAMInvalidContentException, allowing the user program to react accordingly (e.g. by using default values). As far as handling invalid data areas is concerned, there are also methods of not only determining whether the data area is valid, but also marking it as valid. The ability to determine the validity of a data area even before it has been read serves as an alternative to troubleshooting using exceptions. Once a valid data area has been set, NVRAMInvalidContentException will not be triggered while the data is being read. The user program is responsible for interpreting the data, which is likely to be inconsistent. This is useful for user programs which implement faulttolerant archiving of data and can, therefore, reconstruct the most recently valid data. Newly created data areas are also marked as "invalid", i.e. their data must be "initialized" by means of a write operation before it can then be read. The user program is responsible for initializing the entire data area. Non-initialized parts of the data area cannot be recognized by the internal marking procedure (important for user programs which access individual parts of the data area, and do not always access the entire data area). Example: Initialization sequence within a user program try // Length and buffer for application data int vlength = 10; byte [] vdata = new byte [vlength]; // Variable, whether valid data has been read boolean binitializationdataavailable = false; RTNVRAMData vnvram = new RTNVRAMData( "MyData" ); 38 Programming Manual, 04/2014

39 try // Initial attempts to open the area vnvram.open(); try // Open, data can be read vnvram.read( vdata ); // After reading, it is ensured that // valid initialization data is available binitializationdataavailable = true; } catch( DataAccessException e ) // Reading failed // No initialization data available } } catch( DataAccessException e ) // Opening failed, create memory area vnvram.create( vlength ); } // Memory area created // Initialization data not available if( binitializationdataavailable ) // Valid initialization data available // This can be evaluated accordingly... } else // Since no initialization data is available, // default values, for example, must be used... } } catch( DataAccessException e ) // Neither opening nor creation has functioned correctly // This is a serious problem, e.g. output exception in log // in order to determine cause of error... } Programming Manual, 04/

40 Logging Overview Relevant Java package: com.siemens.ad.simotion.log The Logger is the central class of the logging API. Currently, logging outputs are possible in a file or via a socket connection (UDP). For a description of the format for logging outputs, refer to Format of logging outputs (Page 58). Example: Logging The easiest way of using the logger is as follows: static final String APP_NAME = "MyApplication"; public static void main( String [] args ) // Create the logging object Logger vlogger = Logger.getLogger( APP_NAME ); // Logging output vlogger.log( Logger.INFO, "Starting up" ); In the example above, exactly the same settings as those in configuration file JINVOKE.XML are used for logging (see LOGGING element (Page 43)). These have been stored as Java system properties by the InvocationManager. However, it is also possible to make explicit settings: // Create a logger that only outputs error messages // (i.e. FATAL and ERROR) without stack trace information vlogger = Logger.getLogger( APP_NAME, Logger.ERROR, false ); // The messages should be output to log file MYFILE.LOG, // and the file size should not exceed 16 KB. // It is IMPORTANT to specify where the logging outputs // are to be output (file or UDP) before the // logger is used for the first time. vlogger.adddestination( new FileLog( "MYFILE.LOG", 16 ) ); // Logging output vlogger.log( Logger.FATAL, "Terminating" ); 40 Programming Manual, 04/2014

41 Note Particularly in cases where several user programs are being operated simultaneously and logging outputs are output to a file, it may be helpful to assign each user program its own log file. Since the process of writing to the log file is synchronized, logging outputs from different user programs to the same log file could impair performance Creating user programs User programs are created on a development computer. A Java SDK is necessary for compiling Java user programs. We recommend "Java SE Development Kit 6". To enable the Java compiler to find the classes referenced within the SIMOTION API, the relevant Java library must be specified during compilation. For example: javac classpath simotion.jar... To ensure that the user program will not use any Java system classes that are not available within the SIMOTION Jamaica runtime environment, the Java library with system classes can also be specified as a reference during compilation. For example: javac bootclasspath simotion_systemclasses.jar classpath simotion.jar... Following compilation, all of the user program classes must be zipped into a Java library. For example: jar cvf test.jar... The Java library and user program can then be transferred to the target system and started up Configuration files AUTOSTART configuration (JINVOKE.XML) Overview The settings for user programs that are to be started automatically must be made in configuration file JINVOKE.XML. Programming Manual, 04/

42 Settings for the interactive InvocationManager interface and logging can also be made in this file. XML notation must be used for the structure of the configuration file. A simple XML parser (Nano/XML/Lite) is integrated in SIMOTION IT Virtual Machine that is perfectly adequate for editing the configuration file. Before storing the configuration file on the target system, you are advised to display it in a web browser, for instance, so that any syntax errors can be made immediately apparent (if the configuration file has not been created using a special XML editor). NanoXML, in particular, deals with error messages very economically. The individual XML configuration file elements are described below. ROOT element SIMOTION must be used as the ROOT element: <?xml version="1.0" standalone="yes"?> <SIMOTION> <!-- AUTOSTART elements, for example, are listed here --> </SIMOTION> All other elements must then be specified within the Root element. The above example contains only one comment line. AUTOSTART element An AUTOSTART element contains information about a user program that is to be started automatically. You can specify several AUTOSTART elements. Therefore, it is possible to start several user programs. The start sequence corresponds to the sequence in which the AUTOSTART elements are specified. The following attributes are evaluated: LIBRARY Name of the Java library (JAR or ZIP file) that contains the program to be started. The name specification can be either absolute or relative. If the specification is relative, i.e. only the file name is specified without the path, the file itself must be in the current working directory (see CURRENTDIR (Page 47)). CLASSNAME Name of the class containing the method to be executed. METHOD NAME Name of the method to be executed. This method must be declared as public static, and must accept a string array as a single argument. Any value can be returned for the method. 42 Programming Manual, 04/2014

43 Specification of the method name is also unnecessary. In this case, the main method is searched for. ARGUMENT element An AUTOSTART element can contain any number of ARGUMENT elements. The arguments are stored in the sequence in which they were specified in the string array transferred to the method to be executed. An ARGUMENT element only has one attribute, called VALUE. Example: AUTOSTART elements In this example, the MyClass class is first loaded from Java library USER.JAR, and its main method is then executed. The string array transferred to the main method contains the Argument1 and Argument2 strings. Following this, the Test class is loaded from Java library TEST.JAR and its main method is executed. Since no arguments are specified, the string array transferred to the main method is empty. <AUTOSTART LIBRARY="USER.JAR" CLASSNAME="MyClass"> <ARGUMENT VALUE="Argument1"/> <ARGUMENT VALUE="Argument2"/> </AUTOSTART> <AUTOSTART LIBRARY="TEST.JAR" CLASSNAME="Test"/> LOGGING element Overview The LOGGING element contains default settings for logging. These default settings take effect when user programs use the logging API without explicit settings (see Logging (Page 40)). The following attributes are evaluated: DEFAULT_DESTINATION Currently, the default settings dictate that messages are output to a file and transferred to a host via the UDP network connection. Possible specifications: FILE UDP DEFAULT_LEVEL This determines the default logging level. Programming Manual, 04/

44 Possible specifications: FATAL ERROR WARN INFO DEBUG If nothing has been specified, or a specification that does not appear in the list above has been made, the logging level is set to DEBUG. PRINT_STACKTRACE Stack trace information is generally useful for error analyses in Java programs. If PRINT_STACKTRACE is activated, when an exception is logged the relevant stack trace information will automatically be written to the log. Possible specification: true If nothing has been specified, or a specification other than "true" has been made, no stack trace will be logged. FILE element The FILE element writes the default values for the log outputs to a file, and contains the following attributes. FILENAME MAXSIZE_IN_KB Name of the log file Maximum size of the log file in kilobytes The file name specification can be either absolute or relative. If the file name specification is relative and without the path, the file is generated in the current working directory (see CURRENTDIR (Page 47)). The log file resembles a ring buffer in terms of the way entries are made, i.e. when the maximum size that has been specified is exceeded, the process loops back to the beginning of the file. The most recent log entry is always followed by the character string $$END$$, which acts as a kind of separator between old and new log entries and makes it easy to find the most recent log entry. UDP element The UDP element writes the default values for the log outputs via a UDP socket connection, and contains the following attributes: HOST PORTNUMBER IP address of the log outputs host Port number for the log outputs receiver 44 Programming Manual, 04/2014

45 Example: LOGGING element In this example, the logging level is: DEBUG, and logging outputs, including stack trace information, are output to log file LOGFILE.LOG by default; their maximum size is limited to 64 KB. The default values set for UDP logging are for the host and for the port number. <LOGGING DEFAULT_DESTINATION="FILE" DEFAULT_LEVEL="DEBUG" PRINT_STACKTRACE="true"> <FILE FILENAME="LOGFILE.LOG" MAXSIZE_IN_KB="64"/> <UDP HOST=" " PORTNUMBER="20000"/> </LOGGING> INVOCATION_MANAGER element Overview The INVOCATION_MANAGER element may contain other information for the InvocationManager, which is mainly used for setting the interactive socket interface. The following attributes are evaluated: PORTNUMBER If a port number has been specified, the InvocationManager opens a server socket under this number and waits for requests. It is then possible to load and start programs interactively via a socket connection. If no port number has been specified, the InvocationManager ends after the AUTOSTART elements have been processed. PORTRANGE PORTRANGE is useful while developing and testing user programs if the JamaicaVM (and, therefore, the InvocationManager) is restarted frequently. Many TCP/IP implementations reserve this port number for a specific time. During this time, renewed opening of the server socket is not permitted under this port number. If a port range has been specified, the InvocationManager attempts to use the next highest group of port numbers, until the server socket can be opened. The port number that is currently used to access the InvocationManager is always output by means of a logging output. Comment: The InvocationManager attempts to create the server socket cyclically, i.e. even if no port range is specified, the socket connection can be reestablished after the delay time has elapsed. Programming Manual, 04/

46 CONSOLE_OUTPUT Instead of the default target for logging outputs, the InvocationManager uses the screen. The screen output is useful in simulation environments, since it means that no log files need to be evaluated, for example. Possible specification: true If no specification has been made, or something other than "true" has been specified, the default target for logging outputs is used. Example: INVOCATION_MANAGER element In this example, once the AUTOSTART entries have been processed, the InvocationManager opens a server socket under port number and waits for requests. If this port number cannot be used, the InvocationManager also tries port numbers to <INVOCATION_MANAGER PORTNUMBER="10000" PORTRANGE="10"/> DATA_ACCESS element Overview The DATA_ACCESS element is optional: Only the SIMULATION attribute, via which simulation mode can be activated for the data access API, is evaluated. SIMULATION Possible specification: true Simulation mode is activated by specifying true. No accesses are made to the target hardware. Simulation mode is useful for the fundamental testing of user programs, also in advance, (e.g. on a development computer) without the need for target hardware. When reading or writing variables and drive parameters, the current content of each Java variable remains unchanged. Calling system functions returns a positive function result in each case. However, for the purpose of accessing persistent memory areas (NVRAM), simulation mode is restricted in that an attempt to open a memory area will always fail. No persistent data is simulated. If nothing has been specified, or a specification other than "true" has been made, simulation mode will be deactivated. 46 Programming Manual, 04/2014

47 JamaicaVM configuration (VMCONFIG.INI) Overview The configuration file VMCONFIG.INI is only evaluated in the target system. This file is not evaluated in tests on a development computer. Default values are permanently specified for all JamaicaVM settings, i.e. it is possible to operate the JamaicaVM with the relevant default values without the need to make any special settings. Specific default directories for Java program files and Java data files are recommended as of SIMOTION V4.1 SP4 so that the CPU update feature can be used for Java programs as well. These settings are included in the configuration files supplied and should be accepted without making any modifications to them. However, the file must be available for the JamaicaVM to start at all. If necessary, settings for the JamaicaVM itself can be made in configuration file VMCONFIG.INI. The settings take effect when the JamaicaVM is started up. Each parameter must be specified in a single line, with the following format: Parameter=Value. Blank lines are permitted. Spaces are also permitted, but not within the parameter or the value. Comment lines must begin with "#". Each of the parameters and their default values are outlined below: VMCONFIG.INI With SIMOTION V4.1 SP4 and higher, the configuration file VMCONFIG.INI is searched for primarily in the directory:. /USER/SIMOTION/HMICFG/ This means that if file VMCONFIG.INI is found in directory /USER/SIMOTION/HMICFG/, it is evaluated and the JamaicaVM is started with the relevant settings. For reasons of compatibility, VMCONFIG.INI is still evaluated even if it is located in the root directory, However, evaluation only takes place if no VMCONFIG.INI file has been found in the /USER/SIMOTION/HMICFG/ directory. This means that you can continue to use existing configurations/installations without making any changes to them. SIMOTIONVM_HEAPSIZE The size of the memory reserved for the JamaicaVM in bytes. The JamaicaVM reserves the entire memory, even when starting up. If the memory is not available, an error message is output to the output file (see Output file JCONSOLE.TXT (Page 52)). Default: Programming Manual, 04/

48 SIMOTIONVM_NUMUSERTHREADS Number of Java user threads required. The JamaicaVM creates the required number of threads as soon as it starts up. If the JamaicaVM is restarted, it will no longer be possible to change this setting. If the required number of threads cannot be created, an error message is output to the output file (see Output file JCONSOLE.TXT (Page 52)). Default: 4 Maximum number that can be set: 28 This number also contains the main Java program executed by default ("InvocationManager"). In the default setting, three Java threads are thus available for user programs. This means three user programs can be run in parallel. For special solutions, the InvocationManager can also be replaced by a user-defined program: This makes all Java user threads available for user programs. SIMOTIONVM_STACKSIZE Size of each Java thread stack. Default: Maximum number that can be set: This parameter must only be changed in special cases. Such a special case could be a memory problem, for example. Reducing the stack size could help with this problem. If the JamaicaVM is restarted, it will no longer be possible to change this setting. SIMOTIONVM_ANALYSE The JamaicaVM can be instructed to output information relating to the maximum amount of memory required during execution of the previous Java programs, once the JamaicaVM has been exited. Memory analysis mode provides a tool for estimating memory requirements. However, the information in the output file is only the result of the measurement in the most recently run program, and does not indicate the exact memory requirement of the JamaicaVM. Running programs following this can, therefore, result in a larger memory requirement due to external influences (different data, different scheduling of threads due to temporal influences, etc.). For safety reasons, approx. 20 % more memory than is actually required should be available. Information relating to the memory requirement is written to the output file (see Output file JCONSOLE.TXT (Page 52)). This parameter determines the accuracy of the memory analysis as a percentage, i.e. if 10 is specified, the maximum memory requirement specified is accurate to within 10%. Consequently, the results of the analysis may then be up to 10 % higher than the memory that is actually required. However, the analysis slows down the execution of Java programs. If the value is zero, no analysis is carried out. Default: 0 48 Programming Manual, 04/2014

49 HOME Mapped onto the "user.home" Java system property. Default: B:/USER/SIMOTION/HMI/JAVA/FSROOT/ CURRENTDIR Mapped onto the "user.dir" Java system property. "user.dir" is the current working directory for all Java programs. In particular, both the configuration file for the InvocationManager and the Java libraries containing the user programs to be started automatically must be in this directory. Default: B:/USER/SIMOTION/HMI/JAVA/PROG/ TEMPDIR Mapped onto the "java.io.tmpdir" Java system property. Default: A:/ BOOTCLASSPATH Bootclasspath for the JamaicaVM. The JamaicaVM has the actual system classes "on-board". However, the Java library containing the InvocationManager and the API for data access and logging must be specified. When specifying several libraries, the libraries must be separated by semicolons. The file name and the path must be specified. Default: B:/SIEMENS/SIMOTION/SIMOTION.JAR CLASSPATH Additionally required Java libraries can be specified here using the CLASSPATH parameter. If several libraries are specified, they must be separated using dash-points. In the case of CLASSPATH, the file name and the path must be specified. Default: No default value MAINCLASSNAME Name of the Java program that is executed when the JamaicaVM is started up. The default SIMOTION Java start class (i.e. the InvocationManager) executes the user programs in accordance with the settings specified in JINVOKE.XML. For this reason, if required the InvocationManager can be abandoned and a user program executed immediately instead. Arguments cannot be specified. Default: com.siemens.ad.simotion.invocation.invocationmanager Programming Manual, 04/

50 DEBUGGER Setting options for the debugger Several parameters are possible for setting the debugger. These parameters must be formulated in a line, like individual assignments (param=value) in each case. If several parameters are specified, they must each be separated by a comma. The possible specifications are address, suspend and server, followed by the detailed description in each case. address If debugger mode is activated, the address used by the debugger must be specified. The target system is operated as standard as the debugging server. The address then only describes the relevant port number. suspend This parameter is optional. The parameter determines whether or not the JamaicaVM waits for a debugger to connect with it before running the Java applications. The possible values for the parameter are 'y' or 'n'. The default value is 'y'. This means, if debugger mode is activated, the JamaicaVM waits as standard until a debugger has connected to it before running the applications. Different debugger frontends can handle connection buildup to the JamaicaVM differently. For example, when using Eclipse at the start of the debugging session after connection buildup, any set breakpoints and the command for running the Java application are sent simultaneously. In this case, it is necessary, for example, to set desired breakpoints before starting the debugging session so that they take effect immediately when the debugging session is started. server This parameter is optional and determines whether or not the target system is to be operated as the debugging server. The possible values for the parameter are 'y' or 'n'. The default value is 'y'. The target system is then operated as the debugging server. If debugger mode is active, the JamaicaVM opens a remote debugging server port. By specifying 'n', the target system is operated as the debugging client. The JamaicaVM attempts to establish the network connection to a debugging server. The address specification must additionally include the TCP/IP address of the debugging server. The format is then: <TCP/IP address>:<port number>. Examples: DEBUGGER=suspend=n,address=8000 The debugger is activated and opens the remote debugging port with the port number When the JamaicaVM is started up, it does not wait to run the Java applications. DEBUGGER=suspend=y,server=n,address= :8000 The debugger is activated and attempts to establish the network connection to the specified address. When the JamaicaVM is started up, it waits before running the Java applications. 50 Programming Manual, 04/2014

51 If the specification is missing, debugger mode is not activated. Default: No default value (debugger not activated) Example Example Setting the memory size for the JamaicaVM and the current working directory for all Java programs. SIMOTIONVM_HEAPSIZE= CURRENTDIR=B:/JAVA Note To determine the memory size required by the JamaicaVM, see also setting option SIMOTIONVM_ANALYSE (Page 47) Transferring user programs to the target system Transfer via FTP is an extremely user-friendly option for transferring the user program from the development computer to the target system in the form of a Java library (JAR or ZIP file). (An FTP server is normally active on the target system). All you need to do is ensure that "binary mode" is always set, so that the file will be transferred securely. Otherwise, the file could become changed during transmission. This will mean that classes within the Java library cannot be found Diagnostics buffer entry A diagnostics buffer entry is created for errors that prevent the JamaicaVM from starting up. The diagnostics buffer entry is only generated in the target system. The diagnostics buffer entry is not generated in tests on a development computer. The diagnostics buffer entry contains a note if a problem arises when starting the JamaicaVM. In addition, the diagnostics buffer entry contains a simple error number for roughly determining the cause of the error. Table 4-3 Possible error numbers Error number Error cause 1 The JCONSOLE.TXT output file could not be initialized. 2 The VMCONFIG.INI configuration file contains an invalid setting. 3 Error while starting the JamaicaVM (memory could not be reserved, insufficient memory for starting up, start class not found, etc.). If error number 1 appears, the file system must be checked. Programming Manual, 04/

52 If error numbers 2 and 3 appear, the exact description of the error cause can be found in the JCONSOLE.TXT output file. The error can subsequently be eliminated by adjusting the configuration of the JamaicaVM (see JamaicaVM configuration (VMCONFIG.INI) (Page 47)) Output file JCONSOLE.TXT The output file JCONSOLE.TXT is only generated in the target system. This file is not generated in tests on a development computer. All internal outputs of the JamaicaVM (such as information on the start settings, error messages, information after it has been exited, etc.) are written to a file. This output file is called JCONSOLE.TXT. It is recreated each time the entire system is started up, and always in directory /USER/SIMOTION/HMI/SYSLOG/ of drive B:. The output resembles a ring buffer. This means, if the maximum size of 128 KB is exceeded, a start is made again at the beginning of the file. The most recent entry is always followed by the character string $$END$$ to make it easy to find the entry. The character string serves as a separator between the old and new entries. A typical example of the content of this output file: jvmcreate jamaica_main_task_entry: coming up jamaica_main_task_entry: processing jvm configuration SIMOTIONVM_HEAPSIZE = SIMOTIONVM_NUMUSERTHREADS = 4 SIMOTIONVM_STACKSIZE = SIMOTIONVM_ANALYSE = 0 HOME = B:/USER/SIMOTION/HMI/JAVA/FSROOT/ CURRENTDIR = B:/USER/SIMOTION/HMI/JAVA/PROG/ TEMPDIR = A:/ BOOTCLASSPATH = B:/SIEMENS/SIMOTION/SIMOTION.JAR; CLASSPATH = MAINCLASSNAME = com.siemens.ad.simotion.invocation.invocationmanager jamaica_main_task_entry: waiting for prepared worker tasks jamaica_main_task_entry: going to startup JamaicaVM: jamaica -Xbootclasspath:B:/SIEMENS/SIMOTION/SIMOTION.JAR; com.siemens.ad.simotion.invocation.invocationmanager InvocationManager enters main... Current working directory is: B:/ OK - starting user program OK - starting user program $$END$$ The example shows the following: 52 Programming Manual, 04/2014

53 The outputs for the power-up phase of SIMOTION Java The corresponding JamaicaVM parameters, the actual start of the JamaicaVM and the InvocationManager Including the start of two user programs. More detailed InvocationManager outputs, e.g. which user programs have been started up, are output via logging (in accordance with the settings made in LOGGING element (Page 43)). The output file can be transferred for viewing from the target system to the development computer using FTP (an FTP server is normally active on the target system). Information on the JamaicaVM memory requirement If the JamaicaVM is operated in memory analysis mode via the SIMOTIONVM_ANALYSE setting (see also SIMOTIONVM_ANALYSE (Page 47)), information on the maximum amount of memory required during a cycle is also written to the output file after the JamaicaVM has been exited. The output might look like this: ### Application used at most bytes for the Java heap (accuracy 10%). ### Non-Java heap memory used: bytes. ### ### Worst case allocation overhead: ### heapsize dynamic GC static GC ### 12954k 6 3 ### 10854k 7 4 ### 9509k 8 4 ### 8598k 9 4 ### 7929k 10 4 ### 7028k 12 5 ### 6461k 14 5 ### 6054k 16 6 ### 5762k 18 6 ### 5537k 20 7 ### 5218k 24 8 ### 5003k 28 9 ### 4851k ### 4731k ### 4639k ### 4504k ### 4411k ### 4345k ### 4188k ### 4112k ### 4035k ### 4000k ### 3965k In this case, the minimum heap size is 3965 KB. The JamaicaVM could thus also be operated with a heap size of bytes. The second column shows that in the worst-case scenario 384 allocation steps could be required to allocate an object. If, on the other hand, a 4035 KB heap were available, the worst-case scenario would involve 192 allocation steps. Programming Manual, 04/

54 The memory requirement is made up of bytes for the actual Java heap and bytes for the "non-java heap". All objects managed by the garbage collector, and also internal objects of the VM, are stored on the Java heap. The non-java heap contains the stacks and the static structures Interactive InvocationManager interface Overview The interactive InvocationManager interface allows user programs to be tested repeatedly without the need, for example, to exit the JamaicaVM each time. The relevant commands for this can be sent to the InvocationManager via a socket connection. A typical "development cycle" might progress as follows: Create Java library with user program on development computer Store Java library with user program on target system Open Java library via InvocationManager request Start user program via InvocationManager request Once the user program has been exited, the Java library can be closed by means of an InvocationManager request and then recreated, once expansions have been made on the development computer. Following this, it can be updated on the target system (e.g. via FTP transfer) and reopened, and the user program can be started up The InvocationManager protocol All parts of a request must be separated by/ended with a line feed character (0x0A). It is crucial that you do not forget the final line feed character. The InvocationManager waits until it receives the line feed character before executing the request. If the socket connection was terminated before that, the InvocationManager terminates processing of the request. A request must begin with one of the following keywords: cmd followed by the actual command and, if applicable, its parameters job followed by the class name, method name, and arguments (optional) task followed by the class name, method name, and arguments (optional) Commands openarchive This command opens the relevant Java library. The command must be followed by the name of the Java library to be opened. 54 Programming Manual, 04/2014

55 The name specification can be either absolute or relative. If the specification is relative, i.e. only the file name is specified without the path, the file itself must be in the current working directory (see CURRENTDIR (Page 47)) Only one Java library can be opened via the interactive interface at any one time. Before the specified Java library is opened, any other Java library that may currently be open is closed automatically. closearchive This command closes the Java library that is currently open. setlogginglevel The command must be followed by the name of the new logging level. For the correct name, see DEFAULT_LEVEL (Page 43). This command can be used during runtime to change the appropriate logging level for the InvocationManager logging outputs. exit This command is used to exit the InvocationManager. By exiting the InvocationManager, the JamaicaVM is also exited, but only if no other user program is active job/task requests Both types of request enable a user program to be executed. The only difference lies in how the response sent to the client is handled. The method to be called must be declared as public static, and must accept a string array as a single argument. Any value can be returned for the method. The "job" type of request is intended for user programs with a "function result" (i.e. the method called supplies a result object, preferably after a relatively short runtime). With a "job" request, the InvocationManager holds off on sending the response until the method called returns, converts the result object into a string, and sends this string to the client. If the method does not supply a result object (e.g. a method with a void return type), the default response is sent to the client OK - request finished. The "task" type of request is intended for user programs without a "function result" (these may have an extremely long runtime, or may never end). With a "task" request, the InvocationManager sends the default response to the client immediately before the relevant method is called OK - starting user program Programming Manual, 04/

56 It then terminates the socket connection. If the client receives the response, it is guaranteed that the specified class has been successfully loaded and that the specified method is also available. However, a direct function result is not available. If errors occur, the InvocationManager sends the relevant error message to the client as a response. Once the response has been sent, the InvocationManager terminates the socket connection. Note The user program is started in a separate Java thread in the case of both request types. This means that the InvocationManager itself does not block any requests while the user program is running, but can instead continue to receive further requests at the same time Sample requests Open Java library USERPROG.JAR. cmd\nopenarchive\nuserprog.jar\n Load the MyClass Java class and execute the runit method with arguments aargument1 and aargument2 ("zipped" as a string array). job\nmyclass\nrunit\naargument1\naargument2\n\n Note The two line feed characters at the end of the request must be available. An "empty argument" indicates the end of the argument list to the InvocationManager Sample programs In addition to the documentation, sample programs in Java source code format are available as basic help methods (see Scope of delivery (Page 15)). Examples of data access, file functions, marshalling, and multithreading are available. Examples of implementing tools, such as an InvocationManager client and a UDP logging host, are also available. com/siemens/ad/simotion/demo/da/nvramdemo.java Example of using persistent data (stored in the NVRAM) 56 Programming Manual, 04/2014

57 com/siemens/ad/simotion/demo/da/simple.java Example of simple data access com/siemens/ad/simotion/demo/da/stvariable.java Example of accessing variables for an ST program com/siemens/ad/simotion/demo/da/systemvariable.java Example of accessing system variables com/siemens/ad/simotion/demo/da/variablebrowser.java Example of browsing variables, including how to determine the data type of scalar variables using RTVariableANY com/siemens/ad/simotion/demo/da/variableproperties.java Example of reading variable properties. com/siemens/ad/simotion/demo/drive/driveaccess.java Example of how parameters, their description, and the error buffer of a drive can be accessed. Note For the demo program to process successfully, not only is a relevant project required on the target system, but also an addressable drive that is connected to the target system. The example requires a SINAMICS at the logic address 258. com/siemens/ad/simotion/demo/file/simple.java Example of file access; in particular, how file names can evolve independently of a platform com/siemens/ad/simotion/demo/invocation/invocationclient.java Example of how requests are sent to the InvocationManager com/siemens/ad/simotion/demo/marshalling/receiver.java Example of how the values of the Java variables can be set on the basis of the raw data received (UDP data telegram). Programming Manual, 04/

58 com/siemens/ad/simotion/demo/marshalling/udprawdatasender.java Utility program which can be used to send raw data to the marshaling receiver for testing purposes. com/siemens/ad/simotion/demo/log/udplogginghost.java Example of how the logging outputs can be received and output via UDP. com/siemens/ad/simotion/demo/sys/devicefunctions.java Example of how device functions can be called com/siemens/ad/simotion/demo/sys/systemfunctions.java Example of how system functions of a TO can be called com/siemens/ad/simotion/demo/thread/simple.java Example of a user program with several threads. The main thread creates and starts a worker thread, which sends data cyclically to a UDP receiver. At the same time, the main thread waits at a UDP socket for incoming data. When data is received, the main thread stops the worker thread and also stops itself. Note The UDPLoggingHost can be used as a UDP receiver and the UDPRawDataSender as a UDP sender (for the purpose of sending the stop request to the sample program). All you need to do is adapt the connection information (if applicable) Format of logging outputs The format of the logging outputs is as follows: <Timestamp> <LoggingLevel> <LogTopic> <LogMessage> Timestamp Time at which the logging output was created, in milliseconds from 1/1/1970, 00:00. LoggingLevel LoggingLevel that was specified with the logging output. 58 Programming Manual, 04/2014

59 LoggingTopic LoggingTopic that was specified when the logger was created. This allows logging outputs from different user programs to be distinguished from one another. LoggingMessage Message that was specified with the logging output. If an exception (Java exception) is logged, the message also contains the description of the exception, including the stack trace information (only when automatic logging of the stack trace information is activated; see PRINT_STACKTRACE (Page 43)). Example Below is an example of the program lines: static final String APP_NAME = "Simple"; public static void main( String [] args ) Logger vlogger = Logger.getLogger( APP_NAME ); vlogger.log( Logger.INFO, "Starting up" ); vlogger.log( Logger.INFO, "CurrentDirectory is: " + System.getProperty( "user.dir" ) ); and the relevant log outputs for a user program: INFO Simple Starting up INFO Simple CurrentDirectory is: B:/ Restarting the JamaicaVM When the last Java thread has ended, the JamaicaVM will stop. To enable the JamaicaVM to restart, the following address can be called up via a Web browser: Note Restart of the JamaicaVM cannot be forced by calling jvmrestart. A restart will only be successful if the JamaicaVM has shut down in the correct manner. Programming Manual, 04/

60 4.2 SIMOTION IT Servlets 4.2 SIMOTION IT Servlets Scope of functions implemented "Java Servlet Specification, V2.2" supports SIMOTION IT Servlets. However, not all of the concepts from the standard servlet API are implemented in SIMOTION IT Servlets. The following are implemented: Differentiation between type of request (GET, POST) Access to all parameters of the request (from both the URL and form data) Access to the content of the request Access to the request header Specification of the response status Specification of the response header Writing of the response content Logging Initialization parameters from configuration file for servlets Servlet context with attribute management and initialization parameters These enable the implementation of fully-fledged servlets, including structure and entry form editing features (e.g. for web browsers). The section titled Implementing the servlet API (Page 61) contains a detailed description of the functions implemented. More advanced concepts such as the following are not implemented: Support for HTTP sessions Support for RequestDispatcher Support for security functionality Access to client information (remote host, etc.) Internationalization (only the ISO character set is available) Java server pages Note Security functionality An authentication feature is implemented within the connection to the SIMOTION web server, which enables you to limit access to servlets as standard in the interests of security. However, the Java security functions defined within the servlet API (such as the role-based security concept) are not implemented. 60 Programming Manual, 04/2014

61 4.2 SIMOTION IT Servlets Scope of delivery The following files are integral parts of SIMOTION IT Servlets: File name svltapi.jar svltimpl.jar simotion_servlets_doc.zip simotion_servlets_demo.zip JSERVER.XML Description Java library containing the standard servlet API. Java library containing the implementation of the servlet container. Online documentation of the servlet API (HTML format). Java source code for sample servlet. Sample servlet configuration file Implementing the servlet API SIMOTION IT Servlets supports the "Java Servlet Specification, V2.2". For the servlet API itself, the relevant implementation of the "Apache Jakarta Project" is used. This has been developed by the Apache Software Foundation ( ( and does not provide support for Java Server Pages. Essentially, this means that unless Java Server Pages need to be supported, all of the specified interfaces and classes for the servlet API are available. Additionally, the online documentation for the servlet API provides full descriptions of all the interfaces and classes it contains. Certain interfaces, as well as certain interface methods, are not supported in the first version of SIMOTION IT Servlets, as they are not required for simple servlets. Generally speaking, methods referred to in the servlet specification as "deprecated" (meaning that they are outdated and should no longer be used) are not supported. If certain interface methods are not supported, calling them will trigger an exception of type "UnsupportedOperationException". The table below provides both a detailed list of what is included in the servlet API and a description of the scope of functions implemented in SIMOTION servlets. javax.servlet package RequestDispatcher Not implemented ServletConfig Fully implemented Programming Manual, 04/

62 4.2 SIMOTION IT Servlets javax.servlet.http package ServletContext The following methods are implemented: public int getmajorversion() public int getminorversion() public void log(string msg) public void log(string msg, Throwable throwable) public String getserverinfo() public String getinitparameter(string name) public Object getattribute(string name) public Enumeration getattributenames() public void setattribute(string name, Object object) public void removeattribute(string name) public String getcontextpath() ServletRequest The following methods are implemented: public int getcontentlength() public String getcontenttype() public ServletInputStream getinputstream() throws IOException public String getparameter(string name) public Enumeration getparameternames() public String[] getparametervalues(string name) public String getprotocol() public String getservername() ServletResponse The following methods are implemented: public ServletOutputStream getoutputstream() throws IOException public void setcontenttype(string type) public void reset() public boolean iscommitted() public void flushbuffer() throws IOException SingleThreadModel Already implemented as appropriate in servlet API GenericServlet Already implemented as appropriate in servlet API ServletInputStream Fully implemented ServletOutputStream Fully implemented ServletException Already implemented as appropriate in servlet API UnavailableException Already implemented as appropriate in servlet API 62 Programming Manual, 04/2014

63 4.2 SIMOTION IT Servlets HttpServletRequest The following methods are implemented: public Cookie[] getcookies() public long getdateheader(string name) public String getheader(string name) public Enumeration getheadernames() public int getintheader(string name) public String getmethod() public String getcontextpath() public String getpathinfo() public String getquerystring() public String getrequesturi() public String getservletpath() HttpServletResponse The following methods are implemented: public void addcookie(cookie cookie) public boolean containsheader(string name) public void senderror( int sc, String msg ) throws IOException public void senderror(int sc) throws IOException public void setdateheader(string name, long date) public void setheader(string name, String value) public void setintheader(string name, int value) public void setstatus(int sc) HttpSession Not implemented HttpSessionBindingListener Not implemented HttpSessionContext Not implemented Cookie Already implemented as appropriate in servlet API HttpServlet Already implemented as appropriate in servlet API HttpSessionBindingEvent Already implemented as appropriate in servlet API HttpUtils Already implemented as appropriate in servlet API javax.servlet.jsp package This package (along with its subpackages) is not included in SIMOTION servlets Creating user servlets User servlets are created on a development computer. Programming Manual, 04/

64 4.2 SIMOTION IT Servlets A Java SDK is necessary for compiling Java user programs. We recommend "Java SE Development Kit 6". To enable the Java compiler to find the classes referenced within the servlet API, the relevant Java library must be specified during compilation. For example: javac classpath svltapi.jar... If classes are referenced by the SIMOTION API, it is also necessary to specify the relevant Java library during compilation. For example: javac classpath svltapi.jar;simotion.jar... Comment: The separator within the CLASSPATH specification is platform-specific. If a Windows development computer is used, the separator is the semicolon, as in the above example. On a Unix development computer, a colon must be used. To ensure that the user servlet will not use any Java system classes that are not available within the SIMOTION IT Virtual Machine runtime environment, during compilation the Java library can also be specified with the system classes as a reference. E.g.: javac bootclasspath simotion_systemclasses.jar classpath svltapi.jar... Following compilation, all of the user program classes must be zipped into a Java library. For example: jar cvf testsvlt.jar... Following this, the Java library can be transferred to the target system along with the user servlet and loaded by the servlet container Configuration file (JSERVER.XML) The configuration file JSERVER.XML contains the settings for the SIMOTION IT Servlet container and the servlets to be loaded. XML notation must be used for the structure of the configuration file. A simple XML parser (Nano/XML/Lite) is integrated in SIMOTION IT Virtual Machine that is perfectly adequate for editing the configuration file. Before storing the configuration file on the target system, you are advised to display it in a web browser, for instance, so that any syntax errors can be made immediately apparent (if the configuration file has not been created using a special XML editor). NanoXML, in particular, deals with error messages very economically. The individual XML configuration file elements are described below: 64 Programming Manual, 04/2014

65 4.2 SIMOTION IT Servlets ROOT element SIMSERV must be used as the root element: <?xml version="1.0" standalone="yes"?> <SIMSERV> <! Initialization parameter of context --> <INITPARAM NAME="AParameter" VALUE="aValue"/> <!-- SERVLET elements, for example, are listed here --> </SIMSERV> All other elements must then be specified within the ROOT element. The example above contains just one initialization parameter, as described below. INITPARAM element The ROOT element can contain any number of INITPARAM elements. These initialization parameters can be queried from servlets using the Servlet Context, meaning that they are available for all servlets. The following attributes are evaluated: SERVLET element NAME Name of the initialization parameter. If this attribute is missing, the element will not be evaluated any further. VALUE Value of the initialization parameter. If this attribute is missing, the empty string is used as the value. A SERVLET element contains information about the servlet to be loaded. The name of the Java class that implements the servlet and the path (part of the URL following the ContextPath) under which the servlet is to be registered must be specified for a servlet that is to be loaded. You can specify several SERVLET elements. meaning that it is possible to load several servlets. The following attributes are evaluated: LIBRARY Name of the Java library (JAR or ZIP file) that contains the servlet. The name specification can be either absolute or relative. If the specification is relative, i.e. only the file name is specified without the path, the file itself must be in the current working directory. Specifying this is optional. If no Java library is specified, the Java class for the servlet must be located in the CLASSPATH. CLASSNAME Name of the Java class for the servlet. PATH Path under which the servlet is to be registered within the ServletContext. Programming Manual, 04/

66 4.2 SIMOTION IT Servlets NAME Name of the servlet. Providing a name is optional and serves a purely informational purpose (the getservletname() method returns the name). If no specification is made, the name of the Java class is used as the servlet name. INITPARAM element A SERVLET element can contain any number of INITPARAM elements. There initialization parameters can be queried within the servlet by means of the servlet configuration, and apply to this servlet only. In terms of structure, the INITPARAM element for servlets is identical to the one for the ServletContext (see INITPARAM element). An example of SERVLET elements In this example, two servlets are loaded. Java class MyServlet is loaded from the MYSVLT.JAR Java archive and registered under / myservlet within the ServletContext. The servlet can query the two initialization parameters. The name of the servlet matches that of the Java class. A client references the servlet via The Java class TestServlet is loaded via the system class loader and registers within the ServletContext under the path /test. In this case, the Java class TestServlet must be located in the CLASSPATH of SIMOTION IT Virtual Machine. The servlet has no initialization parameters. The name of the servlet is "A test servlet". A client references the servlet via <SERVLET LIBRARY="MYSVLT.JAR" CLASSNAME="MyServlet" PATH="/ myservlet"> <INITPARAM NAME="AParameter" VALUE="aValue"/> <INITPARAM NAME="AnotherParameter" VALUE="anotherValue"/> </SERVLET> <SERVLET CLASSNAME="TestServlet" PATH="/test" NAME="A test servlet"/ > Sample servlet and configuration A sample servlet in Java source code format is included in the scope of delivery as a basic help method. Sample configuration JSERVER.XML may be used accordingly. DemoServlet.java The following section contains an example illustrating the basic principles of how a client request is edited within a concrete servlet. /* * ============================================================== * A simple servlet to demonstrate how to build a user-servlet. * * The servlet generates some "plain-text" only. * 66 Programming Manual, 04/2014

67 4.2 SIMOTION IT Servlets * Copyright (C) 2004 Siemens AG. All rights reserved. * ============================================================== */ // Necessary servlet API import javax.servlet.servletexception; import javax.servlet.http.httpservlet; import javax.servlet.http.httpservletrequest; import javax.servlet.http.httpservletresponse; // Possible io exceptions import java.io.ioexception; import java.io.printwriter; /* * A simple servlet, which generates only a textual response. */ public class DemoServlet extends HttpServlet /* * Generate response for a GET-Request. */ public void doget( HttpServletRequest request, HttpServletResponse response ) throws ServletException, IOException // "request" could be used to query additional // information // e.g. parameters... } } // Set ContentType of the response response.setcontenttype("text/plain"); // Obtain PrintWriter for writing response PrintWriter out = response.getwriter(); // Write response out.println("hello SIMOTION Servlets!"); The sample servlet only generates simple text and does not require any parameters. A servlet that wishes to have an entry form displayed in a browser generates the form in HTML and writes it to the browser as a response to a GET request. In order to edit the entry form, this type of servlet implements editing for the POST request as well, evaluates the form parameters within this, and generates a relevant response again. JSERVER.XML The configuration file supplied shows how the sample servlet can be loaded and how a DumpServlet contained in SIMOTION IT Servlets can be activated. This is useful for the purpose of viewing the current initialization parameters in the ServletContext. <?xml version="1.0" standalone="yes"?> <SIMSERV> Programming Manual, 04/

68 4.2 SIMOTION IT Servlets <!-- Example of a SIMOTION IT Servlets configuration --> <!-- ServletContext parameters --> <INITPARAM NAME="ContextParam1" VALUE="ContextValue1"/> <INITPARAM NAME="ContextParam2" VALUE="ContextValue2"/> <!-- The previously compiled demo servlet is loaded and must be zipped into SVLTDEMO.JAR and stored on the target system. The demo servlet is registered for path /demo, and can, therefore, by accessed by the client via <host>/servlet/demo --> <SERVLET LIBRARY="SVLTDEMO.JAR" CLASSNAME="DemoServlet" PATH="/demo" NAME="Demo-Servlet"/> <!-- No LIBRARY needs to be specified for the DumpServlet included as standard. By way of a response, the DumpServlet provides information about the current request and initialization parameters for the context and servlet (if specified), and can be registered for simple checking of the context initialization parameters, for example. The dump servlet is registered for path /dump/*, for example, and can, therefore, be accessed by the client via or even --> <SERVLET CLASSNAME="com.siemens.ad.SIMOTION.servlets.DumpServlet" PATH="/dump/*" NAME="Sample DumpServlet"> <INITPARAM NAME="ServletParam1" VALUE="ServletValue1"/> <INITPARAM NAME="ServletParam2" VALUE="ServletValue2"/> </SERVLET> </SIMSERV> Restart of the servlet container To stop the ServletContainer by calling an URL on the server, the so-called AdminServlet, a system servlet, must be loaded in the configuration file jserver.xml. <SERVLET CLASSNAME="com.siemens.ad.SIMOTION.servlets.impl.AdminServlet" 68 Programming Manual, 04/2014

69 4.2 SIMOTION IT Servlets PATH="/admin/*" NAME="AdminServlet" /> The servlet is then registered on the subpath: "admin" and it knows the command (written as an http parameter): Action=StopContainer By calling the URL <host><simotion-servlet-prefix>/admin?action=stopcontainer (an HTTP- GET request is output) the servlet container can be stopped. The servlet restarts if the SIMOTION VM is restarted. This is done by calling the URL: <host><simotion-servlet-prefix>/japp/jvmrestart Programming Manual, 04/

70

71 Index C Configuration file JSERVER.XML, 64 D DemoServlet.java, 66 F Functional scope, 61 I Installation of SIMOTION IT Virtual Machine, 14 J JSERVER.XML, 67 JSERVER.XML example configuration, 66 L Limiting access, 60 R References, 3 S Scope of SIMOTION IT Servlets, 60 Scope of supply, 61 Servlet API, 61 U User servlets, 63 Programming Manual, 04/

72