Crestron SIMPL PLUS LANGUAGE REF User Manual

Download

Crestron SIMPL+

Software Language Reference Guide

This document was prepared and written by the Technical Documentation department at:

Crestron Electronics, Inc.

15 Volvo Drive

Rockleigh, NJ 07647

1-888-CRESTRON

All brand names, product names and trademarks are the property of their respective owners.

Crestron SIMPL+

Contents

SIMPL+ Language Reference Guide

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Licensing of SIMPL+ Cross Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

What's New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Software

Converting from an X-Generation to a 2-Series Target . . . . . . . . . . . . . . . . . . . . . . . . 7

X-Generation Target and 2-Series Target Differences . . . . . . . . . . . . . . . . . . . . . . . . 7

Programming Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Programming Environment Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Target Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Edit Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Insert Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Conventions Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Variable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Relative Path Names for Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Operators Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Signed vs Unsigned Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Operator Precedence & Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Numeric Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Task Switching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Task Switching for X-Generation (CNX) Control Systems . . . . . . . . . . . . . . . . . . . 22

Task Switching for 2-Series Control Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Language Constructs & Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Language Constructs & Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Compiler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

#CRESTRON_LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

#DEFAULT_NONVOLATILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Language Reference Guide - DOC. 5797G Contents z i

Software Crestron SIMPL+

#DEFAULT_VOLATILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

#DEFINE_CONSTANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

#HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

#HELP_BEGIN … #HELP_END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

#HINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

#IF_DEFINED … #ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1

#SYMBOL_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

#USER_LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

#IF_NOT_DEFINED … #ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Declarations Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Fixed and Variable Size Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

ANALOG_INPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

ANALOG_OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 8

DIGITAL_INPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

DIGITAL_OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

LONG_INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

SIGNED_INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

SIGNED_LONG_INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

STRING_INPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

STRING_OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

STRUCTURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Nonvolatile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

SendMail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

PUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Stacked Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

FOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

WHILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

CSWITCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

IF - ELSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

SWITCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

GetLastModifiedArrayIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

GetNumArrayCols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

GetNumArrayRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

SetArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

High . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Low . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

RotateLeft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

RotateRight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

RotateLeftLong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

RotateRightLong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Atol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Chr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

ItoA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

ItoHex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

LtoA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

LtoHex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

File Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

ii z Contents Language Reference Guide - DOC. 5797G

Crestron SIMPL+

File Function Return Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Reading and Writing Data to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

CheckForDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

EndFileOperations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

FileBOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

FileClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

FileDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

FileDay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

FileDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

FileEOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

FileGetDateNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

FileGetDayOfWeekNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

FileGetHourNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

FileGetMinutesNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

FileGetMonthNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

FileGetSecondsNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

FileGetYearNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

FILE_INFO Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

FileLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

FileMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

FileOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

FileRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

FileSeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

FileTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

FindClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

FindFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

FindNext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

GetCurrentDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

IsDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

IsHidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

IsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

IsSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

IsVolume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

MakeDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

ReadInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

ReadIntegerArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

ReadLongInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

ReadLongIntegerArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

ReadSignedInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

ReadSignedIntegerArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

ReadSignedLongIntegerArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

ReadString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

ReadStringArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

ReadStructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

RemoveDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

SetCurrentDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

StartFileOperations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

WaitForNewDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

WriteInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

WriteIntegerArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

WriteLongInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

WriteSignedInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

WriteSignedIntegerArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

WriteSignedLongInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Software

Language Reference Guide - DOC. 5797G Contents z iii

Software Crestron SIMPL+

WriteSignedLongIntegerArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

WriteStringArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

WriteStructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

MulDiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

SMAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

SMin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Random . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Rnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Seed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

String Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Gather . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

GetC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Lower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Mid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

REVERSEFIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

SetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Upper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

ProcessLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Pulse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

TerminateEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

GenerateUserNotice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

GenerateUserWarning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

GenerateUserError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

CheckForNVRAMDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

GETDATENUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

GETDAYOFWEEKNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

GETHOURNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

GETHSECONDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

GETMINUTESNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

GETMONTHNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

GETSECONDSNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

GETTICKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

GETYEARNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

MONTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

SETCLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

SETDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

CancelAllWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

CancelWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

PauseAllWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

PauseWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

RetimeWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Function Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

ByRef, ByVal, ReadOnlyByRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Returning a Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

iv z Contents Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Compiler Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Calling a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Function Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Example 2: 8-Level switch on a Pesa switcher . . . . . . . . . . . . . . . . . . . . . . 280

Example 3: Computing the Number of Days in a Month

(Using Functions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Example 4: Computing the Number of Days in a Month

(Using Function Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Compiler Errors and Warnings Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Syntax Errors (Compiler Errors 1000 to 1013) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Compiler Error 1000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Compiler Error 1001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Compiler Error 1002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Compiler Error 1003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Compiler Error 1004 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Compiler Error 1005 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Compiler Error 1006 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Compiler Error 1007 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Compiler Error 1008 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Compiler Error 1009 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Compiler Error 1010 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Compiler Error 1011 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Compiler Error 1012 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Compiler Error 1013 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Fatal Errors (Compiler Errors 1100 to 1101) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Compiler Error 1100 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Compiler Error 1101 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Expression Error (Compiler Errors 1200 to 1201) . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Compiler Error 1200 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Compiler Error 1201 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Declaration Errors (Compiler Errors 1300 to 1312) . . . . . . . . . . . . . . . . . . . . . . . . . 304

Compiler Error 1300 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Compiler Error 1301 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Compiler Error 1302 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Compiler Error 1303 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Compiler Error 1304 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Compiler Error 1305 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Compiler Error 1306 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Compiler Error 1307 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Compiler Error 1308 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Compiler Error 1309 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Compiler Error 1310 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Compiler Error 1311 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Compiler Error 1312 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Compiler Error 1313 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Compiler Error 1314 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Assignment Errors (Compiler Errors 1400 to 1402) . . . . . . . . . . . . . . . . . . . . . . . . . 317

Compiler Error 1400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Compiler Error 1401 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Compiler Error 1402 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Function Argument Errors (Compiler Errors 1500 to 1508) . . . . . . . . . . . . . . . . . . . 319

Compiler Error 1500 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Software

Language Reference Guide - DOC. 5797G Contents z v

Software Crestron SIMPL+

Compiler Error 1501 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Compiler Error 1502 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Compiler Error 1503 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Compiler Error 1504 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Compiler Error 1505 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Compiler Error 1506 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Compiler Error 1507 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Compiler Error 1508 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Construct Errors (Compiler Errors 1600 to 1608) . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Compiler Error 1600 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Compiler Error 1601 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Compiler Error 1602 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Compiler Error 1603 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Compiler Error 1604 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Compiler Error 1605 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Compiler Error 1606 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Compiler Error 1607 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Compiler Error 1608 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

File Errors (Compiler Errors 1700 to 1702) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Compiler Error 1700 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Compiler Error 1701 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Compiler Error 1702 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Compiler Warnings (Compiler Errors 1800 to 1803) . . . . . . . . . . . . . . . . . . . . . . . . 333

Compiler Warning 1800 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Compiler Warning 1801 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Compiler Warning 1802 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Compiler Warning 1803 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

SIMPL+ Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Obsolete Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

System Interfacing - Cresnet and CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

GetCIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

GetCresnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

GetSlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

IsSignalDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

SendCresnetPacket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

SendPacketToCPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

SetCIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

SetCresnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

SetSlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

#ANALOG_OUTPUT_JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

#DIGITAL_INPUT_JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

#DIGITAL_OUTPUT_JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

#STRING_INPUT_JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

#STRING_OUTPUT_JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

CEN-OEM-Specific Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

_OEM_BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

_OEM_CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

_OEM_CTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

_OEM_DTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

_OEM_LONG_BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

_OEM_MAX_STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

_OEM_PACING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

vi z Contents Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .357

Software License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Return and Warranty Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

_OEM_RTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

_OEM_STR_IN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

_OEM_STR_OUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Software

Language Reference Guide - DOC. 5797G Contents z vii

Software Crestron SIMPL+

This page intentionally left blank.

viii z Contents Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Introduction

SIMPL+® is a language extension that enhances SIMPL Windows by using a procedural “C-like” language to code elements of the program that were difficult, or impossible, with SIMPL alone. This help system provides specific information about the SIMPL+ language syntax, and can be used as a reference manual.

For a tutorial on SIMPL+ programming, consult the SIMPL+ Programming Guide (Doc. 5789). The latest version of the guide can be obtained from the Downloads | Product Manuals section of the Crestron website (www.crestron.com).

Software

Software Requirements

SIMPL+ has several versions. Earlier versions of SIMPL+ do not contain features and constructs found in later revisions. Each version of SIMPL+ requires a minimum revisions of SIMPL Windows and Control System Update (UPZ or, for 2-Series control systems, CUZ) files. The specifications are listed below.

Software Requirements

SIMPL+ VERSION MINIMUM SIMPL WINDOWS REQUIRED MINIMUM UPZ MINIMUM CUZ

Version 1.00 1.30.01 5.04.11 N/A Version 2.00 1.40.02 5.10.00 N/A Version 3.00 2.00 N/A 1.00

Language Reference Guide - DOC. 5797G SIMPL+® z 1

Software Crestron SIMPL+

Licensing of SIMPL+ Cross Compiler

Crestron SIMPL+ Cross-Compiler Version 1.1 is simply an Installshield-installed version of the Coldfire GNU C Compiler, which is available on Crestron's FTP site in the SIMPL Windows directory as directory GNUSOURCE in ftp:// ftp.crestron.com/Simpl_Windows and in the \GNUSource directory of the Programming Tools CD.

It includes and references code that is available from www.cygwin.com/cvs.html Some files are deleted by the Installshield procedure which are not necessary for general use of the C compiler, in order to

save space on user PCs. But it is an unmodified version of this code. The original executables and the source code for them can be obtained from the authors at the above sites

The source code has also been gathered underneath a single directory for your convenience and is available on Crestron's FTP site in the SIMPL Windows directory as directory GNUSOURCE in ftp://ftp.crestron.com/Simpl_Windows and in the \GNUSource directory of the Programming Tools CD. They also include GNU utilities, which are copyrighted by the Free Software Foundation.

Other Crestron software simply executes this code as a separate executable, and does not incorporate GNU source code into Crestron software. Crestron's standard licensing agreement does not apply to this software; only the license described here applies.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Refer to the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (it is appended to this document for your convenience); if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

The text for the license agreement below is also available from www.gnu.org/copyleft/gpl.html GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

PREAMBLE The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU

General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

2 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

Software

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The “Program”, below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modification”.) Each licensee is addressed as “you”.

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program

Language Reference Guide - DOC. 5797G SIMPL+® z 3

Software Crestron SIMPL+

itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensee is extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this Licens e .

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) wi th the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not

4 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

Software

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

Language Reference Guide - DOC. 5797G SIMPL+® z 5

Software Crestron SIMPL+

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software that everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

One line to give the program's name and an idea of what it does. Copyright (C) yyyy name of author This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License

as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied

warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Refer to the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA

02111-1307, USA. Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) year name of author

Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' written by James Hacker. signature of Ty Coon, 1 April 2002 Ty Coon, Vice President This General Public License does not permit incorporating your program into proprietary programs. If your program is a

subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

FSF & GNU inquiries & questions to gnu@gnu.org.

6 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

What's New

Converting from an X-Generation to a 2-Series Target

Select 2-Series Target within SIMPL+ environment (From the SIMPL+

•

application menu, select Build | 2-Series Control System Target. The XGeneration Target may be deselected if no longer needed).

Recompile the SIMPL+ program.

•

X-Generation Target and 2-Series Target Differences

I/O Datatypes (DIGITAL_INPUT, etc.) can no longer be passed to functions as

•

arguments. Global variables can no longer be declared within User or Crestron Libraries.

•

If TerminateEvent resides within a Wait Statement Block, it will only exit the

•

Wait Statement Block's function scope - NOT the PUSH, CHANGE, RELEASE or EVENT in which it resides.

The following functions are no longer available in the 2-Series Control System:

GetCIP() SetCIP() GetCresnet() SetCresnet() GetSlot() SetSlot() _OEM functions #ANALOG_INPUT_JOIN #ANALOG_OUTPUT_JOIN #DIGITAL_INPUT_JOIN #DIGITAL_OUTPUT_JOIN #STRING_INPUT_JOIN #STRING_OUTPUT_JOIN

Language Reference Guide - DOC. 5797G SIMPL+® z 7

Software Crestron SIMPL+

Programming Environment

Programming Environment Overview

While running SIMPL Windows, select File | New SIMPL+ and the SIMPL+ programming environment appears. This section describes the environment for SIMPL+ Version 3.00.

The SIMPL+ Module Information template is filled with commented code that makes it easy to remember the language syntax and structure. Simply locate the necessary lines, uncomment them, and add the appropriate code. To uncomment a line of code, either remove the “//” that appears at the start of the line or remove the multi-line comment indicators /*…*/.

Target Selection

Target Selection Pulldown Menu

X Generation (CNX) Control Systems consist of the CEN-TVAV, CNMSX-AV/ PRO, and CNRACKX/-DP.

The 2-Series Control Systems currently consist of the AV2, CP2, CP2E, PAC2, PAC2M, PRO2, and RACK2.

Selecting a target implies that the module MUST work for that target and any statements that are not valid for that target are NOT permitted. It does NOT mean that the module won't work for other targets - it may, if it were compiled for other targets at some future time. More functions and support are available for 2-Series systems, so do not limit yourself to the X-Generation usages, if they are not needed.

8 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

NOTE: In previous versions of SIMPL+, the settings for the target types were system-wide. Those settings applied to all SIMPL+ modules that were opened and not specific to the active module being edited. In version 3.00, the target type setting is specific only to the active module being edited and saved within that module. The toolbar buttons reflect the target type of the active module within the SIMPL+ environment.

