[Note: this text version is only for web crawler.
Click HERE: PUBLICATIONS to access high quality PDF version ] 

Copyright © 2011 Artzat Consulting. Photos modified for confidentiality or illustration clarity.

Best Viewed in Mozilla Firefox


SCADAWARE® System Design Manual 1 Dec 2001 - Preliminary TEST Automation & Controls SCADAWARE® DOCUMENT 1010-05 SCADA SYSTEM DESIGN MANUAL (Preliminary PDF version by AMZ Dec 11 2001) 1 SCADAWARE SYSTEM OVERVIEW 1.1 INTRODUCTION This document provides basic information on the technical design and operational concepts of TEST INC. SCADAWARE systems. Information on the system hardware components, software features, and system configuration options are presented at an introductory level. The intent is to acquaint technical users not familiar with the system with the features and benefits of the system in typical remote data acquisition situations. It is important to note that any SCADA system is a system, and the proper operation of all components is necessary for the system to do its job. Understanding the functions of each subsystem is essential to the proper application and operation of the unit. Other documents must be used to supplement the information contained herein. The TEST SCADA PROTOCOL COMMAND REFERENCE contains information on all commands used to operate the program. Also, the hardware manuals for the various configurations must be used to get particular information on the PC, interface boards, modems, printers, and other hardware used in the system. The SCADAWARE software program was written by Total Engineering Services Team, Inc, New Orleans, La, USA, and is a totally copyrighted work with all rights reserved. The program was developed and written by Arthur M. Zatarain and Corey Moragas for TEST Inc. The program released as of December 1994, was written in Borland Pascal Version 7, in both DPMI and real mode versions. SCADAWARE uses components of the Object Professional and Async Professional Library from TurboPower Software, and graphics primitives from Genus Microprogramming. Note: This version of the SCADAWARE SYSTEM DESIGN CONCEPTS contains information on TEST's products as of Dec 1, 1994. Versions prior to this date may not have all of the features described in this manual. Contact TEST for information on upgrading an existing system. 1.2 TEST'S SCADA HISTORY TEST has been installing various types of control and telemetry equipment since 1970. Older SCADA systems were designed around existing RTU and PLC equipment which often wasn't suited to oilfield and industrial installations. Extensive modification and In almost all cases, the units prior to 1988 were made by a major manufacturer and configured by TEST for each particular installation. Often, the system was affected by compromises that were the result of using a completed unit that best fit the application. It was difficult and expensive to get these standard systems to work in an offshore environment. Sophisticated installations required pre-engineered systems using extremely SCADAWARE® Command Reference Manual 1 Dec 2001 - Preliminary TEST Automation & Controls SCADAWARE® DOCUMENT 1020-05 TSP COMMAND REFERENCE MANUAL (Preliminary PDF version by AMZ Dec 11 2001) 2.1 INTRODUCTION TO TSP ............................................................................................ 6 2.2 SCADAWARE COMMAND PROMPT........................................................................ 6 2.3 COMMAND LINE FORMATS ..................................................................................... 7 2.4 COMMAND LINE PARSING....................................................................................... 7 2.5 COMMAND PROCESSING.......................................................................................... 8 2.6 COMMAND LINE PARAMETERS.............................................................................. 8 2.7 MULTIPLE COMMANDS PER LINE.......................................................................... 8 2.8 AUTO CMD EXECUTION FOR ALL RTUS............................................................... 9 2.9 MENUS......................................................................................................................... 10 2.10 TASK REFERENCES .................................................................................................. 10 2.11 COMMAND RESPONSES .......................................................................................... 10 2.12 COMMAND FILES AND PROCEDURES ................................................................. 11 2.13 COMMAND LINE COMMENTS ............................................................................... 12 3.1 ALPHABETICAL COMMAND SUMMARY ............................................................ 13 3.2 SCADAWARE LITE RESTRICTIONS ...................................................................... 16 ACK Clear First Out Alarm (2) ...................................................................................... 17 AGA3 Recalculation of AGA-3 Meter Channels (1) ..................................................... 17 AGENDA Time of Day Procedure Control (2) .............................................................. 18 ALERT Signal that RTU Needs Attention (1).......................................................... 20 ATTAch Attach Console to Another Task's Serial Port (2) ......................................... 20 BACKDROP Graphic Screen Display Initialization (1)............................................. 21 BLOCK Transmit Command To Remote Unit (2) ....................................................... 21 BOX Draw Textmode Box on Display (1) ..................................................................... 22 BREAK Send Timed Break Signal Over Comm Line (2)........................................... 22 BYE Terminate RTU Communications Session (1).................................................... 23 CAL Calibrate Channel With Rapid Local Display (1) ................................................ 23 CALC Access TSP Expression Evaluator (2) .............................................................. 24 CALL Attach With Local Echo (2) .................................................................................. 25 CHANGE Modify Mode Settings Options for Channel Range (2) ............................. 25 CLEAR Clear Totalizers and Counter Channels (2) .................................................... 26 CLREOL Clear Display to End Of Line (1) ............................................................. 27 CLS Clear Display Screen (1) ........................................................................................ 27 CONFIG Screen Oriented System Configuration (3) ................................................ 27 SCADAWARE® Command Reference Manual 2 Dec 2001 - Preliminary COPY Duplicate DOS Files (2) ..................................................................................... 28 CURSOR Locate and Control Display Cursor (1) ....................................................... 29 DATA Reply from SCAN for Data Values (2) .............................................................. 29 DATE Set System DOS Date (2).................................................................................. 30 DEL Delete DOS File (2) ............................................................................................... 31 DIAL Make Dial-Up Connection to Remote Unit (2)................................................... 31 DIR Display DOS File Directory (1).............................................................................. 32 DISABLE Temporary Alarm Disable for Channel Range (2) ..................................... 32 DISCONNECT Packet Radio Modem Disconnection (1) ........................................... 32 DISPlay Display Channel Data (1) ................................................................................ 33 DRAW Draw Graphic Line on Display (1)................................................................ 33 DUMP Show I/O, RTU, Variable Data, etc. (1)............................................................. 34 ECHO Send Text String to Comm Line (1)................................................................... 34 EDIT Access Internal Text Editor (2) ........................................................................... 35 ELSE Conditional Statement Processing (1).............................................................. 37 ENABLE Re-enable Channels Affected by Disable Command (2) .......................... 37 ENDIF End of Conditional Statement Processing (1) ................................................ 37 ENTRY Screen Oriented Data Entry and Display (1) ............................................. 37 EXEC Execute a DOS Command, Including DOS itself (2) ...................................... 39 FAX FAX Report Generation and Control (1) ............................................................. 40 FILE DOS File Output and Management Functions (2) ............................................. 41 FLAG Manipulate System Wide Control Bit Flag (2)......................................... 42 FONT Graphic Font Control (1) ................................................................................ 43 FORCE Send Command Line to Another Task (2) ..................................................... 43 FORM Real-Time Screen Form Display (1)............................................................... 44 GOSUB Subroutine Call (2) .......................................................................................... 46 GOTO Branch to Program Label (1) ............................................................................. 47 GROUP Callout Group Control (2) ................................................................................ 49 HALT Terminate SCADAWARE and Return to DOS (2) .......................................... 50 HANGUP Disconnect Communications Line (1) ......................................................... 50 HAYES Process Hayes Modem Command Line (1) .................................................. 50 HELP Display Help on RTU commands (1). ................................................................. 51 HOLD Set Channel Holding Status (2) .......................................................................... 52 HORN Annunciator Horn Control (2) ............................................................................ 52 IF Conditional Processing Statement (1) ..................................................................... 53 IMAGE Automatically Save Values to Disk (1)............................................................ 53 INPUT Enter Channel Value or String Data (1)........................................................... 54 KEY Temporary Control of Multi-Drop Modem (1)................................................. 55 LET Alternate to CALC Command (2). .......................................................................... 55 LIBrary Load Command File Library (1) ....................................................................... 56 LINK Program and Control Comm links (2) ................................................................. 56 LOCAL Declare Local Variables (1) .............................................................................. 58 LOG Control and Display of Logged Data (2) ............................................................. 58 SCADAWARE® Command Reference Manual 3 Dec 2001 - Preliminary LOGON Access Password Security (0)........................................................................ 59 MAP Open Architecture Data Channel Mapping Control ...................................... 59 MENU Control Main and User Menus (1) .................................................................... 60 MONITOR Watchdog Timer Monitor Control (2)......................................................... 61 MOUSE Microsoft Compatible Mouse Control (1) .................................................... 61 MSG Display Message on Local Console (1) ............................................................... 62 PAINT Transparent Graphic Image Display (1) ......................................................... 62 PASSWORD Access Password Setups (3) ................................................................. 62 PAUSE Display Message and Pause for Confirmation (0)......................................... 63 PHONE Set the dial out Phone Number or Radio Call Sign (2)............................. 64 PLAY Audio Subsystem Control (1) .......................................................................... 64 POLL RTU Poll Control (2) ............................................................................................. 66 PORT Set and Read PC Output Port (2) ..................................................................... 67 PRC Process Packet Radio Controller Command (1)................................................. 67 PROGram Program Data Channel or Comm Link (3)................................................ 68 PUBLIC Declare Globally Accessible Variables (1) .................................................. 68 PURGE Purge Characters in Communications Input Buffer (1)............................... 69 READ Start Processing Command File (2)................................................................. 70 REBOOT Force Cold Boot of Computer (2) ................................................................ 71 RELEASE Remove Temporary Variables (2).............................................................. 71 REPORT Generate RTU Data Reports (2) .................................................................. 71 REREAD Restart Execution of Current Command File (0)....................................... 72 RESET Reset Misc. Values and Conditions (2) ......................................................... 73 RESYNC Reset Incoming and Outgoing TSP Block Counters (2)........................... 73 RETURN Terminate Execution of Command File (1) ................................................ 74 RFLAG Manipulate RTU Control Bit Flags (2) ............................................................ 75 RTG Real Time Graphic Control (1) ......................................................................... 75 SAVE Save Current RTU Setup Information To Disk (3) ........................................... 76 SAY Display Expression Value or Text String (1) ....................................................... 76 SCAN Request Range of Data Values for an RTU (2) ............................................. 78 SELEct Select the Current RTU by Name (2) ............................................................ 82 SET Set RTU Operational Parameters (2).................................................................. 82 SETDB Set Deadband for a Single Channel (2) ....................................................... 91 SETHIgh Set High Setpoint for a Single Channel (2) ............................................... 91 SETLOw Set Low Setpoint for a Single Channel (2)................................................. 92 SETWAIT Set Alarm Delay Period for a Single Channel (2) ................................... 92 SHELL Shell to DOS (2) ................................................................................................ 92 SLEEP Suspend Task Operation for a Number of Seconds (2) ............................. 93 STATus Display Status of Link, Comm Port, and Tasks (1) ...................................... 93 STOP Stop Command File Execution for a Task (1) ................................................. 93 STORE Write Configuration Data to Standard Output (2)........................................ 94 STUFF Insert Characters Into Another Task's Input Buffer (2) ............................... 94 TAB Position Text Output to Specific Column (1) ..................................................... 95 SCADAWARE® Command Reference Manual 4 Dec 2001 - Preliminary TAP Passive TSP Mult-Drop Communications Control (2)..................................... 96 TASK Control Task Execution and Settings (2) .......................................................... 96 *TERMINAL Put Program in Human Interface Mode (0)........................................... 97 TIME Set DOS Time of Day (2) ..................................................................................... 98 TRANSFER Copy Values from One Group of C hannels to Another (2)................. 98 TYPE Display a DOS Text File or TSP Procedure (1)............................................... 99 UNHOLD Remove a Channel's HOLD Status (2)....................................................... 99 USER Display User Menu (1) ........................................................................................ 99 VER Get SCADAWARE Information (1) .................................................................... 99 WAIT Delay Some Number of Seconds for An Event (2) .......................................... 99 WATCH Monitor Input and Output Characters for Another Task (2)..................... 100 WIN Graphic Window Control ..................................................................................... 102 WRITE - WRITELN Output Delimited Text to Screen or File (1)......................... 102 XFER Copy Values From One Group of Channels to Another (2).......................... 103 1 TEST SCADA PROTOCOL - TSP TEST's SCADAWARE is a Personal Computer based, real-time data acquisition and monitoring system specifically designed for oil field, offshore, and industrial operation. SCADAWARE has advanced communication abilities which enable it to operate in a wide variety of installations. It also supports a number of data channel types, including PID and AGA3 gas meter calculations. Like other SCADA systems, TEST's units must have some means of configuring and programming the various aspects of the system. This manual describes the powerful command system called TEST SCADA PROTOCOL (TSP) which drives all aspects of system configuration and operation. TEST's system is unique in that its programming language, TSP, is also its SCADA Protocol. TSP is a collection of commands, methods, and procedures which control basic operation of the system. TSP also permits the preparation of simple programs that extend its capabilities to meet the needs of specific situations. The availability of TSP is what makes TEST's SCADA System so powerful yet easy to configure and use. TSP is similar to an interpreted programming language, such as BASIC, where the computer "reads" text lines, decodes them on-the-fly, and then executes the meaning of the line. Single lines can be entered and executed right from the keyboard. More often, the programs are written line after line in a simple Text file format and stored for later execution. The software, through TSP, processes these files to perform a complex sequence of instructions. If you are familiar with BASIC programming, TSP will be very easy to understand. SCADAWARE is a generic program that comes with most of the capability needed to install and startup a working SCADA system. However, most locations will need a few special procedures to handle output control, daily reporting, custom displays, special calculations, and other tasks that are associated with operation of a facility. This reference is not a low level instruction manual on computer programming. Although the user is not expected to be a professional programmer, some familiarity with personal computers and telemetry concepts is assumed. This documentation describes the TSP commands that can be used to setup and SCADAWARE® Command Reference Manual 5 Dec 2001 - Preliminary operate the software program. Information on the specific hardware used in each system is contained in documents furnished with each system. This manual makes no assumptions as to hardware capability other than assuming that an IBM-PC/AT (or compatible) type system will be used. A companion document, SCADAWARE SYSTEM DESIGN CONCEPTS, should be referenced for information on basic system concepts, features, and hardware configuration details. Other documents related to GRAPHICS and DATA BASE operations should be used for information on these advanced topics. Note: This version of the TSP COMMAND REFERENCE contains information on the software as of Dec 1, 1994. Versions prior to this date may not have all of the features described in this manual. Contact TEST for information on obtaining a SCADAWARE update. SCADAWARE® Command Reference Manual 6 Dec 2001 - Preliminary 2 COMMAND LINE INTERFACE 2.1 INTRODUCTION TO TSP TEST SCADA PROTOCOL (TSP) processes all commands as simple ASCII text lines. Each line begins with a special unique keyword, and is optionally followed by various sub-keywords, parameters, and option codes. TSP is built upon a command line interface that is usable by both people and computers. The form of the commands is identical in either mode. Human communications uses the plain text form of the command. RTU communications uses an advanced format which includes message routing and error checking information. However, this additional overhead is handled automatically by SCADAWARE and need not be of concern for the average user. All command components consist of simple letters and numbers. No special computer codes or numeric formats are used in any visible part of a TSP command message. Many commands and options can be abbreviated for convenience, and all entries are case-insensitive. The computer processes the text lines and converts them into the internal language of the computer. The use of simple Text messages places a higher processing burden on the computer while making the overall system less complex for the user, technician, or troubleshooter. 2.2 SCADAWARE COMMAND PROMPT When in human interface mode, the program displays a COMMAND PROMPT that indicates it is ready to process another command line. The prompt contains the name of the computer system followed by the name of the currently selected RTU, and then the task number processing the entries. For example, a prompt for system named MASTER, while selecting RTU1, for task 0 would look like MASTER-RTU1 0> The 0 indicates the local user task number. Serial port tasks, which typically handle remote communications, are numbered 1 and higher. NOTE: If the program in running in its demonstration mode, the prompt will be preceded by the keyword DEMO! When in demonstration mode the serial communications , AGA3 calculations, and I/O drivers are disabled. Demo mode operation will only run for about an hour before rebooting. Normally, the CALC keyword has to be specifically used on command lines which will access the expression evaluator. It is possible to put each task in CALCULATOR MODE, meaning that it can assign values directly to channels. When in this mode, the prompt will be preceded by the keyword [CALC] to alert the operator that keyboard entries will automatically affect data in the system. Commands are entered as typed text and ended with a carriage return (ENTER key). This mode is used for operator based command response as well as command file processing. The backspace key can be used to back over and erase typing mistakes, and the standard DOS cancel (control-C) key can be used to terminate an entire line. Previously entered lines can be accessed with the up and down arrow keys, or the ctrl-E and ctrl- X keys. This allows recall and editing of recently used lines without the need to completely retype them. Local tasks are always ready to accept command lines and are said to be in TERMINAL Mode. Serial port tasks, which normally handle remote communications, are normally set up for computer based communications and are said to be in RTU MODE. The only way to manually get out of RTU mode is to enter the line [CRTL-A]*TERMINAL[ENTER] (all upper case). Note that the [CRTL-A] and [ENTER] are a single keystrokes, so a total of 11 keystrokes are necessary to escape from RTU mode. This special SCADAWARE® Command Reference Manual 7 Dec 2001 - Preliminary *TERMINAL key sequence will place the task in TERMINAL mode, allowing direct manual operation. The task will automatically fall back to RTU mode upon disconnect. The local keyboard and terminal are always assigned to RTU task 0, which is in terminal mode at all times. So, the special escape sequence is only needed when calling into the computer from a remote location over a serial port. 2.3 COMMAND LINE FORMATS TSP command lines begin with a unique keyword which identifies the operation to be performed. Most commands have additional pieces of information, called COMMAND LINE PARAMETERS, which follow the keyword. These parameters provide additional information for the command, and they come in a variety of forms including numeric, text, and variable forms. The physical format of TSP command lines is slightly different depending on whether the program is in TERMINAL mode (human operations), or RTU mode (computer to computer operations). RTU mode is never used manually because the error checking procedures are awkward for a person to use. The computers, however, handle the overhead easily and do all the processing necessary for RTU-to-RTU transfers. The command format for RTU mode is more complicated because it provides error checking and other communications overhead. All text lines in RTU mode must begin with a special START OF HEADER code, SOH, which is CONTROL-A. In RTU mode, nothing is processed until the SOH is seen. This is why the CONTROL-A must be entered when switching from RTU mode to TERMINAL mode as described above. TSP has a very sophisticated communications protocol that is designed to be efficient, powerful, and reliable in real-life communications situations. Refer to the SCADAWARE SYSTEM DESIGN CONCEPTS manual for a detailed description of the TSP command protocol in both human and RTU mode. 2.4 COMMAND LINE PARSING The RTU uses a consistent method of command line "parsing", which is the way it separates the various pieces of information found on a line. Either a comma or a space can be used to separate entries on any line, but both cannot be used on the same line (with one exception). If a comma is detected on the line, then the comma is used as the primary separator. If no comma is detected, then a space is used. The reason for having two ways of separating entries is to allow user flexibility and also to allow spaces in certain entries (like channel descriptions). The only exception is that a space can be used as the first delimiter even if commas are used thereafter on the line. This allows for a more conventional entry format where the keyword is followed by a space, and the subsequent parameters are separated by spaces. The rule here is that if a comma is detected and a space is detected, the space must precede the comma. Otherwise, the comma is the only separator allowed on the line. SET HORN S32 ; Space delimited line Set, Horn, S32 ; Comma delimited line Set Horn, S32 ; Alternate use of space then commas Pairs of double quotes "---" can be used to combine a group of words into a single parameter. The parser will look for the presence of these quotes and will take everything in between a pair as a single element. For example, the following command lines are equivalent: Name Global Oil Corp HI 272 JA ; INCORRECT! SCADAWARE® Command Reference Manual 8 Dec 2001 - Preliminary Name, Global Oil Corp HI 272 JA ; Correct Comma Delimited Name "Global Oil Corp HI 272 JA" ; Correct with quotes The program would parse the first line as 7 separate entries, starting with the keyword NAME and ending with JA. The remaining lines would be correctly parsed as two elements. 2.5 COMMAND PROCESSING All command lines begin with a TSP keyword indicating the nature of the command. The keywords are descriptive of the command purpose and are designed to be easily learned by the user. Examples are words like SET, CALC, INPUT, and DISPLAY. The command processor is case insensitive, meaning that any combination of upper and lower case characters can be entered. The keywords CONFIG and ConFig are processed exactly the same. Keywords must be entered exactly as they are shown in the command reference sections. The only time abbreviations are allowed is when a specific alternate form of the command is available. This is done for the most frequently used words like DISPLAY (disp), CONFIGURE (config), LIBRARY (lib), and PROGRAM (prog). In effect, the shortened version of the command is a duplicate of the full length word. SCADAWARE tries to match the TSP keyword found at the start of the line. If not found, the system will normally return an error message. It is possible to have the system search for alternative commands which are stored in TSP procedure files, called command files, which effectively allow the user to extend the TSP language. To use this feature, the SET RTU ON command must be used which tells the system to look for an RTU file with the same name as the unmatched keyword, and if found, execute it immediately. 2.6 COMMAND LINE PARAMETERS Most lines require command line parameters, which are the pieces of information that follow the initial keyword. The number and form of the parameters is dependent on the nature of the command. Some will assume parameters if none are given, while others must have parameters in order to be processed. TSP is very forgiving for the spelling of the parameters because they can often be determined properly with only one or two letters. For example, if a keyword has only two possible parameters like OFF or ON, TSP will simply check two letters of the parameter. In that case, selection of off can be done with either OF or OFF. Of course, there are some instances where an abbreviation or misspelling cannot be allowed because the result may be ambiguous. If it makes sense to you that an abbreviation would be acceptable, then it is probably okay with TSP as well. The goal is to make the system as easy to use as possible by eliminating as many typing mistakes as possible. Command line parameters can be fixed at the time the line is prepared, or they can be created at runtime using special codes which are replaced at the time the command is executed. These replacement codes allow for run-time values to appear on the line just as if they had been entered on the original line. Refer to the SCADAWARE System Design Concepts manual for more information. 2.7 MULTIPLE COMMANDS PER LINE The program allows for multiple TSP commands to appear on the same physical line. There are limitations in the use of this because of the interactive nature of TSP. But for many applications, such as simple procedures, the multiple statement capability will clean up text and make for more compact libraries. The basic idea is to allow several TSP commands which do not require an ACK or user input to be executed in one pass of the command processor. For example, consider the following line that contains four separate commands: SCADAWARE® Command Reference Manual 9 Dec 2001 - Preliminary horn on : sleep 2 : horn off : msg This is a test Note that the default command separator is a colon and a space, not just a colon. Anytime the parser sees a colon followed by a space it will chop off the beginning of the line and process it separately from the rest of the line. It then continues to parse the line from the point where the chop occurred. The default separator character is a colon, but this can be changed with the SET MULTI command. Other characters that can be used as the separator character are !, |, \, and ~. For example, the command SET MULTI ! would set the separator character to be an exclamation point rather than a colon. The multiple command capability can be turned on or off with the SET MULTI command. The format of the command is SET MULTI ON or SET MULTI OFF The default is OFF, so to be able to use this feature the command SET MULTI ON would have to be processed. This is a global setting which affects all tasks. There are times when the multi-statement parsing is not desired. Sometimes we want the parser to treat the entire line as a single chunk of text. This is most likely to occur with the FORCE and BLOCK commands where text is sent to another task or to another unit. The parser can be instructed to leave the text line alone by starting the command with the slash character. Consider the following example: FORCE 1 READ PROC1 : READ PROC2 : READ PROC3 : BYE At first glance you would think this statement would cause the line READ PROC1 : READ PROC2 : READ PROC3 : BYE to be sent to the input message queue for task 1 because of the FORCE 1 at the beginning of the command. However, this is NOT what would occur in this case because the parser will see the line as follows: FORCE 1 READ PROC1 ; Statement 1 executed by current task READ PROC1 ; Statement forwarded to task 1 READ PROC2 ; Statement 2 executed by current task READ PROC3 ; Statement 3 executed by current task BYE ; Statement 4 executed by current task This sequence of events is probably not what was intended by the programmer. The original intent was to send the entire sequence of commands to task 1 for execution. In order for the entire line to be treated as a single statement the following command would have to be used: /FORCE 1 READ PROC1 : READ PROC2 : READ PROC3 : BYE With this syntax, the entire line would be treated as a single statement and everything from READ PROC1 through BYE would be sent to task 1 for processing. 2.8 AUTO CMD EXECUTION FOR ALL RTUS A shorthand method is available to automatically repeat a TSP command for all logical RTUs on a single system. Preceding any command line with the greater-than symbol (>) will cause the command line SCADAWARE® Command Reference Manual 10 Dec 2001 - Preliminary processor to execute the command once for each RTU in the list for that system. For example, the ACK command which is used to acknowledge all alarms for an RTU would have to be used several times, once for each logical RTU, in order to clear all alarms on a Host computer. Rather than do the sequence: Sele RTU1 ACK Sele RTU2 ACK || Sele RTUn ACK The user could instead enter >ACK 2.9 MENUS Most of the typing in everyday use can be eliminated by the use of the powerful built-in pop-up menu system. The menu systems allow many commands to be processed by making a simple key or mouse selection from a menu rather than entering the commands by hand. Menus can be programmed with the built-in editor of the program, so new ideas and changes can be performed and tested right in the field. Once a system is setup, the everyday operators will only select menu entries and enter a few numeric values (like meter plate sizes) as part of their daily routine. The typing they would normally perform is saved in the menu system for activation by the simple menu selections. 2.10 TASK REFERENCES Some commands require a task number to be specified as one of the parameters. There are several ways that a task number can be specified in a command. The physical task number, such as 0, 1, or 2, can be used as a direct reference. This is fine for very simple systems that have no dynamic reassignments of tasks and RTUs. A better method is to refer to tasks by the ID name provided for them in the DAT file which is read when the system starts up. Using the ID name removes dependence on the exact layout of tasks within a system, and eliminates reprogramming when changes are made in the system configuration. Tasks can also be indirectly referenced through a valid RTU name. If the text provided for the Task name cannot be matched, an additional search is made of the RTU list. A match there will cause the task number to be determined by the task responsible for servicing the default link for that RTU. This provides a very powerful and flexible way to determine the task which must be accessed in order to affect an RTU. In effect, sending a message to an RTU is the same as sending it to the task that manages that RTU by default. This is a good idea for systems that dynamically reassign default links to an RTU, possibly for alternate radio and phone communications paths. 2.11 COMMAND RESPONSES Most commands have some form of response, even if it is just a simple "OK" to indicate that the command was processed properly. Errors are detected whenever possible and some form of error message is displayed. In TERMINAL mode, the messages are fairly descriptive. In RTU mode, which is used in computer to computer connections, the message is less informative but does indicate a problem was encountered. The response in RTU mode is a completion code, or CCC line, followed by a number. Numbers 0 and 1 indicate completed executions. Other numbers indicate some sort of processing error. SCADAWARE® Command Reference Manual 11 Dec 2001 - Preliminary For example, the command TIME 08:12:00 entered in TERMINAL mode will cause the time to be set and the program will respond with "Time is 08:12:00". In RTU mode, however, the time would be set but no response would be given. The communications error checking would insure that the command had been received properly and there is no need for the program to furnish a reply. 2.12 COMMAND FILES AND PROCEDURES It is common to place frequently used command sequences into text files which can be processed when required. These are called COMMAND FILES, and they consist of standard DOS ASCII text files prepared with any text editor, including the one built into SCADAWARE. The assumed file type is .RTU, although any valid DOS file type can be used. SCADAWARE® Command Reference Manual 12 Dec 2001 - Preliminary Each file contains a separate function, such as a custom display screen, a download procedure, or an output control routine. Most command sequences are fairly small, between 3 and 10 lines, and there they tend to accumulate quickly to clutter the directory with a large number of small disk files. An alternative to separate files is to put many separate TSP procedures into a single file, called a library, which is loaded into the computer's memory in a single pass. This memory resident library provides a number of benefits: 1. Much faster TSP procedure execution. 2. More efficient use of limited disk space, especially on RAM disk drives. 3. Easier procedure management by reducing number of disk files. 4. Standard Procedure Development through Utility and other Libraries. Refer to the LIB command for more information on library loading and processing. 2.13 COMMAND LINE COMMENTS The semicolon (;) character is used throughout the program as a program comment character. The parser will look for this character and ignore anything that follows it on each line. This allows for non-effective comments to be placed in command files. This is a good programming practice that assists in future modification of the various program files because descriptive comments help explain the purpose of program lines. Comments can be placed in data and RTU files. Anywhere that the program will parse a line, the comment character is valid. Many of the examples provided in this documentation use comments just as they can be used in actual files. SCADAWARE® Command Reference Manual 13 Dec 2001 - Preliminary 3 TSP COMMAND SUMMARY This section provides a quick reference to all SCADAWARE TSP commands. The keywords which do not have abbreviations are shown with in upper case. Keywords which are available as whole words or abbreviations have the significant portion of the keyword in upper case, and the optional portion in lower case. For example, the command ATTACH can be typed as either ATTACH or ATTA, but cannot be typed as ATTAC because this matches neither of the acceptable formats. This list is for quick reference only. Use the detailed command descriptions which follow for more information on the use and options of each command. 3.1 ALPHABETICAL COMMAND SUMMARY ACK Clear a first out alarm condition. AGA3 Forces recalculation of a range of AGA3 meters. AGENDA Control and display time of day event programming. ALERT Signal from One unit that it needs to be polled ATTAch Attach your console to another port. BLOCK Send a message in error-checked block format. BACKdrop Graphic Screen Display Initialization BOX Draw box on local CRT. BREAK Send a communications break for specified seconds. BYE Terminate the RTU communications session. CAL Calibrate channel with rapid display. CALC Do an expression calculation when not in CALC mode. CALL Call and connect to another unit. CHANGE Change the alarm mode setting for a channel range. CLEAR Clear totalizer and counter channels. Close text files for a task. CLREOL Clear Display to End Of Line CLS Clear The terminal screen. CONFIG Screen oriented channel, link, task, and system programming. COPY Duplicate DOS files. CURSOR Control and position the CRT cursor on the screen. DATA Specify data values for a range of channels. DATE Set the date for DOS. DELete Delete DOS files with confirmation. DIAL Cause task to dial-out to other unit. DIR Display DOS file directory. DISABLE Disable processing of a channel. DISCOnnect Disconnect radio modem. DISPlay Display channel and TASK data on screen. DRAW Draw Graphic Line On Screen DUMP Show channel and TASK configuration data ECHO Send the rest of the line to the communications line. EDIT Invoke the Text Editor program. ELSE Alternate conditional statement processing. ENABLE Re-Enable a Disabled channel. ENDIF End of conditional processing. ENTRY Screen Oriented Data entry and Display EXEC Execute a DOS command, including DOS itself. SCADAWARE® Command Reference Manual 14 Dec 2001 - Preliminary FAX FAX Report Generation and Control FILE Open, close, and delete output files. FLAG Manipulate System Wide Control Bit Flag FONT Graphic Font Control FORCE Send a command line to another task. GOSUB Start processing command file, don't close current file. GOTO Jump to a program label. GROUP Program and display Callout Group Info. HALT Stop the RTU program and return to DOS. HANGUP Disconnect the communications line. HAYES Process a Hayes Modem command line. HAYES Process Hayes Modem Command Line HELP Get help on RTU commands. HOLD Set a channel to Holding Status. HORN Turn local horn off and on. IF Conditional Statement Processing. IMAGE Automatic value saves. INPUT Enter channel or string data from console. KEY Temporary Control of Multi-Drop Line LET Does same as CALC. LIBrary Load command files into a procedure library in memory. LINK Program and display Communications Link info. LOCAL Declare local variables for use in calculations. LOG Control and Display of Alarm and Data log. LOGON Access the program through the password system. MAP Open Architecture Data Channel Mapping Control MENU Display main menu or load user menus. MONITOR Set port for watchdog timer monitor, and off-on control. MOUSE Microsoft Compatible Mouse Control MSG Display a message on the local console. PAINT Transparent Graphic Image Display PASSWORD View and modify passwords. PAUSE Prompt and accept input for command file continuation. PHONE Set the dial out phone number or Radio Call Sign. PLAY Audio Subsystem Control POLL Control callout polls. PORT Set output port and display input port values. PRC Process a Packet Radio Controller command line. PROGram Program a data channel. PUBLIC Declare global (public) variables for calculations. PURGE Purge waiting input characters from communications channel. READ Start processing of a command file. REBOOT Force a cold boot of the computer without going to DOS. RELEASE Free variable space after calculations. REPORT Generate an RTU data report to the printer or a file. REREAD Cause the current RTU file to be restarted from the top. RESET Reset alarm conditions on a channel or all channels. RESYNC Reset incoming and outgoing block counters. RETURN Stop execution of a command file. RFLAG Manipulate RTU Control Bit Flag SCADAWARE® Command Reference Manual 15 Dec 2001 - Preliminary SAVE Save current RTU Channel information to DOS Text File SAY Print a message or channel value on the screen. SCAN Request a range of data values from the RTU. SELECT Select a logical RTU as current one. SET Set RTU operational parameters. SETDB Set and/or display a channel's deadband. SETHIgh Set and/or display a channel's high alarm setpoint. SCADAWARE® Command Reference Manual 16 Dec 2001 - Preliminary SETLOw Set and/or display a channel's low alarm setpoint. SETWAIT Set and/or display a channel's alarm delay period. SHELL Shell out to DOS, just like EXEC. SLEEP Suspend console's task operation for a number of seconds. STATus Display Communications port and Task Status. STOP Stop execution of all command files for a task. STORE Write channel configuration data to standard output. STUFF Insert characters into another Task's input buffer. TAB Position Text Output to Specific Column TAP Passive TSP Multi-Drop Communications Control TASK Task control and information display. *TERMINAL Put program in human interface mode (manual operation). TIME Set DOS time of day. TRANSFER Copy Values from One Group of Channels to Another TYPE Display a DOS text file on the terminal. UNHOLD Remove a channel's Holding status. USER Display local CRT user menu. VER Display SCADAWARE Program Version and Settings WAIT Wait for event to occur with timeout. WATCH Monitor input and output characters for another task. WIN Graphic Window Control WRITE Output Delimited Text to Screen or File XFER Copy Values from One Group of Channels to Another (Transfer) 3.2 SCADAWARE LITE RESTRICTIONS The DPMI Protected Mode Version of SCADAWARE has all of the features described in this manual. SCADAWARE LITE is missing some features, most notably the graphics, database, and open architecture features. The Lite version is further restricted in that some commands are not available to tasks other than the local user's Task 0. This is because certain SCADAWARE LITE commands are contained in the program overlay file. These commands must be loaded from the overlay file (or from EMS memory if present) before they can be executed. Program limitations prevent overlay use by background tasks, thereby limiting access to these specific commands. A few commands can be optionally loaded (with the LOAD command in the DAT file) at program startup to make them available for other tasks. When this is done, they are effectively removed from the overlay system and made part of the main program code. These loadable commands are PROG, COPY, DISP, DBASE, and REPORT. SCADAWARE® Command Reference Manual 17 Dec 2001 - Preliminary 4.0 DETAILED TSP COMMAND DESCRIPTIONS The following section contains detailed descriptions of each RTU program command. This serves as a reference to each command describing its format and syntax. A summary of all commands is included in the previous section. All letters of each command must be present and correct. However, certain common commands can be abbreviat ed to simplify manual entry of frequent commands (like using DISP for DISPLAY). All mandatory characters of a command are shown in upper case. If a command can be abbreviated, the optional part is shown in lower case. When processing a command, the RTU program does not distinguish between upper and lower case. The parameters that follow the keyword may usually be abbreviated if desired. Often, only the first letter is significant. Some parameters, like OFF and ON, require at least 2 letters. If in doubt, simply enter the entire keyword. Each command is listed separately with the exact command name, any allowed abbreviation, and a short description of the command's function. The number at the end of each line is the security level required to execute the command in computers which use SCADAWARE's password system. ACK Clear First Out Alarm (2) The ACK (acknowledge) command is used to remove the RTU's first out alarm condition. When a new alarm comes in, the program will attempt to report the alarm (and possibly blow a local horn). When ACK is used, the alarm condition for all NEW alarms for the current RTU is removed and the program is set to accept a new subsequent alarm. The horn activity is also stopped. Alarms that return to normal after ACK, and are set to auto-reset, will return to non-alarm status right away. Others alarms will go into reset status and will require a RESET to occur (either by command or by push-button) to clear. Note that ACK does not clear alarm conditions as is done with the RESET command unless the points are set to auto-reset. Also, any callout requirements caused by an alarm condition are not affected by the ACK command. Example: ACK Related: RESET AGA3 Recalculation of AGA-3 Meter Channels (1) The AGA3 command is used to force a complete re-calculation of a range of meters. This is required for meters that are not local to the system processing a command, or for meters that have long partial recalculation times. TEST's SCADA system operates as an AGA3 gas flow computer by calculating gas flow rates according to the American Gas Association Report Number 3. This is the recognized standard for gas flow throughout the worldwide oil and gas industry. The manner in which the AGA3 calculation is performed on a particular system will depend on the availability of local input devices, the intelligence of the remote units sending the data to a host, and on the power of the computer being used to run the SCADA program. Management of the AGA3 calculations is based on reducing the amount of processor power dedicated to the meters such that adequate values are obtained without wasting the computer's resources. Unlike most RTU's and PLC systems, TEST's SCADS system performs the entire AGA3 calculation in real-time as often as once per second. The entire crunch includes complete calculation of SCADAWARE® Command Reference Manual 18 Dec 2001 - Preliminary 'C-prime' using the entire AGA3 report tables and formulas. The complete crunch is rarely necessary in real-time because parameters like pipe size, gas gravity, and other components don't change at all, much less once per second. Because the AGA3 calculation takes quite a bit of computer power, performing constant calculations can waste this power by crunching numbers that never change. To reduce the PC processor load, the program allows for a "pre-calc" to occur when any of the normally fixed parameters are altered. This is done whenever any AGA3 channel configuration parameter is changed, or with manual or automatic execution of the AGA3 command for a particular meter range. The partial calculation (that always occurs in real-time) accounts for pressure, differential, and temperature on each pass. The full calculation does the entire AGA3 report, including NX-19 gas supercompressibility (unless overridden by the channel configuration). The user never has to look up anything in an AGA3 reference in order to configure or operate the AGA3 gas flow calculator. The AGA3 command is needed to force an immediate calculation of a remote meter when new input data is received. Otherwise, the complete calculation would be delayed for the number of calculation cycles specified in the meter's setup. For example, a host computer polling a dumb RTU only needs to re-calculate when new data comes in over the communications line. In this case, the meter would be programmed to never pre-calc and an AGA3 command line can be placed in the BYE file so that only one re-calc takes place per transmission. The AGA3 command may also be used in a command file that requests information on the gas gravity, plate size, or gas quality (CO2, N2) on an input screen. When the entry is complete, the program should do an AGA3 command on the affected meter so that the "per-calc" will occur immediately and the new values will be taken into account as part of the partial calculation stored in the meter's setup. Examples: AGA3 M1 AGA3 M2:M3 ; Program stub to enter new meter date for meter M1 input, Enter New Gas Gravity, V4 input, Enter New CO2, V5 msg Doing the AGA3 pre-calc AGA3 M1 ; force immediate pre-calc AGENDA Time of Day Procedure Control (2) The AGENDA system allows the program to perform pre-programmed tasks at specific times of the day. The program monitors the time of day in order to send commands to tasks at the specified times. These commands may only contain a single line, but that line can be a READ command which will cause a more extensive command file processing sequence. The agenda system is checked once per second, so commands can be timed to occur on one second intervals. Each task can receive as many commands as desired at any time specified, and more than one task can receive commands at the same instant. The AGENDA LIST command will display all entries in the agenda list and also indicate which entry is the next to be executed for each task. An optional task number can be specified after the LIST keyword which will cause the display to include only the entries for that task. If the AGENDA command appears by itself on the command line then the parameter of LIST is assumed. The agenda process can be halted and re-started with OFF and ON options. The Agenda CLEAR will eliminate all entries and turn processing off. The Agenda RESET command will restart processing of the agenda list from the top (midnight) if no time is specified, or from a specified time if one is given. This is helpful in testing an Agenda list because you can trick the computer into thinking it is earlier or later SCADAWARE® Command Reference Manual 19 Dec 2001 - Preliminary (with the Time command) and then moving the internal Agenda pointer with the RESET option. This beats hanging around till 6:00 AM the next day just to test an Agenda activity. Entries into the agenda list are also made with the agenda command that specifies the task to receive the message, the time to execute, and the message itself. Normally, commas are used to separate the entries on the line so that the message portion can contain embedded spaces. Entries for each task in the agenda list must be entered in the order of time to be processed. The agenda list does not automatically get sorted by time. For example, consider the following incorrect agenda list entries: agenda, 1, 09:00:00, Read UPDATE.RTU ; WRONG ENTRY!!! agenda, 1, 06:00:00, Poll Now agenda, 2, 06:00:00, Poll Now agenda, 1, 10:00:00, Report When the agenda is started it will search down the list for the "next" entry to process for each task. It will find that entry 3 is the next entry to be processed by task 2. Since this is also the only entry for task 2 there can be no problem with the agenda for task 2. Processing the agenda entries for task 1 can be a bit more troublesome. When searching for the "next" entry to process for task 1 the agenda system will first find entry 1 and wait there until it is time to process it. When that entry gets processed the agenda will continue down the list searching for the "next" entry to process. It will then find entry 2. Since the time for entry 2 to be processed has already passed, the agenda will immediately process the entry and look for the next entry. It will then find entry 4 and wait there until 10:00:00 to process it. Now consider the following example in which agenda entries are properly listed: agenda, util, 06:00:00, Read DAILY.RTU agenda, util, 06:20:00, Report agenda, 1, 06:05:00, Poll RTU smi9 agenda, 1, 06:06:00, Poll RTU vr253 agenda, 2, 06:07:00, Poll RTU hi92 Because of the way that the agenda system works, it is up to the user to insure that all agenda entries are listed in the proper order. Usually, all agenda entries are listed in a single file (named AGENDA.RTU) and the file is read to load the agenda. If an agenda entry needs to be added to the list it can first be added to the file, the agenda then cleared, the file read again, and the agenda turned back on. The name of the file that contains the agenda entries can be anything but usually AGENDA.RTU is used. The edit, clear, and reload actions are also normally pre-programmed on a utility menu supplied with the system. Note that the RESET option will process all agenda entries up to the time that the agenda is reset to. The ON option will activate the agenda by starting it at the current time. Turning the agenda on will not cause any entries prior to the current time to be processed. Examples: AGENDA ; display all entries in agenda list AGENDA LIST ; display all entries in agenda list AGENDA LIST 2 ; display all entries for task 2 AGENDA ON ; activate agenda process AGENDA OFF ; stop agenda process AGENDA CLEAR ; stop agenda process and clear list AGENDA RESET ; restarts agenda from midnight AGENDA RESET 12:00:00 ; restarts agenda from noon AGENDA, 0, 09:45:00, read UPDATE.RTU ; for task 0 AGENDA, util, 23:00:00, report ; for util task SCADAWARE® Command Reference Manual 20 Dec 2001 - Preliminary ALERT Signal that RTU Needs Attention (1) ALERT is a command sent from non-PC based RTU's for call-on-exception processing. A small RTU such as the Multi-Drop Type 2200 SCADA Node will detect switch changes and signal that it needs attention by broadcasting an ALERT command followed by its RTU ID. The SCADAWARE computer processing the ALERT will scan its LINK table for a match between the Alert RTU ID and the Link's Phone Number/Call Sign field. If a match is made, the associated LINK is activated and processing continues normally. The small RTU sending the ALERT command will continue to do so every minute for one hour, or until a proper message is received by that unit. The Alert status is normally cleared by polling an RTU, although any successful message into the RTU will clear the Alert. Only one SCADAWARE computer on a multi-drop link can respond to ALERT messages. Therefore, the SET ALERT OFF/ON option is provided to allow tasks on each computer to respond to Alert messages. The SET ALERT ON should be placed in the STARTx procedure for the affected task. The ALERT action can be tested by simply entering ALERT RTUNAME at the local console. The program will scan the link table trying to match RTUNAME, and if found, will activate the appropriate link. Related: Set Alert ON ATTAch Attach Console to Another Task's Serial Port (2) The local keyboard and CRT are "connected" to task 0 of the SCADA program. Any keystrokes entered affect task 0 directly. Modems and other communications devices are connected to very similar tasks inside the program. However, the characters sent to and from the other devices are invisible because tasks have no access to the local CRT. These other tasks control their serial line in the same way that task 0 controls the local CRT and keyboard. They are separate sessions within the program that normally have no reason to cross-connect with one another. Sometimes it is convenient to use the CRT/Keyboard to "talk" to a communications device connected to another task. This would be like getting inside the program for a moment in order to send and receive characters that are normally destined for another task. For example, it may be helpful to send keystrokes to a modem (to make it dial) and see the responses that are returned from the comm line. Without the ability to temporarily connect to the modem, a separate communications program would have to be used to perform the test. The ATTACH command is used to connect the local console to the comm port of another task. This is handy when the operator wants to manipulate the communications channel for diagnostics or other special purposes. In effect, this is a mini-terminal emulation program built into the program itself. Because each serial channel is normally connected to an RTU task, ATTACH puts the other task to sleep for the duration of the ATTACH command. While attached, the local console keystrokes go out of the affected port and all incoming characters are displayed on the local CRT. This condition will remain until the attachment is ended with the special key sequence ESC-X (two keystrokes). When the attachment is ended (by hitting ESC-X), the suspended task is restarted just where it left off. The affect on that task is unpredictable, especially if the task was not operating in the fist place when the ATTACH was started. Commands that are processed in RTU mode contain extra characters, such as checksum characters, which are used for error checking. When attached to a task in RTU mode, all error checking requirements that are usually added to a command automatically must now be typed in manually. Entering the command ^A*TERMINAL will put the program into terminal mode. This will allow commands to be entered without the error checking requirements. SCADAWARE® Command Reference Manual 21 Dec 2001 - Preliminary Example: ATTA 1 ESC-X (key sequence to end the attachment) Will suspend task 1 and attach its serial port to the current console. BACKDROP Graphic Screen Display Initialization (1) Graphic screens can be built on the "backdrop" of a graphic screen contained in a PCX or GIF file. They can also be built on blank screens filled with any color. The BACKDROP command provides the means to initialize the graphic screen with any file or color, and to optionally frame the screen in any standard graphic frame type. The command provides offset options to locate the file at any X-Y position on the screen. Normally the entire screen is used, but this option is provided for special cases such as providing a rectangular area filled with color at random positions on the display. Refer to the Graphics System Documentation for more information. Examples: Backdrop None Blue ; plain blue background backdrop FLOWMET 0 0 double ; display FLOWMET.PCX with a double edge frame backdrop flowmet 10 20 single ; flowmet.pcx offset 10 pix right 20 down with single frame Related: WIN, PAINT BLOCK Transmit Command To Remote Unit (2) The basis of TSP is that text lines are processed by an RTU type task. Sometimes the local computer needs to process a line, and other times we want to send a line to another unit so that the line will be processed over there. The command lines are very similar. The only difference is where they get executed. While in RTU mode, the SCADA system uses error-checked block transmissions (TSP Packets) for all data transfers. The BLOCK command is used in a command file to send a TSP command to another system. For example, while processing a download file at a Host system it is likely that several BLOCK SCAN commands will be processed. If only a SCAN command was used, the local computer would process the line (and send the result to the RTU). By using a BLOCK SCAN, the Host will send everything after the BLOCK keyword to the RTU where the line will then be processed. The resulting DATA line will automatically be blocked over from the RTU to the Host as a response. One consequence of the BLOCK command is that the system will wait for a communications response from the other unit indicating that the message was received. When the response is received, execution continues normally with the next line of the file. If the response is not received, the transmission is repeated several times according to the TSP protocol controls in effect. If still no luck, the communications link and command file processing are automatically terminated. Execution continues, but other commands in the RTU file that rely on in-tact communications will not process properly. The SET ONLINE command can be used to have better control over a problem like this. Lines processed by the block command are "expanded" before transmission to the other unit. This expansion will do a special code replacement similar to the ECHO command. This allows for system SCADAWARE® Command Reference Manual 22 Dec 2001 - Preliminary or run-time information to be placed on the line automatically just before the line is transmitted. One common use of this feature is to set the time and date on the other unit with BLOCK TIME $T and BLOCK DATE $D commands. At run time, the $T and $D will be replaced with the actual time and date of the sending unit. The receiver of the BLOCKed transmission can supply a response line along with the required ACK. This allows for a system to BLOCK over a SCAN command and wait for the normal DATA response before proceeding with local command file processing. All comments are stripped from a line prior to transmission to the other system. This shortens the amount of characters that must be sent when doing block transmissions. Example: Block SCAN A1:a10 E S1:S16 R ; request data from a remote Block DATA RTU1.A1:A3 E 100 200 300 ; send data to a remote BLOCK SELE GA343A ; select another RTU BLOCK CALC T2 = 30 ; pulse timer on remote unit Related: ECHO, PRC, HAYES, SET ONLINE BOX Draw Textmode Box on Display (1) This command can be used only by the local task. It is used to draw a box on the screen which is most useful for enhancing custom displays. The command can be used in a command file along with the CURSOR and SAY commands to create a custom display screen. The x (column number) and y (row number) coordinates for the upper left corner and the lower right corner of the box must be specified with this command. The upper left hand corner of the screen is at position 1,1. An optional 5th parameter is allowed which will be displayed as a string in the title of the box. Examples: BOX 5,10,60,22 ; box at col 5 starting on line 10 thru line 22 BOX 5, 5, 75, 25, This is the title Related: CURSOR, SAY BREAK Send Timed Break Signal Over Comm Line (2) Normally, a communications channel sits idle in a MARK, or 1 state when not transmitting data. The data line is never low more than one character time, even while transmitting a character that is all 0's because of the stop character that is present at the end of each async character. A BREAK signal is defined as the presence of a SPACE (0) for more than one character time. TEST's Modem Monitor device can time a break signal and initiate a CPU reset if the specified time is exceeded. The BREAK command is used to send the required break signal. The only parameter is the number of seconds that the break will occur. A typical sequence is to DIAL an RTU, WAIT for a carrier detect, and then use BREAK x to perform the reset. Example: DIAL WAIT 30 CONN BREAK 5 ; send a 5 second break to cause a reset SCADAWARE® Command Reference Manual 23 Dec 2001 - Preliminary BYE Terminate RTU Communications Session (1) The proper way to terminate an RTU session is with the BYE command. Although the program will normally time out after a specified period of inactivity, using the BYE command will provide an orderly shutdown of the session. BYE allows faster processing of multiple connects because the normal delays associated with timeouts can be eliminated. It can also reduce Cellular costs that are charged in chunks of 5 or 10 seconds because the normal 30 or 60 second timeout can be eliminated. BYE affects the physical and logical on-line state of the task processing the command. Many communications media use the physical carrier detect (DCD) line as a means of verifying the state of the comm line. Others, like multi-drop, must rely on internal timing and other paramet ers to determine the logical state of the connection. The Bye command affects all aspects of the on-line state. A task processing a Bye command will go through various steps to disconnect whatever communications device is connected. It will also reset the command counters for both incoming and outgoing messages so that a fresh communications session can begin with the next call. The BYE command handles ACK responses in a special manner. This is because the comm line is in transition at that point, and sometimes a response to a BYE command will confuse the issue. The basic rule is that the BYE command suppresses the normal TSP ACK requirement unless the BYE originated from the incoming communications line. So, a BYE processed in a command file will cause an immediate hangup, while a BYE sent from another unit will cause an ACK response (like any other command) prior to the disconnect. When BYE is processed, the RTU will disconnect from the communications line and will process a special command file if it exists. This file is named BYEx.RTU, where the x is replaced with the task number. For example, BYE1.RTU is the bye program for task 1. This program can consist of special communication line setups or whatever else the operator wants to have happen each time the program terminates communications. For example, a typical BYE file might appear as follows: set echo off ; make sure task is full duplex prc echo off ; set PRC to full duplex prc maxframe 1 ; no outstanding PRC frames allowed prc tclear ; dump any chars waiting to transmit prc mycall smi4 ; my name will be SMI4 msg Task 1 Disconnected ; tell local console what happened Related: RTU, TERMINAL, SET BYE CAL Calibrate Channel With Rapid Local Display (1) When calibrating an analog channel, it is often desirable to have a quick-response display to assist in the adjustments. The CAL command provides a rapid, one line display of a single channel. Normally, analog inputs are used although any channel type can be specified. The parameters on the line include the required channel identifier (ID number or tag), and an optional wait count. The wait count is the number of system ticks (1/18 sec) that the program will wait between displays. If none is specified, then a value of 9 is used providing a display that is updated about 2 times per second. Lower waits provide quicker displays, but occupy more processor time. Slower displays may often be used because analog inputs are only updated at the speed of the DRIVER task anyway. Displaying faster than the update rate will not produce any additional speed in the display. Therefore, it might be desirable to use a command such as TASK DRIVER DELAY 1 to speed up the driver task during calibration. A counter is provided to show how often the display is being refreshed. This counter has no effect on the actual value being displayed. SCADAWARE® Command Reference Manual 24 Dec 2001 - Preliminary Note that it may be desirable to temporarily clear any negative number restrictions on analog channels during the calibrate process. The change is made on the Analog Channel Config Screen for the affected channel. Eliminating the negative value restriction will allow easier adjustment of the zero point. Remember to restore the correct negative flag for the channel after calibration. Examples: CAL A1 ; accept default update rate CAL A1 18 ; wait about a second between update. CAL A1 1 ; very fast display CALC Access TSP Expression Evaluator (2) Normally, the expression evaluator will not process a line unless the user is in CALC mode. Single lines can be processed by preceding the line with the CALC command. For example: CALC TOTAL = TOTAL + DAYTOTAL would cause the contents of the variable (or channel) DAYTOTAL to be added to the variable TOTAL. Without the keyword CALC, the command processor would not be able to complete the line because the parser would think the desired command is called "TOTAL". Any valid TSP expression can be put on the right of the equal sign. Several special keywords are also allowed a mentioned below. If a number of expressions are being processed, the SET CALC ON command can be used. This will allow automatic execution of any line that is not processed as a normal command. When in effect, the user's prompt indicates [CALC] to warn the user that any lines entered will be processed directly. Although this method is sometimes convenient, it is quicker to process commands when the keyword CALC is specified. All channel types can be set to any value using the CALC (or DATA) command. Also, channels that have time and dates associated with them (i.e. counters and totalizers) will have the time and date automatically set to the current time and date when ever these channels are set to exactly 0. This allows for daily processes to clear the counters and totalizers and reset the starting time in a single command. When using the CALC command, the keywords OFF and ON can be used to set a channel or variable to the values of 0 and 1 respectively. Setting Timer Channels Off will stop them from counting and bypass any alarm action that would have occurred when the timer reached 0 by itself. String variables can also be set using the CALC command. String variables begin with the percent sign, and are referenced by number: %0 through %9. String expressions can be placed in a string variable. Each parameter on the line after the = sign is added to the string. Quotes can also be used to prevent text from being expanded. For example: CALC %1 = test 123 would produce a string like test 123, while the line CALC %1 = test 1 2 3 would produce a string like test 1 2 3. The evaluator will display error information if any problems are encountered when processing a line. For example, if the "target" variable on the left of the = sign is invalid, the system will indicate this with a "TARGET RANGE INVALID" or "COULD NOT SOLVE" line being sent to the task's console (if it has one). The user can control further file execution after any errors with the SET ERROR command. SCADAWARE® Command Reference Manual 25 Dec 2001 - Preliminary Setting this ON will cause the file to stop on any evaluator error. The default setting is OFF, so errors will not normally stop file execution. Examples: CALC O1:o8 = 0 ; Turn off all outputs CALC %1 = SYSTEM $S CALC T5 = 0 ; stop timer and cancel any alarm action Related: LET, SET CALC, SET ERROR CALL Attach With Local Echo (2) CALL is similar to the ATTACH command except that the program processes local characters slightly differently. In CALL mode, the program will locally echo the user's keystrokes rather than waiting for them to come back from the other unit. This assists operation in half-duplex radio installations where there may be a 10 second delay in the PRC transmissions. CALL mode also monitors the state of the Carrier Detect line from the communications port. If the CD is lost, the CALL mode will automatically terminate and the user is returned to normal command mode. As in the ATTACH command, the task normally connected to the serial port is suspended until termination of this command. The results of stopping the task are unpredictable. Terminate the CALL command with an ESC-X sequence. Example: CALL 1 Related: ATTACH, DIAL CHANGE Modify Mode Settings Options for Channel Range (2) Every channel has an "alarm mode" setting, which actually controls more than just its alarming actions. This setting determines how the channel behaves to abnormal conditions. Internally, the setting is a 16 bit word with each bit having a specific purpose. The alarm mode is one of the first things that is programmed during the channel program sequence. The Skip Reports, REMOTE, HOLD, and ENABLE settings for each channel are also modified with the CHANGE command. The CHANGE command allows individual settings to be set or cleared for a range of channels. This can be helpful when transferring a channel setup from an RTU to a HOST. For example, it may be desirable to set all channels to NOT call out at the host station. This can be done easier with the CHANGE command than by re-programming each channel individually just to change a single setting. The command works by taking the specified channel range as the second parameter and a number of "off-on" switches on the remainder of the line. These switches are 1 or 2 letter abbreviations for the setting to be affected. Entering no switches will cause the command to display a quick reminder of the valid options. The options for the CHANGE command are: OPTION EFFECT IF SETTING IS ACTIVE AC Set channel to be an Alarm type channel. CA Call on abnormal conditions. SCADAWARE® Command Reference Manual 26 Dec 2001 - Preliminary CR Call on return to normal (reset needed). AR Set channel to auto reset on return to normal. CF Execute command file on abnormal. LO Log all abnormal conditions. HO Activate local horn on abnormal. SR Skip this point during report generation PL Play Message on abnormal H Hold status for the channel. R Remote status for the channel. E Alarm Enable status for the channel. D Dump (Display) current settings (does not set anything). Plus and minus signs are used to determine if the option is a set or clear operation. For example, entering -HO will set the specified channels to NOT blow the horn on alarm. Using +CR will set the channels to call on reset. The plus and minus can lead or follow the option code. No plus or minus will default to plus. Thus, +CR is the same as plain CR. At lease one space must appear on the line between each option. The DUMP option allows a short display of the mode settings for a channel range. The option, "DUMP", can be specified anywhere on the command line where a change option is allowed. The dump will represent the state of the range at the time the DUMP parameter is encountered. Thus, any changes caused by options specified after the DUMP keyword will not be reflected in the display. For example, entering CHANGE V7:V15 CA - CR- DUMP will cause channels V7 through V15 to be changed to NOT call on alarms or resets. After the changes are made, a display will be generated showing the complete alarm mode settings for this channel range. Although the change command is most often used directly at the keyboard, it can be useful in command files to change the behavior of some channels on-the-fly. For example, it may be desirable to turn off the horn status of certain channels at night. This would prevent awakening the operator for non-critical alarms. To do this, a command file would be run (by hand or as an Agenda item) to change the affected points to HO-, and another file could be run to change them back to HO+ at the appropriate time. A single file could also be used by passing the desired condition (HO+ or HO-) as a command line parameter from a menu hit. Examples: Change S1:s8 +AC CR- CF+ +HO Change A3:a5 HO+ DUMP Change Q1:q4 H- ; un-hold some channels Change A1:A6 $1 S1:s4 $2 ; Use command line parameters Related: PROGRAM, HOLD, UNHOLD, CONFIG CLEAR Clear Totalizers and Counter Channels (2) There are two options that can be used with this command. The keyword ALL can be used to clear all totalizer and counter channels to 0. This is basically just a convenience to clear all accumulator type inputs at the same time. Individual channels can be set with direct assignment statements such as CALC Q1 = 0. The keyword FILES can be used to close all open text files for a task. This command is mainly provided so that files can forcibly be closed in the event of an error. Example: CLEAR ALL SCADAWARE® Command Reference Manual 27 Dec 2001 - Preliminary FORCE 1 CLEAR FILES CLREOL Clear Display to End Of Line (1) Clears the current display line from the cursor position to the end of the line. SCADAWARE uses the proper screen control codes depending on the display type specified in the SET CRT option for each task. The cursor remains at its current position, but all character positions to the right are filled with blanks. Example: cursor 10,12 ; col 10, line 12 clreol ; clear to the right say a1 ; print value of channel A1 Related: SAY, CURSOR, CLS CLS Clear Display Screen (1) This is essentially the same as the DOS CLS (Clear Screen) command except that it also works with remote ANSI CRTs as well. The terminal or console screen is cleared and the cursor is positioned at the top line, left corner. The screen control codes used for this command (and other CRT related commands) depend on the type of CRT installed with the SET CRT command. If it is desired to "home" the cursor to the upper left hand corner but not clear the screen, use the CURSOR 1,1 command instead of CLS. Related: SET CRT, CURSOR, SAY CONFIG Screen Oriented System Configuration (3) CONFIG allows screen editor type configuration on the local CRT screen. CONFIG can only be used on the local CRT and keyboard. The CONFIG command can be used to program channels, links, tasks, database, entry screens, and system variables. When using CONFIG, the user can move from field to field making changes and then save the changes with a single keystroke. A Microsoft (C) compatible mouse is also supported in many editing functions. Note that the CONFIG command can be easily accessed from the built-in menu system to get direct access to any configuration command option. The menu system simply types the proper CONFIG command for you. To configure a channel using this command, enter CONFIG followed by a channel identifier (such as CONFIG a3). The program will display all of the parameters for the channel, and allow editing of each parameter individually. The cursor can be moved using the arrow keys, and can be moved between channels with the PGUP and PGDN keys on the keyboard. The ESC key is used to exit the configuration mode without saving the changes. The F2 key is used accept the changes in memory and exit the configuration mode. NOTE: Saving most changes in memory will allow the system to remember the current setup only as long as the program is running. If the program is halted for any reason (purposely terminated, power failure, etc.) the current setup will be forgotten unless it is first saved to disk. Changes made during a configuration can be permanently saved to disk by using the SAVE command or selecting SAVE CONFIG from the main menu. This type of save will store the current configuration in a disk file that the program reads each time it is started. SCADAWARE® Command Reference Manual 28 Dec 2001 - Preliminary If the system has a mouse attached, it can be used to select a field by placing the mouse cursor on the desired field and pressing the left button. In the case of Y/N fields, the current value can be toggled by pressing the right button. To configure a link, a task, or the system variables the CONFIG command works just like it does for configuring channels. The options available for use with the CONFIG command are: chan id ; program a channel such as s1, v2, etc. LINK [xx] ; default is link 1 TASK [xx] ; default is task 0 SYSTEM ; program variables used by the program ENTRY ; user defined entry screens The following CONFIG options are not included in SCADAWARE Lite: DBASE or DB ; Database Fields ANN ; Annunciator Graphic Object MET ; Meter Graphic Object VBA ; Vertical Bar Graphic Object HBA ; Horizontal Bar Graphic Object SCR ; Scroll Graph Object GRAPH; Graph of current window type Note that this command only works on the local CRT. To program channels or links remotely over a serial line, the older PROG command must be used. Note: In SCADAWARE Lite, the PROG command is an overlay and must be specified with a LOAD command in the system's DAT file if it is to be used from a remote terminal. Just as with the PROG command, changes made with the CONFIG command take effect immediately, but are not saved until a SAVE or LINK SAVE command is issued. Examples: CONFIG v1 CONFIG LINK 2 CONFIG SYSTEM ; configure program variables CONFIG TASK 2 Related: PROG, LINK, SAVE COPY Duplicate DOS Files (2) This is a simple, single file copy utility provided for use within SCADAWARE. The syntax is similar to a DOS Copy, except that wild card characters are not supported. To avoid confusion, the source and destination file names should be completely specified. If a file extension is not specified, the default extension .RTU will be used. This default is similar to the program's DIR command. A file can be copied to a particular drive by specifying the drive in the destination file name. Note: In SCADAWARE Lite, COPY is usable only by the local task. Examples: COPY shutin.rtu wellopen.rtu COPY shutin wellopen ; same as above COPY shutin.bak ; copy shutin.bak to shutin.rtu COPY shutin A: ; copy shutin.rtu to drive A Related: TYPE, DEL SCADAWARE® Command Reference Manual 29 Dec 2001 - Preliminary CURSOR Locate and Control Display Cursor (1) The CRT's cursor is the blinking line or block that indicates the current position on the screen. When writing script files, it is sometimes desirable to locate the cursor at a specific location prior to printing a message. The basic syntax is to provide the X=COLUMN and Y=ROW coordinates for the cursor. If an entry is invalid, the location of the cursor is unchanged. All positions start with 1, and continue to the maximum supported by the user's CRT. So, position 1,1 is the top left corner of the screen. Position 80,1 is the upper right corner, and 80,25 is the bottom of the typical PC screen. The number of columns is 80 for all currently supported CRT types, but the number of lines depends on the CRT type. The local CRT can be 25, 43, or 50 for MONO-CGA, EGA, and VGA screens respectively. Remote ANSI terminals usually have 24 lines. An optional keyword can be used to cause the cursor to be hidden or returned to normal. Thus, CURSOR OFF will cause the cursor to become invisible, and CURSOR ON will restore the standard cursor for that CRT type. This option may not work on certain types of terminals and the cursor will always remain on. If more than 3 parameters are on the line, the fourth (and remaining parameters) is displayed as a text message, an expression evaluation, or as a channel. Text messages can be enclosed in double quotes to maintain spaces or commas within the text. TSP Expressions must be enclosed in parentheses, and channel references can be either the channel tag or number. Formatting characters can also be used to control a display on the screen. These codes follow the parameter with an accent (`) character. See the SAY command for more information on how to display information using this command. TEXT IN GRAPHICS MODE The protected mode version of SCADAWARE can display text in any supported graphics mode. The CURSOR and FONT commands are used to style and position the text output. In graphics mode, the column and row parameters are specified as either a percentage of the entire screen, or as pixel values. As with all SCADAWARE graphic coordinates, position values less than 1 are considered percent of screen. Values of 1 and greater are considered pixel coordinates. For percentage placement, position 0.00,0.00 is the top left corner of the screen, while 0.99,0.99 is bottom right corner. SCADAWARE will calculate the proper pixel coordinate based on the current screen resolution. In pixel mode, 1,1 is the top left, while the bottom right will depend on the current graphic resolution. For normal VGA, the bottom right corner is at 640,480. The size and style of the graphics characters is determined with the FONT command. Various options for font style, size, color, and justification are available. Examples: CURSOR 1,10 ; line 10 column position 1 CURSOR off CURSOR on CURSOR 1 1 "The current time is $T" CURSOR 10 5 V3`R10 ; chan V3 right justified in field of 10 Related: CLS, SET CRT, SAY, FONT DATA Reply from SCAN for Data Values (2) SCADAWARE® Command Reference Manual 30 Dec 2001 - Preliminary DATA lines are the primary means of sending RTU channel information from one unit to another. DATA lines are normally generated as a response to a SCAN line, although they can also be entered as simple text lines. When an RTU is uploading channel data to another computer (in response to a SCAN command), it sends each line of information in the form of DATA lines. These lines indicate a range of channels followed by the appropriate values. The SCAN command is given with a range of channels, and the DATA command represents a response with that range. The values are listed one after another on the line in ascending channel order. If no options are given in the SCAN command, the values are returned in engineering units representing the current value of each channel. DATA commands can also be used in a command file to allow setting of channels to specific values, just as if they had come from another unit. This is helpful is establishing initial values as well as testing without actually connecting to another unit. A special form of the command is DATA @ENDS. This indicates the end of an upload process and causes the receiving system to set the update time and date to the current time. A specific RTU can be indicated after the @ENDS keyword. If not specified, the current RTU for the processing task will be used. A time and date can follow the RTU parameter to specifically set the timestamp instead of letting it default to the receiving system's current time and date. Multiple channel types can be present in the same line. Each group (except the first) begins with a back slash (/) character. Otherwise, the extra groups are similar to the first one. This multiple grouping allows for faster transfers in half-duplex radio systems where transmission overhead is a significant portion of the download time. The only restriction is that all channel references in the same line must refer to the same RTU. This RTU is either specified in the first range or assumed to be the current RTU if none is specified. Combining channel types cuts down the number of transmissions required to complete a download. Refer to the description of the SCAN command for details on the various options and formats for the DATA command. Examples: DATA RTU1.S1:S24 R 4 16 8 DATA RTU2.S1:s8 R 12 /O1:o8 R 4 /A1:a2 E 100 200 DATA RTU1.A1:A8 R 1022 450 344 756 124 544 0 77 DATA RTU1.A1:A4 E 12.3 16.3 17.3 122.5 DATA @ENDS DATA @ENDS RTU1 09:00:00 06/12/91 Related: SCAN DATE Set System DOS Date (2) This sets or displays the DOS date which is used by the program and any other DOS function. Note that this command does not always set the "watch" that maintains time in the computer when power is removed. It appears that for most AT type computers and above, operating under DOS version 3.3 or later, the watch does get set simply by using the DATE command. However, on some machines, setting of the watch requires a separate DOS program that is machine dependent. For example, PC type systems often use the PCCLOCK program, while AT class computers use the ATCLOCK program to directly access the built-in timekeeper. Either of these programs are run as a DOS command by shelling out to DOS using the EXEC or SHELL commands. To find out if a computer requires one of these separate programs, set the date using the DATE command, turn the computer off and then on again, and use the DATE command to see if the new date was saved. If so, a separate program to set the watch is not needed. SCADAWARE® Command Reference Manual 31 Dec 2001 - Preliminary Many 8088 PC level computers use a Dallas Semiconductor "Smartwatch" device to maintain the system time and date. These devices are accessed outside SCADAWARE by a program such as PCCLOCK. SCADAWARE has an option to access the Smartwatch during normal operation, making the Smartwatch act similarly to the AT style CMOS clock device. To use this option, a LOAD SWATCH line must be installed in the DAT file for processing during startup. This option does not apply to 286 and higher machines which have built-in CMOS time chips. Entering the command DATE with no options causes the current value to be displayed. Entering a properly formatted date as a parameter will cause the date to assume that value. As a second parameter, a properly formatted time can be specified which will cause the time to assume that value. This allows both time and date to be set with a single command line. Systems being used in different countries may need to include a line in the config.sys file to control the date format. The following commands can be used in the config.sys file to cause the dates to appear as follows: COUNTRY = 001 -- United States mm/dd/yy (DOS Default) COUNTRY = 003 -- Latin America dd/mm/yy Example: DATE 01/01/88 ; will set DOS to New years day 1988. DATE 01/01/08 12:00:00 ; will set DOS date and time Related: Time DEL Delete DOS File (2) This is similar to a DOS Del or Erase command, including support for wild card characters. Unlike DOS, the program will prompt for "OK to delete" for each file name that matches the specification provided as the first parameter. This confirmation can be overridden by using the switch /N after the file specification. Examples: DEL ab*.rtu ; delete all rtu files starting with AB Del *.RTU /N ; del all rtu files without confirmation Related: Type, copy DIAL Make Dial-Up Connection to Remote Unit (2) This command is normally used in file processing to have a task begin a connection to another unit. A parameter can be provided after the DIAL keyword to specify the phone number, call sign, or Multi- Drop ID to be accessed. If no parameter is given, the default phone number or radio call sign for the currently selected RTU is used. The default phone number and call sign is set during the Link configuration, or optionally with the PHONE command. The DIAL command will start the connection sequence for any type of communications media, including those that do not actually "dial" anything. The action depends on the setting established with the SET MEDIA command. The required delays for the modem will be provided as in any normal dialout procedure. Direct connect and multi-drop connections do not dial at all but do set their modem control signals and internal controls to start a communications session. In any case, processing will continue immediately after the DIAL is complete. The WAIT command is normally used just after the DIAL command to allow time for the call to go through. SCADAWARE® Command Reference Manual 32 Dec 2001 - Preliminary Example: DIAL ; Phone to default number DIAL 837-3699 ; Phone dial out DIAL MP36A ; Radio type dial out DIAL 0 ; special Broadcast mode for multi-drop Related: SET MEDIA, WAIT, PHONE, HANGUP DIR Display DOS File Directory (1) This is very similar to the traditional DOS Directory command, except that the output can be paged for easier terminal viewing. The only parameter is a file specification like *.dat to request a directory display of a particular set of files. The default file extension is RTU. So, entering DIR VR* is the same as entering DIR VR*.RTU. Examples: DIR *.RTU DIR START* Related: SET PAGE DISABLE Temporary Alarm Disable for Channel Range (2) Sometimes it is desirable to temporarily disable the alarm action of a channel. For example, if a piece of monitored equipment is being repaired many nuisance trips may occur. The DISABLE command allows the point to be ignored and not be processed by the system. Disabled points are indicated as disabled in reports and on displays, but no other action is taken on them. It is a good idea to disable all points that are spare so that they will not clutter displays or cause nuisance alarms. The disabled state is not stored in the channel configuration file with the SAVE command, so disabling a point and then SAVING will not cause the channel to be permanently disabled. However, the disabled state does get stored in the data image if image saving is turned on. This will cause the channel to remain disabled, even after system restarts. See the IMAGE command for more details on saving the data image. A range of channels can be specified to disable a number of points in a single command. If required, several ranges can be specified on the same line. Example: DISABLE S10:S16 m1:m3 a4:a5 Related: ENABLE, CHANGE DISCONNECT Packet Radio Modem Disconnection (1) This command is implemented to handle the DISCONNECT response from a packet radio controller (PRC). Normally, all responses are ignored. However, the DISCONNECT response is detected and processed in a manner similar to the BYE command. This command should never have to be used by anyone and is only there to avoid problems with disconnects from some brands of packet controllers. Related: BYE, PRC SCADAWARE® Command Reference Manual 33 Dec 2001 - Preliminary DISPlay Display Channel Data (1) This is the primary on-line data display command. The parameter required is the starting channel to be displayed. Only about 20 lines can be displayed on most terminals, and the program will limit the display to this number if more are specified. Note that all display actions can be accessed via the built-in main menu system reached with the F9 function key. The normal use of the command is DISPLAY followed by a channel type. For example, DISPLAY T will put up a timer channel display starting with the first timer channel. To display a specific channel use the DISPLAY command followed by a channel tag. A display can also be started from the main menu or by pressing the F7 key. The DISPLAY command can also be used to locate new alarms that have not been acknowledged by the operator. The DISPLAY FIRST command will display the channel that first went into alarm for the current rtu. After the First Out alarm is acknowledged, the DISPLAY FIRST command will cause the system to search the current RTU for new alarms using an internal channel order. When no new alarms for the current RTU are found, the system will scan other RTUs for pending alarms. When no new alarms exist, a message is displayed indicating there are no new alarms. The DISPLAY FIRST command can also be initiated by pressing the SHIFT-F7 key. Normally, the DISPLAY command will operate in a continuous display mode where the screen is updated as fast as possible. If the SET CONTinuous OFF command is used, only a single screen will be displayed per entry of the command. Local terminals (i.e. high speed) will normally have continuously updated displays, while slow remotes will get a single display screen by setting continuous off. The display is terminated with the ESC key. During continuous displays, the operator can switch channel types by entering a letter to indicate the desired channel type. The selections are shown in a prompt bar at the bottom of the display. Only channel types available on the particular configuration will be shown in the prompt. The + and - keys can be used during continuous displays to move among the various RTUs on the system. However, the program will not allow movement into RTU 0 using these keys. If displays are longer than a single page, the U or PGUP keys can be used to move up, and the D or PGDN keys can be used to move down. Also, the up and down arrows can be used to scroll a single line at a time. Each channel on a system has an alarm time and date associated with it that is used to keep track of the last time the channel went into alarm. During continuous displays the [ENTER] key can be used to toggle between several display modes. One mode will display the alarm time and date and the other modes will display other relevant channel information. For Output type channels, the ENTER key has no effect on the display. No toggling will occur because all relevant information, including the alarm time and date, is able to fit on the screen at the same time. Initially, each channel's alarm time and date are set to midnight on January 1, 1900. This time and date will appear in the display for any channel that has not yet gone into alarm. When a channel goes into alarm its alarm time and date will immediately be set. That time and date will remain until the channel goes until alarm again and a new time and date is set. The alarm time and date do not clear simply by returning to a normal state. Example: DISP ; Default to S1 DISP A ; Display analog channels starting at 1 DISP V22 ; Put up display containing channel V22 DISP FIRST ; Display first out alarm channel DRAW Draw Graphic Line on Display (1) SCADAWARE® Command Reference Manual 34 Dec 2001 - Preliminary Draw provides a simple line drawing facility that is used when in graphic mode. The beginning and ending positions of the line are provided as either pixel coordinates or percentage of screen. Refer to the Graphic System Documentation for more information. Examples: Draw 10 20 100 200 ; from col 10, row 20 to col 100, row 200 in pixels draw 0.1 0.2 0.8 0.9 ; from 10% X 20% Y to 80% X 90% Y Related: DUMP Show I/O, RTU, Variable Data, etc. (1) This command is used to get a configuration display on the I/O point system, individual RTU setups, specific task data, and more. The options are: TASK x Current or specified TASK (by number). RTU x - Current or specified RTU (by number). LINK - All comm links. GROUP All comm link groupings. IO x - All or specified I/O drivers and maps. VAR - Task variables used by expression evaluator. COMM - All comm ports. CHAN x Text line for a single channel or channel range. AGA x - Specified meter channel internal values. PID x - Specified PID Channel Internal Values. FILE - All open files. ATTR - CRT attributes, using example displays. SCREEN Sends copy of screen to printer. FLAG - Shows status of all globally defined flags. RFLAG - Shows status of all flags for the current RTU. DB or DBASE All open databases and current database information. DUMP SCREEN is a command that allows for custom displays on the local CRT to be printed. To use this command, the SET PRINT ON command must have been entered at some time to allow local printing. The command will use the system's BIOS print screen driver, and will follow the screen image with a line telling the system name, rtu name, and time and date of the printout. This command will be useful for a command file that clears the screen, paints a custom display using SAY and CURSOR commands, and then does the print screen. Example: DUMP TASK 3 DUMP RTU 2 DUMP CHAN C1:C8 DUMP IO DUMP AGA M2 ECHO Send Text String to Comm Line (1). When the program is reading a command file, it can use this command to send a line of text directly to the communications channel. In the case of the local console, this is useful for displaying status messages from within a command file. For remote terminals, this command can be used to send SCADAWARE® Command Reference Manual 35 Dec 2001 - Preliminary non-standard configuration information to the communications controller (modem or PRC). Many of the code conversion features of the ECHO command are also used in the expansion of lines being processed by other commands. ECHO sends the line unaltered except for numeric values entered with the # key and special codes beginning with a dollar sign ($). Values following the # key are converted to a single ASCII character, normally a special control character. For example, #3 is a Control-C, #13 is a carriage return. These decimal values represent the numeric value of the ASCII code for these control codes. If you do not know what ASCII values are, you probably should not be using this command. The special dollar parameters can be specified in an echo line by using the dollar ($) sign followed by a key letter. These special codes will be expanded at run-time to provide information within the text of the line. A literal string can be contained within double quotes which will be displayed without the quotes at runtime. Note that some codes are not available in SCADAWARE Lite. The special codes are: $S System name, set in the NAME line of the DAT file. $L Current link number. $T Current time of day. $D Current date. $#T Time of current database record. $#D Date of current database record. $.T Last update time for the current RTU. $.D Last update date for the current RTU. $@ Last update time and date for the current RTU. $@RTUID Last update time and date for specified RTU. $N Text name of the current RTU. $R 8 character ID of the current RTU. $$ A single dollar sign. $U User's identification from password system. $0-9 Command file command line parameters. $%0-9 Task string variables. $( ) Any valid TSP expression. " " Return string inside of quotes, with or without a $. Unless the special accent mark (') is used at the end of the line, the ECHO command will send a carriage return and line feed character at the end of the text message. If the special character is used, the line is sent without the CR/LF. Examples: ECHO #7 TASK 1 Setup Complete ECHO Alarm at $T on $D ECHO Current link is $L Echo WC45 updated at $@WC45 ST10 Updated at $@ST10 ; specified RTU name Note: The #7 is the ASCII value for the BELL, or terminal beeper. Related: HAYES, PRC, FORCE, MSG EDIT Access Internal Text Editor (2) SCADAWARE has a simple text editor which can be used to create and modify all of the text files used to configure and operate the system. A separate manual provides details on operation of the editor. This section provides only a brief overview of the feature and its access from within SCADAWARE. SCADAWARE® Command Reference Manual 36 Dec 2001 - Preliminary This command can be used to edit configuration files, RTU command files, MENU files, or any other DOS text file. The editor can only be used on the local CRT console, not on remote displays. The editor has many features in addition to the usual insert and delete functions. Some of these features include find and replace, block moves, block copies, block erase, text printing, and word wrap. The control keys used to drive the editor are similar to the standard DOS EDIT, DBASE, and other DOS programs. An on-line help file (called RTUEDIT.HLP) can be displayed by pressing F1 while in the editor. This will cause a small screen to appear with hints on the various editor functions. Entering EDIT by itself will cause a list of files to be displayed. The arrow keys (or mouse) must be used to select the file to edit. The list of files to choose from is determined by a file specification that is remembered by the text editor. When the program is started the default file specification is *.RTU. Whenever a file specification containing a star (*) character is entered along with the EDIT keyword, that file specification will become the default for any future edits. For example, simply entering EDIT once the program is started will cause a list of all the RTU files to be displayed. *.RTU will remain the default file specification until changed. Entering EDIT *.LIB will cause *.LIB to become the default file specification and a list of all the LIB files to be displayed. However, entering EDIT MYFILE.LIB will not cause the default file specification to change because a wild card character (*) was not specified. Entering EDIT followed by a complete file name will cause the specified file to be loaded into the editor. Entering a file name such as START*.RTU will cause all of the STARTx.RTU files to be displayed. Entering EDIT *.DAT will cause all of the DAT files to be displayed. The editor provides a prompt for a file name when doing a block read or block write. This can be used to read existing RTU files into a single LIB file by doing control-K-R to request a block read. Simply specify each existing RTU file to read them into the single LIB file. While in the editor, some of the normal function key functions are not available because they are used by the editor. Some of the keys, like F1 silence, can be accessed by pressing the ALT key when pressing the F1 key. So, ALT-F1 in the editor is the same as F1 outside of the editor. The key assignments of the editor are similar to those of DOS BASIC and Edit, Dbase, Borland Products, and many other traditional DOS programs. PRIMARY ALTERNATE FUNCTION F1 Request help. F2 ^KS Save and continue editing. F7 ^KB Mark start of block. F8 ^KK Mark end of block. ^KD Save and switch files. ESC ^KQ Quit without saving. INS ^V Turn insert mode off and on. DEL ^G Delete to right of cursor. BSP Delete to left of cursor. ARROWS ^SEDX Move up, right, down, left. PGUP ^R Move back a page. PGDN ^C Move down a page. HOME ^QR Top of file. END ^QC End of file. AUTOMATIC FILE BACKUP A SET command option is available to determine if the editor creates a backup file every time a file is saved. On systems with limited disk space, the accumulation of backup files causes a storage SCADAWARE® Command Reference Manual 37 Dec 2001 - Preliminary space problem. Using SET BACKUP OFF will cause the editor to skip the generation of backup files. The default is OFF. See the separate editor manual for a more detailed description of the editor. ELSE Conditional Statement Processing (1) The IF statement will allow sections of a command file to be skipped if the associated expression evaluates to 0. The ELSE command allows a section of code to be processed when the IF's expression does equal 0. See the description of the IF command for more information. Example: IF O1 = 0 msg Output 1 is not on else msg OUTPUT 1 IS ON NOW endif Related: IF, ENDIF ENABLE Re-enable Channels Affected by Disable Command (2) Channels that have been disabled (see DISAble above) are activated with the ENABLE command. This command can accept a range of channels, so a number of similar type channels can be enabled with a single command. Multiple channel ranges can also be entered in a single command line. When channels are enabled, they regain all of the attributes they had before being disabled except for their alarm status. All points being enabled are set to the NO ALARM state, so that their current state will cause the alarm mode to be accurately set at the time they are enabled. Examples: ENABLE s3:s6 ENABLE S1:s4 a4:a6 o3:02 Related: DISABLE ENDIF End of Conditional Statement Processing (1) Every IF statement must have a matching ENDIF statement to mark the end of the conditional statements. See the IF and ELSE commands for further information. Example: IF V1 > 10 msg Value 1 is greater than 10 ENDIF Related: IF, ELSE ENTRY Screen Oriented Data Entry and Display (1) This command is used to set up an entry screen and allow the operator to edit existing values. Channel values, database variables, local variables, public variables, and string variables may be edited SCADAWARE® Command Reference Manual 38 Dec 2001 - Preliminary using this command. When using an entry screen to edit variables the user can move from field to field making changes and then either save all variables or abort all changes with a single keystroke. ENTRY is a more powerful way to edit system variables than can be done with the simpler INPUT command. The ENTRY command must be processed from within a command file and can only be processed by task 0. Therefore, to setup an entry screen the user must create a command file which consists of several ENTRY commands. The ENTRY commands will define the entry screen title, the variables to edit, the prompts to display for each variable, and the screen position for each field. After all fields are defined the command CONFIG ENTRY is used to actually display the entry screen and allow the variables to be edited. Of all the variables that can be edited, only the string variables (denoted by the preceding % sign) will accept text as input. All other variables are defined as real numbers and will not accept anything other than digits and decimal points. The ENTRY setup allows for range checks to be put on numeric entries so that only values within the range will be accepted. The following is a list of keywords and parameters that can be used with the ENTRY command to define an entry screen: TITLE TitleString ADD PrCol PrRow PrStr Var [FldCol FldRow LoVal HiVal DecPlaces FldWidth] TEXT Col Row TextString CLEAR The keyword ADD is used to add a variable to edit to an entry screen. The parameters that must be specified when using this keyword are the column and row of where the prompt will be positioned, the prompt string itself, and the variable to edit. Other parameters can also be specified when using this keyword. These optional parameters are the ones listed inside the brackets. Default values will be used if these parameters are not specified in the command. The default location for an entry field is right behind the prompt on the same row. No range checking is performed when editing real type variables if a high and low limit are not specified in the command. Also, a default of 2 decimal places and a field width of 8 are used for the format of real type variables if not otherwise specified. For most applications the default field width of 8 will work fine. This is because there are usually only a few values that are put on one screen and there is plenty of room to put the variables being edited. However, on screens where many variables must be edited the default width can make the screen overly crowded. Space on such screens is sometimes wasted on numeric value fields that contain only 2 or 3 digits. In these situations, the total field width of the formatted number can be specified by the user in the ENTRY command. It must be at least two more than the value specified for the number of decimal places. The keyword TEXT is used to position a text string on an entry screen without adding a variable to edit. The text string can contain the special $ codes contained in the ECHO command. The keyword CLEAR is used to deallocate all memory used by the current entry screen. The CLEAR option should never have to be used because all memory is automatically deallocated upon termination of the data entry screen, but its use is recommended to be compatible with planned extensions to the ENTRY command . The only time it might be necessary to use the CLEAR option is if fields were added to an entry screen but the entry screen was never displayed by using the CONFIG ENTRY command. A maximum of 64 variables can be added to any one entry screen for editing. There is no limit to the number of text lines that can be added to an entry screen. ; sample Entry screen file entry clear ; clear any existing entry setups Entry, title, SAMPLE ENTRY SCREEN entry add 5,6, Gas Gravity,V5,20,6,0.50,0.80,3 entry add 5,8,Percent N2,V6,20,8,0,10,3 entry text,20,21,Enter the New Values SCADAWARE® Command Reference Manual 39 Dec 2001 - Preliminary config entry ; process the waiting screen screen This small file will put up two fields with prompts and put the local user into the entry mode. Although only 2 entries are in the example, actual programs can use up to 64 different fields on a single "logical" screen. If the row and column positions are off the physical screen, the ENTRY processor will automatically scroll the screen to make the fields visible on the screen when the cursor moves past the screen boundary. Notice how the numeric entries have the optional range specified on their setup line. This prevents the user from entering bogus values because ENTRY will not accept values beyond the specified range. Related: INPUT, CONFIG EXEC Execute a DOS Command, Including DOS itself (2) This command allows access to the DOS operating system either directly (using the standard command.com) or by running the specified program. The RTU program is capable of executing a DOS program as a subtask. The only limitation is the available DOS memory for the Shell or Exec operation. A command line option (/E=) is available to reserve memory for an Exec operation. This must be specified when SCADAWARE is started as run-time adjustment of the program's memory is not possible. EXEC is handy for "shelling out" to DOS to run small programs such as PCCLOCK or ATCLOCK or any other well behaved small DOS program. The problems arise when the programs do things directly to the computer's hardware (sort of like the RTU program itself does!). Many programs are simply not designed to run with other hardware intensive programs, and many will hang the system. This command requires a certain amount of available memory to be able to execute successfully. The more channels a system has the more memory it uses when running the SCADA program. This means that there is less memory available for doing other things such as shelling out. If there is not enough memory available to process this command successfully, a message will be displayed and the command will be canceled. Another complication is the use of the serial port to operate DOS. Although this is acceptable according to DOS technical information, in practice there are many restrictions. When using COM ports, special handling of input and output data must be provided to allow programs that normally access the local keyboard and screen to instead access the remote terminal. DOS itself is not too bad, and requiresthe addition of redirection codes on the command line (like < COM1 > COM1 ). These codes are added automatically when this command is used from a serial port task. Programs not using DOS for console I/O will probably not operate properly because their output will end up on the local CRT rather than the user's remote terminal. This may be tolerable as long as the program does not require any operator input and output. For example, PCCLOCK and ATCLOCK programs used to set the internal timekeeper do not require any operator input, and can be run fine. Other programs are not as easy. Another problem is that the RTU TASK dispatcher (the program that allows multi-tasking) does not want to swap tasks that are currently running a DOS operation. Shelling out to DOS or a DOS program will stop all background tasks that operate as normally scheduled tasks. Tasks that operate directly on each system tick (like the counter channel processor) will continue to operate during the DOS operation, but all others will be suspended. Experiment fully with all programs before running them on a remote unit to avoid system lockups. Examples: EXEC PCCLOCK/S SCADAWARE® Command Reference Manual 40 Dec 2001 - Preliminary EXEC COMMAND.COM Related: SHELL FAX FAX Report Generation and Control (1) The full version of SCADAWARE can generate and transmit FAX reports over phone lines using a standard PC FAX Modem. Use of this feature requires proper setup and configuration of the modem as one-time setup with the OPTION form of the FAX command. Other forms of the command are used to generate and send the report in a multi-step sequence consisting of: 1. Produce standard text form of report using SCADAWARE features. 2. Generate FAX image from text file using FAX MAKE command 3. Use FAX SEND command to send fax image The FAX OPTION statement is used to provide setup information needed by the fax processor during transmission. This information can be specified during startup or at any other time, but it must be done at least once prior to sending of a fax. All options are preceded by a slash /, or dash -, and followed by a parameter. More than one can appear on a single line, although this is not encouraged for clarity reasons. All of the following would follow the command sequence FAX OPTION /I Station identifier ; provide transmitting fax ID which appears on top each page /N Number ; provide complete phone number to send fax to /C n ; Com Port number (1-4) /Q n ; interrupt (IRQ) number if non standard. /B nnn ; modem baud rate, usually 9600 (this is not fax data rate) /F nnn ; Fax data rate (usually 9600 or 14400) /M xxxxxxx ; Modem Init String unique to each fax modem situation /T Title String ; Title used on top each page /H ; enable high-level fax functions if available /S 1|2|A|C ; set fax class to 1, 2, Auto, or Cas. Default is 2 Examples for typical options are as follows: FAX Option -C 3 -Q 9 ; set port to 3, IRQ to 9 Shows multiple options on 1 line FAX option /F 14400 ; fax data rate FAX, option, Number, 1-800-555-1212 ; set fax dialout number. Note commas for delims Fax option /S 2 ; fax modem interface class 2 The FAX command has several other sub-commands in addition to OPTION. They are: FAX MAKE fname Create a fax image file from ASCII file FNAME. No file type is assumed for the input file, but the output will be the same name with a type of APF FAX SEND fname Send the previously created fax image file FNAME with assumed file type of APF. FAX DUMP Provide display information of the current fax setup. FAX SHOW Show real-time status of Fax sub-system. The following simple TSP procedure illustrates the steps necessary to send a typical fax report. SCADAWARE® Command Reference Manual 41 Dec 2001 - Preliminary ; Demo to make and send a fax report msg Generating Text Report set eject off ; no form feed at the end of a report set delim space ; put spaces between writeln outputs sele kissa ; make KISSA current RTU report to faxtest.txt ; write to a ASCII text new file sele kissb ; move on to the next RTU report append faxtest.txt ; add on to existing file created above file append faxtest.txt ; open up file for additional message writeln ; blank line to the file writeln "Thats All Folks!!" file close msg SCADA Report Generated. Adding text comments to end file append faxtest.txt writeln writeln writeln, This is a text comment added to the end of the report writeln, at $T on $D. writeln writeln, The value of Analog Channel 1 is,a1`####.## writeln, Text Text Description of S1 is , s1`z writeln writeln, That is all. file close fax make faxtest.txt ; convert text file to fax image format msg Fax Created. fax option, /i, ARTZ COMPUTER, /C,2, /T,SCADAWARE FAX REPORT, msg Sending Fax now to 9,555-1212 fax option, /n, 9^340-7030 ; set number in modem. Note use of ^ in place of comma fax dump ; tell us what's been setup fax send faxtest.apf ; send the fax format file using fax modem fax show ; display realtime status of fax progress NOTE: During conversion from text to fax format, the program uses a default font style that is contained in a separate file titled APFAX.FNT. This file must be present in the default SCADAWARE directory in order for the conversion to be successful. FILE DOS File Output and Management Functions (2) The RTU program normally sends all responses to the local CRT or serial port operating the task. The program can also send output to disk files (or logical devices that look like files, i.e. PRN) by using this command to set up and control the file. The available operations are: OPEN Create a new file, erasing any old ones with same name. APPEND Create or add on to existing file. CLOSE Stop sending output to the file. DELETE Delete a file from the disk device. S+ and S- Set file more to READ Only or READ/WRITE FILE is a very powerful command, especially when used within a TSP command file. For example, the following script can be used to send a complete data log to a disk file for later processing: SCADAWARE® Command Reference Manual 42 Dec 2001 - Preliminary FILE OPEN DATA.LOG ; open a file called data.log for output SCAN s1:s18 E ; Generate DATA commands for current SCAN a1:a8 E ; status of the system SCAN q1:Q4 FILE CLOSE ; Stop output to the disk file Use of the PRN: device as the file name allows for messages or other information to be directed to the local printer if desired. Examples: FILE OPEN ERROR.LOG FILE APPEND OLDFILE.LOG FILE DELETE BADFILE.LOG FLAG Manipulate System Wide Control Bit Flag (2) This program contains a predefined array of 512 flags that can be accessed by any task. A flag is very similar to a public variable with the exception that a flag can only be set to 0 or 1. The last 16 flags are reserved for system use and are altered with the SET command instead of the FLAG command. The reserved system flags are: FLAG USE 506 Ticking Enabled 507 Warbling Now 508 Warble Enabled 509 Edit Backup 510 Page Eject 511 Alarm Delays 512 Reset Files Activated System flags are set off and on with the FLAG command. To set a flag, specify the number of the flag (1 - 496) followed by either a 0, a 1, or a keyword. Allowable keywords are: TRUE value of 1 FALSE value of 0 ON value of 1 OFF value of 0 FLIP invert current value Multiple flags and flag ranges can be set using a single FLAG command. This can be done either by listing each flag and its value, or by specifying a range of flags followed by a single value. A range of flags can be specified by using either the ".." or ":" notation. All flags can be cleared by using the keyword RESET. The DUMP FLAG command can be used to display the status of all flags. The status of a flag, including the special reserved flag bits, can be checked from within a command file by using the @FLAG(x) function. A special test for @FLAG(0) will return true if any flag is currently turned on. Note that a separate set of flags is available for each RTU through the use of the similar RFLAG command. Refer to the System Design Concepts manual for more information on FLAGs and their use in SCADAWARE applications. Examples: FLAG 1 O ; set flag 1 to 0 FLAG 6 TRUE ; set flag 6 to 1 FLAG 1 ON 2 OFF ; set flags 1 and 2 to 1 FLAG 1..10 ON ; set flags 1 through 10 to 1 SCADAWARE® Command Reference Manual 43 Dec 2001 - Preliminary FLAG 40 FLIP ; change value of flag 40 FLAG RESET ; clear all flags (set to 0) Related: RFLAG, PUBLIC FONT Graphic Font Control (1) The FONT command provides complex control over the graphic font size and style used in graphic based text output procedures. The fonts are contained in the system video ROM and also in a disk based file called RTUFONT.LIB. SCADAWARE has a series of predefined text fonts as follows: FONT FONT PIXEL FONT NUM NAME SIZE Description 0 SYS ? Default System Font 1 Small 8x8 Small ROM Font 2 Medium 8x14 Med ROM Font (EGA standard) 3 Big 8x16 Largest ROM Font (VGA Standard) 4 Sanserif 1-20 Scalable Library Font. Size 3 is aprox 24 pixels 5 Roman 1-20 Scalable Library Font. Size 3 is aprox 24 pixels 6 LED 24 LED Style Font 9 Vertical 8 Rotated Small font The fonts with fixed sizes will always appear the same size on the screen. The scalable fonts (also called stroked fonts) are generated at run time to the size specified in the most recent FONT SIZE command. A size of 3 produces a size of approximately 24 pixels, or 3 times the normal small character height on the screen. Options for the FONT command include Style selection, color selection, alignment, and size as follows: FONT STYLE font_name ; specify the font to use in subsequent output FONT SIZE multiplier ; set scale factor for scalable fonts FONT Alignment position ; right, left, center alignment from specified X-Y position Examples: Font type Roman size 6 ; double sized from normal font color blue alignment center cursor 0.50, 0.50, This is Centered on the Screen Related: Cursor FORCE Send Command Line to Another Task (2) RTU tasks can receive TSP messages from several sources. One source is inter-task messages. This is an internal mechanism that allows one RTU task (and several built-in functions) to send messages into the message queue of another task. With this capability, RTU tasks can control the actions of another task. For example, it may be necessary for the local CRT task to send a message to another task telling it to poll an RTU. The TSP command line is generated by the first task, sent to the second task, and then processed when the message is finally read from the message queue. Note that sending the message does not always cause an immediate reaction from the receiver because it may already be busy processing a previous message or command file. Forcing a line to another task will place the line in a special queue that is checked before any other type of input is processed. However, if a task is currently processing a command file, the queue will not be checked until the file is finished being processed. Therefore, forcing a line to a task that is running SCADAWARE® Command Reference Manual 44 Dec 2001 - Preliminary will cause that task to process the command as soon as possible. This command is most useful to send commands to serial port type tasks. The most common use of this command is to start procedures from the local task and have them processed by a communications task that actually drives a serial port. Another use of this command is to send configuration lines (i.e. SET commands) directly to tasks from the keyboard. Note that the task must be currently running in order to process the line. If the task is stuck or otherwise occupied, it can be restarted via the TASK START command. However, this has the side effect of erasing any waiting messages for the task. The first parameter on the line is either a special keyword, or a task number (or name). The special keywords allowed are CLEAR and DUMP. CLEAR will erase all messages from the input queue of the specified task. DUMP will provide a listing of all messages waiting for all tasks. Example: FORCE 1 SET CRT ANSI FORCE 2 PHONE 555-1234 FORCE clear 0 ; kill messages for task 0 FORCE Dump Related: TASK FORM Real-Time Screen Form Display (1) SCADAWARE has an easy to use screen form function to simplify the design of custom display screens and user menus. The form operates as a combined display and menu hit processor where realtime data can be presented while menu selections are made with keystrokes or a mouse. This is a completely new feature and is subject to revision at this time. Future enhancements will allow for printing of the forms, but this capability is not present at this time other than with PRINT SCREEN functions. The form is created with the text editor and should have a file type of FRM. The main menu has been modified to allow access to FORM display and editing from the position formally occupied by the USER selection. The form text file consists of plain text that will form a backdrop for the screen display. Special identifiers are placed on the form to indicate where data values and menu selections will appear. After the form is defined, additional information is provided in the form file to tell the system what is supposed to appear in the data positions, and what is to happen when menu selections are made. Here is a simple form file: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ SAMPLE FORM FILE FIR RTU [010] [011] Value of Channel V1 is [012] [+] [-] Value of Channel A1 is [013] ÄÄÄÄÄÄÄÄ Total is [014] SIL [s] ACK [a] New Value for V1 [1] New Value for A1 [2] Redraw [r] Form 3 [3] New Form [0] Form 1 [4] Form 4 [5] Exit [x] ?end ?Color blue/gray 010 $R ; insert RTU name automatically 011 $T ; update time on display SCADAWARE® Command Reference Manual 45 Dec 2001 - Preliminary 012 v1`###.## ; show V1 to 2 decimal places 013 a1`###.## 014 $(V1+a1)`###.## ; total of 2 channels a ACK s horn off X ? Msg Form Exited Normally r ?paint + calc v1 = v1 + 1 - calc v1 = v1 - 1 1 cursor 1,24 : input New V1,v1 : cursor 1,24 : clreol 2 cursor 1,24 : input New A1,A1 : cursor 1,24 : clreol 3 ?GOSUB FORM3 ; gosub to a new form called FORM3.FRM 4 ?RETURN ; return to previous form 5 ?FORM5 ; branch to form 5 at same nest level 0 ? Form NEWFORM ;quit this form system and start over ;---------------- end of FORM file -------------- This little text file does a lot of processing once loaded by the FORM statement. The layout of all the prompts and other text will appear just as it looks in the template above. No X-Y coordinates must be calculated by the programmer. The form designer need only write the text and locate the variable locations with the bracketed numbers, as in [020]. The bracket notation is simple. Single letters, characters, and digits are place holders for menu hits. Numbers 10 and above are realtime variable locations. The above file would generate a real-time Form display as follows: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ SAMPLE FORM FILE FOR RTU SMI30 12:29:33 Value of Channel V1 is 12.34 [+] [-] Value of Channel A1 is 25.52 ÄÄÄÄÄÄÄÄ Total is 37.86 SIL ACK New Value for V1 12.34 New Value for A1 56.78 Redraw Form 3 <3> New Form <0> Form 1 <1> Form 4 <4> Exit The amount of information and menu items available for each screen vary between SCADAWARE and SCADAWARE Lite. LITE SCADAWARE Screen Value Elements 60 200 Screen Menu Items 30 200 Text Lines 30 100 Nested Screens 4 8 So, each screen uses single letters or numbers (0-9, a-z, +,-,=, etc) for menu selections, and a multi-digit numbers (010 and greater) for real time variables. The space occupied by the real-time values will be determined by their actual size when formatted per system standards. If no format codes are provided, the default decimal places will be used. However, it is best to individually format each value so that no surprises occur when things change later. The form processor will right justify values so that they align on the right bracket. Space to the left is taken up as needed, so leave enough room between the text and data place holder. SCADAWARE® Command Reference Manual 46 Dec 2001 - Preliminary Menu hits always take 3 character positions. A menu selection item such as [a] will appear on the screen as , converted to upper case. Selecting the item can be done by pressing "A", or by mouse clicking on any of the 3 character positions in . When the menu selection is made, the form processor immediately executes the statement associated with that menu hit. The form remains on the screen during execution. The special control characters used within the form file all start with the question mark. Therefore, the question mark cannot be used as a menu hit identifier. The special control codes which can appear in the form file are: ?END Signals the end of the on-screen portion of the file ?COLOR identify new screen colors, similar to SET ATTRIB ?PAINTMenu option to redraw the Form ?EXIT Menu option to quit the form ?GOSUB Nested call to another form ?RETURN Nested return to calling form ?fname Form name to transfer without nesting ?TSP Process a TSP Command Line During Form Load ?SEL Select logical RTU during Form Load Menu selections with the ? mark are processed differently than ones without the mark. A ? followed by a space tells the form processor that the user wants to exit the form and process the remainder of the menu definition from the normal command prompt. This allows a way to menu-hit out of a form and do something else, including load another form. Use the ?-space combo to leave the form and return to the normal TSP command prompt. The ?PAINT statement in a menu hit tells the form processor to redraw the current form. This may be necessary if text has somehow gotten onto the screen, perhaps as a result of an internally processed command. The ?GOSUB FNAME statement allows another form to be loaded as a subroutine. This is similar to the MENU GOSUB functions in the USER MENU system. If a ?GOSUB is done, the name of the current form is placed in a queue so that it can be reloaded when the subsequent form executes a ?RETURN form statement. This nesting of forms can occur up to 8 deep. The ?FNAME form statement allows transfer to another form at the current nesting level. A ?RETURN executed in the subsequent form will go back to the original form just as if a transfer had not occurred. Note that the ESCAPE key can always be used to exit the entire form system at any time. Any form nesting is lost when the user returns to the command prompt. It is not possible to execute another FORM command within a form itself. To start a new form system, the user must exit the current form and return to the command prompt or a USER menu. FORMs can be started from the main menu with the revised USER/FORM selection. They can also be started from the command line or by any other means with the new TSP command FORM followed by the form file name. For example: FORM MYSCREEN will start a form called MYSCREEN.FRM. A file type other than "FRM" can be used, but this is not recommended. For Task 0, the simple TSP command FORM (without a form file name) can be used. This causes a directory menu to be presented of all files with the FRM filetype. An existing form file can be selected with key or menu. GOSUB Subroutine Call (2) SCADAWARE® Command Reference Manual 47 Dec 2001 - Preliminary The GOSUB command allows processing of command files in subroutine style program flow operations. It is very similar to the READ command. The READ command causes termination of the current file, and continues processing at the start of the named file. The GOSUB command holds processing of the current file and begins execution of the named file. When processing of the new file is complete, the program continues execution at the line following the GOSUB command. This command simplifies the use of standard routines by allowing them to be "called" from within other command files. Command files can be "nested" up to 16 deep. If no file type is specified with the file name, the GOSUB command will search the procedure library for the file. If the file does not exist in the library, the GOSUB command will assume a file type of .RTU and then search on disk for the file. The default file type may be overridden by specifying a file type. If a file type is specified, the GOSUB command will skip the library search and look only on disk for the file. Command line parameters can be passed with the GOSUB command just as they are done with the READ command. Parameters are only local to a single file. In order for a called program to get the parameters, they must be passed on the command line. Consider the following 2 programs started with the command line READ FILE1 PARAM1 PARAM2 PARAM3: ;----------------------------------------------------------- ; Command file FILE1 MSG This is the start of program 1 $1 $2 $3 gosub file2 $3 $2 $1 msg Back to the main file return ----------------------------------------------------------- ; command file FILE2 msg This is from program 2 $1 $2 $3 return ----------------------------------------------------------- When FILE1 is started, it receives the three parameters that become local to that file. When FILE1 calls FILE2, it passes three text parameters to FILE2 in the reverse order because they are defined in reverse order at the time of the call. Running FILE1 as described produces the following output: This is the start of program 1 PARAM1 PARAM2 PARAM3 This is from program 2 PARAM3 PARAM2 PARAM1 Back to the main file Note that the RETURN statement can be used to stop execution of the current command file. Execution also stops when the end of file is reached, so RETURN is only needed if termination is needed within the body of the file. A RETURN from the "topmost" file will return processing to the command line. Examples: GOSUB file1 GOSUB file2.xxx param1 Related: READ, RETURN GOTO Branch to Program Label (1) While processing command files, it is often desirable to have the processing continue at another section of the file. The GOTO allows for a jump similar to a DOS Batch File. The jump point is called a label, and is identified as any word, up to 32 characters in length, that begins with a colon character (:). SCADAWARE® Command Reference Manual 48 Dec 2001 - Preliminary One side affect of the GOTO is that all pending IF statements are canceled. This allows for a branch to be made with a conditional IF without having to keep track of the nested IF level. Consider this small sample file: ; Program to test GOTOs calc v1 = 0 ; initial value cls ; clear the screen cursor 10 1 "GOTO TEST FILE" cursor 10 10 "Value of V1=" :START ; Loop Point calc v1 = v1 + 1 ; increment v1 cursor 25 10 V1 ; display new value sleep 1 ; let value display for 1 second if (v1 10) ; test v1 for over 10 goto start ; if not 10 yet, loop endif msg Program over Labels must begin with a colon in order to be properly found by the GOTO search. In searching, the file is reset to the beginning without the normal DOS close and open operation (similar to REREAD command). This speeds file processing, especially on small files. The search starts at the beginning of the file, so labels that are used more than once in a single file will result in only the first one begin matched. Example: GOTO start Related: READ, REREAD SCADAWARE® Command Reference Manual 49 Dec 2001 - Preliminary GROUP Callout Group Control (2) A callout Group is a collection of communication links that are all activated when channels using the group require a callout. Each channel point has a callout group associated with it, and will use this group whenever a callout is required for either an abnormal or return-to-normal condition. The requirement to call is determined by settings in the point's alarm mode (explained elsewhere). The GROUP command requires that the specific group being referenced be provided as the first parameter on the line. After the group number, any number of links can be referenced. If the link number is entered as a simple number (i.e. 3), then the link is added to the existing links that make up the group. If the link is entered as a minus number (i.e. -3), then the link is removed as a member of the group. This allows for links to be dynamically added or removed from a specific group under program control. To completely clear out a group, the keyword RESET is used just after the group number. If only the group number is entered, then the system will display the links associated with the group. This allows for a quick way to verify the current contents of the group. Examples: GROUP 3 RESET GROUP 2 1 3 5 ; Make links 1,3, and 5 part of group 2 GROUP 3 -4 ; Remove link 4 as part of group 3 Related: LINK SCADAWARE® Command Reference Manual 50 Dec 2001 - Preliminary HALT Terminate SCADAWARE and Return to DOS (2) The HALT command is used to properly terminate the program. If the command is used without any parameters (or if QUIT PROG is selected from the main menu), the prompt "Really want to quit?" will be displayed. A "Y" response will cause task 0 to look for a library procedure or RTU file named HALT and execute it if found. Although this procedure or file does not have to be used, it does allow a more controlled program stop. Typical uses for the HALT procedure or file are: 1. Putting outputs in a particular state. 2. Making final saves to image files. 3. Communications device deactivation. 4. Saving special data to text files. 5. Controlled stop of all tasks. It is probably better to make HALT.RTU a separate file rather than a procedure in the library. This will ensure its availability upon program termination regardless of the state of the library. A typical HALT.RTU file might look like this: task 1 stop task 2 stop task 3 stop task 4 stop image save The keyword HALT (in caps) can be used as a parameter in the HALT command to bypass execution of the HALT file or procedure. Use of the HALT HALT command will also cause the program to be terminated immediately without issuing the prompt to really quit. Examples: halt halt HALT Related: REBOOT HANGUP Disconnect Communications Line (1) The hangup command provides a convenient way to disconnect a radio or telephone communications link. This is slightly different from the BYE command which causes a change in the logical connect state of the current task. The BYE command also causes processing of the BYEx.RTU file to occur. The HANGUP command does none of this. It only processes the disconnect portion of the BYE operation. All other aspects of the task are left alone. This command can be used in special command files that will do non-standard communications operations. A typical example is a command file to call an RTU several times to initiate a modem-monitor reset. This requires several sequential calls in rapid succession, which can be done with the DIAL, WAIT, and HANGUP commands. Example: HANGUP Related: DIAL, WAIT, BYE HAYES Process Hayes Modem Command Line (1) SCADAWARE® Command Reference Manual 51 Dec 2001 - Preliminary If the communications channel is handled by a HAYES (C) compatible modem, the HAYES command can be used to send configuration lines directly to the modem by placing it in local mode. This requires a combination of time delays and special characters (normally +++), and the HAYES command takes care of doing this automatically. Using this line in a command file will allow sending setup information directly to the modem at startup or any other time. This command skips the normal command line parsing so that commas can be used within the hayes string. This command uses everything after the word HAYES as the hayes command string, regardless of the presence of commas or spaces. Typical HAYES commands are as follows: H0 Hang up E0 Echo Off Q1 Quiet mode on S0=x Register for number of rings before answer S6=x Seconds to wait for a dial tone before aborting dialout S7=x Seconds to wait for carrier detect on a callout S8=x Seconds that each comma represents within a phone number S9=x 1/10th seconds that a carrier must be present to be valid S10=x 1/10th seconds that a carrier must be lost to abort S11=x milliseconds for touch tone duration and spacing. Within a phone number, several characters have special meaning: comma Wait for approximately a second (see S8 above) W Wait for a dial tone before proceeding P Use pulse dialing rather than tone T Use touch tone dialing rather than pulse @ Wait for silence before continuing ! Flash (off-on hook toggle for 1/2 second) - Ignored, but makes numbers easier to read A phone number may look like PW9,T1,504-123-4567 This number will be processed as use pulse dialing, wait for a dial tone, dial a 9 (to get an outside line), wait a second, change to tone dialing, dial a 1 (long distance access), wait a second, then send out 5041234567. Note that the dashes in the phone number are permissible but ignored. Because the comma character is used as both a Hayes pause code as well as the program's parameter separator, the program will translate any caret ^ characters into commas at the time the phone number is processed. This allows for pauses in numbers to be entered with the ^ character rather than the normal comma. For example, the number 9^555-1212 will be treated as if it were 9,555-1212 when the number is sent to the modem. Examples: HAYES S0=1 S1=7 HAYES E0 Q1 Related: PRC HELP Display Help on RTU commands (1). The RTU program is designed to operate on a wide variety of computer configurations, and the amount of on-line help available will depend on the amount of local storage available. In small remote systems, the help display may be limited to a list of commands. In larger hard-disk based systems, SCADAWARE® Command Reference Manual 52 Dec 2001 - Preliminary detailed help files may be available for every command. The contents of the help files is left to the user's discretion. The HELP command uses a file name as a parameter. The file must have the assumed extension of .HLP. For example, the file DIR.HLP will contain help information on the DIR command. If no command is specified as a parameter on the line, the HELP command will display a list of files with the extension HLP. The HELP files are simple text files prepared with any editor or word processor that can produce plain ASCII text files. They are sent to the console un-altered, except for lines that begin with the slash character (/). If this character is the first on the line, the line will not be displayed and the command will pause until the operator hits the ENTER key or a time-out period expires. This allows for the file to be broken into logical pages for viewing. Example: HELP HELP PROGRAM HELP AGA3 Related: TYPE HOLD Set Channel Holding Status (2) Each channel has a Hold status that prevents any low-level value conversions from occurring. This is useful when calibrating a channel or when the channel must be manually set for some reason. A common use is to set an AGA3 meter to HOLD, and then calibrate its input channels. During the calibration, the meter value will remain constant. Any totalizer channels reading the meter channel will continue to add the constant value rather than an incorrect value resulting from the calibration process. Examples: HOLD M1 HOLD m1:m2 HOLD M1:M3 A2:A7 Q1:Q5 Related: CHANGE, UNHOLD HORN Annunciator Horn Control (2) The program uses the PC's internal speaker as an alarm horn or "warble." The program also has the built-in ability to manipulate any channel as an alarm horn. Whenever an un-acknowledged alarm is present, the system will set the specified horn channel to 1. When the ACK occurs, the channel is set to 0. Normally, a status input or output is specified as the horn channel, although any channel can be used. The channel is specified with the SET HORN nn command. The HORN command is used to provide generic access to the horn channel without knowing exactly what it is. The only options are HORN ON and HORN OFF. The exact application is up to the user. The horn is the local PC speaker as well as any channel designated with the SET HORN command. The SET WARBLE command is used to control the use of the local speaker as an alarm horn. Use SET WARBLE ON to enable the local speaker and SET WARBLE OFF to disable it. If WARBLE is turned off, the speaker will not sound even if the horn is turned on. Consider the following program stub that manipulates a horn output in two different ways: ; Set up output as a horn and turn it on set Horn O8 ; output 8 is now the horn control SCADAWARE® Command Reference Manual 53 Dec 2001 - Preliminary calc O8 = ON ; directly turn on horn calc o8 = 0 ; turn off the physical output HORN ON ; turn on horn output (and speaker) indirectly HORN OFF ; turn off horn (and speaker) NOTE: The RTU version of SCADAWARE is required to operate a local input/output channel. Related: SET HORN, SET WARBLE IF Conditional Processing Statement (1) Logical "IF" processing can be used in a TSP command file to control program flow. The IF statement allows a TSP expression to be evaluated to either a 0 or non-0 (false or true) state. If the result is true, then the lines in the command file following the IF line are executed. If the result is 0, or false, then the lines following the IF line are skipped until an ENDIF line is processed. The end of a command file is also treated as an ENDIF. Any pending IFs are cleared whenever a command file terminates. IFs can be nested up to 32 deep in any single command file. The program tracks ELSE and ENDIFS using conventional programming logic where each ELSE or ENDIF applies to the most recently processed IF statement. The expressions used in IF statements are processed exactly as they would be in a CALC line except that no assignment to a target variable is allowed. Use parentheses to insure that the desired logical grouping is obtained. The IF and its associated evaluation can be tricky, so experiment with various combinations before releasing programs for general use. File processing in the event of an evaluator error is controlled by the SET ERROR command. Examples: IF (V1 > 10) | (v2 > 10) ; OR test if v2 > 10 msg Both V1 and V2 are greater than 10 else msg V1 only is greater than 10 endif else msg Neither V1 or V2 is greater than 10 endif Related: CALC, ENDIF, ELSE IMAGE Automatically Save Values to Disk (1) The program has an automatic, transparent data save system that continuously saves many dynamic values while the program is running. This feature creates an "image" of the data to be saved in the actual internal format of the program. The IMAGE command is used to save the image to disk, load the image from disk, or have the image automatically saved every so many seconds. The name of the file that contains the saved image defaults to the same as the system name and has a file type of ".IMG". Therefore, a system called VR167 will have an image file called VR167.IMG. The IMAGE FILE command can be used to specify an alternate disk drive and/or file name. The image command options are: IMAGE DUMP ; display image status and contents SCADAWARE® Command Reference Manual 54 Dec 2001 - Preliminary IMAGE ; same as image dump IMAGE LOAD ; load variables from data image file IMAGE SAVE ; force an immediate image save IMAGE ON [xx] ; start automatic image saving IMAGE OFF ; stop automatic save and close image file IMAGE FILE filename ; override default image file name IMAGE TASK xx ; specify which task will save the image IMAGE SELECT xx ; specify the current image slot for a task Loading of IMAGE data is usually only done during system startup. This allows a system to pick up where it left off before the program terminated because most of the dynamic conditions of the program are immediately restored to the values that existed the last time the IMAGE SAVE was processed. This presents a few questions at startup because the user may have special considerations for some values. For example, it may be desirable to have all outputs turned off whenever the system starts regardless of the output states when the program terminated. Simply loading the IMAGE file will restore the outputs as they were when the last image save occurred. To work around this, it is possible to coordinate the RTU configuration load, the image load, and the DRIVER TASK startup such that inadvertent conditions are avoided. Consider the following START0 procedure stub: ; Portion of a START0 process image load if @image(0) = 0 msg Image Loaded Properly else gosub VR123 ; load in the normal RTU configuration data gosub vr123.lin ; link data image save ; initial data save endif calc o1:o8 = off ; make sure all outputs are off task driver start ; now let the I/O system run image on 30 ; start saving every 30 seconds task 2 start task util start task scan start The IMAGE ON command is used to start saving the data image to disk every so many seconds. The default is 60 seconds. An additional parameter can be specified with this command to change the number of seconds between image saves. Note that there are differences in the image file formats of the Full and Lite Versions of SCADAWARE. The image files are not compatible with each other. For more information see Automatic Value Saves in the System Design Concepts Manual Changing of the image file name can only be successful when the file is not already opened. Therefore, the IMAGE FILE command must be used prior to any IMAGE LOAD or IMAGE SAVE actions. Examples: IMAGE ; display image status IMAGE ON ; start automatic saving IMAGE ON 10 ; start saving automatically every 10 secs IMAGE FILE B:MP36 ; set image file name to MP36.IMG on drive B IMAGE SAVE ; save the image right away INPUT Enter Channel Value or String Data (1) This command is used to prompt the operator and allow the entry of a new values for channels, user defined variables, and strings. INPUT uses the same line editor as the PROG command described SCADAWARE® Command Reference Manual 55 Dec 2001 - Preliminary below. Note that many applications previously served by the INPUT command can be better handled by the newer ENTRY screen system. However, INPUT is still desirable for any procedures that must operate over a remote console through a serial port. The command requires a prompt, even if it is blank, followed by a channel or variable identifier. By default, the command will time out in about 10 minutes. The timeout period can be changed by specifying the number of seconds after the variable identifier. The minimum timeout value is 10 seconds. The new value takes effect immediately after completion of the command. Examples: INPUT, Enter New Plate Size,V1 ; use default timeout INPUT, Enter New Flow Rate,V5,300 ; 300 second timeout INPUT, Enter Report Title, %1 Related: PAUSE KEY Temporary Control of Multi-Drop Modem (1) KEY lets the local user control the multi-drop modem or comm link for test purposes. These devices use the RTS or DTR line to control the carrier or line driver which are automatically activated during normal communications. Testing requires that these control lines be manually driven, and the data line be given test data to transmit. All of these functions can be done with the KEY command and its various options. The basic syntax is as follows: KEY port [RTS|DTR] [Period in Seconds] The port is the number of the communications port, such as 1 or 2. RTS or DTR must be specified to tell the system which control line to use. The optional timing period is the number of seconds (defaults to 30) and can be any number. This determines how long the local task will take over the port for purposes of the test. Once KEY takes control, the comm port's control line is activated and a steady 0 signal is transmitted. A timer starts which will time out if the KEY function isn't terminated earlier by the user. During the timing period, the following keys have meaning: ESC Quit the KEY procedure and restore normal port operation Space Toggle the output bit from 0 to 1 to 0. K Turn the output control (RTS or DTR) off and on. T Send a short test burst out the port. Examples: KEY 2 RTS 60 ; Use port 2, pin RTS, for up to 60 seconds KEY 1 DTR ; Port 1 DTR for default timing period LET Alternate to CALC Command (2). The LET command can be used in place of the CALC command to cause execution of the expression evaluator. LET is provided to simulate BASIC programming commands. Refer to the CALC command for more information about this command. Example: LET TOTAL = DAYTOTAL + WEEKTOTAL Related: CALC SCADAWARE® Command Reference Manual 56 Dec 2001 - Preliminary LIBrary Load Command File Library (1) This command is used to load command files into a buffer in memory which acts as a Library of procedures. This command is also used to monitor the files in the Library. The Library system allows loading, merging, and listing of the procedures contained in the Library. For more information on how this works refer to the section called PROCEDURE LIBRARY in the system design documentation. The LIBRARY command options are: LIBRARY LOAD filename ;load a file of procedures into memory LIBRARY MERGE filename ;load entire file into memory as a single procedure using the file name (without the extension) for the name of the procedure. LIBRARY CLEAR ;release all procedures from memory LIBRARY DUMP ;display list of all procedures in memory If filename is not specified in the LIBRARY LOAD command the default file name RTU.LIB is used. If no extension is given in the filename for the LIBRARY LOAD command the default extension used is '.LIB'. If no extension is given in the filename for the LIBRARY MERGE command the default extension used is '.RTU'. Examples: LIBRARY LOAD file1 - load in procedures from file1.lib LIB MERGE x.rtu - load file x.rtu and call it procedure x LIB CLEAR - delete all procedures from memory LIB DUMP - show what procedures are in memory LINK Program and Control Comm links (2) The LINK command allows for programming and control of the communications links to other units. Basically, LINKs are a combination of a task (and its comm port),a phone number, and some control parameters. The link, once programmed, becomes a means of reaching another unit by referencing the link number rather than a specific port and phone number. The LINK command is very similar to the POLL command in that both are used to control communication links. The difference is that the link command is concerned with a specific link whereas the poll command is concerned with a specific RTU. When using the link command the specific link to reset, retry, or activate must be given. When using the poll command only an RTU name needs to be given to reset, retry, or activate a link. The computer will look up the default link for that RTU and use that link to perform the same functions that this link command does. The following is a list of parameters that can be used with the LINK command: link definition - program a link RESET - reset currently active link to idle state RESET xx - reset specified link to idle state RETRY xx - set failed link to active state NOW xx - activate a link SAVE - save link and group data to default file SAVE TO fname - save link and group data to specific file xx - dump link info for specified link To program a link using the link command the following parameters are required in the specified order: 1. Which Link is being referenced. SCADAWARE® Command Reference Manual 57 Dec 2001 - Preliminary 2. Which task will use this link on its comm port. 3. The phone number or radio call sign to use in dialing. 4. The maximum number of re-tries to make the connection. 5. The number of seconds to wait between callouts. 6. The number of seconds to wait for a connect when calling. 7. Yes or No for whether or not this is a host. 8. Link Description 9. Alternate Link Number 10. Number of tries to rapidly callout 11. Max callout tries without resetting counter to 0 Note that commas can be placed in a phone number (for Hayes command processing) by using a caret (^) character in place of the comma. The LINK command will replace the ^ with commas in the phone number field. For example, the line LINK 3 2 9^1^555-1212 5 30 120 ; Link3 on comm 2 will produce a phone number that is actually 9,1,555-1212. The keyword RESET is used to return a link to the idle state regardless of the current state of the link. If RESET is used with no other parameters, then the link to be reset is the link currently in use by the task processing the LINK RESET command. Issuing a LINK RESET can be used to reset the callout request at the sending unit without having to know which of the sender's links was in use. Issuing a LINK RESET for a task that is not currently processing a callout will do absolutely nothing. A likely place to use this command is at the end of a download file. As an alternative, a link number can be specified with the RESET parameter which will cause the specified link to be reset. The keyword RETRY is used to reactivate a failed link. This would be a link that has exceeded its normal retry count. When in the failed state, subsequent attempts to activate the link are ignored until the link is reset (via a LINK RESET command or an F5 Key press). This option, LINK RETRY, will cause the specified link (or the current link if not specified) to be made active again. An example application would be to have an agenda command that periodically re-activates all failed links. The links may have failed because the communications equipment was inoperable, so a periodic RETRY command will kick off the link process. The LINK RETRY only affects links that have failed. Links that are idle or active will not be affected by this command. The keyword NOW is used to activate a specific link. Nothing will be done if an attempt is made to activate a link that is currently processing a callout. If only the link number is provided on the line, then the system will display a description of the link. This provides a quick way to check the current status of a link. An optional keyword ALL is available to be used wherever a link number can appear. This will cause the command to apply to all links rather than just one link. For example, to activate all links you can enter LINK NOW ALL. This can replace the several lines previously needed to activate all of the links in a host system. It will most likely be used in agenda processing where all RTUs are polled at the same time each day. Instead of listing all of the RTUs on separate lines, a single line can be used. Any additional RTUs added to this HOST will automatically be processed by the LINK command when the ALL option is used. The SAVE keyword causes the system's link and group status to be saved to a separate file named after RTU 0 with the file extension of ".LIN". For example, a system called VR167A will have its link setup stored in VR167A.LIN. It is possible to specify a different file name by using the TO option on the same line. Examples: LINK 3 2 555-1212 5 30 120 ; Link3 on comm 2 LINK RESET ; Reset current link SCADAWARE® Command Reference Manual 58 Dec 2001 - Preliminary LINK 2 RESET ; Reset link 2 only LINK RESET ALL ; Reset all links LINK 3 ; Tell us about link 3 LINK SAVE ; Save link data to default file LINK SAVE TO ga694.lin ; Save link data to specified file Related: POLL, GROUP, PHONE LOCAL Declare Local Variables (1) This command is used to declare variables for a task that will be accessible only by the procedure that declares them or by subsequent procedures called with the GOSUB command. For example, if a command file declares a local variable then that file has complete access to that variable. Any command files called from that file with the GOSUB command will also have access to that variable. When the processing of the file that defined the variable terminates the variable is released. See the PUBLIC command for further information on the use of variables. Example: LOCAL TOTAL1 TOTAL2 Related: RELEASE, PUBLIC, GOSUB LOG Control and Display of Logged Data (2) The SCADAWARE LOG SYSTEM stores alarms, data values, and text messages in DOS text files for later retrieval. This system receives input from all alarm points that are programmed to log abnormals. Points with this attribute will generate an alarm message containing the point number, value, time, and date of the abnormal condition. Points that do not have this attribute set will not automatically generate logs. Note that data points do not have to be alarm type channels in order for abnormal conditions to be logged. Return-to-normal conditions can also be logged if the SET RLOG command is issued. This global setting affects all logged points for all RTUs. Channels can also be "logged" via the log command so that their current values will be sent to the log system for later review. This is similar to the action caused by an abnormal condition except that it can be done at any time regardless of the state of the channel. This is useful for totalizer type channels and other channels that must have their values periodically recorded. Logging of messages is done to store text information with time and date stamps. A few events cause logging to occur automatically, but messages can also be stored in command files by using the LOG MSG command. The text string that is saved is everything after the MSG keyword. The message is expanded using the same rules as the ECHO command, so the $T, $D, and other special operators can be used within messages. This is normally not necessary because the log system adds time and date automatically when the message is logged. Logging is done internally by the program in two separate steps. The first is to send the data to a memory queue that holds the messages until they are sent to the disk. The second step is transferring the data from the memory queue to the disk file. The timing on these actions is adjustable to match the performance of the logging system to the hardware. Messages in memory will be lost if the system is reset or loses power. Messages in the log file will be more permanently stored in a standard DOS disk file, with a separate file for each RTU. Each logical RTU set up on a single CPU has its own log file, which is the name of the RTU plus the ".LOG" extension. Log lists only apply to the currently selected RTU. SCADAWARE® Command Reference Manual 59 Dec 2001 - Preliminary The logging options are as follows: LOG - Display contents of the log file and memory log LOG FILE [filename] - Set or display default log file LOG EVERY [xx] - Set or display logging interval LOG CLEAR - Erase disk and memory log LOG RESET - Same as LOG CLEAR LOG MSG any message - Log any text message LOG q1 - Log single channel's current value LOG a1:a8 - Log a range of channel's cur value LOG TASK [xx] - Set or display task responsible for logging LOG FIRST [rtu] - Log first out alarm for current or specified RTU LOG SAVE [filename] - Save log data to disk file for the current RTU LOG SAVE ALL - Save log data to disk files for all RTUs LOG FROM logfile TO outfile FOR range - display channels from a log file The LOG FOR option is used to display a range of channels from the log file. The FROM, TO, and FOR parts are optional and may be listed in any order. Note that setting the logging interval does not cause any data to be logged. This only controls how often the contents of the memory log are transferred to the log file. If the logging interval is set to 0, the memory log is never sent to disk. If a disk error occurs during a log save, the interval is automatically set to 0 to prevent further attempts. Additionally, a command to read a file called LOGERROR.RTU is sent to the utility task. This file can cause any sequence of events to occur, including resetting the log interval. The task which processes the LOGERROR command can be changed with the LOG TASK option. See the SCADAWARE System Design Concepts manual for more information. Examples: LOG every 30 - save any data every 30 seconds LOG file myfile - set new default log file name LOG msg Task 1 communications started LOG a1:a2 LOG from OLDDATA.LOG - look at an old log file LOGON Access Password Security (0) In systems using passwords, the LOGON command is used to gain access by entering a valid password. If the keyword LOGON is entered by itself, the user will be prompted for an access code. An optional access code can be entered directly after the LOGON keyword to eliminate the prompt. This can also be used in command files to change users. If the access code is found in the current Password file, then the user is allowed access to the system at the security level assigned at the time the user's code was entered into the computer. Examples: LOGON Bingo LOGON Related: PASSWORD MAP Open Architecture Data Channel Mapping Control SCADAWARE® Command Reference Manual 60 Dec 2001 - Preliminary SCADAWARE uses a data mapping feature to allow transport of most TSP data values and alarm settings over alternate protocols such as Modbus. The mapping facility allows numeric data values, alarm conditions, setpoints, and other TSP data to be translated into the other protocol using binary bits, words, and IEEE floating point values. The exact syntax of the mapping depends on the protocol being emulated (Modbus, Fisher-ROC, Allen Bradley, etc). Although the concepts among protocols are similar, the exact details will depend on the implementation being performed by SCADAWARE to emulate or enhance the alternate protocol. SCADAWARE can emulate multiple protocols on the same communications channel, allowing it to coordinate communications among diverse units. The various maps are setup and selected using the MAP command and its various options. Refer to the TSP protocol conversion manual for each system for more information. MENU Control Main and User Menus (1) There are two menu systems available to the local user that are controlled by this command. These menus are referred to as the MAIN menu and the USER menu. The Main menu is a PC type "pull down" menu that is used to perform many of the typical SCADA program operations. The Main menu is a standard menu that is the same at each location. The User menu is a "pop-up" type menu system that allows for quick selection of pre-programmed actions. The User menu can be modified to perform custom functions unique to each location. This is done with the use of menu files. See the section on FUNCTION KEYS and MENUs in the System Design documentation for more information on the menu system. When the MENU command is entered by itself, the Main menu is displayed. This is the only case where the menu command refers to the Main menu. When the menu command is entered followed by a keyword, the command refers to the User menu. The User menu is displayed by using the USER command. A list of available keywords used with the MENU command is as follows: LOAD [menufile] load a new user menu file into memory to replace the current one. The LOAD option allows an optional file name to be specified. This can be any legal DOS file name, although one with a ".MNU" extension is recommended. If a filename is not provided, it defaults to RTU.MNU. READ [menufile] transfer to a new menu without nesting GOSUB [menufile] nested transfer to a new menu RETURN go back to previous menu DUMP display information about the current menu file Menu files can be contained within the procedure Library just like RTU command files. The menus are identified with the PROC keyword followed by the name of the menu. The PROC keyword is used even though these files are not actually procedures. The keyword simply serves to identify and separate each section of the Library file. When using menus in the Library file, it is important to not use a .MNU extension when referencing the file. Just as is done with RTU command files, the file processor will skip the Library if the referenced file has a specified file type. So, entering MENU LOAD MYMENU.MNU will force the program to look directly at the current disk, bypassing the Library. However, entering MENU LOAD MYMENU will allow the program to first check the Library. If not found there, the program will append the .MNU file type to the name and look on the disk. For more information on using the Library see PROCEDURE LIBRARY in the System Design Concepts documentation. SCADAWARE® Command Reference Manual 61 Dec 2001 - Preliminary Examples: MENU ; display main menu MENU LOAD SHUTIN.MNU ; load the shutin menu file MENU READ HURRIC ; make hurric current menu file MENU GOSUB EXAMPLE ; nested transfer to example file MENU RETURN ; go back to previous user menu MENU DUMP Related: USER, SET MENU ON MONITOR Watchdog Timer Monitor Control (2) The monitor function of the program toggles the RTS or DTR pin on the serial port once per second as long as all is well within the system. Various functions are monitored by the task manager which will cease the toggle if an error is detected. The serial port pin can be connected to a timeout monitor (watchdog timer) to detect system failures and reset the system. Systems using this feature must have modems that do not rely on the state of the line being toggled. If necessary, remove the pin (usually pin 4 or 20) of the DB25 connector at the modem to prevent any problems. In all configurations, the monitor function operates automatically on COM1. If this causes a problem with certain equipment, then commands should be included in the START0 file to change the port or the status of the monitor signal. Multiple parameters can be entered on one command line. MONITOR ON ; Enable the monitor output MONITOR OFF ; Stop the monitor output MONITOR 1 ; Use com1 RTS line MONITOR 2 ; Use com2 RTS line MONITOR HI ; Set RS-232 signal HI MONITOR LO ; set RS-232 signal LO MONITOR RTS ; Use Pin 4 RTS MONITOR DTR ; Use pin 20 DTR MONITOR FLIP ; Invert the control line Examples: Monitor ON Monitor ON 1 DTR MOUSE Microsoft Compatible Mouse Control (1) The mouse command provides control over basic and advanced functions of a Microsoft compatible mouse installed on a SCADAWARE computer. The actual device may be a touch screen or trackball, but the interface is the same and can use this command. Options provide control over the graphic mouse shape, X-Y coordinate display, and low level software reset. MOUSE OFF|ON ; overall mouse enable MOUSE ACK off|on ; Automatic dialog box fo confirm graphic mouse click MOUSE BLIP OFF|ON ; Audible blip on mouse clicks MOUSE INIT ; Low level mouse initialization MOUSE XY OFF|ON ; control display of graphic X-Y coordinate update MOUSE STYLE style_name ; Sets mouse shape to one of the following: ARROW Standard Arrow CHECK Check mark PLUS Plus or Cross symbol BOX Box shape RTHAND Right Hand Symbol SCADAWARE® Command Reference Manual 62 Dec 2001 - Preliminary UPHAND Up pointing Hand STOP Stop Sign QUESTQuestion Mark HOUR Hour Glass MOUSE COLOR color ; set mouse fill color Note that no options are valid for the text mode mouse other than the RESET function. Examples: Mouse XY ON Mouse Style Uphand Mouse color Blue Mouse style arrow Mouse reset MSG Display Message on Local Console (1) During command file execution, it is often desirable to display messages on the local computer's CRT to indicate progress in execution. The MSG command acts just like a FORCE 0 ECHO command, except that MSG lines processed by the local CRT task are displayed immediately rather than being placed as ECHO commands in task 0's input message buffer. Typical applications would be to indicate connections, logon procedures, or any other action that should be noted on the local CRT. Example: MSG Task 1 Connected at $T Related: FORCE, ECHO PAINT Transparent Graphic Image Display (1) PAINT is used to place scalable graphic objects contained in disk based GIF and PCX files onto the graphic display screen. Objects (images) can be scaled up and down, and can be placed at any pixel coordinate or percentage of screen X-Y. Refer to the Graphics System Documentation for more information on PAINT. Related: Backdrop PASSWORD Access Password Setups (3) The Password system provides a means of controlling access to the system by requiring security codes to be entered by each user. The PASSWORD command is used to display and edit the list of eligible users. Each user has a password and a security level assigned with this command. Only level 3 (supervisor) personnel can access this command and make revisions to the current password setup. See the section on Passwords in the System Design Concepts manual for further information on the password system. SCADAWARE® Command Reference Manual 63 Dec 2001 - Preliminary PAUSE Display Message and Pause for Confirmation (0) Command file execution can be controlled manually with the PAUSE command. The keyword PAUSE by itself will cause the message HIT ANY KEY TO CONTINUE.. to be displayed for 30 seconds or until a key is pressed. In either case, processing will continue with the next line in the command file. There are several optional parameters that can be used with the PAUSE command. These parameters are: 1. Prompt Message 2. Default Response (Yes or No) 3. Timeout in Seconds 4. Continue File Processing on Negative Response (Yes or No) Not all parameters must be specified but the order must be correct. Commas should be used as delimiters in the command so that the Prompt Message can have embedded spaces and omitted parameters can be indicated. If a parameter other than the Prompt Message is provided, a YES or NO will be displayed after the prompt message which indicates a default positive or negative response, respectively, that will be generated by the PAUSE command. This response is used to determine if processing of the current command file should continue or be terminated. The default response will be accepted by the PAUSE command if the user simply presses the ENTER key or allows the command to time out. The default response that is displayed is controlled by the second parameter in the PAUSE command. If this parameter is not specified a NO will be assumed. The user can override the default response by entering YES, ON, or 1 to generate a positive response or by entering NO, OFF, or 0 to generate a negative response. Normally, a negative response will terminate file processing and a positive response will allow processing to continue. However, this is only the default setting and can be changed in one of two ways. First, the SET PAUSE command can be used to control file processing. The default setting for each task is SET PAUSE ON, which allows file processing to continue only when a positive response is generated. As an alternative, the SET PAUSE OFF command can be used to allow file processing to continue regardless of the response generated by the PAUSE command. Remember, the SET PAUSE command is used on an individual task basis, not as a global setting. Second, the fourth parameter on the line of the PAUSE command can be used to override the current SET PAUSE setting. Specifying a YES for this parameter will allow file processing to continue regardless of the response generated by the command. Likewise, specifying a NO will allow file processing to continue only when a positive response is generated. If command file execution is to continue on a negative response , the user must be able to determine if the response was a Yes or a No. This can be done with the @yes(0) and @no(0) functions as shown below. Example 1: set pause off ; do not stop on a No response pause, Enter Y or N, y, 10 ; wait 10 secs, default resp is Yes if @yes(0) msg User entered Yes else msg User entered No SCADAWARE® Command Reference Manual 64 Dec 2001 - Preliminary endif Example 2: set pause on ; stop on a No response pause, Enter Y or N, y, 10 if @no(0) msg This line will never appear because processing stops on No else msg This line will appear if Yes is entered endif Example 3: pause, Enter Y or N, n, 10, y ; last y will cause file ; processing to continue no matter ; what the response if @yes(0) msg User entered Yes else msg User entered No endif Examples: PAUSE PAUSE, DO YOU WANT TO CONTINUE? PAUSE, WANT TO CONTINUE?, N, 10 ; wait only 10 seconds PAUSE, OK TO GO ON?, YES PAUSE, WANT TO CONTINUE?, Y, 45, Y PHONE Set the dial out Phone Number or Radio Call Sign (2) The PHONE command was used in earlier versions of the software to set the phone number for the currently selected RTU. This has been replaced by the complex LINK system (explained elsewhere) that allows for many phone numbers to be used in each computer. The PHONE command has been retained, although its action is different than earlier (pre 1989) versions. Each RTU has a default link assigned to it in the main configuration file when the program is first started. The PHONE command is now used to set the phone number for the default link number assigned to the current RTU. A typical use of the PHONE command is similar to the earlier versions, where a command file will contain a SELECT RTU command followed by a number of RTU related commands. In this context, the PHONE command will work as before. Examples: PHONE 555-1212 PHONE WC433A ; radio example Related: LINK PLAY Audio Subsystem Control (1) PLAY is used to playback prerecorded sounds over the PC sound sub-system. Installation of the sound system requires system-specific drivers to be loaded prior to the start of RTUMON3. SCADAWARE allows playback of multiple sounds in sequence such that separate discrete phrases can be joined to make meaningful messages. Once the required individual phrases are available as WAV files SCADAWARE® Command Reference Manual 65 Dec 2001 - Preliminary on disk, they can be combined into various strings to announce any desired message, including those with numeric runtime values. Phrase playback can be manually initiated from the keyboard or from a menu selection. They can also be activated automatically from a TSP command file, or by an alarm condition for any data channels set to Play Sounds on abnormal. PLAY can also automatically control a Push-To-Talk (PTT) output control to key a radio or PA system. If specified with the SET PTT xx command, the PTT output channel will be activated and a slight wait inserted before playback of the audio message. After the message is complete, another slight delay is inserted before the PTT is deactivated. PLAY occupies complete attention from the task executing the commend, although other tasks are allowed to run during playback. If the local console executes PLAY, it will be held up until the message is complete. The utility task can be used instead to allow playback in the background. In complex systems, a separate PLAY task can be installed to provide separate processor time specifically for audio playback. The syntax of the PLAY command provides for direct specification of the desired phrases. It also allows for a tag reference to be made which causes the command to search a text file which associates predefined phrases with specific tag names. This permits direct announcement of specific phrases, or indirect announcement of phrases associated with a specific data point. To play a direct sound or list of sounds, the PLAY command is used with the desired phrases on a single command line, as in: PLAY COMPRES SHUTDOWN This simple example causes the PLAY subsystem to look for two audio files, COMPRES.WAV and SHUTDOWN.WAV, and play them in sequence. Phrase sequences can also be executed by reference to a tag name. The file which contains the predetermined phrases is a simple ASCII text file for each logical RTU on a system. The default file extension is .PLY. Each line begins with the tag name for the point to be defined, followed by the list of phrases associated with this point. A short file for an RTU named GASMET1 may look like this: ; FILE GASMET1.PLY ; Play List for RTU at Gas Meter One (GASMET1) DIFF1 Low Flow Rate COMPSD Compress Shutdown METER1 Low Meter 1 Rate $(M1) This file defines message strings for three separate RTU data points: DIFF1, COMPSD, and METER1. The words following the tag names are WAV sound file names which are created with software provided by the sound system vendor. The sound files required for this sample are: LOW.WAV Low FLOW.WAV Flow RATE.WAV Rate COMPRESS.WAV Compressor SHUTDOWN.WAV Shut Down METER.WAV Meter 1 One Note that several WAV files are used more than once, demonstrating how sound files can be combined and used for more than one complete message. Note also that a runtime expression $(M1) is used for the METER1 message. The $(M1) will be expanded at the time of announcement into a decimal number, such as 16.5, and will be automatically announced as "ONE SIX POINT FIVE." Any numeric value in the PLAY string will be said as a series of numbers. This requires that the numbers 0-9, and the word POINT exist in the Library containing the prerecorded messages. SCADAWARE® Command Reference Manual 66 Dec 2001 - Preliminary The audio WAV files are normally stored in a separate directory which must be specified with the SET PATH SOUND XXXXXX command. Once specified, the PLAY command will use this directory as the default source for all sound files. To override this specification, enter the complete file name for the desired file, as in: PLAY C:\AUDIO\HELLO The presence of \ signals PLAY to not search the default directory. Note that the default file type of WAV is assumed and need not be entered as part of the phrase file name. The command line options for the PLAY subsystem all begin with the slash / character. Only the first letter is significant, although other letters can be provided for clarity. PLAY /TAG xx ; Play message sequence for tag name xx in current or specified RTU PLAY /PATH xxx ; specify default path for Sound files PLAY /HEADER xx ; display file data for sound file xx.wav PLAY /STOP ; cancel any pending sound playback When a point set to PLAY on Abnormal first goes into the abnormal state, a message is sent to the Utility task in the form of: PLAY /TAG RTUNAME.TAGNAME This causes the current utility task to start the PLAY command in /TAG mode where it expects to find a file named RTUNAME.PLY with an entry for point TAGNAME. If the file exists, and the tag name is matched, then PLAY will work with the sequence of phrase messages specified in the file. If no matches are made, then the command is ignored. It is useful to monitor the Util task (WATCH UTIL) during playback to see errors and status reports for the playback system. Example: PLAY This is a test ; 4 phrases - "This", "Is", "a", and "Test" PLAY /TAG COMPSD ; play phrases associated with tagname COMPSD PLAY /STOP ; stop all playback activity Related: SET PTT POLL RTU Poll Control (2) The POLL command is used to control the default link for an RTU. An RTU name can be specified with this command to affect the link for a particular RTU. If the rtuname option is not provided, the system will assume the currently selected RTU. This command can reset a link, activate a link, or reactivate a failed link. See the LINK command for more information about controlling links. The POLL command has the following options. The [rtuname] code indicates that an optional RTUNAME can be specified to override the choice of the current RTU for the command action: RESET [rtuname] - reset default link to idle state RETRY [rtuname] - set default link to active if failed NOW [rtuname] - activate default link for an RTU REPORT [rtuname] - activate link and print a single report The keyword RESET is used to return the default link for an RTU back to the idle state regardless of the current state of the link. SCADAWARE® Command Reference Manual 67 Dec 2001 - Preliminary The keyword RETRY is used to return the default link for an RTU back to the active state if it has failed. This will allow the callout attempt to be restarted. This command is used to do a poll only if it has previously failed. The keyword NOW is used to activate the default link for an RTU. The keyword REPORT is used to activate a link and then automatically print a report at the time the data transfer is time-stamped. Using this option, a report will be printed as soon as a successful transfer is complete, but will not occur if the transfer cannot be done. This eliminates reports that contain old data. Examples: POLL RESET ; Reset default link for current RTU POLL RESET wc458 ; Reset default link for wc458 POLL RETRY ; Re-poll current RTU if link failed POLL NOW ; Poll current RTU POLL REPORT wc458 ; Poll wc458 and print report Related: LINK PORT Set and Read PC Output Port (2) This command is used to read the input value of a port and to send byte values to a port on the PC's I/O port bus. This can be used to control special function cards installed in the system (like small relay alarm cards). The syntax is PORT followed by the port number specified in either decimal or hexadecimal format. This will read the input value of the port and display the value in both decimal and hexadecimal notation. An additional parameter consisting of a byte (0-255) value can also be specified as a third parameter. If a value is specified, the value is sent to the port number provided as the second parameter. Although the address is the same, the physical registers that are read from and written to may be different. As a useful example, consider a Host RTU that does not have an RTU driver installed. The SET HORN command alone will not work on this Host because it does not have the ability to automatically control physical outputs like an RTU. A simple relay card can be installed to provide a status output to control a local horn. But, a specific TSP program must be prepared to control the horn when the specified HORN output is turned on. ; This runs whenever output point O8 turns on ; Assume relay card at address 768. ; board needs the codes 10 for horn on, 12 for off ; This also assumes that the SET RFILE option is in effect if $1 = 1 PORT 768 10 ; turn on the horn else port 768 12 ; turn the horn off endif Examples: PORT 768 2 ; send the value 2 to port 768 PORT 770 ; display value of port 770 PRC Process Packet Radio Controller Command (1) SCADAWARE® Command Reference Manual 68 Dec 2001 - Preliminary Systems equipped with packet radio controllers (PRC) can have commands sent to the unit via the PRC command. The command will send the text line following the PRC keyword to the unit after placing it in command mode. If the unit was on-line prior to issuing the command, and the command is not a DISCONNECT, then the PRC will be placed back on line after the command is issued. The program sends a break signal to the PRC to place it in command mode. After sending the command to the PRC, the program will place the PRC back in Transparent mode for further data transmissions. Common PRC commands are as follows: CONMODE T Set connect mode to transparent ECHO off Set local echo off or on FLOW on Stop echo to screen while typing MONITOR 0 Select data transmission monitor level MYCALL xxxxxx Set station call sign (normally RTU name) RETRY 3 Max number of frame transmission retries STATUS off Controls status codes sent to terminal TBAUD 1200 Sets terminal (i.e. RTU) baud rate TCLEAR Clear the transmit buffer TXDELAY 50 10s of Milliseconds between push to talk and xmit XFLOW off Software xon-xoff flow control. Examples: PRC ECHO OFF PRC FLOW ON PRC MYCALL SMI174 Related: HAYES, ATTAch PROGram Program Data Channel or Comm Link (3) PROGRAM is used to change parameters associated with data channels and comm links. It is similar to the CONFIG command, but can be used by any RTU type task and not just task 0. The user interface is line-by-line rather than screen-oriented. The system will prompt the operator with the required information and the current value for each parameter. The operator can then enter the new information, or simply hit [ENTER] to accept the current value. Entering a ^C (Ctrl-C) will abort the sequence. See the System Design Concepts manual for further information on channel parameters. If the first parameter is the keyword "LINK", then the system expects the link number as the third parameter. The user is then placed into a prompted program sequence for the specified link. This command can be used over a serial communications line to program a channel or link at a remote location. In SCADAWARE Lite, PROGRAM is an overlaid command, and must therefore be locked in with a LOAD PROGRAM statement in the DAT file if remote operation is desired. To program a channel or link locally use the CONFIG command. Examples: PROG S2 PROG LINK 2 Related: CONFIG PUBLIC Declare Globally Accessible Variables (1) SCADAWARE® Command Reference Manual 69 Dec 2001 - Preliminary In addition to the normal channel values, the expression evaluator supports two types of variables which are declared as either PUBLIC or LOCAL. When a variable is declared it is associated with a particular task. The number of variables allowed for a task is determined by a VARIABLES line in the main configuration (DAT) file. The default number of variables allowed for each task is 0. A LOCAL variable is only accessible by the procedure that declares it or by any nested procedure called with the GOSUB command. When the procedure that declared a LOCAL variable is terminated the variable is released. PUBLIC variables are accessible from any procedure and are released only by using the RELEASE command. Public variables are always located at the highest nesting level regardless of the subroutine level at which they were defined. Unlike local variables, public variables cannot be redefined at a lower level as a separate data item. Variables with the same name can exist for different tasks without conflict. Several variables for a single task can also exist with the same name as long as they are declared at different levels. Consider the following three example files: X.RTU Y.RTU Z.RTU PUBLIC A LOCAL B PUBLIC D LOCAL B LOCAL C LOCAL E CALC A = V1 CALC B = V3 CALC E = A + B CALC B = V2 CALC C = A + B READ Y GOSUB Z CALC D = C * 10 If the file X.RTU is processed this is what would happen. Variables A and B would be declared and set to the values of channels V1 and V2. The READ Y command would then terminate the processing of X.RTU, releasing local variable B, and begin processing the file Y.RTU. Within this file the local variables B and C would be declared. (This variable B has nothing to do with the variable B declared in X.RTU.) After setting B to the value of channel V3, C would be set to the sum of variables A and B. Accessing variable A from within this file would be allowed because it is a public variable and can be accessed by any procedure. The GOSUB Z command would then transfer control to the file Z.RTU. The GOSUB command would only suspend the processing of the file Y.RTU, not terminate it. Therefore, the local variables B and C would still be declared and could be accessed within Z.RTU. After reaching the end of the file, Z.RTU would terminate and release variable E. Control would then return to Y.RTU which would set variable D to C*10. Y.RTU would then terminate and release local variables B and C. At this point all local variables would have been released and only the public variables A and D would remain declared. These two variables could then be used by other commands (or other command files) or freed with the RELEASE command. Whenever a variable is referenced, the evaluator begins a search to locate the variable or channel. The list of RTU channels is searched first. If no match is made, the list of LOCAL variables is searched. If still no match is made, the list of PUBLIC variables is searched. Example: PUBLIC TOTAL1, TOTAL2 Related: RELEASE, LOCAL PURGE Purge Characters in Communications Input Buffer (1) Within command files, it is often necessary to remove any garbage characters that may be waiting in the input buffer as the result of a communications failure or other unusual link termination. The PURGE command is used to empty the input buffer so that any waiting characters will not be processed. Example: if @online(1) SCADAWARE® Command Reference Manual 70 Dec 2001 - Preliminary msg RTU is Online else PURGE msg RTU disconnected return endif READ Start Processing Command File (2) The RTU program normally accepts its input from a communications channel or local keyboard. Certain operations can be automated by placing the commands to be executed in a text file (or Library procedure) and telling the program to begin reading the file. Input from the file is processed as if it was typed in by the user. TSP file processing via the READ command is the primary means of automating SCADAWARE processes. Any command file can be loaded into a fixed memory buffer which acts as a Library of procedures. TSP command files can then be executed from RAM memory rather than disk. See the LIBRARY command for details on how to load command files into the Library. To have a command search the Library for a command file the file type must be omitted from the file name in the command. For example, consider the command READ MYPROG.RTU. When this command is processed, the program will search for the file on disk and execute it if found. If the file type is omitted and the command READ MYPROG is used instead, the program will first search the Library for a procedure named MYPROG and process it if found. If however, no Library procedure with that name is found, the program will assume a default file type of RTU and search on disk for the file. If the READ command is processed from within a command file (or Library procedure), the current file is terminated and processing continues at the start of the named file. Refer to the GOSUB command for a way to temporarily suspend processing of the current file while the called file is being processed. When a READ command is processed, the system picks up command line parameters beginning with the file name. This parameter, and those following it, are referenced within a command file as special $ codes similar to the ones explained in the ECHO command. Each parameter is referenced by number, with $0 being the current file name, $1 being the first parameter, $2 the second, and so on. For example, the line: READ SETOUT o1 RTU1 has parameters as follows: $0 SETOUT $1 o1 $2 RTU1 Note that the highest parameter number allowed is $9, and all parameters are cleared when a new file is read. Examples: READ CLEAROUT READ CLEAR.TXT READ SHUTIN RTU1 30 ; pulse RTU 1 shutin for 30 secs Related: GOSUB, REREAD, PAUSE, SET ONLINE SCADAWARE® Command Reference Manual 71 Dec 2001 - Preliminary REBOOT Force Cold Boot of Computer (2) It is sometimes necessary to completely reset a computer to clear some bogus condition that cannot be cleared any other way. This is often done by pushing the reset button, but this can also be done remotely if the computer is still processing commands. The REBOOT command causes the computer to execute the same code that occurs when the reset is pressed. In order to execute, the system will present a prompt which must be entered by the operator exactly as described by the command. This will prevent inadvertent operation of this command. It is likely that the communications channel will be lost when this command executes, so a re-dial will be needed after using it. Systems equipped with TEST's Modem Monitor device normally do not need to use the REBOOT command but can reset the system remotely using this device. RELEASE Remove Temporary Variables (2) Variables created with the PUBLIC and LOCAL commands can be removed with this command. After they are released, they will no longer be available for any purpose. The memory previously used by the variables will be made available for later variable definitions. This is most often used to control memory allocation of temporary variables used within a single operation. When the operation is complete, the variables should be released so that later operations will not run out of variable space. The number of variables allowed for a task is determined at system startup by an entry in the main configuration (DAT) file. The keyword ALL can be used with the RELEASE command to remove all variables that are currently defined for a task. Examples: RELEASE ALL ; release all variables for a task RELEASE TOTAL1 TOTAL2 ; release variables TOTAL1 and TOTAL2 Related: PUBLIC, LOCAL REPORT Generate RTU Data Reports (2) The RTU data can be sent to the PC printer or to a disk file for later printing. REPORT by itself generates a report for the current RTU which goes to the printer. REPORT followed by only a disk file name will cause the report to be sent to that file. An existing file with the same name is overwritten. Report entered from the keyboard or command file will cause the current task to print the report. Hitting the F4 print key will set a flag which causes a REPORT command to be sent to the Utility task (it one exists). In the SCADAWARE LITE program, the command LOAD REPORT must be used in the main confi guration (.DAT) file in order for the REPORT command to be processed by any task other than task 0. CAUTION: Off-line printers can hang the system, so be sure that the printer is always turned on and powered up. An option is available to use a FOR and/or a TO phrase to specify which RTU to print as well as the destination for the report. This allows more flexibility in printing reports for multi-RTU installations. For example: SCADAWARE® Command Reference Manual 72 Dec 2001 - Preliminary REPORT FOR SMI7 TO SMI7.REP This example specifies SMI7 as the RTU to be reported, and the destination is disk file SMI7.REP. If the FOR is not specified, then the current RTU is assumed. If the TO is not specified, then the printer is assumed. Either option can also be used by itself. The REPORT command also has the option to print only the points that are currently in alarm (i.e. the new alarm or in-alarm state). To use this feature the keyword ALARM must be specified somewhere in the REPORT command, such as: REPORT FOR SMI7 ALARM Reports can also be printed in any of the 3 display styles available on the normal F7 display screens. The default will be the natural format for each channel. To generate a report using a specific style, the keyword STYLE must be specified in the REPORT command followed by an additional keyword. The keywords available for specifying a particular style are NORMAL, ALARM, and SETPOINTS. Examples: REPORT ; current RTU to printer REPORT Data.txt ; specify the disk file for cur RTU. REPORT TO daily.rep for hi356a ; specify both REPORT FOR SMI7 STYLE NORMAL REPORT FOR SMI7 STYLE ALARM REPORT FOR SMI7 STYLE SETPOINTS REPORT FOR SMI7 ALARM STYLE ALARM Take a careful look at the last line from these examples. Note that the first ALARM keyword on the line is a stand-alone keyword which requests only the points that are in alarm to be included in the report. The second ALARM keyword is a directive to the STYLE keyword which requests a specific printout format. Related: SET REPORT, SET PRINT, SET EJECT REREAD Restart Execution of Current Command File (0) Command files often need to repeat over and over in a continuous loop. The REREAD command can be placed anywhere in the file to cause execution to start from the top. This would be similar to placing another READ command in the file except that the name of the file must be coded directly into the command. REREAD avoids this by letting the processor simply reset the file pointer and start reading from the top. This also saves the DOS overhead of closing and then re-opening the file. A bit of caution is worth noting when using this command. When a task is processing a command file, it does not allow commands from any other sources (such as other tasks or a communications channel) to be processed until the file is completed. Because the REREAD command continues to process a file without ever closing it, queued messages won't be processed as long as a file is being reread. If this is a problem, there are alternatives to this command. For example, instead of using the REREAD command, use the FORCE command to have the task queue up a message to itself to read the file again. This will allow any pending messages to get processed before the command file begins processing again. Using REREAD does not clear out the command line parameters entered when the file was first started. SCADAWARE® Command Reference Manual 73 Dec 2001 - Preliminary Example: If loops 10 reread endif Related: READ, SET ONLINE RESET Reset Misc. Values and Conditions (2) The RESET command provides different keyword parameters to affect different things. If no parameter is specified then the keyword ALARM is assumed. If a point is set to be manually reset (i.e. not auto reset), then either the RESET command or the RESET function key must be used to restore the channel's alarming ability. When a point has been acknowledged, it can be reset with the RESET button. Points that have not been ACK'd can be ACK'd and reset with the RESET command. This allows for command files to specifically clear any points listed after the RESET command without knowing about the point's alarm state. All channels, a channel range, or a list of channel ranges can be specified to reset alarm channels. The special keywords are : ALL - Resets all cleared alarms channels and resets all counter channels to 0 ALARMs - Reset all cleared alarm channels. xx xx xx - Channel identifiers like S1, O10, etc. Resets channels that have cleared alarms Other keywords used with the RESET command are : FILES - Close all open files OUTputs - Reset local output channels to normal state CALLouts - Reset the link for the current RTU and remove current need to do a callout COMM - Reset communications channel for current task Examples: RESET ALL RESET S1:S32 RESET A1..A10 S1..S8 O1..O8 RESET CALL RESET OUTPUTS Related: ACK, CLEAR RESYNC Reset Incoming and Outgoing TSP Block Counters (2) When the program is operating in RTU mode (computer to computer operations), TSP command lines are automatically formatted to allow for communication error checking. As part of the error checking system, each TSP message sent to another unit is sequentially numbered. Each message received from another unit is also numbered. If the sequence number of an incoming message has already been processed then the duplicated message will be ignored. This type of error checking is useful because it prevents messages from getting out -of-sequence due to poor or slow packet communications. In situations of continuous communication the counters for these incoming and outgoing messages may exceed their limits. If this happens, the counters will roll over and start counting again from 0. This will cause the next message that is transmitted to have a sequence number less than the previous message. Subsequently, the message will be ignored. To keep this undesirable situation from occurring the RESYNC command can be used. SCADAWARE® Command Reference Manual 74 Dec 2001 - Preliminary The RESYNC command is used to reset the incoming and outgoing block counters. In order for the counters on both units to be reset and stay synchronized the RESYNC command must be used in two steps. First process a BLOCK RESYNC command to reset the message counters at the other unit. Then process a RESYNC command that will reset the message counters on the local unit. Example: ; Continuous download file set online on ; only continue if connected block resync ; tell other unit to start over (see below) resync ; reset local counters scan A1:10 E scan S1:s16 R o1:o16 R reread IMPORTANT RESYNC NOTE: Older (pre 10/92) software required that a BLOCK RESYNC be sent to a remote unit prior to doing a local resync. TSP has been standout to allow an automatic resync by the remote unit whenever message number one is received. Therefore, the BLOCK RESYNC is no longer needed to get a remote unit in sync with the sending unit because the receiver will automatically resync when it detects that the sender has reset its counters. Therefore, the BLOCK RESYNC in the above example would no longer be needed. However, the block resync may still be needed when communicating with systems with older software. RETURN Terminate Execution of Command File (1) Execution of a command file normally continues to the end of file before termination. If it is desirable to stop a file in the middle somewhere, the RETURN command can be used. File execution is stopped and the command processor returns to the command mode just as if the file had ended. If the processing of the file was started from within another file then the processor returns to the calling file. Example: if (v1 > 10) msg Terminating the loop now return endif Related: STOP, GOTO, REREAD SCADAWARE® Command Reference Manual 75 Dec 2001 - Preliminary RFLAG Manipulate RTU Control Bit Flags (2) Each RTU defined on a system contains a predefined array of 512 flags that can be accessed by any task. These flags are very similar to public variables except for the fact that each flag can only be set to 0 or 1. This set of flags is also unique to each RTU. The RFLAG command can be used to set RTU flags for the currently selected RTU. A similar command, the FLAG command, can be used to set flags from a group that are common to all RTUs. To set a flag, specify the number of the flag (1 - 512) followed by either a 0, a 1, or a keyword. Allowable keywords are: TRUE value of 1 FALSE value of 0 ON value of 1 OFF value of 0 FLIP invert current value Several flags can be set using a single RFLAG command. This can be done either by listing each flag and its value or by specifying a range of flags followed by a single value. A range of flags can be specified by using either the ".." or ":" notation. All flags can be cleared by using the keyword RESET. The DUMP command can be used to display the status of all flags for the current RTU. The status of an RTU flag can be checked from within a command file by using the @RFLAG(x) function. Examples: RFLAG 1 O ; set RTU flag 1 to 0 RFLAG 6 TRUE ; set RTU flag 6 to 1 RFLAG 1 ON 2 OFF ; set RTU flags 1 and 2 to 1 RFLAG 1..10 ON ; set RTU flags 1 through 10 to 1 RFLAG 40 FLIP ; change value of RTU flag 40 RFLAG RESET ; clear all RTU flags (set to 0) Related: FLAG, PUBLIC RTG Real Time Graphic Control (1) RTG is used to describe and control Real Time Graphic objects in the graphic display subsystem. Refer to the Graphics System Documentation for more information on RTG. SCADAWARE® Command Reference Manual 76 Dec 2001 - Preliminary SAVE Save Current RTU Setup Information To Disk (3) This SAVE command is used to send a logical RTU's channel configuration to a disk file. An optional file name can be specified after the keyword TO. If none is provided, then the name of the RTU plus the ".RTU" extension is used. This saves all of the channel configuration data and current value for each channel in the current RTU. The file that is generated by the SAVE command is a simple DOS Text file that can be easily transported to another unit via diskette or network connection. The lines in the file contain the setup information for each channel in the RTU. The file also has a SELECT line at the start to insure that the computer processing the file selects the correct logical RTU prior to processing the contents of the file. Examples: SAVE ; save to standard rtuid.rtu file SAVE TO C:SETUP.RTU ; save to alternate file Related: LINK SAVE SAY Display Expression Value or Text String (1) The SAY command can be used in command files to display evaluator expressions, channel values, string variables, or text messages on the CRT. It is normally used after positioning the cursor with the CURSOR command. The process of evaluating what to display using this command is exactly the same as it is for the CURSOR command. The only difference is that the CURSOR command specifies the coordinates of where the display will be located on the screen and this command does not. An expression may be displayed by enclosing it in parentheses. A channel value may be displayed by referencing a channel by number or by tag. String variables may be displayed simply by using the % sign followed by a number 0-9. Any parameter that can not be identified as an expression, channel name, or string variable is considered to be a text message. All text messages should be enclosed in double quotes. Although this is not necessary, it is good practice and allows commas and spaces to be embedded in the messages. Parameters should be separated from one another with commas. When text is displayed, it is expanded as is done in the ECHO command. This allows the special $ values to be displayed on the CRT from within a command file. Individual parameter formatting can also be performed by attaching a format string (sometimes referred to as a "picture mask") to the end of an expression, channel variable, string variable, or text message. The format string consists of the accent character (`) followed by a string of characters which each represent a specific format action. Valid characters that can be used in a format string and their associated actions are as follows: A If formatting a channel variable, this will cause the display to use the channel's alarm video attribute. The A is stripped out of the picture mask and does not occupy a character position. X If formatting a channel variable, this will cause a string to be displayed which is dependent on the type of channel being formatted. If formatting a Status Input or Output type channel, the channel's Abnormal or Normal Text will be displayed, depending on the current state of the channel. For any other type channel, this will cause the channel's Units to be displayed. The X is stripped out of the picture mask and does not occupy a character position. Z If formatting a channel variable, this will cause the Channel's Description to be displayed. The Y is stripped out of the picture mask and does not occupy a character position. SCADAWARE® Command Reference Manual 77 Dec 2001 - Preliminary Cxx Center the resulting string in a field that is xx spaces wide. Note that 2 digits must be provided, as in C10 to indicate a field of 10 or C06 for a field of 6. The Cxx is stripped out of the picture mask and does not occupy any character positions. Lxx Left justify the resulting string in a field that is xx spaces wide. Note that 2 digits must be provided, as in L10 to indicate a field of 10 or L06 for a field of 6. The Lxx is stripped out of the picture mask and does not occupy any character positions. Rxx Right justify the resulting string in a field that is xx spaces wide. Note that 2 digits must be provided, as in R10 to indicate a field of 10 or R06 for a field of 6. The Rxx is stripped out of the picture mask and does not occupy any character positions. ^ This character is used to indicate a comma position in the format string. Because the program's command line parser is sensitive to the use of commas and spaces, it is necessary to use a non-comma character to indicate a desired comma position in the format string. To be consistent with other parts of the program, the up-caret character (^) found above the 6 key is used for this purpose. Any ^ characters found in the format string are automatically replaced by commas. The following characters should only be used in a format string when an evaluator expression or a channel variable is being formatted and the resulting string represents a number. # This represents a digit position. Unused digits are left blank if the picture mask does not contain a * or @ character. A floating minus sign is displayed in front of the number if the picture mask does not contain a + or - character and the number is negative. * This represents a digit position. Unused positions are set to * instead of blanks. Only one * is needed in the picture mask to set this option. The sign will not be displayed unless the picture mask has a + or - character in it also. @ This represents a digit position. Unused positions are set to 0 instead of blanks. Only one @ is needed in the picture mask to set this option. The sign will not be displayed unless the picture mask has a + or - character in it also. $ This represents a digit position. A floating dollar sign is placed in front of the resulting number. + The resulting string will contain a plus sign in the position designated by the + character in the picture mask, provided the number is positive. If the number is negative, the - character is displayed in this position instead. - The resulting string will contain a minus sign in the position designated by the - character in the picture mask, provided the number is negative, If the number is positive, this position is left blank. Some formatting examples of the number 123456.789 are: PICTURE MASK RESULT ###### 123457 Note Rounding ######.# 123456.8 Note Rounding ###^###.## 123,456.79 Comma and Decimal +######.### +123456.789 @@@@@@@@@@.### 0000123456.789 Leading Zeros ##########.### 123456.789 Leading Spaces A###### 123457 Alarm Video L12######.# 123456.8 Left Justified R12######.# 123456.8 Right Justified SCADAWARE® Command Reference Manual 78 Dec 2001 - Preliminary If no picture mask is specified for evaluator expressions and channel variables, the format of the displayed numbers will be determined in the same manner as is done for channel displays and reports. The default number of decimal places to be displayed is controlled with the SET PLACES command. This is a global setting which affects the display of all expression results and channel values. However, each channel can be configured to display a number of decimal places that is different than the default. If this channel parameter is set to something other than a negative number, the default number of decimal places is overridden and the specified number of decimal places will be displayed. Examples: SAY "The current time is ", $T SAY "The value of V1 is ", V1 SAY "The value of string variable 0 is ", %0 SAY V3`R10 SAY (SQRT(V1)+1) SAY V1`A SAY V1`AC10 Related: CURSOR, DISPLAY SCAN Request Range of Data Values for an RTU (2) The SCAN command is the primary means of requesting channel data from a SCADA system for transmission to a remote unit. The SCAN command can access simple channel values as well as the internal settings of the channels that control their configuration or alarm action. When getting data values for use in a computer, it is desirable to get them in a condensed format if possible. The SCAN command specifies a range of channels to be sent via a DATA command that the receiving RTU will provide. Besides the required channel range, various code letters are used to indicate the format and content of the data to be scanned. These codes go on the SCAN command line just after the channel range specification and are repeated in the resulting DATA line that the SCAN command generates. Most options are used one at a time, while a few can be used in conjunction with other codes. The available code letters are: CODEMEANING M Alarm Mode (16-bits representing alarm mode settings) W Time delay (Wait) till alarm, whole seconds only A Alarm time and date E Engineering Units data format R Raw data format L Low Setpoint (Engineering units) H High Setpoint (Engineering units) D Deadband (in engineering units only) G Callout Group (whole numbers only) T Time and Date that channel was started @ Time stamp, link reset signal, and remote channel log # Time stamp clear + Add to existing value [ Julian time and date format ] Compress duplicate times and dates on a single line Not all options apply to all channels types. The following matrix identifies the options which are not universially available. The l symbol indicates that the option for that column is available for the channel type of that row. R D T SCADAWARE® Command Reference Manual 79 Dec 2001 - Preliminary STATUS IN l STATUS OUT l VALUE l FUNCTION l TIMER l AGA3 l ANALOG IN l l TOTALIZER l l COUNTER l l l PID l l The # code can be used with other codes and is usually placed on the first SCAN line. The # code will cause the system processing the DATA line to clear out the update time and date. This allows transfers that are terminated abnormally to be indicated by an invalid time and date. Otherwise, the previous time and date would remain as the valid update time stamp. The @ code can also be used with other codes and is usually placed on the last SCAN line. The @ code will cause the system processing the DATA line to do several things. First, the time and date of the RTU for which the command is processed will get updated using the current time and date. The default link for that RTU will then be reset. The current link for the system is also reset. This may or may not be the same as the default link that gets reset. A report will be printed if set to do so using the SET REPORT ON command or if the SCAN command was processed as a result of the POLL REPORT command. Next, any channels that are in alarm and require logging will get logged. The reason for the delay of the logging process until the end of a transfer is to allow the alarm time and date for each channel to be scanned before doing the log (using the A option). Finally, a command will be queued up to read a file with the same name as the updated RTU and the extension ".UP". The "UP" file can be used to perform any function desired at the end of a data transfer. For example, on systems using databases the "UP" file can be used to update a database with the newly received data. The + code can be used with the E and R codes to cause an incremental update of a channel's value. Normally, when a SCAN is done for a channel's value using engineering units, the system that processes the resulting DATA line will replace the channel's current value with the new value. Using the + code along with the E code will cause the new value to be added to the current value. This is most useful for counter type channels that are read then cleared on every poll. The [ code is used in conjunction with codes that cause times and dates to be transferred. This code causes times and dates to be transferred as integer values rather than formatted time and date strings. For time, the integer value represents the number of seconds since midnight. For dates, the integer value represents the number of days since 1/1/1900. Transferring times and dates in integer format reduces the number of characters that must be transmitted from one unit to another. The ] code is also used in conjunction with codes that cause times and dates to be transferred. This code causes duplicate times and dates in a DATA line to be transferred simply as T and D. This reduces the amount of data to be transferred between two units when times and dates are the same for consecutive channels in a range. The optimal choice is to use both [ and ] when scanning for a time or date because together these codes will generate the smallest DATA line possible. SCADAWARE® Command Reference Manual 80 Dec 2001 - Preliminary The L and H codes generate different results when scanning different types of channels. The high and low setpoints for value type channels (all except STATUS and OUTPUT) are sent as real numbers representing the high and low alarm values. The low setpoint for a digital channel is sent as either a 0 or 1 to indicate the normal state of the channel. The high setpoint for a digital channel is sent as either a 0 or 1 to indicate the alarm condition for the channel. It is unnecessary to send both High and Low for digital channels. Either one will do. The M code will generate a DATA line containing the alarm mode settings of the channels scanned. Normally, HOST and RTU systems have slightly different mode settings. The differences are usually related to Call on Alarm, Call on Reset, and the Sound Horn setting. In order to change the alarm mode setting at the RTU, the user will re-program the HOST to have the desired settings for the RTU. After sending the mode to the RTU, simply re-load the HOST's setup file for the affected RTU. This will restore the original HOST settings. This is done by using the READ command followed by the name of the RTU. The R code letter is used to send raw (i.e. direct I/O data) rather than engineering unit data from one unit to another. In this case, the DATA command will represent raw input values rather than processed engineering values. A SCAN for raw data for Analog and Counter channels will generate a DATA line that contains an integer for each channel scanned. Scanning a Status or Output channel for raw data generates a different response. Status and Output channels can receive the off-on status in a packed format, with 8 channels per entry, rather than a separate entry for each channel. For example, issuing a SCAN S1:S32 R will cause the system to respond with DATA RTUNAME.S1:S32 R a b c d where a b c d will be decimal equivalents of 8 bit values. These values represent 8 points of status input. Values for Status Channels 1-8 will be in the first number, channels 9-16 in the second, and so on. Using the RAW mode allows for faster data transfers than engineering mode. Note that the first channel identifier in the DATA response includes an RTU name in "dot" notation. This way, the receiver knows the RTU from which the data came so it can place it properly in its own data table. The channel numbers are relative to the sending RTU, so the receiver has to know which RTU is sending the data. The dot notation is a prefix that is allowed in may instances where a channel name is required. The program takes the values presented in a DATA line and places the values in the system data table as the current point values. Of course, there can be no local I/O scanning taking place or the values will be quickly overwritten by local I/O points. If the time option is specified for a Counter or Totalizer channel, the time and date will be sent as single entries separated by a space. Time always comes first in the pair. Example: SCAN Q1:Q2 T DATA, RTU.Q1:Q2,T,11:22:33 01/02/88,10:20:30 01/02/88 Note that commas are always used as entry separators in the data response so that spaces can be used in the time and date field. The format of how data is transferred is up to the user. SPECIAL @ENDS KEYWORD The keyword @ENDS can be specified in a SCAN command to generate a DATA command indicating the update time and date for an RTU. The format of the command is SCAN @ENDS. An RTU name can be specified after the @ENDS keyword. If no RTU is specified the current RTU is used. The format of the response is DATA @ENDS RTUNAME TIME DATE. The system that processes the DATA @ENDS command will do everything that the @ option described above does. The only difference is that the update time and date are specified in the DATA @ENDS command instead of simply using the current time and date. SCADAWARE® Command Reference Manual 81 Dec 2001 - Preliminary When an RTU with local channels processes the SCAN @ENDS command, the returned DATA @ENDS command contains the current time and date. When a unit with remote channels processes the SCAN @ENDS command, the returned DATA @ENDS command contains a time and date representing the last time-stamp for the RTU. This command is intended to be used at the end of a host to host download. SCANNING FIRST-OUT ALARMS A first-out alarm is the first channel to go into an alarm condition as long as another first out is not pending. Once an alarm is made the first out, no other alarm can become the first out until the current one is acknowledged. Subsequent alarms will still show as NEW alarms, but they will not be the first out. The log system is used to track the first out alarm (lets call it the "FO" alarm). Log table entry number 0 is used to hold the first out entry, and it can be examined at any time by entering LOG FIRST. The current FO alarm can be scanned by using the SCAN FIRST command. This will cause the system to generate a special DATA line that contains the FO channel number, FO time, FO date, and FO value. This DATA line will be processed by placing this information into the FO table entry for the receiving RTU. When scanning the FO channel, always make it the last scan. It must be on a line by itself as well. It must be the last scan because it is possible that previous scan lines caused alarms that quickly became the FO channel. This may not really be the FO because the order of download is not related to the order that the alarms come in. So, let the normal alarm scan think it found the FO alarm, and let the final SCAN FIRST line override any FO found by the local alarm scanner. Note that each RTU has a separate log table, and therefore a separate FO entry. MULTIPLE SCANS ON SAME LINE Multiple transfers can be done in the same command. This speeds half-duplex radio systems that require a lot of overhead when sending each response. To set up multiple requests, simply enter the additional ones on the line after the first one. The SCAN keyword is not repeated, but each channel range and keyword must be present for each group. Also, note that all points must belong to the same RTU because only the first entry in the response will have the RTU ID. For example, the following could be used on a small RTU to transfer all points in one command: SCAN s1:s8 R o1:o8 R a1:a6 E m1:m1 E Note that this SCAN command requests data for 4 types of channels in a single line. The response might look like this: DATA RTU1.s1:s8,R,12,/O1:O8,R,2,/A1:A6,E,12.3,4.33,2456.00,0,12.45,22.67,/M1 :M1,E,17.65 Multiple scans must be set up so that the resulting line will not exceed 200 characters. This is the maximum line size allowed in all transmissions. In noisy radio environments, shorter lines may produce better overall results due to the difficulty in sending long transmissions. Each extra group begins with a slash (/) character preceding the channel range code. The DATA statement is programmed to look for this character and separates each group when it matches this code. Examples: SCAN s1:s8 R SCADAWARE® Command Reference Manual 82 Dec 2001 - Preliminary SCAN s1:s8 R a1:a6 E q1:q4 E@ ; simple RTU with time stamp SCAN a1:a5 #E c1:c4 R+ s1:s8 R ; counters are added SCAN Q1:Q5 []T ; totalizer start times, compressed and numeric SCAN @ends SCAN FIRST Refer to the DATA command for additional information on the responses to the SCAN command. Related: DATA, DOWNLOAD SELEct Select the Current RTU by Name (2) The program always assumes a current logical RTU for all operations. The current RTU can be changed with the SELECT command by specifying the RTU name. For example: SELECT VR167A would cause the program to search the RTU list from top to bottom looking for an RTU named VR167A. If the name cannot be found, then the current RTU remains unchanged and an error message is displayed. The only exception to this rule is that the system level RTU is selected by number rather than by name. To select RTU 0 and make it the current RTU, the following command must be used: SELECT 0 The F10 key can also be used to pop-up a pick-list type menu listing all of the RTUs. Use the arrow keys to move to the desired RTU and select with the [ENTER] key. The pick-list will not work if the system has only a single RTU. The pick-list can also be displayed by having Task 0 process the SELECT command without specifying a RTU name. During data displays, mouse equipped systems can move the mouse cursor to the upper left hand corner of the screen where the current RTU name is displayed. Pressing the left mouse button will cause the same RTU pick list to be displayed. The desired RTU can be selected with either the mouse or with the keyboard arrows as described above. While in the display mode (F7 key), the plus and minus keys can be used to move from one RTU to another. This also provides for a wrap around so that the user can move from the last RTU to the first RTU and back again without stepping through all the RTUs on the system. Example: Select GA343A SET Set RTU Operational Parameters (2) SET provides access to a command sub-system that allows control and display of many time-out and configuration values that control system operation. Only the first 4 letters of the SET command option are significant, although others can be provided. Some set commands are no longer required, having been replaced by later program features or functions. To maintain compatibility with older software installations, all options remain from earlier versions whether they are needed or not. All SET commands have a similar form which begins with the keyword SET followed by a sub-key which specifies the internal parameter to be affected. If no additional parameters are provided, SET will present a display of the current values for the specified SET option. No changes will be made. If additional parameters are provided, SET will take the appropriate action and display the end result of the changes. SCADAWARE® Command Reference Manual 83 Dec 2001 - Preliminary Most SET options take a parameter which falls into one of the following categories: Boolean Any off/on condition such as 1, 0, Off, On, Yes, No Numeric Any valid number or expression which evaluates to a number Tagname Any channel tag name reference, with or without RTU override. Note that each SET option influences specific portions of the overall system. Some affect only the current task, others the entire system, and others only the current RTU. Each entry in the listing below contains code letters in brackets which indicates the scope of the SET option: [R] Affects only the current RTU [S] Affects entire System [T] Affects task executing the SET command [L] Affects only the local CRT task Set Option Example: DELI Delimiter [T] Specify delimiter (separator) used for WRITE and WRITELN 1st Param Delimiter code, which is any character or the words SPACE, COMMA, NONE Default Comma Example: SET DELIM SPACE The set option is DELI, which stands for delimiter. Use of this SET option will affect only the task executing the SET command, indicating that each task has its own delimiter value. The brief description of the option indicates that DELIM controls the separator character placed by SCADAWARE between values output with the Write command. The 1st parameter (which follows DELI) can be any character desired for the separator, or the special words SPACE, COMMA, or NONE. An alpha listing of all set commands follows. Note that only the first four letters of the primary option keywords are significant. ACK Acknowledge [S] Tagname used for External ACK input 1st Param tagname Default S0 (no input) Example: SET ACK S8 ; use status input 8 for the ACK push button ALER Alert [T] Enable/Disable Alert Response for Call-On-Exception 1st Param Boolean Default Off (Alerts are not processed) Example: SET ALERT ON ATTR Attribute [L] Control CRT display attributes ATTributes DEFAULT | norm title new old reset Sets color (or mono) display attributes for local CRT. Each screen attribute has a number, and can be viewed with the DUMP ATTRibute command. The command SET ATTR DEFAULT will set all attributes to their default values. To set a particular attribute, enter SET ATTR followed by the attribute number follower by the foreground/background color combination. Use a + sign to brighten foreground colors and to cause background colors to blink. If more than one attribute color is specified, the additional ones go the subsequent screen attributes. Examples: SET ATTR DEFAULT ; sets attributes to default SET ATTR 1 green+/black ; set normal text SET ATTR 2 blue+/gray ; set title text SET ATTR 1 green+/black blue+/gray ; same as both above SCADAWARE® Command Reference Manual 84 Dec 2001 - Preliminary The available colors are red, blue, green, cyan, magenta, yellow, black, white, gray, and underline. BACK Backup [L] Controls text editor backup file generation 1st Param Boolean Default Off (no backups are made by the editor) Example: SET Backup ON BAUD Baud [T] Set baud rate for serial comm port. 1st Param Numeric baud rate, must be 300, 1200, 2400, 4800, 9600 Default Determined by DAT file setting, typically 1200 Example: Set baud 4800 BYE BYE [T] Control auto processing of BYE function Tasks normally execute a BYE file when communications are complete. Special cases do not need or want this feature, as when polling multi-drop dumb RTUs in one LINK file. SET BYE can be used to disable the auto BYE function. 1st Param Boolean Default ON Example SET Bye OFF CALC Calculator [T] Controls automatic processing of CALC if TSP command not found Sets auto calculate mode to allow direct assignment of values to channels and data variables. 1st Param Boolean Default: Off ("CALC" is not assumed at the start of each line) Example: Set Calc On CD Carrier Detect [T] Requirement of DCD for valid communications (Same as DCD) 1st Param Boolean Default ON (DCD is required for data communications) Example Set CD OFf ; don't need on multi-drop links COMM Communications Timeout [T] Sets the number of seconds between comm channel resets. No activity on a comm channel causes a BYE operation to occur to re-program any comm devices. The timer is reset every time a BYE operation occurs. 1st Param Numeric Default 3600 ; one hour Example: SET COMM 300 ; set for 5 minutes CONF Config [L] Allow Limited Configuration For Password Level 2 A restricted version of the Config command can be accessed by users with levels less than the normally required level 3 if this option is selected. 1st Param Boolean Default Off Example SET Config ON ; allow Level 2 access to some config parameters CONT Continuous [T] Selects constant screen display or one-time screen display Set continuous action by the DISPLAY commands. 1st Param Boolean Default On for Task 0, Off for others Example: SET CONT OFF ; update screen only once per command CRT CRT Selection [T] Define physical CRT type connected to the affected task Sets type of physical CRT device connected to a task. 1st Param CGA, EGA, VGA, Mono, Ansi, None, QT2 Default: Mono or CGA for Task 0, Ansi for others. Example: Set CRT VGA ; put console into 50 line mode SCADAWARE® Command Reference Manual 85 Dec 2001 - Preliminary DCD Data Carrier Detect [T] Requirement of DCD for valid communications (Same as CD) See CD above DELA Delay [S] Turn alarm delay processing off and on Determines if alarm time delays are in effect for all local channels. Turn off to speed up processing and simplify testing. 1st Param Boolean Default On Example Set Delay OFF ; stop delays to speed up alarm response for test DELI Delimiter [T] Specify delimiter (separator) used for WRITE and WRITELN 1st Param Delimiter code, which is any character or the words SPACE, COMMA, NONE Default Comma Example: SET DELIM SPACE DIR Directory [S] Specify various default directories 1st Param SCREEN, SOUND, RTU 2nd Param Full Path name of file directory for subsystem Default Same as current directory at program startup Example Set Dir Sounds c:\WAVFILES\ DITH Dither [L] Graphic File Conversion Dither Method Graphic files which must be converted to a different resolution or color set are "dithered" according to the rule specified by this option. 1st Param None, Square, Dispersed, Cluster Example: Set Dither Square DRIV Drive [S] Set default drive (path) for RTU files 1st Param Path name for RTU procedure files. Default Current directory at start of program. Example: Set Drive C:\RTUFILES\ ECHO Echo [T] Turn comm echo off and on Send characters received into a serial port out the comm channel. This is normally used for human type interface operations where character echo helps coordinate keyboard entry. 1st Param Boolean Default On for local task, off for all others Example Set Echo ON ; EJEC Eject [S] Turn printer page eject after report off and on Controls form-feed characters at the end of reports. Set On for direct printouts, normally off if print spooler in use. This affects all printouts for all RTUs. 1st Param Boolean Default Off Example Set Eject OFF EMSG ErrorMessage [S] Error Message Trap control Shows last error trapped by system. Also resets trap for new error. 1st Param Boolean Example Set EMSG Off ERRO Error Trap [T] Terminate TSP processing on any error Controls command file execution for this task on any expression evaluator error. Setting off will allow execution to continue after an error. 1st Param Boolean Default Off Example Set Error ON ; stop processing on any expression error SCADAWARE® Command Reference Manual 86 Dec 2001 - Preliminary FAIL Failsafe Comm Timeout [T] Comm timeout for each task after connect Set command time-out (fail-safe) seconds. The task will terminate the comm link if no commands are entered in the specified number of seconds. Set to 0 to disable the automatic timeout and let a task remain online indefinitely. 1st Param Numeric Default 60 seconds for all tasks except task 0 whose default is 0. Example Set Fail 20 ; hangup after 20 seconds of inactivity FAST Fast [S] Enable High-Speed processing for Timers, I/O Scans, Counters Controls high-speed execution of certain internal operations such as 50 ms timers, status inputs for counters, and 50 ms I/O scans. Not normally used on 8088 type systems. 1st Param Boolean Default Off Example Set Fast ON FIRS First Ack [T] Seconds to wait for first ACK from other unit after connect Sets the number of seconds to wait for the first command after going online. 1st Param Numeric Default 30 seconds, but usually set in STARTUP procedure for each task Example Set FIRST 5 ; fast response for direct connect system FONT Font Control [L] Specify default graphic font Set graphic font used in subsequent text output. Replaced by FONT command. 1st Param Any valid Font Name Default System Example Set Font Roman FRAM Frame [L] Specify default graphic frame style and size Controls automatic placement and size of graphic frames on most objects. 1st Param None, Single, Double 2nd Param Pixel Size of frame edge Default None HORN Horn Output [S] Specify channel used for Horn Output Set channel used to indicate alarm condition and to turn the horn off and on. 1st Param Tagname Default S0 (no horn output) Example Set HORN LOUDHORN; use channel named LOUDHORN KEYH KeyHit Sensing [T] Determine if any key press will stop TSP file execution Controls command file processing when a key is hit. This command is effective only when being called from within a file and can be used to exit a loop on any key press. 1st Param Boolean Default Off Example Set Keyhit ON LCD Liquid Crystal Display [L] Turn LCD optimized color set off and on Monochrome LCD screens often look better with a special set of display colors (attributes). Setting LCD on will automatically convert the current color set to one that looks best on an LCD type screen. LEVE Level [T] Set security (password) level for subsequent processing Sets the required security level for further processing of a command file. Processing stops if the current user is not of required level. 1st Param Numeric LEVEL Default 0 Example Set level 3 SCADAWARE® Command Reference Manual 87 Dec 2001 - Preliminary LINK Link [R] Set default link number for current RTU Each RTU had a default link which is activated when any POLL request is made for this RTU. SET LINK allows the default link to be changed at any time for the current RTU. 1st Param Numeric (to indicate line number) Default Determined by DAT file setting Example Set Link 5 ; switch to phone line LPP Lines Per Page [S] Set Lines Per page before form-feed on reports Set report Lines Per Page (LPP). Setting to 0 will disable all page headings. Setting LPP to a very high number will suppress all but the first page heading. 1st Param Numeric Default 60 Example Set LPP 45 MD MultiDrop [T] Multi Drop Communications Options Various Multi-Drop settings are set to control timing and establish ID names. 1st Param DELAY, ID 2nd Param Text Value ID, numeric for Delay Default ID is same as system name. Delay is 2 ticks MEDI Media [T] Select Communications medium (technique) Sets the type of communications media used by a task. Normally, the media is set one time at startup and never changed, although it could be done at runtime if required. 1st Param Phone, Radio, Keyboard, Direct, MultiDrop, or None Default Determined by DAT file setting Example Set Media direct ;connect handheld to this port MENU Menu [L] MAIN or USER menu on F9 Main and User control which menu system is the primary menu system and which is the secondary. The Main menu is the default primary menu. Pressing F9 will display the primary menu and SHIFT-F9 will display the secondary menu. Off and On control the Auto-Menu feature. In Auto-Menu mode, the primary menu will automatically pop-up whenever the user is at a command prompt. 1st Param Off, On, Main, User Default Main and off Example Set Menu USER ; Let F9 call up user menu MULT Multiple [T] Option for Multiple TSP statements per line 1st Param Cmd Separator Character ( !,|, \, ~) or keyword OFF Default Off Example Set Multi | ; use vertical bar as cmd line separator ONLI Online [T] Command processing controlled by comm connect status Controls command file processing requirement for online. This command is effective only when being called from within a file. 1st Param Boolean Default Off Example Set Online on ; need DCD to continue processing from this point PAGE Page Breaks [T] Page break control in reports Set page break for DUMP, TYPE, and DIR type commands. 1st Param Boolean Default Off Example Set Page on PALE Palette [L] Color Palette control for simultaneous 256 color images SCADAWARE® Command Reference Manual 88 Dec 2001 - Preliminary Simultaneous display of multiple color graphic images which use non-standard palettes require some form of compromise to obtain a common color scheme. SCADAWARE converts images as they are loaded with the following options: None Use the palette from the most recently loaded image Convert Convert subsequent images to initial palette Map Take top 16 palette positions for std colors. 1st Param None, Convert, Map Default None Example Set palette PATH Path [S] Set default path for CMD files (Same as Drive) (Same as the SET DRIVE OPTION above) PAUS Pause [T] File processing after Negative response to PAUSE command Controls file processing when the PAUSE command is answered negatively. SET PAUSE OFF allows file processing to continue when a No is answered. This lets the @yes() and @no() expressions to be used for program flow control. SET PAUSE ON causes file processing to terminate when a No is answered. 1st Param Boolean Default On Example Set Pause off ; let file processing continue after N response PLAC Places [T] Sets default decimal places for numeric values Set the default decimal place count used by all value type channels in displays, reports, and data transfers. Each channel has its own parameter for decimal place precision, but if that parameter is less than 0 then the global setting set by this command is used. 1st Param Numeric Default 2 Example Set Places 3 ; want high resolution on this display PORT Port [T] Hardware Comm Port number for executing task Sets the communications port for the current task to the specified number. Use this when linking a task to a port that has a number different from the task itself, as when using COM4 on task number 1. 1st Param Numeric Default Determined by DAT file setting Example Set PORT 2 ; switch to phone line port PRIN Printer [S] Set hardware or logical address for Printer Port SCADAWARE uses standard DOS and BIOS printer routines for all printer output. To work around the poor handling of printer errors offered by the standard interface, SCADAWARE does internal checks which bypass the limited DOS and BIOS error signals. To do this properly, SCADAWARE must be told the printer port number being used for printouts. If none is specified, then no printout will be allowed. When an error is detected, the program attempts to reset the printer, and if this fails, the program automatically sets the Printer value to 0 to prevent further attempts to print until the problem is fixed and a SET PRINT xxx statement is re-executed. 1st Param Numeric LPT port number Default 1 0 (no printing enabled) 2nd Param Numeric value for mask used to test Default 2 90h (90 hex, 10010000 binary) Example Set Print 38h ; special bits for this strange printer PTT Push-To-Talk [S] Set control output for Audio Output System The audio sub-system can control an output for keying radios and PA systems. 1st Param Tagname Default S0 (no output channel) Example Set PTT O5 l output 5 controls the push to talk SCADAWARE® Command Reference Manual 89 Dec 2001 - Preliminary PWAI Printer WAIT [S] Ticks to wait between lines sent to Printer Set the number of process ticks the task printing a report to the printer should wait between each line. This command will slow down the rate at which lines are being sent to the printer. If the lines are being sent too fast and the printer cannot keep up, the system can run slowly or hang completely. Each system tick is approx 50ms. The default PWAIT is 20, so the system will delay a task about one second between lines of output. During this second, other tasks will run uninterrupted. Adjust to provide best performance for each computer and printer system. 1st Param Numeric (number of 50 ms ticks) Default 20 Example Set Pwait 10 ; wait 1/2 second between printed lines RAW Raw Data SCAN Status and Output channels as physical position rather than logical true/false value. Normally closed switches which are currently closed will scan as 1 instead of 0. 1st Param Boolean Default Off example Set RAW ON ; send back physical switch and output positions REPO Report [R] Automatic Report generation on data update timestamp Turn on automatic report generation setting on any polls for each RTU 1st Param Boolean Default Off Example Set REport ON ; current rtu will not print on every update RESE Reset [S] Specify External Channel used for RESET Push Button Set channel to be used as a RESET push-button. 1st Param Tagname Default S0 (no reset input) Example Set Reset S5 ; Switch 5 is reset input RFIL ResetFile [S] Command File Processing when abnormal condition RESETS Controls execution of command files when a channel returns to normal. Setting OFF will not execute files. Setting ON will execute files on return to normal (reset). This setting affects all channels on all RTUs. 1st Param Boolean Default Off Example Set Rfile ON RLOG Reset Logging [S] Logging of Channel Return to Normal Events The data logger normally records only changes from normal to abnormal. This setting allows returns to normal to be similarly recorded. 1st Param Boolean Default Off Example Set RLOG On RTU RTU File Lookup [S] Automatic search for RTU procedure or file when cmd not found Controls automatic search for .RTU files in the event of an unrecognized internal command. 1st Param Boolean Default Off Example: Set RTU ON ; let system automatically search for RTU procedures SILE Silence Input [S] Specify channel used for external Silence Push Button 1st Param Tagname Default S0 (no silence input) Example Set Silence S5 ; Switch 5 is silence input STYL Style [L] Sets default Graphic Font Style Determines graphic font style used in subsequent text output. Replaced by FONT command. SCADAWARE® Command Reference Manual 90 Dec 2001 - Preliminary TAB Tab Setting [T] Specify default TAB spacing used in WRITE command Writes can be done to integer tab space settings changed by this command.. 1st Param Numeric Default 8 Example Set Tab 10 ; columns every 10 character spaces TICK Ticker[S] Turn system tick off and on Set the one second "tick., tick" signal. 1st Param Boolean Default On Example Set Tick OFF ; stop the obnoxious ticking sound TRAC Trace [T] Expression Evaluator Processing Trace Display Determines if the equation evaluator shows intermediate steps during expression solving. 1st Param Boolean Default OFF Example Set TRACE ON TRANS Transparent [L] Specify background color used for Transparent Graphic Object display Controls transparent action of PAINT command by allowing the specified color to be the "clear" background which will not be transferred to the graphic screen. 1st Param Color Default Black Example SET TRANS WHITE TRYS Trys [T] Number of Trys for each communications block transmission Sets the number of tries to send a block and receive an acknowledgement for the task processing the command. 1st Param Numeric Default 3 Example Set TRYS 5 UPFIle Update File [R] Set and Clear Update File Flag for each logical RTU Controls whether or not a command to read the "UP" file gets queued up or not when a @ or @ENDS is processed in a DATA command. If UPFILE is off the command will get queued up and UPFILE will be set to on. The command will not get queued up again when a @ or @ENDS is processed in a DATA command unless UPFILE was turned off using this command. 1st Param Boolean Default Off Example Set Upfile off ; enable a new update request VGA VGA [L] Default VGA and VESA video mode Sets the default VGA or VESA screen mode used with the system switches from ext to graphics mode. 1st Param VGA Mode number Default 7 Example Set VGA 37 ; select 640 x 480 x 256 Common VGA and VESA Mode Numbers VGA CRT CRT Max MODE Horiz Vert Colors 0 320 200 4 1 640 200 16 2 320 200 16 5 640 350 16 7 640 480 16 (default) 8 320 200 256 36 640 400 256 37 640 480 256 (preferred) SCADAWARE® Command Reference Manual 91 Dec 2001 - Preliminary 38 800 600 16 39 800 600 256 40 1024 768 16 41 1024 768 256 42 1280 1024 16 43 1280 1024 256 51 320 200 32K 52 320 200 64K 53 320 200 16m 54 640 480 32K 55 640 480 64K 56 640 480 16M 57 800 600 32K 58 800 600 64K 59 800 600 16M 60 1024 768 32K 61 1024 768 64K 62 1024 768 16M 63 1280 1024 32K 64 1280 1024 64K 65 1280 1024 16M WAIT Wait [T] Seconds to wait for ACK during normal communications Sets the seconds the unit should wait for an ACK response from another unit during callouts. This is a separate setting for each Task and is only used in computer to computer operations. 1st Param Numeric Default 20 Example Set Wait 10 ; 10 second period to before retransmit WARB Warble [S] Control internal PC speaker horn alarm Controls use of local speaker as an alarm horn. 1st Param Boolean Default On Example Set WARB Off ; disable internal speaker alarm SETDB Set Deadband for a Single Channel (2) This command can be used to set the deadband for a single channel without having to go through the entire channel programming process. Th e command can be used for analog inputs, analog outputs, frequency inputs, counter inputs, AGA3 meters, timer channels, value channels, and totalizer channels. The format of the command is the keyword SETDB followed by a channel tag and possibly a value. If a value is specified, the deadband for the specified channel will be set. Otherwise, the current deadband setting will simply be displayed. Note that the deadbands can also be set and read with the SCAN D option. This would be more suitable for sending a set of deadbands from one unit to another. Examples: SETDB A1 2 ; set deadband to 2 SETDB A3 Related: PROGRAM, CONFIG, SCAN D SETHIgh Set High Setpoint for a Single Channel (2) SCADAWARE® Command Reference Manual 92 Dec 2001 - Preliminary The high alarm setpoint for a single channel can be set with this command without going through the complete channel programming sequence. The channels that can have high setpoints are analog inputs, analog outputs, frequency inputs, counter inputs, AGA3 meters, timer channels, value channels, and totalizer channels. The channel number is followed by an optional new setpoint. The current value of the setpoint is displayed after the command is processed. If no new value is provided, the command will display only and leave the setpoint unchanged. Note that the high setpoints can also be set and read with the SCAN H option. This would be more suitable for sending a set of setpoints from one unit to another. Examples: SETHI A1 12.3 SETHI C1 123.4 SETHI M2 Related: SETLOW, PROGRAM, CONFIG, SCAN H SETLOw Set Low Setpoint for a Single Channel (2) This is used to set the low alarm setpoint for a single channel. Low alarms can be set for analog inputs, analog outputs, frequency (rate) inputs, counter inputs, AGA3 meters, timer channels, value channels, and totalizer channels. See the SETHIGH command for syntax rules. Note that the low setpoints can also be set and read with the SCAN L option. This would be more suitable for sending a set of setpoints from one unit to another. Examples: SETLOW M2 345.6 SETLOW A3 Related: SETHI, PROGRAM, CONFIG SETWAIT Set Alarm Delay Period for a Single Channel (2) This command can be used to set the alarm delay period for any type of channel without having to go through the entire channel programming process. The format of the command is the keyword SETWAIT followed by a channel tag and possibly a value. If a value is specified, the alarm delay for the specified channel will be set. Otherwise, the current alarm delay will simply be displayed. Note that the alarm delays can also be set and read with the SCAN W option. This would be more suitable for sending a set of alarm delays from one unit to another. Examples: SETWAIT V1 10 ; set alarm wait to 10 seconds SETWAIT A3 Related: PROGRAM, CONFIG, SCAN W SHELL Shell to DOS (2) This command is exactly like the EXEC command discussed above. It is used to be compatible with other DOS programs that use the Unix term "SHELL" rather than the DOS term "EXEC". SCADAWARE® Command Reference Manual 93 Dec 2001 - Preliminary Related: EXEC SLEEP Suspend Task Operation for a Number of Seconds (2) It is sometimes desirable to have a task suspend operation for a while, as when waiting for equipment to startup. The sleep command specifies a number of seconds that a task will stop execution. The current task is suspended and will not be eligible for processing until the specified number of seconds has elapsed. This is most useful for programmed pauses in command file execution as when waiting for an output action to take affect. Example: Sele RTU1 Dial Wait 30 conn if @online(1) msg RTU is online block CALC t1 = 30 msg Pulse command sent sleep 30 ; wait for ESD to occur msg getting download block read download endif Related: WAIT STATus Display Status of Link, Comm Port, and Tasks (1) The status of all dynamic system variables can be monitored with the STATUS command. The comm port, comm link, task status, and file status can be displayed on a real-time screen. This allows greatly simplified diagnostics because the local CRT can be used to monitor all of the internal workings of the system. This command is used mostly for diagnostics and system setup. The options are as follows: C - Communications Channel Parameters L - Communications Link Parameters T - Task variables and states F - Shows status of open files No options will produce a display of C and L combined. Examples: STATUS STAT T STAT L STAT C STAT F STOP Stop Command File Execution for a Task (1) Execution of a command file normally continues to the end of file before termination. If it is desirable to stop a file in the middle somewhere, the STOP command can be used. This is very similar to the RETURN command because processing of the current file is terminated. The difference is that the RETURN command will only stop processing the current command file. The STOP command will stop SCADAWARE® Command Reference Manual 94 Dec 2001 - Preliminary processing the current command file and any other files currently being processed by the same task. In other words, if the processing of the file was started from within another file then both files will be terminated. The STOP command will always return the command processor to the command mode. Example: if (v1 > 10) stop endif Related: RETURN, GOTO, REREAD STORE Write Configuration Data to Standard Output (2) It is necessary to save the various setup information for each system to some sort of storage unit for later recall when powering up or resetting the computer. The STORE command is used to generate command lines that can later be read by the system (or another system) to re-program it to the settings currently in effect. The things that can be stored include channel setups, link setups, and callout group assignments. The STORE command sends the lines it generates to the standard output device in effect at the time the command is executed. Normally, this is the console or terminal in use by the current task. However, it is possible (using the FILE command) to send output to a disk file or device such as a printer. In this manner, the text lines can be saved for later use or printed out for reference. The SAVE command does the file open and close automatically, although the user can also do this for special cases. Channel configuration is read and written in a text format that divides each channel into its internal layers, with each layer on a single line. Therefore, the number of lines required to describe a channel depends on the type of channel. Link information is generated as one line for each link that is currently being used. Unused links do not generate lines. In-use is determined by the link's task number being > 0. Callout Group information is written for each group that has any links associated with it. Unused groups are not written out. The allowable keywords that can be used with this command are CHANNELS, LINKS, GROUPS, and ALL. These keywords will designate exactly what data will be stored. If no keyword is given the keyword CHANNEL is used. If the keyword ALL is used, all channels, links, and groups will be stored. Only the first 2 letters of any keyword are significant. Examples: STORE ALL ; Store everything STORE GROUPS STORE LINKS STORE CHAN ; Store all channels STORE ; Store all channels Related: SAVE STUFF Insert Characters Into Another Task's Input Buffer (2) This command is used to jam characters into the input buffer of a task. Similar to the FORCE command, this can be used to send commands directly to another task. The difference is that text specified on the STUFF line is sent to the task's comm input buffer, which is checked during execution of most commands. The FORCE command places text in a special queue that is read when the task is not processing any other commands. SCADAWARE® Command Reference Manual 95 Dec 2001 - Preliminary The STUFF command can be used to send special codes similar to those used by the ECHO command. This allows escapes and other codes to be sent to tasks that may be looping waiting for operator input. If the force command was used, this would place a message that would not be read because the task may be stuck in the middle of a command. STUFF gets characters directly into the input buffer as if they had been received over the normal communications line. The following abbreviations are allowed to be used in place of actual ASCII codes: ES Escape CR Carriage return SP Space CA Control C (CANCEL) BS Backspace This command is mostly useful for diagnostics and troubleshooting. Example: STUFF 1 ES STUFF 1 SP STUFF 1 ES CAN ES CAN Related: FORCE TAB Position Text Output to Specific Column (1) TAB is used with the WRITE function to align text output to a specific column. The next logical tab stop is used, which defaults to every 8 characters. The SET TAB command can be used to change the spacing for each task. Tab can also be used to position the text output stream to a specific column by providing the numeric value of the column after the TAB command. file open report.txt ; open a new output file set delim none ; use nothing as delimiter, use TAB spacing instead writeln "SAMPLE REPORT" write A1 tab write A2 tab writeln a3 ; finish the line file close file append report.txt ; re-open the file and add to its end writeln writeln "MORE DATA" write a4 tab 20 write a5 tab 40 writeln a6 file close Examples: TAB ; Move to next tab TAB 50 ; move to column 50 SCADAWARE® Command Reference Manual 96 Dec 2001 - Preliminary Related: SET TAB, SET DELIM, WRITE TAP Passive TSP Mult-Drop Communications Control (2) Multi-Drop systems that have more than one Host on the same line can eliminate redundant transmissions with the TAP option. The feature lets a unit TAP into the multi-drop line for purposes of processing DATA lines only. The unit listening to the line processes the DATA line but does not send an ACK or any other response. This is similar to the normal BROADCAST option in the MultiDrop except that only DATA lines will be processed. BROADCAST allows any line to be processed, and this is not normally desired for most lines. The TAP feature can also be used to set up redundant Host computers by letting one unit actively control a network, while the other unit taps into the comm line and monitors all data transfers. This lets the passive unit be updated without any direct connection to any other units. A typical application will have three or more units on a common line where each unit shows its own data (as an RTU) and data from the other units (as a Host). Whenever one unit sends DATA lines to another one, all units can listen in to the transmission and process the DATA line just as if it had been sent directly to it. Therefore, all units can be updated at the same time with DATA lines, but only the addressed unit will process other command such as file reads, calcs, etc. To use this feature, the affected DAT files must have a statement that specifies the number of RTU's that will be monitored. The syntax of the line is: TAP n where n is the number to use. Example: TAP 5 sets up a list of 5 RTU names that will be matched on each line. The RTU names that can be monitored are entered with one or more command lines that are normally processed during startup. These lines add the RTU names to the acceptable list. For example: TAP Clear ; Clear out any exiting TAPS TAP ADD WC354 HOST EC311 WD61 The status of the TAP can be checked at any time with TAP DUMP. If a multi-drop task processes a data line which is being sent to a unit on its TAP list, it will process the line just as if the line had been sent to its own computer. However, no ACK will be generated by the TAP system. Tasks being Watched will indicate reception and processing of appropriate TAP acceptable lines just as if they had been directed to the affected computer. Refer to the System Design Manual for more information on multi-drop communications and the TAP processing option. TASK Control Task Execution and Settings (2) This command is the primary means of controlling the status of all tasks defined in the RTU.DAT file. The command uses an optional task identifier (number or nickname) followed by a keyword. Current keywords are: START Start a task running with a fresh start. STOP Make a task dormant. SCADAWARE® Command Reference Manual 97 Dec 2001 - Preliminary WAKE Return a sleeping task to a run or wait status. SUSPEND Put a task to sleep for the specified seconds. DELAY Specify ticks to delay between executions. PRIORITY Specify sequential ticks a task can run. DUMP Display task status. Tasks have "nicknames' or ID's assigned to them when they are defined in the DAT file. Typical task ID's are as follows: UTIL Utility task. CALC Calculator task. SCAN Alarm Scanner task. SEC One second task. LOCAL Local CRT task. DRIVER I/O driver task. Starting a task resets the program counter and stack space for the task and sets a task level flag indicating that the task is about to run for the first time. At the next available chance, the task will start running with a "fresh" start. Any previous commands, file status, or other dynamic conditions are all reset with the start command. A task that is locked up for some reason can usually be re-started with this command. Stopping a task halts it in its present state and sets the task status to dormant. The only way to get the task active again is to use the START command above. Stopped tasks use no processor time or other CPU resources. NOTE, stopping task 0 would cause the multi-tasker to crash so this command can not be used to stop task 0. Suspending a task for the specified seconds does not adjust the task's default delay or priority setting. The task is simply put to sleep for a period of time, after which it picks up just where it left off. Because each system has differing processor speeds, task assignments, and other workloads, it is desirable to have control over how much processing time each task has. The TASK command allows the critical timing of each task to be individually controlled at run time. The priority of each task determines how many sequential clock ticks the task will be allowed to execute before it is suspended. If a task completes before its allotment is used up, the next available task gets an early chance to run. Adjust this number up to allow a task more processing time out of each overall cycle. The delay of each task is the ticks that the task will pause between each completion of its full execution. For example, an I/O driver that does not need to run constantly can be assigned a high (say 18) delay number so that after completing a run it will wait a at least a second before running again. The priority of the task can be also set high so that when it does get a chance to run it will have a better chance of running to completion all at one time. Examples: TASK UTIL START ; start the utility task TASK scan delay 1 TASK 0 priority 4 ; speed up screen displays TASK second stop TASK util delay 2 TASK calc wake TASK 2 suspend 10 *TERMINAL Put Program in Human Interface Mode (0) SCADAWARE® Command Reference Manual 98 Dec 2001 - Preliminary This is a very special command because it is immune from the normal error checking requirements that are in effect when the program is in RTU mode. After the command is entered, beginning with the start character ^A (control-A), the program will drop into the terminal mode. This allows entry of commands without the checksum requirements normally associated with RTU data transfers. This command has no effect on Task 0 because Task 0 is always in terminal mode rather than RTU mode. Remember, the start character ^A must be specified and the command must be completely spelled out in upper case. Example: ^A*TERMINAL TIME Set DOS Time of Day (2) This sets or displays the DOS time as seen by the RTU and other programs. The same operation notes that apply to the DATE command discussed earlier apply to the TIME command. The time string must be a full time specification in 24 hour "military time" format. Entering the command TIME with no options causes the current value to be displayed. Entering a properly formatted time as a parameter will cause the time to assume that value. As a second parameter, a properly formatted date will cause the date to assume that value. This allows setting of both the time and date in a single command line. Example: TIME ; display current time TIME 02:32:00 ; set time TIME 02:32:00 01/01/88 ; set time and date Related: DATE, EXEC TRANSFER Copy Values from One Group of Channels to Another (2) This command provides a quick way to copy the values from one group of channels to another group of channels. To use this command two channel ranges must be given. The first range represents the channels to copy from and the second range represents the channels to copy to. Single channel names can be given instead of channel ranges if the value for only one channel needs to be transferred. Channel values can be transferred between different RTUs on a system by specifying the RTU names in the channel ranges using "dot" notation. Dot notation consists of two parts separated by a period (or "dot"). The first part is the RTU name and the second part is the channel range. The current RTU is assumed if no RTU name is specified in a channel range. Example: TRANSFER S1:S5 O1:O5 ; transfer inputs to outputs TRANSFER RTUA.S4:S8 RTUB.S10:S14 ; transfer between two RTUs ; sample Daily file transfer q1:q4 v11:v14 ; move totals to yesterday's value calc q1:q4 = 0 ; start totalizing this day Related: CALC, XFER SCADAWARE® Command Reference Manual 99 Dec 2001 - Preliminary TYPE Display a DOS Text File or TSP Procedure (1) This is similar to the DOS type command, except that the output is paged into screen fulls with a timed pause at the end of each page. The required parameter is the name of the DOS text file to be viewed. If no file extension is provided, a default of RTU is assumed. Example: TYPE AUTOEXEC.BAT Related: SET CONT UNHOLD Remove a Channel's HOLD Status (2) A channel's HOLD status determines if any low level value conversions are made by the channel scanner task. The HOLD command places a channel on hold, preventing these conversions. This is normally used during calibration times. The UNHOLD command is used to clear the HOLD status for any number of channels or channel ranges. Examples: UNHOLD M1 UNHOLD m1:m3 UNHOLD m1:m4 q1:a7 a1:a3 C5 Related: CHANGE, HOLD USER Display User Menu (1) This command is used to display a customized user menu. The user menu is a "pop-up" type menu system that allows for quick selection of preprogrammed actions. The user menu can be modified to perform custom functions unique to each location. This is done with the use of menu files. Before a user menu can be displayed it must first be loaded into memory. See the MENU command for how to load different user menu files into memory. If no menu file is loaded in memory when the USER command is processed, the program will automatically look for a file called RTU.MNU, load it into memory if it exists, and then display the menu. Example: USER ; display currently loaded user menu Related: MENU VER Get SCADAWARE Information (1) This will produce a program version date as well as information about the memory allocated by the program. Examples: VER WAIT Delay Some Number of Seconds for An Event (2) SCADAWARE® Command Reference Manual 100 Dec 2001 - Preliminary Within command files it is often necessary to hold up processing until certain events occur. This command allows the wait to occur for an approximate timeout period (expressed in seconds). If the event occurs during the timeout period, the wait is canceled and processing continues with the next line in the file. If the event does not occur, file processing is suspended until the timeout period expires. Processing will then continue with the next line in the file. Using the SET ONLINE command can be used just after the WAIT command to have the program wait for a connection and then continue processing only if the unit is online. The wait function gives time for the phone or radio connection to be made. Without using the WAIT command, file processing would not allow time for the connection to be completed. If no wait time is provided, a default value is assumed. The default value used is the number of seconds that the current link will wait for a connection before giving up. The local task does not assume a default timeout period because it has no link associated with it. The time can appear anywhere on the command line along with any number of event keywords. If more than one keyword is specified, the wait is terminated when any of the events take place. The keywords currently supported are: CONNECT - Detection of Online status (carrier detect) DISCONNECT - Loss of connection status KEY - Keyboard or serial line input Examples: WAIT Key 10 - Wait up to 10 seconds for a keypress WAIT Conn 60 - Wait 1 minute to make the connection WAIT Key Conn 20 - Wait 20 secs for keypress or connection ; Sample RTU dialout procedure sele RTU1 dial wait 32 conn ; wait up to 32 seconds for a connection if @online(1) --- do something interesting --- endif Related: DIAL, SET ONLINE, PURGE WATCH Monitor Input and Output Characters for Another Task (2) This is a command that will allow a console to monitor the input and output to any other task. This is handy when trying to figure out what another task is doing, and to monitor characters going to and from a communications line. The Watch command is the primary diagnostic for monitoring the progress of any task other than task 0. With the Watch facility, the local user can see every input and response for any other RTU type task. This allows real-time debugging and troubleshooting of the multi-tasking system because the local user can "see" what is happening to another task on the actual equipment processing the programs. No additional equipment is necessary to monitor serial or network communications. The Tasks to be monitored can be referenced by number or name as in any other task related command. Two parameters can be used to start or stop monitoring a task. The first one is the task to be affected. The second is the word OFF or ON to turn the watch function off and on. If only the task parameter is given the option ON will be assumed. No parameters will provide a listing of the tasks that your task is watching. There is also an option to cancel all watches in progress. Using WATCH OFF (with SCADAWARE® Command Reference Manual 101 Dec 2001 - Preliminary no task specification) will cause all current watches to be cleared. This is offered as a simple way to remove all diagnostic traces without having to determine which ones are in effect. CAUTION: Because characters are displayed as they are encountered, the input and output may be mixed making the resulting display difficult to read. Brackets are used to surround characters that come into a task via command file or a force command. These brackets look like { or [ depending on the source of the message. Additional trace information is also displayed during the WATCH period. This includes messages indicating communications connect and disconnect, as well as block format transmission signals. An advanced form of the watch command allows the user to specify which message sources are to be monitored. Normally, text from the comm line, command files, and inter-task message queue are displayed along with the progress reports for the monitored tasks. A special option is available when the watch is started that specifies which of the three input sources will be displayed. The option is specified as a single number that is evaluated by the watch processor as a binary bit field. Each bit controls the monitoring of a specific input source as follows: 0 Command Line Input 1 Command Files and Procedures 2 Inter-Task messages A short table of all combinations is as follows: Value COMM FILE MESSAGES 1 Y N N 2 N Y N 3 Y Y N 4 N N Y 5 Y N Y 6 N Y Y 7 Y Y Y The sources to be monitored must have their bit set to one in the number that is supplied on the WATCH command line. For example, to monitor only the command lines and inter-task messages we would want to set bits 0 and 2. Bit 0 in binary is worth 1, and bit 2 is worth 4. Therefore, the value of 5 (1 + 4) is specified as the mask number as follows: WATCH 1 ON 5 ; task 1 for com port and messages only To watch Task 2 for comm line only, we would use Watch 2 on 1 ; Task 2 for comm line only If no value is provided the system will default to 7 which will cause the Watch command to show all text messages from any source. Examples: WATCH 1 ON ; start monitoring task 1 WATCH 2 ; start monitoring task 2 WATCH Util ; start monitoring task named Util WATCH 2 OFF ; stop monitoring task 2 WATCH OFF ; stop monitoring all tasks SCADAWARE® Command Reference Manual 102 Dec 2001 - Preliminary WIN Graphic Window Control Graphic window assignments are done in separate windows, each of which contains a graphic element such as a bar graph or data trend. WIN is used to setup and control these windows in TSP command files. Refer to the Graphic System Documentation for more information. WRITE - WRITELN Output Delimited Text to Screen or File (1) The WRITE and WRITELN commands simplify text output for special applications such as database or spreadsheet interfaces. This command allows any channel or variable data to be sent to the standard output device (screen, port, or file) with "delimiters" automatically inserted between each value. The standard delimiter is a comma, but this can be changed with the SET DELIMITER command. Write and Writeln can be used to output any TSP data. Write sends the data without a line-end (carriage return/line feed). Writeln terminates the line after the last field. Multiple Write lines can be used to output large amounts of data onto one single line as long as the line is eventually terminated with a WRITELN. The most common usage will be to transfer Database information to a text file so that it can be read into another program such as DBASE or LOTUS. The following example shows the sequence necessary to send data base fields to a file: File open OUTFILE.TXT ; open the output stream db sele mydata.sdb ; open the data base :loop write sdb_01 sdb_02 ; first 2 fields with commas writeln sdb_03 sdb_04 ; last 2 fields and line end db skip if @dberr =0 goto loop endif db close write File generated at $T on $D file close msg Data Output Complete The delimiter is normally a comma, but it can be changed with a SET command. The SET DELIM options are: SET DELIM COMMA ; use a comma SET DELIM SPACE ; use a single space SET DELIM NONE ; join values together SET DELIM ascii_value ; pick up ascii numeric value Write can also be used to generate custom reports to any valid DOS filename, including the logical printer (PRN). The following is a small report that is sent directly to the printer: file open PRN writeln "This is a Sample Report for" $R writeln "Total Gas Production = ", q1+q2'####.#," MMCF" writeln "Line Pressure = ", a5`#####," Psi" file close SCADAWARE® Command Reference Manual 103 Dec 2001 - Preliminary XFER Copy Values From One Group of Channels to Another (2) This command is identical to the TRANSFER command described above. Refer to the TRANSFER command for more information about this command. SCADAWARE® System Design Manual 2 Dec 2001 - Preliminary expensive PLC and mini-computer based software that were tailored to meet the exact needs of the end user. These systems formed the backbone of the large SCADA systems used by the major oil companies. But the smaller companies could not afford to get into the business of developing a system that would meet their unique needs. The design of TEST's SCADA systems began in 1987 as an effort to provide a reliable, affordable, and flexible system for typical offshore oil production applications. TEST sought to find a way to allow the development time and costs to be shared by a larger number of users. This would decrease the per-unit cost because the end users would install TEST's system rather than one specially developed for each company. An effort was made to select an existing, standard SCADA system that TEST could adopt as its own system. Although there were many existing systems on the market at the time, this turned out to be a problem rather than a benefit. It was impossible to find a single product or product line that would work in the wide (and I mean WIDE) variety of installations that TEST must handle. The problem was that they were all too different and required unique engineering and programming for each installation. Each also had a different method of communicating with remote devices. Even different products from the same vendor had different communication requirements. Each supplier worked on his own and provided the features that directly affected his product and its applications without much regard for maintaining compatibility with previously installed systems. The existing systems had all been based on low level electronic units (RTUs) or control oriented Programmable Logic Controllers (PLCs). These systems had "life cycles" of one to three years, after which they were replaced with a newer model. Although these newer models offered cost and performance advantages over their predecessors, they were usually incompatible in both hardware and software. Therefore, considerable manpower was needed to phase out the old system and integrate the new one. It was actually less expensive to install the more costly older equipment because of the engineering time involved to switch to the newer designs. There are many examples of huge SCADA systems that still exist with relic equipment because the cost of upgrading to newer (but incompatible) equipment is far greater than continuing to buy the outdated RTUs. With many oilfield and industrial installations, TEST has been successful in meeting the SCADA needs of both small operators and large multi-national corporations. The design philosophy, based on the standard PC, has become accepted as the obvious trend in telemetry systems. TEST is fortunate to have taken this path early on, and is anxious to apply its experience and technology to SCADA applications in all industries. 1.3 TEST SCADAWARE DESIGN TEST's design strategy was based on the idea that it was time for a radical change in RTU and SCADA system design. The decision was made to start with a "clean slate" and to design a system that would meet the following goals: . Cost Effective SCADA in a wide variety of oilfield and industrial installations . Low engineering and programming costs per installation . Limited hardware obsolescence through the use of generic hardware . Future expansion without re-engineering or re-programming . Extensive field programming and diagnostic capability . Ability to use low cost, dial-up radio and phone communications The design that emerged from the initial study was an RTU and SCADA system based on Personal Computer (PC) technology. Basing the system on the PC provided a level of field processing power that was unheard of in RTU systems. Because the PC had become a generic item, the availability of components was assured well into the next century. And the continued development of the PC into lower cost and higher performance models meant that a system based on the PC would continue to grow along with the industry. SCADAWARE® System Design Manual 3 Dec 2001 - Preliminary Once the hardware side of the design was settled, the software options became endless. With the processing power of a PC, almost any type of SCADA protocol could be implemented. A review of past and pending projects indicated that none of the existing protocols provided anywhere near the level of performance that could be derived from a PC based system. The existing protocols had come from the world of discrete electronics, relays, and primitive computer systems. Although they provided some of the needed features, they were totally inept at solving the problems TEST faced on actual field installations. The decision was made to implement a new protocol that would take advantage of the PC to provide a simple, flexible, and reliable SCADA communications system. This may sound like a harsh attitude in that there were many SCADA systems in operation that worked fine with the older protocols. The main difference in these systems and the ones envisioned by TEST is that the older systems were operated and maintained by skilled technicians. The new TEST system was to be used like the typical PC and would be maintained and operated by normal everyday people. SCADAWARE® System Design Manual 4 Dec 2001 - Preliminary Existing RTU protocols were extremely complex and served the equipment rather than the users. They were designed to allow primitive hardware to work well at the expense of programming time and maintenance nightmares. TEST SCADA PROTOCOL (TSP), implemented with SCADAWARE, put the PC to work and provided many new features designed to reduce the real cost of the systems: engineering, programming, and maintenance. TSP started with a small command set that provided the basic data transfer and command functions. But the design was such that additional commands could be added in the future that would not make any existing systems obsolete. This "upward compatible" philosophy has dominated TEST's SCADA systems since the beginning. We constantly add features to the software (and to TSP), but maintain compatibility with any existing system at the same time. So, any system can operate the newer program provided that the installed hardware can support the demands of the application. If it cannot, than a minimal amount of hardware can be changed to provide the additional processing power. The end result is a SCADA system that is much like a PC based Word Processor or Spreadsheet. It just keeps getting better all the time. TEST's SCADAWARE also works in "Open Architecture" systems which are generally based on the Modbus RTU protocol. This allows a combination of complex TSP and simple Modbus transactions to occur in one system, and provides connection to third party hardware and software. Refer Section 12 for more information on TSP and Modbus interfaces. 1.4 NON-PC BASED RTUS TEST also makes several smaller RTUs which do not have PC type processors. These units, the 2000 series, use a small microcontroller to replace the Intel 8086-80486 processors used in the larger PC based systems. These smaller systems are suitable for limited function locations where the I/O count is small and there are no local processing needs. TEST's small RTUs have many of the same diagnostic and other real-world features of the larger systems, but are less expensive to purchase and install. The units can work in either a TSP protocol system or a Modbus system in slave mode. Refer to the specific manuals for each unit for more information on these cost effective RTU solutions. 1.5 TEST INC HARDWARE The following is a brief description of TEST's SCADA products: UNIT NAME PC BASED APPLICATION T1000 Yes High Point count "Smart" Systems T1200 Yes Med to Low Point Count "Smart" Systems T2000 No Med to Low Point Count "Dumb" Systems and remote I/O T2200 No Low point Count "Dumb" Systems and remote I/O T2250 No Med point Count "Dumb" Systems and remote I/O T100 No Voice output alarm system SCADAWARE® System Design Manual 5 Dec 2001 - Preliminary 2 OVERALL SCADA SYSTEM DESIGN The TEST SCADA / RTU system is based on Personal Computer (PC) technology using off-the-shelf components whenever possible. A wide variety of configurations are possible, but all share the same PC hardware and software background. This section will explain the basic concept of a SCADA System and how some of the important aspects are handled by TEST's equipment and software. 2.1 PURPOSE OF SCADA SYSTEM The purpose of the TEST SCADA system is to provide a Personal Computer (PC) based data acquisition system that is located at a remote process location and can report alarms and other data over some form of communications channel. This unit, called the Remote Terminal Unit (RTU), receives input signals from switches and process transmitters located on the equipment to be monitored. The RTU monitors the signals for alarm conditions and reports back to another computer system, referred to as the "HOST" computer. The HOST is usually just another PC system without any physical I/O attached to it. It receives its input from an RTU (or several RTUs) over a communications channel. The update to a HOST from an RTU can be initiated by either the RTU or the HOST. The updates can occur in periods measured from seconds to hours or even days. The frequency depends on the communications system as well as the requirements of the application. Because the HOST is not physically connected to the actual I/O points, it simply maintains an image of the RTU status. This image represents the state of the RTU at the time of the last update. Therefore, displays and reports generated by the HOST may not exactly correspond to the state of the actual field points if an update has not recently occurred. Aside from the remote I/O, the operation of a HOST computer is almost the same as that of an actual RTU. The system maintains a list of points, per logical RTU, exactly as the points are physically attached at the RTU. The HOST can be used for control by sending commands to the RTU to turn outputs off or on. In some instances, the outputs can be controlled automatically by the RTU without any connection to the HOST. This control is normally associated with process adjustments, equipment control, or reset functions. The Host computer may also have some local data points that are used for various sequencing or control functions. For example, the Host may have timer channels that determine how often certain functions should occur. These Host timers are handled exactly like timers at an RTU because the same program operates at all locations. Other Host related channels may include production totals, flow averages, or communications failure indicators. So, TEST's system allows for RTU type functions at the Host as well as Host type functions at the RTU. 2.2 DATA FLOW The data flow from the field transmitter or switch to the printed report at the Host happens in several discrete steps. Each step is independent of the others, and must happen in the proper sequence in order for timely data to be delivered to the Host system. The data can be examined at each step to verify and diagnose system operation. SCADAWARE® System Design Manual 6 Dec 2001 - Preliminary back of old brochure SCADAWARE® System Design Manual 7 Dec 2001 - Preliminary The data path from the field is as follows: 1 Field Transmitter: This is where the data originates within the process being monitored. Verification of these signals requires measurement in the field and at the connection point to the RTU. The signals are generally switches, voltages, (1- 5VDC) or currents (4-20ma) representing actual process values. 2. I/O Interface: The field signals are converted from voltages into computer data by the I/O interface system. TEST SCADA systems are capable of using different types of I/O devices. These devices simply provide the raw data conversion and are not directly involved in alarm sensing, which is done within the PC. 3. RTU PC Memory: The converted signals from the I/O interface system are read by the processor, converted to engineering units, and stored as numbers in the processor's random access memory (RAM). The points are scanned many times per second, and the processor stores both current values as well as historical values. These are the values displayed on the screen at the RTU (assuming a CRT is connected). 4. Communications Line: The data is sent from one system to another in digital format over the communications line. This is the most difficult section of the data flow to control because it often relies on a less than reliable link. The data must pass through several phases: 1. Digital to tone conversion by the sending modem. 2. Injection into communications line by sending modem. 3. Transmission of the signal by the communications system. 4. Reception of the tone signal by the receiving modem. 5. Conversion of the tone back into digital data. This process occurs instantly in most systems, although some radio and satellite systems have slight delays that can cause timing problems. 5. HOST PC Memory: After reception over the communications line, the data appears in the Host memory exactly as it appeared in the RTU memory. While the RTU memory contains continuously updated data, the host data represents the state of things at the time the data was last received. 6. HOST Display or Printed Report: A display or report on the Host is made from the last known data, and the time of the update is shown on the display or report. 2.3 RTU POLLING Polling is the process where one unit (Host or RTU) contacts another unit and exchanges data. The types of polling supported by the system include: Poll after a number of seconds (using Timers). Poll at specific times of the day (using Agenda). Poll on demand by operator (using F5). Poll on change of alarm status (channel setup). Poll in continuous loop (command file). The RTU will initiate a poll to the HOST whenever the RTU goes into an alarm state from a channel that is setup to cause callouts. After completing the POLL, the RTU should process an Acknowledgement command and thereby take itself out of alarm mode. 2.4 TEST SCADA ADVANTAGES SCADAWARE® System Design Manual 8 Dec 2001 - Preliminary A major difference in the "smart" TEST SCADA systems and other systems is the level of processing power located right at the remote location. Traditional SCADA systems require the HOST computer to continuously call, or "poll", the RTU in order to detect the alarms. In those cases, the RTU merely acts as a means to connect field devices to the HOST computer. The TEST system, however, allows the RTU to have the same processing capabilities as most HOST computers. This has several advantages: 1. The RTU occupies costly communications channels only when necessary, eliminating constant polling requirements. 2. Calculations such as AGA-3 Gas flow can be done directly at the RTU. Alarm points can be specified in actual flow units rather than values related to the variables of the equation. This means that a low gas flow alarm can be specified in MMCF rather than in inches of water across the orifice plate. 3. The RTU or HOST can store information permanently on various types of disk storage devices or a printer. This Data logging and storage can be provided to allow continuous recording during periods of communications failure common in remote locations. Alarm conditions, data values, or text messages can be stored as well as transferred to other computers for later processing. 4. Calibration and maintenance is simplified by providing the power of a full PC right in the field. This is done by providing diagnostic and calibration procedures on the RTU and eliminating the need for the HOST computer to evaluate data values. 5. Some control functions can be provided locally by the RTU without any contact with the HOST. Status outputs can be controlled in response to many types of events such as alarm conditions, timer timeouts, or communications failures. 2.5 TYPICAL APPLICATIONS The basic use of TEST's SCADA systems is to monitor a remote location, such as an unmanned production facility, and have the RTU report back to a HOST computer. The HOST can be at a nearby manned facility or at a distant location. Installations such as this normally use low power radios to communicate between facilities. These radios can be the normal voice radios used in the field, or can be on separate frequencies to reduce noise on the normal channels. Of course, the system can also use phones or direct connections to transfer information among the units. The purpose of such a system is to provide alarm reports as soon as possible so that personnel may be dispatched to correct any problems. Without SCADA, the facility may require frequent visits for routine checks. Another use of the SCADA system is to allow control of the remote facility from the main facility. This control can be for shut-in operations, well control, or other process sequencing as allowed by MMS1 regulations. This system may be further standout by the addition of a phone link from the main facility to a distant location. This allows for the main and remote facilities to be monitored and controlled from the distant location at times when the main facility is unattended. This is often the case during hurricane evacuations or periods when production is curtailed due to market conditions. The HOST system can also act as an RTU by adding I/O interfacing at the host location. Because there is not much difference between an RTU and a HOST in the TEST systems, RTU type operation at any location is possible. The main differences are in the programming and setup options that determine how the system reacts to abnormal conditions. 1MMS - Minerals Management Service, US Department of the Interior SCADAWARE® System Design Manual 9 Dec 2001 - Preliminary SCADAWARE® System Design Manual 10 Dec 2001 - Preliminary 3 RTU AND HOST HARDWARE COMPONENTS 3.1 PERSONAL COMPUTER The TEST SCADA system is based on personal computer technology using many common PC hardware components and techniques. A summary of the hardware components is as follows: 1. PC: Contains the computer portion of the system including CPU processor, ROM and RAM memory, disk storage, video display, keyboard, and process I/O interface. The RTU/SCADA software operates within this component. 2. PROCESS I/O: The input and output devices that connect the physical world to the computer. This includes the computer interface as well as the field transmitters and switches. The I/O devices currently supported are "Metrabus" compatible interface cards, relay type input and output cards, and many generic PC based I/O cards. 3. DATA COMMUNICATIONS: A comm port (serial or network) is used to convert digital computer information to signals that can be transmitted over a wire, voice grade phone line or radio channel, or a computer network. ÚÄÄÄÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÄÄÄ¿ ³ RAM ³ ³ ROM ³ ³ RAM ³ ³RAM DISK ³ ³ MEMORY ³ ³ MEMORY ³ ³ DISK ³ ³PACKS ³ ÀÄÄÄÄÂÄÄÄÄÙ ÀÄÄÄÄÂÄÄÄÄÙ ÀÄÄÄÄÂÄÄÄÄÙ ÀÄÄÄÄÂÄÄÄÄÙ ÚÄÄÄÄÄÄÄÄÄ¿ ³ ³ ³ ³ ³ I B M ÆÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍ PC MEMORY BUS ÍÍÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍ ³ P C ³ ³or Equiv ÆÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÑ PC I/O BUS ÑÍÍÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍ ÀÄÄÄÄÄÄÄÄÄÙ ³ ³ ³ ³ ÚÄÄÄÄÁÄÄÄÄ¿ ÚÄÄÄÄÁÄÄÄÄ¿ ÚÄÄÄÄÁÄÄÄÄ¿ ÚÄÄÄÄÁÄÄÄÄ¿ ³ METRA ³ ³ VIDEO ³ ³ SERIAL ³ ³ DISK ³ ³ IFACE ³ ³ CARD ³ ³ PORTS ³ ³ CONTROL ³ ÀÄÄÄÄÒÄÄÄÄÙ ÀÄÄÄÄÂÄÄÄÄÙ ÀÄÄÄÄÂÄÄÄÄÙ ÀÄÄÄÄÂÄÄÄÄÙ º ³ ³ ³ º LOCAL MODEM FLOPPY M º CRT ³ & HARD º REMOTE DISKS E º CRT º T º ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ÇÄÄÄ´ 32 POINT STATUS IN/OUT CARD ³ R º ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ º A º º ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ B ÇÄÄÄ´ 16 POINT ANALOG INPUT CARD ³ º ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ U º º S º ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ÇÄÄÄ´ 8 POINT COUNTER INPUT CARD ³ º ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ TYPICAL METRABUS BASED RTU CONFIGURATION SCADAWARE® System Design Manual 11 Dec 2001 - Preliminary 4. POWER SUPPLY: Receives either 120 VAC or 10-40 VDC and converts it into the necessary PC operating voltages (+5, +-12 VDC). An additional 24 VDC supply can also be provided to power 4-20ma current loop type transducers. Remote locations may use Solar cells to recharge the batteries which power the system. The HOST and RTU computers are very similar in design and function because they are all basically Personal Computers. Although they are all very similar, each always has one or two features that make it unique to that particular installation. The main difference between an RTU and a HOST computer is that the HOST normally has no actual process I/O devices connected to it. It receives values from the RTU over the communications channel. Once the values are received, they are processed exactly as they were in the RTU. In all other respects, the HOST configuration and operation is identical to the RTU. A typical configuration for an RTU using Metrabus compatible interface cards is shown above. 3.2 PC COMPONENT IBM PC/XT/AT computer. The selection of the actual processor is based on processing requirements, electrical power requirements, and the needs of other computer applications running on the same system. Most RTU installations can be accommodated with a 8Mhz PC/XT type system or higher. With the exception of the disk devices and video, the operation of the system is identical on all hardware configurations. The PC based RTU provides the capability to scan the process I/O, generate displays, make alarm decisions, and report data to another computer. The traditional PC features like video displays, keyboards, serial and parallel ports, DOS operating system, disk storage, and expansion bus cards are all available for use by the SCADA program as well as other PC based software. Note: The use of a PC for an RTU prevents concurrent use by other programs. The use of a PC as a Host is possible although the SCADA program cannot be run at the same time as other applications. Therefore, an RTU needs a dedicated PC while a Host PC can be used with TEST's program as well as other programs. 3.3 PROCESS I/O HARDWARE All SCADA systems require some means of obtaining switch status and analog value data for processing by the computer component. The TEST SCADA system supports I/O devices such as the "Metrabus" family of interface boards manufactured by The Metrabyte Corporation, simple relay type input and output cards that are installed directly into the PC I/O bus, and other generic PC based I/O cards. The details of these systems are provided in separate documents prepared for each system type. The typical I/O system includes the following I/O types: 1. Status (digital) inputs and outputs: These are discrete off-on inputs and outputs. The I/O receives inputs from devices like switches or electronic levels, and controls outputs like control relays, lights, and solenoids. 2. Analog Input: These inputs are typically voltage levels that can vary from some minimum to a maximum level. The minimum is called the "Zero" point, and the maximum is called the "Span". The I/O hardware and a software driver convert the voltages into 16 bit signed numbers that are further manipulated by the SCADA software. If the analog input hardware is less than 16 bits (normally 12 bits), then the software driver will scale the value up to 16 bits. In this manner, all analog inputs look the same to the SCADA software regardless of their actual resolution. 3. Counter Inputs: Counter inputs are used to interface transmitters that generate pulses that relate to rate or total flow. The pulses can be slow (one pulse every second or so) indicating totalized flow, or can be fast (hardware dependent, but often thousands per second) indicating rate. Totalized pulses often originate from instruments such as gas flow computers, while rate pulses originate from turbine meter magnetic pickups. SCADAWARE® System Design Manual 12 Dec 2001 - Preliminary 3.4 DATA COMMUNICATIONS SCADA systems normally require the use of some type of communications medium to send data from the RTU to the Host computer. This has traditionally been some sort of "on-line" communications link using a dedicated phone line or microwave channel. The TEST SCADA system, however, can use either telephone or radio communications on a "dial up" basis to minimize connect time and its associated costs. Using a standard serial communications port on the PC (COM1- COM4), a modem of the proper type connects the computer to the communications line. The modem changes the digital computer data into audio tones that can be transmitted much as any other sound is carried on the line. A similar modem on the receiving end reconverts the tones back into digital data for use by the other computer. Various types of intelligent and dumb modems are used in the SCADA system depending on the type of communications line being used: 1. HAYES Type Phone Modem: The Hayes standard for phone modems has produced a variety of low cost, high performance modems that are essentially identical in operation. The TEST SCADA system can use almost any compatible modem, although some have specific advantages (like 12 VDC operation) that promote their use in certain applications. 2. Packet Radio Controller: The PRC is a special modem device that allows connection of the computer to a voice type radio. The unit takes care of message routing and error checking so that many units can share a common radio frequency. 3. Simple and Multi-Drop Modems: Simple modems which only convert digital data into tones can be used in point-to-point applications. Multi-Drop modems, which turn the transmit carrier off and on, can be used when many stations share a single communications path. 4. Direct Connections: A modem is not actually required as two (or more) units can be connected by direct wire if the proper serial ports are available. RS-232 ports allow only two devices, while other RS-xxx ports allow up to 50 units to share a single wire. Many types of modems are actually micro-processor based devices that are themselves small computer systems. Their processing capabilities are specifically designed for communication tasks, and they take care of many dialing, timing, call sign, and other low level tasks. Consult the operations manual for the specific modem being used for information on its command processing capabilities. The SCADA program provi des special commands (HAYES and PRC) to assist in programming some types of modems. These commands take care of the sticky details of getting the modems in command mode and then returning them to an on-line state if needed. For example, a Hayes modem has the command codes Q1 and E0 to set the modem in Quiet mode and to turn character Echo off. To pass these parameters to the modem, the command line HAYES Q1 E0 can be used. Similarly, the Packet Radio Controller has a command to set its radio address called MYCALL (short for my call sign). To set a PRC's address the command PRC MYCALL anyname could be used. These commands are most often used in the STARTx and BYEx command files, although they can be fed to an RTU task in any other fashion as well. Telephone systems used by the SCADA system can be almost any type that provide a standard Bell RJ11 (modular phone) jack. The communications rate is limited by the quality and reliability of the channel, although the software is designed to handle poor communications. Generally speaking, the telephone line is the weakest part of most remote SCADA system installations. Radio systems can be any type that can provide an adequate bandwidth for the modem. FCC limitations may restrict the amount of data transmitted at any one time. Radio systems, once installed properly, generally SCADAWARE® System Design Manual 13 Dec 2001 - Preliminary provide less trouble than phone systems due to the consistency of the equipment and signal levels. 3.5 POWER SUPPLY The PC, I/O subsystem, communications devices, and other system components require a number of regulated voltages in order to operate properly. The Power Supply is a standard component in a desktop PC, while industrial PC systems may require a special power supply to accommodate battery or Solar power operation. For example, the TEST SCADA system uses a power supply that accepts either 120 VAC or 10-40 VDC (but not both) and produces the +5, +-12 needed by the RTU hardware system. SCADAWARE® System Design Manual 14 Dec 2001 - Preliminary In the case of battery powered systems, solar panels are often used to charge the storage batteries. If possible, one of the status or analog input channels is used to monitor the voltage of the batteries to avoid any downtime due to low battery power. The power requirements of the SCADA system fall into 2 general categories: 1. Processor and I/O: Continuous low power requirement. 2. Communications: Periodic high power and continuous low power requirement. Battery powered systems must be designed to accommodate the periodic requirements based on the anticipated communications usage. [ power supply slide ] SCADAWARE® System Design Manual 15 Dec 2001 - Preliminary 5 COMPUTER SETUP, STARTUP, AND OPERATION 5.1 PROGRAM AND DATA FILES In addition to the main RTU/SCADA program file, SCADAWARE uses a number of data files to store setup, channel program information, and automation tasks. These files are normally contained in the same DOS directory as the program file, although this is not required. The complete version of SCADAWARE is contained in a program titled RTUMON3. The limited version is called RTULITE3. The programs are very similar in function, but internally are very different. RTUMON3 works as a DOS Protected Mode Interface (DPMI) program, while RTULITE3 is a simple real mode program. The full version has all program features, while the "lite" version is missing advanced features in order to reduce program size and complexity. Startup of both types is similar, although there are several differences explained here. In almost all cases, the program name RTULITE3 can be substituted for RTUMON3 without any other changes. 5.2 DOS CONFIG.SYS FILE Warning! Some knowledge of PC boot sequences is necessary to fully understand this section. It is presented as a guide for experienced PC users when setting up the RTU or Host PC Computer. All computers operating the RTU/SCADA program should have a config.sys file present on the boot device. This file will tailor the fundamental properties of the system to meet the needs of the RTU program. In spite of SCADAWARE's real-time, multi-tasking capability, it operates as a very tame DOS application which conforms to rigid DPMI specifications for memory use and processor allocation. In order for SCADAWARE to operate properly, the PC's Config.Sys file should have at least the following lines: CONFIG.SYS DEVICE=HIMEM.SYS Microsoft DOS Extended Memory Manager FILES = 24 Minimum Open files BUFFERS = 20 Typical file buffer count The older RTUMON2 program consisted of two files, RTUMON2.EXE and RTUMON2.OVR. The full SCADAWARE program does not use overlays. SCADAWARE Lite still uses overlays, but stores them in the main program file itself rather than in a separate overlay file. The full RTUMON3 program requires several additional support files that the RTUMON2 program did not. They must be located in the RTU program directory: DPMI16BI.OVL Borland's DPMI Server (interfaces with HIMEM.SYS) RTM.EXE Borland Pascal's run-time manager. RTUFONT.LIB Genus Graphics Package Font and Shape library (Note: these extra files are not required for the Lite version.) The entries in the file that are needed for the RTU program should be added to those necessary for other features or programs on the computer. These entries will vary according to the nature of the hardware implementing the system. For example, ROM and floppy based systems normally require that a RAM disk be installed via the config.sys file to speed up RTU command file processing. Systems being used in different countries may need to include a line in the config.sys file to control the date format. The following commands can be used in the config.sys file to cause the dates to appear as follows: SCADAWARE® System Design Manual 16 Dec 2001 - Preliminary COUNTRY = 001 -- United States mm/dd/yy (DOS default) COUNTRY = 003 -- Latin America dd/mm/yy A typical config.sys for a ROM based system is as follows: shell = a:\command.com /f /p - reconfigure COMMAND.COM buffers = 10 - file transfer buffers files = 16 - max open files device = ansi.sys - Terminal driver device = ssd-drvr.sys X1E - Drive C: device = ssd-drvr.sys X1A - Drive D: 5.3 SCADAWARE VERSIONS RTUMON3 and RTULITE3 are revised versions of TEST's earlier program releases. Some changes are necessary to implement the Release 3 programs on systems running older software. Although these changes are minimal, they are necessary for proper operation of the TEST SCADA program. The main difference between the old and new programs is that the internal structure has been modified to work under the command of a revised Multi-tasking program manager. The full version of the program, RTUMON3, also uses the DOS Protected Mode Interface (DPMI) to access the advanced features of the Intel 80386, 80486, and later processors which are required for its operation. SCADAWARE Lite, RTULITE3, does not use protected mode and will therefore run on an 8086 or 80286 processor. RTULITE3 will use XMS memory to a limited degree and is therefore useful on some larger processors that do not need the advantages of the full SCADAWARE program. The advantages and limitations of Lite version are listed below: RTUMON3.EXE - PROTECTED MODE VERSION 1. Requires 80386, 486, or later CPU. 2. Requires at least 2Mb of RAM with at least 1Mb of free XMS memory. 3. Math Coprocessor is not required, although it will be used if present. 4. Has Database and Graphic capabilities. 5. Has Modbus, ROC, and other Open Architecture features. 6. Can handle up to 250 RTUs and 24 tasks per computer. 7. Real Numbers are stored in IEEE ANSI standard 4-byte format 8. Integers are stored in IEEE ANSI standard 2 and 4-byte format. RTULITE3.EXE - REAL MODE VERSION 1. Small Disk Space Requirement (less than 500K total for RTULITE3.EXE). 2. No need for 80386 or later CPU. 3. Main Memory Requirement is 640K with at least 560K free. 4. Extended Memory (XMS) is not required, although it will be used to store task stacks. 5. Math Coprocessor is not required or used. 6. No Database or Graphic capabilities. 7. No Modbus, ROC, or other Open Architecture features. 8. Simplified Image Save System with no Network Support. 9. Limit of 10 RTUs and 8 tasks per computer. 10. Real Numbers are stored in Borland 6-byte format. In most respects, conversion from older programs is the same for SCADAWARE or SCADAWARE LITE. Only SCADAWARE will be addressed directly, with any special requirements for SCADAWARE LITE mentioned where required. SCADAWARE® System Design Manual 17 Dec 2001 - Preliminary 5.4 AUTOMATED COMPUTER STARTUP Most installations are setup so that the computer automatically runs the RTUMON3 program with the proper parameters each time the system is booted. The standard way of doing this is to have the computer's normal autoexec.bat file execute a command called START as its last line. This command is actually a batch (.BAT) file in the program's root or \RTU directory. The START.BAT file will contain any DOS commands necessary to start the program, including the RTUMON3 command that actually starts the SCADA program. If desired, the START command can be entered in the batch file after the RTUMON3 command so that the program always restarts if somehow terminated. This is fine for unattended locations, but may be a nuisance in other locations because an endless loop is established that continuously runs the RTUMON3 program. An example autoexec.bat (with comments) for a HOST installation with a hard disk may look like: prompt $P$G ; tell user where he is path C:\; C:\DOS; C:\util ; Tell DOS where to look cd \rtu ; switch to program's dir START ; start the RTU program This file, which is always processed by DOS when the PC system is restarted, does some housekeeping and then starts the program directly. When SCADAWARE terminates, it will be automatically restarted because the file ends with a START command. An example autoexec.bat (with comments) for an RTU installation with a ram disk C: may look like: setwait UMB32 LMB512 UMW1 ; Special setup for particular PC set comspec=A:\command.com ; Tell DOS what to use path a:\ ; Default search path pcclock ; Read watch and set time :looper ; Program loop start a: cd \ locate start.bat c:\ d:\ e:\ ; Try and find start file if errorlevel 99 goto looper ; If not found at all, loop if errorlevel 3 goto use_e ; if found on drive E if errorlevel 2 goto use_d ; if found on drive D if errorlevel 1 goto use_c ; if found on drive C goto looper ; keep searching :use_c c: ; Switch to C: cd \ ; Root on C start ; Execute START.BAT to run RTUMON3 goto looper ; Loop again (additional code for each drive follows here) Notice that this autoexec file does the normal housekeeping and then executes a special TEST prepared program called "LOCATE" to find the start.bat file. The program looks in the drive sequence C D E specified on the command line. The advantage of this special program is that it avoids "disk not ready" type errors that will usually cause similar programs to crash. The point is to find the first working disk device that contains the program we want. The location is returned in a special DOS variable called errorlevel, and the program branches according to its value. The value of 99 indicates no file was ever found, so the autoexec just loops till satisfied. SCADAWARE® System Design Manual 18 Dec 2001 - Preliminary This autoexec.bat file is typical of the ROM based RTU systems where the location of the startup file is not known. It may be on a RAM disk, a 5-1/4" diskette, a 3-1/2" diskette, or a ROM disk. This type of autoexec.bat file allows for flexible operation without changing the ROM disk by letting the autoexec find the first acceptable disk from which to run. Once the start.bat file is located, control is turned over to it by the autoexec file. An example START.BAT file for a floppy based RTU that uses a volatile RAM disk F: is as follows: copy *.rtu F: ; copy command files to RAM disk RTUMON3 /f=wc458a ; start program for wc 458a start ; loop forever This example start.bat copies the command files (.RTU) needed for normal operation to the ram disk called F: (which must have been established in the config.sys at boot time). The use of the ram disk allows for very fast command file execution without the power consumption and delays associated with the floppy disk drive. RTU systems running from a permanent RAM disk do not normally need this option. 5.5 ROM BASED DISK DRIVES AND RTU BOOT SEQUENCE The RTU computer can be any type of PC compatible system that will boot according to normal PC standards. However, some installations use special disk devices located on Read Only Memory (ROM) chips or possibly on Non Volatile Random Access Memory (NOVRAM) boards. These devices emulate normal magnetic disk devices but are completely solid state and have no moving parts. In systems with a boot ROM, special instructions are placed in the autoexec.bat file to allow a variety of boot sequences to occur without changing ROMs. A key to this process is a TEST prepared program called LOCATE which allows the start sequence to find the desired programs without running into problems with non-existent or not ready disk devices. This program looks for the initial RTU program called "START.BAT". This is a normal DOS batch file that must exist somewhere in the search path in order for the system to load. If not found, the autoexec.bat file will keep looping till one is found. It can be aborted with the usual control-C to allow manual operation. The ROM will set up disk devices in the RTU according to the following schedule: DISK ACTUAL DEVICE A: Boot ROM itself. B: First Floppy drive C: Novram device D: ROM Drive on Memory Expansion Card During the processing of autoexec.bat, a search is made for the file START.BAT in the following directories. A:\ - ROM Disk (never finds it there!) C:\ - NOVRAM B:\ - First Floppy D:\ - Second ROM Drive The first disk drive that is operable and contains the file START.BAT will become the default system drive (i.e. the one that shows up at the DOS prompt) and execution will continue with START.BAT on that directory. This allows for a flexible startup because the operator can remove and insert a variety of devices and have the system boot from any device containing the program "START.BAT". If more than one contains the program, the first one found in the above search sequence will get control. If you want to skip over one of the drives, remove the NOVRAM or diskette and the startup process will skip over it. SCADAWARE® System Design Manual 19 Dec 2001 - Preliminary startup slide SCADAWARE® System Design Manual 20 Dec 2001 - Preliminary 5.6 RTUMON3 PROGRAM STARTUP No matter how the RTUMON3.EXE program is loaded, the sequence of events that occur after the load will be the same. The RTU/SCADA program will maintain control of the system until the program is terminated. At that point, the START.BAT file that had loaded RTUMON3 will continue. If the program was simply started from the DOS prompt, then control is again returned to the prompt. Just after starting, RTUMON3 signs on with the program version number. The program then looks for the main configuration file (default is RTU.DAT), containing special task setups. If found, this file will tell the multi-tasker how many tasks to setup and what to call them. If not found, the program will halt. The default file name can be overridden by the /F= command line option discussed below. The program then initializes the tasker and clears a number of internal sub-systems. The communications channels are then initialized to default values (which may be overridden during later processing). In the main configuration file just loaded, the DRIVER task setup is used to specify which types of I/O devices are being used. Each type has a separate configuration file associated with it, and these files are processed at this time. If a file name is not specified in the TASK DRIVER line, the file name "RTU" is used with an extension appropriate for each I/O device. For more information about the TASK DRIVER command refer to section 7.11 of this manual. After all this setting up, the multi-tasker is started so that task switching can occur. HOWEVER, ONLY THE LOCAL TASK NUMBER 0 IS AUTOMATICALLY STARTED when the RTUMON3 program starts. The starting of task 0 will cause it to look, by default, for the file START0.RTU, which must contain all of the other steps necessary to start all other scheduled tasks. A different task 0 startup file can be specified with the /S= command line option discussed below. 5.7 RTUMON3 COMMAND LINE OPTIONS It is possible, and desirable, to override the default file names used to initially start the system. This allows for files with names related to the particular installation to be used rather than generic names like "RTU.DAT". For example, the main file for a facility called WC458 can be named WC458.DAT. This also simplifies testing of Host and RTU locations because numerous files can exist in the same directory during setup. The primary means of specifying options are with command line switches. This technique is used on many DOS programs and the method is very similar in all cases. A switch character (the slash "/" character, not the backslash "\" character) is used to signal that an option is being provided on the command line. Information related to the option follows the switch character, and one switch character is required for each option being specified on a single line. In the most basic case, entering "RTUMON3" on the command line is all that is needed to start the system. If options are provided, they must follow the RTUMON3 command after at least one space. In our case, the options consist of a letter and an equal sign followed by a file name. The letter signals the purpose of the option, and the file name is the name that will override the specific default file name assumed by the program. The available options are: /F=filename - Main config file to replace RTU.DAT. RTUMON3 /F=MYRTU.DAT /S=filename - Replacement for START0.RTU. RTUMON3 /S=SPECIAL.RTU A parameter is available to allow selection of the system tick interrupt used by SCADAWARE. This topic is covered in section 4.9 of this document. The new parameter is /T and has the following options: /T=H Hardware Timer Tick, PC interrupt 8 at 18.2 per second. SCADAWARE® System Design Manual 21 Dec 2001 - Preliminary /T=D Dos Multiplex Interrupt 1C hex at 18.2 per second /T=S Soft interrupt called as often as possible with average rate at 18.2 per second. Another parameter is available for setting the address of the security lock (dongle). Details on this option (/D=) are provided below. /D=1 LPT1 ( address determined by bios ) /D=2 LPT2 ( address determined by bios ) /D=3 LPT3 ( address determined by bios ) /D=5 Physical Port address 03BCh /D=6 Physical Port address 0378h /D=7 Physical Port address 0278h The following applies only to RTUMON (full program version): /PLAY Install Sound Playback system The following apply only to RTULITE: /O=filename - Replacement for program overlay file RTULITE3 /O=D:RTU.OVR /B=bufsize - Adjustment to default overlay buffer size RTULITE3 /B=40000 /E=xx - Reserve xxK Memory for Exec Shell. RTULITE3 /E=45 /X - Do not use XMS even if available RTULINE3 /X Note that more than one command line option can be (and often is) used on a single DOS command line. The line is normally part of a standard start sequence that is stored in a DOS Batch file called START.BAT. So, to start the program and have it process VR167A.DAT rather than RTU.DAT, and to start task 0 with SPECIAL.RTU rather than START0.RTU, we would enter: RTULITE3 /F=vr167a.dat /S=special.rtu /B=32000 Note that upper and lower case does not matter in this case. The program also assumes a file type of DAT for the /F option. Normally, the proper command line is placed into a DOS batch file (called START.BAT) along with any other special startup tricks needed for the program. These tricks may include defeating any existing TSR programs, copying files to a ram disk (on floppy based systems), and changing the DOS prompt. A sample start.bat is as follows: copy *.rtu C: - ram disk copy *.dat C: - ram disk c: - change drives prompt Hit EXIT to return to RTUMON3$_$P$G - DOS prompt b:RTULITE3 /F=c:wc146.dat /o=b:RTULITE3.exe - program start prompt $P$G - restore prompt start- do it all over 5.8 LOCATING SCADAWARE LITE PROGRAM FILES The main component of the Lite program, RTULITE3.EXE, can be located on any legal DOS disk device. This allows flexibility in using RAM, ROM, and floppy disk drives to optimize program performance. When using SCADAWARE Lite, it is necessary that both DOS and the program itself be informed of the proper location of the main file because it is accessed during normal program operation to retrieve overlay modules. Identification of the program location takes place in the START.BAT file used to kick off program execution. SCADAWARE® System Design Manual 22 Dec 2001 - Preliminary For example, suppose we have a typical RTU with a boot ROM as drive A:, a floppy disk as drive B:, a RAM drive as C:, and a ROM drive as D:. We want to operate the system using the RAM drive as the default device, but have the program and overlay located on the ROM drive D:. During the startup sequence, the boot ROM A: will search for a file called START.BAT, and when found, will switch to that drive before executing that file. SCADAWARE® System Design Manual 23 Dec 2001 - Preliminary In our example, we want to use drive C: as the default drive where all the RTU and other setup files will be located. So, we will put START.BAT on drive C:. This file will contain the following typical information: prompt ENTER EXIT TO RETURN TO RTU PROGRAM $_$P$G c: d:RTULITE3 /o=d:RTULITE3.exe /f=rtuname.dat prompt $P$G start Each line has a specific purpose when executed by DOS. The first line changes the DOS command prompt to provide a message telling the user how to get back to the RTU program. This message will only appear when the user "shells out" of the RTU program. The second line switches operation to use C: as the default disk drive. The third line is the one that starts the actual RTU program. The first entry on the line tells DOS to load the program RTULITE3.EXE from drive D: rather than from the default drive, which is currently C:. This is all DOS needs to get the program started. The remaining entries on the line are for the RTULITE3 program's internal use only. The /O= parameter tells RTUMON3 where to find it's overlay routines, on drive D:. The /F= parameter would have the name of the control file to be processed on startup. The fourth line will be executed by DOS when the program terminates. It restores the prompt to the normal C:\>. The fifth line restarts this START.BAT program all over again. This is normally done on RTUs to keep the program in a never ending loop. Systems using a hard disk or other large primary device need not relocate anything. Simply put everything in one directory and start the program as follows: RTULITE3 /f=rtuname.dat Once the program starts up, it assumes that all the necessary RTU, MNU, and any other files will be located on the default disk unit (C: in these examples). No disk letter is needed before the RTULITE3 program name because the default of C: will be assumed by DOS. As you can see, there is a lot of assuming going on, and it is important to keep track of what is where, and what the various components expect to find. SCADAWARE® System Design Manual 24 Dec 2001 - Preliminary 6 MULTI-TASKING 6.1 MULTI-TASKER SUPERVISOR The RTU/SCADA program contains a proprietary Multi-Tasking Supervisor (MTS) which is used to control the simultaneous operation of several functions on a single computer. When using the RTU/SCADA program, it appears that several independent functions, called tasks, are operating simultaneously. In reality, only one task is operating at any given instant (measured in milliseconds). This program uses different tasks to perform specific functions which contribute to the overall scheme of operation. Because there are many tasks and only one processor, all tasks must share the processor on a time sharing basis. Each task gets a certain amount of processor time to do whatever it needs to do, then it must stop processing and pass control to another task. Eventually, each task will regain control of the processor and continue processing exactly where it had left off. When its time is up, a task will once again stop processing, pass control to another task, and begin waiting for its turn to continue processing. The computer processes commands so quickly that the time a task spends waiting to regain processor control goes virtually unnoticed. The "round-robin" style of task swapping is a gross simplification of what actually occurs inside the program. Some task functions are given special priorities, most notably the SYSTEM task, which takes care of time critical functions within the program. Another special task, the SCAN task, gets the opportunity to run on each and every clock tick to take care of I/O related functions that occur very quickly (i.e. counter inputs). Message management is also an important part of a multi-tasking supervisor. In TEST's system, a message is a text line containing a TSP command of any type. Tasks "read" these messages from various sources including the keyboard or serial port, files, libraries, and inter-task messages. The MTS provides for the proper transfer of messages from one task to another, and also provides the mechanisms to store messages in a list (queue) until a task is ready to process them. It is very important that the proper task get each message because a task meant for a serial port task will not necessarily make sense to one that manages the local keyboard. All of these functions occur automatically and are mostly hidden from the casual user. However, those interested in setting up or programming complex SCADA applications must understand the MTS and how it manages the complete SCADA system. Multi-tasking is not a trivial subject. However, the concept is critical in understanding the power of TEST's SCADA system and TSP protocol. Think of a TASK as a single high level function within the program. For example, the portion of the program that interacts with the local user is a single task (called the Local task, or Task 0). This unit receives your keypresses, presents displays, edits files, and performs other human oriented duties. Another separate task (or series of tasks) takes care of scanning the input/output devices to read status and analog values. These DRIVER tasks have nothing to do with the Local task just described. Their functions are completely independent (well, almost). When a task is executing, it "thinks" it's the only program on the computer. When they are suspended by the multi-tasker, they effectively go to sleep and resume operation just where they left off when it is again their turn to run. The job of the multi-tasker is to coordinate the actions of these various tasks so that each gets adequate processor time without "hogging" the systems's resources. 6.2 A MULTI-TASKER ANALOGY Its analogy Time! This section will offer a simple analogy for a Multi-Tasker that will help non-programmers grasp the concept. If you are a computer guru, feel free to skip this section. But, if the idea of a CPU juggling a bunch of tasks every few milliseconds bothers you, please read on and get more comfortable with the idea. Our analogy will be between the Multi-Tasker and a busy Dentist's office. It takes a bit of imagination, but it should help you get a better idea of how the computer manages the multiple tasks. Multi-Tasking is much like managing a Dentist's office with several patients in different types of rooms. The patients are at various stages of different dental procedures, some of which are minor and others that are SCADAWARE® System Design Manual 25 Dec 2001 - Preliminary major. One patient may be in a small treatment room for a filling and is waiting for the anesthetic to take affect. Another may be in the dental tech's room for a cleaning and is waiting for the X-rays to develop. And another is in the surgery room in the process of getting a root canal (ouch!). There is also an administrative area where the Dentist takes care of business and receives instructions on what to do in the various rooms. The office is a fixed size, and the space is divided among the various rooms to suit the needs of the work that is normally done there. The Dentist is the worker in this case. He devises a system to manage his time and the office resources, but only he can do the work being considered in this example. The goal is to make the most of the dentist's valuable time. The office procedure does this by managing the moment-to-moment operations while simultaneously serving the needs of all the Dentist's patients. Obviously, the Dentist can only work on a single mouth at any instant. But, he routinely moves from one patient to another so that he is working on several patients during the same period of time. He spends some amount of time on each one before moving on to the next even though the procedure for each patient is not complete. However, the patients feel like they are getting personal service because they expect delays at various stages of their procedures. It would be wasteful (and expensive!) to have the Dentist sit there and tap his shoe while these delays occur. So, he goes off and takes care of each patient one step at a time. Each time period is often called a "unit" in dental terminology, and a typical unit is 10 minutes. Some patients may require more consecutive units than others, but as long as the Doctor eventually gets to each room every everyone is happy. Now suppose an emergency occurs and one of the patients needs immediate attention. This is an interrupt for the dentist, and he must stop whatever he is doing and run quickly to another room to take care of the problem. Before leaving, he can crank up the nitrous oxide and put the patient to sleep so that he will not notice that the dentist has left. When the emergency is over, he can return to wherever he was and awaken the patient to continue the procedure. The emergency gets handled, and the sleeping patient never knows the difference (unless of course he looks at his watch). This interrupt handling capability is essential in allowing the Dentist to leave a patient while still offering the security of knowing he can be there quickly when he is really needed. The Dentist has a special duty to perform once per hour. This is when he stops for a moment and returns phone calls from patients with a special problem. The Dentist does not promise to take phone calls at any moment, but he does have a policy of returning calls at the start of every hour. Once he starts the phone session, he calls everyone who called in during the previous hour. This is a top priority task for the Dentist, but it must wait until the appointed time before it is started. So, the Dentist is a busy guy who takes care of a lot of separate procedures at the same time. He also has to make a living and is always conscious of the needs of the administration area. Of course, only a single patient is actually treated at any one instant. But over a period of time, all patients are attended to in a manner that makes the best use of the Dentist's time and office resources. The Dentist's environment is multi-tasking because he is doing many semi-related tasks at the same time. The priority of each varies according to the needs of the various tasks as well as the resources available at any particular instant. The process of managing the office must allow for many variables such as the needs of the procedures, the speed of the Dentist, the number of patients, the size of the rooms, and the help available from assistants and special equipment. The keys to the success of the process are that no single task needs the constant attention of the Dentist, and that the tasks are willing to cooperate with each other in sharing the Dentist's time. Now for the analogy. The CPU in the multi-tasking system is much like the dentist because there is only one of them that must be shared. The patients in their separate rooms are just like the program's tasks, each with its own set of requirements and problems. The tasks are similar to one another in that they require some effort from the processor, but they each have unique needs of their own. Each task has periods when a delay is appropriate and the CPU is not needed for a while, and like the patients the tasks are willing to give up the CPU's time for these programmed delay periods. Computer memory space is shared among the SCADA tasks just like the limited office space is shared among dental rooms. The CPU divides its time just like the SCADAWARE® System Design Manual 26 Dec 2001 - Preliminary Dentist does, but is in units that are much smaller than the 10 minute chunks used by the Dentist. The PC operates in system or "clock" ticks that occur 18.2 times per second. This is an extremely inconvenient time period which can be traced to the origins of the IBM PC in Boca Raton, Florida, and is a pet-peeve of SCADAWARE's developers. The priority of each patient determines how many consecutive time units he is allowed before the Dentist plans to move on. Likewise, the priority of each SCADA task determines how many consecutive clock ticks a task can have before the MTS forces the processor on to the next waiting task. If the SCADA tasks were not specially programmed for multi-tasking, they would consume all available CPU time even when they had nothing important to do. This would be a waste of computer power and would result in very poor multi-tasking performance. However, SCADA tasks are smart enough (like a dental patient) to voluntarily give up the CPU when they are not very busy. This occurs quite a bit in SCADA applications where a task must wait for relatively slow I/O operations to complete before moving on to the next step. The tasks run for a while, sleep for a while, and then run again all under the management of the MTS. But a task that needs special attention (like the one second SYSTEM task) can be given special priority that allows it to step in line ahead of other waiting tasks. TEST's system uses this technique, called cooperative scheduling, which is typical in PC based multi-tasking systems. The Dentist asks questions and gets responses from the patients as a routine part of his job. He services their requests, one at a time, but can only help them when he is in their room. But the patients are not his only source of information. The Dentist may also get messages from outside sources while he is busy treating a patient. The input will most likely come from the administration area, but it may sometimes come from the lab or the storage area. The information may tell him what to do with the current patient or it may apply to one of those waiting in another room. To keep his messages straight, the Dentist sets up an in-basket in each room that has a "first-in first-out" design. Messages placed in the basket will be read in the same order that they are received. With this system, the Dentist can go to each room and complete his current operation and then check the in-basket to see if any more work is needed on the patient in that room. The administrators, lab techs, and other support people can stay in touch with the Dentist as he makes his rounds in the office. The input from the patients is similar to computer user's input from the keyboard or serial port. The Dentist listens to a request, and then preforms a service for that particular patient. Input from one patient will not normally affect another one unless a patient sends a message to another room. For example, one patient may request the cost of a cleaning and if it is acceptable, he may say "Great. Please clean my child's teeth in the other room." The conversation is between one patient and the Dentist in room one, but the activity will occur in room two. The personal conversation resulted in a message being sent to another room. When the Dentist gets to that room, he will find a message (which he actually sent to himself) telling him the procedure to perform on the patient that is waiting there. This is somewhat like a local CRT/keyboard user answering a prompt about performing a shutdown operation with the SCADA, but requiring that a message be sent to another task to perform the actual work. Sending the message to the wrong task will not get the desired result. The Dentist's inter-office message system is similar to the one in the MTS because it allows for a first-in first-out queue in the form of inter-task messages. It is also similar in that once the Dentist reads a message, he will perform the complete operation before looking again at the message basket. The MTS does the same thing when a message tells a task to process a command file or library procedure. Command File processing is like a multi-step dental procedure. Once it starts, it cannot be terminated unless the entire task is restarted. The Dentist's phone call return policy is much like the one-second SYSTEM task in the SCADA program. Any requests for a phone call are stored and processed by the Dentist exactly on the hour. In the SCADA program, any periodic processing requirements are flagged constantly but are processed on each second. So, the SYSTEM task has a special priority just like the phone call routine performed by the Dentist. Once started, the SYSTEM task runs to completion regardless of the number of system ticks needed to make a complete pass. As more tasks are added to the CPU, the management problems increase. A higher workload will SCADAWARE® System Design Manual 27 Dec 2001 - Preliminary require additional CPU power in order to prevent a slowdown in overall processing. The multi-tasker is adjustable to suit the exact needs of each individual situation, and it also allows dynamic changes to suit needs that pop up under special circumstances. The multi-tasker allows priority components of any task to execute ahead of routine procedures so that time critical functions can be accommodated. And the MTS takes steps to insure that tasks do not interfere with one another by coordinating the limited resources of the computer such as memory, disk files, and communications ports. TEST's Multi-Tasker Supervisor is specially designed to work in a SCADA system environment. It allows field configuration of the number of tasks, types of tasks, priorities, programmed delays, and memory workspace. Some of these settings are done in a special file that is processed when the system is first started. Other settings are dynamic and can be changed while the program is running. The end result is a smooth running system that makes the best use of the available memory and processing power for each separate installation. 6.3 SCADA PROGRAM TASK TYPES There are several types of normally scheduled SCADA system tasks and several special tasks that are constantly being juggled by the tasker. The types of tasks supported by the MTS are: 1. RTU TASK: RTU tasks can receive command lines from the operator, other computers, other tasks, or prepared command files. The use of several RTU tasks allows the local user and additional remote users to access a system at the same time. Each user has control over his own task and can operate without much concern for the other users. On all systems, task 0 is automatically defined during startup as an RTU type task. This task, referred to as the LOCAL task, is used to process commands from the local user. For this task, commands are usually received from the keyboard and responses are sent to the local terminal. This is the only RTU type task that is automatically defined and started. All other RTU type tasks are optional and will not exist unless explicitly defined by the user in the main configuration (DAT) file. Additional RTU tasks can be defined to handle the processing of serial and network communications. An additional RTU task is used for each communications channel. For example, if a system communicates only by phone then only one RTU additional task would be defined. However, if a system supports both phone and radio communications, two additional RTU tasks would be defined. Task 1 is usually set up as the primary communications task for a system. By default, each RTU task is associated with the serial port having the same number as the task itself. For example, task 1 would use COM1, task 2 would use COM2, and so on. If necessary, the comm port associated with a task can be changed by using the SET PORT COMMAND. Refer to the COMMAND REFERENCE MANUAL for more information on this and other available commands. 2. UTILITY TASK: The UTIL task is basically just another RTU task with no terminal or serial line associated with it. It receives commands from other tasks or command files and is used for background functions that do not require interaction with the user or other computers. It is defined like any other RTU task and given the ID (nickname) of UTIL in the DAT configuration file. It is told not to use a communications channel by placing the command SET COMM -1 in the task's startup procedure. A few examples of what the UTIL task is used for are as follows: By default, the UTIL task is responsible for writing log data stored in RAM to a disk based log file. However, the task responsible for this function can be changed by using the LOG TASK command. The UTIL task also processes the IMAGE save functions, although this can be changed if needed with an IMAGE command option. The audio playback system also uses the UTIL task by default. SCADAWARE® System Design Manual 28 Dec 2001 - Preliminary The UTIL task will process report requests if the command LOAD REPORT is processed from within the main configuration (DAT) file during startup. Otherwise, reports will be processed by task 0. Perform actual processing of command files in response to a request initiated by a new alarm. 3. SCAN TASK: This is a background task used to scan all channels for new data, check for alarm conditions, and decrement alarm timers. Upon detection of alarm condition changes, this task is responsible for logging values to memory and activating links for channels configured to call on alarm or reset. This task also initiates execution of command files for channels programmed to do so (READ commands are sent to UTIL task), The SCAN task also executes PID and AGA3 calculations as part of the scan for those channels. Timer and Totalizer channels are also updated once per second as part of the priority processing done by the SCAN task. AGENDA list processing, log system timing, and other internal housekeeping chores are also done by SCAN. 4. DRIVER: The DRIVER task is used on systems with local I/O points to perform the low-level I/O operations for status inputs, status outputs, analog channels, and counter channels. This task will control outputs and convert inputs into digital or value type data. While the DRIVER task is responsible for reading input and output values, other tasks are responsible for processing the data without regard to where it came from. If no I/O hardware is attached the DRIVER task is not needed. Note: The Driver task will not be operated by the MTS unless an RTU security lock (dongle) is attached to the computer. 5. SYSTEM (ONE SECOND TASK): This task is a special task that gets to run once per second. It takes care of system level time-related functions such as callout delays and retrys, data image saves, and report printing. It also toggles the watchdog monitor output if activated with the MONITOR command. When the program initially loads, it automatically allocates the Local RTU task, the System Task, and the SCAN task. Any other RTU or Driver tasks must be defined in the DAT file used to describe each system. Refer to section 7.11 of this manual for information about how to define a task. It is important to understand the concept of the multi-tasker because the power it provides is accompanied by a certain amount of complexity. The main thing to remember is that each of the RTU type tasks is associated with a specific communications line, or local terminal, except for UTIL tasks which do not have any physical I/O device. When commands are processed, it is important that the proper RTU task executes the command. All other tasks perform common support functions that are needed by the RTU tasks. 6.4 TASK SWITCHING The primary function of the multi-tasker program is to constantly switch from doing one function to another so that the computer appears to be operating many programs at once. Task switching refers to the process of halting one function in its tracks and remembering everything about the state of the task at that moment. The next eligible task is then restarted from the point where it was interrupted. This process continues in a never ending loop that gives all tasks a chance to run, one after another. SCADAWARE's multi-tasker uses the principle of cooperative switching. This means that the entire program is written in small segments designed to execute one tiny portion of the overall operation. There are thousands of these procedures in SCADAWARE, each taking a small portion of time (measured in micro seconds). The cooperative multi-tasker monitors overall operation of the system and stops execution of a task when its allotted time has run out. The basis for timing is the PC's real time clock, accessed either directly or though DOS software procedures, with a time base of approximately 18 task switches per second. SCADAWARE® System Design Manual 29 Dec 2001 - Preliminary When each task's time runs out, processing proceeds with the next task in the list which is ready to run. A task may not be ready because it is "sleeping," or executing a programmed delay. This occurs when a task knows in advance that it will not require any processing power for a while. These delays occur during serial data transmission, programmed delays, and other timed activities. The Tasker is smart enough to keep track of these delays so that no processor time is wasted on tasks that have nothing to do. This occurs quite frequently in most I/O intensive systems like SCADA systems that spend a lot of time simply waiting for something to happen. If a task determines that it has nothing to do, it can give up the processor by initiating a task switch much like the timer tick does. In this way, the next eligible task gets a chance to run a little sooner because it will not have to wait for the next timer tick. Although the ticks occur at 18.2 times per second, this is a long time from the computer's viewpoint. The efficiency of the multi-tasker can be observed when it operates a local terminal and two remote terminals with very little apparent degradation in system performance, even on a lowly 8Mhz PC. 6.5 TASK PRIORITIES The above "round-robin" description of the task switching is a simplification of what actually happens in the real system. Only the primary procedure for each task is executed in this manner. Besides managing the primary task functions, the multi-tasker also provides priority processing for specific functions within each task. These priority procedures are provided a chance to run on each system tick, and once per second, regardless of which task was active at any instant. The multi-tasker is therefore operating at several different levels. The main loop handles the main functions of each task, the ones which operate in a cooperative manner. The next level is the system tick level, where each task gets a chance to execute selected routines on each system time interval (18 times per sec). The last level is the one-second level, which occurs every 18 system ticks. The one second priority is adjusted for the 0.2 error inherent in the PC system clock such that over a long measure of time (approximately one minute), the system appears to keep very precise time in spite of the PC's built-in error. The priority of each task defines how many consecutive system ticks it is allowed to operate before the multi-tasker puts it to sleep. The next eligible task will then pick up where it left off when its time had run out. Typical task priorities are 2 and 3 ticks, with longer ones needed only in very special cases. Note that the task priority can be changed at any time, allowing tasks to increase or decrease their processor allocation on-the-fly. This can be useful for tasks that run infrequently, but can use lots of processor time when they are operating. An example could be a serial communications task that is not used often. Part of the "connect" procedure for that task could be to increase its priority, and the "Bye" procedure could be used to restore it to a low level. However, the high efficiency of SCADAWARE's multi-tasker has eliminated concern over task priority because it wastes very little time on high-priority tasks which actually have very little to do. The one-tick and one-second procedures for each task will be executed automatically by the multitasker as required. Each task has its own needs, and they will be executed in the sequence in which the tasks are defined in the DAT file. Any task switching delays (caused by certain DOS and floppy disk operations) will be tracked so that the proper number of passes is made through the tick and second procedures. This may result in the special procedure executing later than normal, but the MTS will insure that they execute the proper number of times as soon as possible after the delay. Also, some tasks "go critical" from time to time to avoid problems associated with task switching under the DOS operating system. Specifically, any file operations that require DOS services will make a task critical so that it does not allow other tasks to run until the current operation is completed. This produces slight (10ms to several seconds) delays in other tasks that must wait for the critical task to complete before getting another chance to run. The critical settings are done automatically by the tasks themselves and are not directly controlled by the user. 6.6 TASK DELAYS SCADAWARE® System Design Manual 30 Dec 2001 - Preliminary Some tasks do not need to run that often, as is the case with the I/O driver task. The delay setting for each task is the number of ticks it will go to sleep after each complete execution cycle. This means that when a task's program is completely finished it will automatically go to sleep for at least the specified number of ticks. Other tasks, such as the alarm scanner, may also be similarly adjusted so that they do not use up an unnecessary amount of processor time. SCADAWARE® System Design Manual 31 Dec 2001 - Preliminary This is different from the time delay caused by pausing a task because its time priority has run out. In this case, a task will be marked as ready to run at the next possible opportunity. When a task completes one cycle and has nothing else to do (as when there are no more keypresses to process), it will go to sleep for the number of ticks specified in the delay setting. The point of the delay setting is to avoid wasting processor time on tasks that do not need to be run constantly. For example, a Host computer will only get new alarms when an update occurs unless there is local point activity from some other source. It may be desirable to only run the Scan task every few seconds by specifying a delay of 30 to 50 ticks. This will avoid wasting processor time checking point values which rarely change. An even fancier application can adjust the delay of the Alarm Scanner "on the fly" during downloads to allow faster alarm processing and then slow it down when the download is complete. 6.7 TASK MONITORING The STATUS command (from the menu or command line) can be used to monitor the status of the multi-tasking system. The displays show the various priorities, delays, memory space (stack) conditions, current commands, and other real-time parameters for each task. These displays are not normally used in routine operation but are invaluable during troubleshooting sessions. The STATUS displays move quickly because they show a "snapshot" of the task condition at the moment a single task is running. In other words, the task painting the display is always running when the snapshot is taken because it must be running in order to generate the display. So, it may be desirable to use another display (connected to a comm port) to monitor the status of Task 0 so that its actions during delays and other off-line periods can be monitored. HOST SYSTEM STATUS 09:16:26 TSK ID TASK_NAME STATE TICKS LEFT DELY LEFT STACK_SIZE CUR_STACK 0 0 Local CRT RUNNING 2 2 2 8000 05BF:6B2C 1 1 Com1 Mdrop RadAsleep 2 2 2 2 8000 05EF:7C84 2 UTIL Utility RTU Asleep 4 4 2 2 8000 0607:7C84 3 Scan Point Scan Asleep 2 2 30 14 8000 0617:7FAA 4 Sec System Asleep 2 2 2 2 8000 061F:7FC6 [ESC] to STOP [ENTER] to TOGGLE DISPLAY MULTI-TASKER STATUS DISPLAY SCADAWARE® System Design Manual 32 Dec 2001 - Preliminary 7 SYSTEM CONFIGURATION FILES The SCADA/RTU program is a complex, multi-tasking program that must be set up for each individual situation. The configuration of each system is primarily performed via two text files that are processed when the program first begins operation. The first file, the main configuration file, is used to define such things as tasks, RTUs, number of channels, and communications media. The second file, the I/O configuration file, is used to define the actual I/O being used. This file is only necessary for systems that contain physical I/O devices. The configuration files are simple ASCII text files that can be prepared and maintained with any text editor, including the one contained in the RTUMON3 (or RTULITE3) program. Each line begins with a keyword and is followed by optional parameters. The processing of the configuration files follows the same parsing rules as the normal command processor. The important point to remember is that either spaces or commas can be used as parameter separators, but not at the same time. If a comma is present anywhere on the line, then it becomes the separator. Otherwise, spaces are used. If any parameter is to be skipped, commas must be used as the separator. Comments can be placed throughout the configuration files by using the semicolon (;) character. When lines are processed, the parser will ignore semicolons and anything that follows them. 7.1 MAIN CONFIGURATION (DAT) FILE Upon startup, the RTUMON3 (or RTULITE3) program will automatically look for and process the main configuration file. The default name for the main configuration file is "RTU.DAT". However, another name can (and should) be used by specifying /F=xxxxx on the DOS command line that starts execution of the main program. For example, to start the SCADAWARE program with a configuration file called WC458A.DAT the following line should be used: RTUMON3 /F=wc458a.dat If no extension is specified in the file name when using the /F option, the extension ".DAT" is assumed. The main configuration file is used to specify the following: 1. Number of variables that can be defined for each task. 2. Number of communications links allowed. 3 First-In-First-Out buffering of UART allowed. 4. Types of RTU and I/O driver tasks. 5. Number of call out groups allowed. 6. Library buffer size and maximum number of entries. 7. Agenda buffer size and maximum number of entries. 8. Which overlay units to load and lock in memory (SCADAWARE Lite Only). 9. Default Communications media and baud rates. 10. Number of logical RTUs on the system. 11. Channel assignment for each RTU. This information is necessary at load time because the system must set aside memory for all of these items. This memory allocation is a one-time operation and on-the-fly reconfiguration cannot be done. So, any changes to the main configuration file requires that the system be restarted so that the file can be processed again with the new information. 7.2 I/O CONFIGURATION FILE All RTU SCADA systems (not Host systems) require some means of getting switch status and analog value data from the actual field devices into the computer for processing by the SCADA program. The RTUMON3 (and RTULITE3) program supports different types of I/O hardware which are used as the interface between the SCADAWARE® System Design Manual 33 Dec 2001 - Preliminary program and the physical I/O devices. The supported hardware includes the "Metrabus" family of interface boards manufactured by Metrabyte Corporation, simple relay type input and output cards that are installed directly into the PC I/O bus, and other generic PC based I/O cards. To inform the program of the type of I/O boards that are being used, a TASK statement must be used in the main configuration (DAT) file to define a driver task and the type of I/O boards it supports. Although the driver TASK statement will automatically get processed during startup, it will only tell the system which type of I/O is being used. The actual configuration of the I/O, such as the number of boards and their addresses, is contained in a separate I/O configuration file. The I/O configuration file for each driver task will automatically get processed whenever the task is started. The purpose of the I/O configuration file is to inform the program of the type of I/O boards that are being used, how many there are, and their addresses. The specific details regarding the information contained in an I/O configuration file can be found in the separate documentation written for each type of I/O subsystem. 7.3 MSG STATEMENT The MSG statement can be used in the main configuration file to display text messages during the processing of the file. The remainder of the line after the keyword MSG is displayed at the local console. This can be used to tell the user what is going on to assist in troubleshooting during the processing of the configuration file. MSG Defining 12 RTU Configurations 7.4 VARIABLES STATEMENT During program execution each task can define variables which can not be accessed by other tasks. Variables are useful for such things as temporary calculations or prompting the operator for input and receiving numeric values. To keep the amount of storage space allocated for variables to a minimum, the default number of variables allowed for each task is 0. The VARIABLES statement (can be abbreviated to VAR) must be used in the main configuration file to specify the number of variables that can be defined for a task. Each VARIABLES line in the configuration file is associated with the most previously defined task. For example, to allocate memory for up to 4 variables for task 1, use the statement VAR 4 after the TASK statement defining task 1 but before the TASK statement for task 2. To set the number of variables for task 0, use the VARIABLES statement before any TASK statement. If the number of variables specified is not in the range 0 - 512, the number of variables available for that task will be set to 12. Once the program is started, variables can be defined for a task by using either the LOCAL or PUBLIC commands. Once defined, public variables can be used by different command files. However, local variables can only be accessed by the files that declare them or by subsequent files called with the GOSUB command. Upon exit from a particular command file, all local variables defined within that file are automatically deleted. However, all public variables will remain defined. The only way to get rid of publicly defined variables is to explicitly delete them using the RELEASE command. VARIABLES 10 ; Need variables for Choke Control SCADAWARE® System Design Manual 34 Dec 2001 - Preliminary rtu config slide SCADAWARE® System Design Manual 35 Dec 2001 - Preliminary 7.5 LINKS STATEMENT A link refers to the relationship between a RTU and a specific phone number (or radio call sign). When an attempt to communicate with another system is made, a link is activated which knows what number to call and what task will handle the communications. By default, a system can have up to 4 links. The keyword LINKS followed by a number can be used in the main configuration file to change the maximum number of communication links available. LINKS 12 ; One for each RTU plus 2 pager channels 7.6 GROUPS STATEMENT Call out groups are used to specify a number of communication links that will be activated together. For example, when a particular channel goes into alarm it might be desirable to have several links activated. This can easily be done by creating a group of links to activate and assigning that group to the channel. The default number of groups available is 4. The keyword GROUPS followed by a number can be used in the main configuration file to change the maximum number of call out groups available. GROUPS 6 ; Six different alarm callout combinations 7.7 LIBRARY STATEMENT During program startup memory is allocated for a procedure library. The procedure library is actually just a buffer in memory which gets loaded during run-time with groups of commands called procedures. These procedures are equivalent to command files except that the need to use DOS for command file processing is eliminated. By default, the size of the SCADAWARE library buffer is 32K and the maximum number of procedures that can be loaded in the library is 128 (SCADAWARE Lite defaults to 8K buffer with 64 entries). The LIBRARY statement can be used in the main configuration file to adjust the size of the library buffer and the maximum number of entries allowed. The format of the statement is LIBRARY buffer_k_size max_entries where the buffer size is specified in Kilobytes. The buffer size can range from 2K and 64K. If a number outside of this range is specified the limiting value is used. The maximum number of entries allowed can not be set below 32. Example: LIBRARY 32 128 ; 32K buffer with 128 entries This statement will cause a 32K library buffer to be allocated when the program is started and allow up to 128 procedures to be loaded in the library. 7.8 AGENDA STATEMENT An agenda system is provided by the main program to allow processing of commands at specific times of day. These commands are loaded during run-time into an agenda buffer from where they are processed at the specified times. The memory for the agenda buffer is allocated during program startup. By default, the size of the agenda buffer is 4K and the number of commands that can be listed in the agenda system is 100. (SCADAWARE Lite defaults to 1K buffer and 32 commands). The AGENDA statement can be used in the main configuration file to adjust the size of the agenda buffer and the maximum number of commands allowed. The format of the statement is SCADAWARE® System Design Manual 36 Dec 2001 - Preliminary AGENDA buffer_K_size max_entries where the buffer size is specified in Kilobytes. The buffer size can range from 1K to 64K. If a number outside of this range is specified the limiting value is used. The maximum number of entries allowed can not be set below 32. Example: AGENDA 16 200 This statement will cause a 16K agenda buffer to be allocated when the program is started and allow up to 200 commands to be listed in the agenda. 7.9 LOAD STATEMENT The LOAD statement is used by RTULITE3, but not by RTUMON3. The purpose of this statement is to permanently load parts of the program's executable code from the overlay and lock them in memory. Without doing this, certain program functions could only be processed by task 0. Although this usually presents no problem, it is sometimes desirable to have these commands processed by other tasks. The affected functions are: DISPLAY Preprogrammed Data Displays PROGRAM Line-by-Line serial port configuration FORM Screen oriented display form REPORT Automatic printed report generation SMWATCH Smart Watch PC Clock read/write For example, the user may wish to use the PROGRAM command to program channels from a remote location. To do that, the PROGRAM command must be processed by a communications task such as task 1. The statement LOAD PROGRAM must be used in the main configuration file to make the PROGRAM command available for use by all tasks, and not only to task 0. The keywords DISPLAY, FORM, REPORT, and SMWATCH can also be used with the LOAD statement to allow the corresponding commands to be processed by any task. When the LOAD statement is not used the program requires a smaller amount of memory to run. Each additional keyword used with the LOAD statement increases the amount of memory the program requires. Therefore, the LOAD statement should be used only when one of these commands must be used by a task other than task 0. Several keywords can be listed in a single LOAD statement or several LOAD statements can be used to specify different keywords. LOAD DISPLAY REPORT ; two options on one line 7.10 COMM STATEMENT Each communications port to be used by the program must be specified in the main configuration file using a COMM line. This allows the system to allocate memory and hook into the interrupt system for these ports. All modifications made to the normal computer system setup are restored to their original settings when the program terminates. The COMM line takes a number of parameters: 1. PORT NUMBER: This is the comm port number, usually 1 or 2 to indicate the system ports COM1 and COM2. The program will support COM3 and COM4 as well, although a high speed computer is recommended if this many ports will be active at the same time. 2. BAUD RATE: This is the default communications rate for this port, typically 1200 for modems and 9600 for direct connections. This can be overridden later with the SET BAUD command. SCADAWARE® System Design Manual 37 Dec 2001 - Preliminary 3. COMM MEDIA: This specifies the media that will be connected to the port. Possible values are PHONE, RADIO, DIRECT, MULTIDROP, and Keyboard. 4. PARITY: The parity setting of the port must be NONE, EVEN, ODD, MARK, or SPACE. The first letter of the parity word is used (N,E,O,M,S). This setting must match that of the computer to which this comm port will connect. 5. DATA BITS: The number of bits in the data word used in communications is set here. Default value is 8. 6. STOP BITS: The number of stop bits (bits after the actual data transmission) is set here. Default value is 2. 7. INPUT BUFFER SIZE: The communications driver in the SCADA program is interrupt driven. This requires that buffer space be set up for both input and output. This parameter determines how many bytes to set up for the input buffer. Default value is 1100, allowing several lines to be input and waiting for processing by the RTU task. 8. OUTPUT BUFFER SIZE: Similar to the input buffer, this buffer holds characters sent from an RTU task and awaiting transmission. Default value is 4096, although values as small as 400 will work in most applications. 9. PC INTERRUPT LEVEL: Comm ports 1 and 2 have pre-specified PC interrupt levels of 4 and 3. However, ports 3 and 4 are non-standard and normally use another interrupt level, typically number 7. In the case of ports other than 1 and 2, the interrupt level must be specified here. 10. PORT BASE ADDRESS: Comm ports 1 and 2 have pre-specified PC port addresses of $3F8 and $2F8. Other comm ports must have different addresses, and the default for port 3 is $3E8 and port 4 is $2E8. If other than these defaults are used, then the port address must be specified here. The following lines are examples of how comm ports 1 and 3 can be setup: COMM 1 1200 Radio N 8 2 200 400 COMM 3 1200 Phone N 8 2 200 400 7 $3E8 ; Special Port and Interrupt 7.11 FIFO STATEMENT High performance serial port chips, called buffered UARTS, can perform first-in-first-out (FIFO) buffering of serial data. This is a very advanced process which required exact coordination between the UART device and SCADAWARE's interrupt driven serial drivers. The default setting is to not use FIFO buffering as it is not needed and works only on certain serial chips. However, the user can turn on FIFO buffering by entering FIFO ON after the COM line which defines each serial port. FIFO ON ; enable uart buffering if available. 7.12 TASK STATEMENT There are three tasks which are automatically defined for each system during startup. These tasks are the LOCAL task, the SCAN task, and the SYSTEM task. All other tasks must be defined in the main configuration (.DAT) file using a TASK statement. The format of the TASK statement is: TASK TaskType TaskName [DriverType] [ControlFileName] There are two keywords that can be used to specify the TaskType. They are: 1. RTU - Task type which processes TSP or other protocol commands SCADAWARE® System Design Manual 38 Dec 2001 - Preliminary 2. DRIVER - Hardware interface for physical I/O If the keyword RTU is specified as the task type, only the TaskName parameter can be specified. There are no other options for an RTU task. The DriverType and ControlFileName parameters have no effect if specified for an RTU type task. If the keyword DRIVER is specified as the task type, the DriverType parameter must be specified to inform the program of which type of I/O is to be used. The available keywords for specifying a driver type are: METRABUS MetraByte Bus I/O Subsystem RELAY Simple PC I/O Port for Status I/O T100 Test Type 100 Voice RTU GENERIC Metrabyte and many other DAS08 type I/O CTM5 Metrabyte 5 Point Counter Input Card. DAC02 Metrabyte 2 Point Analog Output Card When defining a driver task, an additional parameter can be used to specify a particular control file. If the ControlFileName parameter is not specified, the default file names that will be used for each of the drivers listed above are: RTU.MB Metrabus RTU.RLY Relays RTU.LB Type 100 RTU.GIO Generic I/O RTU.CTM Counter Inputs RTU.D02 Analog Outputs Normally a specific file name related to the location is used in place of the above defaults. If a control file name is specified, but it does not contain a file extension, the extensions used for the default file names shown above will be assumed dependent on the type of I/O driver specified. Examples: TASK, RTU, Com1 Phone TASK, DRIVER, I/O Driver, METRABUS, WC458.MB TASK, DRIVER, I/O Driver, RELAY, GA343A 7.13 RTU STATEMENT Each RTU must be setup individually with an RTU line and corresponding channel assignment lines in the main configuration file. The RTU statement tells the system to start a new RTU using the information provided by the statement parameters. The parameters are: 1 RTU ID: This is a short (up to 8 characters) identification code that will be used to reference the RTU. The name must be a valid DOS file name, meaning it can contain no spaces or special characters. Typical names are VR167, GA343A, etc. This name must be unique in the entire network of computers that will access the data from this RTU. 2. RTU NAME: This is a longer, full name that is used on RTU reports and displays. 3. RTU DEFAULT LINK: This is the default comm link that the program will use to reach this RTU (if it is a remote). 4. REMOTE FLAG: If the keyword REMOTE is at the end of the line, the system will mark this RTU as remote to this computer. This means that logical points associated with this RTU are assumed to be connected to another computer. The data for this logical RTU is expected to come in over some sort of SCADAWARE® System Design Manual 39 Dec 2001 - Preliminary communications rather than through hardware attached directly to this computer. Local points are updated constantly (via the Driver task), while remote points only get updated when a comm link is established. Sometimes it is convenient to treat a remote point as local and vice versa. In these cases, individual points can be set to remote or local with the CHANGE command at any time the system is running. 7.14 CHANNEL ASSIGNMENTS AND LOG LIST SIZE The quantity of each channel type must be defined for each RTU (except RTU 0) in the main configuration file. RTU 0, which is the system level, is like a large RTU that contains all the points defined for all other RTUs. In other words, the other RTUs are thought of as subsets that make up RTU 0. Consider, for example, a system that contains 2 RTUs. If 10 status points are defined for one RTU and 20 status points are defined for the other RTU, RTU 0 would automatically contain all 30 status points. It is good practice to install spare points when initially setting up a system. This makes changes easier because only channel reconfiguration is required to add points in the future. For example, a system with 16 installed analog points may only use 5 points during the initial installation. In this case, it would be reasonable to set up a total of 8 analogs so that 3 spares are readily available without having to edit the DAT file to add one or more new analog points. The memory allocated for the memory log list can also be specified in this section. Each RTU has a separate pool of memory buffers to hold alarm and data logs. This memory list is normally eventually written out to disk and will not affect the total number of logs that can be stored. The write to disk time is adjustable, but is generally in the range of 10 to 60 seconds. This memory list size will affect how many concurrent unwritten logs a single RTU can have. If the list length is exceeded before it is written to disk, then subsequent logs will be discarded until there is room in the buffer. The default list length is 16, which is more than adequate for most systems. The list size can range from 0 to 512. If numbers outside this range is specified, the limiting value will be used. This option is available for special RTUs that will have many simultaneous alarms that must be logged at the same instant. Channel quantities and log list size for each RTU are defined with the following keywords: STATUS - Status inputs AIN - Analog Inputs PID - Analog Outputs OUTPUT - Status Outputs COUNTER - Counter Inputs TOTAL - Totalizer Channels TIMER - Timer Channels AGA - AGA3 Meters FUNCTION - Rate, Difference, Average, or Special Procedure Channels VALUE - Simple Real Value Channels LOG - Size of Alarm and Data Log List As each RTU is defined, the channel type keywords are used followed by a number which indicates how many points of that type will belong to that RTU. Each RTU, except RTU 0, must have an entry for each channel type that the RTU will access. In the case of RTU 0, the number will be calculated automatically after the total channel count has been determined after the last RTU is completely defined. A typical setup for a single RTU might be: STATUS 8 ; 8 status points Output 8 Timer 8 AIN 15 ; 15 analog input points Counter 3 SCADAWARE® System Design Manual 40 Dec 2001 - Preliminary AGA3 2 Value 12 Total 2 PID 2 ; used to drive analog outputs As the channel keywords are processed, they apply to the most recently defined RTU. As additional RTUs are defined (see RTU statement), subsequent channel lines will apply to those RTUs. In this way, each RTU can be set up individually. 7.15 NAME STATEMENT This is very similar to the RTU statement above but relates only to the system level RTU called RTU 0. It is used in the main configuration file to complete the definition of the system RTU (number 0) which is automatically started when the program begins execution. The parameters are the same as the RTU statement. The RTU name becomes the system name for the entire computer. No actual points are needed for this RTU as it will inherit the sum of all points defined for all other RTUs. So, use the NAME statement to complete RTU 0's definition before moving on to the definition of any other logical RTU. 7.16 TAP STATEMENT TEST SCADA PROTOCOL (TSP) provides for passive monitoring of a communications line to update "listeners" without addressing messages specifically to them. This "wire tap" feature requires system resources which must be allocated during startup. The TAP statement tells the system how many logical RTU names will be monitored by all tasks which are on multi-drop communications lines. The list of names does not take up much memory. However, the processing time required for the TAP process is non-trivial, and the function is deleted from the system code if the TAP statement is not used in the DAT file. TAP 16 ; provide monitoring for 16 rtus Refer to section 21 for more information on Mulit-Drop communications and TAPs. 7.17 EXAMPLE OF MAIN CONFIGURATION (DAT) FILE The following is a sample configuration file: ; RTU setup file for WACKER Galveston 343 A variables 12 ; Applys to RTU 0 only links 8 ; Total links in the entire system groups 5 ; Five separate alarm callout groups msg Setting Up com ports COM 1 1200 radio N 8 2 200 400 com 3 2400 phone N 8 1 200 400 7 $3e8 ; Special port msg Task definition task, rtu, Com1 Phone ; task 1 task, rtu, Com2 Radio ; task 2 task, rtu, Utility Task ; task 3 task, driver, I/O Driver, generic, ga343.gio ; task 4 msg Finishing RTU 0 name, GA343A, WACKER OIL GA343 RTU SCADAWARE® System Design Manual 41 Dec 2001 - Preliminary msg Starting RTU # 1 rtu, GA343A, WACKER OIL GA343A,1 ; start a local RTU status 8 output 4 ain 16 count 4 total 4 timer 4 aga 2 func 5 value 10 log 32 ; allow for lots of simultaneous logs msg Starting RTU # 2 rtu, GA351B, HARDY OIL GA-351B,1,r ; start a remote RTU status 8 output 4 ain 8 count 2 SCADAWARE® System Design Manual 42 Dec 2001 - Preliminary total 1 timer 4 aga 1 value 8 ; ----------- End of sample DAT file ------------------ SCADAWARE® System Design Manual 43 Dec 2001 - Preliminary 8 TSP COMMAND FILES 8.1 TSP COMMAND FILES Each RTU type task processes commands that can come from a variety of sources. The most basic source is direct keyboard entry by an operator. However, tasks can also process commands which are stored in text files. These files, known as "command files", contain sequences of commands that perform specific functions. The commands processed from within a command file are processed just as if they were entered manually from the keyboard. A list of all available commands can be found in the TEST SCADA PROTOCOL COMMAND REFERENCE. Once a task begins processing a command file, it can not accept commands from any other source until file processing is complete. Command files can be prepared with any text editor or word processor that generates simple ASCII text files. Editors that generate special word processing codes can not be used because the special codes will confuse the program. The SCADA program itself contains a simple text editor that can be used by issuing the EDIT command once the program is started. Command files can have any name and file type, although a specific file type is expected for certain situations, such as RTU task startups and communication events. Other command files can have any valid DOS filename because they will be processed only on command. For example, each task starts execution by looking for a file called STARTx.RTU, where the x is replaced with the task's number. When the local task starts up, it looks for START0.RTU. Task 1 looks for START1.RTU, and so on for all RTU type tasks. Similarly, the communications events look for command files called LINKx.RTU, CONNECTx.RTU, BYEx.RTU, and COMFAILx.RTU for their respective functions. If the files exist, they are processed. If they do not, then nothing is processed as an alternative. The contents of these files depends greatly on the particular installation. The general functions are the same for most applications, but the exact commands and their parameters cannot be easily duplicated for each installation because of differences in hardware and communications channel requirements. Some of the standard command files used on most systems are explained later in this manual beginning with section 8.5. 8.2 COMMAND PROCEDURE LIBRARY It is possible (and desirable) to combine several command files into a single file and define each group of commands using the line PROCedure procname. This procedure file can then be loaded into a buffer in memory which will act as a library of command files. This eliminates the need to use DOS for most command file processing because the text of the file is already in memory. It also simplifies maintenance because many files are combined into one library file and there are fewer files per RTU. When the program processes commands the library will be searched first before looking on disk for command files. This avoids disk accesses for common procedures. The search sequence is to check the library, then the disk for a file with an .RTU extension. However, If the READ or GOSUB commands reference a file with a file type specified, then the library search is skipped. This is illustrated by the following commands. READ START1 ; check library and if not found then disk READ START1.RTU ; go directly to the disk bypassing library This is important because any existing operations that specify a file type in the READ command line will have to be modified in order to benefit from the library function. Also, files that are normally processed from disk (like setup and Link files) will be accessed faster if their file types are included on the command lines that read them. SCADAWARE® System Design Manual 44 Dec 2001 - Preliminary The LIBRARY command is used to load files into the procedure library in memory. By default, SCADAWARE sets up a library buffer of 32K with room for 128 procedures. SCADAWARE Lite defaults to 8K and 64 procedures. The LIBRARY command can be used in the main configuration (DAT) file to adjust the size of the library buffer and the maximum number of entries allowed. The format of the DAT file setup command is LIBRARY buffer_k_size max_entries where the buffer size is specified in Kilobytes. The buffer size can range from 2K and 64K. If a number outside of this range is specified, the limiting value is used. The maximum number of entries allowed can not be set below 32. For example, the following line could be used in the main configuration file to change the size of the library buffer and the number of entries allowed: LIBRARY 20 120 ; set up 20K buffer and allow 120 procedure entries An example of a small library file is as follows: procedure start1 ; Startup serial port task number 1 set port 2 ; override default selection of port 1 set media phone set wait 10 ; time to wait for an ACK from RTU set trys 4 ; number of callout attempts set priority 3 ; 3 ticks for this busy task force local echo Task 1 started at $T $D proc bye1 SET ECHO OFF hayes S0=1 Q1 E0 proc daily ; execute this once per day sele wc640 calc v4 = v5 calc q1:q3 = 0 ; end of library When this file is loaded with the LIBRARY LOAD command, it will make the procedures START1, BYE1, and DAILY available quickly and without DOS accesses. Note that either the keyword PROCEDURE or PROC can be used to indicate the beginning of a new file in the library. If a new procedure with the same name as an existing procedure is added to a library via either the LIBRARY LOAD or LIBRARY MERGE command, then the new one replaces the older one. The old one is still there, it is just de-activated. It will appear in the DUMP of the library with the first letter of the procedure name replaced with a question mark (?). 8.3 COMMAND FILE PARAMETER PASSING Command files and library procedures are read with parameters passed in the command line. This is similar to the parameter passing in DOS batch files. The intent is to allow for similar operations that occur in slightly different ways to be processed by a common file. This is an important concept that can greatly simplify command file preparation and enhance the capability of the system. If you are new to programming you may have to read this section more than once to let it all soak in. Parameters are any text items on the command line that follow the file name in the READ or GOSUB SCADAWARE® System Design Manual 45 Dec 2001 - Preliminary command line. Each parameter is referenced by a number, with parameter number 1 being the first item after the file name. The file name itself can be referenced as parameter 0, although this is rarely needed in actual practice. The parameters are referenced within the command file as special $ codes, similar to the special codes in the ECHO command. For example, the second parameter on the command line is referenced as $2 within the file. What this means is that a standard command file can be written that uses "place holders" rather than exact text that is needed to perform a certain function. These place holders, called the prototype parameters, are always indicated with a dollar sign code from $0 through $9. The file is written with the prototypes in place of the values that will be substituted at runtime. The runtime parameters will hold the actual text that is needed to execute the desired function. This may sound confusing but it really is not difficult to understand, especially after a few examples. Think of a command file that uses parameters as a paper form with a few blanks that need to be filled in. The concept of runtime parameter substitution is to build a command file that acts much like the blank form. Instead of using "blanks" to mark spaces that will later be filled in, the command file uses the prototype parameters marked with the $ codes. The file contains most of what is needed to perform the final act with only the items that will change being left "blank". Lets create a form that will let us specify a name, age, and occupation for different people. Most of the form is the same for each person, with a few changes needed to indicate the different data. Name: ________________ Age: ________________ Job: _________________ This is easy enough to grasp, right? If you were filling in the form, you would need three pieces of information (name, age, job). A command file is very similar in that some information is constant while other parts are variable. A pseudo command file might look like this: Name: $1 Age: $2 Job: $3 Note now the $ codes take the place of the blanks in the earlier example. Now the trick will be to get the needed information into the right place. The way we do this is to "pass" the parameters to the form (the command file) in the proper order. The order of the parameters is extremely important and should be standardized in all your applications. If our form was a file named "INFO" then we could "run" the form with the line: READ INFO Arthur 26 Engineer Here, the parameters are expected to be in the order of Name, Age, and Job. In reality, SCADA programs aren't forms but are sequences of instructions that will be executed at runtime. We all know that Arthur isn't 26 either, but this is just an example. Anyway, if we could run this fictional form with the above command line it would look like this at runtime: Name: Arthur Age: 26 Job: Engineer Note how the prototype parameters $1, $2, and $3 were replaced by the runtime values of Arthur, 26, and Engineer. If you can follow this clearly, then you are ready to look at a real RTU command file. If not, then make another pass through this section until it makes you raise your finger and go "A-ha! Now I got it!" Lets look at a more realistic SCADA file application. The line: SCADAWARE® System Design Manual 46 Dec 2001 - Preliminary READ TESTFILE WC45 O1 ON is parsed as follows: PARAMVALUE 0 TESTFILE 1 WC456 2 O1 3 ON A command file that is designed to call an RTU and set an output off or on might look like this: ; Param 1 is RTU, param 2 is Output, Param 3 is off/on condition sele $1 ; Rtu name dial wait 20 conn set online on msg RTU $1 is online block calc $2 = $3 ; Calc channel to a value msg Output $2 is now $3 hangup As each line is read from the file, the file processor substitutes each $ parameter with the corresponding entry on the line. So, the translated file would look like: sele WC456 dial wait 20 conn set online on msg RTU WC456 is online block calc O1 = ON msg Output O1 is now ON hangup Notice how each $ entry was replaced automatically by the command processor so that the file appears to be prepared especially for this particular operation. The same file could be used for any output at any RTU, in either OFF or ON mode by entering the proper command line. Similar files could be used for pulsing timers, scanning Hi/Lo set points, etc. Now keep in mind that it is possible to write a complete, separate command file for every possible action that will be required of the SCADA system. But isn't it easier to design things so that a fewer number of "generic" files can be used to do similar tasks? Normally, these command lines can be set up in a menu so that the operator need only select the desired operation. Each menu entry would be similar, with only the parameters changing in each line. Any changes needed to the common file would only have to be made once, eliminating redundant files for different RTUs. Consider this small section of a menu control file: |Perform WC-240 Facility Shutdown Read SHUTIN WC240 T5 45 |Perform WC-240 Compressor Shutdown Read SHUTIN WC240 T6 30 |Perform HI-121 Well Shutin Read SHUTIN HI121 T2 60 |Perform EI-232 Facility ESD Read SHUTIN EI232 O3 ON SCADAWARE® System Design Manual 47 Dec 2001 - Preliminary These menu entries will offer 4 separate suggestions from which an operator can select an output control action. Each selection will cause an almost identical action to occur. The same file will be processed but the command line parameters will be different. This allows a single file, SHUTIN, to be used for all four functions because the differences are specified by the menu command line. The end result is that it is much easier to write, test, and debug your command files because a fewer number of them are needed to perform a wide variety of functions. The menu resulting from the above file would look like this: Perform WC-240 Facility Shutdown Perform WC-240 Compressor Shutdown Perform HI-121 Well Shutin Perform EI-232 Facility ESD 8.4 CMD FILES ON ABNORMAL/NORMAL CONDITIONS Each channel has a mode setting option which, if set, will allow a command file to be executed each time the channel enters an abnormal state. The name of the command file must be the same as the channel tag and have the extension ".RTU". This option can be set for each channel by using the CONFIG or PROGRAM command. The prompt for this option is "Execute RTU File?". All value type channels also have the option of specifying an Input Control channel. If one is given, the command file execution will be disabled as long as the Input Control channel is in an abnormal state. Each channel can also execute the same command file each time the channel returns to normal. Two conditions must be met to enable this feature. First, the option just mentioned, which allows command file execution on abnormal, must be set. Second, the global variable RFILE must be set. To set this variable use the command SET RFILE ON. Unlike the setting for file execution on abnormal which is a separate option for each individual channel, this setting controls the file execution on return to normal for all channels on the system. When a command file gets executed the program passes a single command line parameter which depends on the state of the channel. If the channel has entered an abnormal state the value 1 is passed as a parameter to the command file. The value 0 is passed when file execution is caused by a return to normal condition. For example, a channel tagged HORN will cause the file HORN.RTU to be executed by the UTILITY task whenever its state changes. The actual line sent to the UTILITY task will look like READ HORN 1 when the channel goes abnormal and will look like READ HORN 0 when the channel returns to normal. All command files should contain simple logic statements to determine if the file is being processed as a result of a new abnormal or a clearing one. This is easily done as shown in the sample command file below: if $1 = 1 msg This is a new abnormal condition. ; place commands for abnormal condition here else msg This is an abnormal condition clearing back to normal ; place command related to return to normal here endif 8.5 STARTx.RTU - TASK STARTUP FILES When all RTU type tasks are started, they automatically process files called STARTx.RTU, where the x is replaced with the corresponding task number (0,1,2,..). When the program begins, only task 0 (the local user) is automatically started and the file START0.RTU is automatically processed. All other tasks must be started by task 0 once it is running. Therefore, START0.RTU is normally used to setup any system wide controls and SCADAWARE® System Design Manual 48 Dec 2001 - Preliminary start the other tasks. The general sequence of events in a START0 file are as follows: 1. Load procedure library 2. Load existing Data Image from disk file -or- 2a Load RTU channel files. 2b. Load agenda list. 2c Load link information. 3 Set special channels or variables to pre-set conditions 4. Start other tasks. 5. Load Agenda List 6. Setup Logger Data Saves 7. Start Image save 8. Put up main menu or user menu. The most common means of accomplishing these steps if to use a generic START0.RTU file which contains the following information: LIB LOAD $S.LIB ; load in the default library read startup ; branch to standard procedure name This simple file can be used on any system provided that 1) its main library name is the same as the overall system name, and 2) a procedure named STARTUP exists in the library to complete the initialization process. 8.6 CONNECTx.RTU - TASK CONNECT FILES When a system connects with another unit, either from making a call or receiving a call, it will look for and process a file called CONNECTx.RTU if it is found. The x in the file name is replaced with the number of the task handling the communications. These files can be used to do anything that must be done when a connection is made. For example, a CONNECT file can be used to do something as simple as count the number of times a connection has been made. 8.7 LINKx.RTU - CALLOUT CONNECTION When a task on one unit attempts to make a connection with another unit it will wait for a serial port signal called "DCD" before proceeding with file execution. On any DCD the task will execute the CONNECT file mentioned above. If the task was making a call, rather than receiving a call, it will look for and execute a file called LINKx.RTU if it is found. If both a LINK file and a CONNECT file exist, the CONNECT file will get processed first. The x in the LINKx.RTU file name is replaced with the number of the activated link. The LINK file is normally used to change the standard download process of a unit by allowing the unit that originates the call to control the sequence. On most systems a LINK file is not needed. When a unit connects with another unit and no LINK file exists a default command will be executed. The default command will vary depending on whether the link that made the call out is setup for a Host unit or a RTU. This setting is configurable for each link by using the CONFIG or PROGRAM command. If no LINK file exists and the activated link is setup for a Host unit, the command BLOCK READ DOWNLOAD will automatically get processed when the connection is made. This will cause a file called DOWNLOAD.RTU to be read at the RTU to have data sent back to the Host. A LINK file could be used at the Host to have it read a file locally and request data from the RTU rather than have the file at the RTU determine what will be sent to the Host. SCADAWARE® System Design Manual 49 Dec 2001 - Preliminary If no LINK file exists and the activated link is setup for a RTU, the command READ DOWNLOAD will automatically get processed when the connection is made. Again, this will cause a file called DOWNLOAD.RTU to be read at the RTU to have data sent to the Host. 8.8 BYEx.RTU - DISCONNECT FILES When a communications link is disconnected a file called BYEx.RTU is processed, where the x is replaced with the task number handling the communications. These files are normally used to reprogram the communications channel to make sure that the modem or whatever is properly configured for another call. All RTU type tasks, except for task 0, are monitored during periods of inactivity. No activity for a certain amount of time will cause a task to process its BYE file. The amount of time to wait for some type of activity before processing the BYE file can be controlled with the SET COMM command. If the timeout period is set to 0 for a task, its BYE file will never get processed automatically as the result of the timeout feature. Whenever one of the serial communications tasks is started a check is done to see that it is associated with a valid communications channel. If it is, the BYE file for that task is automatically processed. 8.9 COMFAILx.RTU - COMMUNICATIONS FAILURE If a call out attempt is unsuccessful the program will terminate the call, wait a while, and then attempt to call out again. If this process continues until the number of call out attempts has reached its limit the link will be set to the failed state and a file called COMFAILx.RTU will be processed. In this case the x is replaced with the number of the failed link. This file can be used to sound a horn or whatever is necessary to react to the communications failure. One possible use is to reset the callout system and then initiate a poll, which will basically restart the callout process all over again. For systems that must communicate with many RTUs, there may exist more than 9 links. When a link with a number greater than 9 fails, a file called CFAILx.RTU will be processed instead of COMFAILx.RTU. For example, if link 9 fails, a file called COMFAIL9.RTU will be processed. However, if link 10 fails, a file called CFAIL10.RTU will be processed. The reason for this difference is to allow a unique file name to exist for each link without exceeding the maximum of 8 characters for any file name. 8.10 LOGERROR.RTU - PROBLEMS IN THE LOGGING SYSTEM If an error occurs with the logging system when purging the memory buffer, the writing will be stopped to prevent further problems and the UTILITY task will process a special file called LOGERROR.RTU. When the error occurs, a message is sent to the UTIL task (or other user determined task) to process READ LOGERROR. The LOGERROR procedure can be in the library, or it can be in a separate DOS file just like any other TSP procedure. The LOG TASK command can be used to specify a task other than UTIL which will receive the message to process the LOGERROR file. A common causes of logging error is a full disk device, or a failed printer. The LOGERROR file can do whatever is necessary to change log files to another disk, alert an operator, or simply clear up some disk space by deleting files. The LOG EVERY xx command can be used within the file to restart the logging process after freeing up some disk space. To alert the operator, a channel can be setup (such as a spare status channel not associated with any real I/O) and forced into alarm from within the LOGERROR file. For more information about the logging system refer to Section 13 of this manual. 8.11 LOGONx.RTU - PASSWORD PROTECTED ACCESSES SCADAWARE® System Design Manual 50 Dec 2001 - Preliminary When passwords are enabled, this file is processed whenever a user signs on with the LOGON command. This allows for special processing such as logging messages of who is using the system (with the LOG MSG and the $U parameter). Each task has its own file, so it is possible to control the action of local accesses separately from remote accesses. The x in the file name LOGONx.RTU is replaced with the number of the task that processes the Logon command. 8.12 "UP" FILES - PROCESSED AFTER DATA TRANSFERS At the end of a download from one unit to another a SCAN command with an @ sign or the @ENDS keyword is usually processed to get a time-stamp for the time of the update. When an @ or @ENDS is processed in the resulting DATA line by the receiving unit, a command is queued up to read a file with the extension "UP". The name of the file is the same as the ID of the RTU for which the DATA command is processed. The main purpose of an "UP" file is to have the newly received data transferred from the actual channels into a database. This provides an automatic way of continuously updating a database after each data transfer. However, the "UP" file can be used to process any commands the user wishes to have processed at the end of a data transfer. SCADAWARE® System Design Manual 51 Dec 2001 - Preliminary When a command to read the "UP" file is queued up an UPFILE flag is set for that RTU. Another command to read the "UP" file will not get queued up again for that RTU until the UPFILE flag has been cleared. This will prevent more than one command from being queued up when using a direct link and doing a continuous loop within a file to download data and do a time-stamp. When the "UP" file finally gets processed, the UPFILE flag should be cleared to allow the command to be queued up again in the future. An easy way to always clear the flag when necessary is to have the command SET UPFILE OFF as the last command in the "UP" file. If no "UP" file exists for an RTU then the command to read the "UP" file is simply ignored when it is processed. The SET UPFILE command can be used without any parameters to check the status of the UPFILE flag for a RTU. ; Sample Update File for remote RTU. Executes after download is complete db sele WELLPRES ; select the well pressure database db locate $T $D ; position to current time and date record db update ; let Dbase engine retrieve realtime values db close set Upfile OFF ; clear flag so that subsequent Updates will occur SCADAWARE® System Design Manual 52 Dec 2001 - Preliminary 9 PHYSICAL & VIRTUAL CHANNEL PROGRAMMING 9.1 CHANNEL DESIGNATIONS TEST's SCADA system operates on the concept of data "channels" to handle most of the information within the system. Unlike the registers in simple RTU or PLC systems, each channel is much more than a simple binary or numeric value. It is a complete data point within the system consisting of a value integrated with name, tag, setpoints, and other technical features. There are several different types of channels to take care of different types of data. All channel types have some basic things in common, and they also have special features that make them different from the other types. Channels may refer to an actual "physical" data point or to a "virtual" calculated data point like a timer or AGA3 gas meter. This section will provide an in-depth look at all of the channel types and how they are programmed and used within the SCADA system. The most basic feature of all channels is a way to uniquely reference it within the overall system. There are actually several ways to identify each channel, and the simplest is by a channel ID reference. All channel ID references in the system begin with a single letter indicating the type of channel. The letter is followed by a number indicating the exact channel position in a list for each RTU. For example, S16 references Status channel 16 for a particular RTU. Channels are numbered from 1 up to the maximum specified when the system was initialized. The type of channel is specified by the letter as shown in the table below. CODE CHANNEL TYPE EXISTENCE A Analog Input channel Physical C Counter input channel Physical F Function (rate) channel Virtual M AGA3 Meter Channel Virtual O Output control point Physical P PID Calculation/Analog Out Physical & Virtual S Status Input point Physical T Timer channel Virtual Q Totalizer Channel Virtual V Value Channel Virtual Note: The PID channel is detailed in a separate section of this document. Some of the channels represent actual Physical inputs, while others are Virtual channels that exist only within the computer program. The physical channels represent actual inputs and outputs that are connected to the field devices. The virtuals represent calculated values, timers, and other "intangible" channel types. The SCADA program groups points of different types into a collection called a "logical" RTU. Each RTU can be treated as a unit, and all channel IDs must be unique within that RTU. So, there can only be one channel T5 in each RTU, but different RTUs can each have their own channel known as T5. A simple channel ID such as T5 is called an ambiguous reference because it could possibly refer to more than one channel in the overall system (but only one channel in a single RTU). The SCADA program always maintains a current RTU that is assumed to be the default location of any channel references. Any IDs that do not specify a particular RTU will be assumed to exist "internally" within the currently selected RTU. Channels that are outside the scope of the current RTU's range are referred to as "external". For example, if a meter in RTU 3 needs to use channel information from RTU 1, then this is an external reference from RTU 3 to RTU 1. To reference an external channel a standard "dot" notation is used. The dot notation consists of two parts separated by a period (or "dot"). The first part is the RTU name and the second part is the channel identifier. For example, VR167A.S3 references Status channel 3 at RTU VR167A. If no dot notation is used, then the current RTU is assumed by the system. If a dot is used, then the system lets the RTU identification override the default selection of the current RTU for that particular reference only. Note that dot notation can also be used to specify the RTU name even if it is the same as the current RTU. In other words, it doesn't hurt to specify the RTU even when it is already the current one. The system often SCADAWARE® System Design Manual 53 Dec 2001 - Preliminary does this automatically to insure an unambiguous reference to a particular channel. This insures that a system with more than one RTU will not get confused and mistake one RTU's channel A12 with another RTU's A12. If only an A12 reference is used (for analog channel number 12), then it is possible the wrong logical RTU will provide or receive the information that was intended for another unit. By always providing the RTU name as well as the channel ID, any system processing a channel reference will be sure to locate the proper data point within the overall system. This is not as difficult as it sounds because it is fairly easy to get various computers "in sync" so that they are currently addressing the same logical RTU. But whenever possible the system will automatically append the RTU name for you just to make sure that no chance of a mistake occurs. So, while you may request information on channel A5, the system may respond with WC240.A5 to indicate that the point in question belonged to an RTU named WC240. Don't despair if this is not clear at this point because the concept will be covered several more times before the chapter is through. 9.2 CHANNEL RANGES Channels can be referenced one at a time or as a group (or range). A range of channels must often be specified for certain commands (like SCAN). The channel range is noted in a manner similar to the cell ranges in a spreadsheet. The starting and ending channels are written together separated by either a colon (as in Microsoft style) or double dots (as in Lotus style). For example, the notation S1:S20 represents a range of channels from S1 through S20. A1..A3 represents channels A1 through A3. The colon or double dot can be used at any time. For all channel ranges, both the starting and ending channel types must be the same. The program will normally use the channel type of the starting entry and will ignore the channel type of the ending entry. For example, specifying DISPLAY S1..A16 will be interpreted as DISPLAY S1..S16. Wherever possible, the system will check for out-of-range references and chop them to the proper size in any responses. For example, if a system with only 10 analogs was given the command SCAN A1:a16 E, the system would respond with SCAN RTUNAME.A1:A10 E to indicate that only 10 channels were available. Note that the system also appended the RTU name to the beginning of the range to form an unambiguous system level reference to the data channels. 9.3 INITIAL SYSTEM CONFIGURATION The system is configured for the number and type of channels at the time the program is first started by information contained in the configuration file, which defaults to RTU.DAT. More likely, the default name will be overridden with a file name that is the same as the desired system name such as WC311.DAT or HOST.DAT. If this is done, the /F= command line option must be used when starting the program to tell the system the actual name of the file to be used for system configuration. The DAT file tells the program how many of each type channel each logical RTU will have. All other channel configuration is done with the CONFIG or PROGRAM command. These commands require a channel number as a parameter, and will enter a prompting sequence to allow entry of channel configuration data. The types of input required depends on the type of channel being programmed. Once channels are programmed, a SAVE command is used to put the channel information into a separate DOS disk file for each logical RTU. So, each RTU ends up with a separate file containing all of the channel information necessary to describe the RTU. This file can be easily transported (by diskette) to another computer to simplify setting up other computers that will access data from the RTU. When moving a configuration file from one unit to another, there is often a few settings that will be different on the other computers. The most likely change is in the callout requirements for each channel. Normally, an RTU is set to call while a Host is not. The CHANGE command can be used to modify the alarm mode setting for a group of channels. This simplifies transferring a channel setup from a configured RTU to a matching HOST. In these cases, the alarm mode settings are the only differences in the setup. The CHANGE command can also be used in a command file to change the alarm mode settings on-the-fly if needed. SCADAWARE® System Design Manual 54 Dec 2001 - Preliminary 9.4 BASE CHANNEL CONFIGURATION The TEST SCADA system works internally with an "object oriented" data system where many data types are derivatives of another type. This object orientation is visible to the user when the layout of the various channel types is studied. The system defines a base channel type that forms the basis of all other channel types. This base type has features that are common to all of the other types, although the base type is never used by itself. All channels used by actual data points are more complex than the base type. Any additional requirements for a specific type of channel are processed at a "lower level" than at the base level, but each lower level "inherits" the characteristics of the higher type. This forms a sort of tree structure as shown below: BASE CHANNEL LEVEL 1 ³ ÚÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ ³ VALUE DIGITAL LEVEL 2 ³ ³ ÚÄÄÄÄÄÄÄÂÄÄÄÄÂÄÄÄÄÂÄÄÁÄÄÄÄÂÄÄÄÄÄÄÂÄÄÄÄ¿ ÚÄÄÄÁÄÄÄÄÄ¿ AIN COUNTER PID TIMER TOTAL FUNCT AGA3 STATUS OUTPUT LEVEL 3 Internally, the system works with the channels at all 3 levels. Externally however, the user only accesses data at levels 2 and 3. The base channel type has the following attributes that are shared by all other channel types: 1. Channel Name 2. Channel Tag. 3. Alarm Mode. 4. Alarm Delay. 5. Callout Group. 7. Time and Date of Last Abnormal (internally maintained) All channels have descriptive text messages describing the nature of the channel. Typical values are "Oil Pressure" or "Sales Gas Static Pressure". All channels also have an "alarm mode" setting that determines how the channel will react to abnormal or alarm conditions. First of all, each channel has the option of being declared as an alarm type channel or not. Each channel also has the option of being skipped or included in reports. This allows for spare and other non-essential points to be skipped during report generation. Each channel can control its ability to blow a horn (only for alarm type channels), execute an RTU file upon abnormal (this also allows execution of an RTU file when an abnormal clears if SET RFILES ON is used), generate a callout, and be entered into an alarm log on abnormal conditions. Each channel can also control its ability to generate a callout on reset and to reset its alarm condition automatically should the abnormal condition go away. These settings can be set up by either the Config command, Program command, or the Change command (for one or a range of channels). Each channel has an alarm delay setting which determines how long a channel must be in an abnormal condition before going into alarm. If a channel in an alarm condition returns to its normal state before the delay time has expired, no alarm will result. Note that this delay also affects other abnormal actions such as command file processing and abnormal logging. Channels that cause callouts must have a "callout group" assigned to them. A callout group is a list of communication links that will be activated whenever the point requires a callout. This allows for each point to cause specific callout functions that are unique to its individual situation. See the section on communications links for further information. Note that each individual channel has all of these attributes all to itself. Items like call on alarm, delays, SCADAWARE® System Design Manual 55 Dec 2001 - Preliminary and other features can be set individually on a point-by-point basis. While this may seem like a lot of setup for each RTU, it can actually be done very quickly with the Change command that can modify a range of channels. An experienced user can perform the base level setup for a typical RTU in about 30 minutes. Once the base level programming is complete, the system must be configured for the lower level details of each channel. On an actual RTU (one with field devices), all parameters for all channels must be entered. At a Host system (one without actual I/O devices), some of the lower level settings are not important because they will not be used at the Host. For example, an analog channel that must be configured for the Zero and Span of the transmitter need not be programmed at the Host. This is because the conversion from raw to engineering level units (done by the RTU's Driver Task) will usually take place only at the field located RTU. The data from the RTU to the HOST will be passed at a higher level (level 2) so that the details of the transmitter are not important at the Host. This greatly simplifies installation and operation because low level changes at the RTU are not necessary at the Host system. ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA GENERIC CHANNEL 1 Of 8 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Platform ESD Tag S1 Alarm Delay Secs 2 Alarm Type Channel? Y Blow Horn? Y Play Sound? Y Reset After ACK? Y Call on Abnormal? N Call on Reset? N Log Abnormals? N ¨ Execute RTU file? N Skip Reports? N Callout Group 1 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; The channel programming unique to each channel type will be covered in the sections below. Keep in mind that these channels also have the attributes discussed in this section because they inherit all of the capabilities of the base channel. For each parameter a number will be provided in parentheses to indicate the level at which the parameter takes affect. 9.5 STATUS INPUT AND OUTPUT POINT PROGRAMMING SCADAWARE® System Design Manual 56 Dec 2001 - Preliminary Status inputs and outputs are the easiest channel types to understand and program because they represent only off-on type conditions. All that is needed in addition to the inherited base channel parameters is the text messages for normal and abnormal states, and the normal state of the input and output. Normal Text (2) Text associated with the normal state. Abnormal Text (2) Text associated with the abnormal state. Switch Normally On (3) Normally open or closed state for the input. Currently Abnormal (3) Power state of output when logically Off (outputs only). The status channels can only be off or on and have a text message that corresponds to each condition. For example, a status input associated with a pump may have the text messages "Offline" and "Pump Running". The text for each position is completely up to the user. The normally open or normally closed position of the physical input is hidden from the user because each point can be programmed for either state as "normal." The conversion form the field switch to the logical off/on state is done at the RTU only. Once the switch is read, the driver task makes the necessary adjustment for normally open or closed so that an abnormal condition is always a 1 inside the system. Therefore, scanning data from one unit to another will always result in a value of 1 for each channel that is abnormal, regardless of the actual field switch position. This reduces problems in keeping the field and host systems in exact sync as far as field switches are concerned. Likewise, status outputs can also have a normal state of Off or On. This allows all outputs to be turned on by setting them to 1, and off by setting them to 0. The actual needs of the physical output is taken care of by the driver task. Therefore, an output that must be physically On in order to turn Off a function can be setup so that it is always turned off by setting it to 0. For example, an output that is normally energized to keep a piece of equipment operating can be programmed for its normal state to be On. To activate the "function" of the output channel we always set it to 1. The driver will recognize that this particular point uses reverse logic and will turn the physical output off when the logical output is on. Note that status channels, like any other channel, do not have to be associated with actual field devices. It is often convenient to use status channels as indicators or logic controls within the system. We can set status inputs or outputs off or on and use them as logic flow controls within programs. The off/on status can be tested with an IF statement that will determine various actions in a program. Using status channels allows these various settings to be easily transferred among units. So, keep your mind open for creative applications for status channels as you learn more about the system. ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA STATUS CHANNEL 1 Of 8 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Platform ESD Tag S1 Alarm Delay Secs 2 Alarm Type Channel? Y Blow Horn? Y Play Sound? Y Reset After ACK? Y Call on Abnormal? N Call on Reset? N SCADAWARE® System Design Manual 57 Dec 2001 - Preliminary Log Abnormals? N ¨ Execute RTU file? N Skip Reports? N Callout Group 1 Normal Text Normal Abnormal Text ALARM Switch Normally ON? N Currently Abnormal? N ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; 9.6 VALUE CHANNEL PROGRAMMING Value channels (which are at level 2) require a number of parameters in addition to those inherited from the base channel type. All parameters associated with value channels are also inherited by analog, counter, timer, totalizer, function, PID, and AGA meter channels. All Value channel parameters are at level 2. The additional parameters used by value channels are: Units Type of units this channel represents Decimal Places Display and transfer precision Input Control Chan Status input that controls this channel Lo Alarm Value Low setpoint in engineering units Hi Alarm Value High setpoint in engineering units Deadband Margin used before clearing alarms The Decimal Places parameter determines how a channel will be displayed and transferred to another unit. This parameter is separate for each channel. If the parameter is 0 or greater, than the program will format the text version of the channel to the specified number of decimals. If the setting is negative, then the program will use a single, global decimal place count established with the SET PLACES x command. Therefore, most channels can be set easily by setting the system default and leaving each channel at the system default setting. Certain channels, such as orifice plates, will display better with a higher number of decimal places. Other channels, such as AGA-3 flow rates, will display better with 0 or 1 decimal places. These channels can be individually configured as desired, while the majority of the channels can be left at the default system setting. Note that setting the decimal places will limit the default precision of the value on the current system as well as on any system that receives the value via a transmission. If only 1 decimal place is used at an RTU, then the transfer will only provide 1 decimal place as received by the HOST. Setting a higher number of places at the HOST will not result in any additional precision because the precision has been removed at the RTU prior to transmission. The Input Control Channel parameter is optional and can be used to specify a channel which will control SCADAWARE® System Design Manual 58 Dec 2001 - Preliminary this channel's ability to do certain automatic actions. This will prevent inadvertent alarming of value inputs (or any of its derivatives like analog or meter) when certain conditions prevent normal operation of the system being monitored. For example, it is undesirable to get a low oil pressure alarm from an engine that is not running. Assigning a control input that is tied to the engine run status will prevent the analog channel from operating when the engine is not. Leaving the Input Control Channel entry blank defeats this function. ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA VALUE CHANNEL 1 Of 24 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Gas Sales Plate Tag PLATE1 Alarm Delay Secs 0 Alarm Type Channel? N Blow Horn? N Play Sound? N Reset After ACK? N Call on Abnormal? N Call on Reset? N Log Abnormals? N ¨ Execute RTU file? N Skip Reports? N Callout Group 1 Current Value 2.875 Inch (Units) Decimal Places 3 Input Control Channel Lo Alm Val 0 Hi Alm Val 10 Dead Band 0 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Any type of channel can be used as an Input Control Channel. The control rule is that the input control channel must be in the normal state in order for the affected channel to operate. If the control channel is abnormal, the alarm mode functions of the channel are temporarily defeated. The Deadband parameter provides a stage to the alarm process to accommodate points in alarm that are in the process of returning to normal. The deadband is the range that the value must exceed in addition to SCADAWARE® System Design Manual 59 Dec 2001 - Preliminary the normal setpoint before it is allowed to clear. This parameter is provided to reduce nuisance alarms on channel types that hover near the alarm point. Without the deadband, the channel would continually re-alarm in response to small changes in the channel value. The deadband allows for customization of each point to determine how much of a change is required to clear an existing alarm. If a channel has a deadband of 0 then this parameter is ignored. The deadband applies to both high and low alarm conditions. Lets consider a battery voltage channel that has a low alarm setpoint of 11.5 volts. As the voltage drops past 11.5, the point will alarm as expected. If the deadband is 0, then the point will clear when the value rises back to 11.5 or higher. But, this may cause a re-alarm problem if the value stays in the vicinity of 11.5 volts. Each time it dips slightly below 11.5, a new alarm would occur, and each time it rises the alarm would clear. To prevent this, a deadband of 1 volt could be used to prevent the alarm from clearing until the voltage rose past 12.5 volts (11.5 setpoint plus the 1.0 volt deadband). 9.7 ANALOG INPUT PROGRAMMING Analog inputs are derived from value channels to produce an engineering units value related to some form of real-world signal. These signals are usually associated with pressures, temperatures, voltages, and other process values. However, any signal that can be scaled from one point to another can be connected to the analog input system. Less common examples include Ph, specific gravity, moisture content, and valve position. The only requirement is that the input be linear between two fixed values (such as 0-1000 Psi or 50-150 Degrees). Analog inputs enter the system through some form of analog to digital (A/D) converter. These hardware devices convert an electrical signal representing the field condition into a number that can be processed by the computer. The initial conversion from an electrical signal into a number is called the raw conversion. The raw analog input value is processed by the Driver Task into a signed 16 bit integer, providing an overall range of +-32K. This will accommodate A/D cards with up to 16 bit accuracy, although devices with 8 or 12 bits are more common. The hardware driver for the particular system will scale the actual input value up to a 16 bit signed integer. This 16 bit integer is the "raw" value of the channel. From this point on, the SCADA software treats all of the inputs the same regardless of their actual origin. ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA ANALOG CHANNEL 3 Of 8 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Sales Gas Pressure Offset Channel? N Tag STAT1 Value at 0% 0 Alarm Delay Secs 0 Value at 100% 1500 Alarm Type Channel? N Allow Negative? N Blow Horn? N Play Sound? N Reset After ACK? N Call on Abnormal? N Call on Reset? N Log Abnormals? N ¨ Execute RTU file? N SCADAWARE® System Design Manual 60 Dec 2001 - Preliminary Skip Reports? N Callout Group 1 Current Value 428.5 Psig (Units) Decimal Places 1 Input Control Channel Lo Alm Val 0 Hi Alm Val 100 Dead Band 0 ÕÍÍ��ÍÍÍÍÍÍÍ��ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; The program automatically handles straight linear (i.e. 0-10 volt) or offset (4-20ma) type channels. The difference is whether 0% input occurs at 0% of full scale (as in voltage readings) or at 20% of full scale (as in a 4-20ma transmitter). The program will take care of all of the calculations necessary to figure the actual input setpoints based on the user's input which is in engineering units. Each channel can also block negative numbers from being generated during the conversion process. This is desirable for pressure and other inputs that may show slightly negative numbers when idle. This is the default setting, and will cause numbers that otherwise would be less than zero to appear as zero. If negative numbers are desired, set the Allow Negative Option to TRUE during channel configuration. This setting only affects the raw signal conversion, and a negative value can still be placed in a channel with a CALC or DATA statement. Note that all of the parameters associated with analog inputs are at level 3 and only affect the raw calculation at the RTU where the conversion takes place. Offset Channel Is this a 0-x or an x-y type channel. Value at 0% Engr. value at 0% input Value at 100% Engr. value at 100% input. Allow Negative Are negative numbers allowed for this channel. As an example of an analog setup, consider a 50-150 degree temperature transmitter that is connected to an RTU with a 4-20ma signal. This device is an offset input because the low value occurs at 4ma, not 0 ma. The 0% value is 50 degrees, and the 100% value is 150 degrees. We will not want negative numbers for this channel. Another example is a battery input that ranges from 0 to 20 VDC. This may actually be a nominal 12VDC input that is scaled with resistors to produce the actual voltage needed by the analog input (perhaps 0-5VDC). The input would be programmed as Not offset, 0% of 0 VDC, 100% of 20VDC, and no negative allowed. 9.8 COUNTER INPUT PROGRAMMING Counter inputs channels are designed to accumulate events of some sort beginning at a particular moment in time. The channel can accumulate high speed pulses entering a hardware counter circuit, or it can accumulate logical state changes for any other channel type. This allows a counter channel to totalize high SCADAWARE® System Design Manual 61 Dec 2001 - Preliminary speed pulses with a counter input card, or to count slow speed pulses appearing at a status input or output channel. Regardless of the count source, the counter channel accumulates what is called an "event." The value of the channel represents the number of events that have occurred since the channel was last reset. These events may be something simple like pump strokes, or it may be more complex like turbine meter pulses. We probably don't care about how many turbine blade pulses have occurred, but we would like to know how much flow caused the blades to move. The Counter factor value is used to convert any number of events (pulses) into another form of units, such as total flow. ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA COUNTER CHANNEL 1 Of 3 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Condensate Meter Threshold Count 4310 Tag C1 Counter Factor 0.1 Alarm Delay Secs 0 Filter Ticks 0 Alarm Type Channel? N Input Chan Blow Horn? N Play Sound? N Reset After ACK? N Call on Abnormal? N Call on Reset? N Log Abnormals? N ¨ Execute RTU file? N Skip Reports? N Callout Group 1 Current Value 0 Bbls (Units) Decimal Places 1 Input Control Channel Lo Alm Val 0 Hi Alm Val 999999 Dead Band 0 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; The hardware counter input system is very flexible and can monitor very slow to very fast (8000 Hz) input signals. The flexibility of the rate depends on the hardware that is used. The signal level can be from millivolt turbine meter inputs through high level opto-isolated voltage inputs. The counting occurs in two steps. The first step accumulates the raw input pulses until a threshold is reached. At each threshold, one unit of SCADAWARE® System Design Manual 62 Dec 2001 - Preliminary measure is added to the value of the channel. For example, suppose we have a meter that provides 100 pulses per gallon. We can set up the channel to show whole gallons by entering a threshold of 100 as being equal to a value of 1. Or, we can set it up with a threshold of 10 to equal a value of 0.1. This provides a resolution of 1/10 gallon rather than one gallon as in the previous setup. More complicated setups provide for converting gallons to barrels or pounds to cubic feet. The basic concept is the same. How many ticks equal one unit? And how much is one unit? Those two values must be known before the channel can be programmed. The counts from the actual hardware counter circuit are processed on each system tick, 1/18 of a second. The count is added to a software register that is 16 bits wide, allowing 32K counts to be accommodated. The threshold value is specified for each counter channel that provides the number of whole counts in the software register that will equal one unit of measure. The units of measure are accumulated at the value level by adding one unit to the existing total each time the threshold is exceeded. Ok, lets look at another example. Consider a turbine meter that provides 5000 pulses per gallon of fluid. The fluid weighs 5.2 pounds per gallon. We want the counter to indicate total flow in pounds. We set up the threshold value as 5000, because this is the number of counts that represent one unit of measure based on the design of the meter. The conversion factor will be 5.2, so that the resulting value will be in pounds and not gallons. We count 5000 ticks to get one unit, and each unit adds 5.2 to the total. We could also set it up so that 500 ticks is one unit, and each unit is 0.52. One additional parameter called Filter Ticks is used in processing noisy, slow pulsing channels. This parameter, if non zero, sets the system to de-bounce counter inputs and add a delay between allowable inputs. This effectively reduces all counter inputs received in one burst to a single pulse, and locks out any further pulses until the specified number of system ticks has passed. For example, a system with a parameter of 18 that receives 17 random pulses when a relay closure occurs will count all 17 as a single pulse and will wait approximately 1 second (18 ticks) before permitting another pulse to be counted. This is very useful for debouncing real world inputs such as relay and switch contacts as well as noisy solenoid circuits that are monitored as pulse inputs. All counter parameters are at level 3. The special parameters for counter inputs are: Threshold Count Number of counts to = 1 unit of measure Counter Factor Engineering units conversion Filter Ticks Ticks to wait between counting pulses Input Channel Optional SCADA channel to be monitored for 0-1 transition. 9.9 FUNCTION CHANNEL PROGRAMMING The Function channel is a virtual channel that is not directly associated with any real input point. They exist only in the "mind" of the computer. The intent is to take another channel value and provide a special function to it so that another value is produced. This new value is related to the original channel in a specific way. The current functions that are available are Rate (frequency), Average, and Difference. A procedure option can also be used in addition to any of these types. 1. The Rate function will monitor an input in order to determine how much the input changes over a fixed period of time. 2. The Average function is similar except that it calculates the average value during the sample period. 3. The Difference type simply calculates the difference in the input value from one pass to the next. This is useful in detecting rate of change values for the specified input channel. 4. The Procedure Setting makes the Function act much like an automatic Timer channel that calls a TSP SCADAWARE® System Design Manual 63 Dec 2001 - Preliminary procedure once every cycle. The Procedure name is the same as the channel tag name and is processed by the Utility task whenever the time period of the channel expires. But unlike the normal Timer channel output, the Procedure function passes additional information on the command line that is sent to the Utility task for processing. The parameters are: 0 Tag Name (same as procedure name) 1 Mode number of 3 (0=reset, 1=alarm, 2=reserved) 2 RTU name 3 Current value of function channel 4 Current value of input channel 5 Tag name for input channel 6 Function factor 7 Seconds for Function update period Any channel type can be used as an input source for the function channel, although the Rate method is most likely to be used only with a counter input channel. The Rate process operates by reading the input value at the beginning and end of the sample period and then using the difference to calculate the frequency. The Average calculation occurs each second to produce an average over the sample period. So, the Rate method only uses the beginning and ending values while the average method uses the value at each second of the sample period. Some inputs occur randomly, and have no real rate associated with them. Others, like continuous flow turbine meters, have a reasonable rate that can be calculated. The frequency calculation basically examines the number of pulses per time period. The time period for each sample can be set to any number of seconds, with 0 disabling the rate calculation. The length of the sample period is selected to give a reasonable time for a typical number of pulses to occur. Very fast inputs can use each second, while somewhat random pulses may use several minutes worth of seconds to allow for variations in the rate to be smoothed out. ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA FUNCTION CHANNEL 1 Of 4 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Gas Rate Average Input Chan M1 Tag F1 Freq Factor 1 Alarm Delay Secs 0 Sample Secs 30 Alarm Type Channel? N Function ADPR? A Blow Horn? N Play Sound? N Exec File After Sample? N Reset After ACK? N Call on Abnormal? N Call on Reset? N Log Abnormals? N ¨ Execute RTU file? N Skip Reports? N Callout Group 1 SCADAWARE® System Design Manual 64 Dec 2001 - Preliminary Current Value 8.2 MMCF/Day (Units) Decimal Places 1 Input Control Channel Lo Alm Val -1 Hi Alm Val 999999 Dead Band 0 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Each Frequency channel has a factor that will be multiplied by the number of counts/second accumulated during the most recent sample period. This factor can do engineering unit conversion as required to obtain the results in any engineering units. The factor may also account for time period changes. Consider the turbine meter mentioned in the Counter programming section above. If we examine the counter over a 10 second period, the program will determine the difference in the count that occurs in 10 seconds. The count difference will be divided by the number of seconds in the period to get a value related to the number of gallons of fluid that went by during that time. If we want to get a flow rate based on Barrels per day, an additional conversion factor is needed to do the necessary juggling of the numbers. This factor will account for the fact that there are 86400 seconds in a day, and that there are 55 gallons per barrel. The factor will be calculated as follows: Gallon Secs 1 Bbl FACTOR = X ÄÄÄÄÄÄÄÄ * 86400 ÄÄÄÄÄÄ * ÄÄÄ ÄÄÄÄÄÄÄÄ = 1570.9 Sec Day 55 Gallon The factor of 1570.9 will provide the rate calculation in bbl/day, and this unit of measure can be specified for the function channel. Special parameters for function channels are: Input Chan Channel where the input comes from Freq Factor Volume and time conversion factor. Sample Seconds Sample period given in seconds Function ADPR Function Type: Average, Difference, Rate, or Procedure If a channel is set up as an average type channel the rate will be based on the average value over the sample period. Otherwise, the rate will be based on the difference in value over the sample period. 9.10 TIMER CHANNEL PROGRAMMING Timer channels are not directly associated with any physical devices but exist entirely in software. When a timer is started, it loads the time value into a software counter. This counter is decremented (or incremented) once per second for starting times over 100 seconds, and every 50ms for starting times less than 100 seconds. Timers can be operated up or down, single-shot or one-shot. Automatic control of other channels (usually physical outputs) is also easily accomplished with a separate setting for each timer channel. The special parameters used for timer channels include: SCADAWARE® System Design Manual 65 Dec 2001 - Preliminary Up Counter Does timer count up or down. Timing State On Is output on (not off) during timing period. Start Channel Channel which start timer. Output Channel Channel to be set to 1 (usually an Output) Auto Output Does output follow control input. Auto Reset Is count restarted each time. Auto Mode NYRI Auto restart mode of No, Yes, Reset, or Interval The Up Counter parameter determines whether the timer is incremented or decremented when it is timing. A timer channel that is set to count downward will stop timing if its value reaches 0. A timer that counts upward will never stop timing simply by reaching a certain value. If an upward counting timer is left timing indefinitely it will eventually exceed the counter's limits and take on an unpredictable value. The timer's maximum limit is so large that if this ever happened, there is probably an error somewhere else that caused the timer to start counting at the wrong value. During the timing period, the timer can be restarted (with CALC TIMER = ON) which will reload the time value in the high setpoint. This is useful for fail-safe applications like hurricane evacuation timers. If a timer is set up as an alarm type channel the conditions for an alarm depend on whether the timer is counting up or down. A timer that counts downward will go into alarm only when its value becomes equal to or less than the value of the low alarm setpoint. A timer that counts upward will go into alarm only when its value becomes equal to or greater than the high alarm setpoint. After going into alarm, a timer channel will continue timing in its usual manner. The Output Channel parameter can be used to manipulate any other channel during the timing period. If an output channel is specified, it will be set to 0 or 1 while a timer is counting. The state of the output channel is controlled by the Timing State parameter. SCADAWARE® System Design Manual 66 Dec 2001 - Preliminary ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA TIMER CHANNEL 1 Of 10 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Compressor SD Up Counter? N Tag T1 Timing State ON? Y Alarm Delay Secs 0 Start Channel Alarm Type Channel? N Output Channel O1 Blow Horn? N Play Sound? N Auto Output? N Reset After ACK? Y Auto Reset? Y Call on Abnormal? N Auto Mode NYRI? N Call on Reset? N Log Abnormals? N ¨ Execute RTU file? N Skip Reports? N Callout Group 1 Current Value 0 Secs (Units) Decimal Places 2 Input Control Channel Lo Alm Val 0 Hi Alm Val 99999 Dead Band 0 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; The Start Channel parameter allows another channel to control the starting of a timer rather than having to load it or use the CALC command. This option can have a timer start automatically (with its high setpoint value) when a status input or output channel is in its abnormal state, or when a value type channel is within its high and low alarm setpoints. This provides some interesting options when the output of one timer starts another timer. For example, a pulse output can be programmed by having the first timer turn on an output and trigger the second timer, which then turns the output back off when its time expires. This off-on cycling can also be accomplished with the Interval timer option explained below. When an input channel starts a downward counting timer, the timer's count begins with the value of the high alarm setpoint. If the timer counts downward and stops when it reaches 0, it will automatically start counting again if the status of its start channel is still in the proper condition. If the channel is an up counter, it starts automatic timing with the value in the low setpoint. Alarm actions will occur when the high setpoint is reached. However, unlike a down counter, an up counter will not SCADAWARE® System Design Manual 67 Dec 2001 - Preliminary automatically reset when it reaches the setpoint but will continue counting up until reset by some external means. If the auto mode of the channel is YES, then it will restart automatically when a timeout occurs. Timers set up for repeat interval will automatically cycle the output off and on. The on time will be equal to the high setpoint, and the off time is determined by the low setpoint. This function can be used to drive an output off and on according to the current values of the setpoints. These setpoints can be easily changed at runtime, simplifying manipulation of the timing periods. Extra caution should be taken when specifying a Start Input channel that is a value type channel and not set up as an alarm type channel. The user will have no way of knowing if the value of such a channel has exceeded an alarm setpoint and then returned to normal. Therefore, it will appear to the user that this channel should start the timer again automatically when it reaches 0. Unfortunately, this will not work. The channel must be reset and acknowledged before it can start the timer again. This problem can be overcome by configuring the input channel so that is will automatically reset itself when its value returns to an allowable range. The Auto Reset parameter is used to automatically set a timer's value to 0 if the optional Input Control Channel de-activates. This allows a timer to monitor a status input and only time-out if the status input remains active for a continuous period. Intermittent timing periods will not generate a time-out. If the auto reset option is not specified, the timer will time out after timing for any number of timing periods that total up to the timing period. The Auto Output option determines how the output behaves in response to the Input Control Channel during the timing period. If false, then the output will remain active even during periods when the control input is inactive (and the count is holding). If true, then the output will only be active when the timer is actually counting down. When the timer stops, the output will go to the non-timing state. When the count resumes, the output will return to the timing state. The Auto Restart option is used to control whether or not a timer channel is automatically restarted when its value reaches an alarm setpoint. Using this option will cause a downward counting timer to reset itself to its high alarm value whenever it reaches its low alarm value. The timer will automatically continue counting with a "full load.". Likewise, an upward counting timer will automatically reset itself to its low alarm value and continue timing whenever it reaches its high alarm value. The Auto Mode NYRI options have the following meanings: N No - Do not do automatic cycling Y Yes - Do automatic cycling to restart on timeout R Recycle - Same as Yes (for compatibility with older versions) I Interval Timing with high and low setpoint values as on and off times. 9.11 AGA3 METER PROGRAMMING AND ERROR CODES The AGA3 meters are the most complicated type of channel in the system. This is due to the large number of parameters necessary to completely do the AGA3 calculation as specified in the AGA3 publication. Many of the parameters can be left at their default values which represent typical oil field gas production values. Only the values that are known should be changed. Of course, as more parameters are provided the validity of the calculation will improve. The most important parameters are the physical installation specifications including pipe and plate sizes, tap location, and plate material. Also, the gas specific gravity must be fairly accurate in order to get reasonably accurate results. Other values, like percent CO2, are less important and can be ignored if desired. The parameters are obtained at calculation time from two different sources. The parameters that rarely change (like the pipe diameter) are contained in the setup data for the particular channel. Other values that do change (like the plate size) are obtained from a designated input channel. This allows for on-the-fly modification of the AGA-3 parameters through changes to the associated analog, value, or other input channel. SCADAWARE® System Design Manual 68 Dec 2001 - Preliminary The three basic real-time inputs that are used in the meter calculation are the static pressure, differential pressure, and temperature. These inputs may be assigned to any channel type, although analog and value channels are the most common. If a constant must be used (as when there is no actual temperature input), then a value channel must be set up that contains the desired constant. ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA AGA3 CHANNEL 1 Of 2 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Sales Gas Meter 1 Plate Channel PLATE1 Tag M1 Diff Channel DIFF1 Alarm Delay Secs 0 Static Channel STAT1 Alarm Type Channel? N Is Press PSIG? Y Blow Horn? N Play Sound? N Temp Channel TEMP1 Reset After ACK? N Temp in Deg-F? Y Call on Abnormal? N S.G. Channel SG Call on Reset? N MCO2 Channel MCO2 Log Abnormals? N ¨ MN2 Channel MN2 Execute RTU file? Y FPV Channel Skip Reports? N Conv Factor 41.7 Callout Group 1 Height in Feet 70 Current Value 8.22 MMCF/Day (Units) Latitude 30 Decimal Places 2 Tap Upstream? Y Pipe Tap? N Input Control Channel Stainless? Y Lo Alm Val -1 Hi Alm Val 9999999 Temp Base 60 Dead Band 0 Pres Base 14.69999 Pipe Diameter 7.9 Recalc Freq 995 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Two other channel- related inputs are the plate size and the specific gravity. Valid channels must be specified for these inputs. If invalid inputs are specified, the software will not proceed with the AGA3 calculation and will instead generate an AGA3 error value. Two other optional channel-related inputs are the mole percent N2, and the percent CO2. The channel SCADAWARE® System Design Manual 69 Dec 2001 - Preliminary designations for these values can be skipped if desired by leaving the field blank. If the channel for these two inputs is invalid, a value of 0 is assumed when the AGA3 calculation is made. The final channel related input is the optional FPV factor which is the supercompressibility factor used in AGA3 calculations. Normally, this parameter is not needed and the program will automatically calculate the FPV factor from data provided by the other parameters (using NX-19 rules). However, if a valid channel is specified for this input, the program will skip the FPV calculation and simply use the value of the specified channel as the FPV factor. This is necessary for special gases that do not conform to NX-19 guidelines. For these gases, the Fpv will have to be obtained from some other source and supplied to the AGA-3 calculation via a special channel. The special parameters for the AGA3 meters are: Factor Converts calculation from MCF/Hr. to desired time and engr. units. Typical value is 41.667 for (1000 / 24) MMCF/Day. Channels Input channels for Temp, DP, PSIA, SG, Plate Size, %CO2, %N2, and FPV. Pipe Diam Inside Diameter of pipe in inches. Tap Location Up or down stream taps. Tap Type Pipe tap or Flange Plate Matrl Stainless or Monel Plate material Elevation Height above sea level in feet. Latitude Degrees latitude of meter (getting picky!) Temp Base Temp at which gas value is equated (60-F). Press Base Pressure at which gas value is equated (14.7) Calc Freq How often complete calculation is performed. Temp in F True if temperature input is Deg-F, not Deg-C Press in Psig True if static input is in PSIG, not PSIA The AGA3 meters can be calculated in a number of ways to accommodate various operating conditions. Adjustments are provided for remote and local calculation, and for the frequency of the complete AGA3 calculation. Each will be considered separately. When a meter is calculated, a number of parameters are required to determine the final flow rate. If the values are accessed in the local system, then the meter value is calculated locally. This requires that all parameters be correct in the local system. It may be desirable to only maintain the values in the actual remote system, and simply download the calculated meter value from the RTU rather than calculate it locally at the Host. Either method is available. If a meter point is specified as a remote point (by virtue of its belonging to a remote RTU), then the meter value will never be automatically calculated locally. Calculation locally will require the use of the AGA3 command either from the keyboard, or in an RTU command file executed by some task. A Host computer can get AGA3 values in one of two ways. The most common is to download the calculated meter value in engineering units from a smart RTU directly into the meter channel at the Host. This lets all of the details of the calculation be handled by the RTU itself and reduces the Host to a simple display and alarm function. Upon receiving the values, the Host will scan them and generate alarms as required. The actual calculation will never take place at the Host. The Host will simply process the final answer downloaded from the RTU. Another method is to download the input values from the RTU and perform the AGA3 calculation at the Host computer. This will require the use of an AGA3 command if the meter is set up as a remote point at the Host. If the point is configured as local, then it will be calculated constantly just as if it were at an RTU. When doing the calculation at the Host, it is necessary to have all of the meter data correctly installed at the Host. This is not necessary for calculations done at the RTU. NOTE - The calculate at the Host method for getting AGA3 values is required when using a Type 2000 "dumb" RTU. This is because the Type 2000 RTU cannot perform AGA3 calculations at the RTU itself. If a meter channel is marked as a local (non remote) point, then its value is calculated by the SCAN SCADAWARE® System Design Manual 70 Dec 2001 - Preliminary task that normally runs continuously. This would be similar to local analog channels. However, because of the complexity of the AGA3 calculation, an adjustment is provided to control how often the complete calculation is done. A partial calculation, which takes into account only pressure, differential, and temperature, can be done much quicker than the complete calculation. So, depending on the nature of the meter being installed, it may be possible to defer the complete calculation until a lesser parameter is changed. The frequency of calculation is important to avoid overloading low power processors with more than a few meters. For example, a PC level machine with 5 meters running continuously would suffer in performance because the CPU would be so busy doing AGA3 calculations. However, 286 and 368 machines operate more quickly and are not affected nearly as much by the AGA3 calculations. These lesser parameters are any ones other than the 3 primary inputs. A meter whose SG, plate size, Pct N2, etc. change infrequently can use the quick update always. However, a meter with an on-line gas analyzer providing real-time gas quality inputs will have to do the complete calculation on each pass, or as often as desired. The calculation frequency is based on the number of passes by the SCAN task, which is difficult to predict due to system dynamics. A setting of 0 means that the full calculation is never automatically done, and must be initiated by programming the channel, enabling it, or using the AGA3 command. A setting of 1 means that the full calculation happens on each pass. A number higher than 1 means that the set number of cycles will occur with partial calculations before the complete calculation is done and the counter is reset. Any command files that cause changes in any parameters (like the plate size) should issue an AGA3 command so that the complete calculation will occur right away. Also, daily command files can include an AGA3 command to insure that the complete calculation happens at least once per day. The conversion factor included in the setup is used to convert the standard AGA-3 calculation, which is in CF/Hr, to the desired flow units such as MCF/Day. The factor is divided into the AGA-3 calculation, so a conversion to MCF/Day would require a factor of 1000/24, or 41.667. The system defaults to a factor value of 1000 and units of MCF/Hr to match the AGA-3 document requirements. The AGA3 calculator will detect many errors and halt the calculation where the error occurs. A temporary internal variable is used to track the error during each calculation attempt. The error result from the last attempt is held as the externally available error code throughout the next attempt. This avoids the possibility of downloading an incorrect (or missing) error code if the SCAN command happens to catch the calculation in progress at a point where the code was set to 0. In the case of an error, the current rate is shown as 0 and the error code is shown in the AGA3 meter display. A scan on a meter channel that is in error will cause the error number to be downloaded as a negative number. The following is a list of error codes for AGA3 calculations. The terms used refer to the terms used in the actual API publication describing the calculation. These codes are also contained in a small text file called AGA3.HLP. This file can be viewed online using the EDIT or TYPE command or by entering HELP AGA3. AGA-3 ERROR CODE SUMMARY 1 - Pipe diameter = 0 2 - Base pressure = 0 3 - Local gravity factor used in calculating the Location Factor (Fl) is 0 101 - error reading orifice plate channel 102 - error reading specific gravity channel 103 - orifice plate size = 0 104 - orifice is greater than the pipe diameter 105 - specific gravity is = 0 201 - error reading differential pressure channel 202 - error reading static pressure channel 203 - error reading temperature channel 204 - differential pressure 0 SCADAWARE® System Design Manual 71 Dec 2001 - Preliminary 205 - psia calculated to be 0 206 - Reynolds Number Factor (Fr) = 0 207 - Temperature used in calculating the Flowing Temperature Factor (Ftf) is = 0 when converted to Rankine. 208 - error calculating parameter E (which is used to calculate the Supercompressibility Factor (Fpv)) with the range of adjusted pressure and adjusted temperature being 85 = temp = 240 and 0 = press = 2000 209 - error calculating parameter E (which is used to calculate the Supercompressibility Factor (Fpv)) with the range of adjusted pressure and adjusted temperature being -20 = temp 85 and 1300 = press= 2000 210 - error calculating a factor used to calculate Fpv. 211 - calculated gas flow 0 although no other errors occurred. 9.12 TOTALIZER CHANNEL PROGRAMMING Totalizer channels receive input from another channel and accumulate the total amount by calculating rate times clock time. Inputs to the totalizer can be any type of channel, but will most likely be an Analog or Meter channel. Totalizers have the same alarming and control functions as other channels, and programming is very similar. Totalizers start at 0 at a time and date that is automatically tracked by the channel. The total will continue to accumulate until reset by some source, normally a menu selection or a time of day event. For example, the Agenda system may be used to log and clear the Totalizers each morning after transferring the previous day's totals to value channels for later reference. When the Totalizers are cleared, they will automatically set their time and date so that they accurately reflect the totalized flow from a known point in time. The complete formula used in calculating the Totalizer value each second is as follows: Rate Units Rate ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Quant Units Rate Time Period ÄÄÄ = ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Sec Seconds Rate Units F1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ * F2 ÄÄÄÄÄÄÄÄÄÄÄ Rate Time Period Quant Units SCADAWARE® System Design Manual 72 Dec 2001 - Preliminary ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA TOTALIZER CHANNEL 1 Of 2 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Sales Meter Input Channel M1 Tag Q1 Min Value 0.1 Alarm Delay Secs 0 Factor 86400 Alarm Type Channel? N Blow Horn? N Play Sound? N Reset After ACK? N Call on Abnormal? N Call on Reset? N Log Abnormals? N ¨ Execute RTU file? N Skip Reports? N Callout Group 1 Current Value 4.827 MMCF (Units) Decimal Places 4 Input Control Channel Lo Alm Val 0 Hi Alm Val 100 Dead Band 0 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; The factor that needs to be entered is F1 * F2. This takes care of both engineering units conversion as well as time units to produce a number that is just quantity, without a time element. The example below will make this somewhat clearer. The program totalizes every second by taking the current rate value (from whatever source), dividing by the factor, and adding the result to the previous total. The incremental amount should be the quantity accumulated during the previous second, assuming that the rate was constant during the second. Okay, okay. Look at an example and see if it becomes a little clearer. EXAMPLE: A gas meter is programmed to show a rate as millions of cubic feet per day (MCF/Day). We want the totalizer to show thousands per day (MCF/Day) because the flow is fairly low and we want to see the numbers change more often. Because the totalizer runs each second, the factor is calculated as: Secs MMCF F1 = 86400 ÄÄÄÄÄÄ F2 = 0.001 ÄÄÄÄÄÄ SCADAWARE® System Design Manual 73 Dec 2001 - Preliminary Day MCF Factor = F1 * F2 = 86.4 Using the factor of 86.4 will produce a totalized value in MCF from a rate of MMCF/Day. If the current rate is 2.15 MMCF/Day then a one second increment is 2.15/86.4= 0.0249 MCF. This is the amount added to the total for the previous second. EXAMPLE: For a more complicated value, consider a meter that is set to show Gallons/min. We want to totalize in pounds, and the fluid weighs 6.5 pounds per gallon. The factors are: Secs 1 Gallons F1 = 60 ÄÄÄÄÄÄ F2 = ÄÄÄÄÄ ÄÄÄÄÄÄÄ Factor = F1 * F2 = 9.23 Min 6.5 Pounds Using the factor of 9.23 will produce a totalized value in pounds from a rate of gallons/min. The special parameters for totalizer channels are: Input Chan Channel where totalizer gets its input Min Value Minimum value to be considered a valid input Factor Used to convert input into desired rate 9.13 PID CHANNEL The PID channel type is described in detail in section 19 of this document. Configuration of the PID channel type is similar to other value type channels. The configuration screen is as follows: SCADAWARE® System Design Manual 74 Dec 2001 - Preliminary ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³KISSA PID CHANNEL 1 Of 2 REMOTE ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; Channel Name Analog PID Input Channel P1 Tag P1 Setpoint Chan P1S Alarm Delay Secs 0 Proportnl Chan P1G Alarm Type Channel? N Integral Chan P1I Blow Horn? N Play Sound? N Derivative Chan P1D Reset After ACK? N Stdy State Chan P1S Call on Abnormal? N Use Percent? Y Call on Reset? N Low Clamp 0 Log Abnormals? N ¨ High Clamp 100 Execute RTU file? N Chng/Min Clamp 50 Skip Reports? N Sample Period 1 Callout Group 1 Filter Value 0 Current Value 48.9 Pct (Units) Offset Output? N Decimal Places 1 Value at 0% 0 Input Control Channel Value at 100% 100 Lo Alm Val 0 Hi Alm Val 100 Min % Out Chng 0 Dead Band 0 ÕÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ͸ ³ Accept • Previous Channel • Next Channel • Cancel ³ ÔÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ ÍÍÍÍÍ; 9.14 CHANNEL REMOTE, HOLD, AND ENABLE SETTINGS Each channel has 3 temporary settings that control its local calculation and alarm processing abilities. These are the Remote setting, the Hold setting, and the Enable setting. All of these settings can be altered with the CHANGE command and the Hold setting can be altered with the HOLD and UNHOLD commands. The alarm capability of each channel can be changed with the ENABLE and DISABLE commands. SCADAWARE® System Design Manual 75 Dec 2001 - Preliminary The REMOTE setting controls automatic raw to engineering units conversion for each channel type. Local channels are converted by each pass of the SCAN task, while remote channels are assumed to be downloaded only. Remote channels are only checked for alarms when new data is detected, normally just after a download. Each channel can represent data that is either locally accessed or is downloaded from another unit. There is very little difference in processing either type, although some controls are provided to determine low level conversions and alarm processing. Generally speaking, channels not directly connected to a system will not be locally calculated. For example, analog inputs are generally downloaded from an RTU to a HOST, with the raw A/D conversion being done at the RTU. Although it is possible to have the RTU download the raw binary data and then do the conversion at the HOST, this is not necessary. AGA3 meters, however, are more complicated and may require processing at the HOST as well as the RTU. In this case, an AGA3 channel can either be changed to a local channel or it can be calculated at download time with an AGA3 command. The HOLD setting determines if any raw to engineering conversions are placed in the current value for a channel. Placing a channel on HOLD temporarily stops the setting of the current value, as is often required during calibration or end device failures. For example, an AGA3 meter can be placed on hold while its input channels are calibrated. Any totalizer using the meter value as an input would continue to see the same number all during the calibration process. No channels are on hold by default. The ENABLE setting determines a channel's ability to respond to the alarm mode settings. If a channel is enabled, it can blow the horn, cause callouts, etc. If disabled, then the channel can go into alarm or whatever without causing any automatic alarm mode actions. Channels are disabled during calibration or during end element failures to prevent unnecessary alarm activity. All channels are enabled at load time. These three settings are saved to disk for each channel whenever a data image is saved. This allows the settings for all channels to be recovered if the program is ever stopped and restarted. See the section called AUTOMATIC VALUE SAVES for information on the data image. Here's some examples: HOLD M1 ; Freeze Meter 1 during calibration CHANGE A1:a5 R- ; Make these points local (not remote) UNHOLD M1:m5 ; activate all meter channels CHANGE S1:s5 E- ; disable channels during maintenance CHANGE a1:a3 E+ ; re-enable these points ENABLE A1 ; enable battery voltage alarm DISABLE A11:a20 ; turn off alarms for all compressor points SCADAWARE® System Design Manual 76 Dec 2001 - Preliminary 10 COMMUNICATIONS AND DISPLAY TERMINALS 10.1 SERIAL COMMUNICATIONS A serial port is a standard computer I/O device that takes data in 8 bit (one byte or character) form and transmits it one bit at a time to a similar device on the receiving end. The receiver reassembles the byte into an 8 bit unit and transfers it to the receiving computer. This allows two computers to communicate with 8 bit data over a single communications link. The tradeoff is the increased time required to transfer the information one bit at a time rather than one byte at a time. All SCADA computers have serial ports. The RTU/SCADA system uses serial ports for many types of remote communications. The serial port of the PC usually connects to a modem or other data transmission device so that is can send information to a distant unit. The unit on the other end of the link has a similar device that receives the information and feeds it into the computer. SCADAWARE also has the ability to operate via the PC's local console, or via a remote CRT terminal (or a remote PC emulating a terminal). The communications is normally done via one of the PC's serial communications channels, commonly referred to in the PC world as COM1 (pronounced "COM ONE") through COM4. This section is a very basic introduction to serial communications. Numerous texts are available on the subject for those wanting a more in-depth look at the world of communications. The rate of bit transfer is called the "baud" rate, expressed in bits per second. Therefore, 1200 baud refers to a maximum rate of 1200 bits per second. The serial communications method used by the PC is called Asynchronous, meaning that characters can be transmitted at any time with an indefinite time period between characters. The bit spacing within characters must be exactly 1200 bps or else data errors will occur. To detect the errors and synchronize the transmission, additional bits are added to the actual character called Start and Stop bits. These bits surround the actual character being transmitted, so it ends up taking 10 bits (1 start + 8 data + 1 stop) to send one 8 bit byte or character. So, the maximum character transfer rate (at 1200 baud) is 1200 / 10 = 120 characters per second. The device that does this is called a Universal Asynchronous Receiver Transmitter, or UART (YOU-ART). The particular one used in personal computers is the National Semiconductor NC8250 or some variant thereof. The PC system supports baud rates from 300 - 9600. 10.2 SERIAL PORT STANDARDS (RS-232) An industry standard called RS-232-C is the common method of connecting serial devices to PC's. It was originally intended for communications between teletype devices over fairly short distances (25') and at fairly slow speeds (9600 baud max). Later versions, however, have been developed to overcome these limitations. For the purpose of the RTU/SCADA system, only the normal RS-232 type connections will be considered. The voltages used in the RS-232 standard leave a lot of room for voltage drops and other connection problems. To do this, the standard uses a nominal 12 volt signal, both negative and positive, to represent a false (0) and true (1) signal level. There is no simple explanation of which voltage is true and false, because different pins react accordingly. For example, when no data is being transmitted the data lines (2 and 3) are at -12 volts. When no carrier is being detected, the carrier detect is at -12 volts. However, the data lines are sending a true (1 or "Mark") when idle, meaning that -12 is a 1 to the data line. The carrier detect is sending a false using the same voltage. This is the result of the negative logic used on the control signals, and really adds to the confusion. When in doubt, draw a diagram to help make things clear. In actual practice, most devices are not very picky about the signal levels. Most will work with anything up to 30 volts as long as the positive and negative polarity is correct. The actual voltage level is not important, SCADAWARE® System Design Manual 77 Dec 2001 - Preliminary only the polarity. It is not uncommon for modems and terminals to work correctly with 3 volt signals, or even 3 volts positive and 0 volts negative. This is something to be aware of, however, as it explains why certain devices do not operate properly with other devices even though they appear to have adequate voltage levels. The RS-232 standard also provides for short circuit protection on all pins, and it is very difficult to tie any signals together that will cause damage. However, incorrectly wiring a device will definitely keep it from operating correctly. Determining the correct way to wire is sometimes a bit of a mystery, mostly because so many devices do not properly use the RS-232 standard. Note that the RS-232 standard applies to physical connections only and has no affect on the type of data transmission used. The baud rates, error checking, protocols, and other software related functions are not within the scope of the standard. This means that just because two devices have RS-232 ports, they may not be able to communicate at all. The actual communications takes place via a set of rules called a protocol. TEST's systems use a protocol called TSP for TEST SCADA Protocol which is explained in section 12. 10.3 RS-232 CONNECTORS AND SIGNALS The traditional connector for RS-232 devices is a DB-25. This connector has more than enough pins to carry the needed signals, and most of the signals are not even needed any more in modern computers. However, most devices still use the 25 pin connector for compatibility reasons even though as few as 2 pins are actually used. IBM devised a 9 pin RS-232 subset for the AT computer that has become fairly common, although most installations simply use a 9 pin to 25 pin converter so that the port can actually be used with existing equipment and cables. The connectors come in a male and female variety, one with pins in it and one with holes in it. Unfortunately, the one with the pins (the male) actually surrounds the mating connector, so it is sometimes incorrectly called the female. To avoid this, it is recommended that the connectors be referred to as "pins" and "holes" to avoid confusion. Because RS-232 is a two way transmission, it is not easy to identify either side of the link as the sender or receiver. The standard uses the term DCE (data communications equipment) and DTE (data terminal equipment). This made it easy to tell which component was being referenced because the computer or terminal was the terminal equipment (DTE) while the modem or whatever was the communications equipment (DCE). That is fine until two computers are connected. Then, which is DTE or DCE becomes more complicated. The best way to avoid any problems is to know the pinouts of the equipment, understand the RS-232 standard, and make a cable. The 2 and 3 letter codes in the tables below are the common abbreviations for the important RS-232 signals. These codes have historical roots in the communications industry that sometimes hide the current function of the device. It is important to understand the function of each signal in each application because a single wrong or missing connection can keep the entire system from operating properly. One important feature of each signal is whether it is transmitted or received from a particular device. One unit's transmit is another unit's receive. For example, modem type devices send a DCD that is received by computer type devices. This can get very confusing when one computer connects to another because there is no source of DCD unless a wiring change is made. These types of cables are called "null modems" because they effectively replace the functions normally supplied by a pair of modems and a communications system. SCADAWARE® System Design Manual 78 Dec 2001 - Preliminary DB-25 DB-25 TD Transmit Data, also called SD for Send Data. This term refers to data coming out of data terminal equipment (DTE) probably into a modem (DCE). When two computers are connected directly to one another, their TD and RD lines must be crossed with a null-modem device. RD Receive Data. This term refers to data coming into a computer (DTE) from data communications equipment (DCE). When two computers are connected directly to one another, their RD and TD lines must be crossed with a null-modem device. RTS Request to Send. This control signal from a computer (DTE) is used to activate some types of modems. In a direct connect or multi-drop systems, this signal tells the modem to turn on its carrier signal. On other systems, the RTS is not actually required. Note: TEST's Modem Monitor device uses the RTS line to activate the watchdog timer function. This can be changed with the MONITOR command to use the DCD line, but this requires a jumper change to the Modem Monitor circuit. CTS Clear to Send. This signal from a modem device indicates that the modem is ready to receive data from the computer. This is not used by any of the TEST communications systems. DSR Data Set Ready. Another relic signal from a modem that indicates that the unit is ready to receive commands or data. Not used in TEST systems. DCD Data Carrier Detect (also written as CD). This signal originally meant that a tone carrier was being received by a modem device. This would indicate that the modem is "hearing" another unit with an acceptable signal and that data received would be valid. Modern communications devices can generate a DCD signal for a variety of other reasons that generally mean that the unit is in communication to another unit regardless of the presence of an actual tone carrier. The TEST SCADA software uses the DCD signal to control on-line status during serial communications. SCADAWARE® System Design Manual 79 Dec 2001 - Preliminary DTR Data Terminal Ready. This control signal from a computer is used to enable a modem type device. In practical use, the signal is also used to reset smart devices like Hayes modems and Packet Controllers. This signal is toggled off then on during disconnect actions as a hardware method of resetting the modems connected to the computer via the serial port. Not all modems react to this signal, and some act in various ways that depend on jumper or software setting. For example, 2400 baud Hayes modems use the &D command to set the response to the DTR transition. TEST uses the RS-232 signals in fairly traditional ways for most functions. The most unusual application is the use of RTS or DTR as a control line for TEST's Modem Monitor device. The software toggles one of these lines once per second to activate the watchdog timer in the Modem Monitor. If the line does not toggle within a specified time period, the Modem Monitor will reset the computer. See the MONITOR command and the section on the Modem Monitor for more information. The RTS line is also used as a special control signal on multi-drop systems. The RTS line is used to control the carrier output of a modem. The software will turn this signal on prior to transmission and will turn it off when the transmission is complete. Therefore, the watchdog timer in the Modem monitor may have to be moved to the DTR pin if it is likely that a transmission will not occur within the timeout period of the Modem Monitor. In multi-drop mode, the system will monitor the DCD line to make sure the communications line is quiet before turning on the data carrier. If the DCD is clear, the software provides for a delay between the time the RTS line is turned on and transmission starts. This allows modems and radios to get their carriers turned on before the actual data starts down the line. At the end of the data burst, the RTS line is kept active for a short time before it is again turned off. Direct connect systems can be hooked up with a simple 5 wire null-modem cable. This simply crosses the TD and RD lines from each of the computers and also switches the RTS and DCD lines to provide flow control. When the direct connect system "dials" out, it simply raises its RTS line and keeps it on for the duration of the session. The other unit will "see" this signal at its DCD input which will cause it to turn its own RTS line as a response. Therefore, direct connect systems use their RTS line to activate the DCD input of the other computer. The fifth wire is used for the SG Signal Ground, Pin 7 on the DB-25. Therefore, a null modem hookup on a 25 pin connector would use pins 2,3,4,7, and 8. Pins 2 and 3 are crossed, and pins 4 and 8 are crossed. Pin 7 is a straight through connection. 10.4 DATA MODEMS It is possible to connect two devices directly using serial ports and the RS-232 connectors. This is fine for local connections to terminals and printers. However, connecting devices over a longer distance requires some sort of data carrier device, called a modem. Modem is short for MODulator - DEModulator. This refers to the device's ability to take a true or false signal (1 or 0) and transmit it by modulating (changing) a tone signal. The Demodulator part of the device detects the amount of signal change and interprets it as a 1 or 0 on the receiving end. This allows ones and zeros to be transmitted over any link that can carry sound. The RTU/SCADA system uses many types of modems. Some are phone based and are designed around the HAYES smart modem standard. These are used for all types of phones, either hardwired or radio based. Another type of modem is called a PACKET RADIO CONTROLLER, or PRC. This device is intended for operation over radio links. The system will also work with various types of simple modems and multi-drop modems that work with various other communications systems. TEST's system will also work with PC based Network systems. The system is similar to a multi-drop system except that data is exchanged over the network rather than over a communications channel. The details of network operation are explained in a separate document and will not be covered in detail here. All modems do basically the same thing, which is change data into sound and then back again. The difference between the different modem designs is the type of physical output to the communications link. Some are designed for telephone type connections (RJ11 Jacks), while the other has separate audio input and output for connection to the radio. Still others are designed for dedicated wire pairs or microwave circuits. SCADAWARE® System Design Manual 80 Dec 2001 - Preliminary 10.5 RTU COMMUNICATIONS MEDIA The RTU/SCADA program is designed to allow operations from the local PC keyboard and CRT as well as via remote communications links. To accomplish this, most functions within the program do not assume anything particular about the link. Any special requirements are taken care of at a higher level within the program. The communications media types currently supported are: Local Console Local PC CRT and Keyboard Direct Connection RTU or ANSI terminal hardwired to port Phone Modem HAYES modem on serial port PRC Modem Packet Radio Controller on serial port Multi-Drop Special modems or radios on serial port Netbios PC Based Network Communications Aside from the dialing and hang up type functions, the operation of the program over the modem is identical to hard wired or local console operation. The software is not directly aware that the data is being transmitted with sound instead of electricity. The RTU/SCADA programs, however, do a lot of housekeeping to manipulate the modems in order to make the connections, maintain them, and then disconnect for a variety of reasons. In the case of the hard wired connection, these functions are not needed, although the status of the connection is always monitored. The SET MEDIA command is used to tell the program the type of link used for each RTU type task. It is normal to place the proper setup commands in the STARTx file for each task so that the proper setting will always be obtained on startup. The commands can also be repeated in the BYE file for each task to insure that any changes made while online are fixed when a user logs off. 10.6 MODEM ON-LINE STATUS The RTU/SCADA program is particularly sensitive to the on-line status of the communications device and terminal. This is the result of numerous problems with actual installations where the communications channel is unreliable and extremely noisy. The basic means of detecting an on-line state is via pin 8 of the RS-232 line, the DATA CARRIER DETECT (DCD). The DCD input for any type of serial communications link must accurately reflect the state of the connection. The CD or DCD line has traditionally meant that the modem device was sensing the audio tone called the "carrier" that was used to carry the data tones. The variance from the carrier is what determines the one or zero state of the line. If no carrier is being detected, the modem is off-line and any data coming from it must be ignored. This is still true for many modem types that operate in a point-to-point mode with only two devices at a time. Because of the variety of communications links possible with the program, the DCD line is always used as the common means of determining that the link is valid. In the case of the directly connected terminal, the DCD line must be jumped to another pin on the port that is in the same state as a true DCD (i.e. +12v). This will tell the program that the terminal is connected at all times. For a HAYES type modem, the DCD must reflect a connected state to another modem. As long as the HAYES determines that there is a carrier, or that a long enough break in the carrier has not occurred, then the DCD will be true. If the carrier is not present, then DCD will be false and the program will process a disconnect. A setting, either by switch or by command to the modem, is necessary in order for the DCD to function in this way. A constantly active DCD will cause the program to operate as if it were always connected, which is incorrect. This will prevent dialouts and cause the program to loop waiting for data that will never come. Refer to the modem documentation for more information about modems and how to set the DCD for proper operation. Tip: See the &C command in your Hayes compatible modem reference book. SCADAWARE® System Design Manual 81 Dec 2001 - Preliminary The packet radio controller (PRC) is a little more complicated because of the "half-duplex" nature of radio transmissions. The PRC does not send out a constant carrier tone like the HAYES modem does. In the case of the PRC, the DCD status represents a logical connection to another PRC that is determined by radio tone handshaking by the modems themselves. One PRC modem calls another, they exchange codes, and then the DCD is established. Until the PRCs disconnect, the DCD will be true even though no actual carrier is being transmitted. The disconnect will occur after a timeout or if the computer commands the PRC to "hang up". Note that a jumper or other setting inside the PRC must be set properly in order for the DCD to provide this function. Not all PRC units offer this type of DCD function, so check with the manufacturer if you are using a non-standard unit with a TEST system. Multi-drop modems are different from direct-connect devices because the carrier signal is present only in brief spurts of data. Therefore, multi-drop configurations do not use the presence of the DCD as a mechanism to detect an on-line state. The multi-drop system uses a logical rather than physical on-line , much like the Packet Controller. The software keeps track of the on-line status based on the characters received and various timeouts. Therefore, tasks using multi-drop modems will not use the DCD line to determine their on-line state. 10.7 HAYES MODEMS The HAYES standard refers to modems that can do many functions in response to a special command sequence. The standard is used by most PC modems, although many modems have non-standard functions that are hardware dependent. The modems are often referred to as using the standard "AT" command set which identifies the modem as a Hayes type modem without having to use the actual word Hayes in the specifications. The commands are centered on things like phone dialing, timeout detection, call progress monitoring, and other communications functions. The processing of these functions is done within the modem itself using a small microprocessor. The commands go into the modem over the same serial line that the data uses. So, the modem watches for a special sequence of pauses, plus signs, a pause, and the letters "AT" (for attention) to switch from data mode to command mode. The ability of the modem to do the dialing and timing functions eases the burden on the main PC processor. However, the modem must be correctly set up in order to function with the software. Although the means of setup are slightly different for most HAYES modems, the basic setting requirements for most installations are: 1. Carrier Detect must follow the true carrier on the line and must not be present at all times. This is set via a switch on 1200 baud modems and by the &C command on all other Hayes compatible units. 2. Tone dialing (depends on the unit). Override with P if pulse dialing required instead of touch tone dialing. 3. Answer on 2 rings (S0=2). 4. Lost carrier delay of 1 second or mode (S10). 5. DTMF timing set fairly slow (S11) for cellular and radio phones. Fast dialing on land lines is usually OK. There may be other settings particular to each installation and modem that will require setup. The program's HAYES command can be used to send these commands to the modem at startup or each time that a BYEx file is processed. This is recommended to insure that the modem is always properly setup after each communications session. The HAYES modem can be accessed at the RTU or HOST by using the ATTACH command. This will connect the local CRT/KEYBOARD to the serial port going to the modem. Commands can be sent and their responses seen on the local CRT. Note that the modem must be placed on "QUIET OFF" so that it will send responses, and "ECHO ON" so that the user's keystrokes can be seen. This will require a "Q0 E1" command to be sent to the modem. Refer to the modem manual for further information. SCADAWARE® System Design Manual 82 Dec 2001 - Preliminary The phone number in a Hayes dialing string can contain special characters that are often helpful in working with real-world telephone problems. These special codes go right in there with the actual digits and instruct the modem to do special things during the dialing process. The most common codes are listed below. CODE FUNCTION P Switch to Pulse style dialing T Switch to Touch Tone dialing W Wait for a dialtone before proceeding , Programmed delay (normally 1 second, adjustable) / Wait 1/8th second ! Flash @ Wait for quiet before proceeding These codes are used to handle special dialing problems such as getting an outside line, long distance codes, cellular tricks, and other real-world telephone problems. Consider the dialing string P9,T555-1212,454. This character sequence will switch to pulse dialing and dial 9 perhaps to get an outside line on an older switchboard. The comma after the 9 will cause a wait of 1 second which allows time for the internal switchboard to access the outside line. Then the modem switches to Tone dialing and dials the number 555-1212. At the end of the phone number, the modem will wait another second for a long-distance service to kick in. Then, the string will send the tones for the digits 454 which could be for a special long distance access code. Obviously this was a made up example but is typical of the dialing problems that are encountered in actual installations. The most common codes are the P and T to control the dialing method and the comma to put waits into the sequence. There are also several "S" registers internal to a Hayes modem that control timing and other parameters. Most Hayes compatible modems support a basic set of these registers and others have many special ones unique to that particular model of modem. Consult the manual for exact details on each modem. The S registers needed in most applications are listed below. S0 Number of rings before answering, default is 0. S6 Sets seconds to wait (max) for a dialtone (default 2) S7 Sets seconds to wait for carrier on callout (default 30) S8 Sets seconds for delay for each comma in phone number S9 Carrier response time in 1/10 seconds (default 6) S10 Delay from loss of carrier to hangup (default 14/10 secs) S11 Milliseconds between touch tone dial codes (70 ms) These S registers are set in the modem by using the HAYES command, normally during startup and in the BYE file for each task. For example, to set a modem to answer on 3 rings and use 150ms between touch tones we would use HAYES S0=3 S11=150 Hayes modems are very complex devices. The manual should be consulted when troubleshooting any communications problems that may be related to behavior of the modem. 10.8 PACKET RADIO CONTROLLERS The PRC is similar to the HAYES modem in that it contains a small microprocessor that handles many timing and other communications functions. It goes beyond the HAYES modem in that it also handles message routing and error checking. Rather than send data directly as it comes in, the PRC gathers up a group of data called a PACKET and sends it as a chunk to another modem. The packet has the address of the sender and receiver as well as error checking codes to insure that the information is properly routed and received. The PRC receiving the message sends acknowledgement codes to the sender for each packet. SCADAWARE® System Design Manual 83 Dec 2001 - Preliminary There is obviously a lot of work involved in all this processing, but the PRC takes care of it automatically. Rather than dialing a phone, the PRC sends out a connect request to another PRC. If the connection is made, the PRC uses the DCD line on the RS-232 port to indicate a connection. Data can then be sent by the computer without any concern over the additional processing being provided by the PRC. Problems like data errors and disconnects are handled by the PRC which will notify the computer by killing the DCD signal. The PRC must be set properly for each installation in order for it to function correctly. The complexity of the radio transmission requires detailed information on the radio's audio input and output circuits that will be connected to the PRC. Also, the "key up" times and squelch settings of the radio must be adjusted and accounted for with various settings within the PRC. The most important settings are: MYCALL The radio address of the PRC, normally set to the RTU's ID code. TXDELAY Transmission key up delay, or the time between the PRC's push to talk and the actual transmit. DCD Setting that sets DCD to indicate a logical connection to another unit. The PRC can be diagnosed and setup by the RTU or HOST computer by using the ATTACH command. This will let the local CRT/KEYBOARD be used to send and receive characters directly to the PRC. Note that the PRC must have its ECHO ON and STATUS ON in order to see keystrokes and responses from the PRC. Refer to the PRC documentation for further details. 10.9 DISPLAY TERMINAL TYPES Different physical display types require different control codes to do things like clear the screen and position the cursor. In the past, there were hundreds of different terminal styles that made if difficult to write software to work on all of them. This has been eased in recent years by the adoption of an ANSI terminal standard pioneered by Digital Equipment Corp. (DEC). In addition