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.
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 ....
Table of Contents Combining and uncombining channels .......................................................................... 29 String Comparisons................................................................................................. 29 Axcess code - string comparison ................................................................................... 29 Netlinx code - string comparison .................................................................................. 29 Modules .............
Table of Contents Variables ................................................................................................................. 45 Scope ............................................................................................................................ 45 Local variables............................................................................................................... 45 Global variables......................................................................................
Table of Contents Un-combining levels ...................................................................................................... 83 Combining and Un-combining Channels ................................................................. 84 Combining channels ...................................................................................................... 84 Un-combining channels..................................................................................................
Table of Contents CHAR ................................................................................................................................... 104 CHARD ................................................................................................................................ 104 CHARDM ............................................................................................................................. 104 CLEAR_BUFFER ...............................................................
Table of Contents DEFINE_TYPE ..................................................................................................................... 115 DEFINE_VARIABLE ............................................................................................................ 116 DELETE_URL_ENTRY ........................................................................................................ 116 DEV ....................................................................................................
Table of Contents INTEGER ............................................................................................................................. 134 IP_CLIENT_CLOSE ............................................................................................................. 134 IP_CLIENT_OPEN ............................................................................................................... 135 IP_MC_SERVER_OPEN ............................................................................
Table of Contents RELEASE ............................................................................................................................. 146 RELEASE_CHANNEL ......................................................................................................... 146 RELEASE_DEVCHAN ......................................................................................................... 146 RELEASE_DEVICE ........................................................................................
Table of Contents UNCOMBINE_DEVICES ..................................................................................................... 157 UNCOMBINE_LEVELS ........................................................................................................ 158 UPPER_STRING ................................................................................................................. 158 VARIABLE_TO_STRING (VARIABLE ENCODE) ................................................................
Table of Contents Must be integer reference........................................................................................... 169 Out of memory............................................................................................................ 169 Parameter mismatch in CALL....................................................................................... 169 Program_Name must be on line 1 ...............................................................................
Table of Contents _WC ..................................................................................................................................... 173 CH_TO_WC ......................................................................................................................... 173 WC_COMPARE_STRING ................................................................................................... 173 WC_CONCAT_STRING .............................................................................
Table of Contents Server Programming ............................................................................................. 191 Listening for client requests ........................................................................................ 191 Multiple client connections.......................................................................................... 192 Closing a local port .....................................................................................................
Table of Contents NetLinx Programming Language Reference Guide xiii
Table of Contents xiv NetLinx Programming Language Reference Guide
Introduction Introduction NetLinx® is the second generation of the Axcess® programming language and is a superset of the original Axcess language with extensions for additional data types, new event handlers, structure support, multi-dimensional arrays, and other features. This document assumes that you are familiar with Axcess; the focus is on the new language elements and how they extend the functionality of the existing language.
Introduction 2 NetLinx Programming Language Reference Guide
NetLinx Programming Overview NetLinx Programming Overview The NetLinx control system was designed to upgrade the processor bus and improve the power of the Axcess programming language. Originally named Axcess2, the NetLinx was designed to be a superset of the Axcess programming language. The relationship between the new language (NetLinx) and Axcess is very similar to the relationship between C++ and C.
NetLinx Programming Overview NetLinx vs. Axcess - Comparison by Structure DEFINE_DEVICE Axcess Language NetLinx Language Axcess defines devices with a single number (some- NetLinx defines the device by Device:Port:System. times called an address) from 1 to 255. Axcess per- • Device is a 16-bit integer representing the device mits a maximum of 255 devices on the AXlink bus. number. Physical devices range from 1 to 32,767. Virtual devices range from 32,768 to 36,863.
NetLinx Programming Overview DEFINE_VARIABLES Axcess Language NetLinx Language Axcess supports 5 types of variables: NetLinx substantially increased the number of supported variable types. In addition to more data types, NetLinx also supports Sets, Structures, and Multi-dimensional arrays. • Integer Variables (default) can contain a value from 0 to 65,535. • Character Arrays are single element arrays, in which each element has a value from 0 to 255 with Arrays default to Character Arrays.
NetLinx Programming Overview DEFINE_CALL (Subroutines) Axcess Language NetLinx Language Axcess provides two methods for incorporating sub- Like Axcess, NetLinx supports DEFINE_CALL and SYSTEM_CALL. NetLinx also supports functions, which routines into your program. are similar to a DEFINE_CALL(s). They can be used • DEFINE_CALL subroutines are defined in the standalone or in-line as an expression. program and support parameter passing into the call.
NetLinx Programming Overview DEFINE_START Axcess Language NetLinx Language DEFINE_START sets the initialization parameters for the Axcess program. This section defines buffers, levels, sets communication settings, and initializes variables. There is no difference between the way Axcess and NetLinx handle the DEFINE_START section of the program; however, the role of the DEFINE_START section is greatly reduced. Variable initializations are handled in the DEFINE_VARIABLE section.
NetLinx Programming Overview DEFINE_PROGRAM Axcess Language NetLinx Language The DEFINE_PROGRAM or mainline section of the Axcess program is where most of the programming process takes place. Axcess supports 99 reserved identifiers or keywords. 83 of these keywords can be used in the mainline. The DEFINE_PROGRAM or mainline section of the NetLinx program and the DEFINE_EVENTS section of code are responsible for processing events in a NetLinx system.
NetLinx 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.
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.
NetLinx Programming Overview NetLinx allows variables to be defined as constants in the DEFINE_VARIABLE section of the program or module, and in the LOCAL_VAR section of a DEFINE_CALL or a DEFINE_FUNCTION. Assigning constants is consistent with C++ programming conventions. Variables The role of the DEFINE_VARIABLE section is enhanced for NetLinx. The structure of a variable definition is: [NON_VOLATILE|VOLATILE][CONSTANT][] [= ] NetLinx handles variables just like Axcess.
NetLinx 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.
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.
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.
NetLinx Programming Overview DEFINE_TYPE STRUCTURE EMP { INTEGER EMP_NUM CHAR NI_NUM[9] CHAR F_NAME[16] CHAR L_NAME[16] FLOAT CONT_PENSION } Then, within the DEFINE_VARIABLE section, you create an instance of the structure and an array of the structure as follows: DEFINE_VARIABLE EMP JOHN_DOE EMP AMX_EMP[1000] Within the program, we use the information stored within the structure and assign information to the structure in the following manner: JOHN_DOE.EMP_NUM = 101 JOHN_DOE.
NetLinx Programming Overview The actual instancing of the structure is unique to the DEV structure because you separate the individual structure's elements with colons (:) instead of enclosing the structure with braces {} and separating the elements with commas (,).
NetLinx Programming Overview PUSH[MSP_GROUP,1] (* MSP_GROUP IS A DEV SET *) [RELAY, 1] = ![RELAY, 1] [MSP_GROUP, 1] = [RELAY, 1] - or PUSH[MSP_PRESET1] (* MSP_PRESET1 IS A DEVCHAN SET *) [RELAY,1] = ![RELAY, 1] [MSP_PRESET1] = [RELAY, 1] Conditionals & Loops Axcess supports two types of conditional statements and three types of loops: Conditional statements: IF...ELSE statements SELECT...
NetLinx Programming Overview Only the statements associated with the first case that matches the value of the expression are executed. Multiple CASE statements can be stacked within the SWITCH...CASE statement. If the value matches one of the CASE statements, the statements associated with the stack will be executed. If no CASE matches the SWITCH expression, then the statements under the default case (if available) are executed. The default statement must be the last case within the SWITCH...
NetLinx Programming Overview Parameters: Contains one or more statements that are executed one time before any FOR loop statements are executed; each statement must be separated by a comma (,). The condition for which the loop is evaluated before each pass. If the condition evaluates TRUE, the FOR loop statements execute. If the condition evaluates FALSE, the loop terminates.
NetLinx Programming Overview The NetLinx compiler passes all variables by reference. This means that the variable the subroutine operates on is the same variable the caller passed. Any change made to the variable, passed as a calling parameter, updates the variable's value from the caller's perspective. You can take advantage of this pass by reference feature by returning an updated value through a calling parameter rather than as the return value. Constants, on the other hand, are passed by value.
NetLinx Programming Overview Events Axcess is a linear environment. All interactions between external devices and the master processor are handled within mainline code. The processor runs mainline code, services the wait and pulse queues, and checks the bus for any changes in device status. We view these interactions or changes in status as Events, which fall into one of four categories: Button Events, Channel Events, Data Events, and Level Events.
NetLinx Programming Overview The following is an example of how a block of existing Axcess code can be rewritten using the NetLinx BUTTON_EVENT handler. The code below will send an 'A' to an RS-232 port defined as KC1 upon a button push and will repeat the 'A' string every 0.5 seconds until the button is released. Axcess Language NetLinx Language DEFINE_PROGRAM . .
NetLinx Programming Overview Here is the existing Axcess Code: DEFINE_PROGRAM . . PUSH[TP1,21] (* LIFT UP BUTTON *) { PULSE[RELAY,LIFT_UP] PULSE[VPROJ,VP_POWER_OFF] } PUSH[TP1,22] (* SYSTEM OFF BUTTON *) { PULSE[RELAY,RACK_OFF] PULSE[RELAY,LIFT_UP] PULSE[VPROJ,VP_POWER_OFF] } . . NetLinx Channel Event: DEFINE_EVENT . .
NetLinx Programming Overview Data Events Data Events provide some interesting capabilities in a NetLinx system. At first glance, it seems to be concerned with receiving strings of data either from a serial data device such as an NXC-COM2 card or an interface device such as a touch panel or WebLinx. While this is a valid function, DATA_EVENT has many more capabilities and works with many devices.
NetLinx Programming Overview upon receipt of another chunk of data, and is only done when data is received. For example, DATA.TEXT may equal {'over the lazy brown dog',ETX} and the DATA_BUFFER[500] might equal {STX,'The quick gray fox jumps over the lazy brown dog',ETX}. By evaluating the buffer value, you can evaluate the entire string at once. Two other important aspects of the DATA_EVENT are the ONLINE and OFFLINE event handlers.
NetLinx Programming Overview } ACTIVE (1): { (* keypad code *) } } } . . NetLinx Data Event: DEFINE_START CREATE_BUFFER TP1, TP1_BUFFER . . DEFINE_EVENT .. DATA_EVENT[TP1](* EVALUATE TP1 DATA *) { STRING: { SELECT { ACTIVE (FIND_STRING (DATA.TEXT,'PAGE-',1)): { JUNK = REMOVE_STRING (DATA.TEXT,'PAGE-',1) CUR_PAGE = DATA.TEXT } ACTIVE (FIND_STRING (DATA.TEXT,'KEYP-',1)): { (* keypad code *) } ACTIVE (FIND_STRING (DATA.
NetLinx Programming Overview . . Each event handler contains several imbedded data objects that pass data values into the event handler code. Level Events Level Events are triggered by a level change on a particular device. This eliminates constantly evaluating a level against a previous value. In Axcess, a level would need to be created in the DEFINE_START section and a conditional statement would appear in mainline to evaluate and update the level.
NetLinx Programming Overview Combining Devices, Channels and Levels Axcess allows you to combine devices and levels within the DEFINE_COMBINE and DEFINE_CONNECT_LEVEL sections. This method is static and is fixed when the program compiles. You can combine functionality within mainline by stacking push and release statements.
NetLinx Programming Overview COMBINE_LEVELS (, , …) UNCOMBINE_LEVELS () DEVLEV structures defined within the COMBINE_LEVELS are either individual DEVLEV structures or one dimension of a DEVLEV array. Any reference to the levels is handled through the first device in the list. Combining and uncombining channels Combining DEVCHANs is unique to NetLinx.
NetLinx Programming Overview Modules will eventually replace System calls. Where several system calls are currently needed to provide device initialization, buffer processing, and device functionality, one module will handle all three functions. The first line of a Module contains the MODULE_NAME keyword, the Module name, and the parameter list. The format is shown below: MODULE_NAME = '' [(, , … , )] The must match the file name, but has the .
Language Elements Language Elements Statements and Expressions A statement refers to a complete programming instructions such as: Y = X (* Variable Assignment Statement *) X = X + 1 (* Arithmetic Assignment Statement *) IF (Y < 10) Y = Y + 1 (* IF Statement *) [TP, 5] = [VCR, 1] (* Feedback Statement *) Each of these statements compile, providing the referenced variables are defined. Expressions are sub-components of statements.
Language Elements If it is non-zero, the channel associated with the device is turned on. If it is zero, the channel is turned off. Conditionals IF…ELSE The IF...ELSE statement provides a structure for conditional branching of program execution. If a condition evaluates to true, the statement(s) associated with it are executed; otherwise, statements are not executed.
Language Elements Regarding SELECT...ACTIVE statements: Only the statements associated with the first condition evaluated to true are executed. If no condition evaluates to true, no statements are executed. Braces underneath individual ACTIVE statements are required only if multiple statements are assigned to a given condition. SWITCH…CASE The SWITCH…CASE statement provides a programming structure for selective execution of code blocks based on the evaluation of a single condition.
Language Elements SWITCH (var) { CASE 1: { (*statements go here*) BREAK } CASE 3: { (*statements go here*) BREAK } CASE 5: { (*statements go here*) BREAK } DEFAULT: { (*statements go here*) BREAK } } Loops WHILE statements A WHILE statement executes its statement block as long as its associated condition evaluates to true. The condition is evaluated before the first pass through the statements. Therefore, if the conditional expression is never true, the conditional statements are never executed.
Language Elements MEDIUM_WHILE () { (* conditional statements *) } LONG_WHILE statements A LONG_WHILE differs from a WHILE statement in the way input change notifications are processed during the programming loop. The system checks the input queue for a change notification message before execution of each loop, beginning with the second loop. The message is retrieved if one exists.
Language Elements Waits Wait instructions allow delayed execution of one or more program statements. When a wait statement is executed, it is added to a list of currently active wait requests and the program continues running. Naming Waits Supplying a unique name in the wait statement allows the wait to be identified for purposes of canceling, pausing, or restarting the wait request. The name must not conflict with previously defined constants, variables, buffers, subroutines, or functions.
Language Elements Types of Waits (Cont.) Conditional Waits WAIT_UNTIL is a conditional Wait request. Syntax: WAIT_UNTIL [''] { (* wait statements *) } Parameters: • : Any single or compound expression that can be evaluated as a logical expression. The Wait statements are executed if and when the wait condition becomes True. • : The name to assign to the Wait. This name must be a literal string.
Language Elements WAIT_UNTIL 'FIRST WAIT' { (* FIRST WAIT statements *) WAIT_UNTIL 'SECOND WAIT' { (* SECOND WAIT statements *) } } Pausing and restarting Waits The following commands relate to pausing and restarting waits. Pausing and Restarting Waits PAUSE_WAIT PAUSE_WAIT puts a scheduled wait on hold. The wait being paused is identified by the parameter name. The wait timer stops counting down until it is resumed with a RESTART_WAIT command.
Language Elements Comments Comments are designated with a parentheses-asterisk to begin the comment and asterisk-parentheses to end the comment; for example, (*COMMENT*). These comments can span lines and are not limited in length. NetLinx supports a second type of comment with a double forward-slash (//). All text following the double forward-slash is treated as a comment. This type of comment closely follows the conventions of C++. Comments are not part of the actual program code; they are not compiled.
Language Elements Logical operators Logical operators compare two conditions or, in the case of NOT, invert one condition. A true or false result is produced. Logical Operators Operator Function Keyword && Logical And AND || Logical Or OR ^^ Logical Xor XOR ! Logical Not NOT Bitwise operators Bitwise operators are keywords or symbols that perform a bit-by-bit operation between two items.
Language Elements Operator precedence The table below shows the inherent precedence assigned to the operators. As noted in the chart, the NOT (!) operator has the highest precedence in NetLinx systems but the lowest precedence in Axcess systems. Axcess programs that are converted to NetLinx may exhibit logic problems if they use statements that combine NOT (!) and other operators. Contact AMX Technical Support for help resolving these issues.
Language Elements Device:Port:System (D:P:S): This notation is used to explicitly represent a device number, port, and system. For example, 128:1:0 represents the first port of the device number 128 on this system. The syntax: NUMBER:PORT:SYSTEM Parameters: Number 16-bit integer representing the Device number Port 16-bit integer representing the Port number (in the range 1 through the number of ports on the device) System 16-bit integer representing the System number (0 = this system).
Language Elements The index of the last member of the array for which an event notification was received can be determined by calling GET_LAST(MydeviceSet). This is useful for determining which device in an array is referenced in a particular notification message. Device array examples The command below sends 'CHARD10' to all devices in the array, DeviceSetA.
Language Elements A DEVCHAN array is declared in the DEFINE_VARIABLE or DEFINE_CONSTANT section in one of two ways: Declare a DEVCHAN array whose maximum length is determined by the number of elements in the initialization array on the right-hand side, as shown below: DEVCHAN[ ] DCSName = {{Dev1,Chan1}, {Dev2,Chan2}, ...} Use MAXLEN to specify the maximum length of the array, as shown below: DEVCHAN[ ] DCSName[MAXLEN] = {{Dev1,Chan1}, {Dev2,Chan2}, ...
Language Elements Declare a DEVLEV array whose maximum length is determined by the number of elements in the initialization array on the right-hand side. DEVLEV DLName[ ] = {{Dev1,Level1}, {Dev2,Level2}, ...} Use MAXLEN to specify the maximum length of the array. DEVLEV DLName[MAXLEN] = {{Dev1,Level1}, {Dev2,Level2}, ...} In either case, the number of elements in the initialization array determines the effective length of the array. That value can be determined at run-time by calling LENGTH_ARRAY.
Language Elements DEFINE_CALL 'My Subroutine' (INTEGER INT1) LOCAL_VAR INTEGER INT2 { (* body of subroutine *) } DEFINE_CALL 'My Subroutine' (INTEGER INT1) { LOCAL_VAR INTEGER INT2 (* body of subroutine *) } The scope of a local variable is restricted to the statement block in which it is declared.
Language Elements Define_function integer MyFunc(INTEGER nFlag) { LOCAL_VAR INTEGER n IF (nFlag > 0) { LOCAL_VAR INTEGER n // illegal declaration . . } . . } Define_function integer MyFunc(INTEGER nFlag) { IF (nFlag > 0) { LOCAL_VAR INTEGER n . .
Language Elements Modules are reusable NetLinx sub-programs that can be inserted into the main program. The main program is also a module. Refer to the NetLinx Modules section on page 143 for information on program modules. If a local variable shares the same name as a global variable, the local variable always takes precedence.
Language Elements 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".
Language Elements Data Types Intrinsic types The following table lists the data types inherently supported by the NetLinx language.
Language Elements Strings A string is an array of characters of known length. This length may be less than the dimensioned length. For example: DEFINE_VARIABLE CHAR MyString[32] INTEGER StrLen DEFINE_START MyString = 'STOP' StrLen = LENGTH_STRING(MyString) In the example above, StrLen holds the value 4, the length of MyString. The length of MyString can range from 0 to 32. If an attempt is made to assign a string longer than the capacity of the destination string, the copied string is truncated to fit.
Language Elements In the example above, if STOP is 2 and X is a wide character whose value is 1000, the string expression will evaluate to "2, 500, 79, 70, 70, 1000" and StrLen is 6. Each array element can now assume a value of up to 65,535, rather than the limit of 255 imposed by the standard character string. A CHAR string may be assigned or compared to a wide character string.
Language Elements DEFINE_VARIABLE CHAR StringTable_3[3][5] DEFINE_START CHAR StringTable_3[1] = 'Str 1' CHAR StringTable_3[2] = 'Str 2' CHAR StringTable_3[3] = 'Str 3' For multidimensional array types, the data pertaining to each dimension is delimited using braces, as shown below: INTEGER Num2D[ ][ ] = {{1, 3}, {2, 4}, {7, 8}} (* This sets the dimensions to Num2D[3][2] *) Arrays can be manipulated using the operator "=". The "=" operator is used to assign one array to another.
Language Elements Num1D[1] refers to the 1st element Num2D[1] refers to the 1st row Num2D[1][1] refers to the 1st element of the 1st row Num3D[1] refers to the 1st table Num3D[1][1] refers to the 1st row of the 1st table Num3D[1][1][1] refers to the 1st element of the 1st row of the 1st table The following operations are legal: Num2D[2] = Num1D Num2D[5][5] = Num1D[5] Num3D[2] = Num2D Num3D[2][1] = Num1D Num3D[2][1][1] = Num1D[1] LENGTH_ARRAY and MAX_LENGTH_ARRAY are used to determine the effec
Language Elements Structures A structure provides the ability to create a new data type composed of other data types arranged in a specified order. A structure is declared in the DEFINE_TYPE section of the program. Here's an example: DEFINE_TYPE STRUCTURE NEWSTRUCT { INTEGER Number CHAR Text[20] } In the example above, a structure named NEWSTRUCT is declared to contain two data types, a 16-bit number and a 20-character array.
Language Elements Subroutines A subroutine is a section of code that stands alone, and can be called from anywhere else in the program. DEFINE_CALL subroutines The DEFINE_CALL is the standard method provided by NetLinx for defining subroutines. DEFINE_CALL '' [(Param1,Param2,...)] { (* statements *) } where (Param1, Param2, ...) refers to a comma-separated list of pairs. For example, "INTEGER Size" would be one pair.
Language Elements For special cases where multiple copies of a system call are needed, an instance number can be specified in the call. The compiler will compile a separate copy of the subroutine for each system call instance number.
Language Elements ReadBuffer(Buffer,BufSize) Can be used in an assignment statement such as: Count = ReadBuffer(Buffer,BufSize) or as part of an expression such as: IF (ReadBuffer(Buffer,BufSize) > 0) { (* statements *) } The rules pertaining to calling parameters are the same for DEFINE_FUNCTION as they are for DEFINE_CALL subroutines. The parameter list must appear in parentheses to the right of the function name. If the function has no calling parameters a set of parentheses must still be included.
Language Elements Calling parameters Parameters may be passed to any NetLinx function or subroutine. Calling parameters are simply variables or constants that originate from the caller and are received by the function or subroutine being invoked. The NetLinx compiler passes all variables by reference. This means that the variable the subroutine operates on is the same variable the caller passed.
Language Elements 60 NetLinx Programming Language Reference Guide
Event Handlers Event Handlers The NetLinx language provides a special program section called DEFINE_EVENT to define handlers for incoming events/notifications. These handlers are stored in an event table providing quick access to code that must be executed when an event is received. There are handlers to support five types of events: Button events include pushes, releases, and holds, which are associated with a push or release on a particular device-channel.
Event Handlers CHANNEL refers to: CHANNEL A single channel number constant CHAN[ ] An integer array of channel numbers DEVCHAN[ ] A device-channel array LEVEL refers to: LEVEL A single level number constant LEV[ ] An integer array of level numbers DEVLEV[ ] A device-level array The processing of an event associated with a given member of a device, channel, device-channel, level, or device-array must be completed before processing can begin on another event associated with the same array.
Event Handlers Button Objects Property Name Type Description Button.Input DEVCHAN Device + Channel Button.Input.Channel INTEGER Channel Button.Input.Device DEV Device Button.Input.Device.Number INTEGER Device number Button.Input.Device.Port INTEGER Device port Button.Input.Device.System INTEGER System number Button.Holdtime LONG Current hold time in .10 second increments Button.SourceDev DEV Source device of button event Button.SourceDev.
Event Handlers Channel Objects Property Name Type Description Channel.Device DEV Device Channel.Device.Number INTEGER Device number Channel.Device.Port INTEGER Device port Channel.Device.System INTEGER System number Channel.Channel INTEGER Device channel Channel.SourceDev DEV Source Device of Channel Event Channel.SourceDev.Number INTEGER Source Device Number Channel.SourceDev.Port INTEGER Source Device Port Channel.SourceDev.System INTEGER Source Device System.
Event Handlers The following table lists the information contained in data objects: Data Objects Property Name Type Description Data.Device DEV Device Data.Device.Number INTEGER Device number Data.Device.Port INTEGER Device port Data.Device.System INTEGER System number Data.Number LONG Event number Data.SourceDev DEV Source Device of Data Event Data.SourceDev.Number INTEGER Source Device Number Data.SourceDev.Port INTEGER Source Device Port Data.SourceDev.
Event Handlers LEVEL_EVENT[DEVICE,LEVEL] or LEVEL_EVENT[([DEVLEV[ ])] { // level event handler } It contains the information shown in the table below. Level Objects Property Name Type Description Level.Input DEVLEV Device + Level that caused the event to occur Level.Input.Device DEV Device Level.Input.Device.Number INTEGER Device number Level.Input.Device.Port INTEGER Device port Level.Input.Device.System INTEGER System number Level.Input.Level INTEGER Level number Level.
Event Handlers NetLinx Button Event: LEVEL_EVENT [TEMP, 1] { IF (LEVEL.VALUE>= COOL_POINT) { ON[RELAY,FAN] } ELSE IF (LEVEL.VALUE <= HEAT_POINT) { OFF[RELAY,FAN] } } LEVEL_VALUE is an embedded object value in the LEVEL_EVENT statement. If the event handler is specified using an array for DEV, CHANNEL, or a DEVCHAN array, GET_LAST can be used to determine which index in the array caused the event to run.
Event Handlers If the event handler is specified using an array for DEV, INTEGER, or a DEVCHAN array, GET_LAST can determine which index in the array caused the event to run. Event Parameters It has already been stated that DEFINE_EVENT handlers are stored in an event table providing quick access to code that must be executed when an event is received. The event table keeps a list of all events in a sorted order to more quickly determine which code needs to be accessed for a giving incoming event.
Event Handlers In this example, the event will not perform as the previous one did. When the code is compiled, the event parameters are dvTp, which is already assigned, and nMyChannel, which has a value of 0. nMyChannel does not get assigned a value of 1 until DEFINE_START, at which time the event has already been added to the event table.
Event Handlers Will have the effect you expect button probably for a different reason than you expect. Although the event will run for both the push and release of all buttons for dvTp, you may also be tempted to think that you need to make sure the event runs for RELEASE_CHANNEL by adding the following: Example 5: DEFINE_EVENT BUTTON_EVENT[dvTp,PUSH_CHANNEL] BUTTON_EVENT[dvTp,RELEASE_CHANNEL] { PUSH: Send_String 0,"'Button ',ITOA(BUTTON.INPUT.
Event Handlers BUTTON_EVENT[dvMyPanels,nMyButtons] { PUSH: { nPanelIndex = GET_LAST(dvMyPanels) nButtonIndex = GET_LAST(nMyButtons) Send_String 0,"'Button Index=',ITOA(nButtonIndex),' was pushed on Panel Index=',ITOA(nPanelIndex)" } } This event will be run for all combinations of dvMyPanel and nMyButtons, 24 buttons in all. The GET_LAST() function is very useful when running event using array as parameters. GET_LAST() returns an index value, starting at 1, for the element that triggered the event.
Event Handlers TIMELINE_EVENT[TL1] Triggered TIMELINE_CREATE Time 0 1000 Timeline.Sequence = 2000 3000 4000 Time (1mS resolution) 1 2 3 4 5000 5 FIG. 2 Timeline representation } Each TIMELINE data member is defined as follows: ID The ID that the user assigned to the timeline in the TIMELINE_CREATE function. SEQUENCE The index of the time in the Times array that was passed to the TIMELINE_CREATE function.
Event Handlers TIMELINE_EVENT[TL1] // capture all events for Timeline 1 { switch(Timeline.Sequence) // which time was it? { case 1: { SEND_COMMAND dvPanel,"'TEXT1-1 1'" } case 2: { SEND_COMMAND dvPanel,"'TEXT1-1 2'" } case 3: { SEND_COMMAND dvPanel,"'TEXT1-1 3'" } case 4: { SEND_COMMAND dvPanel,"'TEXT1-1 4'" } case 5: { SEND_COMMAND dvPanel,"'TEXT1-1 5'" } } } TIMELINE_EVENT[TL2] { switch(Timeline.
Event Handlers TL1 uses TIMELINE_ABSOLUTE to specify that the times in TimeArray are absolute with respect to the start of the timeline. Since TL1 specifies the TIMELINE_REPEAT, it is also repeating and will generate a TIMELINE_EVENT every second iterating through all five times in a round-robin fashion: 1,2,3,4,5,1,2,3,4,5,1,2,3, and so on. TL2 uses TIMELINE_RELATIVE to specify that the times in TimeArray are relative to each other (i.e. each events occurs 1000 milliseconds after the previous).
Event Handlers LONG TimeArray[100] INTEGER iLoop (***********************************************************) (* STARTUP CODE GOES BELOW *) (***********************************************************) DEFINE_START (***********************************************************) (* THE EVENTS GOES BELOW *) (***********************************************************) DEFINE_EVENT TIMELINE_EVENT[MY_LINE_1] { switch(Timeline.
Event Handlers DEFINE_PROGRAM (***********************************************************) (* create will sort the order of the times but index stays *) (* with the time.
Event Handlers } (***********************************************************) (* Force time to a different value *) (***********************************************************) PUSH[dvPanel,6] { IF (TIMELINE_ACTIVE(MY_LINE_1)) TIMELINE_SET(MY_LINE_1,2000) } (***********************************************************) (* Get the current time from create *) (***********************************************************) PUSH[dvPanel,7] { SEND_COMMAND dvPanel,"'TEXT3-','Timer 1 Time is ',ITOA(TIMELINE_
Event Handlers TIMELINE IDs When creating a TIMELINE_EVENT, the timeline ID must be a user defined long constant. The NetLinx compiler will not semantic check the type of the timeline ID, and the NetLinx runtime system will attempt to cast the contents of the timeline ID constant, to a long constant. A runtime error will occur if the cast is unsuccessful.
Combining Devices, Levels, and Channels Combining Devices, Levels, and Channels The Axcess language supports the concept of combining several panels to make them behave as if they were one panel, in order to simplify code. This feature allows the combination of functionally identical devices, such as identically programmed Touch Panels and Softwire Panels. When the program references one of these devices, all other combined device arrays are also referenced.
Combining Devices, Levels, and Channels devices in the list. This includes level changes. For example, the statement ON [TP1,5Ø] will turn on channel 50 for all three devices in the list. Now let's see how the code example shown above would translate into NetLinx. DEFINE_COMBINE DEFINE_DEVICE VIRTUAL1 = 33000 TP1 = 128 TP2 = 129 TP3 = 130 DEFINE_COMBINE (VIRTUAL1, TP1, TP2, TP3) DEFINE_PROGRAM RELEASE[VIRTUAL1,1] { (*Do Something*) } Note the use of the virtual device (VIRTUAL1) in the above example.
Combining Devices, Levels, and Channels Refer to the Combining and Un-Combining Levels section on page 82 for more information. Un-combining devices UNCOMBINE_DEVICES reverses the effect of COMBINE_DEVICES. All combines related to the specified virtual device are disabled. A syntax example is: UNCOMBINE_DEVICES (VDC) Parameters: VDC The virtual device-channel passed to COMBINE_DEVICES. COMBINE_DEVICES (VDC, DCSet) . .
Combining Devices, Levels, and Channels RELEASE[VIRTUAL1,1] { (*Do Something*) } (*This will only see pushes when combine is NOT active*) RELEASE[TP1,1] { (*Do Something*) } Combining and Un-Combining Levels To approach setting up level combine and un-combine operations in NetLinx, let's first look at the way that level combine operations are done in the Axcess language. The example below illustrates how an Axcess program would combine three Touch Panel levels to act as one.
Combining Devices, Levels, and Channels coming from the virtual device. Output changes, directed to the virtual device or any device in the array, are sent to all devices in the array. The syntax must follow one of these two forms: DEFINE_CONNECT_LEVEL (Vdevice1, 1, DEVLEV [ ]) - or DEFINE_CONNECT_LEVEL (VDEVLEV, DEVLEV [ ]) Combining levels COMBINE_LEVELS connects a single device-level array (DEVLEV[ ]) to a DEVLEV array.
Combining Devices, Levels, and Channels TP4 = 131 DEFINE_PROGRAM (*Activate dynamic level combine*) RELEASE[TP4,1] { COMBINE_LEVELS(VIRTUAL1,1,TP1,1,TP2,1,TP3,1) } (*Remove dynamic level combine*) RELEASE[TP4,1] { UNCOMBINE_LEVELS(VIRTUAL1,1) } Combining and Un-combining Channels Combining channels COMBINE_CHANNELS connects a single virtual device-channel to one or more channels on another device (or devices).
Combining Devices, Levels, and Channels The 6 examples in the program below demonstrate the use of COMBINE_CHANNELS and UNCOMBINE_CHANNELS: PROGRAM_NAME='CombineChannelsExample' DEFINE_DEVICE // common devices for all examples below dvTP = 128:1:0 dvREL10 = 301:1:0 dvIO10 = 310:1:0 vdvControl = 33000:1:0 // example of combining a DEVCHAN set to a virtual [DEV,CHAN] pair DEFINE_VARIABLE DEVCHAN dc1[] = {{dvIO10,1},{dvREL10,1},{dvTP,1}} DEFINE_EVENT BUTTON_EVENT[dvTP,11] // combine_channels 1 { RELEASE: { CO
Combining Devices, Levels, and Channels BUTTON_EVENT[dvTP,14] // uncombine_channels 2 { RELEASE: { UNCOMBINE_CHANNELS (vdvControl,2) } } BUTTON_EVENT[vdvControl,2] // this will work when the combine_channels above is invoked { PUSH: { TO[BUTTON.
Combining Devices, Levels, and Channels { PUSH: { TO[BUTTON.
Combining Devices, Levels, and Channels { RELEASE: { COMBINE_CHANNELS (vdc5,dc5[1],dc5[2],dc5[3]) } } BUTTON_EVENT[dvTP,20] // uncombine_channels 5 { RELEASE: { UNCOMBINE_CHANNELS (vdc5) } } BUTTON_EVENT[vdc5] // this will work when the combine_channels above is invoked { PUSH: { TO[BUTTON.
Combining Devices, Levels, and Channels BUTTON_EVENT[vdc6] // this will work when the combine_channels above is invoked { PUSH: { TO[BUTTON.
Combining Devices, Levels, and Channels 90 NetLinx Programming Language Reference Guide
Master-To-Master (M2M) Master-To-Master (M2M) The functionality of Master-to-Master (M2M) includes several new features including Master routing and intersystem control. Master routing supports the ability to route messages to any other Master or device and is the foundation of all M2M functionality. Intersystem control allows a Master, or its NetLinx program, to control and get status of any other device (or master) connected to another Master.
Master-To-Master (M2M) Master Routing Master routing primarily involves the communication of routing tables between masters. Routing tables are exchanged between masters upon their initial connection, and updates to the routing tables are exchanged as the connections change. NetLinx masters do not automatically connect to other NetLinx masters by virtue of being on the same network. The URL List of the NetLinx master is used to force the master to initiate a TCP connection to the specified URL/IP address.
Master-To-Master (M2M) -> The "->" to the left of system # 5 indicates that system # 5 is the local system (i.e. the system that the telnet session is connected to). System column Lists all of the systems in the master's routing table. Route column Indicates which system number packets are to be routed to in order to get to their destination. For example, to send a message from System #5 to System #1, the message must be sent to/through System #2.
Master-To-Master (M2M) FIG. 4 shows that a maximum of 64 systems can be interconnected using a two-dimensional interconnection topology. Using a three-dimensional topology, even more systems can be interconnected (FIG. 5). FIG. 5 Three-dimensional view of the maximum number of interconnected NetLinx masters FIG. 5 shows that a maximum of 512 systems can be interconnected using a three-dimensional interconnection topology. Note that for the diagram in FIG.
Master-To-Master (M2M) Control/NetLinx Language Support The features of control to M2M include channel control (PUSH/RELEASE/ON/OFF/TO), level control, send commands, and send strings. Channel controls allow one NetLinx master to PUSH/RELEASE a channel on a device of another system via the DO_PUSH/DO_RELEASE functions. Additionally, ON, OFF, TO, and feedback statements can control channels on devices of remote systems.
Master-To-Master (M2M) 96 NetLinx Programming Language Reference Guide
Mainline Mainline Mainline is the program section executed continuously by the NetLinx Central Controller as long as the Controller has power. DEFINE_PROGRAM contains the code known as mainline. A typical NetLinx program is composed of a number of different sections. Each section defines some aspect of a program such as device definitions, variable declarations, channel characteristics, or event processing. The sections that can comprise a NetLinx program are listed in the following table.
Mainline FIG.
Reserved Identifiers Reserved Identifiers Compiler Directives The compiler directives supported by NetLinx are described in the table below. Compiler Directives #DEFINE This directive defines a symbol to be used only by #IF_DEFINED and #IF_NOT_DEFINED directives. #DEFINE [] The name of the symbol must be unique among all other identifiers in the program.
Reserved Identifiers Compiler Directives (Cont.) #INCLUDE To include a file in a program, use the keyword #INCLUDE followed by the filename in single quotes. DEFINE_PROGRAM (* Program statements can go here *) #INCLUDE 'TEST.AXI' (* More program statements can go here *) When the compiler reaches the #INCLUDE statement, it jumps into the specified file and continues compiling. When it has reached the end of that file, it comes back to the line following the #INCLUDE statement and continues compiling.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) ADD_URL_ENTRY This function adds a URL entry to the specified device. The function requires a pre-initialized URL_STRUCT that will be sent to the specified device. SLONG ADD_URL_ENTRY (DEV Device, URL_STRUCT Url) Parameters: • Device: Device number of the device that stores the URL. Typically, it is stored on the local master (0:1:0); if you are currently connected to another master, you can use <0:1:system number of remote master>.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) ATOI Converts a character representation of a number to an signed 32-bit integer. The syntax: SLONG ATOI (CHAR STRING[ ]) Parameters: • STRING - string containing the character representation of the integer. Result: • A 32-bit signed integer representing the converted string. • Any non-numeric characters in the string are ignored. • ATOI returns the value representing the first complete set of characters that represents an integer.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) BREAK The BREAK command terminates execution of the current WHILE, LONG_WHILE, or FOR loop and resumes program execution at the first instruction following that loop. BREAK also jumps to the end of a SWITCH statement. WHILE () { // statements IF () { BREAK // Go to statement: X = X + 1 } } // Execution continues here after BREAK or // after normal completion of the WHILE loop.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) CANCEL_WAIT_UNTIL This keyword cancels a specified WAIT_UNTIL or TIMED_WAIT_UNTIL. Only named WAIT_UNTIL and named TIMED_WAIT_UNTIL commands can be canceled. CASE See SWITCH..CASE on page 153. CHANNEL_EVENT The CHANNEL keyword defines a channel event handler. This type of handler is invoked when an output change occurs on the specified device-channel and can only be used in the DEFINE_EVENT section of the program.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) CLKMGR_ADD_USER DEFINED_TIMESERVER Adds a user-defined time server entry. CLKMGR_DELETE_USER DEFINED_TIMESERVER Deletes the user-defined entry that has its IP-ADDRESS matching the parameter.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) CLKMGR_GET_ TIMESERVERS Populates the currently configured time server entries from the Clock Manager into the specified TIMESERVER array. CLKMGR_GET_TIMESERVERS (CLKMGR_TIMESERVER_STRUCT T[]) The function returns a negative SLONG value if it encounters an error, otherwise the return value is set to the number of records populated into the CLKMGR_TIMESERVER_STRUCT array.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) CLKMGR_SET_RESYNC_ PERIOD Sets the re-sync period to the specified minute value. CLKMGR_SET_RESYNC_PERIOD (CONSTANT INTEGER PERIOD) The upper bound is 480 minutes (i.e., 8 hours). CLKMGR_SET_START_ DAYLIGHTSAVINGS_RULE Sets the START Daylight Savings rule to the specified string which must be in either the Fixed-Date format or the Occurence-Of-Day format.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) COMBINE_DEVICES This keyword defines the combination of functionally identical devices, such as identically programmed touch panels. When the program references one of these devices, all other combined devices in the array are also referenced. The devices in a given array must be enclosed in parentheses. A virtual device is one that does not actually exist but merely represents one or more physical devices.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) COMPARE_STRING This keyword compares two character strings. If either string contains a '?' character, the matching character in the other string is not compared. The '?' is equivalent to a wilcard.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) CREATE_LEVEL This keyword creates an association between a specified level of a device and a variable that will contain the value of the level. This can only appear in the DEFINE_START section of the program. CREATE_LEVEL DEV, Level, Value Parameters: • DEV: The device from which to read the level. • Level: The level of the device to read. • Value: Variable in which to store the level value. • DevLev: A DEVLEV structure.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) CREATE_MULTI_BUFFER (Cont.) • Strings from a device longer than 255 bytes will be broken up into multiple "multi" strings within the buffer.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DATE The system variable DATE returns the current date in (mm/dd/yy) string format. The wildcard character "?" is not allowed for string comparisons because the actual date is needed. IF (DATE = '12/25/00') { } You can replace the wildcard feature by using the COMPARE_STRING function. DAY The system variable DAY returns the current day of the week as one of the following strings: 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT' or 'SUN'.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DEFINE_CALL This keyword defines the implementation of a NetLinx subroutine. DEFINE_CALL '' [(P1,P2,...)] { // body of subroutine } The subroutine name cannot be a previously defined device name, constant, or variable, or a name assigned to a buffer or a wait statement. DEFINE_CALL names are case sensitive and may contain spaces. Note: Subroutines must be defined before they can be used.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DEFINE_DEVICE This keyword defines the devices referenced in the program.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DEFINE_MUTUALLY_ EXCLUSIVE When a channel is turned on in a mutually exclusive set, it activates its physical output as long as the button is pressed. When the button is released, the physical output stops. Even after the physical output stops, the feedback still indicates the channel is on until another channel in the mutually exclusive set is activated.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DEFINE_VARIABLE This keyword declares global variables. Any variable defined in this section is static (its value is maintained throughout the duration of program execution) with module scope (it is accessible from any instruction in the current module). DEFINE_VARIABLE INTEGER INT1 FLOAT FP1 VOLATILE INTEGER BIGARRAY[1000][1000] Note: 1000 marks the limit of the string. See the Variables section on page 11 for more information.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DEVICE_INFO NetLinx stores information, such as manufacturer, device name and device ID, for each device in the system. The DEVICE_INFO keyword allows a programmer to access all available information for any device. If the device does not exist in the system, a Device ID of zero is returned. This keyword is usually used to determine the firmware version of a device in the system.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DEVICE_INFO (Cont.) Example: DEFINE_DEVICE dvNL = 0:1:0 DEFINE_VARIABLE DEV_INFO_STRUCT sDeviceInfo DEFINE_EVENT DATA_EVENT[dvNL] { ONLINE: { DEVICE_INFO(dvNL, sDeviceInfo) SEND_STRING 0,"'MANUFACTURER_STRING=', sDeviceInfo.MANUFACTURER_STRING" SEND_STRING 0,"'MANUFACTURER=',ITOA(sDeviceInfo.MANUFACTURER)" SEND_STRING 0,"'DEVICE_ID_STRING=', sDeviceInfo.DEVICE_ID_STRING" SEND_STRING 0,"'DEVICE_ID=',ITOA(sDeviceInfo.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) DO_PUSH This keyword causes an input change from OFF to ON to occur on a specified device-channel without the device-channel being activated by external means. To prevent the program from stalling mainline too long, there is a 0.5 second timeout on DO_PUSH. DO_PUSH defaults to a 0.5 second push on a channel before issuing a DO_RELEASE for you (unless another DO_PUSH is executed for the same channel).
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FILE_CLOSE This function closes a file opened with FILE_OPEN. This function should be called when all reading or writing to the file is completed. SLONG File_Close (LONG hFile) Parameters: • hFile: Handle to the file returned by File_Open. Result: • 0: Operation was successful • -1: Invalid file handle • -5: Disk I/O error • -7: File already closed There is a limit to the number of file handles available from the system.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FILE_CREATEDIR Creates a specified directory path. Syntax: SLONG File_CreateDir (CHAR DirPath[ ]) This function will not create the number of subdirectories needed to complete the directory path if they do not exist. The subdirectories must be created one level at a time. Note: The LONG command cannot pass negative numbers, so if you have errors these will never be recognized.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FILE_GETDIR This function returns the current working directory. SLONG FILE_GETDIR (CHAR DirPath[ ]) Parameters: • DirPath: Buffer to receive the current working directory. Result: • 0: Operation was successful • -10: Size of DirPath buffer insufficient to hold directory path name CHAR Buffer[256]Result = FILE_GETDIR (Buffer) FILE_OPEN This function opens a file for reading or writing.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FILE_READ This function reads a block of data from the specified file.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FILE_REMOVEDIR This function removes the specified directory path, but it will not remove files or directories below it. CAUTION: If a subdirectory or files exist in the directory that you are trying to remove, the operation will fail and will return a -5 (disk IO error). SLONG FILE_REMOVEDIR (CHAR DirPath[ ]) Parameters: • DirPath: String containing the directory path to remove.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FILE_SETDIR This function sets the current working directory to the specified path. SLONG FILE_SETDIR (CHAR DirPath[ ]) Parameters: • DirPath: String containing the directory path. Result: • 0: Operation successful • -4: Invalid directory path • -5: Disk I/O error Result = FILE_SETDIR ('\CDLIST\TEMP\') FILE_WRITE This function writes a block of data to the specified file.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FIND_STRING This function searches through a string for a specified sequence of characters. INTEGER FIND_STRING (CHAR STRING[ ], CHAR Seq[ ], INTEGER Start)INTEGER FIND_STRING (WIDECHAR STRING[ ], WIDECHAR Seq[ ], INTEGER Start) Parameters: • STRING: The string of character to search. • Seq: The sequence of characters to search for. • Start: The starting character position for the search.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FORMAT Provides a mechanism similar to 'C's printf statement for formatting the display of numbers. This function is similar to ITOA but is infinitely more powerful.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) FORMAT (Cont.) The result is a formatted text string. fTemperature = 98.652 STR = FORMAT('The current temperature is %3.2f',fTemperature) // Displays "The current temperature is 98.65" The table below shows some examples of the output of FORMAT for several different format lines and values: FORMAT Statement Result of FORMAT function FORMAT('%-5.2f',123.234) FORMAT('%5.2f',3.234) FORMAT('%+4d',6) FTOA '123.23' '3.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) GET_DNS_LIST This function returns the domain name and list of DNS server IP addresses that the specified device is programmed to utilize. The order of the returned list is the preferred server order. DNS_STRUCT DnsListresult = GET_DNS_LIST(0:0:0,DnsList) SLONG GET_DNS_LIST(DEV Device,DNS_STRUCT DnsList ) Parameters: • Device: Device from which the DNS servers will be retrieved.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) GET_IP_ADDRESS (Cont.) The Flags member is a bit field that may be used for several different purposes. Each bit is defined below: Differing configuration parameters may be obtained, depending upon the configuration of the network DHCP server. It is possible that the DHCP server will provide the host name, IP address, subnet mask, gateway, and even DNS information.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) GET_MULTI_BUFFER_ STRING To access characters coming into a multi-buffer, you must first use GET_MULTI_BUFFER_STRING to transfer these characters into another array. For example: Device = GET_MULTI_BUFFER_STRING (Buffer, Array) The next string in the specified buffer is copied to the specified array. All three header bytes are stripped before the string is copied.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) GET_URL_LIST This function returns a list of URLs that the specified device is programmed to actively attempt to connect to. The function requires an array of URL_STRUCT Structures that will get filled in with the device's URL list. SLONG Get_URL_List(DEV Device,URL_STRUCT UrlList[ ],INTEGER Type ) Parameters: • Device: Device number of the device from which the URLs will be retrieved.
Reserved Identifiers The Flags member is a bit field that is used for several different purposes. Each bit is defined in the table below: GET_URL_LIST flags member bit fields Bit Mathematical Value Normal value Bit 0 1 (0x01) 1 Meaning 0 = Establishes a UDP connection. 1 = Establishes a TCP connection. Bit 1 2 (0x02) 0 Unused Bit 2 4 (0x04) 0 Unused Bit 3 8 (0x08) 0 Unused Bit 4 16 (0x10) 0 Establishes a Temp Connection.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) HOLD This keyword defines a section in a BUTTON event handler for processing HOLD events. IF This keyword defines an IF statement; the IF statement provides conditional branching of program execution. IF () { // statements } ELSE IF () { // statements } ELSE { // statements } The ELSE IF and ELSE statements are optional.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) IP_CLIENT_OPEN This function opens a port for IP communication with a server. SLONG IP_CLIENT_OPEN (INTEGER LocalPort, CHAR ServerAddress[ ], LONG ServerPort, INTEGER Protocol) Parameters: • LocalPort: A user-defined (non-zero) integer value representing the local port on the client machine to use for this conversation. This local port number must be passed to IP_Client_Close to close the conversation.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) IP_MC_SERVER_OPEN This function opens a server port to listen for UDP multicast messages. SINTEGER IP_MC_SERVER_OPEN(INTEGER LocalPort, CHAR MultiCastIP[], LONG ServerPort) Parameters: • LocalPort: The local port number to open. This number must be passed to IP_SERVER_CLOSE to close the port. • MultiCastIP: A character string representing the multicast address to receive on in the form of: '239.255.255.250'.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) IP_SERVER_OPEN This function opens a server port to listen for client requests. SLONG IP_SERVER_OPEN (INTEGER LocalPort, LONG ServerPort, INTEGER Protocol) Parameters: • LocalPort: The local port number to open. This number must be passed to IP_Server_Close to close the port. • ServerPort: The number of the server port to listen on.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) LEFT_STRING This function returns the specified number of characters from the beginning of a string. CHAR[ ] LEFT_STRING (CHAR STRING[ ], LONG Count) WIDECHAR[ ] LEFT_STRING (WIDECHAR STRING[ ], LONG Count) Parameters: • STRING: The string from which to extract the characters. • Count: The number of character to copy from the beginning of the string. The result is a string containing a copy of the first Count characters from STRING.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) LENGTH_STRING This function returns the length of a CHAR or WIDECHAR string. This function is retained for compatibility with previous versions of Axcess and provides the same information as LENGTH_ARRAY. LONG LENGTH_STRING (CHAR STRING[ ]) LONG LENGTH_STRING (WIDECHAR STRING[ ]) Parameters: • STRING: The input character string. The result is the length of STRING.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) LONG_WHILE This keyword is the same as a WHILE statement except that input messages are retrieved after each pass to allow the LONG_WHILE statements to process the input. LONG_WHILE (){(* conditional statements *)} See the Language Elements section on page 31 for more on programming loop constructs. LOWER_STRING This function changes all alphabetic characters in the specified string to lower case.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) MAX_LENGTH_STRING This function returns the dimensioned length of a CHAR or WIDECHAR string. This function is retained for compatibility with previous versions of Axcess. It provides the same information as MAX_LENGTH_ARRAY. LONG MAX_LENGTH_STRING (CHAR STRING[ ]) LONG MAX_LENGTH_STRING (WIDECHAR STRING[ ]) Parameters: • STRING: The input character string. Result: The dimensioned length of STRING.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) MOD (%) This keyword is used to generate the remainder of a division function. Note: You cannot take the mod of an integer without first loading the value into a variable. For example: VRAM_LSB = ((2 % 16)+$30) (* does not work *) However, ID = 2 OTHER = 16 VRAM_LSB = ((ID % OTHER) + $30) MODULE_NAME (* works *) This keyword introduces the definition of a module. It must appear on the first line of the module implementation file.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) PERSISTENT If a variable is declared with the PERSISTENT keyword, it is initialized to zero the first time the program is loaded but will retain its value after power-down or reload. • The PERSISTENT attribute does not apply to non-static local variables, since non-static local variables are allocated on the program stack (a block of memory reserved for allocation of temporary variables).
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) REBOOT This keyword causes the device to reset and is equivalent to doing a power down and up on the master. REBOOT (DEVICE) Parameters: • DEVICE = ICSP device number to reboot. Note: Not all ICSP devices implement the reboot command. DEVICE refers to: - Device – a single device number. - Dps – a DEV structure. - D:P:S – a device specification such as 128:1:0. - DEV[ ] – a device array.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) REBUILD_EVENT() (Cont.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) REBUILD_EVENT() (Cont.) { SET_LENGTH_ARRAY(nBtns,4000) REBUILD_EVENT() } BUTTON_EVENT[dvTP,nBtns] { PUSH: { // ... } } // end REDIRECT_STRING This keyword is used to pass all strings from device 1 to device 2 and all strings from device 2 to device 1. This is called a redirection and you can assign up to eight at one time. REDIRECT_STRING (Number, DEV1, DEV2) The parameter Number identifies the particular redirection (1-8).
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) REMOVE_STRING This function removes characters from the specified string. All characters up to and including the first occurrence of the specified sequence are removed. CHAR[ ] REMOVE_STRING (CHAR STRING, CHAR Seq[ ], LONG Start) WIDECHAR[ ] REMOVE_STRING (WIDECHAR STRING, WIDECHAR Seq[ ], LONG Start) Parameters: • STRING: String from which to find and remove characters. • Seq: Sequence of characters to find.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) RSHIFT This keyword causes the bits in the associated value field to be shifted right. This has the effect of dividing by 2n where n is the number of bit positions to shift. The symbol >> is equivalent to RSHIFT. For example: INT2 = INT1 RSHIFT 2 is equivalent to: INT2 = INT1 >> 2 Both statements shift INT1 right two positions.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) SET_DNS_LIST This function programs a domain name and the list of DNS servers that the specified device will use to lookup domain names. It requires a pre-initialized DNS_STRUCT structure that will be sent to the specified device.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) SET_IP_ADDRESS (Cont.) The following definitions exist for the Flags member of the IP_ADDRESS_STRUCT structure. CONSTANT CHAR IP_Addr_Flg_DHCP = 1 // Use DHCP The Flags member is a bit field that may be used for several different purposes. Each bit is defined below: Differing configuration parameters may be obtained, depending upon the configuration of the network DHCP server.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) SET_SYSTEM_NUMBER Sets the system number of the NetLinx master. The new system number will take effect after the system has been rebooted. SLONG SET_SYSTEM_NUMBER (INTEGER newSystemNum) Parameters: • newSystemNum: Desired new system number Result: • 0: Operation was successful. • -1: System number is invalid. • -2: Assignment of system number causes conflict.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) STACK_VAR This keyword specifies a non-static variable. A non-static variable's value is reinitialized every time the statement block in which it is declared is executed. References to STACK_VAR variables are not allowed within waits. STACK_VARs are temporary variables that cease to exist when the block in which they are declared is exited. If neither the LOCAL_VAR nor the STACK_VAR keyword is specified, STACK_VAR is assumed.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) SWITCH...CASE This keyword statement provides a programming construct for selective execution of code blocks based on the evaluation of a single condition.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) TIME_TO_SECOND This function returns an integer representing the second portion of a time string. SINTEGER TIME_TO_SECOND (CHAR TimeStr[ ]) Parameters: • TimeStr: Input string containing the time in hh:mm:ss format. If successful, this function returns an integer (0-59) representing the second portion of the time string. If the specified time is invalid, this function returns -1.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) TIMELINE_EVENT These events are generated when a timeline's internal timer is equal to one of the specified times in the times array. The TIMELINE_EVENT must be placed in the DEFINE_EVENT section of the program. TIMELINE_EVENT[timelineID] See the TIMELINE_CREATE function (above) for a more detailed description. TIMELINE_GET This function returns the value of the specified timeline's timer.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) TIMELINE_RELOAD This function is used to change the array times of a timeline. The new array of times takes affect immediately even if the timeline is currently executing. If the timeline is executing when this function is called the timeline continues to execute and the next matching time from the new array triggers an event.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) TO This keyword activates a channel or variable for as long as the corresponding channel of its PUSH statement is activated. When the channel referenced by the PUSH statement changes from off to on, the TO command starts activating the associated channel or variable. When the channel is released, the TO command stops activating of the channel or variable. Therefore, a TO statement must be found underneath a PUSH statement only.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) UNCOMBINE_LEVELS This keyword reverses the effect of COMBINE_LEVELS. All combines related to the specified virtual device-level are disabled. SLONG UNCOMBINE_LEVELS VDL Parameters: VDL: The virtual device-channel passed to COMBINE_LEVELS.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) VARIABLE_TO_XML SINTEGER VARIABLE_TO_XML(CONSTANT VARIANTARRAY A,CHAR B[], LONG C, LONG D) Where: • A is the variable (any type) to be encoded: • B is the CHAR array to hold the resulting XML. • C is the beginning encoding position. Encoding will start as B[C]. • D is the encoding flag. These can be used together. Value $01 is "Encode with Types". If the bit is set, types will be included for every variable being encoded.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) VARIABLE_TO_XML (Cont.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) VARIABLE_TO_XML (Cont.) RELEASE: { } } // Convert To Binary lPos = 1 slReturn = STRING_TO_VARIABLE(MyAlbumStruct, sBinaryString, slPos) // OR Convert To XML slPos = 1 slReturn = XML_TO_VARIABLE (MyAlbumStruct, sXMLString, slPos, 0) VOLATILE This keyword is used as part of a variable declaration to specify that storage space for the variable be allocated in volatile memory.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) XML_TO_VARIABLE SINTEGER XML_TO_VARIABLE(VARIANTARRAY A,CONSTANT CHAR B[], LONG C, LONG D) Where: • A is the variable (any type) to be encoded. • B is the CHAR array holding the source XML. • C is the next beginning encoding position. Encoding ended at B[C-1]. • D are the decoding flags. They can be used together. Value $01 is "Force Types When Decoding".
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) XML_TO_VARIABLE (cont.) PUSH: { // Convert To Binary lPos = 1 slReturn = VARIABLE_TO_STRING(MyAlbumStruct, sBinaryString, lPos) SEND_STRING 0,"’POSITION=’,ITOA(lPos),’ – Result = ‘,ITOA(slReturn)" // Convert To XML lPos = 1 slReturn = VARIABLE_TO_XML(MyAlbumStruct, sXMLString, lPos, 0) SEND_STRING 0,"’POSITION=’,ITOA(lPos),’ – Result = ‘,ITOA(slReturn)" // Save Structure to Disk - Binary slFile = FILE_OPEN(‘BinaryEncode.
Reserved Identifiers Keywords & Run-Time Library Functions (Cont.) XOR (^^) This keyword evaluates two conditions. One and only one condition can be true for the entire expression to be true. Send_Commands Two new Send_Commands have been added to the master. The new commands enable or disable a feature that helps synchronize level values. By default, this feature is disabled for compatibility reasons.
Reserved Identifiers Axcess does not support making elements of an INTEGER array mutually exclusive. Cause: This has always worked this way, even in Axcess.
Reserved Identifiers 166 NetLinx Programming Language Reference Guide
Compiler Messages Compiler Messages Compiler Warnings Sometimes the compiler generates a warning message instead of an error message; these warning messages always start with w. A warning about a particular statement means that the statement is not technically an error, but you should be careful doing it. Warnings, unlike errors, do not stop the program from compiling. (w) Cannot assign unlike types This warning occurs when a variable or value of one type is assigned to a variable of a different type.
Compiler Messages (w) Variable is not used This warning occurs at the end of compilation for each variable that was declared but never used. Compiler Errors The compiler informs you when it finds an error during the compilation process. Most of the time these errors occur due to a typographical error or incorrect syntax of a particular command. Unlike warnings, errors must be corrected before your NetLinx program can be executed.
Compiler Messages Evaluation stack overflow The expression is too complicated. Try breaking it up into smaller pieces. Evaluation stack underflow The expression is too complicated. Try breaking it up into smaller pieces. Identifier expected The compiler is expecting an identifier after a #DEFINE statement or after an integer declaration in the DEFINE_VARIABLE section. Identifier is not an array type A non-array variable was treated as an array.
Compiler Messages PUSH_CHANNEL not allowed within Wait These keywords are not allowed in a section of code which will be executed due to a WAIT keyword. RELEASE_CHANNEL not allowed within Wait These keywords are not allowed in a section of code which will be executed due to a WAIT keyword. PUSH_DEVICE not allowed within Wait These keywords are not allowed in a section of code which will be executed due to a WAIT keyword.
Compiler Messages This all applies to MIN_TO also. Too few parameters in CALL There are not enough parameters being passed to the subroutine. Too many include files In NetLinx, the number of Include files allowed is limited only by the amount of memory available on the PC at compile time. Too many parameters in CALL There are too many parameters being passed to the subroutine. Type mismatch in function CALL A function was called with a parameter of the wrong type.
Compiler Messages Bad assign Call... These errors occur if the Central Controller cannot assign a parameter in a CALL statement to the parameter in the corresponding DEFINE_CALL statement. Bad element assign... These errors occur if an assignment is attempted past the end of an array, or to the Ø location of an array (for example, ARRAY[Ø]). Bad Off... Bad On... Bad To... These errors indicate that the device-channel or variable that is being referenced by an OFF, ON, or TO keyword is out of range.
NetLinx UniCode Functions NetLinx UniCode Functions Overview NetLinx UniCode Functions allow programmers to embed Unicode String literals in their NetLinx programs, manipulate them using run-time functions and send them to touch panels and other user interfaces. NetLinx UniCode Functions _WC This keyword is a macro for Unicode strings. All Unicode string literals must be contained in single quotes and in the _WC macro.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_DECODE This function decodes Unicode string from a character string using one of 4 formats. WIDECHAR[ ] WC_DECODE(CHAR cData[], INTEGER Format, LONG Start) Parameters: • cData: String containing the encoded Unicode string • Format: 1 Unicode: The data is encoded as a Unicode formatted stream. The constant WC_FORMAT_UNICODE is defined as a value of 1 for specifying this format.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_FILE_CLOSE This function closes a file opened with WC_FILE_OPEN. This function should be called when all reading or writing to the file is completed. SLONG WC_FILE_CLOSE (LONG hFile) Parameters: • hFile: Handle to the file returned by WC_FILE_OPEN. Result: • 0: Operation was successful • -1: Invalid file handle • -5: Disk I/O error • -7: File already closed There is a limit to the number of file handles available from the system.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_FILE_OPEN This function opens a file for reading or writing. SLONG FILE_OPEN (CHAR FilePath[ ], LONG IOFlag, LONG Format) Parameters: • FilePath: String containing the path to the file to be opened • IOFlag: 1 Read: The file is opened with READ ONLY status. The constant FILE_READ_ONLY is defined as a value of 1 for specifying this flag. 2 R/W New: The file is opened with READ WRITE status. If the file currently exists, its contents are erased.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_FILE_READ This function reads a block of widechar data from the specified file.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_FILE_WRITE This function writes a block of widechar data to the specified file. SLONG WC_FILE_WRITE (LONG hFile, WIDECHAR Buffer[ ], LONG BufLen) Parameters: • hFile: Handle to the file returned by WC_FILE_OPEN. • Buffer: Buffer containing the data to write. • BufLen: Number of characters to write.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_GET_BUFFER_CHAR This keyword removes a character from a buffer. WIDECHAR WC_GET_BUFFER_CHAR (WIDECHAR A[]) The result is a WIDECHAR value. WC_GET_BUFFER_CHAR has a two-part operation: 1. Retrieve the first character in the buffer. 2. Remove the retrieved character from the buffer and shift the remaining characters by one to fill the gap.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_LOWER_STRING This function changes all alphabetic characters in the specified string to lower case using the case mapping defined by Unicode.org. WIDECHAR[ ] WC_LOWER_STRING (WIDECHAR STRING[ ]) Parameters: • STRING: The widechar string to convert to lower case. Result: The result is the converted widechar string. wcLCString = WC_LOWER_STRING(wcSTRING) WC_MAX_LENGTH_STRING This function returns the dimensioned length of a WIDECHAR string.
NetLinx UniCode Functions NetLinx UniCode Functions (Cont.) WC_RIGHT_STRING Returns the specified number of characters from the end of a string. WIDECHAR[ ] WC_RIGHT_STRING (WIDECHAR STRING[ ], LONG Count) Parameters: • STRING: The string from which to extract the characters. • Count: The number of character to copy from the end of the string. Result: The return is a string containing a copy of the last Count characters from STRING.
NetLinx UniCode Functions Working With UniCode in NetLinx Studio v2.4 Starting with NetLinx Studio 2.4, NetLinx now supports 16-bit Unicode characters. You can type Unicode character literals strings into you program, assigned them to variables, manipulate them using string operations, read and write Unicode characters to the file system and send Unicode strings to user interfaces for display.
NetLinx UniCode Functions 2. Select the NetLinx Compiler tab (FIG. 2). FIG. 2 NetLinx Compiler tab of the Preferences dialog 3. Under Options, check the Enable _WC Preprocessor checkbox. 4. Close the Preferences dialog. Including the Unicode Library The Unicode Library is implemented in a NetLinx Include file, UnicodeLib.axi, that must be included in your program in order to access the Unicode functions.
NetLinx UniCode Functions All Unicode string literals must be wrapped in the _WC macro. Failing to wrap a Unicode string in the _WC macro will result in a compiler error. Storing a Unicode String Unicode strings are stored in WIDECHAR arrays, similar to the way ASCII strings are stored in CHAR arrays.
NetLinx UniCode Functions Character Case Mappings Converting between upper and lower case is accomplished by using the Unicode.org character database to determine the mapping between upper case and lower case characters. Not all Unicode characters have an upper or lower case equivalent; these characters will not be affected by WC_UPPER_STRING and WC_LOWER_STRING. Only the characters defined by Unicode.org as having an upper or lower case mapping are affected by these functions.
NetLinx UniCode Functions Reading and Writing to Files The NetLinx Unicode library supports reading and writing of WIDECHAR arrays. The WC_FILE routines operate the same as the FILE routines with the exception of FILE_OPEN. WC_FILE_OPEN takes an additional parameter; the file format.
NetLinx UniCode Functions Right-to-left languages are not stored differently than left-to-right languages, they are simply rendered differently than right to left languages. However, note that the functions WC_LEFT_STRING and WC_RIGHT_STRING remove a number of characters from the start and end of a string respectively. Using WC_LEFT_STRING on a right-to-left language will return the number of right-most, i.e. first, characters you requested, not the left-most, i.e. end, characters.
NetLinx UniCode Functions 188 NetLinx Programming Language Reference Guide
IP Communication IP Communication Clients and servers communicate via Internet Protocol (IP) using either a connection-oriented or connection-less protocol. Connection-oriented input/output (I/O) channels require a connection or virtual circuit to be established between the client and server before data can be transmitted or received. Transmission Control Protocol (TCP) is the transport protocol typically used for connection-oriented I/O. With TCP, delivery of the data is guaranteed.
IP Communication LocalPort: A user-defined, non-zero integer value representing the virtual port on the client machine that will be used for this conversation. This port number must be passed to IP_CLIENT_CLOSE to close the conversation. ServerAddress: A string containing either the IP address (in dotted-quad-notation) or the domain name of the server to connect to. ServerPort: The port number on the server that identifies the program or service the client is requesting.
IP Communication When processing string data from a device, whether it is a regular device or an IP socket, the master will attempt to copy this data to a buffer, if one has been created using the CREATE_BUFFER keyword, and then try to run a DATA_EVENT…STRING handler for this device. If a DATA_EVENT…STRING handler does not exists, Netlinx will run mainline to allow for any buffer processing that might occur in mainline.
IP Communication Protocol: The transport protocol to use (1 = TCP, 2 = UDP). If this parameter is not specified, TCP (1) is assumed. The constants IP_TCP and IP_UDP can be used to specify this parameter. Multiple client connections With connection-oriented I/O (TCP), more than one client could request a connection with the server at the same time. Support for multiple client connections applies only to connection-oriented I/O, that is, TCP protocol.
IP Communication Receiving data To receive data from a client, use a DATA event handler or a buffer created with CREATE_BUFFER or CREATE_MULTI_BUFFER. If an event handler is used, the data is located in the Text field of the DATA object. The syntax: Data_Event[Device] { STRING: { // process incoming string (Data.Text) } } Parameters: Device is (or contains as part of an array) the device representing the conversation (0:LocalPort:0). Sending data To send data to the client, use the SEND_STRING command.
IP Communication When the message is received at 192.168.0.1, the message will be delivered to the DATA_EVENT for dvUDPServer and the IP address UDP/IP port of the sender of the message will be available in the DATA.SOURCEIP and DATA.SOURCEPORT variables. A UDP (2) socket would be used in this case to send a response to the client.
IP Communication DEFINE_START (* Get My IP Address *) GET_IP_ADDRESS(0:0:0,MyIPAddress) (* Open The Server *) IP_SERVER_OPEN(dvIPServer.Port,nIPPort,IP_TCP) (* Open The Client *) IP_CLIENT_OPEN(dvIPClient.Port,MyIPAddress.
IP Communication { SEND_STRING 0,"'offline: client'" } STRING: { SEND_STRING 0,"'string: client=',Data.
NetLinx Modules NetLinx Modules The ability to reuse code is a desirable goal in software development; however, code reuse takes careful planning and organization. As discussed earlier, NetLinx provides tools such as functions and modules to promote reusability. Modules are NetLinx sub-programs designed to be "plugged into" a main program. Defining a module The MODULE_NAME entry on the first line of the file defines the module.
NetLinx Modules PAUSE = 3 FFWD = 4 REW = 5 SFWD = 6 SREV = 7 REC = 8 PLAY_FB = 241 STOP_FB = 242 PAUSE_FB = 243 FFWD_FB = 244 REW_FB = 245 SFWD_FB = 246 SREV_FB = 247 REC_FB = 248 (* vcr will go into stop after rewinding for a certain time *) VCR1_REW_TO_STOP = 1800 (* 3 min *) (* vcr will go into stop after search rewinding for a certain time *) VCR1_SREV_TO_STOP = 12000 (* 20 min *) (* vcr will go into stop after being paused for a certain time *) VCR1_PAUSE_TO_STOP = 6000 (
NetLinx Modules OFF [dvDECK,nOFFSET_FN+PLAY] OFF [dvDECK,nOFFSET_FN+STOP] OFF [dvDECK,nOFFSET_FN+PAUSE] OFF [dvDECK,nOFFSET_FN+FFWD] OFF [dvDECK,nOFFSET_FN+REW] OFF [dvDECK,nOFFSET_FN+SFWD] OFF [dvDECK,nOFFSET_FN+SREV] OFF [dvDECK,nOFFSET_FN+REC] } DEFINE_CALL 'FEEDBACK' (INTEGER nFUNCTION) { [dvDECK,nOFFSET_FB+PLAY_FB] = (nFUNCTION=PLAY) [dvDECK,nOFFSET_FB+STOP_FB] = (nFUNCTION=STOP) [dvDECK,nOFFSET_FB+PAUSE_FB] = (nFUNCTION=PAUSE) [dvDECK,nOFFSET_FB+FFWD_FB] = (nFUNCTION=FFWD) [dvDECK,nOFFSET_FB+R
NetLinx Modules #IF_DEFINED SYSCALL_NOTIFY SEND_STRING 0,"'IN MODULE ',39,'ModuleExample',39" #END_IF (* RUN A FUNCTION *) nFUNC = GET_LAST(dcTRANPORTS) SWITCH (nFUNC) { CASE PLAY: { IF (![dvDECK,nOFFSET_FB+REC_FB]) { CANCEL_WAIT 'VCR1 REW TO STOP' CANCEL_WAIT 'VCR1 PAUSE TO STOP' CANCEL_WAIT 'VCR1 SREV TO STOP' CALL 'ALL OFF' MIN_TO [dvDECK,nOFFSET_FN+PLAY] CALL 'FEEDBACK' (PLAY) } } CASE STOP: { CANCEL_WAIT 'VCR1 REW TO STOP' CANCEL_WAIT 'VCR1 PAUSE TO STOP' CANCEL_WAIT 'VCR1 SREV TO STOP' CALL 'ALL OF
NetLinx Modules { CANCEL_WAIT 'VCR1 REW TO STOP' CANCEL_WAIT 'VCR1 PAUSE TO STOP' CANCEL_WAIT 'VCR1 SREV TO STOP' CALL 'ALL OFF' MIN_TO [dvDECK,nOFFSET_FN+PLAY] CALL 'FEEDBACK' (PLAY) } ACTIVE ([dvDECK,nOFFSET_FB+PLAY_FB]): { CANCEL_WAIT 'VCR1 REW TO STOP' CANCEL_WAIT 'VCR1 PAUSE TO STOP' CANCEL_WAIT 'VCR1 SREV TO STOP' WAIT VCR1_PAUSE_TO_STOP 'VCR1 PAUSE TO STOP' SYSTEM_CALL 'FUNCTION' (dvDECK,STOP,nFIRST) CALL 'ALL OFF' MIN_TO [dvDECK,nOFFSET_FN+PAUSE] CALL 'FEEDBACK' (PAUSE) } ACTIVE ([dvDECK,nOFFSET_FB
NetLinx Modules CANCEL_WAIT 'VCR1 SREV TO STOP' CALL 'ALL OFF' MIN_TO [dvDECK,nOFFSET_FN+FFWD] CALL 'FEEDBACK' (FFWD) } ACTIVE (dcTRANPORTS[6].
NetLinx Modules OR [dvDECK,nOFFSET_FB+SFWD_FB]))): { CANCEL_WAIT 'VCR1 REW TO STOP' CANCEL_WAIT 'VCR1 PAUSE TO STOP' CANCEL_WAIT 'VCR1 SREV TO STOP' WAIT VCR1_REW_TO_STOP 'VCR1 REW TO STOP' SYSTEM_CALL 'FUNCTION' (dvDECK,STOP,nFIRST) CALL 'ALL OFF' MIN_TO [dvDECK,nOFFSET_FN+REW] CALL 'FEEDBACK' (REW) } ACTIVE (dcTRANPORTS[7].
NetLinx Modules CASE REC: { IF ([dvDECK,nOFFSET_FB+STOP_FB] OR [dvDECK,nOFFSET_FB+REC_FB]) { CANCEL_WAIT 'VCR1 REW TO STOP' CANCEL_WAIT 'VCR1 PAUSE TO STOP' CANCEL_WAIT 'VCR1 SREV TO STOP' CALL 'ALL OFF' MIN_TO [dvDECK,nOFFSET_FN+REC] CALL 'FEEDBACK' (REC) } } } } } (***********************************************************) (* THE ACTUAL PROGRAM GOES BELOW *) (***********************************************************) DEFINE_PROGRAM [dcTRANPORTS[1]] = [dvDECK,nOFFSET_FB+PLAY_FB] [dcTRANPORTS[2]
NetLinx Modules Technically, modules can contain declarations to other modules, provided that no circular references are involved. However, because different instances of the same module must not be separated by instances of a different module, it is highly recommended that you do not declare modules from within other modules - if you have multiple declarations of the parent module they will then be separated by the declarations of the child module. FIG.
NetLinx Modules (***********************************************************) (* MODULE CODE GOES BELOW *) (***********************************************************) DEFINE_MODULE 'ModuleExample' mdlVCR(dvVCR,dcTRANPORTS,nVCR_FIRST) (***********************************************************) (* (* END OF PROGRAM *) DO NOT PUT ANY CODE BELOW THIS COMMENT *) (***********************************************************) 206 NetLinx Programming Language Reference Guide
Internet Inside Internet Inside The Internet Inside™ feature of the NetLinx master allows a web browser to retrieve web pages directly from the master. The web pages provide a user interface that mimics the look and feel of an AMX touch panel. In fact, TPDesign generates the web pages. The components of Internet Inside are as follows: Java TPClasses – The Java client code that runs on the browser essentially emulating a touch panel. WDM – Web Device Manager.
Internet Inside The first parameter is the starting device number, the second parameter is the ending device number inclusive, and the last parameter is the number of NetLinx devices the web user interface uses per instance. The purpose of this format is to allow multiple instances of the same web user interface on multiple browsers. For example, assume a conference room where the user desires the ability to connect two simultaneous web user interfaces.
Encoding and Decoding: Binary and XML Encoding and Decoding: Binary and XML There are six special functions used to encode and decode variables in NetLinx. This encoding process takes a NetLinx variable, no matter how complex, and converts it into a string. The decode process will take this string and copy the contents back into a variable. These functions can be used to take the contents of NetLinx variables and convert them to string.
Encoding and Decoding: Binary and XML (***********************************************************) (***********************************************************) (* System Type : NetLinx *) (***********************************************************) (* REV HISTORY: *) (***********************************************************) (***********************************************************) (* DEVICE NUMBER DEFINITIONS GO BELOW *) (***********************************************************) DEFIN
Encoding and Decoding: Binary and XML DEFINE_VARIABLE VOLATILE _AlbumStruct AlbumStruct[3] VOLATILE _AlbumStruct2 AlbumStruct2[3] VOLATILE CHAR sBinaryString[10000] VOLATILE CHAR sXMLString[50000] VOLATILE LONG lPos VOLATILE SLONG slFile VOLATILE SLONG slReturn (***********************************************************) (* STARTUP CODE GOES BELOW *) (***********************************************************) DEFINE_START (* assign some values *) AlbumStruct[1].
Encoding and Decoding: Binary and XML DEFINE_EVENT (* CONVERT AND SAVE *) BUTTON_EVENT[dvTP,1] { PUSH: { (* CONVERT TO BINARY *) lPos = 1 slReturn = VARIABLE_TO_STRING (AlbumStruct,sBinaryString,lPos) SEND_STRING 0,"'POSITION=',ITOA(lPos),'; RETURN=',ITOA(slReturn)" (* CONVERT TO XML *) lPos = 1 slReturn = VARIABLE_TO_XML (AlbumStruct,sXMLString,lPos,0) SEND_STRING 0,"'POSITION=',ITOA(lPos),'; RETURN=',ITOA(slReturn)" (* NOW WE CAN SAVE THESE BOTH TO DISCS *) slFile = FILE_OPEN('BinaryEncode.
Encoding and Decoding: Binary and XML { PUSH: { (* NOW WE CAN SAVE THESE BOTH TO DISCS *) slFile = FILE_OPEN('BinaryEncode.xml',nFileRead) IF (slFile > 0) { slReturn = FILE_READ(slFile,sBinaryString,MAX_LENGTH_STRING(sBinaryString)) IF (slReturn < 0) SEND_STRING 0,"'FILE WRITE FAIL RETURN=',ITOA(slReturn)" slReturn = FILE_CLOSE(slFile) IF (slReturn < 0) SEND_STRING 0,"'FILE CLOSE FAIL RETURN=',ITOA(slReturn)" } slFile = FILE_OPEN('XMLEncode.
Encoding and Decoding: Binary and XML slReturn = FILE_READ(slFile,sBinaryString,MAX_LENGTH_STRING(sBinaryString)) IF (slReturn < 0) SEND_STRING 0,"'FILE WRITE FAIL RETURN=',ITOA(slReturn)" slReturn = FILE_CLOSE(slFile) IF (slReturn < 0) SEND_STRING 0,"'FILE CLOSE FAIL RETURN=',ITOA(slReturn)" } slFile = FILE_OPEN('XMLEncode.
Appendix A: Marshalling Protocol Appendix A: Marshalling Protocol Marshalling Protocol (Group of Bytes) The protocol assumes that every logical field (group of bytes) is prefixed with type/size information. For example, if there is a 4 byte long integer field within a structure, the byte stream representing that field consists of 5 bytes. The first byte (0xE3) specifies that a long integer follows and then the 4 remaining bytes contain the value of the long integer.
Appendix A: Marshalling Protocol Byte Formats Supported in the Marshaller (Cont.) WORDSTR Sequence of WORD's whose element count is <= 64K. 0xE6 Length Hi Length Lo . . DWORDSTR Sequence of DWORD's whose element count is <= 64K. 0xE7 Length Hi Length Lo . . QWORDSTR Sequence of QWORD's whose element count is <= 64K. 0xE8 Length Hi Length Lo . . LBYTESTR Large sequence of BYTE's whose element count can be > 64K (larger version of BYTESTR).
Appendix A: Marshalling Protocol Marshalling Protocol (Variables) The protocol assumes that every logical field (variable) is identified with a name or index, type/size information and the actual data. For example, if there is a 4 byte long integer field within a structure, the XML stream representing that field would consist of 3 tags: A name tag specifying the name of the variable, a type tag specifying a 4 byte unsigned value, and the data.
Appendix A: Marshalling Protocol Types Supported in the XML Marshaller (Cont.) DOUBLE 8-byte IEEE 754 float value. If var is an element of an array, name is replaced with . The index value, and the type are optional. Typically, only Data is needed. MyName float.IEEE.754.64 4.56 STRUCT ARRAY A structure containing one or more fields.
Appendix A: Marshalling Protocol Types Supported in the XML Marshaller (Cont.) ARRAY Binary Encoded Array of any one of the types in this table except struc- tures. This is the default for all non-CHAR arrays but CHAR arrays can use this encoding as well. The type Type of the parent is the type of the entire array. Type is 100 optional and generally not included. Current Length is optional.
Appendix A: Marshalling Protocol 2 010203040B0C0D0E This is the default type of encoding for non-CHAR arrays but can be used to encode/decode char arrays as well. The data section must contain BytesSize*Elements nibbles.
Appendix A: Marshalling Protocol Binary Encoding Result Binary Encoding Result Byte In Encoded String Description $EC Start of Array Encoding $00 $00 $00 $03 Number of Elements in the Array $EA Start of Structure $E3 DWORD: LONG or SLONG $00 $A9 $63 $48 Data: 11101000 $E5 Start of CHAR Array (String) $00 $0D Length of Array: 13 $42 $75 $66 $66 $65 $74 $2C $20 $4A $69 $6D $6D $79 Data: 'Buffet, Jimmy' $E5 Start of CHAR Array (String) $00 $1A Length of Array: 26 $4C $69 $76 $69 $6E $67
Appendix A: Marshalling Protocol Binary Encoding Result (Cont.
Appendix A: Marshalling Protocol XML Encoding Result 0 1 LTITLEID 11101000 SARTIST 13 Buffet, Jimmy STITLE 26 Living & Dying in 3/4 Time SCOPYRIGHT 3 MCA SLABEL 3
Appendix A: Marshalling Protocol NDISCNUMBER 91 2 LTITLEID 17248229 .... NDISCNUMBER 105 3 LTITLEID 12328612 ...
Appendix B: Glossary Appendix B: Glossary Array: A single variable that has more than one storage location. Buffer: An array variable that is associated with a particular device for the purpose of storing information sent by the device. Button Event: Include pushes, releases, and holds associated with a push or release on a particular device-channel.
Appendix B: Glossary Identifier: A combination of letters, numbers, or underscores that represents a device, constant, or variable. Index value: Number that tells NetLinx which location in an array to retrieve. This value must be nonzero and not greater than the maximum length of the declared array. Input change: A signal sent by the input function of a channel that alerts NetLinx to scan mainline for a reference to that signal. Integer: In NetLinx, the range of whole numbers from Ø to 65,535, inclusive.
Appendix B: Glossary Wildcard character: In NetLinx, the question mark (?) can only be used in a COMPARE_STRING operation (unlike Axcess, which uses the question mark to compare dates and times).
Appendix B: Glossary 228 NetLinx Programming Language Reference Guide
Appendix B: Glossary NetLinx Programming Language Reference Guide 229
It’s Your World - Take Control™ 3000 RESEARCH DRIVE, RICHARDSON, TX 75082 USA • 800.222.0193 • 469.624.8000 • 469-624-7153 fax • 800.932.6993 technical support • www.amx.com 033-004-2255 10/06 ©2006 AMX. All rights reserved. AMX and the AMX logo are registered trademarks of AMX. AMX reserves the right to alter specifications without notice at any time.
