CMPL Instuction Bulletin.pdf

8/10/2019 CMPL Instuction Bulletin.pdf

1/116

Instruction Bulletin63230-300-221/A1

February 2002LaVergne, TN, USA

P OWERLOGIC S eries 4000 Programming Language

(CMPL)


2/116

63230-300-221/A12/2002

ii 2002 Schneider Electric All Rights Reserved


3/116

63230-300-221/A1 Contents2/2002

iii 2002 Schneider Electric All Rights Reserved

CONTENTS CHAPTER 1INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

WHAT IS THE CIRCUIT MONITORPROGRAMMING LANGUAGE UTILITY? . . . . . . . . . . . . . . . . . . . . . . . . . . 1

A WORD OF CAUTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

ORGANIZATION OF THIS INSTRUCTION BULLETIN . . . . . . . . . . . . . . . 2Notational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

TECHNICAL SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

CHAPTER 2CREATING A PROGRAMMING LANGUAGESOURCE FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

THE CIRCUIT MONITOR PROGRAMMING LANGUAGE . . . . . . . . . . . . . 5

CREATING A SOURCE FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Naming the Source File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Inserting Comments and Blank Lines . . . . . . . . . . . . . . . . . . . . . . . . . 6Source File Line Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

REQUIRED ELEMENTS IN A SOURCE FILE . . . . . . . . . . . . . . . . . . . . . . 6Program Version/Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7The Declaration Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8The Initialize Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9The Metercycle Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

OTHER ELEMENTS IN A SOURCE FILE . . . . . . . . . . . . . . . . . . . . . . . . . 9Timer and Event Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Timer Task Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Event Task Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

ORDER OF EXECUTION OF CMPL PROGRAM ELEMENTS . . . . . . . . 13Posting of Program Name and Program Version . . . . . . . . . . . . . . . 13Initialize Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Metercycle Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Event and Timer Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Possible Program Termination Due To Excessive Scan Time . . . . . 14

CHAPTER 3DEFINING MEMORY REGISTERS IN THEDECLARATION SECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

CM4000 MEMORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15MODBUS Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

DECLARING DATA VARIABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Assigning a Name to a Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16ARRAYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Declaring an Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

REDEFINING A REGISTER WITH EQUATE . . . . . . . . . . . . . . . . . . . . . . 18

CREATING CONSTANTS WITH DEFINE . . . . . . . . . . . . . . . . . . . . . . . . 19

A SAMPLE DECLARATION SECTION . . . . . . . . . . . . . . . . . . . . . . . . . . 20


4/116

Contents 63230-300-221/A12/2002

iv 2002 Schneider Electric All Rights Reserved

CHAPTER 4THE CIRCUIT MONITORPROGRAMMING LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

ASSIGNING VALUES TO DATA ITEMS . . . . . . . . . . . . . . . . . . . . . . . . .21Assigning Constant Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21Assigning Variables to Other Data Items . . . . . . . . . . . . . . . . . . . . . .23

MATHEMATICAL AND LOGICAL OPERATIONS . . . . . . . . . . . . . . . . . . 23Add, Subtract, Multiply, Divide, Modulus . . . . . . . . . . . . . . . . . . . . . .24Logical Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Bitwise Shifts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26Logical Shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27Arithmetic Shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

TRIGONOMETRY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Sine, Cosine, Arctan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Square Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

CONVERTING DATA TYPES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

CONTROL OF PROGRAM EXECUTION . . . . . . . . . . . . . . . . . . . . . . . . .31

Conditional Execution Using IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Repeated Execution Using FOR...NEXT . . . . . . . . . . . . . . . . . . . . . .33Subroutine Execution Using CALL . . . . . . . . . . . . . . . . . . . . . . . . . . .34Terminating a Task or Subroutine Using RETURN . . . . . . . . . . . . . .34Terminating a CMPL Program Using HALT . . . . . . . . . . . . . . . . . . . . 35Restarting a CMPL Program Using RESTART . . . . . . . . . . . . . . . . .35

CONTROL OF THE CIRCUIT MONITOR USING CMDREQ . . . . . . . . . . 35

CONTROL OTHER DEVICES USING COMMSREQ . . . . . . . . . . . . . . . .35Communication Control Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

CHAPTER 5COMPILER OPERATION . . . . . . . . . . . . . . . . . . . . . . . . .39

STARTING THE PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

OPENING A SOURCE FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

SETTING COMMUNICATION PARAMETERS . . . . . . . . . . . . . . . . . . . . . 40

SETTING THE ENVIRONMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Formatting the Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41Setting the Background or Text Color . . . . . . . . . . . . . . . . . . . . . . . .41Changing the Tab Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41Setting the Save Reminder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

SETTING THE COMPILER OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . .42Turning Output Generation On and Off . . . . . . . . . . . . . . . . . . . . . . .42Compiling/Assembling a .src File . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

DOWNLOADING AND VIEWING THE CMPL PROGRAM . . . . . . . . . . . . 43Downloading the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Verifying the Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Viewing Circuit Monitor On-Board Information . . . . . . . . . . . . . . . . . .44

RUNNING AND DEBUGGING THE PROGRAM . . . . . . . . . . . . . . . . . . . 44Running the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Using the Compiler to Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Viewing the CMPL Program Memory . . . . . . . . . . . . . . . . . . . . . . . . .46Reading and Writing to Registers . . . . . . . . . . . . . . . . . . . . . . . . . . .46


5/116

63230-300-221/A1 Contents2/2002

v 2002 Schneider Electric All Rights Reserved

CHAPTER 6RUNNING A PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . . 47

PREPARING TO RUN A PROGRAM: READING AND WRITINGCM4000 REGISTERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

VERIFYING PROGRAM DOWNLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

SETTING REGISTERS BEFORE PROGRAM EXECUTION . . . . . . . . . . 48

RUNNING AND HALTING A PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . . 48

CHAPTER 7DEBUG TECHNIQUES FOR CMPL PROGRAMS . . . . . 51

EXAMINING PROGRAM CONTROL REGISTERS . . . . . . . . . . . . . . . . . 51

USING RUNTIME ERROR CODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

DETERMINING THE NAME, VERSION, AND DATE OF A PROGRAM . 51

DETERMINING THE EFFECTS OF CUSTOM CODE ON THE TOTALMETER CYCLE TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

INSERTING A DEBUG CODE INTO A PROGRAM . . . . . . . . . . . . . . . . . 53

APPENDIX APROGRAMMING LANGUAGE RESERVED WORDS . . 55

APPENDIX BPROGRAMMING LANGUAGE SYNTAX . . . . . . . . . . . . 57

APPENDIX CPROGRAMMING LANGUAGE ASSEMBLERAND COMPILER ERROR CODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

APPENDIX DPROGRAMMING LANGUAGE RUNTIMEERROR CODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

APPENDIX ESAMPLE PROGRAM LIBRARY . . . . . . . . . . . . . . . . . . . 65

APPENDIX FCMPL CONTROL REGISTER LIST . . . . . . . . . . . . . . . . 91

