BASIC Programming manual V1.4.
CONTENTS Introduction to Basic Programming.....................................2 Basic Features..................................................................... 3 Basic Fundamentals............................................................3 Program Execution....................................................... 4 Error Handling................................................................... 4 Grammar............................................................................ 4 Comments............
Contents LOWER$ ( )....................................................................... 33 LTRIM$ ( ).......................................................................... 33 MAX ( ).............................................................................. 33 MID$ ( )............................................................................. 34 MIN ( )................................................................................ 34 MINUTES......................................................
01 / 2 BASIC FEATURES & FUNDAMENTALS
Basic Features and Fundamentals The System 5000™ Data Collection Platform contains a built-in BASIC interpreter (as of firmware version 1.2.0) allowing for more complex operations on the data logger. Many traditional BASIC commands and features have been combined with a new subset of operations to create the Basic 5000 language. Basic 5000 is thus able to provide a familiar BASIC base while also providing direct access to the hardware and operations of the System 5000™.
BASIC FEATURES & FUNDAMENTALS Program Execution Basic Programs on the System 5000™ can be used as either Inputs or Outputs and operate in the same manner, being executed according to their associated Task’s priority.
Basic Features and Fundamentals Comments The REM statement (meaning remark) or apostrophe (“ ‘ ”) introduce a comment that extends to the end of the line. Notice that though REM is a statement as well, it does not require a statement separator (“:”) if used on the same line as another statement.
BASIC FEATURES & FUNDAMENTALS Control Statements and Loops Basic 5000 supports traditional control statements such as GOTO and GOSUB as well as single and multi-line IF-THEN statements and SWITCH-CASE statements. GOTO and GOSUB can jump to labels or line numbers within the code. Line numbers may be used in the Basic program, but they are not required. Loops are also allowed using FOR, WHILE, REPEAT, and DO statements.
Basic Features and Fundamentals File I/O Files stored on the System 5000™’s local file system can be accessed for reading, writing, and appending of data. The OPEN command allows files to be opened and assigned a number for use throughout the program. Using the INPUT and PRINT commands with the file’s assigned number allows Basic to read and write to the opened file. Other commands are also available such as EOF, LINE INPUT, SEEK, and TELL for further manipulation of files.
BASIC FEATURES & FUNDAMENTALS String Processing Basic 5000 provides a number of commands that allow for string manipulation and processing. Functions that return string variables contain a trailing “$” whereas functions returning number variables do not have a “$”. Functions such as LEFT$, MID$, and RIGHT$ can be used for extracting parts of a string. Separating a string into usable sections can be done with TOKEN and SPLIT.
Basic Features and Fundamentals Advanced Programming with Symbols In order to provide greater flexibility and reusability of Basic Programs on the System 5000™ , an advanced subset of commands, known as Symbols, are available. These Symbols allow program parameters to be modified and defined on a Task by Task basis through the touch screen interface. A single program could potentially be used for multiple purposes with the use of these Symbols.
BASIC FEATURES & FUNDAMENTALS The ‘GROUP: Symbol specifies where the Basic Program will appear in the Input/Output menus. If not specified or listed without a name, the program will be added to a “Basic Programs” grouping in the menus. The special case of “None” (case-sensitive and without quotes) may be used to not add the Program to a group but rather list Program alongside the other Inputs and Outputs. Any other name used will create and add the Basic Program to the given group name.
02 / BASIC COMMANDS & FUNCTIONS 11
BASIC COMMANDS & FUNCTIONS Basic 5000 uses a combination of commands and functions to allow more complex operations to be performed on the System 5000™. Commands and functions can both return values, though each is done in a different manner.
Basic Commands and Functions ABS (number) Returns the absolute value of the given number. var = ABS(-2.5) var2 = ABS(100) REM stores 2.5 in the var variable REM stores 100 in the var2 variable ACIN Used in conjunction with the GETVALUE command, ACIN requests a new measurement to be made on the AC-In port and stores the value in the given variable.
BASIC COMMANDS & FUNCTIONS ALARMS A parameter to the DATETIME function returning a string representation of the most recent triggered alarm time, formatted as “HH:MM:SS”. var$ = DATETIME(ALARM$) REM stores the most recent alarm e.g. “05:00:00” ANALOGX Used in conjunction with the GETVALUE command, ANALOGX requests a new measurement to be made on the specified Analog channel and stores the value in the given variable.
Basic Commands and Functions Multi-dimensional array: ARRAY myArray$(3,7) REM 2-dimensional string array (3 rows, 7 columns) FOR i = 1 TO 3 FOR j = 1 TO 7 myArray$(i,j) = str$(i * j) REM str$ converts a number to a string NEXT j NEXT i REM myArray$(i,j) now contains values 1 2 3 4 5 6 7 2 4 6 8 10 12 14 ARRAYDIM (array) Returns the given array’s number of dimensions.
BASIC COMMANDS & FUNCTIONS ATAN Returns the arc-tangent value of the given number. var = ATAN(0) PRINT ATAN(1) REM stores 0 in the var variable REM prints “0.785398” (PI/4) BATT Used in conjunction with the GETVALUE command, BATT requests a new measurement to be made of the attached battery and stores the value in the given variable. GETVALUE BATT, var REM stores a new measurement of the attached REM battery in the var variable BREAK Causes an immediate exit from a loop or SWITCH statement.
Basic Commands and Functions CHECKRETURN ( ) Returns the result (return value) of the most recent PRINT to either a serial or ethernet connection. If an error has occurred, this number will be less than zero. A successful PRINT returns the number of characters written to the open connection. This may be most useful for detecting disconnected serial or network ports. OPEN PRINT CEIL(4.7) REM prints “5” CHR$ (number) Returns the number’s ASCII character representation.
BASIC COMMANDS & FUNCTIONS CONTINUE Used to begin the next iteration of a FOR, WHILE, REPEAT, or DO loop. FOR var = 1 TO 10 IF (var = 5) CONTINUE REM “5” won’t be printed PRINT “ “, var; REM prints “ 1 2 3 4 6 7 8 9 10” REM Note: the semicolon removes the default new line (\n) REM that appears at the end of a PRINT statement NEXT var COS (number) Returns the cosine value of the given number.
Basic Commands and Functions DATE$ A parameter to the DATETIME function returning a string representation of the current date, formatted according to the System 5000 Settings (default is “MM/DD/YYYY”). var$ = DATETIME(DATE$) REM stores “12/31/2009”, inferring Dec 31, 2009 DATETIME Used to retrieve the current date, time, subset thereof, or alarm time. Available parameters are DATE, DATE$, DAY, JDAY, MONTH, YEAR, TIME, TIME$, SECONDS, MINUTES, HOURS, EPOCH, EPOCHDAY, and ALARM$.
BASIC COMMANDS & FUNCTIONS DELAY Causes the program to pause execution for the specified number of seconds. A decimal number may be used to specify more specific and smaller time increments (e.g. milliseconds). SLEEP and DELAY are identical commands. SLEEP 2.5 REM pauses the program for 2.5 seconds DELAY 0.25 REM pauses the program for 0.
Basic Commands and Functions DNS Used in conjunction with the SETNETWORK command, DNS will find or set the Domain Nameservers to use for the network. Available parameters are AUTO or MANUAL. AUTO will automatically find the nameservers (performed when the IP AUTO command is issued); MANUAL sets the given parameter as the Preferred DNS. If another DNS MANUAL entry is given, that entry will become the Preferred DNS, and the previous entry will move to the Alternate DNS position.
BASIC COMMANDS & FUNCTIONS END Immediately ends the Basic program. Optional if used as the last statement. var = 12 IF (var > 10) THEN var = 5 END ENDIF var = 10 REM never reached as program has ended (var still equals 5) ENDIF Declares the end of a multi-line IF-THEN statement. Not required on single-line if statements.
Basic Commands and Functions EPOCH A parameter to the DATETIME function returning the number of seconds elapsed since Jan 1, 1970 00:00:00. var = DATETIME(EPOCH) REM stores 1893300182 EPOCHDAY A parameter to the DATETIME function returning the number of seconds elapsed fromJan 1, 1970 00:00:00 until today’s date at 00:00:00. var = DATETIME(EPOCHDAY) REM stores 1893283200 ERROR Ends the Basic program with a custom error message. Primarily intended for troubleshooting Basic programs.
BASIC COMMANDS & FUNCTIONS GETPOWER ETHERNET, var REM stores a 1 if On, 0 if Off for the Ethernet REM port on the daughterboard in the var variable SETPOWER ETHERNET, 0 a = 16.0 REM turns the Ethernet port Off SETPOWER ETHERNET, a REM turns the Ethernet Port On EULER A read-only constant containing the number 2.7182818284590452. var = EULER REM contains 2.71828 EXP (number) Returns e raised to the power of the given number. Identical to EULER^number.
Basic Commands and Functions FOR Begins a for loop encompassed by FOR and NEXT with an optional STEP parameter (default STEP is 1, negative STEPs may be used). FOR x = 1 TO 5 PRINT x * x, “ “; NEXT x REM prints “1 3 9 16 25 “ FOR a = 10 TO 1 STEP -2 PRINT “ “, a; REM prints “ 10 8 6 4 2” NEXT a FRAC (number) Returns the fractional part of the given number. var = 26.245 REM stores 0.
BASIC COMMANDS & FUNCTIONS GETDB ERRORSTR, var$ REM stores the Default Error String in var$ GETDB SITEID, var$ REM stores the System 5000 Site ID in var$ task$ = “myTask” GETDB SCANRATE task$, A REM stores the Scan Rate for myTask in A GETDB TASKNAME, name$ REM stores the calling Task’s name in name$ GETPOWER Used to retrieve the on/off status for a powered piece of hardware.
Basic Commands and Functions GETTASK Returns the provided Task’s most recent measured value. If an unknown Task is specified, the System 5000™ Default Error String (default is -99.99) is returned. If previous a Task/scan measurement is desired, an additional parameter may be specified prior to the last variable. A “1” indicates the most recent scan, “2” indicates the previous scan, “3” indicates three scans prior, etc. GETTASK “myTask”, var PRINT var REM prints “0.
BASIC COMMANDS & FUNCTIONS slot$ = “SLOT2” GETVALUE DIFF34, var REM stores a new quadrature counter measurement of REM ports 3-4 from the daughterboard in the var REM variable GETVALUE ANALOG1 slot$, s$ REM stores a new analog measurement of REM channel 1 from Slot 2 in the s$ string REM variable CLEARSDI() REM Clear any cached SDI values for this time period GETVALUE SDI01, a1$ REM request a new measurement (address 0, param 1) GETVALUE SDI02, a2$ REM retrieve the second parameter C
Basic Commands and Functions GOTO Jumps to the specified label or line number within the program. Unlike GOSUB, GOTO statements never return back to the point of the GOTO and thus have no RETURN statement. Subroutines, defined with the SUB command, cannot be exited with the GOTO statement.
BASIC COMMANDS & FUNCTIONS IF Used to take actions based on the evaluation of given conditional statements. True is determined as anything non-zero; false is zero. The short form of the IF statement does not include a THEN and must remain on one line. Multi-line IF statements contain the THEN keyword as well as ENDIF to mark the ending of the IF statement.
Basic Commands and Functions INSTR (string, string, number) Returns the position, starting at the position given by the third optional parameter (default is 1), of the first occurrence of the second given string within the first given string beginning at the left. Returns the position, starting at the position given by the third optional parameter (default is 1), of the first occurrence of the second given string within the first given string beginning at the left. var = INSTR(“Analog 2: 3.
BASIC COMMANDS & FUNCTIONS LEFT$ (string, number) Returns a string, starting from the left side, containing the given number of characters from the given string. var$ = “Hello World” new_var$ = LEFT$(var$, 6) + “Universe” REM stores “Hello Universe” LEN (string) Returns the length of the given string. var = LEN(“Hello World”) REM stores 11 in var LINE INPUT Reads an entire line from an open file. OPEN “SiteID.
Basic Commands and Functions LOCAL Used within a subroutine, LOCAL marks the given variable as valid only within that subroutine. SUB change_var() LOCAL var var = 100 PRINT “var: “, var REM prints “var: 100” END SUB var = 10 change_var() PRINT “var: “, var REM prints “var: 10” (would print 100 if not LOCAL) LOG (number) Returns the common (base-10) logarithm of the given number. The LN function should be used if a natural logarithm is required. var = LOG(5) var = LOG(10) REM stores “0.
BASIC COMMANDS & FUNCTIONS MID$ (string, number, number) Returns a smaller section (substring) of a given string. The first parameter is the given string, the second is the starting point from the left side, and the third optional parameter dictates how many characters to return. If the third parameter is omitted, all remaining characters are returned. var$ = MID$(“A2: 12.5, VB: 12.250”, 11) REM stores VB: “12.
Basic Commands and Functions NEXT Declares the end of a FOR loop. The initial FOR variable may be optionally specified. FOR a = 1 TO 10 STEP 2 PRINT “ “, a; REM prints “ 1 3 5 7 9” NEXT a NOT Negates the expression immediately following. The ! operator may alternatively be used. FOR a = 1 TO 10 STEP 2 IF (NOT a > 5) REM NOT effectively changes our expression to (a <= 5) PRINT “ “, a; REM prints “ 1 3 5” NEXT a ON number GOSUB Branches to one of a list of GOSUBs based on the given number/argument.
BASIC COMMANDS & FUNCTIONS LABEL print3 PRINT “ *”, a; PRINT “*”; LABEL print2 PRINT “ (“, a; PRINT “)”; LABEL print1 PRINT “ “, a; OPEN Opens a file, serial (COM) port, network (Ethernet) port, or connects to a listening serial or network port. Files may be opened for either READING, WRITING, or APPENDING. A file opened with WRITING mode will create a new file if the file doesn’t exist, or erase the contents of an existing file.
Basic Commands and Functions FileExists = 1 FileName$ = “LogFile.csv” IF (NOT OPEN(#1, FileName$)) THEN FileExists = 0 ELSE CLOSE #1 ENDIF Serial Port: SETPORT 300, 8, none, 1, none, 50, 0 REM port settings OPEN “COM 1” AS #5 REM open the COM at 300 baud w/50ms tx char delay CLOSE #5 Ethernet Port: OPEN “www.waterlog.com:80” AS #2 headers$ = “GET / HTTP/1.1\r\n” headers$ = headers$ + “Host: www.waterlog.
BASIC COMMANDS & FUNCTIONS OR A logical operator used between two expressions in conditional statements (e.g. if, while, etc). Returns TRUE if either the left, right, or both expressions are TRUE, FALSE if both are FALSE. var = 100 IF (var > 0 OR var < 50) PRINT “Small” IF (var > 0 OR var < 150) PRINT “Large” REM prints “Small” REM prints “Large” PI A read-only constant containing the number 3.1415926535897932. var = PI REM stores 3.
Basic Commands and Functions Network communication: PRINT “OPENING Ethernet connection” REM prints to terminal OPEN “192.168.0.1:20” AS #1 REM format must be host:port PRINT #1 “Digital2,AC-In” REM newline automatically added var = 1 var2 = 256.25 var3 = 12.565 REM following line prints “1,256.25” PRINT #1 var, “,”, var2, “,”; REM newline not added PRINT #1 var3 USING “##.##” REM prints “12.
BASIC COMMANDS & FUNCTIONS REPEAT Begins a conditional loop encompassed by REPEAT and UNTIL. The condition is given after the UNTIL statement and while evaluated as TRUE, will continue to iterate through the loop. Once the UNTIL condition is evaluated as FALSE, the loop exits. REPEAT var = var + 1 PRINT “ “, var * var; UNTIL (var = 5) REM prints “ 1 4 9 16 25” RETURN Returns control back to the calling line of a GOSUB call or a subroutine (SUB) call with an optional value.
Basic Commands and Functions RTRIM$ (string) Returns the given string with all whitespace removed from only the right side. PRINT RTRIM$(“ Hello World “) REM prints “ Hello World” SCANRATE Used in conjunction with the GETDB command, SCANRATE requests the given Task’s scan rate and stores it in the given variable. The scan rate is given in seconds. Used in conjunction with the SETDB command, SCANRATE sets the given Task’s scan rate to the given value. The scan rate should be specified in seconds.
BASIC COMMANDS & FUNCTIONS SETDB Sets the requested database value to the given number or string. Available parameters are SITEID and SCANRATE with a mentioned Task and number value (measured in seconds). SETDB SITEID, “Site101” task$ = “myTask” SETDB SCANRATE task$, 60 REM Sets the Scan Rate for myTask to 1 min. SETNETWORK Sets network settings to the given number or string. Available parameters are IP, NETMASK, GATEWAY, and DNS. IP and DNS also require either an AUTO or MANUAL parameter.
Basic Commands and Functions SETTASK Sets the provided Task’s most recent value to the given number or string. If an unknown Task is specified, no value will be stored. task$ = “myTask” GETTASK task$, a SETTASK “myTask”, a * 2 REM doubles the last measurement value of myTask SETTIMESTAMP Sets the provided Task’s most recent timestamp to the given number or string. If an unknown Task is specified, no value will be stored.
BASIC COMMANDS & FUNCTIONS SIN ( ) Returns the sine value of the given number. var = SIN(PI/2) PRINT SIN(0) REM stores 1 in the var variable REM prints “0” SITEID Used in conjunction with the GETDB command, SITEID requests the System 5000™’s Site ID as specified in the System Settings screen and stores it in the given string variable. Used in conjunction with the SETDB command, SITEID sets the System 5000™’s Site ID to the given value.
Basic Commands and Functions The array will be automatically sized (larger or smaller) based on the number of strings that are produced by the split. The number of strings produced will also be returned by the function.
BASIC COMMANDS & FUNCTIONS SUB Declares a user-defined subroutine. Subroutines can specify and accept multiple arguments and can return a number or string value using the RETURN statement. The END SUB statement marks the end of a subroutine. For consistency, it is recommended that any subroutine returning a string should have the subroutine’s name end with a dollar-sign (“$”). Specific SUB commands may also be used as special entry points for designated IO.
Basic Commands and Functions numbers less than or equal to zero will turn the Switched +12 Volt Off. GETPOWER SW12V, var SETPOWER SW12V, 0 a = 16.0 SETPOWER SW12V, a REM stores a 1 if On, 0 if Off for the Switched +12V REM on the daughterboard in the var variable REM turns the Switched +12 Volt Off REM turns the Switched +12 Volt On SWITCH Declares the beginning of a SWITCH-CASE clause. The single variable given after the SWITCH keyword specifies the character or characters to match.
BASIC COMMANDS & FUNCTIONS TELL (filenumber) Returns the current read position of the given file number. Presuming SiteID.csv contains: Digital2,AC-In 1,256.25 OPEN “SiteID.
Basic Commands and Functions TIME$ A parameter to the DATETIME function returning a string representation of the current time, formatted as “HH:MM:SS”. var$ = DATETIME(TIME$) REM stores “05:32:37” TO Used with the FOR statement to specify the range of the loop. FOR a = 1 TO 10 PRINT “ “, a; NEXT a REM prints “ 1 2 3 4 5 6 7 8 9 10” TOKEN (string, array, string) Splits apart a string into an array of strings. The first parameter provides the string to split apart.
BASIC COMMANDS & FUNCTIONS UNTIL Marks the end of a conditional loop encompassed by REPEAT and UNTIL. The condition is given after the UNTIL statement and while evaluated as TRUE, will continue to iterate through the loop. Once the UNTIL condition is evaluated as FALSE, the loop exits. REPEAT var = var + 1 PRINT “ “, var * var; UNTIL (var = 5) REM prints “ 1 4 9 16 25” UPPER$ (string) Returns the given string as all uppercase.
Basic Commands and Functions WHILE Marks the beginning of a conditional WHILE-WEND loop. The condition is specified after the WHILE keyword. As long as the condition evaluates to TRUE, the loop will continue to iterate. Once the condition evaluates to FALSE, the loop will exit. Presuming SiteID.csv contains: Digital2,AC-In 1,256.25 OPEN “SiteID.csv” FOR READING AS #1 WHILE (!EOF(#1)) INPUT #1 “,”, var$ PRINT var$, “ “; REM prints “Digital2 AC-In 1 256.
Xylem 1) The tissue in plants that brings water upward from the roots; 2) a leading global water technology company. We’re 12,000 people unified in a common purpose: creating innovative solutions to meet our world’s water needs. Developing new technologies that will improve the way water is used, conserved, and re-used in the future is central to our work. We move, treat, analyze, and return water to the environment, and we help people use water efficiently, in their homes, buildings, factories and farms.