One or both targets may be selected to compile the program for both types of control systems. When compiling a program for a specific type of control system, an error message appears if a wrong control system target is selected that does not support a particular function or syntax.. Shown below are the two target selection buttons of the menu toolbar.

Toolbar Target Selection Buttons.

Software

X-GEN - shortcut to Build | X-Generation Control Systems Target 2 - shortcut to Build | 2-Series Control Systems Target. (This is the default setting upon opening

SIMPL+.)

NOTE: If a program is compiled for the wrong type of control system, an error message appears when attempting to upload, and the program must be recompiled.

Edit Preferences

Preferences Toolbar Pull-Down Me nu

Language Reference Guide - DOC. 5797G SIMPL+® z 9

Software Crestron SIMPL+

Text Editor Tab

Font - Used to select font to be used in SIMPL+ Text Editor's main window. Cursor Positioning, Auto-Indent - When the 'enter' key is pressed, the cursor will

automatically indent to the same initial tab position as in the current line.

To manually indent a block of text, highlight the block and press TAB.

•

To manually outdent a block of text, highlight the block and press

•

SHIFT and TAB.

If you have manually inserted spaces for tabs, then pressing SHIFT

•

TAB will only outdent by only one space.

Cursor Positioning, Allow cursor positioning past end of line - If checked, the

cursor will be allowed to be placed anywhere within the text editor. This includes any white-space area. Disabling this option will force the cursor to the end of the current line selected when the cursor is clicked on any white-space past the end of the line.

Tab Size - The number of spaces that equal 1 tab character. Insert Spaces for tabs - Spaces will be inserted in place of the tab character.

10 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Target Devices Tab

Software

Execute SIMPL+ Cross Compiler - After target files are compiled, the cross compiler can be launched from the SIMPL+ environment. This will enable you to generate the target file that will be uploaded to the operating system. Normally, the SIMPL Windows environment will handle this, since it is responsible for uploading the target file to the operating system.

Display Compile Warnings - When selected, the compiler displays all program warnings during compile in the compile output window. The total number of warnings will always be displayed whether this option is selected or not.

Insert Category

Displays a list of all available categories for the symbol tree in the SIMPL Windows environment. This list is for reference only.

To specify a category for a SIMPL+ module, the #CATEGORY directive must be used with a category specified in this list. If a category name is typed in that does not exist in the Symbol Tree Category list, the SIMPL+ module will default to the category type, Miscellaneous.

Symbol Tree Category List in SIMPL Windows

Language Reference Guide - DOC. 5797G SIMPL+® z 11

Software Crestron SIMPL+

Insert #CATEGORY Toolbar Pull-Down Menu in SIMPL+

Symbol Tree Category Pop-Up Window

12 z SIMPL+

Category Selection Insertion Box

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

General Information

Conventions Used

Variable names are placed in <> when discussing syntax. For example, PUSH <variable>.

Optional parameters are placed in [ ]. For example, when a list has many parameters, it would be described as <var1>[, <var2>...] When discussing array notation, [ ] is used for array subscripting and is not used to mark optional code.

Examples are placed in a Computer Style font, i.e.,

MyVariable = ATOI(SomeOtherVariable);

Software

Variable Names

Variable names in SIMPL+ may be up to 30 characters long and may not contain any of the operators specified in the “Operators” section. Valid characters in a variable name are a-z, A-Z, 0-9, #, _, and $ but may not begin with 0-9.

Variable names may not duplicate existing function or keyword names. Variable names in SIMPL+ are not case sensitive. For example, declaring a variable

“joe” can be used as “jOe” or “JOE” or any variation of case.

NOTE: Version 3.00.12 users: variable names may be 120 characters for 2-Series systems.

Comments

It is beneficial to comment code to make it more readable and for documentation. Comments do not exist in any form after code generation and are not required.

SIMPL+ has two styles of comments, single line and block comments. Single line comments start with the characters //. The rest of the line (until a carriage return) is considered a comment. If they occur within a quoted string, such as in PRINT, they are NOT treated as comment characters, but rather as two backslash (Hex 2F) characters.

Examples:

PRINT(“Hello, World!\n”); // This stuff is a comment. PRINT(“hello, // world!\n”); // This stuff is a comment, // but the string actually

Language Reference Guide - DOC. 5797G SIMPL+® z 13

Software Crestron SIMPL+

// printed is hello, // world.

The second form of comment characters are the block comments. /* starts a block comment and */ ends a block comment. This is useful for commenting out large sections of code or writing large sections of documentation. Note that nested comments are not supported. Also, if /* or */ appear inside of a quoted string such as in an PRINT statement, they are not considered comments but part of the string.

Examples:

