1mrs751250-men microscada issue date: 29.02.00 … · this chapter introduces the scil programming...

1MRS751250-MENIssue date: 29.02.00

Program revision: 8.4.3

Documentation version: A

Copyright © 2000 ABB Substation Automation OyAll rights reserved.

MicroSCADAProgramming Language

SCIL

Notice 1

The information in this document is subject to change without notice and should notbe construed as a commitment by ABB. ABB assumes no responsibility for any errorthat may occur in this document.

Notice 2

This document version complies with the program revision 8.4.3.

Notice 3

Additional information such as Release Notes and Last Minute Remarks can be foundon the program distribution media.

Trademarks

Microsoft is a trademark of Microsoft Corporation.

Windows NT is a trademark of Microsoft Corporation.

LONWORKS is a registered trademark of Echelon Corporation.

Other brand or product names are trademarks or registered trademarks of their respective holders

All Microsoft products referenced in this document are either trademarks or registered trademarks of Microsoft.

MicroSCADA Programming LanguageSCILTechnical Reference Manual

1MRS751250-MEN

ABB Automation

Related SYS 500 and MicroSCADA Technology Manuals

The following SYS 500 manuals are published with this software release:

Installation 1MRS751254-MEN

Picture Editing 1MRS751255-MEN

Visual SCIL User Interface Design 1MRS751256-MEN

Visual SCIL Objects 1MRS751257-MEN

System Management 1MRS751258-MUM

The following MicroSCADA technology manuals are published with this softwarerelease:

Connecting LONWORKS Devices to MicroSCADA 1MRS751249-MEN

System Configuration 1MRS751248-MEN

System Objects 1MRS751252-MEN

Application Objects 1MRS751253-MEN

Programming Language SCIL 1MRS751250-MEN

Status Codes 1MRS751251-MEN

1MRS751250-MEN Programming LanguageSCILTechnical Reference Manual

MicroSCADA

ABB Automation

Contents

Page

1 Introduction....................................................................................... 1

1.1 Presentation of SCIL ..............................................................................1

1.2 SCIL Programs.......................................................................................4

1.3 SCIL Statements ....................................................................................5

1.4 Organization of this Manual ....................................................................6

2 Programming in SCIL ....................................................................... 9

2.1 SCIL Programming Environment ............................................................9

2.2 SCIL Programming Rules .....................................................................15

3 Data Types....................................................................................... 19

3.1 General ................................................................................................19

3.2 Integer ..................................................................................................19

3.3 Real......................................................................................................20

3.4 Boolean ................................................................................................21

3.5 Time .....................................................................................................21

3.6 Text ......................................................................................................22

3.7 Bit String...............................................................................................22

3.8 Byte String............................................................................................23

3.9 Vector...................................................................................................23

3.10 List .....................................................................................................24

4 Objects............................................................................................. 25

4.1 General ................................................................................................25

4.2 System Objects ....................................................................................26

4.2.1General ..........................................................................................26

4.2.2Base System Objects (B) ...............................................................28

4.2.3Communication System Objects ....................................................29

4.3 Application Objects...............................................................................30

4.3.1General ..........................................................................................30


1MRS751250-MEN

ABB Automation

4.3.2Process Objects (P)....................................................................... 32

4.3.3Scales (X) ...................................................................................... 34

4.3.4Data Objects (D)............................................................................ 35

4.3.5Command Procedures (C) ............................................................. 36

4.3.6Time Channels (T) ......................................................................... 37

4.3.7Event Channels (A)........................................................................ 38

4.3.8Event Objects (E) .......................................................................... 39

4.3.9Variable Objects (V)....................................................................... 40

4.4 User Interface Objects ......................................................................... 41

4.4.1Pictures ......................................................................................... 41

4.4.2Visual SCIL Objects....................................................................... 45

5 Variables .......................................................................................... 49

5.1 General Rules ...................................................................................... 49

5.2 Using Variables.................................................................................... 50

5.3 Predefined Picture Variables................................................................ 53

6 Expressions..................................................................................... 57

6.1 General Principles................................................................................ 57

6.2 Arithmetical Operators ......................................................................... 58

6.3 Relational Operators ............................................................................ 63

6.4 Logical Operators................................................................................. 64

7 SCIL Commands ............................................................................. 67

7.1 General ................................................................................................ 67

7.2 Picture Handling Commands................................................................ 69

7.2.1General Picture Handling Commands............................................ 70

7.2.2Window Handling Commands........................................................ 74

7.2.3Input Commands ........................................................................... 81

7.2.4Miscellaneous Picture Commands................................................. 84

7.3 Control Commands .............................................................................. 85

7.3.1Program Execution Commands ..................................................... 85

7.3.2General Object Handling Commands ............................................ 92

7.3.3Object Query Commands .............................................................. 97

7.3.4Printout Commands..................................................................... 100

7.3.5Error Handling Commands .......................................................... 102


MicroSCADA

ABB Automation

7.3.6Path Commands ..........................................................................104

7.3.7File Handling Commands .............................................................107

7.3.8Miscellaneous Commands ...........................................................113

7.4 Visual SCIL Commands......................................................................113

7.4.1Loading, Creating and Deleting Visual SCIL Objects....................114

7.4.2Handling Visual SCIL Attributes ...................................................116

7.5 VS Object, Window and Picture Function Methods.............................117

7.6 VS Object, Window and Picture Function Attributes ...........................118

8 Functions....................................................................................... 121

8.1 General ..............................................................................................122

8.2 Arithmetical Functions ........................................................................128

8.3 Time Functions...................................................................................131

8.4 String Functions..................................................................................135

8.5 Bit Functions.......................................................................................143

8.6 Vector Handling Functions..................................................................146

8.7 Database and List Functions ..............................................................155

8.8 Functions for Reading and Writing Files .............................................174

8.9 Functions Related to Program Execution............................................179

8.10 Communication Functions ................................................................184

8.11 File and Directory Handling Functions..............................................186

8.12 File and Directory Management Functions .......................................201

8.13 DDE Client Functions .......................................................................207

8.14 DDE Server Functions......................................................................212

8.15 ODBC Functions ..............................................................................213

8.16 RTU Functions .................................................................................219

8.17 Printout Functions ............................................................................223

8.18 Error Tracing Functions....................................................................227

8.19 Data Type Handling Functions .........................................................228

8.20 Miscellaneous Functions ..................................................................231

9 Graphics Primitives ...................................................................... 241

9.1 Introduction.........................................................................................241

9.2 Full Graphics SCIL Commands ..........................................................242

9.2.1Drawing Graphical Elements........................................................242

9.3 Graphics Contexts ..............................................................................248


1MRS751250-MEN

ABB Automation

9.3.1General........................................................................................ 248

9.3.2Defining Graphics Contexts ......................................................... 249

9.3.3Components of Graphics Contexts .............................................. 250

9.3.4Colors and Fonts ......................................................................... 256

9.3.5Reading Graphics Contexts ......................................................... 260

9.4 Graphics Canvas ............................................................................... 260

9.5 Miscellaneous Graphical Commands ................................................. 265

9.5.1Storing and Restoring Selections................................................. 265

9.5.2Display Handling Commands....................................................... 265

10Using Motif Widgets in SCIL ....................................................... 267

10.1 General............................................................................................ 267

10.2 Widget Handling Commands ........................................................... 268

10.3 Widget Methods............................................................................... 270

10.4 Widget Resources ........................................................................... 271

10.4.1 General ..................................................................................... 271

10.4.2 Resources in SCIL .................................................................... 271

10.4.3 Resource Data Types ............................................................... 272

10.4.4 Writing Widget Resources......................................................... 274

10.4.5 Reading Widget Resources ...................................................... 275

10.4.6 Auxiliary Functions.................................................................... 275

11SCIL Programming Guide ........................................................... 277

11.1 Picture Handling .............................................................................. 277

11.2 Visual SCIL Object Handling............................................................ 278

11.3 Program Execution .......................................................................... 279

11.4 Process Supervision and Control..................................................... 280

11.5 Alarm and Event Handling ............................................................... 280

11.6 Calculations and Reports................................................................. 281

11.7 System Configuration and Communication ...................................... 281

11.8 Application Database Management ................................................. 281

11.9 Error Handling.................................................................................. 282

12SCIL Editor ................................................................................... 285

12.1 General............................................................................................ 285

12.2 Menus.............................................................................................. 285


MicroSCADA

ABB Automation

12.3 Toolbar.............................................................................................289

12.4 Opening and Closing the SCIL Editor...............................................289

12.5 Typing and Editing Programs and Texts...........................................291

13The SCIL Compiler....................................................................... 299

13.1 General ............................................................................................299

13.2 Performance Improvement...............................................................299

13.3 Impact on SCIL Programs ................................................................299

13.3.1 Programs that do not Compile...................................................300

13.3.2 Programs that Generate Run-time Error....................................300

13.3.3 Programs that Produce Wrong Results .....................................301

13.3.4 Recommendations ....................................................................301


MicroSCADA1 Introduction

ABB Automation 1

1 Introduction

This chapter introduces the SCIL programming language, the MicroSCADA applica-tion engineering, and the SCIL program structure.

1.1 Presentation of SCIL

What is SCIL?

SCIL, Supervisory Control Implementation Language, is a high level language espe-cially designed for the application engineering of the supervisory control system Mi-croSCADA. All MicroSCADA application programs as well as most system configu-ration programs are built in SCIL.

What is Application Engineering?

In MicroSCADA, ’application engineering’ means the composition of customized,process specific supervisory control software. The result is an application softwarepackage adapted for the user’s needs regarding control functions, communicating pro-cess devices, user interface, level of information, etc. A base system contains one ormore application software packages named applications. The application engineeringcomprises:

• Functional design, i.e. the programming and definition of the SCADA functionsas well as other supervisory control and calculation functions.

• User interface design.

The functional design involves the definition of databases (a database = a set of con-nected data stored in a structured form) and the creation of SCIL programs. Each ap-plication has a process database for handling process supervision and a report data-base for data storage, calculations, automatic activation, etc. The databases are com-posed of objects named application objects.

The user interface design involves the composition of pictures and dialogs. See Figure1. Pictures are dynamic illustrations containing a static background, dynamic win-dows and user activated function keys. Dialogs are independent windows which maycontain a wide range of user interface items, such as menus, buttons, images, note-books, and pictures. Pictures and dialogs represent two different user interface designmethods. The design and programming of dialogs and dialog systems is named “Vis-ual SCIL”.

These two portions of an application are interwoven with each others, and the userinterface design and the functional design generally occur in parallel.

Application engineering is simplified by using the standard application software li-brary, LIB 500, which requires a minimum of object definitions and SCIL program-ming. In any case, SCIL is found in all MicroSCADA applications, even in those


Programming LanguageSCILTechnical Reference Manual

1MRS751250-MEN

ABB Automation2

which are built with LIB 500, because the LIB 500 standard application software isbuilt with SCIL.

Figure 1. A MicroSCADA screen view showing three dialogs, one containing a picture.

The application engineering using LIB 500 is discussed in the LIB 500 User’s Guide.The user interface design is described in the Visual SCIL User Interface Design andthe Picture Editing manuals.

What You Can Do with SCIL

By means of SCIL you can control the entire MicroSCADA system, not only the fea-tures related to the application, but also features related to the system configurationand communication. With SCIL as your tool you can for instance (as shown in Figure2):

• Program the user interface portion of the application, e.g. define the dynamicchanges in pictures and dialogs, and program operator activated function keysand buttons.

• Design various forms of process control, such as manual control, sequentialcontrol, time control, event control, etc.

• Define routines for calculation and updating in databases to be started automati-cally or manually.

• Design reports for presentation on monitor screens or for paper printout.



ABB Automation 3

• Configure, supervise and handle system components, for example printers andmonitors.

• Build process simulations.

• Exchange data with other MicroSCADA applications and with external (not Mi-croSCADA) applications (e.g. office applications).

Learning SCIL requires no previous knowledge of "conventional" programming.

Figure 2. Features controlling the SCIL program execution and features con-trolled by SCIL



1MRS751250-MEN

ABB Automation4

1.2 SCIL Programs

Composition

A SCIL program is composed of one or more textual statements. Each statement rep-resents an instruction to the system about a task to be carried out, e.g. the presentationof a picture or the assignment of a variable value. Consecutive statements mean a se-quence of instructions, which are carried out in the prescribed order.

Occurrence

SCIL programs appear in pictures, in command procedures (objects for automatic orSCIL activated program execution), and in the dialogs and dialog items (Visual SCILobjects). More information about this will be given in Chapter 2.

Activation of SCIL Programs

The SCIL programs can be started manually or automatically, for example:

• The function keys in pictures and the buttons in dialogs contain SCIL programswhich are started manually by the operator.

• The pictures and dialogs can contain programs which are started automaticallywhen a picture is entered or exited, periodically with a certain time interval, andon the occurrence of a process event.

• The command procedures can start automatically by real or simulated processevents, by time, from other SCIL programs, etc.

• SCIL programs can be started by a SCIL command or a program call.

Example

The example in Figure 3 gives an insight into what a SCIL program can look like. Theprogram could be placed under a function key in a picture, which means that it is exe-cuted each time the key is pressed. The purpose of the program is to bring a newpicture called MENU on screen provided that a password is given correctly (999).



ABB Automation 5

Figure 3. A SCIL program for the input and control of a password

1.3 SCIL Statements

Components

Each line in the program example in Figure 3 is a SCIL statement. (A statement couldalso be continued on several lines.) A SCIL statement may consist of the followingmain components:

• Commands. These are words with a pre-declared meaning constituting orders tothe system about steps to be taken. In the example in Figure 3 each program linestarts with a command.

• Objects. Object is a broad concept which may correspond to physical parts ofthe system or the process, database items, user interface objects, or abstractfunctions specific to the MicroSCADA system.

• Variables. Variables are facilities for the temporary storage and use of changingdata. In the example in Figure 3, WORD is a variable.

• Function calls. SCIL has a large number of pre-defined functions for variouspurposes.

• Expressions. Expressions are formulas which can contain constants, object no-tations, variables, function calls and operators (e.g. +, - , /, *).

Statement Format

The components above can be combined into statements according to one of the fol-lowing three formats :

command {arguments} (1)

variable = expression (2)

name.program {arguments} (3)

Type (1) (described in Chapters 7, 9 and 10) implies that an action is performed on orby means of the arguments. The arguments may be object references, expressions,



1MRS751250-MEN

ABB Automation6

variables, names, etc. Some commands do not require any arguments, they are as suchcomplete statements. In some cases the arguments may contain statements. The com-mand names start with a ! (picture commands), # (control commands) or . (VisualSCIL, full graphics and Motif commands).

Type (2) (described in Chapter 5) implies that a variable gets a value. The variable as-signment starts with an @-sign.

Type (3) is a program call which starts a program execution in a picture, dialog ordialog item. This type is described in Chapter 4.

1.4 Organization of this Manual

This manual is composed of 13 chapters, which have the following contents:

Chapter 1. This introduction.

Chapter 2. Describes the tools for SCIL programming, the rules concerningthe structure of SCIL programs, SCIL characters and naming SCILelements.

Chapter 3. Describes the different SCIL data types allowed for data and ex-pressions included in SCIL programs and expressions.

Chapter 4. Describes briefly the different object types - system objects, appli-cation objects, user interface objects - and how they are handled inSCIL.

Chapter 5. Describes the use of variables in SCIL: how to assign values tovariables and how to use them, how to handle vector variables,pre-defined picture variables.

Chapter 6. Describes the construction of SCIL expressions.

Chapter 7. Describes the SCIL commands - picture handling commands, con-trol commands and Visual SCIL commands.

Chapter 8. Describes the pre-declared SCIL functions which can be includedin expressions.

Chapter 9. Describes the lowest level of the full graphics handling (generallynot needed for ordinary application engineering).

Chapter 10. Describes the handling of Motif Widgets (not needed for ordinaryapplication engineering).

Chapter 11. Provides a programmer’s quick guide.

Chapter 12. Describes the SCIL Program Editor.

Chapter 13. Describes the SCIL Compiler.



ABB Automation 7

After chapter 13, you will find a list of subject indices.

Appendix A contains a collection of new SCIL features in MicroSCADA 8.4.

Appendix B contains a list of ODBC error codes.

Appendix C lists Parameter Files.

At the end of the manual, you will find the customer feedback instructions.


MicroSCADA2 Programming in SCIL

ABB Automation 9

2 Programming in SCIL

This chapter describes the SCIL programming environment and the rules for pro-gramming in SCIL:

2.1 The programming environment: the MicroSCADA objects where SCILprograms and expressions are found, the programming tools in brief, the use ofSCIL expressions in external applications via DDE.

2.2 Programming rules: The structure of the SCIL programs, SCIL characters,SCIL names.

2.1 SCIL Programming Environment

General

SCIL programs appear in:

• Pictures.

• Dialogs and dialog items (Visual SCIL objects).

• Command procedures.

In addition, SCIL expressions appear in window, data object and time channel. SCILexpressions can also be entered in external Windows based applications and executedthrough DDE (Dynamic Data Exchange).

SCIL programming is carried out while the MicroSCADA system is running. Duringprogram editing the system does not perform any SCIL syntax error control. To testSCIL programs, statements and expressions, use the test tool accessed from the ToolManager.

The subsequent presentation of the programming environment assumes that you use aMicroSCADA monitor (application session) of type “VS”. In other monitor types(semi-graphic monitors or “X” type monitors) the programming tools are semi-graphic. “X” type monitors are required if the application contains Motif Widgets. Inall other cases, use “VS” type monitors. You choose monitor type when you open aMicroSCADA monitor or screen.

SCIL Program Editor

SCIL programs are written in the SCIL Program Editor which is accessed from toolpictures and from the Tool Manager. The SCIL Program Editor is opened from thePicture Editor, the Dialog Editor and the Command Procedure object definition tool.

The SCIL Program Editor is described in Chapter 12 of this manual.



1MRS751250-MEN

ABB Automation10

Picture Programs

A dynamic picture is composed of a static background, windows, function keys,SCIL-programs and picture functions. Windows are the dynamic parts of the picture.They can present data fields, graphs, figures or complete pictures. The picture func-tions are complete pictures which are integrated in the total picture. Picture functionsand window pictures (pictures shown in a window) are commonly called "part pic-tures" or "sub-pictures", while the total picture is called “main picture”.

Pictures are built and programmed in the Picture Editor where they can be namedfreely. The pictures and picture editing are described in the manual " MicroSCADAPicture Editing".

A picture may contain the following types of picture programs (none of them isobligatory):

• A draw program executed every time the picture is loaded on screen, immedi-ately after the background has been produced on screen but before the start pro-gram is executed. It can, e.g., be used for adding context specific graphics to thebackground by means of graphics commands.

• A start program executed after the draw program. The start program is used forbasic definitions such as initial variable values, update interval, and programblocks.

• An update program, which is executed repeatedly at intervals defined by a SCILcommand (the !UPDATE command, see Chapter 7) as long as the picture is dis-played on screen. The update program should be kept as small as possible.

• An exit program, which is executed each time the picture is exited (even at exitby clicking three times in the upper left corner of the picture).

• Function key programs executed at each click on the function keys to which theybelong.

• Named programs executed by program calls. A SCIL picture may contain anynumber of named SCIL programs. The named programs are started by programcalls as described in section 4.4. The named program names may be up to 63characters long. Each picture may contain a named program with a predefinedname, ERROR_HANDLER, where the programmer can define the error han-dling to be used in the picture. The ERROR_HANDLER program is described inChapter 11.

Besides these programs, the picture contains a background program which is createdautomatically by the picture editor. The background program contains graphics com-mands. Normally, it should not be edited manually.

Window Definitions

The window definitions, see Figure 4, may contain expressions which specify what isto be shown in the windows. The expression of a window is evaluated each time the



ABB Automation 11

window is shown. The window definitions may also contain conditions for the displayof different representations. Both the expressions and the conditions follow the rulesof SCIL.

Figure 4. An example of a window definition

Methods

Each dialog and dialog item can have a number of methods most of which are SCILprograms. (There are also predefined methods which are programmed in C, but theseare not editable).

A dialog or a dialog item may contain the following SCIL programs (methods):

• Methods started at the creation and deletion of the object.

• Cyclically activated methods.

• Event activated methods started by a process event or an event activated bySCIL (through event objects, see section 4.3.).

• Action methods started on an operator intervention (for example, a click on abutton).

• A help method started when help is requested.

• An error handling method.



1MRS751250-MEN

ABB Automation12

In addition, each dialog and dialog item may have an arbitrary number of user definedmethods which are executed by a method call (see section 4.4.).

The methods of the dialogs and dialog items are programmed in the Dialog Editor.The composition and programming of dialogs is described in the manual Visual SCILUser Interface Design.

Command Procedures

A command procedure is an independent SCIL program consisting of up to 10000lines (see Figure 5). A command procedure can be started from a picture program, atime channel (see below), an event channel (controller of event-bound activities) or aSCIL program.

Command procedures are described in the manual “ MicroSCADA, Application Ob-jects".

Figure 5. An example of a command procedure



ABB Automation 13

Data Objects

The data objects (datalog objects) are objects for the registration and storage of data.The object definition, see Figure 6, contains a SCIL expression which states how thedata is to be calculated.

Data objects are described in the manual "Application Objects".

Figure 6. An example of a data object definition

Time Channels

The time channels control the execution of time-bound activities. By conditions whichare SCIL expressions, see Figure 7, the initialization times and execution times canbe restricted, so that an initialization or an execution can only occur when the condi-tions are fulfilled.

Time channels are described in the manual "Application Objects".



1MRS751250-MEN

ABB Automation14

Figure 7. An example of a time channel definition

Using SCIL in External Applications

MicroSCADA applications can be accessed from external Windows applications us-ing the DDE protocol, so that the MicroSCADA application works as a DDE serverand the other application works as a DDE client.

The DDE identifiers service, topic and item have the following meanings when ac-cessing a MicroSCADA application:

Service = MicroSCADA

Topic = MicroSCADA application number (APL object number, see theSystem Configuration manual)

Item, data = Item and data depends on the DDE transaction as follows: REQUEST: item = SCIL expressionPOKE: item = SCIL object notation

data = SCIL expressionEXECUTE: item = SCIL statement.



ABB Automation 15

The DDE Server function in MicroSCADA supports the following SCIL data types(see Chapter 3): integer, real, text, boolean. There are some SCIL functions which canbe used in the composition of the expressions used via DDE. See the DDE ServerFunctions in Chapter 8.

When handling data using DDE Server, occurred SCIL errors are preserved, so thatthe user can read afterwards the last SCIL status code of each DDE conversation bydoing a request transaction giving "DDE_SCIL_STATUS_CODE" as Item value.

Accessing a MicroSCADA application using the DDE Server requires that the DDEServer has been enabled in the base-system configuration (the SYS:BDE attribute).

For more information about using DDE, refer to the DDE documentation of the Win-dows Application you are using.

SCIL Test Tool

The test dialog accessed from the Tool Manager allows the programmer to enter indi-vidual SCIL statements and expressions as well as programs. It also provides meansfor detailed examination of the SCIL expressions. The SCIL Test tool is described inthe System Management manual.

2.2 SCIL Programming Rules

Program Structure

A SCIL program can contain up to 10000 lines, and each line up to 255 characters(including spaces). A SCIL statement comprises one or more lines. A minus sign (-) atthe end of a SCIL line, before a possible comment, indicates that the statement con-tinues on the next line. A line may be divided anywhere where spaces are allowed, butnot within text constants. The statements are not numbered and empty lines are al-lowed anywhere in the programs.

Spaces are allowed anywhere in the program except within numbers, words, names,object notations and composed symbols. These elements, disregarding operators, mustbe adjacent to at least one space at each side. Also the operators DIV and MOD (seeChapter 6) must be adjacent to spaces.

Upper and lower case letters may be freely intermixed. When the program is exe-cuted, lower case letters are converted into upper case, except for lower case letterswithin text constants (see Chapter 3).

The SCIL programs do not demand any initiating or terminating statements, neitherany kind of declarations.

Comments can be placed anywhere in the program. They are preceded by a semicolon(;), which indicates that the rest of the line is a comment. However, if the semicolon isenclosed in quotation marks (";"), it is regarded as a text (see Chapter 3).



1MRS751250-MEN

ABB Automation16

Examples

The following two SCIL-programs are functionally equivalent:

Example 1:@T = TEMP:PAI1#IF %T> 90 #THEN #BLOCK#SET C:PBO2=0#PRINT 2 OVERHEAT#BLOCK_END#ELSE_IF %T< 70 #THEN #SET C:PBO2=1

Example 2:@T = TEMP:PAI1; READ THE TEMPERATURE#IF %T > 90 #THEN #BLOCK; IF WARMED OVER 90

#SET C:PBO2 0; STOP HEATING#PRINT 2 OVERHEAT; PRINT OVERHEAT MESSAGE#BLOCK_END;#ELSE_IF %T < 70 #THEN #SET C:PBO2=1; RESTART HEATING IF T<70

The following statement is divided on two lines. As a text constant cannot be dividedit is necessary to type it as a sum of two texts.@A = "IN THIS EXAMPLE, A LONG TEXT VALUE IS " - ; Comments allowed

+ "ASSIGNED TO VARIABLE A" ; like this

SCIL Characters

SCIL uses an extended ASCII character set (ASCII = American Standard Code for In-formation Interchange). This character set contains 256 characters, each of which cor-responds to a numeric value in the range 0 . . . 255.

Some of these characters have a special meaning in SCIL. They symbolize punctua-tion marks, operators, messages to the system, etc. These special symbols and theirmeanings are listed below. When the symbols are composed of more than one char-acter, the characters can not be separated by spaces.

Symbol Meaning in SCIL- minus sign, continuation of program line+ plus sign* multiplication** exponential operator/ division, separator in picture paths\ separator in Visual SCIL object paths ( left bracket) right bracket, marks an enumeration. decimal point, marks a graphics or Motif command.. marks an index interval" encloses a text@ precedes a variable name by assignment% precedes a variable name by use’ indicates variable expansion# precedes a control command! precedes a picture command: follows an object name; starts a comment= assignment= = equal to



ABB Automation 17

> greater than> = greater than or equal to< less than< = less than or equal to< > not equal to^ marks an octal number

SCIL Names

Most user interface objects (picture and Visual SCIL objects, see Chapter 4) and ap-plication objects (see Chapter 4) are identified by logical names (identifiers), whichcan be chosen freely. Likewise, the names of variables, named programs, user definedmethods, logical library representation files and directory paths can be named freely.

As a rule, the names may be up to 63 characters long. However, the names of pictures,windows, application objects (except variable objects), and logical paths may be only10 characters long.

Allowed characters are the letters A-Z, all digits and underscore (_). In applicationobject names periods (.) are allowed as well. As a rule, the first character of a namemust be a letter. Application object names may also start with a digit, but this is notrecommended.

SCIL supports blanks in Windows NT directory- and filenames.

Examples:

Below are some examples on valid and invalid SCIL names:

Valid names:

RELAYRELAY_STNRELAY_1234

Invalid names:

4TH_RELAY (starts with a digit, not valid as a name on a picture, window or variable)

RELÄ (contains a special character)RELAY_STATION (too long)

Upper case and lower case letters are not distinct. For example, OBJ_NAME andObj_name are one and the same name.


MicroSCADA3 Data Types

ABB Automation 19

3 Data Types

This chapter describes the SCIL data types: integer, real, boolean, time, text, bitstring, byte string, vector and list.

3.1 General

Data Types

In SCIL there are six types of simple data (data constituted of single values): integer,real, boolean, time, text, bit string and byte string. As distinguished from these, thedata type vector represents a string of data items, and the data type list represents alist of attributes and attribute values. An additional data type none exists, if e.g. thelist attribute name has been defined, but its attribute value has no definition.

Meaning

Every SCIL expression (see Chapter 6) is associated with one of these eight datatypes. The data type of an expression determines both the range of values the expres-sion can yield and the operations that can be carried out upon it.

3.2 Integer

Description

The integer data type denotes positive and negative integer values ranging from-2.147.483.648 through +2.147.483.647. Numbers outside these limits are automati-cally regarded as real numbers.

Integer constants can be typed in decimal or octal form. In decimal form integers arewritten by means of digits and signs. No commas or decimal points are allowed, norare exponents. Integer values without any sign are regarded as positive.

Octal numbers have 8 as their base, unlike the decimal numbers (ordinary numbers),which have 10 as their base. Integers written in octal form (max. +- 65535) aremarked with a final up arrow (^).

Internally integer values are represented by 32 bits.

Example

Examples of some valid integer constants:

2560000123-5777^



1MRS751250-MEN

ABB Automation20

The four first ones are in decimal form, the last one in octal form. The last one repre-sents integer value 511 in decimal form.

3.3 Real

Description

The real data type expresses, with limited precision, continuous quantities within alarge range of values. The accuracy of real numbers is limited to about seven digits, ifinitial zeroes are not counted.

Table 1. shows the value ranges of the real numbers. All numbers between the small-est negative and the smallest positive numbers yield the value 0. The ranges are de-termined by the processor of the base system computer.

Table 1. The value ranges of real values.

Smallest negative value -5.88 E(-39)Largest negative value -3.41 E38Smallest positive value 5.88 E(-39)Largest positive value 3.41 E38

Real numbers are written using digits, decimal points and signs. No exponents are al-lowed. Real numbers without any sign are considered positive. At least one digit mustprecede the decimal point. Numbers without any decimal point are considered as inte-ger values if they fall within the value range of integer values. Outside that range,they are considered as real values.

Internally, real numbers are represented by a 32-bit floating point format.

Because the internal representation of a real number is generally not exact, careshould be taken when comparing two real expressions for equality. For example, it isnot safe to rely on such "facts" as ’1.7/5.0 == 0.34’. However, the following holds:Every whole number in the range -16777215 .. +16777215 has an exact representationas a real number. Therefore, for example the relation ’170.0/5.0 == 34.0’ is safe, norounding errors can occur.

Example

Examples of some valid real numbers:

0.01234.5678912345675.0.000000000000000000001

The second number contains 9 significant digits and consequently cannot be storedwithout some loss of precision.



ABB Automation 21

3.4 Boolean

Description

This kind of data may gain two values: FALSE and TRUE.

Boolean values are gained as the result from testing the truth of expressions, usuallyrelationships or functions. They are used in conditional statements and expressions.

Internally, FALSE is represented by the value 0 and TRUE by the value 1. Hence, therelation between the two boolean values is :

FALSE <TRUE.

Integer 0 and 1 are returned when boolean SCIL expressions are used via DDE (Dy-namic Data Exchange).

Examples

Some examples of boolean expressions and their values:

Expression Boolean value

5 = = 5 TRUE

"NIGHT" = = "DAY" FALSE

%V = = FALSE TRUE, if the boolean variable %V is FALSE (see Chapter 5).

3.5 Time

This kind of data is obtained as time information from the system when using the timefunction CLOCK (see section 8.3.) and some attributes, e.g. the RT attribute, regis-tration time (see section 4.3.).

Time data exists only internally and consists of the number of seconds passed sincethe beginning of 1978. This number as an integer value represents time data whenused in expressions. It is also the value returned when Time date is used via DDE.Time data can be given a readable representation (e.g. calendar time) by means of thetime functions (see section 8.3.).

Internally, time data is registered as 32-bit integer values.



1MRS751250-MEN

ABB Automation22

3.6 Text

Description

Text data is composed of one or more, up to 255, characters. All characters are al-lowed. When used in expressions, text data must be enclosed in quotation marks (").These are omitted when text data is shown on screen.

Text data can be typed either in upper-case or lower-case letters. However, if you dis-play lower case text in a semigraphic window, special semigraphic symbols are showninstead of lower case letters. If you have a semigraphic monitor, use the SCIL func-tion UPPER_CASE to convert the lower case letters to upper case before display.

A single quote (’) or double quotes (") contained in a text must be typed as two singlequotes or two double quotes respectively.

Text data is used, e.g., for displaying texts in windows. Texts can also be operated,e.g. added and compared (see Chapter 6).

Examples

Two text constants:

"ABC_123!!?%"

"This is a text constant containing one "" and one ’ ’ "

3.7 Bit String

Description

A bit string is a sequence of bits stored in consecutive memory bytes. The length of abit string (the number of bits in the string) may be anything from 0 to 65535. The bitsin a string are numbered from 1 to 65535 counting from left to right.

Bit strings appear as values of process objects, functions and variables. They have novisible representation, but they can be read as a text by means of the BIN function(section 8.4.), and they can be written by means of the BIT_SCAN and BIT_STRINGfunctions (sections 8.4. and 8.5.). Bit strings can be added and compared (see Chapter6).

Internally, bit strings are represented as a field of two bytes length, followed by somany data bytes as are needed to hold the bits.

Example

An example of a bit string of eight bits converted to a text by means of the BIN func-tion:

BIN(%BITSTRING) = = "01010101"



ABB Automation 23

3.8 Byte String

Description

A byte string is a sequence of consecutive 8-bit bytes with no structure and no pre-defined semantics. The length of a byte string may be anything between 0 and1048576 bytes.

The contents of a byte string are defined by the SCIL programmer. Byte strings areespecially suitable for exchanging non-ASCII data between MicroSCADA and otherapplications.

Byte string data can be added and compared by relational operators.

Byte string can be constructed by the PACK_STR function. By using the functionUNPACK_STR, a byte string can be interpreted as an array of numerical values. Thelength of a byte string can be read by means of the LENGTH function.

3.9 Vector

Description

A vector is a string of data. All data types are allowed in vectors, even so that data ofdifferent types are included in the same vector. A data item as a part of a vector iscalled an element. A vector may contain up to 10000 elements numbered from 1 to10000. This numbering is used as indexes (sequence numbers) when referring to oneor more elements of a vector.

Vectors occur as values of object notations and attributes (see Chapter 4), variables(see Chapter 5) and functions (see Chapter 8). Indexes can only be used together withapplication and system object notations and variables. Hence, indexing is described inthese contexts, i.e., in Chapters 4 and 5.

Vector Aggregates

In expressions a vector can be written as a vector aggregate. Vector aggregates arewritten in the following format:

(element1,element2,element3,....,elementn)

that is, the vector elements separated with comma and enclosed in brackets. The ele-ments are expressions of any data type.

Vectors can also be constructed with the VECTOR function (see Chapter 8).

Example

An example of a vector of five elements written as a vector aggregate:

(-23, "NAME", 0.000001, CLOCK, %A+%B)



1MRS751250-MEN

ABB Automation24

The variables A and B may not be of list type.

3.10 List

Description

Data of this type constitutes a list of attribute names and attribute values (see Chapter4). The attributes may be any data type. A list can hold up to 10000 attributes.

Data of list type occurs as values of variable objects (see section 4.3.), variables (seeChapter 5) and certain functions (see Chapter 8).

Using the LIST function (see Chapter 8), a list can be written in the following form:

LIST(attribute=expression,attribute=expression, ...)

where

’attribute’ is a freely chosen attribute name of up to 63 characters,

’expression’ is an expression of any data type.

A list cannot be included in expressions but by using attribute names and indexes theattribute values can be extracted from a variable object and thereafter be handled assimple data or vectors.

Example

A list could have the following contents:

Attribute name: LN IX UN OA OB OV ....Index1 "A" 4 10 3560 7 0 ....2 "B" 2 11 3430 16 5.5 ....

Using the LIST function, the list would be written:

LIST(LN=("A","B"),IX=(4,2),UN=(10,11),OA=(3560,3430),OB=(7,16),OV=(0,5.5))


MicroSCADA4 Objects

ABB Automation 25

4 Objects

This chapter describes in general terms the objects and how to handle them in SCIL.The objects are of three main categories which are described in the following sec-tions:

4.1 General: an overview of the three object categories, some object relatedconcepts.

4.2 System Objects: The communication system objects and base system objects,their object notation and some attributes.

4.3 Application Objects: The application object types, their object notation, andsome attributes.

4.4 User Interface Objects: The pictures and picture components, the visual SCILobjects, the object hierarchy, the object references, attributes and methods.

This description of the object types is superficial. For a detailed description, refer tothe following manuals: System Objects, Application Objects, Visual SCIL Objects,Visual SCIL User Interface Design and Picture Editing.

4.1 General

Object Categories

There are three categories of objects which represent three levels of system engineer-ing:

• System objects. The system objects are used for system configuration and com-munication. They are of two types: - Base system objects - Communication system objects (previously named system objects).

• Application objects. These objects form the functional portion of the applica-tions. There are nine types of application objects: - Process objects- Scale objects - Data objects- Command procedures- Time channels- Event channels- Event objects- Variable objects- Free type objects.

• User interface objects. There are two types of objects for composing the userinterface portion of applications: - Pictures- Visual SCIL objects. There are about 40 Visual SCIL object types. Each type

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation26

corresponds to a type of dialog, dialog item (e.g. buttons, texts, lists, menus) orimage.

Attributes and Methods

An important concept when talking about objects is the notion of attribute. Most ob-ject types have attributes which represent the values and features of the objects. Thevalue of a process object, for example, is represented by an attribute, the time stamp isanother attribute, and so is the alarm state. Regarding the Visual SCIL objects, the at-tributes may correspond to visual properties such as the label or color of a button.

Through the attributes, the SCIL programmer can use and change the object proper-ties. For instance, the color of a dialog item and the alarm limits of a process objectmay be changed by means of a SCIL statement.

The Visual SCIL objects may also have a number of methods which are programswritten in SCIL or in C. The SCIL programs may be freely modified while the C pro-grams are predefined. By executing predefined methods, the programmer can affectcertain features of the objects.

Handling Objects in SCIL

The values and properties of the objects can be read in SCIL as attributes. Providedthat write access is allowed, the values and properties can also be written by means ofSCIL commands. Reading an attribute means that it is used in a SCIL expression, e.g.,assigned to a variable or shown in a window. Writing an attribute may imply that itsvalue is changed.

The system objects and application objects - or actually their attributes - are accessedby means of an object notation which contains the object name and type and the at-tribute name. The Visual SCIL objects are accessed by means of an object name orpath and an attribute name.

The system objects and most of the application objects are global and accessible notonly within the same application and the same base system, but even in the entire dis-tributed MicroSCADA system. The Visual SCIL objects, on the contrary, are accessi-ble from SCIL only within the same dialog system.

4.2 System Objects

4.2.1 General

Overview

The system objects define the hardware and software configuration of the entire Mi-croSCADA system, as well as the data communication with connected devices. Thereare two types of system objects:

• Base system objects (B) which define the base system configuration.


MicroSCADA4 Objects

ABB Automation 27

• Communication system objects (S) which are images of the physical system de-vices connected to the communication units (NETs).

The base system objects are kept in the RAM memory of the base system computer aslong as MicroSCADA is running. They are not stored on disk, but must be defined ateach start-up of the base system. The communication system objects are stored in thecommunication units (NETs) as long as the units are running. Default values may bestored in the communication programs (board based NETs) as a preconfiguration.

System Object Notation

SCIL refers to a system object value, i.e. an attribute, by an object notation of thefollowing format (the items within curly brackets may be omitted):

name: {application} type attribute {index}

where

name is the name of the object. The system objects have predefined nameswhich are composed of a three-letter type notation and a sequencenumber.

application is an application number. Generally not needed.

type is a character indicating the object type: S = communication systemobject, B = base system object.

attribute is the attribute to be read or written with the notation. The attributenames are a combination of two letters (A...Z). The attribute determinesthe data type of the entire notation. The system object attributes are alldetailed in the manual System Objects.

index is a number or a range of numbers. The indexes have different meaningsdepending on the object type and attribute. For instance, for NET lineattributes the index generally refers to the NET line number. For someattributes, the index denotes an address. The System Objects manualdetails the indexing of the attributes.

An index or index range is given in any of the following ways:

• With an integer number (1 ... 10000), either a positive integer value or an octalnumber. Octal numbers must be used when addressing bits.

• With an integer type expression enclosed by parentheses.

• With an interval enclosed in parentheses, (i..j), where ’i’ denotes the first indexnumber and ’j’ the last. If the index limits are given as expressions (e.g. an objectnotation or a variable) they should be enclosed by parentheses or spaces. Twopoints surrounded by parentheses, (..), denotes all the indices of the actual objectnotation. (i..) means all indices larger than or equal to ’i’, and (..j) all indices lessthan or equal to ’j’. In an index interval either both or none of the index limitsmay be given with bit addresses.

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation28

There may be no spaces between the items in the object notation.

4.2.2 Base System Objects (B)

Description

The base system objects correspond to the devices and applications situated in, con-nected to, or otherwise known to the base system. They determine the hardware andsoftware properties of the base system and its applications. Each base system has itsown set-up of base system objects.

The base system objects have the following names:

SYS The base system itself

APLn Applications (n = 1 ... 20)

PRIn Printers ( n = 1 ... 20)

MONn Monitors (n = 1 ... 50)

INDn Input devices: keyboard, mouse, control board (n = 1...50)

STAn Stations (n = 1 ... 2000)

STYn Station types (n = 1 ... 31)

NODn Nodes: base systems and NETs (n = 1 ... 99)

LINn Links: connection line (n = 1 ... 20)

’n’ represents an ordinal number ("base system object number"). For APL and MONtype objects, it can be omitted from the object notations, which means that the nota-tion refers to the current application or monitor respectively.

Some Attributes

Each of the base system object types have their own attributes. Here are some exam-ples:

AS Application StateThe state of the application (APL): "HOT" = active, "WARM" = notactive, but accessible, "COLD" = passive, not available.

LP Lines per PageNumber of lines per printed page. Belongs to PRI objects.

AC Alarm CountBelongs to APL objects and shows the number of active alarms in theapplication. The alarm class is given as an index. Index 0 refers to thetotal number of active alarms.


MicroSCADA4 Objects

ABB Automation 29

PC Picture Cache SizeThe cache memory space reserved for pictures and libraryrepresentations in main memory. Belongs to SYS objects.

Examples

Examples of some base system object notations:

Notation Value ExplanationAPL1:BAS "HOT" Application number 1 is active.

PRI1:BDT "NORMAL" Printer number 1 is black and white.

PRI2:BLP 70 Printer number 2 writes 70 lines per page.

APL1:BAC 20 There are 20 active alarms in application 1.

4.2.3 Communication System Objects

Description

The communication system objects correspond to the devices connected to the com-munication units. Hence, these devices - communication units, stations, other basesystems, workstations and peripherals - can be accessed and controlled from SCIL ascommunication system objects. Each NET unit has its own set-up of communicationsystem objects.

The communication system objects have the following names:

NETn (or NODn) Communication units and base systems (n = 1 ... 99)

APLn Applications (n = 1 ... 32)

STAn Stations (RTUs, PCLs, relays, etc.) (n = 0 ... 255)

PRIn Printers (n = 1 ... 8)

The ‘n’ above indicates the number of the objects as known to the NET where theyare defined. When handling the objects in SCIL, the 'n' in the object name is the num-ber of the device as known to the current application (according to the device map-ping attributes, see appendix B).

Some Attributes

Each of the object types have their own attributes. Here are just a few examples:

SA Station Address.The station address of a device. The NET objects and STA objects havea station address.

IU In Use.States whether or not the object is in use. Most system objects have thisattribute.

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation30

Value: 0 ... out of use1 ... in use.

PO ProtocolThe protocol of a communication line given as an integer, e.g. 1 = ANSIfull duplex, 14 = SPA. 0 = the line is not defined.

ME MEmory address.The contents of the memory address given as an index. Belongs to theSTA objects (ANSI stations).

Examples

Examples of some communication system object notations :

Notation Value ExplanationSTA1:SSA 201 Station 1 has station address 201.

NET1:SPO2 14 Line 2 of NET1 uses the SPA protocol.

PRI4:SIU 1 The printer is in use.

STA5:SME1234^5 0 The contents of storage address 1234,bit number 5 in STA5

4.3 Application Objects

4.3.1 General

Object Types

The application objects are programmable units which perform various functionaltasks in the MicroSCADA application. They constitute data images of physical proc-ess or system devices, data registers, SCIL programs, scaling algorithms, facilities forautomatic activation, etc.

There are nine types of application objects:

• Process objects (P) . . . data images of the physical process devices connected toprocess stations (remote terminal units (RTUs), protective equipment, PLCs,etc.).

• Scales (X) . . . algorithms for scaling analog process values.

• Data objects (D) . . . collections of stored data ("historical database").

• Command procedures (C) . . . SCIL programs.

• Time channels (T) . . . facilities for automatic time bound activation.

• Event channels (A) . . . facilities for automatic event bound activation.


MicroSCADA4 Objects

ABB Automation 31

• Event objects (E) . . . mechanisms for event activated start-up of SCIL programsor program sequences in pictures and dialog objects.

• Variable objects (V) . . . temporary objects which can contain attributes col-lected from other objects or arbitrary attributes.

• Free type objects (F) . . . special objects for the definition of user-defined proc-ess object types (not described in this manual, refer to Object Description).

Process objects, scales and free type objects are stored in the process database, whichholds an image of the process. Data objects, command procedures, time channels andevent channels are all stored in the report database, which a database supporting re-porting, calculation and control. These objects are also commonly named reportingobjects. Variable objects are stored in the same way as variables (see Chapter 5).Event objects are not stored at all.

All application objects, with the exception of the variable objects, are global and ac-cessible throughout the entire system.

Application Object Notation

SCIL refers to an object value, i.e. an attribute, by an object notation of the followingformat (the terms in curly brackets may be omitted in cases where they are notneeded):

name:{application}type{attribute}{index}

where

name is the object name. The application object names are logical (sym-bolical) and can be freely chosen in accordance with the rulesgiven in section 2.2.

application is the logical number of the application where the object is stored.Application number must be given if the object belongs to an ap-plication other than the current one (the application where the no-tation is used). If the object belongs to the same application, thenumber is omitted. The application number is defined by theAPL:BAP attribute (see the System Objects manual, Chapter 5).

type is the type of the object given by using the letters P, X, D, C, T, A,E, V, S, B or F in accordance with the above.

attribute is the attribute to be read or written by the notation. As a rule, theattribute names are a combination of two letters (A...Z). However,if the object is a variable object the attribute name may be com-posed of up to 63 characters. The object notation may contain oneor none attribute name. The attribute determines the data type ofthe entire notation when used in expressions.

index is a number that distinguishes from each other individual attributeswith otherwise identical object notations from each other. Indexes

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation32

are used to differentiate individual attribute values, which in allother respects have identical object notations, i.e., the same objectname, application, object type and attribute.

As a rule, the indexes refer to the elements of an attribute of vector type. The actualattribute determines the data type of the elements. (In Object Description the data typeand the indexing are given for each attribute.) The predefined process object types arean exception. For these objects, the indexes refer to the individual objects in a group,not to attributes of vector type. Still, for a certain attribute, the values are handled aselements in a vector.

An index or index range is marked in either of the following manners:

• With an integer number, 1 ... 10000. An index of a variable object where the at-tribute is not composed of two letters must be enclosed by parentheses. In allother cases, no parentheses are needed.

• With an integer type expression. The expression must be embraced by brackets.

• With an interval (i..j), where ’i’ denotes the first index number and ’j’ the last. Ifthe index limits are given as expressions (e.g. an object notation or a variable)they should be enclosed by parentheses or spaces. Two points surrounded by pa-rentheses, (..), is interpreted as all the indices of the actual object notation. (i..)means all indices larger than or equal to ’i’, and (..j) all indices less than or equalto ’j’.

No spaces are allowed between the items in the object notation.

4.3.2 Process Objects (P)

Description

The process objects correspond to physical devices connected to the process stations(RTUs, protection equipment, PLCs), for instance switches, sensors and breakers.Each input and output connection in the stations is represented by a process object.Normally, the value of an input object is updated from the process station, while thevalue of an output object is sent to the station when written with the SCIL command#SET (section 7.3.).

Some process objects have no correspondence in the stations. These are called ficti-tious process objects and they can generally be updated only from SCIL programs.They can, e.g., be used for process simulation or manually updated data.

There are nine predefined process object types depending on the type of object value(i.e. the input or output connection in the stations): binary input and output, analoginput and output, digital input and output, double binary indications, pulse countersand bit streams. In addition, for special purposes, e.g. load management, the pro-grammer can define his/her own process object types by means of free type objects.


MicroSCADA4 Objects

ABB Automation 33

An updating of a process object value may cause an alarm, an automatic printout, anupdating on screen (through event objects, section 4.3.8.), and activation of an eventchannel (section 4.3.7.).

Process objects with active alarms are included in an alarm buffer, which can beread by SCIL process queries (the function PROD_QUERY, Chapter 8) and displayedas alarm lists. If desired, the process object events can be stored in a history buffer,which can similarly be read with process queries and displayed as event lists.

Some Process Object Attributes

A few process object attributes are described below. All attributes are detailed in theApplication Objects manual.

OV Object valueThe value of the process object as registered in the process database. Theobject value is the value read from the process (input values) or sent tothe process (output values). The attribute is a common name for theattributes BI, BO, AI, AO, DI, DO, DB, PC and BS (see below andappendix B). Each object value has a time stamp and an error status code.

Value: 1 or 0 for binary objects, real values for analog objects, bitstring for bit streams and integer for the others.

BI Binary Input Binary process value from the process to the control system.Value: 1 or 0.

BO Binary OutputBinary set value from the control system to the process.Value: 1 or 0.

AI Analog InputAnalog measurement value from the process to the control system.Value: real.

AO Analog Output Analog set value from the control system to the process. Value: real.

AL Alarm.States whether the object is in alarm state or not. Value : 0 - no alarm

1 - alarm state.

HI, LI Lower Input, Higher InputLower and higher alarm limits. These attributes are defined only foranalog objects with an alarm function.Value: real.

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation34

If the object notation is given without any attribute, the attribute is assumed to be OV,except in connection with the commands #LIST, #CREATE, #DELETE and#MODIFY (Chapter 7), where the whole object is referenced to.

Groups and Indexes

Related process objects (up to 255) of the predefined types may be given the samename. Process objects with the same name form a process object group. The individ-ual objects in a group are accessed by means of indexes. A process object notation ofany predefined type without an index is interpreted as the lowest indexed object withthe given name and attribute (attributes common to the group are always used withoutindexes) .

Concerning user-defined types (defined by free type objects), the indexes refer to theelements of a vector type attribute. A notation without indexes means the entire vec-tor.

Examples

Some examples of process object notations:

Notation Value ExplanationSWITCH:P 1 The value of the process object (the lowest

indexed object in the group).

SWITCH:POV 1 - " -

SWITCH:PBI23 1 The switch with the index 23 is connected.

TEMP:POV(%N+1) 37 The value of the expression %N+1 iscalculated and used as an index.

TEMP:PHI 90.0 Alarm is given when the temperature risesabove 90.

TEMP:PLI 10.0 or falls below 10.

TEMP:PAL 1 Alarm state prevails.

4.3.3 Scales (X)

Description

Scales are related to the process objects, or more exactly, to the analog process ob-jects. They define algorithms for the transformation of the digital process valuestransferred from the stations to the values of the analog units of the correspondingprocess objects.

Every analog process object has a scale name, which defines the scaling algorithm isto be used for the transformation. The same scale can be used by several process ob-jects.


MicroSCADA4 Objects

ABB Automation 35

Some Scale Attributes

Below are two scale object attributes. All attributes are detailed in the ApplicationObjects manual.

LN Logical NameValue: text.

SA Scaling AlgorithmValue: 0 = 1:1 scaling

1 = linear scaling2 = step-wise linear scaling

4.3.4 Data Objects (D)

Description

Data objects (datalog objects) register and store calculated or sampled data. They areused for the storage of report data, trend data, data for calculation and control, systemconfiguration data, etc. The data objects can also be used instead of global variableswhen there is a need for exchanging data between different objects.

The data registration may be initiated from a program (by means of the commands#EXEC and #EXEC_AFTER, see section 7.3.), from a time channel (section 4.3.6.)or from an event channel (section 4.3.7.). Each registration is performed according toa SCIL expression and a logging function. Besides the calculated or sampled value,each registration includes a time stamp and a status code.

Every data object can store a chosen number of data registrations (up to 65535). Theregistrations, up to 10000 at a time, can be accessed as vectors by means of indexes.The oldest registered value has the index number 1.

Some Data Object Attributes

Some of the most important attributes are listed below. A complete description isgiven in the Application Objects manual.

OV Object Value.Registered value. Value: real or vector of real values.

RT Registration Time.Value: time or vector of time values.

OS Object Status.Indicates the reliability of the registered data.Value: Integer or vector of integers. The status codes listed in

appendix C, e.g.:0 ... OK1 ... uncertain10 ... no values.

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation36

If the object notation lacks an attribute, the attribute is assumed to be OV, except inconnection with the command #EXEC or #EXEC_AFTER (section 7.3.), where thenotation refers to the whole object.

The above mentioned attributes are used indexed. An object notation with these at-tributes without any index refers to the latest registered value.

Examples

Some examples of data object notations:

Notation Value ExplanationDATA:D 5.6 The latest registered value of the data

object.

DATA:DOV 5.6 The latest registered value of the dataobject.

DATA:DRT Time of last registration given as timedata. Can be converted to calendar timeby means of time functions (section 8.3.).

DATA:DRT(5..) The vector formed by the registrationtimes for the datalog object DATA startingwith registration number 5.

DATA:DOV(1..(DATA:DLR)) The values of the registered data rangingfrom the oldest one to the last registration(LR).

4.3.5 Command Procedures (C)

Description

The command procedures contain SCIL programs which can be started automaticallyor by SCIL. They can be used for all kinds of manually or automatically started op-erations, such as calculations, control operations and reporting. They cannot be usedfor affecting the user interface. Command procedures can be started in the followingways:

• From SCIL programs with the #EXEC and #EXEC_AFTER commands (section7.3.). (A command procedure can even start itself).

• From time channels (section 4.3.6.).

• From event channels (section 4.3.7.).

After a command procedure has been started, it is normally executed to the end. Itmay be interrupted by an error and by the #RETURN command (section 7.3.).

A command procedure can hold up to 10000 SCIL statements. As a rule, commandprocedures may not contain user interface related commands (picture commands, Vis-ual SCIL commands or graphical commands, see section 7.1.). However, a commandprocedure, or a selected part of it, can be handled as a vector and be executed with the


MicroSCADA4 Objects

ABB Automation 37

#DO command (section 7.3.) and the DO function (Chapter 8). In these cases, it maycontain user interface commands if the #DO command or DO function is executed ina user interface object.

Some Command Procedure Attributes

Some command procedure attributes are shown below. All attributes are detailed inthe Application Objects manual.

TC Time Channel.The name of the time channel that starts the command procedure.Value: text.

IN Instruction.The program of the command procedure.Value: text vector.

OS Object Status.States how the last execution succeeded. Value: The status codes listed in appendix C, e.g.:

0 ... correctly executed10 ... not executed.

A command procedure notation without an attribute refers to the program, i.e., the INattribute.

Indexes can be used only with the attribute IN where they refer to the line numbers.The IN attribute without indexes refers to the whole program.

Examples

Some examples of command procedure notations :

Notation Value ExplanationTASK:C The program as a text vector.

TASK:COS 0 The program execution succeeded.

TASK:CIN5 "@VAR = 10" The fifth line of the command procedureTASK.

4.3.6 Time Channels (T)

Description

Time channels are used for the automatic start-up of time-bound activities, which canbe:

• The registration of data objects.

• The execution of command procedures.

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation38

A certain time channel can start several data objects and command procedures. Theexecution order is determined by the priorities of the data objects and command pro-cedures.

A time channel is activated at the execution time which means that the connectedobjects are executed. At the initialization time, the time channel is initialized, whichmeans that the registration of connected data objects is restarted from the first record.Both initialization and execution can take place at absolute points of time or periodi-cally with a fixed interval. All times are given with an accuracy of one minute. Dis-continuous time activation is obtained with conditional expressions.

Time channels can be executed also with the #EXEC commands (section 7.3.) andwith event channels (section 4.3.7.).

Some Time Channel Attributes

Some time channel attributes are listed below (a complete list is found in the Appli-cation Objects manual):

IU States whether the time channel is in use or not.Values: 0 = not in use

1 = in use

RT The time of last initialization/activation.Value: time vector

The time channels can be used without an attribute only with the #EXEC commands.

Indexes (1 or 2) can be used e.g. together with the RT attribute. Index 1 refers to theinitialization time and index 2 the activation time.

4.3.7 Event Channels (A)

Description

Event channels are used for the automatic start-up of event-bound activities. Theevents normally originate from the process database, from where the event channelstransmit them to objects in the report database which take the consequential actions(calculations, control actions, etc.). An event channel can start the following opera-tions:

• Registration of a data object.

• Execution of a command procedure.

• Activation of a time channel.

Each process object may have only one event channel, but an event channel may beconnected to up to 11 command procedures and data objects. At the activation of anevent channel, some essential attributes are transmitted as variables from the process


MicroSCADA4 Objects

ABB Automation 39

object to the connected reporting object. Thanks to this feature, several process ob-jects can share the same event channel.

An event channel is activated by the following events in the activating process ob-jects:

• An alarm comes or goes.

• The warning limits or alarm limits of an analog object are transgressed (pro-vided that the control system, not the RTU, handles the limit value supervision).

• The OV attribute (BI, BO, AI, AO, DI, DO, DB, PC or BS) is changed.

• The OV attribute is updated.

The options are chosen with a process object attribute (AA). Event channels can alsobe activated with SCIL (the #EXEC commands, section 7.3.).

In addition, any user-defined attribute can activate the event channel of the object.

Some Event Channel Attributes

Examples of attributes (a complete list is found in appendix B) :

OT Object Type. The type of the object to be executed.Value: text.

ON Object NameThe name of the object to be executed.Value: text.

4.3.8 Event Objects (E)

Description

The event objects are used to start event-bound activities, normally updates, in userinterface objects (pictures and Visual SCIL objects).

In pictures, the activation of an event object causes the execution of the statement(s)determined by the #ON command (section 7.3.) for the specific event object. The#ON commands are valid only for the actual picture - main picture or sub-picture -where they have been executed. The event causes no action if there is no #ON com-mand in force for the actual event in the picture shown on screen at the event moment.

In dialogs and dialog items, the activation of an event object starts the execution ofthe event method, if any, defined to be activated by the event object in question.

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation40

An event object can be activated in two ways:

• From the process database, so that a change in a process object automaticallyactivates an event object with the same name and index as the process object.The activation takes place independently of what causes the change - a changeof state in a station or an assignment in a SCIL program (by the command #SET,section 7.3.). The coupling of an event object to a process object is optional. Theactivating attributes are listed in the manual Application Objects, Chapter 3, theEE attribute description.

• From a SCIL program (in a picture or a command procedure) by the #EXECcommands (section 7.3.). In this case the name of the event object can be freelychosen.

If a process object is equipped with an event object, updating in pictures is carried outautomatically and immediately when a change occurs. The value of the changed at-tribute is not transmitted to the picture, nor is any information about which attributehas changed.

The event object notation does not contain any attribute. Event objects have no val-ues, hence they cannot be parts of expressions.

Example

If the process object

TEMP:P2

is equipped with an event object (EE = 1), the event object

TEMP:E2

is always activated when a change in the process object (for instance the attribute AI)occurs in the process database.

4.3.9 Variable Objects (V)

Description

The variable objects serve as temporary storage places for attributes. They are used tocompose lists, e.g. alarm and event lists, to browse through the object properties, tocopy objects, to create and modify objects, etc.

A variable object is at the same time both an object and a variable of list type (section3.9.). The list as a whole is handled as a variable with the same name as the object(Chapter 5). The attributes in the list are accessed with a variable object notation.


MicroSCADA4 Objects

ABB Automation 41

A variable object can be created and assigned attribute values in two ways:

• By creating the variable object with the #CREATE command (section 7.3.) andassigning it attribute values with a list function or with the #SET command(7.3.). In this case, the attribute names may be arbitrary, up to 63 characters.

• By assigning a variable the value of a list type expression (section 5.2.). A vari-able object with the same name as the variable is formed. The variable objectgets all the attributes of the list expression. This may be a list type function(Chapter 8) or a list type variable.

A variable object notation must always contain an attribute. Unlike the other objecttypes, the names of the variable object attributes can contain 1 ... 63 characters. If theattribute is of vector type, the vector elements are identified by indexes. An objectnotation without an index denotes the whole vector. If the attribute name containsmore or less characters than two, the index must be enclosed by parentheses.

Like variables (Chapter 5), the variable objects belong to the picture, command pro-cedure or dialog system in which they are assigned values. The same name may beused for different variable objects, provided that they appear in different contexts.

The variable objects are stored in the same way as variables and can be transferredbetween different objects as variables, see section 5.1.

Examples

The statement

@VAR = PROD_QUERY(20)

assigns the variable VAR the value of the list defined by the function PROD_QUERY(Chapter 8). At the same time the variable object VAR is formed.

Some variable object notations:

Notation Value ExplanationVAR:VLN1 "SWITCH" The first object name in the list.

VAR:VOV1 0 The first object value in the list.

VAR:VLN(1..10) The first ten object names in the list.

4.4 User Interface Objects

4.4.1 Pictures

General

The pictures and picture components were briefly described in Chapter 2. The PictureEditing manual describes how to build and program the pictures. This section dis-cusses how to reference pictures and picture elements from SCIL.

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation42

In SCIL, the pictures and windows are handled by the picture handling commands de-scribed in section 7.2. In addition, the windows may have attributes which are ac-cessed by a window attribute reference. The named programs of the pictures are exe-cuted by a named program call.

Picture Hierarchy

A picture may contain a number of sub-pictures in the shape of pictures shown inwindows and picture functions. These sub-pictures in turn may contain sub-pictures.A picture and its sub-picture form a picture hierarchy with the main picture (totalpicture) on the top. Figure 8 shows an example of such a hierarchy. A, B, C, D, E andF denotes windows and picture functions.

Main picture

Sub-picture 1 Sub-picture 2 Sub-picture 3

Sub-picture 4 Sub-picture 5 Sub-picture 6

Figure 8. A hierarchical picture structure. The subpictures are picture functions orpictures shown in windows. The letters A ... F denotes the names of win-dows and picture functions.

A picture containing sub-pictures is the parent of its sub-pictures and the containedsub-pictures are children. This parent - child - relationship is of importance for howthe windows are shown in relation to other windows. It is also of importance whenreferencing windows and named programs.

Picture Paths

When referencing windows and named programs, a picture path may be used. A pic-ture path states in which picture - main picture or sub-picture - the window or namedprogram should be searched. A picture path has the following format:

name/name/name/ ... /name

where each ‘name’ is the name of the window or picture function containing the nextpicture in the hierarchy counting from the picture where the command is issued.(Back slash \ could be used instead of forward slash /. ) The main picture can be ref-erenced with the predefined name ROOT. If the picture is included in a dialog system(see section 4.4.2.) ROOT also refers to the picture container where the picture is in-cluded.


MicroSCADA4 Objects

ABB Automation 43

If no picture path is given, the window or named program is first searched from thesame picture as where the reference is issued. If not found there, it is searched fromthe parent picture and so on up to the main picture. Hence, when referencing windowsand programs within the same picture or its parent picture, no path is needed.

For example, the picture path for referencing a named program SAMPLE in sub-picture 4 in Figure 8 from the main picture would be:

A/D

If not found in sub-picture 4, the program is searched in sub-picture 1 and then in themain picture.

Picture Object Attributes

The programmer can assign the windows and picture functions attributes for variouspurposes using the .SET command described in see section 7.4. The attributes have nofunctional meaning, but can be used, e.g., as window or picture function specific vari-ables. The attributes may be given freely chosen names of up to 63 characters in ac-cordance with the rules in section 2.2. They can be assigned data of any data type.

The window and picture function attributes are referenced according to the followingformat:

[picture].attribute

where ‘picture’ is the picture path and ‘attribute’ is the attribute name.

The attribute reference can be used in SCIL expressions where the value of the attrib-ute replaces the reference. The operations allowed depend on the data type of the at-tribute (see Chapter 6). If the attribute is of vector type, the attribute reference denotesthe entire vector. The picture object attributes cannot be indexed.

The picture object attributes can also be expanded in the same way as variables (seeChapter 5).

Examples:

.SET PIC_FUNC_1/WINDOW_2.RESIZED = TRUE

.SET .COUNTER = 0

.SET .COUNTER = .COUNTER + 1

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation44

Named Program Calls

Each picture can have a number of named programs which are started with the fol-lowing program call:

[picture].program [(argument_list)]

where

’picture’ is the picture path to the object containing the named program, seeabove. If omitted, ’program’ is searched for in the picture contain-ing the program call. If not found there, it is searched in its parentpicture, and so on.

’program’ The name of the named program.

‘argument_list’ Arguments given as a list of SCIL expressions separated by com-mas and enclosed in parentheses. Up to 32 arguments may begiven.

When encountered in a program, the program call starts the execution of the namedprogram in the given picture. The subsequent statement in the calling program is notexecuted until the named program has been executed to the end. If no program withthe given name is found, an error status is produced. Named programs can be exe-cuted from any program in the dialog system. They are also used as callback programsof Motif widgets.

The value of the arguments are used by means of the ARGUMENT functions, seeChapter 8.

By using the SCIL command #RETURN (see section 7.3.) in the named program, itcan be programmed to return a value to the calling program. A named program whichreturns a value can be used as operand in expressions, e.g. it can be assigned to a vari-able.


MicroSCADA4 Objects

ABB Automation 45

Example:A/B.CREATE_ERROR_DIALOGExecutes the named program CREATE_ERROR_DIALOG of window B which is a childwindow of window A.

@A = .MY_NAMED_PROGRAM (125,%V+6,”ABC”)The program MY_NAMED_PROGRAM is executed and its return value is assigned tothe variable A.

4.4.2 Visual SCIL Objects

General

The Visual SCIL objects correspond to the dialogs, dialog items and images designedin the Dialog Editor or created with SCIL. There are about 40 types of Visual SCILobjects which could be grouped as follows:

• Dialogs. These are of two types: ordinary dialogs and main dialogs.

• Compound dialog items. These are dialog items which may contain other dialogitems:

• Containers - visible or invisible boxes containing other dialog items.

• Picture containers. These are containers which can contain pictures.

• Menu bars, menus and menu items. Menu bars can contain one ormore menus, menus can contain menus and menu items.

• Notebooks, notebook pages and notebook items.

• Simple dialog items, such as buttons, toggle buttons, texts, lists, etc. The simpledialog items can contain no other objects.

• Images.

In SCIL, the visual SCIL object types are referred to by names starting with VS_. Forinstance, buttons are named VS_BUTTON. The manual “Visual SCIL Objects” listsand describes all the Visual SCIL object types.

Generally, the dialogs, dialog items and images are designed in the Dialog editor,though they can also be created directly with SCIL. Dialog and dialog items created inthe dialog editor are stored in files from where the SCIL command .LOAD loads themin the memory as a visual SCIL object with a specific name. Objects created with.CREATE are not stored in files.

The SCIL commands for handling Visual SCIL objects are detailed in section 7.4.

Unlike the system and application objects, the Visual SCIL objects are not global.They are known and accessed only within the dialog system where they are created orloaded.

Dialog Systems

The Visual SCIL objects are arranged in hierarchical dialog systems with a main dia-log or picture container at the top. Each main dialog and each dialog system starts a

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation46

new dialog system. The object hierarchy is of importance when referencing the ob-jects.

Objects containing another object are called parent objects and the contained objectsare called child objects. The child objects are dependent upon their parent objects.When the parent objects are loaded the child objects are loaded as well, and when theparent objects are deleted (with the .DELETE command), the child objects are alsodeleted.

When loading a dialog or a dialog item with the .LOAD command, it becomes a childobject of the loading object (unless object path is given, see below). When loading amain dialog or picture container, it starts a new dialog system.

Figure 9 shows an example of a Visual SCIL dialog system with four dialogs. Dialog1, which is the main dialog, contains four dialog items. Dialog item B loads dialog 2.This dialog contains three dialog items, one of which, object G loads dialog 3. Dialogitem D contains two dialog items, and dialog item F contains two items. For instance,D could be a menu bar containing menus, which contain menu items (menu options).Dialog item J loads dialog 4.

The dialog items A ... D are child objects of the main dialog. Dialog 2 is the childobject of item B and the parent object of the dialog items G ... I. Dialog 4 is the childobject of item J which is the child object of item F, and so on.

Figure 9. An example of a dialog system

Attributes and Methods

The attributes of the Visual SCIL objects specify their features and functions, e.g.,visibility, position, text contents, behavior, color, fonts, etc. Some attribute values canbe set in the dialog editor, some only with SCIL, and some both in the editor and withSCIL.

The dynamic changes of the dialogs and dialog items are obtained by changing theirattribute values with the SCIL commands .SET and .MODIFY.


MicroSCADA4 Objects

ABB Automation 47

Each object has a number of predefined attributes with predefined names, data typesand meanings. The predefined attributes of each object type are listed and describedin the manual Visual SCIL Objects. In addition, the objects can be given an arbitrarynumber of user defined attributes with the .LOAD, .CREATE and .MODIFY com-mands.

Each dialog and dialog item may have a number of methods which are programs forvarious purposes, e.g. cyclically executed programs, programs executed on certainevents (event objects), programs started by a user operation, and programs started bySCIL.

The programs started by SCIL may be predefined or user defined. They are started bya method call of the format described below.

Visual SCIL Object References

When designing a dialog or dialog item in the Dialog Editor, each item may be givena name. This name will be the Visual SCIL object name of the item when it is in-cluded in a dialog or dialog item loaded with the .LOAD command. The loaded dialogor dialog item is given a Visual SCIL object name with the .LOAD command. Objectscreated with .CREATE are given object names with this command.

Object references are used when loading, creating and deleting objects, and in the at-tribute references and method calls. When referring to an object one level below, theobject name is sufficient. When referring to an object that is more than one level be-low, object path should be given as follows:

name\name\name\.... \name

where each ‘name’ is a Visual SCIL object name.

There are the following predefined path names:

ROOT = the main dialog or picture container on top of the dialog system.

PARENT = the parent of the object.

THIS = the object in question.

PARENT and ROOT are the only possibilities for accessing objects on a higher levelin the hierarchy.

Attribute References

Attributes are referenced with the following notations:

[object].attribute

where ‘object’ is an object reference and ‘attribute’ is the name of the attribute.

If the attribute or method is referenced from a method within the same object, no ob-ject reference is needed. Likewise, when referencing to an attribute belonging to a

MicroSCADA4 Objects


1MRS751250-MEN

ABB Automation48

child object that is one level below, no object name is needed, if no confusion mayoccur.

Attribute references can be used in expressions which means that the reference is re-placed by the value of the attribute. They are also used together with the .SET com-mand to achieve a change of the attribute. The attribute references can be expandedlike variables, see Chapter 5.

Example:.SET MY_BUTTON._TITLE = “OK”

This statement sets the label of the button (the visual SCIL object MY_BUTTON) toOK, which is immediately shown on screen if the button is shown.

Method Calls

Method calls start the execution of methods - predefined methods and user definedmethods. In cases where the method returns a value, the method reference can be usedsimilar to the attribute reference, i.e., it can be used in expressions and the reference isreplaced by the returned value. Method calls have the following format:

[object].method [(argument_list)]

where

‘object’ is an object reference. Not needed when referencing methods inthe same object or one level below.

‘method’ is method name.

'argument_list' Arguments, which may be any SCIL expressions given as a list ofSCIL expressions separated by comma and enclosed in parenthe-ses. Up to 32 arguments may be given.

If the method is a SCIL program, the arguments are used by means of theARGUMENT functions (see Chapter 8). By using the SCIL command #RETURN, themethod can be programmed to return a value. If the method returns a value, themethod call can be used in expressions, and the returned value replaces the methodcall.


MicroSCADA5 Variables

ABB Automation 49

5 Variables

This chapter describes the use of variables in SCIL:

5.1 General Rules: variable names and variable contexts

5.2 Using Variables: how to assign the variables values and how to use thevariables, indexing variables

5.3 Some Predefined Picture Variables

5.1 General Rules

In contrast with constants, the variables have no fixed values. A variable is a namewhich may be assigned any value. After the assignment, the variable name representsthis value within the variable context in question (see below).

On assignment, the variable automatically becomes of the same data type as the as-signed value. All SCIL data types (Chapter 3) are allowed as variable values. The val-ues of variables, and also their data types, may be changed at any time by new as-signments.

Variable Names

The variable names may be freely chosen in accordance with the rules in section 2.2.The variable names may contain up to 63 characters.

Variable Contexts

The variables are not stored on disk. They exist only as long as the variable contextwhere they are defined exists in the primary memory. A variable can be used withinthe context where it was defined (assigned a value) but generally not outside it. Thefollowing objects form a variable context:

• A picture. All programs, windows and sub-pictures within the same picture havetheir variables in common. A variable defined in a window picture, e.g., can beused in the main picture, and vice versa. If window specific variables are de-sired, use user defined window attributes instead of variables (see Chapter 4).

• A dialog system. All dialogs and pictures within the same dialog system havetheir variables in common. Hence, e.g., variables defined in a picture (picturecontainer) can be used in all dialogs opened from that picture. If dialog or dialogitem specific variables are desired, use the user defined attributes (see Chapter4).

• Each individual command procedure, data object and time channel started with#EXEC or #EXEC_AFTER or by an event channel.



1MRS751250-MEN

ABB Automation50

• Command procedures and data objects started by the same time channel. Dataobjects and command procedures connected to a time channel can use variablesdefined in command procedures executed earlier by the same time channel (i.e.which have a higher priority).

Programs executed by the #DO command (section 7.3.) or the DO function (Chapter8) belong to the variable context where the command or function is situated.

Transferring Variable Values between Contexts

There are the following possibilities for transferring variable values between differentcontexts:

• Variable values can be transferred to command procedures, data objects andformat pictures (print-out pictures) by means of the commands #EXEC and#PRINT (section 7.3.).

• Event channels transmit process object attribute values to automatically gener-ated variables ("snapshot variables") with the same names as the attributes.These variable names can be used in the connected data objects and commandprocedures.

• Pictures printed automatically as the consequence of a process event or by the#LIST command can use some automatically defined variables ("snapshot vari-ables") which get both their names and values from the attributes of the printedprocess object.

There are some pre-defined picture variables which are assigned values automatically.These can be used in pictures anywhere in the application (section 5.3.).

Some base system object attributes have been reserved for the use as "global vari-ables" in application programs: SYS:BUV, APLn:BUV and MONn:BUV.

5.2 Using Variables

Variable Assignment

Variables are assigned values with a statement of the following format:

@V = expression

where ’V’ denotes the variable name. The expression, which may be of any data type,is evaluated and the value is assigned to the variable. The variable name hereafter rep-resents the value of the expression and is of the same data type.

In the case where the variable is assigned a list type value, a variable object with thename ‘V’ is created on the assignment.



ABB Automation 51

If the expression is a vector, e.g. an object notation, another vector variable or a vec-tor aggregate (section 3.6.), the variable becomes of type vector. A variable could alsobe assigned individual vector elements by indexing the variable name:

@V(i) = expression

@V(i1..i2) = expression

where

‘i’, ‘i1’ and ‘i2’ are indexes, see “Indexing” below.

In the first case, the variable will be of a simple data type. In the second case, wherean index range is given, the variable will be a vector. If the expression in the secondstatement is a simple data type, all the named elements are assigned this value. If thereare other elements in the vector they remain unchanged.

The rules for indexing variables is described below.

(If the expression is a text constant, the assignment may also be written as follows:

@V character string

which is the same as the statement @V = "character string", except that in the firstcase possible lower case letters are converted to upper case letters. The variable namemust not be indexed.)

Examples

Statement Explanation@VAR = ABC:PAI The value of the process object is read from

the process database and assigned to thevariable.

@TEXT = "ABC:PAI" The object value is not read. The variablegets the text value "ABC:PAI".

@LIST = PROD_QUERY(20) The variable LIST is assigned the value ofthe list formed by the functionPROD_QUERY. At the same time thevariable object LIST:V is created.

@A = FALSE The variable A is given the boolean valueFALSE.

@V = DATA:D(1..20) The variable V becomes a vector containingthe first 20 registered values of the dataobject DATA.

@V(1..5) = D1:D(1..5) + D2:D(1..5) The first five elements in the variable V areassigned the values of the sums of the firstfive registered values of the data objects D1and D2.

@A = (5,4,OBJ:POV3,CLOCK) The variable A becomes a vector with fourelements.



1MRS751250-MEN

ABB Automation52

Using Variables in Expressions

After a variable has been assigned a value, this value is referred to as:

%V

that is, the variable name preceded by a percent sign.

This notation can be used as an operand in expressions where the value of the variablereplaces the notation. The data type of the variable determines which operations maybe carried out on it (Chapter 6). No operations may be carried out on list type vari-ables. These may only be copied to a new variable name.

If the variable ’V’ is a vector, individual elements are referred to by means of indexes.The %V notation without any index refers to the entire vector. See the rules for in-dexing below.

Examples

Statement Explanation@NEW = 30 * %OLD The variable NEW is assigned the value of the

variable OLD multiplied by 30.

@NUMBER = %NUMBER + 1 The old variable value is incremented by one.

@LIST2 = %LIST If LIST is a list type variable, also LIST2 becomes ofthis type and the variable object LIST2:V is created.

!SHOW WIN %VAR The whole vector is shown in the window WIN, whichmust be of the type MULTIFIELD, BAR or CURVE.

@A = %A(1) + %A(2) The sum of the elements one and two in variable A.

Indexing Vector Variables

Vector variables may be used either with or without indexes. When giving an index oran index range, the following rules must be obeyed:

• Indexes are positive integer numbers or integer expressions in the range 1 ...10000.

• Indexes are always surrounded by parentheses.

• An index range is given as (i..j), where ’i’ and ’j’ are positive integer numbers orexpressions. The low index ‘i’ should not be greater than the high index ‘j’. (..)represents all indexes of a vector variable. (i..) means all indices larger than orequal to 'i', and (..j) all indexes less than or equal to 'j'.

A vector variable name without an index refers to the entire vector.



ABB Automation 53

“Variable Expansion”

The variables can also be used for forming text strings and names. By including avariable in a name or text string, you can assign different contents to the text or namedepending on the context. To use a variable as a part of a text or name, enclose thevariable name by quotes as follows:

’V’

The value of the variable is now regarded as a text constant that replaces the quotenotation. In this case, the variable must be of a simple data type, i.e., it must not be avector or a list, and it must not be indexed. An extra assignment is required, if thevalue of vector element or list attribute is "expanded".

This way of using variables is named “variable expansion”. Not only variables butalso the variable object attributes, window attributes and Visual SCIL object attrib-utes can be “expanded”, provided that they are not indexed.

Examples

Statement Meaning@LN = "P_METER"@IX = 22

The variable LN is assigned the text value"P_METER" and the variable IX value 22

@PRESSURE = 'LN':PAI’IX’ The variable PRESSURE is assigned the AIattribute value of the process object P_METERwith index 22.

@PRESSURE = P_METER:PAI22 Same meaning as previous but without use ofvariables.

@QUANTITY=LIST-(QUANT1="PRESSURE",-QUANT2="TEMP",-QUANT3="CURRENT")@A='QUANTITY:VQUANT1':PAI22

Using attributes in variable expansion.Value of 'QUANTITY:VQUANT1' in this case is“PRESSURE”. The variable ‘A’ is assigned thevalue of the AI attribute of the process object‘PRESSURE:P’ with index 22.

5.3 Predefined Picture Variables

There are some picture variables with pre-defined names and meanings. These vari-ables can be used in pictures throughout the system, but their values depend on thecircumstances in which they are used. The predefined picture variable names are:

VIDEO_NR The logical monitor number of the current monitor (applicationsession). The variable is the same as MONn:BAN. It can gain in-teger values in the range 1...50. The monitor number is selectedwhen an application session is started. This variable should not bechanged manually.

PIC_NAME The name of the picture (main picture) displayed on screen at themoment. The variable can have text values containing a max. of 10characters. This variable should not be changed manually.



1MRS751250-MEN

ABB Automation54

CURSOR_POS This variable contains the coordinates of the cursor position of thelast function key selection. It is always updated when a functionkey is selected, except when the system is in input mode (after the!INPUT_VAR, !INPUT_POS or !INPUT_KEY commands). Thevariable is used, e.g., when building line command keys, see Pic-ture Editing, Chapter 6.

The variable is a vector with four elements:

(x,y,x_rel,y_rel)

where

x, y = the coordinates related to the upper left corner of the pic-ture, which is (1,1). x = 1 .. 160, y = 1 .. 96.

x_rel, y_rel = coordinates related to the upper left corner of thewindow where the cursor is situated, which is = (1,1).

KEY_POS This variable contains the coordinates of the last function key se-lection related to the upper left corner of the key. The variable isupdated each time a function key is selected. The variable is avector of two elements:

(x_rel,y_rel)

where

x_rel, y_rel = coordinates related to the upper left corner of thekey, which is (1,1).

ENTER_POS This variable contains the coordinates of the last click on anENTER key. The variable is updated each time a function keycontaining an !ENTER command which terminates !INPUT_VARis pressed, no matter whether the ENTER key contains otherstatements or not. The variable is a vector of four elements:

(x,y,x_rel,y_rel)

where

x, y = coordinates related to the upper left corner of the picture(=1,1).

x_rel,y_rel = coordinates related to the upper left corner of thewindow in where the ENTER key is situated (= 1,1).



ABB Automation 55

Examples

Statement Meaning#EXEC EVENT_’VIDEO_NR’:E#ON EVENT_’VIDEO_NR’:E !SHOW ....

An event object containing the videonumber is activated. In combination with#ON sequences, likewise defined withvideo number, the event is directed to thesame monitor.

#IF %CURSOR_POS(2) = 40 #THEN......

A statement is executed on the conditionthat the pressed line is number 40.

#PRINT 1 ’PIC_NAME’ The current screen picture is printed.


MicroSCADA6 Expressions

ABB Automation 57

6 Expressions

This chapter describes how to compose SCIL expressions using various types of op-erators:

6.1 General Principles

6.2 Arithmetical Operators

6.3 Relational Operators

6.4 Logical Operators

6.1 General Principles

Use

In SCIL, expressions are used as follows:

• For value assignments (objects, attributes, variables).

• As arguments for functions and commands.

• As operands in expressions.

By using SCIL expressions, MicroSCADA application data can be accessed from ex-ternal Windows applications via the DDE protocol.

Composition

Expressions are composed of operands and operators (possibly enclosed by parenthe-ses). The operators are symbols for operations (e.g. + : addition). The operands con-stitute the objectives for these operations.

Operands

Operands may be:

• Constants.

• Variables (Chapter 5).

• System and application object notations (attributes).

• Visual SCIL attributes and window attributes.

• Function calls (Chapter 8).

• Vector aggregates (section 3.9.).



1MRS751250-MEN

ABB Automation58

• Named program calls and method calls (provided that they return a value).

• Expressions enclosed by parentheses.

The simplest type of an expression is a single operand, which may be a constant, e.g.,a text.

The data types of the operands determine which operations that may be carried out onthem, what other types of operands they can be combined with and what the resultwill be. The data compatibility rules for each operator are given in the tables below.List type operands cannot be operated upon by any operator. They can only standalone. The list data type is therefore omitted from the compatibility rule tables. Thedata type of an expression can be read with the function DATA_TYPE (see Chapter8).

Operators

There are three types of SCIL operators:

• Arithmetical operators.

• Relational operators.

• Logical operators.

In the SCIL expressions, they are evaluated in the above mentioned order of priority.

The operators and their usage are described in the next sections.

Reliability of Data

In SCIL, each data has a status code, which expresses the reliability of the data. As arule, when an expression is evaluated, it gets the status code of the least reliable oper-and. Data written explicitly by the programmer or entered by the user always have OKstatus. A bad status code may originate from a process object value, which have beenmarked as obsolete due to a communication fault.

The status code of an expression can be read and written with the SCIL functionGET_STATUS and SET_STATUS. The status codes are listed in the manual StatusCodes.

6.2 Arithmetical Operators

Use

Arithmetical operators are used for numerical calculations. As operands they demandnumerical values, except for addition, which allow text, bit string and byte string op-erators as well (Table 2).



ABB Automation 59

Operators

SCIL has the following arithmetical operators:

+ addition, positive sign

- subtraction, negative sign

* multiplication

/ division

** exponential operator

DIV integer division, the remainder is truncated from the result

MOD modulus operator (the remainder by integer division provided thatthe operators are positive).

The operators DIV and MOD must be enclosed by spaces. For the other operators,spaces are optional.

Priority Order

The order of priority for the arithmetical operators, i.e. the order in which differentparts of an expression are evaluated, does not differ from that in mathematics. It is asfollows (operators with the highest priority first):

1) **

2) / , * , DIV , MOD

3) + , -

Operations with the same order of priority are evaluated from left to right. If the ex-pression contains parentheses, these are evaluated first.

Compatibility Rules

Below are rules for what data types can be combined by means of the arithmetical op-erators and the data type of the resulting expression.



1MRS751250-MEN

ABB Automation60

Addition, +:

I = IntegerR = RealB = BooleanT = TimeC = TextS = Bit/Byte StringV = Vector- = Not allowed

Right op.Left op. I R B T

I I R -R R R - -B - - - -T - - - -C - - - -S - - - -V V V -

C S V

- TR

VV

- - ---

V VV

C- -

-VVVS-

V

Table 2. Addition rules


I I R -R R R - -B - - - -TC - - - -S - - - -V V V

C S V

- VV

- - ---

V

- --

V

--V

T

-

- --

T - I

-

- --

Subtraction, -:

I = IntegerR = RealB = BooleanT = TimeC = TextS = Bit StringV = Vector- = Not allowed

Table 3. Subtraction rules

As can be seen from Table 2 and Table 3, text data may be added to text data. Thecorresponding subtraction is not possible.

It is possible to add to or subtract from time data integer or real numbers, which arethen regarded as numbers of seconds. The results yielded are of time data type. Whentime data is added to an integer the result is time data and when added to a real num-ber the result is a real number.

When two time data expressions are subtracted, the result is an integer number statingthe time difference in seconds. Hence, this difference cannot be used in operationsdemanding time data.

If an integer, real or time value is added to or subtracted from a vector (or vice versa),the value is added to or subtracted from every element in the vector. When a vector isadded to or subtracted from a vector, the operation is carried out element by element.For the elements the same rules apply as for simple data types. If one element has abad status (not OK), the resulting element is given SUSPICIOUS_STATUS. If thenumber of elements is does not match in the operand vectors, the missing elements areregarded as zero, and the odd elements receive SUSPICIOUS_STATUS.

When two bit strings are added, they are appended together with the left operand tothe left and the right operand to the right. When adding two byte strings, they are con-catenated in the same way. If the result is longer than 1048576 bytes, the overflowingbytes are lost.



ABB Automation 61

The positive and negative signs do not change the data types of the values they belongto. The signs cannot be used together with boolean, time or text values.

Multiplication, *:



I I R -R R R - -B - - - -T - - - -C - - - -S - - - -V V V - -

C S V

- VV

- - ---

V

- ----

--

-

- -

---

Table 4. Multiplication rules


I R -R R R - -B - - - -TC - - - -S - - - -V V V

C S V

- VV

- - ---

- ----

-

- --

-

-

- --

Division, /:


R

-- -

-

-

Table 5. Division rules

When a vector is multiplied or divided by an integer or real number (Table 4 andTable 5) the operation is carried out on every element in the vector.

When a vector is multiplied by a vector, the operation is performed between corre-sponding elements. For the vector elements the same rules apply as for simple datatypes. If the number of elements does not match in the operand vectors, odd elementsare multiplied by one and the resulting element receives SUSPICIOUS_STATUS.

A vector cannot be divided by another vector.

In cases where either one of the operands (Table 6) is a vector, the operation is per-formed on each of the vector elements. For the vector elements the same rules applyas for simple data types.



1MRS751250-MEN

ABB Automation62


I -R - -B - - - -T - - -C - - - -S - - - -V - -

C S V

-

- - ---

- ----

--

-

- -

---

-

--

IntegeroperatorsDIV and MOD:

I ---

I

V

V


Table 6. DIV and MOD rules

Exponentialoperator, **:I = IntegerR = RealB = BooleanT = TimeC = TextS = Bit StringV = Vector- = Not allowed


I -R - -B - - - -T - - -C - - - -S - - - -V - -

C S V

-

- - ---

- ----

--

-

- -

---

-

--

RR

RR

-

-

-

Table 7. Exponent rules

Examples

Below are some examples of expressions composed by arithmetical operators. The bitstring operators are written here by means of the BIT_SCAN function, which trans-forms the argument text to bit string. The result of the addition is a bit string andhence it can not be read directly, but it can be read as a text by means of the BINfunction .

Expression Result"A" + "B" "AB"

3**2 9.0

5 DIV 2 2

5 MOD 2 1

2*3 + 4/2 8.0

(2*3 + 4)/2 5.0

BIT_SCAN("0101") + BIT_SCAN("0011") "01010011" (read with the BIN function)



ABB Automation 63

6.3 Relational Operators

Use

Relational operators are used for comparing expressions. The result of a comparisonis always a boolean value, that is, the relation is either TRUE or FALSE.

Operators

The following relational operators are available in SCIL:

= = equal to

> greater than

< less than

< > unequal

< = less than or equal to

> = greater than or equal to

The relational operators have a lower order of priority than the arithmetical operators.Accordingly, arithmetical expressions are evaluated before comparisons are carriedout.

Compatibility Rules

Table 8 presents rules for what data types may be compared by means of relationaloperators.

Relationaloperators:I = IntegerR = RealB = BooleanT = TimeC = TextS = Bit StringV = Vector- = Not allowed


I -R -B - - -T -C - - - -S - - - -V - -

C S V

- - ---

- --

-

--

- -

---

-

--

BB

BB

-

-BB

BBBB

BB

Table 8. Rules for relational operators

Comparison of text expressions is based on the fact that each character corresponds toa number in the range 0…255. The characters are ordered so, that the digits (0...9)precede the letters. The letters are arranged in alphabetical order (except the SwedishÅ, which comes after Ä). The upper-case letters precede the lower-case letters.



1MRS751250-MEN

ABB Automation64

Boolean values and text may be compared only with values of the same data type.Time data can be compared to time data, integer and real values.

Bit strings are compared bit by bit starting from the bit furthest to the left, which isthe most significant bit. A 1 is greater than a 0, and an existing bit (0 or 1) is greaterthan a non-existing bit.

Byte strings may be compared by relational operators. The byte strings are comparednumerically byte by byte (each byte has a value 0 .. 255), the first byte being the mostsignificant. If two byte strings of different lengths are identical to their commonlength, the shorter one is considered ’smaller’.

Vectors cannot be handled by relational operators.

Examples

Below are some examples of expressions containing relational operators .

Expression Result"B" > "A" TRUE

%A - 30 == 0 TRUE, if %A = 30

OBJ:PRT + 60 > CLOCK TRUE, as long as less than oneminute has passed since the latestregistration time

BIT_SCAN("0011") < BIT_SCAN("0101") TRUE



BIT_SCAN("010100") > BIT_SCAN("0101") TRUE

6.4 Logical Operators

Use

With logical operators boolean values can be operated upon.

Operators

In SCIL there are the following logical operators:

AND conjunction, "both .. and"

OR disjunction, "or"

XOR exclusive or, "either, but not both"

NOT logical negation, the opposite



ABB Automation 65

Logical operators have a lower order of priority than the relational operators, that is,relational expressions are evaluated before the logical operations are carried out.

Compatibility Rules

All logical operators demand operands of type boolean. Likewise, the results yieldedfrom logical operations are of type boolean.

In an expression there may be several logical operators. But in cases where the op-erators are different, connected logical expressions must be enclosed by brackets. Seethe following example.

Examples

Imagine that A and B are boolean data with the values shown to the left. The logicaloperators give the following results:

A B A AND B A OR B A XOR B NOT ATRUE FALSE FALSE TRUE TRUE FALSEFALSE TRUE FALSE TRUE TRUE TRUETRUE TRUE TRUE TRUE FALSE FALSEFALSE FALSE FALSE FALSE FALSE TRUE

Wrong: %A == 1 AND %B == 2 OR %C == 3

Right: (%A == 1 AND %B == 2) OR %C ==3

or %A == 1 AND (%B == 2 OR %C == 3)


MicroSCADA7 SCIL Commands

ABB Automation 67

7 SCIL Commands

This chapter describes the SCIL commands. It is divided into four sections as follows:

7.1 General: The different types of SCIL commands, the arguments, and a tableover all picture handling commands, control commands and Visual SCILcommands.

7.2 Picture Handling Commands: The picture handling commands listed anddescribed.

7.3 Control Commands: The control commands listed and described.

7.4 Visual SCIL Commands: The Visual SCIL commands listed and described.

7.5 VS Object, Window and Picture Function Methods: The methods listed anddescribed.

7.6 VS Object, Window and Picture Function Attributes: The attributes listed anddescribed.

7.1 General

Types of SCIL Commands

There are four main types of SCIL commands:

• Picture commands. Picture commands issues orders to the system concerningpicture handling, e.g. producing pictures on screen, showing and erasing win-dows, etc. They are allowed only in pictures and are characterized by a starting !(exclamation mark).

• Control commands. Control commands execute operations concerning objects,system components, printouts, program executions, etc. Control commands arecharacterized by a starting # (number sign) and they can be used within all typesof SCIL programs.

• Visual SCIL Commands. These commands are characterized by a starting dot (.).They can be used in user interface objects (pictures and Visual SCIL objects)provided that the logical monitor (application window or session) has beenopened as a VS monitor.

• Primitive graphics commands. The graphics commands handle full graphicalelements. These commands can be used in MicroSCADA pictures and VisualSCIL objects. The graphics commands are described in Chapter 9.

• Motif widget commands. These commands can be used in MicroSCADA pic-tures and Motif widgets. They are described in Chapter 10. It is not recom-mended to use Motif Widget commands in new applications.



1MRS751250-MEN

ABB Automation68

Arguments

Most commands require arguments to become complete statements. The arguments ofa command specify its objectives and provide additional information. In this chapter,the commands are written in upper case letters and the arguments in lower case let-ters. Arguments in square brackets ([]) are not obligatory. There must be at least oneblank space between a command and its arguments.

Overview

The following tables list all picture commands, control commands and Visual SCILcommands (without their arguments), the tasks they execute and the pages where theyare described.

Command Brief Description Page

!CLOSE!FAST_PIC!INT_PIC!LAST_PIC!NEW_PIC!RECALL_PIC!RESTORE!STORE_PIC!UPDATE!ERASE!SHOW!SHOW_BACK!WIN_BG_COLOR!WIN_CREATE!WIN_INPUT!WIN_LEVEL!WIN_NAME!WIN_PIC!WIN_POS!WIN_REP!CSR_ commands!ENTER!INPUT_KEY!INPUT_POS!INPUT_VAR!RUBOUT commands!TOGGLE_MOD!SEND_PIC!RESET

Closes the monitor. ................................................................................................ 70Adds and removes fast picture definitions in semi-graphic monitors. .................... 70Displays an alarm picture....................................................................................... 71Displays the previous picture. ................................................................................ 71Displays a picture................................................................................................... 72Recalls a stored picture name................................................................................ 73Stops function key blinking..................................................................................... 73Stores the present picture name. ........................................................................... 73Defines the update time interval............................................................................. 74Erases a window from the screen. ......................................................................... 75Shows a window. ................................................................................................... 75Shows the picture background of a window........................................................... 76pecifies the color of the background behind the window........................................ 76Creates a window................................................................................................... 77Assigns a window an expression. .......................................................................... 77Specifies the level parameter of the window.......................................................... 78Creates a new window. .......................................................................................... 78Selects a picture to be shown in the window. ........................................................ 79Positions a window................................................................................................. 79Selects a library representation for a window. ....................................................... 80These commands move the data entry cursor. ...................................................... 81Completes data entry. ............................................................................................ 81Reads function key information.............................................................................. 81Reads mouse or cursor position. ........................................................................... 82Reads an input value from the user. ...................................................................... 83Delete input data.................................................................................................... 83Insert/typeover. ...................................................................................................... 84Copies the picture (semi-graphic) to a printer. ....................................................... 84Deletes variables in a picture. ................................................................................ 84



ABB Automation 69

Command Brief Description Page

#BLOCK commands#CASE, #WHEN, etc.#DO#IF, #THEN, etc.#LOOP, #LOOP_END#LOOP_WITH, #LOOP_END#LOOP_EXIT#ON#PAUSE#RETURN#CREATE#DELETE#EXEC#EXEC_AFTER#GET#MODIFY#SET#INIT_QUERY#SEARCH#LIST#PRINT#ERROR commands#ERROR RAISE#ON ERROR#ON KEY_ERROR#PATH commands#REP_LIB commands#CLOSE_FILE#CREATE_FILE#DELETE_FILE#OPEN_FILE#READ#READ_KEYS#READ_NEXT#READ_PREV#REMOVE#RENAME_FILE#WRITE#SET_TIME.CREATE.DELETE.LOAD.MODIFY.SET

Compound statements (block)................................................................................85Case dependent execution of statements. .............................................................85Executes SCIL statements. ....................................................................................86Conditional statements. ..........................................................................................87Executes a loop. .....................................................................................................88Executes a loop a chosen number of times............................................................89Interrupts a loop. ....................................................................................................90Executes a program block when an event occurs. .................................................90Defines a pause. ....................................................................................................91Stops the program execution and evaluates the ‘expression’. ...............................91Creates a new object..............................................................................................92Deletes an variable, object or variable object.........................................................92Executes an object. ................................................................................................93Executes an object after a time delay.....................................................................94Updates process object values...............................................................................95Changes an object definition. .................................................................................95Assigns values to objects. ......................................................................................96Initiates a process query.........................................................................................97Initialises a search among objects..........................................................................98Prints process object data. .....................................................................................100Prints a picture. ......................................................................................................101Define error handling policy....................................................................................102Activates an error status.........................................................................................103Defines an error handler.........................................................................................103Defines a key error handler. ...................................................................................103Defines a logical path name. ..................................................................................104Defines a logical representation library name. .......................................................106Closes a keyed file. ................................................................................................107Creates and opens a new keyed file. .....................................................................108Deletes a file...........................................................................................................108Opens a keyed file..................................................................................................109Reads a keyed record in an open file. ....................................................................110Reads the keys of an open file. ..............................................................................110Reads a keyed record. ...........................................................................................111Reads a keyed record. ...........................................................................................111Deletes a keyed record...........................................................................................112Renames a file. ......................................................................................................112Writes a keyed record in an open file. ....................................................................113Sets the system time. .............................................................................................113Creates a Visual SCIL object..................................................................................114Deletes a Visual SCIL object. .................................................................................115Loads a Visual SCIL object. ...................................................................................115Modifies one or more attributes of a Visual SCIL object.........................................116Assigns a value to a user interface attribute...........................................................117

7.2 Picture Handling Commands

The picture handling commands can be used only within MicroSCADA pictures.They are not allowed in dialogs, or in command procedures.



1MRS751250-MEN

ABB Automation70

7.2.1 General Picture Handling Commands

!CLOSE

Closes the monitor.

On full graphic operator consoles, the command ends the application session by clos-ing the kernel process of the monitor (PICO).

On a semi-graphic monitor, the command empties the screen from pictures and makesit turn black. The monitor can be refreshed by clicking the mouse, which loads theMicroSCADA start picture on screen. If there are pictures in the monitor alarm pic-ture queue when the !CLOSE command is issued, the monitor screen is not emptiedbut instead the oldest alarm picture in the queue is displayed on screen. If an alarmoccurs while the monitor is kept closed, and the monitor in question is defined as analarm monitor for the object, the alarm picture is immediately displayed.

!FAST_PIC [picture]!FAST_PIC - [picture]!FAST_PIC [-] [picture] , [-] [picture] , ...

Adds and removes fast picture definitions in semi-graphic monitors.

’picture’ A picture specified as:[path/] picture name

where:

’picture name’ is the picture name exclusive the extension,and

’path’ is a logical path name.

If ’path’ is omitted, the default path names are used. See the PATHcommand, section 7.3.6.

Default: the present picture.

!The first command model marks the picture as a fast picture. When the picture is sub-sequently erased from the screen, it is saved as a fast picture. This means that everydynamic part of the picture is saved in the form it had when the picture was erased.Updating is, however, terminated as in the case of ordinary pictures. When the pictureis again displayed on screen, it has the same appearance as when it was previously

The command applies to semi-graphic monitors only and has no effect in full graphicmonitors.



ABB Automation 71

erased and updating starts from this state. The start program of the picture is no fur-ther executed.

The second command model, where the picture name is preceded by a minus sign,removes the fast picture definition. Henceforth, the picture is no longer stored as fastpicture. Several fast picture definitions at a time can be added and removed as shownin the third command model above. Note: if ’picture’ is omitted, the minus sign at theend of the line will denote that the statement is continued on the next line. To avoidthis, type two subsequent minus signs and an empty line as shown in the example be-low.

Fast pictures are monitor specific, i.e. a picture may be a fast picture in one monitorbut not in the others.

The fast pictures are continuously stored in the main memory. If there is insufficientmain memory storage space in the computer, a large number of fast pictures may de-lay the handling of the ordinary ones.

All fast picture definitions are cancelled when the system is exited or the applicationstate is changed. After a fast picture has been edited in the picture editor it functionsin the normal way until it is stored again.

Example:!FAST_PIC MYPIC;Next time the picture MYPIC is exited it is stored as a fast picture.!FAST_PIC - -;empty line;The fast picture definition of the current picture is cancelled. Hereafter it;functions as an ordinary picture.

!INT_PIC

Displays an alarm picture.

Incoming alarms are added to a monitor (application session or window) specificalarm picture queue. This command displays the oldest alarm picture in the queue. Atthe same time the name of the picture is removed from the alarm picture queue. If thealarm picture queue is empty, the command has no effect.

In other respects, the command works like !NEW_PIC.

!LAST_PIC

Displays the previous picture.

This command causes the picture handling process to go one step backwards in thequeue built up by !NEW_PIC, see Figure 10, and display that picture.

In other respects, the command works like !NEW_PIC.



1MRS751250-MEN

ABB Automation72

!NEW_PIC picture

Displays a picture.

’picture’ The picture to be displayed, specified as:[path/] picture name

where

’picture name’ is the picture name exclusive the extension,and

’path’ is a logical path name.

If ’path’ is omitted, the default path names are used. See the#PATH command, section 7.3.6.

The picture with the given name, if it exists, is displayed on screen. First the back-ground becomes visible. After that, possible draw and start programs are executed(unless the picture is stored as fast pictures, see !FAST_PIC). If the named picturedoes not exist, an error message is produced.

When a picture is displayed, its picture name is automatically placed as the last itemin a monitor specific queue of shown pictures, which is maintained by the picturehandling unit. If the picture name already is in the queue, all subsequent picturenames are removed from the queue, and the picture name in its former position isthereafter the last item in the queue, see Figure 10.

If ’path’ is omitted, the picture is searched for in the directories defined by the defaultpath name valid for the actual picture name, see the #PATH command, section 7.3.6.

An error status is produced if the picture does not exist.

Examples:!NEW_PIC MYPIC;The picture named MYPIC is shown on screen. The picture is searched for in the;directory/directories defined by the path name PICT.!NEW_PIC OWNPIC/MYPIC;The picture MYPIC is searched for in the directory/directories defined by the;path name OWNPIC.



ABB Automation 73

Figure 10. The picture queue. Each monitor or picture container has its own picturequeue.

!RECALL_PIC

Recalls a stored picture name.

The picture, the name of which is stored by !STORE_PIC (see below), is displayed onscreen. The command functions like !NEW_PIC.

The command has no effect if !STORE_PIC has not been used.

!RESTORE

Stops function key blinking.

When a function key has been pressed, it may be marked by blinking (depending onthe key definition). This command stops the blinking of all function keys on the entirescreen.

!STORE_PIC

Stores the present picture name.

The name of the present picture is stored and it can later be retrieved with the com-mand !RECALL_PIC.

Only one name at a time may be stored in this way. When the command is used again,the previous picture name is removed.



1MRS751250-MEN

ABB Automation74

!UPDATE interval

Defines the update time interval.

’interval’ Time interval in seconds given as a positive real expression. Thevalue of ’interval’ is automatically rounded to an accuracy of 0.1seconds.

If there is an update program in the picture, it is executed repeatedly with this intervalas long as the picture is displayed on screen, or until a new !UPDATE command is is-sued. After the update program has been executed to the completion, it restarts whenthe time interval given by this command has elapsed. Subsequent !UPDATE com-mands may change the time interval. The most recently given time interval is valid. If0 is given as a time interval, the updating ceases until a new interval other than 0 isgiven.

When an !UPDATE command is issued, the update program is immediately executedonce (provided that the interval is unlike 0). The next execution takes place at a syn-chronization time. After that execution restarts cyclically with the given interval. Thetime interval between the first and second execution may differ from the intervalgiven with the !UPDATE command.

The main picture, its window pictures and picture functions may have different up-dating intervals.

Examples:!UPDATE 5;The update program is restarted when five seconds have elapsed since the;previous execution.!UPDATE %A;The updating interval is assigned the value of the variable A.

7.2.2 Window Handling Commands

Windows can be defined using the Picture Editor or the !WIN_CREATE or!WIN_NAME commands together with the !WIN_POS, !WIN_PIC, !WIN_REP, and!WIN_INPUT commands. Windows are displayed on screen with the !SHOW and!SHOW_BACK commands and erased from screen with the !ERASE command.

When a window is displayed, it is placed on top of its parent picture (see the picturehierarchy in Chapter 4). Windows which are children of the same parent are arrangedaccording to their level parameter which can be changed with the !WIN_LEVELcommand. Windows with the same parent and the same window level are stacked inthe order they were first shown with the !SHOW command so that the newest windowis placed on top. The updating of a window with !SHOW has no affect on the stackingorder. However, when a shown window is moved by !WIN_POS, it is raised to be-come the topmost window among the windows with the same level and the same par-ent. When the level of a displayed window is updated with the !WIN_LEVEL com-mand, the window is stacked as the topmost window among the windows with thesame level and the same parent.

The stacking order is the same whether the child window is totally contained withinits parent or not.



ABB Automation 75

!ERASE [picture path]window

Erases a window from the screen.

’window’ The name of the window to be erased.

’picture path’ A picture path according to the format described in Chapter 4. Ifomitted, the window is sought from the picture or picture functionwhere the command was issued. If the window is not found there,the window is sought from the entire picture.

The command erases the named window from the screen. If the window is of typePICTURE, a possible exit program is executed when the window is erased. If it con-tains windows, these windows are erased, too.

Examples:!ERASE MESSAGE;The window MESSAGE is erased.!ERASE TREND/COLUMN;The window COLUMN in the window (or picture function) TREND is erased.

!SHOW [picture path]window [expression]

Shows a window.

’window’ The name of the window to be shown.

’picture path’ A picture path according to the format described in Chapter 4. Ifomitted, the window is searched from the picture or picture func-tion where the command was issued. If the window is not foundthere, the window is searched from the entire picture.

’expression’ The expression to be shown in the window. Not obligatory.

The window is displayed on screen at the location determined by the window defini-tion. The value of the expression is calculated before the window is displayed.

If the expression is given by the !SHOW command, the expression in the windowdefinition is disregarded. If the expression is omitted here, you may define it by thecommand !WIN_INPUT. Only as the last alternative, the expression is taken from thewindow definition. If the window is defined as PICTURE or FIGURE, the expressionis disregarded.

If the window is of PICTURE type, possible background, draw and start programs areexecuted when the picture is shown. The update program is executed in the intervalgiven in the window picture, which may differ from that of the main picture.

An error status is produced if the window cannot be found.

Windows are erased with the !ERASE command.

Examples:!SHOW MESSAGE "ENTER PASSWORD:"



1MRS751250-MEN

ABB Automation76

;The text ENTER PASSWORD: is shown in the window called MESSAGE.!SHOW TREND/COLUMN %MAX;The variable MAX is shown in the window COLUMN of the window TREND.

!SHOW_BACK [picture path]window [expression]

Shows the picture background of a window.

’window’ The name of the window to be shown.


’expression’ The expression to be shown in the window. Not obligatory.

This command shows the picture background of a window picture. The background ofthe picture functions included in the picture are shown as well. The background anddraw programs of the picture are executed. No other programs are executed. No win-dows are shown and the function keys do not function.

If the window is of some other type than PICTURE, the command works like!SHOW.

An error status is produced if the window cannot be found.

The window background is erased with the !ERASE command.

Example:!SHOW_BACK SCHEME;The picture background of the window SCHEME is displayed.

!WIN_BG_COLOR [picture path]window color

Specifies the color of the background behind the window.

’window’ The name of the window


’color’ The requested background color given as a named color, a vectorof RGB values or a reference, see Chapter 9. Default color: thecolor defined by the MONn:BWC attribute (see the System Ob-jects manual).

When a window is displayed, the background color can be seen for a moment until thewindow is drawn on screen. Likewise, when a window is erased, the backgroundcolor appears for a moment until the background behind the window is redrawn on



ABB Automation 77

screen. By choosing an appropriate background color for the window, disturbing colorswitches can be avoided.

The window background used in the monitor is specified by the base system attributeMONn:BWC. By means of the !WIN_BG_COLOR command, the SCIL programmercan choose the background color of individual windows. The command may be givenbefore or after the window is shown for the first time.

When a window is shown for the first time, the background color is set to the colordefined by the MON:BWC attribute, if not otherwise defined by the!WIN_BG_COLOR command. Later changes of WC do not affect the backgroundcolor.

The !WIN_BG_COLOR command is not applicable to semi-graphic monitors.

!WIN_CREATE [picture path]window

Creates a window.

’window’ The name of the window

’picture path’ A picture path according to the format described in Chapter 4. Ifomitted, the window is created in the picture or picture functionwhere the command was issued.

The command creates a new window during the picture handling. Once the windowhas been created with this command, it can be assigned a position with the!WIN_POS command (default position: the upper left corner of the picture), a repre-sentation with !WIN_REP (library representation) or !WIN_PIC (picture), and an ex-pression with the !WIN_INPUT or !SHOW command. Similar to windows created inthe picture editor, windows created with !WIN_CREATE are shown with the !SHOWcommand.

!WIN_CREATE first checks whether the window already exists. If no picture refer-ence is given, the window is searched only within the current picture. If the windowalready exists, and if it is an ordinary window, the command does not produce any re-sult. If the window exists as a Motif widget, its X background is mapped as a Micro-SCADA window background to enable SCIL graphics to be drawn on it.

The created window exists as long as the picture is displayed on screen, or stored asfast picture (semi-graphic monitors).

Use !WIN_CREATE instead of !WIN_NAME in cases where !WIN_NAME mighthave undesired side-effects.

!WIN_INPUT [picture path]window expression

Assigns a window an expression.

’window’ The name of the window.



1MRS751250-MEN

ABB Automation78

’picture path’ A picture path according to the format described in Chapter 4.

’expression’ The expression to be shown in the window.

The command assigns the window an expression which is stored as long as the pictureis displayed on screen or stored as a fast picture. The expression is evaluated everytime the window is shown with the !SHOW command.

With this command the window expression may be changed during the program exe-cution. The last given expression is valid. Hence, if the expression given with!WIN_INPUT is intended to be used, no expression should be given with the !SHOWcommand.

If ’picture’ is omitted, the window is sought from the picture or picture function wherethe command was issued. If the window is not found there, the window is sought fromthe entire screen. An error status is produced if the window cannot be found.

Example:!WIN_INPUT LINE "TRY AGAIN:"!SHOW LINE;The text TRY AGAIN: is shown in the window LINE.

!WIN_LEVEL [picture path]window level

Specifies the level parameter of the window.

‘window’ The name of the window.

'picture path' A picture path according to the format described in Chapter 4.

'level' An integer value in the range -100 ... +100. -100 = the window isplaced on bottom, +100 = the window is placed on top. Defaultvalue = 0. Instead of values, the following two predefined con-stants can be used: ON_BOTTOM ( = -100) and ON_TOP (=+100).

The command specifies the level of the window in relation to other windows on thesame level in the picture hierarchy (see Chapter 4.). See the general part of this sub-section.

!WIN_NAME [picture path]window

Creates a new window.


'window' The name of the window.

The command has the same function as the !WIN_CREATE command, except for thefollowing:



ABB Automation 79

If no picture reference is given, the !WIN_NAME command searches throughout thewhole main picture. If a window with the given name is found, no new window is cre-ated.

Example:!WIN_NAME A!WIN_POS A (1,1)!WIN_PIC A A_PIC!SHOW A;A window A is created and placed in the upper left corner. The picture A_PIC;is shown in the window.

!WIN_PIC [picture path]window picture

Selects a picture to be shown in the window.

’window’ The name of the window in which the picture will be shown.

’picture path’ A picture path according to the format described in Chapter 4.

’picture’ The name of the picture to be shown in the window specified as:[logical path/] picture name

where

‘picture name' is picture name exclusive the extension, and

'logical path' is a logical path name.

If 'logical path' is omitted, the default path names are used. See the#PATH command, section 7.3.6.

With this command you can change the picture name during program execution. Thelatest issued picture name is the valid one. The name of the window picture is storedas long as the main picture is displayed on screen or stored as a fast picture. Thecommand entails that the picture name in the window definition is ignored.

If 'picture path' is excluded, the window is sought from the picture or picture functionwhere the command was issued. If the window is not found there, the window issought from the entire screen. An error status is produced if the window cannot befound.

Example:!WIN_PIC AREA TABLE!SHOW AREA;The picture TABLE is shown in the window AREA.

!WIN_POS [picture path]window pos

Positions a window.

'window' The name of the window to be positioned.




1MRS751250-MEN

ABB Automation80

’pos’ The new window position as a vector with two positive integerelements. The first element is the x-position (horizontal coordi-nate, 1 ... 160) and the second one the y-position (vertical coordi-nate, 1 ... 96). If ’pos’ contains more than two elements (e.g. thevariable generated with the !INPUT_POS command), these ele-ments are ignored.

The upper left corner of the window ’window’ is positioned to the semi-graphic char-acter position specified by ’pos’. If the x-coordinate is larger than 80 or the y-coordinate larger than 48, the window is placed on the control board, outside thescreen.

If the window is currently shown, it is immediately erased from the old location anddisplayed at the new one. The window is placed on the top of all windows with thesame level parameter and the same parent. The new location is stored as long as themain picture is displayed on screen or stored as a fast picture.

If ’picture’ is excluded from the command, the window is sought from the picture orpicture function where the command was issued. If the window is not found there, thewindow is sought from the entire screen. An error status is produced if the windowcannot be found.

Examples:!WIN_POS ABC (1,1);The window ABC is moved to the upper left corner of the main picture.!SHOW INFO "POINT OUT A NEW LOCATION"!INPUT_POS POS!WIN_POS FIG %POS;The window FIG is moved to the position pointed out with the mouse.

!WIN_REP [picture path]window representation

Selects a library representation for a window.

‘window’ The name of the window to be assigned a library representation.


'representation' The library representation to be used in the window specified as:[library/] representation

where:

'representation' is the name of the representation, and

'library' is a logical library name.

If library name is omitted, the representation is sought from the li-brary DEFAULT. See the command #REP_LIB in section 7.3.6.

With this command the representation to be used in the window may be changedduring the program execution. The most recently given representation is valid. Thegiven representation name is stored as long as the main picture is displayed or stored



ABB Automation 81

as a fast picture. The command entails that the representation given in the windowdefinition is ignored.

If ’picture’ is excluded from the command, the window is sought from the picture orpicture function where the command was issued. If the window is not found there, thewindow is sought from the entire screen. An error status is produced if the windowcannot be found.

Examples:

!WIN_REP LINE PASSWORD!SHOW LINE;The representation PASSWORD states the form for what is to be shown in the;window LINE. The representation is sought from the file(s) defined by the;library name DEFAULT.!WIN_REP LINE ENG/PASSWORD!SHOW LINE;The same as above, but the representation is sought from the file(s) defined;by the library name ENG.

7.2.3 Input Commands

!CSR_LEFT!CSR_RIGHT!CSR_BOL!CSR_EOL

These commands move the data entry cursor.

!CSR_LEFT moves the data entry cursor one step to the left and !CSR_RIGHT onestep to the right. !CSR_BOL moves the cursor to the beginning of the input field,!CSR_EOL to the end of the input field.

These commands may be used only after the !INPUT_VAR command, and have noeffect if this command has not been issued.

!ENTER

Completes data entry.

After an !INPUT_VAR command has been executed, the system waits for characterinputs until it gets an !ENTER command, or the Enter key on the keyboard is pressed.If the program containing the !ENTER command (usually a function key program)contains other statements after !ENTER, these are executed. Then the program exe-cution continues with the statements following after !INPUT_VAR.

The command has no effect if no !INPUT_VAR command has been issued.

!INPUT_KEY keytext var

Reads function key information.

’keytext’ This argument states the kind of information to be read:



1MRS751250-MEN

ABB Automation82

PROGRAM = the program, HEADER = the function key header,HELP = the function key help text.

‘var' A variable name. The variable will contain the selected informa-tion as a text vector.

The chosen information of the clicked function key is read and placed in the variable'var'. The variable becomes a vector, the length of which is determined by the choseninformation.

After this command has been executed, no other commands are executed until a func-tion key has been clicked.

Example:!INPUT_KEY HELP V!SHOW HELP %V;After the !INPUT_KEY command has been executed, the system waits until a;function key is pressed. If this has a help text, the text will be shown in;the window HELP.

!INPUT_POS var

Reads mouse or cursor position.

'var' The name of a variable.

The command reads the coordinates of the subsequent push on the mouse, or the cor-responding keyboard operation, and stores the coordinates in the given variable. Theentire control board is available. After this command has been executed, no othercommands are executed until a position has been pointed out with the mouse.

The variable 'var' becomes a vector with four integer elements:

(x,y,x_rel,y_rel)

where:

'x,y' are the coordinates for the cursor position in relation to the upperleft corner of the screen which is (1,1). The value range of the x-coordinate is 1 ... 160. The coordinates 1 ... 80 belong to the screenand 81 ... 160 lie on the control board outside the screen. Thevalue range of the y-coordinate is 1 ... 96. The screen part lies inthe range 1 ... 48. The coordinates 49 ... 96 are situated on thecontrol board outside the screen.

'x_rel,y_rel' are the coordinates of the cursor position in relation to the upperleft corner (= (1,1)) of the window where the !INPUT_POS com-mand is executed. These coordinates may have negative values.

Examples:!INPUT_POS V;The position of the following push on the mouse is read and assigned to the;variable V.!WIN_POS WINDOW %V



ABB Automation 83

;The window WINDOW is moved to the position determined by the variable V (only;the first two elements are noted, i.e., the first coordinate pairs).

!INPUT_VAR [picture path]window variable max length

Reads an input value from the user.

’window’ Window name of the input field.

’picture path’ A picture reference according to the format described in Chapter 4.

’variable’ Name of the variable to which the input is assigned.

‘max_legth’ Maximum length of the input string (in fullgraphic input fields)

This command allows the user to assign a value to a variable during operation. Thewindow name states in which window the value is echoed. The statement is executedonly if the window is defined and is of FIELD type. The window definition deter-mines the data type of the variable (integer, real or text) as well as the number ofdecimals (if real data).

After this command, the system waits for an input in the form of characters, from thekeyboard or control board, until it gets an !ENTER command or the Enter/Line Feedkey of the keyboard is pressed. No commands are handled other than those affectingthe character input.

Entering data using the control board requires that a character key set is defined in thepicture. When using the keyboard, lower case letters are converted to upper case let-ters. The Nordic letters Å, Ä, Ö, and the German Ü are converted to the correspond-ing MicroSCADA semi-graphic characters, i.e., the ASCII codes [ , \ , and ].

This command is not allowed in update programs.

Example:!INPUT_VAR WIND V;The value of the variable V is read from the window WIND.

!RUBOUT!RUBOUT_CUR!RUBOUT_BOL!RUBOUT_EOL

Delete input data.

!RUBOUT deletes the character to the left of the input cursor.

!RUBOUT_CUR deletes the character in the current position of the cursor.

!RUBOUT_BOL deletes the beginning of the line until, but not including, the cursor.

!RUBOUT_EOL deletes the end of line starting from the cursor position.



1MRS751250-MEN

ABB Automation84

The commands may be used only after the !INPUT_VAR command, and they have noeffect if this command has not been issued.

!TOGGLE_MOD

Insert/typeover.

Shifts from type-over (default) to insert and vice versa. The command may be usedonly after the !INPUT_VAR command and has no effect if this command has notbeen issued.

7.2.4 Miscellaneous Picture Commands

!SEND_PIC device number

Copies the picture (semi-graphic) to a printer.

’device’ Device name = LPT (line printer).

’number’ Logical printer number. Integer expression, 1 ... 20.

The semi-graphic portions of the picture, in its current format, is copied to a printer("hardcopy"). The printer starts a new page both before and after the printout.

Depending on the printer definition in the base system (the PRIn:BOD attribute), theprintout may be stored on disk.

Example:!SEND_PIC LPT 1

!RESET

Deletes variables in a picture.

All variables assigned before this command, except for those of the start program, aredeleted. At the same time the command !RESTORE (section 7.2.1) is executed.

Example:@PROFIT = 350000!SHOW WIND %PROFIT;350000 is shown in the window WIND.!RESET!SHOW WIND %PROFIT;An error message is displayed.#ON ERROR !RESET;The variables are deleted when an error occurs.



ABB Automation 85

7.3 Control Commands

7.3.1 Program Execution Commands

These commands starts the execution of program blocks, or otherwise affect the pro-gram execution. The #DO, #IF, #ELSE, #BLOCK, #LOOP, #CASE and #ON com-mands can be combined. Altogether, there may be at most 40 of these commandsnested inside one another.

See also the #EXEC commands in section 7.3.2. When used with command proce-dures, these commands start the execution of the command procedure programs.

#BLOCKstatement.....statement#BLOCK_END

Compound statements (block).

’statement’ SCIL statements.

#BLOCK may replace ’statement’ after the commands #ON, #THEN and #ELSE andin loops, see below.

Example:#IF %A > %B #THEN #BLOCK

#IF %A - %B > 10 #THEN #BLOCK!SHOW_WIN "THE VALUE TOO LARGE"

#BLOCK_END#ELSE !SHOW_WIN "CHECK!”#BLOCK_END

#ELSE !SHOW_WIN "OK"

The status code SCIL_INVALID_PROGRAM_STRUCTURE is reported if illegallynested structured statements are found, for example in the following case:#BLOCK

#LOOP_WITH I = 1 .. 10#BLOCK_END ;Extraneous #BLOCK_END, still within a #BLOCK

;#LOOP_END ;#LOOP_END missing;#BLOCK_END ;Proper #BLOCK_END missing

#CASE expression[#WHEN selector statement...........#WHEN selector statement][#OTHERWISE statement]#CASE_END

Case dependent execution of statements.

The command executes different statements or program blocks depending on thevalue of an expression and a number of selectors.



1MRS751250-MEN

ABB Automation86

’expression’ An expression of type integer, real, text, boolean or time.

’selector’ The selector can be given according to any of the following for-mats:

1. An expression of type integer, real, text, boolean, time or vector.2. A list of integer, real, text, boolean, time or vector expressions,separated by commas.3. An interval given in any of the following ways:n1 .. n2 which means all values in the range n1 ... n2n1 .. which means all values above the value of n1.. n2 which means all values up to the value of n2.’n1’ and ’n2’ are integer, real or text expressions.Expressions must be enclosed by parentheses.

’statement’ An arbitrary SCIL statement or a block of statement defined by#BLOCK .... #BLOCK_END

The value of ’expression’ is related to each ’selector’ in the #WHEN commands. Thefirst #WHEN statement where ’selector’ (a value in the list or interval) is equal to ’ex-pression’ is executed. The other #WHEN statements are ignored. If no #WHEN state-ment was executed, i.e., none of the selectors matched the ’expression’, the#OTHERWISE statement (if any) is executed.

There may be several selectors which match the expression, but only the first match-ing #WHEN statement is executed. No error is generated, in case no statement is exe-cuted. The status code SCIL_INVALID_PROGRAM_STRUCTURE is reported if il-legally nested structured statements are found.

Examples:#CASE %D

#WHEN 0,3,6,8,9 @SHAPE = "NO STRAIGHT LINES IN THIS DIGIT"#WHEN 1,2,4..5,7 @SHAPE = "CONTAINS STRAIGHT LINES"#WHEN .. -1 #BLOCK

@WISE_GUY = TRUE@SHAPE = "DON''T TRY TO FOOL ME”

#BLOCK_END#OTHERWISE @SHAPE = "ONE DIGIT ONLY,PLEASE"#CASE_END

#CASE DATA_TYPE(%D)#WHEN "INTEGER" @T = 1#WHEN "REAL" @T = 2#OTHERWISE !SHOW W –

"SIMPLE NUMERIC DATA EXPECTED"#CASE_END

#DO expression

Executes SCIL statements.

’expression’ A text expression or a vector expression with text elements. Thetexts must be composed of SCIL statements.

The #DO command executes the SCIL statement or program defined by ’expression’.The program is handled as a subroutine of the calling program (the program contain-ing the #DO command). #DO is used for repeated execution of program sequences.



ABB Automation 87

Variables defined in the calling program are transmitted to the program representedby ’expression’ and vice versa.

In principle, all kinds of SCIL commands and variable assignments are allowed in’expression’. However, user interface related commands are not allowed when the#DO command is executed from a command procedure. In contrast to from the#EXEC-command (section 7.3.2), #DO immediately executes the program. There isno queue.

Example:#DO READ_TEXT("ABC.TXT");The SCIL program of the file ABC.SCL is executed.

#DO ABC:C;The program of the command procedure ABC is executed. (The RT and OS;attributes of the command procedure are not updated).

#IF condition1 # THEN statement1#ELSE_IF condition2 #THEN statement2#ELSE statement3

Conditional statements.

’condition1’

’condition2’ boolean type expressions

’statement1’

’statement2’

’statement3’ SCIL statements. Each of the statements may be replaced with#BLOCK, see below.

’Statement1’ is executed provided that ’condition1’ is TRUE. Otherwise, if ’condition2’is TRUE 'statement2' is executed. If neither ‘condition1’ nor ‘condition2’ are TRUE,‘statement3' is executed. By using the #BLOCK command (see above), a sequence ofstatements can be executed.

#ELSE_IF and/or #ELSE statements may be omitted, which means that no operationis performed if condition1 is not fulfilled. Several #ELSE_IF statements may succeedeach other.

Examples:#IF HOUR >=7 AND HOUR < 15 #THEN @SHIFT = “MORNING”#ELSE_IF HOUR >= 15 AND HOUR < 23 #THEN @SHIFT = “EVENING”#ELSE @SHIFT = “NIGHT”



1MRS751250-MEN

ABB Automation88

#LOOP [condition]statement...statement#LOOP_END [max]

Executes a loop.

’condition’ A conditional expression that determines if the loop iterates.


’max’ The maximal number of times the loop is iterated. An integer ex-pression. Default value: 1000.

The sequence of statements (the loop) is executed repeatedly as long as the conditionis TRUE, or until the loop is interrupted in one of the following ways :

• The maximum number of loop iterations is reached. In this case the loop inter-ruption causes an error status.

• The innermost loop is interrupted when the command #LOOP_EXIT (see below)is met. This causes no error status.

Emergency interruption from outside the loop can be obtained in the following ways:

• Loops in pictures are interrupted by pressing the upper left corner three times orby the statement:#SET MONn:BMS

where ’n’ is monitor number.

• Loops in command procedures are interrupted by the statement:#SET APLn:BRSm

where ’n’ is the application number and ’m’ represents the queue number of theprocess that runs the command procedure. This number is determined as fol-lows:

’m’ = 1, if the command procedure is non-parallel and started by a time channel

’m’ = 2, if the command procedure is non-parallel and started by an event chan-nel or from a picture.

’m’ = 3 or larger, if the command procedure is parallel. The value can becounted as the PQ attribute of the command procedure + 2, unless PQ = 0.

• Loops in format pictures are interrupted by the statement:#SET APLn:BPSm

where

’n’ is application number,



ABB Automation 89

’m’ = 1 for process printouts and

’m’ = 2 for report printouts.

These loop interruptions produce an error status. The status codeSCIL_INVALID_PROGRAM_STRUCTURE is reported when illegally nestedstructured statements are found.

Example:#SEARCH 1 0 "P" "A"@I = 0@POBJ = NEXT(1)#LOOP (POBJ:VIU >= 0 AND %I < 50)

@I = %I + 1@NAME(%I) = POBJ:VLN@POBJ = NEXT(1)#LOOP_END

!SHOW OBJ %NAME;Process objects are browsed through and the names are written into a vector;variable. The names are shown in a window named OBJ.

#LOOP_WITH var = low .. highstatement...statement#LOOP_END

Executes a loop a chosen number of times.

’var’ A variable name which will contain the number of times the loophas been executed (integer).

’low’ The number of the first loop execution given as an integer expres-sion. If given as an expression containing object notations andvariables, it should be surrounded by spaces or brackets.

’high’ The number of the last loop execution given as an integer expres-sion. If given as an expression containing object notations andvariables, it should be enclosed by spaces or parentheses.


The sequence of statements (the loop) is executed repeatedly a certain number oftimes, defined as ’high’ - ’low’ + 1. Each time the loop is completed, the variable ’var’ isincremented by one.

The innermost loop can be interrupted with the #LOOP_EXIT command (see below).This produces no error status. As regards emergency interruption from outside theloop, see the #LOOP command above.

The status code SCIL_INVALID_PROGRAM_STRUCTURE is reported when ille-gally nested structured statements are found.

Example:#LOOP_WITH I = 1 . . LENGTH(%VECTOR)



1MRS751250-MEN

ABB Automation90

!SHOW WIN’I’ %VECTOR(%I)#LOOP_END;Each of the elements in the vector variable VECTOR is shown in a separate;window.

#LOOP_EXIT

Interrupts a loop.

The command interrupts the innermost one of the running loops. It must be situated inthe same program as the command that starts the loop (#LOOP or #LOOP_WITH).

Example:#LOOP_WITH I = 1 .. 20

!SHOW LOOP_NR %I..!SHOW QUESTION "CONTINUE?Y/N"!INPUT_VAR ANSWER ANSWER#IF %ANSWER == "N" #THEN #LOOP_EXIT

#LOOP_END

#ON event [statement]

Executes a program block when an event occurs.

’event’ An event object notation.

’statement’ A SCIL statement (not obligatory). By using the #BLOCK com-mand (see below), a block of statements can be defined.

This command can be used only in pictures. It has no meaning in dialogs or commandprocedures. Only events from the current application can be caught. If an event from aforeign application is tried to catch, a SCIL error is generated.

’statement’ is executed each time the event object is activated, provided that the pic-ture containing the #ON statement is displayed on screen at the event moment - asmain picture, window picture, picture function or control board picture. If the eventobject is activated while the picture is stored as a fast picture, ’statement’ is executedwhen the picture is displayed on screen. Possible expressions included in the state-ment or block defined by ’statement’ are evaluated when ’statement’ is executed. If’statement’ is omitted, the #ON command cancels the previous #ON command for theevent object in question.

The #ON command affects only the picture (main picture, window picture, picturefunction or control board picture) where it is executed. After the #ON command hasbeen executed in a picture (in a start program or key program), it is valid as long asthe picture is displayed on the monitor or stored as a fast picture, or until it is can-celled by a new #ON command. For a certain event object only the last given #ONcommand is valid in a picture.

The #ON command has no relevance in dialogs.

Examples:#ON TEMP:E1 !SHOW W TEMP:PAI1



ABB Automation 91

;When the event object TEMP:E is activated, the value of the process object;TEMP is shown in the window W.

#ON TEMP:E1;The former statement is canceled.

#ON SWITCH:E2 #BLOCK!SHOW SWITCH SWITCH:PBO2!SHOW TIME SWITCH:PRT2#BLOCK_END

;The block is executed when the event object SWITCH:E2 is activated.

#PAUSE interval

Defines a pause.

’interval’ Time interval in seconds given as a real expression.

This command is used to momentarily interrupt the program execution. For example,after a DCP-NET has been started, a pause is required before you can start the on-lineconfiguration of the NET.

Be careful when using this command, especially in command procedures! #PAUSE ina command procedure entails that all activities in the executing process pause for thetime interval defined by this command.

Examples:#PAUSE 3.5;The system waits for 3.5 seconds before the next statement is executed.#PAUSE %T;The length of the pause is specified by the variable T.

#RETURN [ expression ]

Stops the program execution and evaluates the ‘expression’.

‘expression’ Any SCIL expression.

When #RETURN is encountered in a named program, a method, or a program exe-cuted with the DO function (see Chapter 8), it stops the program execution and evalu-ates the ‘expression’. The value of 'expression' replaces the program or function call ifit appears in an expression.

The #RETURN command may be used without 'expression' in any SCIL program(command procedures, #ON blocks, programs executed by #DO) to exit the program.

A program encountering no #RETURN statement returns a value with data type"NONE".

Example:;Suppose you have the following named programs:;Named program ADD:#RETURN ARGUMENT(1) + ARGUMENT(2)

;Named program MULTI_ADD:@TOTAL = 0#LOOP_WITH I = 1 .. ARGUMENT_COUNT

@TOTAL = %TOTAL + ARGUMENT(%I)#LOOP_END#RETURN %TOTAL



1MRS751250-MEN

ABB Automation92

;After the following named program calls:@S = .ADD(1, 0.5)@M = .MULTI_ADD(1, 2, 3, 4)

S has the value 1.5 and M 10.

7.3.2 General Object Handling Commands

#CREATE object [= expression]

Creates a new object.

’object’ An object notation without any attribute. Object types allowed arethe application objects P, C, D, A, T, X, V, and F, and the systemobjects B. An index may be used only together with process ob-jects of the predefined types.

’expression’ An expression of the data type list. If the object being created is avariable object, the expression may be omitted.

The command creates a new object of the given type, with the given name and index(process objects) and assigns it the attribute values of the list expression. Possible oc-currences of name (LN attribute) and index (IX attribute) in the list expression aredisregarded.

If the process object notation for a process object of a predefined type is given with-out an index, a group with the given name is created. A group is automatically createdwhen an indexed process object of a predefined type is created.

A list type expression can be built by creating a variable object and assigning desiredattributes to it (see the examples below). In order to copy the new object from an ex-isting one, use the list type functions FETCH, PHYS_FETCH, NEXT or PREV(Chapter 8).

An error message is produced if the object already exists, or if the assigned attributes(the attributes of ’expression’) do not suit the actual object type.

The command is mainly used in tool pictures and configuration files.

Example:@TMP = LIST(BI = 0, UN = 20, OA = 1, OB = 2)#CREATE ABC:P1 = %TMP;The process object ABC is created and assigned the attributes of the variable;object V.

#CREATE SYS:B = LIST(SA = 192);A SYS:B object is created and assigned the station address 192.

#DELETE object

Deletes an variable, object or variable object.

’object’ An object notation of type P, C, D, A, T, X, V or F. Process ob-jects of the predefined types may have one index. The other object



ABB Automation 93

types may not be indexed. A variable object notation may have anattribute.

The given object is deleted. If a variable object notation contains an attribute, the at-tribute, and not the variable object, is deleted.

Though all process objects in a process object group are deleted, the group name ispreserved. The group is deleted by giving the process object notation without an in-dex. This may be done only if all objects in the group are deleted beforehand.

A time channel may be deleted only if there is no object connected to it. A scale canbe deleted only if no process objects use it. An object of free type (F) can be deletedonly if all process objects of the corresponding type have been deleted.

Examples:@tmp=1#delete tmp:v;The variable tmp is deleted

#DELETE A:P1;The process object A with index 1 is deleted.

#DELETE A:P;The process object group A is deleted (possible only if there are no objects;in the ;group).

#DELETE GHI:T;The time channel GHI is deleted (possible only if there is no object connected;to it).

#DELETE V:VAB;The attribute AB of the variable object V is deleted.

#EXEC object [(variable list)]

Executes an object.

’object’ An application object notation of type D, C, T, A or E without at-tribute. Only event object notations may be indexed.

’variable list’ A list of variable assignments separated with commas. Notobligatory.

The object may be a data object, a command procedure, a time channel, an eventchannel or an event object:

• If the object is a data object, the value of the object (the OV attribute) is calcu-lated and registered in the database. At the same time the RT and OS attributesare registered.

• A command procedure is started by this command. When the command proce-dure is executed to the completion, the RT and OS attributes are registered. Thecommand procedure must not contain picture or graphics commands.

• A time channel is activated, which means that the data objects and commandprocedures connected to it are executed. This does not affect any other functionof the time channel, and the RT attribute of the time channel is not updated.



1MRS751250-MEN

ABB Automation94

• An event channel is activated, which means that the data object, command pro-cedure or time channel connected to it is executed.

• An event object is activated, which means that the #ON sequences defined forthe object in question are executed in all monitor pictures. The object may haveone index.

Internally, event objects are executed by the picture operator process, and event chan-nels by the event channel process. Regarding data objects and command procedures,there may be different processes that handle the execution. The following circum-stances determines which process that executes the object:

• If the #EXEC command is in a command procedure, and the PE attribute of theobject is 0, the execution is handled by the same process which handles thecommand procedure.

• If the #EXEC command comes from a picture, and the PE attribute of the objectis 0, the execution is handled by the event channel process.

• If the PE attribute of the object is 1, the execution is handled by a parallel proc-ess, which is determined by the PQ attribute.

The operation is not executed at once, the request for execution is placed in a queue.Subsequent statements should not assume that the task of the #EXEC statement hasbeen completed.

In the variable list, values are given to variables used in the object. There must alwaysbe a space before the list. The variable list is omitted if no values are to be sent to theobjects. It is always omitted when the object is an event object. The variable valuesare not transmitted back to the calling program.

Examples:#EXEC_AFTER 10 TASK:C (@LN = “DEFG”, @IX = 1);The command procedure TASK is started.

#EXEC DATA:D (@A = %B + 2);The data object DATA is updated.

#EXEC EVENT:E1;An event object named EVENT is activated.

#EXEC_AFTER delay object [(variable list)]

Executes an object after a time delay.

’delay’ The delay time in seconds given as and integer or real expression.

’object’ An object notation of type D, C, T, A or E without attribute. Onlyevent object notations may be indexed.

’variable list’ A list of variable assignments separated with commas. Notobligatory.

The command works like #EXEC, but the execution is delayed for ’delay’ seconds.



ABB Automation 95

If the ’object’ does not exist, or if it is erroneous, an error status is produced when theobject is executed, after the delay. The amount of delayed executions is controlled bythe APL:BQU(4) and APL:BQM(4) attributes (see Object Description, Chapter 5).APL:BQU(4) is the sum of delayed executions not yet started and the APL:BQM(4) isthe maximum number of such executions. If the maximum is exceeded, an error status(REPF_EXECUTION_QUEUE_FULL) is generated.

Example:#EXEC_AFTER 10 TASK:C (@LN DEFG,@IX=1);The command procedure TASK is started after 10 seconds.

#GET object

Updates process object values.

’object’ A process object notation or an STA system object notation withthe attribute ME.

The command entails that the object value is read from the station and updated in theprocess database. The object may be indexed. For process objects, the attribute maybe omitted. It is then assumed to be OV. The command is valid only for process ob-jects corresponding to physical objects in stations on ANSI lines.

Examples:#GET A:PBI#GET B:PBI(1..4)#GET STA1:SME1003^3;The binary object A, the four first indexes of the binary object B and bit;number 3 in station address 1003 of station 1 are read from the RTUs and;updated in the process database.

#MODIFY object = expression

Changes an object definition.

’object’ An application object notation without an attribute. Allowed ob-ject types are P, C, D, A, T, X, V and F. Process objects may haveone index.

’expression’ An expression of data type list.

The object is assigned the attributes and attribute values of the list expression. Theattribute values in the expression replaces possible previous attribute values of theobject. If the object has attributes, which are not included in the expression, they re-main unchanged. If UN and OA attributes are set equal to 0, an error,PROF_BIT_ADDRESS_NOT_ALLOWED, is generated.

Scale objects used by process objects cannot be renamed.

Examples:#CREATE V:V#SET V:VHR = 24#SET V:VTC = "TC_1H"#MODIFY DEF:D = %V;The HR and TC attributes of the data object DEF are changed, but all other



1MRS751250-MEN

ABB Automation96

;attributes remain unchanged.

#MODIFY PROC:P = LIST(AE=1,AN="A_1");The process object PROC is connected to the event channel A_1.

#SET object [= expression]

Assigns values to objects.

’object’ An object notation of type P, D, S, C, T, A, X, V, B or F, includingthe attribute to be set. See Chapter 4.

’expression’ An expression of the same data type as the attribute in the objectnotation (not obligatory). Default = 1.

The attribute in the object notation is assigned the value of the expression. If ’expres-sion’ is omitted, the object is assigned the value 1.

With this command all types of system and application objects, except event objects,may be given values through their attributes. For real process objects of output type,the command implies control of the process via NET. When process objects are set,the RT and RM attributes of the objects (output as well as input objects) are set ac-cording to the system time.

Depending on the object type and the attribute, the object notation may be indexed byone index or an index range. Data objects can be indexed up to the value of the LRattribute. If the object notation has an index range, the given indexes are assigned thevalue of ‘expression’. If ‘expression’ is a simple data, all indexes are assigned thisvalue.

Data object and process object notations may used without an attribute. It is then as-sumed to be the OV attribute.

The attributes which are described as “read-only” in the attribute descriptions (theApplication Objects and System Objects manuals) cannot be set with the #SET com-mand.

Examples:#SET SWITCH:PBO = 1;The switch is set to 1. If the object is in AUTO state, the order is passed;out to the process.

#SET STA3:SME(3121^0..3121^7) = 0;All storage bits in the given interval are set to zero.

#SET TASK:CIU = 1;The command procedure TASK is taken into use.

#SET DATA:DOV5 = 10.0;The fifth registration of the data object is set to 10.0.

#SET TC_1H:TIU = 0;The time channel TC_1H is taken out of use.

#SET A:AON = "B";The event channel A is connected to the object B.

#SET TMP:VATTRIBUTE1 = (1,2,3);The variable object TMP is given an attribute named ATTRIBUTE1 which is;assigned the vector value (1,2,3).

#SET PRI1:BLP = 72



ABB Automation 97

;The number of lines per page is set to 72 for printer 1.

7.3.3 Object Query Commands

#INIT_QUERY n [condition]

Initiates a process query.

’n’ Text expression with the values "A", "P" , "L", "H" or "E":

"A" (Alphabetical)The query encompasses the entire process da-tabase in alphabetical order, so that for eachprocess object group, every index is included(LN+IX).

"P" (Physical) The query concerns the entire process database,but the objects are ordered according to theirphysical addresses (UN + AO + OB).

"L" (alarm List) The query concerns the alarm buffer. The alarmbuffer contains all alarming or unacknowledgedprocess objects sorted in time order accordingto the alarm time (the AT and AM attributes).The buffer is read from the newest to the oldestalarms.

"H" (History) The query concerns the history buffer, which isread with the oldest event first. The historybuffer contains events which occurred in proc-ess objects defined with history buffering (theHA attribute). When this value is chosen, theHP attribute of the application has to have thevalue “EVENT_LOG”.

"E" (Event) The query concerns the history buffer, which isread with the latest event first. When this valueis chosen, the HP attribute of the applicationhas to have the value “EVENT_LOG”.

'condition' A boolean type expression which selects the objects to be includedin the query. The condition is comprised of relations and logicaloperators. The relations have an attribute as the left operand. Allattributes (including CA), except those of vector type, can be used.The objects, the attributes of which fulfill the condition (give theexpression the value TRUE), are included in the query. In the for-mation of names, the characters % and * can be used. % representsone character anywhere in the name, * represents none, one orseveral characters at the end of the name.

With this command you determine which items are to be included in the processquery executed by the function PROD_QUERY (Chapter 8). The #INIT_QUERY



1MRS751250-MEN

ABB Automation98

command must precede the PROD_QUERY function within the same picture orcommand procedure. Only one #INIT_QUERY at a time is valid.

The #INIT_QUERY command searches through the process objects in the RAMmemory. If no condition is given, the query concerns all process objects within thescope specified with ’n’. The query concerns only the process objects of the applica-tion where the query command is issued.

The command assumes that the maximum length for the process database queries,which is defined by the base system object attribute APL:BQL, is large enough.

Examples:#INIT_QUERY "A";The process query includes all objects in alphabetical order.

#INIT_QUERY "P" UN == 5;The objects of RTU 5 in address order.

#INIT_QUERY "A" LN == "K*";Process objects beginning with K.

#INIT_QUERY "L" AR == 0;Unacknowledged objects in the alarm list.

#SEARCH n apl type order [start [condition]]

Initialises a search among objects.

’n’ The identification number of the search. An integer expression 1 ...10 that identifies the search within a picture, command procedureor dialog system.

’apl’ Logical application number. Integer expression, 0 . . . 20. 0 = theown application. The application must be situated in the same basesystem.

’type’ The object type, "P", "D", "C", "A", "T", "X" or "F" given as a textexpression.

’order’ The search order given as a text expression:

"A" = Alphabetical order. Searching through the ob-ject names in alphabetical order (no index).Regarding process objects, only group namesare included in the search.

"I" = Index order (only for process objects of prede-fined types). Searching through the individualobjects of a process object group.

"P" = Address order (only for process objects).

"E" = Execution order. The execution order within atime channel. ’type’ can be either "D" or "C".Both are equal and means that the search con-



ABB Automation 99

cerns both data objects and command proce-dures.

’start’ The starting point of the search. Depending on ’order’, the pa-rameter has the following values:

’order’ = "A": name, where ‘name’ is object name as a textexpression. If omitted, the search starts fromthe first name.

'order' = "I": name or (name,index), where ‘name’ is thename of the object given as a text expressionand ‘index’ is omitted, the browsing starts fromthe first index.

'order' = "P": unit or (unit,address) or (unit, address, bit ad-dress), where ‘unit’ is the RTU number givenas an integer expression, ‘address’ is the wordaddress given as an integer expression, ‘bit ad-dress’ is the bit address given as an integer ex-pression.

'order' = "E": time channel or (time channel, type, name),where ‘time channel’ is the name of the timechannel given as a text expression, 'type' and'name' is the name and type of the connectedobject from where the search starts, given astext expressions.If only the time channel name is given, thesearch starts from the object with the highestpriority. Otherwise, the search starts from theobject called 'name' of type 'type'. Both dataobjects and command procedures are included.

'start' is obligatory when 'order' is "I" or "P", and when a conditionis appended to the statement. If 'order' is "A" or "E", 'start' can begiven as an empty string (" ").

'condition' A boolean type expression which selects the objects to be includedin the browsing. The condition is comprised of relations and logi-cal operators. The relations have an attribute as the left operand.All attributes, except vector type attributes, can be included in theexpression. The objects, the attributes of which fulfill the condi-tion (give the expression the value TRUE), are included in thebrowsing. In the formation of names, the characters % and * canbe used. % represents one character anywhere in the name, * rep-resents none, one or several characters at the end of the name.

The #SEARCH command initializes a search among the objects stored on hard disk.After a search has been initialized, it can be completed with the functions NEXT andPREV (see Chapter 8). Up to ten searches can be initialized in parallel in a picture,command procedure or dialog system.



1MRS751250-MEN

ABB Automation100

Examples:#SEARCH 1 0 "P" "A";All process objects are included in search number 1 which is per formed in;alphabetical order.

#SEARCH 2 2 "T" "A";Browsing through all time channels in alphabetical order.

#SEARCH 3 1 "P" "P" (4,1000) LN == "B*";The search refers to those objects of station 4 which have an address = 1000;(octal number) and begins with B. The search is performed in address order.

#SEARCH 4 0 "D" "E" "10MIN";Searching among those data objects and command procedures which are connected;to the time channel 10MIN.

7.3.4 Printout Commands

#LIST printer object [(variable list)]

Prints process object data.

’printer’ Logical printer number. Integer expression, 1 ... 20.

’object’ A process object notation without an attribute.

’variable list’ A list of variable assignments, separated with commas (notobligatory).

The format picture of the process object is written to the printer. If the process objectis given with an index, the physical format picture (PF) is written, otherwise the logi-cal format picture of the group (LF) is used. For process objects of user-defined types,the command always prints the physical format picture (PF).

The start program of the picture, exclusive of the picture commands, is executed be-fore printout. Only those windows which have an expression are printed. Curves andbars are not printed. Depending on the printer definition in the base system (thePRIn:BOD attribute), the printout may be stored on disk.

The variable list, which may be omitted, defines the variables used in the printed pic-ture (in windows or in start programs). The variable list may assign a value to a vari-able called FORM_FEED, which determines the paper form feed, see the #PRINTcommand. Together with #LIST, the default value of FORM_FEED is 0, which meansthat the printer starts a new page only when the previous one is full.

The #LIST command defines a couple of variables which get their names as well astheir values from attributes ("snapshot variables"). If the process object is given withan index, these attributes may be (depending on the object type and definition): LN,IX, OV, BI, BO, DB, DI, DO, AI, AO, PC, BS, AL, AS, OS, SE, SP, OF, AZ, RT,RM, AT, AM and CA. For user-defined object types also other attributes may also betransferred to variables. The corresponding variables (for example %LN) may be usedin the physical format. If the process object is given without an index, only the LN at-tribute is transmitted in this way to the logical format. The variable values given inthe variable list have precedence of these automatically generated variables.



ABB Automation 101

Examples:#LIST 3 TEMP:P (@A=30);The logical format of the process object group is printed to printer 3. The;printer starts a new page both before and after each printout.

#LIST 1 LEVEL:P7 (@FORM_FEED = 2);The physical format of the process object is printed to printer 1. E.g. the;variable %LN has the value "LEVEL", and the variable %IX the value 7. The;printer starts a new page before, but not after a printout.

#PRINT printer picture [(variable list)]

Prints a picture.

’printer’ Logical printer number. Integer expression, 1 ... 20.

’picture’ The picture to be printed, specified as:[path/] picture name

where’picture name’ is picture name exclusive the extension, and’path’ is a logical path name.If ’path’ is omitted, the default path names are used. See the#PATH command, section 7.3.6.

’variable list’ A list of variable assignments, separated by commas. Not obliga-tory.

This command is used when a paper printout of a picture is needed, for example, areport picture. The start program of the picture, excluding the picture commands, isexecuted before the print process. Only those windows which have an expression areprinted. Curves and bars are not printed. Depending on the printer definition in thebase system (the PRIn:BOD attribute), the printout may be stored on disk.

The variable list, which may be omitted, defines the variables used in the printed pic-ture (in windows or in start programs). In addition, the variable list may assign a valueto a predefined variable called FORM_FEED, which controls the form feed duringprinting. The FORM_FEED parameter can have the following values:

0 ........ form feed only when the page is full (the page length is determined bythe PRIn:BLP attribute, where ’n’ is physical printer number)

1 ........ form feed before (if not already done) and after printout 2 ........ form feed before printout (if not already done)3 ........ form feed after printout

Together with #PRINT, the default value of FORM_FEED is 1.

Examples:#PRINT 1 REPORT (@VAR=TEMP:PAI(1..20));The picture named REPORT is written to printer 1. The printer starts a new;page both before and after each printout.LOOP N = 1 . . 20

#PRINT 1 FORM_’N’ (@FORM_FEED = 0)#LOOP_END

;The pictures FORM_1 ... FORM_20 are printed without form feed.



1MRS751250-MEN

ABB Automation102

7.3.5 Error Handling Commands

The commands in this section specifies the error handling within programs.

#ERROR IGNORE#ERROR CONTINUE#ERROR STOP#ERROR EVENT

Define error handling policy.

IGNORE means that the program execution continues regardless of errors.The error handling programs are not activated and no error mes-sage is produced.

CONTINUE means that an error handler is activated or an error message is pro-duced, but the program execution continues.

STOP means that an error handler is activated or an error message is pro-duced and the execution of the program containing the error isaborted. The statement of an active #ON ERROR command isexecuted (see below).

EVENT means that the execution of the program containing the error isaborted, but no error message is produced. The statement of an ac-tive #ON ERROR command is executed (see below). Not possiblein the methods of the dialogs.

An #ERROR command applies only to the program or #ON block in which it is exe-cuted. The latest given #ERROR command is valid.

The most recent error status that has occurred in the program can be read with theSTATUS function, Chapter 8.

If no ERROR command has been executed in a program, the following default poli-cies are valid:

Background and draw programs: CONTINUEStart programs: STOP in monitors, IGNORE when printedUpdate programs: IGNOREExit Programs: IGNOREKey programs: STOPNamed programs: STOP (not in ERROR_HANDLER)Command procedures: STOP#ON blocks: IGNOREMethods in dialogs: STOP ( not in delete method)Error handling programs: IGNORE

In error handling programs, the error handling policy is always IGNORE, independ-ently of possible #ERROR commands. In delete methods all errors are ignored.



ABB Automation 103

#ERROR RAISE [status]

Activates an error status.

’status’Integer expression. The status code to be activated. Default: the latest errorcode occurred in the program.

The command is mainly used within error handling blocks (#ON ERROR or #ONKEY_ERROR blocks) in order to activate an error status in the program. In error han-dling blocks, ’status’ can be omitted, whereby the activated status is the most recent er-ror status that has occurred in the program. Outside an error handling block, the com-mand interrupts the program execution.

Example:#ON ERROR #BLOCK#IF STATUS = 107 #THEN !SHOW

#ELSE #ERROR RAISE#BLOCK_END

#ON ERROR [statement]

Defines an error handler.

’statement’ A SCIL statement to be executed when an error occurs. By usingthe #BLOCK command (section 7.3.1) a block of statements canbe defined.

The command defines a statement, or block of statements, to be executed in a pro-gram each time an error occurs, in the cases where the error handling is defined by#ERROR STOP or #ERROR EVENT (see above). The command is valid only for theprogram or #ON block in which it has been executed. Only the last executed #ONERROR command is valid. The #ON ERROR command takes precedence over the#ON KEY_ERROR command (see below).

Example:#ON ERROR !SHOW MESSAGE STATUS;The window MESSAGE is shown when an error occurs.

#ON KEY_ERROR [statement]

Defines a key error handler.

’statement’ A SCIL statement. By using the #BLOCK command, a block ofstatements can be defined.

The command defines a program section to be executed in a picture each time an erroroccurs in a function key program. The command is valid only in the picture in whichit has been executed. If there is no key error handler in a picture, it utilizes the errorhandler of its main picture, if any. The #ON ERROR command (see above) takesprecedence over the #ON KEY_ERROR command.



1MRS751250-MEN

ABB Automation104

Example:#ON KEY_ERROR !SHOW MESSAGE "FUNCTION KEY ERROR"

7.3.6 Path Commands

#PATH name [dir, .., dir]#PATH name + dir, .., dir,#PATH name - [dir, ... , dir]

Defines a logical path name.

’name’ A logical path name. The name must be added here according tothe rules in Chapter 2.

’dir’ Real directory name including the complete path in the operatingsystem format. A starting \ means that the directory path startsfrom the sc directory. A trailing \ is stripped off, so the path can bewritten either with or without it. Up to 255 directories are allowedin the command. If a directory does not exist, it is automaticallycreated. However, if the word NO_CREATE is included in the di-rectory list, the subsequent directories are not created. If they donot exist, the error FILE_DIRECTORY_DOES_NOT_EXIST israised. Default directory: The directory from where the main pro-gram has been started.

Logical path names can be used in all commands where files are called by name, e.g.together with picture names. Each path name may correspond to several directories,which are given in order of priority and separated by commas. When a file is re-quested with the path name, it is first searched for in the first directory of the path,then in the next one, etc. If a path name is used when a new file (e.g. a picture) is cre-ated, the new file will be stored in the first directory of the path name.

A #PATH command without any sign defines a "global" path. Such a path definitionis monitor specific when executed in a picture or dialog. If executed in a commandprocedure, it applies to all command procedures. If executed in a printed picture, itapplies to all pictures printed with #PRINT. If the directory list is omitted, all directo-ries of the path name are removed, but the path name remains.

A #PATH command with a + or - sign defines "local" and temporary paths by addingdirectories to, or removing them from, the path definition. A + sign means that the di-rectories are added to the beginning of the directory list of the path name. A - signmeans that the directories are removed from the directory list. If the directory list isomitted, the - sign removes all locally defined directories from the path name. (Note:as a terminating - sign means that the statement is continued on the next line, and inthis case should be typed as two subsequent minus signs followed by an empty line,see the example below).

A local path applies only to for the dialog system, picture, printout picture, commandprocedure or time channel (objects started by the same time channel) where it was de-fined. A local path defined in a picture is valid as long as the picture is shown orstored as a fast picture. In a printout picture, it is valid as long as the picture is



ABB Automation 105

printed, and in a command procedure as long as it is under execution. A local path de-fined in a command procedure started by a time channel is valid as long as the timechannel is active. The local path definitions have precedence over the global ones.

When an object invokes another one, both the global and local path definitions are in-herited as local path definitions in the started object. If, e.g., a picture program starts acommand procedure, the paths of the picture will be local paths in the command pro-cedure and, hence, take precedence over the global command procedure paths.

The latest definition of a path is valid. Hence, by defining paths locally (with + and -),you ensure that no inherited definitions will override the desired path definitions.

The following automatically defined path names are used as default paths:

SCS_ \SCS\ACTIVE\SCS_

LAN_ \LAN\ACTIVE\LAN_

SYSF \LAN\ACTIVE\SYSF

SYSO \LAN\ACTIVE\SYSO

PICG \LAN\ACTIVE\PICG

PICL \LAN\ACTIVE\PICL

PROD \LAN\ACTIVE\PROD

PROL \LAN\ACTIVE\PROL

REPC \LAN\ACTIVE\REPC

REPL \LAN\ACTIVE\REPL

SYS_ \SYS\ACTIVE\SYS_

APL_ \APL\application\APL_

FORM \APL\application\FORM

PICT \APL\application\PICT

These default path names are valid everywhere, though the corresponding directoriesmay be changed globally or locally. A file called without any path name is stored orsought in the directory/directories defined by the default path name which coincidewith the first four characters in the file name. If no other path name suits, PICT isused. Visual SCIL main dialogs constitute an exception to this case. This is describedin the Visual User Interface Design manual.

The path name definitions, except the original default path names, are removed whenthe system is shut down or the application is closed.



1MRS751250-MEN

ABB Automation106

Defined paths can be read with the path functions, see Chapter 8.

Example:#PATH PROCESS /APL/APPL1/PICT, NO_CREATE, /APL/APPL2/PICT;A logical path named PROCESS is created. If the directory /APL/APPL1/PICT;does not exist, it is created, but if the directory /APL/APPL2/PICT does not;exist, it is not created.

!NEW_PIC PROCESS/PICTURE;The picture named PICTURE is first sought in the application branch APPL1,;then in application branch APPL2.

#PATH PROCESS +/APL/APPL3/PICT;The picture named PICTURE is first sought in the application branch APPL3,;then APPL1 and APPL2.#PATH PROCESS - -

;empty line;The local path definitions (/APL/APPL3/PICT) is removed.

#REP_LIB library [file, ...,file]#REP_LIB library + [file, ...file]#REP_LIB library - [file, ...file]

Defines a logical representation library name.

’library’ A logical library name. The name must adhere to the rules inChapter 2.

’file’ A representation library file specified in either of the followingtwo manners:

1. [path/]file_name

where ’path’ is a logical path name and ’file_name’ is the name ofthe file, possibly including an extension. If ’path’ is omitted, the de-fault path names are used (see the #PATH command above).

2. file_name

where ’file_name’ is the name of the file including the completepath in the operating system format (max. 14 characters).Up to 255 representation library files can be included in the com-mand.

Logical library names can be used everywhere, where library representations are re-quested. Each library name may correspond to several library files, given in order ofpriority and separated by commas. When a library representation is requested, it isfirst sought in the first library, then in the next one, etc. If a library name is used whena new library representation is created, the new representation will be stored in thefirst file related to the library name.

A #REP_LIB command without any sign defines a "global" library name. Such aname is monitor specific, when executed in a picture or dialog. If executed in aprinted picture, it applies to all pictures printed with #PRINT. If the file list is omit-ted, all files defined for the library name are removed, but the library name is pre-served.



ABB Automation 107

A #REP_LIB command with a + or - sign defines "local" and temporary library namesby adding files to, or removing files from, the given library name. A + sign means thatfiles are added to the beginning of the file list of the library name. A - sign means thatfiles are removed from the list. If the file list is omitted from the command, the minussign removes all locally added files from the actual library name. (Note: as a termi-nating - sign means that the statement is continued on the next line, this case shouldbe typed as two subsequent minus signs followed by an empty line, see the examplebelow).

The local definitions are picture and printout picture specific. If executed in a picture,they are valid only as long as the picture is shown or stored as a fast picture. In aprintout picture, they are valid as long as the picture is printed. The local definitionshave precedence over the global ones. If a printout is started from a picture, theprinted picture inherits all its global and local library name definitions as local defini-tions. The latest definition of a library name is valid. Hence, by defining librarynames locally (with + and -), you ensure that no inherited definitions will override thedesired library name definitions.

If no library name is given, a representation is searched for in the library calledDEFAULT. Unless changed with a #REP_LIB command, the library nameDEFAULT corresponds to the files:

1. /APL/application/APL_STAND.PIR

2. /LAN/ACTIVE/LAN_/LAN_STAND.PIR

in the order outlined.

An error status is produced if a non-existent or empty logical library name is used.

The logical library name definitions, except the original meaning of DEFAULT, areremoved when the system is shut down or the application is closed. If a logical repre-sentation name is defined or redefined with #REP_LIB, and the real file does not ex-ist, the logical name is deleted.

Defined library names can be read with the replib functions, see Chapter 8.

Example:#PATH PATH /APL/APPL2#REP_LIB PROCESS PATH/MYLIB!WIN_REP WINDOW PROCESS/MYREP;The library representation MYREP, which is to be shown in the window WINDOW,;is sought from the file MYLIB in the application APPL2.

7.3.7 File Handling Commands

#CLOSE_FILE n

Closes a keyed file.

’n’ File number. The file number assigned to the file when openedwith the #OPEN_FILE or #CREATE_FILE command. Integer ex-



1MRS751250-MEN

ABB Automation108

pression, 1..10.

Closes the file defined by ’n’. This command should always be issued to terminate theoperations on an opened file.

Example:#CLOSE_FILE 2;The file opened as number 2 in a picture or command procedure is closed.

#CREATE_FILE n apl file keylength

Creates and opens a new keyed file.

’n’ File number. An ordinal number which identifies the file withinthe picture, command procedure or dialog system where the#CREATE_FILE command is executed. Integer expression, 1...10.

’apl’ Logical application number, integer expression 0... 99. 0 is theown application. The application must be local.

’file’ Text expression. The file to be created specified in one of the fol-lowing ways:

1. [path/]file_name

where ’path’ is a logical path name and ’file_name’ is the name ofthe file, possibly including an extension. If ’path’ is omitted, the de-fault path names are used (see the #PATH command describedearlier).

2. file_name

where ’file_name’ is the name of the file including the completereal path in the operating system format (max. 14 characters).

’keylength’ The key length. Integer expression.

The command creates a file with the properties given as arguments and opens the file.After completing the operations on the created and opened file, it should be closedwith the #CLOSE_FILE command (see above).

Example:#CREATE_FILE 3 0 "RTU5" 5;A file called RTU5 with the key length 5 is created and opened in the current;application.

#DELETE_FILE apl file

Deletes a file.

’apl’ Logical application number. Integer expression, 0 ... 99. 0 = thecurrent application. The application must be local.



ABB Automation 109

’file’ Text expression. The file to be deleted given in one of the follow-ing two ways:

1. [path/]file_name

where ’path’ is a logical path name and ’file_name’ is the name ofthe file, possibly including an extension. If ’path’ is omitted, the de-fault path names are used, see the #PATH command, section 7.3.6.

2. file_name


The command deletes the named file in the given application. Use this command withcare. The file deletion cannot be undone.

Example:#DELETE_FILE 3 "RTU52";The file RTU5 in application 3 is deleted.

#OPEN_FILE n apl file keylength

Opens a keyed file.

’n’ File number. A number which identifies the file within the picture,command procedure or dialog system where the #OPEN_FILEcommand is executed. Integer expression, 1..10.

’apl’ Application number, integer expression 0 ... 99. 0 = the current ap-plication. The application must be local.

’file’ Text expression. The ASCII file from where text lines are read.The file can be specified in one of the following ways:

1. [path/]file_name

where ’path’ is a logical path name and ’file_name’ is the name ofthe file, possibly including an extension. If ’path’ is omitted, the de-fault path names are used (see the #PATH command, section7.3.6).

2. file_name


’keylength’ A variable name.

The command opens a file for operations. Any keyed file can be opened. Up to 10files can be open at the same time in a picture, command procedure or dialog system.



1MRS751250-MEN

ABB Automation110

The variable ’keylength’ gets the value of the key length (integer) used in the file.

After completing the operations on the opened file, it should be closed with the#CLOSE_FILE command, see below.

Example:#OPEN_FILE 2 1 "RTU3" %L;The file RTU3 in application 1 is opened. The variable %L will contain the key;length.

#READ n key result1 [result2]

Reads a keyed record in an open file.

’n’ File number. The file number assigned to the file when openedwith the #OPEN_FILE or #CREATE_FILE commands (seeabove). Integer expression, 1...10.

’key’ The key of the record to be read. A text expression containing’keylength’ number of characters (see the #OPEN_FILE commandabove).

’result1’ Variable names.

’result2’

The command reads the contents of the record defined by ’key’ and places it as a textin one or two variables, ’result1’ (up to 255 characters) and ’result2’ (the rest of thecontents if the record exceeds 255 characters).

Example:#READ 2 RTU_KEY(X:POA1) V1 V2;The record corresponding the process object X in the opened file number 2 is;read. The RTU_KEY function is described in Chapter 8.

#READ_KEYS n vector [key1 [key2]]

Reads the keys of an open file.

’n’ File number. The file number assigned to the file when openedwith the #OPEN_FILE or #CREATE_FILE commands (seeabove). Integer expression, 1..10.

‘vector' A variable name.

'key1' The first key to be read. A text expression containing 'keylength'number of characters (see the #OPEN_FILE command above). Notobligatory.

'key2' The last key to be read. A text expression containing 'keylength'number of characters. Not obligatory.



ABB Automation 111

The command reads the keys of the file defined by ’n’ and stores them in the variable’vector’. Up to 10000 keys are read, starting from ’key1’ and ending with ’key2’. If’key2’ is omitted the keys are read to the end of the file, or until the vector is full(10000 keys). If ’key1’ and ’key2’ are omitted, the keys of the entire file, up to 10000,are read.

Example:#READ_KEYS 2 V;The keys in the file opened as number 2 are read and stored in the variable V;(up to 10000).

#READ_NEXT n key result1 [result2]

Reads a keyed record.

’n’ File number. The file number assigned to the file when openedwith the #OPEN_FILE or #CREATE_FILE commands (seeabove). Integer expression, 1..10 .

’key’ The key of the record previous to the record to be read. A text ex-pression.


’result2’

The command reads the contents of the record following the record defined by ’key’and places it as text in one or two variables, ’result1’ (up to 255 characters) and ’re-sult2’ (the rest of the contents if the record exceeds 255 characters).

Example:#READ_NEXT 2 RTU_KEY(A:POA1) V1 V2;The record following process object A1 is read. The RTU_KEY function is;described in Chapter 8.

#READ_PREV n key result1 [result2]

Reads a keyed record.


’key’ The key of the record following the record to be read. A text ex-pression.


’result2’

The command reads the contents of the record previous to the record defined by ’key’and places it as text in one or two variables, ’result1’ (up to 255 characters) and ’re-



1MRS751250-MEN

ABB Automation112

sult2’ (the rest of the contents if the record exceeds 255 characters).

Example:#READ_PREV 2 RTU_KEY(A:POA1) V1 V2;The record previous to the process object A is read. The RTU_KEY function is;described in Chapter 8.

#REMOVE n key

Deletes a keyed record.


’key’ The key of the record to be deleted. A text containing ’keylength’number of characters (see the #OPEN_FILE command above).

The command deletes the chosen record. The deletion cannot be undone.

Example:#REMOVE 2 RTU_KEY(D:POA5);The record configuring the process object D is deleted.

#RENAME_FILE apl old new

Renames a file.

’apl’ Logical application number. Integer expression, 0 ... 99. 0 is thecurrent application. The application must be local.

’old’ Text expression. The file to be renamed given in one of the fol-lowing two ways:

1. [path/]file_name

where ’path’ is a logical path name and ’file_name’ is the name ofthe file, possibly including an extension. If ’path’ is omitted, the de-fault path names are used, see the #PATH command, section 7.3.6.

2. file_name


’new’ Text expression. The new file given in the same way as ’old’.

The command renames the file ’old’ to ’new’. If ’new’ already exists,an error message is raised.

Example:#RENAME_FILE 0 "W89" "W90";The file W89 in the current application is renamed to W90.



ABB Automation 113

#WRITE n data1 [data2]

Writes a keyed record in an open file.

’n’ File number. The file number assigned to the file when openedwith the #OPEN_FILE or #CREATE_FILE command (see above).Integer expression, 1..10.

’data1’

’data2’ Two text expressions containing the data to be written.

The command writes a record to the file defined by ’n’. ’data1’ contains as a text thekey of the record and data to be written, up to 255 characters. The rest of the data tobe written is in ’data2’. The key is included as the first characters in ’data1’.

Any possible previous data in the record is overwritten.

Example:#WRITE 2 %V1 %V2;The data of the variables %V1 and %V2 is written in the file opened as number;2.

7.3.8 Miscellaneous Commands

#SET_TIME time

Sets the system time.

The command sets the time of the system clock (both the operating system clock andthe physical clock). If the computer has an external clock, the command has no rele-vance.

’time’ Time given in the format YY-MM-DD HH:MM:SS (if SYS:BTF =0) or DD-MM-YY HH:MM:SS (if SYS:BTF = 1). The secondsmay be omitted.

Example:#SET_TIME 90-04-25 12:00

7.4 Visual SCIL Commands

The Visual SCIL commands creates, loads and deletes the Visual SCIL objects andhandles the attributes of the Visual SCIL objects. The Visual SCIL objects are super-ficially described in Chapter 4 of this manual. They are described in more detail in theVisual SCIL User Interface Design and Visual SCIL Objects manuals.



1MRS751250-MEN

ABB Automation114

7.4.1 Loading, Creating and Deleting Visual SCIL Objects

.CREATE object = type [(attribute = value, .... , attribute = value)]

Creates a Visual SCIL object.

’object’ The name of the object or an object reference including the path(see Chapter 4). Giving a path means that the object is created asthe last child in the object chain. The object name must be uniqueamong the objects with the same parent. Up to 63 alpha-numericcharacters are allowed in the object name.

’type’ The name of the Visual SCIL object type. See the manual VisualSCIL Objects.

’attribute’ The name of an attribute which is assigned the subsequent value. Ifno predefined attribute with the given name exists, the attribute iscreated as a user defined attribute.

‘value’ The value assigned to the attribute. If the attribute is predefined,the value must be of the correct data type (see the manual VisualSCIL Objects). If the attribute is user defined, the value may be ofany data type.

The .CREATE command creates the object and loads it into the dialog system. Unlessan object path is given, the object will be the child object of the object containing the.CREATE command.

The predefined attributes which are not assigned values in the attribute list are givendefault values. After an object has been created, its attributes can be changed with the.MODIFY and .SET commands, see below.

The .CREATE command is normally used for creating objects whose appearance isdynamically defined, based on some run time information. It must also be used forcreating objects of the ready-built types which are not accessed in the Dialog Editor.The .LOAD command described below is used for loading dialogs and dialog itemsdrawn in the editor.

Generally, methods cannot be written with this command. However, if the object hasaction methods, these can be written with attributes, see the manual Visual SCIL Ob-jects. Except for this type of methods, objects created with .CREATE will only havethe predefined methods with predefined contents.

Examples:.create CANCEL = VS_BUTTON(_TITLE =“Cancel”, _NOTIFY=vector(“.delete DLG”));The statements above creates a button with the label text Cancel and the;NOTIFY program .delete DLG (deletes the dialog DLG).

.create ROOT\DLG = VS_DIALOG( - _GEOMETRY=LIST(X=100,Y=100,W=220,H=110))

.create ROOT\DLG\GROUP = VS_CONTAINER( - _GEOMETRY=LIST(X=5,Y=5,W=100,H=100))



ABB Automation 115

.create ROOT\DLG\GROUP\ROWS = VS_CHECK_BOX( - _TITLE="Check 1", - _GEOMETRY=LIST(X=5,Y=5,W=80,H=20))

.create ROOT\DLG\GROUP\COLUMNS = VS_CHECK_BOX( - _TITLE="Check 2", - _GEOMETRY=LIST(X=5,Y=30,W=80,H=20))

.create ROOT\DLG\CONTAINER = VS_CONTAINER( - _GEOMETRY=LIST(X=115,Y=5,W=100,H=100))

.create ROOT\DLG\CONTAINER\OK = VS_BUTTON( - _TITLE="OK", - _GEOMETRY=LIST(X=5,Y=5,W=50,H=25))

.create ROOT\DLG\CONTAINER\CANCEL = VS_BUTTON( - _TITLE="Cancel", - _GEOMETRY=LIST(X=5,Y=35,W=50,H=25))

.create ROOT\DLG\CONTAINER\HELP = VS_BUTTON( - _TITLE="Help", - _GEOMETRY=LIST(X=5,Y=65,W=50,H=25))

.set ROOT\DLG._OPEN = TRUE

The example above creates a dialog containing two containers, each of which containsdialog items. The last statement makes the dialog visible on screen.

.DELETE object

Deletes a Visual SCIL object.

’object’ The object name, possibly including a path (see Chapter 4).

Deleting a Visual SCIL object means that it is removed from the screen (if shown)and from the dialog system. When an object is deleted, all its children are deleted aswell.

When an object is deleted, its Delete method, if any, is executed.

Examples:.DELETE DIALOG1;Deletes the object DIALOG 1 and all its child objects.

.DELETE ROOT;Deletes the entire dialog system.

.LOAD object = type( file , name {, attr = value, attr = value, ....})

Loads a Visual SCIL object.

’object’ The Visual SCIL object reference (name and possibly path) of theloaded object. This argument determines the name of the loadedobject and its situation in the object hierarchy. If the object refer-ence is given with an object path, the loaded object will be createdas the last child in the object chain. If no path is given, only objectname, the object will be the child object of the object containingthe .LOAD command. The object name can be freely chosen, onlyit is unique among all objects with the same parent. Up to 63 al-pha-numeric characters are allowed in the object name.



1MRS751250-MEN

ABB Automation116

’type’ The name of the Visual SCIL object type. The Visual SCIL objecttypes are listed and described in the manual Visual SCIL Objects.

’file’ Text. The name of the file where the object is stored, including thepath. Path is not needed if the file is situated in the directory de-fined as the default path of the main dialog of the dialog system.The default path is defined by the attribute DEFAULT_PATHwhen loading the main dialog.

’name’ Text. The name under which the dialog, dialog item or image isstored within the file. The name is given in the dialog editor.

’attr’ An attribute name.

’value’ A value assigned to the attribute.

This command is used for loading objects (dialogs, dialog item and images) built inthe dialog editor and stored in files. It loads the specified object as a Visual SCIL ob-ject with the given name. If a loaded dialog or dialog item contains other dialog items,they are also loaded. The contained dialog items will be known as Visual SCIL ob-jects with the names they were given in the dialog editor. The loaded object is incor-porated with all its child objects into the existing object hierarchy.

When loaded, the create methods of the objects are executed (see the Visual SCILUser Interface Design manual). If the load command contains attribute definitions, theattributes are set after the create methods.

A stored dialog, dialog item or image can be concurrently loaded several times in par-allel under different object names or in different contexts.

Example:.load DIALOG = VS_DIALOG(“MYFILE.VSO”,”MYDIALOG”,_OPEN = TRUE)

In the example above, the dialog stored as MYDIALOG in the file MYFILE is loadedas a Visual SCIL object of type VS_DIALOG. As the visibility attribute _OPEN is setto “TRUE”, the dialog is shown immediately. The command loads the complete con-tents of the dialog MYDIALOG.

7.4.2 Handling Visual SCIL Attributes

.MODIFY object = LIST(attribute = value, .... , attribute = value)

Modifies one or more attributes of a Visual SCIL object.

'object' A Visual SCIL object reference, possibly including an object path.

'attribute' Attribute name. If an attribute name does not exist as a predefinedattribute, it is created as a user defined attribute.

'value' Attribute value. For predefined attributes, the value should be ofan appropriate data type.



ABB Automation 117

Example:.create CANCEL = VS_BUTTON.modify CANCEL = list(_TITLE=“Cancel”, _NOTIFY=vector(“.delete DLG”))

.SET object.attribute = value

Assigns a value to a user interface attribute.

‘object’ A Visual SCIL object reference or a picture reference (see Chapter4).

'attribute' An attribute name.

'value' The value given to the attribute. If the attribute is predefined, thevalue must be of an allowed data type (see the attribute descrip-tions in the manual Visual SCIL Objects). If the attribute is userdefined, any data type is allowed.

The command assigns the given attribute the given value. If the object is shown whenthe .SET command is issued, the assignment may cause an immediate change of theappearance of the object.

When referencing Visual SCIL attributes, an error is produced in the event that theattribute does not exist. When referencing a window attribute, the attribute is definedif it does not exist.

User defined attributes will always have the data type of the value last assigned to theattribute.

Examples:

Moving a button:.SET BUTTON._GEOMETRY = (20,20,20,20)

Defining or modifying window attributes:.SET PIC_FUNC_1/WINDOW_2.RESIZED = TRUE.SET .COUNTER = 0

7.5 VS Object, Window and Picture Function Methods

object._FLAG_FOR_EXECUTION( name , program [, delay])

The predefined method _FLAG_FOR_EXECUTION indicates that the object, VSobject, window or picture function, should execute a SCIL program in the future.

'name' Text value used as the identifier of the flagged execution. Anempty name is allowed.

'program' Text or text vector, the program to be executed.

'delay' Real value indicating the minimum amount of seconds to elapsebefore the program is executed.



1MRS751250-MEN

ABB Automation118

Default is 0.

If _FLAG_FOR_EXECUTION method of an object is called twice using the same’name’, the first flagged execution is cancelled if not yet done.

object._QUEUE_FOR_EXECUTION(program [, delay])

This method is used when the programmer wants to execute a SCIL program at a laterpoint in time when the system is idle. The program to be executed is given as pa-rameter in the method call. There is no way to exactly know when in time the programis executed. A minimum time that has to expire can however be defined in seconds asan optional second parameter in the method call. The maximum number of queuedprograms per object is 100. If this limit is exceeded all queued executions are re-moved and a SCIL error is produced.

’program’ Text or text vector, the program to be executed.

’delay’ Real value indicating the minimum amount of seconds to elapsebefore the program is executed.

Return value: No return value.

Below is an example that shows how to ensure that the blocking cursor of a dialog isswithed off after a long program execution even if an error occurs that interrupts thenormal program flow....my_dialog._queue_for_execution(".set my_dialog._blocked = false").set my_dialog._blocked = true;long SCIL processing here...

7.6 VS Object, Window and Picture Function Attributes

Attributes of windows and picture functions contain properties of these. Many of theattributes of windows and picture functions are common with those of Visual SCILObjects(see Visual SCIL Objects manual).

_FILE_REVISION

Predefined read-only VS object and window attribute _FILE_REVISION contains theFILE_REVISION attribute of the picture file where the window was loaded from. Fora window created on-the-fly, the attribute is empty.

Value: Text (up to 255 characters).

Access: Read-only.

_ATTRIBUTE_NAMES

Value type: List.



ABB Automation 119

Value: Attribute USER_DEFINED: Text vector containing the names ofuser-defined attributes, i.e. the at-tributes created by .MODIFY com-mand (or by .SET command in apicture container context).

Attribute PREDEFINED: Text vector containing the names ofthe attributes defined by the objectclass.

_CHILD_OBJECTS

Value type: Text vector.

Value: The names of the immediate children of the object listed in the or-der of creation.

_OBJECT_CLASS

Value type: Text.

Value: The name of the class of the object.

If the object is a window or picture function, the attribute has value "WINDOW" or"PICTURE_FUNCTION", respectively.

_OBJECT_NAME

Value type: Text.

Value: The name of the object.

_SOURCE_FILE_NAME

Value type: Text.

Value: The full operating system format name of the ’vso’ file where theobject has been loaded from or the full name of the ’pic’ file wherethe window or picture function has been read from.

Value is an empty string, if the object is created on-the-fly, i.e.

The attributes are listed in no particular order.



1MRS751250-MEN

ABB Automation120

using .CREATE, !WIN_NAME or !WIN_CREATE command.

_VARIABLE_NAMES

Value type: Text vector.

Value: The names of SCIL variables defined in the SCIL context that theobject belongs to.

Note: The names are listed in no particular order.

_SG_GEOMETRY

This attribute is inapt for VS objects.

Value type: List.

Value: Attribute X: X position of window/pf relative partpicture / picture function.

Attribute Y: Y position of window/pf relative partpicture / picture function.

Attribute ABSOLUTE_X: X position of window/pf relativeROOT.

Attribute ABSOLUTE_Y: Y position of window/pf relativeROOT.

Attribute W: width of window/picture function insemigraphical characters.

Attribute H: height of window/picture function insemigraphical characters.

W and H are 0 if window is not shown.


MicroSCADA8 Functions

ABB Automation 121

8 Functions

This chapter describes the predefined SCIL functions. The chapter is organized intothe following sections:

8.1 General

8.2 Arithmetical Functions

8.3 Time Functions

8.4 String Functions

8.5 Bit Functions

8.6 Vector Handling Functions

8.7 Database and List Functions

8.8 Functions for Reading and Writing Files

8.9 Functions Related to Program Execution

8.10 Communication Functions

8.11 File and Directory Handling Functions

8.12 File and Directory Management Functions

8.13 DDE Client Functions

8.14 DDE Server Functions

8.15 ODBC Functions

8.16 RTU Functions

8.17 Printout Functions

8.18 Error Tracing Functions

8.19 Data Type Handling Functions

8.20 Miscellaneous Functions

Besides the SCIL functions described in this chapter, there are also some functions forhandling full graphic elements, which are described in Chapter 9.



1MRS751250-MEN

ABB Automation122

8.1 General

Function Calls

SCIL provides a number of standard functions, which return values according to apredetermined algorithm. When a function is called upon, its value is immediatelycalculated, and the result replaces the function call. Function calls are used as oper-ands in expressions (see example 8-1).

A function call has the following format:

function(argument(s))

The arguments are one or several arbitrary expressions, separated by commas. Theallowed data types of the arguments, as well as the data type of the result (value), arefixed by the actual function. The data type of the result determines how the functioncall is used in expressions (see Chapter 6).

In the function descriptions in this chapter, the data types of the arguments, as well asthe data type of the resulting value, are given for each function. Arguments in squarebrackets are not obligatory. If not otherwise stated, all arguments can be arbitrarySCIL expressions of the specified data types.

Examples

The following examples illustrates the use of functions:!SHOW TIME TIMES(OBJ:PRT);The latest registration time for the object is written out as a text in the;window called TIME.#IF ODD(%I) #THEN #SET S:PBO(%I) = 0;If the variable I is an odd number, the function ODD gets the value TRUE and;the #SET statement is executed.@SUM = PICK(A:D(1..1000),%I) + PICK(B:D(1..1000),%I);Corresponding indexes of the data objects A and B are summed. The indexes are;determined by the variable I.!SHOW PEAK HIGH(EFFECT:DOV(1..1000));The peak effect is shown in the window PEAK. As the function HIGH returns a;vector of one element, the window should be of type MULTIFIELD, BAR or CURVE.

Overview

The following table lists all SCIL functions and the tasks they perform along with thepage numbers where they are described.

Function Brief Description PageABS(arg) The absolute value of the argument. 128ADD_INTERLOCKED( object , index , amount ) Implicitly modifies the UV or SV attribute of a SYS or an

APL object.231

APPEND(v1, v2) The function appends data to a vector. 146APPLICATION_OBJECT_ATTRIBUTES(apl,type,objects,attributes)

Returns the values of specified attributes of selectedobjects.

168

APPLICATION_OBJECT_COUNT(apl, type [,order[,direction [, start [,condition]]]])

Counts the application objects of a specified type whichobeys a given criterion.

156

APPLICATION_OBJECT_LIST(apl,type[,order[,direction[,start[,condition[,attributes[,max]]]]])

Returns a list of application objects selected by type andother criteria.

165



ABB Automation 123

Function Brief Description PageARCSIN(arg)ARCCOS(arg)ARCTAN(arg)

Arcus sinus, arcus cosinus and arcus tangent. 128

ARGUMENT(n) Reads input arguments. 179ARGUMENT_COUNT Returns the total number of arguments in the argument

list of the program call.180

ARGUMENTS Returns all arguments in the argument list of the programcall as a vector.

180

ASCII(n) Returns the ASCII character corresponding to theargument.

135

ASCII_CODE(c) Returns the ASCII code of the argument. 135AUDIO_ALARM Sets and resets the specified audio alarm(s). 231BCD_TO_INTEGER(bcd) Converts BCD coded numbers to integer 136BIN(b) Converts bit strings, integers and vectors to texts and text

vectors.136

BIT(a,n) The bit value of a given bit number in a bit string orinteger.

143

BIT_AND(a1,a2)BIT_OR(a1,a2)BIT_XOR(a1,a2)

Combining bit representations with and, or and xor. 144

BIT_CLEAR(a,b1, ... ,bn) Sets given bits to zero. 144BIT_COMPL(a) Calculates a new integer or bit string by complementing

the bits of the argument.145

BIT_MASK(n1,....,n32) Creates an integer by setting given bit numbers to 1. 145BIT_SCAN(string) Converts character strings to bit strings. 137BIT_SET(a,b1, ..., bn) Modifies integers and bit strings by setting given bit num-

bers to 1.145

BIT_STRING(l[,b1, ... ,bn]) Creates a bit string by setting given bit numbers to 1 andthe other ones to 0.

146

CAPITALIZE(text)LOWER_CASE(text)UPPER_CASE(text)

Changes the case of a text. 137

CLASSIFY(vector,n,low,high) Classifies the elements of a vector into size classes andre-turns the counts of each class.

146

CLOCK(time) The present time. 131COLLECT ( v, delimiter ) Collects the elements of a vector to a text string where

the elements are surrounded by given delimitercharacters.

147

COMPILE(source) Runs the SCIL compiler. 180

CONSOLE_OUTPUT(text) Writes a message in the notify windows. 232CUMULATE(vector) The elements of the argument vector are accumulated to

the result vector.147

DATA_FETCH (appl,name,index1[,step[,count]])DATA_FETCH (appl,name,time1,time2[,step[,shift]])DATA_FETCH(appl,name,time1[,step[,count[,shift]]])DATA_FETCH (appl,name,indexes)

Reads the records of a data object and returns them as alist.

172

DATA_STORE (appl,name,data,index1[,step])DATA_STORE (appl,name,data,indexes)

Writes historical data into a data object and returns thestatus of the operation.

173

DATA_TYPE(expression) Returns the data type of the argument. 228DATE[(time)] The date (year, month and day). 131DAY[(time)] The date of the day specified by the argument. 132DDE_CONNECT(service, topic) Opens a connection to an external application. 208DDE_DISCONNECT(connection_id) Closes the connection specified by the argument. 209DDE_EXECUTE(connection_id, statement[,timeout])

Executes a statement in a remote application. 211



1MRS751250-MEN

ABB Automation124

Function Brief Description PageDDE_POKE(connection_id, item, value [,timeout]) Sets the value of ’item’ in a remote application. 210DDE_REAL(real , separator) Creates a text format real number with a user defined

decimal separator.213

DDE_REQUEST(connection_id, item [,timeout]) Requests data from a remote application. 209DDE_VECTOR(vector , decimal separator , listseparator)

Creates a text format vector with user defined list separa-tor.

212

DEC(value[,length[,decimals]]) Converts integer and real data to text. 137DEC_SCAN(string) HEX_SCAN(string)OCT_SCAN(string)

Converts character strings to decimal numbers. 139

DELETE_ELEMENT ( v, index [ , index2 ] ) Deletes individual elements in the vector ‘v’. 148DELETE_PARAMETER(file, section[, key]) Deletes a parameter in a paramter file. 179DIRECTORY_MANAGER("COPY", source, target ) Copies a directory and all its contents into a new

directory.188

DIRECTORY_MANAGER("COPY", source, target[,filter[, subdirectories[, overwrite]]])

Copies the files of a directory into another directory.Optionally, the subdirectories are recursively copied aswell.

188

DIRECTORY_MANAGER("CREATE", directory[,recursion])

Creates a directory or a hierarchy of directories. 188

DIRECTORY_MANAGER("DELETE", directory) Deletes one or more directories and all the directoriesand files contained in them.

188

DIRECTORY_MANAGER("DELETE_CONTENTS",directory[, filter[, subdirectories]])

Deletes files and directories contained in a givendirectory.

188

DIRECTORY_MANAGER("EXISTS", directory) Checks the existence of one or more directories. 188DIRECTORY_MANAGER("GET_ATTRIBUTES" ,directory)

Returns attribute information from one or moredirectories.

188

DIRECTORY_MANAGER("LIST", directory[, filter[,recursion]])

Lists the directories contained in a given directory. 188

DIRECTORY_MANAGER("MOVE", directory, target) Moves a directory to another directory. 188DIRECTORY_MANAGER("RENAME", directory,name

Renames a directory. 188

DO (program [, a1, .... , an]) Executes a SCIL program given as argument. 181DOW[(time)] Day of week. 132DOY[(time)] Day of year. The number of the day since the beginning

of the year.132

DRIVE_MANAGER("EXISTS", drive) Checks the existence of one or more drives. 193DRIVE_MANAGER("GET_ATTRIBUTES", tag) Returns some information from drives. 193DRIVE_MANAGER("GET_DEFAULT") Returns the default drive, i.e. the drive assumed if an

absolute path does not contain the drive.193

DRIVE_MANAGER("LIST") Returns the drives available in the system. 193DUMP( data ) Transforms the value of an expression into text format. 232EDIT(text,key) Rearranges text. 138ELEMENT_LENGTH(vl) The lengths of vector elements and list attributes 148END_QUERY Tells whether a process query initiated with

#INIT_QUERY is completed.169

ENVIRONMENT(variable) Retrieves the value of the specified variable from theenvironment block of the calling process.

232

EQUAL(v1, v2, [, status_handling]) Two scil values are compared for equality 129ERROR_STATE Returns the current ‘ERROR_STATE’. 181EVALUATE( expression ) Evaluates an expression given in text format. 232EXP(arg) The number e (neper's number) raised to the power of the

argument.178

FETCH(appl,type,name[,index]) Fetches the attribute of a selected object. 169FILE_LOCK_MANAGER(function, file) Locks and unlocks files. 193FILE_MANAGER("COPY", source, target[,overwrite])

Copies the contents of a file to another file. 194

FILE_MANAGER("DELETE" , file ) Deletes one or more files. 194



ABB Automation 125

Function Brief Description PageFILE_MANAGER("EXISTS" , file ) Checks the existence of one or more files. 194FILE_MANAGER("GET_ATTRIBUTES", file ) Returns attribute information from one or more files. 194FILE_MANAGER("LIST", directory[, filter[,recursion]])

Lists the files ( but not directories ) contained in a givendirectory.

194

FILE_MANAGER("MOVE", file, target) Moves a file to another directory. 194FILE_MANAGER("RENAME", file, name) Renames a file. 194FM_APPLICATION_DIRECTORY Creates the absolute directory tag of the home directory

of current application.197

FM_COMBINE(tag1[, tagi ]*, tagn ) Combines two or more drive, directory or file tags tocreate a new directory or file tag.

200

FM_COMBINE_NAME(’name’, ’extension’) Combines a proper file name and an extension to a filename.

201

FM_DIRECTORY(path[, check]) Creates a directory tag from one or more directory pathsor checks directory paths.

197

FM_DRIVE(name[, check]) Creates a drive tag from one or more drive names orchecks drive names.

197

FM_EXTRACT(tag, component) Extracts a component from one or more directory or filetags.

200

FM_FILE(path[, check]) Creates a file tag from one or more file paths or checksfile paths.

198

FM_REPRESENT(tag[, option]* ) Converts one or more drive, directory or file tags into anOS dependent text representation.

199

FM_SCIL_DIRECTORY(name[, check]) Creates a directory tag from one or more SCIL names orchecks SCIL names.

197

FM_SCIL_FILE(name[, option][, option]) Creates a file tag from one or more SCIL names orchecks SCIL names.

198

FM_SCIL_REPRESENT(tag[, case]) Converts one or more directory or file tags into a SCILname text representation.

199

FM_SPLIT_NAME(file) Extracts the proper name and the extension from one ormore file names.

201

GET_STATUS(expression) Returns the status code(s) of an expression. 233HEX(n) Converts integers to text and hexadecimal format. 138HIGH(vector)LOW(vector)

The largest (high) or the smallest (low) element in avector.

149

HIGH_INDEX(vector)LOW_INDEX(vector)

The index of the largest or smallest element in a vector. 149

HISTORY_DATABASE_MANAGER(command[,command_arguments])

Function for handling the history database 156 -164

HOD[(time)] Hours of day. Hours passed since the beginning of theday.

132

HOUR[(time)]MINUTE[(time)]SECOND[(time)]

Hour, minute and second respectively. 132

HOY[(time)] Hours of year. Hours passed since the beginning of theyear.

132

HR_CLOCK System time in seconds and milliseconds. 133INTEGER_TO_BCD(int [, digits ]) Converts an integer value to a BCD coded bit string. 139INTERP(vector,x) Interpolates a value from a curve. 149INVERSE(vector,n,low,high) Inverts a curve. 150KEYED_FILE_MANAGER( function, file {,output_file{, key_size}})

File maintenance function. 203

LENGTH(arg) Returns the "length" of the argument. 233LIST(attribute=expression, attribte=expression, ...) Forms a list of attributes and attribute values. 234LIST_ATTR(list) The function returns a vector of all attributes contained in

a list.234

LN(arg) The natural logarithm of the argument. 129LOAD_DCP(file,link,start) Loads and starts an internal DCP-net. 184



1MRS751250-MEN

ABB Automation126

Function Brief Description PageLOCATE(string1, string2 [, all])) Searches for a text string in a text or text vector and re-

turns the position of its first character.139

MEAN(vector) The mean value of all the elements in the argumentvector.

150

MEMORY_POOL_USAGE(pool) Monitor the usage of memory pools. 235MEMORY_USAGE Returns the amount of memory pool (as bytes) allocated

for the expression, or for the variable.235

MIN(arg1,...,arg32) MAX(arg1,...,arg32) Returns the smallest or the largest value in the argumentlist.

130

MONTH[(time)] The number of the month. 133NEXT(n) PREV(n) Next object and "previous object". 170OCT(n) Returns the octal ASCII representation of integers. 141ODD(arg) EVEN(arg) Tells if an expression is odd or even. 130OPS_CALL(command [,0]) The function executes an operating system command. 182OPS_PROCESS ( command [ , directory [ , wait ] ] ) Starts an external program as a separate process within

the operating system environment.182

PACK _TIME(year,month,day,hour,minute,second) Transforms calendar time to internal system time given astime data.

133

PACK_STR ( source , type [, length [, byte_order]] ) Converts text vector to text or integer vector to bit or bytestring.

228

PARSE_FILE_NAME ( name [ , file ] ) Converts logical paths names and file names to operatingsystem file names.

204

PATH( name ) The real directory paths of a logical path name. 205PATHS( level ) The logical paths defined on a specified level. 206PHYS_FETCH (appl,unit,address[,bitaddress]) The function forms a list with attributes taken from a

process object.170

PICK(vector,indexes) Picks specified elements from a vector and stores them inanother vector.

151

PRINT_TRANSPARENT( data [, log] ) Sends printout to a printer. 223PRINTER_SET Returns the target printer numbers. 226PROD_QUERY(n) Returns the attributes of the process objects selected with

#INIT_QUERY.171

RANDOM( n1 , n2 ) Generates a random number in a given range. 235READ_BYTES( file [ , start [ , length ] ] ) Reads data from a binary file. 174READ_COLUMNS( file, pos, width [ , start [ , count ]] )

Reads the columns of a text file. 175

READ_PARAMETER(file, section, key, alt) Reads a parameter in a parameter file. 178READ_TEXT(file[,start[,number]]) The function reads selected lines from an ASCII file and

stores them as a text vector.176

REMOVE_DUPLICATES(v [, status_handling]) Removes duplicate elements of a vector 151REP_LIB( name ) The real file names of a logical representation library

name.205

REP_LIBS( level ) The logical library names defined on a specified level. 206REPLACE(text, string, new_string) Replace textstrings with a new textstring 141REVERSE(vector) Assembles a new vector by reversing the order of the ele-

ments in the argument vector.151

REVISION_COMPATIBILITY( issue { , enable }) Selects the compatibility issues to be used in the context. 236RTU_ADDR(key) Returns a list with the address of the object in a certain

re-cord.219

RTU_AINT(i) Converts an integer to ascii characters (according to theRP570 protocol).

220

RTU_AREAL(r) Converts a real number to four ASCII-characters (floatDS801).

220

RTU_ATIME[(t,[msec])] Converts time data (operating system time) to ascii(RTU200 time).

221



ABB Automation 127

Function Brief Description PageRTU_BIN(h) Converts hex-ASCII numbers given as a text to binary

numbers in text form.221

RTU_HEXASC(b) Converts binary numbers given as a text to hex-ASCIInumbers as a text.

221

RTU_INT(a) Converts two ascii characters (2’s Complement RP570) toan integer.

221

RTU_KEY(oa) Returns the search key for a record in an RTU200configura-tion file.

222

RTU_MSEC(atime) Returns the milliseconds of the 6-byte rtu time stringatime.

222

RTU_OA(type,ba) Returns the object address. 222RTU_REAL(a) Converts 4 ascii characters (float DS801) to a real

number.222

RTU_TIME(a) Converts ascii (RTU200 time) to microscada time data. 223SCALE(v, scale_object [, direction ]) Scaling of a real value with a scala object 237SCIL_HOST Returns the name and number of the kernel process that

executes the current scil code.237

SELECT(source,condition,[wildcards]) The function selects the elements of a vector or a list thatfulfill a given criterion.

152

SEPARATE( text , delimiter ) Converts text to vector. 141SET_CLOCK(time) Sets the system time. 133SET_STATUS(source,status) Writes the status codes of an expression. 238SHADOW_FILE( file_name ) Enable shadowing of files not created by microscada. 206SHUFFLE( n ) Arranges specified integer numbers in a random order

and returns them as a vector.236

SIN(arg)COS(arg)

The sine and cosine of the argument. 130

SORT(data,[start,[length]]) Sorts a vector in ascending order or alphabetical order. 153SPACOM(message) Communicates with a spacom unit connected to a com

port.185

SPREAD(vector,indexes,value) The function replaces certain vector elements with othervalues.

153

SQL_BEGIN_TRANSACTION(connection_id) Marks the beginning of a transaction. 217SQL_COMMIT(connection_id) Commits a transaction the start of which was marked with

SQL_BEGIN_TRANS.218

SQL_CONNECT(source, user, password ) Opens an odbc connection to a data source. 214SQL_DISCONNECT(connection_id) Closes the ODBC connection defined by the argument. 215SQL_EXECUTE(connection_id, SQLstring) Executes an SQL statement. 215SQL_FETCH(statement_id) Fetches a row of data from a result set obtained by

SQL_EXECUTE.216

SQL_FREE_STATEMENT(statement_id) Frees the specified statement and stops processingassociated with the statement.

217

SQL_ROLLBACK(connection_id) Rolls back a transaction started withSQL_BEGIN_TRANS.

219

SQRT(arg) The square root of the argument. 131STATUS The status produced by the latest error situation in the

program that is being executed.183

SUBSTR(string,start,length) Extracts a substring from a text or bit string. 142SUM(vector) The sum of all the elements in a vector. 154SUM_POS(vector)SUM_NEG(vector)

The sum of the positive or negative elements in a vector. 154

TIMEOUT(integer) Changes communication time-out. 185TIMES[(time)] TIME[(time)] Date and time, with and without seconds. 134TODS[(time)]TOD[(time)]

Time of day. 134

TRACE_BEGIN( filename [, append ] [,time_tags]) Starts trace logging. 227



1MRS751250-MEN

ABB Automation128

Function Brief Description PageTRACE_END Stops trace logging. 227TRACE_PAUSE Pauses trace logging 227TRACE_RESUME Resumes trace logging 227TRANSLATE(text [,language]) Translates texts defined in visual scil objects. 239TREND(vector,n) Assembles a new vector from the last (highest indexed)

elements in a vector.155

TRUNC(arg)ROUND(arg)

Transform the arguments from real into integer. 131

TYPE_CAST ( source, type ) Converts data from one data type to another. 230UNPACK_STR ( source [, length [, byte_order]]) Converts texts, bit strings and byte strings to vectors of in-

teger or text elements.229

VECTOR[([element1, ....., elementn])] Creates a vector with given elements. 155WEEK[(time)] The number of the week within a year. 134WORKSTATION_CALL(command[, other, ...]) Function for communicating with workstation. 183WRITE_BYTES(file, data[, append] ) Writes data in a binary file. 175WRITE_COLUMNS ( file, pos , width , data [ ,append ] )

Writes text in columns in a text file. 176

WRITE_PARAMETER(file, section, key, value) Writes a parameter in a parameter file. 178WRITE_TEXT(file,text[,cont]) The function writes the contents of a text vector into an

ASCII-file.177

YEAR[(time)] The year in complete format (for example 1993). 134

8.2 Arithmetical Functions

ABS(arg)

The absolute value of the argument.

’arg’ An integer or real expression, or a vector with integer or real val-ues.

Value: The same data type as the argument (’arg’).

Example:ABS(-3) ;returns the value 3.

ARCSIN(arg)ARCCOS(arg)ARCTAN(arg)

Arcus sinus, arcus cosinus and arcus tangent.

These functions return the angles in radians, whose sine, cosine or tangent are the ar-guments.

’arg’ An integer, real or vector expression. The elements of a vectormust be integer or real expressions.

Value: A real number or a vector with real elements. The angles in radi-ans.



ABB Automation 129

EQUAL(v1, v2, [, status_handling])

Two SCIL values are compared for equality.

’v1’ First value of any type.

’v2’ Second value of any type.

’status_handling’ Text value, either "CONSIDER_STATUS" or"IGNORE_STATUS"), default = "IGNORE_STATUS"

Value: Boolean value TRUE if ’v1’ is equal to ’v2’, otherwise FALSE.

Two values are considered equal if :

• The value types are the same and

• The values are the same and

• The status values are the same (when "consider_status") or else both valid (< 10)(when "ignore_status")

The test for equality is recursive, i.e. if the value is a vector or list, its components aretested for equality.

Example:@b_istrue_1=EQUAL(1,1);returns TRUE@b_istrue_2=EQUAL(1,10);returns FALSE@i_A=TRUNC(RANDOM(1,10))@i_B=TRUNC(RANDOM(1,10))@b_istrue_3=EQUAL(%i_A,%i_B);returns TRUE or FALSE

EXP(arg)

The number e (Neper’s number) raised to the power of the argument.

’arg’ An integer or real expression, max. +88.0, or a vector of integerand real expressions max. +88.0.

Value: A real number or a vector with real elements.

LN(arg)

The natural logarithm of the argument.

’arg’ An integer or real expression > 0, or a vector, the elements ofwhich are integer or real expressions > 0.

Value: A real number or a vector with real elements.



1MRS751250-MEN

ABB Automation130

MIN(arg1,...,arg32)MAX(arg1,...,arg32)

Returns the smallest or the largest value in the argument list.

'arg1' ... 'arg32’ 1 ... 32 integer and real values and vectors with integer or realelements. The number of arguments may be up to 32.

Value: An integer, a real number or a vector. If all arguments or all com-pared elements are integers, the result is an integer or an integerelement, otherwise a real/real element.

If the argument list contains both numbers and vectors, the numbers are comparedwith each one of the vector elements and corresponding vector elements are com-pared. If the number of vector elements is unequal, odd elements getSUSPICIOUS_STATUS (see the Status Codes manual).

Example:@X = (MIN(4,83,-1.8,-3) ;returns -3.0@A = (2,4)@B = (5,6,1)@C = MIN(3,%A,%B);Vector C gets value (2,3,1);The last element has SUSPICIOUS_STATUS.

ODD(arg)EVEN(arg)

Tells if an expression is odd or even.

These functions return the boolean value TRUE if the argument is odd (ODD) or even(EVEN) respectively.

'arg' An integer or an integer vector.

Value: A boolean value or a vector, the elements of which are boolean.

Examples:@A = ODD(5) ;returns TRUE@A = EVEN(5) ;returns FALSE

SIN(arg )COS(arg)

The sine and cosine of the argument.

'arg' One or several angles given in radians as an integer or real numberor as a vector with integer or real values.

Value: A real value, or a vector with real elements.



ABB Automation 131

SQRT(arg)

The square root of the argument.

’arg’ An integer or a real value > = 0, or a vector, the elements of whichare integer or real > = 0.

Value: A real value > = 0 or a vector, the elements of which are real > =0.

TRUNC(arg)ROUND(arg)

Transform the arguments from real into integer.

TRUNC truncates all the decimals, no matter what value they have. ROUND roundsoff to the nearest integer number.

‘arg' A real number or a vector with real elements.

Value: An integer or a vector with integer elements.

Examples:@X = TRUNC(4.8) ;returns 4@X = ROUND(4.8) ;returns 5

8.3 Time Functions

The time functions are used for reading time information in various forms, setting thesystem time, and converting time information from one form to another. All timefunctions, except PACK_TIME and SET_CLOCK, require arguments of type time,integer (positive) or vector. In vector type arguments, all elements must be time dataor positive integers. Integer arguments are regarded as time data given as the numberof seconds (see Chapter 3). The time functions may also be used without any argu-ment. In such cases, the argument is assumed to be the present time.

At the end of this section you find examples of the time functions.

CLOCK[(time)]

Returns its argument as such.

Always used without an argument to obtain current time.

Value: Time data.

DATE [(time)]

The date (year, month and day).



1MRS751250-MEN

ABB Automation132

The date is given in the format yy-mm-dd or dd-mm-yy depending on the value of theattribute SYS:BTF.

Value: A text or text vector.

DAY[(time)]

The date of the day specified by the argument.

Value: An integer or integer vector.

DOW[(time)]

"Day of Week".

The number of the day counting from Monday which is number one.


DOY [(time)]

"Day of Year". The number of the day since the beginning of the year.


HOUR[(time)]MINUTE[(time)]SECOND[(time)]

Hour, minute and second respectively.


HOD[(time)]

"Hours of Day". Hours passed since the beginning of the day.

Value: A real or real vector.

HOY[(time) ]

"Hours of Year". Hours passed since the beginning of the year.

Value: A real or real vector.



ABB Automation 133

HR_CLOCK

System time in seconds and milliseconds.

Value: A list containing the following two attributes:

CL = the system time as time data (= CLOCK)

US = the microseconds of the system time as an integer (with anaccuracy depending on the operating system, often 10 millisec-onds).

Example:@TIME = HR_CLOCK!SHOW TIMES TIMES(TIME:VCL)!SHOW MILLI TIME:VUS/1000

MONTH[(time)]

The number of the month.


PACK_TIME(year,month,day,hour,minute,second)

Transforms calendar time to internal system time given as time data.

’year’ Integer, 1978 ... 2045

’month’ Integer, 1 ... 12

’day’ Integer, 1 ... 31

’hour’ Integer, 0 ... 23

’minute’ Integer, 0 ... 59

’second’ Integer, 0 ... 59

If any of the arguments are outside the given intervals, the time is assumed to be Jan1st 1978, 00:00 o’clock.

Value: Time data.

SET_CLOCK(time)

Sets the system time.

’time’ Time data or a list with the following two attributes:

CL = system time on second level.



1MRS751250-MEN

ABB Automation134

US = the microseconds of the system time.

Value: A real value. The number of seconds that the system clock timewas changed. A positive value means that the clock was set for-ward. A negative value indicates that it was set backward.

Example:@T = SET_CLOCK(LIST(CL = CLOCK, US = 500000))

TIMES[(time)]TIME[(time)]

Date and time, with and without seconds.

The date and time is given in the form yy-mm-dd hh:mm:ss or dd-mm-yy hh:mm:ssdepending on the value of the attribute SYS:BTF.


TODS[(time)]TOD[(time)]

"Time of Day".

The TODS function returns the time in the format hh:mm:ss. The TOD function re-turns the same as TODS, but without seconds.


WEEK[(time)]

The number of the week within a year.


YEAR[(time)]

The year in complete format (for example 1993).




ABB Automation 135

Examples:

On 19 February ’97 at 20:35:04 o’clock the time functions returned the followingvalues (supposing SYS:BTF == 0):

Function call ValueTIMES "97-02-19 20:35:04"TIMES(CLOCK-1) "97-02-19 20:35:03"TIMES(OBJ:PRT) "97-01-28 15:43:26" (the latest registration

time for the object)TIME "97-02-19 20:35"TODS "20:35:04"DATE "97-02-19"YEAR 1997MONTH 2HOUR 20MINUTE 35SECOND 4DOY 50HOD 20.58444TIMES(PACK_TIME(1993,5,5,12,30,0)) 97-05-05 12:30:00!SHOW TIME TIMES(LISTA:VRT) All the registration times of the variable object

are shown as a column in the window TIME.

8.4 String Functions

The string functions perform operations on texts, bit strings and byte strings, for ex-ample transformations of numbers into character strings or vice versa.

ASCII(n)

Returns the ASCII character corresponding to the argument.

’n’ An integer in range 0 ... 255, or a vector, all elements of which areintegers within the given range.

Value: An ASCII character or a vector with ASCII characters.

Examples:@A = ASCII(65);returns "A"@A = ASCII(13);returns ‘carriage return’

ASCII_CODE(c)

Returns the ASCII code of the argument.

’c’ An ASCII character or a vector with ASCII characters.



1MRS751250-MEN

ABB Automation136

Value: An integer in range 0 ... 255 or a vector with integers within thisrange.

Example:

ASCII_CODE("A") == 65

BCD_TO_INTEGER(bcd)

Conversion of bcd coded number to integer. (Binary Coded Decimal)

BCD values are represented in SCIL by values of BIT_STRING data type. Each digittakes 4 bits so the length of a BCD bit string is a multiple of 4. The length of a BCDvalue is limited to 9 digits.

’bcd’ Bit string value containing the BCD coded number.

Value: List value with attributes

STATUS Integer status code of the conversion

INT Integer value, the result of conversion

If the bit string represents a valid BCD number, the STATUS attribute is set toOK_STATUS ( 0 ) and the result of the conversion is returned in attribute INT.

If the bit string is invalid, i.e. it contains nibbles out of range 0 .. 9, its length is not amultiple of 4 or its length is greater than 36, STATUS is set toSCIL_NOT_A_BCD_NUMBER and INT attribute is not returned.

Example:@bcd_string_of_number=INTEGER_TO_BCD(98) ;returns list with BCD representation of the integer ;as the value of the attribute named BCD@l_of_number=BCD_TO_INTEGER(bcd_string_of_number:vBCD) ;returns list with attribute INT containing the ;integer, 98@i_number=l_of_number:vINT ;assign the value of the INT attribute to ;the variable ’i_number’

BIN(b)

Converts bit strings, integers and vectors to texts and text vectors.

If the argument is a bit string, the function returns its first 255 bits as a text. If the ar-gument is an integer, the function returns its bit representation as a text. If the argu-ment is a vector if bit strings and integers, the vector elements are converted to textscorrespondingly.

‘b' A bit string or integer, or a vector of bit strings and integers .

Value: A text or text vector. Each text element converted from an integerwill contain 32 characters. A text element converted from a bit



ABB Automation 137

string will contain the same number of characters as the bit string,however, at most 255 characters.

Example:@A = BIT_SCAN ("010101")@B = BIN (%A);returns "010101"@C = BIN (23);returns "0000...0010111" (initially 27 zeroes)

BIT_SCAN(string)

Converts character strings to bit strings.

’string’ A text or text vector. The text must be composed of the digits 0and 1.

Value: A bit string or a vector of bit strings.

Example:

BIT_SCAN ("010101") = a bit string with the contents 010101 (not visible)

CAPITALIZE(text)LOWER_CASE(text)UPPER_CASE(text)

Changes the case of a text.

LOWER_CASE converts the text to lower case letters. UPPER_CASE converts thetext to uppercase letters. CAPITALIZE converts the first character of the text or eachtext vector element to an uppercase letter, the rest of the text to lower case letters.

’text’ A text or text vector.


DEC(value[,length[,decimals]])

Converts integer and real data to text.

The function converts an integer or a real value or a vector of integer and real values(’value’) to a text or text vector respectively.

’value’ An integer or real expression, or a vector of integer and real ex-pressions.

’length’ An integer expression. The minimum length of the produced text.Default = 6.



1MRS751250-MEN

ABB Automation138

’decimals’ An integer expression. The number of decimals included in theconversion of real or integer data to text. Default = 0.

Value: A text of ’length’ characters or more, or a text vector, the elementsof which contain ’length’ characters or more. If the number isshorter than ’length’, the string is filled up by initial blanks.

Examples:@A = DEC (1000);returns "1000"@A = DEC (-1);returns "-1"@A = DEC(1.3,6,3);returns "1.300"

EDIT(text,key)

Rearranges text.

The function rearranges a text (’text’) by removing spaces and tabs according to aspecified rule (’key’).

’text’ A text or text vector expression.

’key’ A text. One of the following key words:

"TRIM" = Removes leading and trailing spaces and tabs.

"LEFT_TRIM" = Removes leading spaces and tabs.

"RIGHT_TRIM" = Removes trailing spaces and tabs.

"COLLAPSE" = Removes all spaces and tabs.

"COMPRESS" = Replaces multiple spaces or tabs with singlespaces.


HEX(n)

Converts integers to text of hexadecimal format.

The function converts an integer or integer vector (‘n’) to its hexadecimal ASCII rep-resentation.

'n' An integer or integer vector.

Value: A text of 4 or 8 characters or a text vector, the elements of whichcontain 4 or 8 characters. If the number is shorter than 4 charac-ters, or longer than 4 but shorter than 8, the string is filled up byinitial zeroes.



ABB Automation 139

Example:@A=HEX(26);returns "001A"@A=HEX(-1);returns "FFFF"@A=HEX(123456);returns “0001E240”

BIN_SCAN(string)DEC_SCAN(string)HEX_SCAN(string)OCT_SCAN(string)

Converts character strings to decimal numbers.

BIN_SCAN converts character strings of binary numbers, DEC_SCAN decimal num-bers, OCT_SCAN octal numbers, and HEX_SCAN hexadecimal numbers to the cor-responding integers.

’string’ A text of digits or a text vector of digits. Leading blanks, a signand a decimal point are allowed, all other non-digit characters pro-duce an error.

Value: An integer or a real number, or a vector with integer or real ele-ments. If the argument lacks a decimal point, the result is an inte-ger. If there is a decimal point, the result is a real number. If an ar-gument without decimal point falls outside the integer value range(see Chapter 3), DEC_SCAN returns a real value, whileOCT_SCAN and HEX_SCAN cuts off the value to an integer.

Examples:@A = BIN_SCAN("10011");returns 19@A = BIN_SCAN("10.1");returns 2.5@A = DEC_SCAN(" -5");returns -5@A = DEC_SCAN("40000");returns 40000@A = OCT_SCAN("10");returns 8@A = OCT_SCAN("1.2");returns 1.25@A = HEX_SCAN("F");returns 15@A = HEX_SCAN("A.8");returns 10.5

INTEGER_TO_BCD(int [, digits ])

Converts an integer value to a BCD coded bit string. (Binary Coded Decimal)

BCD values are represented in SCIL by values of BIT_STRING data type. Each digittakes 4 bits so the length of a BCD bit string is a multiple of 4. The length of a BCDvalue is limited to 9 digits."

’int’ Integer value containing the integer to be converted.



1MRS751250-MEN

ABB Automation140

’digits’ Integer value 0 to 9, number of BCD digits in the result. Default is0.

Value: List value with attributesSTATUS Integer status code of the conversionBCD Bit string value, the BCD coded representation of ’int’

If ’digits’ is 0, a bit string long enough to hold the result is returned. Otherwise exactly’digits’ BCD digits are returned, padded with leading zeroes, if necessary.

If the value of ’int’ can be represented as a BCD bit string ( i.e. it is non-negative andin the range specified by ’digits’ ), the STATUS attribute is set to OK_STATUS ( 0 )and the result of the conversion is returned in attribute BCD.

If the argument is invalid, STATUS is set to SCIL_ARGUMENT_OUT_OF_RANGEand BCD attribute is not returned.

Example:@i_A=9876@l_bcd=INTEGER_TO_BCD(%i_A,9) ;converts the value of the variable ’i_A’ ;returns a list with attributes ’BCD’ and ’STATUS’@t_bcd=bin(l_bcd:vbcd) ;returns the BCD code converted to textformat@t_status=dec(l_bcd:vSTATUS) ;returns the status converted to textformat@l_converted=BCD_TO_INTEGER(l_bcd:vbcd) ;returns a list with attributes ’INT’ and ’STATUS’@i_converted=l_converted:vINT ;returns an integer as value of the attribute ’INT’ ;from the list named ’l_converted’@t_converted_status=dec(l_converted:vSTATUS) ;returns the status converted to textformat ;from the list named ’l_converted’

LOCATE(string1, string2 [, all])

Searches for a text string in a text or text vector and returns the position of its firstcharacter.

’string1’ A text or text vector. The text to be searched through.

’string2’ A text. The text string to be located.

‘all’ A text expression, “ALL”. If given, LOCATE searches for all oc-currences of ‘string2’ in ‘string1’.

Value: An integer (>=0), a vector containing integer elements (>= 0) oranother vectors, which contains integer elements. It represets thestart position of 'string2' in 'string1'.

Without [, all] The result represents the start position of thefirst found string2 in string1. If ‘string 2’ oc-curs several times in the text, the result givesonly the position of the first occurrence. Theresult is a integer if ‘string1’ is a text value. If‘string1’ is a vector, the result is a vector of



ABB Automation 141

same length as string1 containing integer val-ues. Zero means that the string was not found.

With [, all] The result represents the start position of allfound string2 in string1. If ‘string 2’ occursseveral times in the text, the result gives the po-sition of all occurrences. The result is a vectorwith integer values if ‘string1’ is a text value. If‘string1’ is a vector, the result is a vector of thesame length as ‘string1’ containing vectors withinteger values. Zero means that the string wasnot found.

Example:@A = LOCATE ("ABC","BC");returns 2@A = LOCATE ("ABC","BC ");returns 0@A = LOCATE (“ABB”,”B”,“ALL”);returns vector(2,3)@A = LOCATE (("FGHBBN","ABBBB"),"BB","ALL");returns (vector(4), vector(2,4))@A = LOCATE (("HBBN","ABBBB","BB","AA"),"BB","ALL");returns (vector(2), vector(2, 4), vector(1), vector(0))

OCT(n)

Returns the octal ASCII representation of integers.

‘n’ An integer or an integer vector.

Value: A text of 6 or 11 characters or a text vector, the elements of whichcontain 6 or 11 characters. The argument ‘n’ in octal format. If theoctal number is shorter than 6 characters, or longer than 6 butshorter than 11, the string is filled up by initial zeroes.

Examples:@A = OCT(10);returns "000012"@A = OCT(-1);returns "177777"

REPLACE(text, string, new_string)

Replace text strings by another text string in a text or textvector.

'text' Text or text vector containing the input text.

'string' Text value, the string to be replaced.

'new_string' Text value, the replacing string.

Value: Text or text vector containing the text in 'text' with all occurrencesof 'string' replaced by 'new_string'.



1MRS751250-MEN

ABB Automation142

If the string resulting string is too long ( > 255 characters ),SCIL_STRING_TOO_LONG error is generated when the ’text’ argument is of texttype. If it is a vector, the status of the overflowing element is set toSCIL_STRING_TOO_LONG.

SEPARATE ( text , delimiter )

Converts text to vector.

The function converts the first argument (‘text’) to a vector by taking text stringsseparated by a specified delimiter (‘delimiter’) as elements.

‘text' Any text expression. The original text string.

'delimiter' A text expression of one character. The delimiter.

Value: A text vector containing the fields of 'text' that are delimited bythe delimiter character. The delimiter character itself is not in-cluded. If there is no delimiter character found in the text, the en-tire text is returned as the only element of the resulting vector. Anempty field is returned in case of two consecutive delimiters.

Example:@A = SEPARATE(“A,B,C,D”, “,”);returns the vector (“A”,”B”,”C”,”D”).

SUBSTR(string,start,length)

Extracts a sub-string from a text or bit string.

’string’ A text, a bit string or a byte string, or a vector of texts, bit stringsand byte strings. The text, bit string or vector from which a sub-string is extracted.

’start’ An integer 1 ... 255 (texts) or 1 ... 65535 (bit strings) or 1 ...1048576 (byte strings). The starting position of the sub-string.

’length’ An integer 0 ... 255 (texts) or 0 ... 65535 (bit strings) or 1 ...1048576 (byte strings). The length of the sub string. If ’length’ = 0,the function returns the end of ’string’ starting from ’start’. If thesub-string extends ’string’, i.e. if ’length’ > the number of charactersin ’string’, the result is padded with blanks (texts) or bit zeroes (bitstrings) or zero bytes (byte strings).

The arguments ’string’ and ’new_string’ may be of different length.Argument ’new_string’ may be empty. In this case, all the occurrences of ’string’ aredeleted.



ABB Automation 143

Value: The same data type as ’string’. The substring.

Examples:@A = SUBSTR("ABCDE",3,2);returns "CD"@A = SUBSTR("ABCDE",4,3);returns "DE "@A = SUBSTR("ABCDE",6,3);returns " "

@V = BIT_SCAN("1010101")@B = BIN(SUBSTR(%V,2,3));returns "010"

@A = SUBSTR(%BYTES, 1, 100000);returns a byte string containing the first 100000 bytes of byte string %BYTES.

8.5 Bit Functions

The bit functions manipulate numbers, characters and bit strings on bit level.

One "word" consists of 32 bits. The bits are numbered 0 ... 31 from right to left, i.e., 0= Least Significant Bit (LSB) and 31 = Most Significant Bit (MSB). A bit string canbe composed of up to 65535 bits numbered 1 ... 65535 from left to right (see Chapter3).

See also the SUBSTR function in section 8.4. This function extracts a small bit stringfrom a larger one.

BIT(a,n)

The bit value of a given bit number in a bit string or integer.

The function returns the bit value of bit number 'n' in ‘a’. If ‘a’ is an integer, it returnsbit number ‘n’ in the bit representation of the integer.

'a' An integer or a bit string, or a vector of integers and bit strings.

'n' The bit number. An integer in the range 0 ... 31 or 1 ... 65535 de-pending on the data type (integer or bit string) of 'a' or its elements,see the general part of this section. 'n' must not exceed the numberof bits in 'a' or its elements.

Value: An integer, 0 or 1, or a vector with elements which are 0 or 1.

Examples:@A = BIT(3,0);returns 1@A = BIT(-1,15);returns 1@A = BIT(BIT_SCAN("010101"),5);returns 0



1MRS751250-MEN

ABB Automation144

BIT_AND(a1,a2)BIT_OR(a1,a2)BIT_XOR(a1,a2)

Combining bit representations with AND, OR and XOR.

The function returns an integer or a bit string calculated by AND-ing, OR-ing orXOR-ing bit-wise the corresponding bits in two bit string arguments or in the bit rep-resentations of two integer arguments.

’a1’ An integer or a bit string, or a vector of integers and bit strings.

’a2’ The same data type as ’a1’.

Value: An integer or a bit string, or a vector of integers and bit strings.

If one of the arguments is a vector and one a simple data, the operation is performedbetween the simple data and each vector element. If both arguments are vectors, theoperation is performed between corresponding elements. If the number of vector ele-ments is unequal, odd elements are given SUSPICIOUS_STATUS (see the StatusCodes manual).

Examples:@A = BIT_AND(6,5);returns 4@A = BIT_AND(BIT_MASK(0,2,4,6,12),BIT_MASK(1,2,4,7,13));returns 20 (the bits 2 and 4)@A = BIT_OR(6,5);returns 7@A = BIT_XOR(6,5);returns 3

BIT_CLEAR(a,b1, ... ,bn)

Sets given bits to zero.

The function returns the value yielded when the bit numbers ’b1’ ... ’bn’ in a bit stringor in the bit representation of an integer (’a’) are set to zero.

’a’ An integer or a bit string, or a vector of integers and bit strings.

’b1’ ... ’bn’ The bit numbers to be set to 0. Up to 31 integers in the range 0 ...31 or 1 ... 65535 depending on the data type (integer or bit string)of ’a’ or its elements, see the general part of this section. The bitnumbers must not exceed the number of bits in ’a’ or its elements.

Value: The same data type as the argument ’a’.

Examples:@A = BIT_CLEAR(3,0);returns 2@A = BIT_CLEAR(2,0);returns 2@A = BIT_CLEAR(-1,15);returns - 32769@A = BIT_CLEAR(BIT_SCAN("01111"),2,4,5) = = BIT_SCAN("00100");returns true



ABB Automation 145

BIT_COMPL(a)

Calculates a new integer or bit string by complementing the bits of the argument.

The function returns an integer, bit string, or vector calculated by complementing thebits in a bit string argument or the bits in the bit representation of an integer argument.

‘a' An integer or bit string, or a vector of integers and bit strings.

Value: The same data type as the argument 'a'.

Examples:@A = BIT_COMPL(0);returns -1@A= HEX(BIT_COMPL(HEX_SCAN("207F")));returns "DF80"@A= BIT_COMPL(BIT_SCAN("0101"));returns bitstring “1010”

BIT_MASK(n1,....,n32)

Creates an integer by setting given bit numbers to 1.

The function returns the integer number yielded when the bit numbers given in the ar-gument list are set to 1 and all the others are set to zero.

’n1’ ... ’n32’ Bit numbers. 1...32 integer values in the range 0..31.

Value: An integer.

Examples:@A=BIT_MASK(0);returns 1@A=BIT_MASK(4,0);returns 17@A=BIT_MASK(4,0,15);returns 32785@A=HEX(BIT_MASK(0));returns "0001"

BIT_SET(a,b1, ..., bn)

Modifies integers and bit strings by setting given bit numbers to 1.

The function returns the value yielded when the bit numbers ’bn’ in the bit representa-tion of ’a’ are set to one.

’a’ An integer, a bit string or a vector of integers and bit strings.

’b1’ ... ’bn’ The bit numbers to be set to 1. Up to 31 integers in the range 0 ...31 or 1 ... 65535 depending on the data type (integer or bit string)of ’a’ or its elements, see the general part of this section. The bitnumbers must not exceed the number of bits in ’a’ or its elements.

Value: The same data type as ’a’.



1MRS751250-MEN

ABB Automation146

Examples:@A=BIT_SET(0,3);returns 8@A=BIT_SET(-1,15);returns -1@A=BIT_SET(6,0);returns 7@A=BIT_SET(BIT_SCAN("0101"),1,3);returns bitstring “1111”@A=BIT_SCAN("1111");returns bitstring “1111”

BIT_STRING(l[,b1, ... ,bn])

Creates a bit string by setting given bit numbers to 1 and the other ones to 0.

’l’ An integer, 1 ... 65535. The number of bits in the bit string.

’bn’ An integer, 1 ... ’l’. The bit numbers (’n’ = 0 ...31) which are to beset to 1. All other bits are set to 0.

Value: Bit string.

Example:

BIT_STRING(5,1,3,5) == BIT_SCAN("10101")

8.6 Vector Handling Functions

The vector functions perform various manipulations on vector data.

APPEND(v1,v2)

The function appends data to a vector.

’v1’ A vector. The vector to which data is appended.

’v2’ Any SCIL data type. The data which is appended to ’v1’.

Value: A vector. The result vector is ’v1’ and ’v2’ merged.

Example:@V1 = (1,2,3)@V2 = (4,5)@V = APPEND(%V1,%V2);returns (1,2,3,4,5)@X = APPEND(%V1,6);returns (1,2,3,6)

CLASSIFY(vector,n,low,high)

Classifies the elements of a vector into size classes and returns the counts of eachclass.

’vector’ A vector with real elements. The vector to be classified.



ABB Automation 147

’n’ An integer in the range 1..10000. The number of classes.

'low', 'high’ Integer or real numbers (high > low).

The range 'low' ... 'high' is divided into 'n' equal classes. The length of each class isthus: ('high' - 'low')/'n'. The value of the function is a vector, the elements of whichstate the number of elements in each of these classes from the first one to the last one.If an element in 'vector' is smaller than or equal to 'low', it is counted to the lowestclass. Elements larger than or equal to 'high' are counted to the highest class. Elementson the class limits are classified to the upper class.

Value: A vector of length 'n' with real elements. The number of elementsin each class.

Examples:@A(1) = 1.@A(2) = 5.0@A(3) = 3.0;The variable B is assigned values as follows:@B = CLASSIFY(%A,2,0.0,10.0)

;B(1) = = 2.0 (the range 0.0 ... 5.0);B(2) = = 1.0 (the range 5.0 ... 10.0)

COLLECT ( v, delimiter )

Collects the elements of a vector to a text string where the elements are surrounded bygiven delimiter characters.

‘v’ Any text vector expression.

‘delimiter’ One character given as an expression. The delimiter which willsurround the vector elements in the text.

Value: A text where the elements of are concatenated with the delimitercharacter into one string.

CUMULATE(vector)

The elements of the argument vector are accumulated to the result vector.

Each element number n of the result vector is set to the sum of the n first elements ofthe argument vector.

'vector' A vector with integer, real or time elements.

Value: A vector of the same length as the argument vector. The elementsof the vector are of real type.

Example:@V = (1,-5.6,3.3,37)CUMULATE(%V);returns (1.0,-4.6,-1.3,35.7)



1MRS751250-MEN

ABB Automation148

ELEMENT_LENGTH( vl )

The lengths of vector elements and list attributes.

’vl’ Vector or list value.

Value: Vector or list containing the lengths of elements or attributes of’vl’.

If the argument ’vl’ is a vector, the value of the function call is an integer vector of thesame length, the n:th element of the resulting value containing the length of n:th ele-ment of ’vl’.

If the argument ’vl’ is a list, the value of the function call is a list having the same at-tributes as ’vl’, each containing the length of the corresponding attribute of ’vl’.

Example 1:@v_txtvector=READ_TEXT("c:\sc\stool\misc\languages.txt") ;returns a vector which elements are rows ;from the text file@v_txtvector_len=ELEMENT_LENGTH(%v_txtvector) ;returns a vector which elements are integers giving ;the length of corresponding element of the textvector

Example 2:#CREATE P_OBJ_LIST:V=LIST(AL=APPLICATION_OBJECT_LIST-(0,"P","A","F","*","","LN",100)) ;returns a list containing logical names of process objects@l_list_elem_len=ELEMENT_LENGTH(P_OBJ_LIST:VAL) ;returns a list, with the same attributes giving the length ;of the corresponding attribute in the processobjects list

DELETE_ELEMENT ( v, index [ , index2 ] )

Deletes individual elements in the vector ‘v’.

‘v’ Any vector expression.

‘index’ A positive integer or a vector specifying the element or elements tobe deleted. If index is higher than the length of vector v or nega-tive, nothing is deleted.

‘index2’ A positive integer ( >= index ). If given, the range index .. index2is deleted. If omitted, only one element is deleted.

Value: A vector which is otherwise identical to ‘v’, but the element(s)specified by the index or index range are deleted.

Example:@V = (1,3,5,7,9)@I = (6,2,4,0,4)@R = DELETE_ELEMENT(%V,%I) ;returns vector (1,5,9)



ABB Automation 149

HIGH(vector)LOW(vector)

The largest (HIGH) or the smallest (LOW) element in a vector.

’vector’ A vector, the elements of which are integer, real or time data.

Value: A vector of one element which is the largest or smallest element inthe argument vector. The element is of the data types integer ortime, provided all elements in the argument vector are of thesedata types, else it is a real value.

Example:@V = (1,-5.6,3.3,37)@HIGH = HIGH(%V);returns 37.0@LOW = LOW(%V);returns -5.6

HIGH_INDEX(vector)LOW_INDEX(vector)

The index of the largest or smallest element in a vector.

HIGH_INDEX returns the index of the largest and LOW_INDEX the index of thesmallest element in the argument vector. If the argument vector is empty, or if thereare no valid elements, the function returns the value 0.

‘vector' A vector with integer, real or time elements.

Value: An integer.

Examples:@V = (1,-5.6,3.3,37)@A = HIGH_INDEX(%V) ;returns 4 @B = LOW_INDEX(%V) ;returns 2

INTERP(vector,x)

Interpolates a value from a curve.

'vector’ A vector with integer or real elements.

'x' A real or integer number.

'vector' is interpreted as (X,Y) coordinate pairs defining a curve. The 1st and 2nd ele-ments define one point (x,y) on the curve, 3rd and 4th define another point, etc. The Xvalues must be given in ascending order. The Y value corresponding to the given 'x' isinterpolated from the curve and returned as a real number. If 'x' < X1, Y1 is returned.If 'x' > Xn, Yn is returned (where 'n' denotes the number of coordinate pairs in thevector).

Value: A real number.



1MRS751250-MEN

ABB Automation150

Examples:@A(1) = 1.0 ;X1@A(2) = 6.0 ;Y1@A(3) = 3.0 ;X2@A(4) = 7.0 ;Y2Y3=INTERP(%A,1.0) ;returns 6.0Y4=INTERP(%A,2.0) ;returns 6.5Y5=INTERP(%A,5.0) ;returns 7.0

INVERSE(vector,n,low,high)

Inverts a curve.

’vector’ A vector with real elements given in ascending order.

’n’ An integer in the range 1...10000, the length of the resulting vec-tor.

’low’,’high’ Real or integer numbers (high > low).

The elements in ’vector’ are thought to define a monotonously ascending curve y =y(x), where the indexes of the vector represent x-values and the elements of the vectorrepresent y-values. The INVERSE function inverts the curve, i.e. solves the curve x =x(y) by linear interpolation.

The numeric solution is returned in the resulting vector elements so that the i:th ele-ment gives the x-value corresponding to y = ’low’ + i * (’high’ - ’low’)/’n’. The y valuessmaller than the first x value (first index of the source vector) are assigned the valueof the first index, and the elements larger than the highest index are assigned the valueof the highest index.

Value: A vector of length ’n’ with real elements, where the element valuesare the x values of the inverted curve, y(x) in the range y = ’low’ ...’high’. The y values are counted according to the formula y = ’low’+ i * (’high’ - ’low’)/’n’, where ’i’ is the index of the x value.

Examples:@A(1) = 3.0@A(2) = 4.0@A(3) = 9.0

@X = INVERSE(%A,5,0.0,10.0);The vector X now consists of the elements:; 1.0 (y=2); 2.0 (y=4); 2.4 (y=6); 2.8 (y=8); 3.0 (y=10)

For y=2, x gets the value 1.0, because this is the lowest possible value, and for y=10,x gets the value 3.0, because this is the highest possible value.

MEAN(vector)

The mean value of all the elements in the argument vector.



ABB Automation 151

’vector’ A vector, the elements of which are of the data type real, integer ortime.

Value: A vector of one element. The data type of the element is real.

Example:@V = (1,-5.6,3.3,37)@M = MEAN(%V);Now M(1) == 8.925

PICK(vector,indexes)

Picks specified elements from a vector and stores them in another vector.

’vector’ A vector expression. The source vector from which elements areselected.

’indexes’ A vector with integer elements, 1...10000. The vector specifies theindexes of the elements which will be selected from the sourcevector.

Value: A vector containing the elements selected from the source vector.

If the index vector contains indexes that cannot be found in the source vector, the cor-responding elements in the result vector are given NOT SAMPLED_STATUS (seethe “Status Codes” manual).

Example:@P = (1,2,3,5,7,11,13,17,19)@N = (7,4,1)@S = PICK(%P,%N);Now S == (13,5,1)

See also SELECT.

REMOVE_DUPLICATES(v [, status_handling])

Removes duplicate elements of a vector.

'v' Vector value to be examined.

'status_handling' Text value, either "CONSIDER_STATUS" or"IGNORE_STATUS"), default = "IGNORE_STATUS"

Value: Vector value containing the different element values of 'v'.

Two elements are considered equal if all the following criteria are satisfied:

• The value types are the same.

• The values are the same.



1MRS751250-MEN

ABB Automation152

• The status values are the same ( when "CONSIDER_STATUS") or else bothvalid ( < 10 ) (when "IGNORE_STATUS").

The test for equality is recursive, i.e if an element is a vector or list, its componentsare tested for equality.

The element values are returned in the order of appearance in ’v’.

REVERSE(vector)

Assembles a new vector by reversing the order of the elements in the argument vector.

’vector’ A vector.

Value: A vector of the same length as the argument vector.

Example:@V = (1,-5.6,3.3,37)REVERSE(%V);returns (37,3.3,-5.6,1)

SELECT(source,condition,[wildcards])

The function selects the elements of a vector or a list that fulfill a given criterion.

’source’ A vector or a list where all attributes are vectors of equal length.The source vector or list from which the elements are selected.

’condition’ A text containing the selection criterion. If ’source’ is a vector, theindividual elements can be referred to by the notation ( ), whichcan be used as an operand. Alternatively, the selection criterioncan be typed as an incomplete conditional expression which lacksleft operands. The condition starts with a relation operator and if itcontains logical operators, they are followed by relational opera-tors. If ’source’ is of list type, the attribute names can be used asoperands.

‘wildcards’ Text, “WILDCARDS” or “NO_WILDCARDS”. “WILDCARDS”= wildcards % and * allowed. “NO_WILDCARDS” = wildcardsnot allowed.

If 'source' is a vector, each vector element is related to the condition. The indexes ofthose elements which fulfil the condition, i.e., give it the value TRUE, are included inthe result vector. Likewise, if 'source' is a list type expression, the function selects theindexes which fulfil the condition.

If wildcards are allowed, % can be used in ‘condition’ to represent any single charac-ter, and * to represent one or more characters, including spaces.

Value: An integer vector containing the indexes of the elements that wereselected from the source vector or list.



ABB Automation 153

Examples:@A = (1.0,2.5,7.0,10.6)@I = SELECT(%A,">= 2 AND < 10");Now I == (2,3)@S = SELECT(A:DOS(1..30),">0")@A = PICK(B:DOV(1..30),%S);The registrations of the data object A that have a status >0 are selected and;the corresponding values of the data object B are picked.;If ’source’ is a list containing the attributes AB and CD the condition can bewritten, ;e.g., ;"(AB > 10) AND (CD == 5)" which implies that the indexes which;fulfil these conditions are selected.SELECT(%V,"GET_STATUS () == 0");means that the elements with status == 0 in the vector %V are selected.

SORT(data,[start,[length]])

Sorts a vector in ascending order or alphabetical order.

The function sorts a vector of numeric data or ASCII strings into ascending order oralphabetical order (ASCII code order) respectively. If the vector contains ASCII ele-ments, the sorting can be based on a selected sort key, i.e., a substring, in the ele-ments.

’data’ The vector to be sorted. The elements of the vector must be uni-form, either numeric or ASCII strings.

’start’ The start position (1 ... 255) of the sort key string if ’data’ is com-posed of ASCII elements. Default = 1, i.e., the first character in theASCII elements.

’length’ The length in number of characters (1 ... 255) of the sort key, if’data’ is composed of ASCII elements. Default = 255, i.e., the en-tire string.

Value: An integer vector containing the indexes of ’data’ arranged in theorder gained from the sorting. For instance, if the first element ofthe result vector is 25, the 25th element of the ’data’ vector is thesmallest one or the first one in alphabetic order.

Example:@UNSORTED = (7,9,4,3,35,6)@INDEX = SORT(%UNSORTED)

;Now: %INDEX == (4,3,6,1,2,5)@SORTED = PICK(%UNSORTED,%INDEX)

SPREAD(vector,indexes,value)

The function replaces certain vector elements with other values.

’vector’ A vector. The source vector containing the elements to be re-placed.

’indexes’ A vector of integer elements, 1...10000. The index vector contain-ing the indexes to be replaced.

’value’ Any SCIL data type. The replacing value(s).



1MRS751250-MEN

ABB Automation154

Those elements in the source vector which have the indexes specified by the indexvector are replaced with ’value’. If ’value’ is a vector, its elements replace in turn theelements specified by the index vector. If ’value’ contains more elements than ’in-dexes’, the superfluous elements are disregarded. If there are fewer elements in ’value’than in ’indexes’, the indexes that have no corresponding value are omitted from theresult vector. If the index vector contains higher indexes than what are included in thesource vector, they are disregarded, i.e., the length of ’vector’ is not changed.

Value: A vector.

Example:@V = (1,2,3,4,5)@I = (1,3,5)@A = (6,7,8)@S = SPREAD(%V,%I,%A)@T = SPREAD(%V,%I,0);Now;%S = = (6,2,7,4,8);%T = = (0,2,0,4,0)

SUM(vector)

The sum of all the elements in a vector.

’vector’ A vector with integer, real or time elements.

Value: A vector of one element. The element is an integer or a time valueif all the elements in the argument vector are integers or time val-ues respectively. Else it is a real number.

Example:@V = (1,-5.6,3.3,37)@SUM= SUM(%V);Now;%SUM(1) = = 35.7

SUM_POS(vector)SUM_NEG(vector)

The sum of the positive or negative elements in a vector.

These functions work in the same way as SUM, but SUM_POS calculates the sum ofthe positive values, and SUM_NEG the sum of the negative values.

’vector’ A vector with integer, real or time elements.

Value: A vector of one element. The element is an integer or a time valueif all the elements in the argument vector are integers or time val-ues respectively. Else it is a real number.

Examples:@V = (1,-5.6,3.3,37)@POS = SUM_POS(%V)@NEG = SUM_NEG(%V);Now;%POS(1) == 41.3;%NEG(1) = = -5.6



ABB Automation 155

TREND(vector,n)

Assembles a new vector from the last (highest indexed) elements in a vector.

’vector’ A vector.

’n’ An integer in the range 0...10000. The number of elements to beincluded in the result vector.

Value: A vector of length ’n’. If ’n’ is greater than the length of the argu-ment vector, the first elements get no values (they getNOT_SAMPLED_STATUS, see appendix C).

Examples:@V = (1,-5.6,3.3,37)TREND(%V,2) == (3.3,37);returns vector (3.3,37)

VECTOR [ ( [element1, ....., elementn] ) ]

Creates a vector with given elements.

‘elementn’ An expression of any data type. The elements in the vector. Up to10000 elements can be given. Using VECTOR without any ele-ment list creates an empty vector.

Value: A vector with the given elements.

Example:@A = VECTOR();The variable A will be an empty vector.

8.7 Database and List Functions

The functions in this section are used for building application object navigators, ob-ject lists, event and alarm lists.

The functions APPLICATION_OBJECT_COUNT, APPLICATION_OBJECT_LIST¸and APPLICATION_OBJECT_ATTRIBUTES provide the same functionality as theNEXT and PREV functions used along with the #SEARCH command. Unlike the#SEARCH command, the APPLICATION_ functions operate in memory (RAM). Asthey do not read the database files, they give a faster result than NEXT and PREV.Some simple cases, such as APPLICATION_OBJECT_COUNT(apl ,type), do not re-quire browsing the database and are therefore very fast.

A navigation tool should not rely on the counts returned byAPPLICATION_OBJECT_COUNT and APPLICATION_OBJECT_LIST being thesame, because the database may change between the calls.



1MRS751250-MEN

ABB Automation156

History Database Functions

HISTORY_DATABASE_MANAGER("OPEN"[, apl])

Open a session to the history database of an application.

The HISTORY_DATABASE_MANAGER function is session-based. A query sessionis first created. Subsequent calls of the function may then set various query parame-ters and do queries. At last, the session is closed.

There may be up to 10 open query sessions within one SCIL context.

When a SCIL context is deleted, the open query sessions are closed automatically.However, it is a good practice to close the sessions explicitly by SCIL to save systemresources.

’apl’ Integer or text value.

When an integer, specifies the application number ( 0 = currentapplication )

Text keyword "NO_APPLICATION" is used to specify no appli-cation.

Default value is 0.

Value: List.

SESSION Integer value. Used to identify the session insubsequent calls.

STATUS Integer value, SCIL status code.

This command opens a new query session and sets the query parameters to their de-fault values (described later). If already 10 sessions are open, statusSCIL_TOO_MANY_HDB_SESSIONS is returned in the STATUS attribute of the re-sult.

If another than the current APPLICATION is specified, it has to be local ( in sameSYS ) but its state is allowed to be COLD.

If no application is specified, SET_DIRECTORY command must be used to tell thehistory database manager where to find the database.

If a cold application or no application at all is specified, the user defined attributes ofuser defined process objects are not returned, because there is no process database tofind the attribute descriptions of corresponding F-type objects.



ABB Automation 157

HISTORY_DATABASE_MANAGER("CLOSE", session)

Close a session to the history database of an application.

’session’ Integer value returned by OPEN command.

Value: List.


This command closes the session by releasing all the resources associated to the ses-sion.

HISTORY_DATABASE_MANAGER("SET_PERIOD", session, begin[,end])

Set time period of database query.


’begin’ Time value defining the first day of the period. The following for-mat can be used pack_time(1998,4,1,0,0,0)

’end’ Time value defining the last day of the period, default = ’begin’.


Value: List.

DATE_COUNT Integer value. Number of days whosehistory database was successfullyopened.

MISSING_DATES Time vector containing the dates whosedatabase files could not be read.

MISSING_STATUS Integer vector containing the status codesof failed database file reads.


The period defines the time period whose database files are included in the query. Aperiod may contain up to 1000 database files. Status SCIL_PERIOD_TOO_LONG isreturned, if this limit is exceeded.

The arguments ’begin’ and ’end’ are used only to define the date: hours, minutes andseconds are ignored.

The period is initially empty.



1MRS751250-MEN

ABB Automation158

HISTORY_DATABASE_MANAGER("SET_DIRECTORY", session, di-rectory)

Set location of database files.


’directory’ Text or text vector containing the directory ( or directories ) whereto locate the database files.

Value: List.


Up to 20 directories may be specified. Status SCIL_TOO_MANY_DIRECTORIES isreturned if this limit is exceeded.

Setting this parameter resets the active period.

When a session is opened, this parameter is set to point to the APL_ subdirectory ofthe application. If no application is defined, the parameter is left empty.

HISTORY_DATABASE_MANAGER("SET_WINDOW", session, begin,end)

Set the time window of the query.


’begin’ Time value or an integer 0.

Begin time of the window. If 0, the window has an open begin-ning.

’end’ Time value or an integer 0.

End time of the window. If 0, the window has an open end.

Value: List.


This command sets the time window of the query. A time window may have an openbeginning and/or an open end, meaning all events older than ’end’ or old events newerthan ’begin’, respectively.



ABB Automation 159

When a session is opened, the window is set to ( 0 , 0 ).

HISTORY_DATABASE_MANAGER("SET_ORDER", session, order)

Set logging order.


’order’ Text keyword, either "LOG" or "EVENT".

Value "LOG" requests the manager to return the events in the or-der they were written into the database, value "EVENT" in the or-der of ET and EM attribute value.

Value: List.


If logging order is requested, the time window applies to attributes HT and HM of theevent, otherwise to attributes ET and EM.

When a session is opened, the order is set to "EVENT".

HISTORY_DATABASE_MANAGER("SET_DIRECTION", session, di-rection)

Set search direction.


’direction’ Text keyword, either "FORWARD" or "BACKWARD".

Value ’FORWARD’ requests the manager to start the query fromthe beginning of the time window, value "BACKWARD" from theend of the time window .

Value: List.


The results of a query are returned in the order of ’direction’: If "FORWARD", theyare returned in time order, if "BACKWARD", they are returned in reversed time or-der.

If both ’begin’ and ’end’ are non-zero, they may be given in any order.



1MRS751250-MEN

ABB Automation160

When a session is opened, the direction is set to "BACKWARD".

HISTORY_DATABASE_MANAGER("SET_TIMEOUT", session, time-out)

Set a maximum time a query may last.


’timeout’ Integer or real value, time-out in seconds.

Value: List.


The time-out of a query specifies the maximum time a query may last. If it is ex-ceeded, the query is interrupted and the partial results found so far are returned.

When a session is opened, the time-out is set to 5 seconds.

HISTORY_DATABASE_MANAGER("SET_CONDITION", session,condition)

Set a condition for requested events.


’condition’ Text value, the condition requested events should fulfill.

Value: List.


The condition is given as in #INIT_QUERY and #SEARCH commands.

When a session is opened, the condition is set to an empty string.

HISTORY_DATABASE_MANAGER("SET_ATTRIBUTES", session, at-tributes)

Set the attributes whose values are to be returned a query. History database informa-tion related to each event are described in the Application Objects manual Chapter 3.


’attributes’ Text vector.

Specifies the set of attributes whose value is returned by the query.



ABB Automation 161

Value: List.


Up to 100 attributes may be specified. Status SCIL_TOO_MANY_ATTRIBUTES isreturned if this limit is exceeded.

Attributes LN, IX, OV, ET and EM do not have to specified, they are always includedin the set. The object type specific names ( BI, BO, etc. ) for the object value attributeare not used. If no application is specified for the session, the user defined attributesof user defined process objects are not returned by the query.

The initial value of the set is ( LN, IX, OV, ET, EM ).

HISTORY_DATABASE_MANAGER("GET_PARAMETERS", session)

Get current value of parameters.


Value: List.

DIRECTORY Text vector, file directories to locate databasefiles.

PERIOD Two place vector containing the first and lastdate of the period, see SET_PERIOD com-mand.

WINDOW Two place vector containing the beginning andend of the time window, see SET_WINDOW,

ORDER "LOG" or "EVENT".

DIRECTION "FORWARD" or "BACKWARD".

TIMEOUT Real value, the query time-out in seconds.

ATTRIBUTES Text vector, the attributes returned by thequery.

CONDITION Text value, the query condition.


HISTORY_DATABASE_MANAGER("QUERY", session, count[, start])

Query history database.




1MRS751250-MEN

ABB Automation162

’count’ Integer value, the maximum number of events to be returned.

’start’ Integer or vector value, the identifier of event to start the query at.

Integer value 0 restarts the query. Default is 0.

Value: List.


SUCCESS Text value, indicating the success of the query :

"DONE" All the specified events were found.

"MORE" The number of events specified by ’count’ werefound. There may be more events to find.

"TIMEOUT" The query took a too long time and was inter-rupted. There may be more events to find.

COUNT Integer value depicting the number of the re-turned events.

LAST Vector value, the event identifier of the lastprocessed event.

ID Vector value containing the identifiers of thereturned events.

DATA List value containing the attributes of the re-turned events.

To continue a query, the event id returned by the interrupted query ( attribute LAST )should be used as the argument ’start’ of the subsequent query. The event identified by’start’ is not included in the result.

The attribute DATA of the function result contains the event data read from the data-base as a list. The attributes of the list are the ones specified by SET_ATTRIBUTEScommand, see 2.12. History database information related to each event are describedin the Application Objects manual Chapter 3. The value of each attribute is a vector oflength COUNT. If an event does not have a certain attribute, the corresponding ele-ment in the vector has status PROF_ATTRIBUTE_DOES_NOT_EXIST. The list maybe further processed with SELECT function by the event list dialog, if needed.

When a query is interrupted by TIMEOUT and the query order is EVENT, it is notguaranteed that the events returned by two subsequent queries are returned in exactlycorrect order. It is possible, that events contained in database files not yet processedshould have been included in the results of the interrupted query.

The following example reads the latest 20 events, then waits a second and reads thenew ones. For clarity, error handling is omitted.



ABB Automation 163

Example:@R = HISTORY_DATABASE_MANAGER("OPEN")@SESSION = R:VSESSION@PER=HISTORY_DATABASE_MANAGER(“SET_PERIOD”, SES:VSESSION,PACK_TIME(1998,4,1,0,0,0),CLOCK)@FIRST = HISTORY_DATABASE_MANAGER("QUERY",%SESSION,20)#IF FIRST:VCOUNT > 0 #THEN #BLOCK #PAUSE 1 @R = HISTORY_DATABASE_MANAGER("SET_ORDER",%SESSION,"FORWARD") @SECOND = HISTORY_DATABASE_MANAGER("QUERY",%SESSION,100,FIRST:VID(1))#BLOCK_END

HISTORY_DATABASE_MANAGER("READ", session, event)

Read all the attributes of the event specified by the event identifier. History databaseinformation related to each event are described in the Application Objects manualChapter 3.


’event’ Vector value, the event identifier of the event.

Value: List.

DATA List value containing all the attributes of theevent.


HISTORY_DATABASE_MANAGER("SET_COMMENT", session,event, comment)

Set the EX attribute of the specified event.


’event’ Vector value, the event identifier of the event.

’comment’ Text value, the comment.

Value: List.


The second query may miss a new event if its time-stamp is out of order.



1MRS751250-MEN

ABB Automation164

HISTORY_DATABASE_MANAGER("WRITE", session, data)

Writes an event into the history database.

’data’ List value describing all the attributes of one event.


Value: List.


This command writes an event into the history database. The attribute values to bewritten are given in the list argument ’data’.

Attribute HT is used to specify the history database file, into which the event is writ-ten. The file is created if it does not exist.

The following conventions are used to handle missing attributes:

1. Current time is used for missing HT, HM and HD.

2. HT, HM and HD values are used for missing ET, EM and ED.

3. All other missing numeric attributes are set to zero.

4. All missing text attributes are set empty.

General Object Listing Functions

APPLICATION_OBJECT_COUNT (apl, type [,order [,direction [, start[,condition]]]])

Counts the application objects of a specified type which fulfill a given criterion.

‘apl’ Integer. The number of the application where objects are counted.0 = current application. The function supports both local and ex-ternal applications.

‘type’ Text value. Object type, See the ‘type’argument of theAPPLICATION_OBJECT_LIST function.

‘order’ See the ‘order’ argument of the APPLICATION_OBJECT_LISTfunction.

‘direction’ See the ‘direction’ argument of theAPPLICATION_OBJECT_LIST function.

‘start’ See the ‘start’ argument of the APPLICATION_OBJECT_LISTfunction.

‘condition’ See the ‘condition’ argument of theAPPLICATION_OBJECT_LIST function.



ABB Automation 165

Value: Integer. The number of objects of the given type fulfilling the con-dition.

Example:@Alarms_in_Unit_5 = APPLICATION_OBJECT_COUNT ( 0, "IX", "UNIT", "", 5,- "AL == 1")@Time_Channel_Count = APPLICATION_OBJECT_COUNT ( 0, "T")

APPLICATION_OBJECT_LIST(apl,type[,order[,direction[,start[,condition[,attributes[,max]]]]])

Returns a list of application objects selected by type and other criteria.

‘apl’ Integer. The number of the application to navigate in. 0 = currentapplication. The function supports both local and external applica-tions.

‘type’ Text value. Object type: "P", "IX", "UP", "IX_AND_UP", "X","F", "D", "C", "T" or "A".

"P" denotes process objects (predefined).

"IX" denotes indexes of process objects (predefined).

"UP" denotes process objects of user defined types.

"IX_AND_UP" denotes process objects of both predefined anduser defined types.

"X" denotes scales.

"F" denotes free type objects.

"D" denotes data objects.

"C" denotes command procedures.

"T" denotes time channels.

"A" denotes event channels.

‘order’ Text. The search order given as a text expression:

"A" or “ALPHABETICAL” Alphabetical order. Searchingthrough the object names in alpha-

Because of modifications to types "P" and "IX", the new behavior is not fully com-patible with revision 8.4.1. Types "P" and "IX" no longer count process objects ofuser defined types.



1MRS751250-MEN

ABB Automation166

betical order (no index). Whenused with type “P”, only groupnames are included in the search.If used with type "IX" or"IX_AND_UP", the indexes aresearched in name/index order.

"I" or “INDEX” Index order (only for process ob-jects of predefined types). Returnsthe indexes of the process objectgiven as 'start’.

P" or “PHYSICAL” Address order. Only applicablewhen ‘type’ is “IX”, “UP” or“IX_AND_UP”.

"U" or "UNIT" Alphabetic ( name / index ) orderwithin the unit given as 'start' (type "IX", “UP” or“IX_AND_UP”).

"E" or "EXECUTION" Execution order. The executionorder within a time channel. 'type'can be either "D" or "C". Both areequal and means that the searchconcerns both data objects andcommand procedures.

"" Default value ( = "A" )

‘direction’ Text value:

"F" or "FORWARD" Forward browsing

"B" or "BACKWARD" Backward browsing

"" Default value ( = "F" )

‘start’ Start point of the search. Depends on the object type and searchorder as follows:

Order "A": Type "IX" and "IX_AND_UP": Logical name(text), or a list with the following attributes:

LN Logical name ( text )

IX Index ( integer )

Other types Logical name (text)

All types: "" = default value



ABB Automation 167

Order "I": Logical name ( text )

Order "P": Unit (integer), or a list with the following at-tributes:

UN Unit ( integer )

OA Object address ( integer ) (optional)

OB Object bit address ( integer ) (op-tional)

"" = default value

Order "U": Unit number ( integer), or a list with the fol-lowing attributes:

UN Unit ( integer )

LN Logical name ( text ) (optional)

IX Index ( integer ) (optional)

Order "E": Time channel name ( text ), or a list with thefollowing attributes:

TC Time channel name ( text )

OT Object type: "D" or "C" (optional)

ON Object name ( text ) (optional)

If the ‘start’ argument specifies an existing object, that object is not included in thesearch. The ‘start’ argument is case insensitive.

‘condition’ A text containing the criterion for selecting objects. The selectioncriterion is a boolean type expression composed of relations andlogical operators. The relations have an attribute as the left oper-and. All attributes, except vector type attributes, can be included inthe expression. In the formation of names, the wildcard characters% and * can be used. % represents one character anywhere in thename, * represents none, one or several characters at the end of thename. Default = "".

‘attributes’ Text vector containing the names of attributes to be returned inaddition to LN (and IX or OT). Default = "" ( no additional attrib-utes ).

‘max’ Maximum number of objects to be returned ( integer ). Default =max. vector length.

Value: A list including the following attributes:



1MRS751250-MEN

ABB Automation168

COUNT Integer value, number of objects returned

MORE Boolean value. TRUE if browsing was inter-rupted due to ‘max’ being exceeded

LN Text vector, names of the objects

IX Integer vector, indexes ( types "IX" and"IX_AND_UP" only)

OT Text vector ( values "D" or "C" ) (order "E"only)

Plus additional attributes defined by the 'attributes' argument.

The objects are returned in the order specified by 'order' even ifbackward browsing is specified.

Example:@l_ctype=APPLICATION_OBJECT_LIST(0,"C","E","F","TC_TEST","","",100)@v_attributes=("GC","GT","LF","ZT")@l_ptype=APPLICATION_OBJECT_LIST(0,"P","A","F","","",%v_attributes,100)@ATS_V=("EP","OS","AG","IU")@l_POINDEX=APPLICATION_OBJECT_LIST(0,"IX","P","F","","",%ATS_V,100)@l_xtype=APPLICATION_OBJECT_LIST(0,"X","A","F","","","",100)@EVENT_CHANNEL_ATS_V=("CM","ON","LN","OT","SN","ST","ZT")@l_atype=APPLICATION_OBJECT_LIST(0,"A","A","F","*","",-%EVENT_CHANNEL_ATS_V,100)

APPLICATION_OBJECT_ATTRIBUTES (apl,type,objects,attributes)

Returns the values of specified attributes of given objects.

‘apl’ Application number ( as in APPLICATION_OBJECT_LIST ).

‘type’ Object type ( as in APPLICATION_OBJECT_LIST ).

‘objects’ A text vector containing the names of the objects or a list with theattribute LN as a text vector. In the case when the ´type´ argument(second argument) is “IX” or “IX_AND_UP”, the ´objects´ argu-ment (third argument) is a list with the attributes:

LN Text vector containing object names

IX Integer vector containing the indexes

‘attributes’ Text vector containing the names of attributes to be read.

Because of modifications to types "P" and "IX", the behavior in 8.4.2 revision is notfully compatible with 8.4.1. Types "P" and "IX" no longer returns process objects ofuser defined types.



ABB Automation 169

Value: A list with attributes specified by ’attributes’. Each attribute has avector value containing the values of object attribute.

Example:@ATTRS_V=( "AB","UB","PB","XB")@OBJECTS_L=LIST(LN=vector("HLTEST","HLTEST"),IX=vector(10,22))@OBJ_A=APPLICATION_OBJECT_ATTRIBUTES(0,"IX",%OBJECTS_L,%ATTRS_V)

Notes referring to Example, the example requires the existance of a processobjectnamed ´HLTEST´. Object ´HLTEST´ needs to have at least the indexes 11 and 22.The returned value is a list of 4 attributes.

END_QUERY

Tells whether a process query initiated with #INIT_QUERY is completed.

The function tests whether all objects matching a process query initiated by the#INIT_QUERY command (Chapter 7) have been read with the PROD_QUERY func-tion. The END_QUERY function is always used without an argument.

Value: Boolean data. TRUE = the query is completed. FALSE = the queryis not completed.

Example:#IF END_QUERY #THEN #BLOCK

!SHOW MESSAGE "READY"#BLOCK_END

#ELSE #BLOCK@LIST = PROD_QUERY(20)!SHOW NAME LIST:VLN!SHOW VALUE LIST:VOV#BLOCK_END

If the query has been completed, the message READY is shown on screen. Otherwise,20 more process objects are handled.

FETCH (appl,type,name[,index])

Fetches the attribute of a selected object.

The function forms a list containing all definition attributes of an object, which can bea process object, a data object, a command procedure, a time channel, an event chan-nel, a scale, a base system object or a free type object.

'appl' Integer expression, 0 ... 99. The number of the application. 0 = theown application. The function supports both local and external ap-plications.

'type' Text expression. The type of the object: "D", "C", "T", "A", "P","X", "B" or "F".

'name' Text expression. The name of the object.

'index' Integer expression, 0...255. The index of a process object of a pre-defined type (not obligatory). If 'index' is omitted or == 0 for proc-



1MRS751250-MEN

ABB Automation170

ess objects of the predefined types, the function returns the attrib-utes that are common to the process object group.

Value: List. The list contains most attributes of the object (excludingsome changing attributes, such as OV). If the named object doesnot exist, a list is returned with only one attribute, IU, which hasthe value -1.

Example:@V = FETCH(0,"P","A",1);V:VLN has value "A";V:VIX has value 1

NEXT (n)PREV (n)

"Next object" and "previous object".

These functions enables browsing through the records of a search initiated with the#SEARCH command. Process objects, data objects, command procedures, scales,time channels, event channels and free type objects can be searched through. Thefunctions require that the search has been initiated with the #SEARCH command(Chapter 7. ).

’n’ Integer, 1 ... 10. The identity number of the search within the pic-ture, command procedure or dialog system (see the #SEARCHcommand in Chapter 7.).

Value: A list containing all the attributes of the next or the previous objectof the search. The object type determines which attributes are re-turned. If the object does not exist a list is returned containing onlythe IU attribute which has the value -1.

Example:#SEARCH 2 0 "P" "A" "A"@OBJ = NEXT(2)!SHOW NAME OBJ:VLN

The name of the process object group following A in alphabetical order is shown.

PHYS_FETCH (appl,unit,address[,bitaddress])

The function forms a list with attributes taken from a process object.

The process object is specified with its physical address.

’appl’ Integer, 1 ... 99. The application number. 0 = the own application.

’unit’ Integer. The unit number of the process unit where the object issituated. This is the station number as known to the application.

’address’ Integer. Object address. The OA attribute of the process object.



ABB Automation 171

’bitaddress’ Integer, 0...15. Bit number (can be omitted). The OB attribute ofthe object.

Value: List. All attributes which appear in the object definition form areincluded in the list. If the object does not exist, the list containsonly one attribute, IU, which has the value -1.

Example:@OBJ = PHYS_FETCH (0,3,1010,5)

PROD_QUERY (n)

Returns the attributes of the process objects selected with #INIT_QUERY.

The function returns in list form the attribute values of the process objects selectedwith the preceding #INIT_QUERY command (see Chapter 7.). The PROD_QUERYfunction must be situated in the same picture, command procedure or dialog system asthe #INIT_QUERY command. The query concerns always the current application.

After one #INIT_QUERY, the function may be called several times. Each time itcontinues from where it finished previously.

’n’ Integer, [-] 1 ... APL:BQL. The maximum number of process ob-jects that are included in the query. If the number is given with anegative sign, the browsing is performed backwards. For computerperformance reasons, it is recommended not to give a number thatis larger than 100.

Value: A list containing the following attributes:

Identification: LN (Logical Name), IX (Index), PT (Process Object Type), OI(Object Identification), OX (Object Text)

Object value: OV (Object Value), OS (Object Status)

Alarm state: AL (Alarm), AS (Alarm State), AR (Alarm Receipt), AZ (AlarmZone)

Time stamps: RT (Registration Time), RM (Registration Milliseconds), AT(Alarm Time), AM (Alarm Milliseconds), YT, YM

RTU attributes: SE (Selection), SP (Stop Execution), OF (Overflow),

Stamps set by the station: BL, CT, OR, RA, RB, SB

Blocking attributes: AB, HB, PB, UP, XB

Miscellaneous attributes: RI, RX

In addition, when the query concerns the history buffer: CA (Changed Attribute)



1MRS751250-MEN

ABB Automation172

The attribute values of a certain attribute form a vector. For example, the LN attributeis a vector of all object names included in the query. Vector elements with the sameindex refer to the same process object (does not concern objects of user-definedtypes).

Examples:

The result of the function call PROD_QUERY(4) could be:

Attributes

Index LN IX OV

1 "TEMP" 1 63.02 "PH" 5 6.53 "SWITCH" 1 14 "SWITCH" 2 0

The attribute LN (logical name) constitutes the first vector, IX (index) the second oneand OV (object value) the third one.

Data Object Functions

DATA_FETCH (appl,name,index1[,step[,count]])DATA_FETCH (appl,name,time1,time2[,step[,shift]])DATA_FETCH (appl,name,time1[,step[,count[,shift]]])DATA_FETCH (appl,name,indexes)

Reads the records of a data object and returns them as a list.

Up to 10000 data records can be read in one function call. If the function call com-prises more records, only the first 10000 records are returned, but no error message isgiven.

’appl’ Integer, 0 ... 99. The application number (0 = the own application).

’name’ Text data. The name of the data object.

’index1’ Integer, 0 ... 65535. The index of the first record to be fetched.

’step’ Integer, -32767 ... +32767. Defines the step between indexes to befetched. The default value = 1 (all indexes are fetched). If ’step’ isnegative, the values are returned in reverse time order.

Examples:

’step’ = 2: indexes ’index1’, ’index1’ + 2, ’index1’ + 4, etc. are fetched.’step’ = -2: indexes ’index1’, ’index1’ - 2, ’index1’ - 4, etc. arefetched.

’count’ Integer, 0 ... 10000. The number of indexes to be fetched. 0 (de-fault) means all existing indexes up to 10000.



ABB Automation 173

’indexes’ Vector. An integer vector defining explicitly the indexes to befetched.

’time1’ Time data. The start of the time interval to be fetched.

’time2’ Time data. The end of the time interval. If ’time1’ < ’time2’, thevalues are returned in time order regardless of the sign of ’step’. If’time1’ > ’time2’, the values are returned in reversed time order re-gardless of the sign of ’step’. The given time range is regarded as asemi-open range. For example, if the range is given as 09.00.00 -10.00.00, a record sampled at 09.00.00 is included but a recordsampled at 10.00.00 is excluded (if shift = 0, see below).

’shift’ Integer, 0 or 1. 0 = no shift, 1 = a shift of one sampling interval.For example, a record sampled at 10.00.05 is included in the timerange 09.00.00 - 10.00.00, but a record sampled at 09.00.05 is ex-cluded. Default value: 0.

Value: A list including the following attributes:

OV real vector, registered data

RT time vector, the registration times

OS integer vector, the status codes

IX integer vector, the indexes of the values

LE integer, the number of elements in the resultvectors above (OV, RT, OS, IX).

Examples:@A = DATA_FETCH (0,"ABC",1,5,0);Every fifth registration of the data object ABC, from the first index to thelast one, but at ;the most 10000 registrations, are fetched and placed in thevariable object A:V.@T1 = PACK_TIME (1989,9,10,0,0,0)@T2 = PACK_TIME (1989,9,10,12,0,0);Two time data values are defined.

@A = DATA_FETCH (0, "ABC", %T1, %T2);The registrations in the data object ABC of the given time interval.

@B = DATA_FETCH (0, "DEF", A:VIX);The corresponding values of the data object DEF.

@C = DATA_FETCH (0, "GHI", A:VIX +5);The corresponding values of GHI shifted by 5.

DATA_STORE (appl,name,data,index1[,step])DATA_STORE (appl,name,data,indexes)

Writes historical data into a data object and returns the status of the operation.

’appl’ Integer, 0 ... 99. The application system number. 0 = the own ap-plication.



1MRS751250-MEN

ABB Automation174

’name’ Text. The name of the data object.

’data’ List. The values to be stored.

’index1’ Integer, 1 ...65535. The index of the first record where data isstored.

’step’ Integer. This argument defines the step between indexes to bestored. Default value = 1 (all indexes are stored). If ‘step’ is nega-tive, the values are stored in reverse time order.

Examples:

'step' = 2: indexes 'index1', 'index1' + 2, 'index1' + 4, etc., are stored.

'step' = -2: indexes 'index1', 'index1' - 2, 'index1' - 4, etc., are stored.

'indexes' Integer vector. Defines explicitly the indexes where data is stored.

The following attributes in 'data' are stored:

OV real vector - recorded values

RT time vector - registration times

OS integer vector - status codes

If the RT attribute is missing from 'data', the original registration times are kept. If theOS attribute is missing, the status codes in the OV vector are stored as the OS attrib-ute.

Value: Integer. A status code. See the status codes in the Status Codesmanual.0 = OK.

Examples:@V = DATA_FETCH(0,"A",%I)@OS = DATA_STORE(0,"DATA",%V,5,2)@OS = DATA_STORE(2,"A",%V,%I)

The registrations of the data object A in the current application are stored in the vari-able V and copied to the data object DATA in the current application and the dataobject A in application 2.

8.8 Functions for Reading and Writing Files

The following two files reads and writes binary files:

READ_BYTES ( file [ , start [ , length ] ] )

Reads data from a binary file.



ABB Automation 175

This function enables the importing of binary data from a file. The function is analo-gous to the READ_TEXT function (see below) but returns byte string data instead ofa text vector.

‘file’ Text. The name of the file. See the ‘file’ argument of theREAD_TEXT function below.

‘start’ Positive integer value, defaults to 1. Specifies the byte positionwithin the file where to start reading.

‘length’ Non-negative integer value. Specifies the maximum number ofbytes to be read. Default value = 1048576 (max. byte stringlength).

Return value: Byte string containing the read data.

WRITE_BYTES ( file , data [ , append ] )

Writes data in a binary file.

This function enables the export of binary data to a file. The function is analogous tothe WRITE_TEXT function (see below) but takes a byte string data argument insteadof a text vector.

‘file’ Text or byte string. The name of the file. See the ‘file’ argument ofthe READ_TEXT function below.

‘data’ Byte string value containing the data to be written.

‘append’ Integer value 0 or 1, defaults to 0. If 0, a new file is created. If 1,the data are appended to the file, if it already exists.

Value: Integer value. The status code of file write operation, 0 if OK.

The following two functions read and write data in text files:

READ_COLUMNS(file, pos, width[, start[, count]])

Reads the columns of a text file.

The file reads the columns and stores them in a vector where each element is a textvector containing the text of one column.

‘file’ Text or byte string. The name of the file. See the ‘file’ argument ofthe READ_TEXT function below.

‘pos’ Integer vector. Specifies the start positions of the columns to beread ( 1 .. 510). The positions do not have to be in ascending order.

‘width’ Integer vector. The ‘width’ argument must be of the same length asthe ‘pos’ argument. Specifies the column widths ( 1 .. 255). The



1MRS751250-MEN

ABB Automation176

columns are allowed to overlap. Columns are read up to characterposition 510 only.

‘start’ Positive integer value, defaults to 1. Specifies the line numberwithin the file where to start reading.

‘count’ Non-negative integer value, defaults to 10000. Specifies themaximum number of lines to be read.

Value: A vector of the same length as ‘pos’ and ‘width’. Each element ofthe vector is a text vector containing the contents of one column.

WRITE_COLUMNS ( file, pos , width , data [ , append ] )

Writes text in columns in a text file.

The text to be written is given as a vector where each element is a text vector corre-sponding to one column in the file.

‘file’ Text value or byte string. The name of the file. See the ‘file’ argu-ment of the READ_TEXT function below.

‘pos’ Integer vector. Specifies the start positions of the columns to bewritten ( 1 .. 510). The positions do not have to be in ascendingorder.

‘width’ Integer vector. Must be of the same length as pos. Specifies thecolumn widths ( 1 .. 255). The columns are allowed to overlap. Ifthey do, a column earlier in the list will be covered by the laterone. Any data written past character position 510 are lost. Possiblegaps between the columns are filled with space characters.

‘data’ Vector value of the same length as pos and width. Each element ofthe vector is a text vector containing the contents of one column.The element vectors must be of the same length.

‘append’ Integer value 0 or 1, defaults to 0. If 0, a new file is created. If 1,the data are appended to the file, if it already exists.

Value: Integer value. The status of the write operation, 0 if OK.

READ_TEXT(file[,start[,number]])

The function reads selected lines from an ASCII file and stores them as a text vector.

'file' Text or byte string expression. This argument specifies the ASCIIfile from where text lines are read given in one of the followingmanners:

- [path/]file_namewhere 'path' is a logical path name and 'file_name' is the



ABB Automation 177

name of the file, including a possible extension. If ’path’ isomitted, the default path names are used (see the #PATHcommand), except in Visual SCIL objects where the pathdefined by the attribute DEFAULT_PATH in the maindialog is used.

- file_namewhere ’file_name’ is the name of the file in operating sys-tem dependent form.

- file tag. The internal file name representation.See file handling functions.

’start’ Positive or negative integer. If the integer is positive, it is thenumber of the first line to be read from the ASCII file countedfrom the beginning of the file (1 = the first line). If it is negative, itis the number of the last line to be read counted from the end ofthe file (-1 = the last line). Default: 1.

’number’ Integer, 0 ... 10000. The number of lines to be read from the ASCIIfile.0 = nothing is read. Default: 1000.

If ’start’ is omitted, reading starts from the beginning of the file. If ’number’ is omitted,reading is performed to the end of file, or until 1000 lines have been read.

Value: A vector containing the lines read from the ASCII file, in the sameorder as in the file. The elements of the vector are of text type.

Example:!SHOW DIRECTIVE READ_TEXT("DIRECT.TXT");The contents of the file DIRECT.TXT are shown in the window DIRECTIVE.#SET T:VIN = READ_TEXT("ABC.TXT")#SET T:VIU = 1#CREATE ABC:C = %T

The file ABC.TXT is read and its contents are stored as the program of the commandprocedure ABC.

READ_TEXT("FILE",-1,100) means that the last 100 lines are read,READ_TEXT("FILE",-101,100) the preceding 100 lines, etc.

WRITE_TEXT(file,text[,cont])

The function writes the contents of a text vector into an ASCII-file.

’file’ Text or byte string data. This argument specifies the ASCII file tobe written. See the ‘file’ argument of the READ_TEXT function.

'text' A text vector containing the text to be written.

'cont' An integer, 1 or 0. Default = 0.



1MRS751250-MEN

ABB Automation178

The text in the text vector is stored under the name and in the directory determined by’file’. If ’cont’ = 1, the contents of the text vector are appended to the file, and possibleprevious contents are saved. If it is 0, or if it is lacking, the function destroys possibleprevious contents of the file. If ’text’ contains elements of other types than text, theseelements are written as empty lines.

Value: An integer. The status code of the action. See the Status Codesmanual.0 = OK.

Example:@A = WRITE_TEXT("A",%V,1);Now %A == 0, if the operation was successful.

The following three functions are used to handle ASCII files, here called parameterfiles. The parameter files are described in Appendix C.

WRITE_PARAMETER(file, section, key, value)

Writes a parameter in a parameter file.

The file and/or the section is created if it does not exist.

‘file’ Text or byte string data. This argument specifies the parameter fileto be written. See the ‘file’ argument of the READ_TEXT func-tion.

‘section’ Text. The name of the section.

‘key’ Text. The key of the parameter.

‘value’ Text. The value to be assigned to the parameter.

Return value: A list with one attribute:

STATUS = The status code of the write operation.

Parameter file lines may be up to 510 characters long. If both the key and the data areexactly 255 characters long, error SCIL_PARAMETER_FILE_LINE_TOO_LONG israised.

READ_PARAMETER(file, section, key, alt)

Reads a parameter in a parameter file.





ABB Automation 179

‘key’ Text. The key of the parameter.

‘alt’ Text. The value to be returned if "section" or "key" does not existin the specified file.

Value: A list with the following two attributes if the operation was suc-cessful:

STATUS = The status code of the read operation.

VALUE = The value of the parameter. In case that opera-tion did not succeed only a list with attribute:STATUS = “the statuscode” is returned.

If the fourth argument is not given error status 558SCIL_SECTION_DOES_NOT_EXIST/559 SCCIL_KEY_DOES_NOT_EXISIT isreturned if the section/key does not exist.

Example:@PORT=READ_PARAMETER("C:\WINNT\WIN.INI","MCILAU","UDP PORT")

DELETE_PARAMETER(file, section[, key])

Deletes a parameter in a parameter file.



‘key’ Text. The key of the paramter to deleted. If ‘key’ is omitted fromthe argument list, the whole section is deleted.

Return value: A list with the attribute STATUS.

STATUS = The status code of the delete operation.

8.9 Functions Related to Program Execution

The argument functions are used in programs that can take arguments and return avalue. Such programs are named programs, user defined methods and programs exe-cuted with the DO function.

ARGUMENT( n )

Reads input arguments.

This function reads the input arguments given in the argument list of method calls,named program calls and the DO function. By means of this function the argumentscan be used in the programs.



1MRS751250-MEN

ABB Automation180

’n’ Integer. The ordinal number of the argument ( 1 .. 32 ) as given inthe argument list.

Value: The value of the n:th argument in the argument list.

If there are fewer than ‘n’ arguments in the argument list, a value with data type"NONE" is returned. The actual count of the arguments in the call is obtained by theARGUMENT_COUNT function.

Example:

See the DO function below.

ARGUMENT_COUNT

Returns the total number of arguments in the argument list of the program call.

Value: Integer, 0 .. 32.

ARGUMENTS

Returns all arguments in the argument list of the program call as a vector.

Value: Vector with 0 ... 32 elements. The arguments given in the argu-ment list of the program call (method call, named program call orDO function). If the program call has no arguments, a zero lengthvector is returned.

Example:@A = ARGUMENTS@B = DO (%PROGRAM, %A)

COMPILE(source)

Runs the SCIL compiler.

'source' Text vector containing the SCIL source code.

Value: A list value with following attributes:

STATUS Integer, status code from the com-pilation

CODE Byte string , the compiled bytecode

ERROR_LINE Text, the erroneous source line

ERROR_LINE_NUMBER Integer, the line number in error



ABB Automation 181

ERROR_POSITION Integer, the character position inerror

Attribute CODE is returned if the compilation succeeds (STATUS == 0). AttributesERROR_LINE, ERROR_LINE_NUMBER and ERROR_POSITION are returned ifthe compilation fails.

DO (program [, a1, .... , an] )

Executes a SCIL program given as argument.

Up to 31 arguments can be passed to the SCIL program. If the executed programcontains a #RETURN command the function returns the value of the expression fol-lowing the #RETURN command (see Chapter 7.). If the SCIL program does not con-tain a #RETURN command, integer zero is returned.

‘program’ A text vector containing the SCIL program to be executed.

‘a1’ ... ’an’ Any SCIL data type. These arguments are passed to the SCIL pro-gram (up to 31 arguments may be specified).

Value: The value returned by the #RETURN command in the executedprogram, or 0 if the program did not terminate by #RETURNcommand.

Example 1:@RESULT = DO ( READ_TEXT ( "APL_/TEST.TXT" ))

;Contents of file TEST.TXT:@l_app_info=APL:BSV11#return %l_app_info

Example 2:;An example that calculates the tangent function of its argument.@RESULT = DO ( READ_TEXT ( "TANGENT.TXT" ), 0.5 )

;Contents of file TANGENT.TXT:#RETURN SIN ( ARGUMENT ( 1 ) ) / COS ( ARGUMENT ( 1 ) )

ERROR_STATE

Returns the current ‘ERROR_STATE’ at execution point.

Value: Text value depicting the current error state: "STOP","CONTINUE", "IGNORE" or "EVENT".

Example:@t_old_state = ERROR_STATE

;assign value of current error handling policy to t_old_state#ERROR IGNORE

;set error handling policy to IGNORE@t_error_state1=ERROR_STATE

;returns IGNORE that is the ’ERROR_STATE’ at this point#ERROR CONTINUE

;set error handling policy to CONTINUE@t_error_state2=ERROR_STATE

;returns CONTINUE that is the ’ERROR_STATE’ at this point#ERROR STOP



1MRS751250-MEN

ABB Automation182

;set error handling policy to STOP@t_error_state3=ERROR_STATE

;returns STOP that is the ’ERROR_STATE’ at this point#ERROR EVENT

;set error handling policy to EVENT@t_error_state4=ERROR_STATE

;returns EVENT that is the ’ERROR_STATE’ at this point#ERROR ‘t_old_state’

;reset error handling policy

OPS_CALL(command [,0])

The function executes an operating system command.

’command’ Text. The command to be executed.

’0’ Integer. If not included, the OPS_CALL starts the execution of thecommand and waits until it has finished. If included, the commandonly starts the execution of the command.

Value: A list with the following attributes is returned:

ST Integer, the status value returned by the oper-ating system. 0 = OK, any other value = failure.

FN 0. The attribute has no meaning when WindowsNTi is used.

Example:@A = OPS_CALL("mons -d rbsnt 4 -n");Opening a MicroSCADA application window.

OPS_PROCESS ( command [ , directory [ , wait ] ] )

Starts an external program as a separate process within the operating system environ-ment.

The functionality is close to that of OPS_CALL function. However, OPS_PROCESSdoes not start the command interpreter, it simply runs the program given as an argu-ment of the function call. In Windows NT this means that only "EXE" files may bestarted this way. To execute "BAT" files, OPS_CALL should be used.

‘command’ Text value containing the command to start the process, e.g."\tools\my_tool my_file -my_option".

‘directory’ Optional text value containing the work or default directory to beused by the process. The directory is given in OS dependent for-mat (see PARSE_FILE_NAME function to obtain OS directorynames ). An empty name, "", denotes the work directory of thecaller. Default value = "".

i Windows NT is a trademark of Microsoft Corporation



ABB Automation 183

‘wait’ Optional text value, either "WAIT" or "NOWAIT". If "WAIT" isgiven, termination of the created process is waited for. Otherwise,the function returns immediately after the process has started. De-fault is "NOWAIT".

Value: A list value containing the following attributes:

START_STATUS Integer value containing the OS dependentstatus code obtained when starting the process.

EXIT_STATUS Integer value containing the OS and applicationdependent exit status of the process. This at-tribute is returned only if "WAIT" is specifiedand start of process succeeded.

STATUS

The status produced by the latest error situation in the program that is being executed.

The function is set to zero after use and when a new program other than named pro-gram is started. If a program executes a named program, then the status will not be setto zero. Hence, if STATUS <> 0 in the program that is calling the other one, thenSTATUS is also <> 0 in the named program. The function is always used without anargument.

Value: A positive integer. A status code. See the status codes in the StatusCodes manual.

Example:#ERROR IGNORE@S = STATUS#SET ABC:PBI = 0@S = STATUS#IF %S <> 0 #THEN !SHOW ERROR %S#ELSE !ERASE ERROR

WORKSTATION_CALL(command[, other, ...])

Function for executing commands on the workstation.

'command' Text, the action to be done at the workstation.

"EXECUTE" = workstation execution

"VIEW_DOCUMENT" = viewing a document in a browser

Argument is case insensitive.

'other' Text, command specific arguments.

Argument is case insensitive with a maximum length of 255 char-acters..



1MRS751250-MEN

ABB Automation184

Return value: SCIL status code.

When WORKSTATION_CALL is used, the first argument should always be one ofthe commands.

When the command "EXECUTE" is used, the second argument should be the programto be started (including the path and possible program specific parameters) and thethird argument should be a default working directory to be used. When "EXECUTE"is used, the first two arguments must be included.

When the command "VIEW_DOCUMENT" is used, the second argument should bethe page to be shown in a browser. When "VIEW_DOCUMENT" is used, the twofirst arguments must be included.

Initialization file for viewing documents is "wserver.ini" and it is located in\sc\prog\exec -directory. It contains information about the document viewer (Browserincluding the path) to be started to view a document.

Listing of wserver.ini:

[document_viewer]

viewer = C:\Program Files\Plus!\Microsoft Internet\Iexplore.exe;;viewer = C:\Program Files\Netscape\Communicator\Program\netscape.exe

If the installation of the browser is located elsewhere, the wserver.ini file should beedited to point to the installation directory of the browser.

Examples:@S=WORKSTATION_CALL("VIEW_DOCUMENT", "file://c:/ms_docs/help.html");Opens a file called help.html in the browser on the workstation@S=WORKSTATION_CALL("EXECUTE", "c:\winnt\notepad.exe test.txt", "c:\");Starts the notepad program on the workstation

8.10 Communication Functions

LOAD_DCP(file, link, start)

Loads and starts an internal DCP-NET.

The function LOAD_DCP loads a DCP-NET program to an internal DCP-NET (situ-ated within the base system), and starts the NET unit. The file named in the argumentlist is read from the disk and stored in the RAM memory of the communication unit.The program starts if the ’start’ is other than 0.

The function could be placed in the initial NET configuration programSYS_NETCON.COM or in an initial application program (APL_INIT_1 or 2). It canalso be used for restarting NET during operation.

’file’ Text. The file name of the communication program which isloaded to the communication unit. The communication programincludes the NET node number of the communication unit and apreconfiguration (default configuration).



ABB Automation 185

’link’ Integer. The base system object number of the link, the LINn:Bobject, to which the communication unit is connected. The LINobject (the LINn:BSD attribute) defines the system device name ofthe unit, RM00 or RM01, which was given to the unit during in-stallation. Hence, the program given with ‘file’ is loaded to theNET unit with the device name defined in the LIN object specifiedwith ‘link’.

'start' An integer stating whether the NET unit will be started or not afterthe program has been loaded: 0 = the NET is not started, anythingelse = the NET is started.

Value: The function always returns the value 0.

Example:@LOAD = LOAD_DCP("SYS_NET2",2,1)

In the example the function loads the communication program called SYS_NET2 tothe communication board connected to link number 2 (defined as LIN2:B).

SPACOM(message)

Communicates with a SPACOM unit connected to a COM port.

The SPACOM function sends the ‘message’ string to the SPACOM unit and returnsthe reply character string. The function can be used only for communication withSPACOM units connected to the basesystem. This assumes that the base system at-tributes SYS:BSD and SYS:BSP have been set (see the System Objects manual,Chapter 4).

‘message’ Text. The message to be sent to the SPACOM unit.

Value: Text. Reply string. “N” is returned if the unit replies with NAK,and “T” is returned if the unit does not reply or the reply cannot beinterpreted (time-out).

TIMEOUT(integer)

Changes communication time-out.

Changes locally the base system time-out used in the communication with othernodes. The function affects only the context where it is used. The global time-out isspecified by the SYS:BTI attribute.

'integer' Integer expression, >= 0. The time-out in milliseconds.

0 means that SYS:BTI will be used for time-out.

Value: The previous time-out value.



1MRS751250-MEN

ABB Automation186

Example:@OLD = TIMEOUT(10000);The time-out is changed#SET STA:S.. ....... ;Communication with NET@TEMP = TIMEOUT(0) ;The time-out is reset to SYS:BTI.

8.11 File and Directory Handling Functions

File handling SCIL functions implement the handling of drives (or disk-like devices ),directories and files in an operating-system independent way.

Used terminology:

Drive name Printable drive name in OS dependent format. In NT, one-letter name A, B, ... or a UNC name. Lower case letters ac-cepted as a function argument.

Directory name Printable directory name. In NT, any valid file name. Re-turned in case stored by the file system, case-insensitive as afunction argument. For portability, directory names createdby SCIL should contain only letters A-Z, digits and under-scores.

File name Printable file name. In NT, any valid file name. Returned incase stored by the file system, case-insensitive as a functionargument.By convention, file name is divided into the proper filename and the extension separated by a period. If there areseveral periods in the name, the last one is considered as thename/extension separator.For portability, file names created by SCIL should containonly letters A-Z, digits, underscores and at most one period.

Absolute path Printable absolute directory or file path in OS dependentformat. Absolute path contains the drive name ( or uses thedefault drive ) and all the intermediate directory names touniquely identify a directory or a file.In NT, the syntax of an absolute path is[drive:]\[directory_name\]*name.

Relative path Printable relative directory or file path in OS dependentformat. Given a root directory, relative path contains inter-mediate directory names ( if any ) to uniquely identify a di-rectory or a file within the root directory. The absolute pathof a file is obtained by combining the absolute path of theroot directory and the relative path of the file.In NT, the syntax of a relative path is [direc-tory_name\]*name. In MMC, also the syntax referring to thecurrent directory (e.g. "..\file") may be used.

SCIL name File (or directory) name given in operating system inde-pendent format used by other SCIL commands and func-tions, see PARSE_FILE_NAME function for details.Examples:



ABB Automation 187

"PATH/FILE.EXT","/SYS/ACTIVE/SYS_/SYS_BASCON.COM", "/LIB"

Drive tag An OS independent identifier of a drive represented as abyte string data in SCIL.

Absolute directory tag An OS independent representation of the absolute path of adirectory. A drive tag is a valid absolute directory tag refer-ring to the root directory of the drive.

Relative directory tag An OS independent representation of the relative path of adirectory.

Absolute file tag An OS independent representation of the absolute path of afile.

Relative file tag An OS independent representation of the relative path of afile.

Filters Filters used when browsing directories may contain follow-ing wildcard characters:

* Matches with any character string includingnull string.

? Matches with any single character, at the end ofname or extension it matches also nullcharacter.

% Matches with any single character.

An example: sysm?.exe? matches withsysm.exe, but sysm%.exe% does not.

Operation of the filters is comparable to theWindows NT Find|Files or Folders operation.

Calling Syntax

The calling syntax and functionality of the SCIL functions is described below.

The common calling syntax of DRIVE_MANAGER, DIRECTORY_MANAGER andFILE_MANAGER is

FUNCTION_NAME ( command [ , argument ]* )

The first argument ’command’ is a text keyword that selects the requested subfunction.The keyword is case-insensitive. In the descriptions of subfunctions below, the ’com-mand’ argument is represented as an upper-case text constant. Any valid SCIL expres-sion resulting to a valid keyword value will do, of course.

The auxiliary functions do not follow this convention.

Example listing all files at given directory:

@tag=FM_DIRECTORY(“c:\temp”)



1MRS751250-MEN

ABB Automation188

@list=FM_REPRESENT(FILE_MANAGER(“LIST”, %tag)); %list is a vector containing the filenames of the directory “c:\temp”.

Compatibility

The functions in this chapter all use abstract tags instead of text names as file identifi-ers.

To enable using these functions together with the file handling commands and func-tions of section 8.12, all the functions of section 8.12 will also accept a file tag argu-ment as the identifier of the file.

DIRECTORY_MANAGER

The following commands are recognized by DIRECTORY_MANAGER:

• LIST

• CREATE

• DELETE

• DELETE_CONTENTS

• EXISTS

• COPY

• COPY_CONTENTS

• MOVE

• RENAME

• GET_ATTRIBUTES

DIRECTORY_MANAGER("LIST", directory[, filter[, recursion]])

Lists the directories contained in a given directory.

’directory’ Absolute directory tag of the directory whose contents are listed.

’filter’ Text value: The filter for the directory names to be listed. Maycontain wildcard characters * , % and ?.Default value is "" (no filter).

’recursion’ Text keyword "RECURSIVE" or "NON_RECURSIVE". Recur-sive listing means that whole directory hierarchy rooted in ’root’ islisted. Default value is "NON_RECURSIVE".

Value: Vector value containing the relative directory tags of the directo-ries found.



ABB Automation 189

DIRECTORY_MANAGER("CREATE", directory[, recursion])

Creates a directory or a hierarchy of directories.

’directory’ Absolute directory tag of the directory to be created.

’recursion’ Text keyword "RECURSIVE" or "NON_RECURSIVE".Recursive creation means that all missing directories contained in‘directory' are created.Default value is "NON_RECURSIVE".

Value: Integer value: The status code of the operation.

DIRECTORY_MANAGER("DELETE", directory)

Deletes one or more directories and all the directories and files contained in them.

'directory' Absolute directory tag or a vector of tags to be deleted.

Value: List value with following attributes:OK Boolean value, TRUE if successful.FAILED A vector value containing relative directory or file tags

of directories and files not deleted. Missing if OK == TRUE.

STATUS An integer vector containing the status codes of faileddeletions. Missing if OK == TRUE.

DIRECTORY_MANAGER("DELETE_CONTENTS", directory[, filter[,subdirectories]])

Deletes files and directories contained in a given directory.

'directory' Absolute directory tag of the directory whose contents are deleted.

'filter' Text value: The filter for the file and directory names to be de-leted.May contain wildcard characters * , % and ?.Default value is "" (no filter).

'subdirectories' Text keyword "INCLUDE_DIRECTORIES" or"OMIT_DIRECTORIES"Specifies whether the subdirectories are deleted or not.If subdirectories are deleted, the filter is applied to the name ofsubdirectories ( not to the contained files ).Default value is "OMIT_DIRECTORIES".

Value: List value with following attributes:

OK Boolean value, TRUE if successful.



1MRS751250-MEN

ABB Automation190

FAILED A vector value containing relative directory orfile tags of directories and files not deleted.Missing if OK == TRUE.

STATUS An integer vector containing the status codes offailed deletions. Missing if OK == TRUE.

DIRECTORY_MANAGER("EXISTS", directory)

Checks the existence of one or more directories.

’directory’ Absolute directory tag or a vector of tags to be checked.

Value: Boolean or boolean vector value indicating whether the directoriesexist or not.

DIRECTORY_MANAGER("COPY ", source, target )

Copies a directory and all its contents into a new directory.

’source’ Absolute directory tag of the source directory.

’target’ Absolute directory tag of the target directory, which is created byCOPY.



FAILED A vector value containing relative directory orfile tags of directories and files not copied.Missing if OK == TRUE.

STATUS An integer vector containing the status codes offailed copies. Missing if OK == TRUE.

DIRECTORY_MANAGER("COPY_CONTENTS ", source, target[, fil-ter[, subdirectories[, overwrite]]])

Copies the files of a directory into another directory. Optionally, the subdirectoriesare recursively copied as well.

’source’ Absolute directory tag of the source directory.

’target’ Absolute directory tag of the target directory ( not created byCOPY_CONTENTS ).



ABB Automation 191

’filter’ Text value: The filter for the file and directory names to be copied.May contain wildcard characters * , % and ?.Default value is "" (no filter).

’subdirectories’ Text keyword "INCLUDE_DIRECTORIES" or"OMIT_DIRECTORIES"Specifies whether the subdirectories are copied or not.If subdirectories are copied, the filter is applied to the name ofsubdirectories ( not to the contained files ).Default value is "OMIT_DIRECTORIES".

’overwrite’ Text keyword "OVERWRITE" or "DONT_OVERWRITE"Specifies whether an existing file in target directory is overwrittenor not.Default value is "DONT_OVERWRITE"

Value: List value with following attributes :


FAILED A vector value containing relative directory orfile tags of directories and files not copied.Missing if OK == TRUE.

STATUS An integer vector containing the status codes offailed copies. Missing if OK == TRUE.

DIRECTORY_MANAGER "MOVE", directory, target)

Moves a directory to another directory.

’directory’ Absolute directory tag of the directory to be moved.

’target’ Absolute directory tag of the directory to become the new parentdirectory.


STATUS Integer value, the status code of the operation.

NEW_TAG New tag for the moved directory (if STATUS == 0)

Keyword arguments ’subdirectories’ and ’overwrite’ may be given in any order.



1MRS751250-MEN

ABB Automation192

DIRECTORY_MANAGER("RENAME", directory, name)

Renames a directory.

’directory’ Absolute directory tag of the directory to be renamed.

’name’ Text value, the new directory name.



NEW_TAG New tag for the renamed directory (if STATUS == 0)

DIRECTORY_MANAGER("GET_ATTRIBUTES", directory)

Returns attribute information from one or more directories.

’directory’ Absolute directory tag or vector of directory tags of interest.

value List value containing the following attributes:

STATUS Integer or integer vector value containing thestatus of each query.

READ_ONLY Boolean or boolean vector value.

SYSTEM Boolean or boolean vector value, TRUE if ex-clusively used by the OS.

FAILURES Integer value telling the number of failed que-ries.

DRIVE_MANAGER

A drive is the root of a file hierarchy. Depending on the operating system, a drive maycorrespond to a physical disk-like device or it may consist of several physical devicesor it may be a partitioning of a physical device or it may map to a directory of anotherdrive. In Windows NT, a drive corresponds to a Windows NT logical drive ( labeledA, B, and so on ) or an UNC (Universal Naming Convention) name of the form\\servername\sharename.

The following commands are recognized by DRIVE_MANAGER:

• LIST

• EXISTS

• GET_DEFAULT

• GET_ATTRIBUTES



ABB Automation 193

DRIVE_MANAGER("LIST")

Returns the drives available in the system.

Value: Vector value containing the drive tags of the available drives.

DRIVE_MANAGER("EXISTS", drive)

Checks the existence of one or more drives.

’drive’ Drive tag or a vector of drive tags to be checked.

Value: Boolean or boolean vector value indicating whether the drive(s)exist or not.

DRIVE_MANAGER("GET_DEFAULT")

Returns the default drive, i.e. the drive assumed if an absolute path does not containthe drive.

Value: Byte string value containing the tag of the default drive.

DRIVE_MANAGER("GET_ATTRIBUTES", tag)

Returns some information from drives.

’tag’ The drive tag or a vector of drive tags of interest.

Value: A list of following attributes:

STATUS Integer or integer vector value,the status code(s) of the query. Bad status is notreturned if TYPE is "REMOVABLE" and de-vice is not available.

FAILURES Integer value containing the number of failedqueries.If FAILURES == 0, STATUS contains all ze-roes.

TYPE Text or text vector value: "FIXED""REMOVABLE""CDROM""NETWORK""RAM""SHARED""UNKNOWN"



1MRS751250-MEN

ABB Automation194

CAPACITY Integer or integer vector value: The total ca-pacity of the drive in kilobytes. 0 is returned forunavailable device of TYPE "REMOVABLE".

FREE Integer or integer value: The unused capacity ofthe drive in kilobytes. 0 is returned for unavail-able device of TYPE "REMOVABLE".

FILE_MANAGER

The following commands are recognized by FILE_MANAGER:

• LIST

• DELETE

• EXISTS

• COPY

• MOVE

• RENAME

• GET_ATTRIBUTES

FILE_MANAGER("LIST", directory[, filter[, recursion]])

Lists the files ( but not directories ) contained in a given directory.

’directory’ Absolute directory tag of the directory whose contents are listed.

’filter’ Text value: The filter for the file names to be listed.May contain wildcard characters * % and ?. Default value is "" (no filter).

’recursion’ Text keyword "RECURSIVE" or "NON_RECURSIVE".Recursive listing means that all files in the directory hierarchyrooted in ’directory’ is listed.Default value is "NON_RECURSIVE".

Value: Vector value containing the relative file tags of the files found.

FILE_MANAGER(“DELETE",file )

Deletes one or more files.

’file’ Absolute file tag or a vector of file tags to be deleted.


DELETED Integer value containing the number of deletedfiles.



ABB Automation 195

FAILED Integer value containing the number of faileddeletions.

STATUS Integer or vector value containing the statuscode for each deletion.

FILE_MANAGER("EXISTS", file)

Checks the existence of one or more files.

’file’ Absolute file tag or a vector of file tags to be checked.

Value: Boolean or a boolean vector value indicating whether the file ex-ists or not.

FILE_MANAGER("COPY", source, target[, overwrite])

Copies the contents of a file to another file.

’source’ Absolute file tag of the source file.

’target’ Absolute file tag of the target file.

’overwrite’ Text keyword "OVERWRITE" or "DONT_OVERWRITE".Default value is "DONT_OVERWRITE".

Value: Integer value, the status code of the operation.

FILE_MANAGER("MOVE", file, target)

Moves a file to another directory.

’file’ Absolute file tag of the file to be moved.

’target’ Absolute directory tag of the directory to become the new parentdirectory.



NEW_TAG New tag for the moved file ( if STATUS == 0 )

FILE_MANAGER("RENAME", file, name)

Renames a file.

’file’ Absolute file tag of the file to be renamed.



1MRS751250-MEN

ABB Automation196

’name’ Text value, the new file name.



NEW_TAG New tag for the renamed file (if STATUS == 0).

FILE_MANAGER("GET_ATTRIBUTES", file )

Returns attribute information from one or more files.

’file’ Absolute file tag or vector of file tags of interest.

Value: List value containing the following attributes:

STATUS Integer or integer vector value, the status of thequery.

FAILURES Integer value telling the number of failed que-ries.

READ_ONLY Boolean or boolean vector value.

SYSTEM Boolean or boolean vector value, TRUE if ex-clusively used by the OS.

CREATED_S,

CREATED_US List or list vector values containing the creationtime of the file.

MODIFIED_S,

MODIFIED_US List or list vector values containing the modifi-cation time of the file.

SIZE_KB,

SIZE_B List or list vector values containing the size ofthe file.

The creation and modification times are given in two attributes:

xxx_S Time value, time to the accuracy of one second.

xxx_US Integer value, microseconds.

The file size is given in two attributes:

SIZE_KB Integer value, kilobytes.



ABB Automation 197

SIZE_B Integer value 0 … 1023, bytes.

Auxiliary Functions

FM_DRIVE(name[, check])

Creates a drive tag from one or more drive names or checks drive names.

'name' Text or text vector value, drive name(s). In NT, one-letter nameoptionally followed by ":" or a UNC name.

'check' Text keyword "CHECK".

Value: If "CHECK", a text or text vector value "OK" or "ERROR", oth-erwise a drive tag ( a byte string value ) or a vector of drive tags.

FM_DIRECTORY(path[, check])

Creates a directory tag from one or more directory paths or checks directory paths.

'path' Text or text vector value, directory path(s).In NT, any valid directory path.

'check' Text keyword "CHECK".

Value: If "CHECK", a text or text vector value:

"ABSOLUTE" if 'path' denotes a valid absolute path.

"RELATIVE" if 'path' denotes a valid relative path.

"ERROR" if 'path' is not a valid path.

Otherwise an absolute or relative directory tag ( a byte stringvalue) or a vector of tags.

FM_APPLICATION_DIRECTORY

Creates the absolute directory tag of the home directory of current application.

Value: The absolute directory tag of the home directory of current appli-cation.

FM_SCIL_DIRECTORY(name[, check])

Creates a directory tag from one or more SCIL names or checks SCIL names.

'name' Text or text vector value, SCIL name(s).



1MRS751250-MEN

ABB Automation198

’check’ Text keyword "CHECK".

Value: If "CHECK", a text or text vector value.

"ABSOLUTE", if ’name’ denotes a valid absolute directory.

"RELATIVE", if ’name’ denotes a valid application directory.

"ERROR", if ’name’ is not a valid SCIL name.

Otherwise an absolute directory tag ( a byte string value ) or avector of tags.

FM_FILE(path[, check])

Creates a file tag from one or more file paths or checks file paths.

’path’ Text or text vector value, file path(s).In NT, any valid file path.

’check’ Text keyword "CHECK".


"ABSOLUTE" if ’path’ denotes a valid absolute path.

"RELATIVE" if ’path’ denotes a valid relative path.

"ERROR" if ’path’ is not a valid path.

Otherwise an absolute or relative file tag ( a byte string value ) or avector of tags.

FM_SCIL_FILE(name[, option][, option])

Creates a file tag from one or more SCIL names or checks SCIL names.

’name’ Text or text vector value, SCIL name(s).

’option’ Text keyword "CHECK" or "IGNORE_EXISTING".


"ABSOLUTE" if ’name’ denotes a valid absolute file.

"RELATIVE" if ’name’ denotes a valid application file.

"ERROR" if ’name’ is not a valid SCIL name.

Otherwise an absolute file tag ( a byte string value ) or a vector oftags.



ABB Automation 199

If "IGNORE_EXISTING" option is not specified, the function does a lookup for thename given, and returns a tag for the found file. If the file does not exist, a tag for afile that would be created by ’name’ is returned. If the option is specified, the lookup isbypassed.

FM_REPRESENT(tag[, option]* )

Converts one or more drive, directory or file tags into an OS dependent text repre-sentation.

’tag’ Byte string or a byte string vector value: drive, directory or filetag(s).

’option’ One or more of following text keywords in any order

"DRIVE_POSTFIX" In NT, append a ":" to a drivename ( if a drive tag ).

"DIRECTORY_POSTFIX" In NT, append a "\" to directorypath ( if a directory tag ).

"UPPER_CASE" Use upper case letters.

"LOWER_CASE" Use lower case letters.

"CAPITALIZE" Capitalize the names.

Value: Text or text vector value, the text representation of the giventag(s).

By default, in NT a drive name is given without the trailing ":", a directory name isgiven without the trailing "\" and the case used when the tag was created is notchanged.

If ’tag’ denotes the default drive, an empty string is returned.

FM_SCIL_REPRESENT(tag[, case])

Converts one or more directory or file tags into a SCIL name text representation.

’tag’ Byte string or a byte string vector value: directory or file tag(s).

’case’ One of the following text keywords:

"UPPER_CASE" Use upper case letters.

"LOWER_CASE" Use lower case letters.

"CAPITALIZE" Capitalize the names.



1MRS751250-MEN

ABB Automation200

Value: Text or text vector value, the SCIL name representation of thegiven tag(s).

A zero length text is returned if the ’tag’ cannot be converted into a SCIL name, i.e. itcontains a drive or is not located below the root of SCIL file hierarchy (in NT,"\SC\").

FM_COMBINE(tag1[, tagi ]*, tagn )

Combines two or more drive, directory or file tags to create a new directory or filetag.

’tag1’ A drive or a directory tag ( either absolute or relative ).

’tagi’ One or more (up to 30 ) directory tags.The tags must be relative directory tags, except for the first onewhich can be an absolute directory tag using the default drive if’tag1’ is a drive tag.

’tagn’ A directory or file tag or vector of tags.

Value: A directory or file tag denoting the path from ’tag1’ to ’tagn’ or avector of such tags.

The tags given as the arguments must follow the order of file hierarchy. A drive mustbe first argument if any. Any absolute path containing a drive may not be specified ifthe first argument is a drive tag. Only one absolute path may be given. An absolutepath may not follow a relative path in the argument list. A file path must be the lastargument if any.

FM_EXTRACT(tag, component)

Extracts a component from one or more directory or file tags.

’tag’ Any directory or file tag or a vector of such tags.

’component’ Text keyword specifying the component to be extracted.

"DRIVE" The drive, zero length byte string is returned if’tag’ is not an absolute path.

"PATH" The intermediate directory path to the lastcomponent.

"DIRECTORY" The directory containing the ’tag’ ( "DRIVE"and "PATH" combined).

"LAST" The directory or file denoted by ’tag’.



ABB Automation 201

"APPLICATION_RELATIVE" The tag relative to the currentapplication directory.

Value: A byte string or a byte string vector containing the tag(s) of theselected component.

For a missing component, a zero length byte string is returned.

If the selected component is "LAST", a relative directory or file tag is returned.

If the selected component is "PATH" or "DIRECTORY", the result is absolute if ’tag’is absolute and relative if ’tag’ is relative.

FM_COMBINE_NAME(’name’, ’extension’)

Combines a proper file name and an extension to a file name.

’name’ Text or text vector value, the proper file name(s).

’extension’ Text or text vector value, the file name extension(s).

Value: Text or text vector value, the combined file name(s).

Either ’name’ or ’extension’ or both may be vectors. If both, they must be of equallength.

Trailing blanks, if any, are removed from ’name’ and ’extension’. If the extension isempty, the name is returned. Otherwise, a period is inserted between name and exten-sion. The resulting file name is not syntax checked.

FM_SPLIT_NAME(file)

Extracts the proper name and the extension from one or more file names.

’file’ Text or text vector value, file name(s).

Value: List value with following attributes.

NAME Text or text vector value, the proper name(s).

EXTENSION Text or text vector value, the extension(s).

8.12 File and Directory Management Functions

FILE_LOCK_MANAGER (function, file)

Locks and unlocks files.



1MRS751250-MEN

ABB Automation202

This function is used to temporarily lock a file for use of only one SCIL context. Thisfunction is mainly needed by tools (such as dialog editor) to prevent simultaneousmodification of same data by two users. All the SCIL tools accessing the file shoulduse FILE_LOCK_MANAGER to synchronize the access to the file, locking a filewith FILE_LOCK_MANAGER does not prevent accessing of the file byREAD_TEXT, WRITE_TEXT or other SCIL functions.

‘function’ Text value, the function to be performed:

“LOCK" lock the file for exclusive use.

"UNLOCK" unlock the file.

"BREAK" break the lock.

‘file’ Text value containing the name of the file to be locked in OS de-pendent format ( see PARSE_FILE_NAME function to obtain OSfile names).

Value: A text value containing:

"OK" Function successfully performed.

"LOCKED" "LOCK" failed because of an existing lock.

"BROKEN" "UNLOCK" detected that the file not locked,i.e. broken by somebody else.

“ INVALID" The 'file' argument is invalid. This means thatthe name is not a valid file name or the direc-tory in the name does not exist or the access toit is denied.

Notes:

• The file does not have to exist, actually ’file’ argument is used as a unique identi-fier of the lock. The argument is used a seed for a lock file name, which is gen-erated by prefixing the file name in ’file’ by ’_L_’ , for example if ’file’ is"C:\DATA\ABC.DAT", then the lock file name used is"C:\DATA\_L_ABC.DAT". Therefore, the file name should not be extremelylong.

• Two different ’file’ arguments may refer to one and same lock. For example, if alogical drive K points to directory "C:\DATA", then ’file’ arguments"C:\DATA\ABC.DAT" and "K:\ABC.DAT" denote the same lock.

• When a SCIL context is destroyed, all the locks it holds are automatically re-leased by the base system software.

• The function "BREAK" should be used with care. It should be used only after aprogram crash or other such failure which has left the file locked.



ABB Automation 203

KEYED_FILE_MANAGER ( function, file {,output_file {, key_size}})

File maintenance function.

This function saves corrupted files and does some other file maintenance. It can han-dle one file at a time, the ‘file’ argument, and provides the following operations se-lected by the ‘function’ argument:

"INFORMATION" Returns some information of the file.

"COMPACT" Compacts the file by rewriting the records in their key order. Afterthe compacting, the file is smaller and faster to access. The off-lineprogram REORG was previously used for this purpose.

"REBUILD" Reconstructs the file by scanning and rewriting the data blocks ofthe file, ignoring the index blocks. This function should be used ifthe internal structure of the file is corrupted, for example if status5015 ( FILE_INCONSISTENT ) is returned when the file is ac-cessed. The file may not be used by MicroSCADA when thisfunction is performed. The off-line program SAVER was previ-ously used for this purpose.

The optional argument 'key_size' overrides the key size read fromthe status block of the file. It should be used only if the statusblock of the file is corrupted. The corruption is indicated by statuscode 5016 (FILE_INVALID_KEY_SIZE) when attempting thisfunction without the key_size argument, or the same status codewhen trying to access the output file generated by this functionwithout the key_size argument.

The correct value of this argument is obtained by applying the"INFORMATION" function to an uncorrupted file of the sametype.

‘function’ Text: "INFORMATION", "COMPACT", or "REBUILD". Theoperation to be performed on the file (see above):

‘file’ Text or byte string value containing the file name.

‘output_file’ Text or byte string value containing the output file name (functionsCOMPACT and REBUILD only).

‘key_size’ Integer value, the size of the record key (function REBUILD only).

Value: List value containing various information depending on the func-tion argument.

The ‘function’ value "INFORMATION" returns the following at-tributes in the result list:

STATUS The status of the operation.



1MRS751250-MEN

ABB Automation204

VERSION The file format version number, currently0 or 1.

USED_BLOCKS Number of 512-byte blocks allocated forthe file.

KEY_SIZE The length of the record key.

INDEX_LEVELS The number of index levels used by theindex tree of the file.

The attributes VERSION, USED_BLOCKS and INDEX_LEVELSare present only if STATUS = 0.

The ‘function’ value "COMPACT" returns the same attributes asthe ‘function’ value "INFORMATION" ( the values are those be-fore the compacting) and in addition the following attribute:

RECORDS Number of records copied.

The ‘function’ value "REBUILD" returns the same attributes asthe ‘function’ value "COMPACT" and in addition the followingattribute:

DUPLICATES A text vector containing the key values thatwere found duplicated in the source file. The corresponding rec-ords in the output file may contain obsolete or otherwise bad data,they should be checked. Max. 1000 duplicate keys are reported.

If the status block of the file was corrupted, attributes VERSION,USED_BLOCKS and INDEX_LEVELS are not returned.

PARSE_FILE_NAME ( name [ , file ] )

Converts logical paths names and file names to operating system file names.

The path names and file names are converted in an operating system independentway.

‘name’ Text value: directory or path name, either

1) SCIL path name, e.g. "PICT"

2) SCIL directory name, e.g. "/APL/TEST/PICT" or "PICT/"

3) OS dependent directory name, e.g. "C:\SC\APL\TEST\PICT"

‘file’ Text value: optional file name, e.g. "station.pic"

Value: Text value containing the path name of the file ( or directory ) inOS dependent format, e.g."C:\SC\APL\TEST\PICT\STATION.PIC" ( or



ABB Automation 205

"C:\SC\APL\TEST\PICT"). Returns "", if there is an error in ar-guments.

Notes:

• The directory name in SCIL format may be given with or without the trailing "/"(see however note 3).

• The OS dependent directory name may be given with or without the OS depend-ent delimiter (e.g. "\").

• In SCIL, depending on the context, "PICT" may mean either the path PICT or thedirectory "/APL/xxx/PICT". To resolve the ambiguity, "PICT" is used for thepath and "PICT/" for the directory.

• If a path name is given as ’name’ and file is not given, the function returns thefirst directory in the path.

• If a path name is given as ’name’ and ’file’ exists, the complete file path name ofthe found file is returned.

• If a path name is given as ’name’ and ’file’ does not exist, the returned path namecontains the first directory of the logical path, i.e. the returned value is the com-plete would-be name of the file if created.

• The arguments of the function are case-insensitive. The case of the returnedvalue is OS dependent. In NT, upper case string is returned.

PATH ( name )

The real directory paths of a logical path name.

‘name’ Text expression containing the name of a logical path.

Value: Text vector containing the names (in an operating system depend-ent format) of directories that make up the logical path.

REP_LIB ( name )

The real file names of a logical representation library name.

‘name’ Text expression containing the name of the logical representationlibrary.

Value: Text vector containing the names (in an operating system depend-ent format) of library files that make up the logical library.



1MRS751250-MEN

ABB Automation206

PATHS ( level )

The logical paths defined on a specified level.

‘level’ Integer value 0 to 3 specifying the requested level in path hierar-chy:

0 = global paths

1 = application paths

2 = process specific paths (e.g. monitor paths)

3 = temporary paths

Value: Text vector containing the names of the defined logical paths onthe requested level.

REP_LIBS ( level )

The logical library names defined on a specified level.

‘level’ Integer value 0 to 3 specifying the requested level in path hierar-chy:

0 = global paths

1 = application paths

2 = process specific paths (e.g. monitor paths)

3 = temporary paths

Value: Text vector containing the names of the defined logical represen-tation libraries on the requested level.

SHADOW_FILE ( file_name )

Enable shadowing of files not created by MicroSCADA.

This function should be used, for example, by a tool that copies files to an applicationdirectory using operating system file transfer utilities.

‘file_name’ Text or byte string value containing the file name


STATUS status code ( 0 = OK ).



ABB Automation 207

QUEUED Boolean value indicating whether the file wasqueued for shadowing.

The function first locates the file. The status is returned in attribute STATUS. Then itchecks whether the file belongs to an application that is currently shadowed. If yes,the file is queued for shadowing ( the function does not wait for the completion ofshadowing) and TRUE is returned in attribute QUEUED. If not, FALSE is returnedand nothing is done.

8.13 DDE Client Functions

The DDE client functions allow the MicroSCADA user (application) access to exter-nal applications using the DDE (Dynamic Data Exchange) protocol. The DDE clientfunctions establish a DDE link between MicroSCADA and other Windows applica-tions, such as Microsoft Excel or Word. The MicroSCADA application works as aclient and the other application as a server. The other application must be runningwhen the connection is opened.

If the client and server applications are running in separate computers, NetDDE mustbe used.

The DDE protocol is supported by most Microsoft Windows applications. To use theMicroSCADA DDE client functions, the user should be familiar with the server ap-plication and its DDE functions.

The MicroSCADA DDE client functions support the following data transaction com-mands directed from the client (MicroSCADA) to the server application:

Request Requests a data transfer from a server to a client .

Poke Writes data in the server application.

Execute Executes an item (a command) in the server application (if executesupported by the application).

The DDE client functions use the following three identifiers to address data in theserver application:

Service name Usually the name of the server application.

Topic name Identifies a logical data context, e.g. a file.

Item name Identifies the data.

The DDE functions in MicroSCADA use status codes listed below, most of which areDDE protocol status codes. The status code texts can be, and should be, used as suchin SCIL expressions. They are defined as predefined integers in the MicroSCADAkernel.

STATUS codes Decimal value

DMLERR_NO_ERROR 0



1MRS751250-MEN

ABB Automation208

DMLERR_ADVACKTIMEOUT 16384

DMLERR_BUSY 16385

DMLERR_DATAACKTIMEOUT 16386

DMLERR_DLL_NOT_INITIALIZED 16387

DMLERR_DLL_USAGE 16388

DMLERR_EXECACKTIMEOUT 16389

DMLERR_INVALID_PARAMETER 16390

DMLERR_LOW_MEMORY 16391

DMLERR_MEMORY_ERROR 16392

DMLERR_NOTPROCESSED 16393

DMLERR_NO_CONV_ESTABLISHED 16394

DMLERR_POKEACKTIMEOUT 16395

DMLERR_POSTMSG_FAILED 16396

DMLERR_REENTRANCY 16397

DMLERR_SERVER_DIED 16398

DMLERR_SYS_ERROR 16399

DMLERR_UNADVACKTIMEOUT 16400

DMLERR_UNFOUND_QUEUE_ID 16401

DMLERR_ITEM_TOO_LONG 20483

DDE_CONNECT(service, topic)

Opens a connection to an external application.

The connection gets an identification number which is used in the subsequent DDEoperations. The DDE connections are SCIL context specific which means that theyare automatically closed when a picture is exited, when a command procedure hasbeen executed to the end or when the dialog system is deleted. Each SCIL context canhave up to 10 open DDE connections simultaneously.

The remote application must be running when the DDE_CONNECT function is is-sued. Likewise, the topic for which DDE_CONNECT is issued must be available. Forinstance, for Excel this means that the desired spreadsheet must be opened. The re-mote application can be started from SCIL with the OPS_CALL command. At thesame time the desired topic (e.g. a file) can be opened. A topic can also be openedlater by sending an open command to the server application using the DDE-_EXECUTE function.

’service’ Text. The service name the remote application responds to. Usu-ally the same as the application name.

’topic’ Text. A valid topic name within the remote application.



ABB Automation 209


STATUS = A predefined integer (see above). Thevalue indicates whether the function wassuccessfully executed or not.DMLERR_NO_ERROR (= 0) meansthat the operation succeeded.

CONNECTION_ID = Integer, 1 ... 10. The Id-number of theconnection. If the connection did notsucceed (STATUS <>DMLERR_NO_ERROR), theCONNECTION_ID is undefined.

Example:

Connecting to Excel 5.0, sheet 1:

@RESULT=DDE_CONNECT("EXCEL", "SHEET1")#IF RESULT:VSTATUS == DMLERR_NO_ERROR #THEN #BLOCK

@CONN = RESULT:VCONNECTION_ID#BLOCK_END ; Connection was successful#ELSE #BLOCK ; Connection not successful#BLOCK_END

DDE_DISCONNECT(connection_id)

Closes the connection specified by the argument.

’connection_id’ Integer, 1 .. 10. The DDE connection identifier obtained using theDDE_CONNECT.

Value: A list containing the following attribute:

STATUS = A predefined integer, see above. The value in-dicates whether the function was successfullyexecuted or not. DMLERR_NO_ERROR (= 0)means that the operation succeeded.

Example:

Disconnecting from a remote application (e.g. Excel):

@RESULT=DDE_DISCONNECT(%CONN )#IF RESULT:VSTATUS == DMLERR_NO_ERROR #THEN #BLOCK;Connection was successfully closed.#BLOCK_END#ELSE; Connection not successfully closed.

DDE_REQUEST(connection_id, item [,timeout])

Requests data from a remote application.

A connection to the application must be open (see above).



1MRS751250-MEN

ABB Automation210

’connection_id’ Integer, 1 ... 10. The DDE identifier obtained using theDDE_CONNECT.

’item’ Text. A valid DDE item in the remote application.

‘timeout’ Integer, 0 ... 1000. The DDE transaction timeout in seconds. Theparameter is optional. Default value = 20 s.


STATUS = A predefined integer (see above). The value in-dicates whether the function was successfullyexecuted. DMLERR_NO_ERROR (= 0) meansthat the operation succeeded.

DATA = Text (max length 255). Includes requested data.If STATUS is NOT equal toDMLERR_NO_ERROR, the DATA is unde-fined.

Example:

Requesting data from Excel:

@RESULT=DDE_REQUEST(%CONN, "R1C1", 30)#IF RESULT:VSTATUS== DMLERR_NO_ERROR #THEN #BLOCK

@ITEM_VALUE=RESULT:VDATA;The request was successful

#BLOCK_END#ELSE #BLOCK

;The request was NOT successful#BLOCK_END

DDE_POKE(connection_id, item, value [,timeout])

Sets the value of 'item' in a remote application.

A connection to the application must be open (see above).

'connection_id' Integer, 1 ... 10. The DDE identifier obtained using theDDE_CONNECT.

'item' Text. A valid DDE item in the remote application.

'value' Text. The value which will be set into item.

The cell references in Excel are language dependent if the referens style R1C1 is used(R for row and C for column). To check the type of referens style and the cell referensnotation of your Excel version select: Tools | Options | Genaral tab.



ABB Automation 211

‘timeout’ Integer, 0 ... 1000. The DDE transaction time-out in seconds. Theparameter is optional. Default value = 20 s.


STATUS = A predefined integer (see above). The valueindicates whether the function was success-fully executed. DMLERR_NO_ERROR (= 0)means that the operation succeeded.

Example:

Setting "Time of Day" in cell "R1C1" in Excel:

@RESULT=DDE_POKE(%CONN, "R1C1", TOD, 30)#IF RESULT:VSTATUS == DMLERR_NO_ERROR #THEN #BLOCK;The value was successfully set.#BLOCK_END#ELSE #BLOCK;The value was NOT successfully set.#BLOCK_END

DDE_EXECUTE(connection_id, statement [,timeout])

Executes a statement in a remote application.

The connection to the application must be open. To be able to use this function youneed to have the DDE documentation of the server application.

'connection_id' Integer, 1 ... 10. The DDE connection identifier obtained using theDDE_CONNECT.

'statement' Text. A valid executable statement in the remote application (seethe documentation of the application in question).

‘timeout’ Integer, 0 ... 1000. The DDE transaction time-out in seconds. Theparameter is optional. Default value = 20 s.


STATUS = A predefined integer (see above). The valueindicates whether the function was success-fully executed. DMLERR_NO_ERROR (= 0)means that the operation succeeded.

Example:

Executing a statement in Excel:

@RESULT=DDE_EXECUTE(%CONN, "%o~", 30)#IF RESULT:VSTATUS== DMLERR_NO_ERROR #THEN #BLOCK;The request command was successfully executed#BLOCK_END#ELSE #BLOCK;The request was NOT successful.#BLOCK_END



1MRS751250-MEN

ABB Automation212

The string "%o~" corresponds to <Alt+o><ENTER> in Excel and opens a dialog forcell formatting.

8.14 DDE Server Functions

MicroSCADA applications can be accessed from external Windows applications us-ing the DDE protocol, so that the MicroSCADA application works as a server and theother application as a client. See Chapter 2.

DDE Server supports the following SCIL data types:

Integer

Text

Time (Time will be returned as seconds count from 1.1.1978)

Boolean (Boolean will be returned as 0 or 1)

Real (Real will be returned to client application as SCIL real format("." as decimal separator))

The vector data type is not supported directly but can be used with the help of theDDE_VECTOR function described below. MicroSCADA real data can be trans-formed into text data with user defined decimal separator using the DDE_REALfunction (see below). The data types Bit string, Byte string and List are not sup-ported.

DDE_VECTOR(vector , decimal separator , list separator)

Creates a text format vector with user defined list separator.

The function transforms a SCIL vector into a format readable in the client in the ap-plication.

‘vector’ Vector. A valid SCIL expression. The vector may only containreal, integer, text and boolean elements. Note that the vector willbe transformed into a text which can contain no more than 256characters.

‘decimal separator’ Text. A valid separator in the client application.

‘list separator’ Text. A valid separator in client application.

Use the DDE_EXECUTE function with caution! Different applications respond dif-ferently to the DDE_EXECUTE statement. Excel, for example, must be the activeapplication on the desktop to be able to execute a submitted DDE_EXECUTE com-mand.



ABB Automation 213

Return value: A text composed of the elements in ‘vector’ separated by the listseparator (see the example below).

If a vector element is of invalid data type or missing, there is anempty value in result string. In other words, there are two con-secutive list separator characters in the result string.

Example:#SET APL:BUV = (TEST,1,2.0)@A = DDE_VECTOR(APL:BUV," ." ," ;" )

;Result: %A = TEST;1;2.0

DDE_REAL(real , separator)

Creates a text format real number with a user defined decimal separator.

‘real’ Real. A valid SCIL expression.

‘separator’ Text. A valid decimal separator in client application.

Return value: A text value with defined decimal separator.

Example:#SET APL:BUV1 = 1.23@A = DDE_REAL(APL:BUV1,",")

;Result: %A = 1,23

8.15 ODBC Functions

The ODBC functions provide means for accessing databases and applications thatsupport SQL (Structured Query Language), e.g. databases built with Microsoft Ac-cess, Paradox and Oracle. MicroSCADA uses the database interface Microsoft ODBC(Open Database Connectivity) and SQL statements.

Access to databases requires that an ODBC driver for the database management sys-tem in question has been installed and configured in the MicroSCADA computerwhere the ODBC functions are executed (the base system computer or an MMC com-puter). For more information, see the ODBC documentation.

To be able to use the ODBC functions, the programmer should be familiar with SQLstatements. Refer to suitable SQL manuals and books.

The ODBC functions may return the following seven status codes, which can be usedas such in SCIL expressions because they are defined as predefined integers:

0 SQL_SUCCESS1 SQL_SUCCESS_WITH_INFO-1 SQL_ERROR100 SQL_NO_DATA_FOUND2 SQL_STILL_EXECUTING99 SQL_NEED_DATA2001 SQL_UNSUPPORTED_DATATYPE



1MRS751250-MEN

ABB Automation214

In certain cases, also an error code may be returned (for status codes SQL_ERRORand SQL_SUCCESS_WITH_INFO). The error codes are the ODBC error codes listedin appendix B.

SQL_CONNECT(source, user, password )

Opens an ODBC connection to a data source.

The data source may be situated in the same computer or in another computer on thenetwork. The connection gets an identification number which is used in the subse-quent ODBC functions.

The ODBC connections are SCIL context specific. This means that when the context,e.g. the picture or command procedure, is exited, the connections are automaticallyclosed.

Up to 10 ODBC connections may be open simultaneously.

’source’ Text. The data source name as defined by the ODBC administra-tion tool.

’user’ Text. A text string containing the user name that is to be usedwhen accessing the data source specified in ’source’. An emptystring if no user name needed.

’password’ Text. A text string containing the password for ’user’ when ac-cessing the data source specified in ’source’. An empty string if nopassword needed.

Value: A list containing the following three attributes:

STATUS = A predefined integer (see above). Thevalue indicates whether the function wassuccessfully executed or not.

CONNECTION_ID = Integer, 1...10. The identification numberof the connection. If the operation didnot succeed, i.e., STATUS is neitherSQL_SUCCESS norSQL_SUCCESS_WITH_INFO,CONNECTION_ID is undefined.

ERROR_CODE = Text. A five characters long ODBC-errorcode. If STATUS is anything else thanSQL_ERROR orSQL_SUCCESS_WITH_INFO,ERROR_CODE is undefined.

Example:

Opening the connection to a data source named ACCESS:

@RESULT = SQL_CONNECT("ACCESS", "MICRO", "SCADA")#IF RESULT:VSTATUS == SQL_SUCCESS OR-



ABB Automation 215

RESULT:VSTATUS == SQL_SUCCESS_WITH_INFO #THEN #BLOCK@CONN = RESULT:VCONNECTION_ID;Continue the database interaction.#BLOCK_END#ELSE #BLOCK;The connection was not successful.#BLOCK_END

SQL_DISCONNECT(connection_id)

Closes the ODBC connection defined by the argument.

If SQL_BEGIN_TRANSACTION has been issued, SQL_COMMIT is run automati-cally before the connection is closed (see below). All statements associated with theconnection are freed.

’connection_id’ Integer 1 ... 10. The connection identification of the connectionthat is to be disconnected.


STATUS = A predefined integer (see above). Avalue that indicates whether the functionwas successfully executed.


Example:

Closing the connection opened in the example above:

@RESULT = SQL_DISCONNECT(%CONN)#IF RESULT:VSTATUS <> SQL_SUCCESS AND-

RESULT:VSTATUS <> SQL_SUCCESS_WITH_INFO #THEN #BLOCK;The connection was not successfully disconnected.

#BLOCK_END

SQL_EXECUTE(connection_id, SQLstring)

Executes an SQL statement.

The function executes the SQL statement on the connection specified by the ‘connec-tion_id’ argument. It reserves a statement identification number which is used in apossible subsequent SQL_FETCH function. Each connection may have up to ten si-multaneous execute statements.

'connection_id' Integer 1 ... 10. The identification number of the connection onwhich the statement is to be executed.

'SQLstring' Text or textvector. The SQL statement that is to be executed. Formore information, see SQL manuals.




1MRS751250-MEN

ABB Automation216

STATUS = A predefined integer (see above). Avalue that indicates whether the functionwas successfully executed.

STATEMENT_ID = Integer, 1 ... 100. The identificationnumber of the statement. If STATUS issomething else than SQL_SUCCESS or

SQL_SUCCESS_WITH_INFO,STATEMENT_ID is undefined.


Example:

Deleting all records in the table “MYTABLE” where the value in the column “AGE”is equal to 18:

@SQLSTMT = "DELETE FROM MYTABLE WHERE AGE = 18"@RESULT = SQL_EXECUTE(%CONN, %SQLSTMT)#IF RESULT:VSTATUS == SQL_SUCCESS OR-RESULT:VSTATUS == SQL_SUCCESS_WITH_INFO -#THEN #BLOCK

@STMT = RESULT:VSTATEMENT_ID;Continue the database interaction.

#BLOCK_END#ELSE #BLOCK;The statement was not successfully executed.#BLOCK_END

See also the SQL_FETCH example below.

SQL_FETCH(statement_id)

Fetches a row of data from a result set obtained by SQL_EXECUTE.

The function has no meaning if SQL_EXECUTE not executed.

'statement_id' Integer 1 ... 10. The statement identification number returned bySQL_EXECUTE.


STATUS = A predefined integer (see above). A value thatindicates whether the function was successfullyexecuted.

DATA = A vector containing data fetched from a resulttable. If STATUS is neither SQL_SUCCESSnor SQL_SUCCESS_WITH_INFO, DATA isundefined.

ERROR_CODE = Text. A five characters long ODBC-error code.If STATUS is anything else than SQL_ERROR



ABB Automation 217

or SQL_SUCCESS_WITH_INFO,ERROR_CODE is undefined.

Example:

Reading names and addresses from a database:

@SQLSTMT = "SELECT NAME, ADDRESS FROM EMPLOYEE"@RESULT = SQL_EXECUTE(%CONN, %SQLSTMT)#IF RESULT:VSTATUS == SQL_SUCCESS OR-

RESULT:VSTATUS == SQL_SUCCESS_WITH_INFO -#THEN #BLOCK@STMT = RESULT:VSTATEMENT_ID#LOOP

@RESULT=SQL_FETCH(%STMT)#IF RESULT:VSTATUS == SQL_SUCCESS OR-RESULT:VSTATUS == SQL_SUCCESS_WITH_INFO -#THEN #BLOCK

...... ; FETCH succeeded#BLOCK_END#ELSE #LOOP_EXIT

#LOOP_END#BLOCK_END;RESULT:VDATA(1) and RESULT:VDATA(2) contain;the name and address respectively.

SQL_FREE_STATEMENT(statement_id)

Frees the specified statement and stops processing associated with the statement.

This function must be used if several calls to SQL_EXECUTE are issued on the sameconnection. All open statements associated with the connection will be freed auto-matically when a connection is closed.

’statement_id’ Integer, 1... 100. The statement identification returned fromSQL_EXECUTE.



ERROR_CODE = Text. A five characters long ODBC-error code.If STATUS is anything else than SQL_ERRORor SQL_SUCCESS_WITH_INFO,ERROR_CODE is undefined.

Example:@RESULT=SQL_FREE_STATEMENT(%STMT)#IF RESULT:VSTATUS <> SQL_SUCCESS AND-

RESULT:VSTATUS <> SQL_SUCCESS_WITH_INFO -#THEN #BLOCK;The statement was not successfully freed.

#BLOCK_END

SQL_BEGIN_TRANSACTION(connection_id)

Marks the beginning of a transaction.



1MRS751250-MEN

ABB Automation218

The transaction will be completed when SQL_COMMIT or SQL_ROLLBACK is en-countered (see below). Disconnecting the connection will also commit the transaction.

’connection_id’ Integer, 1 ... 10. The identification of the connection on which thetransaction is to be executed.




Example:@RESULT = SQL_BEGIN_TRANSACTION(%CONN)#IF RESULT:VSTATUS == SQL_SUCCESS OR- RESULT:VSTATUS == SQL_SUCCESS_WITH_INFO - #THEN #BLOCK

@SQLSTMT = "DELETE FROM MYTABLE WHERE AGE = 18"@RESULT1 = SQL_EXECUTE(%CONN, %SQLSTMT)@SQLSTMT = "UPDATE MYTABLE SET AGE = 18 WHERE AGE = 17"@RESULT2 = SQL_EXECUTE(%CONN, %SQLSTMT)#IF (RESULT1:VSTATUS == SQL_SUCCESS OR- RESULT1:VSTATUS == SQL_SUCCESS_WITH_INFO) AND- (RESULT2:VSTATUS == SQL_SUCCESS OR- RESULT2:VSTATUS == SQL_SUCCESS_WITH_INFO) - #THEN #BLOCK

@RESULT = SQL_COMMIT(%CONN)#IF RESULT:VSTATUS <> SQL_SUCCESS AND-

RESULT:VSTATUS <> SQL_SUCCESS_WITH_INFO - #THEN #BLOCK;The commit was not successful

#BLOCK_END#BLOCK_END#ELSE #BLOCK

@RESULT = SQL_ROLLBACK(%CONN)#IF RESULT:VSTATUS <> SQL_SUCCESS AND-

RESULT:VSTATUS <> SQL_SUCCESS_WITH_INFO -#THEN #BLOCK;The rollback was not successful

#BLOCK_END#BLOCK_END

#BLOCK_END#ELSE #BLOCK

;The transaction could not be started.#BLOCK_END

SQL_COMMIT(connection_id)

Commits a transaction the start of which was marked with SQL_BEGIN_TRANS.

’connection_id’ Integer, 1 ... 10. The identification number of the connection onwhich a transaction is to be committed.





ABB Automation 219


Example:

See the example related to the SQL_BEGIN_TRANSACTION function above.

SQL_ROLLBACK(connection_id)

Rolls back a transaction started with SQL_BEGIN_TRANS.

’connection_id’ Integer, 1 ... 10. The connection identification of the connection onwhich a transaction is to be rolled back.



ERROR_CODE = Text. A five characters long ODBC-error code.If STATUS is different from SQL_ERROR andSQL_SUCCESS_WITH_INFO,ERROR_CODE is undefined.

Example:

See the example related to the SQL_BEGIN_TRANSACTION function above.

8.16 RTU Functions

The following functions apply only to S.P.I.D.E.R. RTUs.

RTU_ADDR(key)

Returns a list with the address of the object in a certain record .

’key’ Text of three characters. The search key of the record.

Value: A list with the following attributes:

TP Integer, 0...11. The type of the RTU200 object(see below).

BA Integer. The block address in RTU200.

The TP attribute contains the four most significant bits and the BA attribute the 12least significant bits of the object address (OA).



1MRS751250-MEN

ABB Automation220

The TP attribute has the following meanings:

0 = No object type

1 = Object command

2 = Regulation command

3 = Digital set-point

4 = Analog set-point

5 = General persistent output

6 = Analog value

7 = Indication (single or double)

8 = Pulse counter

9 = Digital value

10 = Indication event recording (indication with time stamp)

11 = Analog event recording

Example:RTU = RTU_ADDR(RTU_KEY(X:POA1));Now;RTU:VTP = = 5;RTU:VBA = = 201

RTU_AINT(i)

Converts an integer to ASCII characters (according to the RP570 protocol).

’i’ An integer number.

Value: A text of two characters.

Example:RTU_HEXASC(RTU_AINT(342));returns "0156"

RTU_AREAL(r)

Converts a real number to four ASCII characters (float DS801).

’r’ A real number.

Value: A text of four ASCII characters.



ABB Automation 221

Example:RTU_HEXASC (RTU_AREAL(5.5));returns "40B00000"

RTU_ATIME[(t,[msec])]

Converts time data (operating system time) to ASCII (RTU200 time).

’t’ Time data. Default: the present time.

’msec’ The milliseconds of the time. Default = 0.

Value: A text of 6 ASCII characters.

Example:RTU_HEXASC (RTU_ATIME (OBJ:PRT));returns "0EC5226ED990"

RTU_BIN(h)

Converts HEX-ASCII numbers given as a text to binary numbers in text form.

’h’ A text or a text vector of HEX-ASCII numbers.

Value: Text or text vector. The texts represent binary numbers.

Example:RTU_BIN("414243");returns "ABC"

RTU_HEXASC(b)

Converts binary numbers given as a text to hex-ascii numbers as a text.

’b’ A text or text vector representing 8 bit binary numbers.

Value: A text of hex-ascii numbers.

Example:RTU_HEXASC("ABC");returns "414243"

RTU_INT(a)

Converts two ASCII characters (2’s complement RP570) to an integer.

’a’ A text of two ASCII characters.

Value: Integer.

Example:RTU_INT(RTU_BIN("0156"))



1MRS751250-MEN

ABB Automation222

;returns 342

RTU_KEY(oa)

Returns the search key for a record in an RTU200 configuration file.

The process object corresponding to the record must be known.

’oa’ Integer. The object address, the OA attribute, of the process objectstored in the record.

Value: A text of three characters. The search key for the record.

Example:@UN = X:PUN1#OPEN_FILE 1 0 "RTU’UN’.CFG" KL#READ 1 RTU_KEY(X:POA1) RECORD;%RECORD contains the configuration record associated with the object X:P1.

RTU_MSEC(atime)

Returns the milliseconds of the 6-byte RTU time string atime.

’atime’ Text. The RTU time.

Value: Integer. The number of milliseconds.

RTU_OA(type,ba)

Returns the object address.

’type’ Integer, 0 ... 11. The type of the object (see the TP attribute in theRTU_ADDR description above).

’ba’ Integer. The address (block address) of the object in RTU200, seethe BA attribute in the RTU_ADDR description above.

Value: Integer. The object address, the attribute OA of the process object.

Example:RTU_OA(5,201);returns 20681

RTU_REAL(a)

Converts 4 ASCII characters (float DS801) to a real number.

’a’ A text of four ASCII characters.

Value: A real number.

Example:RTU_REAL(RTU_BIN("40B00000"))



ABB Automation 223

;returns 5.5

RTU_TIME(a)

Converts ASCII (RTU200 time) to MicroSCADA time data.

’a’ A text of 6 ASCII characters.

Value: Time data.

8.17 Printout Functions

PRINT_TRANSPARENT ( data [, log] )

Sends printout to a printer.

The function sends printout (data, printer commands and control codes) directly toprinters defined as "transparent" and writes data to the printer log file. The functionenables full printer control and allows the printout of freely formatted texts andgraphics.

When called in a printed picture (printout activated by the #PRINT or #LIST com-mand or by an event in the process database), the function spools the output (printercommands, control codes and data) to the printer, where it is formatted (see Figure11).

The function should be placed in the start program of all pictures used for printout on"transparent" printers. If the printed picture contains picture functions, the start pro-grams are executed in the following order: the start program of the main picture, thestart program of the base function, the start programs of the picture functions in theinstallation order. Used in other environments than printed pictures (pictures shownon screen, command procedures), the function causes an error message(SCIL_UNKNOWN_FUNCTION).



1MRS751250-MEN

ABB Automation224

Figure 11. SCIL defined or “transparent” printout



ABB Automation 225

The target printer(s) of the printout are defined by the initiating #PRINT or #LISTcommand or the LD attribute of the process object. If there is no "transparent" printeramong the target printers, the function has no effect. Printers defined as "transparent"can only handle printout defined by this function.

Unlike the semi-graphic picture based printout, the printout produced with thePRINT_TRANSPARENT function does not automatically include any MicroSCADApicture elements, only the texts, graphics and formatting specified by the function.However, complete pictures and picture elements may be included as printout files.

The first argument of the function, ’data’, specifies the printout - i.e. the printed data,formatting and print processing. The second (optional) argument, ’log’, specifies theoutput to the log file. The function returns the status of the printer spool operation.

’data’ Vector. The printout vector. 0 = no printout.

The printout vector is an ordinary SCIL vector containing text, in-teger and vector type elements. It may contain the following ele-ments:

- The data to be sent to the printer. This is specified by textsand text vectors given as constants or SCIL expressions.The texts may be encoded in any symbol set supported bythe printer. The SCIL expressions must be marked by theprintout processing command -5 as the preceding element(see below). They are evaluated at the moment of physicalprinting, and the result is sent to the printer. Expressionscan be used, e.g. to print the actual printout time of a re-port. The text elements may also comprise printer controlsequences for producing graphics. However, this is gener-ally not recommended, because they would make the printvector printer interface dependent and the print processorwould not be able to keep track of output pages. Instead,printer control sequences can be defined in the CS attributeand included in the print vector as printer control com-mands. Files (e.g. window dump files transferred to print-out files) may be included using the READ_TEXT func-tion.

- Printer control commands. The printer control commandsare logical commands that control the printer. They arerepresented as positive integers defined by the printer spe-cific CS attribute of the printer object (see the System Ob-jects manual, Chapter 10). There is a tool for defining theprinter control commands.

- Print processor commands. The print processor commandscontrol the processing of the print vector itself. They aregiven as negative integers. The following print processorcommands are available:

-1 Auto-NL on Automatic new line feature on (default)-2 Auto-NL off Automatic new line feature off-3 Increment LN Increment line number attribute LN-4 Increment PN Increment page number attribute PN



1MRS751250-MEN

ABB Automation226

-5 Formula follows The next element in the vector will beinterpreted as a SCIL expressioninstead of plain text

The automatic new line feature (on by default) means that a newline command (printer control command 1, see above) is automati-cally appended to each text element in the print vector.

The increment LN and increment PN commands may be used toinform the print processor that a new line or new page is startedusing printer control commands that are not predefined (see the CSattribute).

’log’ Vector. The contents of the vector is in full transferred to the logfile (provided that the printer has been defined with printer logoutput in the base system configuration). SCIL expressions areevaluated before the transfer. 0 = no log file output.

Value: Integer. The status code generated by the print spool operation. 0 =OK or no "transparent" printer among the target printers.

Example:@S_H=SCIL_HOST@OX = ‘LN’:POX’IX’@CX = ‘LN’:PCX’IX’#IF S_H:VNAME == "PRIN" #THEN #BLOCK @S=PRINT_TRANSPARENT((-2,TIMES,"OBJECT TEXT:",%OX,- "COMMENT TEXT:",%CX," OBJECT VALUE:",-1,DEC(%OV)))#BLOCK_END

This program block checks whether the picture is being printed or shown on screen. Ifit is printed, the PRINT_TRANSPARENT function prints a row starting with the pre-sent time, and ending with the object value given as a text. After the object valuestarts a new line.

PRINTER_SET

Returns the target printer numbers.

The function returns the logical target printer numbers (as known to the applicationthrough printer mapping) of the printed picture (printout started with the #PRINTcommand or a process database event). By means of this function, the SCIL programmay examine the numbers and types of target printers.

Called somewhere else than in a printed picture, the function has no meaning.

The target printers can be examined by means of the PRINTER_SET function (seebelow). By reading the SCIL_HOST function, the SCIL program can concludewhether the picture is being printed or displayed on screen.



ABB Automation 227

Value: A vector of integer elements. The integer elements are the logicalprinter numbers (as known to the application through the printermapping).

8.18 Error Tracing Functions

The functions in this section are used for debugging SCIL programs. Tracing meansrecording of the SCIL statements that are executed. The tracing is started by theTRACE_BEGIN function and stopped by TRACE_END. If TRACE_BEGIN is calledwhile tracing is already on, the second call is ignored but counted: twoTRACE_ENDs are needed to stop tracing. When applied in a picture, tracing recordsall the programs executed within the picture.

The statements that contain variable expansions (’macros’), are recorded in their ex-panded form. Each line is preceded by the depth of the control structure hierarchy tohelp find matching BLOCKs and BLOCK_ENDs etc.

TRACE_BEGIN( filename [, append ] [,time_tags])

Starts error tracing.

‘filename’ Text value. The name of the file where the trace output is written.

‘append’ Text value "APPEND". If given, the trace output is appended tothe file if it already exists.

‘time_tags’ Text value "TIME_TAGS". Switches on time tags which are timestamps on every line in the tracefile.

Value: Integer value. The status of file creation ( 0 = successful ).

TRACE_END

Stops error tracing.

Value: Integer value. The status of closing the trace file ( 0 = successful).

TRACE_PAUSE

Pauses trace logging.

Value: Integer value. The status the operation ( 0 = successful).

TRACE_RESUME

Resumes trace logging.

Value: Integer value. The status of the operation ( 0 = successful).



1MRS751250-MEN

ABB Automation228

8.19 Data Type Handling Functions

DATA_TYPE(expression)

Returns the data type of the argument.

The function can, e.g. be used for testing the correctness of an expression.

’expression’ An expression of any data type.

Value: Text. The data type of the expression:INTEGERREALBOOLEANTEXTTIMEBIT_STRINGBYTE_STRINGVECTORLISTNONE (= the expression is wrong or undefined)

Example:DATA_TYPE(CLOCK) == "TIME"#IF DATA_TYPE(DATA:DOV) == "NONE" #THEN .......

PACK_STR ( source , type [, length [, byte_order]] )

Converts text vector to text or integer vector to bit or byte string.

The function converts the ‘source’ vector to the data type given by ‘type’.

'source' A vector containing integer and text elements.

'type' Text. The data type of the result: "TEXT", "BIT_STRING" or“BYTE_STRING”.

'length' An integer value, 1, 2, 4, 8, 16 or 32.

If 'type' = "BIT_STRING", this is the number of bits in each ele-ment of the source vector.

If type = "TEXT", 'length' is ignored.

If ‘type’ = “BYTE_STRING” , the 'length' argument specifies howmany bytes are initialized by each element of the vector. Thelength may be 1, 2 or 4. For example, if the length is 2, each ele-ment of the vector is taken as a 2-byte integer and then appendedto the resulting byte string (The two high order bytes of the ele-ment are ignored).



ABB Automation 229

Default = 1.

‘byte_order’ Text: "BIG_ENDIAN" and "LITTLE_ENDIAN". This argument isrelevant only when ‘type’ is “BYTE_STRING”. The 'byte_order'argument may be used to create byte strings for an applicationrunning in a computer of a different architecture. In a little endianarchitecture (e.g. Intel, Alpha), integers are stored with the leastsignificant byte first. In a big endian architecture (e.g. Motorola),integers are stored with the most significant byte first. This argu-ment should be used only if the resulting byte string is going to beexported into a foreign system requiring a specific byte ordering. Ifomitted, the byte string is created with the byte ordering of the un-derlying architecture.

Value: Text, bit string or byte string depending on the 'type' argument.

Examples: PACK_STR(("A","B","CD"),"TEXT") == "ABCD"PACK_STR((0,1,0),"BIT_STRING") == BIT_SCAN("010")PACK_STR((0,3,1),"BIT_STRING",2) == BIT_SCAN("001110")

UNPACK_STR ( source [, length [, byte_order]])

Converts texts, bit strings and byte strings to vectors of integer or text elements.

UNPACK_STR creates an integer or text vector out of the ‘source’ argument. When‘source’ is a byte string, it is interpreted as an array of integers of 'length' bytes. Byusing function UNPACK_STR, a byte string can be interpreted as an array of numeri-cal values.

’source’ Text, bit string or byte string.

’length’ Integer. The length of the elements in the result vector.

If 'source' is a bit string, ‘length’ is the number of bits in each bitstring. The following values are allowed: 1, 2, 4, 8, 16, 32.

If ‘source’ is a byte string, ‘length’ is the number of bytes in thebyte strings. The values 1, 2 and 4 are allowed. ‘length’ may alsobe negative (-1, -2 or -4), in which case the integers in the bytestring are taken as signed, otherwise they are taken as unsigned.

Default = 1.

‘byte_order’ Text. The 'byte_order' argument specifies the byte ordering of thebyte string (see PACK_STR above). It should only be used if thebyte string has been imported from a foreign system. If omitted,the bytes string is supposed to have the byte ordering of the un-derlying architecture.

Value: Vector of text ('source' = a text) or integer ('source' = a bit string orbyte string) elements. If a bit string contains a number of bits thatis not evenly divisible with 'length', the excess bits are ignored.



1MRS751250-MEN

ABB Automation230

Examples:UNPACK_STR("ABC") == ("A","B","C")UNPACK_STR("ABCDE",2) == ("AB","CD","E")UNPACK_STR(BIT_SCAN("0111")) == (0,1,1,1)UNPACK_STR(BIT_SCAN("011011"),2) == (2,1,3)UNPACK_STR(BIT_SCAN("0110111"),2) == (2,1,3)

TYPE_CAST(source, type )

Converts data from one data type to another.

This function converts data from one data type to another as follows:

• Data of data type INTEGER, REAL, TIME or BOOLEAN to a selected data typewhich may be INTEGER, REAL, TIME or BOOLEAN.

• Data of data type TEXT, BIT_STRING or BYTE_STRING to a selected datatype which may be TEXT, BIT_STRING or BYTE_STRING.

’source’ The source expression to be converted to another data type. Inte-ger, real, time, boolean, text or bit string.

’type’ Text expression specifying the result data type. If ’source’ is inte-ger, real, time or boolean, ’type’ may have any of the followingvalues:

"INTEGER","REAL","TIME","BOOLEAN"

If ’source’ is a text or bit string, ’type’ may have the following val-ues:

"TEXT","BIT_STRING", “BYTE_STRING”

Value: The value of 'type' represented in the data type specified by'source'. The function returns the bit pattern of the representationof 'source' interpreted as data type 'type'. Note that type castingfrom and to real data is hardware dependent and may result in in-valid floating point numbers. Type-casting from text to bit stringreturns the bit pattern of the text as a bit string, the length of whichis 8 times the length of the text (one character occupies 8 bits).Type-casting from bit string to text returns a text the length ofwhich is 1/8 of the bit string.

Example:

TYPE_CAST(TRUE,"INTEGER") returns the integer value 1, which is the integerrepresentation of the boolean value TRUE.



ABB Automation 231

8.20 Miscellaneous Functions

ADD_INTERLOCKED( object , index , amount )

Implicitly modifies the UV or SV attribute of a SYS or an APL object.

ADD_INTERLOCKED supports synchronization of SCIL programs executing in par-allel.

’object’ Text value, either "SYS" or "APL".Specifies the base system object. Note that application numbermay not be given, the current application is always assumed.

’index’ Integer or vector value.If an integer, specifies the index of the UV attribute to be modi-fied.If a vector, specifies both the attribute and the index:

First element is a text value, either "UV" or "SV"

Second element is an integer value specifying the index

’amount’ Integer value to be added into the element of the UV or SV attrib-ute.

Value: Integer value, the result of the addition.

Example:#LOOP ADD_INTERLOCKED("SYS",77,1) <> 1 ;Try to reserve the resource

@DUMMY = ADD_INTERLOCKED("SYS",77,-1) ;Didn’t get it#PAUSE 0.5 ;Wait a while

#LOOP_END ;and try again; The resource is now reserved for exclusive use

@DUMMY = ADD_INTERLOCKED("SYS",77,-1) ;Release the resource

A system wide (inter-application) binary semaphore may be implemented by thisSCIL code. SYS:BUV77 is used as the semaphore. It is supposed to been set to zeroin SYS_BASCON.COM. For clarity, the code to handle a deadlock situation is omit-ted. In a real application, it is needed to avoid too long waits and/or SCIL error mes-sages. Note that the value returned by 2nd and 3rd call of the function is not usedanywhere, it is known to be zero (unless there is a SCIL design error somewhere elsein the system).

AUDIO_ALARM (alarm_class, on_or_off)

Sets or resets the specified audio alarm(s).

‘alarm_class’ Integer value 1 … 7 or text keyword “ALL”

‘on_or_off’ Text keyword value “ON” or “OFF”



1MRS751250-MEN

ABB Automation232

Value: Integer, returns the status code of the operation,(0=OK_STATUS).

CONSOLE_OUTPUT(text)

Writes a message to the MicroSCADA Notify windows.

‘text’ Text. The message to be written to the MicroSCADA Notify win-dows.

Value: The status code of the operation. 0 = OK.

It is not recommended to use control characters (for example CR or LF) in text sent tothe MicroSCADA notification window. If control characters are used, the behaviouris undefined.

DUMP(data)

Transforms the value of an expression into text format.

‘data’ An expression of any data type.

Value: Text vector representing the contents of data in SCIL expressionsyntax. The status code of each data item (unless 0) is alsodumped.

ENVIRONMENT(variable)

Retrieves the value of the specified variable from the environment block of the callingprocess.

'variable' A text string specifying the name of the environment variable.

Value: A text specifying the value of the environment variable. The valueis an empty text string if the environment variable with the speci-fied name is not existing.

Example:@t_env = ENVIRONMENT("OS");returns the text "Windows_Nt"

EVALUATE ( expression )

Evaluates an expression given in text format.

‘expression’ A text or text vector value containing the SCIL expression to beevaluated. If a text vector is given, other lines but the last one mustend with a continuation character ( - ).



ABB Automation 233

Return value: The result of the evaluation, which may be of any data type.

Example:

The following examples shows how to store any data value (such as complicated list)in a disk file and then read it back:

@WRITE_STATUS = WRITE_TEXT("DUMP.TXT",DUMP(%V))#IF WRITE_STATUS == 0 #THEN -

@W = EVALUATE(READ_TEXT("DUMP.TXT"))

GET_STATUS(expression)

Returns the status code(s) of an expression.

’expression’ An expression of any data type. Typically, ’expression’ is a vari-able reference (e.g. %V, %V(5), LISTVAR:VAT ).

Value: If ’expression’ is of a simple data type (integer, real, text, time, orboolean), the function returns an integer value. If it is a vector, thefunction returns an integer vector containing the status codes ofeach element of the argument vector. If it is a list, the function re-turns a list with the same attribute names, each attribute containingthe status code of the corresponding argument attribute.

LENGTH(arg)

Returns the "length" of the argument.

’arg’ Any data type.

Value: Integer. According to the data type of the argument, the followingis returned:

Integer 1

Real 1

For any value v, EVALUATE ( DUMP ( v ) ) results to v, except for one case:Real numbers may slightly lose their precision.

When the GET_STATUS function is used in the condition of the SELECT func-tion (see section 8.6.), elements with status codes larger than 10 are not regarded.



1MRS751250-MEN

ABB Automation234

Boolean 1

Time 1

Text the number of characters in the text.

Bit string the number of bits in the string

Byte string the length of the byte string

Vector the number of elements in the vector.

List the number of attributes in the list.

Examples:LENGTH(340) = =1LENGTH("ABCD") = =4LENGTH(PROD_QUERY(20)) = =18LENGTH(" ") = =1LENGTH("") = =0

LIST(attribute=expression, attribute=expression, ...)

Forms a list of attributes and attribute values.

The argument list can contain up to 10000 attribute assignments.

’attribute’ A freely chosen attribute name of up to 63 characters.

’expression’ An expression of any data type. The value assigned to the ‘attrib-ute’.

Value: A list of the given attributes and attribute values.

Example:@l_new_list=LIST(NUMBER = (1, 2 ,3), NAME = (“A”, “B”, “C”))

List is actually not a function, because it does not have expressions as its arguments.

LIST_ATTR(list)

The function returns a vector of all attributes contained in a list.

’list’ A list type expression.

Value: A vector with text elements composed of the attribute names in’list’.

Example:@X = LIST(AA=1,BB=2,CM="TEST");Now;LIST_ATTR(%X) == ("AA","BB","CM")



ABB Automation 235

MEMORY_POOL_USAGE(pool)

Monitor the usage of memory pools.

’pool’ Text keyword value telling the pool to get information from:

"LOCAL" Local pool of the process.

"GLOBAL" Global memory pool.

"PROCESS" The pool used by the process.

Value: List value with following attributes

SIZE Size of the pool as megabytes.

USED Bytes used.

FREE Bytes free.

BLOCK_SIZES Vector of allocation block sizes used by thepool (only if SIZE > 0).

USED_BLOCKS Vector counting allocations of each block size(only if SIZE > 0).

FREE_BLOCKS Vector counting free blocks of each size (onlyif SIZE > 0).

POOL Text value, "LOCAL" or "GLOBAL" (only if’pool’ is "PROCESS").

MEMORY_USAGE ( keyword, arg )

This function helps debugging and analyzing SCIL applications. It returns the amountof memory pool (as bytes) allocated for the expression, or for the variable (includingthe bookkeeping data and the value of the variable).

keyword Text keyword argument, either "EXPRESSION" or "VARIABLE"

If keyword = "EXPRESSION":arg: Any valid SCIL expression.

If keyword = "VARIABLE":arg: Text expression, the name of the variable.

Returns Integer value, the amount of memory pool allocated for the expres-sion or the variable.



1MRS751250-MEN

ABB Automation236

Examples:

(Memory usage in current implementation of SCIL, may change in future releases.)

MEMORY_USAGE ("EXPRESSION","ABC")returns 8

MEMORY_USAGE ("EXPRESSION",1)returns 0, since integer values are not allocated from the pool

@X = "ABC"MEMORY_USAGE("VARIABLE","X")returns 136

RANDOM ( n1 , n2 )

Generates a random number in a given range.

‘n1’ An integer or real value.

‘n2’ An integer or real value.

Value: Integer or real value.

If ‘n1’ and ‘n2’ are integer values, an integer value in the range n1 ... n2 (including n1and n2) is returned. If n1 and n2 are real values, a real value in the range [ n1 , n2 ) ,i.e. including n1 but excluding n2, is returned.

SHUFFLE ( n )

Arranges specified integer numbers in a random order and returns them as a vector.

This function shuffles the integer numbers 1 to ‘n’ into a random order and returnsthem in an integer vector. Each number 1 to n appears in the vector once and onlyonce.

‘n’ Integer value in range 0 .. max. vector length ( = 10000 ).

Value: Integer vector of length ‘n’.

Example:

To rearrange any vector V to a random order:

@SHUFFLED = PICK(%V,SHUFFLE(LENGTH(%V)))

REVISION_COMPATIBILITY ( issue { , enable })

Selects the compatibility issues to be used in the context.

The compatibility with the old revision is enabled/disabled by compatibility issues.The REVISION_COMPATIBILITY function overrides temporarily (in the picture,command procedure or dialog system) the revision compatibility, or a part of it, de-fined in the APL:BRC attribute.



ABB Automation 237

‘issue’ Text. The name of the compatibility issue. See the description ofthe APL:BRC attribute in the System Objects manual.

‘enable’ An optional boolean argument. TRUE = compatibility is enabled.FALSE = compatibility is disabled. If this argument is not given,the function only reads the compatibility state without modifyingit.

Value: Boolean value indicating the compatibility before it was changedwith the function.

Example:@RC = REVISION_COMPATIBILITY ("FILE_FUNCTIONS_CREATE_DIRECTORIES", FALSE); WRITE_TEXT function used here@RC = REVISION_COMPATIBILITY ("FILE_FUNCTIONS_CREATE_DIRECTORIES", %RC)

The first variable assignment disables the compatilibity issueFILE_FUNCTIONS_CREATE_DIRECTORIES, which means that theWRITE_TEXT function does not create new directories. The second variable assign-ment resets the compatibility issue to the value it had before (enabled or disabled).

SCALE(v, scale_object [, direction ])

Scaling of a real value with a scale object.

'v' Real value, the value to be scaled.

'scale_object' Text value, the name of the scale object to do the scaling.

'direction' Text value, either "INPUT" or "OUTPUT". Defaults to "INPUT".

Value: Real value, the scaled value.

The direction "INPUT" corresponds to the scaling of analog input process objects, di-rection "OUTPUT" corresponds to the scaling of analog output process objects.

Example:@r_invalue=SCALE(100,"TEST_SCALE","INPUT")@r_outvalue =SCALE(0.1,"TEST_SCALE","OUTPUT")

SCIL_HOST

Returns the name and number of the kernel process that executes the current SCILcode.

For example, by reading this function, the start program of a picture, can find outwhether the picture is being displayed on a monitor or printed.

Value: A list containing two attributes, NAME and NUMBER.

NAME is the process name as a text string. The possible values are:



1MRS751250-MEN

ABB Automation238

- "MAIN" The main process

- "PICO" A monitor process

- "REPR" A report process

- "PRIN" A printer spooler process processing a format picture

- "PRNC" A printer process processing a page header

- "PICL" A picture documentation process

- "EXTERNAL" An external program running the SCIL interpreter

NUMBER is the process number as an integer. For theMAIN process and EXTERNAL processes,the value is 0. For a PICO and PICL process,this is the base system monitor object number.For a REPR process, the number is coded as

100 x apl + nwhere ’apl’ is the systemapplication number and

’n’ = 1 for the time channelqueue,

’n’ = 2 for the event channelqueue and

’n’ = 2 + p for parallelqueue ’p’.

For a PRIN process, the number is coded as

100 x apl + nwhere ’apl’ is the systemapplication number and ’n’= 1 for process printoutsand 2 for report printouts.

Example:

See the example of the PRINT_TRANSPARENT function.

SET_STATUS(expression,status)

Writes the status codes of an expression.

’expression’ An expression of any data type. The expression will be assignedthe status code(s) specified by the ’status’.



ABB Automation 239

’status’ An integer expression, 0 ... 65535, or a vector of integer expres-sions. The status codes. If ’expression’ is a simple data type, ’status’must be an integer.

Value: The ’expression’ argument with the assigned status code .

The function returns the ’expression’ argument modified by the ’status’ argument asfollows:

• If ’expression’ is of a simple data type, ’status’ must be an integer value, whichbecomes the status of ’expression’.

• If 'expression' is a vector, 'status' may be an integer or vector value. If ‘status’ isan integer, the status of each element of 'expression' is set to 'status'. If ‘status’ isa vector, the status of n:th element of 'expression' is set to the n:th element of'status'. If the vector 'status' is shorter than the vector 'expression', the 'expression'is modified only up to the length of 'status'. If 'status' is longer than 'expression',the extra elements are ignored.

• If 'expression' is a list, 'status' may be an integer or list value. If ‘expression’ is aninteger, the status of each attribute of 'expression' is set to 'status'. If ‘expression’is a list, the status of 'expression' attribute NN is set to the value of 'status' attrib-ute NN. The attributes of 'status' that do not exist in 'expression' are ignored. Theattributes of 'expression' that do not exist in 'status' are unaffected.

If a value in 'expression' has a status code >= 10, and it is assigned a status code <10,the value is initialized to integer zero.

Examples:@V = SET_STATUS(%A,2);Status code 2, OBSOLETE_STATUS, is set to the variable A.

@V = SET_STATUS(%A,GET_STATUS(%B));The status of the variable A is copied from the variable B.

TRANSLATE(text [,language])

Translates texts defined in Visual SCIL objects.

‘text’ A text. A reference to a text identified defined in the dialog editor.The reference starts with an @.

‘language’ A text. Language identifier as defined in the ISO standard 639. De-fault: the language defined by the base system configuration, bythe MON:BLA attribute.

The function can only be used in user interface objects (pictures and Visual SCILobjects). The function searches for the text reference and language in the dialog ordialog item where the function is encountered. If either the text reference or the lan-guage is not found there, the reference is searched for in the parent object, and so on,up to the object that was loaded with SCIL.



1MRS751250-MEN

ABB Automation240

The ‘language’ argument is used only if you wish to override the language selected inthe base system configuration. If no ‘language’ argument is given, the language is theone defined by the MON:BLA attribute. If no MON:BLA attribute has been defined,the language is the one set by the APLn:BLA attribute, and if no such attribute hasbeen defined, the language is English.

Value: Text data. The translated text. If there is no initial @ character in‘text’, no translation is done, but the text is returned as such. Ifthere are two initial @ characters, one of the @ characters is re-moved from the resulting text, but no translation takes place.


MicroSCADA9 Graphics Primitives

ABB Automation 241

9 Graphics Primitives

This chapter describes the use of the graphics primitives, which constitute the base ofall full graphics elements in MicroSCADA pictures, partly also in dialogs. The firstsection introduces some concepts related to the graphics primitives.

9.1 Introduction

MicroSCADA full graphics in pictures, partly also in dialogs, are realized using SCILgraphics commands. There are SCIL commands for drawing various types of graphi-cal elements, such as points, lines, polylines and polygons, arcs, circles, ellipses,boxes (rectangles), and texts. The SCIL graphics commands specify the geometry ofthe graphical elements, while the location and size, as well as other features, are givenas arguments.

The graphics commands can be included in any MicroSCADA picture program (seesection 2.1.) and in the methods of the dialogs and dialog items. TheBACKGROUND program of a picture contains the graphics commands generated bythe picture editor. As a rule, this program should not be edited manually. Context de-pendent graphics in the background can be written in the DRAW program. Like pic-ture commands and Visual SCIL commands (Chapter 7), the graphics commands arenot allowed in command procedures, unless they are executed by #DO commands orDO functions situated in user interface objects. The graphics commands are describedin section 9.2.

Graphics Contexts

The features of the graphical elements - color, type of line, line width, font, etc. -are defined by graphics contexts, which are identified by integer numbers. A graphicscontext is a series of properties, called "components", such as the ones mentioned.Several commands can use the same graphics context, though all properties are notused by all graphics commands. The graphics contexts are described in section 9.3.

Graphics Canvas

The graphical elements are displayed in the user interface object (picture, picturefunction, dialog item) chosen as graphics "canvas". By default, the canvas is the pic-ture or Visual SCIL object where the graphical commands are situated.

Any picture and picture function can be chosen as graphics canvas. However, regard-ing the dialogs, only certain types of dialog items can contain graphics elements.These are the dialog items that allow the display of images (have the image attribute).

The location of a graphical element is given by x,y coordinates related to the homeposition of the canvas. The upper left corner of the picture or picture function wherethe element will be displayed. As the resolution of screens varies, the graphics com-mands use a screen independent coordinate system. The coordinate system can con-tain SCIL coordinates or VS coordinates. The SCIL coordinate system is fixed by ascaling factor. By means of an input command, the coordinates can be read from the



1MRS751250-MEN

ABB Automation242

mouse position. Refer to section 9.4. to learn about the SCIL and VS coordinates, andthe mouse input commands.

Miscellaneous

The context definitions, canvas selection and scaling can be temporarily stored andrestored within the same picture. See section 9.5.

The display of the graphics on screen can be controlled by some display handlingcommands (section 9.5.2).

9.2 Full Graphics SCIL Commands

9.2.1 Drawing Graphical Elements

The commands below draw graphical elements on screen, in the user interface objectselected for canvas (default = the same object as where the commands are situated).Coordinate system is different in pictures and in VS objects. The command.COORDINATE_SYSTEM is described in section 9.4.

The color and other features of the elements are fixed by the graphics contexts. Thegraphics contexts are described in section 9.3.

In most cases, several elements can be drawn with one command by giving vectors forcoordinates and sizes. If one coordinate or size is a scalar while the other one is avector, the scalar argument is handled as a vector with all elements equal, for example.POINT 0, (100,200) is equivalent to .POINT (0,0), (100,200). If the coordinates falloutside the canvas (that is they are negative or too large), they will still affect theshape of the graphical element. The part of the graphical element that falls outside thecanvas will not be displayed.

In the command syntax descriptions below, all arguments given in lower case letterscan be SCIL expressions of the data type required for the respective argument.

.ARC [[scope,]n :] x,y, r, a1,a2 [,FILL]

Draws one or several arcs as circle segment arcs.

’scope’ The scope of the context (see section 9.3.).

’n’ Graphics context number, 0 ... 20 or 0 ... 50 depending on thescope. Default = 0. Used components: FUNCTION,FOREGROUND, BACKGROUND, LINE_WIDTH,LINE_STYLE, CAP_STYLE, DASH_OFFSET, DASH_LIST,ARC_MODE. See section 9.3.

’x,y’ The coordinates of the center of the circle. Real, integer or vectorof real and integer elements.



ABB Automation 243

’r’ The radius of the circle given in coordinate units, see section 9.4.Real, integer or vector of real and integer elements.

’a1’ The angle from where the arc starts, given in degrees increasingcounter-clockwise from horizontal 0 value. Real, integer or vectorof real and integer elements. See Figure 12.

’a2’ The angle of the arc given in degrees. If a2 is positive, the arc isdrawn counter-clockwise. Otherwise, it is drawn clockwise. Real,Integer or vector of real and integer elements. See Figure 12.

If the FILL option is given, the arc is filled according to the ARC_MODE componentof the graphics context.

a1

(x,y)

a2 if positive

a2 if negative

Figure 12. Drawing an arc with the .ARC command

.BOX [[scope,]n :] x,y, width, height [,FILL]

Draws one or several boxes (rectangles).

’scope’ The scope of the context, see 9.3. below.

’n’ Graphics context number, integer 0 ... 20 or 0 ... 50 depending onthe scope. Default = 0. Used components: FUNCTION,FOREGROUND, BACKGROUND, LINE_WIDTH,LINE_STYLE, CAP_STYLE, JOIN_STYLE, DASH_OFFSET,DASH_LIST. See section 9.3.

‘x,y' Integer or real, or vector of integer or real data. The coordinates ofthe upper left corner of the rectangle.

'width' Integer or real or vector of integer or real data. The width of therectangle given in coordinate units, see section 9.4.



1MRS751250-MEN

ABB Automation244

’height’ Integer or real or vector of integer or real data. The height of therectangle given in coordinate units, see section 9.4.

If the FILL option is given, the box is filled (in the FOREGROUND color).

.CIRCLE [[scope,]n :] x,y, r [,FILL].

Draws one or several circles.

’scope’ is the scope of the context, see 9.3. below.

’n’ Graphics context number, integer 0 ... 20 or 0 ... 50 depending onthe scope. Default = 0. Used components: FUNCTION,FOREGROUND, BACKGROUND, LINE_WIDTH,LINE_STYLE, CAP_STYLE, DASH_OFFSET, DASH_LIST.See section 9.3.

’x,y’ Integer or real data, or integer or real vector. The coordinates forthe center of the circle.

’r’ Integer or real data, or integer or real vector. The radius given incoordinate units, see section 9.4 .

If the FILL option is given, the circle is filled.

.ELLIPSE [[scope,]n :] x,y, a,b [,FILL]

Draws one or more ellipses.


’n’ Graphics context number, 0 ... 20 or 0 ... 50 depending on thescope. Default = 0. Used components: FUNCTION,FOREGROUND, BACKGROUND, LINE_WIDTH,LINE_STYLE, CAP_STYLE, DASH_OFFSET, DASH_LIST

’x,y’ Integer or real data, or integer or real vectors. The coordinates ofthe center of the ellipse.

’a,b’ Integer or real data, or integer or real vectors. The axes of the el-lipse given in coordinate units, see section 9.4.

If the FILL option is given, the ellipse is filled.

.IMAGE x, y, w, h, filename, tag_1[, tag_2[, tag_3[, tag_4] ] ]

.IMAGE command draws a VS_IMAGE object into the current window or VS object.

’x’ Real, x coordinate



ABB Automation 245

’y’ Real, y coordinate

’w’ Real, width

’h’ Real, height

’filename’ Text, vso file name

’tag_n’

’tag_8_10’ Text, tag name within the vso file, image to be used when 8 x 10font is used.




The current coordinate system is SCIL, the coordinates x and y define the position ofthe upper left corner of the image, otherwise the lower left corner.

’w’ and ’h’ specify the size of the rectangle the image is drawn into, the image is scaledto fill the rectangle.

If ’w’ is 0, no horisontal scaling is done. If ’h’ is 0, no vertical scaling is done.

’filename’ specifies the VSO file where the image is stored.

At least one image must and up to 4 images may be specified in the command. Theone used in drawing depends on the size of the current MicroSCADA font. If no im-age is specified for the current font size, the image for the next smaller font is used. Ifthere is no image for smaller fonts, the image for the next larger font is used. When animage for a wrong font size is used, it is scaled in proportion to font sizes ( if ’w’and/or ’h’ is 0).

.IMAGE command is ignored in monitors of other type than VS.

.LINE [[scope,]n :] x1,y1, x2,y2

Draws one or more lines from (x1,y1) to (x2,y2).


’n’ Graphics context number, integer 0...20 or 0...50 depending on thescope. Default = 0 Used components: FUNCTION,FOREGROUND, BACKGROUND, LINE_WIDTH,LINE_STYLE, CAP_STYLE, DASH_OFFSET, DASH_LIST.See section 9.3.



1MRS751250-MEN

ABB Automation246

’x1,y1’ Integer or real, or vector of integer or real data. The coordinates ofthe start point. See section 9.4.

’x2,y2’ Integer or real, or vector of integer or real data. The coordinates ofthe end point. See section 9.4.

.POINT [[scope,]n :] x,y, [RELATIVE]

Draws one or several points of one pixel’s size at the coordinates (x,y). If any of x or yor both are vectors, and the option RELATIVE is given, the first point is taken ascanvas relative, the next one as relative to the previous one, etc.

’scope’ The scope of the context, see section 9.3 .

’n’ Graphics context number, integer 0 ... 20 or 0 ... 50 depending onthe scope. Default: 0. Used components: FUNCTION,FOREGROUND. See section 9.3.

’x,y’ Integer or real, or vector of integer or real data. coordinates for thepoint, see section 9.4.

.POLYLINE [[scope,]n :] x,y [,RELATIVE] [,FILL]

Draws a polyline or a polygon.

’scope’ is the scope of the context, see 9.3. below.

’n’ Graphics context number, integer 0 ... 20 or 0 ... 50 depending onthe scope. Default = 0. Used components: FUNCTION,FOREGROUND, BACKGROUND, LINE_WIDTH,LINE_STYLE, CAP_STYLE, JOIN_STYLE, DASH_OFFSET,DASH_LIST.

’x’ real or integer, or vector with real and integer elements, the x-coordinates in SCIL or VS coordinate units.

’y’ real or integer, or vector of real and integers, the y-coordinates inSCIL or VS coordinate units.

The corresponding elements in the x and y vectors are taken as x,y-coordinates (seeFigure 13). The command draws a line between each of the coordinates.

If the RELATIVE option is included in the argument list, the first coordinate pair isplaced relative to the upper left corner of the canvas and each of the following coor-dinates are drawn relative to the previous one.

If the first and last point coincide, the polyline will form a closed figure (a polygon),where the end points are joined according to the JOIN_STYLE component of thegraphical context.



ABB Automation 247

If the FILL option is included in the argument list, the polygon outlined will be filled(with the FOREGROUND color). In this case, the polyline is always closed.

x(1),y(1)

x(2),y(2)

x(3),y(3)

x(4),y(4)

x(5),y(5)

x(6),y(6)

Figure 13. Drawing a polyline with .POLYLINE

.TEXT [[scope,]n :] x,y, text [,FILL] [,EXTENDED] [,align]

This command draws horizontal text starting at (x,y). The size and font of the texts isdetermined by the graphics context.


’n’ Graphics context number, integer expression 0 ... 20 or 0 ... 50 de-pending on the scope. Default = 0. Used components:FUNCTION, FOREGROUND, BACKGROUND, FONT. Seesection 9.3.

’x,y’ Integer, real or vector of integer or real. The coordinates of thestart point of the text. The starting-point (x,y) defines the locationof the origin pixel of the first character (if left alignment). The lo-cation of the origin pixel is font dependent. For the MicroSCADAsemi-graphic font, it is the upper left corner of a character.

’text’ A SCIL expression of type text or a text vector. The text to be dis-played. The SCIL text functions LOWER_CASE, UPPER_CASEand CAPITALIZE can be used for converting the text to lower-case, upper-case or capitalized text respectively, see section 8.4.

’align’ The alignment of the text: LEFT, RIGHT or CENTER. The defaultis LEFT, if the font is a left-to-right font, and RIGHT if the font isa right-to-left font (e.g. Hebrew).

When multiple lines are drawn, i.e. ’text’ is a text vector, the x,y coordinates can bevectors with the coordinates for each new line or they can be scalars. In the lattercase, the text lines are displayed under one another starting from x,y with a line spaceadjusted to the font characteristics.



1MRS751250-MEN

ABB Automation248

If the EXTENDED option is given, extended (2 byte) character coding is used, other-wise, normal (1 byte) coding is used. The EXTENDED option is only valid in X-typemonitors.

If the FILL option is given, the background of the text is filled with theBACKGROUND color of the graphics context, otherwise the background is transpar-ent.

9.3 Graphics Contexts

9.3.1 General

General

A graphics context is a collection of components (section 9.3.3.) each of which definea graphical property, for instance, background color, foreground color, font. A picturecontains a number of graphical contexts identified by a number. The context numbersare used as arguments in the graphical commands. The maximum number of graphicscontexts that can be used in one picture is limited to 2000.

The defined graphics contexts (together with the canvas selection and the scaling) canbe temporarily stored and restored, see section 9.5.

Scope of Graphics Contexts

The scope of a graphics context is the set of objects where the context applies. Agraphics context can be defined for a single object (picture, dialog object), for a groupof objects, or for all objects used in the monitor. There are five different scopes, eachof which can contain a number of graphics context definitions. In the context defini-tion commands, the scope is given by a text, a single letter or a word as follows:

"C" or "CURRENT" The scope is the object (picture or Visual SCIL object)containing the .GC command. Max. number of contexts: 20.

"P" or "PARENT" The scope is the parent object of the object in which thecontext is defined with .GC. Max. number of contexts: 20.

"R" or "ROOT" The scope is the root object (main dialog, picture containeror main picture). Max. number of contexts: 20.

"M" or "MONITOR" The scope is all object used in the monitor. Max. number ofcontexts: 50. This scope is reserved for LIB 500 pictures.

"U" or "USER" The scope = all objects shown in the monitor. Max. numberof contexts: 50. This scope is for use in the application pic-tures.

The number of the context together with its scope identify the context and distin-guishes it from other contexts with different context number or scope.

When a part picture is shown, it inherits the contexts of its parent picture. However,changes in the contexts of the parent picture do not affect the contexts of the part



ABB Automation 249

pictures which are already displayed on screen. Likewise, the contexts are inheriteddownwards in the hierarchy of a dialog system.

Default Settings

As long as no component definitions have been done for a context in a certain scope,all the components have the default values mentioned in the component descriptionssection 9.3.3. The contexts (except number 99) can be modified any time with thecommands described in section 9.3.2.

Context number 99 contains the default settings of the components. This contextscannot be changed. It contains the following components:

FUNCTION = "COPY"

FOREGROUND = "WHITE"

BACKGROUND = "BLACK"

LINE_WIDTH = 0

LINE_STYLE = "SOLID"

CAP_STYLE = "BUTT"

JOIN_STYLE = "MITER"

FONT = "" (semi-graphic)

ARC_MODE = "PIESLICE"

NAME = ""

GC number 99 may only be used as a source in GC copy. For self-documentation, apredefined constant name DEFAULT_GC may be used instead of number 99(DEFAULT_GC == 99).

Context number 0 is the default context in those cases where no context number isgiven in the graphics commands.

9.3.2 Defining Graphics Contexts

The following three commands are used for the modification of graphics contexts.The graphics contexts can be read with a SCIL function described in section 9.3.5.

.GC [[scope,]n [=[scope,]m]]:[[component = value]...[,component = value]]

Modifies the graphics context number ’n’.

’scope’ is a text which specifies the scope of the context, i.e., the objects(pictures, and Visual SCIL objects) where the context is valid.’scope’ can take the values "C" or "CURRENT", "P" or"PARENT", "R" or "ROOT", "M" or "MONITOR", "U" or"USER". See section 9.3.1. Default value = "C".



1MRS751250-MEN

ABB Automation250

’n’ The number of the graphics context, integer 0 ... 20 or 0 ... 50. Thisnumber is used in the graphical commands, see section 9.2. De-fault: 0.

’m’ The number of another graphics context which is copied to thecurrent one before modification. Integer, 0 ... 20 or 0 ... 50.

’component’ The name of a component to be modified. The component namescan be given in the complete or abbreviated form, see section9.3.3.

’value’ A SCIL expression, the value assigned to the component. The al-lowed data types are mentioned in the component descriptions insection 9.3.3.

The modification concerns all graphical elements subsequently drawn with the con-text in question. It does not affect the graphical elements drawn previously with thesame context number. Those components which are not included in the componentlist are not affected by the command. The graphics contexts are inherited to the pic-tures shown in windows and to the picture functions.

The ROOT, MONITOR and USER scopes represent separate sets of contexts, whilethe CURRENT and PARENT scopes can mean the same or separate sets of contextsdepending on the situation.

Example:

("C",5), ("R",5), ("M",5) and ("U",5) are all different graphics contexts. The contexts("C",5) and ("P",5) may be the same or different contexts: When a part picture isshown, its context is the same as the one of the parent (i.e. CURRENT = PARENT).If the parent’s context is changed later, they become two different contexts and theparent’s context is referred to as ("P",5).

The PARENT scope could, e.g., be used in a general purpose tool designed to changethe appearance of any picture it is used in. The MONITOR and USER scopes are suit-able for defining monitor specific graphics contexts in the start program of theAPL_INIT picture, which is shown each time a monitor is mapped for an application(either at system start-up or later).

Example:.GC 0 = DEFAULT_GC : FOREGROUND = "RED"

9.3.3 Components of Graphics Contexts

This sub-section describes the components included in the graphics contexts. Thecomponents are listed in alphabetical order.

The components are assigned values by means of the commands described in section9.3.2. The values are given as SCIL expressions of the allowed data types. From thestart, the components have the default values given below. In the context definingcommands, the component names can be given in complete form or in the abbreviatedform found to the left in the description below.



ABB Automation 251

AM ARC_MODE

This component specifies how filled arcs are drawn: as sectors or segments.

Value: "CHORD" = The end points of the arc are connected and the re-sulting segment is filled."PIESLICE" = The end points of the arc are connected in the cen-ter of the circle and the resulting sector is filled.

Default: "PIESLICE"

BG BACKGROUND

Specifies the "background color" of the full graphic lines and text. ThisBACKGROUND color is used in the following cases:

• In the gaps of double dashed lines.

• As the background of "filled" texts.

Values: The color can be given in the following four ways (see section9.3.4.): - With a color name given as a text, e.g., "LIGHT BLUE"- With a RGB number given as a vector of three elements, e.g.,(10000,20000,30000)- With a color number given as an integer expression, e.g. 5- With scope and color number given as a vector of two elements:(scope,color_number), e.g., ("M",5).

Default value: "BLACK"

CS CAP_STYLE

Specifies the endpoints of the line, see Figure 15.

Values: "BUTT" = The line is cut off in a 90° angle to the line direction atthe end point.

"NOTLAST" = The same as "BUTT", but the line is cut off onepixel before the end point.

"PROJECTING" = The line is cut off in the same way as "BUTT"half its width past the endpoint.

"ROUND" = The line end is rounded in a half circle with r = halfits width past the endpoint.

Default value: "BUTT"



1MRS751250-MEN

ABB Automation252

DL DASH_LIST

Specifies the length of dashes and gaps when drawing dashed lines.

Value: Vector of even length. The odd indexes define the lengths ofdashes and the even indexes the lengths of the gaps. The lengthsare given in coordinate units, see section 9.4.

Default: The dashes as well as the gaps are four pixels long.

StartPoint

EndPoint

Width

Figure 14. Wide lines are drawn centered in relation to the start and end points

Figure 15. The CAP_STYLE component

"PROJECTING" and "ROUND" are meaningful only for lines with a width largerthan 1 pixel.



ABB Automation 253

Figure 16. The JOIN_STYLE component

DO DASH_OFFSET

Specifies the position in the dash pattern where to start a dashed line. For example, ifDASH_LIST == (5,2) and DASH_OFFSET == 5, the line starts with the gap.

Value: Positive integer

Default value: 0

FT FONT

Specifies the X-windows name of the font used to draw a text.

Value: The value can be given in the following three ways (see section9.3.4.):

• With a font name given as a text, e.g. "KANJI_24"

• With a font number given as an integer expression, e.g. 3.

• With scope and font number given as a vector of two elements: (scope,font_number), e.g., ("M",3).

Default: The MicroSCADA semi-graphical font which is called"MICROSCADA-SEMIGRAPHICS".

FG FOREGROUND

This component specifies the color in which the graphical element is displayed.

Values: The color can be given in the following four ways (see section9.3.4.): - With a color name given as a text, e.g., "LIGHT BLUE".- With a RGB number given as a vector of three elements, e.g.,



1MRS751250-MEN

ABB Automation254

(10000,20000,30000).- With a color number given as an integer expression, e.g. 5.- With scope and color number given as a vector of two elements: (scope,color_number), e.g., ("M",5).

Default value: "WHITE"

FU FUNCTION

This component states how the color of added pixels (’new’) are combined with thecolor of already existing pixels (’old’) on screen.

Each color in use has a palette number (pixel value, 0 ... 255). The FU componentdetermines how the bit representations of the color numbers are combined bit-wise bymeans of logical operators.

Value: Definition:

"CLEAR" 0

"AND" new AND old

"ANDREVERSE" new AND (NOT old)

"COPY" new

"ANDINVERTED" (NOT new) AND old

"NOOP" old

"XOR" new XOR old

"OR" new OR old

"NOR" (NOT new) AND (NOT old)

"EQUIV" (NOT new) XOR old)

"INVERT" (NOT old)

"ORREVERSE" new OR (NOT old)

"COPYINVERTED" (NOT new)

"ORINVERTED" (NOT new) OR old

"NAND" (NOT new) OR (NOT old)

"SET" 1

"SCIL_XOR" X server independent XOR

Default value: "COPY"

Examples:

"COPY" means that the added color replaces the former color.



ABB Automation 255

Using "SCIL_XOR" or "XOR" (the latter does not work in all X servers) repeatedlyon the same graphic element alternately draws and deletes the graphics.

JS JOIN_STYLE

Specifies how corners are drawn for wide lines drawn with a single graphics com-mand, see Figure 16.

Values: "MITER" = The outer edges of the two lines are extended to meet in one point.

"ROUND" = The lines are joined by a circular arc with r = half the line width centered on the join point.

"BEVEL" = The outer edges of the lines are joined at the end points.

Default: "MITER"

LS LINE_STYLE

Specifies how the line is drawn and in which colors.

Values: "SOLID" = The line is continuous (without dashes) and drawn in the FOREGROUND color.

"ONOFFDASH" = The line is dashed with the dashes drawn in the foreground color.

"DOUBLEDASH" = The line is dashed with the dashes drawn in the foreground color and the gaps between the dashes in the background color.

Default value: "SOLID"

LW LINE_WIDTH

Specifies the width of the line in coordinate units (see section 9.4.). Wide lines aredrawn centered between the start and the end point given in the drawing command,seeFigure 14.

Values: Integer or real, >= 0

Default value: 0

LINE_WIDTH = 0 specifies the width to one pixel regardless of the scaling. LW = 0is the most efficient line width and fastest to draw. However, width 0 is X serverdependent and may not match exactly with lines of pixel width 1 (which is X serverindependent).



1MRS751250-MEN

ABB Automation256

NA NAME

A freely chosen name of the graphics context. This component is not copied whencopying a context.

Value: Text

9.3.4 Colors and Fonts

Colors

The final color of a graphical element displayed on screen depends on theFOREGROUND, BACKGROUND and FUNCTION components of the graphicscontext (section 9.3.3.). The colors can be given in four manners:

• By color names (Windows or X windows). The names of the colors in the semi-graphic pictures are: WHITE, BLACK, RED, GREEN, BLUE, CYAN,MAGENTA, YELLOW.

• By RGB intensities given as a vector of three elements where the first elementdefines the red, the second element the green and the third element the blue in-tensity of the color as an integer or real value in the range 0 ... 65535. Conse-quently, for example, (0,0,0) is black and (65535,65535,65535) is white.

• By a color mix number. A color mix number is a dedicated color cell in the colorpalette of the operating system or X server. The number is defined by the.COLOR command, see below.

• With scope and color mix number given as a vector of two elements:(scope,color_number), e.g., ("M",5).

The .COLOR command below is used for creating and modifying color mix numbers,and the COLOR function for reading the numbers.

.COLOR [scope,] number : color [,SHARED]

.COLOR [scope,] number : color [,PRIVATE]

The .COLOR command defines the color mix number.

’scope’ The scope of the color number. The scope is given in the same wayas for graphics contexts in section 9.3.2.

If the operating system or X-server is not capable to provide the requested color ex-actly (e.g. because the palette of the server is full due to the use of many differentcolors on screen), the nearest possible color is used.



ABB Automation 257

’number’ Color number given as a positive integer expression. Each scopecan have the following maximal number of colors: “C": 20, "R":20, "M": 50, "U": 50.

'color' Color definition given in one of the four manners described above.

The color mix number can be used for color selection in the graphics contexts(BACKGROUND and FOREGROUND).

The color allocation policy may be private or shared. Private colors allocate a dedi-cated palette entry for the color, shared colors do not.

If there are several MicroSCADA windows (or other applications requiring many col-ors) open on a monitor, it may happen that the palette runs out of entries. To avoidthis from happening, define the color as SHARED.

A change to a private color appears immediately on screen, i.e., all the pixels drawnwith the color are immediately affected. Changes to a shared color affect only pixelsdrawn with the color after the change. Hence, private colors are needed for color ani-mation (done for example in the color chooser pictures).

The default color allocation policy is specified with the value of the APL:BCP attrib-ute of the application that uses the monitor. The default color allocation policy for amonitor is specified by the new monitor attribute CP. The default color allocationpolicy for an application (all monitors used by the application) is defined by the ap-plication attribute, CP.

The allocation policy is assigned to a color when the color is first defined. The later.COLOR commands applying to the same color do not change the policy unless ex-plicitly requested.

COLOR([scope,]number)

Returns the RGB values of the color specified by the arguments.

'scope' The scope of the color

'number' The number of the color

Result: Vector of three elements

Example:.COLOR 1: "NAVYBLUE".GC : FG = 1.BOX 100, 100, 200, 200, FILL@RGB = COLOR(1)@RGB(1) = %RGB(1) + 10000.COLOR 1 : %RGB

The example creates a color mix initialized as navy blue, then draws a filled box inthe selected color. The color is added with more red, which appears in the color of thebox according to the color allocation policy definitions.



1MRS751250-MEN

ABB Automation258

Fonts

The font used in texts is specified by the FONT component of the graphics context(section 9.3.3.). Fonts can be given as follows:

• With a font name given as a text, e.g. "KANJI_24".

• With a font number given as an integer expression, e.g. 3. The font numbers aredefined by the .FONT command, see below.

• With scope and font number given as a vector of two elements:(scope,font_number), e.g., ("M",3).

• As a list with one or several of the follwing attributes: FAMILY (FA),POINT_SIZE (PS), FACE (FC).

The .FONT command below defines font numbers, and the FONT function is used forreading font numbers.

.FONT [scope,] number:font

Defines a font number.

’scope’ The scope of the font number. The scope is given in the same wayas for graphics contexts in section 9.3.2.

’number’ Font number given as a positive integer expression. Each scopecan have the following maximal number of fonts: "C": 10, "R": 10,"P": 10, "M": 20, "U": 20. 0 = the MicroSCADA semi-graphicfont. Do not change that!

’font’ Font definition given in any of the three manners allowed for theFONT component, see section 9.3.3.

FONT([scope,] number)

’scope’ The scope of the font.

’number’ The number of the font.

Result: The font function returns a list with the attributes shown in Figure17.



ABB Automation 259

Figure 17. The attributes returned by the font function

NA Name

HE Height (number of pixels)

AS Ascent (logical extent above baseline in number of pixels)

DE Descent (logical descent below baseline in number of pixels)

WI Width (width of the widest character in the font in number of pix-els)

FA Family (the name of the font family)

PS Point size

SS SCIL size

FC Face

EN Encoding

HE is always the sum of AS and DE.



1MRS751250-MEN

ABB Automation260

9.3.5 Reading Graphics Contexts

The defined graphics contexts can be read with the following SCIL functions:

GC([scope,]n)

The function returns the values of the components of the context.

’scope’ The scope of the context, see section 9.3.

’n’ Graphics context number, integer 0 ... 20 or 0 ... 50 depending onthe scope, see section 9.3.2.

Value: List, where the abbreviated names of the components are the at-tributes.

Example:@GC_DEF = GC(0)!SHOW INFO "CURRENT DEFAULT FONT IS " + GC_DEF:VFT

COLOR_IN([scope,] n)

The function returns the RGB values of the foreground color in the context as a vectorof three elements.

’scope’ Scope of the context.

’n’ Graphics context number.

FONT_IN([scope,] n)

The function returns a list value with the same attributes as for the FONT function,see section 9.3.4.

’scope’ Scope of the context.

’n’ Graphical context number.

9.4 Graphics Canvas

General Description

The graphical elements are displayed on the selected canvas which can be:

• The object (picture, picture function, dialog object) which contains the command(default).

• The root object - the main picture or the main dialog.



ABB Automation 261

• A named window or dialog object.

• The parent object of the object where the command is executed.

The canvas can be selected with the commands in next section Selecting Canvas (to-gether with the context definitions and the scaling factor) can be temporarily stored.See section 9.5.

Selecting Canvas

If not changed with any of the commands listed below, the canvas for the graphicscommands is the object where the commands are executed. Use the following com-mands in order to get the elements displayed on another canvas:

.CANVAS object

The command selects the named picture object (window picture or picture function)or dialog object (dialog or dialog object) - for canvas.

’object’ A picture reference or a Visual SCIL object reference, see Chapter4.

.CANVAS ROOT

The root object is used as canvas. In a picture the root object is the main picture. In adialog system, the root is the main dialog or picture container.

.CANVAS PARENT

The parent object is used as canvas. In a picture the parent object is the parent pictureof the current window picture or picture function. In a dialog system, the parent is ....

.CANVAS CURRENT

The current object is used as canvas, i.e., the object containing the graphics command.Hence, this command returns the canvas to the default.

.COORDINATE_SYSTEM coordinate_system

Specifies the coordinate system to be used in graphic drawing commands and mousehandling commands.

The coordinate system is specified by one of the following key words: SCIL, VS.

Changes of the coordinate system with the COORDINATE_SYSTEM command arevalid only within the SCIL program where the change was made.



1MRS751250-MEN

ABB Automation262

Example:.COORDINATE_SYSTEM SCIL

The SCIL Coordinate System

Within the SCIL coordinate system, the (0,0) coordinate lies in the upper left cornerof the canvas. The relation between SCIL coordinates and pixels on screen dependson the semigraphic font used in the MicroSCADA Monitor and on the scaling factorused by the drawing commands. See Figure 18.

pixel_coord = SCIL_coord *MicroSCADA_Monitor_Width / scaling_factor

where

‘pixel_coord = the pixel coordinates as displayed on screen.

SCIL_coord = the coordinates given in the graphics SCIL command.

MicroSCADA_Monitor_Width = 80 * Width of semigraphic character = 80*8 or 80*12 or 80*15.

scaling_factor = the scaling factor. The default scaling factor is1280. The scaling factor can be changed with the .SCALING command see section 9.4.4.

Scaling factor

x coordinates(0,0)

y coordinates

Canvas=Main Picture

Canvas=Window Picture orPicture function

Figure 18. The SCIL coordinate system

The Visual SCIL Coordinate System

Within the Visual SCIL coordinate system, the (0,0) coordinate lies in the lower leftcorner of the canvas. The Visual SCIL coordinates are equal to the pixel positionswithin the canvas. Visual SCIL coordinates can not be used in monitors of X-type.

When handling dialogs, the origin of the coordinate system lies at the bottom left cor-ner of the screen. When handling dialog items, the origin is in the lower left corner ofthe parent object. A unit in the coordinate system is a pixel.



ABB Automation 263

Coordinates are also used, for example, when giving a position with the_GEOMETRY attribute and when reading a position with the _GET_POINTER_POSmethod. For more information on VS coordinates, see the section 2.4 in the VisualSCIL manual.

The Graphics Contexts components LW, DL, DO are defined according to the activecoordinate system. These Graphics Contexts components are not affected by the coor-dinate system used at drawing.

Example:.COORDINATE_SYSTEM VS.GC : LW = 5.LINE 10,10,100,100 ;line width is now 5 units according to

;the VS coordinate system (pixels)..COORDINATE_SYSTEM SCIL.LINE 10,10,100,100 ;line width is still 5 units according to

;the VS coordinate system (pixels),;because the Graphics Components were defined under;VS coordinate system

Changing Scaling Factor

The scaling factor can be changed by the following command:

.SCALING [s]

Sets the scaling factor to be used in the subsequent SCIL graphics commands.

’s’ is an integer or real expression, the scaling factor. If ’s’ = 0, the co-ordinates are taken as pixel coordinates of the screen where thegraphical element is displayed. If ’s’ is omitted, the scaling factor isreturned to the default (= 1280).

For example, a graphical element programmed with s = 0 will have different sizes de-pending on the resolution of the screen where it is shown.

The scaling factor can be temporarily stored (together with context definitions andcanvas selections) by the commands in section 9.5. Note that the scaling factor onlyaffects the SCIL coordinate system.

Mouse Input

The coordinates can be read from the cursor position with the .MOUSE command.The .MOUSE command can be used with or without tracing. If tracing is OFF, thecommand reads the cursor position and the current mouse button states. If tracing ison, the command notes the following mouse events: button press and release, move-ment of mouse (provided that motion event is on, see the .MOUSE ON command). Bymeans of the .MOUSE ON and .MOUSE OFF commands, tracing is switched on andoff (default = OFF).

.MOUSE x, y [, button [, buttons [, RELATIVE] ] ]

Reads the SCIL coordinates of the cursor and the mouse button states.



1MRS751250-MEN

ABB Automation264

x and y two variables that get the value of the x and y coordinates respec-tively (SCIL or VS coordinates).

button a variable that gets the value of the pressed or released mousebutton number (1, 2 or 3). If the registered mouse event was a mo-tion event, the variable gets the value 0. If tracing is OFF, the vari-able gets the value 0.

buttons a variable that receives the current mouse button states if tracing isOFF, or the button states immediately before the mouse event iftracing is ON. The states are returned as a bit mask, where each bitnumber represents a mouse button. The bit values have the fol-lowing meanings: 0 = the button is released, 1 = the button is helddown.

RELATIVE an optional keyword. If RELATIVE is given as the last argumentof the command, the coordinates are relative to the current canvas(If the canvas is not explicitly set, the window or picture functionexecuting the .MOUSE command acts as the current canvas). IfRELATIVE is not given, the coordinates returned by .MOUSEcommand are relative to the part picture (picture shown in win-dow) executing the command.

Examples:.MOUSE X, Y, RELATIVE.MOUSE X, Y, BUTTON, RELATIVE.MOUSE X, Y, BUTTON, BUTTON_MASK, RELATIVE

.MOUSE ON [,MOTION]

.MOUSE OFF

.MOUSE ON sets the program in tracing state. If the MOTION option is given, alsothe motion of the cursor is traced.

.MOUSE OFF ends the tracing state. The tracing state is automatically ended when aprogram is completed.

Example:

The following SCIL sequence draws a line segment from (0,0) to the position pointedby the user. The final position is given by releasing button 1.

.MOUSE ON@B1_PRESSED = FALSE#LOOP NOT %B1_PRESSED

.MOUSE X, Y, BUTTON, BUTTONS#IF (%BUTTON ==1) AND (BIT(%BUTTONS , 1)==0) #THEN #BLOCK

@B1_PRESSED = TRUE#BLOCK_END

#LOOP_END

The program sequence above waits until mouse button 1 is pressed, then the followingis executed:

.MOUSE ON, MOTION

.GC : FUNCTION = "XOR"

.LINE 0, 0, %X, %Y



ABB Automation 265

#LOOP %B1_PRESSED.MOUSE NEW_X, NEW_Y, BUTTON, BUTTONS.LINE 0, 0, %X, %Y#IF %BUTTON == 1 #THEN @B1_PRESSED = FALSE#ELSE #BLOCK

.LINE 0, 0, %NEW_X, %NEW_Y@X = %NEW_X@Y = %NEW_Y

#BLOCK_END#LOOP_END

The line is drawn and erased until the mouse button is released, then the following isexecuted:.GC : FUNCTION = "COPY".LINE 0, 0, %NEW_X, %NEW_Y.MOUSE OFF

The line is drawn from (0,0) to the coordinates given be the variables %NEW_X and%NEW_Y.

9.5 Miscellaneous Graphical Commands

9.5.1 Storing and Restoring Selections

.PUSH

.POP

The commands .PUSH and .POP are used for storing temporarily the context defini-tions, the scaling factor and the canvas selection. They are useful, when there is aneed to store standard selections, meanwhile make other selections, and then restorethe standard selections after a while. They are used, for example, when a subroutineuses specific values for canvas, scaling and graphics contexts, which should not inter-fere with the picture that executes the subroutine.

.PUSH stores the current canvas selection, scaling factor and graphics contexts defi-nitions. .POP restores the selections stored with .PUSH. The .POP command must belocated in the same program as the corresponding .PUSH command.

9.5.2 Display Handling Commands

.FLUSH

This command forces a blink timing and an immediate updating of the entire applica-tion window. However, if there is an ongoing pending, see below, the command hasno effect. The command is rather time consuming.

.PEND ON

.PEND OFF

Pending is used to prevent disturbing flickering when drawing related graphics primi-tives in sequence (for example when changing position of an object in animation).



1MRS751250-MEN

ABB Automation266

The graphics drawn after PEND ON are not shown on screen until the matchingPEND OFF is encountered. At PEND OFF the resulting output of the interveningcommands is shown as a flash (that is the drawn primitives are not displayed one byone). PEND ON and the matching PEND OFF must be located in the same SCIL pro-gram. If a SCIL program ends while the output is pending, an automatic PEND OFF isgenerated by the base software. PEND commands may be nested. In this case, the out-ermost PEND off triggers the output.

An implicit PEND ON - PEND OFF is set by the base software around the semi-graphical background and the draw program when a picture is displayed.


MicroSCADA10 Using Motif Widgets in SCIL

ABB Automation 267

10 Using Motif Widgets in SCIL

This chapter describes the SCIL interface to the Motif programming, which is sup-ported in the X/OSF/Motif environment. Motif programming is briefly described insection 10.1. Section 10.2 describes the SCIL commands for creating, deleting andmodifying widget instances. Section 10.3 describes the use of widget methods formanaging and unmanaging widget instances. Section 10.4 describes the handling ofwidget resources with SCIL.

The reader is assumed to be familiar with Motif programming. Refer to the followingMotif programming manuals: Motif Programming Manual, O’Reilly & Associates,Inc. and OSF/Motif Programmer’s Reference Manual. Motif support in MicroSCADA8.4.1 is based on Motif version 1.1.

10.1 General

Motif widgets are standardized components of the Motif user interface, e.g. dialogboxes, buttons, labels, scroll bars, etc. The Motif widgets are organized into classeswith similar properties and functions. Figure 19 shows the Motif widget classes andthe class hierarchy. The class hierarchy is constructed so that the lower classes (to theright in the figure) have all the properties of the higher classes (to the left in the fig-ure) plus some additional properties. For instance, the PushButton class has all theproperties of the Label class, but also some other essential properties which the Labelclass lacks.

A widget specified for display on screen is called a widget instance or an object. Awidget instance is always also an X window, except for the widgets called gadgets.The top-level window of a MicroSCADA operator process window, i.e. the windowdirectly under the root window (= the screen), is always a widget of the class. Appli-cationShell. The MicroSCADA main window is implemented as a DrawingArea wid-get.

Composite widget classes support the containment of other widgets within them. Thecontained widgets are called child widgets, and the containing widgets are called par-ent widgets. Widgets of the classes below Manager - manager widgets - have the abil-ity to manage the position and size of their children. Generally, for space reservingreasons, the descendants of a widget, ie., its children in one or more links, must bemanaged before the widget itself and its ancestors are managed. When a parent widgetis shown, all its managed child widgets are shown as well.

The configurable features of the widgets, e.g. color, position, and function of a widgetinstance is specified by its resources (section 10.4.). Each widget class has its own setof resources plus some resources inherited from widget classes higher up in the wid-

The Motif Widgets described in this chapter can be used only in MicroSCADAmonitors defined as type “X”. Using this monitor type0 excludes the possibility touse Visual SCIL and Visual SCIL based tools. It is therefore not recommendable touse Motif Widgets when building new MicroSCADA 8.4 applications.



1MRS751250-MEN

ABB Automation268

get class hierarchy. The resources can be assigned values when a widget instance iscreated, or later. Resources can also be set in resource files.

In Motif there are a number of creation routines for creating widget instances or com-pound objects comprising several widget instances. These routines can be invoked bymeans of SCIL commands. There are SCIL commands for creating, deleting andmodifying widgets (section 10.2.). The SCIL programmer can also manage and un-manage the widgets (sections 10.2. and 10.3.).

The Motif widgets, their resources and the Motif creation routines are described in theMotif Programming Manuals.

OverrideShell

Object

RectObj

WindowObj

ArrowButtonGadgetGadget

LabelGadget

SeparatorGadget

CascadeButtonGadget

PushButtonGadget

TroggleButtonGadget

ArrowButton

Label

List

Scrollbar

Separator

Text

TextField

CascadeButton

DrawnButton

PushButton

ToggleButton

Primitive

BulletinBoard

DrawingArea

Frame

PanedWindow

RowColumn

Scale

ScrolledWindow

Form

SelectionBox

MessageBox

MainWindow

M anagerConstraint

FileSelectionBox

Command

Composit

WMShellShell

VendorShell

MenuShell

TransientShell

TopLevelShell

DialogShell

ApplicationShell

- Motif- Xt Intrinsics

Core

Figure 19. The class hierarchy of the Motif Widget set.

10.2 Widget Handling Commands

.CREATE [parent/]widget = routine[(resources)]

.CREATE_MANAGED[parent/]widget=routine[(resources)]

Creates a Motif widget instance or a group of instances (compound object).



ABB Automation 269

’widget’ A freely chosen name of the widget instance, i.e., the widget in-stance whose widget ID is returned. The widget name may be up to63 characters long.

’parent’ The "path" to the widget specified by a chain of parent/child rela-tions where the links are separated by slashes. Each link can beeither a widget or a semigraphic window. If the last link in thechain is a Motif widget, the window containing it will be the par-ent. If ’parent’ is omitted, the application shell containing the Mi-croSCADA main window will be the parent.Example: MOTHER/MY_PUSH_BUTTON.

’routine’ The Motif creation routine used to create the widget (or gadget) orgroup of widgets. Any of the 57 Motif creation routines staringwith XmCreate may be used along with the TopLevelShell definedin Xt (see appendix A of Motif Programming Manual or OSF Mo-tif Programmer’s Reference Manual). ’routine’ is formed by re-moving XmCreate from the creation routine name, adding an un-derscore preceding any upper case letter in the name and prefixingthe result with ’MOTIF’.Example: XmCreateSimpleMenuBar becomes MOTIF_SIMPLE_MENU_BAR in SCIL.Note: The XtTopLevelShell widget class can be used in SCIL under the name MOTIF_TOP_LEVEL_SHELL.

’resources’ A list of resource assignments in the format: resource_name = value

If there are several assignments, they are separated by commas. Read about resourcesin section 10.4.

The created widget is not displayed on screen until the widget and all its ancestorshave been managed. It can be managed and unmanaged by means of widget methods,see section 10.3. If you want the widget to be managed immediately, use theCREATE_MANAGED command instead of CREATE.

Examples: .CREATE PB = MOTIF_PUSH_BUTTON (label_string = "Close")Creating a push button labelled "Close".

.CREATE BAR = MOTIF_SIMPLE_MENU_BARCreating a simple menu bar called BAR.

.MODIFY [parent/]widget = expression

Modifies the resource values of a widget instance (corresponds to the XtSetValuesfunction of Xt).

’widget’ Widget name.

’parent’ The "path" to the widget specified by a chain of parent/child rela-tions. If ’parent’ is omitted, the first found widget instance with thegiven name is modified.



1MRS751250-MEN

ABB Automation270

’expression’ A list type expression containing the names and values of the re-sources to be set. See section 10.4.

The modifications come into effect immediately. The resources not included in the listcommand remains unchanged.

Example:.MODIFY RUNNING_WIDGET = LIST(X = RUNNING_WIDGET.X + 10,- Y = RUNNING_WIDGET.Y + 10)

The widget is moved by adding 10 to its x- and y- coordinates.

.DELETE [parent/]widget

DELETE destroys a widget instance and all its descendants.


’parent’ The "path" to the widget specified by a chain of parent/child rela-tions. If ’parent’ is omitted, the first found widget instance with thegiven name is selected.

The widget(s) are erased from screen and their definitions are deleted. In order toerase the widgets and preserve the widget definitions, use the UNMANAGE widgetmethod (see section 10.3.).

When a MicroSCADA picture is removed from screen, all its widgets are automati-cally deleted.

10.3 Widget Methods

[parent/]widget.method

Widget methods are functions that widgets can execute on behalf of the caller. Thesyntax of a widget method call is as follows:

Executes a widget method.

’widget’ The name of the widget instance.


’method’ The name of the method. The following four predefined methodsare available:

MANAGE Manages a previously created widget. If all itsancestors have been managed, the widget andall its managed children are shown on screen.



ABB Automation 271

UNMANAGE Unmanages a widget and all its descendants,but the widget instances are preserved.

MANAGE_ALL_CHILDREN Recursively manages allSCIL-created descendants of a widget in cor-rect order, i.e. starting from the child widgetfurthest down in the parent/child chain.

SET_STATE This method corresponds to the Motif routineXmToggleButtonSetState. It sets the ’state’ and’notify’ parameters according to the valuesgiven to the STATE and NOTIFY resources(see sections 10.4.2. and 10.4.4.). The resourcesmust be assigned values immediately before themethod is executed.

Examples:.CREATE A.CREATE A/B.CREATE B/CC.ManageB.ManageA.ManageMAIN_DIALOG.MANAGE_ALL_CHILDREN

10.4 Widget Resources

10.4.1 General

The widget resources are the configurable features of the widgets, e.g., position, size,color, font, callback routines. The Motif (and Xt) widget classes and their resourcesare listed and described in Appendix B of the Motif Programming Manual (O’ReillyAssociates, Inc.) and in the OSF/Motif Programmer’s Reference Manual.

All listed resources can be used in SCIL, except those which have data types not im-plemented in SCIL (see section 10.4.3). In SCIL, the Motif resources are recognizedby names which resembles the Motif resource names (see 10.4.2). The data types ofthe resources are translated to SCIL data types (see 10.4.3). The value of a resourcecan be written as described in section 10.4.4, and read as an expression as describedin 10.4.5.

10.4.2 Resources in SCIL

The SCIL name of a Motif resource is formed by removing the XmN from the Motifresource name and inserting an underscore in front of any upper case letter in thename. For example, the SCIL resource name of the Motif resource XmNhelpLabel-String becomes HELP_LABEL_STRING.

In addition, each Motif resource whose data type is Dimension or Position has a spe-cial SCIL resource name obtained by prefixing the standard name with ’SCIL_’, e.g.:

SCIL_DEFAULT_BUTTON_SHADOW_THICKNESS



1MRS751250-MEN

ABB Automation272

These resource names function like the standard resource names, but the dimension orposition is given in SCIL coordinate units.

Besides the Motif resources, the following non-motif resources are available in SCIL:

PARENT This resource can only be read, see section 10.4.4. It contains thewidget identification number of the parent widget as an integervalue. The value should only be used as a value of a Widget typeresource of another widget in a CREATE, MODIFY or SET com-mand.

STATE The ’state’ parameter (boolean) of the Motif routine XmToggle-ButtonGetState. In SCIL, the routine corresponds to theSET_STATE method, see section 10.3.

NOTIFY The ’notify’ parameter (boolean) of the Motif routine XmToggle-ButtonGetState. In SCIL, the routine corresponds to theSET_STATE method, see section 10.3.

10.4.3 Resource Data Types

Table 9 shows an overview of the Motif resource data types and the correspondingSCIL data types. Some Motif resource data types have not been implemented in SCILand the resources of these datatypes therefore cannot be used.

The function data types, except for callback functions, are not implemented.

The implemented resource value types whose SCIL counterparts are not obvious arebriefly described below.

Mnemonic values

All the unsigned char type resources which may have one of the predefined values de-fined by constant names in Motif, are given as text values in SCIL. The text value isformed by omitting ’Xm’ from the constant name. For example, the valueXmSHADOW_IN of XmNshadowType resource is in SCIL resource list given as

SHADOW_TYPE = "SHADOW_IN".

CallbackList resources

The callback resources may be given as a text or a vector value. If text, the text is in-terpreted as the name of the named program to be used as the callback procedure (see1.6). If a vector value is specified, the vector should contain the SCIL program to beused as the callback procedure.

Examples:DESTROY_CALLBACK = "I_AM_DYING"OK_CALLBACK = ("@OK = TRUE" , ".SET A.LABEL_STRING = ""Done""")



ABB Automation 273

Only one callback procedure may be specified for a resource. Currently, the additionalinfo fields that appear in some CallbackStruct structures are not delivered to SCILcallback procedures.

XmFontList resources

Font lists are given as vectors, the elements of which are SCIL font specifications (seesection 9.3.4.).

Examples:@FL(1) = ("M",2) ;Monitor specific font number 2.CREATE W = MOTIF_LABEL(FONT_LIST = %FL, ...)

The charset attribute of the font is not supported.

Table 9. The Motif resource data types and the corresponding SCIL data types

Resource Type SCIL Data Type Comments(*) () Not implementedAtom Not implementedBoolean Boolean or

Integer: 0 = false, 1 = trueCardinal IntegerColormap Not implementedDimension Integer elements See the textint IntegerKeySym Text of one characterPixel SCIL color specification:

text, vector or integerSee section 9.3.4.

Pixmap Pixmap See section 10.4.6.Pointer Not implementedPosition Integers See the text.Screen Not implementedshort IntegerString Text or text vectorStringTable Vector of text elementsunsigned int Integerunsigned char TextVisual Not implementedWidget Text or integer See the text.WidgetList Not implementedWindow Not implementedXmButtonTypeTable Text vectorXmFontList Vector See the text.XmKeySymTable Text vectorXmNavigationType Text vectorXmString TextXmStringCharSetTable Not implementedXmStringDirection Not implementedXmStringTable Vector of text elementsXmTextPosition IntegerXmTextSource Not implementedXtAccelerators Not implementedXtCallbackList Text or vector of text elements See the text.XtTranslations Not implemented



1MRS751250-MEN

ABB Automation274

Pixel resources

Pixel resources are given as SCIL color specifications (see section 9.3.4.).

Examples:BACKGROUND = "NAVY BLUE" ;by nameFOREGROUND = (10000,20000,30000) ;by RGB valuesBORDER_COLOR = ("M", 5) ;monitor specific color # 5

XmString and XmStringTable resources

XmString resources are given as a text and XmStringTable resources as a vector oftext elements. No other properties of XmString type are implemented.

Widget resources

Widget resources are given either by a text value specifying the widget (path) name orby an integer value specifying the widget id (Currently, the only way to get a widgetid is to read the PARENT ’pseudoresource’ of a widget. See section 10.4).

Example:.CREATE W = MOTIF_SCROLLED_WINDOW(-

HORIZONTAL_SCROLL_BAR = "BAR",...)

10.4.4 Writing Widget Resources

.SET [parent/]widget.resource = expression

Assigns a value to a widget resource.



’resource’ Resource name (see section 10.3).

’expression’ An expression of the same datatype as the resource.

The value of ’expression’ is assigned to the resource. The new resource value comesinto effect immediately, except when writing the STATE and NOTIFY resources. Thevalues given to these resources come into effect when the SET_STATE method isexecuted (see section 10.3).

Examples: .SET A/B.BACKGROUND = "NAVY BLUE"Setting the background color.

.CREATE TB = MOTIF_TOGGLE_BUTTON

.SET TB.NOTIFY = FALSE

.SET TB.STATE = TRUETB.SET_STATE



ABB Automation 275

10.4.5 Reading Widget Resources

The value of a widget resource may be read as a SCIL expression of the followingformat:

[parent/]widget.resource

where

’parent’ The parent/child path to the widget.

’widget’ The name of the widget.

’resource’ The resource name. When reading the STATE and NOTIFY re-sources, the resource names must be preceded by GET_, i.e., thenames are GET_STATE and GET_NOTIFY.

The value of the expression is the value of the resource, but the resource data type hasbeen transformed to a SCIL data type according to Table 9.

Examples: The expressionA/B.WIDTHhas the value of the WIDTH resource of the widget called B of the parent A.

The command.SET A/B.WIDTH = A/B.WIDTH + 10adds 100 units to the width resource (e.g. 100 pixels if the UNIT_TYPE ispixel).

SET A.Work_Area = S.PARENTThe parent of widget S will be the work area of widget A.@STATE = TB.GET_STATE

10.4.6 Auxiliary Functions

PIXMAP(name)

Creates a pixmap (a two dimensional array of pixels) of the named library representa-tion. The function, or variables assigned values by means of the function, can be usedfor all Motif resources of the datatype pixmap.

’name’ Text. Library representation. The representation is given in one ofthe following ways:

1. Library representation name.

2. Logical library name/representation name (see the #REP_LIB command in section 7.10.

Result: Pixmap

Example:@PIX = PIXMAP("FIG_1")



1MRS751250-MEN

ABB Automation276

GIF_PIXMAP ( file_name)

GIF_PIXMAP enables the importing of GIF format images in Motif environment.

’file_name’ Text value. The name of the GIF format file to be imported. Thename is given in operating system format.

Result: Integer value, which can be used as a pixmap resource value inMotif.

Example:.CREATE_MANAGED BUTTON = MOTIF_PUSH_BUTTON(- SCIL_X = 200,- SCIL_Y = 200,- LABEL_TYPE = "PIXMAP",- LABEL_PIXMAP = GIF_PIXMAP("/USR/SC/GIF/BUTTON.GIF"))

A Motif button is created. The image drawn in the button is imported from a GIF file.

The importing of a GIF picture may fail if all the colors in the X server color paletteare reserved and the program does not find a color which is close enough to the de-sired color. Unless your graphical board supports the use of 65536 colors simultane-ously, it is not recommended to use GIF pictures which comprise a wide range ofcolors.


MicroSCADA11 SCIL Programming Guide

ABB Automation 277

11 SCIL Programming Guide

This chapter provides a programming guide for the most important SCIL tasks. Theguide gives brief instructions for accomplishing various tasks with SCIL and refers tothe sections in this manual and other manuals where the used SCIL elements are de-tailed. The following main subjects are discussed:

• Picture handling.

• Visual SCIL object handling.

• Program execution.

• Process supervision and control.

• Alarm and event handling.

• Calculations and reports.

• System configuration and communication.

• Application database management.

• Error handling.

11.1 Picture Handling

Loading Pictures

Task Use CommentsLoading a new picture !NEW_PIC command Section 7.2.Re-loading the previouspicture

!LAST_PIC command Section 7.2.

Loading an alarm picture !INT_PIC command Section 7.2.The alarm picture is processobject specific and defined inthe process object definition.

Window Handling

Task Use CommentsShowing or updating windows !SHOW command Section 7.2.Erasing windows !ERASE command Section 7.2.Showing window background !SHOW_BACK Section 7.2.Creating windows with SCIL !WIN_CREATE or

!WIN_NAMESection 7.2.

Positioning windows with SCIL !WIN_POS Section 7.2.Defining window expressionwith SCIL

!WIN_INPUT or !SHOW Section 7.2.

Defining windowrepresentation with SCIL

!WIN_REP Section 7.2.

Defining window picture withSCIL

!WIN_PIC Section 7.2.

Changing window level !WIN_LEVEL Section 7.2.Reading window attributes attribute reference:

{picture}.attributeSection 4.4.



1MRS751250-MEN

ABB Automation278

Task Use CommentsWriting window attributes .SET + attribute reference Section 7.4.

Named Programs

Task Use CommentsExecuting named programs Program call:

{picture}.name{(arguments)}Section 4.4.

Using named programs inexpressions

Program call as above. Section 4.4. Possibleonly for namedprograms which returnvalues.

Building named programswhich use arguments andreturn a value

Use the argumentsARGUMENT functions toread the arguments givenin the program call.Use the #RETURNcommand to return avalue.

The ARGUMENTfunctions aredescribed in Chapter8. The #RETURNcommand in section7.3.

Updating Pictures

Task Use CommentsCyclical updating Updating program.

Start the updating anddefine the updatinginterval with the!UPDATE command.

Section 7.2.

The updating programshould not becomprehensive.

Event based updating #ON blocks +

event object activation

Section 7.3.Event objectactivation fromprocess objectsrequires that the EEattribute is = 1.

Miscellaneous

Task Use CommentsStopping function key blinking !RESTORE Section 7.2.Hardcopy (semi-graphic) ofpicture

!SEND_PIC Section 7.2.

Closing application windows !CLOSE Section 7.2.

11.2 Visual SCIL Object Handling

Loading, Creating and Deleting Objects

Task Use CommentsLoading objects stored in aVisual SCIL object file

.LOAD command Section 7.4.

Creating objects with SCIL .CREATE command Section 7.4.Deleting objects .DELETE command Section 7.4.



ABB Automation 279

Executing Methods

Task Use CommentsExecuting methods from SCIL method call:

{object}.method{(arguments)}Section 4.4.Such methodswhich areexecutable withSCIL.

Using method calls inexpressions

Program call as above Section 4.4.Possible only formethods whichreturn values.

Building methods which usearguments and return a value

Use the argumentsARGUMENT functions toread the arguments givenin the program call.Use the #RETURNcommand to return a value.

The ARGUMENTfunctions aredescribed inChapter 8. The#RETURNcommand in section7.3.

Reading and Writing Attributes

Task Use CommentsReading attributes (functionsand features)

Attribute reference:{object}.attribute{(arg:s)}

Section 4.4.

Modifying attributes .SET command + attributereference.MODIFY command +object reference + attributelist

Section 7.4.Attributes can alsobe modified with the.LOAD and.CREATEcommands.

11.3 Program Execution

Executing Programs

Task Use CommentsExecuting commandprocedures

#EXEC, #EXEC_AFTER Section 7.3.Also started by timechannels and eventchannels.

Executing named programs inpictures

See above.

Executing methods in VisualSCIL objects

See above.

Executing a program written astext vector, e.g. in a text file

#DO commandDO functionUse READ_TEXT to reada file to a text vector

Section 7.3.Chapter 8Chapter 8

Miscellaneous

Task Use CommentsConditional execution ofprogram block

#IF ... #THEN#ELSE_IF..... #THEN#ELSE

Section 7.3.



1MRS751250-MEN

ABB Automation280

Task Use CommentsBuilding program blocks withinprograms

#BLOCKstatements#BLOCK_END

Section 7.3.

Executing different programblocks depending on thesituation

#CASE#WHEN#OTHERWISE#CASE_END

Section 7.3.

Executing program loops #LOOP#LOOP_END#LOOP_WITH#LOOP_EXIT

Section 7.3.

Pausing the program execution #PAUSE Used in exceptionalcases

User defined functions DO function withargumentsIn the program:Read arguments with theARGUMENT functions.Return values with the#RETURN command.

Chapter 8Chapter 8Section 7.3.

Stopping program execution,possibly returning a value

#RETURN Section 7.3.

11.4 Process Supervision and Control

Task Use CommentsUsing process object value inexpressions

Process object notation Section 4.3.Process objects aredescribed in theApplication Objectsmanual.

Controlling process objects #SET command +process object notation

Section 4.3. and section7.3.

11.5 Alarm and Event Handling

Task Use CommentsAlarm and event handlingfeatures

Defined in the processobjects, see theApplication Objectsmanual.

Building alarm and event lists #INIT_QUERYPROD_QUERYNEXT, PREV

Section 7.3.Chapter 8.

Printing event and alarminformation

Automatically fromprocess object orwith #PRINT commandandPRINT_TRANSPARENTif full graphic printout

Defined in processobject.Section 7.3.Chapter 8.Requires a printoutpicture.



ABB Automation 281

11.6 Calculations and Reports

Task Use CommentsExecuting CommandProcedures

#EXEC, #EXEC_AFTER+ command procedure

Section 7.3.Command proceduresdetailed in ApplicationObjects manual.Also: time channels,event channels.

Acquiring Report Data #EXEC, #EXEC_AFTER+ data object

Section 7.3.Data objects detailedin Application Objectsmanual.Also: time channels,event channels.

Reading and Using StoredData

Data object notation Section 4.3.

Editing report data #SET + data objectnotation

Section 7.3.

11.7 System Configuration and Communication

Task Use CommentsCreating base system objects #CREATE command +

LIST functionSection 7.3.Chapter 8

Defining NET lines #SET + NET line attributePO

Section 7.3.System Objects manualMay also be done inpreconfiguration

Creating communicationsystem objects

#SET + NET object anddevice creation attribute

Section 7.3.System Objects manualMay also be done inpreconfiguration

Setting system objectattributes

#SET + object notation Section 7.3.System Objectsmanual.

Starting internal DCP-NET LOAD_DCP function Chapter 8.Starting PC-NET Defining link base system

objectSee above.

11.8 Application Database Management

Task Use CommentsCreating application objects #CREATE + list data Section 7.3.

ToolsDeleting application objects #DELETE Section 7.3.

ToolsModifying application objects #MODIFY Section 7.3.

ToolsSearching among objects #SEARCH, NEXT, PREV

APPLICATION_OBJECTfunctions

Section 7.3. Chapter 8ToolsChapter 8.

Copying objects #CREATE +FETCH, PHYS_FETCH,DATA_FETCH

Section 7.3.Chapter 8Tools



1MRS751250-MEN

ABB Automation282

11.9 Error Handling

Task Use CommentsError handling policy #ERROR STOP

#ERROR CONTINUE#ERROR IGNORE

Section 7.3.

Error handling programs In pictures:Named program namedERROR_HANDLERIn Visual SCIL Objects:Error handling method.

See below.See Visual SCIL UserInterface Design.

Reading and writing errorstatus

STATUS functionSET_STATUS

Chapter 8.Status Codes manual.Argument in errorhandling programs

Error Handling in Pictures

The error handling in pictures can be defined by a named program with the nameERROR_HANDLER. When a SCIL error occurs in a picture program, theERROR_HANDLER program, if it exists, is started. The following 6 arguments aretransferred to the error handler and can be used in the named program by means of theARGUMENT functions (see the SCIL manual, Chapter 8):

• The SCIL status code (integer).

• The picture and the program where the error occurred (text) given as a picturepath starting from the main picture, for example:

.UPDATE (= the update program of the main picture)

WINDOW1/PIC_FUNC_1/WINDOW2.MY_NAMED_PROGRAM

• The erroneous SCIL line (text).

• The column position within the line (integer, may be 0).

• Current error handling policy (text), either "STOP" or "CONTINUE".

• Program line number (integer).

The error handler program is searched for in the following order:

1 The picture - main picture, window picture or picture function - where the erroroccurred.

2 The picture functions of the picture where the error occurred.

3 The parent of the picture where the error occurred.

4 The picture functions of the parent picture .

5 The parent of the parent picture, etc., up to the main picture.

The first error handler program found is executed.



ABB Automation 283

If no error handler is found, the standard picture error message is shown on the topline of the main picture. See the Status Codes manual.


MicroSCADA12 SCIL Editor

ABB Automation 285

12 SCIL Editor

This chapter describes the SCIL Editor when it is accessed from the Tool Manager orfrom other tools like Picture Editor, Command Procedure Object Definition tool andDialog Editor for Visual SCIL.

12.1 General

Figure 20. The SCIL editor as accessed from the Tool Manager

The SCIL editor is a text editor designed for editing text files and SCIL programs.The editor has ordinary editing functions and tools for assisting design of SCIL pro-gram code. The assistant tools for SCIL programming are dialogs for inserting SCILcommands, statements and functions as well as syntax checking. Figure 20 shows theSCIL editor as opened from the Tool Manager. The menu bar and the toolbar are lo-cated above the text window and below there is a status bar. The status bar shows cur-rent cursor position in terms of rows and columns. The active path is also shown in afield on the status bar. Unsaved changes in the program are indicated with a coloredpencil on the status bar. The pencil is dimmed when there are no unsaved changes.

12.2 Menus

Commands of the File menu:

New Open a new file with the default name ‘Untitled.txt’. In casethere are unsaved changes to the current file a dialog askingif changes are to be saved is shown.



1MRS751250-MEN

ABB Automation286

Open... Open an existing file. Clicking Open displays a File Chooserdialog box for selecting the file to open.

Save Save the file without changing the filename. The Savecommand acts as Save As if invoked on a new file.

Save As... Save the file. A File Chooser dialog box for choosing pathand file name is opened.

Import... Insert the contents of a text file after the current line. Opensa File Chooser dialog box for selecting the file to be im-ported.

Export... Export the whole text or the selected text. Opens a FileChooser dialog box, with a default file name ‘Exported.txt’,for selecting the file to export to.

Print Setup... On a VS local monitor this command opens a standard PrintSetup dialog provided by the Windows NT operating sys-tem.

Print… On a VS local monitor this command opens a standard Printdialog provided by the Windows NT operating system. On aVS remote monitor the current text is printed immediately.

File history commands The names and the paths of the most recently opened files.The maximum number of the file names and paths showncan be determined from the File History Length in the Op-tions menu.

More History This submenu is placed under the 5th file history commandand displays the possible commands from 6 to 20. The sub-menu is visible if File History Length is set to more than 5,and if more than 5 files have been opened after the settingwas made. The commands on the submenu do not containany mnemonics.

Exit Exit the SCIL editor. The user is informed if there areunsaved changes to the text.

The commands of the File menu differ whether the SCIL editor is opened from theTool Manager or from within another tool. When the SCIL editor is opened from theTool Manager the File menu contains the commands New, Open, Save and Save As...,while opened from within another tool these commands are replaced by the Updatecommand.

Commands of the Edit menu:

Undo Undo last executed command.

Redo Redo last executed command.

Cut Cut selected text and place on the Clipboard.

Copy Copy selected text and place on the Clipboard.

Paste Paste the text of the Clipboard at current cursor position.



ABB Automation 287

Clear Clear selected text. The cleared text is not placed on theClipboard.

Select All Select the whole text.

Comment Insert a semicolon at the beginning of the current or selectedline(s). The semicolon acts as sign for commenting and theSCIL interpreter recognises lines starting with a semicolonas a remark.

Uncomment Delete the semicolon from the beginning of current or se-lected line(s).

Indent Increase indent of current or selected line(s).

Unindent Decrease indent of current or selected line(s).

Modify All Lines|Upper Case Converts the lines to upper case letters.

Modify All Lines|Lower Case Converts the lines to lower case letters.

Modify All Lines|Capitalize Converts the first character to upper caseand the rest to lower case letters.

Modify All Lines|Left Trim Removes leading spaces from the lines

Modify All Lines|Right Trim Removes trailing spaces from the lines

Modify All Lines|Compress Spaces Replaces multiple spaces with a singlespace.

Modify All Lines|Sort Alphabetically Sorts the lines in the alphabetical order.

Modify All Lines|Sort by Length Sorts the lines in the length order.

Modify All Lines|Reverse Order Reverses the order of the lines.

Modify All Lines|Remove Duplicates Removes duplicate lines.

Find/Replace… Open a Find/Replace dialog with a field for text to find anda field for the optional replacement text.

Find Next Performs the last specified find operation from the currentcursor position.

Find Block Find subsequent blocks of code in a SCIL program. For ex.blocks delimited by a loop command.

Go To Line Move cursor to a line which line number is given in thedialog shown by the command.

Commands of the SCIL menu:

Naming Standards Open a dialog showing naming conventions for SCIL vari-ables and Visual SCIL objects / text identifiers.

Insert SCIL... Open a dialog for inserting SCIL commands, functions andobjects. The dialog shows the different categories in a tree



1MRS751250-MEN

ABB Automation288

structure. To expand a category click the plus sign in frontof the category name. Clicking an item in the tree structureshows the syntax of the SCIL code in the text field to theright in the dialog. Clicking the Insert button inserts thecode at current cursor position. Click Close to exit the dia-log.

Check Syntax Check the syntax of SCIL code. Information of no found er-rors is shown as a message. A found error is shown in adialog along with an error code and the line number of theinvalid program code. The line containing invalid syntax isshown in the text field. Edit the program and click theCheck button to verify the correction. If the correction passthe syntax check, the next error is located and shown. Whenno more errors are found, a ‘syntax checking successful’message is displayed.

Commands of the Options menu:

Assistant View Open or update read-only secondary window with a copy ofthe current program.

Status Updating On On/off option for status bar field, menu bar items and tool-bar buttons. Checked means that menu items and toolbarbuttons are enabled and the status bar fields are updated ac-cording to the current status of the program.

Toolbar Visible Toolbar visible/invisible option. Checked means toolbar isvisible.

Check Syntax at Save Toggle item for turning on or off the automatic syntaxchecking of the program during program saving. Defaultstate is off.

Compilation In Use Toggle item for turning on or off the auto-compilation of theprogram during program saving. Turning off also deletes thepossible existing compiled program. Enabled only if thecalling tool supports program compilation. Includes syntaxchecking.

File History Length Determines the maximum number of the names and thepaths, of the most recently opened files, displayed as filehistory commands under the File menu. The file historylength can be set between 0 and 20. Giving the length 0means that the file history is disabled.

Indent... Open a dialog for setting indent character count and thestate for indenting new lines.

Font|Set Font Brings up a Font Chooser for selecting the editor font. Theselected font is saved in the parameter file, and restoredwhen the editor is opened next time. VS Local and VS Re-mote monitors both have their own font settings.

Font|Enlarge Size Find the next larger point size and set the editor font.

Font|Reduce Size Find the next smaller point size and set the editor font.



ABB Automation 289

Font|Reset Font Set the editor font to the default value: Courier MediumModern 10 for VS Local monitor, and Courier Medium 14for VS Remote monitor.

Commands of the Help menu:

Shortcut Keys Shows a dialog with the sequences of keystrokes that corre-sponds to certain actions not included in the menus.

User Parameter Saving Shows information about whether tool or user specific pa-rameters are used to save the properties and geometry of theSCIL editor.

About SCIL editor Shows a dialog with Tool information and System informa-tion.

12.3 Toolbar

The toolbar of the SCIL editor is a collection of buttons corresponding to commandsfound in the menus. The toolbar is shown in Figure 21. The corresponding commandof each button is explained in Table 10.

Figure 21. Toolbar of the SCIL editor as opened from the Tool Manager

Table 10. Corresponding commands of the buttons on the toolbar. The last button‘Evaluate in Test Dialog’ is present on the tool bar when the editor isopened from the Test Dialog.

File|Exit Edit|Copy Edit|Find/Replace

File|New Edit|Paste Edit|Find Next

File|Open Edit|Comment Edit|Find Block

File|Save Edit|Uncomment SCIL|Insert SCIL

Edit|Undo Edit|Indent SCIL|Check Syntax

Edit|Cut Edit|Unindent Evaluate in Test Dialog

12.4 Opening and Closing the SCIL Editor

Opening the SCIL Editor

The SCIL Editor is opened when you select a program for editing in the Picture Edi-tor, Command Procedure object definition tool, Test Dialog or the Dialog Editor. Theprograms and the procedures for starting the program editing are described in themanuals Picture Editing, Visual SCIL User Interface Design and Application Objects.



1MRS751250-MEN

ABB Automation290

You can also open the SCIL program editor from the Tool Manager by clicking theSCIL Editor icon in the Miscellaneous page.

When the SCIL Editor is opened from a tool, you have already chosen a program forediting. If it exists, its contents is shown in the editor. If it is new, the editor is empty.

Opening Files

When you have opened the editor from the Tool Manager, you can open a text file forediting or create a new file. This possibility is usually not available when you haveopened the editor from an object tool. To open a file:

1 Click Open from the File menu. A file chooser dialox box appears.

2 Select directory from the directory tree. All files are listed as default. Fourdifferent path selection modes are supported, as described on page 205. Thedefault is MicroSCADA Relative Paths. The file list can be viewed as a list or withdetails by clicking on either the List ( ) or the Details ( ) button on the right,above the file list box.

3 Click the name of the text file, or type the file name in the data entry field belowthe file list. A file can be opened also as a read-only file by selecting the Read-onlycheck box.

4 Click Open.

To close a file and start editing of another file, open another file or click New fromthe File menu to open a new file. If the previous file was not saved, you are asked tosave the changes or abandon them.

In the File Chooser the paths can be selected in four different modes:

Application Relative Paths Path representation in the MicroSCADA path formatrelative to the current MicroSCADA applicationhome directory. The application home directory itselfcan’t be referenced.

MicroSCADA Relative Paths Path representation in the MicroSCADA path formatrelative to the MicroSCADA root directory. The Mi-croSCADA root directory itself can’t be referenced.

Logical Paths Path representation in the MicroSCADA logical pathformat.

Operating System Paths Path representation in the format used by the operat-ing system.

Creating Files

File name is given when the file is saved. If the file does not exist, a new file is cre-ated.



ABB Automation 291

Saving Files

You can save your work any time. To save a file:

1 Click Save or Save As from the File menu. The Save command saves the file withthe same name, if it already exists. Use the Save As command to save the file withanother name.

2 When selecting Save for the first time or Save As, the file chooser dialog boxappears. Select the correct folder from the directory tree and click on the file name,or type it in the Save as text box. Four different path selection modes aresupported, as described on page 205. A new folder can also be created by clickingon the Create New Folder button ( ) above the file list.

3 Click Save.

If you have opened the SCIL Editor from an object tool, save the program by choos-ing Update on the File menu.

Undo Operation

To undo the last editing operation, click Undo on the Edit menu. The undo operationrevokes the last editing operation. The maximum number of actions that can be un-done is 50.

Closing the SCIL Editor

To close the editor, click Exit on the File menu.

If you have made changes since the last time you saved the program, a dialog box ap-pears asking if you want to save changes.

12.5 Typing and Editing Programs and Texts

Typing

The basic function of the SCIL Editor compares to common text editing programs.Most keyboard keys have their natural functions. The functions of some importantkeys are explained below:

Insert toggles between insert and overwrite.

Home moves the cursor to the beginning of the line and theEnd key to the end of line.

<Ctrl>+Home moves the cursor to the beginning of the program.

<Ctrl>+End moves the cursor the end of the program or text.

← and → moves the cursor one step to the left and right respec-tively.



1MRS751250-MEN

ABB Automation292

<Ctrl>+← and <Ctrl>+→ moves the cursor to the beginning of thenext/previous word.

Tab inserts a specified number of spaces defined by theuser and moves the cursor the same number of stepsto the right.

More information on shortcut keys is found by choosing Shortcut Keys from the Helpmenu.

Selecting Text for Editing

The whole program or parts of it can be selected for moving, copying and deleting asfollows:

• To select a word, double-click it.

• To select a text section, place the cursor at the beginning of the section, press themouse button and hold it down while dragging the pointer to the end of the text.

• To select the whole program or text, press <Ctrl>+A or choose Select All fromthe Edit menu.

The selected text is shown in reversed colors. It can be moved, copied and deleted asdescribed below. You can also replace text strings in the selected section.

Copying

To copy a text within the program or from one program to another:

1 Select the text you want to copy as described above.

2 Choose Copy from the Edit menu or press the <Ctrl> and C keys at the same time(<Ctrl>+C). The text is copied to the clipboard.

3 If you want to move text from one program to another, activate the program towhich you want to copy.

4 Place the cursor at the position where you want to insert the copied text.

5 Click Paste from the Edit menu or press <Ctrl>+V.

Moving Text

To move text:

1 Select the text you want to move as described above.

2 Choose Cut from the Edit menu or press <Ctrl>+X. The selection is removedfrom the screen and placed in the clipboard.

3 If you want to move text from one program to another, activate the program towhich you want to move.

4 Click the place where you want to insert the text.



ABB Automation 293

5 Choose Paste from the Edit menu or press <Ctrl>+V.

Deleting

To delete text:

1 Select the text you want to delete as described above.

2 Click Clear from the Edit menu or press Delete key.

The selected text disappears.

Commenting

A comment in a SCIL program is a line or a part of a line marked by a comment mark(;) at the beginning. When this sign appears in a program line, the rest of the line isregarded as a comment and not executed. You can use comments, for example, to ex-plain how the program works or to prevent the execution of a program line withoutdeleting it permanently. The comment signs may be inserted and deleted using the or-dinary text editing functions. If you wish to mark several subsequent lines as com-ments, you can also use the Comment and Uncomment commands of the Edit menu.

To mark a program section as comments:

1 Select the lines you want to mark as comments, see above.

2 Click Comment on the Edit menu.

A semicolon is inserted as the first character of each line in the selection.

To remove the comment marks located in the beginning of lines:

1 Select the lines from which you want to remove the comment marks.

2 Click Uncomment on the Edit menu.

All the comment marks that are located at the beginning of the lines are removed.Semicolons located elsewhere are not removed.

Indenting

Text in paragraphs usually extends from the left margin to the right margin. A para-graph can be indented to set it off from other text. Indenting is used to increase read-ability of program code. Setting the measurement for indenting is done by choosingIndent... from the Options menu. The checkbox ‘Auto-indent enabled’ means that anew line is indented according to previous line.

To indent a section:

1 Select the lines you want to indent. If no text is selected, the current line isindented.

2 Click Indent from the Edit Menu.



1MRS751250-MEN

ABB Automation294

To unindent a section:

1 Select the lines you want to unindent.

2 Click Unindent from the Edit Menu.

Finding Text

The Find/Replace command searches for a given text in the program. It stops when itfinds the first match and shows it as a selection. To use the Find/Replace command:

1 To search a certain part of the text, select the text to be searched. Otherwise thewhole document is searched. The Find or Replace operation is always started fromthe current cursor position.

2 Click Find/Replace from the Edit menu. The dialog box shown in Figure 22appears. Moving the cursor is possible in the main window while the Find/Replacedialog box is open.

Figure 22. You can search for text that is located somewhere in the same programusing the Find/Replace command on the Edit menu.

3 In the ‘Find what:’ field, type the text you want to search for. You can eithersearch in an upward or downward direction of the program by selecting Forwardsor Backwards under Direction in the dialog. If the case of the text (uppercase/lower case) is of importance, select the check box Match Case. If a text wasselected in step 1, ‘Selection’ is selected under Scope.

4 Click Find First. If a matching text is found, the first match is shown selected inthe text window. If no matching text is found, a dialog box saying “Text notfound” appears. After the first find operation the Find First command button isreplaced with Find Next command button, which can be used for finding the nextoccurrence. Find Next may be invoked repeatedly to search for the string until youClose.

The Find Next operation in the main window is not possible while the Find/Replacedialog is open.

The last twenty items of the Find/Replace word lists are saved and restored whenclosing and opening the SCIL Editor. The lists are sorted in the chronological order,last used words first.



ABB Automation 295

Replacing Text

To replace the occurrences of a text string with another one:

1 If you wish to replace the occurrences found in a certain text section, select thesection. Otherwise the whole document is considered. The Find or Replaceoperation is always started from the current cursor position.

2 Click Find/Replace from the Edit menu. The dialog shown in Figure 23 appears.Moving the cursor is possible in the main window while the Find/Replace dialogbox is open.

Figure 23. With this dialog you can replace one text with another

3 In the first text box, type the text you want to replace, and in the second box, typethe text you want to replace it with. You can also select whether the wholedocument or the selected text section. If the case of the text is of importance, selectMatch Case. Select search direction under ‘Direction’.

4 Click Find First to find the first occurrence of the text string without replacing itimmediately. After the first find operation the Find First command button isreplaced with Find Next command button, which can be used for finding the nextoccurrence. Find Next may be invoked repeatedly to search for the string until youClose.

5 When an occurrence to be replaced is found, click Replace. This replaces theselected text and searches the next occurrence of the text string. If the found text isedited manually in the main window during a Find or a Replace operation, clickingReplace button replaces nothing, but the Find Next operation is performed.Replace All replaces all occurrences of the text string.

The Find Next operation in the main window is not possible while the Find/Replacedialog is open

The last twenty items of the Find/Replace word lists are saved and restored whenclosing and opening the SCIL Editor. The lists are sorted in the chronological order,last used words first.

Finding Blocks

If you want to go to a certain SCIL block in the program, click Find Block in the Editmenu. The Find Block command searches for the following Block commands down-wards in the program starting from the cursor:#BLOCK .... #BLOCK_END#LOOP ....#LOOP_END#CASE ....#CASE_END



1MRS751250-MEN

ABB Automation296

When a block is found, it is selected in the text window. To find another block, placethe cursor after the command that ends the previous block and then click Find Blockagain.

Finding a Line

If you want to move quickly to a certain line number:

1 Click Go To Line from the Edit menu or pressing <Ctrl>+L on the keyboard.

The dialog shown in Figure 24 appears.

Figure 24. You can move to a certain line using this dialog.

2 In the text box, type the number of the line to which you want to move and clickOK.

If the line number is invalid, the cursor is moved to the first line and if the given linenumber is too big the cursor is moved to the last line.

Importing and Exporting Text

Importing text means that the contents of a text file is inserted after the current lineexcept for the case when the cursor is located at the beginning of the text, then thetext is inserted at the beginning. To import a text file:

1 Click Import… from the File menu. The file chooser dialog box appears.

2 Select the correct folder from the directory tree and click on the name of the file.

3 Click OK.

Exporting a file means that the selected or the whole text is stored in a file. To exporta text:

1 Select a text if only part of the text is to be exported.

2 Click Export from the File menu. The file chooser dialog box appears with thedefault file name Exported.txt in the File name text box.

3 Select the correct folder from the directory tree and enter a name for the file in theFile name text box. A new folder can also be created by clicking on the CreateNew Folder button ( ) above the file list.

4 Click OK.

If there is an existing file with the same name, the user is asked to confirm overwrit-ing of the existing file.



ABB Automation 297

In the file chooser four different path selection modes are supported, as described onpage 205.

Undoing and Redoing Operations

Most editing operations can be cancelled using the Undo command, for example Cut,Copy, Paste and Replace commands. When you undo typing, undo will affect all thatwas written since the last editing operation, for example Copy, Undo, Save.

To undo an operation, click Undo from the Edit menu.

The operations that you have cancelled using Undo, can be done again. This meansthat you are also able to cancel an Undo operation. To do this click Redo from theEdit menu.

Insert SCIL Commands, Functions and Objects

This assisting tool in the SCIL editor is designed to help writing SCIL code. The dia-log below appears as the Insert SCIL... command on the SCIL menu is invoked. Thetext box to the left in the dialog contains the different categories of commands, func-tions and objects. Expand the nodes in the tree by clicking the plus sign. Subcatego-ries appear as leafs in the tree structure. Select a subcategory by clicking. When this isdone commands, functions or object definition attributes appear in the text box to theright in the dialog. The desired command, function or attribute is selected by clicking.The status bar at the bottom of the dialog displays a short description of the selectedcommand, function or attribute.

Figure 25. The Insert SCIL Commands, Functions & Objects dialog of the SCILeditor

To insert a SCIL command:

1 Place the cursor where the command is to be inserted.

2 Click Insert SCIL on the SCIL menu.

3 Expand one of the categories by clicking the plus sign in front.



1MRS751250-MEN

ABB Automation298

4 Select one of the subcategories by clicking.

5 Select a command by clicking.

6 Click Insert. The command is inserted at current cursor position. Possiblearguments are replaced by the user.

7 Repeat steps 3 to 6 to insert next command or click Close to exit the tool. Thecursor position may also be moved while the ‘Insert SCIL Commands, Functions& Objects dialog’ is open.

Syntax Checking of a SCIL Program

The syntax check, independent of current cursor position, always starts at the begin-ning of the program. A successful syntax check displays ‘Syntax checking successful’in a message box. The syntax check command itself does not alter the code, changesare made by the user. The first encountered invalid code is displayed in a dialog asshown in the picture below. The erroneous line is shown in the dialog and it is alsomade the current line of the editor. The error is corrected in the text window and thenchecked by clicking the Check button in the ‘SCIL Syntax Error’ dialog. If the cor-rection passes the syntax check, the next error is displayed. This procedure continuesuntil no more errors are found and the ‘Syntax checking successful’ message isshown. To exit the dialog while errors still exist, click Close.

Figure 26. The Syntax check command shows a dialog like this, when a syntax erroris encountered.

To check the syntax of a SCIL program:

1 Open a SCIL program.

2 Click Syntax Check on the SCIL menu. If an error is found a dialog showing theinvalid code is displayed. If no errors are found in the program code, ‘Syntaxchecking successful’ is displayed.

3 The erroneous line is shown in the ‘SCIL Syntax Error’ dialog and the line isselected in the editor.

4 In the text window, correct the invalid code and click the Check button in ‘SCILSyntax Error’ dialog. The next found error is displayed.

5 Repeat steps 3 and 4 until ‘Syntax checking successful’ is displayed in a messagebox.


MicroSCADA13 The SCIL Compiler

ABB Automation 299

13 The SCIL Compiler

13.1 General

The SCIL programs of pictures and command procedures can be compiled for betterperformance. Compiling a SCIL program means that it is converted into an operatingsystem independent format which is then executed by a so called virtual SCIL ma-chine. The compiled code is stored, in addition to the original SCIL code, in the pic-ture or in the command procedure. Once a SCIL program is compiled, the compiledversion is automatically used instead of the original SCIL code. The compilation iscontrolled by means of the corresponding tools, picture editor and command proce-dure tool.

13.2 Performance Improvement

By compiling the SCIL code the interpretation time is reduced to only a fraction ofthe original time. The total time needed to execute a SCIL statement depends howeververy much on what the statement does and hereby no single performance improve-ment between executing uncompiled and compiled SCIL code can be given. The per-fomance improvement varies between no improvement and up to 50 times faster. Twoextreme cases are shown below:

The following program is 50 times faster when compiled compared to uncompiled:

#loop_with i=1..1000 #if TRUE #Then #block #Block_End#Loop_end

The following program is not faster when compiled compared to uncompiled:

#pause 1

The picture change time of a typical single line diagram picture built with LIB500,which is compiled, is about 2/3 of the time of the uncompiled version.

13.3 Impact on SCIL Programs

In most cases, a valid SCIL program executes exactly in the same way (apart from thespeed) whether compiled or not. However, there are some rare cases that must be con-sidered:

1 A valid SCIL program may be impossible to compile.

2 A SCIL program may compile but generates a run-time error when run by theVirtual SCIL Machine.

3 The compiled and uncompiled program may generate different results.

Case nr 1 is the simplest one to handle as it is discovered during compilation. Theprogram must be corrected and recompiled. Case nr 2 is more difficult, a carefulretesting is required to point out the possible problems. Case nr 3 is the most difficultone. Fortunately, it is an almost academic case which is hard to encounter unless de-



1MRS751250-MEN

ABB Automation300

liberately written. Because of these possible incompatibilities, a compiled SCIL pro-gram must be thoroughly retested.

In most cases, the problems arise from wild usage of variable expansions. The casesare described in more detail below. Recommendations how to avoid this kind ofproblems are given as well.

A compiled SCIL program may be harder to debug, because source lines are notavailable at run-time. The error message field in the top left corner of a picture is notable to show the erroneous SCIL line (only the line number is given). The standard er-ror dialog of VS objects is also unable to display the line that caused the error. It isrecommended that a SCIL program is first debugged uncompiled, and after that com-piled to a product version.

13.3.1 Programs that do not Compile

There are two cases when a valid SCIL program does not compile:

• MMI commands do not compile. MMI commands are commands that are ad-dressed to the MMI program started by !MODULENAME command (such asthe old picture editor program PICG). In normal pictures they generate an error;896 (PICO_NO_MODULE_TO_SEND_MESSAGE). This restriction is a delib-erate choice. MMI commands are needed very seldom and it is easy to write aMMI command by mistake, e.g. by omitting character # or @ at the beginning ofa line.

• Variable expansions are used in a way that hides the program structure from thereader.

Examples of the second case:

Example 1:@CONDITION = "#IF A == B"’A’ #THEN .DO_SOMETHING

Example 2:@END = "_END"#BLOCK

.DO_SOMETHING#BLOCK’END’

Example 3:@A = "1 + "@B = ’A’ 2

13.3.2 Programs that Generate Run-time Error

There are two cases when a program runs without errors when uncompiled but notwhen compiled:

• Alias checking is always performed by the Virtual SCIL Machine regardless ofthe revision compatibility switch (NO_ALIAS_CHECKING). The SCIL pro-



ABB Automation 301

gram design must be corrected to enable compilation if the compiled programfails with error code 580 (SCIL_VARIABLE_ALIASING_ERROR).

• Variable expansions are used in a way that hides certain syntactical languageelements from the reader.

It is impossible to list all the examples of the second case, but here are some:

Example 1:@V = "AI(%INDEX)"@POWER = OBJECT:P’V’ ;Index expression hidden

This one works:

@V = "AI5"@POWER = OBJECT:P’V’

Example 2:@A = 1@B = 2@C = ’A’.’B’ ;The compiler assumes that the right hand

;expression is a VS object or window attribute;reference

13.3.3 Programs that Produce Wrong Results

If variable expansions are used in a way that hides the correct evaluation order of anexpression, the results of compiled and uncompiled program may be different.

Example:@A = "1 + 2"@B = "3 + 4"@C = ’A’ * ’B’

As uncompiled, the meaning of the third line is

@C = 1 + 2 * 3 + 4

after the expansions, which is evaluated as 1 + ( 2 * 3 ) + 4 = 11.

The compiler ’relies on what it sees’, it generates byte code which expands and evalu-ates A first, then B and finally multiplies the two. The result is (1 + 2) * (3 + 4) = 21.

13.3.4 Recommendations

To avoid the potential problems described above ( and to make SCIL programs morereadable ), following recommendations on the use of variable expansions may begiven:

• Use direct variable access instead of expansion whenever possible.

Instead of ’A’ + ’B’, write %A + %B.

Instead of "’A’", write %A ( if A has a text value ).



1MRS751250-MEN

ABB Automation302

Instead of "X’A’Z", write "X" + %A + "Z" ( if A has a text value ).

As another advantage, the direct variable access is faster than expansion even in un-compiled programs.

• Use variable expansion mainly for generating various identifiers.

Examples of ’good’ usage of expansions might be:

#SET ’LN’:PBO1 = 1 ;As an object name#SET ABC’POSTFIX’:PBO1 = 1 ;As a part of an object name

@OLD_ERROR_STATE = ERROR_STATE#ERROR IGNORE.DO_SOMETHING#ERROR ’OLD_ERROR_STATE’ ;As a command keyword value

.SET ’DIALOG’\BUTTON.TITLE = "Push me" ;As a VS object name

!NEW_PIC ’NEXT_PICTURE’ ;As a picture name

When variable expansions are used as recommended above, the compiled and uncom-piled program always behave identically. Even most cases of other ’non-pathological’(or even ’pathological’) use of expansions work as they are expected.

Examples of such cases:@V = "PBO1"#SET OBJECT:’V’ = 1

@V = "OBJECT:PBO1"#SET ’V’ = 1

@V = "DIALOG\BUTTON".SET ’V’.TITLE = "Push me".SET ’V’_2.TITLE = "Push me too"

@NAME = "ABC"@’NAME’ = %’NAME’ + 1


MicroSCADAIndex

ABB Automation

Index

Page

A

ABS....................................................................................................................................126absolute value.....................................................................................................................126accuracy................................................................................................................................20ADD_INTERLOCKED .....................................................................................................228addition...........................................................................................................................57, 58alarm buffer ..........................................................................................................................32alarm list...............................................................................................................................33alarm picture.........................................................................................................................69alarm picture queue ..............................................................................................................69AM .....................................................................................................................................249AND.....................................................................................................................................62APL ................................................................................................................................28, 29APPEND ............................................................................................................................144application......................................................................................................................27, 31application engineering ..........................................................................................................1application objects................................................................................................................25APPLICATION_OBJECT_ATTRIBUTES.......................................................................165APPLICATION_OBJECT_COUNT .................................................................................161APPLICATION_OBJECT_LIST.......................................................................................162arc.......................................................................................................................240, 241, 249ARC ...........................................................................................................................240, 241ARC_MODE......................................................................................................................249ARCCOS............................................................................................................................126ARCSIN .............................................................................................................................126ARCTAN ...........................................................................................................................126argument.......................................................................................................................55, 120ARGUMENT .....................................................................................................................177ARGUMENT_COUNT .....................................................................................................177arguments .....................................................................................................................66, 177ARGUMENTS...................................................................................................................177arithmetical operator ............................................................................................................56ASCII .................................................................................................................................133ASCII_CODE ....................................................................................................................133assignment............................................................................................................................49attribute ..............................................................................................................24, 26, 27, 31Audio alarms ......................................................................................................................228AUDIO_ALARM...............................................................................................................228

B

BACKGROUND................................................................................................................249background color................................................................................................................249background program ............................................................................................................10base system object ..........................................................................................................26, 28BCD_TO_INTEGER .........................................................................................................133BG......................................................................................................................................249BIN.....................................................................................................................................134

MicroSCADAIndex


1MRS751250-MEN

ABB Automation

BIN_SCAN........................................................................................................................136BIT.....................................................................................................................................141bit function.........................................................................................................................140bit string .......................................................................................................................22, 140bit string. ..............................................................................................................................19BIT_AND ..........................................................................................................................141BIT_CLEAR...................................................................................................................... 142BIT_COMPL.....................................................................................................................142BIT_MASK ....................................................................................................................... 142BIT_OR .............................................................................................................................141BIT_SCAN ........................................................................................................................134BIT_SET............................................................................................................................143BIT_STRING ....................................................................................................................143BIT_XOR ..........................................................................................................................141BLOCK................................................................................................................................83BLOCK_END...................................................................................................................... 83Boolean..........................................................................................................................21, 61box .....................................................................................................................................241BOX...................................................................................................................................241byte string ............................................................................................................................23

C

calendar time......................................................................................................................131Canceling in SCIL Program Editor ....................................................................................293canvas ........................................................................................239, 240, 244, 246, 259, 263CANVAS...........................................................................................................................259CANVAS CURRENT........................................................................................................259CANVAS PARENT...........................................................................................................259CANVAS ROOT ...............................................................................................................259CAP_STYLE .............................................................................................................249, 250CAPITALIZE ....................................................................................................................135CASE ...................................................................................................................................83CASE_END.........................................................................................................................83characters .............................................................................................................................16Child object..........................................................................................................................45circle ..................................................................................................................................242CIRCLE .............................................................................................................................242CLASSIFY.........................................................................................................................144CLOCK..............................................................................................................................129Close ..................................................................................................................................287CLOSE.................................................................................................................................68CLOSE_FILE ....................................................................................................................105COLLECT .........................................................................................................................144color ...........................................................................................................................251, 254COLOR......................................................................................................................254, 255COLOR_IN........................................................................................................................258command................................................................................................................................5

OR ..................................................................................................................................88command procedure.................................................................................................12, 30, 36commands ............................................................................................................................55Comment Mark ..................................................................................................................289Commenting in SCIL Program Editor................................................................................289comments .............................................................................................................................15communication function.....................................................................................................182communication system object ........................................................................................27, 29Communication System Objects ..........................................................................................29communication unit..............................................................................................................29


MicroSCADAIndex

ABB Automation

communication units ............................................................................................................27COMPILE ..........................................................................................................................177component ..........................................................................................................247, 248, 256components ........................................................................................................239, 254, 258conditional statement............................................................................................................85CONSOLE_OUTPUT........................................................................................................229constant ................................................................................................................................49CONTINUE .......................................................................................................................100control command..................................................................................................................65coordinate system...............................................................................................................239COORDINATE_SYSTEM ................................................................................................259Copying in SCIL Program Editor.......................................................................................288COS....................................................................................................................................128cosine .........................................................................................................................126, 128Create .................................................................................................................................286CREATE ..............................................................................................................90, 112, 266CREATE_FILE..................................................................................................................106CREATE_MANAGED......................................................................................................266CS.......................................................................................................................................249CSR_BOL ............................................................................................................................79CSR_EOL ............................................................................................................................79CSR_LEFT...........................................................................................................................79CSR_RIGHT........................................................................................................................79CUMULATE......................................................................................................................145CURRENT .................................................................................................................246, 247CURSOR_POS ....................................................................................................................53

D

DASH_LIST ......................................................................................................................250DASH_OFFSET ................................................................................................................251dashed line..........................................................................................................................250data object ................................................................................................................13, 30, 35data type .......................................................................................................19, 120, 225, 270DATA_FETCH..................................................................................................................169DATA_STORE..................................................................................................................170DATA_TYPE.....................................................................................................................225DATE.................................................................................................................................129date and time ......................................................................................................................132DAY...................................................................................................................................129Day of Week ......................................................................................................................129Day of Year ........................................................................................................................130DCP-NET...........................................................................................................................182DDE client..........................................................................................................................204DDE protocol ...............................................................................................................14, 209DDE Server ........................................................................................................................209DDE_CONNECT...............................................................................................................205DDE_DISCONNECT ........................................................................................................206DDE_EXECUTE ...............................................................................................................208DDE_POKE.......................................................................................................................208DDE_REAL .......................................................................................................................210DDE_REQUEST................................................................................................................207DDE_VECTOR..................................................................................................................210debugging...........................................................................................................................224DEC....................................................................................................................................135DEC_SCAN .......................................................................................................................136default path names..............................................................................................................103DELETE...............................................................................................................90, 113, 268

MicroSCADAIndex


1MRS751250-MEN

ABB Automation

DELETE_ELEMENT........................................................................................................146DELETE_FILE..................................................................................................................106DELETE_PARAMETER ..................................................................................................176Deleting in SCIL Program Editor ......................................................................................289dialog systems......................................................................................................................45dialogs....................................................................................................................................1DIRECTORY_MANAGER COPY...................................................................................187DIRECTORY_MANAGER COPY CONTENTS .............................................................188DIRECTORY_MANAGER CREATE ..............................................................................186DIRECTORY_MANAGER DELETE...............................................................................186DIRECTORY_MANAGER DELETE_CONTENTS........................................................186DIRECTORY_MANAGER EXISTS ................................................................................187DIRECTORY_MANAGER GET_ATTRIBUTES ...........................................................189DIRECTORY_MANAGER LIST .....................................................................................186DIRECTORY_MANAGER MOVE..................................................................................189DIRECTORY_MANAGER RENAME.............................................................................189DIV ................................................................................................................................57, 60division ..........................................................................................................................57, 59DL......................................................................................................................................250DO .......................................................................................................................84, 178, 251DOW..................................................................................................................................129DOY...................................................................................................................................130draw program.......................................................................................................................10DRIVE_MANAGER EXISTS...........................................................................................190DRIVE_MANAGER GET_ATTRIBUTES ......................................................................190DRIVE_MANAGER GET_DEFAULT ............................................................................190DRIVE_MANAGER LIST................................................................................................190DUMP................................................................................................................................229

E

EDIT ..................................................................................................................................135element.................................................................................................................................23ELEMENT_LENGTH.....................................................................................................145ellipse.................................................................................................................................242ELLIPSE............................................................................................................................242ELSE....................................................................................................................................85ELSE_IF ..............................................................................................................................85END_QUERY ...................................................................................................................166endpoints............................................................................................................................249ENTER ................................................................................................................................79ENTER_POS .......................................................................................................................54ENVIRONMENT.............................................................................................................229EQUAL..............................................................................................................................126equal to ................................................................................................................................61ERASE.................................................................................................................................73ERROR CONTINUE.........................................................................................................100ERROR EVENT................................................................................................................100error handling policy..........................................................................................................100ERROR IGNORE ..............................................................................................................100ERROR RAISE..................................................................................................................101ERROR STOP ...................................................................................................................100ERROR_STATE ..............................................................................................................179EVALUATE .....................................................................................................................229EVEN.................................................................................................................................128EVENT ..............................................................................................................................100event channel .................................................................................................................30, 38event list...............................................................................................................................33


MicroSCADAIndex

ABB Automation

event object ....................................................................................................................30, 39EXEC .............................................................................................................................36, 91EXEC_AFTER.....................................................................................................................92Execute...............................................................................................................................205execution time ......................................................................................................................38exit program .........................................................................................................................10EXP ....................................................................................................................................127exponent ...............................................................................................................................60exponential operator.............................................................................................................57exponents..............................................................................................................................19Export.................................................................................................................................292expression.................................................................................................................19, 50, 75expressions .......................................................................................................................5, 52

F

FALSE..................................................................................................................................21FAST_PIC............................................................................................................................68FETCH...............................................................................................................................166FG ..............................................................................................................................251, 255fictitious process objects ......................................................................................................32file ......................................................................................................................................106FILE_LOCK_MANAGER.................................................................................................199FILE_MANAGER COPY..................................................................................................192FILE_MANAGER DELETE .............................................................................................192FILE_MANAGER EXISTS...............................................................................................192FILE_MANAGER GET_ATTRIBUTES ..........................................................................193FILE_MANAGER LIST....................................................................................................191FILE_MANAGER MOVE.................................................................................................193FILE_MANAGER RENAME............................................................................................193Finding ...............................................................................................................................290FLUSH ...............................................................................................................................263FM_APPLICATION_DIRECTORY .................................................................................195FM_COMBINE..................................................................................................................197FM_COMBINE_NAME....................................................................................................198FM_DIRECTORY .............................................................................................................194FM_DRIVE........................................................................................................................194FM_EXTRACT..................................................................................................................198FM_FILE ...........................................................................................................................195FM_REPRESENT..............................................................................................................196FM_SCIL_DIRECTORY...................................................................................................195FM_SCIL_FILE.................................................................................................................196FM_SCIL_REPRESENT ...................................................................................................197FM_SPLIT_NAME............................................................................................................199font .............................................................................................................................251, 256FONT .................................................................................................................251, 256, 258font number ........................................................................................................................256FOREGROUND.................................................................................242, 245, 251, 253, 254format picture .......................................................................................................................98free type object.....................................................................................................................31FT.......................................................................................................................................251FU ......................................................................................................................................252function ........................................................................................................................55, 120FUNCTION ...............................................................................................252, 254, 262, 263function call........................................................................................................................120function key program ...........................................................................................................10functions.................................................................................................................................5

MicroSCADAIndex


1MRS751250-MEN

ABB Automation

G

GC..............................................................................................................................247, 258GET .....................................................................................................................................93GET_STATUS ..................................................................................................................230GIF_PIXMAP....................................................................................................................274global variable .....................................................................................................................35global variables ....................................................................................................................50Go To.................................................................................................................................292graphical element .......................................................................................239, 240, 248, 258graphics command .......................................................................................................65, 259graphics commands....................................................................................................239, 247graphics context .........................................................................239, 246, 247, 248, 254, 258graphics contexts................................................................................................240, 256, 263greater than ..........................................................................................................................61greater than or equal to ........................................................................................................61group....................................................................................................................................34

H

HEADER .............................................................................................................................80HELP ...................................................................................................................................80HEX...................................................................................................................................136HEX_SCAN.......................................................................................................................136HIGH .................................................................................................................................146HIGH_INDEX...................................................................................................................146history buffer........................................................................................................................33HISTORY_DATABASE_MANAGER CLOSE................................................................154HISTORY_DATABASE_MANAGER GET_PARAMETERS ........................................158HISTORY_DATABASE_MANAGER OPEN..................................................................153HISTORY_DATABASE_MANAGER QUERY ..............................................................159HISTORY_DATABASE_MANAGER READ .................................................................160HISTORY_DATABASE_MANAGER SET_ATTRIBUTES...........................................157HISTORY_DATABASE_MANAGER SET_COMMENT...............................................160HISTORY_DATABASE_MANAGER SET_CONDITION.............................................157HISTORY_DATABASE_MANAGER SET_DIRECTION..............................................156HISTORY_DATABASE_MANAGER SET_DIRECTORY ............................................155HISTORY_DATABASE_MANAGER SET_ORDER......................................................156HISTORY_DATABASE_MANAGER SET_PERIOD.....................................................154HISTORY_DATABASE_MANAGER SET_TIMEOUT.................................................157HISTORY_DATABASE_MANAGER SET_WINDOW .................................................155HISTORY_DATABASE_MANAGER WRITE ...............................................................161HOD...................................................................................................................................130HOUR................................................................................................................................130hours of day .......................................................................................................................130hours of year ......................................................................................................................130HOY...................................................................................................................................130HR_CLOCK ......................................................................................................................130

I

identifiers .............................................................................................................................17IF 85IGNORE ............................................................................................................................100Import ................................................................................................................................292IND ......................................................................................................................................28index ............................................................................................................23, 27, 31, 34, 52indexing ...............................................................................................................................23INIT_QUERY..............................................................................................................95, 168


MicroSCADAIndex

ABB Automation

initialization time..................................................................................................................38INPUT_KEY........................................................................................................................79INPUT_POS ........................................................................................................................80INPUT_VAR .......................................................................................................................81Inserting SCIL commands, functions and objects ..............................................................293INT_PIC...............................................................................................................................69integer...................................................................................................................................19INTEGER_TO_BCD .........................................................................................................137INTERP..............................................................................................................................147INVERSE...........................................................................................................................147item.......................................................................................................................................14Item name...........................................................................................................................205

J

JOIN_STYLE.............................................................................................................251, 253JS 253

K

KEY_POS ............................................................................................................................54KEYED_FILE_MANAGER..............................................................................................200

L

LAST_PIC ...........................................................................................................................69LENGTH............................................................................................................................230less than................................................................................................................................61less than or equal to..............................................................................................................61level parameter ...............................................................................................................72, 76LIB500 ...................................................................................................................................1library representation............................................................................................................78LIN.......................................................................................................................................28line......................................................................................................................243, 250, 253LINE...................................................................................................................................243LINE_STYLE ....................................................................................................................253LINE_WIDTH ...................................................................................................................253list...................................................................................................................................19, 24LIST .......................................................................................................................24, 98, 231LIST_ATTR.......................................................................................................................231LN ......................................................................................................................................127LOAD.................................................................................................................................113LOAD_DCP.......................................................................................................................182LOCATE............................................................................................................................138logical names........................................................................................................................17logical operator ..............................................................................................................56, 62logical path name ...............................................................................................................102logical representation library name ....................................................................................104LOOP ...................................................................................................................................86LOOP_END ...................................................................................................................86, 87LOOP_EXIT ........................................................................................................................88LOOP_WITH.......................................................................................................................87LOW...................................................................................................................................146LOW_INDEX ....................................................................................................................146LOWER_CASE .................................................................................................................135LS.......................................................................................................................................253LW .....................................................................................................................................253

M

main picture..........................................................................................................................10

MicroSCADAIndex


1MRS751250-MEN

ABB Automation

MAX..................................................................................................................................127MEAN................................................................................................................................148MEMORY_POOL_USAGE..............................................................................................232MEMORY_USAGE ..........................................................................................................232method .........................................................................................................................11, 268method calls .........................................................................................................................48methods................................................................................................................................26MIN ...................................................................................................................................127MINUTE............................................................................................................................130mix .............................................................................................................................254, 255MOD..............................................................................................................................57, 60MODIFY..............................................................................................................93, 114, 267MON....................................................................................................................................28monitor.................................................................................................................................68MONITOR.................................................................................................................246, 247month .................................................................................................................................131MONTH.............................................................................................................................131Motif ..................................................................................................................................265Motif Widget .....................................................................................................................266Motif widget commands ......................................................................................................65MOUSE .............................................................................................................................261mouse input........................................................................................................................261MOUSE OFF .....................................................................................................................262MOUSE ON...............................................................................................................261, 262Moving in SCIL Program Editor........................................................................................288multiplication .................................................................................................................57, 59

N

NA .....................................................................................................................................254name...............................................................................................................................27, 31NAME................................................................................................................................254named program ........................................................................................................10, 43, 44natural logarithm................................................................................................................127NET .....................................................................................................................................29New Folder ................................................................................................................287, 292NEW_PIC............................................................................................................................70NEXT.................................................................................................................................167NOD...............................................................................................................................28, 29Notify windows..................................................................................................................229

O

object ......................................................................................................................... 5, 30, 90object notation ...............................................................................................................27, 31object query .........................................................................................................................95objects..................................................................................................................................25OCT ...................................................................................................................................138OCT_SCAN.......................................................................................................................136octal form.............................................................................................................................19octal number ........................................................................................................................19ODBC functions.................................................................................................................210ODD...................................................................................................................................128ON .........................................................................................................................39, 88, 101ON ERROR .......................................................................................................................101ON KEY_ERROR .............................................................................................................101OPEN_FILE ......................................................................................................................107operands.........................................................................................................................55, 59operator..............................................................................................................55, 56, 62, 63


MicroSCADAIndex

ABB Automation

OPS_CALL........................................................................................................................179OPS_PROCESS .................................................................................................................180OR ........................................................................................................................................62OTHERWISE.......................................................................................................................83

P

PACK _TIME ....................................................................................................................131PACK_STR........................................................................................................................225parameter files ....................................................................................................................175PARENT ....................................................................................................................246, 247Parent object.........................................................................................................................45PARSE_FILE_NAME .......................................................................................................202part picture ...........................................................................................................................10PATH .........................................................................................................................102, 203PATHS...............................................................................................................................203PAUSE.................................................................................................................................89PEND OFF.................................................................................................................263, 264PEND ON ..................................................................................................................263, 264pending...............................................................................................................................263peripherals equipment ..........................................................................................................29PHYS_FETCH...................................................................................................................167PIC_NAME..........................................................................................................................53PICK ..................................................................................................................120, 148, 151picture...................................................................................................................................77Picture commands ................................................................................................................65Picture Editor .......................................................................................................................10picture handling commands..................................................................................................67picture path...........................................................................................................................42picture programs...................................................................................................................10picture queue ........................................................................................................................71pictures .............................................................................................................................1, 41PIXMAP.............................................................................................................................273point ...................................................................................................................................244POINT................................................................................................................................244Poke....................................................................................................................................204polygon...............................................................................................................................244polyline.......................................................................................................................244, 245POLYLINE ................................................................................................................244, 245POP ....................................................................................................................................263predefined picture variable...................................................................................................53PREV .................................................................................................................................167PRI .................................................................................................................................28, 29PRINT ..................................................................................................................................99PRINT_TRANSPARENT..................................................................................................220PRINTER_SET..................................................................................................................223printout ...................................................................................................................98, 99, 220printout function.................................................................................................................220process database ...................................................................................................................31process object.......................................................................................................................30process objects .....................................................................................................................32process queries .....................................................................................................................32process query........................................................................................................................95PROD_QUERY .................................................................................................................168PROGRAM..........................................................................................................................80PUSH .................................................................................................................................263

MicroSCADAIndex


1MRS751250-MEN

ABB Automation

R

RANDOM..........................................................................................................................233READ ................................................................................................................................108READ_BYTES..................................................................................................................172READ_COLUMNS ...........................................................................................................172READ_KEYS ....................................................................................................................108READ_NEXT....................................................................................................................109READ_PARAMETER ..............................................................................................124, 176READ_PREV ....................................................................................................................109READ_TEXT ....................................................................................................................174read-only ............................................................................................................................286real .................................................................................................................................19, 20RECALL_PIC......................................................................................................................71Redoing in SCIL Editor .....................................................................................................293relational operator ..........................................................................................................56, 61remote terminal unit .............................................................................................................30REMOVE ..........................................................................................................................110REMOVE_DUPLICATES ................................................................................................149RENAME_FILE ................................................................................................................110REP_LIB ...................................................................................................................104, 203REP_LIBS .........................................................................................................................203Replace ..............................................................................................................................291REPLACE..........................................................................................................................139Replacing in SCIL Program Editor ....................................................................................290report database .....................................................................................................................31reporting object....................................................................................................................31Request ..............................................................................................................................204RESET .................................................................................................................................82resource..............................................................................................................................269resource data types.............................................................................................................271resourcesœ .........................................................................................................................265RESTORE............................................................................................................................71result ..................................................................................................................................120RETURN .............................................................................................................................89REVERSE..........................................................................................................................149REVISION_COMPATIBILITY........................................................................................233ROOT ........................................................................................................................246, 247ROUND .............................................................................................................................128RTU .............................................................................................................................30, 216RTU function .....................................................................................................................216RTU_ADDR......................................................................................................................217RTU_AINT........................................................................................................................217RTU_AREAL ....................................................................................................................218RTU_ATIME.....................................................................................................................218RTU_BIN ..........................................................................................................................218RTU_HEXASC .................................................................................................................218RTU_INT...........................................................................................................................219RTU_KEY.........................................................................................................................219RTU_MSEC ......................................................................................................................219RTU_OA............................................................................................................................219RTU_REAL.......................................................................................................................220RTU_TIME .......................................................................................................................220RUBOUT.............................................................................................................................81RUBOUT_BOL...................................................................................................................81RUBOUT_CUR...................................................................................................................81RUBOUT_EOL ...................................................................................................................81


MicroSCADAIndex

ABB Automation

S

Save....................................................................................................................................287scale................................................................................................................................30, 34SCALE ...............................................................................................................................234SCALING ..........................................................................................................................261scaling factor ..............................................................................................239, 259, 261, 263SCIL.......................................................................................................................................1SCIL compiler ....................................................................................................................177SCIL coordinate .................................................................................................................260SCIL defined printout.........................................................................................................221SCIL Editor ........................................................................................................................281SCIL program.......................................................................................................................15SCIL Program Editor .....................................................................................................9, 288SCIL_HOST.......................................................................................................................234scope ..................................................................................................................................247SEARCH......................................................................................................................96, 167Searching............................................................................................................................290SECOND............................................................................................................................130SELECT .............................................................................................................................149Selecting Text.....................................................................................................................288SEND_PIC...........................................................................................................................82SEPARATE........................................................................................................................139service ..................................................................................................................................14Service name ......................................................................................................................205SET ........................................................................................................................32, 94, 115SET_CLOCK .....................................................................................................................131SET_STATUS ...................................................................................................................235SET_TIME.........................................................................................................................111SHADOW_FILE................................................................................................................204SHOW..................................................................................................................................73SHOW_BACK.....................................................................................................................74SHUFFLE ..........................................................................................................................233SIN .....................................................................................................................................128sine .............................................................................................................................126, 128snapshot variables ................................................................................................................50SORT .................................................................................................................................150SPACOM ...........................................................................................................................182SPREAD ............................................................................................................................151SQL ....................................................................................................................................210SQL statement ....................................................................................................................213SQL_BEGIN_TRANSACTION ........................................................................................215SQL_COMMIT..................................................................................................................216SQL_CONNECT ...............................................................................................................211SQL_DISCONNECT .........................................................................................................212SQL_EXECUTE................................................................................................................213SQL_FETCH......................................................................................................................213SQL_FREE_STATEMENT...............................................................................................214SQL_ROLLBACK.............................................................................................................216SQRT .................................................................................................................................128square root..........................................................................................................................128STA................................................................................................................................28, 29stacking order .......................................................................................................................72start program ........................................................................................................................10statement ............................................................................................................................4, 5statements ...............................................................................................................................5station ...................................................................................................................................30

MicroSCADAIndex


1MRS751250-MEN

ABB Automation

STATUS ....................................................................................................127, 148, 152, 180status code..............................................................................................35, 56, 101, 230, 235STOP .................................................................................................................................100STORE_PIC ........................................................................................................................71string function ....................................................................................................................133STY......................................................................................................................................28sub-picture ...........................................................................................................................10subroutine ............................................................................................................................84SUBSTR ............................................................................................................................140subtraction......................................................................................................................57, 58SUM...................................................................................................................................151SUM_NEG ........................................................................................................................152SUM_POS .........................................................................................................................152Syntax check ......................................................................................................................294SYS......................................................................................................................................28system objects ......................................................................................................................25System Objects.....................................................................................................................26system time ........................................................................................................................131

T

tangent................................................................................................................................126text .........................................................................................................................19, 22, 245TEXT.................................................................................................................................245Text Selecting ....................................................................................................................288THEN...................................................................................................................................85time ................................................................................................................................19, 21TIME .................................................................................................................................131time channel ...................................................................................................................13, 30time channels .......................................................................................................................37time function ......................................................................................................................129time of day .........................................................................................................................132time stamp............................................................................................................................35time-out..............................................................................................................................183TIMEOUT .........................................................................................................................183TIMES ...............................................................................................................................131TOD...................................................................................................................................132TODS.................................................................................................................................132TOGGLE_MOD ..................................................................................................................82topic .....................................................................................................................................14Topic name ........................................................................................................................205TRACE_BEGIN ................................................................................................................224TRACE_END ....................................................................................................................224TRACE_PAUSE................................................................................................................224TRACE_RESUME ............................................................................................................224tracing. ...............................................................................................................................261TRANSLATE ....................................................................................................................236transparent printout ............................................................................................................221TREND..............................................................................................................................152TRUE...................................................................................................................................21TRUNC..............................................................................................................................128type ................................................................................................................................27, 31Type ...................................................................................................................................287TYPE_CAST .....................................................................................................................227

U

Uncommenting...................................................................................................................289Undo ..................................................................................................................................287


MicroSCADAIndex

ABB Automation

Undoing in SCIL Program Editor.......................................................................................293unequal .................................................................................................................................61UNPACK_STR..................................................................................................................226UPDATE..............................................................................................................................72update program.....................................................................................................................10update time interval ..............................................................................................................72UPPER_CASE ...................................................................................................................135USER .........................................................................................................................246, 247user interface objects............................................................................................................25User Interface Objects..........................................................................................................41

V

value ...................................................................................................................................120variable.......................................................................................................................5, 23, 49Variable Assignment ............................................................................................................50variable expansion................................................................................................................53variable name .......................................................................................................................50variable object ................................................................................................................31, 40vector..............................................................................................................................19, 23VECTOR............................................................................................................................152vector aggregate .............................................................................................................23, 51vector function....................................................................................................................143vector variable......................................................................................................................52WEEK ................................................................................................................................132WHEN..................................................................................................................................83VIDEO_NR..........................................................................................................................53widget.................................................................................................................................265widget methods...................................................................................................................268widget resource ..................................................................................................................269widget.method ....................................................................................................................268WIN_BG_COLOR...............................................................................................................74WIN_CREATE ....................................................................................................................75WIN_INPUT........................................................................................................................75WIN_NAME........................................................................................................................76WIN_PIC .............................................................................................................................77WIN_POS ............................................................................................................................77WIN_REP ............................................................................................................................78window...........................................................................................................................72, 73window level ........................................................................................................................72Visual SCIL............................................................................................................................1Visual SCIL Commands.......................................................................................................65Visual SCIL objects .....................................................................................................44, 111word ...................................................................................................................................140workstation...........................................................................................................................29WORKSTATION_CALL ..................................................................................................181WRITE...............................................................................................................................111WRITE_BYTES ................................................................................................................172WRITE_COLUMNS..........................................................................................................173WRITE_PARAMETER.....................................................................................................175WRITE_TEXT...................................................................................................................175

X

XOR .....................................................................................................................................62

Y

YEAR.................................................................................................................................132


MicroSCADAAppendix A

ABB Automation

App. A. NEW SCIL FEATURES IN VERSION 8.4

About this Appendix

This appendix presents a summary of new SCIL features introduced in MicroSCADAversion 8.4., related to version 8.2. It also presents some compatibility notes for youwho are updating a MicroSCADA application from version 8.2. to 8.4..

Overview of New Features

User Interface Design

MicroSCADA version 8.4 introduces a new method for user interface design, the Vis-ual SCIL method. In SCIL, the new method implicates the introduction of a new ob-ject category, the Visual SCIL objects. The Visual SCIL objects are handled by a setof new SCIL commands, the Visual SCIL commands.

The Visual SCIL method is described in the manual Visual SCIL, User Interface De-sign.

DDE Client/Server Communication

MicroSCADA now supports data exchange with other Windows applications, namelythose Windows applications that support the DDE (Dynamic Data Exchange) proto-col. Most Windows applications support this protocol. By using DDE a Micro-SCADA application can read and write data produced by applications such as Micro-soft Excel and Word. Likewise, external Windows applications can access Micro-SCADA applications. In the former case, MicroSCADA works as a client, and in thelatter case as a server. The MicroSCADA client communication is implementedthrough a number of SCIL functions (the DDE Client functions in chapter 8). The Mi-croSCADA server communication is effectuated by using the DDE functions of theexternal applications. In MicroSCADA, the data handling is supported by two SCILfunctions (the DDE Server functions in chapter 8).

SQL Communication

MicroSCADA supports the access to external databases and applications by means ofSQL statements. Hence, a MicroSCADA application can access databases developedwith database management systems such as Access, Oracle and Paradox. Micro-SCADA uses the ODBC (Open database connectivity) interface and the database ac-cess is implemented by means of a number of SCIL functions (the ODBC functions).

Variable and Function Names

Variable names may be up to 63 characters long. Likewise, command and functionnames may be up to 63 characters long.



1MRS751250-MEN

ABB Automation

Data Types

A new simple data type has been implemented: byte string. Data of type byte stringcan be used in additions, and two byte strings can be compared with relational opera-tors. By means of SCIL functions, texts or bit strings can be transformed to bytestrings, and vice versa.

Vector Handling

Data of vector type can be created with a new SCIL function, namely the VECTORfunction. This enables the programmer to easily create empty and single elementvectors. Another new vector function, DELETE_ELEMENT, enables the deletion ofindividual vector elements in a vector. Text vectors can be created from data of texttype and transformed to data of text type using new SCIL functions, SEPARATE andCOLLAPSE.

Window Handling

Windows can now have attributes which are defined and assigned values by a SCILcommand (.SET). The window attributes are accessed by means of attribute refer-ences which may be used as operands in SCIL expressions.

Windows can be shown on specified levels in relation to other windows. The level isset by a new SCIL command, !WIN_LEVEL.

The creation of new windows using SCIL has been improved by a new command,!WIN_CREATE.

Variable Expansion

Besides variables, the variable object attributes and the user interface attributes (pic-ture attributes and Visual SCIL object attributes) can be used in variable expansion.

Program Arguments and Return Values

A new command, #RETURN, makes it possible to build programs that return values.This possibility applies to named programs, methods (the programs of the VisualSCIL objects) and programs executed with the new SCIL function DO. The programscan be assigned arguments (input data) which are used in the evaluation of the returnvalue. New SCIL functions (the ARGUMENT functions) have been implemented forreading the arguments.

The named program and method calls, like the DO function, can be included as oper-ands in expressions where the return value replaces the program call. Hence, they canbe used as user defined SCIL functions.



ABB Automation

Error Handling

The standard error messages shown in the upper left corner of pictures can now beavoided. Each picture may contain a named program with predefined name,ERROR_HANDLER, where the programmer can define the error handling to be usedin the picture. The ERROR_HANDLER program receives information about the er-rors.

Reading and Writing Files

Two new SCIL functions (READ_BYTES and WRITE_BYTES) enable importingand exporting binary (non-ASCII) data between MicroSCADA and other applications.

Graphics Primitives

It is now possible to easily reset the graphics contexts to default values.

Color handling has been improved in order to avoid the color palette from becomingfull.

The .MOUSE command has been given a new keyword, RELATIVE, which enablesthe programmer to relate it to the current canvas, e.g. the picture function.

Logical Paths and Libraries

The creation of new directories when using the #PATH command can be avoided byusing the new keyword, NO_CREATE.

Up to 255 directories or library files can be used in the logical path and library defi-nitions. The directories and library files can be read by new SCIL functions (PATHand REP_LIB).

Version Compatibility

Compatibility with previous versions can to some degree be selected by means of anew application attribute. The selected compatibility may be temporarily sidesteppedwith a SCIL function (REVISION_COMPATIBILITY).

Keyed File Maintenance

A new SCIL function, KEYED_FILE_MANAGER, is implemented to retrieve cor-rupted files and to perform other file maintenance procedures. This function replacesthe off-line programs SAVER and REORG.



1MRS751250-MEN

ABB Automation

Tracing of Program Execution

For debugging purposes, tracing of SCIL program execution is implemented as anumber of SCIL functions. Tracing implies recording of the SCIL statements that areexecuted.

Database Navigation

To support navigation through process and report databases, three new SCIL func-tions are implemented: APPLICATION_OBJECT_COUNT,APPLICATION_OBJECT_LIST and APPLICATION_OBJECT_ATTRIBUTES.

The functionality of the functions APPLICATION_OBJECT_LIST andAPPLICATION_OBJECT_ATTRIBUTES resembles that of the command#SEARCH used with the functions NEXT and PREV. However, there are two im-portant differences. Firstly, the new functions operate in memory, they do not read thedatabase files. Secondly, they return a vector of object names/attributes in one call.Consequently, they are much faster than the #SEARCH command followed by a loopof NEXT/PREV function calls.

Miscellaneous

Two random number generating SCIL functions (RANDOM and SHUFFLE) havebeen implemented for system and application testing and other purposes.

Compatibility with Previous Versions

Names and Words

Variable names may now be up to 63 characters long. All the characters are signifi-cant. In MicroSCADA version 8.2, only the first 10 characters were significant, andthe rest were ignored. This may result in a slight incompatibility. For example, in ver-sion 8.2, the variable names LONG_VARIABLE and LONG_VARIABL were con-sidered as identical. In version 8.4, they are two different variables.

Similarly, SCIL command and function names are now up to 63 characters long. InMicroSCADA version 8.2, only the first 10 characters were significant and the restwere simply ignored. For compatibility reasons, shortened names are still accepted ifthey are correct. For example, #CREATE_FIL is accepted for #CREATE_FILE, andPRINT_TRANSPAR or PRINT_TRAN is accepted for PRINT_TRANSPARENT.However, PRINT_TRANSPRENT is no longer accepted, though the spelling errorwent undetected in version 8.2.

HEX_SCAN, OCT_SCAN

The result of these functions is always an integer value if the argument lacks a deci-mal point. If the result falls outside the integer value range (-2.247.483.648 ...+2.147.483.647), it is shortened. In 8.2, the result was given as a real value if it wasoutside the integer value range.


MicroSCADAAppendix B

ABB Automation

App. B. ODBC ERROR CODES

About this Appendix

This appendix lists the ODBC error codes which the SCIL SQL interface may return.

General

The character string value consists of a two character class value followed by a threecharacter subclass value. A class value of “01” indicates a warning and is accompa-nied by a return code of SQL_SUCCESS_WITH_INFO. The class values other than“01”, except for the class “IM”, indicate an error and are accompanied by a returncode of SQL_ERROR. The class “IM” is specific to warnings and errors that derivefrom the implementation of ODBC itself. The subclass value “000” in any class is forimplementation defined conditions within the given class.

Note 1 Although successful execution of a function is normally indicated by areturn value of SQL_SUCCESS, the SQLSTATE 00000 also indicatessuccess.

Note 2 Although the SCILSQL interface has only eight functions the user cancall, it includes several different ODBC functions. ODBC error codesmay also refer to those hidden functions.

List of CodesSQLSTATE Error01000 General warning01002 Disconnect error01004 Data truncated01006 Privilege not revoked01S02 Option value changed01S03 No rows updated or deleted01S04 More than one row updated or deleted07001 Wrong number of parameters07006 Restricted data type attribute violation08001 Unable to connect to data source08002 Connection in use08003 Connection not open08004 Data source rejected establishment of connection08007 Connection failure during transaction08S01 Communication link failure21S01 Insert value list does not match column list21S02 Degree of derived table does not match column list22003 Numeric value out of range22005 Error in assignment22008 Datetime field overflow22012 Division by zero23000 Integrity constraint violation24000 Invalid cursor state25000 Invalid transaction state28000 Invalid authorization specification34000 Invalid cursor name37000 Syntax error or access violation

MicroSCADAAppendix B


1MRS751250-MEN

ABB Automation

40001 Serialization failure42000 Syntax error or access violationIM001 Driver does not support this functionIM002 Data source name not found and no default driver specifiedIM003 Specified driver could not be loadedIM004 Driver’s SQLAllocEnv failedIM005 Driver’s SQLAllocConnect failedIM006 Driver’s SQLSetConnect-Option failedIM009 Unable to load translation DLLIM013 Trace file errorS0001 Base table or view already existsS0002 Base table not foundS0011 Index already existsS0012 Index not foundS0021 Column already existsS0022 Column not foundS1000 General errorS1001 Memory allocation failureS1002 Invalid column numberS1003 Program type out of rangeS1008 Operation cancelledS1009 Invalid argument valueS1010 Function sequence errorS1011 Operation invalid at this timeS1012 Invalid transaction operation code specifiedS1090 Invalid string or buffer lengthS1092 Option type out of rangeS1109 Invalid cursor positionS1C00 Driver not capableS1T00 Timeout expired


MicroSCADAAppendix C

ABB Automation

App. C. PARAMETER FILES

About this Appendix

This appendix describes the parameter files used in MicroSCADA. First, it gives ageneral description, then a detailed description in BNF format.

General

Parameter files contain data in a Windows “ini-file” similar format. One parameterfile can contain 0..n number of sections as well as 0..n number of comment lines.Each section consists of a section header and 0..n number of key-value pairs, 0..nnumber of empty lines and 0..n number of comment lines.

Example:

[SECTION1]

KEY=VALUE

;this is a comment

[SECTION2]

KEY=VALUE

The section begins with the header e.g. “[section name]” and ends at another sectionbeginning or at the end of the file. The enclosing brackets ([]) are required, and theleft bracket must be in the leftmost column.

Comment lines begins with a semicolon (;).

BNF Description

ini_file ::= {comment_line}* {section}*

section ::= section_header {item}*

section_header ::= [ section_name ] new_line

section_name ::= name

item ::= new_line | key_line | comment_line

comment_line ::= comment new_line

comment ::= {blank}* ; {blank}* comment_string

comment_string ::= character_string

key_line ::= {blank}* key_name equal key_value new_line

equal ::= {blank}* = {blank}*

MicroSCADAAppendix C


1MRS751250-MEN

ABB Automation

key_value ::= character_string

character_string ::= {string_char {extended_string_char}*}

extended_string_char ::= {blank}* string_char

string_char ::= ASCII(33) .. ASCII(255)

key_name ::= name

name ::= name_char {extended_name_char}*

extended_name_char ::= {blank}* name_char

name_char ::= e_letter | digit | special_char

new_line ::= {blank}* (NT_new_line | UNIX_new_line)

NT_new_line ::= CR LF

UNIX_new_line ::= LF

blank ::= SP

e_letter ::= A .. Z | a .. z

digit ::= 0 .. 9


MicroSCADACustomer Feedback

ABB Automation

Customer Feedback

About This Chapter

This chapter contains information on how to send customer feedback and how to gettechnical support from the SA Help Desk.

Customer Feedback Database

Customer Feedback is a Lotus Notes database, using which ABB companies can re-port errors, make improvement proposals and queries related to products manufac-tured by ABB Substation Automation Oy. Customer Feedback database is connectedto the change management system of ABB Substation Automation Oy, which handlesall error corrections and improvements made to the products.

Please note that the Customer Feedback database is primarily intended for writing re-ports about released products. If you are using for example a beta release in a pilotproject, this should be clearly stated.

Writing A Customer Feedback Report

When writing a Customer Feedback report, the following general instructions shouldbe taken in consideration:

• Write the report in English.

• Write only one error report, query or improvement proposal in a Customer Feed-back report.

• If you are reporting an error, try to isolate the error as well as possible. Describethe sequence of events and actions that lead to the error. If any error messages orother debug information is provided by the system, please write it down. Includealso information of the system, e.g. a system diagram, revision information andconfiguration data.

• If you are making an improvement proposal, try to describe how the improvedfunction should work and avoid providing solutions. Information about the im-portance of the improvement, e.g. number of projects that require the improve-ment, helps us to make the decision whether and when the improvement should beimplemented.

To make a Customer Feedback report, select Feedback Report from the Create menu.This opens an empty Customer Feedback document. Fill out the fields listed below. Aquestion mark next to a field provides help for filling out the field.

1 Subject. This should contain a short description of the issue. A more detailed de-scription can be given in the Description of Feedback field below.

2 Type of Feedback: Comment/Improvement, Query or Complaint/Error.

3 Customer Information.



1MRS751250-MEN

ABB Automation

4 Reporting Information. This should contain detailed information of the product thereport is about.

5 The person who you want to send the feedback to and whether you want to get areply from that person.

6 Information related to internal handling of the report (not obligatory).

7 Category.

8 You can issue the report by clicking the Issue Feedback button. This will send thereport to the selected person and change its status to “in progress”.

Actions

When ABB Substation Automation Oy receives a Customer Feedback report, it isanalysed by a sales person or a representative of the technical support. The analysermay ask for additional information in order to completed the analysis. After the reporthas been analysed, one of the following actions is taken:

• In case of a clear error, the report is moved to the change management system ofABB Substation Automation Oy. In this system, the error is analysed in detail andcorrected in a future patch release or major release depending on the severity andimpact of the error.

• In case of an improvement proposal, the report is also moved to the change man-agement system, where it is taken as a requirement to future releases.

• In case of a query, an answer is provided.

When Customer Feedback reports are handled in the change management system, theoutcome can be one of the following:

No Actions It is decided that the report re-quires no further action. If, for ex-ample, the problem is caused by aconfiguration error, it belongs tothis category.

Will be implemented in patch/current release This result means that the correc-tion or new feature will be avail-able in the next official programrelease.

Moved to future release This result means that the newfeature will be available in somenew program release in the nearfuture.

SA Help Desk

ABB Substation Automation Oy provides a technical support service called SA HelpDesk to support local engineering centres in their system projects. The purpose of SAHelp Desk is to provide support for urgent issues such as:

• Year 2000 issues.

• High-priority issues concerning systems at customers’ sites.



ABB Automation

For other kind of technical support, please use the Customer Feedback database. SAHelp Desk is available every day from 06:00 to 21:00 Central European Time.

SA Help Desk can be contacted by telephone. The number is:

+358 50 334 1900

1mrs751250-men microscada issue date: 29.02.00 … · this chapter introduces the scil programming...

Documents