java programming interface (java-api) - abb group · 1mrs751851-men sys 600 *9.1 7 microscada pro...

MicroSCADA ProSYS 600 *9.1Java Programming Interface (Java-API)

User’s Guide

MicroSCADA ProJava Programming Interface (Java-API)User’s Guide

SYS 600 *9.11MRS751851-MEN

Issued: 15.03.2002Version: C/25.02.2005

1. About this manual .....................................................................51.1. Copyrights .....................................................................................51.2. Trademarks ...................................................................................51.3. General .........................................................................................51.4. Related documents .......................................................................71.5. Document revisions .......................................................................7

2. Safety information .....................................................................92.1. Backup copies ...............................................................................92.2. Fatal errors ....................................................................................9

3. Instructions ..............................................................................113.1. General .......................................................................................113.2. Installation ...................................................................................123.3. Configuration ...............................................................................153.4. Configuring Java API for several products ..................................173.5. Using Java classes, applications and applets .............................17

3.5.1. Java classes ....................................................................173.5.2. Java applications .............................................................173.5.3. Examples .........................................................................19

4. Technical reference ................................................................274.1. Java classes ................................................................................27

4.1.1. SCIL_Connection .............................................................274.1.2. SCIL_SSL_Connection ....................................................284.1.3. SCIL_Interface .................................................................284.1.4. SCIL_Object .....................................................................314.1.5. Objects inherited from the SCIL_Object ..........................32

4.1.5.1. SCIL_BaseSystemObject ...................................324.1.5.2. SCIL_CommandProcedureObject ......................334.1.5.3. SCIL_DataObject ...............................................334.1.5.4. SCIL_EventChannelObject ................................344.1.5.5. SCIL_EventObject ..............................................344.1.5.6. SCIL_ProcessObject ..........................................344.1.5.7. SCIL_ScaleObject ..............................................354.1.5.8. SCIL_SystemObject ...........................................354.1.5.9. SCIL_TimeChannelObject .................................36

4.1.6. SCIL_FreeTypeObject .....................................................364.1.7. SCIL_Value ......................................................................394.1.8. SCIL_Message ................................................................454.1.9. EventLog ..........................................................................46

5. Example application ...............................................................49

©Copyright 2005 ABB Oy, Substation Automation Products, Vaasa, FINLAND 3

1MRS751851-MENMicroSCADA ProJava Programming Interface (Java-API)User’s Guide

SYS 600 *9.1

5.1. Using the example application .................................................... 495.1.1. First page (main.html) ...................................................... 495.1.2. General info (generalinfo.html) ........................................ 505.1.3. Configuration & diagnostics (configuration.html) ............. 52

5.1.3.1. Applications (apl.html) ....................................... 535.1.3.2. Monitors (mon.html) ........................................... 565.1.3.3. Nodes (nod.html) ............................................... 565.1.3.4. Printers (pri.html) ............................................... 575.1.3.5. Links (lin.html) .................................................... 575.1.3.6. Stations (sta.html) .............................................. 585.1.3.7. Nets (net.html) ................................................... 585.1.3.8. Memory (memory.html) ...................................... 585.1.3.9. Time (time.html) ................................................. 605.1.3.10.Queues (queuemeters.html) .............................. 615.1.3.11.Bar-chart (diagram.html) .................................... 615.1.3.12.Line-diagram (linediagram.html) ........................ 62

6. Glossary .................................................................................. 657. Index ........................................................................................ 67

4

1MRS751851-MEN SYS 600 *9.1MicroSCADA ProJava Programming Interface (Java-API)User’s Guide

1. About this manual

1.1. CopyrightsThe information in this document is subject to change without notice and should not be construed as a commitment by ABB Oy. ABB Oy assumes no responsibility for any errors that may appear in this document.

In no event shall ABB Oy be liable for direct, indirect, special, incidental or consequential damages of any nature or kind arising from the use of this document, nor shall ABB Oy be liable for incidental or consequential damages arising from use of any software or hardware described in this document.

This document and parts thereof must not be reproduced or copied without written permission from ABB Oy, and the contents thereof must not be imparted to a third party nor used for any unauthorized purpose.

The software or hardware described in this document is furnished under a license and may be used, copied, or disclosed only in accordance with the terms of such license.

Copyright © 2005 ABB Oy All rights reserved.

1.2. TrademarksRegistrations and trademarks used in this document include:

Windows: Registered trademark of Microsoft Corporation.

LonWorks: Registered trademark of Echelon Corporation Inc.

1.3. GeneralThis manual provides thorough information on Java API for MicroSCADA and need information related to it. This manual gives instructions for installation and describes how to configure Java and MicroSCADA for a client-server communication. Explanations for the abbreviations used in this manual can be found in the Glossary chapter.

Java APIJava API for MicroSCADA is kind of a client-server application. A Java applet or application communicates with the server, which in turn communicates with MicroSCADA. Java applets work inside the Web browsers on PCs and applications run on the PC itself. The server is designed to be used in both the Intranet and the Internet. When used in the Internet, some of the functionalities may have to be restricted to only certain hosts or users.

5


SYS 600 *9.1

Figure 1.3.-1 shows a diagram describing the Java API. In case of the HSB system, only the application in Hot state can be contacted. More information about the application state (AS attribute) can be found in Chapter 5 (APL Objects for Base System) of the System Objects manual.

Java_API

Fig. 1.3.-1 The applets, as well as the applications, are connected to MicroSCADA via the Java API and Java classes complementing the API.

BenefitsThe main advantage is to provide an easy-to-use programming environment for the development of the application extension programs. In this environment, dynamic data types (vectors, lists etc.) are handled in a safe way. The temporarily allocated memory in the MicroSCADA memory pool will be automatically released, if it is not needed any more. One purpose to use Java API is to get information from MicroSCADA to the office computers without opening MicroSCADA monitors.

Java API functionsThe main purpose for Java API is to provide the same functionality as in C-API, but in the Java environment. The functions in the C-API are grouped into several Java classes. The Java classes which handle the communication with MicroSCADA are located in the SCIL.jar file.

The SCIL_Interface functions can be used to read/write variables, execute SCIL commands, read MicroSCADA events etc. When the SCIL_Interface class has been created, a new SCIL_Context is also created. The context remains the same until the SCIL_Interface is destroyed. When there is more than one SCIL_Interface, each of the SCIL_Interfaces have their own SCIL context. The variables used in one SCIL_Context cannot be accessed in another context.

6


The data is transferred between Java and MicroSCADA mainly using the SCIL_Value class. The SCIL_Value encapsulates the SCIL data types. The SCIL_Message class is used when working with the MicroSCADA events. The EP messages from MicroSCADA can be used by methods in the SCIL_Interface. The user can select which events to order by using the methods in SCIL_Interface. The message can be read by using the getAepMessage function. Depending on the timeout value, the function will be blocked infinitely until the message is found or the time limit is reached.

1.4. Related documentsOther useful or related manuals are:

1.5. Document revisions

Name of the manual MRS NumberSystem Objects 1MRS751847-MENProgramming Language SCIL 1MRS751849-MENInstallation and Commissioning Manual 1MRS751853-MEN

Version Revision number Date HistoryA 8.4.4 15.03.2002 Document createdB 9.0 30.06.2004 Document updatedC 9.1 25.02.2005 New revision number

7


2. Safety information

This chapter gives information about the prevention of hazards.

2.1. Backup copiesWe suggest that you take backup copies before making any changes, especially the ones that might have side effects. Software and data need to be copied to another place, usually to a CD or a backup tape. A writable CD and DAT tape are commonly used.

Backup copies make it easier to restore the application software in case of a disk crash or any other serious failure when the stored data is lost. It is therefore recommended that backup copies are taken regularly.

There should be at least two system backup copies and two application copies. A new backup is copied over the oldest backup. This way the latest version is always available, even if the backup procedure fails.

Detailed information on how to take backup copies should be delivered to the customer with the application.

System backupUsually a system backup is taken after the application is made. A backup should be taken again when changes are made to the MicroSCADA system. For example, if the driver configuration or the network set-up is changed.

Application backupAn application backup is also taken simultaneously with the system backup, after the application is made. A backup should be taken again when changes are made to the application. For example, if pictures or databases are edited or new pictures are added.

2.2. Fatal errorsA fatal error is an error that causes a break-down or a locked situation in the MicroSCADA program execution.

HandlingIn case of a fatal error:1. Write down the possible MicroSCADA error messages.2. Shut down the MicroSCADA main program. If this cannot be done in the

MicroSCADA Control Panel, try to end the task in Windows1 Task Manager.

Shutting down the base system computers by switching off the power might damage the files.

1. Windows is a trademark of Microsoft Corporation

9


SYS 600 *9.1

3. In Windows, the data kept in the main memory at the moment of a fatal error is placed in the drwtsn32.log file. It is placed in a system folder, for example, Winnt. Analyse and copy the data in this file.

4. Restart the system.

Report the program break-down together with the possible MicroSCADA error messages and the information from drwtsn32.log file to the MicroSCADA supplier.

Status codesError messages in SCIL are called status codes. A list of status codes and short explanations can be found in the Status Codes manual.

10


3. Instructions

This chapter gives information on the software requirements for your computer. It will also inform you about the installation and configuration, and how to use the software. Some short examples will also be included.

3.1. GeneralAll of the Java classes are packaged in an archive file. Since all browsers do not support the same archive format, there are both SCIL.jar and SCIL.cab files.

