AMX NETLINX PROGRAMMING LANGUAGE User Manual

4 (1)

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 in the statement:

CALL 'Read Data' (Buffer)

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

DEFINE_VARIABLE

CHAR MyString[32]

INTEGER StrLen

Square brackets indicate an optional element in a command. Angle brackets indicate substitution. In the example below, the notation <return type> indicates that a valid data type (such as CHAR, INTEGER, or FLOAT) must be substituted for <return type>. The square brackets surrounding it indicate that the return type is optional.

DEFINE_FUNCTION [<return type>] <name> [(Param1, Param2, …)]

{

(* body of subroutine *)

}

Related Instruction Manuals

These instruction manuals contain additional information that relates to the NetLinx Programming Language:

Axcess Programming Language Instruction Manual

NetLinx Studio Program Instruction Manual

NetLinx Programming Language Reference Guide	1

Introduction

2	NetLinx Programming Language Reference Guide

NetLinx Programming Overview

The NetLinx control system was designed to upgrade the processor bus and improve the power of the Axcess programming language. Originally named Axcess2, the NetLinx was designed to be a superset of the Axcess programming language. The relationship between the new language (NetLinx) and Axcess is very similar to the relationship between C++ and C.

Just as C++ brought a whole new level of power to C programming, NetLinx offers a variety of new tools and commands to dynamically increase the speed and power of present and future applications.

Use the NetLinx Studio software program to create, compile, and transfer Axcess/

NetLinx code.

Defining the Superset

NetLinx contains all of the elements of Axcess. Largely, you can use the same code from Axcess systems in NetLinx systems. Some exceptions include variable names conflicting with new NetLinx keywords; however, Axcess keywords are valid in NetLinx.

You cannot compile NetLinx code on an Axcess compiler, or download NetLinx code to an Axcess control system. To upgrade an existing Axcess control system to NetLinx you must upgrade the Axcess Master to a NetLinx Master. You can still use the existing Axcess equipment as long as you can disable the existing Axcess Central Controller.

The exceptions are the Axcent, the Axcent2, the AXB-EM232, and the AXB-MPE+ Master Port Expander. None of these integrated controllers allow you to disable the Central Controller. Both Axcess Card Frame Systems and Axcent3 systems allow you to either remove or disable the Axcess Central Controller. If you are using an Axcent3 / Axcent3 Pro, you can disable the Master with the OpenAxcess program. You can connect the Axcent3 / Axcent3 Pro to a NetLinx Master Module via AXlink. Then you can compile and download the existing Axcess code.

Several Axcess control limitations have been fixed in NetLinx.

NetLinx expands the types of data and variables from Axcess.

NetLinx provides multiple processes and event threads beyond the Mainline in Axcess.

NetLinx offers more options in distributed processing. NetLinx expands and strengthens Master-to-Master communications and expands the traditional AXlink bus to include ICSNet and Ethernet Network communications.

Axcess is linear in its process. At run time, Axcess runs the DEFINE_START code once when the system is loaded or restarted. Axcess then makes a pass through mainline code, polls the bus for activity, checks the wait and pulse stacks, and repeats the process again. The length of mainline and the activity on the bus affect runtime speeds. The mainline process is considered a single thread.

NetLinx runs on multiple threads; mainline and event handlers run on parallel threads. Event handlers are defined within NetLinx and operate like mini-mainlines. They contain far less code and run faster than mainline. If an event occurs, and an event handler has been defined for that event, NetLinx bypasses mainline and runs the event handler.

NetLinx Programming Language Reference Guide	3

NetLinx Programming Overview

NetLinx vs. Axcess - Comparison by Structure

DEFINE_DEVICE

Axcess Language			NetLinx Language

Axcess defines devices with a single number (some-			NetLinx defines the device by Device:Port:System.
times called an address) from 1 to 255. Axcess per-			• Device is a 16-bit integer representing the device
mits a maximum of 255 devices on the AXlink bus.			number. Physical devices range from 1 to 32,767.

