MicroSCADA Pro SYS SCIL Programming Interface (SCIL-API)

Transcription

1 MicroSCADA Pro SYS

2

3 1MRS Issued: Version: A/ MicroSCADA Pro SYS Contents Copyrights Introduction This manual Related documents Document revisions Safety Information Backup Copies Fatal Errors Instructions Making Programs SCIL-API Interface Data Types Object Interface Process Object Interface Interpreter Interface Time Data External Program Starting an External Program Initializing an External Program Program Flow of an External Program Application Extension Program Starting an Application Extension Program Initializing an Application Extension Program Program Flow of an Application External Program Integrated Program Starting an Integrated Program Initializing an Integrated Program Program flow of an Integrated Program Human-machine Interface Starting a Human-Machine Extension Program Initializing a Human-Machine Extension Program Program Flow of a Human-Machine Extension Program SCIL Functions AEP_START AEP_STOP AEP_SEND AEP_PROGRAMS IP_START

4 SYS MicroSCADA Pro 1MRS IP_STOP IP_SEND IP_PROGRAMS Example Programs External Program Application Extension Program Abbreviations Index

5 1MRS MicroSCADA Pro SYS Copyrights The information in this document is subject to change without notice and should not be construed as a commitment by ABB Oy. ABB Oy assumes no responsibility for any errors that may appear in this document. In no event shall ABB Oy be liable for direct, indirect, special, incidental or consequential damages of any nature or kind arising from the use of this document, nor shall ABB Oy be liable for incidental or consequential damages arising from use of any software or hardware described in this document. This document and parts thereof must not be reproduced or copied without written permission from ABB Oy, and the contents thereof must not be imparted to a third party nor used for any unauthorized purpose. The software or hardware described in this document is furnished under alicense and may be used, copied, or disclosed only in accordance with the terms of such license. Copyright 2010 ABB Oy All rights reserved. Trademarks ABB is a registered trademark of ABB Group. All other brand or product names mentioned in this document may be trademarks or registered trademarks of their respective holders. Guarantee Please inquire about the terms of guarantee from your nearest ABB representative. 5

6 6

