OCL (Operator's Control Language)
 Misc microblock
|
The OCL microblock allows you to create your own microblock when the existing EIKON for WebCTRL microblocks are not suitablefor your application. You define the microblock's inputs, outputs, and internal calculations.
An OCL program is made up of two parts: the variable declaration section and the body of the program itself. The variable declaration section allows you to define features that are unique to the microblock and variables that are used in the body of the program. OCL also provides a number of terms, variables, mathematical functions, and programming commands you can use to complete your program.
Note that although OCL has a great deal of flexibility, you should not try to program an entire control program into a single microblock. The program will function more efficiently if you break it up into smaller sections, using wires and other microblocks whenever possible. This way, you will also be able to easily see the components of the control program, which will make the program easier to troubleshoot if necessary.
The OCL program is not case-sensitive, but there are certain characters that have a special meaning, and there are cases in which a certain syntax must be used for the command to be understood.
When you click OK in the OCL microblock dialog box, the program is saved and checked for errors.
|
 
To create a custom microblock
- Click the OCL microblock icon from the Misc microblock menu.
- Click where you want to place the microblock.
The OCL microblock appears as a blank gray microblock when it is first placed. When you define the microblock's title, inputs, and outputs, the microblock will expand to accommodate the necessary text on the microblock's face.
- To enter the programming for the microblock, press F5 and then click the OCL microblock.
- Type the program into the editing window.
- Click OK to save the program and close the editing window.
If errors are found in the program, a message appears. The message indicates which line of the program the error was found in, so you can correct the error more easily.
If no errors are found, the program is saved and the microblock changes appearance to reflect the title and any inputs or outputs defined.
TIP If you want to use this microblock in more than one control program, select the microblock by pressing F9 and clicking the microblock. Then save the microblock as a symbol by clicking Edit-Copy To.
Sample program
Variable declaration section
The first part of an OCL program is the variable declaration section. In this section you define values that are specific to the microblock you want to create, such as the microblock's title, the microblock's inputs and outputs, and the settings that appear on the Properties Pages. The values you define in the variable declaration section are used in the body of the OCL program along with the predefined symbols, system variables, functions, and structures.
The following list explains the terms you can define in the variable declaration section of the program. You cannot create a variable using the same name as any of the predefined symbols, functions, or commands.When entering the variable declaration section, you only need to include those items that are used by the microblock. Each term can be typed either in upper or lower case letters and should be followed by at least one space.
|
Term
|
Notes
|
AINPUT
|
This term is used to define the microblock's analog inputs. Each input's name must begin with a letter. While each name can be up to 32 characters long, only the first four characters appear on the face of the microblock. If you need to define more than one analog input, separate each input's name with a comma.
Example
AINPUT TMP1,CUR5,ENT3
This line creates three analog inputs for the microblock named TMP1, CUR5, and ENT3.
|
AOUTPUT
|
This term is used to define the microblock's analog outputs. Each output's name must begin with a letter. While each name can be up to 32 characters long, only the first four characters appear on the face of the microblock. If you need to define more than one analog output, separate each output's name with a comma.
Example
AOUTPUT COIL,POWR,HEAT
This line creates three analog outputs for the microblock named COIL, POWR, and HEAT.
|
DINPUT
|
This term is used to define the microblock's digital inputs. Each input's name must begin with a letter. While each name can be up to 32 characters long, only the first four characters appear on the face of the microblock. If you need to define more than one digital input, separate each input's name with a comma.
Example
DINPUT STA1,PMP2
This line creates two digital inputs for the microblock named STA1 and PMP2.
|
DOUTPUT
|
This term is used to define the microblock's digital outputs. Each output's name must begin with a letter. While each name can be up to 32 characters long, only the first four characters appear on the face of the microblock. If you need to define more than one digital output, separate each output's name with a comma.
Example
DOUTPUT SEC7,LIG2
This line creates two digital outputs for the microblock named SEC7 and LIG2.
|
PAR
|
This term is used to define variables that are used in the body of the OCL program, and if necessary, to define the text for these variables that appears on the Properties page. Each variable can be any letter or letter combination you choose, as long as it is not already used by OCL.
If the variable appears on the Properties page, the Properties page text should be entered within quotation marks following the variable. To display the value of the property, you must use the expression enclosed in a pair of "$" signs.
TIP If you want to display the variable's value on the Properties page but do not want the value to be changed, you can set the editable property to false.
Example
PAR E = 2.71 "E equals $E$", X = 5.0 "$X:editable="false"$"
In this example, OCL assigns the variable E to 2.71 and X to 5.0. On the Properties page, the text "E equals 2.71" will be displayed, with the "2.71" as an editable field. The text "X equals 5.0" also appears on the Properties page, but the value "5.0" appears as an uneditable status field.
|
TIMER
|
The TIMER declaration is used to define timing variables. These are defined similar to the VAR declaration, with a variable name, text within quotes, and an expression enclosed in a pair of "$" signs to display the present value of the variable.
Example
TIMER T2 "Time remaining for Timer2 = $T2$ (mm:ss)"
In this example, OCL displays the given text on the Properties page along with the present value of T2 instead of the string of tildes.
|
TITLE
|
This term defines the title of the microblock that appears on the microblock's face. The title will not appear if no inputs or outputs are defined. The title may be up to eight characters long.
Example
TITLE ICEPLANT
In this example, OCL assigns the name "ICEPLANT" to the microblock.
|
VAR
|
This term is used to define variables that are used in the body of the OCL program, and if necessary, to define the text for these variables that appears on the Properties page. Each variable can be any letter or letter combination you choose, as long as it is not already used in the variable declaration section or by OCL. If the variable appears on the Properties page, the Properties page text should be entered within quotation marks following the variable. To display the value of the variable, you must use the expression enclosed in a pair of "$" signs.
Example
VAR Z "Z equals $Z$"
In this example, OCL displays the text "Z equals" along with the present value of Z.
|
Predefined symbols
OCL provides a number of predefined symbols, which are terms that already have an assigned value. These terms can be used in the body of your OCL program. You cannot change the value of any of these terms, and you should not list these terms in the variable declaration section.
|
Symbol
|
Value
|
GRAY
|
1
|
HRED
|
2
|
KBLUE
|
3
|
LTBLUE
|
4
|
GREEN
|
5
|
SPECKLE
|
6
|
YELLOW
|
7
|
ORANGE
|
8
|
CRED
|
9
|
WHITE
|
10
|
TRUE
|
1
|
FALSE
|
0
|
ON
|
1
|
OFF
|
0
|
OCC
|
1
|
UNOCC
|
0
|
OCCUPIED
|
1
|
UNOCCUPIED
|
0
|
YES
|
1
|
NO
|
0
|
JAN
|
1
|
FEB
|
2
|
MAR
|
3
|
APR
|
4
|
MAY
|
5
|
JUN
|
6
|
JUL
|
7
|
AUG
|
8
|
SEP
|
9
|
OCT
|
10
|
NOV
|
11
|
DEC
|
12
|
MON
|
1
|
TUE
|
2
|
WED
|
3
|
THU
|
4
|
FRI
|
5
|
DAT
|
6
|
SUN
|
7
|
System variables
OCL provides several system variables that read information from the control program. You can use these variables in your program whenever one of these values is required. Each system variable produces a number corresponding to the variable's current value in the control program.
|
System variable
|
Notes
|
COLOR
|
Control program's current color (1-10)
|
MDAY
|
Current day of the month (1-31)
|
MONTH
|
Current month (1-12)
|
TIME
|
Current time (0-1439; in minutes since midnight)
|
WDAY
|
Current day of the week (Monday=1, Sunday=7)
|
YDAY
|
Current day of the year (1-366)
|
YEAR
|
Current year (1981-2040)
|
Special characters
When typing your OCL program, there are certain characters that represent specific functions or values in OCL.
|
Character
|
Notes
|
( )
|
Used to override order of evaluation in an expression, delineate arguments in function calls, and to specify a conditional expression.
|
, (comma)
|
Used to separate arguments in function calls.
|
: (colon)
|
Used to identify labels referenced by GOSUB and GOTO keywords.
|
//
|
Used to place comments in the program. Any text following two slashes is ignored by the OCL compiler.
|
H
|
Used to represent one hour, or 3600 seconds.
|
M
|
Used to represent one minute, or 60 seconds.
|
S
|
Reserved but has no effect. The default time unit is seconds.
|
Mathematical functions
OCL provides a number of mathematical and logical functions you can use in your program. Each of these functions acts on a value or set of values in parenthesis following the name of the function. These functions can act on numbers, variables, or expressions to calculate the results.
|
Function
|
Notes
|
ABS
|
This function returns the absolute value of the number, variable, or expression in parenthesis.
Example
X = -10 Y = ABS(X) Z = ABS(5+3)
In this example, OCL assigns Y to 10, because the absolute value of X equals 10. OCL assigns Z to 8, because the absolute value of 5+3 equals 8.
|
AVG
|
The AVG function returns the average of a set of values.
Example
XAN = 5 BETA = AVG(1,4,XAN,9)
In this example, OCL assigns BETA to:
|
BETWEEN
|
This function evaluates the three values in parentheses and determines whether the first value falls between the second and third values. If the first value does fall between the second and third values, the function returns a value of 1.0. If not, the between function returns a value of 0.0.
Example
STAT1 = BETWEEN(17,15,20) BETA = 2 STAT2 = BETWEEN(BETA,3,5)
In this example, OCL assigns the value of STAT1 to 1.0, since 17 falls between 15 and 20. OCL assigns the value of STAT2 to 0.0, since BETA (which has a value of 2) is not between 3 and 5.
|
COS
|
This function computes the cosine of the value (in degrees) in parentheses.
Example
VAL = COS(45)
In this example, OCL assigns the value of VAL to 0.707.
|
DELON
|
This function calculates whether a variable or expression has been on or true for the amount of time specified. The time must be specified as a number, variable, or expression.
Example
STAGE1 = DELON(GAS, 1:00)
This example turns on the variable STAGE1 after the variable GAS has been on for 1 minute.
Example
STAGE2 = DELON(FLOW1 > 125, 5 H)
This example turns on the variable STAGE2 after the value of the variable FLOW1 has been greater than 125 for 5 hours.
|
LMT
|
This function calculates whether a variable or expression has been on or true for the amount of time specified. The time must be specified as a number, variable, or expression.
Example
STAGE1 = DELON(GAS, 1:00)
This example turns on the variable STAGE1 after the variable GAS has been on for 1 minute.
Example
STAGE2 = DELON(FLOW1 > 125, 5 H)
This example turns on the variable STAGE2 after the value of the variable FLOW1 has been greater than 125 for 5 hours.
|
LN
|
The LN function calculates the natural logarithm of the indicated value.
Example
Y = LN(134)
In this example, OCL sets Y equal to 4.8978.
|
LOG
|
The LOG function calculates the base 10 logarithm of the indicated value.
Example
X = LOG(134)
In this example, OCL sets X equal to 2.1271
|
MAX
|
This function determines the larger number from a set of two numbers, variables, constants, or expressions.
Example
SIGMA = 7 GAMMA = MAX(SIGMA,10)
In this example, OCL sets GAMMA equal to 10, since 10 is larger than SIGMA (which is set to 7).
|
MIN
|
This function determines the smaller number from a set of two numbers, variables, constants, or expressions.
Example
X = 2 RHO = MIN(1+X,4)
In this example, OCL sets RHO equal to 3, since 1+X (when X = 2) is less than 4.
|
POW
|
This function calculates the first value raised to the power of the second value.
Example
CHI = POW(TAU,3)
In this example, OCL sets CHI equal to TAU raised to the power of 3 (TAU cubed).
|
RATIO
|
This function converts a value in a range to a proportionate value in a different range. The first value in parenthesis is the value to be converted. The next two values indicate the current range that the first value belongs in. The last two numbers indicate the range the value should be converted to.
Example
N=40 DELTA = RATIO(N, 0, 100, 3, 13)
In this example, OCL sets DELTA to 7.
|
RND
|
The RND function rounds the specified number to the nearest whole number.
Example
KAPPA = RND(3.442) LAMBDA = RND(10.59)
In this example, OCL sets KAPPA equal to 3.0 and LAMBDA equal to 11.0.
|
SIN
|
This function calculates the sine of the value (in degrees) in parenthesis.
Example
X = SIN(90)
In this example, OCL sets X equal to 1.0
|
SQRT
|
This function calculates the square root of the indicated value.
Example
Y = SQRT(81)
In this example, OCL sets Y equal to 9.
|
START
|
The START function turns on the variable or variables in parenthesis. You can use as many variables as necessary, separating each variable with a comma.
Example
START(FAN1, PUMP4, STAGE2)
In this example, OCL turns on the variables FAN1, PUMP4, and STAGE2.
|
STOP
|
This function turns off all of the variables listed in parenthesis. You can use as many variables as necessary, separating each variable with a comma.
Example
STOP (ALARM, LIGHT2, COMP4)
This example turns off the variables ALARM, LIGHT2, and COMP4.
|
TAN
|
This function calculates the tangent of the value (in degrees) indicated in parenthesis.
Example
XI = TAN(71)
In this example, OCL sets the variable XI equal to 2.904.
|
TOF
|
This function returns the amount of time in seconds that the variable or expression in parenthesis has been off or false.
Example
X = TOF(CHILLER1)
In this example, OCL sets X equal to the amount of time in seconds that CHILLER1 has been off.
|
TON
|
This function returns the amount of time in seconds that the variable or expression in parenthesis has been on or true.
Example
Y = TON(BOILER2)
In this example, OCL sets Y equal to the amount of time in seconds that BOILER2 has been running.
|
TRN
|
This function discards the fractional portion of the value in parenthesis.
Example
WEIGHT= TRN((CREQ1 + CREQ2 + CREQ3)/3)
In this example, OCL evaluates the equation in parenthesis and truncates the value. If CREQ1 equals 2, CREQ2 equals 5, and CREQ3 equals 0, the value of WEIGHT is 2.
|
Programming structures
OCL supports several programming structures that are common to many other programming languages.
|
Structure
|
Notes
|
BEGIN...END
|
The BEGIN...END structure is used to group together a number of program statements. This structure is often used to group together a sequence of statement that should be executed when a given condition is met.
Example
IF (OCC) THEN BEGIN START PUMP1 START BOILER1 RATE = 4 * LMT(FLOW,5,10) END
In this example, OCL starts PUMP1, starts BOILER1, and calculates RATE whenever OCC is TRUE.
|
DELAY
|
This structure halts execution for the amount of time specified. The time may be defined in hours (H), minutes (M), or seconds (the default unit).
Example
DELAY 10H
This example stops the execution of OCL for 10 hours.
|
EVERY...DO
|
This structure tells OCL to execute a program statement once every time the specified interval of time passes. The time may be defined in hours (H), minutes (M), or seconds (the default unit). The actual amount of time can be a number or a variable.
Example
EVERY 10 M DO A = B + AVG(C, D + E)
This example calculates the value of the variable A every 10 minutes.
|
EXITLOOP
|
The EXITLOOP structure is used to skip the remaining portion of a WHILE...DO loop if the specified condition is met.
Example
WHILE (CONTENT < 90.1) DO BEGIN IF (TLO = ON) THEN EXITLOOP D = D + 2 END
In this example, OCL continues to calculate the value of the variable D until either the value of CONTENT becomes greater than 90.1 or the variable TLO turns on.
|
EXITPROG
|
EXITPROG is used to end the OCL program. You should place all subroutines after the EXITPROG statement to prevent them from being executed inadvertently.
Syntax The GOSUB structure is used to call a subroutine which is referenced by a label or name. You should place all subroutines after the EXITPROG statement to ensure that they are not executed inadvertently. Once the subroutine is finished, the RETURN statement resumes execution of the OCL program at the point where the subroutine was invoked.
Example
IF X < 23.0 THEN GOSUB TURNON ELSE GOSUB TURNOFF EXITPROG TURNON: START (LOCK1) START (LOCK2) RETURN TURNOFF STOP (LOCK1) STOP (LOCK2) RETURN
In this example, OCL begins the TURNON subroutine, which turns LOCK1 and LOCK2 on, if X is less than 23. If X is greater than 23, OCL begins the TURNOFF subroutine, which turns LOCK1 and LOCK2 OFF.
|
GOTO
|
The GOTO structure transfers execution of OCL to the designated label. Use of the GOTO structure is not recommended because it creates difficulties in debugging the OCL sequence.
Example
IF (PH >= 6) THEN GOTO ACID Y = GB - X GOTO LAST ACID: Y = GB + X LAST:
In this example, OCL jumps to the line labeled ACID if PH is greater than or equal to 6. After it reaches line ACID, it sets Y equal to GB + X and proceeds to the line LAST. If PH is less than 6, OCL sets Y equal to GB - X and jumps to the line LAST.
|
IF...THEN
|
The IF...THEN structure tells OCL to execute the given program statement if the value of the variable or expression in parenthesis is TRUE.
Example
IF (BOILER9) THEN X = 45
In this example, OCL sets X equal to 45 if BOILER9 is on.
|
IF...THEN...ELSE
|
The IF...THEN...ELSE structure works similarly to IF...THEN but adds an alternative statement to be executed if the value of the variable or expression in parenthesis is FALSE.
Example
IF (HUMIDITY > 88) THEN DEMAND = 4 ELSE DEMAND = 2
In this example, OCL sets DEMAND equal to 4 if HUMIDITY is greater than 88; otherwise OCL sets DEMAND equal to 2.
|
IFONCE...THEN
|
This structure works similarly to the IF...THEN structure but executes the program statement only once after the value of the variable or expression in parenthesis has been determined to be true.
Example
IFONCE(PRESSURE > 178) THEN START (ALARM6)
In this example, OCL starts ALARM6 if PRESSURE becomes greater than 178.
|
Operators
|
The following operators can be used with If statements:
WHILE...DO
This structure tells OCL to execute a program statement provided that the value of the variable or expression in parenthesis is TRUE.
Example
WHILE (POSITION>150) DO POSITION = POSITION - 1
|
|