/* This is all a comment! */ PUSH Trig { // code that does something. }

Relative Path Names for Files

Your current working directory is reset to the default (“\” or root) whenever “StartFileOperations” is performed. It is changed only by “SetCurrentDirectory”.

File names can consist of full path names or relative path names.

Full path names have the same restrictions as DOS file names in

•

characters and format, with a maximum length of 256 characters.

Relative path names do not begin with a “\” and start from the current

•

working directory.

14 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Operators

Operators Overview

SIMPL+ operators perform functions between two or more variables. SIMPL+ operators consist of Arithmetic, Bitwise, and Rational Operators.

Arithmetic Operators

OPERATOR NAME EXA MPLE EXPLANATION

- Negation -X Negate the value of X (2’s Complement of X). * Multiplication X *Y Multiply X by Y (signed arithmetic). / Unsigned Division X / Y Divide X by Y, truncates result (unsigned arithmetic). S/ Signed Division X S/ Y Divide X by Y, truncates result (signed arithmetic). MOD Signed Modulo X MOD Y Remainder after dividing X by Y (signed arithmetic). UMOD Unsigned Modulo X UMOD Y Remainder after dividing X by Y (unsigned arithmetic).

Only 2-Series Systems.

+ Addition X + Y Add the value of Y to X.

- Subtraction X - Y Subtract the value of Y from X.

Bitwise Operators

OPERATOR NAME EXAMPLE EXPLANATION

<< Shift Left X << Y Shift X to the left by Y bits; 0 is Shifted in. >> Shift Right X >> Y Shift X to the right by Y bits; 0 is Shifted in. {{ Rotate Left X {{ Y Rotate X to the left by Y bits; full 16 bits used. Same as

RotateLeft().

}} Rotate Right X }} Y Rotate X to the right by Y bits; full 16 bits used. Same as

RotateRight(). NOT 1's Complement NOT(X) Change 0 bits to 1, 1 bits to 0. & Bitwise AND X & Y AND the bits of X with the bits of Y. | Bitwise OR X | Y OR the bits of X with the bits of Y. ^ Bitwise XOR X ^ Y XOR the bits of X with the bits of Y.

NOTE: For the Shift and Rotate operators, only the lower 5-bits of Y are used, giving values of Y ranging from 0 to 31. For example, if Y=600, the lower 5-bits equate to

24. Rotating a 16-bit number through 16 positions gives the original number back. Therefore, for rotating 24, the result is equivalent to rotating through 8. Shifting greater than 16 will always give a 0 as a result.

Language Reference Guide - DOC. 5797G SIMPL+® z 15

Software Crestron SIMPL+

Relational Operators

OPERATOR NAME EXAMPLE EXPLANATION

= Comparison X = Y True if X is equal to Y, False otherwise. = Assignment X = Y Assigns the contents in Y to X. The assignment

operator cannot be used within expressions.

! Complement ! X If X = 0, X changes to 1. If X is different from 0,

evaluates to 0. <> Not Equal To X <> Y X is not equal to Y. < Unsigned Less Than X < Y X is less than Y (unsigned). > Unsigned Greater X > Y X is greater than Y (unsigned). <= Unsigned Less Than or Equal X <= Y X is less or equal to Y (unsigned). >= Unsigned Greater Than or Equal X >= Y X is greater or equal to Y (unsigned). S< Signed Less Than X S< Y X is less than Y (signed). S> Signed Greater Than X S> Y X is greater than Y (signed). S<= Signed Less Than or Equal X S<= Y X is less or equal to Y (signed). S>= Signed Greater Than or Equal X S>= Y X is greater or equal to Y (signed). && Logical AND X && Y True if X and Y are both non-zero. False

otherwise. || Logical OR X || Y True if either X or Y is non-zero. False otherwise.

All of the above operators, with the exception of the negation (-), NOT, and complement (!) operators, are called binary operators. Binary operators take two values, perform an operation, and return a third value as a result. For example, 5 + 6 would return the value of 11. The arguments for a given operator are called its operands. In the above example, the + sign is the operator and 5 and 6 are the operands.

The negation, NOT, and complement operators are called unary operators, which means it takes a single number and performs an operation. In this case, the negation operator performs a negate, or 2's complement. A 2's complement takes a 16-bit number, bitwise inverts it, and adds 1. The operand in a negation is the value being negated. Operands do not have to be simple numbers. They may also be variables or the results of a function call. For example, in the expression -X, the - sign is the operator and the variable X is the operand.

16 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

String Operators

OPERATOR NAME EXAMPLE EXPLANATION

= Assignment* A$ = B$ Assigns the value in B$ to A$. *NOTE: Not allowed in expressions because of possible confusion with comparison . = Comparison A$ = B$ A$ equal B$ <> Not Equal To A$ <> B$ A$ is not equal to B$ < Less Than A$ < B$ A$ is less than B$ > Greater Than A$ > B$ A$ is greater than B$

For less than and greater than operations, the string is evaluated in ASCII order. For example, the comparison “ABC” > “ABD” would be false. The system looks character by character; the first two characters are identical in both strings, and when it evaluated the characters C (ASCII 67) vs. D (ASCII 68), the result is false. The comparison “ABC”<“ABCD” is true because a shorter string alphabetically precedes one that is identical but longer.

Software

Language Reference Guide - DOC. 5797G SIMPL+® z 17

Software Crestron SIMPL+

Signed vs Unsigned Arithmetic

ANALOG_INPUT, ANALOG_OUTPUTs, and INTEGER in SIMPL+ are 16-bit quantities. A 16-bit quantity can range from 0 - 65535 when it is treated without having a sign (positive or negative). If a 16-bit number is treated as signed in SIMPL+, the range becomes -32768 to 32767. The range from -32768 to -1 maps into 32768 to 65535. Expressed mathematically, the mapping is 65536 AbsoluteValue(Number). The values are treated differently depending on whether signed or unsigned comparisons are used. Another way is as follows.

Signed 0 - 32767 32768 - 65535 Unsigned 0 - 32767 -32768 - -1

Assignments may be directly done with negative constants, for example:

INTEGER I, J; I = -1; J = 65535;

Results in I being equivalent to J.

Example:

IF (65535 S> 0) X=0; ELSE X=1;

Above, the value of X is set to 1 since in signed arithmetic, 65535 is the same as -1, which is not greater than 0.

IF (65535 > 0) X=0; ELSE X=1;

Above, the value of X is set to 0 since in unsigned arithmetic, 65535 is greater than 0.

18 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Datatype Conversions

Software

SOURCE DESTINATION ACTION

INTEGER LONG_INTEGER Lower 2 bytes of destination = source.

Upper 2 bytes cleared.

INTEGER SIGNED_INTEGER The 2 bytes of source moved to destination.

2 byte number now treated as signed.

INTEGER SIGNED_LONG_INTEGER Lower 2 bytes of destination = source.

Upper 2 bytes cleared.

LONG_INTEGER INTEGER Lower 2 bytes of source moved to destination,

treated as unsigned.

LONG_INTEGER SIGNED_INTEGER Lower 2 bytes of source moved to destinatio n,

treated as signed.

LONG_INTEGER SIGNED_LONG_INTEGER The 4 bytes of destination = source, now treated as

signed. SIGNED_LONG_INTEGER INTEGER Lower 2 bytes of source moved to destination. SIGNED_LONG_INTEGER SIGNED_INTEGER Lower 2 bytes of source moved to destination. SIGNED_LONG_INTEGER LONG_INTEGER The 4 bytes of destination = source, now treated as

unsigned. SIGNED_INTEGER INTEGER Lower 2 bytes of source moved to destination, 2 byte

number now treated as unsigned. SIGNED_INTEGER LONG_INTEGER 2 byte source is sign extended to 4 bytes SIGNED_INTEGER SIGNED_LONG_INTEGER 2 byte source is sign extended to 4 bytes

Language Reference Guide - DOC. 5797G SIMPL+® z 19

Software Crestron SIMPL+

Operator Precedence & Grouping

In an expression where many operators are present, some operators have “priority” over others. Operators with the same precedence level are evaluated strictly left to right. Grouping is used to change the way an expression is evaluated.

Operator Precedence & Grouping

PRECEDENCE LEVEL OPERATORS

1 - (Negate) 2 ! NOT 3* / S/ MOD 4 + 5{{ }} 6 << >> 7 > < >= <= S> S> S>= S<= 8 = <> 9& 10 ^ 11 | 12 && 13 ||

As an example, the expression:

3+5*6

Evaluates to 33 since the multiplication is performed first. It may be beneficial to use grouping to show which operations are performed first. Grouping is simply starting an expression with '(' and ending with ')'. Therefore, the expression 3+5*6 is equivalent to 3+(5*6). Grouping is very important if you want to override the default behavior and have one piece of the expression evaluated first. Therefore, to make sure the + is evaluated first, the expression is written as (3+5)*6, for a result of 48.

20 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Numeric Formats

Numeric (Integer) constants may be expressed in three formats; decimal, hexadecimal, or quoted character.

Decimal constants are specified by writing a decimal number. Hexadecimal constants are specified by prefacing the hex constant by 0x. Quoted character constants are a single character placed between single quotes (') and have the numeric value specified on an ASCII chart.

Example:

INTEGER I; I=123; // Specify Decimal constant. I=0xABC; // Specify a Hexadecimal constant (Decimal value

2748) I='A'; // Specify a character constant (Decimal value 65) INTEGER K; K=54; // Specify Decimal constant K=0x36; // Specify a Hexadecimal Constant (Decimal // Value 54) K='6'; // All three of these are the same value // (Decimal value 54)

The three forms may be used interchangeably and are used to make code more readable.

Example:

STRING A$[10], B$[10], C$[10]; INTEGER I; BUFFER_INPUT COM_IN$[50]; // A$, B$, and C$ contain identical values // after these lines run. A$=CHR('A'); B$=CHR(65); C$=CHR(0x41); // Preserve the lower nibble of a word, mask the rest out. I = VAL1 & 0x000F; // Read until a comma is detected in the stream. DO { I = GetC(COM_IN$) } UNTIL (I = ',');

Language Reference Guide - DOC. 5797G SIMPL+® z 21

Software Crestron SIMPL+

Task Switching

Task Switching for X-Generation (CNX) Control Systems

Each SIMPL+ module runs as a separate task in the X-Generation (CEN-TVAV, CNMSX-AV/PRO, CNRACKX/-DP) Control System. In order to insure that no SIMPL+ program takes up too much time, each task is allotted a certain amount of time to run. If the task exceeds this time limit, the system will switch out and allow other tasks (including the SIMPL program) to run.

The system will not arbitrarily switch out at any point in time. Even if the task limit is exceeded, the system will force a task switch only at predetermined points.

The system will perform a task switch when a PROCESSLOGIC, DELAY, or PULSE function is encountered. When a task switch is performed, the output I/O definitions are updated (refer to ANALOG_OUTPUT, DIGITAL_OUTPUT, STRING_OUTPUT for further information). Note that a WAIT does not cause a task switch.

When a WHILE, DO-UNTIL, or FOR construct encounters its last statement, or any construct that causes a “backwards branch”, the system checks to see if a timeout has occurred. If the timeout has occurred, then the system will task switch away. When the module is given time to run, it will resume at the top of the construct.

For this reason, a designer of a SIMPL+ module should take care to design with this in mind. A particular concern is if the outputs need to be updated in a specific fashion and have a loop, which may potentially cause the system to switch away. One solution would be to store the output variables in intermediate arrays or variables, and assign the intermediate variables to the output variables before the event terminates.

Example:

DIGITAL_INPUT trig; ANALOG_OUTPUT i; INTEGER j; PUSH trig { j=0; FOR(j=0 to 32000) { i = j; } }

22 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

A SIMPL program drives the trig signal and monitors the state of the analog_output with an ANALOG DEBUGGER (Speedkey: TEST2) symbol. If the system did not task switch out, the only TEST2 output would show 32000. If this program were run, there would be many outputs, indicating each time the FOR loop exceeded the allotted time, the SIMPL program would be given time to run and the TEST2 symbol would post the results.

If it were critical that the analog_output were only updated with the final value, the following alternative solution could be used:

DIGITAL_INPUT trig; ANALOG_OUTPUT i; INTEGER j, q; PUSH trig { j=0; FOR(j=0 to 32000) { q = j; } i = q; }

This program output would only show the final result; the TEST2 would be triggered once with the value 32000. The system will still perform whatever task switching it requires.

When an event has task switched away, it is possible that the event may be retriggered and a new copy of the event will start running. Therefore, SIMPL+ events are considered to be re-entrant. The event may be reentered only a limited number of times before an Rstack overflow error occurs (refer to “Common Runtime Errors” that begins on page 302). In order to prevent the event from running multiple times, consider the following example:

DIGITAL_INPUT trig; INTEGER I; PUSH trig { FOR(I = 0 TO 32000) { // code } }

This code will task switch away at some point in the FOR loop. If trig is hit again while the event is task switched out, a new copy will run. This code can be changed to prevent multiple copies from running.

DIGITAL_INPUT trig; INTEGER I, Running; PUSH trig { IF(!Running)

Language Reference Guide - DOC. 5797G SIMPL+® z 23

Software Crestron SIMPL+

{ Running = 1; FOR(I = 0 TO 32000) { // code } Running = 0; } } FUNCTION MAIN() { Running = 0; }

In this case, a new variable, Running is declared and set to 0 on system startup in the MAIN. When the event is triggered, if Running is 0, then it will be set to 1, and the FOR loop will execute. Assume now the event has a task switch. If trig is hit again, the event will start, but will immediately exit because IF statement evaluates to false. When the task resumes, and ultimately completes, Running will be set to 0 again so the bulk of the function may execute again.

NOTE: The event is STILL reentering. It is being forced to terminate immediately and prevent reentry more than one level deep.

24 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Task Switching for 2-Series Control Systems

In the 2-Series Control Systems, each SIMPL+ module also runs as one or more concurrent tasks in the control system. The MAIN and each event handler run as separate tasks sharing a common global data space.

To insure that no SIMPL+ program takes too much time, each task is allotted a certain amount of time to run. If the task exceeds this time limit, the system will switch out and allow other tasks (including the SIMPL program) to run. It should also be noted that the task would run until it has completed the operation, the allotted time expires or a task switching call is executed.

Unlike the X-Generation systems, the system will arbitrarily switch out at any point in time. If this may result in undesirable behavior, then the programmer should control his task switching by issuing a PROCESSLOGIC function.

The system will perform a task switch when a PROCESSLOGIC or DELAY function is encountered. The PULSE will no longer cause a task switch because it is no longer needed for the logic processor to process the digital output pulse. Note that a WAIT does not cause a task switch but will execute in its own task.

All outputs are processed by the logic processor as soon as assigned. As soon as the SIMPL+ module releases the processor, all the outputs are seen by the logic processor. Also, the programmer can read back DIGITAL_OUTPUTS and ANALOG_OUTPUTS without having to insert a PROCESSLOGIC in between.

To use the example from the Task Switching for X-Generation Control System discussion:

DIGITAL_INPUT trig; ANALOG_OUTPUT i; ANALOG_OUTPUT NewNumber; INTEGER j; PUSH trig { j=0; NewNumber = 1234; j = NewNumber; //j = 1234, not old value of NewNumber FOR(j=0 to 32000) { i = j; } }

A SIMPL program drives the trig signal and monitors the state of ANALOG_OUTPUT with an ANALOG DEBUGGER (Speedkey: TEST2) symbol. The TEST2 output would show all numbers from 0 to 32000. If it were critical that the ANALOG_OUTPUT were only updated with the final value, the following alternative solution could be used:

DIGITAL_INPUT trig; ANALOG_OUTPUT i; INTEGER j, q;

Software

Language Reference Guide - DOC. 5797G SIMPL+® z 25

Software Crestron SIMPL+

PUSH trig { j=0; FOR(j=0 to 32000) { q = j; } i = q; }

This program output would only show the final result; the TEST2 would be triggered once with the value 32000. The system will still perform whatever task switching required. As with the X-Generation series, re-entrance can still be a problem. When an event has task switched away, the event may be retriggered and a new copy of the event will start running. Therefore, SIMPL+ events are considered to be re-entrant. The amount of times that this could occur is dependent upon the available memory in the system. In order to prevent the event from running multiple times, refer to the reentrant example in the X-Generation task switching section.

The programmer should exercise caution when using looping constructs without constraints (i.e. while(1) ) or depend upon outside influence. Because each event will run for the allotted time unless specified otherwise, PROCESSLOGIC calls should be used to reduce the CPU overhead. Consider the following:

DIGITAL_INPUT diInput1, diInput2; INTEGER I, LastNumSeconds; PUSH diInput1 { WHILE (diInput1) { // do something } } main() { LastNumSeconds = 0; WHILE (1) { seconds = GetNumSeconds(); IF (seconds <> LastNumSeconds) { // do something } } }

At the loop in MAIN, the programmer wants to perform an operation every second. This code will achieve that goal. However, a side effect of the code is that every time the task is scheduled to run, it will si t in a very tight loop checking for a change in the

26 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

number of seconds. Since the allotted time for a SIMPL+ task to run is in fractions of a second, it is very unlikely to change during the allotted time. Unless the programmer puts in a DELAY which will put the task to “sleep” for a period of time, this task will dominate the CPU time.

The programmer who writes the MAIN() function should also be aware that the MAIN() function begins running when the SIMPL Windows program is initializing. The module’s inputs do not have their programmed state until sometime after the first break in the program execution due either to a process logic statement or expiration of a time slice.

The PUSH event indicates a more subtle problem. The programmer wants to loop in the event until the input diInput1 is released. Once the task containing the event is started, it will run for its allotted time and no other inputs will change. If the signal attached to the diInput1 signal goes low, the event will not see to the change until the event switches out and the diInput1 low signal is processed.

The following is an alternative:

DIGITAL_INPUT diInput1, diInput2; INTEGER I, LastNumSeconds; PUSH diInput1 { WHILE (diInput1) { // do something

ProcessLogic(); } } MAIN() { LastNumSeconds = 0; WHILE (1) { seconds = GetNumSeconds(); IF (seconds <> LastNumSeconds) { // do something } delay(10); } }

Here, a 100ms delay is put in the MAIN loop. That means that the task will only wake up 10-times per second. It will still catch the change of the seconds to within a 1/10 of a second and lessen system requirements.

The PROCESSLOGIC call in the PUSH event handler will immediately cause a task switch to be performed. This will allow a low transition on the diInput1 signal to be seen immediately, making the system more responsive.

Language Reference Guide - DOC. 5797G SIMPL+® z 27

Software Crestron SIMPL+

One more operational difference between the X-Generation and 2-Series control systems is the event interaction. For example:

DIGITAL_INPUT diEvent1, diEvent2; PUSH diEvent1 { PRINT(“Starting Event 1\n”); DELAY(500); // 5 sec delay PRINT (“Event 1 done\n”); } PUSH diEvent2 { PRINT (“Starting Event 2\n”); DELAY (1500); // 15 sec delay PRINT (“Event 2 done\n”); }

The output from the X-Generation system would be:

Starting Event 1 Starting Event 2 Event 2 Done Event 1 Done

The order dictates that the second delay (15 seconds) will hold off the first delay. As soon as the second delay has finished, the first delay is checked. Therefore, the two events complete at approximately the same time (15 seconds).

The output from the 2-Series system would be:

Starting Event 1 Starting Event 2 Event 1 Done Event 2 Done

The events run independently. When the 5-seconds expires for the first delay, the first event continues and prints its message. The second delay expires 10 seconds later and the message is displayed.

28 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Language Constructs & Functions

Language Constructs & Functions Overview

Functions take one or more comma-separated parameters and return a result. The following template shows how each language construct and function is explained.

Name:

The name used to refer to the construct or function.

Syntax:

The SIMPL+ specific language requirements for this particular construct or function. This section demonstrates exactly how to enter the statement in a SIMPL+ program.

For completeness, the general syntax for SIMPL+ functions is shown below:

<Return Value Type> FunctionName(<Parameter 1 Type> [,

<Parameter 2 Type> ...]);

The Types are described as STRING, INTEGER, LONG_INTEGER, SIGNED_INTEGER, and SIGNED_LONG_INTEGER.

If a STRING is specified as a return type, a STRING or STRING_OUTPUT variable may be used.

If an INTEGER or LONG_INTEGER is specified as a return type, an INTEGER, LONG_INTEGER, ANALOG_OUTPUT or DIGITAL_OUTPUT may be used.

If a STRING is specified as a parameter, a STRING, STRING_INPUT, BUFFER_INPUT or literal string (i.e. “Hello””) may be used.

If an INTEGER, LONG_INTEGER, SIGNED_INTEGER or SIGNED_LONG_INTEGER is specified as a parameter, an INTEGER, LONG_INTEGER, ANALOG_INPUT, ANALOG_OUTPUT, DIGITAL_INPUT or DIGITAL_OUTPUT may be used. A literal integer (i.e. 100) may also be used. Note that for DIGITAL_OUTPUT values, a value of 0 is equivalent to digital low, and any other value is a digital high.

Description:

General overview of what this function does.

Parameters (applies to functions only):

Specifics on each of the parameters listed.

Language Reference Guide - DOC. 5797G SIMPL+® z 29

Software Crestron SIMPL+

Return Value (applies to functions only):

Values placed in the return variable include error conditions. Error conditions are results that occur if one or more of the input values does not have values that are legal for that function.

Example:

A code example of how this function is typically used.

Version:

The version of SIMPL+ in which the construct or function was made available and any revision notes about differences between various versions of SIMPL+. All constructs and functions are available in all subsequent versions except where noted.

Control System:

The control system platform for which the function is valid. Unless specified, the construct or function is valid for both X-Generation (e.g., CEN-TVAV, CNMSXAV/PRO, CNRACKX/-DP) and 2-Series control systems. SIMPL+ is not available in the control systems preceding the X generation - CNMS, CNRACK/-D/-DP, CNLCOMP/-232, and ST-CP.

30 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Arrays

Various one and two dimensional arrays are supported. All input and output arrays are 1-based, meaning that the first element has index 1, not 0. Internal variables are 0-based, meaning that the first element has index 0. In both cases, the index of the last element is the same as the dimension of the array.

Do not confuse the declaration of the length of STRINGs with the declaration of arrays. E.g. STRING s$[32] is a single string of length 32, and STRING ManyS$[10][32] is an array of 11 strings of length 32 each. You must use the BYTE function to access the character at a particular position in a string, but you can use the array index to access a particular string in an array of strings. Positions in a string are 1-based. Refer to the discussion of Minimum Size Arrays in Declaration Overview on page 45.

One dimensional arrays of the following types are supported:

Software

DIGITAL_INPUT DIGITAL_OUTPUT ANALOG_INPUT ANALOG_OUTPUT STRING_OUTPUT BUFFER_OUTPUT STRUCTURES

One dimensional arrays of strings are also supported, although since the declaration also contains a string length, it looks like a 2-dimensional array:

STRING_INPUT BUFFER_INPUT STRING

One and two dimensional arrays of the following types are supported:

INTEGER LONG_INTEGER SIGNED_INTEGER SIGNED_LONG_INTEGER

Language Reference Guide - DOC. 5797G SIMPL+® z 31

Software Crestron SIMPL+

Declaration Examples:

DECLARATION MEANING

DIGITAL_INPUT in[10]; 10 digital inputs, in[1] to in[10] INTEGER MyArray[10][20]; 11 rows by 21 columns of data, from

MyArray[0][0] to MyArray[10][20]

STRING PhoneNumbers[100][32]; 101 strings that are a maximum of 32

characters long, e.g. PhoneNumbers[0] to PhoneNumbers[100]

STRING_INPUT in$[32]; One input string called in$ that is 32 characters

long.

STRING_OUTPUT out$[10]; Ten output strings, out$1 to out$[10]. Their

length does not have to be specified.

STRING_INPUT in$[5][32]; Five input strings, in$[1] to in$[5] that are 32

characters long.

<struct_type> myStruct[10]; 11 structure elements from myStruct[0] to

myStruct[10].

32 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Compiler Directives

Compiler Directives Overview

Compiler directives are used by the SIMPL+ compiler to control attributes of the symbol without generating the actual SIMPL+ code.

#CATEGORY

Name:

#CATEGORY

Syntax:

#CATEGORY “<category ID>”

Description:

Software

A Category is the name of the folder in the Logic Symbols library tree where the module is shown. To specify a category for a SIMPL+ module, the #CATEGORY directive must be used with a category specified in the list shown in the SIMPL+ Editor. Just click "Edit" then "Insert Category" for a list of categories. Choose one and the appropriate line of code is added to your SIMPL+ program.

Example:

#CATEGORY “6” // Lighting

If a category ID does not exist in the Symbol Tree Category list, the SIMPL+ module will default to the Miscellaneous category type.

Version:

SIMPL+ Version 3.00

Control System:

2-Series only

Language Reference Guide - DOC. 5797G SIMPL+® z 33

Software Crestron SIMPL+

#CRESTRON_LIBRARY

Name:

#CRESTRON_LIBRARY

Syntax:

#CRESTRON_LIBRARY “<Crestron Library Name>”

Description:

Directs the compiler to include code from a Crestron provi ded li brary. The modul e name specified is the Crestron Library Filename without the CSL extension.

Example:

#CRESTRON_LIBRARY “Special Integer Functions”

Directs the compiler to include the Crestron Library “Special Integer Functions.CSL” from the Crestron SIMPL+ Archive.

Version:

SIMPL+ Version 3.00 - Global variables can no longer be declared within Crestron Library (.csl) files.

SIMPL+ Version 2.00

34 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

#DEFAULT_NONVOLATILE

Name:

#DEFAULT_NONVOLATILE

Syntax:

#DEFAULT_NONVOLATILE

Description:

Program variables retain their value if hardware power is lost. The compiler will default all variables declared within the SIMPL+ module as nonvolatile. Individual variables can use the Volatile keyword to override this default. See also #DEFAULT_VOLATILE on page 36.

Example:

#DEFAULT_NONVOLATILE

Version:

SIMPL+ Version 3.00

Control System:

2-Series only

Language Reference Guide - DOC. 5797G SIMPL+® z 35

Software Crestron SIMPL+

#DEFAULT_VOLATILE

Name:

#DEFAULT_VOLATILE

Syntax:

#DEFAULT_VOLATILE

Description:

Program variables will not retain their value if hardware power is lost. The compiler will default all variables declared within the SIMPL+ module as volatile. Individual variables can use the Nonvolatile keyword to override this default. See also #DEFAULT_NONVOLATILE on page 35.

Example:

#DEFAULT_VOLATILE

Version:

SIMPL+ Version 3.00

Control System:

2-Series only. On an X-generation system, all variables are non-volatile.

36 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

#DEFINE_CONSTANT

Name:

#DEFINE_CONSTANT

Syntax:

#DEFINE_CONSTANT <constant_name> <constant_value>

Description:

Define a <constant_value> that will be substituted anywhere in the current source file where <constant_name> is used.

Example:

#DEFINE_CONSTANT ETX 0x03

INTEGER I; I=ETX;

Assigns the value of 0x03 to the variable I.

Version:

SIMPL+ Version 1.00

Language Reference Guide - DOC. 5797G SIMPL+® z 37

Software Crestron SIMPL+

#HELP

Name:

#HELP

Syntax:

#HELP “<help text>”

Description:

Several #HELP lines can be specified. When F1 is hit either on the symbol in the Symbol Library, in either the Program View or the Detail view, the help text will be displayed. If this directive or the #HELP_BEGIN … #HELP_END directive is not present, the help text shown is “NO HELP AVAILABLE”. Note that it is preferable to use the #HELP_BEGIN … #HELP_END directives rather than #HELP since it is easier to edit and read the code.

Example:

#HELP “This is line 1 of my help text”

#HELP “This is line 2 of my help text”

Version:

SIMPL+ Version 1.00

38 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

#HELP_BEGIN … #HELP_END

Name:

#HELP_BEGIN … #HELP_END

Syntax:

#HELP_BEGIN

Help Text Line 1 Help Text Line 2 etc. #HELP_END

Description:

The #HELP_BEGIN, #HELP_END pair makes it easier to create help since each line does not need a separate #HELP directive. When F1 is hit either on the symbol in the Symbol Library, in either the Program View or the Detail view, the help text will be displayed. If this directive or #HELP is not present, the help text shown is “NO HELP AVAILABLE”. Note that the text will show up exactly as typed between the begin/ end directives (including blank lines).

Example:

#HELP_BEGIN

This is help line 1. This is help line 3. #HELP_END

Version:

SIMPL+ Version 1.00

Language Reference Guide - DOC. 5797G SIMPL+® z 39

Software Crestron SIMPL+

#HINT

Name:

#HINT

Syntax:

#HINT “Hint Text”

Description:

The #HINT shows up in the status bar and provides a short tactical clue as to the function of the symbol, in the same way that Crestron-defined built-in symbols do. If the hint is specified, it will be visible when the symbol is highlighted in the User Modules section of the Symbol Library. The text shows up as the symbol name as it is stored on disk, followed by a colon, followed by the text. For example, a symbol with the name “My Symbol” might be stored on disk with the filename MYSYM.USP. If the hint is specified as #HINT “This is my symbol!” then the status bar will show “MYSYM.USP : This is my symbol!”. If no #HINT is specified, then only the filename is shown.

Example:

#HINT “This module controls a CNX-PAD8 Switcher”

Version:

SIMPL+ Version 1.00

40 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

#IF_DEFINED … #ENDIF

Name:

#IF_DEFINED … #ENDIF

Syntax:

#IF_DEFINED <constant_name>

<code> #ENDIF

Description:

Results in compilation of the <code> only if <constant_name> has previously been defined. This construct is generally useful for putting in code for debugging purposes, giving the ability to easily turn the debugging on and off during compilation.

Example:

#DEFINE_CONSTANT DEBUG 1

DIGITAL_OUTPUT OUT$; INTEGER I; FOR(I=0 to 20) { #IF_DEFINED DEBUG PRINT(“Loop index I = %d\n”, I); #ENDIF OUT$ = ITOA(I); }

The value of the loop is printed only if the DEBUG constant is defined. In order to prevent compilation of the code, delete the line that defines the constant or comment it out.

Version:

SIMPL+ Version 2.00

Language Reference Guide - DOC. 5797G SIMPL+® z 41

Software Crestron SIMPL+

#SYMBOL_NAME

Name:

#SYMBOL_NAME

Syntax:

#SYMBOL_NAME “<name of symbol>”

Description:

By specifying <name of symbol>, this name will show up on the header of the symbol in the detail view as well as in the USER SIMPL+ section of the Symbol Library. If this directive is not present, the default name shown in the Symbol Library/Program View/Detail view is the name of the USP file as saved on disk. For example, if the file is saved as “Checksum Program.USP”, the tree views will show “Checksum Program” as the name.

Example:

#SYMBOL_NAME “My SIMPL+ Program”

Version:

SIMPL+ Version 1.00

42 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

#USER_LIBRARY

Name:

#USER_LIBRARY

Syntax:

#USER_LIBRARY “<User Library Name>”

Description:

Directs the compiler to include code from a User written library. The module name specified is the User Library Filename without the USL extension that is used by User Libraries. Pathnames are not allowed as the USL modules are stored in the User SIMPL+ path (refer to Edit | Preferences | Paths in SIMPL Windows). User libraries can be created by saving a SIMPL+ module as type SIMPL+ library, instead of the default type SIMPL+ file.

Example:

#USER_LIBRARY “My Functions”

Directs the compiler to include the User Library “My Functions.USL” from the User SIMPL+ directory.

Version:

SIMPL+ Version 3.00 - Global variables can no longer be declared within User Library (.usl) files.

SIMPL+ Version 2.00

Language Reference Guide - DOC. 5797G SIMPL+® z 43

Software Crestron SIMPL+

#IF_NOT_DEFINED … #ENDIF

Name:

#IF_NOT_DEFINED … #ENDIF

Syntax:

#IF_NOT_DEFINED <constant_name>

<code> #ENDIF

Description:

Results in compilation of the <code> only if <constant_name> has not been previously defined. This construct is generally useful for putting in code for debugging purposes, giving the ability to easily turn the debugging on and off during compilation.

Example:

#DEFINE_CONSTANT DEBUG 1

DIGITAL_OUTPUT OUT$; INTEGER I; FOR(I=0 to 20) { #IF_DEFINED DEBUG PRINT(“Loop index I = %d\n”, I); #ENDIF #IF_NOT_DEFINED_DEBUG OUT$ = ITOA(I); #ENDIF }

The value of the loop is only printed if the DEBUG constant is defined. The output OUT$ is only generated if the debug constant is not defined (if debug mode is not turned on). In order to generate “release” code, the debug constant can be deleted or commented out.

Version:

SIMPL+ Version 2.00

44 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Declarations

Software

Declarations Overview

Declarations control the name, type, and number of inputs and outputs on a SIMPL+ symbol. The name is shown as a cue on the symbol in SIMPL Windows and is used as the variable name in the body of the SIMPL+ program. When the symbol is drawn in SIMPL Windows, the inputs are shown in the order of DIGITAL_INPUTs, ANALOG_INPUTs, STRING_INPUTs. The outputs are shown in the order of DIGITAL_OUTPUTs, ANALOG_OUTPUTs, STRING_OUTPUTs. When specifying a declaration, several variable names can be put after a declaration or multiple declaration statements may be used.

For example:

ANALOG_INPUT val1, val2, val3;

is equivalent to:

ANALOG_INPUT val1, val2;

ANALOG_INPUT val3;

Allowable I/O List Combinations

SIMPL+ Version 2.00 and later gives the ability to define arrays in the Input/Output Lists. SIMPL+ version 3.01 and later introduced the ability to declare multiple fixedsize arrays in the input/output lists, and a minimum expanded size to variable-size arrays.

The following are the allowable combinations:

Zero or more DIGITAL_INPUTs

•

Zero or more DIGITAL_INPUT arrays, the last is variable-size, the others are

•

fixed-size.

Zero or more ANALOG_INPUTs, STRING_INPUTs, or BUFFER_INPUTs

•

in any combination. Zero or more ANALOG_INPUT, STRING_INPUT, or BUFFER_INPUT

•

array, the last is variable-size, the others are fixed-size. Zero or more DIGITAL_OUPUTs

•

Zero or more DIGITAL_OUTPUT array, the last is variable-size, the others

•

are fixed-size. Zero or more ANALOG_OUTPUTs, STRING_OUTPUTs in any

•

combination. Zero or more ANALOG_OUTPUT or STRING_OUTPUT array, the last is

•

variable-size, the others are fixed-size.

Language Reference Guide - DOC. 5797G SIMPL+® z 45

Software Crestron SIMPL+

Fixed and Variable Size Arrays

Although SIMPL+ symbols can only handle one variable size DIGITAL_INPUT array, one variable-size DIGITAL_OUTPUT array, one variable-size ANALOG/ STRING/BUFFER input array, and one variable size ANALOG/STRING/OUTPUT array, it is convenient to be able to refer to other inputs and outputs with array notation. Therefore, SIMPL+ allows an unlimited number of fixed-size input or output arrays, that are essentially single input or output values but array notation can be used. Every member of these fixed-size arrays is always shown in the symbol. All arrays, except the last one of each kind, are fixed-size arrays. The last one is variablesize, meaning that the symbol initially shows the first array value. The user can press ALT+ to expand the symbol to its maximum number of array inputs or outputs. In addition, a minimum size can be declared in all variable-size arrays, meaning that the minimum number of array members is always shown, not just the first one, and the array can be expanded from there.

NOTE: The minimum array size numb er mu st b e fr om 1 to the size of the array. If a minimum array size is specified on any array, but it is the last one within any type, it will be a compile error.

Example:

DIGITAL_INPUT YesVotes[10] DIGITAL_INPUT NoVotes[10} DIGITAL_INPUT AbstainVotes[10,5];

The symbol will show 10 digital inputs labelled: YesVotes[1], YesVotes[2] ...YesVotes[10], followed by 10 more labelled: NoVotes[1], NoVotes[2] ...NoVotes[10], followed by 5 labelled: AbstainVotes[1], AbstainVotes[2] ...AbstainVotes[5]. You can continue to expand the last one up to AbstainVotes[10].

Predefined Names:

The names "on" and "off" are reserved. Assigning "on" to a variable sets the variable to 1, assigning "off" sets that variable to 0.

The following shows equivalent, given that VALUE is a DIGITAL_OUTPUT:

VALUE = 1; and VALUE = on; VALUE = 0; and VALUE = off;

46 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

ANALOG_INPUT

Name:

ANALOG_INPUT

Syntax:

ANALOG_INPUT <var1>[,<var2>...]; ANALOG_INPUT <var[size]>; ANALOG_INPUT <var[size[,<min>]]>

Description:

Routes analog inputs from the outside SIMPL program into a SIMPL+ program with the specified variable names. ANALOG_INPUT values are 16-bit numbers. They are treated as signed or unsigned values inside of a SIMPL+ program depending on the operators or functions being used.

NOTE: ANALOG_INPUT variables may not be passed to functions in Version 3.00 for the 2-Series Control Systems. If you need to pass an ANALOG_INPUT variable to a function, assign it to a locally declared variable and pass that variable to the function.

NOTE: <min> is the number of inputs shown at a minimum in SIMPL Windows. The Default is 1. The user can expand the minimum up to the full size. Only the last array of a type can have <min>. Refer to Arrays on page 31, and Declarations on page 45.

For an array of ANALOG_INPUTs, the maximum value of SIZE is 65535. Valid indices are 1 through the specified size.

Example:

ANALOG_INPUT ramp1;

Signifies that one analog input is coming into the SIMPL+ program from the SIMPL Program.

ANALOG_INPUT light_levels[25];

Signifies that up to 25 analog inputs are coming into the SIMPL+ program from the SIMPL Program, referenced as light_levels[1] through light_levels[25]. One is shown as a minimum but the symbol input can be expanded by the user up to 25.

ANALOG_INPUT temp_set_pts[20,4];

Signifies that up to 20 analog inputs exist, referenced as temp_ set_pt s[1] thro ugh temp_set_pts[20]. Four are shown at a minimum, and the symbol inputs can be expanded by the user up to 20.

Version:

SIMPL+ Version 2.00 for ANALOG_INPUT arrays, 3.01 for fixed arrays and minimum sizes. SIMPL+ Version 2.00 for ANALOG_INPUT arrays. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G SIMPL+® z 47

Software Crestron SIMPL+

ANALOG_OUTPUT

Name:

ANALOG_OUTPUT

Syntax:

ANALOG_OUTPUT <var1>[,<var2>...]; ANALOG_OUTPUT <var[size]>; ANALOG_OUTPUT<var[size[,<min>]]>;

Description:

Routes a value from the SIMPL+ program to the SIMPL program as an analog value. ANALOG_OUTPUT values are 16-bit numbers. They are treated as signed or unsigned values inside of a SIMPL+ program depending on the operators or functions being used. Refer to the discussion on Arrays on page 46.

NOTE: ANALOG_OUTPUTs may be jammed with other analog values from a SIMPL program (i.e., from a RAMP or other analog logic, even other SIMPL+ symbols). When such an output is jammed, the new value is read back into the SIMPL+ symbol and the value of the output is altered.

NOTE: <min> is the number of outputs shown at a minimum in SIMPL Windows. The Default is 1. The user can expand the minimum up to the full size. Only the last array of a type can have <min>. Refer to Arrays on page 31, and Declarations on

page 45.

In X-Generation Control Systems, the logic process only sees the last analog that was posted after the SIMPL+ module tasks switched away. Therefore, in a loop that iterates from 1 to 10000, only a few of the values will be seen by the logic process. If all values should be seen to by the logic process, a PROCESSLOGIC statement is required after the assignment to the ANALOG_OUTPUT.

When the SIMPL+ program writes to the ANALOG_OUTPUT, the new value is posted immediately. Therefore, if the value is read back after being assigned, the new value is read back (unlike a DIGITAL_OUTPUT on X-Generation control systems).

In the 2-Series Control Systems, the logic process sees ALL values that are assigned to the ANALOG_OUTPUT. No PROCESSLOGIC is required.

For an array of ANALOG_OUTPUTs, the maximum value of SIZE is 65535. Valid indices are 1 through the specified size.

48 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Example:

ANALOG_OUTPUT LEVEL;

Signifies that one analog input is being sent from the SIMPL+ program to t he SIMPL program.

ANALOG_OUTPUT LEVELS[25];

Signifies that up to 25 analog outputs, referred to as LEVELS[1] through LEVELS[25] are being sent from the SIMPL+ program to the SIMPL program.

ANALOG_OUTPUT LEVELS[25,5];

Signifies same as above, except that a minimum of 5 are shown at any time.

NOTE: If LEVEL or any of the elements from LEVELS is jammed from outside the symbol, it will take on that new jammed value.

NOTE: You should use isSignalDefined to test whether the output is connected to an actual signal in the SIMPL Windows program before assigning a value to it. If you assign a value and there is no signal, a message is placed in the system error log.

Version:

SIMPL+ Version 3.01 - Fixed size arrays and minimum sizes. SIMPL+ Version 3.00 - Can no longer be passed to functions by reference. (2-Series

Control Systems only) SIMPL+ Version 2.00 for ANALOG_OUTPUT arrays. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G SIMPL+® z 49

Software Crestron SIMPL+

BUFFER_INPUT

Name:

BUFFER_INPUT

Syntax:

BUFFER_INPUT <var1[max_length]>[,<var2[max_length]>...]; BUFFER_INPUT <var[size][max_length]>; BUFFER_INPUT<var[size[,<min>]][max_length]>;

Description:

Routes serial inputs from the outside SIMPL program into a SIMPL+ program under the specified variable names. This is used when a serial string coming from a communications port needs to be processed by a SIMPL+ program. When new data comes in on a BUFFER_INPUT, the data is appended to the end of a BUFFER_INPUT. If the buffer is full, the contents are shifted up and the new data is appended to the end. This differs from STRING_INPUTs in that new data entering into a STRING_INPUT variable replaces the previous string contents. BUFFER_INPUTs may be processed with string handling functions. The GETC function may be used to read a character from the beginning of the buffer and shift the contents up by 1. Buffer inputs may be written to, so their data space may be used as a storage spot for doing something such as parsing through a string without declaring temporary storage. Refer to the discussion on arrays on page 46.

NOTE: BUFFER_INPUT variables may not be passed to functions in Version 3.00 for the 2-Series Control Systems. If you need to pass a BUFFER_INPUT variable to a function, assign it to a locally declared variable and pass that variable to the function.

MAX_LENGTH may be a value up to 255 in SIMPL+ Version 1.00. SIMPL+ Version 2.00 and later allow for MAX_LENGTH to be up to 65535. For an array of BUFFER_INPUTs, the maximum value of SIZE is 65535. Valid indices are 1 through the specified size.

Example:

BUFFER_INPUT FromComPort[100];

Signifies that a 100 character buffer with the name “FromComPort” is specified as a BUFFER_INPUT.

BUFFER_INPUT ComBuffers[2][100];

Signifies that two 100 character buffers have been set up that may be referenced with the names ComBuffers[1] through ComBuffers[2].

BUFFER_INPUT ComBuffers[2,2][100];

Same as above except both are always shown on the symbol.

50 z SIMPL+

Version:

SIMPL+ Version 3.01 for fixed size arrays and minimum sizes. SIMPL+ Version 2.00 for BUFFER_INPUT arrays and MAX_LENGTH to 65535. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

DIGITAL_INPUT

Name:

DIGITAL_INPUT

Syntax:

DIGITAL_INPUT <var1>[,<var2>...];

DIGITAL_INPUT <var[size]>; DIGITAL_INPUT <var[size[,min]]>;

Description:

Routes digital inputs from the outside SIMPL program into a SIMPL+ program under the specified variable names. DIGITAL_INPUT values are either 0 (digital low) or 1 (digital high). Refer to the discussion on arrays on page 46.

NOTE: DIGITAL_INPUT variables may not be passed to functions in Version 3.00 for the 2-Series Control Systems. If you need to pass a DIGITAL_INPUT variable to a function, assign it to a locally declared variable and pass that variable to the function.

For an array of DIGITAL_INPUTs, the maximum value of SIZE is 65535. Valid indices are 1 through the specified size.

Example:

DIGITAL_INPUT osc_in, toggle_in;

Signifies that two digital inputs are coming into the SIMPL+ program from the SIMPL Program.

DIGITAL_INPUT status_bits[8];

Signifies that up to eight digital inputs are coming into the SIMPL+ program from the SIMPL Program, referenced under the names status_bits[1] through status_bits[8].

DIGITAL_INPUT flags[8,2];

Signifies up to eight digital inputs, with at least two shown.

Version:

SIMPL+ Version 3.01 for fixed arrays and minimum sizes. SIMPL+ Version 2.00 for DIGITAL_INPUT arrays. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G SIMPL+® z 51

Software Crestron SIMPL+

DIGITAL_OUTPUT

Name:

DIGITAL_OUTPUT

Syntax:

DIGITAL_OUTPUT <var1>[,<var2>...];

DIGITAL_OUTPUT <var[size]>; DIGITAL_OUTPUT <var[size[,<min>]]>;

Description:

Routes a value from the SIMPL+ program to a SIMPL program. If a value different from 0 is placed on a DIGITAL_OUTPUT, the digital signal in the SIMPL program is set high when the control system processes the logic.

Refer to the discussion on arrays on page 46.

NOTE: DIGITAL_OUTPUTs may be jammed with other digital values from a SIMPL program (i.e., from a BUFFER or other jammable digital logic, even other SIMPL+ symbols). When such an output is jammed, the new value is read back into the SIMPL+ symbol and the value of the output is altered.

page 45.

52 z SIMPL+

In X-Generation Control Systems, if a new value is assigned to the DIGITAL_OUTPUT from the SIMPL+ program, the value read back from it within the SIMPL+ program will have the original state until the logic is serviced. For example, if a DIGITAL_OUTPUT has a value of 0, and the value 1 is written to it, the value read back will be 0 until the system processes the rest of the logic attached to that SIMPL+ symbol. This is unlike an ANALOG_OUTPUT. If every change of a DIGITAL_OUTPUT is required to be seen by the logic, a PROCESSLOGIC statement is required after the assignment to the DIGITAL_OUTPUT.

In the 2-Series Control Systems, the logic process sees ALL values that are assigned to the DIGITAL_OUTPUT. No PROCESSLOGIC is required. As an example, if the following code is used in the 2-Series Control Systems:

DIGITAL_OUTPUT State1;

State1=1; State1=0;

The logic will end up seeing a short pulse. For an array of DIGITAL_OUTPUTs, the maximum value of SIZE is 65535. Valid

indices are 1 through the specified size.

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Example:

DIGITAL_OUTPUT State1, State2;

Signifies that two digital signals are to be sent to a SIMPL program from this SIMPL+ program.

NOTE: For example, if State1 is jammed high via a BUFFER from outside the SIMPL+ program, the value of State1 becomes 1 and should be handled accordingly in the SIMPL+ code.

DIGITAL_OUTPUT state_bits[3];

Signifies that up to three digital signals are to be sent to a SIMPL program from this SIMPL+ program. The names are referred to as state_bits[1] through state_bits[3]. The same jamming rules apply as in the previous example.

DIGITAL_OUTPUT state_bits[3,3];

Same as above except all three are always shown on the symbol.

Version:

SIMPL+ Version 3.01 - Fixed arrays and minimum sizes. SIMPL+ Version 3.00 - can no longer be passed to functions by reference. (2-Series

Control Systems only) SIMPL+ Version 2.00 for DIGITAL_OUTPUT arrays. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G SIMPL+® z 53

Software Crestron SIMPL+

INTEGER

Name:

INTEGER

Syntax:

INTEGER <var1>[,<var2>...];

INTEGER <var1>[size] [,<var2>[size]…]; INTEGER <var1>[rows1][columns1] [,<var2>[rows2][columns2]…];

Description:

The first form declares an integer value that is local to this SIMPL+ program. INTEGER values are 16-bit quantities and are treated the same as ANALOG_INPUT values and range from 0-65535.

The second form declares a one-dimensional array of INTEGER values. The third form declares a two-dimensional array of INTEGER values. A two-

dimensional array can be thought of as a table or matrix. The values for SIZE, ROWS, and COLUMNS may be up to 65535.

An INTEGER array element may be used anywhere an INTEGER is legal. Array elements are referenced by using the name followed by [element] for onedimensional arrays or [element1][element2] for two-dimensional arrays. The element number may range from 0 to the element size. For example, if an array is declared as NUM[2], then legal elements are NUM[0], NUM[1], and NUM[2]. The bracket notation is often called an array subscript.

NOTE: (X-Gen) The values of INTEGERs declared outside of functions are nonvolatile. If the system is powered down and up, th e variables will take the previous values. If programs are changed and uploaded, the values are not preserved.

NOTE: (2-Series) INTEGERs can be volatile or non-volatile. The default is defined using the compiler directives #DEFAULT_NONVOLATILE or #DEFAULT_VOLATILE or overridden using the nonvolatile or volatile keywords.

NOTE: If no RETURN statement is encountered, the function automatically returns a 0.

54 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Example:

INTEGER temp_level;

Specifies one locally declared INTEGER in this SIMPL+ program

INTEGER CommandBytes[2];

Specifies an array of three INTEGERS that can be referenced under the name CommandBytes. In pictorial form, it appears as:

CommandBytes[0] CommandBytes[1] CommandBytes[2]

INTEGER Matrix[4][3];

Specifies a two-dimensional array of integers five rows deep by four columns wide. In pictorial form, it appears as:

Matrix[0][0] Matrix[0][1] Matrix[0][2] Matrix[0][3] Matrix[1][0] Matrix[1][1] Matrix[1][2] Matrix[1][3] Matrix[2][0] Matrix[2][1] Matrix[2][2] Matrix[2][3] Matrix[3][0] Matrix[3][1] Matrix[3][2] Matrix[3][3] Matrix[4][0] Matrix[4][1] Matrix[4][2] Matrix[4][3]

NOTE: The subscripts of an array may be an expression, i.e.:

INTEGER location[5], room; room = 2; location[room] = 10;

Version:

SIMPL+ Version 1.00 SIMPL+ Version 2.00 allowed INTEGER to be declared inside of functions.

Language Reference Guide - DOC. 5797G SIMPL+® z 55

Software Crestron SIMPL+

LONG_INTEGER

Name:

LONG_INTEGER

Syntax:

LONG_INTEGER <var1>[,<var2>...];

LONG_INTEGER <var1>[size] [,<var2>[size]…]; LONG_INTEGER <var1>[rows1][columns1] [,<var2>[rows2][columns2]…];

Description:

The first form declares a long value that is local to this SIMPL+ program. LONG_INTEGER values are 32-bit quantities ranging from 0-4294967296.

The second form declares a one-dimensional array of LONG_INTEGER values. The third form declares a two-dimensional array of LONG_INTEGER values. A

two-dimensional array can be thought of as a table or matrix. The values for SIZE, ROWS, and COLUMNS may be up to 65535.

A LONG_INTEGER array element may be used anywhere a LONG_INTEGER is legal. Array elements are referenced by using the name followed by [element] for one-dimensional arrays or [element1][element2] for two-dimensional arrays. The element number may range from 0 to the element size. For example, if an array is declared as NUM[2], then legal elements are NUM[0], NUM[1], and NUM[2]. The bracket notation is often called an array subscript.

NOTE: (2-Series) LONG_INTEGERs can be volatile or non-volatile. The default is defined using the compiler directives #DEFAULT_NONVOLATILE or #DEFAULT_VOLATILE or overridden using the nonvolatile or volatile keywords.

56 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Example:

LONG_INTEGER temp_level;

Specifies one locally declared LONG_INTEGER in this SIMPL+ program

LONG_INTEGER CommandBytes[2];

Specifies an array of three LONG_INTEGERs that can be referenced under the name CommandBytes. In pictorial form, it appears as:

CommandBytes[0] CommandBytes[1] CommandBytes[2]

LONG_INTEGER Matrix[4][3];

Specifies a two-dimensional array of LONG_INTEGERs five rows deep by four columns wide.

In pictorial form, it appears as:

NOTE: The subscripts of an array may be an expression, i.e.:

LONG_INTEGER location[5], room; room = 2; location[room] = 10;

Version:

SIMPL+ Version 3.00.01

Control System

2-Series Only

Language Reference Guide - DOC. 5797G SIMPL+® z 57

Software Crestron SIMPL+

SIGNED_INTEGER

Name:

SIGNED_INTEGER

Syntax:

SIGNED_INTEGER <var1>[,<var2>...];

SIGNED_INTEGER <var1>[size] [,<var2>[size]…]; SIGNED_INTEGER <var1>[rows1][columns1] [,<var2>[rows2][columns2]…];

Description:

The first form declares an integer value that is local to this SIMPL+ program. SIGNED_INTEGER values are 32-bit quantities ranging from -32678 to 32767.

The second form declares a one-dimensional array of SIGNED_INTEGER values. The third form declares a two-dimensional array of SIGNED_INTEGER values. A

two-dimensional array can be thought of as a table or matrix. The values for SIZE, ROWS, and COLUMNS may be up to 65535.

A SIGNED_INTEGER array element may be used anywhere an SIGNED_INTEGER is legal. Array elements are referenced by using the name followed by [element] for one-dimensional arrays or [element1][element2] for twodimensional arrays. The element number may range from 0 to the element size. For example, if an array is declared as NUM[2], then legal elements are NUM[0], NUM[1], and NUM[2]. The bracket notation is often called an array subscript.

NOTE: (2-Series) SIGNED_INTEGERs can be volatile or non-volatile. The default is defined using the compiler directives #DEFAULT_NONVOLATILE or #DEFAULT_VOLATILE or overridden using the nonvolatile or volatile keywords.

58 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Example:

SIGNED_INTEGER temp_level;

Specifies one locally declared SIGNED_INTEGER in this SIMPL+ program

SIGNED_INTEGER CommandBytes[2];

Specifies an array of three SIGNED_INTEGERS that can be referenced under the name CommandBytes. In pictorial form, it appears as:

CommandBytes[0] CommandBytes[1] CommandBytes[2]

SIGNED_INTEGER Matrix[4][3];

Specifies a two-dimensional array of integers five rows deep by four columns wide. In pictorial form, it appears as:

NOTE: The subscripts of an array may be an expression, i.e.:

SIGNED_INTEGER location[5], room; room = 2; location[room] = 10;

Version:

SIMPL+ Version 3.00.06

Control System:

2-Series Only

Language Reference Guide - DOC. 5797G SIMPL+® z 59

Software Crestron SIMPL+

SIGNED_LONG_INTEGER

Name:

SIGNED_LONG_INTEGER

Syntax:

SIGNED_LONG_INTEGER <var1>[,<var2>...];

SIGNED_LONG_INTEGER <var1>[size] [,<var2>[size]…]; SIGNED_LONG_INTEGER <var1>[rows1][columns1] [,<var2>[rows2][columns2]…];

Description:

The first form declares a long value that is local to this SIMPL+ program. SIGNED_LONG_INTEGER values are 32-bit quantities ranging from 2,147,483,647 to 2,147,483,647.

The second form declares a one-dimensional array of SIGNED_LONG_INTEGER values.

The third form declares a two-dimensional array of SIGNED_LONG_INTEGER values. A two-dimensional array can be thought of as a table or matrix.

The values for SIZE, ROWS, and COLUMNS may be up to 65535.

A SIGNED_LONG_INTEGER array element may be used anywhere a SIGNED_LONG_INTEGER is legal. Array elements are referenced by using the name followed by [element] for one-dimensional arrays or [element1][element2] for two-dimensional arrays. The element number may range from 0 to the element size. For example, if an array is declared as NUM[2], then legal elements are NUM[0], NUM[1], and NUM[2]. The bracket notation is often called an array subscript.

NOTE: (2-Series) SIGNED_LONG_INTEGERs can be volatile or non-volatile. The default is defined using the compiler directives #DEFAULT_NONVOLATILE or #DEFAULT_VOLATILE or overridden using the nonvolatile or volatile keywords.

60 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Example:

SIGNED_LONG_INTEGER temp_level;

Specifies one locally declared SIGNED_LONG_INTEGER in this SIMPL+ program

SIGNED_LONG_INTEGER CommandBytes[2];

Specifies an array of three SIGNED_LONG_INTEGERs that can be referenced under the name CommandBytes. In pictorial form, it appears as:

CommandBytes[0] CommandBytes[1] CommandBytes[2]

SIGNED_LONG_INTEGER Matrix[4][3];

Specifies a two-dimensional array of SIGNED_LONG_INTEGERs five rows deep by four columns wide.

In pictorial form, it appears as:

NOTE: The subscripts of an array may be an expression, i.e.:

SIGNED_LONG_INTEGER location[5], room; room = 2; location[room] = 10;

Version:

SIMPL+ Version 3.00.06

Control System

2-Series Only

Language Reference Guide - DOC. 5797G SIMPL+® z 61

Software Crestron SIMPL+

STRING

Name:

STRING

Syntax:

STRING <var1[size1]>[,<var2[size2]>...];

STRING <var1[num_elements1][num_characters1]>[, <var2[num_elements2][num_characters2]>...];

Description:

Declares a string that is local to this SIMPL+ program. Strings are of arbitrary length, so a maximum size must be specified. When a STRING variable has new data assigned to it, the old data is lost.

NOTE: Strings in Version 3.00 for the 2-Series Control Systems may not be passed by value to a function. They must be passed by reference.

NOTE: If no Return Value is specified within an String_Function, then an empty string (0) will be returned by default.

When used in its second form, a one-dimensional array of strings is allocated. The array has num_elements+1 elements, and num_characters per element allocated. The legal indices for referencing the strings are 0 through num_elements.

The value of SIZE and NUM_CHARACTER may be up to 255 in SIMPL+ Version

1.00. In SIMPL+ Version 2.00 and later, they may be up to 65535. The value of NUM_ELEMENTS may be up to 65535.

NOTE: (X-Gen) The values of STRINGs declared are non-volatile. If the system is powered down and up, the variables will take on their previous values. If programs are changed and uploaded, the values are not preserved.

NOTE: (2-Series) STRINGs can be volatile or non-volatile. The default is defined using the compiler directives #DEFAULT_NONVOLATILE or #DEFAULT_VOLATILE or overridden using the nonvolatile or volatile keywords.

62 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Example:

STRING temp$[10];

Signifies that one local STRING is declared in this SIMPL+ program.

STRING temp$[2][10];

Signifies that three strings of 10 characters long have been allocated. To assign values, the following would be legal:

temp$[0]=”Val1”;

temp$[1]=”Val2”; temp$[2]=”Val3”;

Version:

SIMPL+ Version 2.00 for SIZE and NUM_CHARACTER up to 65535. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G SIMPL+® z 63

Software Crestron SIMPL+

STRING_INPUT

Name:

STRING_INPUT

Syntax:

STRING_INPUT <var1[max_size1]>[,<var2[max_size2]>...]; STRING_INPUT <var[size][max_size]>; STRING_INPUT <var[size[,<min>]][max_size]>;

Description:

Routes serial inputs from the outside SIMPL program into a SIMPL+ program under the specified variable names. Strings are of arbitrary length, so a maximum size must be specified. Upon receiving new data, the value is cleared and the new string is put in. Strings received greater than the specified size are truncated to the size in the declaration. String inputs may be written to, so their data space may be used as a storage spot for doing something such as parsing through a string without declaring temporary storage. Refer to the discussion on arrays on page 46.

NOTE: STRING_INPUT variables may not be passed to functions in Version 3.00 for the 2-Series Control Systems. If you need to pass a STRING_INPUT variable to a function, assign it to a locally declared variable and pass that variable to the function.

The value of SIZE and NUM_CHARACTER may be up to 255 in SIMPL+ Version

1.00. In SIMPL+ Version 2.00 and later, they may be up to 65535. For an array of STRING_INPUTs, the maximum value of SIZE is 65535.

Example:

STRING_INPUT FirstName[100], SecondName[25];

Signifies that two serial inputs are coming into the SIMPL+ program from the SIMPL Program. The first one may only be a maximum of 100 characters, the second may only be a maximum of 25 characters. If an input is longer than the specified length, everything after the specified limit is lost.

STRING_INPUT DataBaseNames[9][100];

Signifies that 9 serial inputs are coming into the SIMPL+ program from the SIMPL program. Each name has a 100 character limit. The names are referenced as DataBaseNames[1] through DataBaseNames[9].

STRING_INPUT Database Names [9,3][100];

Same as above except at least three are shown at all times.

64 z SIMPL+

Version:

SIMPL+ Version 3.01 for fixed arrays and minimum sizes. SIMPL+ Version 2.00 for STRING_INPUT arrays and SIZE, NUM_CHARACTER to 65535. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

STRING_OUTPUT

Name:

STRING_OUTPUT

Syntax:

STRING_OUTPUT <var1>[,<var2>...]; STRING_OUTPUT <var[size]>; STRING_OUTPUT <var[size[,<min>]][size]>;

Description:

Routes serial strings from the SIMPL+ program to the SIMPL program. A string length is not required as the output string buffer management is performed by the operating system. Refer to the discussion on arrays on page 46.

NOTE: These outputs may be jammed with other serial string signals in the SIMPL program, although the value does not propagate back into the SIMPL+ symbol.

NOTE: The maximum string length for a STRING_OUTPUT is 255 characters. Assigning a string with a length of more than 255 will result in a loss of data.

page 45.

The value of a STRING_OUTPUT cannot be read. If knowledge of the value of the STRING_OUTPUT is required, the value to be written to the STRING_OUTPUT can also be written to a STRING for local storage.

In X-Generation Control Systems, if several values are issued to a STRING_OUTPUT, the logic will only see the last value written to the STRING_OUTPUT when the SIMPL+ pro gram task switches away. If all values are required to be seen by the logic, a PROCESSLOGIC statement is required after writing to the STRING_OUTPUT.

In the 2-Series Control Systems, all values written to a STRING_OUTPUT are maintained. The logic will see each value of the STRING_OUTPUT. No PROCESSLOGIC is required.

For an array of STRING_OUTPUTs, the maximum value of SIZE is 65535. Valid indices are 1 through the specified size.

Language Reference Guide - DOC. 5797G SIMPL+® z 65

Software Crestron SIMPL+

Example:

STRING_OUTPUT TheName$;

Signifies one string called TheName$ that is generated by the SIMPL+ program and sent to the SIMPL program.

STRING_OUTPUT SortedNames$[5];

Specifies five strings that are generated by the SIMPL+ program and sent to the SIMPL program. The names are referred to as SortedNames[1] through SortedNames[5].

STRING_OUTPUT SortedNames$[5,5];

Same as above except all five are always shown.

Version:

SIMPL+ Version 3.01 - Fixed size arrays and minimum sizes. SIMPL+ Version 3.00 - can no longer be passed to functions by reference. (2-Series

Control Systems only) SIMPL+ Version 2.00 for STRING_OUTPUT arrays. SIMPL+ Version 1.00 for everything else.

66 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

STRUCTURES

A structure is a collection of one or more variables grouped together under a single name. These variables, called structure fields or members, may consist of bo th integer and string datatypes. Structures help organize related data because they allow variables to be grouped together as a unit instead of as separate entities.

Structure datatypes can only be defined globally. Variables of a defined structure datatype may be declared both globally and locally and passed as function arguments. Structures are always passed to functions by reference. INTEGER, LONG_INTEGER, SIGNED_INTEGER, SIGNED_LONG_INTEGER and STRING are the only SIMPL+ datatypes allowed to be used as structure member fields. INTEGER and LONG_INTEGER can include 1 and 2 dimensional arrays. String arrays are not permitted.

The syntax for defining a structure is as follows:

STRUCTURE struct_name

{ type member1; type member2; . . . type memberN; };

The keyword, STRUCTURE, tells the compiler that a new datatype is being defined. Each type is one of the SIMPL+ datatypes, INTEGER, LONG_INTEGER, SIGNED_INTEGER, SIGNED_LONG_INTEGER or STRING. Struct_name is the name for the structure that will be used as the new datatype.

Declaring a variable of a structure datatype is as follows:

struct_name var_name;

An example of a structure would be an entry in a phone book. The phone book contains many entries, all containing the same three pieces of information: the person’s name, address and phone number. The structure would be defined as follows:

STRUCTURE PhoneBookEntry

{ STRING Name[50]; STRING Address[100]; STRING PhoneNumber[20]; }; PhoneBookEntry OneEntry; PhoneBookEntry Entry[500];

In this example, the name, PhoneBookEntry, is the datatype defined that will encapsulate the structure fields, Name, Address and PhoneNumber. Two variables are then defined to be of this datatype. The variable, OneEntry, is a variable that contains one instance of the datatype, PhoneBookEntry.

Language Reference Guide - DOC. 5797G SIMPL+® z 67

Software Crestron SIMPL+

The variable, Entry, is then defined to be an array of the datatype, PhoneBookEntry consisting of 501 individual instances, namely Entry[0] to Entry[500].

To access a structure’s field, the structure’s declared variable name is used, followed by a period (also known as the ‘dot’ or ‘dot operator’), then followed by a structure member variable name.

From the example above, accessing the Name field from the declared variable would be written as follows:

OneEntry.Name

Entry[5].Name

Using this in a SIMPL+ statement might look as follows:

If ( OneEntry.Name = “David” )

Return; If ( Entry[5].Name = “David” ) Return;

Passing structures as function arguments is as follows:

FUNCTION myFunction ( PhoneBookEntry argOneEntry,

PhoneBookEntry argEntry[] ) { if ( argOneEntry.Name = “David” ) return; if ( argEntry[5].Name = “David” ) return; }

Version:

SIMPL+ Version 3.00.02

Control System

2-Series Only

68 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Declaration Modifiers

Volatile

Name:

Volatile

Syntax:

Volatile

NOTE: This is not a declaration but a declaration modifier. It works only in conjunction with another declaration keyword.

Description:

Software

Global integer and string program variables will not retain their value if hardware power is lost.

Example:

Volatile integer n;

Volatile string s[100];

Version:

SIMPL+ Version 3.00

Control System

2-Series Only . The X-generation compiler will give an error message saying that all variables are non-volatile.

Language Reference Guide - DOC. 5797G SIMPL+® z 69

Software Crestron SIMPL+

Nonvolatile

Name:

Nonvolatile

Syntax:

Nonvolatile

NOTE: This is not a declaration but a declaration modifier. It works only in conjunction with another declaration keyword.

Description:

Global integer and string program variables will retain their value if hardware power is lost.

Example:

Nonvolatile integer n;

Nonvolatile string s[100];

Version:

SIMPL+ Version 3.00

Control System:

2-series only. The X-generation processors will give a message that says all va riables are non-volatile.

70 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

E-mail Functions

Software

Important SendMail Considerations

1. In the SIMPL+ function call to “Send Mail”, the parameters “Mailserv”, “To” and “From” fields are MANDATORY, whereas “cc”, “subject” and “message” are not.

2. Only the “SMTP AUTH” authentication type with “LOGIN” authentication scheme is supported for now.

3. Questions for the ISP/e-mail service provider to determine compatibility with the SEND MAIL feature.

A. Does the ISP/service provider support NON-WEB clients?

B. Does the ISP/service provider support “SMTP AUTH”

authentication type with “LOGIN” authentication scheme?

C. For example: the e-mail provider SBC YAHOO supports web

as well as non web clients. For non web clients, one of the mail servers to communicate with is SMTPAUTH.FLASH.NET. This mail server supports SMTP AUTH and LOGIN auth scheme.

4. SEND MAIL client queries the mail server to determine the authentication type and scheme and returns an “unsupported” error (error # -9) if the mail-server does not support LOGIN scheme; however if the client is unable to determine information regarding the schemes supported, it will go ahead and try to send out the e-mail to the intended recipients, but the server may refuse to relay it to external destinations. This will return a “failure” code, which is a POSITIVE integer (Refer to E-mail Function Return Error Codes on page 72).

5. For mail servers needing no authentication, the “username” and “password” field are set to an EMPTY STRING (““). Again, as in (4) above there is no guarantee that the mail-server will relay the e-mail to external destinations.

6. In case of an error/failure, the first occurring error/failure code is returned.

7. If the message line exceeds 998 characters without a <CR-LF> sequence, the SEND MAIL module automatically inserts one.

8. The “Mail-server” parameter in the SIMPL+ function call to Send Mail can be an IP address, ex. “132.149.6.220” or a name “mail1.Mycompany name.com”. In case of a name, DNS will be used to resolve the name, and the control system MUST have a DNS server setup.

9. **REMINDER**: Strings in SIMPL can only be 256 characters long. But internal to SIMPL+ they can be concatenated to a total length of 65536 characters, as long as a SIMPL+ BUFFER_INPUT type is used to accumulate the strings.

Language Reference Guide - DOC. 5797G SIMPL+® z 71

Software Crestron SIMPL+

E-mail Function Return Error Codes

ERROR CODE # DESCRIPTION

SMTP_OK 0 Success

SMTP ERRORS (NONRECOVERABLE ERRORS)

ERROR CODE # DESCRIPTION

SMTP_ERROR_FATAL -1 Any non-recoverable error from the e-mail

module of the firmware (for example: if

“mailserver”, “from” and “to” are empty). SMTP_ERROR_ILLEGAL_CMD -2 General internal error. SMTP_ERROR_CONNECT -3 Failure to connect to the mailserver. SMTP_ERROR_SEND -4 Internal error while actually sending out e-mail. SMTP_ERROR_RECV -5 Internal error while actually receiving out e-mail. SMTP_ERROR_NU_CONNECT -6 Internal error while processing the send. SMTP_ERROR_NU_BUFFERS -7 Lack of memory buffers while processing send

or receive mail. Internal error. SMTP_ERROR_AUTHENTICATION -8 Authentication failure. SMTP_ERROR_AUTH_LOGIN_UNSUPPORTED -9 CLEAR TEXT login scheme is not supported. SMTP_INV_PARAM -10 Bad parameters to SendMail. Must supply

Server, From, and To. SMTP_ETHER_NOT_ENABLED -11 Ethernet not enabled. Cannot send mail. SMTP_NO_SERVER_ADDRESS -12 No DNS servers configured. Cannot resolve

name. SMTP_SEND_FAILURE -13 SendMail failed.

SMTP FAILURES (RECOVERABLE ERRORS)

ERROR CODE # DESCRIPTION

SMTP_FAILURE_TO_RCPT_COMMAND 3 There was an error sending e-mail to the “to”

recepient. SMTP_FAILURE_CC_RCPT_COMMAND 4 There was an error sending e-mail to the “CC”

recepient. SMTP_FAILURE_DATA_COMMAND 5 There was an error sending the message body.

72 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

SendMail

Name:

SendMail

Syntax:

SIGNED_INTEGER SendMail( STRING Server,

STRING UserLogonName, STRING UserLogonPassword, STRING From, STRING To, STRING CC, STRING Subject, STRING Message )

Description:

Send an e-mail message using SMTP protocol.

Parameters:

Server - Required. Specifies address of the mail server. It can either be an IP address in dot-decimal notation (ex: 192.168.16.3) or a name to be resolved with a DNS server (ex: mail.myisp.com). If a name is given, the control system must be configured with a DNS server (ADDDNS console command). Maximum field length: 40.

UserLogonName - Optional, but if authentication is not required, put an empty string in its place. If the mail server requires authentication, UserLogonName indicates the user name of the sender for the mail server. An empty string indicates that authentication is not required. Only “clear text” authentication is implemented. “Clear text” refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server. Maximum field length: 254.

UserLogonPassword - Optional, but if authentication is not required, put an empty string in its place. If the mail server requires authentication, UserLogonPassword indicates the password of the sender for the mail server. An empty string indicates that authentication is not required. Only “clear text” authentication is implemented. “Clear text” refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server. Maximum field length: 254.

From - Required. Specifies the e-mail address of the sender in the a@b.com format. Only one e-mail address is allowed. Aliases or nicknames are not supported. This argument is mandatory. Maximum field length: 242.

To - Required. Specifies the e-mail address of the recipient(s) in the a@b.com format. Multiple recipients may be specified delimited with a “;”. This argument is mandatory. Maximum field length: 65535.

CC - Optional , but put an empty string in its place to indicate that there are no recipients. Specifies the e-mail address of the carbon copy recipient(s) in the

Language Reference Guide - DOC. 5797G SIMPL+® z 73

Software Crestron SIMPL+

a@b.com format. Multiple recipients may be specified delimited with a “;”. Maximum field length: 65535.

Subject - Optional, but use an empty string to indicate that there is no subject. Specifies the subject of the e-mail message. Maximum field length: 989.

Message - Optional, but use an empty string to indicate that there is no message. Specifies the body of the e-mail message. An empty string indicates an empty message. Maximum field length: 65535.

Return Value:

0 if successful. Otherwise, E-mail Return Error Code is returned. Negative return error codes indicate that no part of the e-mail was sent (example: user logon password was incorrect). Positive return error codes indicate a failure (example: one or more recipient e-mail addresses was invalid), but the e-mail was still sent. In the event of more than one failure, the return error code of the first failure is returned.

Example:

SIGNED_INTEGER nErr;

nErr = SendMail( “192.168.16.3”, “UserLogonName”, “UserLogonPassword”, “SenderEmailAddress@crestron.com”, “RecipientEmailAddress@crestron.com”, “ccEmailAddress@crestron.com”, “This is the subject”, “This is the message” ); if ( nErr < 0 ) Print( “Error sending e-mail\n” ); else Print( “SendMail successful!\n );

74 z SIMPL+

Version:

SIMPL+ Version 3.01.xx (Pro 2 only)

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Events

Software

Events Overview

SIMPL+ is an event driven language. There are four functions which deal with activating events in a given SIMPL+ program; CHANGE, EVENT, PUSH, and RELEASE.

CHANGE

Name:

CHANGE

Syntax:

CHANGE <variable_name1> [, <variable_name2> ...]

{ [Local Variable Definitions] <statements> }

Description:

<variable_name> may be either a DIGITAL_INPUT, ANALOG_INPUT, or STRING_INPUT type. If it is a DIGITAL_INPUT, the statements between { and } will be executed when the input transitions from low to high or high to low. If it is an ANALOG_INPUT or STRING_INPUT, the statements between { and } will be executed whenever the variable changes. Note that for an ANALOG_INPUT or STRING_INPUT, the same value re-issued will also cause the CHANGE to activate.

When using ANALOG_INPUT, BUFFER_INPUT, DIGITAL_INPUT, or STRING_INPUT arrays, only a change in the entire array can be detected, not an individual element. Refer to “GetLastModifiedArrayIndex” on page 93 to determine which element actually changed. Use IsSignalDefined to ensure that you send data only to outputs that exist or take input from signals that exist.

When listing multiple variable names, the names can be pu t on the same li ne or broken up into several CHANGE statements for readability.

Refer to “Stacked Events” on page 80.

Language Reference Guide - DOC. 5797G SIMPL+® z 75

Software Crestron SIMPL+

Example:

STRING_INPUT some_data$[100];

ANALOG_OUTPUT level;

CHANGE some_data$ {

level=48;

}

When the STRING_INPUT changes, the ANALOG_OUTPUT level will have the value 48 put into it. If the same data comes in on some_data$, the CHANGE block is executed again.

ANALOG_INPUT ThingsToAdd[20];

ANALOG_OUTPUT Sum; INTEGER I, Total;

CHANGE ThingsToAdd {

Total=0; FOR(I=0 to 20)

if (IsSignalDefined (ThingsToAdd[I]))

Total = Total + ThingsToAdd[I];

Sum = Total;

}

In this example, an array is used to hold elements to add. When any element of the array changes, the sum is recomputed and issued on an analog output variable.

76 z SIMPL+

Version:

SIMPL+ Version 3.00 - local variables are allowed within CHANGE statements. SIMPL+ Version 2.00 for ANALOG_INPUT, BUFFER_INPUT,

DIGITAL_INPUT, and STRING_INPUT arrays as <variable_name>. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

EVENT

Name:

EVENT

Syntax:

EVENT

{

[Local Variable Definitions] <statements>

}

Description:

Executes the defined <statements> anytime one of the inputs to the SIMPL+ symbol changes. It is similar to having a CHANGE statement listed for every input, and each change is set up to execute a common block of code. Refer to “Stacked Events” on

page 80.

Example:

ANALOG_INPUT level1, level2, level3;

STRING_INPUT extra$[2][20]; STRING_OUTPUT OUT$;

EVENT { OUT$=extra$[0]+extra$[1]+CHR(level1)+CHR(level2)+CHR(level3)

; }

In this example, when the ANALOG_INPUTs level1, level2, level3, or level4 have any change or the STRING_INPUT array extra$ has changed, the STRING_OUTPUT OUT$ will be recomputed and reissued.

Version:

SIMPL+ Version 3.00 - Local variables are allowed within EVENT statements. SIMPL+ Version 1.00

Language Reference Guide - DOC. 5797G SIMPL+® z 77

Software Crestron SIMPL+

PUSH

Name:

PUSH

Syntax:

PUSH <variable_name1> [, <variable_name2> ...]

{

[Local Variable Definitions] <statements>

}

Description:

<variable_name> is a DIGITAL_INPUT type. On the rising edge of <variable_name>, the statements between the opening { and closing } are executed.

When using DIGITAL_INPUT arrays, only a change in the entire array can be detected, not an individual element. Refer to “GetLastModifiedArrayIndex” on

page 93 for a method of detecting a change to an individual element.

When listing multiple variable names, the names can be pu t on the same li ne or broken up into several PUSH statements for readability. Refer to “Stacked Events” on page 80.

Example:

DIGITAL_INPUT trigger;

STRING_OUTPUT output$;

PUSH trigger { output$ = “Hello, World!”; }

In this example, when the DIGITAL_INPUT trigger transitions from low to high, the STRING_OUTPUT output$ will have the string “Hello, World!” put into it.

Version:

SIMPL+ Version 3.00 - local variables are allowed within PUSH statements. SIMPL+ Version 2.00 for DIGITAL_INPUT arrays as <variable_name>. SIMPL+ Version 1.00 for everything else.

78 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

Release

Name:

RELEASE

Syntax:

RELEASE <variable_name1> [, <variable_name2> ...]

{ [Local Variable Definitions] <statements> }

Description:

<variable_name> is a DIGITAL_INPUT type. On the trailing edge of <variable_name>, the statements between the opening { and closing } are executed.

When using DIGITAL_INPUT arrays, only a change in the entire array can be detected, not an individual element. Refer to “GetLastModifiedArrayIndex” on

page 93 for a method of detecting a change to an individual element.

When listing multiple variable names, the names can be pu t on the same li ne or broken up into several RELEASE statements for readability. Refer to “Stacked Events” on page 80.

Example:

DIGITAL_INPUT trigger;

STRING_OUTPUT output$;

RELEASE trigger {

output$ = “Hello, World!”;

}

In this example, when the DIGITAL_INPUT trigger transitions from high to low, the STRING_OUTPUT output$ will have the string “Hello, World!” put into it.

Version:

SIMPL+ Version 3.00 - local variables are allowed within RELEASE statements. SIMPL+ Version 2.00 for DIGITAL_INPUT arrays as <variable_name>. SIMPL+ Version 1.00 for everything else.

Language Reference Guide - DOC. 5797G SIMPL+® z 79

Software Crestron SIMPL+

Stacked Events

Stacked Events refers to multiple CHANGE, PUSH or RELEASE functions followed by a single block of code (complex statement).

NOTE: Only CHANGE, PUSH, or RELEASE functions are used in stacked events. If necessary, refer to the descriptions of each function for details.

NOTE: An input signal can be used in more than one event function. The order execution is as follows:

The order for a PUSH:

PUSH statements in the order they appear in the source. CHANGE statements in the order they appear in the source EVENT statement

The order for a RELEASE:

RELEASE statements in the order they appear in the source. CHANGE statements in the order they appear in the source EVENT statement

A typical event statement may appear as:

PUSH var1, var2

{

// code

}

SIMPL+ allows event stacking, which allows a block of code to be called from different CHANGE, PUSH, or RELEASE statements. An example is:

STRING_INPUT A$[100];

DIGITAL_INPUT IN1, IN2, IN3, IN4; ANALOG_INPUT LEVEL; ANALOG_INPUT PRESETS[5]; PUSH IN1 PUSH IN2 CHANGE IN3, LEVEL, A$, PRESETS RELEASE IN3, IN4 {

// code

}

This allows one piece of code to execute from many different types of event statements.

80 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Expressions & Statements

An expression consists of operators and operands. i.e.,

5 * 6

(VAL1 + 5) / 30

(26 + BYTE(THESTRING$,1)) MOD Z = 25

Statements consist of function calls, expressions, assignments, or other instructions. There are two types of statements, Simple and Complex.

A simple statement ends with a semicolon (;). Examples of simple statements are:

X = Z/10; // Simple assignment statement using // operators. PRINT(“Hello, World!\n”); // Simple statement using a function

// call. CHECKSUM = ATOI(Z$) + 5; // Simple assignment statement using

// a function call and operators.

A complex statement is a collection of simple statements that start with '{' and end with '}'. An example would be:

{ // Start of a complex statement X = Z/10; // Simple assignment statement // using operators. PRINT(“Hello, World!\n”); // Simple statement using a // function call. CHECKSUM = ATOI(Z$) + 5; // Simple assignment statement // using a function call and // operators. } // End of a Complex statement

Software

Language Reference Guide - DOC. 5797G SIMPL+® z 81

Software Crestron SIMPL+

Looping Constructs

Looping Constructs Overview

Loops are used to perform a section of code zero or more times in a row in a given SIMPL+ program. The body of the loop can consist of statements, expressions, function calls, or other loops.

DO - UNTIL

Name:

DO - UNTIL

Syntax:

[{]

[}] UNTIL (<expression>);

Description:

This loop performs a set of <statements> at least one time and will terminate when <expression> evaluates to true. If only one statement is present in the body of the loop, then the { and } characters are not required, but may be used. If more than one statement is present in the loop body, then the { and } characters are mandatory. Note that <expression> is evaluated each time through the loop.

Example:

INTEGER X;

X=0; DO { X = X + 1; PRINT(“X = %d\n”, X); } UNTIL (X = 25);

In this example, the loop will execute 25 times. The PRINT function will show the value of X after it is incremented to the computer port of the control system.

Version:

82 z SIMPL+

SIMPL+ Version 1.00

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

FOR

Name:

FOR

Syntax:

FOR (<variable> = <start_expression> TO <end_expression>

[STEP <step_expression>]) [{] <statements> [}]

Description:

This loop executes the <statements> while <variable> iterates from the value of <start_expression> to the value of <end_expression>. The variable is incremented by <step_expression> at the end of the loop, if STEP is specified, else it is incremented by 1. The <step_expression> can be negative which will result in the loop counting down. If only one statement is present in the body of the loop, then the { and } characters are not required, but may be used. If more than one statement is present in the loop body, then the { and } characters are mandatory. Note that <start_expression> and <end_expression> are evaluated once before the loop starts and are not re-evaluated during the execution of the loop. If it is defined, <step_expression> is evaluated each pass through the loop, so <step_expression> may be modified during execution of the loop.

In the 2-Series control systems, the <step_expression> cannot change its sign during the execution of the loop. That is, if it is initially a positive number, then it is assumed if it will always count up. If it is negative, it will always count down.

NOTE: If <variable> is set to a value greater than the <end_expression> within the body of the FOR loop, the FOR loop will exit when it reaches the end.

At the end of the loop, the loop index has the value of <end_expression> + 1 (unless the loop index was modified in the body of the loop).

The comparisons are based on signed numbers, the maximum loop size for a step of one would be from 1 to 32767. If larger indices are needed, for example, from 1 to 60000 a DO-UNTIL or WHILE loop could be used.

Language Reference Guide - DOC. 5797G SIMPL+® z 83

Software Crestron SIMPL+

Example:

STRING_INPUT IN$[100];

INTEGER X; FOR (X = 1 TO LEN(IN$)) {

PRINT(“Character %d of String %s is %s\n”, X, IN$, MID(IN$, X, 1));

}

In this example, the loop will iterate through each character of a string and print out the string and its position in the original string.

Version:

SIMPL+ Version 1.00

84 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

WHILE

Name:

WHILE

Syntax:

WHILE(<expression>)

[{]

[}]

Description:

This loop performs a set of <statements> as long as <expression> does not evaluate to zero.

If only one statement is present in the body of the loop, then the { and } characters are not required, but may be used. If more than one statement is present in the loop body, then the { and } characters are mandatory. Note that depending on <expression>, the body of the loop may never be executed. Note that <expression> is evaluated at the beginning of each time through the loop.

Example:

INTEGER X;

X=0; WHILE(X < 25) { X = X + 1; PRINT(“X = %d\n”, X); }

In this example, the loop will execute 25 times. The PRINT function will show the value of X after it is incremented to the computer port of the control system.

Version:

SIMPL+ Version 1.00

Language Reference Guide - DOC. 5797G SIMPL+® z 85

Software Crestron SIMPL+

Branching & Decision Constructs

BREAK

Name:

BREAK

Syntax:

BREAK;

Description:

Terminates the innermost DO-UNTIL, FOR, or WHILE loop before the exit condition is met. Execution resumes after the end of the bop.

Example:

INTEGER X;

ANALOG_INPUT Y; X=0; WHILE(X<25) {

IF(Y = 69) BREAK; X = X + 1; PRINT(“X=%d\n”, X);

}

In this example, the WHILE loop will terminate if the ANALOG_INPUT Y equals the value of 69. Otherwise, the loop will exit via the normal term ination condition.

Version:

SIMPL+ Version 1.00

86 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

CSWITCH

Name:

CSWITCH

Syntax:

CSWITCH (<expression>)

{ CASE (<unique integer constant>): [{] <statements1> [break;] [}]

CASE (<unique integer constant >): [{]

<statements2> [break;] [}]

[DEFAULT: [{]

<statements> [break;] [}] }

NOTE: In SIMPL+ v3.01.00 and later, the 'break' statement is required to terminate the case statement block that it resides within. If no 'break' statement exists, the program will continuing executing to the next case statement block or default statement block.

NOTE: Many CASE statements may be used in the body of the CSWITCH.

Description:

CSWITCH is a more direct method of writing a complex IF-ELSE-IF statement. In the CSWITCH, if <expression> is equal to a CASE’s constant, then the statement block for that CASE value is executed. This same method would apply to as many CASE statements as are listed in the body of the CSWITCH. Note that if any of the

Language Reference Guide - DOC. 5797G SIMPL+® z 87

Software Crestron SIMPL+

<statements> blocks are only a single statement, the { and } characters on the CASE may be omitted. If no condition is met in the CASE statements, the DEFAULT case, if specified, is used.

CSWITCH has the restriction that the case statement only contains unique integer constants. CSWITCH differs from SWITCH in that the operating system is able to evaluate and execute the CSWITCH statement faster. Therefore, you should use CSWITCH in place of SWITCH whenever unique constants are being evaluated.

Example:

ANALOG_INPUT AIN;

INTEGER X; CSWITCH( AIN ) { CASE (2): { X = 0; break; // terminate this case statement block }

CASE (3):

{

X = AIN; // continue executing to next case statement block ==>

case(5)

}

CASE (5):

{

X = X + AIN + 1; break;

}

DEFAULT:

{

PRINT(“Unknown command %d!\n”, AIN);

break; } }

In this example, if the value of AIN is 2, X is set equal to 0. If AI N is 3, X is set AIN + AIN + 1. If AIN is 5, X is set equal to AIN+1. If AIN is any oth e r value, an error message is printed.

88 z SIMPL+

Version:

SIMPL+ Version 3.00.05

Control System

2-Series Only

Language Reference Guide - DOC. 5797G

Crestron SIMPL+

Software

IF - ELSE

Name:

IF - ELSE

Syntax:

IF ( <expression>)

[{] <statements> [}]

[ELSE]

[{]

[}]]

Since <statements> can be an IF construct, you can string out a series of IF-ELSE-IF statements of the form:

IF (<expression>)

[{]

[}]

[ELSE] IF (<expression>) [{] <statements> [}]]

NOTE: A final ELSE may be used to express default handling if none of the previous conditions were met.

IF (<expression>) [{]

<statements> [}]

[ELSE] IF (<expression>) [{]

<statements> [}]

[ELSE] [{]

<statements> [}]

Language Reference Guide - DOC. 5797G SIMPL+® z 89

Software Crestron SIMPL+

Description:

Executes a piece of code only if its associated <expression> evaluates to true. Many expressions can be tested if the IF-ELSE-IF construct is used. Note that only one <statements> block in an IF-ELSE or IF-ELSE-IF construct is executed. In any section of the construct, if <statements> is only a single statement, then the { and } characters may be omitted.

Example:

STRING_INPUT IN$[100];

STRING Y$[100]; INTEGER X; IF (IN$ = “STRING1”) {

X=5; Y$ = IN$;

}

ELSE

{

X=6; Y$ = ““;

}

In this example, if IN$ is equal to STRING1, then the first two statements are executed. If IN$ is a different value, then the second groups of statements are evaluated. A more complex IF-ELSE-IF construct appears as:

IF (IN$ = “STRING1”)

{ X=5; Y$ = IN$; } ELSE IF (IN$=”STRING2”) { X=6; Y$ = ““; } ELSE { X = 7; Y$ = “ZZZ”; }

Version:

SIMPL+ Version 1.00

90 z SIMPL+

Language Reference Guide - DOC. 5797G

Crestron SIMPL PLUS LANGUAGE REF User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

SIMPL+ Language Reference Guide

Introduction

Software Requirements

Licensing of SIMPL+ Cross Compiler

What's New

Converting from an X-Generation to a 2-Series Target

X-Generation Target and 2-Series Target Differences

Programming Environment

Programming Environment Overview

Target Selection

Edit Preferences

Insert Category

General Information

Conventions Used

Variable Names

Comments

Relative Path Names for Files

Operators

Operators Overview

Signed vs Unsigned Arithmetic

Operator Precedence & Grouping

Numeric Formats

Task Switching

Task Switching for X-Generation (CNX) Control Systems

Task Switching for 2-Series Control Systems

Language Constructs & Functions

Language Constructs & Functions Overview

Arrays

Compiler Directives

#CRESTRON_LIBRARY

#DEFAULT_NONVOLATILE

#DEFAULT_VOLATILE

#DEFINE_CONSTANT

#HELP

#HELP_BEGIN … #HELP_END

#HINT

#IF_DEFINED … #ENDIF

#SYMBOL_NAME

#USER_LIBRARY

#IF_NOT_DEFINED … #ENDIF

Declarations

Declarations Overview

Fixed and Variable Size Arrays

ANALOG_INPUT

ANALOG_OUTPUT

BUFFER_INPUT

DIGITAL_INPUT

DIGITAL_OUTPUT

INTEGER

LONG_INTEGER

SIGNED_INTEGER

SIGNED_LONG_INTEGER

STRING

STRING_INPUT

STRING_OUTPUT

STRUCTURES

Nonvolatile

SendMail

EVENT

PUSH

Release

Stacked Events

WHILE

CSWITCH

IF - ELSE