AMX NETLINX PROGRAMMING LANGUAGE User Manual
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 <file> ................................... 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
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 '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
Programming examples appear in the same fixed font. For example:
DEFINE_VARIABLE
CHAR MyString[32]
INTEGER StrLen
Introduction
CALL in the statement:
THE FONT SHOWN HERE, in all capital letters.
Square brackets indicate an optional element in a command. Angle brackets indicate substitution. In the
example below, the notation
FLOAT) must be substituted for <return type>. The square brackets surrounding it indicate that
or
the return type is optional.
DEFINE_FUNCTION [<return type>] <name> [(Param1, Param2, …)]
{
(* body of subroutine *)
}
<return type> indicates that a valid data type (such as CHAR, INTEGER,
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
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 Axcent
to either remove or disable the Axcess Central Controller. If you are using an
3
Axcent
You can connect the Axcent3 / Axcent3 Pro to a NetLinx Master Module via AXlink.
Then you can compile and download the existing Axcess code.
/ Axcent3 Pro, you can disable the Master with the OpenAxcess program.
NetLinx Programming Overview
3
systems allow you
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
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
DEFINE_START code once when the system
3
NetLinx Programming Overview
NetLinx vs. Axcess - Comparison by Structure
DEFINE_DEVICE
Axcess Language NetLinx Language
Axcess defines devices with a single number (sometimes called an address) from 1 to 255. Axcess permits a maximum of 255 devices on the AXlink bus.
DEFINE_DEVICE
VCR = 1 (* AXC-IRS *)
VPROJ= 2 (* AXC-IRS *)
TP = 128 (* AXT-CA10*)
NetLinx defines the device by Device:Port:System.
• Device is a 16-bit integer representing the device
number. Physical devices range from 1 to 32,767.
Virtual devices range from 32,768 to 36,863.
Note: These numbers do not seem so random when
represented in hexadecimal. Physical devices range
from $0001 to $7FFF. Virtual devices range from
$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.
DEFINE_CONSTANT
VALUE_MAX = 140
DEFAULT_NAME = 'Axcess'
ETX = "$FE,$FF"
VALUE_MAX = VALUE_MIN + 100
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
DEFINE_VARIABLES
Axcess Language NetLinx Language
Axcess supports 5 types of variables:
• 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
a maximum of 255 elements
• 2-Dimensional Arrays equate to a maximum of
255 single element character arrays. Each
element can have a value from 0 to 255.
• Integer Arrays are single element arrays, in which
each element can contain a value from 0 to 65,535
with a maximum of 255 elements
• 2-Dimensional Integer Arrays may have a
maximum value of 65,535.
Variables are Non-Volatile (the variable loses its
value when the program is loaded, but retains its
value if the controller is reset).
DEFINE_VARIABLE
VALUE
ARRAY[3]
ARRAY_2DIM[4][6]
INTEGER INT_ARRAY[6]
NetLinx substantially increased the number of supported
variable types. In addition to more data types, NetLinx
also supports Sets, Structures, and Multi-dimensional
arrays.
Arrays default to Character Arrays. Variables default to
Integer Variables. Variables default to Non-Volatile, but
can be set as Non-Volatile or Volatile (Volatile variables
are initialized when code is loaded or when the system
is reset).
DEFINE_VARIABLE
CHAR VALUE1
WIDECHAR BIGCHAR
INTEGER VALUE2
SINTEGER SIGNED1
LONG BIGVALUE
SLONG SIGNED2
FLOAT DECIMAL
DOUBLE VERYBIGVALUE
INTEGER ARRAY[3][3][3]
VOLATILE INTEGER RESET_VAR
NetLinx Programming Overview
NetLinx Programming Language Reference Guide
5
NetLinx Programming Overview
DEFINE_CALL (Subroutines)
Axcess Language NetLinx Language
Axcess provides two methods for incorporating subroutines into your program.
• DEFINE_CALL subroutines are defined in the
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)
Like Axcess, NetLinx supports DEFINE_CALL and
SYSTEM_CALL. NetLinx also supports functions, which
are similar to a DEFINE_CALL(s). They can be used
standalone or in-line as an expression.
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)
6
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.
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]
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
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.
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.
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
Shift Right shifts the bits of a value to the right n binary positions or effectively divides the
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 *)
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.
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.
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.
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.
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 (
Decrement-by-One operator or double minus sign (
++) increments the value of its variable by one. The
--) decrements the value of its variable by one.
An example of value increment and decrement operators is shown below.
X = 1
Y = 5
X++ (* X is now equal to 2 *)
Y-- (* Y is now equal to 4 *)X = Y++(* This is not a legal statement *)
8
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
following code, however, the two systems behave differently. In reality, Axcess gives the operator
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)
NOT highest precedence while giving AND and OR lowest. As demonstrated in the
NOT
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 !A && B B && !A !B && !A
0 0 0 0 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
CHAR Single byte values and character
WIDECHAR Wide character strings dealing with
INTEGER Default variable value to store values
SINTEGER Signed integer values both greater
FLOAT Small real numbers with 5 digits of
DOUBLE Large real numbers with 15 digits of
LONG Stores large integer values esp.
SLONG Signed large integer values less than -
Used to Store Data Ranges Sample of Stored Values
0 to 255 (8-bit) 'a', 145, $FE, 'The quick gray fox'
strings
0 to 65,535 (16-bit) "'OFF',500"
Unicode fonts that use 16-bit character
codes (and most Far-eastern fonts)
up to 65,535
than and less than zero
precision
precision
greater than 65,535
32,767 and greater than 32,767
0 to 65,535 (16-bit) 512, 32468, 12
32,767 to 32,767
(16-bit)
10e-38 to 10e38 1.2345
10e-308 to 10e308 1.23456789012345
0 to 4,294,967,295
(32-bit)
-2,147,483,647 to
2,147,483,647
(32-bit)
24, -24, 568, -568
123.451.2345e5
-16.323.1415
12,345,678.9012545
3.14159265358979
-0.048512934
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 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 <char code> 'R' or 255
String Literal 'ssss’ 'Reverse'
The standard format for
<constant name> = <constant expression>
DEFINE_CONSTANT is:
DEFINE_CONSTANT accepts data in these formats:
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][<type>]<variable name> [= <value>]
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.
NON_VOLATILE and VOLATILE keywords specify what happens to a variable when the program is
The
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
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
allow you to explicitly declare a constant's data type, using the
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
VOLATILE variable in the DEFINE_VARIABLE section, the variable initializes every
DEFINE_CONSTANT section does not
CONSTANT keyword allows you to
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
This is how Axcess handles variables defined with
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_EVENT, WHILE statements, WAIT statements, etc.
STACK_VAR defines a non-static local variable. STACK_VAR defines local variables the same
LOCAL_VAR, and like LOCAL_VAR, STACK_VAR can appear in any statement block.
way as
LOCAL_VAR will be in memory unless the variable is initialized).
LOCAL_VAR. NetLinx does not limit
DEFINE_FUNCTION,
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 [NON_VOLATILE | VOLATILE] [CONSTANT] [<type>] name [= <value>]STACK_VAR
[<type>] name [= <value>]
LOCAL_VAR and STACK_VAR variables include:
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 CHAR cMyString[100]
All persistent variables are automatically non-volatile. It is not legal to define a variable as VOLATILE
PERSISTENT.
and
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.
PERSISTENT storage modifier as show below:
12
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
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:
NetLinx Programming Language Reference Guide
DEFINE_VARIABLE
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 *)
INTEGER NEW_LIST[] = {10, 20, 30, 40}
LEN = MAX_LENGTH_ARRAY (NEW_LIST) (* LEN = 4 *)
LEN = LENGTH_ARRAY (NEW_LIST) (* LEN = 4 *)
INTEGER MULTI_LIST[4][10] = { {1, 2, 3}, {4, 5, 6, 7}, {8, 9} }
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 *)
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 '
data type of the array. You cannot assign a two-dimensional long array to a one-dimensional character
array. The
LENGTH_ARRAY of the array to the right of the '=' operator.
to the
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 *)
=' operator, if the arrays match the number of dimensions and the
MAX_LENGTH_ARRAY of the array to the left of the '=' operator must be greater than or equal
14
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 <name>
{
[<type>] <data1>
[<type>] <data2>
.
.
}
Using this format, we define our 'employee' structure in the DEFINE_TYPE section:
NetLinx Programming Language Reference Guide
Loading...