Amx Netlinx Language Reference Guide

  • May 2020
  • PDF

This document was uploaded by user and they confirmed that they have the permission to share it. If you are author or own the copyright of this book, please report to us by using this DMCA report form. Report DMCA


Overview

Download & View Amx Netlinx Language Reference Guide as PDF for free.

More details

  • Words: 67,733
  • Pages: 246
Language Reference Guide

NetLinx Programming Language

NetLinx Programming

Document ID: 033-004-2255 Last Revised: 10/05/2006

Software License and Warranty Agreement LICENSE GRANT. AMX grants to Licensee the non-exclusive right to use the AMX Software in the manner described in this License. The AMX Software is licensed, not sold. This license does not grant Licensee the right to create derivative works of the AMX Software. The AMX Software consists of generally available programming and development software, product documentation, sample applications, tools and utilities, and miscellaneous technical information. Please refer to the README.TXT file on the compact disc or download for further information regarding the components of the AMX Software. The AMX Software is subject to restrictions on distribution described in this License Agreement. LICENSEE MAY NOT SUBLICENSE, RENT, OR LEASE THE AMX SOFTWARE. Licensee may not reverse engineer, decompile, or disassemble the AMX Software.

INTELLECTUAL PROPERTY. The AMX Software is owned by AMX and is protected by United States copyright laws, patent laws, international treaty provisions, and/or state of Texas trade secret laws. Licensee may make copies of the AMX Software solely for backup or archival purposes. Licensee may not copy the written materials accompanying the AMX Software.

TERMINATION. AMX RESERVES THE RIGHT, IN ITS SOLE DISCRETION, TO TERMINATE THIS LICENSE FOR ANY REASON AND UPON WRITTEN NOTICE TO LICENSEE. In the event that AMX terminates this License, the Licensee shall return or destroy all originals and copies of the AMX Software to AMX and certify in writing that all originals and copies have been returned or destroyed. PRE-RELEASE CODE.

Portions of the AMX Software may, from time to time, as identified in the AMX Software, include PRE-RELEASE CODE and such code may not be at the level of performance, compatibility and functionality of the final code. The PRE-RELEASE CODE may not operate correctly and may be substantially modified prior to final release or certain features may not be generally released. AMX is not obligated to make or support any PRE-RELEASE CODE. ALL PRE-RELEASE CODE IS PROVIDED "AS IS" WITH NO WARRANTIES. LIMITED WARRANTY. AMX warrants that the AMX Software will perform substantially in accordance with the accompanying written materials for a period of ninety (90) days from the date of receipt. AMX DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH REGARD TO THE AMX SOFTWARE. THIS LIMITED WARRANTY GIVES LICENSEE SPECIFIC LEGAL RIGHTS. Any supplements or updates to the AMX SOFTWARE, including without limitation, any (if any) service packs or hot fixes provided to Licensee after the expiration of the ninety (90) day Limited Warranty period are not covered by any warranty or condition, express, implied or statutory.

LICENSEE REMEDIES. AMX's entire liability and Licensee's exclusive remedy shall be repair or replacement of the AMX Software that does not meet AMX's Limited Warranty and which is returned to AMX. This Limited Warranty is void if failure of the AMX Software has resulted from accident, abuse, or misapplication. Any replacement AMX Software will be warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer. Outside the United States, these remedies may not available. NO LIABILITY FOR CONSEQUENTIAL DAMAGES. IN NO EVENT SHALL AMX BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS AMX SOFTWARE, EVEN IF AMX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO LICENSEE.

