### OCL (Operator's Control Language) The information below provides a FULL description of this microblock and all of its properties. What information you see and what you can do with it depends on your license and the application you are in, and in some cases, a controller's driver version.
Microblock family | Misc microblocks
Icon and symbol |
What it does | OCL allows you to create your own microblock when no other microblock suits your application. You define the microblock's inputs, outputs, and internal calculations. Although the OCL has great flexibility, you should not put an entire control program into one microblock. Break it into smaller sections, using wires and other microblocks. You will be able to easily see the components of the control program, making it easier to troubleshoot.
Click for details below To create an OCL microblock Sample program Variable declaration section Predefined symbols System variables Special characters Mathematical functions Programming structures Operators
#### To create an OCL microblock In the EIKON® application, click the OCL microblock icon in the Misc microblock menu. Click in the workspace where you want to place the microblock. The OCL microblock first appears as a blank gray microblock. After you define it's title, inputs, and outputs, the microblock will show these. In the Property Editor, type the variable declaration section. Press Enter to add a blank line. Type the programming sequence that the OCL microblock will execute. Use the following: Information from the variable declaration section Predefined symbols System variables Special characters Functions Structures NOTES The OCL program is not case-sensitive. A red box around the microblock indicates the program contains errors. The Property Editor turns the program's text red, displays a description of the error below the program's text, and highlights the line containing the error. The outputs of an OCL program are updated only at the end of the program execution, essentially at the "EXITPROG" line. Changes calculated during a program loop will not be output until the execution exits the loop and reaches the end of the program. TIP To use your programmed OCL microblock in more than one control program, right-click the microblock, then select Add to Favorites.
#### Sample program
#### Variable declaration section In this section, you define the microblock's: Title Inputs and outputs Variables used in the OCL program Text that appears on the Properties pages In the variable declaration section of your OCL program, add the following terms that will be used by the microblock. Type each term in upper or lower case letters, and add at least one space after the term. Do not create a variable using the same name as any of the predefined symbols, functions, or commands.
Term | Notes
--- | ---
AINPUT | Defines the microblock's analog inputs. Each input's name must begin with a letter and be no more than 32 characters (only the first 4 appear on the microblock). Separate multiple names with a comma. EXAMPLE `AINPUT TMP1,CUR5,ENT3` This line creates 3 analog inputs for the microblock named TMP1, CUR5, and ENT3.
AOUTPUT | Defines the microblock's analog outputs. Each output's name must begin with a letter and be no more than 32 characters (only the first 4 appear on the microblock). Separate multiple names with a comma. EXAMPLE `AOUTPUT COIL,POWR,HEAT` This line creates 3 analog outputs for the microblock named COIL, POWR, and HEAT.
DINPUT | Defines the microblock's digital inputs. Each input's name must begin with a letter and be no more than 32 characters (only the first 4 appear on the microblock). Separate multiple names with a comma. EXAMPLE `DINPUT STA1,PMP2` This line creates 2 digital inputs for the microblock named STA1 and PMP2.
DOUTPUT | Defines the microblock's digital outputs. Each output's name must begin with a letter and be no more than 32 characters (only the first 4 appear on the microblock). Separate multiple names with a comma. EXAMPLE `DOUTPUT SEC7,LIG2` This line creates 2 digital outputs for the microblock named SEC7 and LIG2.
PAR | Defines variables that are used in the OCL program, and if necessary, the text for these variables that appears on the Properties page. A variable can be any letter or letter combination as long as it is not already used by OCL. If the variable appears on the Properties page, type the Properties page text after the variable and in quotation marks. To display the value of the property, type the expression between $ signs. TIP To display the variable's value on the Properties page but not have the value be an editable field, set the editable property to false. EXAMPLE `PAR E = 2.71 "E equals $E$", X = 5.0` `"$X:editable="false"$"` OCL assigns the variable E to 2.71 and X to 5.0. The Properties page will display the text "E equals 2.71", with the "2.71" as an editable field. The Properties page will also show "X equals 5.0", but the value "5.0" will not be editable.
TIMER | Defines timing variables. Similar to the VAR declaration, type a variable name, text in quotation marks, and an expression between $ signs to display the variable's present value. EXAMPLE `TIMER T2 "Time remaining for Timer2 = $T2$ (mm:ss)"` OCL displays the given text on the Properties page along with the present value of T2.
TITLE | Defines the microblock's title that appears on the microblock's face. The title will not appear if no inputs or outputs are defined. The title can be up to 8 characters. EXAMPLE `TITLE ICEPLANT` OCL assigns the name "ICEPLANT" to the microblock.
VAR | Defines variables that are used in the OCL program, and if necessary, the text for these variables that appears on the Properties page. A variable can be any letter or letter combination as long as it is not already used in the variable declaration section or by OCL. If the variable appears on the Properties page, type the Properties page text after the variable and in quotation marks. To display the value of the variable, type the expression between $ signs. EXAMPLE `VAR Z "Z equals $Z$"` OCL displays the text "Z equals" followed by the present value of Z.
#### Predefined symbols OCL predefined symbols are terms that already have an assigned value. You can use these terms in the OCL program. You cannot change a symbol's value. Do not list these terms in the variable declaration section.
Symbol | Value | Symbol | Value
--- | --- | --- | ---
GRAY | 1 | JAN | 1
HRED | 2 | FEB | 2
KBLUE | 3 | MAR | 3
LTBLUE | 4 | APR | 4
GREEN | 5 | MAY | 5
SPECKLE | 6 | JUN | 6
YELLOW | 7 | JUL | 7
ORANGE | 8 | AUG | 8
CRED | 9 | SEP | 9
WHITE | 10 | OCT | 10
TRUE | 1 | NOV | 11
FALSE | 0 | DEC | 12
ON | 1 | MON | 1
OFF | 0 | TUE | 2
OCC | 1 | WED | 3
UNOCC | 0 | THU | 4
OCCUPIED | 1 | FRI | 5
UNOCCUPIED | 0 | SAT | 6
YES | 1 | SUN | 7
NO | 0 |  |
#### System variables You can use the following system variables in your OCL program to read information from the control program. Each 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)
WKDAY | Current day of the week (Monday=1, Sunday=7)
YDAY | Current day of the year (1-366)
YEAR | Current year (1981-2040)
#### Special characters You can use the following special characters in your OCL program.
Character | Use to...
--- | ---
( ) | Use to override order of evaluation in an expression, delineate arguments in function calls, and to specify a conditional expression.
, (comma) | Use to separate arguments in function calls.
: (colon) | Use to identify labels referenced by GOSUB and GOTO keywords.
// | Use to place comments in the program. Any text following 2 slashes is ignored by the OCL compiler.
H | Use to represent one hour, or 3600 seconds.
M | Use to represent one minute, or 60 seconds.
S | Reserved but has no effect. The default time unit is seconds.
#### Mathematical functions You can use the following mathematical and logical functions in your OCL 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 | 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 | Returns the average of a set of values. EXAMPLE `XAN = 5` `BETA = AVG(1,4,XAN,9)` In this example, OCL assigns BETA to 4.75.
BETWEEN | Evaluates the 3 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 | 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 | 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 | Limits a value based on the high and low limits specified. This function requires 3 values: the first value is the value to be limited, the second value is the low limit, and the third value is the high limit. Each of the values can be a number, a variable, or an expression. If the first value falls between the low and high limits, the value is unchanged. If the first value is lower than the low limit, the low limit becomes the function’s value. If the first value is higher than the high limit, the high limit becomes the function’s value. EXAMPLE `ZETA1 = 3` `ZETA2 = LMT(ZETA1, 5, 10)` In this example, ZETA2 = 5, since the value of ZETA1 (which is 3) is less than the low limit of 5.
LN | Calculates the natural logarithm of the indicated value. EXAMPLE `Y = LN(134)` In this example, OCL sets Y equal to 4.8978.
LOG | Calculates the base 10 logarithm of the indicated value. EXAMPLE `X = LOG(134)` In this example, OCL sets X equal to 2.1271
MAX | Determines the larger number from a set of 2 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 | Determines the smaller number from a set of 2 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 | 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 | 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 2 values indicate the current range that the first value belongs in. The last 2 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 | 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 | 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 | Calculates the square root of the indicated value. EXAMPLE `Y = SQRT(81)` In this example, OCL sets Y equal to 9.
START | 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 | 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 | 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 | Returns the amount of time in seconds that the variable or expression in parenthesis has been off or false. WARNING Do not put this function in a conditional section of the program. It must execute to calculate properly. EXAMPLE //first do things that always need to be executed X=TOF(COMP1) //then do things appropriate to the state we're in, but EXITPROG each time to check the state IF (FOO) THEN BEGIN ...do something... IF (PUMP) THEN FOO = FALSE //if pump comes on, break out of the loop EXITPROG //leave, knowing you'll be right back if FOO is still true END IF (X>300) THEN... In this example, OCL sets X equal to the amount of time in seconds that COMP1 has been off, and updates that time regardless of the FOO loop.
TON | Returns the amount of time in seconds that the variable or expression in parenthesis has been on or true. WARNING Do not put this function in a conditional section of the program. It must execute to calculate properly. EXAMPLE P1_TIME = TON(PUMP1) P2_TIME = TON(PUMP2) IF (PRIMARY) THEN X=P1_TIME ELSE X=P2_TIME IF (X>30) = THEN START(CHILLER1) In this example, OCL sets P1_TIME equal to the amount of time in seconds that PUMP1 has been running, and P2_TIME equal to the amount of time in seconds that PUMP2 has been running.
TRN | 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 | Groups a number of program statements. This structure is often used to group a sequence of statements 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 when OCC is TRUE.
DELAY | Halts execution for the specified amount of time. Define the time 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 | Tells OCL to execute a program statement once every time the specified time interval passes. Define the time 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 | Skips 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 | Ends the OCL program. Place all subroutines after the EXITPROG statement to ensure they are not executed inadvertently.
GOSUB | Calls a subroutine which is referenced by a label or name. Place all subroutines after the EXITPROG statement to ensure they are not executed inadvertently. When the subroutine finishes, 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 | Transfers execution of OCL to the designated label. 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 | Tells OCL to execute a program statement if the value of the variable or expression in parenthesis is TRUE. EXAMPLE `IF (BOILER9) THEN X = 45` In this example, if BOILER9 is on, OCL sets X to 45 .
IF...THEN...ELSE | 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 | 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.
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 (WASTETIME>150) DO` `WASTETIME = WASTETIME - 1` NOTE The WHILE...DO function is provided to support existing OCL programs, but we recommend that you do not use it in new programs. In some cases, each WHILE...DO loop can add up to a 100 msec delay. Ten WHILE...DO loops will create a 1 second delay. This delay affects all programs within the controller, not just the OCL program. Also, OCL output values will not update until the "While" condition is no longer true and the program exits the WHILE...DO loop.
#### Operators Mathematical Operators
+ | (Add)
- | (Subtract)
* | (Multiply)
/ | (Divide)
NOTE Do not use ** to raise to a power. Use the POW function instead. Logical Operators
= |
> |
< |
>= | (Greater Than or Equal To)
<= | (Less Than or Equal To)
<> | (Not Equal To)
AND |
OR |
NOT |
Examples
This statement... | Will be true if...
--- | ---
IF ((A1+A2=4) AND NOT (A1=A2)) THEN ANS = 1 | A1=1 and A2=3 but not if A1=A2=2
IF ((A1+A2=4) OR NOT (A1=A2)) THEN ANS = 1 | A1+ A2=4 or if A1 does not equal A2
IF (POW(A1,2)+A2=4) THEN ANS = 1 | A12 + A2 = 4