TRACER SUMMIT

Custom Programming
This book applies to
Tracer Summit software
version 6.0 and later.

Volume 5
BMTS-IOP-504
November 1997

This is Volume 5 in a seven-volume set. Refer to engineering bulletin BAS-EB-57 for a list of literature numbers
applicable to the current and previous versions of Tracer Summit software.

Literature File Information

Library ....................................................................Service Literature
Product Section ..........................Electronic Systems and Controllers
Product ................................................Building Automation Systems
Model........................................................................................BMTS
Literature Type ................Installation/Operation/Programming Guide
Sequence .........................................................................................5
Date ...........................................................................................11/97
File No. ..................................................SV-ES-BAS-BMTS-IOP-504
Supersedes ...........................................SV-ES-BAS-BMTS-IOP-503

The Trane Company

St. Paul, Minnesota
An American-Standard Company
American Standard Inc. 1997

Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Tracer Summit Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii
Screen Nomenclature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii
Additional Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii

General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Using the CPL Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Editing CPL Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Creating a CPL Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Compiling a CPL Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Creating a CPL object in the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
Testing a CPL Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
CPL Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
CPL Program Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
CPL Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
CPL Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
CPL Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
CPL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
CALL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
CONTROL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
DEFxxx Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
DO... Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
ERR Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
ERROR Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
EXIT Statement

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
FOR...NEXT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
FOR NEXT OBJECT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
FUNCTION...END FUNCTION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
GOTO Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
IF...THEN...ELSE...END IF Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20

Local - Predefined variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21

Tracer Summit Custom Programming

Table of Contents

Program END Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22

REPEAT...Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
RESUME Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24
SELECT CASE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
STOP Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27
SUB...END Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
Task Switch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29
WAIT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
WHEN ERROR Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31
WHILE...WHILE END Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
CPL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34

Appendix A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Example CPL Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Appendix B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
CPL Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Tracer Summit Custom Programming

Preface
Tracer Summit Software

F Unauthorized use of the software or

related materials discussed in this
manual can result in civil damages and
criminal penalties.

Copyright American Standard, Inc. 1997

All rights reserved.
Use of the software contained in this
package (BCU or PC Workstation) has been
provided under a software license
agreement. The terms of this license are
included with the software diskettes. Please
read them thoroughly.
The Trane Company has conducted testing
on the system described in this manual.
However, Trane does not guarantee that the
system contains no errors.
The Trane Company reserves the right to
revise this publication at any time and to
make changes in its content without
obligation to notify any person of such
revision or change.
The Trane Company may have patents or
pending patent applications covering items
in this publication. By providing this
document, the Trane Company does not
imply giving license to these patents.

About This Manual

This book applies to Tracer Summit
software version 6.0 and later. This book
is part of a seven-volume set. Refer to
BAS-EB-57, Tracer Summit Software
Versions, for a list of literature numbers
applicable to all versions of Tracer Summit.

Tracer Summit Custom Programming

Trademarks
The following are trademarks of their
respective companies: ARCNET from
Datapoint Corporation, BACnet from
ASHRAE, IBM, Operating System/2,
OS/2, and PS/2 from IBM Corporation,
Paintbrush and PC Paintbrush from
ZSoft Corporation, Paint Shop Pro from
JASC, Inc., Windows from Microsoft,
Pentium from INTEL Corporation, and
Collage and Collage PM from Inner
Media, Inc.

The following are registered trademarks

of their respective companies:
Microsoft and MS-DOS from Microsoft
Corporation, PC Paintbrush from ZSoft
Corporation, AutoCAD from Autodesk,
Inc., SMC from Standard Microsystems
Corporation, and U.S. Robotics,
Sportster, Sportster 28,800 Data/Fax,
and Sportster 14,400 Data/Fax from U.S.
Robotics, Inc.

Preface

This manual describes how to create, edit,

save, compile, download, and test CPL text
files. This guide also contains a chapter
dedicated to CPL syntax.
Refer to the Contents or Index for a list of
items covered by this manual.

Typographical Conventions
The following typographical conventions are
used throughout this manual:

& Additional Reading

For information about installation, setup,
and operation of your Tracer Summit
system, consult the following volumes in the
Tracer Summit literature set:
Volume 1: Hardware Installation
Volume 2: Software Setup
Volume 3: Unit Control Modules
Volume 4: Applications

BOLD ITALICIZED
UPPER CASE

Text you must type

exactly as shown.

Volume 5: Custom Programming

Italicized

Menu selections,
check boxes, and push
buttons selectable with
the mouse.

Volume 7: Library

Bold

Proper names, such as

dialog boxes, entry
fields, list boxes, and
editors.

ITALICIZED UPPER
CASE

User-dependent
information you enter
(for example, date or
time).

Volume 6: Daily Operations

For a list of the literature numbers that apply

to your version of Tracer Summit software,
refer to BAS-EB-57, Tracer Summit Software
Versions.

Screen Nomenclature
The diagrams on the following pages display
names assigned to different areas of typical
Tracer Summit windows and dialog boxes.

ii

Tracer Summit Custom Programming

Preface

Title Bar Icon

Title Bar

Selected Menu Items

Minimize/Maximize Buttons

Menu Bar

Window Display
Areas
Scroll Bar

Selected
Menu Item
Description
Pull-down
Menus

Slider Bars

Tracer Summit Custom Programming

iii

Preface

Entry Field

Check Box

Radio Buttons

Group

Drop-down List Box

Push Buttons
List Box

Scroll Bars

iv

Tracer Summit Custom Programming

General Information
This chapter serves as a programming
reference for system supervisors and
qualified technicians (hereafter referred to
collectively as programmers) using the
Custom Programming Language (CPL)
application. Use CPL to perform functions
and calculations that cannot be done by
other applications within Tracer Summit.
CPL Features & Applications
CPL allows programs to be customized to
meet the applications required to monitor or
operate the site, building, and/or system.
CPL can be used to write programs in the
CPL Editor, compile programs on the PC
Workstation, create CPL programs (as
objects) in the database, and execute
programs in a BCU. The list below defines
CPL features and typical applications.

A variable execution frequency

(seconds, minutes, hours, days). CPL
programs can be event driven (for
instance, run on an alarm condition).
The ability to define named routines that
perform common calculations such as
enthalpy or mode control. Some features
of these routines are input parameters,
re-entrant, local variables, and return
value and/or output parameters.
Sixteen global variables per CPL
program that can be used as dynamics on
graphic displays, set up as analog inputs,
or passed between CPL programs.
A test mode in CPL that allows testing
of a CPL object in a BCU.

Typical CPL features include:

A context-free language, meaning
language statements can be formatted as
the programmer chooses, separating
words with multiple spaces and lines.
Numerous routines and functions, which
can be implemented by using symbols
(up to 256) that include variable, label,
and procedure names.
Looping, which reduces lists of
repetitive statements and promote arrays
of all data types available for data
storage. CPL allows looping.

Typical CPL applications include:

Resetting setpoints based on space
conditions, building load, or time of day.
Emergency shutdown sequences.
Determining average, minimum, or
maximum temperature of a VAV group.
Making decisions based on the outside
air temperature (for instance, enabling
and disabling the economizer on an air
handler).
Calculating CFM.

Tracer Summit Custom Programming

1-1

General Information

Calculating Outdoor Air Enthalpy.

3.

Create the CPL Object in the Database.

Once the text file has been successfully
compiled, either Create a new CPL
object or Replace an existing CPL
object in the system database. During
this step, a CPL object name, a run
frequency (if any), and the BCU where
this program executes are assigned.

4.

Test the CPL Program. Once the CPL

object has been downloaded to the BCU,
use the CPL Editor to step through the
program and test the logic for accuracy.

Controlling points, especially when

conditional parameters are involved (for
instance, to test whether a valve is open
before a pump is turned on).
CPL Overview

The Tracer Summit PC Workstation is

required to create CPL programs. Once the
CPL program is created, the program is
downloaded to the system database and
stored in a specific BCU. The BCU software
schedules the CPL program to execute at a
selected frequency and performs the
program logic during each execution.
The following four procedures must be
performed in order to successfully create and
test a CPL program object:
1.

Edit the CPL Text File. CPL text files

are edited using the CPL Editor. Using
the CPL Editor is preferred because it
contains features specific to CPL. The
text file contains program logic
statements and comments. When the text
file is complete, assign it an eight
character DOS file name and give the file
an extension of .CPL. Once the CPL text
file is saved, go to step 2.

2.

Compile the CPL Text File. Once the

text file is loaded into the CPL Editor,
the syntax can be checked and corrected
(if needed). When the syntax is error
free, the text file can be compiled.
Compiling the text file creates a CPL
object that can be downloaded to the
system database.

1-2

The following sections of this chapter

overview the menu selections of the CPL
Editor and describe these four steps in
detail. Refer to Appendix A for examples
of CPL programs.

Tracer Summit Custom Programming

General Information

Using the CPL Editor

Access the CPL Editor through the
Applications menu in the Tracer Summit
Main Window.
1.

Click the Applications menu item in the

Tracer Summit Main Window.

2.

Click the Custom programming

language... item in the pull-down menu.

3.

The CPL Editor window displays.

The CPL Editor uses the facilities of OS/2

Presentation Manager. This provides a
graphic windowing interface with a menu
method of operation. The CPL Editor works
on only one program at a time, the one
currently in the Edit window. From this
window, all the features of the CPL Editor
are accessible. The CPL Editor edits,
compiles, downloads, and debugs CPL
programs. The following pages provide
tables for the first five menu bar items that
describe their associated submenu items.

Tracer Summit Custom Programming

1-3

General Information

The File menu item manages CPL

text files.

New. Use this command to create a new CPL text file. The Edit window is cleared and the cursor is
placed at the top left corner.
Open... Use this command to display an existing CPL text file in the CPL Editor. An Open dialog
box displays allowing you to retrieve a CPL text file from a specific drive and subdirectory.
Merge...Use the Merge command to insert an existing CPL text file into the displayed file at the
current cursor position. An Open dialog box displays, allowing you to merge a CPL text file from a
specific drive and subdirectory.
Save. Use the Save command store an existing CPL text file to disk with the same name.
Save As... Use the Save As command to store the existing CPL text file to disk with a different
name.
Delete...Use the Delete command to specify the name of the CPL text file to be deleted.
Print Setup... Use this command to configure printer settings, such as layout and paper size.
Print The Print command sends the CPL text file to the system printer.
Token Dump This option is used for troubleshooting by BASD personnel. If you are having troubles
compiling a CPL text file, BASD personnel may ask you to perform a token dump, which displays
below the CPL file, and send either a printout or a file to them for inspection. BASD uses the data to
verify whether files are compiling correctly.
Save Token Dump As . . . This option saves troubleshooting information, which is used by BASD
personnel. If you are having problems compiling a CPL text file, BASD personnel may ask you to
perform a token dump and save it to a file. BASD uses the information to verify whether files are
compiling correctly.
Exit. Use the Exit command to close the CPL Editor and return to the Tracer Summit Main
Window.

1-4

Tracer Summit Custom Programming

General Information

The Edit menu item is used to

assist with editing CPL text
files.

Undo. Use the Undo command to undo the last editing change made.
Cut. Cut removes the selected text from the CPL text file and places it in the clipboard.
Copy. Copy takes the selected text and places it in the clipboard without removing it from the CPL
text file.
Paste. Paste takes the contents of the clipboard and places it in the CPL text file at the current
cursor location.
Delete. Delete removes the selected text from the CPL text file and discards it. Unlike the Cut
command, it does not get placed in the clipboard.
Add Statement. This command displays a list box containing all the CPL statement structures. To
enter a statement, select the desired statement from the list. It is inserted in the CPL text file at the
current cursor location.
Add Function. This command presents a list box containing all the functions provided with CPL.
To add a function to the program, select the desired function from the list. It is inserted in the CPL
text file at the current cursor location.
Add Object. This command displays the standard Objects and Properties dialog box. By
selecting the desired object, you can add it to the CPL file at the current cursor location.
Add Obj&Property. This command displays the standard Objects and Properties dialog box. By
selecting the desired object and property, you can add it to the CPL file at the current cursor
location.
Add Enum Bool. This command displays the standard Objects and Properties dialog box. By
selecting the desired object and property, you can select an enumeration that is entered into the
CPL file at the current cursor location. This is useful for multi-state and binary properties.
Find/Change. This command displays a dialog box where you enter the text string. The CPL
Editor then scans the text file for the text string. Once entered, the search is begun at the current
cursor location and proceeds to the end of the CPL text file. The dialog box also allows you to
enter a text string to be scanned and the text string to replace it. Beginning at the current cursor
location, each occurrence of the search string is found and replaced with the change string until
the end of the CPL text file.
Select all. This command selects every line in the CPL program. The selected text can then be cut
or copied to the clipboard.
Go To Line... This command prompts you for the line number to move to. The cursor is placed at
the beginning of the entered line if that line number exists.

Tracer Summit Custom Programming

1-5

General Information

The Program menu item is

used to work with CPL program
objects.

Open CPL Object... This command displays an existing CPL program object in the CPL Editor. A
Select CPL Program dialog box displays, which allows you to select a CPL object. The CPL object
is automatically decompiled and presented in a text file format.
Create CPL Obj... Use this command to download a compiled CPL text file as a new CPL object
to the system database.
Replace CPL Obj... Use this command to download a compiled CPL text file over an existing CPL
object to the system database.
Compile. This command works on the CPL text file currently in the CPL Editor. It performs a syntax
check and verifies that all objects and properties in the text file exist in the database. A successful
compile results in a CPL program object file being built.
Syntax Check. This command checks the syntax of the CPL text file. Syntax check differs from
Compile in that object and property names are not verified with the system database and the CPL
object is not built. Syntax Check is useful when CPL programs are being created on an offline PC
Workstation.

