Cicode Programming ~" Training Manual Version 7.0(CHAPTER 5: CICODE FUNCTIONS: Overview Writing Simple Functions... Function Elements .. Public and Private Funetion Declaring Functions..... Naming Funetions Statements... Void Functions... Cicode Variables... Converting and Formatting Cieode Variables Include Files. Summary oo CHAPTER 6: CONDITIONAL EXECUTORS, Overview IF Statement For Loop. While Loop SELECT CASE Statement. Summary... CHAPTER T: MORE CICODE FUNCTIONS, Overview Return Functions... Debugging Code Arrays. Comments... Summary CHAPTERS: — CICODE DEBUGGER Overview. — . Cicode Editor Environment en Taking your Next Step Aggfiged Stepping) Summary x CHAPTERS: COURSE SUYBLARS Course Evaluation oath eal Further Training : Citect Examinat . APPENDIX A: STRUCTURE TecHNiQuEs Overview CitectHMi/SCADA Version 7.0 8-14 ‘August 2007Chapter 1: _ Introduction to Cicode Programmin: Overview Introduction Contents Cicode is a simple, easy-to-use computer programming lanetiage designed especially for plant monitoring and control applicationsi=t is language similar to Visual Basic or 'C', however you need_no previous programming experience to use it. E 2 Using Cicode, you have access to all real-time, data (vafables) in the CitectHMUSCADA project, and all CitectHIMI/SCADAfaellitics - variable tags, alarms, trends, reports, and so on. You can use Cicode to interface to various resources on the computer, such as the operating system and communication ports. fl Cicode supports advanced features ineluding pre-emptive multi-tasking, ‘multi-threads, and remote procedure calls that, will be discussed Jater in this course, z ‘This chapter contains the fotl@wing t my ‘Topic 7 See Page > Before You Bedi, E 1-2 > Course Overview all 13 > Conveggigns Used in this Manual 1-5Before You Begin Your Instructor Please write the name of your Instructor here Z ‘Your Instructor will be spending the next two days with you, andiwill guide you through this training course. Your Instructor is”an. expetienced Defining the This training manual is a supplement to Citect Certified Training. In order to Scope of this make full use of the software you should also reference théOnline Help and Training CitectSCADA Knowledge Base Manual ‘The graphics displaying sereen shots have beé#t taken using the Windows XP operating system using Classic mode display properties. If you are running a different version of Windows then your screens may differ slightly from the ones shown in the training manual, CitectHIMUSCADA Version 7.0 August 2007Course Overview Course Objectives Course Material By the completion of this training course you will Be able to apply what you have learnt to yougovm spl vvyvy Be able to write your own Cicode functions z g 3 2 zg g 2 s & & Ez & S 6 g 3 2 5 2 3 & a g g > Citect Compendium » Citect Mouse Pad » Pen » Notepad > Memory Stil >» The current us ‘Continued on next page Manual Release 1 13Course Program Course Overview, Continued ae The training course will take two days to complete. The following program outlines the topics that will be covered on each day: Day [| Topies 1 Introduction to Cicode » Variable Operators used in Cicode > The Cicode Editor att > Writing Simple Functions > Using Cicode Variables >» Conversion Functions: Include Files Conditional Executors > Cicode Return FunctigAs » Arrays CitectHMUSCADA Version 7.0 ‘August 2007Conventions Used in this Manual Objectives ‘These are the skills you will achieve by the end of each chapter. Aioverview providing a brief synopsis ofthe topic begins each section. Often, examples are given to illustrate the conceptual overview. S Example ~ Objectives The Unity Pro configuration environments gonsists of spferal toolbars, browser windows and programming editors. ‘This chapter infroduces the user to the configuration cnvironment using an exaniple:projest with pre-defined elements. Contents This chapter contains the following topics. Topic See Page > Topic A > Topic B ns > Topic C Exercises Afier a concept you just learned. cach exercise and the each procedure. I be given exercises that practise the skills exercises begin by explaining the general concept of y-sfep procedures are listed to guide you through Exercise 6-1 mm a Hliry in the Include project onto a test page called Utility. ade project then trigger and view some alarms. ing template settings: is veal 1 provide you with useful or helpful information that will configuring your project easier Continued on next page es “Gicode Programming Manual Release 1 15Conventions Used in this Manual, Continued Note A note will refer to a feature which may not be obvious at first glanee, but something that you should always keep in mind % Example - Menus and Text separated by the pipe symbol “»” indicatesythat you are to go fo a menu ‘Menu Options ze Example - Eile » New... Horizontal and ‘Text written this, way igigates the Horizontal then the (Vertical) tab you are t0 - Vertical Tabs choose. ia “Wen ge Example ~ : Whenever yau anges to type information into a field of dialog box it will be written inthis font : See Also . Fer further information about Templates, see CitectSCADA Help - Using Page Templates. CitectHMISCADA Version 7.0 ‘August 2007Overview Introduction Contents Chapter 2: —_ Introduction to Cicode three main categories; commands, expressions and functions: In this chapter you will learn how to perform a range of tasks. These fall into > Setting Variables > Expressions > Multiple Statements > Getting Operator Input v Passing Multiple Argum: vv Passing Numetig.Arguments v Passing Variables as egumey a Returning Data from Functions Starting Paint See Page 2-2 25 29 2-12 214 218 2.20 2.23 2.25 2.28 2-30 2.33Commands Overview How to Cicode commands provide the contro! element of a CitectHMI/SCADA control and monitoring system, You use commands ‘0, control youl CiteetHMI/SCADA system and therefore the processes in the plant Each command has a mechanism to activate it, Gommands can be issued ‘manually, through an operator typing a key sequefiee or clicking on a button (or object) on a graphics page. You can also configure commands to execute automatically: % > When an operator logs into or out of the runtime system > When a graphics page is opened, being displayed or closed > When an alarm is triggered : > Ina report . 5 > When an event is triggered ge % Todefine a Cicode committid, & Enter a statement (or group of statém s) in the Execute command field (Input category) for affighject. This command changes the text object Test to display ON Each statement in a command usually performs a single task, such as setting a variable to a value, calculating a value, displaying a message on the screen, or running a report Continued on next page CitectHMUSCADA Version 7.0 ‘August 2007Commands, Continued Exercise 2-1 *Bieode Programming Step | Action 1 | Create ‘two buttons to turn the tag AgitatgfiSilo,V ON and OFF. Open the page Chapters j Create a button under the headiag Chapter 2 in the Appearance (General) pr is% le toi 3 fon: foaarone Sat ror reioeg Coed | toss [ie Continued on next page Manual Release 1 23Commands, Continued Exercise 2-1 (continued) Action = ‘Step 7 (cont) iv. _ In the Input (Touch) properties insert thetext Agitator_Silo_V = 1 into the Up command field Gillean OK greate a¥ggond button and repeat steps ii - v. in this case ‘ype Turn Silo Agitator OFF in the Text ficld and SS itAtOr_Silo_V = 0 in the Up command field vil? Save your page 2 and Run your Project to test the new command CitectHMSCADA Version 7.0 ‘August 2007Setting Variables Digitals ‘Commands execute specific tasks like setting a variable tag or efianding a bit. As we saw in the previous exercise we can change something like the étarus ofa pump. If we define a digital tag called PLANT1_PUMP to eontrol a pump, Analogs In the same way we can set theyalue of iF analog variable. If, for example, we have an analog tag called OVEN_TEMP, we can set its value to, say 10, bya ae the ‘gre command: (ane ‘Command OVEN _TENP = 0; You can following Execute Command f ~ OVEN_TEMP - KETTLE _TEMP; value of OVEN_TEMP is set to the value of KETTLE_TEMP only when the and is issued. The value of KETTLE_TEMP could change immediately aier but OVEN_TEMP remains unchanged until the command ied again Continued on next page ‘Manual Release 1 25Setting Variables, Continued Exercise 2-2 Step_| Action 1 | Greate buttons on the Chaptors page to set WalUeS to th variables TIC_Gool_PV and TIC_Pt_PV. Under the heading Chapter 2 create value of TIC_Cool_PV to -3, Create a button to change the value of FIC_P1_P¥to the value of TIC_Cool_PV. -4 button to charge the Z| Save yk jour page. CitectHHMUSCADA Version 7.0 ‘August 2007Strings Setting Variables, Continued You can also use string variables in expressions. For" examp! BATCH_NAME is a variable tag defined as a string data type, you can U following command to set the tag to the value "Bread" Execute Command BACH NAME = "Bread"; Note: When you use a literal string, you must enclose the string in quotation marks. Continued on next page ‘Manual Release 1 27Setting Variables, Continued & Exercise 2-3 Step ‘Action Use a touch command to change the value ofa string tagto a literal string. * i. Create a button on the Chapters page to change the:value of the tag Recipe to the literal string ji, Save the page CitectHIMISCADA Version 7.0 ‘August 2007Expressions Numeric ‘A Cicode expression is the basic element of the Cicode Jingudige. An” Expressions expression can be a constant, the value of a variable tag, of the result of a complex equation. You can use expressions to display andelog data for monitoring and analysis, and to trigger various elements'im your “system, such as alarms, events, reports, and data logging. You can enter a Cicode expression in any expkession property. Unlike a command, an expression does not execute a specifig task, instead it is simply something that can be evaluated. The evaluation prodess.retiitns a value that you can use to display information on the screen (for example, as a bar graph) or to make decisions. The following simple expression returns a result of 12: Numeric Haphesia a In the above example, the value of'thic express because the elements of the expr ion is always a constant (12) afe Constants (8 and 4). = # Performing You can also perform mathaigl calculations in a Cicode statement, for Caleulations example: 7 fee Execute Command” MILL1_SPEED = MILD: Re When the com is executed, the variable MILL1_SPEED is set to a value that is the sum o} ae MILL2_SPEED and MILL3_SPEED minus 100, Notice the sity. that i€tised in these calculations. The variable that holds the result@t the: jon is placed first in the command sequence. * ole + operand 2 ~ operands; tinued on next page “ead Progen ara Ros 29Expressions, Continued Displaying Data In the following example, the value of the expression is the #alue @f. the variable BURNER_TEMP. As its value changes, the value of the expression also changes, You can use this expression to display a number oma graphics page. goo Numeric Expression BURNER _TEMP Expressions can also include mathematical calculations *=E6F example, you can add two variables together and display the combined total: ‘Numeric Expression BURNER TEMB + WATER, TEMP x s. In this case, the value of the expression is the combined total. As the value of one variable (or both variables) changes, the,yalue of the expression changes. ‘ontinued on next page CitectHiilISCADA Version 7.0 ‘August 2007Expressions, Continued E Exercise 2-4 Step ‘Action Greate a button to execute a command igiadathe vals of two analog tags. i i. Goto the page Chapters and cree a button cal TIC_P4_PV on the sereen that adds the value of TIC_P1_PV end THE_P2_PV then atu the gut into TIC_BA_ PY. il, Save the page ‘Compile and run the project. i. Open the Chapters page and test your new command ‘Manual Release 1 anMuitiple Statements Combining Statements Execute Command é ‘OVEN_TEMP = KETTLEGPEMP; BATCH NAME = “Bre: MILL1_SPEED = 10 ‘The first statement sets the variable OVEN_TEMP to the Valli¢ of the variable KETTLE_TEMP; the second statement sets the variable BATCH_NAME to the string "Bread"; and the third statement scts.the variable MILL1_SPEED to 10. Each statement is executed in order. 2° The number of statements you can enter ita’commiand property is limited only by the size of the field. Howeves, for elanity, it is better not use 100 many statements - enter the statements: ‘into ans “include file” or write a Cicode function instead. You can then refer to she include file or eall the funetion in the Execute command propétty, (Incite files and functions will be discussed later), CCitectHMSCADA Version 7.0 August 2007Exercise 2-5 Multiple Statements, Continued Step_[ Action 1 | Create a multiple statement. si ‘on the prompt line. ji. Save the page. iti, Compile and run the project to check the result. Stee, Go to the page Chapters and back'to the button'you previously created to calculate the level of the TIG.P4_PV tag Create another statement to display “Calculation fs finished” Y Hints & Tips: £ € Use the function Prompt{*Calculatiog ts functions later in the chapter, = uss a is finished"). We will be looking at *Gigode Programming Manual Release 1 243Getting Operator Input é Keyboard You can define a keyboard command as a key sequence, to perfattn a specific Commands task each time the key sequence is pressed. For example: een noes Key Sequence | Execute Command F2 Enter Key Sequence 7 A key sequence can include provision for the opetiitor to enter data. In the following example, the operator can set the Vilue, of the variable CONVEYOR SPEED: semua ieocion © POL Pozen Fine) Operator Input ~ Key sequence commend— [CONVEVER_SPEED=Arqvabel Aeipperuce issues the command by pressing the F2 key, then enters up to & “gy thre® characters, and presses the Enter key. The three character sequence RE gages entified by the three hash (#) characters) is called an argument. The “Fe, a ment is passed into the command (as ArgValuel) when the command is aqcompleted (when the operator presses the Enter key). 28S CitectHMUSCADA Version 7.0 August 2007Getting Operator Input, Continued Operator Input (continued) *Binade Programming ‘The operator might type: F2(1][2]B |[ENTER| ‘The value 123 is passed to the command and GONVEYOR_SPEED is set to 123. o ‘ ‘You should always use a specific key (for cxamplper to sigtal the end of a key sequence. If, for example, you use the key Seqpigtice F2 #AH#, the operator must enter 4 characters for the command to be executed - CitectHMI/SCADA waits for the fourth character. But if you use F2 st Enter, the operator can enter between ong"@iid-four characters as required The command executes as soon as the Ener key is pressed. You can pass more than one argument:to..aseommand. You separate arguments by commas (.) in the Key Sequence and pass each argument into a statement in the command: = MEBs to 18. When you are passing multiple arguments these then equ » Arg?, Arg3....and so on. There are gins define the argument, ‘These are ArgX as shown in the example above iid ArgValueX. There is an important difference between the two. “i does not. This means that if you use ArgX for the rator can enter a number or letter and it will write to the if an integer tag has been set using Argl, and in runtime ntered accidentally, the result is that the value 0 is written to operator inpul ime you should use Arg] is if you are writing to a string tag erwise you should always use ArgValuel. If you use ArgValuel and try a ‘letter’ to the tag you get an "Invalid Data" error at the prompt and the system will not write to the ta Continued on next page Manual Release 1 245Get Exercise 2-6 g Operator Input, Continued Step | Action 7 | create a System Keyboard Key to use in @ new Key Seqiiénes. Open the Citect Project Editor and chigose System» Keyboard Keys from the menu Create a now key called F2 that uses the Key Code KEY_F2 Define a key sequence ta chafige the value of the string tag Misc1 when the miguse is positioned over the text object on the Chapters page. Return to the Chaptérs page and double-click the Miset text 0 open the progerties dialog Sr srupuse> ooaten A (Sey | Sane wea escbist FF Same pirlege obec Command xox [latwea a] idee love Pore =] Clee 0 fesse re Continued on next page CitectHMUSCADA Version 7.0 ‘August 2007Getting Operator Input, Continued Exereise 2-6 (continued) Step | Action ‘3 _ | Save the page and compile your project, i. Run the project and open the pagghapters li, Position your pointer over the tex object Misct. Recipe aise ey Enter the key sequence | F2 Hello ENTER® i as you nfs teayiSfeuonsh you wit soe tne Keyboard Echo dsplalahe charagharsthat you type. a il, After the eMeie, is pressed you will see the word “Hello” {@qq, SsPlay0d inthe Mise string object. 7 Helle *Cigode Programming ‘Manual Release 1 27Calling Functions in Commands and Expressions. ee You can calla funetion by entering its name in any command ar expreision property. The syntax is as follows: Execute Command PunctionName (Argi, Arg? 1 Where: FunctionName is the name of the function Argi, Arg2, ... are the arguments you pass tithe iin: [Key Sequence Execute Command [End Key Shutdown) When the End keyboard key is pressed the and CiteetHMY/SCADA jis shutdown, tdown () CitectHMVSCADA Version 7.0 function is called Cantinued on next page ‘August 2007Calling Functions in Commands and Expressions, Continued Exercise 2-7 Step [Action 1 | Add a button to the page Chapters to open the Tag Debug. i. Draw a new button under the Chapter 2 heading Appearance (General) tab add the text Tag Debi field. in the to the Text i, Open the Input (Touch) tab and add the Hewitip command, 2 | Save the page and compile your project. in the project. ‘Shutdown the project “Cigode Programming ‘Manual Release 1 249Passing Data to Func! ‘ an) Arguments The parentheses () in the function name identify the statement as a filietion and enclose its arguments. Arguments are the values or variables that ae passed into the function when it executes. % String Functions can require several arguments or, as iff the following example, a Arguments single argument: % - Execute Command PageDisplay ("Boilerd*) ; This function displays the graphies page calféd "Boiler". Note that when you pass a string to a function, you must always.encloge the string in double quotes. ‘ee Y Hints & Tips: ce % To find out information about parimeters requiréd in any Cicode function, go to the CitectSCADA Help and search for the:function in the Index. The following example u “Press F'1 for Help” on the sereen-whien the command executes: Execute Command Prompt ("Press Fi for Help"); Be Continued on next page 220% CitecthMW/SCADA Version 7.0 August 2007Passing Data to Functions, Continued Exercise 2-8 Step 7 ‘Action z Greate a System Keyboard Command thatepens the project page called Chapters when you click on the Right Mouse Button. |, Open the citect Project Editor and ehoose System } Keyboard Commands from the menu S ii, Choose the Key Sequence RBUTTON_UP. iii. Add the function PageDisplay (*Chapters”) to the ‘command field i Run the project 4 Glick the right mouse button anywhere on the Home page “hiss run the keyboard command and open the Chapters pages Y Hints’& Tips: keyboard command RBUTTON_UP will execute the command if you slick anywhere. RBUTTON_CMD_UP will execute the command Lonily ifthe mouse is positioned over the object. * Gieode Programming Continued on next page Manual Release 1 221Passing Data to Functions, Continued Exercise 2-9 Step Action | Create a button on the page Chapters caliediExeel that uses the Exec() function to start up Excel. i i. Open the Chapters page and createla new button, = | ji Add the text Excel to the textfield ofthe Appearance (General) tab. 2 iii, Open the input (Touch) tab and add the new Up command. Windows Explorer to verity the location of your Excel.exe Wggltne screenshot above olsplays the defeut location used Yu, by Office 2003, 4 | Shutdown the project Save the page and compile the project. Run your project. ‘pen the page Chapters and test your new command. CitectHIMISCADA Version 7.0 ‘August 2007Passing Multiple Arguments Separating Arguments iy “Gigade Programming Some functions require several arguments. You must list lf aéjqument between the parentheses, and separate each argument with a gpm (Yin the following exampie: Execute Command Ee [Eogin Nenager' BEET: Ty . ‘The order of the arguments is important to the operafien of anyunction, The Login () funetion logs a user into your runtime system: Fhe first argument ("Manager") indicates the name of the user, and the second argument ("ABC") is the user's password. If you reverse the order of the arguments, the function would attempt to login a user calléd "ABC" - if a user by this name does not exist an error message displays. yntinued on next page Manual Release 1 223Passing Multiple Arguments, Continued : Exercise 2-10 Step_[ Action 1 | Create a popup trend page and specify the trend tags be displayed r ee |. Greate a new page besed on the CES, Style PopTrene template, . ii. Save the page and name it IMyPopTrend & iii, Create a new button on the Chapters pagéseaifie the button Pop Trend. iv. Open the Input (Toueh) tob and add this function into the Up command ‘TrendPopUp (" !MyPopTrend" "PL_PY, D2 PY, "53 Pv ,Upa OW select List in the Eile » Op Save the page and eamipile the project. Run i praject and test the new command. CitectH¥MUSCADA Version 7.0Passing Numeric Arguments Exercise 2-11 You can pass numbers (integers and floating point numbergp directly. toa funetion, for example: Execute Command] AlarmAck (2, 35) Step | Action ‘Add a command to the Chapters page to opew'@ popup control at @ specific location. i, Open the properties of the Valye_Cool_CMD text object ii, Open the Input (Touch) tb and ndg.the AssWin() function to the Up command, AssWin(" 1Valve", 488,310,512+8+1, "Valve_Cool_cwD") Jeena [eae pacar Continued on next page ‘Eigode Programming ‘Manual Reloase 1 225Passing Numeric Arguments, Continued ise 2-11 (continued) Step _| Action 3) Run the project. ‘object. The popup page should oper i. Open the page Chapters and click the Valve_Cool CMD text Malye Cool_cMD OFF | valve 4W_CMD OFF Aalvefov_cmD ore ‘Shutdown the project. 7 bar of the popup page. 2 ipTitle ("valve_Cool_cMD") fentiteVaive_ Cesk CMD") CitectHIMVSCADA Version 7.0 = — aa another command Waibiay the name ofthe Tag inthe te i. Open the citect Graliiie Builder and return to the Chapters page, Open the propetties of the Valve_Cool_CMD text object and @@q,this command £ the Input (Touch) Up command, Since yollage now usidig multiple lines of Cicade, you will need to place a seftiecolonal the end of the first commana. [asswesrvave" ai S10ST2CSH1 “Vata Cool Gaawasgenecon Bea Ficbey Continued on next page August 2007Passing Numeric Arguments, Continued Exercise 2-11 (continued) Step_| Action 6 _ | Save the page and compile the project. 7 | Run the project. 1. Open the Chapters page and test etve_ceot cw Mateo 6 vatve_Ftove_cmp OFF ore OFF age roaring Aaret toe 220Passing Variables as Arguments When variables (such as real-time data) are used as arguments, the Wah the variable is passed, not the variable itself, The following example uses th Depstr () function to display the value of process variablé @t-Animation point 25: Execute Command = : Depstr(25, "TextFont", COAL LEVEL) = je In this instance, the value of COAL_LEVEL displays. [Filisa-realtime variable, the number that displays depends on its value at the time. Note: If you include a tag in double quotes, the text string COAL_LEVEL displa variable. @COAL_LEVEL", then "-nét the value of the Continued on next page CitectHMVSCADA Version 7.0 August 2007Passing Variables as Arguments, Continued Exercise 2-12 Step ‘Action 1 | Use a function with variable arguments tg display the Walue of a tag in a Cicode object. i, Open the Pasteuris F page and pice a Cicode object above the Alfast object. 3 il Croato a;pow buttonigiine Hestouriser page called Which Recipe?“ Gpen the Input (Touch) tab and add this function to the Up command, pspstr (i, "controlsimits", Recipe) Note: The numéri@urgument is the Object AN of the Cicode object. You will need to check your own AN number. ‘Save the Page and compile the project. [project and test your new command. i. Opeithe page Pasteuriser i cli the new button Which Recipe?. The Cicode object wit \ eaigplay the current value of the Recipe tag “Glgade Programming Manual Release 1 229Returning Data from Functions Overview failure of the function. Both the PageNext () and Pagebisplay() functions return 0 (zero) if the page displays successfilllyy otherwise. they return an error number. For most simple applications, you can, ignore this return value. . Some functions return data that you can use in an expression of command. ‘The Date‘) function returns the current date as a sttingaeFo display the current date on a graphics page, use the following expression in a text object display value property: ‘The following example shows an entff'command event for a graphies page, using @ combination of two functions, “Th FuLiName () function retums the name of the user who is cuffrently loggied in 10 the run-time system, passing this name to the calling functiom,P To set the Startup Parameter The above form will display Hell lo World in a message box on startup, Continued on next page “Bilcode Programming Menual Release 1 233Starting Functions on System Startup, Continued Exercise 2-14 Step _[ Action % 1 | Display @ message that says Hello World when the project, starts. iii, Open the Computer Setup Wizard the Custom Setup to go to tho Startup Functions Setup. : uP os Selec sre nosy he statu actors fr wach component. Continued on next page CitectHMUSCADA Version 7.0, August 2007Starting Functions on System Startup, Continued Exercise 2-14 (continued) Step_[ Action 7 vi. Finish the Computer Setup Wizard and yun (cont) g vi. Once the project has started this méssage will appear Programming Manual Release 1 235Summary Summary Questions In this chapter you have covered the following topics: > > cr 7 v vwy Commands Setting Variables Expressions Multiple Statements Getting Operator Input Calling Functions in Commands and Expressions” Passing Data to Functions Passing Multiple Arguments Passing Numeric Arguments Passing Variables as Arguments Returning Data from Functions Starting Funetions on System What is a Cicode expression What chat. is used to combine several tasks? What is the 3 Ning a function? Cent What is the FSi of How de you s losing a tag in double quotes? ea apie startup function? CitectHMVSCADA Version 7.0 August 2007Overview Introduction Contents Chapter 3: Variable Operators Cicode is used to manipulate data and perform tasks. Data manipulation is achieved using five classes of operators. These aretthi he l, Bit, Logical, Relational and Format operators. In this chapter we will leam how to use the opettors in each ofthe different classes. This chapter contains the following topics: Topic See Page Mathematical Operators 3-2 > Logical Operators 3-4 > Bit Operators 38 > Relational Operators! 39 Format Operator 3 3413Mathematical Operators on niimeric Calculations The standard mathematical operators used to perform cacti Fhe available variables such as integers and floating point numbers. mathematical operators are: Operator Description z + Addition (for numeric value) s + ‘Coneatenation (for string varidbles) = 5 ‘Subtraction Z ¥ Multiplication ae 7 Division MOD Modulus (Remainder) How to TAG_1= TAG_2 NOD 100 Then if TAG_2 is 101, then TAG:4, becdiiés equal to 1 (the remainder after TAG_2 is divided by 100). % How to Example - Prompt ("the vall@ige Tag 1 ts, * + rerostr (tag t)) i, a Naa Vere Wise string This is a string llowed to be passed fo the Prompt{) function and one way 'AG_A can be displayed is to use concatenation. Note that pe of TAG_4 is an integer we need to convert its type to a can use it. Hence the use of the function intToStr(. Continued on next page CitectHIMISCADA Version 7.0 ‘August 2007Mathematical Operators, Continued Exercise 3-1 “Geode Programming Step Action, Greate a button that will porform a ealculation'using thie MOD operator. a i. Open the Chapters page and create a button called Modulus under the heading Chapter 3 ii, Open the Input (Touch) tab and pi: this expreggion in the Up command. TIC_P2_PV = TIC_P4_py MOD Greate a button that will perform a Congatenation. i. Create a new button called: Goncatenation ii, Open the Input (Touéhi) tab are’ Bilece this expression in the Up command, = Jig. Change the value of the TIC_P4_ PV tag to 43 alick the Modulus button and check the result wv i display tue Concatenation button. This message box will ‘Shutdown your project. Maral Release 1 33Logical Operators “eThe Tests an Logical operators can be used to test the logical state of an operant Operand return result after the test can only be TRUE (1) or FALSE (9), The three logical operators are: ‘Operator Description nr AND, Logical AND OR Logical OR . NOT Logical NOT XOR Logical XOR CitectHAWUSCADA Version 7.0 ‘August 2007Logical Operators, Continued Exercise 3-2 Step [Action 1 | Test the AND condition. i, Create a new button called AND Cone Chapter 3 heading. e ii. Open the Input (Touch) tab and ada this expressign to the Up command i Agitator_Silo_V= Agitator Alfast_v AND centrifuge_Clar_v Save the page and compile ti 3 __| Run the project and test the AND condition. |. Turn the tags Agitator Alfast_V and Centrifuge_Clar_V OFF. Click the AND Coinditienbution. Since both conditions are FALSE the Agitater_Silo_V will be OFF ii, Turn the At or_AlfastVON. Since only one of the conditions is TRUE,the Agitator_Silo_V will still be OFF. ‘il, Tugn the Centrifuge Clar_V ON. Now that bath conditions are 1 Agitator_Bilo_V wilt turn ON Manual Release 1 35Logical Operators, Continued Exercise 3-3 Action Step 1 Greate a text object that will change its value based on tl condition of an alarm property tag. Condition A will display the property is in its HIGH OR HIGHHIGH state. Condition B will display if the property is in its LOW or LOWLOW state. i. Go to the Pasteuriser page and open the properties of the text, object Normal ass il, Go to the Appearance (Display Value) tab. Choose the Type Multi-state and fill out the properties as shown below [Ea] niga Sa Te Sav@:the page and compile the project. Run the praject and test the OR condition. Open the Pasteuriser page Change the value of the Holding Tube tag by using the slider. Check that the text object changes when the Holding Tube Alarm changes into any of its High or Low states. It will display OVERHEAT if the state is HH OR HH and COLD if the state Is LOR LL Continued on next page CitecthiMUSCADA Version 7.0 August 2007“lease Programming Logical Operators, Continued Exercise 3-4 Step ‘Action Greate a digital alarm that is triggered wheH@), digital tag is turned OFF. » Digital Alarms from the menu. ‘i Ad the following atarm to the forms Open the Citect Project Editor and/ehoose Alarms. ‘Alarm Tag | Alfast ‘Alarm Name | Alfast Agipator Off ‘Alarm Dese | Alfast Agitaror @TOPPED VarTagA | NOT Agitato® Alfget_V ‘Compile and run the ject i. Open ‘haastouriser pag a Agitator OFF ‘The Alarm Toolbagiat, the bottom of the page will display the new alert. Sy eg turn the Alfast Shutdown the prajecti= Manual Release 1 37Bit Operators ‘Standard bit operators are provided with Cicode. These are: ‘Operator Description BITAND Bitwise AND BITOR Bitwise OR BITXOR, Exclusive OR How to ‘The bit operators can be used on words or individual bits. Example - 11011 AND 1101 becomes 01001. CitectHMVSCADA Version 7.0 August 2007Relational Operators To test the relationship between (wo values, the relational opgratots: used, Operator Description = Is EQUAL to => Is NOT Equal to = IS LESS than > Is GREATER than <= Is LESS than or Equal to = Is GREATER than or Equal to Continued on next page ~ “Gigode Programming Manual Release 1 39Exercise 3-5 Relational Operators, Continued Step_| Action reaches a value greater than or equal ta3- i. Open the Citect Project Editor and Alarms from the menu, ji. Add the following alarm to the form. © ‘Alarm Tag [Cooi_& ‘Alarm Name | Coolant Ovextieat ‘Alarm Dese | Coolant Tén 3 3idea Expression | TIC_Cool_BY, Create an advanced alarm that will be triggered when ose Alarms: >Gelvanced 2] Compito-and ran the praject._ Open the Rasteurisatigh page, {Change the vai the CBlant to 3 oF more li, The advanced alarm wil be triggered CCitectHiMU/SCADA Version 7.0 August 2007Format Operator How to agers ‘The format operator is used to convert numeric values into forsiatted’stxings for display purposes. % Operator Description (colon) String Format > To convert a numeric value to a string we Would TAG_L:#eHa.# In this example, TAG 1 will be displayedias four digits before and one digit afier the decimal point. This type of formatting can be used when displaying a number as a string, We commonly use this ft Feport format files. ontinued on next page ‘Manual Release 1 anFormat Operator, Continued Exercise 3-6 Step ‘Action Use the format operator in @ massage box tS Gisplay the Wale ofa tag. i. Go to the Citect Graphics Builder ang open the Chay ll. Greate a new button called Pasteuriger 3 undernea Chapter 3 heading Wii Open the Input (Touch) tab and add this: command Save and compile the project, RUN theiproject. i. Open the Chapters gaye anditlick the Pasteuriser 3 button. The message box shou this. CitectHMSCADA Version 7.0 ‘August 2007Order of Precedence of Operators In Cicode each operator has been assigned a precedence. This dfteansithat an operator of higher precedence will execute before operators of lower precedence. The precedence of operators from highest to lowest is: ‘Order | Operator so] 20] ma] afer] |e |ro] — iS Example — If'we have the expression: TAG_1 OR TAG_2 ‘The NOT TAG_3 is evaluated fitst, which is logically ANDed with TAG_2, the result of whils logically ORed with TAG_1, This is equivalent to: (TAG_t OR (TAC ID (NOT TAG_3})) iy, te re Note: Having the brackets shows more clearly the order of precedence taken Continued on next page “Gieoge Programming Manual Release 1 38Exercise 3-7 Order of Precedence of Operators, Continued Step | Action Statement. - Up command Agitator Alfast_v Create a button to test order of precedence, i. Open the Chapters page and create gnew ‘button aited . y il. Open the Input (Touch) tag and entef, this expressiof into the centrifuge _Clar_V = NOT Agitator_silo_v AND resulting value of the Centrifuge_Clar_V “Test the logic of the expression. YGhlige the values of the Agitator_Alfast_V and/‘Agitator_Silo_V valves and check the CitectHMVSCADA Version 7.0 ‘August 2007Summary Summary In this chapter you have covered the following topies: Mathematical Operators Logical Operators Bit Operators Relational Operators Format Operator Order of Precedence of Operators vwvvvy Questions The following questions are used to ched Name two of the classes of of How do you test the relations! matted strings? vvyvy z 2 = 8 S 2 g 3 g Programming Manual Release 1 315Chapter 4: The Cicode Editor Overview Introduction The Cicode Editor is a fully integrated programming “én specifically designed for writing Cicode. The Cicedé’editor.als debugger that will make writing and debugging y help for Cicode functions that will allow you to Cicode easy, a \d help on Cicede functions instantly. ‘The Cicode Editor has also been upgraded to CitectVBA. Contents This chapter contains the following topic: Topic See Page > How to Start the Cieode Editor 44 > Goto Errors on Line Numbers 44 > File Navigation aq > Baiting Tools 410 » Function Tools: 4-15 > Preferences 418How to Start the Cicode Editor ‘The Cicode Editor can be started by clicking on the Cicode Egitor*button from the Citect Explorer Cee roletalal aiel all gall Fxampieis.¢ habeas tugs STRING 8 FONCTION tecttes Uaschday (2 Breve STRING sbey J bay 9STRTOINE(sBay) : 3 Gfibay<),.08 (Day) >6) THEN SeosagetErece”,"Tavalia number enterec Breakpoint To get help om iy, of the icons go to Help » Cicode Editor Help from the Cicode Editor. One€in the help click the menus, buttons, and other screen elements for anexplanation,. (You can also use the Tool tips). Continued on nexi page CitectHMUSCADA Version 7.0 ‘August 2007How to Start the Cicode Editor, Continued Exercise 4-1 Create a new Cicode file Step_[ Action a 1 Go to the Cicode editor and create a new Gicode file called Training. This will be used for your own Cicode. i. From the Cicode Editor cick on the Oil button. From the menu select Eile » New | li, This dialog box will appear prompting you to choose the file type. Choose Cicode. Jil. Save the new file as Training, “Bicode Programming ‘Manual Release 1 43,Goto Errors on Line Numbers Compiler Compiler Errors support allows the rapid finding of Cicode compiler errors, Errors a When a Cicode error is encountered a compile error dialog fort ‘will appear as follows: —<— of eda ae Ra Tete [ENGEaTsetFucetTronngc ee conta ESRF Cros TTS ae | oe | eco: 1 F deletes In the context field the line number where thie-error occurs is shown as well as { } around the cause of the error. How to > To go to alline containing amerror Click the GoTo button 10 een, the.Cicode editor, The Cicode file containing the error will open the at the liné'nimber where the error occurs, Compiling and Running Yean also compile a project without running it by clicking on the Complile PI ution Continued on next page CitectHMIISCADA Version 7.0 ‘August 2007Goto Errors on Line Numbers, Continued Exercise 4-2 d Step_| Action 1 | Greate a new function to test the com i. Using the Cicode Editor open the Training. te you previously created type in this sirmple funct FUNCTION S angevalue {} TagValue~10 END Save the file 4 Fe Da ape ee | Fe me Cente [Ere gata Tapas END age | tee cor! 1 F Deis ‘sf Continued on next page ‘Gieade Programming anual Release 1Goto Errors on Line Numbers, Continued Exercise 4-2 (continued) ‘Action Wy, Glide on GoTo. This screen will appears FUNCTION cameras 2 Breakpon tae [ itectHMUSCADA Version 7.0 ‘August 2007File Navigation File Window ‘The Cicode Editor has been enhanced to make editing your code qi¢ker and” easier. One of these new features is the File Window that allows you toView files in a tree view. (= Cesare TRENDERC.Ct Ej Sano bes 5 wera Fes Open Pronet [AlProbis 2 Open Files ‘The Open Files tab will list all oe that are currently open in the Cicode Editor, The “i Open Files tab is that it will display the full path of the file. i a ‘ag Continued on nevi page cs~ “Cleode Programming ‘Manual Release 1 arFile Navigation, Continued Open Files ‘his feature is useful when you need to open files of the same natie. from ” (continued) different projects. The Cicode Editor's Window list will display the name-of the file, Using this view it is impossible to differentiate between files of the same name from different projects [i Hele, ‘cca Te ranges “Gove a 2s 1 Beanpot Dare 3sonele.bas PILE Example DESCRIPTICH: This file con sana am C\gageo (CAEFSAi sen ExampaSompie be CAGBIRGH HAF sompleSagle Ct TF _fxexpie( INT Bie) Continued on next page CitectHMUSCADA Version 7.0, ‘August 2007File Navigation, Continued Open Project All Projects selected in the Citect Explorer. Files may be opened from thig tab by déuble clicking the file name, “S Fle a ee etves Abmes are ct ) maewencct =} Soros The All Projects tab lists_all code. files of ali projects that are linked to the Citect Explorer. File mag be ‘opened frem this tab by double clicking the file name, re BCA eae Eaemene ‘lame El owmea —.Ed ing Tools Dockable The Cicode Editor allows the user to manipulate the display‘areain the Windows and — workspace. Windows and toolbars are easy to show and fide by right ” Toolbars clicking on the top of the menu area, This will activate a popup menu listing, the available toolbars and windows. The toolbars,anid-svindows'that are currently displayed are checked in the list. _ : ls ¥ Otest eat Debus 1 Fornat + Wow 1» Bookmarts Castemisable frealport Wind ‘Oupak Weds ‘Gobi Vriele Windows ‘Sade Widow Tveed Window Campi ors Wars ‘checbn watch Window Fes | | Moving Toolbars Holding the left mouse butt ~ Move Handle Ci and Gragginigihg ool ‘to a new location. ss ge | (ease IBA |) Aly all] Continued on next page CitectHiM/SCADA Version 7.0, August 2007Editing Tools, Continued 4 Indent and ‘A formatting toolbar has been added to the Cicode Editor 16° Indent and Comment Comment lines of eode. Outden Uncomment How to > Te comment code Highlight the lines of code you 4vish.t6 Change then press the appropriate button. For Example to comment several lines highlight the code, 11 canecax™@ opgeceDytlane (s0bjectNeme) : 11 @iieo ior Broo jectGetPropecty (Citleter, "BackColor") : 11 @3F oldggior = 255 THEN Jb _opy@ecSerProperty (CiMever, "BackColor™, 8421376); fae 7) “SgaopjectserProperty(Cimeter, "BackColor", 255}; ez/ END Continued on next page “Giga Programmi Manual Release 1 an rogrammingEditing Tools, Continued Bookmark and Breakpoint Indicator Bar Bookmarks and breakpoints are useful tools to use when ait debugging code. ‘The bookmark and breakpoint indicator bar igfostioned ep 7 the left side of the code window. FUNCTION : Bookmark—————> [) Createcsmerer( er sa, TMF Ya, TNT 2g INT 2) OBJECT CiMeter; = STRING sCiMfeterClas: STRING sEventClass; STRING sObjectNames INT nAN? Breakpoint ———> Insert a Bookmark by right clicking on the ifidieator bar. To remove the Bookmark right click again on the bookmark. [eft ¢licking on the indicator bar will add and remove Breakpoints. A nh Bookmark toolbar has also been added to the Cicode Editor | Alatalal| This Toolbar allows you to add or and previous bookmarks. Cantinwed on next page CitectHIM/SCADA Version 7.0, ‘August 2007Editing Tools, Continued Exercise 4-3 PO Step | Action 1 Use some of the new editing features to eféate a new Aative X function. |. Use the All Projects tab to open the file Sample.¢kn the Example Project { ii. Highlight and copy the function creapecietert, hen place a bookmark on the Indicator Bar - lil, Paste the copied text above the original CreateCiMeter() text iv, Highlight the pasted text then use Ctrl-H to open the Replace form. Replace the text CiMeter itn WebBrowser in the selected toxt # Fedniat fEteep SI Gpittes place th. atone al : z Mach ery F Matches | C Whats & Sehcion rl Replace the. cd in these lines: with this text ‘Vitgy ~“AnzyNane ("WebBrowser") ; DepSEtTip(nAN, "My Web Browser") Vi, Select several lines of text in the new function and click the Comment == button. If you cannot see the Comment button | Fight click on the tootbars and choose Format from the options | displayed in the menu. Uncomment the lines of code by highlighting the text and clicking on the Uncomment button: ‘Continued on next page “Ciegde Programming ‘Manual Release 1 413Editing Tools, Continued Exercise 4-3 (continued) Step ‘Action 1 (cont) jent Bly ston’ vil. Select some lines of text and click the: Move the text back to its original logation by highiighting then . clicking the Outdent = F putton. 5 vii, Set a bookmark next to the new function by right licking the Indicator bar next to the new code. Press:F2 onsthe keyboard! The cursor will stop at each of the bookmarks. ‘Comment out ail the lines of text in the new function. ‘Save the page. TOT CitectHIMUSCADA Version 7.0 ‘August 2007Function Tools mm List in A context sensitive function list is now available. Right click’ the file and Fan de and choose List Functions from the menu or press Ctri-Space on the keybaard. CiVBA ‘This will display either a list of Cicode functions or a list af, CitectVBA functions - whichever is appropriate for the current files : (STG Tac eSSCONT Gincionboniaai ee Sir aie a IM Timersanigne nae" | MB tinesee ecttwoa of Cicode Funetion List ~CitectVBA Function List The function you need maybe found by-typing the name of the file or by using the scroll bar. As you typeithe name of the function the list will scroll down to the first function whose initial characters match those that you have typed. Notice that the, tool tip becomes a prompt displaying the complete function with all parameters When the function is double clicked it is inserted into your document {86 msertion point. Intellisense The previous example, displays the autoprompt appearing in the tool tip when AutoPrompt the function dist. is displayed. The Autoprompt will also appear when the function agd opening, bracket has been typed into your document ckBoxt SublGhecK6 cx stan xpos. sta y pos, wath, hei ‘Continued on next page “Cigode Programming ‘Manual Release 1 445Function Tools, Continued Exercise 4-4 Step Action Open the file Training.ci that you cr chapter li, Create a simple function to calculate the area of a circle REAL FUNCTION AreaOfCircle (REAL Radius) sw RETURN (3.142 * PoufFRaddus,2)); END ii, Save the file and compié e iv. Close the file Traini Open the Cigode_Milk=§ projet tree on the Open Project tab and the file Training.ci will.peslisted Se Desi ice fen the Tile Training.ei by double clicking the file name from Je Open Project list. The name of the function will now be jed in blue. function to test your new user function AreaOfCircle(). Underneath the code for the AreaOfCirele() function type in this code. i FUNCTION Preet () Continued on next page CitectHiMSCADA Version 7.0 ‘August 2007Exes Func! Nn Tools, Continued 4-4 (continued) Step_| Action om 2] 11. The next line of code will est the new userfanction’ = (cont) AreaOfCircle(). y Feae0) Avenceesre tet iii, When the new function Is typédwith the opening bracket the complete function is displayed aga tgol tip, ye iv. Delete the text AreaOfCirele(from tA line, This time right Shak on teins and choaseGgt Fugetions from the mest unre ‘reat [REAL esBiCiSaPE aszchesnse janaChasausnree v sleicode functions and any user functions you have {and compiled) will appeat in the Ist. Clicking on one Hfanctions wil dsplay the complete function as a too! tip © aL.the insertion point. re.” Ise the END statement to finish the function, FUNCTION st () AreadfCircle (20) END “Save the file and compile. Manual Release 1 a7Preferences Changing the The code window may be customised to display your own preferences for Look ofthe viewing code. Right clicking on the code area and choosing Preferences from the menu displays the Preferences dialog, Code Window The Preferences dialog allows the usef to ingzease the Tab Width and remove the Auto Indent, Syntax Colouring and Keyword Case by removing the ticks so allay the user to change the font attributes Con wed on nex page CitectHHMUSCADA Version 7.0 August 2007Preferences, Continued Step_| Action |” 1 [change the Preferences of the Gicode Editorilising an @Histing Cicode file. i. Open the file Sample.ci from the Example Project ji. Right click on the code window and choose Preferences from the menu iii, In the Preferences dialog box change the tall click OK ith to 8 then A neath a tab val ‘move to the right, iv. Open the Préferefiees dialog box again and cick the Font.. button 2 Change the font then click OK to continue ‘Continued on next page Programming Manual Release 1 419Preferences, Continued Exercise 4-5 (continued) Step_| Action 1 vy. Remove the tick from the Syntax Colouring heck box then (cont.) click OK. Restore the Syntax Colouring by adding aitick 16 the check box. A vi. Choose the Comments element fromthe Colors tist ip the rawan [ IF Aube indane SyeaeCeleng vii, Choose theitrings ei attributes. “Wigs wnt and check the Bold and Italic aby FO CitecttiMUSCADA Version 7.0 August 2007Summary Summary Questions fe Programming In this chapter you have covered the following topics: > How to Start the Cicode Editor Goto Errors on Line Numbers File Navigation Editing Tools Function Tools Preferences vvyvvy ‘The following questions are to check yo ing. > How can you view files easily? > Why use bookmarks and breakpoiijts? > How can you change the lookof indow? Manual Release 1 421Overview Introduction Contents, Chapter 5: Cicode Functions CitectHMV/SCADA is supplied with over 600 in-built functions, One or a combination of these functions can usually perforif Tigst, taskSin your system. However, where system functionality eannot be achieved with in- built functions, you can write your own functiong. \ A Cicode function is a small program that maj.contain a collection of statements, variables, operators, conditional executors:andéfiinctions, in fact, of all the elements of Cicode. This chapter contains the following topics Topic Writing Simple Functions Function Elements Public and Private Funétigns Declaring Functions vwvwve Naming Funeti p Statements _ ~ > Void Functions v » Cicode Vatiables > Convertir Sige Cicode Variables > Includg File aWriting Simple Functions Cicode functions can have many purposes. Some functions/are’ simple, created to avoid a long command or expression. tis For example, the following command increments the vafiablétag COUNTER: Execute Command IF COUNTER < 100 THEN COUNTER = COUNSER + 1; ELSE COUNTER = 0; 7 END aa This command would be easier to use (and te-use) if it was written as a funetion that can be called in the command: °°" ‘The function is written in a Cicode file Se, Syntax Function Public ‘The Scope of the function — can be Public or Private FuNcTioN Tells the compiler where to start ‘ compiling the funetion Tnecounter What the function will be called TF COUNTER <"8Q0. THEN ‘The code which runs when the cost coffirme + 1; | function is calfed suse @ Z IE % Ends the IF statement This indicates to the compiler that Z the cade is finished iy, The indented code is identical to the long command above. The “compiled code executes the statements one at a time, just as it does ontimied on nex! page CitectHRWSCADA Version 7.0 ‘August 2007Writing Simple Functions, Continued Function To leam how to write our own functions we need to get the Syntax ‘We will start by looking at a simple command in pseudocode, Imagit ook like this: HELLO standup () IP told THEN stand Up; ELSE Remain Seated; FINISHED GOODBYE fe Programming ‘Warual Release 1 53Function Elements Four Elements — Functions contain four basic elements. These are * Scope * Declaration * Name CitectHRV/SCADA Version 7.0 ‘August 2007*@ieade Programming Public and Private Functions use public explicitly, In other words, they can be shared across Cicode files and called from all pages within the project. Sometimes yout might want to make a function private in order to hide it from globalisage.., This theans that it is only available within the file that it is written; To make a function Private you must prefix it with the word PRIVATE, Ino scope is stated then it is PUBLIC by default. However, for the sake Of clarity in te first few examples we have left the word PUBLIC in place. Public (Scope is PUBLIC or PRIVATE) FUNCTION Funct ionName () Statement; END Manual Release 1 55Declaring Functions Function and In Cicode functions must be declared. In other words you need, End Statements know where the beginning and end of the code for a functi declare functions with the FUNCTION statement: Scope [7 Funcrron Matching Funct ionName () ed Statement; io L_ eno ‘You must finish your function with the E} CitectHMISCADA Version 7.0 ‘August 2007Naming Functions Each Function Needs a Unique Names “Giggde Programming After the funetion is declared you must give your new functiort can use up to 32 characters to name your functions. You can use any Valid name except for a reserved word. ‘The case is not important (othe Y Hints & Tips: When you are writing functions itis a good idea to uge a mixture of upper and lower case for clarity. For example, MyPageDisplay(fis easier to read than or MYPAGEDISPLAY(). = , mypagedispla A funetion declaration must contain parentheses () for enclosing arguments (more about arguments later), whether or notitiases them, for example: SCoPE FUNCTION Funct ionName() ee Statement; END 4 Manual Release 1 57Statements What the Statements are the whole point of what we are doing. The statement igeth Function is code that runs when the function is called. For example if you. e Going to Do function to show a prompt when the Mash Pump is on then the. function would be: “i = PUBLIC FUNCTION StatementExample () IF MASH PUMP THEN PROMPT ("Mash Pump ON’ Matching Pair ELSE ‘yf Z| The Statement PROMPT (“Maslt: Pump “OFF” ) ; CitoctHMAUSCADA Version 7.0, August 2007Void Functions Many functions return some value or confirmation that the fungfion Has, been’ completed. However, Void Functions, when called, do not return any datisto the calling function or command line. The ShutDown() com cused in the configuration course did not return information or-datajit.only performed some action, Void functions are typically used to’ perform a Set of tasks on buttons or keyboard commands ete. The functioss that we have been looking at so far are void functions. « 2 PUBLIC FUNCTION voidexample () IR IF MASH PUMP THEN Prompt ("Mash Pump ontyiy ELSE END Note: Nothing is retur performed that displays on the prompt line whether the pump is, niniiing or not To call this function w8jequld execute a command such as: Manual Release 1 59Void Functions, Continued & Exercise $-1 Step ‘Action Create a function that will display the dateland Gime string tags. 2 i. Go to the Cicode editor and open the Training.ci fil created earlier 2 ji, Begin your function by defining the PUBLIC Hil, Next Dectare the function PUBLIC FUNCTION iv. Add the Namely puentc runction “i MyDateTime () vga tne Statements that wil display the date in the Variable tag MISC1 and the time in Variable tag MISC2 Date (3); Time (1); End the function PUBLIC ‘FUNCTION MyDateTime () MISCL = Date (3); MISC2 = Time(1); END vii, Create a button on the page Chapters to call the function Continued on next page CitectHMVSCADA Version 7.0 ‘August 2007Void Functions, Continued Exereise 5-1 (continued) Step_[ Action 2 | Greate 2 function which may be used fo gona. an ‘augible alarm with a popup message on the Y a i. Open the Training.ci file and writg_a function cated AudAlarm(). This function will play a wav file and display 2 message box, . 5 li, Define the Scope, Declaration and Nv Jaurenew function. PUBLIC FUNCTION AudAlarm(} oe : iii. Use the function DspPlaySoundijite play the wav file tada.way. The way'file isJogated! in your project directory. PUBLIC FUNCTION AudAlarm() Dalpay Sound (~ §RON} 0 THEN #5 PageDisplay (gsDefault: age) ; RETURN istatus; END ie - The variable gsDet eae tet file in the system. be used in any function of any Cicode Not use Global variables with caution - if you have many being used by many functions, finding bugs in your ‘ome very time consuming. Use Local variables Continued on next page CitectHMUSCADA Version 7.0 August 2007Cicode Variables, Continued Module Cicode A Module Cicode variable is specific to the file in which it is deca Variables means that it can be used by any function in that file, but not by functiong.in other files. By default, Cicode variables are defined as Module, therefore fimctions that need to use it, for example: j MODULE STRING msDefaultPage i This declares the value of the Defatikt raga! Mimic Page. It can then be used in al. current file. Example - PUBLIC INT FuNcTron : MyPageDisplay(STRiNs sPagé) in istatus; < {status dpasebiplay (erage) ; IF istatud a, 0 THEM PageDi Spilay (msDefaultPage) ; ae 4 nevi istatue, i END y PUBLIC Fonction DefaultPdgeDi splay () BageDi splay {meDefaultPage) ; END % ith caution - if you have many les being used by many functions, finding bugs in your -an become very time consuming. Use Local variabies Continued on next page “Ciegdle Programming ‘Manual Release 1 517Cicode Variables, Continued Local Cicode Variables A Local Cicode variable is only recognised by the fun declared, and can only be used by that function. You must declare Local variables before you can use them. & Any variable defined within a function (i.e. after the Sir tion namie) isa Local « variable therefore no prefix is needed. it Local variables are destroyed when the function exits. Local variables always take precedence over Global variables, Module variables and Variable Tags. If you define a Local variable in a function with the same name as a Global or Module variabley'the-Local variable is used; the Global/Module variable is unaffected by the funetions. This situation should be avoided, however, as it is likely to sefiont Bon, ambiguity and a maintenance nightmare. Example - PUBLIC INT FUNCTION LocalExample() @. INT Average * iaverage 9: RETURN iAver: & ‘Continued on next page CitectHiMUSCADA Version 7.0 ‘August 2007Cicode Variables, Continued Variable Naming Standards Variable Tags *Giose Programming ‘The variable data type needs to be named when the variable is declan so it has become a convention to label your variables with a small letter prefix. For example: ‘Type Prefix |Description = INT (G32 bits) i index, loop counter REAL G2 bits) real type variables STRING (255 bytes) OBJECT (32 bits) string type vari ActiveX control ola See Also: For fre formation about Naming Standen 869)Ctect Hep Topics - Variable Naming: Cicode Standards. You can use any variable, that yoou ae ‘defined in the database (with the Variable Tags form) in youtfunctions. ‘These were used in Exercise 1-1. To use a database variable, specify the.tag fame: s & Where is the name labase variable, For example, to change the value ofthe database variable PUMP at run time, you would use the following stdement in your function: PUMP = 1200; 1c of PUMP to 1200. ‘Continued on next page Manual Release 1 519Cicode Variables, Continued Biz Exercise 5-2 Step_| Action 1 | Greate another Audible Alarm function using Woeal variables, i. Your existing function should look soniething like this. FUNCTION AudAlarm(} DspPlaySound (* [RUN] :Tada.wav" , 0}; Message ("Alarm”, "Too Hot”, 48); END pe f e4 ji, Copy and paste the function tindgfneattt your original function and then rename your copy ‘AudAlarm2) ii, Replace tha arqumentgi@fihe tunctlens with local cicode vatiables. FUNCTION aAudalarm2 () DspPlaySound (5! "a Comtinwed on next page CitectHMUSCADA Version 7.0 ‘August 2007Cicode Variables, Continued Exercise 5-2 (continued) Step [Action ray (cont.) Call the function from a button on the,GHapters pagay,tiow that Cicode variables have been uséd it is possible to input the filename, title and message wher.the function is placed on the button. ‘This means that the function may be used repeatedly with different arguments. 2 AudAlavm2 ("C:\Windows \Media\Chimés.Wav", "Holding Tube", "Too Cold") pSave th page and compile the project. [2 __| Riitighe project to test the new function. ~Glegde Programming Manual Release 1 521Converting and Formatting Cicode Variables Data Types Data types are handled quite rigidly in Cicode. If you wish to inpiit nitabers using the Input() function and then use those numbers in a caléulation yowy will need to change the data type from a string to an integer or real, . ‘The reason that this is necessary is because the Input()sfinkétion returns, data that is a string type. Strings cannot be used in mathematical calculations. Conversely if you with to display the value of angeger or real fn a report you will need to change the data to a string type. The process of changing a value from one data typetgzanether is called Conversion. CitectHMI/SCADA provides four functions for converting integers and real numbers into strings, and vice versa. ‘Type Function eos 4 IntToStr), Converts an integer vatiabl¢ into a strinj RealToStr) Converts a floating-point Variable into a string SuToin() Converts a stringgint an integer variable. StrToReal() Converts a string intow floating-point variable. There is also a series of Time afidDate fignctions that convert time variables into strings for display purposes.“ Example - - } £ a [Type Function TimeToSt() a, | Converts a time/date variable into a string. StrFoDate() Rarer a "date" string into a time/date variable. Continued on next page CitectHMW/SCADA Version 7.0 ‘August 2007Exercise $-3 ‘Action Step 1 Use the Realfo8tn) function to display thewalueiof the Holding Tube tag in a popup message. i. Open the Chapters page and creale a new button galled Holding Tube ji, Add the Message() function to the Wegommang Message ("Holding Tube”, TIC_Hold_Pv, 64) ili, ‘The problem with this furietion i thatthe TIC_Hold_PV tag is type REAL and the Message (4functign can only display a string, This is where the RealToStrf} function must be used This function has threeargumeénts the floating-point number Xo convert, the width of thesstring and the number of decimal places, iv. in ia inal Message() command replace the TIC_Hold_PV tag witlt the,RealTaStr() function above, ‘The resulting Se expression Wt ike this. “Cid Programming Segtiolding Tube Manual Release 1 523Exercise 5-4 Step. Action Create a function that will allow you to use afiinput box to, enter a string value that will then be placed into an integer tag. 1. Greate a new function called Operafprinput) FUNCTION Operator Input () Ji, Add the Input() function. FUNCTION Operatorinput () . Input ( "ENTER" Evite Wi As the Inpétijifunctior’ returns: string create a Cicode variable ‘to temporarily st@fe.the value. Call this Cicode variable sTag. nput ("ENTER, "Enter a value", *"); pIC_Silo_PV =eTag; Convert the variable sTag into an Integer by using the funetion StrToint() FUNCTION OperatorInput () STRING sTag; sTag=Tnput ("BNTER", "Enter a value", "); LIC_Silo_PV =StrToInt (sTag) ; END ‘Continued on next page CitectHiMISCADA Version 7.0 August 2007 &Converting and Formatting Cicode Variables, Continued, Exereise 5-4 (continued) Ties, Step_| Action 2 | Save the file and compile. 3 | Test the new function. Open the page Chapters and add this function inte the Up Command of the LIC_Silo_PV text object. “Gigode Programming ‘Manual Release 1 (Continued on next page 525Converting and Formatting Cicode Variables, Continuet Exereise 5-4 (continued) (Step [Action [5 [Run the praject i. Open the page Chapters and left cligk the LIC_Sile object, The Input Box will appear. Erie ake Se sae Ce] seesf gh 1. Enter a number between:0 and 4G06' then click OK. Ii ga The LIC_Silo_PV numeric object will aisplay the change in Walue of the LIC_Silo_PV tag © Vie, sito Pv? asa Seer fo CitectHIMUSCADA Version 7.0 ‘August 2007Exercise 5-5 * CiGode Programming Step | Action 1 | Display a time variable on a page using umeformat. i, Go to the Chapters page and opegthe Clarifier Runtime numeric object. li Use the function TimeToSte() so tal the tag wil > isplayed in the format HH:MM:SS. Y Hints & Tips: The Clarifier Runtime object is Help entry Accumulator Pro} Y Hints & Tips: Check the modg.f the TimeffoSti) function in the GtectSCADA Help and use an option thal displays thestime variable in seconds. 2 | Run your correctly, ‘Manual Release 1 527Include Files 1d Character There is a maximum number of characters that you can type in aCommind or Limit Expression field (usually 128). If you need to include many.¢ommands 6r expressions in a property field, you can define a separate Include File that contains the commands or expressions, 4 ‘An Include File is a separate and individual ASCtE text file containing ONLY one sequence of CitectHMISCADA Commands or Expressions that would otherwise be too long or complicated to type into the ommand.6t Expression field within CitectHMI/SCADA. The Include File namé'ig entered instead, and the whole file is activated when called. When you compile the project, the commatids ‘Giexpressions in the Include File are substituted for the property field, just asif you had typed them directly into the field, es : How to > To configure include files: Use any text editor to createithe, text file, sueh as the Notepad ey editor supplied with your WindoWs:package. Enter the name : of the Include File (in either upj a: or lower case) in the property, in the folidWing format: NOTEPAD.EE @ Where filenames ARE part of the properties (cx ay valid DOS file name, Note that the <> characters You can use the Include File facility with most £ Av be previous example, the SETVARS.CI Include Fite would contain commands to be substituted for the Command property when you compile “SSepysiir project, for example: gPV12 = @ pv22 = 20; pv13 PageDisplay ("Mimic") ; ‘Comtinued on next page CitectHIMIISCADA Version 7.0 August 2007