The latest version of the JDK can be found (at least) at the WWW-sites of the Sun Microsystems (http://www.sun.com, http://java.sun.com). Sun also provides very useful information about the Java programming language.

Java Secure Socket Extension is used to handle sequred TCP/IP connections. The latest version of JSSE can be found at the WWW site http:/java.sun.com/products/jsse/ .

The numbering of the MicroSCADA application is dependent on the application that the AEPs have been started from. More information about the numbering can be found from Application Mapping in Chapter 5 of the System Objects manual.

IP AddressEach node or host in a TCP/IP network has a unique identifier, an IP address. The IP address is composed of four numbers which range from 0 to 255. The numbers are separated with dots:

aaa.bbb.ccc.ddd

The IP address is requested during the configuration of the LAN software, i.e., during the installation of the Windows operating system in the base system and workstation computers, and during the installation of the PC/TCP software in front-ends.

The IP addresses of the MicroSCADA base system, workstation and front-end computers must comply with the addresses of other nodes on the network. Consult your local area network administrator for valid IP addresses and other LAN configuration issues. More information on configuring MicroSCADA for LAN can also be found from the Installation and Commissioning manual.

Hardware and software requirementsMinimum memory needed on the server computer is 64 Mb, but the recommenda-tion is 128 Mb. The installation needs approximately 5 Mb hard disk space.

The following software is required for a client computer:• An operating system - Windows.• A WWW-browser with Java support. For example, IE version 4.01 (includes

service pack 1) or Netscape 4.x.

11


SYS 600 *9.1

The following software is required for a server computer:• In case of Java applets, a WWW-server. For example, Peer Web-server (NT

Workstation) or IIS (NT Server).• One of the following MicroSCADA software is required:

• MicroSCADA 8.4.3 or newer.• COM 500 3.0 or newer.• SMS 510 1.0 or newer.• CAP 501 2.0 or CAP 505 2.0 or newer.

• Java 2 Runtime Environment or Software Development Kit, version 1.3.1 or higher.

• Java Secure Socket Extension, version 1.0.2 or higher.

3.2. InstallationThis section describes the main steps of the installation of the Java API for MicroSCADA with the help of figures describing the informative dialog boxes seen during the installation. The Java API for MicroSCADA is installed into a computer which already has MicroSCADA, a WWW server and the JRE/JDK. More information of installing MicroSCADA can be found in the Installation and Commissioning Manual. If Peer Web-server is installed to the server computer after installing MicroSCADA, odbc32.dll and odbcint.dll files are replaced with older versions of the same files. If this happens, the newer files can be found in the MicroSCADA Java API installation disk and should be copied to the Windows system32 directory. Windows administrator rights are required before the installation of Java API can be started.

The main steps for installing the Java API for MicroSCADA are as follows:1. When the installation execution file is run from the installation disk, the first to

appear on the screen is the Welcome - MicroSCADA Java API Installation dialog box, shown in Figure 3.2.-1.

Welcome

Fig. 3.2.-1 The Welcome dialog box is the first to appear when the installation program is started.

2. The Welcome dialog box gives two options, OK and Cancel. If you click the OK button, the installation will continue. If you click the Cancel button instead, the

12


Install dialog box will appear on the screen, with an option for terminating the installation.

3. The installation program will check which MicroSCADA products have been installed already. The checking is done in the following order:3.1. SYS 500 8.4.33.2. COM 500 3.03.3. SMS 510 1.03.4. CAP 501 2.03.5. CAP 505 2.03.6. MicroSCADA 8.4.3

Java API is installed in context with the first found MicroSCADA product. For example, if SYS 500 has been installed on D-drive and SMS 510 on C-drive, Java API will be installed on D-drive. The installation drive and path can be changed by clicking the Change Directory… button, see Figure 3.2.-2.

4. When you have selected to continue with the installation from the Welcome dialog box, the next one to appear is the Select dialog box, shown in Figure 3.2.-2. The Select dialog box is for customising the installation. It contains four installation options:

• Java API. This module contains the application extension program and the MicroSCADA Java package (it includes the files scil_jni.dll, scil2java.exe, SCIL.jar and SCIL.cab). The default installation path is C:\MS_Interfaces\Java\.

• Java Runtime Libraries. This module contains JRE 1.3.1-02, JSSE 1.0.2 and some ODBC drivers. Files will be copied to the selected drive in MS_Interfaces\Java\Setup\Drivers\ directory.

• Java Demo. This module contains a demo application, which can be used to show some basic information about MicroSCADA. Java Demo refers to the example application introduced in the Chapter 5 of this manual. The default installation path on the selected drive is MS_Interfaces\Java\ms_java_demo\.

• Documentation for Java API. This module contains the Java API manual in PDF-format and the documentation of Java API classes in HTML-format. The default installation path on the selected drive is MS_Docs\MS_Tech\Java\.

The Select dialog box gives also information on the hard drive space required for the installation and the space available on the destination drive.

13


SYS 600 *9.1

Java_API_Inst

Fig. 3.2.-2 The Select dialog box contains options for customizing the installation.

5. At the bottom of the Select dialog box there are again two options for starting and exiting the installation. If you click the Start command button, extraction of the files from the source disk to the destination drive will be started. An installation progress indicator dialog box will also appear on the screen. You can terminate the installation by clicking Exit, or after having started the extraction of files, by clicking Cancel on the installation progress indicator dialog box. By clicking Help you will get information about the installation. Back returns to the previous dialog box.

6. After all the files have been extracted from the disk to the destination drive, a dialog box will appear on the screen with a text “Your MicroSCADA system has been successfully installed.”

The files scil_jni.dll, scil2java.exe, SCIL.jar and SCIL.cab are placed in C:\MS_Interfaces\Java\. The scil2java.exe is an application extension program and must be started from the MicroSCADA by the aep_start function. It is possible to start the scil2java from the command prompt by giving “NO_AEP” as the first

14


argument. This may be useful when testing the Java programs. When the scil2java is started from the command prompt, it is not possible to use the MicroSCADA messages.

The JRE and JSSE are included in the Java API package, but the modules need to be installed separately. The JRE installation execution file, j2re-1_3_1_02-win-i.exe and the JSSE installation file is jsse-1_0_2-gl.zip, can be found under sc\MS_INterfaces\Java\Drivers\ on the hard drive, after the Java API package has been installed. After JRE is installed JSSE archive should be unzipped and added to JRE as an extension library (see installation instructions in the JSSE package).

Java API Server needs to load JVM.DLL file from the JRE package. Before it can be started the path to this DLL must be added to the system PATH variable. The DLL location depends on the JRE/JDK version. If 1.3.x version is used, the path is <JRE_HOME>\BIN\HOTSPOT\. If 1.4.x version is used, the path is <JRE_HOME>\BIN\CLIENT\. Here <JRE_HOME> is the root folder of JRE.

3.3. ConfigurationThe configurations described in this section will be necessary to perform only if remote applets or applications are used.

Access controlThe configuration for Java API is stored in \sc\sys\active\sys_\sys_java.ini. There must be at least the following lines:[Config]Default_Access = READ_WRITE

The Default_Access can also be “READ”. If there is no configuration file at all, the default access will be “NO_ACCESS”. More information concerning the configurations can be found in the following two sections of this manual.

Java API serverThe configuration file is ”sys_java.ini” and it is located in SYS_ directory. It is a normal text file in the same format as other Windows INI-files. When the server is started it will read the configuration. The following items are configurable:Max_Connections The maximum number of simultaneous connections. This

is the total number of clients (Java applets and applications). Default value is 100.

Server_Port TCP port used by the Java API Server. The server listens this port and accepts client connections. Default value is 1501.

Default_Access The default access level if nothing else is specified by the user or the IP number. The access level can be FULL_ACCESS, NO_ACCESS, READ or READ_WRITE. Default is NO_ACCESS.

The JRE or the JDK and JSSE must be installed on the host before this Java API can be used.

15


SYS 600 *9.1

Log_Enable This key indicates whether the connections should be logged in or not. It can have values TRUE or FALSE. If this is TRUE, the logging messages will be written to the NT event log. The default value is TRUE.

SSL_Enabled If SSL encoding is required this parameter should be set to TRUE otherwise - FALSE.

Authentication_Type The type of client authentication mechanism. Possible values: NONE - client authentication is not required; INI_FILE - all user names and passwords are kept in sys_java.ini file within the [Passwords] section in the following format: user_name = password , the password is case sensitive; SCIL_FILE - client is authenticated by a SCIL program. The SCIL program file name is specified in Auth_SCIL_File_Name parameter. The name and password are passed to this program in the SCIL variables - CLIENT_NAME, CLIENT_PASSWORD. The result of authentication should be placed into SCIL variable AUTHETICATED, 0 - if the authentication failed and 1 - if the authentication successful.

Auth_SCIL_File_Name This key specifies the full file name of SCIL program. It is used only when Authentication_Type = SCIL_FILE.

Instead of the access level defined in the default access field, the host(s) may have its (their) own access level(s) defined in the following way:Number_Of_Hosts The number of host sections. If there are N hosts, there

must be corresponding sections [Host1], [Host2]…[HostN].

[Host<X>] Section for host specific information (IP number, access level etc.). The <X> is the number of the host entry.

IP_Number The IP number for the host.Access_Level The access level for this IP address. It can be one of the

access levels mentioned above in the Dafault_Access paragraph.

Clients names and passwords can be defined in the following way:[Passwords] Section for storing client names and passwords. It’s used

only when the Authentication_Type = INI_FILE.<Client name> Specifies the password for the <Client name>.

MicroSCADAThe scil2java can be started, for example, from the command procedure “apl_init” which will be executed automatically when the MicroSCADA application is started. The following command line can be added to the command procedure:@ret=aep_start(“c:\MS_Interfaces\Java\scil2java.exe”)

16


3.4. Configuring Java API for several productsIf several products are installed on the same computer, Java API can be configured to work with all of them. For example, if you have SYS 500 8.4.3 and SMS 510 1.0 installed, Java API will be installed and configured for SYS 500. The following tasks should be done to configure Java API for the SMS:

1. Copy the SYS_JAVA.INI from \sc\sys\active\sys_ directory to \SMS 510\sys\active\sys_.

2. Copy the EMSG.DLL from \sc\prog\exec to \SMS 510\prog\exec only if the EMSG.DLL in SMS is an older one.

3. Start Java API from the SMS with the following command line:@ret=aep_start(“c:\MS_Interfaces\Java\scil2java.exe”)

3.5. Using Java classes, applications and appletsThis section describes the using of Java classes, applications and applets, both locally and remotely. Some short examples will also be included.

3.5.1. Java classesThere are two possibilities to use the Java classes. They can be used locally (in the same host as MicroSCADA itself) or remotely. The usage of the Java classes is almost the same in both local and remote cases. The main difference is that when the classes are used remotely, there must be a SCIL_Connection class which handles the actual connection to MicroSCADA at a remote host.

3.5.2. Java applicationsThere can be both local and remote Java applications, also at the same time. Local applications can actually be used in the same way as other application extension programs. There can be more than one local Java programs started from one or more MicroSCADA applications.

The remote Java applications/applets are connected to MicroSCADA through a server process which will be started when the scil2java is started without any class name.

The API can be used on the local host also by creating a Java application whose name is then given as an argument to the scil2java program. Details about the usage of the related objects will be given in the following chapters and sections of this manual.

There can be only one server process in the same host at the same time.

If you are using the applets, a WWW-server is required. The files SCIL.jar and SCIL.cab must also be in the same directory where the applets are placed.

17


SYS 600 *9.1

Local applicationsIt is possible to create a Java application and run it using the scil2java.exe. In this case the Java class is given as an argument to the scil2java program. The name of the Java class should be without the “.class” extension. Because this Java class is an application, the main(String [])–method is required.

The scil2java and the Java class make an application extension program. together.

The number of the application extension program (from MicroSCADA) is given as the first argument to the Java class. The second argument is the application number from where the application extension program was started.

The Java application is started in the following way:@aepn = aep_start(“c:\MS_Interfaces\Java\scil2java.exe”, “prg_name”)

The “prg_name” is the name of the Java class.

Remote applets and applicationsFirst of all, a SCIL_Connection must be created. The SCIL_Connection must be given as an argument to the constructors of other SCIL_Interface and SCIL_Object classes to give them access to MicroSCADA. In case of a Java applet, the address of the MicroSCADA host must be the same as the address where the applet itself was loaded. The address of the MicroSCADA host is given as an argument to the constructor of the SCIL_Connection.

Remote_Appl

Fig. 3.5.2.-1 Description of a browser based remote application, similar to the one described in the Example Application chapter of this manual

1. The URL information is sent to the WWW-server.2. The WWW-server returns the HTML-page and the applet.3. Communication between the Applet and MicroSCADA via the Java API server.

18


3.5.3. ExamplesThe following six sections include small examples of SCIL Interface, MicroSCADA events, SCIL objects, free type objects, a Java application and a Java applet.

SCIL interfaceHere is a simple example of how to use the SCIL Interface to execute SCIL commands, read variables etc.

This example also demonstrates the use of the SCIL_Connection.public void test() {

SCIL_Interface iface; SCIL_Connection con; SCIL_Value v;

// 127.0.0.1 is simply the local host. // You can define your own host here. // If you are creating an applet, there are methods for getting the host // where they were loaded from.

con = new SCIL_Connection(“127.0.0.1”);

// Connection to the default application.

iface = new SCIL_Interface(con);

// Now there is a SCIL context created. // Let’s simply define a variable by using a SCIL command

iface.executeCommand(“@XYZ=100”);

// The variable is now defined and the value of the variable can // be received by getVariable() method. // Note that variables in other SCIL_Interfaces can not be seen // from here because of the different contexts.

v = iface.getVariable(“XYZ”);

if (v != null) System.out.println(v.toString()); // Writes the value to the standard output}

MicroSCADA eventsThis example creates a SCIL Interface connection to MicroSCADA and waits for the events.public void test() {

SCIL_Interface iface; SCIL_Message msg; // Connection to the default application

The MicroSCADA interface classes must be imported before they can be used (add “Import SCIL.*;” to the Java code).

19


SYS 600 *9.1

iface = new SCIL_Interface();

// The event(s) to be received is/are defined here. // Replace the “event_name” with the name of the event to be // subscribed.

iface.subscribeEvent(“event_name”, SCIL_Message.SCIL_ALL_OBJECT_INDEX);

msg = iface.getAepMessage(100000); // Block until timeout or until a message is received.}

The following example is applet, which works until exit event is received and handles different type of events:import java.awt.*;import java.applet.*;import SCIL.*;

public class ExitEvent extends Applet implements Runnable{ SCIL_Interface iface; SCIL_Connection con; String s=""; Threadtest_thread;public void start(){ String s1 = getCodeBase().getHost(); System.out.println("Connecting to " + s1); con = new SCIL_Connection(s1); // Connects to the local host iface = new SCIL_Interface(con); iface.subscribeExitEvent(); iface.subscribeEvent(“event_name”, SCIL_Message.SCIL_ALL_OBJECT_INDEX); // subscribe to some event test_thread = new Thread(this); test_thread.start();}public void run() { SCIL_Message Msg; System.out.println("Reading message..."); do{ Msg = iface.getAepMessage(10000); if(Msg != null) { if(Msg.message_type == 3) exitEventHandler(); // Handles the exit event else eventHandler(Msg); // Handles all other events } } while(Msg == null || Msg.message_type != 3);}public void exitEventHandler(){ s="Exit event received!"; System.out.println("Exit event received!");}public void eventHandler(SCIL_Message Msg) {// handles all subscribed MicroSCADA events except the exit event.}public void paint(Graphics g) { g.drawString(s,10,10);}}

20


SCIL ObjectsThis example shows how to access the MicroSCADA objects.public void test() {

SCIL_DataObject data; SCIL_Value v, tmp; int i;

data = new SCIL_DataObject(“data1”, 1);

/ Connect to datalog object “data1”, // in application 1.

v = data.getAttribute(“OV”, 1, 10);

// Returns a vector with 10 elements.

if (v.getValueType() == v.SCIL_VECTOR_TYPE) for (i=0; i<10; i++) { tmp = v.elementAt(i); System.out.println(tmp.toString()); }}

Free type objectsThe free attributes of the free type process objects must be read and written in the same order as they are defined. First of all, the attributes are read from MicroSCADA into the Java object. After that the individual attributes can be accessed.

The following example demonstrates the use of the free type objects. The code is a simple example about inheritance. In most cases it is reasonable to inherit your own object type from SCIL_FreeTypeObject.public class MyObject extends SCIL_FreeTypeObject {

public int XX; // Attribute XX

public MyObject(String name, int apl_num) { super(name, apl_num);

// Add your constructor code here… }

// The readAttributes() –method can be overloaded to simplify the // access to the different attributes e.g. in the following way.

public void readAttributes() {

// First the attributes are read to the byte array.

super.readAttributes();

// The first attribute is read as integer. // Now it is easier to access the attribute XX by simply //writing:

obj_name.XX = 123;

21


SYS 600 *9.1

// To make it really work, also the writeAttributes() –method must be //overloaded XX = getInt(); }

public void writeAttributes() { setInt(XX); }}

The new object can now be used e.g. in the following way:public void test() {

MyObject obj;

obj = new MyObject(“test”, 0); obj.readAttributes(); obj.XX = 100; obj.writeAttributes();

// Now the value of the attribute XX in MyObject “test” is 100.}

Java applicationThis simple Java application example demonstrates the use of the classes in the SCIL package.import java.awt.*;import java.applet.Applet;import SCIL.*;

/*This is a very simple Java application which demonstrates the use of the classes in the SCIL package. This application reads the current time from MicroSCADA and shows it on a window.*/

public class test_application implements Runnable {

public Frame MainWindow; Thread thr_Thread1; SCIL_Interface ifc_Iface1; SCIL_Value val_Value1=null; Label lbl_Txt1; Font fnt_Font; String s_txt1;

public test_application() {

// // A window is created. // MainWindow = new Frame(); MainWindow.show(); MainWindow.setSize(150, 100); fnt_Font=new Font("Courier",Font.PLAIN,14);

lbl_Txt1=new Label("Reading..."); lbl_Txt1.setForeground(Color.blue);

22


lbl_Txt1.setFont(fnt_Font); MainWindow.add(lbl_Txt1);

// // The MicroSCADA must be on the same host than this application // ifc_Iface1 = new SCIL_Interface(); }

void getTime() {

SCIL_Value val_Value1;

if (ifc_Iface1 == null) return;

val_Value1 = ifc_Iface1.evaluateExpression("tods"); if (val_Value1.getValueType() == val_Value1.SCIL_TEXT_TYPE) { s_txt1 = val_Value1.getString(); } else s_txt1 = "???";

lbl_Txt1.setText("Time: " + s_txt1); }

public void start() {

if (thr_Thread1 == null) { thr_Thread1 = new Thread(this); thr_Thread1.start(); }

}

public void run() {

while (thr_Thread1 != null) { try { Thread.sleep(1000); } catch (InterruptedException e) { }

getTime(); } thr_Thread1=null; }

public void stop(){

if (thr_Thread1 != null) { thr_Thread1.stop(); thr_Thread1 = null; } } public static void main(String argv[]) {

test_application apl;

apl = new test_application(); apl.start(); }}

23


SYS 600 *9.1

Java appletThis simple Java applet example demonstrates the use of the classes in the SCIL package.import java.awt.*;import java.applet.Applet;import SCIL.*;

/*This is a very simple applet which demonstrates the use of the classes in the SCIL package. This applet reads the current time from MicroSCADA.*/

public class test_applet extends Applet implements Runnable {

Thread thr_Thread1; SCIL_Connection con_Connection; SCIL_Interface ifc_Iface1; SCIL_Value val_Value1=null; Label lbl_Txt1; Font fnt_Font; String s_txt1;

public void init(){ setBackground(Color.white); fnt_Font=new Font("Courier",Font.PLAIN,14); lbl_Txt1=new Label("Reading..."); lbl_Txt1.setForeground(Color.blue); lbl_Txt1.setFont(fnt_Font); add(lbl_Txt1); // // Connect to the host where this applet was loaded from. // con_Connection=new SCIL_Connection(getCodeBase().getHost());

ifc_Iface1 = new SCIL_Interface(con_Connection);}void getTime() {

SCIL_Value val_Value1; if (ifc_Iface1 == null) return; val_Value1 = ifc_Iface1.evaluateExpression("tods"); if (val_Value1.getValueType() == val_Value1.SCIL_TEXT_TYPE) { s_txt1 = val_Value1.getString(); } else s_txt1 = "???"; lbl_Txt1.setText("Time: " + s_txt1);}

public void start(){

if (thr_Thread1 == null) { thr_Thread1 = new Thread(this); thr_Thread1.start(); }

24


}

public void run() {

while (thr_Thread1!=null) { try { Thread.sleep(1000); } catch (InterruptedException e) { }

getTime(); } thr_Thread1=null;}

public void stop(){

con_Connection.closeSCIL_Connection();

if (thr_Thread1 != null) { thr_Thread1.stop(); thr_Thread1 = null; }}}

25


4. Technical reference

This chapter gives technical reference information about the Java Classes.

4.1. Java classesThe Java classes can be used as follows:1. The user creates a Java application.2. The scil2java program is started as any other application extension program.3. The name of the Java application can be given as an argument to the scil2java

program. If there is no special name given, the server program is the default program to be executed.

4. The Java interpreter which is included in the scil2java will execute the Java code.

The specific Java classes will be introduced in the following sections.

4.1.1. SCIL_ConnectionThe SCIL_Connection class is the basic element in a client/server connection. It provides remote programs with an interface to MicroSCADA. When the other classes are used remotely, the SCIL_Connection handles the data transfer over the TCP/IP network. The idea of using the SCIL_Connection class between the SCIL_Object(s)/SCIL_Interface(s) is that the SCIL_Connection works like a multiplexer. There is no need for a separate connection for each object Instead, there is only one connection to the server for each applet/application. The commands are executed in the same order as they are requested by the objects on the client.

The server is a multithread Java application that listens to a TCP/IP socket waiting for object(s) to connect. The server creates a new thread for each connection. The server itself communicates with MicroSCADA using JNI which is actually a program written in C. The functions handle translations of MicroSCADA data types to Java data types. Special care has been taken to make this multi-thread safe (both Java and C codes).

The server listens to a TCP/IP port (the default is 1501). When a method is called in the client side, the class sends only the id of the method and the arguments to the server. The server will execute the actual code and send the return values if they are available.

Constructorspublic SCIL_Connection(String address)

Creates a new SCIL_Connection.

Parameter:'address' The address of the MicroSCADA host.

27


SYS 600 *9.1

public SCIL_Connection(String address, int port)

Parameter:'port' The port of the MicroSCADA server

public SCIL_Connection(String address, String name, String password)

Parameters:'name' The client name used for authentication'password' The client password used for authentication

public SCIL_Connection(String address, int port, String name, String password)

Methodspublic void closeSCIL_Connection()

This method must be run after the SCIL_Connection is not needed anymore. In case of an applet, this method must be run in the stop method of the applet in order to stop the receiver thread in the SCIL_Connection.

public boolean isConnected()

This method returns the connection state: true - if connection is established and false otherwise.

4.1.2. SCIL_SSL_ConnectionThe SCIL_SSL_Connection class is the child class of the SCIL_Connection. The only difference between these classes is that SCIL_SSL_Connection class handles the data transfer with SSL encoding.

Constructors

public SCIL_SSL_Connection(String address)

public SCIL_SSL_Connection(String address, int port)

public SCIL_SSL_Connection(String address, String name, String password)

public SCIL_SSL_Connection(String address, int port, String name, String password)

MethodsThe same as in the SCIL_Connection class.

4.1.3. SCIL_InterfaceThis is the interface to the MicroSCADA SCIL interpreter. By using this interface it is possible to read and set variables, execute SCIL commands, get events etc.

Local Constructorspublic SCIL_Interface()

Creates a new SCIL_Interface for the default application.

28


public SCIL_Interface(int apl)

Creates a new SCIL_Interface.

Parameter:'apl' The number of the MicroSCADA application.

public SCIL_Interface(int apl, int program_number)

Creates a new SCIL_Interface.

Parameters:'apl' The number of the MicroSCADA application.'program_number' The number of the application extension program.

Remote Constructorspublic SCIL_Interface(SCIL_Connection conn)

Creates a new SCIL_Interface reference for the default application and connects it to MicroSCADA using the SCIL_Connection.

Parameter:'conn' The SCIL_Connection that has been connected to

MicroSCADA.

public SCIL_Interface(SCIL_Connection conn, int apl)

Creates a new SCIL_Interface reference and connects it to MicroSCADA using the SCIL_Connection.

Parameters:'conn' The SCIL_Connection that has been connected to

MicroSCADA.'apl' The number of the MicroSCADA application.

MethodsThe methods are the same for both local and remote constructors.

public int getStatus()

This function reads the status from MicroSCADA.

Returns:The status value.

public void executeCommand(String command)

Executes the SCIL command in MicroSCADA.

Parameter:'command' The SCIL command to be executed.

29


SYS 600 *9.1

public SCIL_Value evaluateExpression(String expression)

Evaluates the given expression in MicroSCADA and returns the result as a SCIL_Value.

Parameter:'expression' The SCIL expression.

Returns:The result of the evaluation.

public void setVariable(String name, SCIL_Value value)

This function sets the SCIL variable to the given value.

Parameters:'name' The name of the variable.'value' The new value of the variable.

public SCIL_Value getVariable(String name)

Retrieves the value of the given SCIL variable.

Parameter:'name' The name of the variable.

Returns:The value of the variable (or null if the variable does not exist).

public void subscribeEvent(String name, int index)

This procedure makes a subscription to one or more events. You may specify the event name and index, event name and SCIL_ALL_OBJECT_INDEX (for all indexes of the name) or event name '*' and SCIL_ALL_OBJECT_INDEX (for all events of the application).

Parameters:'name' The name of the event.'index' The index of the event.

public void cancelEventSubscription(String name, int index)

Cancels the subscription that has been made for the event and index.

Parameters:'name' The name of the event.'index' The index of the event.

public void subscribeExitEvent()

This procedure makes a subscription to the exit event. It can be used only with remote interface. The exit event is sent to java programs when the scil2java.exe is stopped.

public void cancelExitEventSubscription()

Cancels the subscription for the exit event.

30


public SCIL_Message getAepMessage(int timeout)

Reads a message from MicroSCADA or waits for the message until it comes or the timeout exceeds.

Parameter:'timeout' The timeout value in milliseconds.

public void sendAepMessage(int aep_num, SCIL_Message msg)

Sends a message to another application extension program.

Parameters:'aep_num' The number of the application extension program.'msg' The message to be sent.

4.1.4. SCIL_ObjectThis class is used only as a superclass for the SCIL object classes described in Section 4.1.5.

Methodspublic int getStatus()

Reads the status from MicroSCADA.

Returns:The status code from MicroSCADA.

public String getName()

Returns the name of the object.

Returns:The name of this object.

public void setAttribute(String name, SCIL_Value value)

Sets the value of the given attribute.

Parameters:'name' The name of the attribute.'value' The value of the attribute.

public void setAttribute(String name, int start, int end, SCIL_Value value)

Sets the value of the given attribute. This method is used when there is more than one index in the MicroSCADA object.

Parameters:'name' The name of the attribute.'start' The start index of the attribute.'end' The end index of the attribute.'value' The value of the attribute. The type is vector if start≠end.

31


SYS 600 *9.1

public SCIL_Value getAttribute(String name)

The value of the named attribute is fetched from MicroSCADA.

Parameter:'name' The name of the attribute.

Returns:The value of the attribute.

public SCIL_Value getAttribute(String name, int start, int end)

The value of the named attribute is fetched from MicroSCADA. This method is used when there is more than one index in the MicroSCADA object.

Parameters:'name' The name of the attribute.'start' The start index of the attribute.'end' The end index of the attribute.

Returns:The value of the attribute. The value is type vector if start≠end.

public void activateObject(int index)

Activates an object. This function works only for datalogs, command procedures, event channels and event objects.

Parameter:'index' The index of the object to be activated.

4.1.5. Objects inherited from the SCIL_ObjectThe following objects have inherited the same methods that are available in the objects already mentioned in the section above.

4.1.5.1. SCIL_BaseSystemObjectThis object can be used to access a base system object in MicroSCADA.

Constructorspublic SCIL_BaseSystemObject(String name, int apl)

This constructor initialises a local base system object.

Parameters:'name' The name of the object (in MicroSCADA).'apl' The number of the MicroSCADA application.

public SCIL_BaseSystemObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote base system object.

Parameters:'name' The name of the object (in MicroSCADA).

32


'conn' The SCIL_Connection that has been connected to MicroSCADA.

'apl' The number of the MicroSCADA application.

4.1.5.2. SCIL_CommandProcedureObjectThis object can be used to access a command procedure object in MicroSCADA. It is also possible to activate an object of this type.

Constructorspublic SCIL_CommandProcedureObject(String name, int apl)

This constructor initialises a local command procedure object.


public SCIL_CommandProcedureObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote command procedure object.Parameters:'name' The name of the object (in MicroSCADA).'conn' The SCIL_Connection that has been connected to


4.1.5.3. SCIL_DataObjectThis object can be used to access a datalog object in MicroSCADA. It is also possible to activate an object of this type.

Constructorspublic SCIL_DataObject(String name, int apl)

This constructor initialises a local data object.


public SCIL_DataObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote data object.

Parameters:'name' The name of the object (in MicroSCADA).'conn' The SCIL_Connection that has been connected to


33


SYS 600 *9.1

4.1.5.4. SCIL_EventChannelObjectThis object can be used to access an event channel object in MicroSCADA . It is also possible to activate an object of this type.

Constructorspublic SCIL_EventChannelObject(String name, int apl)

This constructor initialises a local event channel object.

Parameters:'name' The name of the object (in MicroSCADA ).'apl' The number of the MicroSCADA application.

public SCIL_EventChannelObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote event channel object.



4.1.5.5. SCIL_EventObjectThis object can be used to access an event object in MicroSCADA. It is also possible to activate an object of this type.

Constructorspublic SCIL_EventObject(String name, int apl)

This constructor initialises a local event object.


public SCIL_EventObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote event object.

Parameters:'name' The name of the object (in the MicroSCADA).'conn' The SCIL_Connection that has been connected to


4.1.5.6. SCIL_ProcessObjectThis object can be used to access a process object in MicroSCADA.

34


Constructorspublic SCIL_ProcessObject(String name, int apl)

This constructor initialises a local process object.


public SCIL_ProcessObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote process object.



4.1.5.7. SCIL_ScaleObjectThis object can be used to access a scale object in MicroSCADA.

Constructorspublic SCIL_ScaleObject(String name, int apl)

This constructor initialises a local scale object.


public SCIL_ScaleObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote scale object.



4.1.5.8. SCIL_SystemObjectThis object can be used to access a system object in MicroSCADA.

Constructorspublic SCIL_SystemObject(String name, int apl)

This constructor initialises a local system object.

35


SYS 600 *9.1


public SCIL_SystemObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote system object.



4.1.5.9. SCIL_TimeChannelObjectThis object can be used to access a time channel object in MicroSCADA.

Constructorspublic SCIL_TimeChannelObject(String name, int apl)

This constructor initialises a local time channel object.


public SCIL_TimeChannelObject(String name, SCIL_Connection conn, int apl)

This constructor initialises a remote time channel object.



4.1.6. SCIL_FreeTypeObjectThis object is usually used as a parent class for some inherited objects. The free type process objects can be defined by the user, and that is why it is useful to create your own object which handles the user-defined attributes in a useful way. The basic idea of this object is that first all of the user-defined attributes are read from MicroSCADA to a byte array by using the readAttributes method. The data in the byte array is then handled by the get*** -functions in order to get the attribute. The attributes must be read in the same order in which they have been defined in MicroSCADA. It is the user’s responsibility to read the attribute as the same data type as it was defined in MicroSCADA.

When the values of the attributes are set using the set*** -methods (in the right order), they must be written to MicroSCADA by using the writeAttributes method.

36


Constructorspublic SCIL_FreeTypeObject(String name, int apl_num)

Creates a new SCIL_FreeTypeObject.

Parameters:'name' The name of the free type object.'apl_num' The number of the application.

public SCIL_FreeTypeObject(String name, SCIL_Connection conn, int apl_num)

Creates a new (remote) SCIL_FreeTypeObject.

Parameters:'name' The name of the free type object.'conn' The connection to the MicroSCADA.'apl_num' The number of the application.

Methodspublic void readAttributes()

Reads the attributes from MicroSCADA.

public void writeAttributes()

Writes the attributes to MicroSCADA.

public int getInt()

Reads the next attribute as integer.

public String getString(int length)

Reads the next attribute as string.

Parameter:'length' The length of the string.

public float getFloat()

Reads the next attribute as float.

public boolean getBoolean()

Reads the next attribute as boolean.

public Date getTime()

Reads the next attribute as scil time value.

public BitSet getBitString(int length)

Reads the next attribute as bit string.

Parameter:'length' The length of the bit string.

37


SYS 600 *9.1

public byte[] getBytes()

Returns all attributes as a byte array. The attributes are still in little endian format.

public void setInt(int value)

Sets the next attribute. The attribute must be of type integer.

Parameter:'value' The value of the attribute.

public void setString(String str, int length)

Sets the next attribute. The attribute must be of type string.

Parameters:'str' The value of the attribute.'length' The length of the string (specified in the definition of the

free type object. Note that this is not always the same as the actual length of the string (str)).

public void setFloat(float value)

Sets the next attribute. The attribute must be of type float.


public void setBoolean(boolean value)

Sets the next attribute. The attribute must be of type boolean.


public void setTime(Date value)

Sets the next attribute. The attribute must be of type scil time.


public void setBitString(BitSet bset, int length)

Sets the next attribute. The attribute must be of type bit string.

Parameters:'bset' The value of the attribute.'length' The length of the bit string.

public void setBytes(byte bytes[], int count)Sets the values of all the free attributes. The bytes in the byte array must be in little endian format.

Parameters:'bytes[]' The attributes as a byte array.'count' The number of bytes in the array.

38


4.1.7. SCIL_ValueThis class encapsulates the SCIL data types. Before the value of this object is read, it is very wise to check the data type by using the getValueType method before the actual get*** method, unless you are sure about the current data type of the object. Trying to read a wrong data type can cause an unwanted result. Methods that return an object, throw a runtime exception in case of a wrong data type. Methods like getInt() throw a runtime exception in case it is a sensible value and can cause misunderstandings in some cases.

ConstantsThe constants listed below indicate the different types of SCIL_Values. They are simply integers. The return value of the getValueType -function can be compared to these constants to find out the actual type of the SCIL_Value.

SCIL_BIT_STRING_TYPE

The SCIL_Value is of type bit string. The bits in the bitstring can be handled with functions bitSet() and bitClear().

SCIL_BOOLEAN_TYPE

The SCIL_Value is of type boolean. The valid values are true and false.

SCIL_BYTE_STRING_TYPE

The SCIL_Value is of type byte string.

SCIL_INTEGER_TYPE

The SCIL_Value is of type integer.

SCIL_LIST_TYPE

The SCIL_Value is of type list.

SCIL_NO_TYPE

There is actually no value in the SCIL_Value. The setValue(***) functions can be used for this type of SCIL_Value, but it is not possible to read this type of SCIL_Value.

SCIL_REAL_TYPE

The SCIL_Value is of type real.

SCIL_TEXT_TYPE

The SCIL_Value is of type text.

SCIL_TIME_TYPE

The SCIL_Value is of type SCIL time. The time is handled as a Date object in Java. Note that if you are using the time as seconds from the specified year, there is a difference between MicroSCADA and Java. In MicroSCADA the seconds start from the year 1978 but in Java the start is earlier, in 1970.

SCIL_VECTOR_TYPE

The SCIL_Value is of type vector.

39


SYS 600 *9.1

Constructorspublic SCIL_Value()

Creates a SCIL_Value object of SCIL_NO_TYPE.

public SCIL_Value(String value)

Creates a SCIL_Value object of SCIL_TEXT_TYPE.

Parameter:'value' Sets a String type value for the created object.

public SCIL_Value(int value)

Creates a SCIL_Value object of SCIL_INTEGER_TYPE.

Parameter:'value' Sets an int type value for the created object.

public SCIL_Value(float value)

Creates a SCIL_Value object of SCIL_REAL_TYPE.

Parameter:'value' Sets a float type value for the created object.

public SCIL_Value(boolean value)

Creates a SCIL_Value object of SCIL_BOOLEAN_TYPE.

Parameter:'value' Sets a boolean type value for the created object.

public SCIL_Value(Date value)

Creates a SCIL_Value object of SCIL_ TIME _TYPE.

Parameter:'value' Sets a Date type value for the created object.

public SCIL_Value(BitSet value)

Creates a SCIL_Value object of SCIL_BIT_STRING_TYPE.

Parameter:'value' Sets a BitSet type value for the created object.

public SCIL_Value(byte value[])

Creates a SCIL_Value object of SCIL_BYTE_STRING_TYPE.

Parameter:'value[]' Sets a byte type value for the created object.

40


public SCIL_Value(Vector value)

Creates a SCIL_Value object of SCIL_ VECTOR _TYPE.

Parameter:'value' Sets a Vector type value for the created object. If an

element is not of SCIL_Value type, a runtime exception will be thrown.

public SCIL_Value(Hashtable value)

Creates a SCIL_Value object of SCIL_ LIST _TYPE.

Parameter:'value' Sets a Hashtable type value for the created object. If an

element is not of SCIL_Value type, a runtime exception will be thrown.

Methodspublic void setValue(String value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_TEXT_TYPE.

Parameter:'value' Resets a String type of value for an earlier created

SCIL_Value object.

public void setValue(int value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_INTEGER_TYPE.

Parameter:'value' Resets an int type of value for an earlier created

SCIL_Value object.

public void setValue(float value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_REAL_TYPE.

Parameter:'value' Resets a float type of value for an earlier created

SCIL_Value object.

public void setValue(boolean value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_BOOLEAN_TYPE.

Parameter:'value' Resets a boolean type of value for an earlier created

SCIL_Value object.

41


SYS 600 *9.1

public void setValue(Date value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_TIME_TYPE.

Parameter:'value' Resets a Date type of value for an earlier created

SCIL_Value object.

public void setValue(BitSet value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_BIT_STRING_TYPE.

Parameter:'value' Resets a BitSet type of value for an earlier created

SCIL_Value object.

public void setValue(byte value[])

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_BYTE_STRING_TYPE.

Parameter:'value[]' Resets a byte type of value for an earlier created

SCIL_Value object.

public void setValue(Vector value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_VECTOR_TYPE.

Parameter:'value' Resets a Vector type of value for an earlier created

SCIL_Value object. If an element in the vector is not of SCIL_Value type, a runtime exception will be thrown.

public void setValue(Hashtable value)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_LIST_TYPE.

Parameter:'value' Resets a Hashtable type of value for an earlier created

SCIL_Value object. If an element in the vector is not of SCIL_Value type, a runtime exception will be thrown.

public void setTime(int seconds)

Sets the value of the SCIL_Value. The type of the SCIL_Value will be SCIL_TIME_TYPE.

Parameter:'seconds' The time value in seconds from 1.1.1970.

42


public int getValueType()

Gets the type of the SCIL_Value. This function should be called before calling any of the Get functions.

Returns:The type of the SCIL value (SCIL_NO_TYPE ... SCIL_ LIST_TYPE).

public String getString()

If the object is of type SCIL_TEXT_TYPE, this function will return the text string. Otherwise it throws a runtime exception.

public int getInt()

If the object is of type SCIL_INTEGER_TYPE, this function will return the integer value. Otherwise it throws a runtime exception.

public float getFloat()

If the object is of type SCIL_REAL_TYPE, this function will return the real value. Otherwise it throws a runtime exception.

public boolean getBoolean()

If the object is of type SCIL_BOOLEAN_TYPE, this function will return the boolean value. Otherwise it throws a runtime exception.

public Date getTime()

If the object is of type SCIL_TIME_TYPE, this function will return the SCIL time as a date object. Otherwise it throws a runtime exception.

public int getSeconds()

If the object is of type SCIL_TIME_TYPE, this function will return the SCIL time, converted to seconds from 1970, as an integer. Otherwise it throws a runtime exception.

public BitSet getBitString()

If the object is of type SCIL_BIT_STRING_TYPE, this function will return the bit string object. Otherwise it throws a runtime exception.

public byte[] getByteString()

If the object is of type SCIL_BYTE_STRING_TYPE, this function will return the byte string object. Otherwise it throws a runtime exception.

public Vector getVector()

If the object is of type SCIL_VECTOR_TYPE, this function will return the vector object. Otherwise it throws a runtime exception.

public Hashtable getList()

If the object is of type SCIL_LIST_TYPE, this function will return the list object as a Hashtable where the name of the attribute is the key. Otherwise it throws a runtime exception.

43


SYS 600 *9.1

public SCIL_Value elementAt(int index)

Returns the selected SCIL_Value from SCIL_Value of type vector. If the type of the SCIL_Value is not SCIL_VECTOR_TYPE, this method will throw a runtime exception.

Parameter:'index' The index of the element in the vector.

Returns:The value of the element or null.

public void addElement(SCIL_Value v)

Sets the selected item in the vector.

Parameter:'v' The SCIL_Value to be added to the vector.

public void setElementAt(SCIL_Value v, int index)

Sets the selected item in the vector.

Parameters:'v' The SCIL_Value to be added to the vector.'index' The place where the value will be added.

public SCIL_Value getAttribute(String name)

Returns the value of the selected attribute from SCIL_Value of type list. If the type of the SCIL_Value is not SCIL_LIST_TYPE, this method will throw a runtime exception. If the attribute does not exist it returns null.

Parameter:'name' The name of the attribute.

Returns:The value of the attribute.

public Enumeration listAttributes()

Lists the attributes of a SCIL_Value of type list.

Returns:The names of the attributes. If the type of the SCIL_Value is not of SCIL_LIST_TYPE, this method will throw a runtime exception.

public void setAttribute(String name, SCIL_Value v)

Sets the selected attribute in the list.

Parameters:'name' The name of the attribute.'v' The new value of the attribute.

44


public void bitSet(int bit)

Sets the selected bit in the bit string.

Parameter:'bit' The number of the bit to be set.

public void bitClear(int bit)

Clears the selected bit in the bit string.

Parameter:'bit' The number of the bit to be cleared.

4.1.8. SCIL_MessageThese messages are sent to the application extension program by using the scil function aep_send, a process object or another application extension program.

Variablespublic SCIL_Value arguments[]

The arguments as an array of SCIL_Values. This value is valid when the type of the message is SCIL_EP_MESSAGE_SCIL.

public int count

The number of the arguments. This value is valid when the type of the message is SCIL_EP_MESSAGE_SCIL.

public byte data[]

The message data. This value is valid when the type of the message is SCIL_EP_MESSAGE_EP.

public int index

The index of the event. This value is valid when the type of the message is SCIL_EP_MESSAGE_EVENT.

public int length

The length of the message data. This value is valid when the type of the message is SCIL_EP_MESSAGE_EP.

public int message_type

The type of the message. The value can be one of the types defined above (SCIL_EP_MESSAGE_NONE...SCIL_EP_MESSAGE_EP).

public String name

The name of the event. This value is valid when the type of the message is SCIL_EP_MESSAGE_EVENT.

45


SYS 600 *9.1

Event Indicating ConstantsThe following constants indicate the different types of MicroSCADA events.

SCIL_ALL_OBJECT_INDEX

This can be used in the subscription and cancelling of events. It indicates that all indices of the specified object will be subscribed or cancelled.

SCIL_EP_MESSAGE_EP

This type of messages are sent by another application extension program. When the message is created with the default constructor, the message is of this type to be able to send it to another application extension program.

SCIL_EP_MESSAGE_EVENT

This type of messages are generated by process objects when the value of the object is changed.

SCIL_EP_MESSAGE_EXIT

When this message is received, MicroSCADA wants to shut down this application extension program. After this message it is not possible to receive any other messages.

SCIL_EP_MESSAGE_NONE

There is no data in the message object.

SCIL_EP_MESSAGE_SCIL

This type of message can be sent by SCIL function aep_send.

SCIL_MAX_EP_MESSAGE_ARGUMENTS

This is the maximum number of arguments of type SCIL_Value in case the message type is SCIL_ EP_MESSAGE_SCIL.

Constructorspublic SCIL_Message()

Creates a new SCIL_Message of type SCIL_EP_MESSAGE_EP.

public SCIL_Message(int type)

Creates a new SCIL_Message.

Parameter:'type' The type of the message.

EventLogThis class is used to write messages to the NT event log. It can be used only in a local Java application loaded by AEP_START(“scil2java.exe”, <java_class>) command. Remote applications and applets cannot use this class.

46


Constructorspublic EventLog()

Creates a new EventLog object.

Methodspublic void writeUserError(int userErrorCode, String errorStr)

Writes external application event of type “Error” to the NT event log.

Parameters:

'userErrorCode' The error code.'errorStr' The error message.

public void writeUserInformation(int userInfoCode, String infoStr)

Writes external application event of type “Information” to the NT event log.

Parameters:

'userInfoCode' The information code.'infoStr' The information message.

public void writeUserWarning(int userWarningCode, String warningStr)

Writes external application event of type “Warning” to the NT event log.

Parameters:

'userWarningCode' The warning code.'warningStr' The warning message.

public void writeUserAuditSuccess(int userAuditCode, String auditStr)

Writes external application event of type “Audit Success” to the NT event log.

Parameters:

'userAuditCode' The audit success code.'auditStr' The audit success message.

public void writeUserAuditFailure(int userAuditCode, String auditStr)

Writes external application event of type “Audit Failure” to the NT event log.

Parameters:

userAuditCode' The audit failure code.

'auditStr' The audit failure message.

47


5. Example application

This chapter describes an example implementation of Java API. It also describes how the applets communicate with each other and how they function in general. The installation of the example application is described in Section 3.2. of this manual.

The purpose of the implementation is to show how Java can be used to present data, fetched directly from MicroSCADA, in the Internet.

A small demonstration of a typical System Diagnostics program has been made with Java, HTML and SCIL.

Use Microsoft Internet Explorer 4.01, or a later version, to get the right layout on the pages.

AbbreviationsThe following abbreviation will be used in this chapter:'labeltype' An applet which displays information of text or numbers

in labels, choices and textfields.

5.1. Using the example applicationIn this section you will be given instructions and information which concern the configuration and diagnostics of the example application.

5.1.1. First page (main.html)The first page is just a normal HTML-page like any other in the Internet. It includes a picture in jpg-format, an applet and an animated link.

An applet was made to speed up the next page (General info). The applet imports the SCIL.* , java.awt.* and the java.applet.*. classes.This has been proved to speed up the initialisation time for the bigger applets. The applet name is preload.java.

The following line, which can be found at the top of the source code, loads the page main2.html after about 5 - 10 seconds, depending on the transmission.

<META HTTP-EQUIV="refresh" CONTENT="10;URL=main2.html">

49


SYS 600 *9.1

Frontpage

Fig. 5.1.1.-1 MicroSCADA System Diagnostics is the first page to appear on the screen when the web connection to MicroSCADA is established. After 5-10 seconds this page will automatically change into General System Information page (see Figure 5.1.2.-1).

5.1.2. General info (generalinfo.html)This applet is of label type and it displays:• Net-, Tool- and Librevision• System machine name• Hardware, Software and License information• Customer and site information

The applets on this page are called generalinfo.java and logo.java.

50


General_Sys_Info

Fig. 5.1.2.-1 The General System Information page

About the codeIn these applets, a function has often been made to view the labels. Here it is called addLabel(Label, String, int, int, GridBagConstraints, GridBagLayout, Font).

'Label' The label to add'String' The caption of the label'int' X-coordinates'int' Y-coordinates'GridbagConstraints' Constraints'GridbagLayout' Layout'Font' The name of the font

The function that reads the information from MicroSCADA and shows it on the right labels is called getValues(). This applet does not require any updating so the getValues() function is called only once, after the initialisation.

51


SYS 600 *9.1

5.1.3. Configuration & diagnostics (configuration.html)The page which is shown after this selection is made, is the System basic configuration and a link-frame. Basic system configuration (sysconfiguration.java) on the page info.html contains information about:• Node number• Station address• Enable routing• Timeout length• File sync criteria

This applet is of label type.

A link frame (links.html) can be found at the top of the page. Small gif-pictures are used as links to get a nice-looking layout, see Figure 5.1.3.-1. Two gif-animations have also been made for the diagrams. This frame is visible only if Configuration & Diagnostics has been chosen.

Basic_Sys_Conf

Fig. 5.1.3.-1 The Basic System Configuration page

52


5.1.3.1. Applications (apl.html)On these pages you will find two applets (a listapplet and an infoapplet) communicating with each other.

The applets use the aplcom class to communicate.

Fig. 5.1.3.1.-1 Applet - applet communication

The aplcom.class uses public static variables to enable the communication.

Here is a sample of the source-code:public static synchronised void sendValues(String par1,String par2,String par3,String par4,String par5,String par6,String par7,String par8,String par9,String par10,String par11, String par12,String par13,String par14,String par15){

s_Par1=par1;s_Par2=par2;s_Par3=par3;s_Par4=par4;s_Par5=par5;s_Par6=par6;s_Par7=par7; s_Par8=par8;s_Par9=par9;s_Par10=par10;s_Par11=par11;s_Par12=par12; s_Par13=par13;s_Par14=par14;s_Par15=par15;

}

public static String fetchPar1(){if(b_Sendflag==true){

return s_Par1;}

else return s_Empty;}

53


SYS 600 *9.1

The basic idea in the communicating applets is that:• Applets initialise the layout• They connect to MicroSCADA and call the function getValues()• They evaluate the expressions made by the textfile• They loop, trim the text with trimText(String) and add each item to the list

When an item is selected from the list:1. Find out which item is selected.2. Fetch the information from MicroSCADA.3. Send the information to aplcom.class and set the b_Sendflag variable true.

Now the infoapplet can fetch the information from aplcom and place it on the screen.

The application page includes the applets’ apllist and aplinfo to display the following information:• Application number• Application name• Type, State• Node number• Translated object number• Alarm signal size• History buffer• Parallel queues

This page contains also two links, diagnostics (apldiagnostics.html) and mapping (mapping.html). The applets on these pages also communicate with the listapplet. These applets communicate via an applet called pagecom, which is placed in the link-frame. So when a selection is made from the list, a parameter (in this case the application number) is sent to the pagecom applet and the b_Sendflag variable is set to true. The other applets can then get information from MicroSCADA with this parameter.

54


Applications

Fig. 5.1.3.1.-2 The Applications page. Links to Diagnostics and Mapping pages can be found here.

Application diagnostics (apldiagnostics.html)Here you can find two applets, aplshadow and apldiag, which work in the same way as the generalinfo applet explained in Section 5.1.2. However, these applets are a bit special because they get the application number from the pagecom.class.

To display the diagnostic counters, apldiag.class uses the attribute APLn:BSD.

The aplshadow.class shows the following information by:• Shadowing connection time• Shadowing flush time• Shadowing diagnostic interval• Shadowing number• Shadowing phase• Shadowing the Event channel queue• Shadowing receive timeout• Shadowing state

55


SYS 600 *9.1

• Shadowing watchdog• Time synchronisation interval

Application mapping (mapping.html)Four applets are placed on this page, and they all display a list with a logical and a physical number. STA-, MON-, APL- and PRI-mappings are listed.

They get the application number from the pagecom.class and the vector from a specific attribute. The vector is then looped through, and the items are trimmed and added to the list. The attributes are as follows:APLn:BST StationAPLn:BMO MonitorAPLn:BAP Application

5.1.3.2. Monitors (mon.html)Similar applets to the ones on apl.html are placed on this page (monlist.class and moninfo.class).

The file mon.txt in the temp directory is read and after that the information is fetched from MicroSCADA.

The information displayed is:• Monitor number• Translation type• Logged in / APL• Input locked• Type• Device connection• System device name• Diagnostic interval• Colour allocation policy• Semigraphic

5.1.3.3. Nodes (nod.html)Identical applets as in apl.html (nodlist.class and nodinfo.class).

The file nod.txt in the temp directory is read and the information is fetched from MicroSCADA.

Information displayed is:• Node number• Station address• Registration date and time• LAN node name• Last transaction number• Link number

56


• Diagnostic interval• Diagnostic timeout• Node type

5.1.3.4. Printers (pri.html)Identical applets as in apl.html (prilist.class and priinfo.class).

The file pri.txt in the temp directory is read and the information is fetched from MicroSCADA.

Information displayed is:• Printer number• Device type• Translation type• State• Open on job basis• Translated object number• Device connection• System device name• Line per page• Output destination• Log length• Log flush timeout• Log directory

5.1.3.5. Links (lin.html)Identical applets as in apl.html (linlist.class and lininfo.class).

The file lin.txt in the temp directory is read and the information is fetched from MicroSCADA.

Information displayed is:• Link number• Link type• LAN transport• System device name• Redundancy• Timeout length• Fairness count• NAK limit• ENQ limit• Start command

There is also a link to a diagnostics page called lindiagnostics.html.on this page.

57


SYS 600 *9.1

Link diagnostics (lindiagnostics.html)This applet reads a parameter from the pagecom.class and displays the link diagnostic counters. The same principle is used here: the list sends the parameter to both the aplcom and pagecom.

The attribute used for the Links diagnostic counters is LINn:BDC.

5.1.3.6. Stations (sta.html)Only one applet is displayed on this page (stalist.class). The applet uses System Self Supervision to get information about the stations. The applet does not function, if System Self Supervision is not installed. It is provided in the LIB 500 package.

Information displayed in the station list:(LN) Logical Name(OI) Object Identity(OX) Object text(OV) Object value

5.1.3.7. Nets (net.html)This page contains an applet which is almost identical to the Station applet. The query here is BSWNETINET.

When a selection has been made, the applet checks which item has been selected. With another query (BSWNETILIN) it produces a new query and uses the SELECT-function (described in the SCIL-manual) to get information about the lines.

Information displayed in the net list:(LN) Logical Name(OI) Object Identity(OX) Object text(OV) Object value

5.1.3.8. Memory (memory.html)The memory page contains two applets (memory.class, vumeter.class) and two links (memblocks.html, memmeters.html).

Memory.class is a labeltype applet and it displays information about:• Total memory size• Picture cache size• Report cache size

Vumeter.class is an applet which contains graphics. The applet monitors the total memory usage and displays the current value in a numerical and graphical form.

Furthermore, it has a green warning label which turns into red when a specific value is reached.

58


Vu_Meter

Fig. 5.1.3.8.-1 The Vu-meter applet

This is how the applet works:• The layout is set• A connection to MicroSCADA is made• The memory usage is calculated• It checks the warning limit• It scales the value to fit on the picture• It draws the picture

Points 3-6 are updated once in every 2 seconds.

The used picture and report caches (memmeters.html)This page contains two applets (picmeter.class, repmeter.class). These applets monitor the picture cache and report cache used by the system.

The current value is displayed both numerically and graphically. The functions are the same as in the Vu-meter in the section above.

59


SYS 600 *9.1

Memorymeter

Fig. 5.1.3.8.-2 The Memorymeter

Memoryblocks (memblocks.html)This is also a graphical applet. It shows the memory block sizes and memory blocks used as a diagram.

Almost everything in this applet is painted. One special thing is that the applet reads the file sc\temp\memblocks.txt every time it is started and when the x-axis scale needs to be updated. A loop is made through a vector which contains the current values of the memoryblocks being used. The value is calculated as SYS:BMS * SYS:BMU.

5.1.3.9. Time (time.html)This page contains two applets (time.class, Clock.class). The first applet, time.class, is a labeltype applet and it shows information about:• External clock address• Clock read frequency• External clock• Clock status• Time zone• Time season• Current date• Current time

This applet is updated once every half a second, but because of the many attributes this applet displays, the time is updated every fourth or fifth second.

The second applet, Clock.class, shows an analog clock and it is updated every second. The clock is painted in two steps: first the base, then the numbers and the current time. Calculation is taken care of by the method drawClock(Graphics).

60


Clock

Fig. 5.1.3.9.-1 The clock

5.1.3.10. Queues (queuemeters.html)This page contains two applets (printermeter.class, eventmeter.class).

The used attributes are:APL:BPM Printer spooler queue length maximumAPL:BPU Printer spooler queue length usedAPL:BEM Event channel queue length maximumAPL:BEU Event channel queue used

Printermeter.class has also a choice-component with two options, process printouts and SCIL printouts.

5.1.3.11. Bar-chart (diagram.html)This page shows an applet which displays a bar-chart (diagram.java) with data from a specific data-object, see Figure 5.1.3.11.-1. The dataobject source is configurable from the applet.

The Interval-time and the Max-value are configurable from the HTML-page.

This is how the applet works:• The layout is set• Parameters are read from the HTML-page• The base is drawn• When the Start button is selected a connection to MicroSCADA is made• The applet fetches the values from MicroSCADA• The values are calculated to fit in the window• The diagram is drawn

This applet is updated with the interval configured from the HTML-page.

61


SYS 600 *9.1

Bar_Chart

Fig. 5.1.3.11.-1 An example of a bar-chart with data from a specific data object

5.1.3.12. Line-diagram (linediagram.html)This is an applet which shows line diagrams (linediagram.class) with information fetched from two data objects, see Figure 5.1.3.12.-1. The data object source is configurable from the HTML-page. The maximum value of the Y-axis is also configurable. If you click the Help-button, a small frame will open showing a help-text.

This is how the applet works:• Parameters are read from the HTML-page• The layout is set• A connection to MicroSCADA• is made• A base is drawn• The first graph’s minimum and maximum values are sorted out• The first graph is painted

62


• The second graph’s minimum and maximum values are sorted out• The second graph is painted

This applet is updated every second

Line_Diagram

Fig. 5.1.3.12.-1 Line diagrams with information fetched from two data objects

63


6. Glossary

This section describes terminology and defines words used in this document. The same words may have quite different meanings in other circumstances; these explanations refer only to this document and the systems described in this document.

Definitions and abbreviationsAEPApplication Extension Program.

DATDigital Audio Tape.

ENQ limitEnquire limit.

EP message(Application) Extension Program message.

GIFGraphics Interchange Format. CompuServe’s graphics file format.

HSBHot Stand-by.

HTMLHypertext Markup Language.

IEMicrosoft Internet Explorer.

IISInternet Information Server.

INI-fileInitialisation-file.

IP addressInternet Protocol address. The transport layer which describes a packet format for data to pass on a TCP/IP network and on the Internet.

Java APIJava Application Programming Interface.

JDKJava Development Kit.

JNIJava Native Interface.

65


SYS 600 *9.1

JREJava Runtime Environment.

LANLocal Area Network. A network spanning a small physical area, for example, a building. LAN operates at high speed (10-100 Mbit/s).

LIB 500The LIB 500 Application Software Library consists of product packages for building the applications in a MicroSCADA application.

MicroSCADAIt is a computer-based, programmable and distributed Supervisory Control And Data Acquisition (SCADA) system.

NAK limitNegative Acknowledge limit.

SCILSupervisory Control Implementation Language.

SPRMicroSCADA System Progress Report.

TCP/IPTransmission Control Protocol/Internet Protocol.

URLUniform Resource Locator. A standard method for defining the location of the resource for remote access, for example, by a WWW-browser.

WWWWorld Wide Web. A networked information service using the HTML for its formatting and interfaces.

66


7. Index

Symbols .................................................................................................................. 16

Numerics7SCIL_Context ........................................................................................... 6

AAccess level .............................................................................................. 15Access levels ............................................................................................ 16AddLabel .................................................................................................. 51Administrator rights .................................................................................. 12AEP ........................................................................................................... 11Aep_send .................................................................................................. 46Aep_start function .................................................................................... 14Alarm signal size ...................................................................................... 54Animated link ........................................................................................... 49Animations ............................................................................................... 52Apl.html .............................................................................................. 56, 57APL:BEM ................................................................................................. 61APL:BEU ................................................................................................. 61APL:BPM ................................................................................................. 61APL:BPU .................................................................................................. 61Apl_init ..................................................................................................... 16Aplcom ..................................................................................................... 58Aplcom.class ...................................................................................... 53, 54Apldiag ..................................................................................................... 55Apldiagnostics.html .................................................................................. 54Aplinfo ...................................................................................................... 54Apllist ....................................................................................................... 54APL-mapping ........................................................................................... 56APLn:BAP ................................................................................................ 56APLn:BMO .............................................................................................. 56APLn:BSD ................................................................................................ 55APLn:BST ................................................................................................ 56Aplshadow ................................................................................................ 55Aplshadow.class ....................................................................................... 55Applet ............................................................................... 18, 28, 49, 51, 58Applet - applet communication ................................................................ 53Application ............................................................................................... 56

Extension program ................................................................................ 6Name ................................................................................................... 54Number ............................................................................................... 54Page .................................................................................................... 55State ...................................................................................................... 6

67


SYS 600 *9.1

Application extension program .................................................... 18, 27, 46Application mapping ................................................................................ 11Archive format ......................................................................................... 11Argument .................................................................................................. 27Arguments ................................................................................................ 27Array ......................................................................................................... 45AS attribute ................................................................................................ 6Audit failure message ............................................................................... 47Audit success code ................................................................................... 47Audit success message ............................................................................. 47Auth_SCIL_File_Name ........................................................................... 16authentication mechanism ........................................................................ 16Authentication_Type ................................................................................ 16AUTHETICATED ................................................................................... 16

BB_Sendflag ............................................................................................... 54Bar-chart ............................................................................................. 61, 62Base .................................................................................................... 61, 62Base system object ................................................................................... 32Basic System Configuration ..................................................................... 52Benefits ...................................................................................................... 6Bit string ....................................................................................... 37, 38, 39Bit string object ........................................................................................ 43BitSet type of value .................................................................................. 42BitSet type value ...................................................................................... 40Boolean ........................................................................................ 37, 38, 39Boolean type of value ............................................................................... 41Boolean type value ................................................................................... 40Boolean value ........................................................................................... 43Browsers ................................................................................................... 11BSWNETILIN ......................................................................................... 58BSWNETINET ........................................................................................ 58Byte array ........................................................................................... 36, 38Byte string ................................................................................................ 39Byte type of value .................................................................................... 42Byte type value ......................................................................................... 40

CCancelling of events ................................................................................. 46C-API ......................................................................................................... 6Caption of the label .................................................................................. 51Choice-component ................................................................................... 61Class aplcom ............................................................................................ 53Classes ...................................................................................................... 22Client ........................................................................................................ 27

68


Client name ............................................................................................... 28Client password ........................................................................................ 28Client use .................................................................................................. 11Client/server connection ........................................................................... 27CLIENT_NAME ...................................................................................... 16CLIENT_PASSWORD ............................................................................ 16Clients ....................................................................................................... 15Clients names and passwords ................................................................... 16Clock ......................................................................................................... 61

Read frequency ................................................................................... 60Status .................................................................................................. 60

Clock.class ................................................................................................ 60Colour allocation policy ........................................................................... 56Command line .......................................................................................... 16Command procedure ................................................................................ 16Command procedure object ...................................................................... 33Command prompt ..................................................................................... 14Configuration ................................................................................ 11, 15, 49Configuration & Diagnostics .................................................................... 52Configuration file ..................................................................................... 15connection state ........................................................................................ 28Constraints ................................................................................................ 51Constructors .............................................................................................. 18Current

Date ..................................................................................................... 60Time .................................................................................................... 60

Customer information ............................................................................... 50Customizing the installation ..................................................................... 14

DData

Object ..................................................................................... 61, 62, 63Data object ................................................................................................ 33Data transfer ............................................................................................. 27Date object .......................................................................................... 39, 43Date type of value ..................................................................................... 42Date type value ......................................................................................... 40Default access field ................................................................................... 16Default_Access ................................................................................... 15, 16Description of a browser based remote application ................................. 18Destination drive ...................................................................................... 14Device

Connection .................................................................................... 56, 57Type .................................................................................................... 57

DiagnosticInterval ................................................................................................ 56

69


SYS 600 *9.1

Timeout .............................................................................................. 57Diagnostics page ...................................................................................... 55Diagram.java ............................................................................................ 61Dialog boxes ............................................................................................. 12Dynamic data types .................................................................................... 6

EEasy to use programming environment ...................................................... 6Enable routing .......................................................................................... 52ENQ limit ................................................................................................. 57EP messages ............................................................................................... 7Error code ................................................................................................. 47Error message ........................................................................................... 47Event

Channel queue length maximum ........................................................ 61Channel queue used ............................................................................ 61

Event channel object ................................................................................ 34Event object .............................................................................................. 34EventLog .................................................................................................. 46EventLog object ....................................................................................... 47Eventmeter.class ....................................................................................... 61Events ............................................................................................. 7, 19, 28Example application ........................................................................... 13, 49Example implementation of Java API ...................................................... 49Examples ............................................................................................ 11, 19exit event .................................................................................................. 30Exit event handler ..................................................................................... 20External clock ........................................................................................... 60External clock address .............................................................................. 60

FFairness count ........................................................................................... 57FALSE ...................................................................................................... 16Fatal error ................................................................................................... 9File sync criteria ....................................................................................... 52Float .................................................................................................... 37, 38Float type value ........................................................................................ 40Font .......................................................................................................... 51For customising the installation ............................................................... 13Free attributes ..................................................................................... 21, 38Free type objects ....................................................................................... 21Free type process objects .................................................................... 21, 36

GGeneral info .............................................................................................. 49General System Information .............................................................. 50, 51Generalinfo ............................................................................................... 55

70


Generalinfo.java ....................................................................................... 50Get functions ............................................................................................ 43Get*** -functions ..................................................................................... 36Get*** method ......................................................................................... 39GetAepMessage function ........................................................................... 7GetBytes() ................................................................................................. 38GetByteString() ........................................................................................ 43GetInt() ..................................................................................................... 39GetValues() function ................................................................................ 51GetValueType method .............................................................................. 39Gif-pictures ............................................................................................... 52Graphical applet ........................................................................................ 60GridBagConstraints .................................................................................. 51GridBagLayout ......................................................................................... 51

HHard drive space ....................................................................................... 13Hard drive space available ........................................................................ 13Hardware .................................................................................................. 50Hardware requirements ............................................................................ 11Hashtable .................................................................................................. 43Hashtable type of value ............................................................................ 42Hashtable type value ................................................................................. 41Help-text ................................................................................................... 62History buffer ........................................................................................... 54Host ........................................................................................................... 16Host entry ................................................................................................. 16Host sections ............................................................................................. 16Host specific information ......................................................................... 16Hot application state ................................................................................... 6HSB ............................................................................................................ 6HTML ....................................................................................................... 49HTML page .............................................................................................. 18HTML-page ........................................................................................ 61, 62

IIE .............................................................................................................. 11IIS ............................................................................................................. 12Import SCIL.* ........................................................................................... 19Index ......................................................................................................... 44Index of the event ..................................................................................... 45Individual attributes .................................................................................. 21Info.html ................................................................................................... 52Infoapplet .................................................................................................. 53Information code ...................................................................................... 47Information message ................................................................................ 47

71


SYS 600 *9.1

Inheritance ................................................................................................ 21Inherited ................................................................................................... 32Inherited objects ....................................................................................... 36INI_FILE .................................................................................................. 16Initialisation .............................................................................................. 51Initialisation time ..................................................................................... 49Input locked .............................................................................................. 56Installation .......................................................................................... 12, 49Installation disk ........................................................................................ 12Installation progress indicator .................................................................. 14Int ............................................................................................................. 51Int type of value ........................................................................................ 41Int type value ............................................................................................ 40Integer ..................................................................................... 37, 38, 39, 43Integer value ............................................................................................. 43Integers ..................................................................................................... 39Internet ....................................................................................................... 5Interval-time ............................................................................................. 61Intranet ....................................................................................................... 5IP address ........................................................................................... 11, 16IP number ................................................................................................. 15IP-Number ................................................................................................ 16

JJava

Applet ................................................................................................... 5Application ........................................................................................... 5Class ..................................................................................................... 6Environment ......................................................................................... 6

Java API ................................................................................................... 12Java applet ................................................................................................ 24Java applets ........................................................................................ 12, 15Java application ........................................................................................ 27Java applications ...................................................................................... 15Java class .................................................................................................. 18Java classes ............................................................................................... 11Java code ............................................................................................ 19, 27Java data types .......................................................................................... 27Java interpreter ......................................................................................... 27Java object ................................................................................................ 21Java program ............................................................................................ 17Java programming language ..................................................................... 11Java support .............................................................................................. 11Java.applet.* ............................................................................................. 49Java.awt.* ................................................................................................. 49Java.awt.*- ................................................................................................ 49

72


JDK ..................................................................................................... 11, 15JNI ............................................................................................................ 27Jpg -format ................................................................................................ 49JRE ........................................................................................................... 15JSSE .......................................................................................................... 12

LLabel ............................................................................................. 51, 52, 60Labeltype .................................................................................................. 49LAN

Node name .......................................................................................... 56Transport ............................................................................................. 57

Last transaction number ........................................................................... 56Layout ....................................................................................................... 51LIB 500 package ....................................................................................... 58Librevision ................................................................................................ 50License ...................................................................................................... 50Lin.txt ....................................................................................................... 57Lindiagnostics.html .................................................................................. 57Line diagrams ..................................................................................... 62, 63Line per page ............................................................................................ 57Linediagram.class ..................................................................................... 62Lininfo.class ............................................................................................. 57Link

Diagnostic counters ............................................................................ 58Diagnostics ......................................................................................... 54Number ......................................................................................... 56, 57Type .................................................................................................... 57

Link-frame .......................................................................................... 52, 54Links.html ................................................................................................. 52Linlist.class ............................................................................................... 57LINn:BDC ................................................................................................ 58List ........................................................................................................ 6, 39Listapplet ............................................................................................ 53, 54Little endian format .................................................................................. 38LN ............................................................................................................. 58Local ................................................................................................... 17, 29Local Applications .................................................................................... 18Log

Directory ............................................................................................. 57Flush timeout ...................................................................................... 57Length ................................................................................................. 57

Log_Enable ............................................................................................... 16Logged in / APL ....................................................................................... 56Logging messages .................................................................................... 16Logical Name ........................................................................................... 58

73


SYS 600 *9.1

Logo.java .................................................................................................. 50

MMain2.html ............................................................................................... 49Mapping pages ......................................................................................... 55Mapping.html ........................................................................................... 54Max_Connections .................................................................................... 15Max-value ................................................................................................. 61Memblocks.html ....................................................................................... 58Memblocks.txt .......................................................................................... 60Memmeters.html ...................................................................................... 58Memory

Block sizes ......................................................................................... 60Page .................................................................................................... 58

Memory.class ........................................................................................... 58Memorymeter ........................................................................................... 60Message data ............................................................................................ 45MicroSCADA .................................................................................. 5, 6, 12

Memory pool ........................................................................................ 6System Diagnostics ............................................................................ 50

MicroSCADA application ........................................................................ 16MicroSCADA data types ......................................................................... 27MicroSCADA events ............................................................................... 46MicroSCADA host ............................................................................. 18, 27MicroSCADA interface classes ............................................................... 19MicroSCADA messages .......................................................................... 15MicroSCADA object ................................................................................ 32MicroSCADA objects .............................................................................. 21MicroSCADA port ................................................................................... 28MicroSCADA SCIL interpreter ............................................................... 28Microsoft Internet Explorer ...................................................................... 49Mon.txt ..................................................................................................... 56Moninfo.class ........................................................................................... 56Monitor ..................................................................................................... 56Monitor number ....................................................................................... 56Monlist.class ............................................................................................. 56MON-mapping ......................................................................................... 56Multiplexer ............................................................................................... 27Multithread Java application .................................................................... 27

NNAK limit ................................................................................................. 57Name of the font ....................................................................................... 51Net list ...................................................................................................... 58Netrevision ............................................................................................... 50Netscape ................................................................................................... 11

74


New object ................................................................................................ 22New value ................................................................................................. 30NO_ACCESS ........................................................................................... 15NO_AEP ................................................................................................... 14Nod.txt ...................................................................................................... 56Node number ................................................................................ 52, 54, 56Node type .................................................................................................. 57Nodinfo.class ............................................................................................ 56Nodlist.class .............................................................................................. 56NONE ....................................................................................................... 16NT event log ....................................................................................... 16, 46NT Server ................................................................................................. 12Number of the application extension program ......................................... 29Number of the arguments ......................................................................... 45Number of the MicroSCADA application ................................................ 29Number_Of_Hosts .................................................................................... 16Numbering of the MicroSCADA application ........................................... 11

OObject

Identity ................................................................................................ 58Text ..................................................................................................... 58Value ................................................................................................... 58

Object type ................................................................................................ 21Objects Inherited From the SCIL_Object ................................................. 32OI .............................................................................................................. 58Open on job basis ..................................................................................... 57Operating system ...................................................................................... 11Output destination .................................................................................... 57OV ............................................................................................................ 58OX ............................................................................................................ 58

PPagecom ............................................................................................. 54, 58Pagecom.class ..................................................................................... 55, 58Parallel queues .......................................................................................... 54Parent class ............................................................................................... 36 .................................................................................................................. 16Passwords section ..................................................................................... 16Peer Web-server ....................................................................................... 12Picmeter.class ........................................................................................... 59Picture cache ............................................................................................. 59Picture cache size ..................................................................................... 58Preload.java .............................................................................................. 49Prg_name .................................................................................................. 18Pri.txt ........................................................................................................ 57

75


SYS 600 *9.1

Priinfo.class .............................................................................................. 57Prilist.class ............................................................................................... 57PRI-mapping ............................................................................................ 56Printer

Number ............................................................................................... 57Spooler queue length maximum ......................................................... 61Spooler queue length used ................................................................. 61

Printermeter.class ..................................................................................... 61Process object ........................................................................................... 35Process printouts ...................................................................................... 61Public BitSet getBitString() ..................................................................... 43Public BitSet getBitString(int length) ...................................................... 37Public boolean getBoolean() .............................................................. 37, 43public boolean isConnected() ................................................................... 28Public byte data(( ..................................................................................... 45Public Date getTime() ........................................................................ 37, 43Public Enumeration listAttributes() ......................................................... 44public EventLog() .................................................................................... 47Public float getFloat() ........................................................................ 37, 43Public Hashtable getList() ........................................................................ 43Public int count ........................................................................................ 45Public int getInt() ............................................................................... 37, 43Public int getSeconds() ............................................................................ 43Public int getStatus() .......................................................................... 29, 31Public int getValueType() ........................................................................ 43Public int index ........................................................................................ 45Public int length ....................................................................................... 45Public int message_type ........................................................................... 45Public SCIL_BaseSystemObject(String name, int apl) ........................... 32Public SCIL_BaseSystemObject(String name, SCIL_Connectionconn, int apl) ............................................................................................. 32Public SCIL_CommandProcedureObject(String name, int apl) .............. 33Public SCIL_CommandProcedureObject(String name, SCIL_Connection conn) ........................................................................... 33Public SCIL_Connection(String address) ................................................ 27public SCIL_Connection(String address, int port) ................................... 28public SCIL_Connection(String address, int port, String name, String password) ....................................................................................... 28public SCIL_Connection(String address, String name, String password) 28Public SCIL_DataObject(String name, int apl) ........................................ 33Public SCIL_DataObject(String name, SCIL_Connection conn, int apl) 33Public SCIL_EventChannelObject(String name, int apl) ........................ 34Public SCIL_EventChannelObject(String name, SCIL_Connectionconn, int apl) ............................................................................................. 34Public SCIL_EventObject(String name, int apl) ...................................... 34Public SCIL_EventObject(String name, SCIL_Connection conn, int apl) 34

76


Public SCIL_FreeTypeObject(String name, int apl_num) ....................... 37Public SCIL_FreeTypeObject(String name, SCIL_Connection conn, int apl_num) .................................................................................... 37Public SCIL_Interface() ........................................................................... 28Public SCIL_Interface(int apl) ................................................................. 29Public SCIL_Interface(int apl, int program_number) .............................. 29Public SCIL_Interface(SCIL_Connection conn) ..................................... 29Public SCIL_Interface(SCIL_Connection conn, int apl) ......................... 29Public SCIL_Message getAepMessage(int timeout) ................................ 31Public SCIL_Message() ............................................................................ 46Public SCIL_Message(int type) ............................................................... 46Public SCIL_ProcessObject(String name, int apl) ................................... 35Public SCIL_ProcessObject(String name, SCIL_Connection conn, int apl) ............................................................................................. 35Public SCIL_ScaleObject(String name, int apl) ....................................... 35Public SCIL_ScaleObject(String name, SCIL_Connection conn, int apl) 35Public SCIL_SSL_Connection(String address) ....................................... 28public SCIL_SSL_Connection(String address, int port) .......................... 28public SCIL_SSL_Connection(String address, int port, String name, String password) ................................................................. 28public SCIL_SSL_Connection(String address, String name, String password) ....................................................................................... 28Public SCIL_SystemObject(String name, int apl) .................................... 35Public SCIL_SystemObject(String name, SCIL_Connection conn, int apl) ....................................................................................................... 36Public SCIL_TimeChannelObject(String name, int apl) .......................... 36Public SCIL_Value arguments(( .............................................................. 45Public SCIL_Value elementAt(int index) ................................................ 44Public SCIL_Value evaluateExpression(String expression) .................... 30Public SCIL_Value getAttribute(String name) .................................. 32, 44Public SCIL_Value getAttribute(String name, int start, int end) ............. 32Public SCIL_Value getVariable(String name) ......................................... 30Public SCIL_Value() ................................................................................ 40Public SCIL_Value(BitSet value .............................................................. 40Public SCIL_Value(boolean value) .......................................................... 40Public SCIL_Value(Date value) ............................................................... 40Public SCIL_Value(float value) ............................................................... 40Public SCIL_Value(Hashtable value) ...................................................... 41Public SCIL_Value(int value) .................................................................. 40Public SCIL_Value(String value) ............................................................. 40Public SCIL_Value(Vector value) ........................................................... 41Public static variables ............................................................................... 53Public String getName() ........................................................................... 31Public String getString() ........................................................................... 43Public String getString(int length) ............................................................ 37Public String name ................................................................................... 45

77


SYS 600 *9.1

Public Vector getVector() ........................................................................ 43Public void activateObject(int index) ....................................................... 32Public void addElement(SCIL_Value v) .................................................. 44Public void bitClear(int bit) ..................................................................... 45Public void bitSet(int bit) ......................................................................... 45Public void cancelEventSubscription(String name, int index) ................. 30Public void cancelExitEventSubscription() ............................................. 30Public void closeSCIL_Connection() ...................................................... 28Public void executeCommand(String command) .................................... 29Public void readAttributes() ..................................................................... 37Public void sendAepMessage(int aep_num, SCIL_Message msg) .......... 31Public void setAttribute(String name, int start, int end, SCIL_Value value) ................................................................................... 31Public void setAttribute(String name, SCIL_Value v) ............................ 44Public void setAttribute(String name, SCIL_Value value ....................... 31Public void setBitString(BitSet bset, int length) ...................................... 38Public void setBoolean(boolean value) .................................................... 38Public void setElementAt(SCIL_Value v, int index) ............................... 44Public void setFloat(float value) .............................................................. 38Public void setInt(int value) ..................................................................... 38Public void setString(String str, int length) .............................................. 38Public void setTime(Date value) .............................................................. 38Public void setTime(int seconds .............................................................. 42Public void setValue(BitSet value) .......................................................... 42Public void setValue(boolean value) ........................................................ 41Public void setValue(Date value) ............................................................. 42Public void setValue(float value) ............................................................. 41Public void setValue(Hashtable value) .................................................... 42Public void setValue(int value) ................................................................ 41Public void setValue(String value) .......................................................... 41Public void setValue(Vector value) ......................................................... 42Public void setVariable(String name, SCIL_Value value) ...................... 30Public void subscribeEvent(String name, int index) ................................ 30Public void subscribeExitEvent() ............................................................. 30Public void writeAttributes() .................................................................... 37public void writeUserAuditFailure(int userAuditCode, String auditStr) . 47public void writeUserAuditSuccess(int userAuditCode, String auditStr) 47public void writeUserError(int userErrorCode, String errorStr) .............. 47public void writeUserInformation(int userInfoCode, String infoStr) ...... 47public void writeUserWarning(int userWarningCode, String warningStr) 47

RREAD ....................................................................................................... 15Read variables .......................................................................................... 19READ_WRITE ........................................................................................ 15ReadAttributes method ............................................................................. 36

78


Real ........................................................................................................... 39Real value ................................................................................................. 43Receiver thread ......................................................................................... 28Redundancy .............................................................................................. 57Registration date and time ........................................................................ 56Remote ................................................................................................ 17, 29Remote Java applications/applets ............................................................. 17Remote programs ...................................................................................... 27Repmeter.class .......................................................................................... 59Report cache ............................................................................................. 59Report cache size ...................................................................................... 58Requirements ............................................................................................ 11Runtime exception ............................................................ 39, 41, 42, 43, 44

SScale object ............................................................................................... 35SCIL ................................................................................................... 49, 58

Commands ............................................................................................ 6Printouts .............................................................................................. 61

SCIL commands ....................................................................................... 19SCIL data types ........................................................................................ 39SCIL expression ....................................................................................... 30SCIL Interface .......................................................................................... 19SCIL package ..................................................................................... 22, 24SCIL time ........................................................................................... 39, 43Scil time .................................................................................................... 38Scil time value .......................................................................................... 37SCIL variable ............................................................................................ 30SCIL.* ...................................................................................................... 49SCIL.cab ....................................................................................... 11, 14, 17SCIL.jar .................................................................................... 6, 11, 14, 17SCIL_ EP_MESSAGE_SCIL .................................................................. 46SCIL_ LIST _TYPE ................................................................................. 41SCIL_ LIST_TYPE .................................................................................. 43SCIL_ TIME _TYPE. ............................................................................... 40SCIL_ VECTOR _TYPE ......................................................................... 41SCIL_ALL_OBJECT_INDEX ........................................................... 30, 46SCIL_BIT_STRING_TYPE ................................................... 39, 40, 42, 43SCIL_BOOLEAN_TYPE ...................................................... 39, 40, 41, 43SCIL_BYTE_STRING_TYPE ..................................................... 39, 40, 42SCIL_Connection ......................................................................... 18, 19, 27SCIL_Connection class ............................................................................ 17SCIL_EP_MESSAGE_EP ....................................................................... 46SCIL_EP_MESSAGE_EVENT ......................................................... 45, 46SCIL_EP_MESSAGE_EXIT ................................................................... 46SCIL_EP_MESSAGE_NONE ........................................................... 45, 46

79


SYS 600 *9.1

SCIL_EP_MESSAGE_SCIL ............................................................. 45, 46SCIL_FILE ............................................................................................... 16SCIL_FreeTypeObject ....................................................................... 21, 37SCIL_INTEGER_TYPE ........................................................ 39, 40, 41, 43SCIL_Interface ........................................................................... 6, 7, 18, 28Scil_jni.dll ................................................................................................ 14SCIL_LIST_TYPE ....................................................................... 39, 42, 44SCIL_MAX_EP_MESSAGE_ARGUMENTS ........................................ 46SCIL_Message ..................................................................................... 7, 46SCIL_NO_TYPE ......................................................................... 39, 40, 43SCIL_Object classes ................................................................................ 18SCIL_REAL_TYPE ............................................................... 39, 40, 41, 43SCIL_SSL_Connection ............................................................................ 28SCIL_TEXT_TYPE ............................................................... 39, 40, 41, 43SCIL_TIME_TYPE ..................................................................... 39, 42, 43SCIL_Value .............................................................................. 7, 30, 41, 44SCIL_Value object ............................................................................. 41, 42SCIL_Values ............................................................................................ 39SCIL_VECTOR_TYPE ......................................................... 39, 42, 43, 44Scil2java ....................................................................................... 16, 17, 27Scil2java.exe ...................................................................................... 14, 18Seconds ........................................................................................ 39, 42, 43Select dialog box ................................................................................ 13, 14SELECT-function .................................................................................... 58Semigraphic .............................................................................................. 56Sensible value ........................................................................................... 39Server ................................................................................................... 5, 15Server process .......................................................................................... 17Server use ................................................................................................. 12Service pack ............................................................................................. 11Set*** -methods ....................................................................................... 36SetValue(***) functions ........................................................................... 39Shadowing

Connection time ................................................................................. 55Diagnostic interval ............................................................................. 55Event channel queue ........................................................................... 55Flush time ........................................................................................... 55Number ............................................................................................... 55Phase .................................................................................................. 55Receive timeout .................................................................................. 55State .................................................................................................... 55Watchdog ........................................................................................... 56

Simultaneous connections ........................................................................ 15Site information ........................................................................................ 50Software ................................................................................................... 50Software requirements .............................................................................. 11

80


Source -code ............................................................................................. 49Source disk ............................................................................................... 14SSL encoding ...................................................................................... 16, 28SSL_Enabled ............................................................................................ 16Stalist.class ............................................................................................... 58STA-mapping ........................................................................................... 56Start button ............................................................................................... 61Start command .......................................................................................... 57State .................................................................................................... 54, 57Station ....................................................................................................... 56

Address ......................................................................................... 52, 56Applet ................................................................................................. 58List ...................................................................................................... 58

Status code .......................................................................................... 10, 31Status value ............................................................................................... 29Stop method .............................................................................................. 28String .................................................................................................. 37, 51String type of value .................................................................................. 41String type value ....................................................................................... 40Subscription .............................................................................................. 30Subscription of events .............................................................................. 46Sun Microsystems .................................................................................... 11SYS:BMS * SYS:BMU ............................................................................ 60SYS_ directory ......................................................................................... 15Sys_java.ini .............................................................................................. 15Sysconfiguration.java ............................................................................... 52System

Device name ................................................................................. 56, 57Diagnostics program ........................................................................... 49Machine name .................................................................................... 50Self Supervision .................................................................................. 58

System object ............................................................................................ 35

TTCP/IP network ........................................................................................ 27TCP/IP port ............................................................................................... 27TCP/IP socket ........................................................................................... 27Technical reference .................................................................................. 27Temp directory ................................................................................... 56, 57Terminating the installation ...................................................................... 13Text ........................................................................................................... 39Text string ................................................................................................. 43The Java API server .................................................................................. 18The Java Classes ....................................................................................... 27Time

Limit ..................................................................................................... 7

81


SYS 600 *9.1

Season ................................................................................................ 60Synchronisation interval ..................................................................... 56Zone .................................................................................................... 60

Time channel object ................................................................................. 36Time.class ................................................................................................. 60Timeout .................................................................................................... 31

Length .......................................................................................... 52, 57Value .................................................................................................... 7

Toolrevision ............................................................................................. 50Total

Memory size ....................................................................................... 58Memory usage .................................................................................... 58

Translated object number ................................................................... 54, 57Translation type .................................................................................. 56, 57Translations .............................................................................................. 27TrimText(String) ...................................................................................... 54TRUE ....................................................................................................... 16Type .................................................................................................... 54, 56

UURL location ............................................................................................ 18User .................................................................................................... 15, 36User defined attributes ............................................................................. 36Using the Java API ................................................................................... 17

VVector ................................................................................. 6, 39, 44, 56, 60Vector object ............................................................................................ 43Vector type of value ................................................................................. 42Vector type value ..................................................................................... 41Vu-meter ................................................................................................... 59Vu-meter applet ........................................................................................ 59Vumeter.class ........................................................................................... 58

WWarning

Label ................................................................................................... 58Limit ................................................................................................... 59

Warning code ........................................................................................... 47Warning message ..................................................................................... 47Welcome dialog box ................................................................................. 13Windows INI-files .................................................................................... 15WriteAttributes method ............................................................................ 36WWW-browser ........................................................................................ 11WWW-server ............................................................................... 12, 17, 18

82


XX-axis ....................................................................................................... 60X-coordinates ........................................................................................... 51

YY-axis ....................................................................................................... 62Y-coordinates ........................................................................................... 51

83

ABB OySubstation Automation ProductsP.O. Box 699FI-65101 VaasaFINLANDTel. +358 10 22 11Fax. +358 10 224 1094www.abb.com/substationautomation

1MR

S75

1851

-ME

N E

N 0

2.20

05

java programming interface (java-api) - abb group · 1mrs751851-men sys 600 *9.1 7 microscada pro...

Documents