DEFINE_DEVICE			Virtual devices range from 32,768 to 36,863.
VCR	= 1	(* AXC-IRS *)	Note: These numbers do not seem so random when
VPROJ= 2		(* AXC-IRS *)	represented in hexadecimal. Physical devices range
TP	= 128	(* AXT-CA10*)	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		NetLinx processes constants just like Axcess. NetLinx
value between 0 and 65,535 or an array with a max-		also allows you to define an expression in the
imum length of 255 bytes in which each element can		DEFINE_CONSTANT section. The expression cannot
hold a value from 0 to 255. These values can be		contain any variables.
expressed in ASCII, Decimal, or Hexadecimal.		DEFINE_CONSTANT

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

4	NetLinx Programming Language Reference Guide

		NetLinx Programming Overview
DEFINE_VARIABLES

Axcess Language	NetLinx Language

Axcess supports 5 types of variables:	NetLinx substantially increased the number of supported
• Integer Variables (default) can contain a value	variable types. In addition to more data types, NetLinx
	also supports Sets, Structures, and Multi-dimensional
from 0 to 65,535.
	arrays.
• Character Arrays are single element arrays, in
	Arrays default to Character Arrays. Variables default to
which each element has a value from 0 to 255 with
a maximum of 255 elements	Integer Variables. Variables default to Non-Volatile, but
	can be set as Non-Volatile or Volatile (Volatile variables
• 2-Dimensional Arrays equate to a maximum of
	are initialized when code is loaded or when the system
255 single element character arrays. Each
	is reset).
element can have a value from 0 to 255.
	DEFINE_VARIABLE
• Integer Arrays are single element arrays, in which
	CHAR	VALUE1
each element can contain a value from 0 to 65,535
	WIDECHAR	BIGCHAR
with a maximum of 255 elements
	INTEGER	VALUE2
• 2-Dimensional Integer Arrays may have a
	SINTEGER	SIGNED1
maximum value of 65,535.
	LONG	BIGVALUE
Variables are Non-Volatile (the variable loses its
	SLONG	SIGNED2
value when the program is loaded, but retains its
	FLOAT	DECIMAL
value if the controller is reset).
	DOUBLE	VERYBIGVALUE
DEFINE_VARIABLE
	INTEGER	ARRAY[3][3][3]
VALUE
	VOLATILE INTEGER RESET_VAR
ARRAY[3]

ARRAY_2DIM[4][6]
INTEGER INT_ARRAY[6]

NetLinx Programming Language Reference Guide	5

NetLinx Programming Overview