1-6

Tracer Summit Custom Programming

General Information

The Test menu item is used when

the programmer is testing the
execution of the current program.*

Run Program. This command executes the program from the current statement line and continues
to the next break point or to the end of the program.
Debug Program. This is a dual function command that allows you to select a CPL program object
to test. The selected program is ready for execution at the first statement. Stop Debug
discontinues the debug program function.**
Step. This command executes the next statement in the program.
Halt. This command stops/halts a running debug program that has not returned control to the
CPL Editor.
View Variable... Use this command to view the current value of variables and properties used in
this program. By stepping through the program and viewing the variables and properties, you can
debug the program.
Set Break. Use this command to set breakpoints at the beginning of statements. Breakpoints halt
execution when and if they are reached.
Clear Break. Use this command to remove an existing breakpoint.
Next Breakpoint. Use this command to view each sequential breakpoint in turn.
Home Halt Point. This command places the cursor to the statement where the program is
currently halted.
Calling Sequence. Use this command to view all calls to subroutines and functions used to get to
the current point in the program.
Inhibit DB writes. Use this command to run a CPL program object without performing any outputs
to the system database.
Debug Color. Use this command to select a color for the background that appears while the debug
program is running.

+
+

*This menu item is available only when the PC Workstation is online.

**When a CPL program is in the debug mode, the programmer is manually running the CPL
program. All outputs from the program are performed unless Inhibit DB writes: is selected.

Tracer Summit Custom Programming

1-7

General Information

The Options menu item is

used to change the CPL
Editors screen performance.

Description Bar. This command is a check item switch used to select whether menu and command
descriptions are displayed at the bottom of the CPL Editor screen.
Query Lines. This command displays the total number of source statement lines in the current CPL
program object file.
Word Wrap. This command is a toggle that enables or disables auto word wrapping at the end of
the CPL text file statement lines.
Background Color. Use this command to change the background color of the CPL Editor screen.
Screen Font. Use this command to change the test font that displays on the CPL Editor screen.

1-8

Tracer Summit Custom Programming

Editing CPL Text Files

Creating a CPL Text File
The structure of a CPL text file is a cross
between C and Microsoft Quick BASIC. The
general steps required to edit a CPL text file
are:
1.

Start the text editor, which is used to

create the initial CPL text file.

2.

Type the word PROGRAM on the first

line of the program to let Tracer Summit
know that it is the beginning of a CPL
program and then type a name for the
program.

3.

Add a header to the program.

4.

Define the variables for the program.

5.

Using the CPL syntax, define the

calculations and control statements that
the program will use.

6.

Type the word END on the last line of

the program to let Tracer Summit know
that the program is done.

7.

Save the program with a .CPL

extension.

Tracer Summit Custom Programming

2-1

Editing CPL Text Files

Example Program:
Program AREA1_SHUTDOWN
// Written: December 15, 1992 by Ryan Smith
// Modifications:
//
//

1/12/93 RAS:
Added enumerations for On and Off

// Properties modified:
//
//
//
//
//

{AHU1 Fan Start/Stop}.{Present Value}

{Smoke Dampers EP-1}.{Present Value}
{Smoke Dampers EP-2}.{Present Value}
{AREA1 VAV Supply Drive Closed}.{Present Value}
{AHU1 Fan Purge}.{Present Value}

/// This program is executed by Binary Input AREA1 ALARM;

/// therefore, the frequency should be set at 0 seconds.
/// This program turns the AHU Off, drives the smoke dampers
/// closed, and drives the VAV boxes closed anytime the area
/// alarm sensor is turned On.
/// This CPL object uses the text file named AREA1SD.CPL
Defint
On = 1,
Off = 0,
Closed = 1,
Open = 0,
Auto = 0

// Define enumerations

// First Half (SHUTDOWN)

If ({AREA1 ALARM}.{Present Value} = On) Then
// If alarm switch is turned On
Control ({AHU1 Fan Start/Stop}, {Present Value}, Off, 5, SET)
// Turn the fan Off (PCM1 BSP1)
WAIT 00:01:00
//Wait 60 seconds

Control ({Smoke Dampers EP-1}, {Present Value}, Closed, 5, SET)

Control ({Smoke Dampers EP-2}, {Present Value}, Closed, 5, SET)
// Drive dampers closed
Control ({AREA1 VAV Supply Drive Closed}, {Present Value}, Closed, 5, SET)
// Drive VAV Supply Boxes Closed
(Continued next page...)

2-2

Tracer Summit Custom Programming

Editing CPL Text Files

// Second Half (NORMAL)
Else

// If alarm switch is turned Off

Control ({Smoke Dampers EP-1}, {Present Value}, Open, 5, SET)
Control ({Smoke Dampers EP-2}, {Present Value}, Open, 5, SET)
// Drive dampers open
Control ({AREA1 VAV Supply Drive Closed}, {Present Value}, Auto, 5, SET)
// Release VAV Supply Boxes to Auto
WAIT 00:01:00
//Wait 60 seconds
Control ({AHU1 Fan Start/Stop}, {Present Value}, On, 5, SET)
// Turn the fan On (PCM BSP)
Control ({AHU1 Fan Purge}, {Present Value}, Off, 5, RELEASE)
// Release the outside air dampers, in case of purge

End If
End

Tracer Summit Custom Programming

2-3

Editing CPL Text Files

Assigning Objects and Properties

The most important data in the Tracer
Summit system is held in the objects and
their associated properties. Unlike variables
that are declared and used only as long as
the CPL program is executing, objects and
properties are part of the system and do not
need to be declared before being used. Every
property has a predefined type, so no data
type character suffix is used when specifying
these data items.
CPL programmers have access to a major

subset of the objects defined in the database.

The programmer can directly enter an object
name or property name, if it is known. To
assist the programmer in specifying an
object and property, the CPL Editor has
object and property selection dialog boxes
that can be accessed using the Edit menu in
the CPL Editor.

complete object, the delimited name is not

followed by a property name ({FINANCE
DEPT TCM}).
To indirectly reference an object, CPL
provides an object pointer. These can be
defined with the DEFOBJ statement. These
variables are useful for being passed to
procedures that process an object and/or
property. When not pointing to an object,
object pointers have a null value.
Example:
1

DEFOBJ RTU