APPENDIX GALARMS (EVENTS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

APPENDIX HPROGRAMMING TIPS . . . . . . . . . . . . . . . . . . . . . . . . . 101

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103


6/116

Contents 63230-300-221/A12/2002

vi 2002 Schneider Electric All Rights Reserved


7/116

63230-300-221/A1 Chapter 1Introduction2/2002 What is the Circuit Monitor Programming Language Utility?

1 2002 Schneider Electric All Rights Reserved

CHAPTER 1INTRODUCTION

This chapter defines the Circuit Monitor Programming Language utility anddescribes the uses for which it is intended. The last sections of the chapterdescribe this manual and explain terms and notation conventions usedthroughout.

WHAT IS THE CIRCUIT MONITORPROGRAMMING LANGUAGE UTILITY?

The Circuit Monitor Programming Language (CMPL) is a tool designed totailor the capabilities of the Series 4000 Circuit Monitor to meet specializedapplication requirements. Based on external, timer, or metercycle events,CMPL provides a means for the end user to customize the following:

data calculation logging and reporting I/O point operation remote device communication command interface control

Using the Windows-based compiler environment included in the CMPLDevelopers Kit, you can develop and test application-specific firmware for thecircuit monitor. Once you are satisfied with the program you develop, you canuse the POWERLOGIC Downloadable Firmware Utility (DLF-3000, version3.0 or higher) to install it in a circuit monitor.

A CMPL program is capable of reading data from registers within the circuitmonitor and from devices on a communications daisy chain. It can also senseexternal events that pass from true to false or the reverse.

Processing this information according to the instructions in the sourceprogram, a custom program can control output relays, write values to a rangeof registers designated for that purpose, and write entries into a data log orwaveform capture files.

When you purchase CMPL, you receive:

the CMPL compiler program that runs on a personal computer (with theMicrosoft Windows NT or 2000 operating system)

this instruction bulletin a help file that contains instructions for creating and executing CMPL

program files example files

A WORD OF CAUTION CMPL provides rapid, flexible responses to customer needs. However, criticalcontrol functions should be provided by specialized equipment designed for aspecific purpose and tested for reliability. Users should not use CMPL toreplace sophisticated equipment engineered for and dedicated to control

tasks.Application engineers who use CMPL must verify that their programsaccurately solve the problems they address. This manual surveys theprogramming tools available and explains debug facilities that can verifylogical operations while programs are executing. However, since the creatorsof CMPL cannot anticipate all of its possible uses, application engineers usingthis product must ensure the accuracy of the programs they wish to include inthe circuit monitor.


8/116

Chapter 1Introduction 63230-300-221/A1Organization of this Instruction Bulletin 2/2002

2002 Schneider Electric All Rights Reserved2

Pay particular attention to the time constraints beyond which CMPLprograms will be terminated to preserve the integrity of other circuit monitoroperations. Most standard circuit monitor operations may be configured bythe user, and some features may be entirely disabled. Therefore, the amountof free (or idle) time available to CMPL will vary widely from one circuitmonitor to the next. In most cases, a CMPL program should not be placed in

a circuit monitor that is configured to execute many of the advanced features,such as CVMT analysis, WFC of several types with high sample rates, and alarge number of subcycle events. Worst-case conditions for both the timerequired to execute custom programs and the memory used by eachprogram should be tested.

ORGANIZATION OF THIS INSTRUCTIONBULLETIN

This bulletin provides the information necessary to write, compile, load, andrun custom circuit monitor programs. The bulletin includes seven chaptersand eight appendixes. There is a table of contents for the entire manual atthe beginning of the document.

The first four chapters describe CMPL and explain procedures andrequirements for writing custom programs. Chapters 5 and 6 describe how tocompile, load, and run a program, and how to read output values. Chapter 7explains debugging methods.

The appendixes provide additional programming language information witha listing of reserved words, a language syntax outline, compiler and runtimeerror codes, and a library of sample programs. A supplemental guide to theCM4000 registers that pertain to CMPL is included.

This manual includes only minimal technical specifications and functionalinformation for the CM4000 circuit monitor. It does not includecomprehensive coverage of DLF3000 or any of several available userinterfaces to the circuit monitor. For complete information on these topics,see the appropriate technical publications.

Notational Conventions To more easily distinguish CMPL commands from explanatory text, thisdocument uses the following notational conventions:

Type Style . A typewriter-style type face is used for text that is typed intothe computer by the programmer, such as programming commands,variable names, and control directives. In the program examples, wordsand characters displayed in boldface are required instructions for theprogram. Two forward slashes (//) represent the beginning of comments.Comments, in a different type style, are not required.

Example 1-1

data_float = 0.0 //Sets data_float to zero(required program line) (commentnot required)

Brackets . The syntax for some CMPL commands allows for assignmentof multiple values or parameters. These values are indicated insidebrackets ([]) as a way of showing they are optional. The bracketsthemselves are not included in the code.

Example 1-2

The format for a DEFINE is as follows:

DEFINE value_name value [value] [value]


9/116

63230-300-221/A1 Chapter 1Introduction2/2002 Technical Support


Actual program lines might be:

The values assigned to end_date are separated by at least one space. Thebrackets are not included.

Capitalization . Program examples are shown using both upper- andlower-case letters. CMPL is not case sensitive and will accommodateeach programmers preference. For example, the compiler seesEND_date and end_Date as the same.

TECHNICAL SUPPORT Programming services, programming instruction, and POWERLOGICtraining classes are available for a fee. Contact your local representative forinformation on any of these services. Or visit our website at:

www.powerlogic.com

DEFINE True 1

DEFINE end_date 0x090e 0x5e0b 0x0f27 0x0064


10/116

Chapter 1Introduction 63230-300-221/A1Technical Support 2/2002



11/116

63230-300-221/A1 Chapter 2Creating a Programming Language Source File2/2002 The Circuit Monitor Programming Language


CHAPTER 2CREATING A PROGRAMMING LANGUAGE SOURCE FILEThis chapter describes the structure of the Circuit Monitor ProgrammingLanguage (CMPL) and tells how to create a source file using the language.

THE CIRCUIT MONITORPROGRAMMING LANGUAGE CMPL is similar to the BASIC language used to program computers. Itperforms integer and floating-point math, including square root and the basictrigonometric functions. Its syntax allows looping and conditional execution.Custom programs written with this language can read from and write toregisters within the CM4000 circuit monitor and remote devices, and can testcircuit monitor events.

Because CMPL contains features that resemble BASIC and other languagesused in general-purpose computer programming, experience with any high-level computer language will benefit engineers who begin to write customprograms for the CM4000 circuit monitor. Training in some form of computerprogramming will make the methods outlined here seem familiar and is highlyrecommended.

As illustrated in Figure 21 , implementing a CMPL program requires three

steps:1. Create a source program file using the CM4000PL compiler editor on a

Microsoft Windows based computer (Windows NT or 2000).

2. Use the CM4000PL compiler to convert the source program file intoinstructions that can be executed by the CMPL function of the circuitmonitor.

3. Download the instructions created in Step #2 to the circuit monitor diskon chip using the POWERLOGIC Downloadable Firmware Utility (DLF-3000 v. 2.02 or higher) provided with the CM4000 Program DevelopersKit. Or, for testing purposes, download the program using the CM4000PLcompiler/debugger to the circuit monitor random access memory (RAM).

source file .fw file download

PROG.SRCCMPL

compile

PROG.lst

DLF3000

compile

compiler listing file

debug(CMPL.dbg)

PROG.fw

Figure 21: Implementing a CMPL Program

CMPLcompile


12/116

Chapter 2Creating a Programming Language Source File 63230-300-221/A1Creating a Source File 2/2002


CREATING A SOURCE FILE A CMPL source file contains a series of instructions written according to therules given in this manual. (For details, see Chapter 3, beginning on page 15 ,and Chapter 4, beginning on page 21 .) These instructions consist of simpleEnglish commands and terms relating to the operation of the circuit monitorand to its internal registers.

Naming the Source File Use standard Windows file-naming conventions (one to 256 characters inlength using letters, numbers, underscores, and selected symbols). TheCMPL compiler requires a filename extension of .SRC. (Files created in theeditor/compiler automatically include the .SRC extension when they aresaved.) Example 2-1 illustrates a correctly named source file.

Example 2-1

PROG_01.SRC

Inserting Comments and Blank Lines Comments and blank lines are not required but will help to clarify anddocument a program. The CMPL compiler ignores blank lines and lines thatbegin with two right slant characters (//). Inserting the two / characters in themiddle of a line makes the remainder of that line a comment that will also beignored. (There must be at least one blank space between the source codeand the beginning of the comment.) Be sure to use two right slant charactersand not two left slant characters (\\).

Blank lines help to clarify a program by separating different logical sections.Inserting blank space will make any program easier to read.

Use comment lines to label each section of a program or to explain programlogic. Comments serve as reminders and are useful to other programmerswho need to understand or modify the original program.

Source File Line Limit A line of code can contain up to 200 characters. Each source file must

contain no more than 32,767 lines. Blank lines and lines containingcomments are included in this number. However, this is a very large numberof lines, and the limit is not likely to restrict any program.

Case Sensitivity CMPL is not case sensit ive. Use lower or upper case letters or anycombination of the two.

Examples in this manual show some lines in lower case and some in all caps.These are only suggestions used to clarify program elements. Differentpatterns of capitalization are possible-depending on each programmerspreference.

REQUIRED ELEMENTS IN A SOURCEFILE See the following sections for descriptions of the required elements in CMPLprograms:

Program Version/Security on page 7 The Declaration Section on page 8 The Initialize Task on page 9 The Metercycle Task on page 9

Include these in this order in each source file. Mark each of these sectionsby inserting lines beginning with two pound sign characters (##). All lines


13/116

63230-300-221/A1 Chapter 2Creating a Programming Language Source File2/2002 Required Elements in a Source File


beginning with the ## notation are called control directives. See Example2-2 .

The first two required sections have one line. The other three requiredsections must contain two control directives, and the two tasks must alsocontain at least one instruction line. The minimum entries required for thesesections follow:

Example 2-2

## PROGRAM SECURITY: 1234567

## PROGRAM VERSION: 1234

## DECLARATION SECTION:

## END DECLARATION

## INITIALIZE TASK:

RETURN

## END INITIALIZE

## METERCYCLE TASK:RETURN

## END METERCYCLE

Notice that the first line of each pair of control directives ends with a colon (:),and that there is a space following the ## notation. These are required. Alsonotice that the instruction RETURN appears in each task. It must appearbetween the control directives that mark the beginning and end of theinitialize task, and of the Metercycle task. This is true even though there areno other instructions within the task sections.

The source file lines shown above will do no useful work, but they illustratethe shortest possible example of a program that will compile intodownloadable instructions without error.

Program Version/Security he Program Version code is required. It has two purposes:

DLF-3000 uses it to verify downloads. Programmers use it to identify program changes.

The program name, which is optional, and version must be entered beforethe declaration section in the formats given below:

Each entry must be on a separate line that begins with the ## notation (witha blank space following the colon and the ##) reserved for control directives.

These are the only lines, besides comments and blank lines, that can appearbefore the required declaration section. They can be very useful. Valuesentered here are placed in designated circuit monitor registers when 1 or 5

## PROGRAM NAME: name_of_program //optional

## PROGRAM VERSION: number_of_version //required

where name_of_program contains up to 16 ASCII characters (letters, numbers,or punctuation)

and number_of_version is a decimal integer in the range 0 to 9999


14/116

Chapter 2Creating a Programming Language Source File 63230-300-221/A1Required Elements in a Source File 2/2002


is entered in register 8189. They provide a convenient way to determinewhich version of which program is currently installed and ready for execution.

NOTE: The program name is stored in registers 8175 8182. The versionnumber of the program is stored in register 8183.

In Example 2-6, note that, by convention, an integer value of 100 denotesversion 1.00; 101, version 1.01; and so on.

Example 2-6

The Program Security code is used in conjunction with the circuit monitorrevenue security. If revenue security is enabled, the CMPL Program Secur itysection is required (by the circuit monitor). If revenue security is disabled, setProgram Security to 0. When enabled, programmers can only access circuitmonitor functions allowed by their security level.

The Declaration Section The declaration section of a custom program defines the circuit monitorregisters used by that program to store data or to read data generated byother circuit monitor functions. Because the declaration section containsdefinitions and declarations instead of instructions, it does not require areturn instruction. Like other required sections, however, it does require twocontrol directives to mark the beginning and end of the sectioneven in theunlikely event that there are no declarations included.

The declaration section must be the first major section in the source file. Onlythe program security, program name, and program version lines can appearbefore the data declarations.

Lines in Example 2-3 and the examples that follow are marked with thecomment Example of Entry and illustrate typical entries in the variousprogram sections. These lines are not required and only represent a sampleof the types of entries that can appear in these sections. The instructionsused are explained in Chapter 3, beginning on page 15 , and in Chapter 4,beginning on page 21 . As given here, they are not a part of any specificprogram.

The control directives beginning with ## are required parts of any CMPLprogram. There must be a colon at the end of the control directive that beginseach of these sections. There must be a blank space following the ##notation and between the elements of all lines of code (e.g., betweenREGISTER and cyclecount in the second line of Example 2-3).

## PROGRAM NAME: CMPL_EXAMP1 //Name is CMPL_EXAMP1

## PROGRAM VERSION: 101 //Version is 1.01


15/116

63230-300-221/A1 Chapter 2Creating a Programming Language Source File2/2002 Other Elements in a Source File


Example 2-3

The Initialize Task The initialize task must immediately follow the declaration section. It beginsand ends with required control directives, and its beginning line must endwith a colon. Instructions within this section execute only when a customprogram is initiated or restarted.

The CMPL compiler requires two control directives and a return instructionfor the initialize task section, even if there are no other instruction lines in thesection.

Example 2-4

The Metercycle Task The metercycle task section must immediately follow the initialize task. Itbegins and ends with control directives, and its beginning line must end witha colon. Instructions within this section execute as a part of each 1-secondmeter cycle update.

The CMPL compiler requires two control directives and a return instruction

for the metercycle task, even if there are no other instruction lines in thesection.

Example 2-5

OTHER ELEMENTS IN A SOURCE FILE The CMPL compiler requires that the program version, program security (ifusing revenue security), declaration section, initialize task, and metercycletask be in every source code file, but it also permits other kinds of tasks andallows embedding of program name and version information.

Timer and Event Tasks The timer task and event task sections use the same format as the initializetask and metercycle task. The timer and event task sections must follow themetercycle task section and must precede any subroutines that may beused. (See the Subroutines section in this chapter.) As with the requiredtasks, each optional task section must begin and end with a control directive

## DECLARATION SECTION : //Required Line

REGISTER cyclecount S14090 //Example of Entry

REGISTER stepcnt S14091 //Example of Entry

BITREG Inputvals S10022 //Example of Entry## END DECLARATION //Required Line

## INITIALIZE TASK: //Required Line

cyclecount = 0 //Example of Entry

return //Required Line

## END INITIALIZE //Required Line

## METERCYCLE TASK: //Required Line

cyclecount = cyclecount + 1 //Example of Entry


## END METERCYCLE //Required Line


16/116

Chapter 2Creating a Programming Language Source File 63230-300-221/A1Other Elements in a Source File 2/2002


(indicated by ##) and must contain at least one return command at the endof the event task or the timer task.

A program can contain more than one timer task and more than one eventtask. Each must specify the elapsed time or the event that will trigger itsexecution. The number of timer and event task sections, taken together, maynot exceed 36.

The instructions within a timer task or an event task execute during thecurrent meter cycle in which the time lapse or the trigger event specifiedoccurred. When more than one section is performed during a single metercycle, they execute in the order that they appear in the program source file.

Timer Task Format The control directive that begins each timer task must be in one of thefollowing two formats, indicating the time that must elapse before the task isperformed:

The first format measures seconds elapsed, and the second formatmeasures both elapsed time and offset in minutes. The offset value ismeasured from midnight (12:00 a.m.) every day. For example, if a timer taskwere to execute beginning at 8:00 a.m. each day, an offset of 480 minuteswould be required. After 8:00 a.m. the timer task is executed at the specifiedinterval until 11:59 p.m.

Vary the value of the offset in the second format when a program containsmore than one timer task with the same time interval delay. Otherwise, all ofthe tasks with the same interval will occur in the same meter cycle. The endof each timer task must be marked by a control directive like this:

## END TIMER

Each timer task section must also include at least one return instruction atthe end of the timer task.

Example 2-7

## TIMER TASK: INTERVAL x SECONDS

where x is a decimal integer in the range 1 to 32767

or## TIMER TASK: INTERVAL x MINUTES OFFSET y MINUTES

where x is a decimal integer in the range 1 to 1440

and y is a decimal integer in the range 0 to 1439

## TIMER TASK: INTERVAL 45 SECONDS //Required Line

if (event2state = false) //Example of Entry

{ //Example of Entry

false_count = false_count + 1 //Example of Entry} //Example of Entry


## END TIMER //Required Line


17/116

63230-300-221/A1 Chapter 2Creating a Programming Language Source File2/2002 Other Elements in a Source File


Example 2-8

Event Task Format Event tasks all begin with a control directive in one of the following formats:

Each event task section must terminate with a control directive in this format:

## END EVENT

Each event task must also contain at least one return instruction at the end

of each event task. Examples 2-9 and 2-10 illustrate event tasks.

## TIMER TASK: INTERVAL 1 MINUTES OFFSET 0 MINUTES //Required

if (event2state = false) //Example

{ //Example

false_count = false_count + 1 //Example} //Example

return //Required

## END TIMER //Required

## EVENT TASK: EVENT event_number FALSE-TO-TRUE

or

## EVENT TASK: EVENT event_number TRUE-TO-FALSE

where event_number is a decimal integer used to refer to a legal CM-4000 event(See Appendix G, Alarms (Events) , for information on how to set up user-defined alarms. See Table 21 below for valid event numbers.)

Table 21:Valid Event Numbers

Event No. 1 Description

10011080 Normal alarms

20012020 High speed alarms

30013020 Disturbance alarms

40014040 Digital alarms

50015015 Boolean alarms60016004 Waveshape fault alar ms

7001 Transient alarm

1 Event numbers contain two pairs of digits:

The first pair describes the alarm type. 10 = standard, 20 = high-speed, etc.The second pair describes the alarm position for that alarm type. By default, 01 = overcurrent phase A for standard-speed alarms, and 01 = voltage swell A-D for disturbancealarms. However, keep in mind that you can change the defaults.


18/116

Chapter 2Creating a Programming Language Source File 63230-300-221/A1Other Elements in a Source File 2/2002


Example 2-9

Example 2-10

NOTE: Before an event task program can be executed, the event must beenabled using POWERLOGIC application software (such as SMS-3000), orthrough Setup > Alarms on the circuit monitor display.

Subroutines Subroutines use the same format as other sections containing instructionsand must follow all other sections in the source file. The number ofsubroutines is limited only by the memory available to the CMPL program.

Each subroutine begins with a control directive that assigns it a unique nameand concludes with another control directive marking the end of thesubroutine. The required format for the control directives that define asubroutine is as follows:

Each subroutine must also contain at least one return instruction at the endof the section.

The instructions in a subroutine execute each time it is called by name fromwithin any task section or from another subroutine. (For details, seeSubroutine Execution Using CALL on page 34 .) After the completion of asubroutine, the task or other subroutine that called it continues its executionbeginning with the line immediately following the subroutine call.

Example 2-11

You can use subroutines to reduce the total number of program linesrequired. For example, if a sequence of instructions more than two or threelines in length appears in two or more different task sections, or if such asequence is written more than once in a single section, replace the sequencewith a subroutine.

## EVENT TASK: EVENT 1002 FALSE-TO-TRUE //Required Line

event1002 = event1002 + 1 //Example of Entry


## END EVENT //Required Line

## EVENT TASK: EVENT 1002 TRUE-TO-FALSE //Required Line

event1002 = event1002 + 1 //Example of Entry


## END EVENT //Required Line

## SUBROUTINE: subr_name

## END SUBROUTINE

where subr_name is a unique name by which this subroutine is called. Thisname can contain up to 27 letters, numbers, and underscore characters.

No other punctuation or characters may be used.

## SUBROUTINE: COMPUTE_TOTAL_CURRENT //Required Line

totalamps = ia + ib + ic //Example of Entry


##END SUBROUTINE //Required Line


19/116

63230-300-221/A1 Chapter 2Creating a Programming Language Source File2/2002 Order of Execution of CMPL Program Elements


Experienced programmers who prefer to use structured techniques toorganize their programs will also find subroutines useful. Note that all dataitems are global in scope, and that subroutines and all other tasks access allvalues by direct address.

Subroutines can contain instructions to call other subroutines. The CMPLcompiler permits up to eight layers of nesting of subroutines within othersubroutines.

ORDER OF EXECUTION OF CMPLPROGRAM ELEMENTS

CMPL program elements execute in the following order (described in thefollowing paragraphs):

program name and version initialize task metercycle task event and timer tasks subroutines

NOTE: A CMPL program downloaded to a CM4000 circuit monitor, using theDownloadable Firmware Utility (DLF-3000), remains inactive until a registeris set or a compiler command is issued to run the program.

Posting of Program Name and ProgramVersion

If the program name or the program version are included in the source file,their values are inserted into specific circuit monitor registers at the t ime thecustom program is downloaded. This permits users to see what customprogram is installed in the circuit monitor even when the program logic is notbeing executed.

Initialize Task When program execution first occurs, the instructions in the initialize tasksection execute, followed by those in the metercycle task section and thenany appropriate timer task or event task sections. The initialize task sectiondoes not execute again until the custom program is halted and restarted.(Loss of control power or any reset of the circuit monitor will cause a programto halt.)

Metercycle Task The instructions within the metercycle task section are the first to beperformed except in the first meter cycle of program operation. Only in thevery first meter cycle does the initialize task section execute first.

Event and Timer Tasks The instructions in the event task and timer task sections, if any, execute afterthe metercycle task instructions if their specific event or timer conditions aremet. For example, if an event occurs for which an event task exists, theinstructions in that event task will execute following the metercycle taskduring the current meter cycle.

Similarly, if a time interval specified by a timer task has elapsed (plus anyspecified offset), the instructions in that timer task will execute following themetercycle task instructions during the current meter cycle. If coincidence ordesign causes more than one t imer task or event task to be eligible forexecution during the same meter cycle, the tasks will be completed in theorder in which they appear in the program source file.

Until program execution is halted, the instructions in all of the task sectionsare considered for execution during each meter cycle in the circuit monitor.Event tasks and timer tasks will likely not all be executed during each meter


20/116

Chapter 2Creating a Programming Language Source File 63230-300-221/A1Order of Execution of CMPL Program Elements 2/2002


cycle, but they will be considered for execution each time in the order in whichthey appear in the source file. Instructions in the metercycle task will beexecuted each time unless they are prevented by the logic in the metercycletask instructions themselves.

Subroutines Instructions within subroutine sections execute only when called from insideother sections. They may occur many times during a single meter cycle orthey may not be performed at all, depending upon logic that appears in othersections of the program.

Possible Program Termination Due ToExcessive Scan Time

Terminated programs will not automatically restar t, and forced terminationcan cause a failure to collect expected data or perform programmedoperations.

Program designers must consider that simultaneous triggering of timer andevent task sections, in addition to the regularly performed metercycle tasksection, may increase program execution time during specific meter cycles.Invoking too many instructions during a single cycle could force theunexpected termination of the entire custom program. Overly complexprograms may not be allocated sufficient processing t ime to complete alltasks. These programs will be terminated because of excessive scan time,and will generate runtime error 1101 or 1102. These errors may also becaused by a logic error, such as endless loops, in the program.


21/116

63230-300-221/A1 Chapter 3Defining Memory Registers in the Declaration Section2/2002 CM4000 Memory


CHAPTER 3DEFINING MEMORY REGISTERS IN THE DECLARATION SECTION

This chapter describes the storage registers available in the CM4000 circuitmonitor for access by the Circuit Monitor Programming Language (CMPL)utility. It tells how to use the Declaration section of a CMPL program to makethe registers available for use within that program.

CM4000 MEMORY The circuit monitor contains both a program memory area and an extendedseries of data registers. Program memory is an extension of the circuitmonitors operating system. The POWERLOGIC DLF-3000 DownloadableFirmware Utility (DLF-3000) will insert instruction codes (created fromsource program files by the language compiler) into the program memoryarea. This is also how a compiled custom program is installed in the circuitmonitor.

Data registers are storage areas used by custom programs or by otherfunctions within the circuit monitor. Some registers contain informationgenerated by specific circuit monitor functions. A CMPL program can readfrom any of these registers but cannot write data into them. Other registers

(read/write registers) are designated specifically for use by custom programsand are available for the long- or short-term storage of data.

The register read/write capability of POWERLOGIC application software,such as SMS-3000, allows users to communicate commands to the circuitmonitor by writing to a small number of registers. Each register contains 16data bits and corresponds to what experienced programmers will recognizeas a 16-bit word of accessible memory.

MODBUS Registers MODBUS registers are available both to CMPL programs and to other circuitmonitor functions. They are addressed by the letter S followed by a 4- or5-digit number in the range 1000 through 65535.

Many of these registers are CMPL volatile registers (S40000S41999),

meaning that a loss of power erases the values stored there. The CMPL non-volatile registers that are both read from and written to by custom programsare S14000 through S14499.

Both sets of registers are reserved for the exclusive use of the CMPLfunction. They serve both as information storage during the execution of aprogram and as the principal means of communication between CMPLprograms and any external user interface.

DECLARING DATA VARIABLES Before a custom program can read from or write to any register, the registermust be assigned a name in the declaration section of that program. Anydeclaration of a name for a register must also give the data type to beassociated with that name. The choice of data type determines the uses that

can be made of any declared register by the custom program.Table 31 on page 16 shows the types of data that can be declared in CMPL.It defines the range of values permitted for each type and suggests somepotential uses for each. It also shows the number of registers required tosupport that data type.

Some data types require only one register. Others require two or more. If, forexample, register S14001 is defined as a data type requiring two registers,then register S14002 is included in the definition although it is not mentionedby name.


22/116

Chapter 3Defining Memory Registers in the Declaration Section 63230-300-221/A1Declaring Data Variables 2/2002


Assigning a Name to a Register There is one form of declaration that assigns a name and a data type to aregister. It must be written on a single line and has the following format:

data_type name_of_register

The data type chosen determines the possible uses of this data item.Throughout the custom program that uses this declaration, the name of thedata item will be the same as the register name used in the declaration. Data

types requiring more than one register are known only by the register nameused in the declaration.

A more advanced form of declaration makes it possible to label data itemswith names that are easier to remember or understand. These names aresometimes called variable names or just variables to parallel the use ofvariables in many computer programming languages. CMPL data items canrefer to read-only registers as well as read/write registers.

Declarations of these names are also entered on a single line and have thefollowing format:

Using this format to declare data items makes programs more easilyunderstood by those without a complete knowledge of the circuit monitorregisters. Using descriptive variable names also simplifies the programmerstask by replacing register addresses with meaningful terms that are easier toremember.

Table 31:Data Types

Data Type Range of Values RequiredRegisters

Description of Use Existing Use in CM-4000

REGISTER 32768 to +32767 1 Signed integer valueswithin permitted range

Amperes, Volts

BITREG 16 single-bit values 1 Logical flags or switches I/O or status flags

LONGREG 2,147,483,648 to +2,147,483,647 2 Large signed integers

FLOAT 1.2 E 38 to 3.4 E +38 2 Floating point values to7 digits of precision

POWFACT 0.999 to +1.000 1 Power factors Power factors

MOD10L2 9999 9999 to +9999 9999 2 Signed counters to 8 digits Digital input operationcounter

MOD10L3 9999 9999 9999 to +9999 9999 9999 3 Signed counters to 12 digits Energy

MOD10L4 9999 9999 9999 9999 to +9999 9999 9999 9999 4 Signed counters to 16 digits Energy

DATETIME 1/1/2000 00:00:00 to 12/31/2099 23:59:59 4 Date and time accurate tonearest second

D/T of events, resets,min/max demand, etc.

data_type name_of_variable name_of_register

where data_type is the name of any valid data type

name_of_variable is an easily understood and rememberedname consisting of up to 27 letters, numbers, and underscores

and name_of_register is the name (beginning with S) of anyregister


23/116

63230-300-221/A1 Chapter 3Defining Memory Registers in the Declaration Section2/2002 Arrays


To parallel the earlier example, the following declaration defines a variablenamed max_value of type FLOAT that occupies register S14000 and, byextension, register S14001 (because variables of type FLOAT require tworegister).

Example 31:

Throughout a program that uses this declaration, this data item can bereferred to by the variable name max_value or by the register nameS14000. The register address S14001 is also defined and cannot be used forany other purpose. S14001 is not a legal name for this data item.

ARRAYS CMPL permits the declaration of arrays of up to 256 data items. Each dataitem in an array is of the same type. All items in an array have the samename. A reference to a specific member in the array consists of the variablename or register name used to declare the array plus an integer in the range1 to 256 contained in square brackets ([]). The integer value indicates which

of the entries in the array is intended.Indicate the total number of entries in each array as a part of its declaration.Arrays can contain up to 256 data items, but it is common to have fewer. Forexample, the following line declares an array of 10 variables. The array isnamed sample_array and each of its ten members is a separate data itemhaving a data type of FLOAT.

Example 32:

Within a custom program that uses this declaration, the 10 individual dataitems will be called sample_array[1] , sample_array[2] , and so on.

Each data item of type FLOAT requires two registers, so this declaration of10 items requires a total of 20 registers. The array sample_array usestwenty registers beginning with S14000 and extending through S14019.These registers are not available for other uses within the custom programthat contains this declaration.

Arrays are useful in more advanced programs that compute the value of thenumber in square brackets (sometimes called a subscript or index) while theprogram is running. This permits a program to write to or read from differentparts of an array under different conditions that occur during the programsexecution.

FLOAT max_value S14000 //S14000 and S14001

FLOAT sample_array[10] S14000


24/116

Chapter 3Defining Memory Registers in the Declaration Section 63230-300-221/A1Redefining a Register With Equate 2/2002


Declaring an Array Declare an array as you would a simple data item and insert the valueindicating the number of array entries into the declaration formats as follows:

NOTE: The array index, n , cannot be a mathematical expression, such as(value + 1); n must be a decimal integer.

Access members of an array using either the array name and the subscript(as in sample_array[3] ) or the declared register name and the subscript(as in S14000[3] ). Use either of these when the declaration is in the firstformat and includes both an array name and a register name.

REDEFINING A REGISTER WITHEQUATE

Never declare any data register as a part of more than one data item;doing so will cause a compiler error. Take care when using data typesthat require more than one register or when creating arrays containingmultiple data items . Exclude all of the registers encompassed by onedeclaration statement from any other declaration.

The one exception to this rule is the declaration of an EQUATE. An EQUATE is not a true data type, but this term can appear in a declaration statement asif it were a data type. The format for declaring an EQUATE is as follows:

The requirements for declaring an EQUATE are exactly opposite those forall other data declarations. An earlier data declaration must already includethe register named in name_of_register . The CMPL compiler onlypermits the redefinition of single registers in this manner, and customprograms can only use names declared with EQUATE as if they were of thedata type REGISTER.

Declaring an EQUATE makes it possible to address a single registercontained in a multi-register data type or to attach a special name to anindividual register that lies within an array definition. When declaring anEQUATE, be certain that the register to be redefined is already included inanother declaration. The other declaration must appear above the EQUATE in the declaration section of the source file.

data_type name_of_array[n] name_of_register

where data_type is the name of any valid data type

name_of_array is an easily understood and rememberedname consisting of up to 27 letters, numbers, andunderscores.

name_of_register is the name (beginning with S) ofany register

and n is a decimal integer in the range 1 to 256

EQUATE name_of_variable name_of_register

where name_of_variable is an easily understood and remembered name

consisting of up to 27 letters, numbers, and underscores.and name_of_register is the name (beginning with S) of any register


25/116

63230-300-221/A1 Chapter 3Defining Memory Registers in the Declaration Section2/2002 Creating Constants With DEFINE


CREATING CONSTANTS WITH DEFINE Another kind of statement that can appear in the declaration section is aDEFINE. A DEFINE does not affect the use of data registers. It is a featurethat is included to make custom programs easier to create and read by givingeasily remembered names to constant numeric values.

The format for a DEFINE is as follows:

To define constants, use numeric values that are decimal integers or floating-point values or hexadecimal integers in the format 0xnnnn where nnnn represents from 1 to 4 digits of a hexadecimal value. To create constants thatoccupy multiple registers, DEFINE the name of the constant as equal tomultiple numeric values, one for each register used.

As a simple example of a DEFINE, the following statements substitute thewords FALSE and TRUE for the numeric values 0 and 1. This reduces the riskthat a programmer may reverse the numeric values and forget which oneindicates which logical state.

Example 33:

Use DEFINE to substitute a name for any value (such as a delay time or athreshold value) that is used several times in a program, and that maychange in the future. When this value changes, only the DEFINE will need tobe modified and the correction will be carried throughout the program.

What follows is a more complex example in which a multiple-registerconstant is defined using separate numeric values for each register:

Example 34:

The value of max_energy established by this DEFINE is the equivalent of adata item requiring four registers. Constants created with DEFINE can onlyappear in arithmetic expressions with variables whose size in number ofregisters and whose range of numeric values are consistent with the value ofthe constant. (See the Converting Data Types on page 29 for moreinformation on matching data types within expressions.)

DEFINE value_name value [value] [value]

where value_name is an easily understood and remembered nameconsisting of up to 27 letters, numbers, and underscores.

and value represents a numeric value or, in some cases, multiplenumeric values in each register. (Do not include the brackets inthe code.) See Example 3-5.

DEFINE FALSE 0

DEFINE TRUE 1

DEFINE max_energy 1234 5678 9000 0000


26/116

Chapter 3Defining Memory Registers in the Declaration Section 63230-300-221/A1A Sample Declaration Section 2/2002


A SAMPLE DECLARATION SECTION

## DECLARATION SECTION:

DEFINE OFF 0

DEFINE ON 1

DEFINE NO 0DEFINE YES 1

BITREG OUTPUT_STATUS S4006

REGISTER IA_AMPS S1100

REGISTER IB_AMPS S1101

REGISTER IC_AMPS S1102

REGISTER TOTAL_CURRENT S14101

REGISTER AVERAGE_TOTAL_CURR S14102

REGISTER S14103

REGISTER PEAK_CURRENT S14104

REGISTER DISPLAY_LIST[10] S14110

DATETIME START_TIME S14120

MOD10L4 ENERGY_VAL S14124

POWFACT POWER_FACT_TOT S14130

## END DECLARATION //------- end declarations


27/116

63230-300-221/A1 Chapter 4The Circuit Monitor Programming Language2/2002 Assigning Values to Data Items


CHAPTER 4THE CIRCUIT MONITOR PROGRAMMING LANGUAGEThis chapter describes the commands that make up the Circuit MonitorProgramming Language (CMPL). These are the keywords and expressionsthat specify actions to take place in each of the task sections of a customprogram. See Required Elements in a Source File on page 6 for completediscussions of the different kinds of tasks and of the required and optionalelements in each custom program written for the CM4000. See DefiningMemory Registers in the Declaration Section on page 15 for a description ofthe declaration section that defines data items for use with the commandsdiscussed below.

ASSIGNING VALUES TO DATA ITEMS The declaration section of a CMPL program does not assign any values todata items. The registers that can only be read by custom programs will, ofcourse, receive values from other functions within the circuit monitor. Allother data items will have indeterminate values until the CMPL programassigns values to them within the initialize task or one of its other tasksections.

Make sure that each program initializes all of its variables. Never assume thatany of the writable registers in the circuit monitor will contain any particularvalue unless it is explicitly initialized within a custom program.

In the initialize task section, assign a starting value to each item that mustequal 0, 1, or some other value. This ensures that the program performs asexpected. The initialize task section provides a one-time opportunity toensure that variables usedsuch as counters and pointershaveappropriate beginning values. Initialize all remaining data items within theother task sections of the program . Depending on the logic of theprogram, data items initialized in the initialize task section may need to bereset during program execution. Any task section can contain instructions tochange the contents of any declared, writable data register at any time.

Remember that all data items are global in scope . This means that any

value set in one section of the program immediately becomes effective in allother parts of the program. Be careful that one task section does not reset avariable that is used in another task.

Assigning Constant Values The simplest format for assigning a value to a data name (called anassignment statement ) is as follows:

The data name of the variable that is to receive the value must be on the left-hand side of the equals sign. The constant numeric value or values must beon the right. An assignment statement looks like an algebraic equation, but italways indicates that the value on the right-hand side of the statement isassigned to the data item on the left. These positions cannot be reversed.

data_name = value [value] [value] [value]

where data_name is a variable name or subscripted memberof an array that has been declared in the Declarationsection

and value is either a decimal constant, a hexadecimalconstant, or, if data_name is of a data type that usesmultiple registers, represents the value in eachregister. (Do not include the brackets in the code.)

Example: count = 4 6 8 10


28/116

Chapter 4The Circuit Monitor Programming Language 63230-300-221/A1Assigning Values to Data Items 2/2002


Example 45:data_name[2] = 4

The name of a data item receiving a value in an assignment statement canbe either the register address of that item or a variable name, depending onthe format used to declare it in the declaration section. One member of an

array of data items can also receive a value in an assignment statement. Toassign a value to one member of an array, give the data name declared forthe array. After the data name, in square brackets, enter the subscriptnumber of the selected array member.

The numeric value assigned to any variable must not exceed the valuespermitted for items of that variables data type. (See Table 31 on page 16 fora complete list of data types and their associated value ranges.) Data itemsof type REGISTER, for example, can only have integer values that lie between

32768 and +32767. LONGREG data items are also restricted to integervalues, but they can be in a range from 2,147,483,648 to +2,147,483,647,which is the range supported by that data type. See Example 4-1.

Data items of types MOD10L2, MOD10L3, and MOD10L4 (sometimes calledthe MODULO 10K types) define multiple registers. They accept multiplevalues in a single assignment statementa separate value for each registerincluded in the data item.

DATETIME data items can also accept four values that correspond to the fourregisters included in the data item. However, it is less common to assignvalues to items of type DATETIME. These are usually values supplied by thecircuit monitor; they are used in custom programs to compute elapsed timeor to record times when events occur.

All numeric constants assigned to data items can be preceded by a plus (+)or minus () sign. Positive values are assumed unless a negative is specified.Be careful that a signed value is not outside of the allowed range for the datatype used. Of all the data types, only DATETIME and BITREG items do notpermit any negative values. (See Example 47. )

The following examples show valid assignment statements and specify thedeclarations that are necessary for each.

Example 46:

Example 47:

The numeric constants 0 and 0.0 have the same value, of course, as do 1and 1.0, etc. Constants assigned to data types that support only integersmust not include decimals.

When an assignment statement includes a constant expressed inhexadecimal (or numeric base 16) the value is always an integer.

data_int = 0 Sets the data item to zero.

This is a valid assignment statement if data_int has been declared to be of data type REGISTER,LONGREG, or FLOAT each of which accepts theinteger 0 as a valid value.

data_int = 0x00ff Sets the data item to 00ff hex or 255 decimal

This is a valid assignment statement if data_int

has been declared to be of data type BITREG or REGISTER.


29/116

63230-300-221/A1 Chapter 4The Circuit Monitor Programming Language2/2002 Mathematical and Logical Operations


Example 48:

Assigning Variables to Other Data Items The value of one data item or variable can be assigned to another data itemby an assignment statement. Example 49 assigns the value ofcounter_val to hold_counter :

Example 49:

Notice that the value of the variable on the right is always assigned to thevariable on the left-hand side of the equation. In this example, counter_val does not change, but hold_counter takes on the same value ascounter_val . An assignment statement such as this is useful to preservethe current value of counter_val before re-initializing counter_val forfurther use within the program.

Data items used in an assignment statement must all be of the same datatype. (Use the CONVERT function, described in Converting Data Types onpage 29 to transfer values from one data type to another.) Any of thevariables in the assignment statement can be a subscripted member of anarray.

Do not include signs (+, ) in an assignment statement that assigns onevariables value to another.

MATHEMATICAL ANDLOGICAL OPERATIONS

Special cases of the assignment statement make it possible to perform botharithmetic and logical operations using data items. Through all of thevariations on the basic assignment statement that appear below, rememberthese three rules:

1. All data items in an assignment statement must be of the same data type.The only exception to this is in the use of the CONVERT function to movevalues from one data type to another.

2. Values on the right-hand side of the equationwhether numericconstants, arithmetic expressions, or other expressionsare alwaysassigned to a single data item on the left-hand side. Only one data itemcan appear on the left-hand side of any assignment statement.

3. Functions cannot be combined with arithmetic operations. For example,the expression x = sin(angle_value + 1) is invalid.

meter_mod10 = 0 0 Sets meter_mod10 to zero.

This example assumes that meter_mod10 is ofdata type MOD10L2 which uses two registers.

hold_counter = counter_val


30/116

Chapter 4The Circuit Monitor Programming Language 63230-300-221/A1Mathematical and Logical Operations 2/2002


Add, Subtract, Multiply, Divide, Modulus To perform any of the five arithmetic operations, write an assignmentstatement in which the value of an arithmetic expression on the right-handside of the equation is assigned to a single data item on the left. Use theoperators:

+ *

/ %

to add, subtract, multiply, divide, and perform modulus division.

Arithmetic expressions are evaluated from left to r ight. Parentheses orbrackets are not permitted within expressions, and it is not possible to alterthe order of evaluation. Limit each expression to a maximum of six operators.Complex arithmetic operations may require a series of assignmentstatements to perform the operation one part at a time.

Numeric constants used in arithmetic expressions can be decimal integersor floating-point decimal values. See Assigning Constant Values on page21 for a discussion of appropriate values for use with different data types.Remember that all data items within an assignment statement must be of thesame data type. All numeric constants used in arithmetic expressions mustbe in a format that is consistent with the data type of the variables in thatstatement.

Some data types cannot be used in some arithmetic operations because it isillogical to perform these operations on those types of data. Do not use datatypes BITREG or DATETIME in any arithmetic operations. MOD10L2,MOD10L3, and MOD10L4 are generally considered to be counters or meters.Do not use these in multiplication or division.

The following examples show some typical assignment statements used toperform basic arithmetic (note the blank space between each element):

Example 410:

Example 411:

Example 412:

Example 412 demonstrates a common and important use of arithmetic in

an assignment statement. The CMPL program will evaluate the expressionon the right-hand side of the equation (new_value + 1) and then assignthe result to the data item on the left (new_value) , thereby incrementingnew_value by 1.

This contradicts the rules of traditional algebra, but it is a very commonfeature of most computer programming languages. The principle that itdemonstrates underlies all types of assignment statements: CMPL fullyevaluates the right-hand side of the equation and then assigns that value tothe single data item on the left-hand side.

new_value = 3 * old_value Multiplies old-value by three andassigns the result to new_value .

new_value = 3 * old_value + 7 Multiplies old-value by three; adds 7to the result, and assigns the total tonew_value .

new_value = new_value + 1 Increases the value of new_value by 1.


31/116

63230-300-221/A1 Chapter 4The Circuit Monitor Programming Language2/2002 Mathematical and Logical Operations


Logical Operations CMPL includes several functions that generate values based on a logical comparison of the individual bits in the functions operand(s). The AND, OR,and XOR functions are similar to the trigonometric and square root functions(see Trigonometry on page 27 ), but they have two operandscontainedwithin a single set of parentheses and separated by a comma. The NOT function has only one operand.

All data items used as operands of these logical functions must be of datatype BITREG. Values produced by these functions are always assigned to aBITREG variable. The BITREG data type consists of a single register whoseindividual binary bits are examined or set one at a t ime. A bit (or BInary digiT)can only have one of two values. It is always equal to either 1 ( on or true ) or0 (off or false ).

Subscripts are permitted when a BITREG data item is a part of an array.Signs (+ or ) are not permitted with logical functions.

One of the operands of an AND, OR, or XOR logical function can be a numericinteger constant expressed in either numeric base 10 or base 16. The valueof any numeric constant should be between 32768 and +32767 if written innumeric base 10 or between 0x0000 and 0xffff if written in numeric base 16.

The AND function sets each bit in the result if, and only if, the correspondingbits in the operands are set. Otherwise, the bit is reset.

The OR function sets each bit in the assigned value to on if the correspondingbit is set in either of the operand registers.

The XOR (eXclusive OR) function sets the assigned value bits on only if thecorresponding bits are set in only one of the two operand registers.

AND

A B Result

0 0 0

0 1 0

1 0 0

1 1 1

OR

A B Result

0 0 0

0 1 1

1 0 1

1 1 1

XOR

A B Result

0 0 0

0 1 1

1 0 1

1 1 0


32/116

Chapter 4The Circuit Monitor Programming Language 63230-300-221/A1Mathematical and Logical Operations 2/2002


The NOT function assigns a value in which the pattern of bits turned on andoff is the opposite of the pattern found in its single operand.

The following examples assume that a_var , b_var , and c_var are all ofdata type BITREG. They show typical uses of these functions:

Example 413:

Example 414:

Example 415:

Example 416:

Bitwise Shifts Advanced program engineers may want to write assignment statements that

use the CMPL SHIFT function. The SHIFT function has two operands. Theyare written within a single pair of parentheses and separated by a comma.

The first operand is always the name of a data item of data type BITREG orof data type REGISTER. The second operand consists of either the letter L(left) or R (right) followed by a numeric constant in the range 1 to 15,inclusive. As with any assignment statement, the data item that receives thevalue produced by the SHIFT function should be of the same data type asthe data item that is the first operand.

Like the logical functions shown above, subscripts are permitted as a part ofdata names. Signs (+ or ) are not permitted.

NOT

A Result

0 1

1 0

a_var = AND(b_var, c_var) A bitwise AND of b_var and c_var isperformed and the result is assigned toa_var.

a_var = OR(b_var, c_var) A bitwise OR of b_var and c_var isperformed and the result is assigned toa_var .

a_var = XOR(bar_var, c_var) A bitwise eXclusive OR of b_var andc_var is performed and the result isassigned to a_var .

a_var = NOT(b_var) A bitwise NOT of b_var is assigned toa_var .


33/116

63230-300-221/A1 Chapter 4The Circuit Monitor Programming Language2/2002 Trigonometry


The following are examples of assignment statements using the SHIFT function:

Example 417:

Example 418:

Logical Shift The SHIFT function performs differently with data items of type BITREG thanwith data items of type REGISTER. If the first operand and the receiving valueare of data type BITREG, a logical shift is performed. A logical shift one bit tothe right causes a zero to be inserted in the leftmost, or most significant bit position. Any value in the rightmost, or least significant bit position, displacedby the shift is dropped. A logical shift to the left inserts a zero in the leastsignificant bit position and drops any value in the most significant bit position.

Arithmetic Shift If the operand and receiving variable are of data type REGISTER, the SHIFT command executes an arithmetic shift. An arithmetic shift will continuallycopy the sign bit to the most significant bit position. Any value in the leastsignificant bit position displaced by the shift is dropped. An arithmetic shift tothe left inserts a zero in the least significant bit position and drops any valuein the most significant bit position.

Example 419:

Arithmetic shifts are useful to programmers familiar with binary arithmetic(using numeric base 2). Data items of type REGISTER are rapidly multiplied

or divided by 2 or multiples of 2 using this specialized technique.

TRIGONOMETRY CMPL can perform the basic trigonometric functions: sine, cosine, arctan,and square root. If necessary, other trigonometric operations are easilyderived from the basic functions. For example, arcsine = 1/sine; andarccosine = 1/cosine.

a_var = SHIFT(b_var, L4) The pattern of bits in the registerindicated by b_var are duplicated in the

register indicated by a_var , but theyare shifted 4 bits to the left.

Before: b_var = 0000 1111 1111 0000

After a_var = 1111 1111 0000 0000

a_var = SHIFT(b_var, R4) The pattern of bits in the registerindicated by b_var are duplicated in theregister indicated by a_var , but theyare shifted 4 bits to the right.

Before: b_var = 0000 1111 1111 0000

After a_var = 0000 0000 1111 1111

a_var = SHIFT(b_var, R1) The pattern of bits in the registerindicated by b_var are duplicated in theregister indicated by a_var , but theyare shifted 1 bit to the right.

Before: b_var = 1000 1111 0000 1111

After: a_var = 1100 0111 1000 0111


34/116

Chapter 4The Circuit Monitor Programming Language 63230-300-221/A1Trigonometry 2/2002


Sine, Cosine, Arctan The examples below demonstrate the use of the SINE, COSINE, andtwo-argument ARCTANfunctions. Notice that these always appear on theright-hand side of the assignment statement and that the computed valuesare then assigned to a data name on the left-hand side.

Example 420:

Example 421:

Example 422:

Data items receiving values from the SINE , COSINE, and ARCTAN functionsmust all be of data type FLOAT. The value within the parentheses of eachfunction (the operand of that function) must also be a data item of data typeFLOAT. Arithmetic expressions are not permitted as operands.

Do not use numeric constants as function operands. The constant value canbe calculated outside the program and inserted into the source file to helpminimize the run time.

All angular values for SINE and COSINE are expressed in radians and mustbe within the range /2 to /2 (i.e., 90 to 90 degrees), inclusive.

ARCTAN returns a value in the range of to radians. ARCTAN uses thesign of the two arguments to decide which quadrant the value is in. There isnot a limited range for the operands of ARCTAN. Value_2 cannot equal 0.

Square Root The SQROOT function computes square roots in much the same way that thetrigonometric functions compute their values. The SQROOT function mustappear on the right-hand side of an assignment statement. Its operand (inparentheses) must be a data item of type FLOAT with a positive numericvalue. The square root of the operand is computed and assigned to the dataitem, also of data type FLOAT, that appears on the left side of the assignmentstatement. This function returns positive roots only.

sin_value = SINE(angle_val) Assigns sine of angle-val tosin-value .

cos_value = COSINE(angle_val) Assigns cosine of angle-val tocos_value .

arct_value = ARCTAN(value_1,value_2)

Evaluates ( value_1 / value_2 ) wherevalue_1 is the Y coordinate andvalue_2 is the X coordinate; assignsarctan of result to arct_value .


35/116

63230-300-221/A1 Chapter 4The Circuit Monitor Programming Language2/2002 Converting Data Types


An example follows:

Example 423:

CONVERTING DATA TYPES In all of the forms of the assignment statement discussed above, all dataitems in any statement must be of the same data type. Data items of differentdata types cannot appear in a single arithmetic expression, but the CONVERT function makes it possible to assign the value of one data item to anotherdata item of a different data type.

In the examples that follow, assume that data_int has been declared witha data type of REGISTER and data_float has been declared with a datatype of FLOAT:

Example 424:

In Example 424, no information is lost because the floating-point variabledata_float can contain any integer value that can possibly be stored bythe REGISTER variable, data_int . This statement makes the integer valuecontained in data_int available in floating-point format ( data_float ) tobe used with other f loating-point values.

Example 425:

In Example 425, the data item of data type REGISTER ( data_int ) cannot store any fractional part of the value of data_float . Only the integerportion of the value of data_float is assigned to data_int .

NOTE: The use of the CONVERT function includes this possibility for thedistortion or truncation of values. Avoid value conversions where possible.Approach all uses of the CONVERT function with caution to preventunexpected distortion or loss of data.

You cannot convert from a data type FLOAT having a value greater than32767 to a data type REGISTER .

sqrt_value = SQROOT(x_value) The square root of x_value is assignedto sqrt_value .

data_float = CONVERT(data_int) Assigns the value of the REGISTERdata_int to the FLOAT data_float .

data_int = CONVERT(data_float) Assigns the integer part of the value ofthe FLOAT data_float to theREGISTER data_int .


36/116

Chapter 4The Circuit Monitor Programming Language 63230-300-221/A1Converting Data Types 2/2002


CMPL limits the number of different conversions that the CONVERT functioncan perform. The following table shows the conversions that are permitted:

Table 41:Permitted Data Conversions

From Data Type To Data Type

BITREG

REGISTERLONGREG

FLOAT

REGISTER

BITREGLONGREG

FLOAT

REGISTER

LONGREGBITREG

FLOAT

DATETIME

REGISTER

FLOAT

BITREGLONGREG

POWFACT

MOD10L2

MOD10L3

MOD10L4

FLOAT POWFACT

MOD10L2MOD10L4

MOD10L3

LONGREG DATETIME


37/116

63230-300-221/A1 Chapter 4The Circuit Monitor Programming Language2/2002 Control of Program Execution


CONTROL OF PROGRAM EXECUTION Custom programs use various forms of the assignment statement tocompute values and initialize data items, but other commands exist thatpermit powerful control over the specifics of program execution. It is possibleto test the values of data items and execute or not execute parts of tasksections depending on the values found. It is also possible to designate apart of a task section to be performed more than once, which can significantly

reduce the number of lines in a program.Subroutine sections, which were introduced in Chapter 2, can also help toreduce the number of lines in a program. Combining conditional executionwith subroutines provides a basis for more complex program organization.

Conditional Execution Using IF To define commands that execute only under certain conditions, use the IF command, also sometimes called the IF...ELSE command. The twoformats for the IF command (with and without the ELSE phrase) follow:

The IF command must appear as the first word on a line in a source file. Itmust be followed on that same line by a comparison (also called aconditional expression ) enclosed in parentheses. Write a comparison usingtwo data items or numeric constants joined by a comparison operator.

The comparison operators are as follows:

Other combinations of these operators, such as = > or > greater than

< > not equal to

< = less than or equal to

> = greater than or equal to


38/116

Chapter 4The Circuit Monitor Programming Language 63230-300-221/A1Control of Program Execution 2/2002


The examples below demonstrate the use of the IF statement.

Example 426:

Example 427:

Example 428:

Conditional expressions such as these are meaningless until othercommands are defined to be executed or not depending on the outcome ofthe IF comparison. Immediately following an IF command, there mustappear an opening curly brace ({) character to mark the beginning of theconditional block. The { must be on a separate line following the IF command, but it can be followed with a program instruction.

The conditional block of commands should be indented for readability, as inExample 429 . The final line of program instruction concludes with a closingcurly brace (}). This character must be the last character on a line. Customlogic commands that appear between the { and the } are performed onlywhen the condition tested by the IF command is true.

Example 429:

Any number of valid CMPL commands can appear between the { and } ofan IF command. These are all conditional commands .

An IF command can appear inside the conditional block of another IF command, creating a nested series of conditional commands. The nested IF is only tested if the outer condition is true and the conditional commands ofwhich it is a part are executed. CMPL permits IF statements to be nested upto nine layers deep .

The ELSE phrase, in the IF...ELSE format, is optional. If used, thecommand ELSE must be the first and only item on a line. It must follow a }that terminates the conditional commands associated with the IF and mustbe followed by another series of conditional commands enclosed in braces.

NOTE: Only one ELSE statement is permitted for each IF statement.

As with the conditional commands following the IF , the { must be on aseparate line following the IF command, but it can be followed with aprogram instruction. Likewise, a } must be the final item on a line, althoughit can be preceded by a program instruction . Commands between thesecharacters will be performed if the condition tested by the IF command isfalse .

IF (a_var < b_var) Tests if a_var is less than b_var

IF (b_var = 3) Tests if b_var is equal to the numeric constant 3

IF (b_var < = a_var) Tests if b_var is less than or equal to a_var

IF (b_var < > 10) If b_var does not equal 10

{a_var = a_var + 1 Increment a_var by 1

b_var = a_var * 2} And make b_var equal a_var multiplied by 2


39/116

63230-300-221/A1 Chapter 4The Circuit Monitor Programming Language2/2002 Control of Program Execution


Repeated Execution Using FOR...NEXT Use the FOR...NEXT command when a program requires repeatedexecution of a block of code or set of command lines. The format for theFOR...NEXT command is as follows:

The word FOR must be the first item other than spaces on a line. It must befollowed, on the same line, by the index variable and the expression shownabove that defines the range of values for the index variable.

The word NEXT and the name of the index variable must be the only items onthe line that marks the end of the commands to be repeated.

The index variable, which must be of data type REGISTER, will be initializedto the first numeric value given. All commands within the FOR...NEXT loopwill be executed; then the value of the index variable will be incremented by1, unless you increment or decrement the counter inside the loop. If, afterbeing incremented, the index variable does not exceed the second numericvalue given following the FOR command, the commands within the loop willbe performed again and the index variable will again be incremented.

The commands within the loop continue to be performed until the indexvariable, having been incremented by 1, exceeds the defined upper limit.Execution of the program will then continue immediately following the NEXT command line.

The FOR...NEXT loop provides a way to specify the number of times a taskis performed. The index variable can also be used within the loop to cause adifferent action on each successive repetition.

Example 430 shows a FOR...NEXT loop used in a program. This assumesthat rpt_count is a variable of data type REGISTER, that the array

wk_tble is declared to have at least 25 members, and that wk_tble andiaamps are of the same data type:

Example 430:

This example shows that the REGISTER data item used to count repetitionscan also appear in commands inside the FOR...NEXT loop. In this case,rpt_count serves as a subscript to the array wk_tble . This is a commonprocedure that places the value of iaamps in a different member of the arrayduring each repetition of the loop.

FOR ndx_var = n TO m

prog_command(s)

NEXT ndx_var

where ndx_var is an index variable of data type REGISTER

n and m are decimal constants that set the lower and upperlimits, respectively, of the index variable ( n must always belower than m )

and prog_command(s) are one or more valid programminglanguage commands to be executed once for each value ofndx_var .

FOR rpt_count = 1 TO 25 Rpt_count ranges from 1 to 25

wk_tble [rpt_count] = iamps Value of iaamps is assigned to themember of wk_tble determined byrpt_count.

NEXT rpt_count Rpt_count is incremented andcompared to 25.


40/116

Chapter 4The Circuit Monitor Programming Language 63230-300-221/A1Control of Program Execution 2/2002


No explicit command is provided to abruptly terminate a loop before the indexvariable has been incremented to exceed its defined upper limit. However, itis possible to assign a different value to the index variable during theexecution of the loop.

In Example 430 , a line could be inserted between the FOR and NEXT commands that would assign a value of 25 or more to the rpt_count variable. Execution would continue until the NEXT command incrementedrpt_count at the bottom of the loop. Since rpt_count would certainly begreater than 25, the loop would not be repeated again.

In a realistic programming application, a line setting an index variable equalto its upper limit would probably be a part of a conditional expression usingIF...ELSE .

IF...ELSE commands can appear within FOR...NEXT loops, andFOR...NEXT loops can be a part of conditional commands controlled byIF...ELSE .

FOR...NEXT loops can also be nested within other FOR...NEXT loops upto four levels deep.

Subroutine Execution Using CALL The CALL command, used with the name of a specific subroutine, causesthat subroutine to be executed. When the subroutine ends,

CMPL Instuction Bulletin.pdf

Documents

Transcript of CMPL Instuction Bulletin.pdf