DEFINE_CALL (Subroutines)

	Axcess Language	NetLinx Language

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

	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	There is no difference between the way Axcess and
	the Axcess program. This section defines buffers,	NetLinx handle the DEFINE_START section of the pro-
	levels, sets communication settings, and initializes	gram; however, the role of the DEFINE_START section
	variables.	is greatly reduced. Variable initializations are handled in
	DEFINE_START is run once when the program is	the DEFINE_VARIABLE section. Device initializations
	DEFINE_START is run once when the program is	are handled with a DATA_EVENT in the DEFINE_EVENT
	loaded or the system is reset.	are handled with a DATA_EVENT in the DEFINE_EVENT
	loaded or the system is reset.	section.
	DEFINE_START	section.
	DEFINE_START	DEFINE_START
	CREATE_BUFFER TP, TP_BUFFER	DEFINE_START
	CREATE_BUFFER TP, TP_BUFFER	ON[CLEAR_TO_SEND]
	CREATE_LEVEL VOL, 1, VOL_LEVEL1	ON[CLEAR_TO_SEND]
	CREATE_LEVEL VOL, 1, VOL_LEVEL1
	SEND_COMMAND SWT,
	'SET BAUD 9600,N,8,1,DISABLE'
	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 cer-
		tain 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 Time-
		line 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	The DEFINE_PROGRAM or mainline section of the
	Axcess program is where most of the programming	NetLinx program and the DEFINE_EVENTS section of
	process takes place. Axcess supports 99 reserved	code are responsible for processing events in a NetLinx
	identifiers or keywords. 83 of these keywords can be	system. NetLinx has expanded the list of keywords to
	used in the mainline.	194 reserved identifiers. NetLinx also supports loops,
	Axcess runs through a loop where:	data conversions, string processing, and file handling.
	Axcess runs through a loop where:	NetLinx handles mainline in a similar fashion to Axcess,
	• The AXlink bus is queried for any changes.	NetLinx handles mainline in a similar fashion to Axcess,
	• The AXlink bus is queried for any changes.	with a couple of differences. Because NetLinx supports
	• Mainline code is run.	with a couple of differences. Because NetLinx supports
	• Mainline code is run.	multiple bus formats (AXlink, ICSNet, and Ethernet),
	• Axcess checks the wait stack and the pulse stacks	multiple bus formats (AXlink, ICSNet, and Ethernet),
	• Axcess checks the wait stack and the pulse stacks	events and changes in bus status are handled through a
	for any expired waits and pulses.	connection manager and message queue. NetLinx
	• The process is repeated.	checks the message queue to see if an event is defined
		for the message. If not, NetLinx makes a pass through
		mainline. When NetLinx finishes the event handler or
		mainline, NetLinx processes the Wait list and Pulse list,
		and returns to the message queue to start the process
		again.

Operators

NetLinx added several operators to the language consistent with C++ programming. In conditional statements (True or False statements), the double equal signs (==) can be used to evaluate whether two statements are equal. The double equal signs perform the same function as a single equal sign.

There are two Bitwise operators:

Shift Left shifts the bits of a value to the left n binary positions or effectively multiplies the value by 2n, where n is the number of places to shift. Shift Left is designated by a double lessthan sign (<<) or the LSHIFT keyword.

Shift Right shifts the bits of a value to the right n binary positions or effectively divides the value by 2n, where n is the number of places to shift. Shift Right is designated by a double greater-than sign (>>)or the RSHIFT keyword.

An example of both is shown below.

X = 1

Y = 8

X = X << 2 (* X is now equal to 4 *)

Z = Y >> 3 (* Z is now equal to 1 *)

NetLinx also includes value increment and decrement operators. These operators with variables as statements work just like an Assignment operator or the equal sign does. The Increment-by-One operator or double plus sign (++) increments the value of its variable by one. The

Decrement-by-One operator or double minus sign (--) decrements the value of its variable by one.

An example of value increment and decrement operators is shown below.

X = 1

Y = 5

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 NOT highest precedence while giving AND and OR lowest. As demonstrated in the following code, however, the two systems behave differently. In reality, Axcess gives the operator NOT lowest precedence.

DEFINE_VARIABLE

C D E

DEFINE_CALL 'GO' (A,B)

{

C = !A && B

D = B && !A

E = !B && !A

}

DEFINE_PROGRAM

PUSH[1,1]

CALL 'GO' (0,0)

PUSH[1,2]

CALL 'GO' (1,0)

PUSH[1,3]

CALL 'GO' (0,1)

PUSH[1,4]

CALL 'GO' (1,1)

Axcess RESULTS
A	B	!A && B	B && !A	!B && !A
0	0	1	0	1
1	0	1	0	1
0	1	1	1	0
1	1	0	0	1
NETLINX RESULTS
A	B	!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	Used to Store	Data Ranges	Sample of Stored Values
Names

CHAR	Single byte values and character	0 to 255 (8-bit)	'a', 145, $FE, 'The quick gray fox'
	strings

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

INTEGER	Default variable value to store values	0 to 65,535 (16-bit)	512, 32468, 12
	up to 65,535

SINTEGER	Signed integer values both greater	32,767 to 32,767	24, -24, 568, -568
	than and less than zero	(16-bit)