U.S. GOVERNMENT RESTRICTED RIGHTS. The AMX Software is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph ©(1)(ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.2277013 or subparagraphs ©(1) and (2) of the Commercial Computer Software Restricted Rights at 48 CFR 52.227-19, as applicable. SOFTWARE AND OTHER MATERIALS FROM AMX.COM MAY BE SUBJECT TO EXPORT CONTROL. The United States Export Control laws prohibit the export of certain technical data and software to certain territories. No software from this Site may be downloaded or exported (i) into (or to a national or resident of) Cuba, Iraq, Libya, North Korea, Iran, Syria, or any other country to which the United States has embargoed goods; or (ii) anyone on the United States Treasury Department's list of Specially Designated Nationals or the U.S. Commerce Department's Table of Deny Orders. AMX does not authorize the downloading or exporting of any software or technical data from this site to any jurisdiction prohibited by the United States Export Laws. This Agreement replaces and supersedes all previous AMX Software License Agreements and is governed by the laws of the State of Texas, and all disputes will be resolved in the courts in Collin County, Texas, USA. For any questions concerning this Agreement, or to contact AMX for any reason, please write: AMX, 3000 Research Drive, Richardson, TX 75082.

Table of Contents

Table of Contents Introduction ........................................................................................................1 Conventions Used in this Document ......................................................................... 1 Related Instruction Manuals...................................................................................... 1

NetLinx Programming Overview ........................................................................3 Defining the Superset ............................................................................................... 3 NetLinx vs. Axcess - Comparison by Structure.......................................................... 4 DEFINE_DEVICE.............................................................................................................. 4 DEFINE_CONSTANT ...................................................................................................... 4 DEFINE_VARIABLES........................................................................................................ 5 DEFINE_CALL (Subroutines) ........................................................................................... 6 DEFINE_START ............................................................................................................... 7 DEFINE_EVENT .............................................................................................................. 7 DEFINE_PROGRAM ........................................................................................................ 8

Operators ................................................................................................................. 8 Axcess/NetLinx Incompatibility................................................................................. 9 Data Types.............................................................................................................. 10 Constants................................................................................................................ 10 Variables ................................................................................................................. 11 Persistent Variables ................................................................................................ 12 Arrays ..................................................................................................................... 12 Structures ............................................................................................................... 14 Data sets ....................................................................................................................... 15

Conditionals & Loops.............................................................................................. 17 SWITCH...CASE statements........................................................................................... 17 FOR loops ..................................................................................................................... 18

Functions ................................................................................................................ 19 DEFINE_CALL................................................................................................................ 19 DEFINE_FUNCTION ...................................................................................................... 20

Events ..................................................................................................................... 21 Button Events................................................................................................................ 21 Channel Events.............................................................................................................. 22 Data Events ................................................................................................................... 24 Level Events .................................................................................................................. 27

Combining Devices, Channels and Levels ............................................................... 28 Virtual devices, levels and device/channel sets ............................................................. 28 Combining and uncombining devices............................................................................ 28 Combining and uncombining levels............................................................................... 28

NetLinx Programming Language Reference Guide

i

Table of Contents

Combining and uncombining channels .......................................................................... 29

String Comparisons................................................................................................. 29 Axcess code - string comparison ................................................................................... 29 Netlinx code - string comparison .................................................................................. 29

Modules .................................................................................................................. 29

Language Elements ..........................................................................................31 Statements and Expressions ................................................................................... 31 Assignments............................................................................................................ 31 Variables........................................................................................................................ 31 Output channels ............................................................................................................ 31

Conditionals ............................................................................................................ 32 IF…ELSE ........................................................................................................................ 32 SELECT…ACTIVE........................................................................................................... 32 SWITCH…CASE ............................................................................................................. 33

Loops ...................................................................................................................... 34 WHILE statements ......................................................................................................... 34 MEDIUM_WHILE statements ......................................................................................... 34 LONG_WHILE statements ............................................................................................. 35 FOR loop structure ........................................................................................................ 35

Waits....................................................................................................................... 36 Naming Waits ................................................................................................................ 36 Types of Waits............................................................................................................... 36 Nesting Waits ................................................................................................................ 37 Pausing and restarting Waits......................................................................................... 38 Canceling Waits............................................................................................................. 38 Using Waits - Limitations ............................................................................................... 38

Comments............................................................................................................... 39 Operators ............................................................................................................... 39 Arithmetic operators ..................................................................................................... 39 Relational operators ...................................................................................................... 39 Logical operators .......................................................................................................... 40 Bitwise operators .......................................................................................................... 40 Assignment operators ................................................................................................... 40 Operator precedence .................................................................................................... 41

Identifiers................................................................................................................ 41 Devices .......................................................................................................................... 41 Device arrays ................................................................................................................. 42 Device array examples .................................................................................................. 43 Device-channels and device-channel arrays ................................................................... 43 Device-level arrays ........................................................................................................ 44

ii

NetLinx Programming Language Reference Guide

Table of Contents

Variables ................................................................................................................. 45 Scope ............................................................................................................................ 45 Local variables............................................................................................................... 45 Global variables............................................................................................................. 47 Constancy...................................................................................................................... 48 Persistence .................................................................................................................... 48

Constants................................................................................................................ 49 Data Types.............................................................................................................. 50 Intrinsic types ................................................................................................................ 50 Type conversion ............................................................................................................ 50 Type conversion rules.................................................................................................... 50

Strings .................................................................................................................... 51 String expressions ......................................................................................................... 51 Wide strings .................................................................................................................. 51

Arrays .................................................................................................................... 52 Multi-dimensional arrays ............................................................................................... 53

Structures ............................................................................................................... 55 Subroutines............................................................................................................. 56 DEFINE_CALL subroutines ............................................................................................ 56 SYSTEM_CALL subroutines ........................................................................................... 56 Function Subroutines .................................................................................................... 57 Calling parameters ........................................................................................................ 59

Event Handlers .................................................................................................61 Button events................................................................................................................ 62 Channel events.............................................................................................................. 63 Data events ................................................................................................................... 64 Level events .................................................................................................................. 65 Custom events .............................................................................................................. 67 Event Parameters .......................................................................................................... 68

Timeline Functions .................................................................................................. 71 Creating a timeline........................................................................................................ 71 TIMELINE example ........................................................................................................ 74 TIMELINE IDs ................................................................................................................ 78

Combining Devices, Levels, and Channels ........................................................79 Combining and Un-Combining Devices................................................................... 79 Combining devices ........................................................................................................ 79 Un-combining devices ................................................................................................... 81

Combining and Un-Combining Levels ..................................................................... 82 Combining levels........................................................................................................... 83

NetLinx Programming Language Reference Guide

iii

Table of Contents

Un-combining levels ...................................................................................................... 83

Combining and Un-combining Channels ................................................................. 84 Combining channels ...................................................................................................... 84 Un-combining channels.................................................................................................. 84

Master-To-Master (M2M) ..................................................................................91 Master Routing ....................................................................................................... 92 Design considerations and constraints .......................................................................... 93

Control/NetLinx Language Support........................................................................ 95 Design considerations and constraints .......................................................................... 95 General Master-to-Master Issues................................................................................... 95

Mainline ............................................................................................................97 Reserved Identifiers ..........................................................................................99 Compiler Directives ................................................................................................ 99 #DEFINE ................................................................................................................................ 99 #END_IF ................................................................................................................................ 99 #ELSE .................................................................................................................................... 99 #IF_DEFINED ........................................................................................................................ 99 #IF_NOT_DEFINED ............................................................................................................... 99

Keywords & Run-Time Library Functions............................................................... 100 __DATE__ ............................................................................................................................ 100 __FILE__ .............................................................................................................................. 100 __LDATE__ .......................................................................................................................... 100 __LINE__ ............................................................................................................................. 100 __NAME__ ........................................................................................................................... 100 __TIME__ ............................................................................................................................. 100 ABS_VALUE ........................................................................................................................ 100 ACTIVE ................................................................................................................................ 100 #INCLUDE ........................................................................................................................... 100 #WARN ................................................................................................................................ 100 ADD_URL_ENTRY .............................................................................................................. 101 AND (&&) ............................................................................................................................. 101 ASTRO_CLOCK .................................................................................................................. 101 ATOI ..................................................................................................................................... 102 ATOF .................................................................................................................................... 102 ATOL .................................................................................................................................... 102 BAND (&) ............................................................................................................................. 102 BNOT (~) .............................................................................................................................. 102 BOR (|) ................................................................................................................................. 102 BREAK ................................................................................................................................. 103 BUTTON_EVENT ................................................................................................................ 103 BXOR (^) .............................................................................................................................. 103 CALL .................................................................................................................................... 103 CANCEL_ALL_WAIT ........................................................................................................... 103 CANCEL_ALL_WAIT_UNTIL ............................................................................................... 103 CANCEL_WAIT .................................................................................................................... 103 CANCEL_WAIT_UNTIL ....................................................................................................... 104 CASE ................................................................................................................................... 104 CHANNEL_EVENT .............................................................................................................. 104

iv

NetLinx Programming Language Reference Guide

Table of Contents

CHAR ................................................................................................................................... 104 CHARD ................................................................................................................................ 104 CHARDM ............................................................................................................................. 104 CLEAR_BUFFER ................................................................................................................. 104 CLKMGR_ADD_USERDEFINED_TIMESERVER ............................................................... 105 CLKMGR_DELETE_USERDEFINED_TIMESERVER ......................................................... 105 CLKMGR_GET_ACTIVE_TIMESERVER ............................................................................ 105 CLKMGR_GET_DAYLIGHTSAVINGS_OFFSET ................................................................ 105 CLKMGR_GET_END_DAYLIGHTSAVINGS_RULE ........................................................... 105 CLKMGR_GET_RESYNC_PERIOD .................................................................................... 105 CLKMGR_GET_START_DAYLIGHTSAVINGS_RULE ....................................................... 105 CLKMGR_GET_TIMESERVERS ......................................................................................... 106 CLKMGR_GET_TIMEZONE ................................................................................................ 106 CLKMGR_IS_DAYLIGHTSAVINGS_ON ............................................................................. 106 CLKMGR_IS_NETWORK_SOURCED ................................................................................ 106 CLKMGR_SET_ACTIVE_TIMESERVER ............................................................................ 106 CLKMGR_SET_CLK_SOURCE .......................................................................................... 106 CLKMGR_SET_DAYLIGHTSAVINGS_MODE .................................................................... 106 CLKMGR_SET_DAYLIGHTSAVINGS_OFFSET ................................................................. 106 CLKMGR_SET_END_DAYLIGHTSAVINGS_RULE ............................................................ 106 CLKMGR_SET_RESYNC_PERIOD .................................................................................... 107 CLKMGR_SET_START_DAYLIGHTSAVINGS_RULE ....................................................... 107 CLKMGR_SET_TIMEZONE ................................................................................................ 107 CLOCK ................................................................................................................................. 107 COMBINE_CHANNELS ....................................................................................................... 107 COMBINE_DEVICES ........................................................................................................... 108 COMBINE_LEVELS ............................................................................................................. 108 COMMAND .......................................................................................................................... 108 COMPARE_STRING ........................................................................................................... 109 CONSTANT ......................................................................................................................... 109 CREATE_BUFFER .............................................................................................................. 109 CREATE_LEVEL ................................................................................................................. 110 CREATE_MULTI_BUFFER ................................................................................................. 110 DATA_EVENT ...................................................................................................................... 111 DATE .................................................................................................................................... 112 DAY ...................................................................................................................................... 112 DATE_TO_DAY ................................................................................................................... 112 DATE_TO_MONTH ............................................................................................................. 112 DATE_TO_YEAR ................................................................................................................. 112 DAY_OF_WEEK .................................................................................................................. 112 DEFAULT ............................................................................................................................. 112 DEFINE_CALL ..................................................................................................................... 113 DEFINE_COMBINE ............................................................................................................. 113 DEFINE_CONNECT_LEVEL ............................................................................................... 113 DEFINE_CONSTANT .......................................................................................................... 113 DEFINE_DEVICE ................................................................................................................. 114 DEFINE_EVENT .................................................................................................................. 114 DEFINE_FUNCTION ........................................................................................................... 114 DEFINE_LATCHING ............................................................................................................ 114 DEFINE_MODULE ............................................................................................................... 114 DEFINE_MUTUALLY_EXCLUSIVE ..................................................................................... 115 DEFINE_PROGRAM ........................................................................................................... 115 DEFINE_START .................................................................................................................. 115 DEFINE_TOGGLING ........................................................................................................... 115

NetLinx Programming Language Reference Guide

v

Table of Contents

DEFINE_TYPE ..................................................................................................................... 115 DEFINE_VARIABLE ............................................................................................................ 116 DELETE_URL_ENTRY ........................................................................................................ 116 DEV ...................................................................................................................................... 116 DEVCHAN ............................................................................................................................ 116 DEVICE_ID .......................................................................................................................... 116 DEVICE_ID_STRING ........................................................................................................... 116 DEVICE_INFO ..................................................................................................................... 117 DEVLEV ............................................................................................................................... 118 DO_PUSH ............................................................................................................................ 119 DO_PUSH_TIMED ............................................................................................................... 119 DO_RELEASE ..................................................................................................................... 119 DOUBLE .............................................................................................................................. 119 DUET_MEM_SIZE_GET ...................................................................................................... 119 DUET_MEM_SIZE_SET ...................................................................................................... 119 ELSE .................................................................................................................................... 119 FALSE .................................................................................................................................. 119 FILE_CLOSE ....................................................................................................................... 120 FILE_COPY ......................................................................................................................... 120 FILE_CREATEDIR ............................................................................................................... 121 FILE_DELETE ...................................................................................................................... 121 FILE_DIR ............................................................................................................................. 121 FILE_GETDIR ...................................................................................................................... 122 FILE_OPEN ......................................................................................................................... 122 FILE_READ .......................................................................................................................... 123 FILE_READ_LINE ................................................................................................................ 123 FILE_REMOVEDIR .............................................................................................................. 124 FILE_RENAME .................................................................................................................... 124 FILE_SEEK .......................................................................................................................... 124 FILE_SETDIR ...................................................................................................................... 125 FILE_WRITE ........................................................................................................................ 125 FILE_WRITE_LINE .............................................................................................................. 125 FIND_STRING ..................................................................................................................... 126 FIRST_LOCAL_PORT ......................................................................................................... 126 FLOAT .................................................................................................................................. 126 FOR ...................................................................................................................................... 126 FORMAT .............................................................................................................................. 127 FTOA .................................................................................................................................... 128 GET_BUFFER_CHAR ......................................................................................................... 128 GET_BUFFER_STRING ...................................................................................................... 128 GET_DNS_LIST ................................................................................................................... 129 GET_IP_ADDRESS ............................................................................................................. 129 GET_LAST ........................................................................................................................... 130 GET_MULTI_BUFFER_STRING ......................................................................................... 131 GET_PULSE_TIME ............................................................................................................. 131 GET_SERIAL_NUMBER ..................................................................................................... 131 GET_SYSTEM_NUMBER ................................................................................................... 131 GET_TIMER ......................................................................................................................... 131 GET_UNIQUE_ID ................................................................................................................ 131 GET_URL_LIST ................................................................................................................... 132 HEXTOI ................................................................................................................................ 133 HOLD ................................................................................................................................... 134 IF .......................................................................................................................................... 134 INCLUDE ............................................................................................................................. 134

vi

NetLinx Programming Language Reference Guide

Table of Contents

INTEGER ............................................................................................................................. 134 IP_CLIENT_CLOSE ............................................................................................................. 134 IP_CLIENT_OPEN ............................................................................................................... 135 IP_MC_SERVER_OPEN ..................................................................................................... 136 IP_SERVER_CLOSE ........................................................................................................... 136 IP_SERVER_OPEN ............................................................................................................. 137 ITOA ..................................................................................................................................... 137 ITOHEX ................................................................................................................................ 137 LDATE .................................................................................................................................. 137 LEFT_STRING ..................................................................................................................... 138 LENGTH_ARRAY ................................................................................................................ 138 LENGTH_STRING ............................................................................................................... 139 LENGTH_VARIABLE_TO_STRING (VARIABLE Encode) .................................................. 139 LENGTH_VARIABLE_TO_XML ........................................................................................... 139 LEVEL_EVENT .................................................................................................................... 139 LOCAL_VAR ........................................................................................................................ 139 LONG ................................................................................................................................... 139 LONG_WHILE ...................................................................................................................... 140 LOWER_STRING ................................................................................................................ 140 LSHIFT ................................................................................................................................. 140 MASTER_SN ....................................................................................................................... 140 MASTER_SLOT ................................................................................................................... 140 MAX_VALUE ........................................................................................................................ 140 MAX_LENGTH_ARRAY ...................................................................................................... 140 MAX_LENGTH_STRING ..................................................................................................... 141 MEDIUM_WHILE ................................................................................................................. 141 MID_STRING ....................................................................................................................... 141 MIN_VALUE ......................................................................................................................... 141 MIN_TO ................................................................................................................................ 141 MOD (%) .............................................................................................................................. 142 MODULE_NAME ................................................................................................................. 142 NOT (!) ................................................................................................................................. 142 NON_VOLATILE .................................................................................................................. 142 OFF ...................................................................................................................................... 142 OFFLINE .............................................................................................................................. 142 ON ........................................................................................................................................ 142 ONERROR ........................................................................................................................... 142 ONLINE ................................................................................................................................ 142 OR (||) .................................................................................................................................. 142 PAUSE_ALL_WAIT .............................................................................................................. 142 PAUSE_WAIT ...................................................................................................................... 142 PERSISTENT ....................................................................................................................... 143 PROGRAM_NAME .............................................................................................................. 143 PULSE ................................................................................................................................. 143 PUSH ................................................................................................................................... 143 PUSH_CHANNEL ................................................................................................................ 143 PUSH_DEVCHAN ................................................................................................................ 143 PUSH_DEVICE .................................................................................................................... 143 RANDOM_NUMBER ............................................................................................................ 143 RAW_BE .............................................................................................................................. 143 RAW_LE .............................................................................................................................. 143 REBOOT .............................................................................................................................. 144 REBUILD_EVENT() ............................................................................................................. 144 REDIRECT_STRING ........................................................................................................... 146

NetLinx Programming Language Reference Guide

vii

Table of Contents

RELEASE ............................................................................................................................. 146 RELEASE_CHANNEL ......................................................................................................... 146 RELEASE_DEVCHAN ......................................................................................................... 146 RELEASE_DEVICE ............................................................................................................. 146 REMOVE_STRING .............................................................................................................. 147 REPEAT ............................................................................................................................... 147 RESTART_ALL_WAIT ......................................................................................................... 147 RESTART_WAIT ................................................................................................................. 147 RETURN .............................................................................................................................. 147 RIGHT_STRING .................................................................................................................. 147 RSHIFT ................................................................................................................................ 148 SELECT…ACTIVE ............................................................................................................... 148 SEND_COMMAND .............................................................................................................. 148 SEND_LEVEL ...................................................................................................................... 148 SEND_STRING .................................................................................................................... 148 SET_DNS_LIST ................................................................................................................... 149 SET_IP_ADDRESS ............................................................................................................. 149 SET_LENGTH_ARRAY ....................................................................................................... 150 SET_LENGTH_STRING ...................................................................................................... 150 SET_OUTDOOR_TEMPERATURE ..................................................................................... 150 SET_PULSE_TIME .............................................................................................................. 150 SET_SYSTEM_NUMBER .................................................................................................... 151 SET_TIMER ......................................................................................................................... 151 SET_VIRTUAL_CHANNEL_COUNT ................................................................................... 151 SET_VIRTUAL_LEVEL_COUNT ......................................................................................... 151 SET_VIRTUAL_PORT_COUNT .......................................................................................... 151 SINTEGER ........................................................................................................................... 151 SLONG ................................................................................................................................. 151 STACK_VAR ........................................................................................................................ 152 STRING ................................................................................................................................ 152 STRING_TO_VARIABLE (VARIABLE DECODE) ................................................................ 152 STRUCTURE ....................................................................................................................... 152 SWITCH...CASE .................................................................................................................. 153 SYSTEM_CALL ................................................................................................................... 153 SYSTEM_NUMBER ............................................................................................................. 153 TIME ..................................................................................................................................... 153 TIME_TO_HOUR ................................................................................................................. 153 TIME_TO_MINUTE .............................................................................................................. 153 TIME_TO_SECOND ............................................................................................................ 154 TIMED_WAIT_UNTIL ........................................................................................................... 154 TIMELINE_ACTIVE .............................................................................................................. 154 TIMELINE_CREATE ............................................................................................................ 154 TIMELINE_EVENT ............................................................................................................... 155 TIMELINE_GET ................................................................................................................... 155 TIMELINE_KILL ................................................................................................................... 155 TIMELINE_PAUSE .............................................................................................................. 155 TIMELINE_RELOAD ............................................................................................................ 156 TIMELINE_RESTART .......................................................................................................... 156 TIMELINE_SET .................................................................................................................... 156 TO ........................................................................................................................................ 157 TOTAL_OFF ........................................................................................................................ 157 TRUE ................................................................................................................................... 157 TYPE_CAST ........................................................................................................................ 157 UNCOMBINE_CHANNELS .................................................................................................. 157

viii

NetLinx Programming Language Reference Guide

Table of Contents

UNCOMBINE_DEVICES ..................................................................................................... 157 UNCOMBINE_LEVELS ........................................................................................................ 158 UPPER_STRING ................................................................................................................. 158 VARIABLE_TO_STRING (VARIABLE ENCODE) ................................................................ 158 VARIABLE_TO_XML ........................................................................................................... 159 VOLATILE ............................................................................................................................ 161 WAIT .................................................................................................................................... 161 WAIT_UNTIL ........................................................................................................................ 161 WHILE .................................................................................................................................. 161 WIDECHAR .......................................................................................................................... 161 XML_TO_VARIABLE ........................................................................................................... 162

Send_Commands .................................................................................................. 164 DEFINE_MUTUALLY_EXCLUSIVE and Variables.......................................................... 164 XOR (^^) ............................................................................................................................... 164

Compiler Messages ........................................................................................167 Compiler Warnings ............................................................................................... 167 (w) Cannot assign unlike types .................................................................................... 167 (w) Define_Call is not used .......................................................................................... 167 (w) Integer applies to arrays only ................................................................................ 167 (w) Long_While within While ....................................................................................... 167 (w) Possibly too many nested levels ............................................................................ 167 (w) Variable is not used ............................................................................................... 168

Compiler Errors .................................................................................................... 168 A "<symbol>" was expected ...................................................................................... 168 ACTIVE keyword expected ......................................................................................... 168 Allowed only in DEFINE_START .................................................................................. 168 Attempted CALL to undefined subroutine .................................................................. 168 Comment never ends, EOF encountered .................................................................... 168 Conditional compile nesting too deep ........................................................................ 168 Constant type not allowed .......................................................................................... 168 DEFINE_CALL must have a name ................................................................................ 168 DEFINE_CALL name already used ............................................................................... 168 Device values must be equal ....................................................................................... 168 Duplicate symbol......................................................................................................... 168 Evaluation stack overflow ........................................................................................... 169 Evaluation stack underflow ......................................................................................... 169 Identifier expected...................................................................................................... 169 Identifier is not an array type ...................................................................................... 169 Include file not found .................................................................................................. 169 Invalid include file name.............................................................................................. 169 Library file not found .................................................................................................. 169 Maximum string length exceeded............................................................................... 169 Must be char array reference ...................................................................................... 169

NetLinx Programming Language Reference Guide

ix

Table of Contents

Must be integer reference........................................................................................... 169 Out of memory............................................................................................................ 169 Parameter mismatch in CALL....................................................................................... 169 Program_Name must be on line 1 ............................................................................... 169 Push/Release not allowed within Push/Release ........................................................... 169 Push/Release not allowed within Wait......................................................................... 169 PUSH_CHANNEL not allowed within Wait .................................................................. 170 RELEASE_CHANNEL not allowed within Wait............................................................. 170 PUSH_DEVICE not allowed within Wait....................................................................... 170 RELEASE_DEVICE not allowed within Wait ................................................................. 170 String constant expected ............................................................................................ 170 String constant never ends, EOF encountered............................................................ 170 String literal expected................................................................................................. 170 Subroutine may not call itself ...................................................................................... 170 Syntax error................................................................................................................. 170 SYSTEM_CALL name not same as PROGRAM_NAME in ................................... 170 This variable type not allowed .................................................................................... 170 TO statements that occur outside the data flow of PUSH events/statements may not work 170 Too few parameters in CALL ....................................................................................... 171 Too many include files ................................................................................................. 171 Too many parameters in CALL .................................................................................... 171 Type mismatch in function CALL ................................................................................. 171 Undefined identifier .................................................................................................... 171 Unmatched #END_IF ................................................................................................... 171 Unrecognized character in input file............................................................................ 171 Use SYSTEM_CALL [instance] 'name'........................................................................... 171 Variable assignment not allowed here ........................................................................ 171 Wait not found ............................................................................................................ 171

Run-Time Errors .................................................................................................... 171 Bad assign 2dim... ....................................................................................................... 171 Bad assign Call... ......................................................................................................... 172 Bad element assign... .................................................................................................. 172 Bad Off... Bad On... Bad To......................................................................................... 172 Bad re-assign Call... ..................................................................................................... 172 Bad run token.............................................................................................................. 172 Bad Set_Length... ........................................................................................................ 172 Bad While .................................................................................................................... 172

NetLinx UniCode Functions ............................................................................173 Overview .............................................................................................................. 173

x

NetLinx Programming Language Reference Guide

Table of Contents

_WC ..................................................................................................................................... 173 CH_TO_WC ......................................................................................................................... 173 WC_COMPARE_STRING ................................................................................................... 173 WC_CONCAT_STRING ...................................................................................................... 173 WC_DECODE ...................................................................................................................... 174 WC_ENCODE ...................................................................................................................... 174 WC_FILE_CLOSE ............................................................................................................... 175 WC_FILE_OPEN ................................................................................................................. 176 WC_FILE_READ .................................................................................................................. 177 WC_FILE_READ_LINE ........................................................................................................ 177 WC_FILE_WRITE ................................................................................................................ 178 WC_FILE_WRITE_LINE ...................................................................................................... 178 WC_FIND_STRING ............................................................................................................. 178 WC_GET_BUFFER_CHAR ................................................................................................. 179 WC_GET_BUFFER_STRING .............................................................................................. 179 WC_LEFT_STRING ............................................................................................................. 179 WC_LENGTH_STRING ....................................................................................................... 179 WC_LOWER_STRING ........................................................................................................ 180 WC_MAX_LENGTH_STRING ............................................................................................. 180 WC_MID_STRING ............................................................................................................... 180 WC_REMOVE_STRING ...................................................................................................... 180 WC_RIGHT_STRING .......................................................................................................... 181 WC_SET_LENGTH_STRING .............................................................................................. 181 WC_TO_CH ......................................................................................................................... 181 WC_TP_ENCODE ............................................................................................................... 181 WC_UPPER_STRING ......................................................................................................... 181

Working With UniCode in NetLinx Studio v2.4..................................................... 182 Configuring NetLinx Studio......................................................................................... 182 Including the Unicode Library ..................................................................................... 183 Defining a Unicode String Literal ................................................................................ 183 Storing a Unicode String ............................................................................................. 184 Working with WIDECHAR arrays and Unicode Strings ................................................ 184 Character Case Mappings ........................................................................................... 185 Concatenating String .................................................................................................. 185 Converting between WIDECHAR and CHAR ............................................................... 185 Using FORMAT............................................................................................................ 185 Reading and Writing to Files....................................................................................... 186 Send strings to a User Interface .................................................................................. 186 Right-to-Left Unicode Strings...................................................................................... 186 Compiler Errors ........................................................................................................... 187

IP Communication ..........................................................................................189 Client Programming.............................................................................................. 189 Initiating a conversation .............................................................................................. 189 Terminating a conversation ......................................................................................... 190 Sending data ............................................................................................................... 190 Receiving data............................................................................................................. 190

NetLinx Programming Language Reference Guide

xi

Table of Contents

Server Programming ............................................................................................. 191 Listening for client requests ........................................................................................ 191 Multiple client connections.......................................................................................... 192 Closing a local port ..................................................................................................... 192 Connection-oriented notifications ............................................................................... 192 Receiving data............................................................................................................. 193 Sending data ............................................................................................................... 193 Receiving Data with UDP ............................................................................................ 193 Multicast...................................................................................................................... 194 Example IP Code ......................................................................................................... 194

NetLinx Modules ............................................................................................197 Defining a module ....................................................................................................... 197 Using a module in a program ...................................................................................... 204

Internet Inside ................................................................................................207 Java TPClasses............................................................................................................. 207 WDM Configuration .................................................................................................... 208

Encoding and Decoding: Binary and XML ......................................................209 Appendix A: Marshalling Protocol ..................................................................215 Marshalling Protocol (Group of Bytes) .................................................................. 215 Marshalled Stream Format .......................................................................................... 215

Marshalling Protocol (Variables) ........................................................................... 217 Marshalled Stream format ........................................................................................... 217 Encoding notes:........................................................................................................... 219 String encoding ........................................................................................................... 219 Binary array encoding.................................................................................................. 219 Binary Encoding Result................................................................................................ 221 XML Encoding Result .................................................................................................. 223

Appendix B: Glossary .....................................................................................225

xii

NetLinx Programming Language Reference Guide

Table of Contents

NetLinx Programming Language Reference Guide

xiii

Table of Contents

xiv

NetLinx Programming Language Reference Guide

Introduction

Introduction NetLinx® is the second generation of the Axcess® programming language and is a superset of the original Axcess language with extensions for additional data types, new event handlers, structure support, multi-dimensional arrays, and other features. This document assumes that you are familiar with Axcess; the focus is on the new language elements and how they extend the functionality of the existing language. For background information on Axcess, refer to the Axcess Programming Language instruction manual. For a side-by-side comparison of programming in Axcess and NetLinx, refer to the NetLinx Programming Overview section on page 3.

Conventions Used in this Document NetLinx contains a number of keywords that define various available operations to perform in a NetLinx command, such as the word CALL in the statement: CALL 'Read Data' (Buffer)

Keywords are case insensitive. For example, the PUSH command is the same as push. Keywords are reserved, meaning that identifiers (device names, constants, or variables) must have unique names. These keywords are listed and defined in the Reserved Identifiers section on page 99. All references to NetLinx language keywords in this document appear in THE FONT SHOWN HERE, in all capital letters. Programming examples appear in the same fixed font. For example: DEFINE_VARIABLE CHAR MyString[32] INTEGER StrLen

Square brackets indicate an optional element in a command. Angle brackets indicate substitution. In the example below, the notation indicates that a valid data type (such as CHAR, INTEGER, or FLOAT) must be substituted for . The square brackets surrounding it indicate that the return type is optional. DEFINE_FUNCTION [] [(Param1, Param2, …)] { (* body of subroutine *) }

Related Instruction Manuals These instruction manuals contain additional information that relates to the NetLinx Programming Language: Axcess Programming Language Instruction Manual NetLinx Studio Program Instruction Manual

NetLinx Programming Language Reference Guide

1

Introduction

2

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

NetLinx Programming Overview The NetLinx control system was designed to upgrade the processor bus and improve the power of the Axcess programming language. Originally named Axcess2, the NetLinx was designed to be a superset of the Axcess programming language. The relationship between the new language (NetLinx) and Axcess is very similar to the relationship between C++ and C. Just as C++ brought a whole new level of power to C programming, NetLinx offers a variety of new tools and commands to dynamically increase the speed and power of present and future applications. Use the NetLinx Studio software program to create, compile, and transfer Axcess/ NetLinx code.

Defining the Superset NetLinx contains all of the elements of Axcess. Largely, you can use the same code from Axcess systems in NetLinx systems. Some exceptions include variable names conflicting with new NetLinx keywords; however, Axcess keywords are valid in NetLinx. You cannot compile NetLinx code on an Axcess compiler, or download NetLinx code to an Axcess control system. To upgrade an existing Axcess control system to NetLinx you must upgrade the Axcess Master to a NetLinx Master. You can still use the existing Axcess equipment as long as you can disable the existing Axcess Central Controller. The exceptions are the Axcent, the Axcent2, the AXB-EM232, and the AXB-MPE+ Master Port Expander. None of these integrated controllers allow you to disable the Central Controller. Both Axcess Card Frame Systems and Axcent3 systems allow you to either remove or disable the Axcess Central Controller. If you are using an Axcent3 / Axcent3 Pro, you can disable the Master with the OpenAxcess program. You can connect the Axcent3 / Axcent3 Pro to a NetLinx Master Module via AXlink. Then you can compile and download the existing Axcess code.

Several Axcess control limitations have been fixed in NetLinx. NetLinx expands the types of data and variables from Axcess. NetLinx provides multiple processes and event threads beyond the Mainline in Axcess. NetLinx offers more options in distributed processing. NetLinx expands and strengthens Master-to-Master communications and expands the traditional AXlink bus to include ICSNet and Ethernet Network communications. Axcess is linear in its process. At run time, Axcess runs the DEFINE_START code once when the system is loaded or restarted. Axcess then makes a pass through mainline code, polls the bus for activity, checks the wait and pulse stacks, and repeats the process again. The length of mainline and the activity on the bus affect runtime speeds. The mainline process is considered a single thread. NetLinx runs on multiple threads; mainline and event handlers run on parallel threads. Event handlers are defined within NetLinx and operate like mini-mainlines. They contain far less code and run faster than mainline. If an event occurs, and an event handler has been defined for that event, NetLinx bypasses mainline and runs the event handler.

NetLinx Programming Language Reference Guide

3

NetLinx Programming Overview

NetLinx vs. Axcess - Comparison by Structure DEFINE_DEVICE Axcess Language

NetLinx Language

Axcess defines devices with a single number (some- NetLinx defines the device by Device:Port:System. times called an address) from 1 to 255. Axcess per- • Device is a 16-bit integer representing the device mits a maximum of 255 devices on the AXlink bus. number. Physical devices range from 1 to 32,767. Virtual devices range from 32,768 to 36,863. DEFINE_DEVICE VCR = 1 (* AXC-IRS *) Note: These numbers do not seem so random when VPROJ= 2 (* AXC-IRS *) represented in hexadecimal. Physical devices range from $0001 to $7FFF. Virtual devices range from TP = 128 (* AXT-CA10*) $8000 to $8FFF. • Port is a 16-bit integer representing the port number in a range of 1 through the number of ports on the device. • System is a 16-bit integer representing the system number (0 indicates this system). DEFINE_DEVICE VCR = 1:1:0 (* NXC-IRS4 PORT 1 *) VPROJ= 1:2:0 (* PORT 2 *) TP = 128:1:0 (* AXT-CA10 *)

DEFINE_CONSTANT Axcess Language

NetLinx Language

Axcess defines constants as either a fixed integer value between 0 and 65,535 or an array with a maximum length of 255 bytes in which each element can hold a value from 0 to 255. These values can be expressed in ASCII, Decimal, or Hexadecimal.

NetLinx processes constants just like Axcess. NetLinx also allows you to define an expression in the DEFINE_CONSTANT section. The expression cannot contain any variables.

DEFINE_CONSTANT VALUE_MAX = 140 DEFAULT_NAME = 'Axcess' ETX = "$FE,$FF" VALUE_MAX = VALUE_MIN + 100

4

DEFINE_CONSTANT VALUE_MIN = 40 DEFAULT_NAME = 'Axcess' ETX [] = {$FE,$FF} VALUE_MAX = VALUE_MIN + 100

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

DEFINE_VARIABLES Axcess Language

NetLinx Language

Axcess supports 5 types of variables:

NetLinx substantially increased the number of supported variable types. In addition to more data types, NetLinx also supports Sets, Structures, and Multi-dimensional arrays.

• Integer Variables (default) can contain a value from 0 to 65,535.

• Character Arrays are single element arrays, in which each element has a value from 0 to 255 with Arrays default to Character Arrays. Variables default to Integer Variables. Variables default to Non-Volatile, but a maximum of 255 elements can be set as Non-Volatile or Volatile (Volatile variables • 2-Dimensional Arrays equate to a maximum of are initialized when code is loaded or when the system 255 single element character arrays. Each is reset). element can have a value from 0 to 255. DEFINE_VARIABLE • Integer Arrays are single element arrays, in which CHAR VALUE1 each element can contain a value from 0 to 65,535 WIDECHAR BIGCHAR with a maximum of 255 elements INTEGER VALUE2 • 2-Dimensional Integer Arrays may have a SINTEGER SIGNED1 maximum value of 65,535. LONG BIGVALUE Variables are Non-Volatile (the variable loses its SLONG SIGNED2 value when the program is loaded, but retains its FLOAT DECIMAL value if the controller is reset). DOUBLE VERYBIGVALUE DEFINE_VARIABLE INTEGER ARRAY[3][3][3] VALUE VOLATILE INTEGER RESET_VAR ARRAY[3] ARRAY_2DIM[4][6] INTEGER INT_ARRAY[6]

NetLinx Programming Language Reference Guide

5

NetLinx Programming Overview

DEFINE_CALL (Subroutines) Axcess Language

NetLinx Language

Axcess provides two methods for incorporating sub- Like Axcess, NetLinx supports DEFINE_CALL and SYSTEM_CALL. NetLinx also supports functions, which routines into your program. are similar to a DEFINE_CALL(s). They can be used • DEFINE_CALL subroutines are defined in the standalone or in-line as an expression. program and support parameter passing into the call. Changing the parameter value inside the call changes the value of the variable passed to the parameter. The DEFINE_CALL can use global variables or defined local variables. DEFINE_CALL is for standalone statements and cannot be used in-line as an expression. • SYSTEM_CALL is an externally defined subroutine with a '.LIB' extension. SYSTEM_CALL programs are produced by AMX and are available on CD-ROM and on the Tech Support Web site at www.amx.com. DEFINE_CALL 'SWITCH' (CARD,IN,OUT) { SEND_STRING CARD, "ITOA(IN),'*',ITOA(OUT),'!'" } DEFINE_CALL 'MULTIPLY' (X,Y,RESULT) { RESULT = X * Y } DEFINE_PROGRAM PUSH[TP,11] { CALL 'SWITCH' (SWITCHER,4,1) } PUSH[TP,12] { CALL 'MULTIPLY' (3,4,VALUE) } SYSTEM_CALL [1] 'VCR1' (VCR,TP,21,22,23,24,25,26,27,28,0)

6

Functions are defined in the DEFINE_CALL section of the code as a global function. Defining a function differs slightly from a DEFINE_CALL: • The data type of the function's return value must be specified. • The function name is not enclosed with quotes or case sensitive. DEFINE_CALL 'SWITCH' (CARD,IN,OUT) { SEND_STRING CARD, "ITOA(IN),'*',ITOA(OUT),'!'" } DEFINE_FUNCTION INTEGER MULTIPLY (INTEGER X, INTEGER Y) { RETURN (X * Y) } DEFINE_PROGRAM PUSH[TP,11] { CALL 'SWITCH' (SWITCHER,4,1) } PUSH[TP,12] { VALUE = MULTIPLY(3, 4) } SYSTEM_CALL [1] 'VCR1' (VCR,TP,21,22,23,24,25,26,27,28,0)

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

DEFINE_START Axcess Language

NetLinx Language

DEFINE_START sets the initialization parameters for the Axcess program. This section defines buffers, levels, sets communication settings, and initializes variables.

There is no difference between the way Axcess and NetLinx handle the DEFINE_START section of the program; however, the role of the DEFINE_START section is greatly reduced. Variable initializations are handled in the DEFINE_VARIABLE section. Device initializations are handled with a DATA_EVENT in the DEFINE_EVENT section.

DEFINE_START is run once when the program is loaded or the system is reset. DEFINE_START CREATE_BUFFER TP, TP_BUFFER CREATE_LEVEL VOL, 1, VOL_LEVEL1 SEND_COMMAND SWT, 'SET BAUD 9600,N,8,1,DISABLE' ON[CLEAR_TO_SEND]

DEFINE_START ON[CLEAR_TO_SEND]

DEFINE_EVENT Axcess Language

NetLinx Language

Axcess does not support events.

Events are a new process in NetLinx. The events thread runs parallel to the mainline thread. Events describe certain types of conditions within the control system. If the conditions are defined as a DEFINE_EVENT, the event code is run and mainline is bypassed. There are five different types of events: Button Events, Channel Events, Data Events, Level Events, and Timeline Events. DEFINE_EVENT BUTTON_EVENT[TP,21] (* KC REPEAT 'A' *) { PUSH: {SEND_STRING KC, 'A' } RELEASE: { } HOLD[5,REPEAT]: { SEND_STRING KC, 'A' } }

NetLinx Programming Language Reference Guide

7

NetLinx Programming Overview

DEFINE_PROGRAM Axcess Language

NetLinx Language

The DEFINE_PROGRAM or mainline section of the Axcess program is where most of the programming process takes place. Axcess supports 99 reserved identifiers or keywords. 83 of these keywords can be used in the mainline.

The DEFINE_PROGRAM or mainline section of the NetLinx program and the DEFINE_EVENTS section of code are responsible for processing events in a NetLinx system. NetLinx has expanded the list of keywords to 194 reserved identifiers. NetLinx also supports loops, data conversions, string processing, and file handling.

Axcess runs through a loop where: • The AXlink bus is queried for any changes. • Mainline code is run. • Axcess checks the wait stack and the pulse stacks for any expired waits and pulses. • The process is repeated.

NetLinx handles mainline in a similar fashion to Axcess, with a couple of differences. Because NetLinx supports multiple bus formats (AXlink, ICSNet, and Ethernet), events and changes in bus status are handled through a connection manager and message queue. NetLinx checks the message queue to see if an event is defined for the message. If not, NetLinx makes a pass through mainline. When NetLinx finishes the event handler or mainline, NetLinx processes the Wait list and Pulse list, and returns to the message queue to start the process again.

Operators NetLinx added several operators to the language consistent with C++ programming. In conditional statements (True or False statements), the double equal signs (==) can be used to evaluate whether two statements are equal. The double equal signs perform the same function as a single equal sign. There are two Bitwise operators: Shift Left shifts the bits of a value to the left n binary positions or effectively multiplies the value by 2n, where n is the number of places to shift. Shift Left is designated by a double lessthan sign (<<) or the LSHIFT keyword. Shift Right shifts the bits of a value to the right n binary positions or effectively divides the value by 2n, where n is the number of places to shift. Shift Right is designated by a double greater-than sign (>>)or the RSHIFT keyword. An example of both is shown below. X = 1 Y = 8 X = X << 2

(* X is now equal to 4 *)

Z = Y >> 3

(* Z is now equal to 1 *)

NetLinx also includes value increment and decrement operators. These operators with variables as statements work just like an Assignment operator or the equal sign does. The Increment-by-One operator or double plus sign (++) increments the value of its variable by one. The Decrement-by-One operator or double minus sign (--) decrements the value of its variable by one. An example of value increment and decrement operators is shown below. X = 1 Y = 5

8

X++

(* X is now equal to 2 *)

Y--

(* Y is now equal to 4 *)X = Y++(* This is not a legal statement *)

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

Axcess/NetLinx Incompatibility According to previous versions of each of their language reference manuals, Axcess and NetLinx each give the operator NOT highest precedence while giving AND and OR lowest. As demonstrated in the following code, however, the two systems behave differently. In reality, Axcess gives the operator NOT lowest precedence. DEFINE_VARIABLE C D E DEFINE_CALL 'GO' (A,B) { C = !A && B D = B && !A E = !B && !A } DEFINE_PROGRAM PUSH[1,1] CALL 'GO' (0,0) PUSH[1,2] CALL 'GO' (1,0) PUSH[1,3] CALL 'GO' (0,1) PUSH[1,4] CALL 'GO' (1,1)

Axcess RESULTS A

B

!A && B

B && !A

!B && !A

0

0

1

0

1

1

0

1

0

1

0

1

1

1

0

1

1

0

0

1

NETLINX RESULTS A

B

0

0

!A && B 0

B && !A 0

!B && !A 1

1

0

0

0

0

0

1

1

1

0

1

1

0

0

0

The problem applies whether A and B are channels, variables, or expressions, and for OR as well as AND. To solve the problem, AMX always recommends the use of (!A) && B instead of !A && B; however, and this is critical, some programs out there are taking advantage of the logic flaw. Where the Axcess programmer intended the truth table of !(A && B) he/she may have coded !A && B and gotten the desired result. If these systems are converted to NetLinx Masters, the logic will not work as desired. Please be aware of this difference as you support programs being converted from Axcess to NetLinx. When it occurs, Axcess-like operation can generally be achieved by including all the conditions to the right of the NOT in a single set of parentheses. For example: IF (SYSTEM_POWER && ![VCR,PLAY] || [VCR,RECORD])

becomes: IF (SYSTEM_POWER && !([VCR,PLAY] || [VCR,RECORD]))

NetLinx Programming Language Reference Guide

9

NetLinx Programming Overview

Data Types NetLinx expanded the types of data handled beyond the 8-bit and 16-bit integers handled by Axcess. NetLinx supports integers up to 32-bits and signed values to allow positive and negative values. The following table lists the data types available to NetLinx. Data Types Supported by NetLinx Type Names

Used to Store

Data Ranges

Sample of Stored Values

CHAR

Single byte values and character strings

0 to 255 (8-bit)

'a', 145, $FE, 'The quick gray fox'

WIDECHAR

0 to 65,535 (16-bit) "'OFF',500" Wide character strings dealing with Unicode fonts that use 16-bit character codes (and most Far-eastern fonts)

INTEGER

Default variable value to store values up to 65,535

0 to 65,535 (16-bit) 512, 32468, 12

SINTEGER

Signed integer values both greater than and less than zero

32,767 to 32,767 (16-bit)

24, -24, 568, -568

FLOAT

Small real numbers with 5 digits of precision

10e-38 to 10e38

1.2345 123.451.2345e5 -16.323.1415

DOUBLE

Large real numbers with 15 digits of precision

10e-308 to 10e308 1.23456789012345 12,345,678.9012545 3.14159265358979 -0.048512934

LONG

SLONG

Stores large integer values esp. greater than 65,535

0 to 4,294,967,295 (32-bit)

Signed large integer values less than - -2,147,483,647 to 32,767 and greater than 32,767 2,147,483,647 (32-bit)

1,000,000 2,000,046 -1,000,000 1,000,000-2,000,000 2,000,000

Constants The DEFINE_CONSTANT section in NetLinx is similar to the DEFINE_CONSTANTS section in Axcess. The scope of the constant extends throughout the module in which it is defined. If the DEFINE_CONSTANT section appears in the main program or in an include file, the constant's scope extends globally throughout the program. DEFINE_CONSTANT accepts data in these formats: DEFINE_CONSTANT Data Formats Types

Formats

Examples

Decimal Integer

0000

1500

Hexadecimal Integer $000

$DE60

Binary Integer

000b

01110011b

Floating Point

000.0

924.5

Exponential Notation 0.0e0

.5e-12

Character

'c' or 'R' or 255

String Literal

'ssss’

'Reverse'

The standard format for DEFINE_CONSTANT is: =

10

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

NetLinx allows variables to be defined as constants in the DEFINE_VARIABLE section of the program or module, and in the LOCAL_VAR section of a DEFINE_CALL or a DEFINE_FUNCTION. Assigning constants is consistent with C++ programming conventions.

Variables The role of the DEFINE_VARIABLE section is enhanced for NetLinx. The structure of a variable definition is: [NON_VOLATILE|VOLATILE][CONSTANT][] [= ]

NetLinx handles variables just like Axcess. NetLinx defaults non-array variables to the integer data types and defaults array variables to character data type array. The variable must be explicitly declared if using any other data type. The NON_VOLATILE and VOLATILE keywords specify what happens to a variable when the program is downloaded or after a system reset. NON_VOLATILE variables (the default) lose their values when the program is downloaded, but

retain their values when the system resets. VOLATILE variables lose their values when the system is loaded and after the system resets.

If you initialize a VOLATILE variable in the DEFINE_VARIABLE section, the variable initializes every time the code is loaded or after a system reset. The variable initializes like it would in the DEFINE_START section. If you initialize a NON_VOLATILE variable within the DEFINE_VARIABLE section, the variable only initializes when the system is loaded, and it retains any changed values after system resets. Variables can now be defined as constant variables. Since the DEFINE_CONSTANT section does not allow you to explicitly declare a constant's data type, using the CONSTANT keyword allows you to explicitly declare the data type of a constant, and to define constant values for structures and arrays of structures. CONSTANT STR_TV CHAN_5 = {'KXAS', 5} CONSTANT SINTEGER ABS_ZERO = -273

With Axcess, the DEFINE_CALL section allowed you to define local variables with the LOCAL_VAR keyword. NetLinx expands the scope of LOCAL_VAR beyond the DEFINE_CALL section of code. Local variables now come in two flavors: LOCAL_VAR now defines a static (fixed) local variable (the next time a DEFINE_CALL is called, the last value of the LOCAL_VAR will be in memory unless the variable is initialized). This is how Axcess handles variables defined with LOCAL_VAR. NetLinx does not limit LOCAL_VAR definitions strictly to the DEFINE_CALL section. LOCAL_VAR definitions can appear within any statement block. This includes (but is not limited to) DEFINE_FUNCTION, DEFINE_EVENT, WHILE statements, WAIT statements, etc. STACK_VAR defines a non-static local variable. STACK_VAR defines local variables the same way as LOCAL_VAR, and like LOCAL_VAR, STACK_VAR can appear in any statement block.

The difference is that the value stored in the variable is initialized to zero whenever the statement block is called, and the value is destroyed when the statement block is finished. The structure for LOCAL_VAR and STACK_VAR variables include: LOCAL_VAR [NON_VOLATILE | VOLATILE] [CONSTANT] [] name [= ]STACK_VAR [] name [= ]

NetLinx Programming Language Reference Guide

11

NetLinx Programming Overview

Persistent Variables Persistent variables have been implemented in the second release of NetLinx. Persistent variables are NetLinx program variables that maintain their value between updates to the NetLinx program. The user can define a variable to be persistent using the PERSISTENT storage modifier as show below: PERSISTENT CHAR cMyString[100]

All persistent variables are automatically non-volatile. It is not legal to define a variable as VOLATILE and PERSISTENT. When a NetLinx program has a persistent variable declared, subsequent downloads of new NetLinx programs containing the same persistent variable will retain the variable settings. By default, nonpersistent variables are set to zero after a NetLinx program download. Persistence overrides this behavior by setting the variable in the newly downloaded program to be the same as it was before the download. Typically, persistent variables are used for saving preset information. Suppose you have a system that contains several PosiTrack camera positioning systems, and that the user interface to the system allows the user to set the position of any of the cameras and record that position for recalling later. The position presets are stored in a non-volatile array variable so they are maintained during a power cycle. Without persistent variables, an update to the NetLinx program would zero out all of the presets the user had stored. With persistent variables, the new NetLinx program can be downloaded and all of the presets remain intact. When a new NetLinx program is downloaded to the Master, the Master iterates through all non-volatile variables from the new program looking for persistent ones. When it finds a persistent variable in the new program, it searches the old programs persistent variable space for the same variable. When it finds the same variable, the value of the new variable is set to the same value as the old variable. The Master identifies the same variable by verifying the following: Variable name Variable source location Variable type Therefore, in order for persistence to function properly the name, type, and file location declared must be the same as the previously downloaded NetLinx program. If you changed any of the three, the new persistent variable will not be set with the old variable's value.

Arrays Arrays are the most common way of combining a number of data items into a single unit. Axcess uses three methods to store data in arrays: 8-bit single dimensional arrays 16-bit single dimensional arrays 8-bit two-dimensional arrays Axcess arrays are limited to storing 255 elements per dimension. Axcess does not allow you to store two-dimensional arrays as constants; instead, you set and initialize a two-dimensional array in the DEFINE_START section. You are responsible for maintaining the integrity of the initialized value. NetLinx enhances the handling of arrays. You can define arrays of any data type in single and multidimensional arrays. You can define arrays of structures, initialize arrays within the DEFINE_VARIABLE section, and define arrays as constants. NetLinx handles arrays similar to C++, except that the first index value of the array is 1 rather than an index of 0 used by C++. With array initialization you don't need to count how many items are initialized. These definitions are functionally the same:

12

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

CHAR TV_CHAN[11] = {2, 3, 4, 5, 8, 11, 13, 21, 27, 33, 39} CHAR TV_CHAN[] = {2, 3, 4, 5, 8, 11, 13, 21, 27, 33, 39}

Multi-dimensional arrays allow multiple collections of data. NetLinx allows up to five array dimensions; array size is limited only by available memory. A two-dimensional array is a collection of single dimensional arrays. Three-dimensional arrays are collections of two-dimensional arrays. Here are examples of multi-dimensional arrays: INTEGER NUM1D[10]

(* [COLUMN] *)

INTEGER NUM2D[5][10]

(* [ROW][COLUMN] *)

INTEGER NUM3D[2][5][10]

(* [TABLE][ROW][COLUMN] *)

NUM3D[1]

refers to the 1st table

NUM3D[1][4]

refers to the 4th row of the 1st table

NUM3D[1][3][7] refers to the 7th column of the 3rd row of the 1st table

CHAR

NAME[16]

(* [PRESET NAME] *)

CHAR

PRESET[10][16]

(* [PRESET NUM][PRESET NAME] *)

CHAR

USER_PRESET[10][10][16]

(* [USER][PRESET NUM][PRESET NAME] *)

CHAR USER_PRESET[10][10][16] allows you to define tables that can store ten 16-character preset

names for ten users. With Axcess, you would either store ten two-dimensional arrays or index one twodimensional array (USER_PRESET[100][16]). For example, the fifth user would occupy USER_PRESET[41] through USER_PRESET[50]. It is sometimes difficult for people to envision multi-dimensional arrays beyond three-dimensions. We sometimes try to define the arrays spatially, as in a three-dimensional array. If we take the approach of cascading arrays, it is easier to understand. Using the previous example of defining user presets, you can expand the array to five dimensions by classifying the preset name by location and department. For example: AMX has three domestic locations; each location has a sales team, a professional services team and a tech support team; each team has a maximum of ten employees; each employee has the ability to store 10 preset names; each preset name can have up to 16 characters. The array would look like this: CHAR USER_PRESET[3][3][10][10][16] (*[LOCATION][DEPT][USER][PRESET][NAME]*)

NetLinx has a new set of functions to better deal with arrays. LENGTH_ARRAY and MAX_LENGTH_ARRAY determine the effective length and defined length of an array. When used with multi-dimensional arrays, LENGTH_ARRAY and MAX_LENGTH_ARRAY return the lengths associated with the level of the array supplied as the argument. For example: INTEGER NUM_LIST [10] = {1, 2, 3, 4, 5} LEN = MAX_LENGTH_ARRAY (NUM_LIST)

(*

LEN = 10 *)

LEN = LENGTH_ARRAY (NUM_LIST)

(*

LEN = 5

*)

LEN = MAX_LENGTH_ARRAY (NEW_LIST)

(*

LEN = 4

*)

LEN = LENGTH_ARRAY (NEW_LIST)

(*

LEN = 4

*)

LEN = MAX_LENGTH_ARRAY (MULTI_LIST[2])

(*

LEN = 10 *)

LEN = LENGTH_ARRAY (MULTI_LIST[2])

(*

LEN = 4

*)

LEN = MAX_LENGTH_ARRAY (MULTI_LIST)

(*

LEN = 4

*)

LEN = LENGTH_ARRAY (MULTI_LIST)

(*

LEN = 3

*)

INTEGER NEW_LIST[] = {10, 20, 30, 40}

INTEGER MULTI_LIST[4][10] = { {1, 2, 3}, {4, 5, 6, 7}, {8, 9} }

NetLinx Programming Language Reference Guide

13

NetLinx Programming Overview

NetLinx expands the capabilities of the assignment operator '=' to support arrays. Similar array levels are assigned to another array using the '=' operator, if the arrays match the number of dimensions and the data type of the array. You cannot assign a two-dimensional long array to a one-dimensional character array. The MAX_LENGTH_ARRAY of the array to the left of the '=' operator must be greater than or equal to the LENGTH_ARRAY of the array to the right of the '=' operator. INTEGER ARRAY1[10] = {1, 2, 3, 4} INTEGER ARRAY2[10] = {5, 6, 7} INTEGER ARRAY3[10] INTEGER DIM2ARRAY1[3][4] = { {1, 2, 3}, {4, 5, 6} } INTEGER DIM2ARRAY2[3][4] = { {7, 8, 9} } INTEGER DIM2ARRAY3[3][4] ARRAY3 = ARRAY1

(* ARRAY3 = {1, 2, 3, 4} *)

DIM2ARRAY2[2] = ARRAY1

(* DIM2ARRAY2 = { {7, 8, 9}, {1, 2, 3, 4} } *)

DIM2ARRAY3 = DIM2ARRAY1

(* DIM2ARRAY3 = { {1, 2, 3}, {4, 5, 6} } *)

Structures Arrays are limited by their inability to have multiple data-types within one array. NetLinx supports Structures to remove this limitation. Structures group different data types together as one data unit. Structures also group arrays of structures together so that each element of the array contains all of the elements of the structure. This may sound complex, but it is actually very familiar. A database table is an array of structures. The database table is an array of records. Each record is a structure. Each record contains data of different types. Let's first consider the elements of a database table. We then show how to define the structure and create a variable that uses the data structure in an array. We show how to access the individual elements of the structure. Employee Number

(* INDEX - Integer Value *)

Employee National Insurance Number (* National Insurance Number - Long *) Employee First Name

(* First Name - Character Array *)

Employee Last Name

(* Last Name - Character Array *)

Contribution to Pension

(* Contribution in % - Float *)

The DEFINE_TYPE section is added to the basic structure of a NetLinx Program. Structures are defined within the DEFINE_TYPE section. The DEFINE_TYPE section appears between the DEFINE_CONSTANT section and the DEFINE_VARIABLE section. Since structures cannot be used within the DEFINE_CONSTANT section but must be declared before they are used within the DEFINE_VARIABLE section, placing DEFINE_TYPE between DEFINE_CONSTANT and DEFINE_VARIABLE is the logical location. The attributes NON_VOLATILE, VOLATILE, and CONSTANT do not apply to the individual data elements of the structure, but can be attributed to the instances of the structure as defined in the DEFINE_VARIABLE section. The standard format for structures is: STRUCTURE { [] [] . . }

Using this format, we define our 'employee' structure in the DEFINE_TYPE section:

14

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

DEFINE_TYPE STRUCTURE EMP { INTEGER EMP_NUM CHAR NI_NUM[9] CHAR F_NAME[16] CHAR L_NAME[16] FLOAT CONT_PENSION }

Then, within the DEFINE_VARIABLE section, you create an instance of the structure and an array of the structure as follows: DEFINE_VARIABLE EMP JOHN_DOE EMP AMX_EMP[1000]

Within the program, we use the information stored within the structure and assign information to the structure in the following manner: JOHN_DOE.EMP_NUM = 101 JOHN_DOE.NI_NUM = ’155426367’ JOHN_DOE.F_NAME = ’JOHN’ JOHN_DOE.L_NAME = ’DOE’ JOHN_DOE.CONT_PENSION = 0.01

EMP_INDEX = JOHNDOE.EMP_NUM

(* EMP_INDEX = 101 *)

AMX_EMP[101] = JOHNDOE (* AMX_EMP[101] = {101, '155426367', 'JOHN', 'DOE', 0.01}*) AMX_EMP[60].EMP_NUM = 60 AMX_EMP[60].F_NAME = 'BOB'

Other uses for arrays of structures include channel listings, speed-dial lists, and user password lists.

Data sets NetLinx predefines several structures designed to work with NetLinx device numbers, channels, and levels. Data sets allow you to group and combine certain elements of NetLinx devices. There are three data set structures supported by NetLinx: DEV (Device Sets) DEVCHAN (Device-Channel Sets) DEVLEV (Device-Level Sets)

You have already seen the structure DEV structure in the DEFINE_DEVICE section. If we were to define the structure DEV in the DEFINE_TYPE section, it would look like this: STRUCTURE DEV { INTEGER DEVICE INTEGER PORT INTEGER SYSTEM }

NetLinx Programming Language Reference Guide

15

NetLinx Programming Overview

The actual instancing of the structure is unique to the DEV structure because you separate the individual structure's elements with colons (:) instead of enclosing the structure with braces {} and separating the elements with commas (,). For example: DEV PANEL_A = 128:1:0

(* correct *)

DEV PANEL_B = {128, 1, 0}

(* wrong *)

Using the DEV structure, you create the structures DEVCHAN and DEVLEV like this: STRUCTURE DEVCHAN { DEV DEVICE INTEGER CHANNEL } STRUCTURE DEVLEV { DEV DEVICE INTEGER LEVEL }

DEVCHAN and DEVLEV instance and initialize similarly to other NetLinx structures: DEV PANEL_A = 192:1:0 DEV PANEL_B = 129:1:0 DEVCHAN BUTTON_A = { PANEL_A, 1 } DEVCHAN BUTTON_B = { 128:1:0, 2 } DEVLEV LEVEL_1 = { PANEL_A, 1 } DEVLEV LEVEL_2 = { 128:1:0, 2 }

DEV, DEVCHAN, and DEVLEV are structures built into the NetLinx language. You can do more with DEV, DEVCHAN, and DEVLEV than you could with structures you create within the code. DEV PANEL_GROUP1[] = { 128:1:0, 129:1:0, 130:1:0 } DEV MSP_GROUP[5] = { MSP1, MSP2, MSP3 } DEVCHAN PRESET1_BUTTONS[5] = { {TP1, 21}, {MSP1, 1}, {134:1:0, 1} } DEVLEV VOL1_LEVEL[] = { {TP1, 1}, {MSP1, 1}, {192:1:0, 1} }

You can use the structures and arrays of the structures within many commands and situations where you would use a device number, a device and channel combination, or a device and level combination. These data sets allow you to combine devices, devices and channels, and devices and levels without using the DEFINE_COMBINE or DEFINE_CONNECT_LEVEL sections. This gives you the ability to combine certain pages of panels or to combine panels under certain conditions. In Axcess, once the panels were combined you were locked into that system configuration. Instead of writing the following statements: PUSH[MSP1, 1] PUSH[MSP2, 1] PUSH[MSP3, 1] [RELAY, 1] = ![RELAY, 1] [MSP1, 1] = [RELAY, 1] [MSP2, 1] = [RELAY, 1] [MSP3, 1] = [RELAY, 1]

You can use device sets or channel sets to accomplish the same functionality:

16

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

PUSH[MSP_GROUP,1]

(* MSP_GROUP IS A DEV SET *)

[RELAY, 1] = ![RELAY, 1] [MSP_GROUP, 1] = [RELAY, 1]

- or PUSH[MSP_PRESET1]

(* MSP_PRESET1 IS A DEVCHAN SET *)

[RELAY,1] = ![RELAY, 1] [MSP_PRESET1] = [RELAY, 1]

Conditionals & Loops Axcess supports two types of conditional statements and three types of loops: Conditional statements: IF...ELSE statements SELECT...ACTIVE statements

Loops: WHILE statements MEDIUM_WHILE statements LONG_WHILE statements

NetLinx supports: Conditional statements: IF...ELSE statements SELECT...ACTIVE statements SWITCH...CASE statements

Loops: FOR statements WHILE statements LONG_WHILE statements MEDIUM_WHILE statements are obsolete in NetLinx due to eliminating the timeout of WHILE loops. LONG_WHILE loops now differ from WHILE loops in the way input change notifications are processed during the programming loop. WHILE, MEDIUM_WHILE and LONG_WHILE statements are all still

accepted syntax to provide compatibility with existing Axcess programs.

SWITCH...CASE statements NetLinx adds the SWITCH...CASE conditional statements. The SWITCH...CASE statements provide selective execution of code blocks evaluated by a single condition. The value of the SWITCH expression is tested against each CASE value (which must be a numeric constant or a string literal). If a match is found, the statements associated with the CASE are executed. All other CASE statements are ignored. If no match is found, the DEFAULT case statements (if any) are executed. The SWITCH expression is evaluated only once. The following rules apply to SWITCH...CASE statements:

NetLinx Programming Language Reference Guide

17

NetLinx Programming Overview

Only the statements associated with the first case that matches the value of the expression are executed. Multiple CASE statements can be stacked within the SWITCH...CASE statement. If the value matches one of the CASE statements, the statements associated with the stack will be executed. If no CASE matches the SWITCH expression, then the statements under the default case (if available) are executed. The default statement must be the last case within the SWITCH...CASE, otherwise the remaining case statements will not execute. All cases must be unique. Braces should be used to bracket the statements in a case. They are required only if variables are declared within the case. The BREAK statement applies to the SWITCH and takes execution to the end of the SWITCH. Unlike C and C++, cases do not fall through to the next case if a break is not used. Because of this, BREAK statements are not required between cases. The following is the structure for the SWITCH...CASE statement: SWITCH (<expression>) { CASE : { (* statements for CASE 1 *) } CASE : { (* statements for CASE 2 *) } CASE : { (* statements for CASE n; there can be as many cases as necessary *) } DEFAULT : { (* statements for DEFAULT case *) } }

FOR loops FOR loops are an alternative to traditional loops. Functionally they do the same thing, but FOR loops are more readable. FOR loops, like WHILE loops, do not process input changes from the message buffer. The structure for a FOR loop is shown below: FOR (;;) { (* loop statements *) }

18

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

Parameters:

Contains one or more statements that are executed one time before any FOR loop statements are executed; each statement must be separated by a comma (,).



The condition for which the loop is evaluated before each pass. If the condition evaluates TRUE, the FOR loop statements execute. If the condition evaluates FALSE, the loop terminates.



Contains one or more statements that are executed after each pass through the loop statements; each statement is separated by a comma (,). This is typically a statement that increments the FOR-loop index.

The number of loop executions is usually stated at the beginning of the loop, unlike WHILE and LONG_WHILE loops. In Axcess, a typical loop may look something like this: COUNT =

0

WHILE (COUNT<10) { COUNT = COUNT + 1 (* loop statements *) }

In NetLinx you can write the same loop with a FOR statement and clarify how the loop operates: FOR (COUNT=0 ; COUNT<10 ; COUNT++) { (* loop statements *) }

By defining the loop like this, you clearly see how it is initialized and incremented. No errors appear if you forget to initialize the WHILE loop or counter. The FOR loop helps to insure proper structure.

Functions Axcess only supports one method to create subroutines: DEFINE_CALL. The DEFINE_CALL does not return values very eloquently. If you pass a variable to a parameter of the DEFINE_CALL and then change the parameter value within the subroutine, the program updates the value of the global variable in the mainline code. NetLinx has two methods for creating subroutines: DEFINE_CALL and DEFINE_FUNCTION.

DEFINE_CALL DEFINE_CALL is intended to run segments of code that are repeated throughout the program, but don't require a return value. For example, this DEFINE_CALL creates a macro to lower a screen, turn on the projector, and set the lights to Preset 1. The subroutine executes three commands and no values are returned to the program. DEFINE_CALL 'PRESENTATION MACRO' { SYSTEM_CALL [1] 'SCREEN1' (0, 0, 1, 0, SCREEN, 1, 2, 3, 0) SEND_STRING VPROJ, "'PON',$0D,$0A" SEND_STRING RADIA, "'1B',$0D" }

NetLinx Programming Language Reference Guide

19

NetLinx Programming Overview

The NetLinx compiler passes all variables by reference. This means that the variable the subroutine operates on is the same variable the caller passed. Any change made to the variable, passed as a calling parameter, updates the variable's value from the caller's perspective. You can take advantage of this pass by reference feature by returning an updated value through a calling parameter rather than as the return value. Constants, on the other hand, are passed by value. When this happens, a copy of the parameter is delivered to the subroutine. Any change made to the variable representing the constant is lost once the function or subroutine is lost. To specify an array as a function or subroutine parameter, one set of brackets for each array dimension must follow the variable name, as shown in the following example: DEFINE_CALL 'READ INPUT' (CHAR BUFFER[][]) { (* body of the subroutine *) }

The parameter BUFFER is declared to be a two-dimensional array by including two sets of brackets after the name. For compatibility with existing programs, the array dimensions may be specified inside the brackets. These dimensions, however, are not required and are ignored by the compiler. The NetLinx Interpreter will do bounds checking on the array and generate a run-time error if the array bounds are exceeded.

DEFINE_FUNCTION DEFINE_FUNCTION provides a way to return a value to a statement. It has the same functionality as a DEFINE_CALL. The DEFINE_FUNCTION is used inline in a statement, where a DEFINE_CALL must be

used as a standalone statement. The basic structure is: DEFINE_FUNCTION [][(<param1>,<param2>, … <parameN>)] { (*

statements

*)

}

The following DEFINE_FUNCTION creates a subroutine to cube a number and returns a LONG integer value: DEFINE_FUNCTION LONG CUBEIT (LONG VALUE) { STACK_VAR RESULT RESULT = VALUE * VALUE * VALUE RETURN RESULT } DEFINE_PROGRAM PUSH[TP1, 1] { CUBED_VAL = CUBEIT ( 3 ) (* CUBED_VAL = 27 *) }

20

NetLinx Programming Language Reference Guide

NetLinx Programming Overview

Events Axcess is a linear environment. All interactions between external devices and the master processor are handled within mainline code. The processor runs mainline code, services the wait and pulse queues, and checks the bus for any changes in device status. We view these interactions or changes in status as Events, which fall into one of four categories: Button Events, Channel Events, Data Events, and Level Events. NetLinx has a special program section called DEFINE_EVENT to handle incoming events. The event processing that previously could only occur within mainline code can now be handled in the DEFINE_EVENT section. NetLinx maintains a table of defined event handlers. When a new event comes into the NetLinx processing queue, the event is compared against the table of events. If the event is found, only the code in the event definition is evaluated and executed; mainline is bypassed. If an event handler is not defined, mainline is run and the event is evaluated against the mainline code. This provides a more efficient mechanism for processing events, since mainline is not required to process a single I/O request. If no events are pending, mainline is run. Mainline becomes an idle time process. With the addition of the DEFINE_EVENT section for processing events, the mainline's role in NetLinx becomes greatly diminished, if not totally eliminated. Programs can still be written using the traditional technique of processing events and providing feedback in mainline code; however, programs written using the event table structure will run faster and be much easier to maintain.

Button Events Events associated with a button on a touch panel or an AXD-MSP32 will fall into one of three categories: What happens when the button is pushed. What happens when the button is released. What happens if the button is held. The structure for Button Events is as follows: BUTTON_EVENT [<device>,] { PUSH: { (* push event handler code *) } RELEASE: { (* release event handler code *) } HOLD [

Related Documents