7 1MRS MicroSCADA Pro SYS Introduction 1.1. This manual The SCIL API header file scil_iface.h should be included and the library file scsshr.lib should be used in the project. The Use run-time library for the project settings should be set to Multithreaded. Explanations for the abbreviations used in this manual can be found in Chapter 6. Naming conventions The naming convention is different between the C and C++ programming languages. The SCIL-API functions use C style naming convention. If the API functions are called from C++ code, a notice of error "Unresolved external..." will appear in the linking phase, if the functions are called in a default (C++) way. Use the following code to include the header file and to force the compiler to call these functions in "C style": extern "C" { #include "scil_if843.h" #include "scil_iface.h" } It is also possible to create SCIL-API files for versions older than of MS (max. 10 characters for object names, max. object index 65535). The header file scil_if843.h should not be included in that case Related documents Other useful or related manuals are: Name of the manual SYS System Objects SYS Programming Language SCIL SYS Installation and Administration Manual MRS number 1MRS MRS MRS Document revisions Version Revision number Date History A New document 7

8 8

9 1MRS MicroSCADA Pro SYS Safety Information This chapter gives information about the prevention of hazards Backup Copies It is suggested to take backup copies before making any changes, especially the ones that might have side effects. Software and data need to be copied to another place, usually to a backup tape. A DAT tape is commonly used. Backup copies make it easier to restore the application software in case of a disk crash or any other serious failure when the stored data is lost. Therefore, it is recommended that backup copies are taken regularly. There should be at least two system backup copies and two application copies. A new backup is copied over the oldest backup. This way the latest version is always available, even if the backup procedure fails. Detailed information on how to take backup copies should be delivered to the customer with the application. System Backup Usually a system backup is taken after the application is made. A backup should be taken again when changes are made to the SYS 600 system. For example, if the driver configuration or the network set-up is changed. Application Backup An application backup is also taken simultaneously with the system backup, after the application is made. A backup should be taken again when changes are made to the application.for example, if pictures or databases are edited or new pictures are added Fatal Errors A fatal error is an error that causes a break-down or a locked situation in the SYS 600 program execution. Handling In case of a fatal error: 1. Write down the possible SYS 600 error messages Shut down the SYS 600 main program. If this cannot be done in the SYS 600 Control Panel, try to end the task in Windows Task Manager. NOTE! Shutting down the base system computers by switching the power off might damage the files. 2. In Windows, the data kept in the main memory at the moment of a fatal error is placed in the drwtsn32.log file. It is placed in a system folder, for example, Winnt. Analyse and copy the data in this file. 3. Restart the system. 9

10 SYS MicroSCADA Pro 1MRS Report the program break-down together with the possible SYS 600 error messages and the information from drwtsn32.log file to the SYS 600 supplier. Status Codes Error messages in SCIL are called status codes. A list of status codes and short explanations can be found in SYS 600 Status Codes. 10

11 1MRS MicroSCADA Pro SYS Instructions 3.1. Making Programs 3.2. SCIL-API Interface There are four ways to make your own programs: 1. The first example is an EP. It can communicate in just one direction, from EP to MS. A program can be started "externally" and MS is not interested when an EP finishes its execution. When the program is started, it must call the scil_program_init function. 2. The second example is an application extension program. It can communicate in two directions: from aep to MS and from MS to aep. This program communicates just with the application it is bound to. It is started with AEP_START from an application and stopped with AEP_STOP. When the program is started it must call the scil_ae_program_init function. The program can stop itself by calling scil_ae_program_exit function. Messages to the AEprogram can be sent by AEP_SEND function. The program must call the scil_ae_program_exit function before it is going to terminate. 3. The third possibility would be an integrated program. This is a bit old-fashioned way to do things, but it can be used when you want to use a program which is not bound to any of the applications. It can communicate in two directions too. It is started with IP_START and it is stopped with IP_STOP. When the program is started it must call the scil_integrated_program_init - function. 4. The fourth possibility would be a human-machine interface. This can be used to show windows and values in windows. A human-machine program is started from a picture (*.PIC) or a VS_PICTURE_CONTAINER using the SCIL command!modulename. When the program is started it must call scil_integrated_program_init function. The SCIL-API is a quite powerful interface. There are some important things that have to be taken into consideration when using the API. The memory which the dynamic data types (vector, list, text...) allocate must be released by the user, if it is not released implicitly by functions such as: scil_set_variable() etc. The release is done by scil_dispose_value(), scil_dispose_text, scil_dispose_bit_string, scil_dispose_byte_string, scil_dispose_vector and scil_dispose_list. If it is not done (by MS or by the user) there will be a memory leak in the MS memory pool. Strings which the user gets (inside the SCIL_Value structure) by scil_get_variable, scil_get_aep_message etc. are not NULL-terminated. Because the string pointer in the SCIL_Value text type points directly to the MS memory pool, it is much better to copy the characters into a temporarily created char array than to use the string directly. It is not possible to simply add a NULL character (or any other characters) to the end of the string because the string is fixed in length. Any characters that you try to add to the string will go to the memory pool but to the wrong address. This can cause unpredictable effects, usually a crash, sooner or later. It is best to use strncpy() while copying strings to the SCIL values. Otherwise the NULL character will be copied to the SCIL string. 11

12 SYS MicroSCADA Pro 1MRS Data Types The status field in the SCIL_Value structure must be initialized to SCIL_OK_STATUS (0) before the SCIL_Value is passed to the scil_set_variable or scil_set_object functions. The SCIL-API files must be of the same version as the MS base system itself. The following data types are allowed: SCIL_NO_TYPE SCIL_INTEGER_TYPE SCIL_REAL_TYPE SCIL_TEXT_TYPE /* Dynamic */ SCIL_TIME_TYPE SCIL_BOOLEAN_TYPE SCIL_BIT_STRING_TYPE /* Dynamic */ SCIL_BYTE_STRING_TYPE /* Dynamic */ SCIL_VECTOR_TYPE /* Dynamic */ SCIL_LIST_TYPE /* Dynamic */ The data types marked with Dynamic must be released after being used. Otherwise they will cause memory leaks in the MS memory pool. The structure of SCIL_Value is: typedef struct { union { SCIL_Integer i; SCIL_Real r; SCIL_Text_Ptr s; SCIL_Time t; SCIL_Boolean b; SCIL_Bit_String_Ptr z; SCIL_Byte_String_Ptr x; SCIL_Vector_Ptr v; SCIL_List_Ptr l; } u; SCIL_Value_Type vtype; SCIL_Short_Status_Code status; } SCIL_Value; where: SCIL_Integer and SCIL_Time are long SCIL_Real is float SCIL_Boolean is unsigned char SCIL_Text_Ptr has the following structure: typedef struct { SCIL_String_Length char } SCIL_Text_Line; typedef SCIL_Text_Line length; chars[scil_max_string_length]; *SCIL_Text_Ptr; where: SCIL_String_Length is unsigned char SCIL_MAX_STRING_LENGTH is

13 1MRS MicroSCADA Pro SYS SCIL_Bit_String_Ptr has the following structure: typedef struct { SCIL_Bit_String_Length length; unsigned char bits[scil_max_bit_string_bytes]; } SCIL_Bit_String; typedef SCIL_Bit_String *SCIL_Bit_String_Ptr; where: SCIL_Bit_String_Length is unsigned short SCIL_MAX_BIT_STRING_BYTES is 8192 SCIL_Byte_String_Ptr has the following structure: typedef struct { SCIL_Byte_String_Length length; unsigned char bytes[scil_max_byte_string_length]; } SCIL_Byte_String; typedef SCIL_Byte_String *SCIL_Byte_String_Ptr; where: SCIL_Byte_String_Length is unsigned long SCIL_MAX_BYTE_STRING_LENGTH is SCIL_Vector_Ptr has the following structure: typedef struct _SCIL_Vector_Value *SCIL_Vector_Ptr; typedef struct _SCIL_Vector_Value { SCIL_Vector_Length length; char pad[2]; SCIL_Value e[scil_max_vector_length]; } SCIL_Vector_Value; where: SCIL_Vector_Length is unsigned short SCIL_MAX_VECTOR_LENGTH is SCIL_List_Ptr: typedef struct _SCIL_List_Value *SCIL_List_Ptr; Example of copying value from a text vector (v_test) element 2 to a character string (s_text): strncpy(s_text, v_test.u.v->e[1].u.s->chars, v_test.u.v->e[1].u.s->length); //copy s_text[v_test.u.v->e[1].u.s->length] = '\0'; // adding the NULL character to the character string It is more safe to check the status and the data type before accessing any SCIL_Value like: if (v_test.status == 0) if (v_test.vtype == SCIL_VECTOR_TYPE) if (v_test.u.v->e[1].vtype = SCIL_TEXT_TYPE)... // Do the copy here 13

14 SYS MicroSCADA Pro 1MRS Object Interface The following object types (SCIL_Object_Type (unsigned char)) can be written and read: SCIL_DATALOG_OBJECT 0 SCIL_COMMAND_PROCEDURE_OBJECT 1 SCIL_TIME_CHANNEL_OBJECT 2 SCIL_EVENT_CHANNEL_OBJECT 3 SCIL_PROCESS_OBJECT 4 SCIL_SCALE_OBJECT 5 SCIL_SYSTEM_OBJECT 6 SCIL_EVENT_OBJECT 7 SCIL_BASE_SYSTEM_OBJECT 8 SCIL_FREE_TYPE_OBJECT 9 There are some functions to read and to write system and application objects. The dynamic data types used in some of those functions must be given back to MS after use. The functions are: scil_evaluate_object(&obj, &result, &status); where the parameters are of the following data type &obj SCIL_Object_Reference &result SCIL_Value (see section Data Types) &status SCIL_Status_Code (int) where SCIL_Object_Reference has the following structure: typedef struct { SCIL_Object_Identifier char SCIL_Object_Index_Range } SCIL_Object_Reference; id; attr[2]; index; where SCIL_Object_Identifier has the following structure: typedef struct { SCIL_Application_Number SCIL_Object_Type #ifdef SCIL_IFACE_843 SCIL_Identifier #else char #endif SCIL_Object_Index } SCIL_Object_Identifier; apl; otype; name; name[scil_object_name_length]; index; /* Used only by scil_activate_object and scil_activate_object_with_context */ where SCIL_Identifier has the following structure (in case of MS version 8.4.3): #define SCIL_MAX_IDENTIFIER_LENGTH 63 typedef struct { unsigned char length; char chars[scil_max_identifier_length]; } SCIL_Identifier; 14

15 1MRS MicroSCADA Pro SYS where SCIL_Object_Index is long, and where SCIL_Object_Index_Range has the following structure: typedef struct { SCIL_Object_Index_Range_Type SCIL_Object_Index SCIL_Object_Bit_Index SCIL_Object_Index SCIL_Object_Bit_Index } SCIL_Object_Index_Range; rtype; first; first_bit; last; last_bit; SCIL_Object_Index_Range_Type rtype (unsigned char) can be one of the following: SCIL_NO_INDEX 0 SCIL_SINGLE_INDEX 1 SCIL_INDEX_RANGE 2 SCIL_NO_INDEX is used for Command Procedures, Data Objects, STA, STY etc. SCIL_SINGLE_INDEX is used for reference to only one Process Object at a time. SCIL_INDEX_RANGE is used for Process Objects reference to several indexes of the same logical name. SCIL_Object_Index first and last should be assigned according to the value of rtype, the first should be set to the first index in the reference. The last should be set to the last index in the reference, i.e. the first and last should be the same if the reference holds only one index or bit. The same also applies to the objects of bit streams Process Object Interface The switch state (SS) of a process object can be read using the function scil_get_switch_state(appl, &name, index, &state, &status); were the parameters are: appl SCIL_Application_Number name SCIL_Identifier index SCIL_Process_Index (unsigned short) state SCIL_Switch_State (unsigned char) status SCIL_Status_Code SCIL_Status_Code can be one of the following: SCIL_SWITCH_MIDDLE 0 SCIL_SWITCH_CLOSED 1 SCIL_SWITCH_OPEN 2 SCIL_SWITCH_FAULTY 3 The function scil_read_free_attributes(appl, &name, &pt, &dynattr, &freeattr, freeattr_length, actual_length, &status), reads the process object type, dynamic common attributes and free attributes of a process object. The parameters are: appl SCIL_Application_Number name SCIL_Identifier pt SCIL_Process_Object_Type (unsigned char) 15

16 SYS MicroSCADA Pro 1MRS dynattr SCIL_Dynamic_Common_Attributes freeattr char freeattr_length unsigned short actual_length unsigned short status SCIL_Status_Code where SCIL_Dynamic_Common_Attributes has the following structure: typedef struct { SCIL_Short_Status_Code os; // unsigned char SCIL_Time rt; // long unsigned short rm; SCIL_Time at; unsigned short am; SCIL_Boolean al; SCIL_Boolean ar; unsigned char as; SCIL_Alarm_Zone az; SCIL_Boolean ofl; } SCIL_Dynamic_Common_Attributes; where SCIL_Alarm_Zone (unsigned char) can be one of the following: SCIL_NORMAL_ALARM_ZONE 0 SCIL_LOW_ALARM 1 SCIL_HIGH_ALARM 2 SCIL_LOW_WARNING 3 SCIL_HIGH_WARNING 4 It is the caller's responsibility to interpret the structure of freeattr consistently to MS. The free attribute values are stored byte-aligned in the order of the corresponding Free object definition (depicted by PT) as follows: (AT is the attribute value type and AL the attribute length of the free attribute.) Table Attribute values and attribute length AT (type) AL INTEGER Abs(AL) bytes REAL 4 bytes BOOLEAN 1 byte (value 1 or 0) TIME 4 bytes TEXT if AL > 0, then AL bytes if AL < 0, then 1 + Abs(AL) bytes. The first byte contains the actual length of the text. BIT STRING if AL > 0, then (AL + 7) div 8 bytes if AL < 0, then 2 + (Abs(AL) + 7) div 8 bytes. The first 2-byte word contains the actual length of the bit string. The freeattr_length specifies the length of the buffer freeattr. The byte count actually required by the free attributes is returned in actual_length. If actual_length > freeattr_length, only freeattr_length bytes will be read. 16

17 1MRS MicroSCADA Pro SYS The function scil_write_free_attributes(appl, &name, &freeattr, freeattr_length, &status), writes the free attributes of a process object. Parameters with the same names as in scil_read_free_attributes() are of the same data type. freeattr_length specifies the number of bytes to be written. It may be smaller than the actual byte count required to store all the free attributes Interpreter Interface The function scil_new_context(&c, appl) or scil_new_context_with_status(&c, appl, &status) must be called before any other interpreter function is called. The context (c) has to be released by call to the function scil_dispose_context(&c) after used. The following functions are available: scil_execute_command scil_evaluate_expression scil_evaluate_expression_for_dde scil_set_variable scil_get_variable scil_define_variable scil_return_variable scil_execute_command Executes an ASCII text string (command) as a SCIL command in the given context. scil_execute_command(c, &command, &status); where the parameters are: c command status SCIL_Context_Ptr SCIL_Text_Line SCIL_Status_Code scil_evaluate_expression Evaluates a SCIL expression given as an ASCII text string in the given context. The returned value (result) must be released by the caller, if of a dynamic data type. scil_evaluate_expression(c, &expression, &result, &status); where the parameters are: expression result SCIL_Text_Line SCIL_Value 17

18 SYS MicroSCADA Pro 1MRS scil_evaluate_expression_for_dde Evaluates a SCIL expression given as an ASCII text string in the given context. INTEGER, REAL, TIME, BOOLEAN and TEXT type expressions are converted to ASCII according to DDE communication rules. Other type expressions result to bad status. scil_evaluate_expression_for_dde(c, &expression, &result, &status); scil_set_variable Defines a SCIL variable in the given context. The dynamic data in val (if any) is released by MS even if the cal fails. scil_set_variable(c, &name, &val, &status); where the parameters are: &name &val SCIL_Identifier SCIL_Value scil_get_variable Reads the value of a SCIL variable. The returned value (val) must be released by the caller, if of a dynamic data type. scil_get_variable(c, &name, &val, &status); scil_define_variable Defines a SCIL variable in the given context. After the call, the pointer in val (if any) should not be used by caller. scil_define_variable(c, name[scil_object_name_length], &val); where char name[scil_object_name_length] SCIL_OBJECT_NAME_LENGTH 10 scil_return_variable Reads the value of a SCIL variable. The returned value (val) must be released by the caller, if its value type is text, bit string, byte string, vector or list. scil_return_variable(c, name[scil_object_name_length], &val); Additional Functions for Manipulation of SCIL Data Here follows some additional functions for manipulation of SCIL data. The returned value (val) must be released by the caller, if of a dynamic data type. 18

19 1MRS MicroSCADA Pro SYS scil_get_list_attribute(l, &name, &val, &status); reads the value of the given attribute of a list. Parameters: l name val status SCIL_List_Ptr SCIL_Identifier SCIL_Value SCIL_Status_Code scil_retrieve_attribute(l, attr[2], &val, &found); reads the value of the given attribute of a list. The data type of attr[2] is char and found is SCIL_Boolean. scil_get_nth_list_attribute(l, n, &name, &val, &status); reads the name and value of the nth attribute of a list. Zero length name is returned if n is greater than the length of list. The parameter n is integer data type. scil_set_list_attribute(l, &name, &val, &status); sets the value of an attribute of a list. scil_insert_attribute(l, attr[2], &val, &found) sets the value of an attribute of a list. Creation of Text, Bit String, Byte String, Vector and List Data The above-mentioned functions return SCIL_Value data. Together with the belowmentioned procedures they provide the only means for creating entities of these data types. scil_create_text(&s, length, &status); Parameters: s length SCIL_Text_Ptr SCIL_String_Length scil_create_bit_string(&z, length, &status); where z is of data type SCIL_Bit_String_Ptr. scil_create_byte_string(&x, length, &status); where x is of data type SCIL_Byte_String_Ptr. 19

20 SYS MicroSCADA Pro 1MRS scil_create_vector(&v, length, &status); where v is of data type SCIL_Vector_Ptr. scil_create_list(&l, &status); where l is of data type SCIL_List_Ptr. Release of Text, Bit String, Byte String, Vector and List Data Every data item of these data types that has been read from SYS 600 or created by the above mentioned scil_create_xxx functions, must be released with one of these functions or given back to MS with scil_set_object, scil_set_variable, scil_define_variable, scil_set_list_attribute or scil_insert_attribute. scil_dispose_value(&val); where val is of data type SCIL_Value. scil_dispose_text(&s); where s is of data type SCIL_Text_Ptr. scil_dispose_bit_string(&z); where z is of data type SCIL_Bit_String_Ptr. scil_dispose_byte_string(&x); where x is of data type SCIL_Byte_String_Ptr. scil_dispose_vector(&v); where v is of data type SCIL_Vector_Ptr. scil_dispose_list(&l); where l is of data type SCIL_List_Ptr Time Data It is also possible to use the time and date from MS. The function scil_clock() returns SCIL_Time(long) (compare clock in MS). The following functions can be used to get seconds, minutes etc. from the SCIL_Time (all of them return int): scil_second_in(scil_time) scil_minute_in(scil_time) scil_hour_in(scil_time) scil_day_in(scil_time) scil_month_in(scil_time) 20

21 1MRS MicroSCADA Pro SYS scil_year_in(scil_time) scil_day_of_week_in(scil_time) scil_day_of_year_in(scil_time) scil_week_in(scil_time) The return from the function scil_pack_time(year, month, day, hour, minute, second) (SCIL_Time) is zero if any of the parameters is out of range. All the parameters are of data type integer. It is also possible to use the function scil_split_time(time, &year, &month, &day, &hour, &minute, &second), to get the year, month, day etc. The parameter time is of SCIL_Time, all the other integer External Program Starting an External Program An external program can be started as a normal executable file in Windows Initializing an External Program The function scil_program_init() starts the communication with a running MS. There are no parameters in this function Program Flow of an External Program It is possible to set and activate application and system objects from the EP, but it is not possible to get any return to it from MS Application Extension Program Starting an Application Extension Program An AEP must be started from MS by the command aep_start (file_name[, vector_of_arguments]). This command returns an integer: the AEP identifier. The identifier should be used later on when sending and stopping the program Initializing an Application Extension Program The function scil_ae_program_init(&appl, &ae_program_number, &scil_argument); initialize the communication with MS, where: &appl is of data type SCIL_Application_Number (unsigned char) &ae_program_number is of data type SCIL_AE_Program_Number (long) &scil_argument is of data type SCIL_Value This function must be called by an application extension program immediately after being started by MS to receive the program arguments and to establish communication with MS. An application extension program is later identified by appl and ae_program_number. The parameter scil_argument is the start parameter given in the SCIL function AEP_START(). The maximum number of arguments is

22 SYS MicroSCADA Pro 1MRS Program Flow of an Application External Program The call to scil_subscribe_to_event(appl, ae_program_number, &obj_id, SCIL_ALL_OBJECT_INDEX); must be done if we want to get event messages to the AEP. The parameters are: appl ae_program_number &obj_id SCIL_ALL_OBJECT_INDEX SCIL_Application_Number (unsigned char) SCIL_AE_Program_Number (long) SCIL_Identifier SCIL_Object_Index (unsigned short) where SCIL_Identifier has the following structure: #define SCIL_MAX_IDENTIFIER_LENGTH 63 typedef struct { unsigned char length; char chars[scil_max_identifier_length]; } SCIL_Identifier; This procedure makes a subscription to one or more events. You may specify either: event name and index event name and SCIL_ALL_OBJECT_INDEX (all indexes of the name) event name '*' and SCIL_ALL_OBJECT_INDEX (all events of the application) It may be used by an application extension program only. The function, scil_get_aep_message(appl, ae_program_number, &msg, ms0, &timeout);, reads one message from MS-AEP communication mailbox. The parameter ms0 specifies the number of milliseconds to wait if the mailbox is empty (zero value indicates no wait, negative value an infinitive wait). The parameter timeout is set to FALSE, if a message is read. Otherwise it is set to TRUE. In case of a SCIL message, the received values (msg->scil.arguments[i]) must be released by the AEP, if they are of dynamic data type. We need an endless loop to get more than one event from MS. The function scil_get_aep_message(appl, ae_program_number, &msg, ms0, &timeout); should be called in the loop. The parameters are: &appl &ae_program_number &msg ms0 &timeout SCIL_Application_Number (unsigned char) SCIL_AE_Program_Number (long) SCIL_to_EP_Message long SCIL_Boolean 22

23 1MRS MicroSCADA Pro SYS The scil message from MS (msg in the case above) has the following structure: typedef struct { SCIL_to_EP_Message_Type mtype; union { SCIL_to_EP_SCIL_Message scil; SCIL_to_EP_Event_Message event; SCIL_EP_to_EP_Message ep; } u; } SCIL_to_EP_Message; The mtype (long) can be one of the following: SCIL_EP_MESSAGE_NONE (0) SCIL_EP_MESSAGE_SCIL (1) SCIL_EP_MESSAGE_EVENT (2) SCIL_EP_MESSAGE_EXIT (3) SCIL_EP_MESSAGE_EP (4) The message type SCIL_EP_MESSAGE_SCIL has the following structure: typedef struct { int count; SCIL_Value arguments[scil_max_ep_message_arguments]; } SCIL_to_EP_SCIL_Message; where count is the number of arguments given in the MS function AEP_SEND (aep_number[, (argument1, argument2,..., argument31)]). The following code checks if the data type of the first argument is integer. if (msg.u.scil.arguments[0].vtype == SCIL_INTEGER_TYPE) // do something It is also possible to communicate between two AEP:s by using the function scil_send_aep_message(apl, aepn, &msg, length, &status). The parameters are: apl aepn &msg length &status SCIL_Application_Number SCIL_AE_Program_Number const void unsigned char SCIL_Status_Code The receiving program (defined by apl and aepn) reads the message with procedure scil_get_aep_message. The message is received as a SCIL_EP_MESSAGE_EP type message. The length of the message (length) should be <=255 bytes. 23

24 SYS MicroSCADA Pro 1MRS Integrated Program Starting an Integrated Program An IP must be started from MS using the SCIL function IP_START(IPN, file_name). It is not possible to send any parameter in the start program to an IP Initializing an Integrated Program The function scil_integrated_program_init(&argument), where the parameter is the programs identifier IPN. It must be called to start the communication with MS Program flow of an Integrated Program It is possible to send parameters to an IP using the SCIL function IP_SEND(IPN[, argument1, argument2,... argument31]). The communcation between MS and IP is quite similar to AEP. The function scil_get_ip_message(ipn, &msg, ms0, timeout) has to be used instead of scil_get_aep_message(). It is also possible to send messages from one IP to another, using the function scil_send_ip_message(ipn, &msg, length, &status); where the parameters are: ipn &msg length &status SCIL_Integrated_Program_Number const void unsigned char SCIL_Status_Code The receiving program (defined by ipn) reads the message with procedure scil_get_ip_message. The message is received as a SCIL_EP_MESSAGE_EP type message. The length of the message (length) should be <=255 bytes Human-machine Interface Previously the Human-Machine Interface (HMI) was called Man-Machine Interface (MMI). Therefore MM has been used as a shortening for Man-Machine in the SYS 600 programming terminology Starting a Human-Machine Extension Program A human-machine program (which is an integrated program) is started from a picture (*.PIC) or a VS_PICTURE_CONTAINER using the SCIL command!modulename which has the following syntax:!modulename program program The integrated program to be started Initializing a Human-Machine Extension Program When a human-machine extension program is being started by MS, it must first initialize itself, using the function scil_integrated_program_init(&argument). The program argument of a human-machine program is its monitor number which is used later. 24

25 1MRS MicroSCADA Pro SYS Program Flow of a Human-Machine Extension Program A human-machine program should only respond to events that it gets from the picture. This means that it should always wait on the function scil_get_mm_message(m, &msg) and respond according to the messages it receives from the picture. The parameters are: m &msg SCIL_Monitor_Number (unsigned char) SCIL_MM_Message where SCIL_MM_Message has the following structure: typedef struct { SCIL_MM_Message_Type mtype; union { SCIL_Text_Line command; SCIL_MM_Input_Descriptor mm_input; } u; } SCIL_MM_Message; where SCIL_MM_Input_description has the following structure: typedef struct { char name[scil_window_name_length]; SCIL_Value val; } SCIL_MM_Input_Descriptor; where SCIL_WINDOW_NAME_LENGTH is 10 Possible messages: SCIL_MM_COMMAND SCIL_MM_INPUT SCIL_MM_EXIT SCIL_MM_QUIT General scenario: In response to the commands received, the human-machine program can use the following appropriate functions: scil_show_window scil_show_value_in_window scil_erase_window scil_get_picture_variable scil_put_picture_variable After using the functions above, the message has to be acknowledged using the function scil_acknowledge_mm_message except when the command is SCIL_MM_QUIT (see description below). 25

26 SYS MicroSCADA Pro 1MRS Response to the messages: SCIL_MM_COMMAND When a human-machine program is active, all commands which are issued in the picture and are not recognized as SCIL commands, are passed to the human-machine program in the command variable part of the SCIL_MM_Message data structure. After doing what has to be done using the functions listed above, the command has to be acknowledged using scil_acknowledge_mm_message(). SCIL_MM_INPUT Using this function it is possible to send user input from the picture to the humanmachine program. On the SCIL side, this message is generated using the INPUT command. The user input is received by the human-machine program as a SCIL_MM_INPUT message in the mm_input structure of the message. SCIL_MM_EXIT When this message is received, the human-machine program can use the functions listed above. The command has to be acknowledged using scil_acknowledge_mm_message(). SCIL_MM_QUIT When this message is received, the human-machine program should quit immediately and not acknowledge the message. 26

27 1MRS MicroSCADA Pro SYS SCIL Functions 4.1. AEP_START This chapter describes SCIL functions related to SCIL-API. These functions are used to start, stop, and send a message to an application extension program (AEP). AEP_START (name {, argument }) Starts an Application Extension program. 'name' Text value containing the (path) name of the program to be started, e.g. "C:\PROGRAMS\AEP". 'argument' Optional argument to the AE program, may be of any SCIL data type. Value: Integer. The AEP identification number of the started program AEP_STOP AEP_STOP (n) Stops an Application Extension program (by sending an exit message to it). 'n' Integer value. The AEP identification number of the program to be stopped. Value: Integer value: The status code of the operation. 0 = OK AEP_SEND AEP_SEND (n {, argument }* ) Sends data to an Application Extension program. 'n' Integer. The AEP identification number of the program which will receive the data data. 'argument' Up to 31 values of any SCIL data type. The data to be sent to the AE program. Value: Integer value. The status code of the operation. 0 = OK AEP_PROGRAMS This function is available in MS version and later. AEP_PROGRAMS ( apl ) This function returns information about AEP programs currently running. apl integer value, application number to be queried (0 = current application) Value: a vector describing the running AEP programs. Each element of the returned vector provides information of one extension program invocation as a list value with following attributes: 27

28 SYS MicroSCADA Pro 1MRS PROGRAM_NUMBER Integer AEP program number returned by AEP_START START_COMMAND Text the command that was used to start the program in AEP_START ARGUMENT Any type the SCIL argument given to the program when started START_TIME Time the time the program was started PROCESS_NAME Text the name of the executable, e.g. "topcal.exe" PROCESS_ID Integer the process ID (PID) of the executing process 4.5. IP_START IP_START ( ipn, start_command ) Starts an integrated program. ipn Integrated Program Number, integer start_command Text, "DOS command line" to start the program Value: SCIL status code 4.6. IP_STOP IP_STOP ( ipn ) Stops an integrated program (by sending exit message to it). ipn Integrated Program Number, integer Value: SCIL status code 4.7. IP_SEND IP_SEND ( ipn {, arg1,.., argn} ) Sends a message to an IP. ipn Integrated Program Number, integer arg1.. argn Any SCIL values, up to 31 values Value: SCIL status code 4.8. IP_PROGRAMS IP_PROGRAMS This function is available in MS version and later. This function returns information about IP programs currently running. Value: a list with the same attributes as those returned by AEP_PROGRAMS. 28

29 1MRS MicroSCADA Pro SYS Example Programs 5.1. External Program Here are some examples of extension programs written with SCIL API. The first example is an external program. It can communicate just to one direction, from external program to SYS 600. Program can be started "externally" and SYS 600 is not interested when an external program finishes its execution. When the program is started, it must call scil_program_init function. #include <stdio.h> #include <string.h> #include "scil_iface.h" /* * * This example demonstrates the use of the * scil_evaluate_expression. * * When compiling this code, the project settings must include * the following in the "Code generation" choise of the C/C++ * page. * * Struct member alignment: 8 bytes * * Use run-time library: "debug multithreaded" or * "multithreaded" * * This test code must be linked with the scsshr.lib that comes * with the API. * * TK / 1998 * */ #define TEST_EXPR "SYS:BSV" void main() { SCIL_Context_Ptr c; SCIL_Status_Code status; SCIL_Text_Line expr; SCIL_Value v; scil_program_init(); // Create the SCIL context scil_new_context_with_status(&c, 0, &status); expr.length = strlen(test_expr); // The strings in scil api are not NULL terminated. strncpy(expr.chars, TEST_EXPR, expr.length); 29

30 SYS MicroSCADA Pro 1MRS scil_evaluate_expression(c, &expr, &v, &status); printf("scil_value type: %d", v.vtype); switch(v.vtype) { case SCIL_INTEGER_TYPE: // Do something... break; } // Important! // If the scil value is of dynamic datatype, the // contents of the value must be deallocated. // Otherwise it will cause a memory leak in the // MicroSCADA memory pool. scil_dispose_value(&v); } // The context is not needed any more and the // allocated resources must be released. scil_dispose_context(&c); 5.2. Application Extension Program The second example is an application extension program. It can communicate to two directions: from aep to MS and from MS to aep. An aep program communicates just with the application it is bound to. It is started with AEP_START from an application, and stopped with AEP_STOP. When the program is started, it must call scil_ae_program_start function. Messages to the AE-program can be sent by AEP_SEND function. AEP_STOP SCIL function sends SCIL_EP_MESSAGE_EXIT message to the aep. In responce to this message, aep calls scil_ae_program_exit function and terminates. #include <stdio.h> #include "scil_iface.h" /* * * This example code demonstrates the use of MicroSCADA * events. * * When compiling this code, the project settings must include * the following in the "Code generation" choise of the C/C++ * page. * * Struct member alignment: 8 bytes * * Use run-time library: "debug multithreaded" or * "multithreaded" * * This test code must be linked with the scsshr.lib that * comes with the API. * * TK / 1998 * */ 30

31 1MRS MicroSCADA Pro SYS main() { SCIL_to_EP_Message msg; SCIL_Boolean timeout; long ms0 = ; SCIL_Application_Number appl; SCIL_AE_Program_Number ae_program_number; SCIL_Value argument; FILE *testfile; /* This program must be started with AEP_START from MicroSCADA. This AE-program will receive its AEP-number and the possible arguments by this function call. */ scil_ae_program_init(&appl, &ae_program_number, &argument); /* The events that we are waiting for are defined here. */ scil_subscribe_to_event(appl, ae_program_number, "* ", SCIL_ALL_OBJECT_INDEX); // This is only for testing purpose... testfile = fopen("c:\\test.txt", "w"); if (testfile == NULL) { scil_ae_program_exit(appl, ae_program_number); return(1); } for (;;) { scil_get_aep_message(appl, ae_program_number, &msg, ms0, &timeout); switch (msg.mtype) { case SCIL_EP_MESSAGE_NONE: fprintf(testfile, "%s\n", "SCIL_EP_MESSAGE_NONE"); fflush(testfile); break; case SCIL_EP_MESSAGE_EP: fprintf(testfile, "%s\n", "SCIL_EP_MESSAGE_E"); fflush(testfile); break; case SCIL_EP_MESSAGE_SCIL: fprintf(testfile, "%s\n", "SCIL_EP_MESSAGE_SCIL"); fflush(testfile); /* * If the SCIL_Value in this type of SCIL_Message * is of dynamic * datatype, it must be deallocated after use! */ break; 31

32 SYS MicroSCADA Pro 1MRS case SCIL_EP_MESSAGE_EVENT: fprintf(testfile, "%s\n", "SCIL_EP_MESSAGE_EVENT"); fflush(testfile); break; case SCIL_EP_MESSAGE_EXIT: fprintf(testfile, "%s\n", "SCIL_EP_MESSAGE_EXIT"); scil_ae_program_exit(appl, ae_program_number); fclose(testfile); return(0); break; } default: break; } } return(0); 32

33 1MRS MicroSCADA Pro SYS Abbreviations Abbreviation AEP EP HMI IP IPN MMI MS Description Application Extension Program External Program. In SCIL-API function and structure names, this term sometimes refers to an extension program of any kind (EP, AEP, IP, or HMI). Human-Machine Interface Integrated Program Integrated Program Number Man-Machine Interface MicroSCADA. It is a computer-based, programmable and distributed Supervisory Control and Data Acquisition (SCADA) system. 33

34 34

35 1MRS MicroSCADA Pro SYS Index Symbols!MODULENAME...24 &ae_program_number...21 &appl...21 &scil_argument...21 A AEP_SEND...11 AEP_START...11 Aep_start...21 AEP_START()...21 AEP_STOP...11 AE-program...11 Application backup...9 Application Extension Program...21 B Backup copy...9 E Event name...22 F Fatal error...9 H Header file...7 I Initializing an AEP...21 Initializing an EP...21 IP_START...11, 24 IP_STOP...11 M MS memory pool...11 N Naming convention...7 P Program Flow of an EP...21 S Scil_ae_program_init...21 SCIL_ALL_OBJECT_INDEX...22 SCIL_BASE_SYSTEM_OBJECT

36 SYS MicroSCADA Pro 1MRS SCIL_Bit_String_Length SCIL_Bit_String_Ptr SCIL_Boolean SCIL_Byte_String_Length SCIL_Byte_String_Ptr SCIL_COMMAND_PROCEDURE_OBJECT SCIL_DATALOG_OBJECT Scil_dispose_bit_string Scil_dispose_byte_string Scil_dispose_list Scil_dispose_text Scil_dispose_value Scil_dispose_vector SCIL_EP_MESSAGE_EP Scil_erase_window SCIL_EVENT_CHANNEL_OBJECT SCIL_EVENT_OBJECT SCIL_FREE_TYPE_OBJECT Scil_get_aep_message Scil_get_mm_message Scil_get_picture_variable Scil_get_variable SCIL_Identifier SCIL_INDEX_RANGE SCIL_Integer Scil_integrated_program_init Scil_integrated_program_init - function SCIL_MAX_BIT_STRING_BYTES SCIL_MAX_BYTE_STRING_LENGTH SCIL_MAX_STRING_LENGTH SCIL_MAX_VECTOR_LENGTH SCIL_MM_COMMAND... 25, 26 SCIL_MM_EXIT... 25, 26 SCIL_MM_INPUT... 25, 26 SCIL_MM_Input_description SCIL_MM_QUIT... 25, 26 SCIL_NO_INDEX SCIL_Object_Identifier SCIL_Object_Index SCIL_Object_Index_Range SCIL_Object_Index_Range_Type SCIL_Object_Reference SCIL_Object_Type SCIL_OK_STATUS SCIL_PROCESS_OBJECT Scil_program_init()

37 1MRS MicroSCADA Pro SYS Scil_put_picture_variable...25 SCIL_Real...12 SCIL_SCALE_OBJECT...14 Scil_set_variable...11, 12 Scil_show_value_in_window...25 Scil_show_window...25 SCIL_SINGLE_INDEX...15 SCIL_String_Length...12 Scil_subscribe_to_event...22 SCIL_SYSTEM_OBJECT...14 SCIL_Text_Ptr...12 SCIL_Time...12 SCIL_TIME_CHANNEL_OBJECT...14 SCIL_Value...12 SCIL_Vector_Length...13 SCIL_WINDOW_NAME_LENGTH...25 SCIL-API...11, 12 SCIL-API files...7 Starting an AEP...21 Starting an EP...21 Status codes...10 System backup...9 V VS_PICTURE_CONTAINER...11, 24 37

38

39

40 Contact us ABB Oy Substation Automation Products P.O. Box 699 FI Vaasa FINLAND Tel Fax MRS A/ Copyright 2010 ABB. All rights reserved.