FLOAT	Small real numbers with 5 digits of	10e-38 to 10e38	1.2345
	precision		123.451.2345e5
			123.451.2345e5
			-16.323.1415

DOUBLE	Large real numbers with 15 digits of	10e-308 to 10e308	1.23456789012345
	precision		12,345,678.9012545
			12,345,678.9012545
			3.14159265358979
			-0.048512934

LONG	Stores large integer values esp.	0 to 4,294,967,295	1,000,000
	greater than 65,535	(32-bit)	2,000,046
			2,000,046

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

Constants

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

DEFINE_CONSTANT Data Formats

Types	Formats	Examples

Decimal Integer	0000	1500

Hexadecimal Integer	$000	$DE60

Binary Integer	000b	01110011b

Floating Point	000.0	924.5

Exponential Notation	0.0e0	.5e-12

Character	'c' or <char code>	'R' or 255

String Literal	'ssss’	'Reverse'

The standard format for DEFINE_CONSTANT is:

10	NetLinx Programming Language Reference Guide

NetLinx Programming Overview

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

Variables

The role of the DEFINE_VARIABLE section is enhanced for NetLinx. The structure of a variable definition is:

[NON_VOLATILE|VOLATILE][CONSTANT][<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.

The NON_VOLATILE and VOLATILE keywords specify what happens to a variable when the program is downloaded or after a system reset.

NON_VOLATILE variables (the default) lose their values when the program is downloaded, but retain their values when the system resets.

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

If you initialize a VOLATILE variable in the DEFINE_VARIABLE section, the variable initializes every time the code is loaded or after a system reset. The variable initializes like it would in the DEFINE_START section. If you initialize a NON_VOLATILE variable within the DEFINE_VARIABLE section, the variable only initializes when the system is loaded, and it retains any changed values after system resets.

Variables can now be defined as constant variables. Since the DEFINE_CONSTANT section does not allow you to explicitly declare a constant's data type, using the CONSTANT keyword allows you to explicitly declare the data type of a constant, and to define constant values for structures and arrays of structures.

CONSTANT STR_TV CHAN_5 = {'KXAS', 5}

CONSTANT SINTEGER ABS_ZERO = -273

With Axcess, the DEFINE_CALL section allowed you to define local variables with the LOCAL_VAR keyword. NetLinx expands the scope of LOCAL_VAR beyond the DEFINE_CALL section of code. Local variables now come in two flavors:

LOCAL_VAR now defines a static (fixed) local variable (the next time a DEFINE_CALL is called, the last value of the LOCAL_VAR will be in memory unless the variable is initialized). This is how Axcess handles variables defined with LOCAL_VAR. NetLinx does not limit LOCAL_VAR definitions strictly to the DEFINE_CALL section. LOCAL_VAR definitions can appear within any statement block. This includes (but is not limited to) DEFINE_FUNCTION, DEFINE_EVENT, WHILE statements, WAIT statements, etc.

STACK_VAR defines a non-static local variable. STACK_VAR defines local variables the same way as LOCAL_VAR, and like LOCAL_VAR, STACK_VAR can appear in any statement block. The difference is that the value stored in the variable is initialized to zero whenever the statement block is called, and the value is destroyed when the statement block is finished. The structure for LOCAL_VAR and STACK_VAR variables include:

LOCAL_VAR [NON_VOLATILE | VOLATILE] [CONSTANT] [<type>] name [= <value>]STACK_VAR

[<type>] name [= <value>]

NetLinx Programming Language Reference Guide	11

NetLinx Programming Overview

Persistent Variables

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

PERSISTENT CHAR cMyString[100]

All persistent variables are automatically non-volatile. It is not legal to define a variable as VOLATILE and PERSISTENT.

When a NetLinx program has a persistent variable declared, subsequent downloads of new NetLinx programs containing the same persistent variable will retain the variable settings. By default, nonpersistent variables are set to zero after a NetLinx program download. Persistence overrides this behavior by setting the variable in the newly downloaded program to be the same as it was before the download.

Typically, persistent variables are used for saving preset information. Suppose you have a system that contains several PosiTrack camera positioning systems, and that the user interface to the system allows the user to set the position of any of the cameras and record that position for recalling later. The position presets are stored in a non-volatile array variable so they are maintained during a power cycle. Without persistent variables, an update to the NetLinx program would zero out all of the presets the user had stored. With persistent variables, the new NetLinx program can be downloaded and all of the presets remain intact.

When a new NetLinx program is downloaded to the Master, the Master iterates through all non-volatile variables from the new program looking for persistent ones. When it finds a persistent variable in the new program, it searches the old programs persistent variable space for the same variable. When it finds the same variable, the value of the new variable is set to the same value as the old variable. The Master identifies the same variable by verifying the following:

Variable name

Variable source location

Variable type

Therefore, in order for persistence to function properly the name, type, and file location declared must be the same as the previously downloaded NetLinx program. If you changed any of the three, the new persistent variable will not be set with the old variable's value.

Arrays

Arrays are the most common way of combining a number of data items into a single unit. Axcess uses three methods to store data in arrays:

8-bit single dimensional arrays

16-bit single dimensional arrays

8-bit two-dimensional arrays

Axcess arrays are limited to storing 255 elements per dimension. Axcess does not allow you to store two-dimensional arrays as constants; instead, you set and initialize a two-dimensional array in the DEFINE_START section. You are responsible for maintaining the integrity of the initialized value.

NetLinx enhances the handling of arrays. You can define arrays of any data type in single and multidimensional arrays. You can define arrays of structures, initialize arrays within the DEFINE_VARIABLE section, and define arrays as constants.

NetLinx handles arrays similar to C++, except that the first index value of the array is 1 rather than an index of 0 used by C++. With array initialization you don't need to count how many items are initialized. These definitions are functionally the same:

12	NetLinx Programming Language Reference Guide

NetLinx Programming Overview

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

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

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


INTEGER NUM1D[10]			(* [COLUMN] *)
INTEGER	NUM2D[5][10]		(*	[ROW][COLUMN] *)
INTEGER	NUM3D[2][5][10]		(*	[TABLE][ROW][COLUMN] *)
NUM3D[1]		refers to the 1st table
NUM3D[1][4]		refers to the 4th row of the 1st table

NUM3D[1][3][7] refers to the 7th column of the 3rd row of the						1st table
CHAR	NAME[16]	(* [PRESET		NAME]	*)
CHAR	PRESET[10][16]	(*	[PRESET	NUM][PRESET NAME]		*)
CHAR	USER_PRESET[10][10][16]	(*	[USER][PRESET		NUM][PRESET	NAME] *)

CHAR USER_PRESET[10][10][16] allows you to define tables that can store ten 16-character preset names for ten users. With Axcess, you would either store ten two-dimensional arrays or index one twodimensional array (USER_PRESET[100][16]). For example, the fifth user would occupy

USER_PRESET[41] through USER_PRESET[50].

It is sometimes difficult for people to envision multi-dimensional arrays beyond three-dimensions. We sometimes try to define the arrays spatially, as in a three-dimensional array. If we take the approach of cascading arrays, it is easier to understand. Using the previous example of defining user presets, you can expand the array to five dimensions by classifying the preset name by location and department. For example: AMX has three domestic locations; each location has a sales team, a professional services team and a tech support team; each team has a maximum of ten employees; each employee has the ability to store 10 preset names; each preset name can have up to 16 characters. The array would look like this:

CHAR USER_PRESET[3][3][10][10][16]

(*[LOCATION][DEPT][USER][PRESET][NAME]*)

NetLinx has a new set of functions to better deal with arrays. LENGTH_ARRAY and MAX_LENGTH_ARRAY determine the effective length and defined length of an array. When used with multi-dimensional arrays, LENGTH_ARRAY and MAX_LENGTH_ARRAY return the lengths associated with the level of the array supplied as the argument. For example:

INTEGER NUM_LIST [10] = {1, 2, 3, 4, 5}
LEN = MAX_LENGTH_ARRAY (NUM_LIST)	(*	LEN = 10 *)
LEN = LENGTH_ARRAY (NUM_LIST)	(*	LEN = 5	*)
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 '=' operator, if the arrays match the number of dimensions and the data type of the array. You cannot assign a two-dimensional long array to a one-dimensional character array. The MAX_LENGTH_ARRAY of the array to the left of the '=' operator must be greater than or equal to the LENGTH_ARRAY of the array to the right of the '=' operator.

INTEGER ARRAY1[10] = {1,	2, 3, 4}
INTEGER ARRAY2[10] = {5,	6, 7}
INTEGER ARRAY3[10]
INTEGER DIM2ARRAY1[3][4]	= { {1, 2, 3}, {4,	5, 6}	}
INTEGER DIM2ARRAY2[3][4]	= { {7, 8, 9} }
INTEGER DIM2ARRAY3[3][4]
ARRAY3 = ARRAY1	(* ARRAY3 = {1,	2, 3,	4} *)
DIM2ARRAY2[2] = ARRAY1	(* DIM2ARRAY2 =	{ {7,	8, 9}, {1, 2, 3, 4} } *)
DIM2ARRAY3 = DIM2ARRAY1	(* DIM2ARRAY3 =	{ {1,	2, 3}, {4, 5, 6} } *)

Structures

Arrays are limited by their inability to have multiple data-types within one array. NetLinx supports Structures to remove this limitation. Structures group different data types together as one data unit. Structures also group arrays of structures together so that each element of the array contains all of the elements of the structure. This may sound complex, but it is actually very familiar.

A database table is an array of structures. The database table is an array of records. Each record is a structure. Each record contains data of different types. Let's first consider the elements of a database table. We then show how to define the structure and create a variable that uses the data structure in an array. We show how to access the individual elements of the structure.

Employee Number	(*	INDEX - Integer		Value	*)
Employee National Insurance Number (*		National Insurance Number				-	Long *)
Employee First Name	(*	First Name -	Character Array *)
Employee Last Name	(*	Last Name - Character			Array		*)
Contribution to Pension	(*	Contribution	in	% - Float		*)

The DEFINE_TYPE section is added to the basic structure of a NetLinx Program. Structures are defined within the DEFINE_TYPE section. The DEFINE_TYPE section appears between the DEFINE_CONSTANT section and the DEFINE_VARIABLE section. Since structures cannot be used within the DEFINE_CONSTANT section but must be declared before they are used within the

DEFINE_VARIABLE section, placing DEFINE_TYPE between DEFINE_CONSTANT and

DEFINE_VARIABLE is the logical location.

The attributes NON_VOLATILE, VOLATILE, and CONSTANT do not apply to the individual data elements of the structure, but can be attributed to the instances of the structure as defined in the

DEFINE_VARIABLE section.

The standard format for structures is:

STRUCTURE <name>

{

[<type>] <data1> [<type>] <data2>

}

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

14	NetLinx Programming Language Reference Guide

+ 216 hidden pages

AMX NETLINX PROGRAMMING LANGUAGE User Manual

Introduction

Conventions Used in this Document

Related Instruction Manuals

NetLinx Programming Overview

Defining the Superset

NetLinx vs. Axcess - Comparison by Structure

DEFINE_DEVICE

DEFINE_CONSTANT

DEFINE_VARIABLES

DEFINE_CALL (Subroutines)

DEFINE_START

DEFINE_EVENT

DEFINE_PROGRAM

Operators

Axcess/NetLinx Incompatibility

Data Types

Constants

Variables

Persistent Variables

Arrays

Structures