RTU1 = {FINANCE DEPT TCM

not
RTU1 = {FINANCE DEPT TCM}.{PRESENT VALUE}

The CPL text file uses object names from the

Tracer Summit system assigned by the
programmer. The object and property names
used in the CPL text file must be identical to
the names that appear in the system (for
instance, in the VAV Editor).
The CPL interpreter running internally in the
BCU uses the object ID for identification and

Syntax:
Whether selected or directly typed, the
object name portion is delimited with
opening and closing braces { } and
optionally followed by a property name
separated by a period ({FINANCE DEPT
TCM}.{Present Value}). To specify the

2-4

not the object name. Therefore, changing the

names externally (with the UCM editors)
does not affect the execution of the CPL
program. However, it affects the results
when you compile the CPL text file. Having
object names in the CPL text file that do not
correspond exactly to the object names
found on the Tracer Summit system
generates syntax errors. You then need to
search through the database to find and
correct the discrepancy.

Tracer Summit Custom Programming

Editing CPL Text Files

Therefore, to compile a CPL text file

successfully, it is critical that these names
match both in the CPL text file and on the
Tracer Summit system in the various UCM
editors.

OK push button. The Enumeration/Boolean

dialog box (shown below) displays, allowing
you to select the desired enumeration.

Assigning Enumerations
In the Tracer Summit system, all binary and
multi-state properties are treated internally
as an integer. For example, the state of a
binary output objects present value property
is either On or Off. Internally, On is
associated with the integer 1 and Off is
associated with the integer 0.
To make CPL programs easier to read, these
internal numbers (integers) can be converted
to Enumerations. Enumerations are the
association between words and integers. For
example, it can be specified in a CPL
program that anytime the word Off
appears in the program, the Tracer Summit
software interprets that word as the integer 0.
Enumerations are created using the DEFINT
statement (refer to Chapter 3 for more
information on DEFxxx statements). If you
know the integers associated with the
enumeration, you can define these directly
while creating the CPL program (some
common enumerations are: On = 1, Off = 0,
Enabled = 1, Disabled = 0). However, the
defined integers associated with a particular
propertys enumerations are not always
known (for instance, the numbers associated
with the switch settings for the chiller front
panel).
To assist in assigning enumerations, select
the Add Enum Bool submenu from the Edit
menu in the CPL Editor (refer to page 2-7).
The Select Object Type, Name, and
Property dialog box appears. Select the
desired property from the list and click the

Tracer Summit Custom Programming

The enumeration is then defined as an

integer with the proper syntax at the top of
the CPL program. If the enumeration is
entered without the assistance of the CPL
Editor, make sure the integer is correct and
corresponds to the integer recognized
internally by the Tracer Summit software.
For example, you are writing a CPL program
in which the present value of a PCM
(attached to AHU1) is controlled to priority
shutdown. You want to define an
enumeration for priority shutdown. To do
this perform the following steps (refer to
example programs 1 and 2 on the following
pages):

2-5

Editing CPL Text Files

1.

2.

2-6

Put the cursor at the location in the CPL

program being written where the
enumeration is to occur (for instance, at
the location in the control statement
where the present value of the PCM is
controlled on or off).

3.

Select the PCM object type, AHU1 object

name, and PRESENT VALUE object
property and click the OK push button.
The Enumeration/Boolean dialog box
displays with the selectable
enumerations listed.

4.

Choose Priority Shutdown from the

available list and click the OK push
button.

5.

The program adds the words

Priority_Shutdown where the cursor
was located. At the top of the program it
automatically defines an integer for
Priority_Shutdown and sets it equal to 6
(6 is the integer recognized internally by
the system as Priority_Shutdown for the
present value of the AHU1 PCM).

Select the Edit menu from the CPL

Editor menu bar and Add Enum Bool
from the menu. The Select Object Type,
Name, and Property dialog box
displays.

Tracer Summit Custom Programming

Editing CPL Text Files

Note: It is critical that the

enumeration, once defined, appear
the same throughout the entire
program (matching spelling, upper
and lower case).
Note: If desired, the DEFINT
statement can be moved to another
location in the CPL Editor.

Tracer Summit Custom Programming

2-7

Editing CPL Text Files

Example Program 1:
This is an example of a CPL text file before
an enumeration is assigned.
Program AHU1_SHUTDOWN
// Written: December 15, 1992 by Ryan Smith
// Modifications:
//

None

// Properties modified:
//

{AHU1 PCM}.{Present Value}

/// This program is executed by Binary Input AHU1 ALARM;

/// therefore, the frequency should be set at 0 seconds.
/// This program turns the AHU Off anytime the binary input
/// AHU1 ALARM is turned On.
/// This CPL object uses the text file named AHU1SD.CPL
Defint
On = 1, // Define enumerations
Off = 0
If ({AHU1 ALARM}.{Present Value} = On) Then
// If alarm switch is turned On
Control ({AHU1 PCM}, {Present Value},6 , 2, SET)
// Turn the AHU Off
Else
// If alarm switch is turned Off
Control ({AHU1 PCM}, {Present Value},6 , 2, RELEASE)
// Release the AHU to normal control
End If
End

2-8

Tracer Summit Custom Programming

Editing CPL Text Files

Example Program 2:
This is the same CPL text file after the CPL
Editor assigns the enumeration.
Defint Priority_Shutdown = 6
Program AHU1_SHUTDOWN
// Written: December 15, 1992 by Ryan Smith
// Modifications:
//

None

// Properties modified:
//

{AHU1 PCM}.{Present Value}

/// This program is executed by Binary Input AHU1 ALARM;

/// therefore, the frequency should be set at 0 seconds.
/// This program turns the AHU Off anytime the binary input
/// AHU1 ALARM is turned On.
/// This CPL object uses the text file named AHU1SD.CPL
Defint
On = 1, // Define enumerations
Off = 0
({AHU1 ALARM}.{Present Value} = On) Then
// If alarm switch is turned On

IF

Control ({AHU1 PCM}, {Present Value}, Priority_Shutdown, 2, SET)

// Turn the AHU Off
Else
// If alarm switch is turned Off
Control ({AHU1 PCM}, {Present Value}, Priority_Shutdown, 2, RELEASE)
// Release the AHU to normal control
End If
End

Tracer Summit Custom Programming

2-9

Editing CPL Text Files

Assigning Arrays
Tracer Summit CPL allows arrays of objects
and/or properties to be created to reduce the
number of CPL statements needed for a CPL
program. Arrays also make it easier to edit a
CPL program once it has been created by
arranging objects/properties in a specific
order. Arrays are typically used in CPL
programs where repetitive calculations are
performed (such as programs that use
FOR...NEXT statements).
Syntax:
Defint

[6]
[1]={object}.{property}
BIP[2]={object}.{property}
BIP[3]={object}.{property}
BIP[4]={object}.{property}
BIP[5]={object}.{property}
BIP[6]={object}.{property}
BIP
BIP

Defobj

[6]
[1]={object}
BOP[2]={object}
BOP[3]={object}
BOP[4]={object}
BOP[5]={object}
BOP[6]={object}
BOP
BOP

2-10

Tracer Summit Custom Programming

Editing CPL Text Files

Example Program:
The following example is a program that
looks at the status of binary inputs set up in
an array, goes through this array in the
program, and matches a binary output to the
binary input. The binary output might be
directed to another TCM binary output that
controls a lighting status panel somewhere
else in the facility.
PROGRAM

Motion_Status_Lights

// Written 11/20/92, by Seymour Anderson

// Properties modified: (BOPs)
//
{Area1 Status Light}.{Present Value}
//
{Area2 Status Light}.{Present Value}
//
{Area3 Status Light}.{Present Value}
//
{Area4 Status Light}.{Present Value}
//
{Area5 Status Light}.{Present Value}
//
{Area6 Status Light}.{Present Value}
// Properties read: (BIPs)
//
{Area1 Motion}.{Present Value}
//
{Area2 Motion}.{Present Value}
//
{Area3 Motion}.{Present Value}
//
{Area4 Motion}.{Present Value}
//
{Area5 Motion}.{Present Value}
//
{Area6 Motion}.{Present Value}
/// This program monitors the status of several binary inputs throughout the building
/// and directly controls matching binary outputs connected to the status light panel
/// in the security station.
/// This program is executed anytime a binary input changes state.
/// This CPL object uses the text file named AREASTAT.CPL
DEFINT

Off = 0, // Enumeration for Off

On = 1, // Enumeration for On
NUMB = 6,
// Define number of binary inputs
BIPS[NUMB],
// Define array for binary inputs
i
// Define index for FOR-NEXT statement
(Continued next page...)

Tracer Summit Custom Programming

2-11

Editing CPL Text Files

DEFOBJ
BOPS[NUMB]

// Define array of binary outputs that will

// match the binary inputs

// Define the array of binary inputs
BIPS[1] = {Area1 Motion}.{Present Value}
BIPS[2] = {Area2 Motion}.{Present Value}
BIPS[3] = {Area3 Motion}.{Present Value}
BIPS[4] = {Area4 Motion}.{Present Value}
BIPS[5] = {Area5 Motion}.{Present Value}
BIPS[6] = {Area6 Motion}.{Present Value}
// Define the array of binary outputs
BOPS[1] = {Area1 Status Light}
BOPS[2] = {Area2 Status Light}
BOPS[3] = {Area3 Status Light}
BOPS[4] = {Area4 Status Light}
BOPS[5] = {Area5 Status Light}
BOPS[6] = {Area6 Status Light}
For i =1 to NUMB step 1
If (BIPS[i] = On)
Then
CONTROL(BOPS[i], {Present Value}, On, 5, SET)
// Turn the simulating BOP ON
Else
CONTROL(BOPS[i], {Present Value}, Off, 5, SET)
// Turn the simulating BOP OFF
End If
Next
End

2-12

Tracer Summit Custom Programming

Editing CPL Text Files

Using Saved Values

Each CPL program has 16 properties called
saved values. Saved values can store
variables in memory between CPL
executions, share CPL variables with other
CPL programs or applications within the
Tracer Summit system, or display on a
graphic. For example, an analog input can be
set up to reference a CPL saved value and
alarm if it exceeds one of the high or low
alarm limits (refer to Volume 4,
Applications for more information on setting
up analog inputs).
Typically, a saved value is used when you
want to save a calculation from one
execution to the next (such as a timer or
counter).

F Note: CPL variables are initialized to

zero and are not saved between CPL
executions. Therefore, CPL variables
must be assigned a value at the start of
the program or calculate a new value
each time the CPL program runs.
Syntax:
If the you want to read or write a saved
value within the same CPL program:
Local.{Saved Value}[1]

If you want to read or write a saved value

from another CPL program object:
{CPL object name}.{Saved Value}[1]

Note: The number within the

square bracket indicates the array
number of the saved value (1-16).

Tracer Summit Custom Programming

2-13

Editing CPL Text Files

Example Program:
In the following example, a timing function
is performed based on a local saved value.
Program Exhaust_Fan1
// Written 3/22/97 by Eugene Jones
// Properties modified:
//
{Exhaust Fan1}.{Present Value}
//
Local.{Saved Value}[1]
// Properties read:
//
{Warehouse Temperature}.{Present Value}
//
{Warehouse Exhaust Fan Setpoint}.{Present Value}
/// This program controls the exhaust fan for the warehouse on anytime the space
/// temperature exceeds setpoint for 10 minutes.
/// This program is executed every minute to keep timers in sync.
/// This CPL object uses the text file named EXHAUST1.CPL
Defint
Off = 0, //Enumeration for Off
On = 1, //Enumeration for On
Timer_1
// If space temperature is 1 F above setpoint, start 10 minute timer
If
({Warehouse Temperature}.{Present Value} > ({Warehouse Exhaust Fan Setpoint}.{Present
Value} +1))
Then
Timer_1 = Local.{Saved Value}[1] + 1
Else
Timer_1 = 0
End If
// Control the exhaust fan On or Off
If (Timer_1 > 10) Then
Control({Exhaust Fan1}, {Present Value}, On, 5, SET)
Else
Control({Exhaust Fan1}, {Present Value}, Off, 5, SET)
End If
// Store Timer value for the next execution
Local.{Saved Value}[1] = Timer_1
End

2-14

Tracer Summit Custom Programming

Editing CPL Text Files

Saving the CPL Text File

Once the CPL program is written and before
it is compiled, downloaded, and tested, the
CPL text file must be saved.

F Note: Save CPL text files frequently

during creation to avoid losing work.
To save a CPL text file:
1.

Select the File menu from the CPL

Editor main menu and select the Save or
Save As... item from the menu (see
figure on the right). If the text file is
new, the Save item is grayed.

2.

The Save As dialog box displays.

3.

Choose the desired subdirectory from

the Directory list box. It is
recommended that CPL text files be
stored in the C:\SUMMIT\CPL
subdirectory.

4.

Type in the desired name for the text file

using the .CPL extension in the Save as
Filename field.

Tracer Summit Custom Programming

5.

Click the OK push button.

Note: CPL text files reside on the

PC Workstation database. (For
more information on transferring
CPL text files between PC
Workstations, refer to Appendix
A of Volume 2, Software Setup).

2-15

Editing CPL Text Files

Compiling a CPL Text File

Once the text file for the CPL program is set
up, the next step is to compile the program.
Compiling the text file structures the
information into a CPL object format so that
it can be downloaded into the Tracer
Summit database.

Loading a Text File into the CPL

Editor
To load a CPL text file into the CPL Editor:
1.

Select the File menu from the main

menu bar in the CPL Editor and the
Open... item from the menu.

2.

The Open File dialog box displays.

Select the appropriate subdirectory from
the Directory list box (CPL text files
should be stored in the C:\SUMMIT\CPL
subdirectory). The name of the CPL text
file displays in the File: list box. Click
the file you want to open. It displays in
the Open Filename field.

The general steps used to compile a CPL text

file are:
1.

If a text editor was used instead of the

CPL Editor, start the Tracer Summit

program and select the Custom

Programming Language application
from the Applications menu in the
Tracer Summit Main Window.
2.

Open the .CPL file just created in the

text editor.

3.

Run the Syntax Check function.

4.

Correct any syntax errors found in the

program.

5.

Run the Compile function.

6.

Correct any errors found in the program.

F Note: If syntax corrections are made, be

sure to resave the CPL text file.
In the following sections, it is assumed that
the Tracer Summit program has been started
and you are ready to load a CPL text file.

2-16

Tracer Summit Custom Programming

Editing CPL Text Files

3.

box identifies the line in the program

where there is a syntax error and the
type of error that occurred.

Click the OK push button. The CPL

Editor redisplays with the selected CPL
text file loaded.

Check the Syntax of the Text

File
To check the syntax of the CPL text file:
1.

2.

Select the Program menu from the main

menu bar in the CPL Editor and the
Syntax Check item from the menu.

The CPL Editor analyzes the loaded

CPL text file for syntax errors. If there
are no syntax errors, the Compile
Results dialog box displays a green
background color. If there are syntax
errors, the Compile Results dialog box
displays a red background. This dialog

Tracer Summit Custom Programming

Note: Depending on how the text

file was edited, the line given as
the location of the syntax error may
actually be the line after the
location where the error occurred
(for instance, the line indicated is
line 31 of the program but the error
may really be on line 30).
Therefore, look at the line
indicated and the line before it
when looking for syntax errors.

3.

Correct any syntax errors found in the

CPL text file (refer to the Creating a
CPL Text File section earlier in this
chapter).

4.

After corrections are made and a green

background color appears after running a
Syntax Check, click the OK push
button.

5.

Save the CPL text file again (refer to

Saving a CPL Text File found earlier
in this chapter). It is important to save
the file after a successful syntax check.

2-17

Editing CPL Text Files

Compile the Text File

Compiling the CPL text file performs the
same function as the syntax check, in
addition to verifying that the object and
property names used in the program are
valid objects and properties in the database.
The names of objects and properties used in
the program must match the names in the
database exactly. Errors generated here
probably mean that an object and property
name has been misspelled. To compile the
text file:
1.

Select the Program menu from the CPL

Editor main menu bar and select
Compile from the menu.

2.

The CPL Editor analyzes the currently

loaded CPL text file for syntax errors and
valid object and property names. If there
are no syntax errors and the object and
property names are valid, the Compile
Results dialog box displays a green
background. If there are syntax errors or
misspellings in the object and property
names, the Compile Results dialog box
displays a red background and identifies
the line in the program where the error
occurred.

generated, but fail if errors are

generated.
3.

After corrections are made and a green

background color displays after running
Compile, click the OK push button.

4.

Note: Correct spelling for names of

objects and properties can be
viewed by selecting Add Obj &
Property... from the Edit menu.

Save the CPL text file again (refer to

Saving a CPL Text File found earlier
in this chapter). It is important to save
the text file after a successful compile.

F Note: In addition to errors, there are

also warnings. Programs can
successfully compile when warnings are

2-18

Tracer Summit Custom Programming

Editing CPL Text Files

Creating a CPL object in the

database
In this step, a successfully compiled CPL
text file is used to create a CPL object in the
Tracer Summit database. During this step,
you will be selecting:
The CPL object name.
The security classes.
The CPL frequency (if any).

b.

And the BCU where the CPL object will

be stored.
To create a CPL object:
1.

Select the Program menu from the CPL

Editor main menu bar and select Create
CPL Obj... if creating a new CPL object,
or Replace CPL Obj... if overwriting an
existing CPL object. If replacing an
existing CPL object, go to Step 3.

2.

If creating a new CPL object:

a.

The Save as new CPL Program

dialog box displays. Select from the
BCU: drop-down list box the BCU
where the CPL program object will
be stored. Store the CPL object in
the same BCU that most of the
objects and properties referenced in
the CPL program reside.

Tracer Summit Custom Programming

Type the name that the CPL object

will be saved as in the CPL
Program Name: field. The default
is the name entered for the CPL text
file. Do not change the name.

Note: If special startup

sequences are required after a
power failure, naming a CPL
program object STARTUP_1,
STARTUP_2, etc. causes the
program(s) to execute before
all other applications execute
after the power is restored on
the BCU. See the example
program in Appendix A of
this volume.

c.

Assign security classes by selecting

the Security Classes... push button.
For more information on assigning
security classes, refer to Volume 2,
Software Setup. (Security Classes
can also be assigned in Step f).

d.

Click the OK push button. The

Property Edit dialog box displays.

2-19

Editing CPL Text Files

e.

f.

2-20

If a description other than the

program name is desired, type a
brief description in the Program
Description field. The default for
this field is the program name. Do
not change the name.

g.

The Run Frequency group allows

you to define the frequency that the
CPL program runs. The frequency is
set by clicking the up/down arrows
on the right of the scroll boxes. It is
recommended that CPL programs
run no faster than every 30 seconds.
Normally, programs run every
minute, every hour, every day, or
are event-driven, based on the
functions performed in the CPL
program.

h.

After the frequency is set, click the

OK push button.

i.

A Status dialog box displays stating

whether the download operation
was successful. If the PC
Workstation is online, a Successful
Operation Online message
displays. If the PC Workstation is
offline, the CPL Editor downloads
the CPL object to the PC
Workstation database and a
Successful Operation Offline
message displays. When the PC
Workstation goes online, it
downloads the CPL object to the
selected BCU.

j.

Click the OK push button to return

to the CPL Editor.

Assign security classes by selecting

the Class push button. For more
information on assigning security
classes, refer to Volume 2, Software
Setup. (Security classes can also be
assigned in Step c).

Tracer Summit Custom Programming

Editing CPL Text Files

3.

If replacing an existing CPL object in the

database:
a.

Select Replace CPL Obj... from the

Program menu. The Select CPL
Program Object dialog box
displays (shown below).

b.

Select the CPL program object to be

replaced and click the OK push
button.

c.

The Property Edit dialog displays.

Follow Steps e through j as
described under Step 2 to complete
the procedure for replacing an
existing CPL object.

Tracer Summit Custom Programming

2-21

Editing CPL Text Files

Testing a CPL Program

Testing allows you to step through a specific
CPL program to view variables, properties,
and verify proper performance of the
program. To test a CPL program:
1.

Select Test from the CPL Editor main

menu bar and select Debug Program
from the menu. The Select CPL
Program dialog box displays.

3.

As the CPL Editor performs the test, the

background color of the screen changes
to cyan. Refer to Appendix B for
explanations on error codes and possible
solutions.

F Notes: When a CPL program is in the

debug mode, the programmer is
manually running the CPL program. All
outputs from the program are performed
unless the Inhibit DB writes: menu item
is also selected.
When a CPL program is in the debug
mode, WAIT statements are executed.
For longer WAIT statements, it is
recommended that they temporarily be
shortened or commented out (insert //
or /// in front of the statement and
recompile) before testing the CPL
program.

2.

Highlight the program you want to test

and click the OK push button or double
click the desired program.

2-22

Note: CPL testing can only be

performed when the PC
Workstation is online with the BCU
containing the CPL object.

Tracer Summit Custom Programming

CPL Syntax
CPL Program Words

CPL Reserved Words

ABS
AFTER
AND
AVG
Reserved words
CALL
Reserved words are those in the language
CASE
that have a predefined meaning like FOR, IF, CONTROL
or PROGRAM. Reserved words are case
CLNG
insensitive, meaning that the mix of
DATE
capitalized letters and lower case letters does DATENOW
not matter. For and FOR are regarded as
DATEVALUE

HOUR
IF
IMP
INT
IS
LESS_EQUAL
LET

DAY
DAYOFWEEK
DO
User-defined words
DEFINT
User-defined words are created by you and
are used as program names, variable names, DEFLNG
DEFFLT
subroutines, functions, and labels (for goto
DEFDBL
statements). Unlike reserved words,
DEFOBJ
user-defined words are case sensitive. This
means that the variables Temperature and DEFSTR
ELSE
temperature are different since in one
ELSEIF
instance the beginning letter is capitalized
and the other is lower case. You cannot use a END
EQV
reserved word as a user-defined word.
ERROR
User-defined words can be up to 32
EXIT
characters long (no spaces or reserved
characters). You are also restricted to 256
FIX

LOG
LOOP
MAX
MIN
MINUTE
MOD
MONTH
NEXT
NOT
NOT_EQUAL
NOW
OBJECT
OR
PRINT
PROGRAM
RELEASE

Words that appear in the program come in

two forms: reserved words and user-defined
words.

the same wordthe start of a FOR

statement. Reserved words are shown at
right.

FOR
FUNCTION
GOTO
GREATER_EQUAL

REPEAT
RESUME
SECOND
SELECT
SET
SGN
SQR
STEP
STOP
SUB
SWITCH
TASK
THEN
TIME
TIMENOW
TIMEVALUE
TIMER
TO
UNTIL
VALUE
WAIT
WEEKDAY
WHEN
WHILE
XOR
YEAR

different user-defined words per CPL

program object.
CPL Terms
A glossary of terms used in describing CPL
and its syntax is shown on the next page.

Tracer Summit Custom Programming

3-1

CPL Syntax

CPL Terminology
array
array bounds
assignment

The upper and lower limits of the dimensions of an array.

The process of transferring a value to a variable name. The
statement x = 3 assigns x a value of 3.

boolean expression

Any expression that returns the value true or false. If used as a

numeric expression, true is non-zero and false is zero.

condition

This is normally a boolean expression. Any numeric expression is

evaluated as true for non-zero values and false for zero.

constant

A value that does not change during program execution.

expression
expression list
line label
logical operators

A combination of operands and operators that yields a single value.

One or more of the following, separated by commas: numeric
expression, string expression
An ASCII name followed by a colon with no embedded spaces at
the beginning of a line.
NOT, AND, OR, XOR, EQV, IMP

numerical operators

^, *, /, \, MOD, +, -

numeric-expression

Any expression that returns a numeric value. If used as a boolean

expression, a non-zero value is true and 0 is false.

object_var

An object variable that points to or references a specific object.

operand

A constant or variable value that is manipulated in an expression.

operator

One or more symbols that specify how the operand or operands of

an expression are manipulated.

prop-name

A predefined constant that specifies the property of an object.

relational operation

This is a relational operator followed by an expression.

relational operators

=, <>, <, <=, >, >=

variable

3-2

A sequentially numbered set of elements with the same type.

A value that can (and usually does) change during program

execution.

Tracer Summit Custom Programming

CPL Syntax

Scope
Global scope names are those names visible
anywhere in the program. All function and
subroutine names have global scope and can
be used anywhere in the program, as well as
variables defined outside of a function,
subroutine, and the main program body.
Names defined in the main program body, a
subroutine, and a function have local scope
and can only be referenced inside the
routines encompassing body. It is possible
to define the same local and global variable
and, in this case, the compiler uses the local
name. When a variable name is referenced,
the compiler first checks local names for a
match and then it tries the global names for
resolution.
Names can be referenced before their
definition. Functions, subroutines, labels,
and variables can be used even when their
definition appears later in the program.

Tracer Summit Custom Programming

3-3

CPL Syntax

CPL Comments
Comments begin with two or three forward
slashes and extend to the end of the line as
follows:
// This is a comment that goes to the end of this line.

Comments beginning with two slashes are

stripped and not saved in the database.
Those with three slashes are retained and
displayed when the CPL object is
decompiled.
Example
/// This is a comment that is saved in the database.
// This is a comment that is stripped off and not stored in the database.

F Note: Only comments that are critical

for describing the CPL program should
be stored in the database because
comments require BCU memory
resources.

3-4

Tracer Summit Custom Programming

CPL Syntax

CPL Data Types

Variable names keep track of where the data
is stored in the executing devices memory.
Variables are declared with DEF statements.
CPL supports 16 & 32 bit integers, 32 & 64
bit real numbers, and data type where the
eight byte object identifiers can be stored.
Integer and floating point are the numeric
data types supported. There are no true
boolean variables. CPL considers 0 to be
FALSE and any other numeric value to be
TRUE. Logical (boolean) expressions always
return zero for FALSE and non-zero for
TRUE.
Integer Variables
There are two types of integer variables:
1.

2.

Integer. Integer variables can have a

value between -32,768 and +32,767 (two
bytes of storage).
Long integer. A long integer variable
can have a value between
-2,147,483,648 and +2,147,483,647
(four bytes of storage).

Note: Integers are preferred over

long integers because they use less
memory in the BCU.

Floating Point Variables

There are two types of floating point
variables:
1.

2.

Double. A double precision floating

point variable is accurate to about 15
decimal places (eight bytes of storage).
+3.2 x 1038 to -3.2 x 1038.

Note : Single floating point

variables are preferred over double
floating point variables because
they use less memory in the BCU.

Object Variable
An object variable references an object on
the database.
Type characters are needed to identify
parameter types and function return values.
The type names, characters, and declaration
statements are shown in the table below.
Data Types
Type Name

Type
Character

Declaration
Statement

Integer

DEFINT

Long integer

&

DEFLNG

Single floating
point

DEFFLT

Double floating
point

DEFDBL

DEFOBJ

Object pointer

Single. A single precision floating point

variable is accurate to about seven
decimal places (four bytes of storage).
+3.2 x 1038 to -3.2 x 1038.

Tracer Summit Custom Programming

3-5

CPL Syntax

CPL Expressions
Expressions range from the simple to very
complex.
a = 1 // where 1 would be a simple expression
a = (((t / a) - 99.9) * ({Obj Ref}.{Property Ref}) * index) // a more complex expression

Parenthesis are important for specifying

evaluation order, because expressions in
parenthesis get evaluated first. Suppose you
want to add two numbers and divide them by
2 to obtain the average. The expression
Var1 + Var2 / 2 would not accomplish this
because Var2 would first get divided by 2
and then added to Var1.
Using parenthesis to clarify evaluation order
solves this problem: (Var1 + Var2) / 2 works
fine. By using parenthesis, you also let the
next programmer know exactly what was
intended when the expression was written.
Expression operators are shown below.
Expression

Description

Operators
=

Assignment operator or an equivalence operator in a conditional expression

< >

Not equal

Minus operator between two operands or unary minus with one operand

Multiplication operator

Division operator

Addition operator

3-6

<

Less than

>

Greater than

<=

Less than or equal to

>=

Greater than or equal to

MOD

Modulo operator

Tracer Summit Custom Programming

CPL Syntax

CPL Statements
CPL statements are CPL specific keywords,
operators, and variables that perform
predefined operations.

The following section defines and illustrates

the use of CPL statements. Syntax
conventions and their descriptions are shown
in the table below.
Syntax Convention

Description

SUB, IF, LOOP

Bold capital letters indicate language specific keywords with special

meaning to CPL. Keywords are a required part of statement syntax,
unless they are enclosed in double brackets as explained below.

name
[optional item]

Small italic letters indicate information you must supply.

Items inside square brackets are optional.

{choice1 | choice2}

Braces and a vertical bar indicate a choice among two or more

items. You must choose one of the items unless all the items are
also enclosed in double square brackets.

repeating elements...

Three periods following indicate that more of the same item may
appear.

...statement_block...

Indicates one or more valid statements on separate lines

Tracer Summit Custom Programming

3-7

CPL Syntax
CALL Statement

Syntax:
CALL subroutine-name [(argument-list)]

Comments:
The CALL statement transfers control to a
subroutine, not a function. The CALL
statement branches to a subroutine written in
CPL that is also in the text file. The
arguments to the subroutine must match the
parameters as specified in the definition of
the subroutine. The arguments may be either
variables, arrays, or expressions.
Arguments are passed by reference or by
value to procedures written in CPL. A
reference parameter passes the address of the
parameter so the original calling variable is
changed. When called by value, the original
variable is not modified. To prevent a
variable from being a reference parameter,
the variable is enclosed in parenthesis in the
CALL statement. CPL passes a copy of the
variable.
Example:
call sub_array_init( a[ ] )

// this is passing the entire array by reference and which

could be modified by the subroutine

call sub_var_init( i )

// pass by reference and the routine could modify i

call sub_var_init( a[1] )

// pass by reference and the routine could modify this array

element

call sub_calc( a+1, (a) )

// This call to sub_calc has two parameters that are both

value parameters since they are both expressions. The
parameter (a) is passed by value since it has been made
into an expression being enclosed by the parentheses.
This means that the value in the storage location
assigned to a will be passed to the routine rather than the
address of the variable.

3-8

Tracer Summit Custom Programming

CPL Syntax
CONTROL Statement

Syntax :
({object-name}, {Present Value}, value, priority, SET | RELEASE)

CONTROL

Comments:
The CONTROL statement requests a change
to the state or value of the present value of an
object. The object must be specified. The
priority array for applications requesting
control of the same property is shown below.

Priority
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
NA

Tracer Summit Default

User-Emergency
Custom Programming - No Min
Minimum On/Off
User-High
Custom Programming - High
Miscellaneous
Demand Limiting
Miscellaneous
VAV Air Systems
Chiller Plant Control
Area Control
User-Low
Miscellaneous
Timed Override
Time of Day Scheduling
Custom Programming - Low
Relinquish Default

The requested value can be a constant or an

expression. A priority is given, which is the
level at which this control request is
arbitrated with other control requests for this
object and property. Using the SET parameter
takes control at the priority given, while
RELEASE frees control at the priority.

BACnet Default
Manual Life Safety
Auto Life Safety
Miscellaneous
Miscellaneous
Critical Equipment Control
Minimum On/Off
Custom Programming - High
Manual Operator
VAV Air Systems
Chiller Plant Control
Area Control
Manual Operator - Low
Miscellaneous
Timed Override
Time of Day Scheduling
Custom Programming - Low
Relinquish Default

Note: You can choose between the Tracer Summit and BACnet default priority levels. The names for
each priority level are editable and are customizable to suit each circumstance. Refer to Volume 2,
Software Setup in the Tracer Summit literature set for more information on customizing priority levels.

Note: BACnet defaults are applicable for Tracer Summit Version 5.0 and above. Refer to Volume
2, Software Setup or BAS-EB-59 for more information on BACnet.

Example:
Control statement using an object name:
control ({Object Reference}, {Present Value}, 10, 5, RELEASE) // using constants

Control statement using an object variable:

DEFOBJ

obj ={Object Reference}

control ( obj, {PV},10, 5, SET) // using an object variable

Tracer Summit Custom Programming

3-9

CPL Syntax
DEFxxx Statement

Syntax:
xxx variable-name[(subscripts )],variable-name[(subscripts)]...

DEF

Comments:
The DEFxxx statement declares variables for
use in a CPL program. Note that variable
names are case sensitive, which means that
the variable temp is not the same as Temp.
Reserved words such as DEFINT are not case
sensitive and are recognized whatever the
mixture of capitals and lower case
characters. Arrays cannot be initialized and
begin with 1. There is no array[0]. Available
DEFxxx statements are:
DEFINT

Integer

DEFLNG

Long Integer

DEFFLT

Single Floating Point

DEFDBL

Double Floating Point

DEFOBJ

Object Pointer

Example:
temperature, average, outside_temp // simple variables
price = 10.23, percent = 100.00 // defines with initializations
DEFINT rooms[20], halls[10] // array declarations (arrays cant be initialized but can
// be assigned later).
DEFINT cnt, I = 0, seconds[60] // a mixture
DEFINT

DEFFLT

DEFOBJ

obj1 = {Meeting Room},

obj2 = {Hall1} // Obj variables free formatted on several lines
It is also possible to use initialized integer variables in array declarations. For instance:
= 100
temp1[LIMIT], temp2[LIMIT] // 2 float array with 100 elements each

DEFINT LIMIT
DEFFLT

Initialized variables can also be used to initialized other variables.

obj_var = {Building}
obj_var_2 = obj_var
Deflt temp1 = 72.32
defflt temp2 = temp1 // the result would be that this variable is initialized with 72.3
DEFOBJ
DEFOBJ

3-10

Tracer Summit Custom Programming

CPL Syntax
DO... Statement
Syntax:
DO

{WHILE | UNTIL} condition

...statement_block...
[EXIT DO]
...statement_block...

LOOP

Comments:
Condition is any expression the CPL
interpreter can determine to be true (non
zero) or false (0). CPL repeats the program
lines contained in the statement block(s) as
long as a WHILE condition is true or an
UNTIL condition is false.
When an EXIT DO statement is executed,
control is transferred to the statement that
follows the LOOP statement. When used
within a nested loop, an EXIT DO statement
moves control out of the immediately
enclosing loop.
Example:
Do while 1
// an endless loop
call Check_air_flow
call Check_temperature
wait 0:30:0
// Wait 30 minutes
Loop
Do While ( {Inside}.{Air Temperature}<Comfort_level )
call Increase_heat
Loop
Do while 1
// endless loop
wait 1:0:0
/// Beep the guard every hour to keep him awake
call beep_the_guard
if ( {Building}.{On Fire} )
exit DO
end if
Loop

Tracer Summit Custom Programming

3-11

CPL Syntax
ERR Variable

Syntax:
ERR

Comments:
ERR is a predefined variable that holds the
run-time error code for the last error that was
trapped by the interpreter. This predefined
variable is case sensitive. Using the
RESUME and WHEN ERROR statements
resets the ERR value to 0. To retain the value
of the error code stored in ERR, it should be
assigned to a variable. The value of ERR can
be set directly through an assignment
statement, and indirectly through the ERROR
statement.
A run-time error occurs at times when a
database access fails. An example is when a
CPL program is written referencing an object
in a BCU that is NOT AVAILABLE.
Example:
Error_handler: // label for error WHEN ERROR statement
if ( error_cnt = max_errors) // make sure we dont exceed the bounds of the array
stop
errors[ error_cnt ] = ERR // save the error code for later examination
error_cnt = error_cnt + 1 // increase the error count
ERR

= 0 // reset the error variable

RESUME AFTER

3-12

// return to the statement where the error occurred

Tracer Summit Custom Programming

CPL Syntax
ERROR Statement

Syntax:
ERROR

errorcode

Comments:
ERROR errorcode simulates the occurrence
of a CPL or user-defined error. The
errorcode argument, which represents the
error code, must be an integer between 1 and
32,767. If an errorcode is one that CPL
already uses, the ERROR statement simulates
an occurrence of that error.
User-defined error codes should employ
values greater than those used for standard
CPL error codes. To ensure that non-CPL
error codes are chosen, user-defined codes
should work down from 32,767.
If an ERROR statement is executed, and
there is no error-handling routine enabled,
CPL ignores this statement and continues
running.

Tracer Summit Custom Programming

3-13

CPL Syntax
EXIT Statement

Comments:
EXIT statements are used with DO, FOR
functions, and REPEAT substatements and
routines. For more information on the use of
EXIT statements, refer to these CPL
statement descriptions for examples.

3-14

Tracer Summit Custom Programming

CPL Syntax
FOR...NEXT Statement

Syntax:
FOR

counter = start TO end [ STEP increment]

...statement_block...
[ EXIT FOR ]
...statement_block...

NEXT

Comments:
The FOR...NEXT statement repeats the
statement block a fixed number of times,
determined by the values of start, end and
step. (see the table below).

Example:
DEFINT

a[10], b[10], i

/// initialize array elements to 0

FOR i =1 to 10
a[i] = 0
NEXT

Argument
counter

Description

Variable used as the

loop counter

start

Beginning value of the

counter

end

Ending value of the

counter

increment

The amount by which

the counter is changed
each time the loop is
run through. (The
default is one.)

/// initialize every other array elements to 0

FOR i =1 to 10 step 2
b[i] = 0
if ({building}.{present value} < 10) then
EXIT FOR
end if
NEXT

// EXIT FOR comes here

..statement_block... CPL functions,

statements, or methods
to be executed

F Note: CPL cannot jump into a loop.

Tracer Summit Custom Programming

3-15

CPL Syntax
FOR NEXT OBJECT Statement

Syntax:
FOR

object_pointer...statement_block... NEXT OBJECT

Comments:
The NEXT OBJECT statement steps the
object_pointer variable to the next
occurrence of the object of the type the
object_pointer is referencing. This affects all
objects of this type in a given BCU.
Example:
Defobj chiller_obj = {Chiller 1}
chiller_obj
chiller_obj.{Diagnostic Exists} = 0
chiller_obj.{Summit Free Cooling Request} = 0

FOR

NEXT OBJECT

3-16

Tracer Summit Custom Programming

CPL Syntax
FUNCTION...END FUNCTION Statement

Syntax:
name type_character [(argument-list)]
name = expression

FUNCTION

END FUNCTION

Comments:
The FUNCTION...END FUNCTION structure
defines a function procedure. The purpose of
a function is to produce and return a single
value of a specified type. Recursion is
supported.
The parameters are specified as a
comma-separated list of parameter names.
Currently, the parameter names must end
with a type character (%, &, !, #, or @). If
no parameters are defined, the parenthesis
should not be used.
CPL procedures use both the
call-by-reference and call-by-value
conventions.

In the FUNCTION statement, the name of the

function must end with a type character,
which specifies the type that the function
returns. When calling the function, the type
character is not required. The value is
returned to the caller by assigning a value to
the function name.
Functions can only be globally defined, and
they cannot be declared inside subroutines,
other functions or the main program body.

Tracer Summit Custom Programming

3-17

CPL Syntax

Example:
// This function returns the average of three temperatures supplied by the caller
Function Average_Temperature! (temp1!, temp2!, temp3!)
Average_Temperature = (temp1+temp2+temp3) / 3
End Function
Program Boca_Raton Hall_Temperature
defint hall_temperature
hall_temperature = Average_Temperature ({Hall 1}.{Present Value}, {Hall 2}.{Present Value},
{Hall 3}.{Present Value})
end

3-18

Tracer Summit Custom Programming

CPL Syntax
GOTO Statement
Syntax:
GOTO

{line label}

Comments:
GOTO sends control to a label. CPL does not
use line numbers. A label has the same
format as any other CPL name and it is
followed by a colon(:).
GOTOs cannot be used to transfer control out

of the current function or subprogram.

The interpreter does not support jumps
inside statements (like FOR NEXT...), so
labels can only be placed between
statements.
Example:
DEFINT Temps[10]
Program Frog
DEFINT

Init_temps( Temps[] )
For i = 1 to 10
if (Temps[I] = 100) then
goto jump_here
end if
end for
jump_here:

call cool_it

end // frog

Tracer Summit Custom Programming

3-19

CPL Syntax
IF...THEN...ELSE...END IF Statement

Syntax A:
IF

condition THEN then_statement [ELSE else_statement] END IF

Syntax B:
condition THEN
...statement_block...
[ELSEIF expression THEN
...statement_block...]
[ELSE
...statement_block...]
IF

END IF

Comments:
The IF...THEN...ELSE...END IF structure
organizes alternative actions into separate
blocks of code. The resulting action depends
on the logical value of one or more
conditions expressed in the structure.
The condition can be any expression that is
evaluated as true (non-zero) or false (zero).
Example:
if ((outside < 80) and (inside < 60))
then
call warm_it(inside, outside)
inside = new_temperature
end if
if (inside_temp < 90)
then
call under_ninety
elseif (inside_temp < 100)
then
call under_100
else
call over_100
end if

3-20

Tracer Summit Custom Programming

CPL Syntax

Local - Predefined variable

Syntax:
Local

Comments:
Local is a predefined object variable that
provides the ability to reference the program
currently being written. It resolves a
chicken and egg situation when you want
to change the saved value array of the
program being written. Since the object has
not been created, any references to itself
would be unresolved at compile time and
generate an error.

F Note: This predefined variable is case

sensitive.
Example:
Local.{Saved Value} [1] = 120 // Setting saved variable 1 equal to 120

Tracer Summit Custom Programming

3-21

CPL Syntax

Program END Statement

Syntax:
PROGRAM

Program_name

END

Comments:
One main program body has to appear in a
CPL program. Local variables may be
defined and used in its scope. The first
statement in the main program body is the
first statement executed when the program is
started. The program_name is the default
CPL program description when the program
object is created, but this description can be
changed in the CPL Editor. The program
name cannot have any spaces and can be up
to 32 characters long.
Example:
PROGRAM

Sample

(Program Statements)
END

F Note: If special startup sequences are

required after a power failure, naming a
CPL program object STARTUP_1,
STARTUP_2, etc. causes the
program(s) to execute before all other
applications execute after the power is
restored on the BCU. See the example
program in Appendix A of this
volume.

3-22

Tracer Summit Custom Programming

CPL Syntax
REPEAT...Statement

Syntax:
REPEAT

...statement_block...
[EXIT REPEAT]
...statement_block...
LOOP {WHILE | UNTIL} condition

Comments:
Condition is any expression that CPL can
determine to be true (non zero) of false (0).
CPL repeats the program lines contained in
the statement block(s) as long as a WHILE
condition is true or an UNTIL condition is
false. At least one iteration of the loop
happens.
When an EXIT REPEAT statement is
executed, control is transferred to the
statement that follows the LOOP statement.
When used within a nested loop, an EXIT
REPEAT statement moves control out of the
immediately enclosing loop.
Example:
Cnt = 0
REPEAT

Cnt = Cnt + 1
(Cnt = 10)

LOOP UNTIL

Tracer Summit Custom Programming

3-23

CPL Syntax
RESUME Statement

Syntax:
RESUME [AFTER]

Comments:
The RESUME statement halts error-handling
code and returns back to the exact statement
that caused the error. When the RESUME
AFTER statement is used, control is passed
to the statement that immediately follows the
statement where the error occurred.
Example:
See WHEN ERROR or ERR

3-24

Tracer Summit Custom Programming

CPL Syntax
SELECT CASE Statement

Syntax:
test expression
[CASE expression list
...statement_block...]
[CASE expression list
...statement_block... ]

SELECT CASE

.
.
[CASE ELSE
...statement_block... ]
END SELECT

Comments:
The SELECT CASE statement executes one
of a series of statement blocks, depending on
the value of an expression.
The test expression can be any expression.
Each ...statement_block... can contain any
number of statements on any number of
lines.
The expression list(s) may be a
comma-separated list of expressions of the
following forms:
expression
expression TO expression
IS comparison_operator expression

Each expression type must be compatible

with the type of test expression.
The compiler executes the first match
between test expression and the CASE
expressions. The statement block following
the CASE clause is executed. When the next
CASE clause is reached, execution control
passes to the statement that follows the END
SELECT statement.

Tracer Summit Custom Programming

3-25

CPL Syntax

When the TO keyword is used to specify a

range of values, the smaller value must
appear first. The comparison_operator used
with the IS keyword is one of: <, >, <=, , >=,
<>.
The optional CASE ELSE alternative is the
default processing if there are no matches in
the case alternate lists.
Example:
SELECT CASE

{Object Ref}.{Present Value}

1, 3, 5
Stop
CASE 2, 4, 6
Even = True
Go to Continue
CASE 7 TO 10, 17 TO 20 // short for 7, 8, 9, 10, 17, 18, 19, 20
call middle
call high_middle
CASE IS > 20 // all values greater than 20
call upper
CASE IS < 10 // all remaining values below 10
call lower
CASE index, Error_cnt - 1 // using variables and expressions
call variable
CASE ELSE // all leftovers
call leftovers
CASE

END SELECT
STOP

3-26

Tracer Summit Custom Programming

CPL Syntax
STOP Statement

Syntax:
STOP

Comments:
The STOP function halts program execution.
STOP statements can be used in any
statement block to terminate execution.
Example:
If (Outside Air Temperature > 50) Then
Cooling = On
Else
Stop
End If

Tracer Summit Custom Programming

3-27

CPL Syntax
SUB...END Statement

Syntax:
SUB

name [(parameters)]

EXIT SUB
END SUB

Comments:
The SUB...END SUB structure defines a
subroutine procedure. A call to a subroutine
stands alone as a separate statement. (See the
CALL statement.) Recursion is supported.
Parameters are specified as a commaseparated list of parameter names. Currently,
the parameter names must end with a type
character (@, %, &, !, or #). If no
parameters are defined, do not use
parenthesis.
The subroutine returns to the caller when the
END SUB statement is reached or when an
EXIT SUB statement is executed.
Subroutines have to be defined outside of
the main program body, functions, and other
subroutines. Subroutines can be referenced
before they are declared. The following
example does not cause a problem.
Example:
Program example // The programs main body can go anywhere in the program
call sub1 // defined below but not a problem
End
Sub sub1
defint b[10] // ten integers all aligned in an array
call sub2( b[ ] ) // The array will be changed by sub2
End Sub1
Sub sub2( array_var%[ ] )
array_var[1] = 10
End sub

3-28

Tracer Summit Custom Programming

CPL Syntax

Task Switch
Syntax:
Task Switch

Comments:
The Task Switch statement causes the
program to relinquish execution and allows
other active CPL programs an opportunity to
run.
Normally, CPL programs relinquish
execution by completing or waiting on some
condition. The Task Switch is useful for CPL
programs that have extremely long and/or
continuous (loop) runtimes.
Example:
For i = 1 to 100
VAV[i] = i + 2
If (i = 50) then
Task Switch
End If
Next

// Halfway through loop Task Switch

Tracer Summit Custom Programming

3-29

CPL Syntax
WAIT Statement

Syntax A:
WAIT

Wait_time

Syntax B:
WAIT

Wait_time OR { WHILE | UNTIL } condition

Syntax C:
WAIT

{ WHILE | UNTIL } condition

Comments:
The WAIT statement causes a pause at the
current point in the execution of this CPL
program. The wait can be time-based,
conditional, or a combination. Once the
WAIT is satisfied, control transfers to the
statement following the WAIT statement.
Time-based waits specify the number of
hours, minutes, and seconds to wait in the
following format:
For example: 0:1:0 // one minute
Conditional waits using the WHILE keyword
generate a pause in the execution as long as
the condition is true (zero), and continues
once the condition becomes false (non-zero).
Conditional waits using the UNTIL keyword
generate a pause in the execution as long as
the condition is false (non-zero), and
continue once the condition becomes true
(zero).
Example:
WAIT 24:0:0 // waits a day
// Wait 2 hours, 2 minutes, and 2 seconds or if the temperature level goes too low
WAIT 2:2:2 OR UNTIL ({Obj Ref}.{Present Value} < Comfort_level)

3-30

Tracer Summit Custom Programming

CPL Syntax
WHEN ERROR Statement

Syntax:
WHEN ERROR GOTO

label

Comments:
The WHEN ERROR statement enables an
error-handling alternative other than the
interpreter, specifying the location of the
CPL code within the procedure. Unless a
WHEN ERROR statement is used, any
run-time error is fatal (such as CPL
terminates the execution of the program).
The GOTO label enables the error-handling
routine that starts at label. The designated
label has to be in the same procedure as the
WHEN ERROR statement.
A runtime error occurs at times when
database access fails. Once an error-handling
routine is enabled, a run-time error results in
program control switching to the
error-handling label and activating the
error-handler. The error-handler remains
active from the time the run-time error is
trapped until a RESUME statement is
executed in the error-handler.
Example:
DEFINT

error_cnt = 0

sub set_limits (obj_array@[], how_many%, limit%)

// This routine initializes the property {Maximum} for all the objects in obj_array
// If an error occurs trying to set the property, the subroutine branches to the
// error label, increments the error count, and returns to the statement after the
// statement where the error occurred.
defint i
(Continued next page...)

Tracer Summit Custom Programming

3-31

CPL Syntax
WHEN ERROR

goto error_handler // Enable error handler for this routine only

for i = 1 to how_many
obj_array[i].{Maximum} = limit // on error code below just in case...
next
EXIT SUB

error_handler:
error_cnt = error_cnt + 1
RESUME AFTER

end sub

3-32

Tracer Summit Custom Programming

CPL Syntax
WHILE...WHILE END Statement

Syntax:
condition
...statement_block...

WHILE

WHILE END

Comments:
The WHILE...WHILE END structure control a
repetitive action. As long as the condition
remains true (non-zero), the statements in the
statement_block are executed. Once the
condition becomes false (non-zero) control is
transferred to the statement following the
WHILE END.
Example:
While {Object Ref}.{Present Value} < minimum
call adjust
While end

Tracer Summit Custom Programming

3-33

CPL Syntax

CPL Functions
CPL functions are built-in subroutines that
return a single value to the CPL program.
The following section defines and illustrates
some uses for CPL functions. The following
predefined functions may appear as a simple
expression or in a complex expression.
ABS Function __________________________________

Syntax:
(numeric-expression)

ABS

Comments:
The ABS function returns the positive value
of the specified numeric-expression.
Example:
Temperature = Abs (Inside - 10)

//If inside = 8, Temperature = 2

AVG Function __________________________________

Syntax:
(expression [, expression]...)

AVG

Comments:
AVG accepts a variable parameter list and
returns the average of the variables values.
Example:
DEFFLT VAVAVG
VAVAVG = AVG

(Temp_1, Temp_2, Temp_3)

F Note: The AVG function can accept up to

63 parameters.

3-34

Tracer Summit Custom Programming

CPL Syntax
CLNG Function
Syntax:
CLNG

(numeric-expression)

Comments:
Converts a numeric-expression to a long (4
byte) integer by rounding the fractional part
of the expression.
Example:
DEFINT

i=10

DEFLNG l
l = clng( i ) // converts the integer (i) to a long
DATE Function _________________________________

F Note: The BCU stores the date in a

32-bit integer defining the number of

seconds from the BCU base date.
Syntax:
(Year-expression, month-expression, day-expression)

DATE

Comments:
Returns a 32-bit long value that is the date
for the passed in parameters. Parameters
are: four-digit year, month 1-12, day 1-31
Example:
DEFLNG date_of_Christmas
date_of_Christmas = date(1993, 12, 25)

Tracer Summit Custom Programming

3-35

CPL Syntax
DATENOW Function

F Note: The BCU stores the date in a

32-bit integer defining the number of
seconds from the BCU base date.

Syntax:
DATENOW

Comments:
Returns a 32-bit long value that is the
current date. No parameters.
Example:
date_of_Christmas, today
date_of_Christmas = date(1993, 12, 25)
today = datenow
if (today = date_of_Christmas) then
...
end if
if (datenow = date_of_Christmas) then
end if

DEFLNG

DATEVALUE Function___________________________

F Note: The BCU stores the date in a

32-bit integer defining the number of
seconds from the BCU base date.
Syntax:
(String-Constant)

DATEVALUE

Comments:
Returns a 32-bit long value that is the date
for the passed in string. The string format
is mm-dd-yyyy
Example:
DEFLNG

date_of_Christmas

date_of_Christmas = datevalue( 12-25-1999")

3-36

Tracer Summit Custom Programming

CPL Syntax
DAY Function
Syntax:
(expression)

DAY

Comments:
Returns 1-31 from a time-date long value.
Example:
DEFLNG

the_day

the_day = day(datenow) //Set variable the_day = current calendar day

FIX Function ___________________________________
Syntax:
FIX

(numeric-expression)

Comments:
FIX returns the integer part of a
numeric-expression. The argument given is
any numeric-expression. For both positive
and negative numeric-expressions, FIX
removes the fractional part of the expression
and returns the integer part only. For
example: FIX (1.5) returns 1, FIX (-1.5)
returns -1.
Example:
DEFINT

a, b

DEFFLT

b, f=10.5

a = -10
b = abs( a ) + fix( f ) // b would have the value of 20.0

Tracer Summit Custom Programming

3-37

CPL Syntax
HOUR Function

Syntax:
HOUR

(expression)

Comments:
Returns 0-23 from a time-date long value.
Example:
hour_is
hour_is = hour(timenow)

DEFINT

INT Function __________________________________

Syntax:
INT (numeric-expression)

Comments:
INT returns the largest integer less than or
equal to the numeric-expression. The INT
function returns the integer part of any
numeric-expression. For positive
numeric-expressions, INT removes the
fractional part of the expression and returns
the integer part only. For negative
numeric-expressions, INT returns the largest
integer less than or equal to the expression.
For example, INT (1.5) returns 1, and INT
(-1.5) returns -2.

3-38

Tracer Summit Custom Programming

CPL Syntax
LOG Function
Syntax:
LOG

(numeric-expression)

Comments:
LOG returns the natural logarithm of the
numeric-expression.
Example:
Defflt

OATEMP

= {outside air temperature}.{Present Value}

Local.{Saved Value} [1] = LOG (273.16/((OATEMP - 32.0)/1.8 + 273.16))

OATEMP

MAX Function __________________________________

Syntax:
MAX

(expression [, expression]...)

Comments:
MAX accepts a variable parameter list and
returns the largest value in it.
Example:
DEFFLT VAVMAX
VAVMAX = MAX

(Temp_1, Temp_2, Temp_3)

F Note: The MAX function can accept up

to 63 parameters.

Tracer Summit Custom Programming

3-39

CPL Syntax
MIN Function

Syntax:
MIN (expression [, expression]...)

Comments:
MIN accepts a variable parameter list and
returns the minimum value from it.
Example:
DEFFLT VAVMIN
VAVMIN = MIN

(Temp_1, Temp_2, Temp_3)

F Note: The MIN function can accept up to

63 parameters.

MINUTE Function ______________________________

Syntax:
(expression)

MINUTE

Comments:
Returns 0-59 from a long value (typically
the return from the TIMENOW function).
Example:
minute_is
minute_is = minute(timenow)

DEFINT

3-40

Tracer Summit Custom Programming

CPL Syntax
MONTH Function

Syntax:
MONTH

(expression)

Comments:
Returns 1-12 from a long value (typically
the return from the DATENOW function).
Example:
month_is
month_is = month(datenow)

DEFINT

NOW Function _________________________________

F Note: The BCU stores the date in a

32-bit integer defining the number of

seconds from the BCU base date.
Syntax:
NOW

Comments:
Returns a 32-bit long value that is the
current date and time. No parameters.
Example:
DEFLNG

date_of_Christmas, todays_date, todays_date_and_time

todays_date_and_time = now

Tracer Summit Custom Programming

3-41

CPL Syntax
SECOND Function

Syntax:
Second (expression )

Comments:
Returns 0-59 from a long value (typically
the return from the TIMENOW function).
Example:
second_is
second_is = second(timenow)

DEFINT

SGN Function __________________________________

Syntax:
SGN

(numeric-expression)

Comments:
SGN returns a value indicating the
numeric-expression sign. The value is:
+1 if numeric-expression
0 if numeric-expression
-1 if numeric-expression

> 0.
= 0.
< 0.

SQR Function __________________________________

Syntax:
SQR

(numeric-expression)

Comments:
SQR returns the square root of the
numeric-expression.
Example:
Velocity
Velocity = Flow_Coef x SQR(Pressure - 4)

DEFINT

3-42

Tracer Summit Custom Programming

CPL Syntax
TIME Function

Syntax:
TIME

(Hour-expression, Minute-expression, second-expression)

Comments:
Returns a 32-bit long value that is the time
for the passed in parameters. Parameters
are: hour, minute, second. The TIME
function returns the number of seconds that
have elapsed since midnight.
Example:
DEFLNG

noon

noon = time(12, 0, 0)
TIMENOW Function _____________________________

Syntax:
TIMENOW

Comments:
Returns a 32-bit long value that is the
current time. No parameters. The TIMENOW
function returns the number of seconds that
have elapsed since midnight.
Example:
DEFLNG noon
noon = time(12, 0 , 0)
if (noon > timenow) then
...
end if

Tracer Summit Custom Programming

3-43

CPL Syntax
TIMER Function

Syntax:
TIMER

Comments:
The TIMER function returns the number of
seconds that have elapsed since midnight.
Example:
DEFLNG A
A = TIMER

TIMEVALUE Function ___________________________

Syntax:
(String-Constant)

TIMEVALUE

Comments:
Returns a 32-bit long value that is the time
for the passed in string. The string format
is hh:mm:ss.
Example:
noon
noon = timevalue(12:00:00")

DEFLNG

3-44

Tracer Summit Custom Programming

CPL Syntax
WEEKDAY Function

Syntax:
WEEKDAY

(expression)

Comments:
Returns a 32-bit long value that is the date
for the passed in parameters. Parameters
are: Sunday = 1.
Example:
DEFINT

current_day = Weekday(now)

YEAR Function _________________________________

Syntax:
(expression)

YEAR

Comments:
Returns a four-digit year value from a
time-date long value.
Example:
year_is
year_is = year(datenow)

DEFINT

Tracer Summit Custom Programming

3-45

CPL Syntax

3-46

Tracer Summit Custom Programming

Appendix A
Example CPL Programs
The following programs present previously created CPL programs that may be modified to
suit your needs when setting up the Tracer Summit system.
Resetting an Air Handler
Program AHU_Reset
//
// Written: March 18, 1997 by R. Trane
//
// Properties Modified:
//
{AHU 1 Setpoint}.{Present Value}
//
// Properties Read:
//
{Zone X Temperature}.{Present Value} (X = 1 - 4)
//
{AHU 1 Setpoint}.{Present Value}
//
/// Entrant: This program should have an execution frequency of once a minute.
//
/// This program determines the setpoint for Air Handler based
/// on the maximum temperature of the areas it serves.

//
/// This program uses the text file AHURESET.CPL
Defflt
MaxTemp,
TempSetpt,
ActualSetpt
// Determine the maximum temperature of the four zones.
MaxTemp = Max({Zone 1 Temperature}.{Present Value},
{Zone 2 Temperature}.{Present Value},
{Zone 3 Temperature}.{Present Value},
{Zone 4 Temperature}.{Present Value})
(Continued on next page...)

Tracer Summit Custom Programming

A-1

Appendix A

Example CPL Programs

// If the maximum zone temperature is greater than 75 F,

// decrease the AHU setpoint by 0.5 F. Set a minimum setpoint
// of 55 F.
If (MaxTemp > 75) Then
TempSetpt = {AHU 1 Setpoint}.{Present Value} - 0.5
ActualSetpt = Max (TempSetpt, 55)
End If
// If the maximum zone temperature is less than 74 F, increase
// the AHU setpoint by 0.5 F. Set a maximum setpoint of 63 F.
If (MaxTemp < 74) Then
TempSetpt = {AHU 1 Setpoint}.{Present Value} + 0.5
ActualSetpt = Min (TempSetpt, 63)
End If
// Send the Air Handler the new setpoint.
Control({AHU 1 Setpoint}, {Present Value}, ActualSetpt, 5, Set)
End

A-2

Tracer Summit Custom Programming

Example CPL Programs

Appendix A

Calculating Chiller Demand

Program Calc_Demand
//
// Written: April 1, 1997 by R. Trane
//
// Properties Modified:
//
Local.{Saved Value}[x], x = 1 - 16
//
// Properties Read:
//
Local.{Saved Value}[x], x = 1 - 16
//
{Main Voltage Phase x}.{Present Value}, x = A, B, C
//
{Switch Station - 02 - 007}.{Analog In}[01]
//
{Switch Station - 02 - 004}.{Analog In}[0x], x = 1, 2, 3
//
/// Entrant: This Program should have an execution frequency of one minute.
//
/// This program calculates the instantaneous and last 15 minute
/// average demand. The formula used for instantaneous demand
/// is; (Va * Ia + Vb * Ib + Vc * Ic) * PF / 100
//
/// This program uses the text file CALCDMND.CPL.
//
// Local.{Saved Value}[1] = Instantaneous Demand (KW)
// Local.{Saved Value}[16] = 15 Minute Average Demand (KW)
Defint
i,
// Array index
Amps[3],// Array of current draw values
Volts[3] // Array of voltage values
Defflt
Phase[3],
// Array of V*A values for each phase.
Watts, // Sum of V*A values * power factor.
Power, // Intermediate variable.
Powersum,
// Sum of instantaneous values for last 15
mins.
PowFac // Power factor.
Volts[1] = {Main Voltage Phase A}.{Present Value}
Volts[2] = {Main Voltage Phase B}.{Present Value}
Volts[3] = {Main Voltage Phase C}.{Present Value}
Amps[1] = {Switch Station - 02 - 004}.{Analog In}[01]
Amps[2] = {Switch Station - 02 - 004}.{Analog In}[02]
Amps[3] = {Switch Station - 02 - 004}.{Analog In}[03]
PowFac = {Switch Station - 02 - 007}.{Analog In}[01]
(Continued on next page...)

Tracer Summit Custom Programming

A-3

Appendix A

Example CPL Programs

For i = 15 to 2 Step -1
Local.{Saved Value}[i] = Local.{Saved Value}[i-1]
Next
For i = 1 to 3 Step 1
Phase[i] = Volts[i] * Amps[i]
Power = Power + Phase[i]
Next
Watts = Power * PowFac / 100
Local.{Saved Value}[1] = Watts / 1000
For i = 1 to 15 step 1
Powersum = Powersum + Local.{Saved Value}[i]
Next
Local.{Saved Value}[16] = Powersum / 15
End

A-4

Tracer Summit Custom Programming

Example CPL Programs

Appendix A

Chiller Rotation
Program Chiller_Rotation
//
// Written 3/1/97 by Carl Summit
//
// Properties Read:
//
{Chiller #1 Sequence Number}.{Present Value}
//
// Properties Modified:
//
{Chiller #1 Sequence Number}.{Present Value}
//
/// This program will change the Chiller Sequence numbers if
/// the current day and time in the BCU are equal to the selected
/// Rotation day and time.
//
/// This program is executed every hour.
//
/// This CPL object uses the text file named CHLR_ROT.CPL
Defint
Chlrs = 3,
RotDay = 4,
RotHour = 9,
CurDay, // Current Day
CurHour,
TempSeq

// Number of Chillers
// Rotation Day
// Rotation Hour
// Current Hour
// Temporary Sequence Number

// Set Temporary Sequence equal to current sequence

TempSeq = {Chiller #1 Sequence Number}.{Present Value}
CurDay = WEEKDAY(NOW)
CurHour = HOUR(NOW)

// Determine current day in BCU (1 = Sunday)

// Determine current hour in BCU

// If rotation day and time are correct, rotate the chillers. (Wed, 9:00 A.M.)
If ((CurDay = RotDay) And (CurHour = RotHour))
Then
TempSeq = TempSeq + 1
If TempSeq > Chlrs Then
TempSeq = 1
End If
End If
// Make sure Temporary Sequence is a valid number
TempSeq = Min(TempSeq, Chlrs)
TempSeq = Max(TempSeq, 1)
// Set current sequence equal to Temporary Sequence
Control({Chiller #1 Sequence Number}, {Present Value}, TempSeq, 5, Set)
End

Tracer Summit Custom Programming

A-5

Appendix A

Example CPL Programs

Calculating Dewpoint
Program Dewpoint
//
// Written: March 1, 1997 by R. Trane
//
// Modifications:
//
3/8/97 DJU;
//
Divide humidity by 100 to attain percent. Testing
//
indicates correct value.
//
// Properties modified:
//
{Dewpoint}.{Present Value}
//
// Properties read:
//
{Outdoor Air Temperature).{Present Value}
//
{Humidity}.{Present Value}
//
/// Entrant: This program should have an execution frequency of once a minute.
//
/// This program determines the dewpoint based on dry bulb temperature and Humidity.
/// The result is stored in the present value of the dewpoint object. It also triggers the
/// execution of the Enthalpy CPL routine.
//
/// This CPL object uses the text file named DEWPOINT.CPL.
Defflt
Humidity,
Dry_Bulb,
Dewpnt // Dewpoint value.

// Outdoor Air Humidity variable.

// Outdoor Air Temperature variable.

Humidity = {Outdoor Air Humidity}.{Present Value}

Dry_Bulb = {Outdoor Air Temperature}.{Present Value}
Dewpnt = Dry_Bulb - 0.16 * (1 - Humidity/100) * (Dry_Bulb + 175) / (0.54 + Humidity/100)
Control({Dewpoint}, {Present Value}, Dewpnt, 5, Set)
{Enthalpy}.{Run Program Flag} = 1
// Execute Enthalpy CPL Program
End
// Dewpoint Program.

A-6

Tracer Summit Custom Programming

Example CPL Programs

Appendix A

Calculating Enthalpy
Program Enthalpy
//
// Written: March 1, 1997 by R. Trane
// Testing indicates correct value.
//
// Properties modified:
//
{Enthalpy}.{Present Value}
//
// Properties read:
//
{Outdoor Air Temperature}.{Present Value}
//
{Outdoor Air Humidity}.{Present Value}
//
/// Entrant: This program is run from the Dewpoint CPL routine.
//
/// This program determines enthalpy based on Dry Bulb temperature and Humidity.
/// The result is stored in the present value of the enthalpy object.
//
/// This program uses the text file named ENTHALPY.CPL
Defflt
Dry_Bulb,
Humidity,
Enthlpy // Enthalpy value.

// Outdoor Air Temperature.

// Outdoor Air Relative Humidity.

Dry_Bulb = {Outdoor Air Temperature}.{Present Value}

Humidity = {Outdoor Air Humidity}.{Present Value}
Enthlpy = 8 + 0.27 * (Dry_Bulb - 35) + 0.5 * ((Dry_Bulb - 35) * Humidity / 100)
Control ({Enthalpy}, {Present Value}, Enthlpy, 5, Set)
End
// Enthalpy Program.

Tracer Summit Custom Programming

A-7

Appendix A

Example CPL Programs

Calculating Series Chiller Setpoint

Program Series_Chiller_Setpoint
// Written: July 11, 1996 by Jerry Aldini
// Modified:
// Properties Read:
//
{Chiller 1}.{Present Value}
//
(Chiller 2}.{Present Value}
//
{Chilled Water Supply}.{Present Value}
//

{Chilled Water Return}.{Present Value}

//
{System Chilled Water Setpoint}.{Present Value}
//
// Properties Modified:
//
{Upstream Chiller Setpoint}.{Present Value}
//
// Routine Summary:
/// This routine calculates the setpoint for the upstream chiller in a series chiller pair.
//
/// Routine Execution: This program is executed every minute.
//
/// Routine Text File: This CPL object uses the text file named SER_STPT.CPL
//
//
***** Define and Initialize Variables *****
// In the first three sections of this routine, the programmer must define the variables used
// throughout this routine. Only variables in the User Edited Variables section should
// be changed.
Defobj
Upstream_Chlr,
Downstream_Chlr,
Setpoint

// upstream chiller object

// downstream chiller object
// seetpoint Analog output object

Sys_Sup,
Sys_Ret,
Sys_Delta,
Sys_Stpt,
Upstream_Stpt,

// System Chilled Water Supply Temp

// System Chilled Water Return Temp
// System Temp
// System Chilled Water Supply Setpoint
// Upstream Chiller Chilled Water Supply

Defflt

Setpoint
//******************** User edited variables ***********************
Min_Setpt = 40.0
// minimum Chiller chilled water setpoint

(Continued next page...)

A-8

Tracer Summit Custom Programming

Example CPL Programs

Appendix A

Defint
Upstream_Cap = 400,
Downstream_Cap = 400

// Capacity (Tons) of the upstream chiller

// Capacity (Tons) of the downstream chiller

//
***** Initialize Objects *****
// In this section chiller and setpoint objects are assigned. The object names must match the
// names in the database exactly. The programmer should use the Add Object
// selection found under the Edit menu in the CPL editor to complete this section.
Upstream_Chlr = {Chiller 1}
Downstream_Chlr = {Chiller 2}
Setpoint = {Upstream Chiller Setpoint}

// upstream chiller object

// downstream chiller object
// setpoint Analog output object

//
***** Initialize Variables *****
// In this section system temperatures are assigned or calculated. The object and property
// names must match the names in the database exactly. The programmer should use the Add
// Obj&Property selection found under the Edit menu in the CPL editor to complete this
// section.
Sys_Sup = {Chilled Water Supply}.{Present Value}
Sys_Ret = {Chilled Water Return}.{Present Value}
Sys_Stpt = {System Chilled Water Setpoint}.{Present Value}
//************* End of user edited variables *********************
//
***** Calculate and Validate Upstream Chiller Setpoint *****
// In this section the upstream chiller setpoint is calculated. If both chillers are not in the
// occupied mode the setpoint is set to the system setpoint. The setpoint calculation is done
// only when both chillers are occupied. In both instances the new setpoint is validated so it is
// never less than the minimum setpoint. No changes are required in this section.
Sys_Delta = Sys_Ret - Sys_Sup
If (Upstream_Chlr.{Present Value} <> 0) and (Downstream_Chlr.{Present Value} <> 0) Then
Upstream_Stpt=Sys_Stpt+(Sys_Delta*(Upstream_Cap/(Upstream_Cap+Downstream_Cap)))
Else
Upstream_Stpt = Sys_Stpt
End If
Upstream_Stpt = Max (Upstream_Stpt, Min_Setpt)
(Continued next page...)

Tracer Summit Custom Programming

A-9

Appendix A

Example CPL Programs

//
***** Upstream Chiller Chilled Water Setpoint *****
// In this section the Analog output point in the database is controlled to the value calculated in
// the section above. The control is // only done when a change occurs. No changes are
// required in this section.
If (Setpoint.{Present Value} <> Upstream_Stpt) Then
(Setpoint,{Present Value},Upstream_Stpt,16,SET)

CONTROL

End If
End

A-10

// end of routine

Tracer Summit Custom Programming

Example CPL Programs

Valve Position and Average one T emperature

Appendix A
st

Floor VAV

Program VAV_INFO
//
// Written: July 9, 1997 by R. Trane
//
// Properties Modified:
//
Local.{Saved Value}[1] = First floor Max Air Valve Position
//
Local.{Saved Value}[2] = First floor Max Zone Temperature
//
Local.{Saved Value}[3] = First floor Min Air Valve Position
//
Local.{Saved Value}[4] = First floor Min Zone Temperature
//
Local.{Saved Value}[5] = First floor Avg Zone Temperature
//
// Properties Read:
//
{Room 100}.{Air Valve Position}
//
{Room 100}.{Zone Temperature}
//
{Room 110}.{Air Valve Position}
//
{Room 110}.{Zone Temperature}
//
{Room 120}.{Air Valve Position}
//
{Room 120}.{Zone Temperature}
//
{Room 130}.{Air Valve Position}
//
{Room 130}.{Zone Temperature}
//
{Room 140}.{Air Valve Position}
//
{Room 140}.{Zone Temperature}
//
{Room 150}.{Air Valve Position}
//
{Room 150}.{Zone Temperature}
//
{Room 160}.{Air Valve Position}
//
{Room 160}.{Zone Temperature}
//
{Room 170}.{Air Valve Position}
//
{Room 170}.{Zone Temperature}
//
{Room 180}.{Air Valve Position}
//
{Room 180}.{Zone Temperature}
//
{Room 190}.{Air Valve Position}
//
{Room 190}.{Zone Temperature}
//
/// Entrant: This program should have an execution frequency
/// of once a minute.
//
/// This program determines the maximum and minimum air valve
/// positions as well as maximum, minimum and average zone
/// temperatures for the VAV boxes on the first floor.
//
/// This program uses the text file VAV_INFO.CPL

(Continued next page...)

Tracer Summit Custom Programming

A-11

Appendix A

Example CPL Programs

Defint
i,
// For loop index.
Boxes = 10
(Continued...)

// Number of boxes processed.

vavbox[Boxes]

// Array of VAV box objects.

Defobj

Defflt
TempSum,
// Sum of the temperatures for average
calculation.
Position, // Air valve position of the VAV box being processed.
Temp, // Zone temp of the VAV box being processed.
MaxPos, // Maximum air valve position (initialized to 0).
MaxTemp,
// Maximum zone temperature (initialized to 0).
MinPos = 100.0,
// Minimum air valve position (initialized to
100).
MinTemp = 100.0,
// Minimum zone temperature (initialized to
100).
AvgTemp
// Average zone temperature (initialized to 0).
// Load the vavbox array with the VAV objects.
vavbox[1] = {Room 100}
vavbox[2] = {Room 110}
vavbox[3] = {Room 120}
vavbox[4] = {Room 130}
vavbox[5] = {Room 140}
vavbox[6] = {Room 150}
vavbox[7] = {Room 160}
vavbox[8] = {Room 170}
vavbox[9] = {Room 180}
vavbox[10] = {Room 190}
For i = 1 to Boxes step 1
Position = vavbox[i].{Air Valve Position}
Temp = vavbox[i].{Zone Temperature}
TempSum = TempSum + Temp
// Check each box for having an Air Valve position greater than the previous
// maximum position. Update if necessary.

(Continued next page...)

A-12

Tracer Summit Custom Programming

Example CPL Programs

Appendix A

If (Position>MaxPos) Then
MaxPos = Position
End If
// Check each box for having a Zone Temperature greater than the previous
// maximum temperature. Update if necessary.
If (Temp > MaxTemp) Then
MaxTemp = Temp
End If
// Check each box for having an Air Valve position less than the previous
// minimum position. Update if necessary.
If (Position < MinPos) Then
MinPos = Position
End If
// Check each box for having a zone temperature less than the previous
// minimum temperature. Update if necessary.
If (Temp < MinTemp) Then
MinTemp = Temp
End If
Next
// Save the calculated values.
Local.{Saved Value}[1] = MaxPos
Local.{Saved Value}[2] = MaxTemp
Local.{Saved Value}[3] = MinPos
Local.{Saved Value}[4] = MinTemp
Local.{Saved Value}[5] = TempSum / Boxes
End

// Program VAV_INFO

Tracer Summit Custom Programming

A-13

Appendix A

Example CPL Programs

Startup Program First to Run After Power Failure

Program STARTUP_1
// Written: November 12, 1992 by R. Trane
// Modifications:
//
None
// Properties modified:
//
{Chiller 1}.{Present Value}
//
{Chiller 2}.{Present Value}
//
{Chiller 3}.{Present Value}
/// This program is automatically executed by the BCU when
/// power is restored after a power failure because it is named
/// STARTUP_1.
/// This program controls all the chillers to Unoccupied so the
/// Chiller Sequencing CPL program can stagger the starts
/// to prevent a power demand peak from occurring.
/// This CPL object uses the text file named START1.CPL
Defint
Unoccupied = 0

// Define enumerations

// Turn the chillers Unoccupied

Control ({Chiller 1}, {Present Value}, Unoccupied, 5, SET)
Control ({Chiller 2}, {Present Value}, Unoccupied, 5, SET)
Control ({Chiller 3}, {Present Value}, Unoccupied, 5, SET)
End

A-14

Tracer Summit Custom Programming

Example CPL Programs

Appendix A

Startup Program Binar y Output Object Initiali a tion on Startup

Program STARTUP_BOP_BCU1
// Written Jan. 19, 1995 by Duden
//
// Properties modified:
//
All Binary Output objects in BCU1
//
/// Entrant: This routine should have an execution frequency of 0. It runs only when
/// the BCU starts up (resets).
//
/// The purpose of this routine is to initialize the properties referenced by the Binary /// Output
Objects in BCU1. A similar routine should be implemented for analog
/// output objects and in EVERY BCU on the site.
//
/// CPL text file name: STARTUPB.CPL
Defobj
BOP

// Representative Binary Output object variable

//************************* Initialize the variables *******************************

// Step 1: Rename BCU1 BOP to the name of an actual binary output object in this
// BCU.
BOP = {BCU1 BOP}
//********************* Initialize the Binary Outputs *******************************
// All objects of the type assigned to the variable BOP (Binary Outputs if step 1 is
// heeded) will be initialized to their Relinquish Default value at priority 16 (CPL Low). // This
will cause the property they are referencing to be initialized also.
For BOP
Control(BOP, {Present Value}, BOP.{Relinquish Default}, 16, Set)
Next Object
End

Tracer Summit Custom Programming

A-15

Appendix A

A-16

Example CPL Programs

Tracer Summit Custom Programming

Appendix B
CPL Error Codes
Error
Error-30

Error-39

Possible Cause

Possible Solution

Requested unit is down.

The CPL object is trying to access a property in a

BCU that is currently not available.
An invalid index was provided The array of Local.{Saved Value} properties in each
for accessing an array element. CPL object has only 16 elements. Trying to access
element 17 or higher causes this error. For example,
the following compiles, but causes this error.
Num =21
For i = 1 to Num step 1
Local.{Saved Value}[i] = VAV[i].{Zone Temperature}
Next

Error-103

Error-250

Error-251

The CPL programs Get

Property table entry call failed.
The CPL program has a bad
symbol type.
The CPL program has a bad
expression stack.

The property referred to in the CPL routine could not

be found for that object.
Recompile and replace the CPL object. If the problem
persists, contact your local Trane sales
representative.
A bad expression exists in the routine. A common
error is to forget to add the property in a statement
that is intended for testing the property. For example,
If ({Area 1} = 2) Then
rather than
If ({Area 1}.{Present Value} = 2) Then
Another common error is to define an array of
objects, but enter a property as an array element.
Defobj
Chiller[2]
Chiller [1] = {CenTraVac Chiller 1}.{Present Value}
Chiller [2] = {RTHB Chiller 2}.{Present Value]
Note: The syntax check in Summit Version 4.5 and
higher does not allow the second common error to
occur.

Tracer Summit Custom Programming

B-1

Appendix B

Error

Possible Cause

Possible Solution

Error-252

CPL program has a bad

program stack.

(For Tracer Summit versions before 4.5.) Adjust the

Context Size property of the CPL routine. The default
context size is 400, but it appears as 0 in Objects and
Properties. Change the value from 0 to 500. If the
error still occurs, change the value to 1000. If the
routine then runs, change the value to 750, etc. Keep
adjusting the value to find the proper context size.

Error-253

CPL program has an invalid

symbol stack offset.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-254

Recompile and replace the CPL object. If the problem

program has a bad
execution queue or persists, contact your local Trane sales
representative.
the entry was not found.

CPL

BCX_ITRP

Error-255

The CPL program has an

invalid/unsupported token
operation.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-256

The CPL program has a

general problem with a
symbol.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-257

The CPL program has

overflowed its P stack or E
stack

(For Tracer Summit versions before 4.5.)Adjust the

Context Size property of the CPL routine. The default
context size is 400, but it appears as 0 in Objects and
Properties. Change the value from 0 to 500. If the
error still occurs, change the value to 1000. If the
routine then runs, change the value to 750. Keep
adjusting the value to find the proper context size.

Error-258

CPL program has an array

index that is out of bounds

An array index is too big or too small. You may have

defined the array to have three elements, and then
tried to perform an operation on array element four.
Remember that 0 is not a valid array index.

Error-259

The CPL program has a bad

assignment (usually unequal
types)

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-260

The CPL program has an

unknown token.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

B-2

Tracer Summit Custom Programming

Appendix B

Error

Possible Cause

Possible Solution

Error-261

The CPL program has a

BCX_ITRP that had a problem
looking up symbol (usually
invalid type).

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-262

The CPL program parameter

and argument types do not
match.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-263

The CPL program has

underflowed its expression
evaluation stack.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-264

The CPL program has

Recompile and replace the CPL object. If the problem
underflowed its program stack. persists, contact your local Trane sales
representative.

Error-265

The CPL program (or

BCX_ITRP) has problem with
nested If statements.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-266

The CPL program has

attempted to divide by zero.

Debug the routine to find where the divide by zero

error is occurring. Determine whether a variable is not
being initialized (variables are always 0 unless
initialized to another value). Question whether the
MIN/MAX operators or an IF-THEN statement can be
used to prevent the variable in the denominator from
going to 0.

Error-267

The CPL program has a bad

storage address for symbol.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-268

The CPL program is too small

to be correct.

Recompile and replace the CPL object. If the problem

persists,contact your local Trane sales representative.

Error-269

The CPL context is too small

to be correct.

Recompile and replace the CPL object. If the problem

persists, contact your local Trane sales
representative.

Error-307

An invalid property size was

given.

Debug the routine to find where the property size

error is occurring. A common error is controlling a
binary output to a value other than 0 or 1.

Tracer Summit Custom Programming

B-3

Appendix B

B-4

Tracer Summit Custom Programming

Index
A
ABS function, 3-34
Add
Function, 1-5
Object, 1-5
Object & Prop., 1-5
Statement, 1-5
Add Enum. Bool., 1-5 2-5
example program, 2-8
Assigning arrays, 2-10
example program, 2-11
Assigning enumerations, 2-5
Assigning objects and properties, 2-4
directly referencing objects, 2-4
indirectly referencing objects, 2-4
AVG function, 3-34

C
CALL statements, 3-8
Calling Sequence, 1-7
CASE ELSE statements, 3-26
Check box, 1-iv
Checking text file syntax, 2-17
Clear Break, 1-7
CLNG functions, 3-35
Comments, 3-4
Compile, 1-6
Compiling
CPL text files, 2-16
text files, 2-18
Control Statements
priority, 3-9
CONTROL statements, 3-9

Tracer Summit Custom Programming

CPL
Add Enum. Bool, 2-5
applications, 1-1
assigning arrays, 2-10
assigning enumerations, 2-5
assigning objects and properties, 2-4
checking text file syntax, 2-17
comments, 3-4
compiling CPL text files, 2-16
compiling text files, 2-18
creating a CPL objects, 2-19
creating text files, 2-1
editing text files, 2-1
error codes, B-1
example programs, 2-2 A-1
expressions, 3-6
features, 1-1
functions, 3-34
loading files into the editor, 2-16
menu location, 1-3
overview, 1-2
program words, 3-1
purpose, 1-1
replacing CPL objects, 2-21
required procedures, 1-2
saving CPL text files, 2-15
statements, 3-7
Terminology, 3-2
testing CPL programs, 2-22
using saved values, 2-13
CPL terms, 3-1
Create CPL Object function, 1-6
Creating CPL objects, 2-19
Creating CPL text files, 2-1

Index-1

Index

example program, 2-2

general steps, 2-1
Custom Programming Language
See CPL

D
Data types, 3-5
Floating Point variables, 3-5 3-10
Integer variables, 3-10
Object variables, 3-5 3-10
Data Types
Integer variables, 3-5
DATE functions, 3-35
DATENOW functions, 3-36
DATEVALUE functions, 3-36
DAY functions, 3-37
Debug Color, 1-7
Debug Program, 1-7
DEFxxx statements, 3-10
DO... statements, 3-11
Drop down list box, 1-iv

E
Editing CPL text files, 2-1
assigning arrays, 2-10
assigning enumerations, 2-5
assigning objects and properties, 2-4
checking text file syntax, 2-17
compiling CPL text files, 2-16
compiling text files, 2-18
creating CPL objects, 2-19
loading files into the editor, 2-16
replacing CPL objects, 2-21
saving CPL text files, 2-15
testing CPL programs, 2-22
using saved values, 2-13
Entry field, 1-iv
ERR variable, 3-12
Error codes, B-1

Index-2

ERROR statements, 3-13

Example CPL programs, A-1
Example programs, 2-2
EXIT statements, 3-14
Expressions, 3-6

F
FIX functions, 3-37
Floating Point variables, 3-5
Double, 3-5 3-10
Single, 3-5
Floating Point Variables
Single, 3-10
FOR NEXT OBJECT statements, 3-16
FOR...NEXT statements, 3-15
FUNCTION...END FUNCTION statements,
3-17
Functions, 3-34
ABS, 3-34
AVG, 3-34
CLNG, 3-35
DATE, 3-35
DATENOW, 3-36
DATEVALUE, 3-36
DAY, 3-37
FIX, 3-37
HOUR, 3-38
INT, 3-38
LOG, 3-39
MAX, 3-39
MIN, 3-40
MINUTE, 3-40
MONTH, 3-41
NOW, 3-41
SECOND, 3-42
SGN, 3-42
SQR , 3-42
TIME, 3-43
TIMENOW, 3-43
TIMER, 3-44

Tracer Summit Custom Programming

Index

TIMEVALUE, 3-44
WEEKDAY, 3-45
YEAR, 3-45

MONTH functions,

3-41

Next Breakpoint, 1-7

NOW functions, 3-41

General information, 1-1 - 1-8

GOTO statements, 3-19
Group, 1-iv

H
Home Halt Point,
HOUR functions,

1-7
3-38

I
IF...THEN...ELSE...END IF statements,
3-20
Inhibit DB Writes, 1-7
INT functions, 3-38
Integer variables, 3-5
Integer, 3-5 3-10
Long Integer, 3-5 3-10

L
List box, 1-iv
Loading files into the editor,
Local - Predefined variable,
LOG functions, 3-39
Long Integer, 3-5 3-10

Object variables, 3-5 3-10

Open CPL Object, 1-6
Other literature, 1-ii
Overview, 1-2

Priority
Control statements, 3-9
Program END statements, 3-22
Program words, 3-1
CPL terms, 3-1
reserved words, 3-1
scope, 3-3
user-defined words, 3-1
Push buttons, 1-iv

Q
2-16
3-21

M
MAX functions, 3-39
Maximize button, 1-iii
Menu description, 1-4 - 1-8
Menu location, 1-3
MIN functions, 3-40
Minimize button, 1-iii
MINUTE functions, 3-40

Tracer Summit Custom Programming

Query Lines,

1-8

R
Radio button, 1-iv
Repeat statements, 3-23
Replace CPL Object function, 1-6
Replacing CPL objects, 2-21
Required procedures, 1-2
Reserved words, 3-1
RESUME statements, 3-24
Run Program, 1-7

S
Index-3

Index

Saving CPL text files, 2-15

Scope, 3-3
Scroll bar, 1-iii - 1-iv
SECOND functions, 3-42
SELECT CASE statements, 3-25
Set Break, 1-7
SGN functions, 3-42
Slider bars, 1-iii
SQR functions, 3-42
Sta tements
FUNCTION...END FUNCTION, 3-17
Statements, 3-7
CALL, 3-8
CASE ELSE, 3-26
CONTROL, 3-9
DEFxxx, 3-10
DO..., 3-11
ERROR, 3-13
EXIT, 3-14
FOR NEXT OBJECT, 3-16
FOR...NEXT, 3-15
GOTO, 3-19
IF...THEN...ELSE...END IF, 3-20
Program END, 3-22
Repeat, 3-23
RESUME, 3-24
SELECT CASE, 3-25
STOP, 3-27
SUB...END, 3-28
WAIT, 3-30
WHEN ERROR, 3-31
WHILE...WHILE END, 3-33
Step, 1-7
STOP statements, 3-27
SUB...END statements, 3-28
Syntax Check, 1-6

Testing CPL programs, 2-22

TIME functions, 3-43
TIMENOW functions, 3-43
TIMER functions, 3-44
TIMEVALUE functions, 3-44
Title bar, 1-iii
Title bar icon, 1-iii

U
User-defined words, 3-1
Using saved values, 2-13
example program, 2-14

V
Variable
ERR, 3-12
Local - Predefined,
View Variable, 1-7

3-21

W
WAIT statements, 3-30
WEEKDAY functions, 3-45
WHEN ERROR statements, 3-31
WHILE...WHILE END statements,
Word Wrap, 1-8

3-33

Y
YEAR functions,

3-45

T
Task switch, 3-29
Terminology, 3-2

Index-4

Tracer Summit Custom Programming