User manual AMX NETLINX PROGRAMMING LANGUAGE

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 "" 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 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. DEFINE_CONSTANT VALUE_MAX = 140 DEFAULT_NAME = 'Axcess' ETX = "$FE,$FF" VALUE_MAX = VALUE_MIN + 100 NetLinx Language 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_MIN = 40 DEFAULT_NAME = 'Axcess' ETX [] = {$FE,$FF} VALUE_MAX = VALUE_MIN + 100 4 NetLinx Programming Language Reference Guide