Академический Документы
Профессиональный Документы
Культура Документы
NetLinx Studio
v2.4 or higher
So ftw are
INTELLECTUAL PROPERTY.
The AMX Software is owned by AMX and is protected by United States copyright laws, patent laws, international treaty provisions, and/or state of Texas trade secret laws. Licensee may make copies of the AMX Software solely for backup or archival purposes. Licensee may not copy the written materials accompanying the AMX Software.
TERMINATION. AMX RESERVES THE RIGHT, IN ITS SOLE DISCRETION, TO TERMINATE THIS LICENSE FOR ANY REASON AND UPON WRITTEN NOTICE TO LICENSEE.
In the event that AMX terminates this License, then Licensee shall return all copies of the AMX Software to AMX and certify in writing that all copies have been destroyed.
PRE-RELEASE CODE.
Portions of the AMX Software may, from time to time, as identified in the AMX Software, include PRE-RELEASE CODE and such code may not be at the level of performance, compatibility and functionality of the final code. The PRE-RELEASE CODE may not operate correctly and may be substantially modified prior to final release or certain features may not be generally released. AMX is not obligated to make or support any PRE-RELEASE CODE. ALL PRE-RELEASE CODE IS PROVIDED "AS IS" WITH NO WARRANTIES.
LIMITED WARRANTY.
AMX warrants that the AMX Software will perform substantially in accordance with the accompanying written materials for a period of ninety (90) days from the date of receipt. AMX DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH REGARD TO THE AMX SOFTWARE. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. Any supplements or updates to the AMX SOFTWARE, including without limitation, any (if any) service packs or hot fixes provided to you after the expiration of the ninety (90) day Limited Warranty period are not covered by any warranty or condition, express, implied or statutory.
LICENSEE REMEDIES.
AMX's entire liability and your exclusive remedy shall be repair or replacement of the AMX Software that does not meet AMX's Limited Warranty and which is returned to AMX. This Limited Warranty is void if failure of the AMX Software has resulted from accident, abuse, or misapplication. Any replacement AMX Software will be warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer. Outside the United States, these remedies may not available. NO LIABILITY FOR CONSEQUENTIAL DAMAGES. IN NO EVENT SHALL AMX BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS AMX SOFTWARE, EVEN IF AMX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/ COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. U.S. GOVERNMENT RESTRICTED RIGHTS. The AMX Software is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at 48 CFR 52.227-19, as applicable.
This Agreement replaces and supercedes all previous AMX Software License Agreements and is governed by the laws of the State of Texas, and all disputes will be resolved in the courts in Collin County, Texas, USA. Should you have any questions concerning this Agreement, or if you desire to contact AMX for any reason, please write: AMX Corporation, 3000 Research Drive, Richardson, TX 75082.
Table of Contents
Table of Contents
NetLinx Studio (v2.4 or higher) ...............................................................................1
Overview ........................................................................................................................... 1 Supported Operating Systems and Minimum PC Requirements ...................................... 2
Supported operating systems: ................................................................................................. 2 PC Requirements:.................................................................................................................... 2 Other PC requirements: ........................................................................................................... 2
Supported File Types ........................................................................................................ 2 What's New Dialog ............................................................................................................ 3 WebUpdate ....................................................................................................................... 3 Software History2 Application ........................................................................................... 3 DIP Switch 2.0................................................................................................................... 3
Terminal Window............................................................................................................. 17
Table of Contents
Using The Terminal Window .................................................................................................. 17 Terminal Window Context Menu ............................................................................................ 18
ii
Table of Contents
Identifiers vs. Disk Filenames.......................................................................................... 47 Viewing And Editing System File Properties ................................................................... 47 Device Mapping............................................................................................................... 48
Device Mapping Dialog .......................................................................................................... 48 DEVICE:PORT:SYSTEM (D:P:S) .......................................................................................... 49 To Remove Device Mapping Information from a File............................................................. 50 System File Device Map Context Menu ................................................................................. 50
iii
Table of Contents
Include File Folder Context Menu .......................................................................................... 58 Include File Context Menu ..................................................................................................... 59
iv
Table of Contents
Programming ..........................................................................................................77
Overview ......................................................................................................................... 77
Source Code Editor Context Menu ........................................................................................ 77
Table of Contents
Debugging Source Code Files ............................................................................................... 94 To enter debug mode:............................................................................................................ 95 Using Single-step Mode ......................................................................................................... 95 Master Controller Debug Options........................................................................................... 96 Changing The Value Of A Watched Variable......................................................................... 96 Debug Mode Error Messages ................................................................................................ 96
Breakpoints ..................................................................................................................... 97
Using Breakpoints (NetLinx Only) .......................................................................................... 97 Setting A Breakpoint .............................................................................................................. 97 Clearing Breakpoints.............................................................................................................. 98 Editing Breakpoints ................................................................................................................ 98
PUSH Messages............................................................................................................. 98
Insert Push Message Dialog .................................................................................................. 98 Find Push Message Dialog .................................................................................................... 99
Using the Terminal Window .......................................................................................... 104 ASCII / HEX / DECIMAL CONVERSIONS TABLE ....................................................... 105
vi
Table of Contents
Compiling an Individual File .......................................................................................... 109 Compiler Errors and Warnings ...................................................................................... 110 Compiler Errors ............................................................................................................. 110 Compiler Warnings........................................................................................................ 113
Compiler Error Warnings Report Dialog............................................................................... 114 Disabling Compiler Warnings In Netlinx Code ..................................................................... 114
NetLinx Diagnostics - NetLinx Device Emulation .......................................................... 127 NetLinx Diagnostics - NetLinx Device Control............................................................... 129
Viewing Push Results .......................................................................................................... 130
vii
Table of Contents
Setting NetLinx Time and Date ..................................................................................... 136 Rebooting the Master.................................................................................................... 137 Axcess/NetLinx Debugging ........................................................................................... 137
Debugging Source Code Files ............................................................................................. 137 Notes on Using Current Length (when the Total Length option is disabled):....................... 138 Master Controller Debug Options......................................................................................... 138 Changing The Value Of a Watched Variable ....................................................................... 139
viii
Table of Contents
Configuring TCP/IP Communication Settings (Netlinx Only) ............................................... 156 Configuring Serial Communication Settings......................................................................... 157 Configuring Modem Communication Settings...................................................................... 157 Configuring Virtual Netlinx Master Communication Settings (Netlinx Only)......................... 158 Configuring the Panel For Virtual Netlinx Master TCP/IP Transfers .................................... 158
ix
Table of Contents
Preferences Dialog - Toolbars Tab ............................................................................... 178 Preferences Dialog - Tools Tab .................................................................................... 178
Adding/Removing Application Shortcuts In The Tools Menu ............................................... 179
Preferences Dialog - Diagnostics Tab........................................................................... 182 Preferences Dialog - Terminal Tab ............................................................................... 183 Preferences Dialog - File Transfer Tab ......................................................................... 183 Preferences Dialog - Workspace Tab ........................................................................... 184
NetLinx Master Error - Device_ID Error ........................................................................ 186 Debug Option Disabled For Axcess Code File.............................................................. 186
Symptom .............................................................................................................................. 186 Cause................................................................................................................................... 186 Resolution ............................................................................................................................ 186
You must have Administrator rights to install and run all required System files.
PC Requirements: Pentium 233 MHZ processor (minimum requirement); 300 MHZ or faster recommended. 75 MB of free disk space (minimum requirement); 150 MB recommended. 128 MB of installed memory (RAM). Minimum (VGA) screen resolution of 800x600. Other PC requirements: Windows-compatible CD-ROM drive. Windows-compatible mouse (or other pointing device).
If the mouse wheel on your Microsoft IntelliMouse doesn't' work with NetLinx Studio, try downloading the latest IntelliMouse drivers from Microsoft.
The following file types are supported, but are edited using external AMX applications, as described below:
Type TPD file Associated AMX Application Extension TPDesign3 *.TPD *.TP4 *.KPD *.IRL, *.IRV
NetLinx Studio will attempt to open all other file types (*.*) using the application already associated with that file type in Windows.
WebUpdate
The AMX WebUpdate program is a stand-alone application that communicates with the AMX website, allows a user to select from a list of available AMX Software programs to choose for updating, determines the latest version of the selected applications, returns a listing of available updates, allows a user to download the selected installation files, and upon request, launches the installation of those downloads.
The WebUpdate application is not installed by NetLinx Studio, and must be installed separately. If not found, NetLinx Studio will prompt you to download the application from www.amx.com.
Select Help > Web Update to launch this application. Refer to the WebUpdate on-line help for details and instructions.
Title Bar
Displays the name of the application, and the name of the currently active file. An asterisk (*) after the file name indicates that it contains unsaved changes.
Toolbars
There are eight toolbars in NetLinx Studio. Hover the mouse cursor over any toolbar button (for about one second) to display a" tooltip" describing the button. Choose View > Toolbars to open the Toolbars sub-menu to view or hide the toolbars:
Build toolbar Debug Watch toolbar Diagnostics toolbar Edit toolbar Project toolbar Standard toolbar Terminal toolbar Window Mgmt toolbar FIG. 2 Toolbars
See Also... The Adding/Removing Commands From The Toolbars section on page 177. The Creating Custom Toolbars section on page 178.
Menu Bar
The Menu Bar is located along the top of the application window, between the title bar and the toolbars. Click on any of the main menu items to open the associated drop-down menu.
If you are running NetLinx Studio in Windows 2000, NT or XP, you may have to press the ALT key to view the menu item hotkeys.
Status Bar
Click View > Status Bar (or click the toolbar button) to toggle (hide/show) the Status Bar. The Status Bar displays general information, including communication status, a brief description of any option in the program, cursor location, last Push received, COM port currently being used, network IP address (NetLinx systems only) and current PC keyboard settings.
The elements of the Status Bar are described below, from left to right:
Program Status/Quick descriptions of program options - The far-left side of the status bar displays quick descriptions of program options anytime you position the mouse cursor over a toolbar button or menu item. This field also displays the total number of replaced instances resulting from a search & replace operation. Notifications Messages Status - Displays the status of NetLinx notification messages (OFF/ON). Diagnostics Messages Status - Displays the status of asynchronous notification messages (OFF/ON). Last Push Message and History - Displays the most recently received Push (if Push is enabled via the Diagnostics > Enable Push Message Status Bar Display command), or Push status (Push Enabled/Disabled). Left-mouse click on the push message displayed to view a history of push messages. Then, right-mouse click within the list box to view the available options. Master Controller Connection Information - Displays the name and status of the active communications port. If a TCP/IP connection exists, the current IP address is displayed. If Virtual NetLinx Master is selected, then the Virtual NetLinx Master is displayed with its System number. Master Security Status - Indicates the current security status for the Master (locked = Authentication Enabled, unlocked = Authentication disabled). Cursor Location - Displays the cursor's location in the active Source Code Editor window (line and column numbers). Keyboard Settings - When a file is open (in a Source Code Editor window), the three boxes on the far-right side of the status bar indicate the status of the following keyboard settings: OVR: Overwrite/Insert (OVR indicates that the keyboard is currently in overwrite mode - new characters will replace or overwrite existing characters in the Source Code Editor). CAP: Caps Lock (CAPS indicates that the keyboard is currently in Caps Lock mode - all letters typed will appear in upper case. NUM: Number Lock (NUM indicates that the 10-key number/arrow keypad is set to type numbers - arrow functions are disabled).
Workspace Window
Use the Workspace Window (FIG. 4) to manage Project files, System files and online devices. The Workspace Window contains two tabs (Workspace and Online Tree), which display all open Workspace files (containing Projects and their associated System files), and all devices currently on-line, in a tree structure.
Click View > Workspace (or click the toolbar button) to toggle (show/hide) the Workspace window. Right-click inside the menu bar or menu area to display the View Control Context Menu, where you can select to hide or display the NetLinx Studio toolbars. Workspace Window - Workspace Tab The Workspace tab contains a tree structure of all the available Projects (and Systems) contained within a Workspace file. You may create multiple Projects within a Workspace. Within a Project, you can create multiple Systems. The Workspace view can be expanded to show all of the various elements within each opened Project file, as shown below. The first level within the open Workspace is the Project folder level. The next level is the System(s) contained within the Project, each represented by a System folder. The third level contains the System File folders (Source, Include, Module, User Interface, IR and Other).
The 'Module' folder only appears if NetLinx is designated as the system platform (via the Communication Settings dialog).
The fourth level contains all of the actual files that make up the System (.AXS, .AXI, .TPD, .TKO, .TP4 .IRL/.IRV, and *.*). The fifth and final level indicates the file mapping information for each file, as applicable.
Click on the "+" folder flags to expand the folders to expose any subfolders; click the "-" folder flags to collapse the folders. The hierarchical file structure of the Workspace tab is described below: Workspace Folder You can have one Workspace open at a time. A Workspace contains at least one Project, and each Project contains at least one System. Right-mouse click anywhere within the workspace tab to open the Workspace context menu. Project Folders Right-mouse click on any Project folder to open the Project Folder context menu. Expand any Project folder to display the System folder(s) contained in that Project. System Folders Each System has it's own platform (Axcess or NetLinx) setting along with the communication information (i.e. IP address or COM port setting with the appropriate baud rate, etc.). Right-mouse click on any System folder to open the System Folder context menu.
Expand any System folder to display the six System File folders contained in that System (Source, Include, Module, User Interface, IR and Other). System File Folders Expand any System File folder to display the System File(s) contained in that folder. Right-click on any System File folder to open the System File Folder context menu associated with that folder type. System Files Right-mouse click on any System File to open the System File context menu associated with that file type. Double-click any code file (Master Source Code, Source Code, Module or Include) to open that file for viewing and/or editing in a Source Code Editor window. Double-click any TPD file to open the TPDesign3 program (if it is installed). Double-click any TP4 file to open the TPDesign4 program (if it is installed). Double-click any KPD file to open the KPDesign program (if it is installed). Double-click any IR file to open the IREdit program (if it is installed). When you add a file to a System (Project > Add File To System), the file is automatically placed (as a link) in the appropriate System File folder, based on it's file type. You cannot have the same file referenced more than once within a system (i.e. cannot add the same file name to the Source folder and the Other folder within the same System). File Mapping Information Any file that has device-file mapping information associated with it is represented in the Workspace tab with a "+" flag. Click on the "+" symbol to expand the view to indicate the File Mapping Information. Other key functions and features of the Workspace tab include: You can drag and drop files from Explorer into the appropriate sub-folders within a System. All files are linked files associated with a system, not copies of files from one location to another. For the TPD/4, IR files and other source code files, you have the ability to map multiple devices to the selected file. The Master Source Code file will always be mapped automatically to device address 0:1:0 for NetLinx masters or 0 for Axcess masters. You have the ability to copy a selected System folder to paste into another or the same Project folder. You have the ability to designate a single source code file as the Master Source Code file.
10
Right-click on any open area inside the Workspace tab to open the Workspace Window Context Menu. Workspace File Context Menu Right-click on the Workspace file (in the Workspace tab of the Workspace Window) to open the Workspace File context menu. This context menu contains various Workspace file-level commands and options, including:
New Workspace Closes the currently open Workspace file, and starts a new (empty) workspace (no Project/System associated until you add them manually). Launches the Workspace Wizard, which steps you through the process of creating a new Workspace with a Project/System. Opens the Open Workspace dialog, where you can locate and select an existing Workspace (.APW) file. You can have only one Workspace open at any time, so in the event that you have a Workspace open, it will be replaced by the one you open. Closes the Workspace file. The program prompts you to close the files associated with the Workspace before closing them. Saves the Workspace file, under its current name and location. Opens the Save Workspace As dialog, where you can specify a new name and/or location for the saved Workspace file. Builds (compiles) the Workspace (including all contained Projects). The progress and results of the build can be viewed in the Status tab of the Output Display window. Opens the Export Workspace File To Go dialog, where you can export the Workspace for distribution as an AXW file. AXW files preserve all relative file path information for the Projects, Systems and System files contained in the Workspace making them ideal for distribution to remote sites. Opens the Select AXW File dialog, where you can select a previously exported "To Go" (AXW) file to import into the program. Opens the New Project Properties dialog, which allows you to assign an Identifier and general properties for a new Project. Once created, the new project is added to the Workspace. Opens the Open Workspace dialog, where you can locate and select a Workspace (.APW) file. This invokes the Import Components From a Workspace dialog. Use the dialog to select a specific Project contained in the Workspace. You can copy and paste Projects by selecting Copy Project from the Project Folder context menu, and selecting the Paste Project command. Collapses the Project/System/File tree to show only the Workspace and its Project(s).
Import a Project
Paste Project
Collapse Tree
Expand To System Level Expands the Project/System/File tree to show the Workspace, Project(s) and System(s). Docking view Hide Quick Load Workspace Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window. This option allows you to access the File Transfer dialog, already configured to send all files in the Workspace (active Project/System only) to the Master associated with the active System. Opens the Workspace Properties dialog, where you can view the basic properties of the open Workspace. The options in this dialog also allow you to edit the Workspace Identifier and Description.
Workspace Properties
11
Workspace Window - Online Tree Tab The Online Tree tab of the Workspace Window (FIG. 6) displays an Online Device tree for either the NetLinx or Axcess Master Controller. This tab displays a list of devices detected to be currently online by the Master Controller (and the firmware version for each). The Device Tree also provides port status information for each device.
Refer to the Working With the Online Device Tree section on page 116 for more information.
FIG. 7 Output Display Window (by default opens to the Status tab)
12
Right-click inside any of the Output Display window tabs to access the Output Display window context menu. Output Display Window Context Menu Right-click inside any of the Output Display window tabs (Status, Find In Files, Find IR Files, File Transfer Status, Notifications or Diagnostics) to open the Output Display window context menu.
As indicated, some of the options below are not relevant to all tabs.
13
Saves all items to a user-defined file. You will be prompted for a file name to save the contents of the tab. Saves only the selected items to a user-defined file. You will be prompted for a file name to save the contents of the tab.
Compiler Error /Warning Report This option scans the contents of the Status tab, and then lists each compiler error and warning (one per line) in the Status tab. This option invokes the Compiler Error Warnings Report dialog, which allows you to specify wether you want to include compiler Errors, Warnings or both in the report. By default, Errors and Warnings are both selected. Find (Notifications and Diagnostics tabs only) Search for text within the tab, via the Find dialog. You may search up or down the tab based on the current cursor location within the tab. The search can be case sensitive. When the text is found in the tab, the program highlights the row and scrolls the row into view. Clears all the items within the list.
Clear
File Transfer Tab Context Menu Right-click on any item listed in the File Transfer Status tab of the Output Display window to access the File Transfer Tab Context Menu:
Copy All Items Copy Selected Items Save All Items Save Selected Items Clear Copies all items in the list to the clipboard. Copies only the selected items in the list to the clipboard. Saves all items to a user-defined file. You will be prompted for a file name to save the contents of the tab. Saves only the selected items to a user-defined file. You will be prompted for a file name to save the contents of the tab. Clears all the items within the list. WARNING: Canceling during a file transfer may leave the target device in an unstable state. Cancel Selected Transfer Items Cancel Remaining Transfer Items Cancel All Transfer Items Cancels only transfer items that have been selected (highlighted). Cancels all remaining transfers in the list, but allows the current transfer to complete. Cancels all transfer items in the list, including the current one (if applicable).
Output Display Window - Notifications Tab The Notification tab of the Output Display Window displays the asynchronous notification messages being received from the master controller. You can right-mouse click in the tab to see the available options to save or copy the contents of this list. Output Display Window - Diagnostics Tab The Diagnostics tab of the Output Display Window displays all internal system diagnostic messages that are generated by a NetLinx master controller. You can right-mouse click in the tab to see the available options to save or copy the contents of this list.
14
Use the Source Code Editor windows to generate and edit Axcess and/or NetLinx code files.
NetLinx Studio features a Code Wizard that steps you through the process of generating several different types of code.
Do not attempt to open .LIB or .SYC files for editing in the Source Code Editor. Doing so could cause program failure.
Source Code Editor Window - Features Source Code Editor window features include:
Unicode Characters Select Unicode Edit from the Edit menu, or the Source Code Editor Context Menu (right-click inside the editor window to access) to open the Enter Text... dialog which allows you to insert unicode characters in your code, at the cursor position in the editor.
15
Code folding
Fold levels can be used to simplify the view in the Source Code Editor windows by allowing you to "fold" each major section of the code (DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) so that only the header row is visible. This way, you only see the section(s) that you are actually working in. In order to use fold levels, you must first enable the option in the Editor tab of the Preferences dialog (by default, this option is disabled). As you type in a variable name, device name or a language reserved word, the program will suggest a name that has been previous defined within the source code (this option is toggled on and off in the Preference dialog - Editor Options tab). Press the Tab key to incorporate an Auto-Suggest. The text in the Editor windows is syntax highlighted for increased readability with a default set of colors. Use the options in the Editor Options tab of the Preferences dialog to customize various aspects of the Source Code editor windows (i.e. syntax highlighting, auto-indent, show/hide line numbers and clipboard text buffer settings). Note: Syntax highlighting assigns different colors to different types of data in your Source Code file. Use syntax highlighting to make your code easier to read and manage. For example, you could syntax highlight all comments to yellow, all identifiers to red and strings to blue to make them more easily identifiable in your code file.
Syntax Highlighting
Drag and drop any supported file type from Explorer into the Source Code Editor to open that file in a new Source Code Editor window. Drag and drop selected text to another Editor window (at the cursor location), or to another location within the same Editor window.
Floating Window
Source Code Editor windows are moveable and resizeable. Use the options in the Window menu to arrange (cascade or tile) multiple windows. Use the New Window option in the Window menu to open the same code file in multiple Editor windows. This feature allows you to view and edit different locations in a large code file. Right-click anywhere within a Source Code Editor window to open the Source Code Editor context menu. Hold down the Alt key and select text with the left mouse button for columnar Cut, Copy, and Paste operations. Use the Edit > Insert Section option to insert a (empty) section of code at the cursor position. Use the Edit > Goto Section option to move the cursor to the beginning of a selected section of code in the active Editor window. The Edit > Undo and Redo commands allow unlimited Undo/ Redo operations. Use the Edit > Make Selection Uppercase and Make Selection Lowercase commands to automatically change the case on a selection of text.
Source Code Editor context menu Columnar Cut, Copy and Paste Insert Section Goto Section
Undo and Redo Make Selection Uppercase and Make Selection Lowercase
Sequentially Renumber Selection Use the Edit > Sequentially Renumber Selection command to sequentially renumber selected number text in the active Editor window. Block Comment-Uncomment The Edit > Block Comment-Uncomment option allows you to block comment-uncomment selected text in the active Editor window.
16
To indent a block of text, select text and press the Tab key. Use Shift + Tab to remove the indentation. Multiple clip-board buffer capabilities. Ability to print an entire file. Mouse wheel support.
Terminal Window
NetLinx Studio provides a terminal interface to NetLinx and Axcess devices that support an interactive terminal mode. Select Tools > Terminal (or click the toolbar button) to invoke the Terminal Window. Key features of the Terminal window (accessible through the Terminal window context menu) are described below: Paste operations - Text data contained in the clipboard can be pasted into the terminal window. However, text can only be pasted when the Terminal window is connected (online), and only the first line of text in the clipboard will be pasted.
All characters pasted in the Terminal window are not pasted into the window directly, regardless of the current position of the caret. Rather, they are sent out the port to the device just as if they had been typed directly from the keyboard. This means that you will not necessarily see the text that was pasted unless echoing is currently enabled on the device. Also, carriage-return characters are not appended to the pasted text (even if the clipboard text contains one). You must press the return key to enter a pasted command.
Terminal communication settings - The Terminal window has it's own dedicated communications settings. Refer to the Master Communication Settings help topic for information on configuration of the Terminal communication settings. The Terminal window does not support: Cut operations. Editing operations within the window, other than to input characters at the cursor (the text in the terminal window actually reflects what has been received from the device. Text that is typed in the window will not appear unless echoing is currently enabled on the device). Using The Terminal Window Select Tools > Terminal (or click the toolbar button) to open the Terminal window. The Terminal window puts the Master Controller into dumb terminal mode. Anything that is typed on the screen exits through the Master communications port, and anything coming in from the communications port is displayed in the Terminal window. Use the Terminal window to communicate directly with the Master Controller and to debug RS-232-controlled devices. You cannot use the Terminal window while a communication port is in use for a file transfer or debug operation. Type "ECHO ON" in the Terminal window to display messages. If the Terminal window becomes unresponsive, close and re-open the window. To leave the Terminal Emulator window active for a long session, click the Terminal Locks the Port option in the General tab of the Preferences dialog.
17
Use the Terminal Options tab of the Preferences dialog to modify the behavior and change the appearance of the Terminal window. To use the Terminal window with NetLinx systems, you must be connected to the Master via the PROGRAM port. Otherwise, you can use Windows TelNet for terminal control of NetLinx systems. Terminal Window Context Menu Several of the key functions of the Terminal Window are accessible via the Terminal Window context menu. To open this context menu, right-click inside the Terminal Window. The options include:
Display Clear Save To File Disconnect Click to open the Display sub-menu, which contains view options for the Terminal Window. The options are ASCII, HEX (hexadecimal) and DEC (decimal). Clears the contents of the Terminal Window. Opens the Save As dialog, which allows you to save the contents of the Terminal Window as a text file (.txt). Disconnects the Terminal. The terminal window background turns a light shade of gray, to indicate that it is disconnected.
Last commands At the bottom of this menu is a list of the last commands entered. Use the items in this list as shortcuts to recently used commands.
Watch Window
The Watch window is displayed when Start Debugging is selected from the Debug menu (or the Debug Watch toolbar). The Watch window is a dockable window that allows you to view and edit the contents of specified variables within a compiled Axcess or NetLinx program. Also, you can control the execution of the mainline of a compiled Axcess or NetLinx program. The Watch window contains three tabs (Watch1-Watch3), which allow you to watch up to three separate sets/ lists of specified variables. The Watch window consists of a table with four columns:
Name Enter the name of the watched variable in this column.
Line (NetLinx only) Enter line number (in the Source Code file) where the variable is declared. Length Value Display This column displays the length of the watched variable. This column displays the value of the watched variable. This column displays the format of the variable (ASCII, Decimal, Hexadecimal, Octal, ASCII or Binary).
You can also drag and drop a variable from the Source Code Editor window into the debug window.
Right-click inside the Watch Window to access the Watch Window context menu.
18
Watch Window Context Menu Right-click inside the Watch Window to access the Watch Window context menu, described below:
Refresh List Add Variable Refreshes the contents of the Watch Window. Opens a text field in the Name column, to allow you to add a variable to the Watch Window.
Add Variable From List Opens the List of Watched Variables dialog, where you can select a variable to add to the Watch Window from a list of all variables located in the TKN file of a compiled NetLinx source code file. Delete Variable Delete All Variables Total Length Deletes the selected variable from the Watch Window. Deletes all variables from the Watch Window. Sets the viewing mode for arrays to show the total length of the array in the Length column of the Watch Window. All of the locations of the array are displayed, regardless of the Current Length value of the array. By default, this option is enabled. When disabled, the viewing mode shows Current Length in the Length column. Toggles the step mode between Run and Single Step mode. In NetLinx systems, this command executes a single instruction in the source file; in Axcess systems, it executes a single line of code in the Mainline.
19
20
21
13. Click Next to proceed to the System Communications dialog. This dialog displays the current Master Communication Settings in a read-only text box. 14. Click Communication Settings to set the communication settings for this System, in the Communication Settings dialog.
These settings become the default communication settings for all new Workspace files, until they are manually changed.
15. Click Next to proceed to the Master Source Code File Selection dialog. 16. Use the radio buttons to select the type of Master Source Code file to create for this System: Create an empty AXS File - This option generates an AXS file that is totally empty (no templates used): a. Click Next to proceed to the Master Source Code File Name dialog. b. Enter a name (up to 128 characters) for the new (empty) Master Source Code File. c. Click Source Code File Description to enter a description (up to 2,000 characters) in the Source Code File Description dialog, and click OK to return to the Master Source Code File Name dialog. d. Click Next to proceed to the New File Location dialog. e. Specify the target location for the new file in the text field (click the Browse button to locate and select a target directory via the Browse For Folder dialog). f. Click Next to complete the Wizard. Add an existing AXS File to the System - This option adds an existing AXS file to the System as the Master Source Code File: a. Click Next to proceed to the Existing Master Source File Location dialog. b. Enter a path and filename of the desired Master Source Code File, or click the Browse button to locate and select the desired AXS file via the Open dialog. c. Click Source Code File Description to enter an optional description (up to 2,000 characters) in the Source Code File Description dialog, and click OK to return to the Existing Master Source File Location dialog. d. Click Next to complete the Wizard. Create an AXS File using Templates - This option generates an AXS file using either the NetLinx or Axcess template, depending on the System type specified in Step 9. This option results in a Source Code file that is formatted with header/footer information and all of the main sections of a typical Source Code File of the selected type: a. Click Next to proceed to the File Template dialog. b. Enter a name (up to 128 characters) for the new Master Source Code File. c. Click Next to proceed to the New File Location dialog. d. Specify the target location for the new file in the text field (click the Browse button to locate and select a target directory via the Browse For Folder dialog).
22
e. Click Source Code File Description to enter an optional description (up to 2,000 characters) in the Source Code File Description dialog, and click OK to return to the Master Source Code File Name dialog. f. Click Next to proceed to the New File Location dialog. g. Specify the target location for the new file in the text field (click the Browse button to locate and select a target directory via the Browse For Folder dialog). h. Click Next to complete the Wizard. Add the Master Source Code File Later - This option allows you to exit the Workspace Wizard at this point, and manually specify the System's Master Source Code File later. 17. In the Wizard Completed dialog, click Finish to exit the Wizard. The new Workspace (with your new Project containing the new System) is represented in the Workspace tab of the Workspace Window. Building the Workspace One advantage to the Workspace concept employed by NetLinx Studio (v2.0 or later) is that you can choose to build (compile) the entire Workspace. That is, every Source Code, Include, and Module file contained within the open Workspace can be compiled with a single command: Build Workspace. There are several ways to access the Build Workspace command - via the Build menu, the Workspace context menu (in the Workspace tab of the Workspace Window), or via the toolbar button. To compile the open Workspace: 1. Select Build > Build Workspace (or click the toolbar button). Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. This dialog gives you the option of ignoring the errors and continuing with the build. 2. The status and results of the build are displayed in the Status tab of the Output Display Window.
23
The Code Wizard can be toggled to display individual dialogs for all the above functionality, for use by advanced users. When the Wizard generates a new code segment, it is automatically inserted in the active Source Code file, in the appropriate section of the code.
24
One advantage of the Workspace file is that it serves as a time-saver: Once you have saved a Workspace file, (containing a particular set of Projects, Systems and System Files), the next time you open the application, you can simply open the single Workspace file (File > Open Workspace) to load the Projects/Systems it contains. This way you bypass the need to open each Project, System and System File individually. All Projects and associated Systems and System files are linked to the Workspace, so that you can add and remove Projects and Systems without having to make copies of the files. NetLinx Studio also allows you to copy and paste Projects within the Workspace; in the case that you need to create several similar Projects you can quickly generate multiple Projects and modify each one as necessary.
Since all System files are linked to the Workspace, when you open a file for editing, you are opening and editing the actual file, not a local copy. It is important to understand that in the event that the file is linked to multiple Systems, any changes made to the file will be reflected in every instance that the file is used (not just the System that you were in when the changes were made). Even if you don't have multiple links to the same file, you should still be careful about altering the file. If you are linking to a file that other people might use, they will be affected by the changes you make to the file. So, if you intend to make changes to a System file, and you want those changes to be specific to only one System in the Workspace, you should make a copy of the original file (under a different name), make your changes, then remove the original file from the System and link the new file to the System.
Workspace files also allow you to build (compile) multiple Projects/Systems. The Build Workspace command compiles every file contained in the Workspace. It is important to note that in NetLinx Studio (v2.0 and later), there is no concept of Projects outside the context of a Workspace. A Project can only be opened by adding it to a Workspace. This is to support the file linking aspect of the program.
25
Other features of the Workspace file include: You can import other Project or Systems folders from previously saved Workspace files. You can copy and paste existing Projects and Systems within a Workspace. You can edit the identifier that is used to display the workspace name in the tree display along with the description for the Workspace file via the Workspace Properties dialog. You can export all the files associated with the Workspace (including the Workspace file) into a .ZIP file. Opening Workspace Files 1. Select Open Workspace from the File menu or the Workspace context menu (or click the toolbar button) to open the Open Workspace dialog. 2. Use the options in this dialog to locate and select a Workspace (.APW). 3. Click Open to open the selected Workspace file.
Since you can only have one Workspace open at a time, the program will prompt you to save any changes before closing the active Workspace and opening the selected one.
Creating New (empty) Workspace Files To create a new empty Workspace: Right-click on the Workspace folder to access the Workspace context menu, and select New Workspace. Before the new Workspace is created, the program will prompt you to save any changes made to the currently open Workspace (if applicable). A new Workspace file is created. As indicated in the Workspace tab, this Workspace contains no Projects/Systems. All Projects/Systems and associated files must be added manually.
To create a new Workspace with a Project and System, use the Workspace Wizard.
Import an Existing Project You can import existing Projects into the active workspace, via the Import a Project option in the Workspace context menu. To import an existing Project into the active Workspace: 1. Right-click on the Workspace folder (in the Workspace tab of the Workspace window) and select Import a Project from the Workspace context menu. 2. In the Open Workspace dialog, locate and select the Workspace (.APW) file that the Project you want to import currently belongs to.
The same Project can be included in more than one Workspace file.
26
3. In the Import Components From a Workspace dialog, use the check boxes to select which Project(s) contained in the specified Workspace file to import. 4. Click OK.
If the selected Project(s) contain any identifiers that are already being used by the target Workspace, the program prompts you to change them. In this case, use the Import Name Change dialog to specify a new identifier for the imported Project.
5. The specified Project(s) should now appear as part of the open Workspace. Copying and Pasting Projects One advantage to the concept of Workspaces is that you can easily copy and paste Projects (and all of the associated Systems and System Files) within a Workspace. This allows you to develop a core Project which you can then copy, paste and modify as necessary. In cases where there are only minor variations from one Project to the next, this can be a real timer-saver. To copy and paste a Project (within a Workspace): 1. Open a Workspace (in the Workspace tab of the Workspace Window) and click to select (highlight) a Project folder. 2. Right-click on the Project folder and select Copy Selected Project from the Project Folder context menu. 3. Right-click on the Workspace file, and select Paste Project from the Workspace context menu. Deleting A Project From The Workspace When you "delete" a Project from the open Workspace, no System files are actually deleted from the hard drive; the Project is simply removed from the open Workspace. To delete a Project from the Workspace: 1. Click to select the Project that you want to remove (in the Workspace tab of the Workspace Window). 2. Select Delete Project from the Project menu, the Project Folder context menu, or click the toolbar button. 3. The program prompts you to confirm removing the selected Project. 4. Click Yes to remove the Project. Importing Projects Into A Workspace You can import existing Projects into the active workspace, via the Import a Project option in the Workspace context menu. To import an existing Project into the active Workspace: 1. Right-click on the Workspace folder (in the Workspace tab of the Workspace window) and select Import a Project from the Workspace context menu. 2. In the Open Workspace dialog, locate and select the Workspace (.APW) file that the Project you want to import currently belongs to.
27
The same Project can be included in more than one Workspace file.
3. In the Import Components From a Workspace dialog, use the check boxes to select which Project(s) contained in the specified Workspace file to import. 4. Click OK.
If the selected Project(s) contain any identifiers that are already being used by the target Workspace, the program prompts you to change them. In this case, use the Import Name Change dialog to specify a new identifier for the imported Project.
5. The specified Project(s) should now appear as part of the open Workspace. Saving The Workspace Click File > Save Workspace (or click the toolbar button) to save the Workspace using the current filename and identifier. Select File > Save Workspace As to save the file under a new name. If you save the Workspace under a different name, the program will ask you wether you want to change the Workspace Identifier (the name that appears at the top of the Workspace tab of the Workspace Window) to match the new filename. Exporting Workspace Files For Distribution The Export Workspace Files To Go option in the Project menu allows you to export the open Workspace for distribution as an AXW file. AXW files preserve all relative file path information for the Projects, Systems and System files contained in the Workspace, making them ideal for distribution to remote sites. As is indicated in this dialog, there are three major points to understand when exporting your Workspace files: All files will reside in the same directory as the APW file upon extraction of the AXW file. No directory/path information is required for the "To Go" APW File Name. You may enter non-existing folders and the program will create them for you. 1. Select Export Workspace Files To Go from the Project menu, the Workspace context menu, or click the toolbar button to open the Export Workspace Files To Go dialog. 2. By default, the name and target directory of the AXW file to be created matches the name of the open Workspace file. Use the Name of the "To Go" File text field to change the name and target directory for the resulting AXW file, if desired. Use the Browse button to navigate to a different folder. 3. By default, the name and target directory of the APW file to be created (and included in the AXW "To Go" file) matches the name of the open Workspace file, with "_Exported" appended to the end (for example "NetLinx Boardroom.APW" becomes "NetLinx Boardroom_Exported.APW" once it is extracted from the AXW file). Use the "To Go"
28
Workspace Filename To Create text field to change the name and target directory for the resulting AXW file, if necessary. 4. Use the radio buttons in the Export Options area of the dialog to specify exporting the Full Workspace (all Projects and Systems included), or only the currently active Project (Only Active Project) or the currently active System (Only Active System). By default, the program is configured to export the entire Workspace file. 5. Use the checkboxes in the Export Options area to select additional options as desired: Select the Include User IRN Database(s) checkbox to include any user-defined .IRN (IR database) files in the resulting AXW file. If the selected Workspace file does not include any user-defined IRN files, this option is disabled. Select the Include Module Files that are not part of the Workspace checkbox to include AXS (*.TKO) and Duet (*.JAR) Module files that are needed for a successful NetLinx compile and link, but have not been added to the Workspace. Module files are found by searching the "Module Files" directories defined on the NetLinx Compiler tab of the Preferences dialog. If the selected Workspace file does not utilize Module files, this option is disabled. Select the Exclude All Source Code/AXS and Duet Module Files checkbox to exclude source code and Duet module files from the resulting AXW file. Excluding AXS/AXI files will result in device mappings of the exported AXW file to be set to "Custom". Since no source files will be part of the exported AXW, all device mappings will need to be resolved in the newly created APW file. Naturally, the previous two options are mutually exclusive. If you select one, the other is disabled. Select the Include the Compiled TKN/TOK File checkbox to include the compiled TKN/TOK file in the exported APW file. Select the Include the Complied SRC File checkbox to include the compiled SRC file (in addition to the compiled TKN/TOK file). Note that this option is only enabled if the Include the compiled TKN/TOK file option is selected. The Progress bar indicates the progress of the export operation. Once the export operation is done, detailed results of the operation are listed in the Export Workspace Files Report dialog. Importing Exported ("To Go") Workspace Files 1. Select Project > Import From Exported Workspace File (or click the toolbar button) to access the Select AXW File dialog. 2. Locate and select the desired AXW file, and click Open. 3. In the Import From Exported Workspace File dialog, the file selected in the Select AXW File dialog is listed in the AXW File to Extract From field. Use the browse button to locate and select a different file, if necessary. 4. The target directory indicated in the Extract To field matches the source directory for the selected file by default. Use the browse button to locate and select a different target directory for the Workspace file, if necessary.
29
5. Click Extract to extract the selected Workspace file to the specified directory. If a file of the same name already exists in the target directory, the NetLinx Studio Extraction Overwrite dialog prompts you to either overwrite the existing file (Yes or Yes To All), to preserve the existing file (No), or to cancel the operation. 6. Once the file is extracted, the Workspace file is automatically loaded, and is represented in the Workspace tab of the Workspace Window.
If a Workspace file is open when the file is extracted, the program prompts you to close the currently open Workspace, as well as any associated System files.
Viewing and Editing Workspace Properties Use the Workspace Properties dialog to view and/or edit general properties of the open Workspace. To access this dialog, select Workspace Properties from the Project menu, the Workspace context menu, or click the toolbar button. You can edit the Identifier and Description fields, but the File Name and Creation Date are readonly.
Identifier File Name Description Creation Date The Workspace Identifier can have a maximum of 128 characters. The File Name cannot be changed and is only for display. The Description text is optional and can have a maximum of 2,000 characters. This read-only field indicates the creation date of the open Workspace.
Conversion Date If a NetLinx Studio v2.0 (or higher) workspace file was converted from a NetLinx Studio v1.2 *.PJS file, the Conversion Date will also be displayed.
Workspace File Context Menu Right-click on the Workspace file (in the Workspace tab of the Workspace Window) to open the Workspace File context menu. This context menu contains various Workspace file-level commands and options, including:
New Workspace Closes the currently open Workspace file, and starts a new (empty) workspace (no Project/System associated until you add them manually). Launches the Workspace Wizard, which steps you through the process of creating a new Workspace with a Project/System. Opens the Open Workspace dialog, where you can locate and select an existing Workspace (.APW) file. You can have only one Workspace open at any time, so in the event that you have a Workspace open, it will be replaced by the one you open. Closes the Workspace file. The program prompts you to close the files associated with the Workspace before closing them. Saves the Workspace file, under its current name and location. Opens the Save Workspace As dialog, where you can specify a new name and/or location for the saved Workspace file. Builds (compiles) the Workspace (including all contained Projects). The progress and results of the build can be viewed in the Status tab of the Output Display window.
30
Opens the Export Workspace File To Go dialog, where you can export the Workspace for distribution as an AXW file. AXW files preserve all relative file path information for the Projects, Systems and System files contained in the Workspace making them ideal for distribution to remote sites. Opens the Select AXW File dialog, where you can select a previously exported "To Go" (AXW) file to import into the program. Opens the New Project Properties dialog, which allows you to assign an Identifier and general properties for a new Project. Once created, the new project is added to the Workspace. Opens the Open Workspace dialog, where you can locate and select a Workspace (.APW) file. This invokes the Import Components From a Workspace dialog. Use the dialog to select a specific Project contained in the Workspace. You can copy and paste Projects by selecting Copy Project from the Project Folder context menu, and selecting the Paste Project command. Collapses the Project/System/File tree to show only the Workspace and its Project(s).
Import a Project
Paste Project
Collapse Tree
Expand To System Level Expands the Project/System/File tree to show the Workspace, Project(s) and System(s). Docking view Hide Quick Load Workspace Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window. This option allows you to access the File Transfer dialog, already configured to send all files in the Workspace (active Project/System only) to the Master associated with the active System. Opens the Workspace Properties dialog, where you can view the basic properties of the open Workspace. The options in this dialog also allow you to edit the Workspace Identifier and Description.
Workspace Properties
31
32
Even if you don't have multiple links to the same file, and instead have only a single link, you still need to be careful about altering the file. If you are linking to a file that other people might use, they will be affected by the changes you make to the file. So, if you intend to make changes to a System file, and you want those changes to be specific to only one System in the Workspace, you should make a copy of the original file (under a different name), make your changes, then remove the original file from the System and link the new file to the System.
2. Enter an Identifier (name) for the Project (required). The Identifier can have a maximum of 128 characters, and must be unique within the open Workspace file.
33
3. Enter Dealer, Designer, Sales Order, Purchase Order info (maximum of 128 characters each), and a Description for the Project (maximum of 2,000 characters). These fields are all optional. 4. Click OK to add the new Project to the active Workspace.
34
The original NetLinx Studio v1.2 file is not altered during this conversion process.
To convert NetLinx Studio v1.2 Project Files for use with NetLinx Studio v2.0: 1. Select File > Open Workspace (or use the toolbar button) to open the Open Workspace dialog. 2. Change the Files of type option (at the bottom of the dialog) to NetLinx Studio V1.2 PJS File (*.pjs) files. 3. Locate and select the desired NetLinx Studio v1.2 Project file (*.PJS). 4. The program prompts you to proceed with the conversion process. Click Yes to continue to the PJS to APW Project File Conversion dialog. 5. Click Convert to start the process. 6. The program prompts you when the conversion is complete (click OK in the Conversion Succeeded dialog). 7. Once the file has been successfully converted, the program prompts you to change the Communication Settings for the converted file. For Projects with multiple systems, the program prompts you to change the communication settings for each System individually. Click Yes to change the System-Level Communications Settings for each System contained in the converted Project (via the Master Communications Settings dialog), or click No to leave the communication settings alone for this Project/System. The converted file now exists as a .APW file, in the same folder that contained the original .PJS file under the same name, but with the .APW file extension. The new Workspace file is automatically opened in the Workspace Window - Workspace tab. At this time, any open Workspace files are automatically closed. If there have been any unsaved changes made to the open Workspace, the program prompts you to save your changes before the Workspace is closed. The converted file now appears as a Workspace with one Project, and one System, and can be treated like any other NetLinx Studio v2.0 Workspace file.
When converting NetLinx Studio v1.2 Projects that contain Module Files, all Module files will appear in NetLinx Studio v.2's Source folder, as opposed to the Module folder. Any TKO files resulting from compiling those files will be placed in the Module file folder. This is only true for converted files, and doesn't apply to Module files added to a new Workspace file created in NetLinx Studio v2.0.
35
Project Folder Context Menu Right-click on any Project folder (in the Workspace tab of the Workspace Window) to open the Project Folder context menu. This context menu contains various Project -level commands and options, including:
New Project Opens the New Project Properties dialog. The options in this dialog allow you to specify information for the new Project, including Project Identifier, Dealer, Sales Order, Designer, Purchase Order and Description. Deletes the selected Project from the Workspace. This option does not delete the Project or its associated files from the disk. Builds (compiles) the Project (including all contained Systems and System files). The progress and results of the build can be viewed in the Status tab of the Output Display window. Copies the selected Project to clipboard memory, so it can be pasted (within the same Workspace only), via the Paste Project command in the Workspace context menu. Opens the System Properties dialog, which allows you to assign an Identifier, System ID, and Description for a new System. The System Properties dialog also contains options that allow you to set custom communication settings for the new system. Once created, the new system is added to the Project. Opens the Open Workspace dialog, where you can locate and select the Workspace (.APW) file that contains the System you want to import into the Project. Once you select an APW file, the Import Components From a Workspace dialog is invoked. Use this dialog to select specific Systems contained in the selected Workspace. You can copy and paste Systems (within a single Workspace) by selecting Copy Selected System from the System context menu, then opening the target Project, and selecting the Paste System command. Collapses the Project/System/File tree to show only the Workspace and its Project(s).
New System
Import a System
Paste System
Collapse Tree
Expand To System Level Expands the Project/System/File tree to show the Workspace, Project(s) and System(s). Docking View - Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hide Quick Load Project Hides the Workspace Window. This option (only available for the active Project) allows you to access the File Transfer dialog, already configured to send all files in the active Project to the Master associated with the active System. Opens the Project Properties dialog, where you can view and edit the basic properties of the Project (Project Identifier, Dealer, Sales Order, Designer, Purchase Order and Description).
Project Properties
36
In NetLinx Studio v2.0 (or later), all Projects and associated Systems and System files are linked to the Workspace, so that you can add and remove Projects and Systems without having to make copies of the files. NetLinx Studio v2 also allows you to copy and paste Projects within the Workspace; in case you need to create several similar Projects you can quickly generate multiple Projects and modify each one as necessary.
Since all System files are linked to the Workspace, when you open a file for editing, you are opening and editing the actual file, not a local copy. It is important to understand that in the event that the file is linked to multiple Systems, any changes made to the file will be reflected in every instance that the file is used (not just the System that you were in when the changes were made).
Even if you don't have multiple links to the same file, and instead have only a single link, you still need to be careful about altering the file. If you are linking to a file that other people might use, they will be affected by the changes you make to the file. So, if you intend to make changes to a System file, and you want those changes to be specific to only one System in the Workspace, you should
37
make a copy of the original file (under a different name), make your changes, then remove the original file from the System and link the new file to the System.
To create a new System: 1. Select the Project that you want to add the new System to in the Workspace Window (Workspace tab). 2. Select New System from either the Project menu or the Project context menu (or click the toolbar button) to open the New System dialog. Use the options in this dialog to specify an Identifier, System ID and Description for the new System.
The System ID number only applies to NetLinx systems. If you are creating an Axcess system, ignore the System ID field.
3. Click Communication Settings to open the Communication Settings dialog, where you specify the System platform, communications port settings or network settings as required: Click the Platform Selection radio buttons to select either Axcess or NetLinx as the system platform. Select a Transport Connection Option (TCP/IP, Serial or Modem). TCP/IP - To specify network TCP/IP settings (NetLinx systems only), select the TCP/IP radio button, and click Settings to open the TCP/IP Settings dialog, where you can enter the System's IP Address assignment.
Do not change the Port number! It should always be set to 1319 (default).
Serial - Select the Serial radio button, and click Settings to open the Serial Settings dialog, where you can select and configure a Serial COM port to use. Modem - Select the Modem radio button, and click Settings to open the Modem Settings dialog, where you can select and configure a Modem COM port to use. 4. Click OK to add the new System to the selected Project.
38
39
6. Click Edit Settings to specify the communication settings for the selected connection option: For TCP/IP connections: Set the TCP/IP address (TCP/IP Settings dialog).
40
For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). For Virtual NetLinx Master connections: Specify the System number for the Virtual Master (Virtual NetLinx Master Settings dialog; default = 1). The default settings for Serial and Modem ports are:
Com Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1
Some combinations of settings may result in truncation in the Settings display text field (indicated by an ellipsis). If this is the case, simply hover the mouse cursor over the Settings display text field to view the full description.
7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. Alternatively, you can also access these System-level communications settings options via the System Properties dialog: 1. Select (highlight) a System in the Workspace tab of the Workspace Window, and select System Properties from either the Project menu or the System Folder context menu (or click the toolbar button) to open the System Properties dialog. 2. In the Communication Settings area (at the bottom of the dialog), click Communication Settings to open the Communication Settings dialog. 3. Follow steps 4 through 8 (above) to specify communication settings for the selected System.
41
Use the Recent tab to quickly locate and select recently used files.
4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.
5. Edit the file information (if necessary). 6. If the file you are adding is to be used as the Master Source Code file, check the Master File option. 7. Click OK to add the file to the selected System. Alternatively, you can drag and drop files into a System in the Workspace Window from Windows Explorer or from the Find In Files/Find IR Files tabs of the Output Display Window. See the Drag and Drop Files into a System topic for details.
Drag And Drop Files Into A System
NetLinx Studio allows you to drag and drop files into a System: In Windows Explorer, select a file that you want to add to a System in the Workspace Window (Workspace tab). Drag and drop the file into the System folder. In the Output Display Window, you can select any of the files listed as search results in either the Find In Files or Find IR Files tabs. Drag and drop the file into the System folder.
Do not drop the file into the specific System File folder that matches its type. Regardless of type, all files must be dropped into the System folder to be added (imported) correctly into the System.
When the file is dropped into the System folder, the File Properties dialog is invoked. Use the options in this dialog to rename the selected file, browse for a different file, and/or enter a description for the file (if desired). Click OK to add the file to the System. Note that the file is placed in the appropriate System File folder based on the file type.
42
3. The program prompts you to verify this action. 4. Click Yes to remove the file from the System.
Alternatively, you can simply select a System file and press the Delete key for the same results.
To compile the Active System: 1. Select Build Active System from the Build menu, or click the toolbar button. Any errors detected by the program before the build operation starts are listed in the Pre-Build Errors dialog. Assuming that a Master Source Code file has been defined for the System, this dialog gives you the option of ignoring the errors and continuing with the build. 2. The status and results of the build are displayed in the Status tab of the Output Display Window.
43
Communication Settings The Communication Settings window displays the current communications settings for this System. To change these settings, click the Communication Settings command button to open the Communication Settings dialog.
System Folder Context Menu Right-click on any System folder (in the Workspace tab of the Workspace Window to open the System Folder context menu. This context menu contains various System-level commands and options, including:
Set as Active System New System Sets the currently selected System as the Active System. Opens the New System dialog. The options in this dialog allow you to specify information for the new System, including System Identifier, System ID, Description and Communication Settings. Deletes the selected System from the selected Project. This option does not delete the System or its associated files from the disk. Builds (compiles) the active System (including all contained System files). The progress and results of the build can be viewed in the Status tab of the Output Display window.
Copy Selected System Copies the selected System to clipboard memory, so it can pasted into another Project (via the Paste System command in the Project Folder context menu). Add File To System Opens the Add Existing File dialog, which allows you locate and select an individual file to be added to the active System. The selected file will automatically be added to the appropriate System File folder, based on file type. Collapses the System/File tree to hide all System files. Expands the System/File tree to show all System files contained in the System File folders. Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window. This option (only available for the active System) allows you to access the File Transfer dialog, already configured to send all files in the active System to the Master associated with the active System. Opens the System Properties dialog, where you can view and edit the basic properties of the active System (System Identifier, System ID, Description and Communication settings).
Collapse Tree Expand System Tree Docking View Hide Quick Load System
System Properties
44
System Files
System Files represent the actual files that are needed to operate a particular controlled device in the named System. System files include Source Code, Include files, NetLinx Module files, IRLib files, User-Interface (UI) files and any other (*.*) files that you might want to include. System files are placed in the appropriate System file folder (in the Workspace tab of the Workspace Window) as links only. System file types are described below:
Master Source Code file Source Code files This is the Source Code file that defines the devices in the System. Master Code files are sent only to the Axcess or NetLinx Master Controller. Master Source Code files are placed in the Source file folder. These include all code files (.AXS) that are not Master Code Files. Source Code Files are created in NetLinx Studio, and are sent to specific devices on the bus. Source Code files are placed in the Source file folder. These are Axcess or NetLinx code files (.AXI) that are separate from the main Master and Source Code files, but are included in the compile process. These files are created in NetLinx Studio. Include files are placed in the Include file folder. These files provide pre-fabricated (.AXS) code or compiled (.TKO) code to control a specific device on the bus. NetLinx Studio v2.3 (or higher) supports Duet (.JAR) Module files. Module files cannot be designated as master files. When the System is being compiled, these Module files are compiled first, then copied to the directory where the designated Master Source code file resides. Module files are placed in the Module file folder. User-Interface (UI) files These are (.TPD/.TP4) or (.KPD) files that are imported into Projects. TPD/TP4 touch panel UI files define the look and functionality of touch panel pages. TPD files are touch panel UI files created in TPDesign3 (for use with G3 level firmware touch panels), TP4 files are created in TPDesign4 (for use with G4 level firmware touch panels, i.e. Modero series panels). KPD files are created in the KPDesign KeyPad Design program, and define the buttons and functionality of PLK-DMS and PLK-IMS Keypads. UI files represent the user-interface for the control system. UI files are placed in the User Interface file folder. These files (.IRL or .IRV) are created in IR Edit and contain infrared (IR) control functions for IR controlled devices. IR files are placed in the IR folder. IRN files provide links to the AMX IR Database and/or user-defined IR Database files. In many cases, it is helpful to save document and image files (for example, .TXT, .DOC, .BMP) with the other system files, even if they are not directly utilized by the control system. "Other" files are placed in the Other file folder.
Include files
Module Files
45
Use the Project > Add File To System command to add the file to a System.
To create new System file: 1. Select New from the File menu, or click the toolbar button to open the New dialog. 2. Select the type of file that you want to create (Source File, Include File, Block File, or Standard Text).
The Workspace Wizard option launches the Workspace Wizard, which steps you through the process of creating a new Workspace with a Project and one System.
3. Click OK to open an empty Source Code Editor window. 4. Develop the file as needed in the Source Code Editor window, and select File > Save (or click the toolbar button). 5. Specify a name and target location for the new file in the Save As dialog. File Types And Extensions
File Type Axcess Source Code File Include File File Extension .AXS .AXI
Compiled Axcess Source Code File .TOK Compiled NetLinx Source Code File .TKN NetLinx Source Code File Block File TPDesign3 User Interface File TPDesign4 User Interface File KPDesign Keypad Touch File IR Library File IRV File IRN (IR Database) File Standard Text File Other File .SRC .AXB .TPD .TP4 .KPD .IRL .IRV .IRN .TXT .* (any other extension)
46
Compile As
Creation Date The date the file was created (read only).
47
Device Mapping
The Device Mapping dialog allows you to map files to System devices for file transfers. To access the Device Mapping dialog, select a System (in the Workspace tab of the Workspace Window) and select Project > Device Mapping. Alternatively, you can access the Device Mapping command via the Device Mapping command in the Source File, User Interface, and IR File context menus, or use the toolbar button. Device Mapping Dialog The Device Mapping dialog consists of two windows. The File View window (on the left) presents a view of the Projects, Systems and System Files contained in the open Workspace file, in a tree structure similar to the one displayed in the Workspace tab of the Workspace Window. Double-click the Project folders to show the System folders. Double click to expand the System folders to show the System File folders (Source, User Interface and IR only, since these are the only file types that can mapped). Double-click these folders to view the System files. The Device View window (on the right) presents a view of devices specified in the DEFINE_DEVICE section of the selected System's Master Source Code file, with their associated device numbers. There is also a <Custom> listing, which allows you to specify a D:P:S assignment other than what is specified within the Master Source Code file. With a file selected (in the File View window), select a target device for the file in the Device View window, and click the Map button to map that file to the selected device. If you select <Custom>, the Enter DPS dialog will prompt you to enter the D:P:S assignment of the device you want to map to. Files can be mapped to multiple devices. In Axcess, Master Source Code files are always mapped to the Master Controller (device = 0), and cannot be mapped to any other device. This does not apply to NetLinx Master Source Code files. Once a file has been mapped to a device, the mapping assignment is indicated in the File View window of the Device Mapping dialog as well as in the Workspace tab of the Workspace Window. The file mapping information is saved with the Workspace file, and this association is maintained until the mapping information is removed (via the Remove option in the Device Mapping dialog, or the Delete command in the System File Device Map context menu.
Workspace mappings are only updated when the source code file is saved.
NetLinx Studio makes it easy to map System files to devices on the bus for file transfer operations: 1. Select and open the Project containing the Source Code file to be mapped to a device (in the Workspace tab of the Workspace Window). 2. Select the System containing the file.
48
3. Select Device Mapping from the Project menu (or use the toolbar button) to open the Device Mapping dialog.
You can also access the Device Mapping command via the Source File, User Interface, and IR File context menus. The Device Mapping option is only available if you have selected a Source Code file that is not designated as the Master Source Code file.
4. In the Device Mapping dialog, select a System from the File View window on the left side of the dialog (if different than the System already selected). 5. Double-click to expand the System folder to view the System File folders (Source, User Interface and IR). 6. Double-click to expand the System File folder containing the file you want to map to a device, and select the file you want to map. 7. In the Device View window (on the right side), select the target device for the selected file from the list of devices (as specified in the in the DEFINE_DEVICE section of the System's Master Source Code file). To map to a device that is not specified in the Master Source Code file, select <Custom>, and enter the device's D:P:S assignment (in the Enter DPS dialog).
The System's Master Source file will always be mapped automatically to 0:1:0 for NetLinx Masters, and 0 for Axcess Masters.
8. Click the Map button to map the file to the target device. Once a file has been mapped to a device, the mapping assignment is indicated in the File View window of the Device Mapping dialog as well as in the Workspace tab of the Workspace Window. The file mapping information is saved with the Workspace file, and this association is maintained until the mapping information is removed (via the Remove option in the Device Mapping dialog, or the Delete command in the System File Device Map context menu.
Workspace mappings are only updated when the source code file is saved.
DEVICE:PORT:SYSTEM (D:P:S) A device is any hardware component that can be connected to the NetLinx bus. Each device must be assigned a unique number to locate that device on the bus. The Axcess language allows physical device numbers in the range 0-255. The NetLinx language allows numbers in the range 0-32767. Device 0 refers to the master; numbers above 32767 are reserved for internal use. NetLinx requires a Device:Port:System (D:P:S) specification where Axcess expected only a device number. This D:P:S triplet can be expressed as series of constants, variables separated by colons, or as a DEV structure, to explicitly represent a device number, port and system. Here's the syntax:
DEVICE:PORT:SYSTEM
49
where: Device: 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) that the device belongs to. For example, 128:1:0 represents the first port on device 128 on this system. DEV structure example:
STRUCTURE DEV { INTEGER Number INTEGER Port INTEGER System }
In Axcess, Master Source Code files are always mapped to the Master Controller (device = 0), and cannot be mapped to any other device. This does not apply to NetLinx Master Source Code files.
To Remove Device Mapping Information from a File 1. Select a device-mapping icon in the File View window. 2. Click the Remove button. System File Device Map Context Menu Right click on a Device Mapping icon (in the Workspace tab of the Workspace Window) to access the System File Device Map context menu:
Device Mapping Opens the Device Mapping dialog for mapping files to System devices. Delete Removes the selected file's device-file mapping association.
50
Adding A New Source Code File To A System NetLinx Studio provides a set of dialogs that step you through the process of creating a new Source Code (*.AXS) file. To create new Source Code file, and automatically add it to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Source folder to access the Source File Folder context menu, and select Add New Source File to open the File Template dialog.
Alternatively, you can also either select File > New, and select Source File (in the New dialog), or click the New toolbar button.
3. In the File Template dialog, select a template to use to create the file (NetLinx Standard, Axcess Standard or User-Defined), and click Next to proceed.
If you select to use the NetLinx or Axcess templates, the new Source Code file will include all of the sections and headings (i.e. DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) that differentiate the various sections contained in a typical Source Code file for the indicated system type.
4. Enter a file name for the new Source Code file, and select wether to assign this new file as the System's Master Source Code file (via the Make this the Master Source Code file option checkbox). Click Next to proceed. 5. In the New File Location dialog, specify a target directory for the file. By default, the target directory is the NetLinx Studio v2 directory. Use the Browse button to navigate to another folder if necessary. 6. The program notifies you that the file was created. Click Finish to close the File Template dialog. The new file should appear in the Source folder, under the selected System. Adding An Existing Source Code File To A System To add an existing Source Code file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Source folder to access the Source File Folder context menu, and select Add Existing Source File. 3. In the Add Existing Source File dialog, locate and select the Source (.AXS) file that you want to add to the selected System.
4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.
51
5. Edit the file information (if necessary). 6. If the file you are adding is to be used as the Master Source Code file for the System, check the Master File option. 7. Click OK to add the file to the selected System. 8. The file should now appear in the Source folder under the selected System, as the Master Source Code file (indicated by the letter "M" on the file icon in the Workspace tab). Removing A File From A System Since all files are linked in NetLinx Studio v2.0 (or later), when you remove a file from a System, the file is not deleted from the disk, only removed from the System. If the same file is used in multiple Systems in the open Workspace, the Remove File from System option only removes the file from the selected System (as opposed to all instances of the file in the Workspace). To remove a file from a System (in the open Workspace): 1. Click to select (highlight) the file that you want to remove. 2. Select Remove File From System from either the Project menu or the System File context menu (or click the toolbar button). 3. The program prompts you to verify this action. 4. Click Yes to remove the file from the System.
Alternatively, you can simply select a System file and press the Delete key for the same results.
Creating A Source Code File To create a Source Code file: 1. Select New from the File menu, or click the toolbar button to open the New dialog. 2. Select Source File and click OK. 3. In the File Template dialog, select whether to use an existing template to create the file: If you click Yes, you will be prompted to select a template (NetLinx, Axcess or User Defined). If you select the User-Defined Template option, click the Browse button (...) to open locate and select any Source file (.AXS) to use as the template (via the Open dialog). Select the desired template or file and click Next to proceed to step 4. If you click No, you can start developing the file immediately, in a new Source Code Editor window.
If you select to use one of the existing templates (NetLinx or Axcess), the new Source Code file will include all of the sections and headings (i.e. DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) that differentiate the various sections contained in a typical Source Code file for the indicated system type.
4. Enter a name for the new Source Code file. 5. The program notifies you that the file was created.
52
6. Develop the file as needed in the Source Code Editor window, and select File > Save (or click the toolbar button). 7. Specify a name and target location for the new file in the Save As dialog.
Existing Source Code files can be added to Systems via the Project > Add File To System command.
Saving The Active File Click File > Save (or click the toolbar button) to save the active file in the Source Code Editor, using the current file name and identifier. Saving All Open Files Click File > Save All (or click the toolbar button) to save all open files, using their current file names and identifiers. File Revisions The Save As Revision option allows you to save the active Source Code files with file revision information included in the file. This feature allows you to specify a revision number (or other identifier), and add text comments to assist in managing multiple revisions of the same file. Additionally, the program automatically includes a date/time stamp in the revision information. This file revision information is then added as a block of text to the top of the source code file when the revision is saved. Use the options in the Save File Revision dialog (File > Save File Revision) to view/edit the PROGRAM_NAME, revision number (or identifier), file name, and add any comments associated with this revision that you would like to include. To save a file revision of the active Source Code file: 1. Select File > Save File Revision to open the Save File Revision dialog. 2. Enter/edit the information in this dialog as desired:
PROGRAM_NAME = Revision This editable field indicates the PROGRAM_NAME, as it appears in the active source code file. Enter a number (or other identifier) for this revision of the file (for example, REV 1).
Update Name With Revision Text Click this option to automatically generate the PROGRAM_NAME and the File Name to include the revision identifier (as entered in the Revision field). File Name Directory Path Comments This editable field indicates the name (*.AXS) of the active file. This read-only field indicates the directory path of the active Source Code file. Use this field to record any comments that would be helpful to add to the file.
3. Click Save to save the file revision. Note that the specified revision information is added to the top of the file, as can be seen in the Source Code Editor window.
53
The file that was replaced with the new file revision will not be deleted from your hard drive.
The program will insert the file revision information specified here at the top of the source code file, before any other revision information that already exists in the file (if any exists). The example below shows file revision information, as it appears in the source code file after two revision have been saved:
In this case, the Update Name With Revision Text option was enabled, as is indicated by the "Rev2 " that follows the comma delimiter in the PROGRAM_NAME line.
Designating The System's Master Source Code File Each System must have a Master Source Code file, and only one Source Code file in the System can be designated as the Master Source. There are two possible ways to designate the Master Source Code file for a System: You can designate a Source Code file as the Master Source at the time that it is added to the System, via the Master File option in the File Properties dialog. Alternatively, you can designate any Source Code file in the System as the Master Source by right-clicking on a Source Code file (in the Workspace tab of the Workspace Window), and selecting Set As Master from the Source Code File context menu. Compiling Source Code Files There are several ways to compile individual Source Code files: Right-click on a Source Code file (in the Workspace tab of the Workspace Window), and select Compile from the Source Code File context menu. In the Build menu, select Compile <filename.AXS>.
54
To specify the compiler to use (NetLinx or Axcess), double-click to open the file in a Source Code Editor window, and select Compile as NetLinx or Compile As Axcess from the Build menu. The status and results of the build are displayed in the Status tab of the Output Display Window. UTF-8 Encoding In the Save As dialog, select UTF-8 from the Encoding menu to enable UTF-8 support for new files, to help NetLinx Studio files to work better with other editors. You can also select the Enable UTF-8 Encoding option in the Editor tab of the Preferences dialog.
You may also encode files created with a previous version of NetLinx Studio by choosing "Save-As" and selecting the UTF-8 encoding.
SRC File Extraction NetLinx Studio can generate a compressed version of NetLinx program files anytime they are compiled or transferred. The compressed NetLinx files are called Source Files, and have the extension .SRC. To generate NetLinx Source Files at compile time, enable the Build With Source option in the NetLinx Compiler tab of the Preferences dialog. If this option is not enabled, a dummy file is zipped and named "NOSOURCE.TXT".
The Build With Source option also allows you later send the Source files to another Master, with the ability to debug the code.
The Extract From SRC File command allows you to extract these files: 1. Select Tools > File Extraction > Extract From SRC File to open the Select SRC File dialog. 2. Locate and select the SRC file you want to extract, and click Open.
This is the directory containing the actual program file (.AXS). Source files only exist in the directory if the program file has been successfully compiled (using the Build With Source option).
3. In the Extract NetLinx Source From a SRC File dialog, the selected file (with full directory path) is indicated in the SRC File To Extract From field. 4. In the Extract To field, specify the target directory for the extracted NetLinx Source files, and click Extract to extract the files. When extracted, the program will always replicate the directory paths associated with the compressed files when the file was created. To use the original directory paths, enter C:\ as the destination directory. For example if you enter C:\ as the destination directory, you know that the NetLinx.AXI file will be copied into the proper directory for compiling (C:\Program Files\Common Files\AMXShare\AXIs). If a file with the same name already exists in the specified target directory, the program alerts you, and prompts you to overwrite it or pick a different target directory. If you enter non-existent folders, the program will create them for you.
55
The error "Dynazip Unzip Error: Bad or missing decryption key (Problem extracting file(s))" indicates a mismatch between the password assigned to the file (via the Build With Password option), and the NetLinx password entered in the NetLinx Compiler tab of the Preferences dialog (Password field). If you receive this error message, click OK in the error message dialog to access the Enter Password dialog, and re-enter the password exactly as it was entered when the file was compiled.
ZIP File Extraction NetLinx Studio allows you to export an entire Workspace (including all contained Projects, Systems and System Files) as a .ZIP file. The Extract From ZIP File command allows you to extract these files: 1. Select Tools > File Extraction > Extract From ZIP File to access the Select ZIP File dialog. 2. Locate and select the ZIP file you want to extract, and click Open.
While this feature exists primarily to allow you to unzip exported Workspace files, you can use this feature to unzip any .ZIP file.
3. In the Files From a ZIP File dialog, the selected file (with full directory path) is indicated in the ZIP File To Extract From field. Select the Extract using original directory path(s) option to preserve the original directory paths of the files (default = disabled). 4. In the Extract To field, specify the target directory for the extracted Workspace files, and click Extract to extract the files.
If a file with the same name already exists in the specified target directory, the program alerts you, and prompts you to overwrite it or pick a different target directory.
Source File Folder Context Menu Right-click on any Source folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add New Source File Adds a new Source Code (.AXS) file to the selected (not necessarily the "active") System, via the new file wizard. The options in the new file wizard dialogs allow you to assign a File Template, File Name and Location to the new Source Code file.
Add Existing Source File Opens the Add Existing Source File dialog, where you can add an existing Source Code file to the System containing the selected Sources folder. The new file will be added to the selected Sources folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.
56
Source Code File Context Menu Right-click on any Source Code File (in the Workspace tab of the Workspace Window) to access the context menu described below:
Set As Master Compile Sets the selected Source Code file as the Master Source file for the system it belongs to. Compiles the selected file, using the compiler (Axcess or NetLinx) associated with the file. The status and results of the build are displayed in the Status tab of the Output Display Window. Opens the Device Mapping dialog which allows you to map the file to a system device for transfer.
Device Mapping
Remove File From System Removes the selected file from its System (the file is not deleted from the disk, only removed from the System). Quick Load File This option (only available for the Master file in the active System) allows you to access the File Transfer dialog, already configured to send the file to the Master associated with the active System. Opens the File Properties dialog, where you can view (and edit) properties for the selected Source Code file.
File Properties
57
Existing Include files can be added to Systems via the Project > Add File To System command.
Adding A New Include File To A System To create new Include file, and automatically add it to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Include folder to access the Include File Folder context menu, and select Add New Include File. 3. In the New Include File dialog, specify a File Name and target location for the new Include file. 4. Click OK to create the file. The new file should appear in the Include folder, under the selected System. Adding An Existing Include File To A System To add an existing Include file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Include folder to access the Include File Folder context menu, and select Add Existing Include File. 3. In the Add Existing Include File dialog, locate and select the Include (.AXI) file that you want to add to the selected System.
4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.
5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the Include folder under the selected System. Include File Folder Context Menu Right-click on any Include folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add New Include File Adds a new Include (.AXI) file to the selected (not necessarily the "active") System, via the New Include File dialog. The options in this dialog allow you to assign a name and target directory for the new Include file.
58
Add Existing Include File Opens the Add Existing Include File dialog, where you can add an existing Include file to the System containing the selected Include folder. The new file will be added to the selected Include folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.
Include File Context Menu Right-click on any Include file (in the Workspace tab of the Workspace Window) to access the context file described below:
Remove File From System Click to remove the selected Include file from the System that it is saved in. The program prompts you to confirm this action before the file is deleted from the System. The file is not deleted from disk. File Properties Opens the File Properties dialog, where you can view (and edit) properties for the selected Include file.
Refer to the Cafe Duet online help file for details on creating JAR module files.
JAR module files are also stored in the Module folder (in the Workspace tab of the Workspace Window), and the same basic rules apply to JAR module files that were true for NetLinx modules: Module files cannot be designated as Master Source Code files. When the System is being compiled, first the Module files are compiled and then the Master Source Code (.AXS) file is compiled. NetLinx Studio (v2.3 or higher) constructs a composite TKN file when Duet module(s) are included in the Workspace and are referenced in the NetLinx Source code. The composite TKN file
59
is a DynaZip file containing the compiled TKN file as well as the JAR modules that need to be transferred to the NetLinx master in order for the TKN file to execute properly. Minimum Support Requirements For Modules Minimum support requirements for the KPDesign module: PLK-DMS Keypad, v5.1 PLK-IMS Keypad, v5.0 NetLinx Studio v1.2 NetLinx Master v2.0, build 94 Minimum support requirements for Duet modules (*.JAR): NetLinx Studio v2.3 NetLinx Master Firmware build 304 Adding A New Module File To A System To create new Module (*.AXS) file, and automatically add it to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Module folder to access the Module File Folder context menu, and select Add New Module File. 3. In the File Template dialog, select whether to use an existing template to create the file. If you click Yes, you will prompted to select the template (NetLinx or Axcess). You can select to create a module file using the "module standard" template ("NetLinx Module.axs"). The module standard template file is located in the same directory as the NetLinx Studio application .EXE file. If you click No, you will proceed directly to the New File Location dialog.
If you select to use one of the existing templates (NetLinx or Axcess), the new Source Code file will include all of the sections and headings (i.e. DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) that differentiate the various sections contained in a typical Source Code file for the indicated system type.
4. In the New File Location dialog, enter a File Name, and specify a target directory for the module file. Use the Browse button to navigate to another folder, if necessary. 5. The program notifies you that the module file was created. 6. Click Finish to close the File Template dialog. The new file should appear in the Module folder, under the selected System. Adding An Existing Module File To A System To add an existing Module file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). Doubleclick the folder to view the System File folders.
60
2. Right-click on the Module folder to access the Module File Folder context menu, and select Add Existing Module File (or click the toolbar button). 3. In the Add Existing Module File dialog, locate and select the Module (.AXS, .TKO or .JAR) file that you want to add to the selected System.
4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected module file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.
5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the Module folder under the selected System. Source Code Entry To include a module into your program, use the following module line: DEFINE_MODULE 'DMS-IMSMod' Module_Name(Virtual_Dev, Real_Dev, strFileName, strVarTextArray) Where:
Module_Name Virtual_Dev Real_Dev StrFileName
DMS-IMSMod.tko A virtual device you define. The device number of the DMS or IMS panel. A string variable (CHAR array) containing the file name of the KPD file to run. should be the largest variable text number you want to use. The second dimension should be the maximum size of the string you want displayed (maximum is 40 characters).
StrVarTextArray A two-dimensional array to store variable text in. The first dimension
For example, a NetLinx module for a DMS keypad would look like:
DEFINE_MODULE "DMS-IMSMod" mdlDMS (dvDMS, dvDMS_R, strFILE_NAME, StrVartextArray)
Where:
DMS-IMSMod MdlDMS DvDMS DvDMS_R StrFILE_NAME
The name of the compiled TKO file. The module name. The module ID device number (ex 32768). The device number of the keypad. Exact name of the KPD file.
StrVarText Array Description of the parameters for the variable text buffer.
61
Compiling Module Files There are several ways to compile individual Module files: Right-click on a Module file (in the Workspace tab of the Workspace Window), and select Compile from the Module File context menu. Double-click to open the Module file in a Source Code Editor window and select Compile <filename.AXS> from the Build Menu. To specify the compiler to use (NetLinx or Axcess), open the Module file in a Source Code Editor window, and select Compile as NetLinx or Compile As Axcess from the Build menu. The status and results of the build are displayed in the Status tab of the Output Display Window. Module File Folder Context Menu Right-click on any Module folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add New Module File Adds a new Module (.AXS) file to the selected (not necessarily the "active") System, via the new file wizard. The options in the new file wizard dialogs allow you to assign a File Template, File Name and Location to the new Module file.
Add Existing Module File Opens the Add Existing Module File dialog, where you can add an existing Module file to the System containing the selected Module folder. The new file will be added to the selected Module folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.
Module File Context Menu Right-click on any Module file (in the Workspace tab of the Workspace Window) to access the context menu described below:
Compile Compiles the selected Module file. This option is available only if the selected file is an AXS file (not available for TOK or JAR files).
Remove File From System Click to remove the selected Module file from the System that it is saved in. The program prompts you to confirm this action before the file is deleted from the System. The file is not deleted from disk. File Properties Opens the File Properties dialog, where you can view (and edit) properties for the selected Module file.
62
NetLinx Studio allows you to associate UI files with each System, and to map and transfer the files to their target panels or master.
While Touch Panel UI files are transferred to the panels themselves, KPD files are transferred to the master and not directly to the keypad.
If the TPDesign3, TPDesign4 and/or KPDesign applications are installed on your PC, you can double-click on any UI file in the Workspace tab to launch the associated editor program (TPDesign3, TPDesign4 or KPDesign). You can add external programs to the Tools menu via the Add Tool option. Adding An Existing User Interface File To A System To add an existing User Interface (UI) file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the User Interface folder to access the User Interface File Folder context menu, and select Add Existing User Interface File. 3. In the Add Existing User Interface File dialog, locate and select the UI (.TPD, TP4 or .KPD) file that you want to add to the selected System. .TPD = Touch panel UI files created in TPDesign3 .TP4 = Touch panel UI files created in TPDesign4 .KPD = Keypad UI files created in KPDesign
63
4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.
5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the User Interface folder under the selected System. Configuring NetLinx Source Code for KPD Files You need to configure your NetLinx code to accommodate using KPD files. Before beginning, either use or write a new program (in NetLinx Studio) that: Defines the Virtual devices Defines the Keypad devices Associates the KPD file with defined devices Once you have a program: 1. In the DEFINE_DEVICE section of the code, verify that the dvDMS is set to any user-defined value within the range of 32768 - 36863. 2. In the REALS section of the program, re-write the dvDMS_R to equal the value of the new Device number set in the Device Addressing Tab of the Tools > NetLinx Diagnostics dialog box. An example is if the Changed Device number value is set to 6001, the dvDMS_R value would now read 6001:1:0. Each consecutive keypad device would become:
dvDMS_R 6002, 6003, 6004 +.
3. In the STARTING CODE GOES HERE / CREATE FILE section of the program, the StrFILE_NAME must equal the exact name of the KPD file being used in the compile. 4. Add the KPD file to the project by choosing Project > Add File To System. This opens the Add Existing File dialog. 5. Locate and select for the desired KPD file. 6. Click OK to close the Add Existing File dialog. The file is added to the project file in the UI system folder (in the Workspace tab of the Workspace Window).
64
Sample Netlinx Code To send a KPD file to a NetLinx Master, you must use the NetLinx DMS-IMS module, with the following DEFINE_MODULE entry in the Master Source Code:
DEFINE_MODULE 'DMS-IMSMod' Module_Name(Virtual_Dev, Real_Dev, strFileName, strVarTextArray)
or
DEFINE_MODULE 'DMS-IMSMod' mdlIMS (
For example:
(**********************************************) (* DEVICE NUMBER DEFINITIONS GO BELOW *) (**********************************************) DEFINE_DEVICE DvVIRT = 33001:1:0 DvDMS = 6020:1:0 (**********************************************) (* VARIABLE DEFINITIONS GO BELOW *) (**********************************************) DEFINE_VARIABLE CHAR strFileName[100] (**********************************************) (* STARTUP CODE GOES BELOW *) (**********************************************) DEFINE_START StrFileName = 'avcnt11.kpd' (**********************************************) (* VARIABLE DEFINITIONS GO BELOW *) (**********************************************) DEFINE_VARIABLE CHAR strVarTextArray[100][40]
Where:
DVVirt DvDMS StrFileName
an arbitrary Virtual Device number you define (range for keypad panels = 32768 -36863). the real device number of the DMS or IMS panel. a string variable (CHAR array) containing the file name of the KPD file to transfer or run. should be the largest variable text string number you want to use. The second dimension should be the maximum size of the string you want displayed (maximum is 40 characters). When using two or more keypad panels, you can create a single threedimensional array for a keypad panels, instead of separate two-dimensional arrays for each keypad panel.
StrVarTextArray a two-dimensional array to store variable text in. The first dimension
65
User Interface File Folder Context Menu Right-click on any User Interface folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add Existing User Interface File Opens the Add Existing User Interface File dialog, where you can add an existing User Interface file to the System containing the selected User Interface folder. Docking View Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.
Hide
User Interface File Context Menu Right-click on any User Interface file (in the Workspace tab of the Workspace Window) to access the context file described below:
Device Mapping Opens the Device Mapping dialog to map the selected User Interface file to a specific device on the bus.
Remove File From System Click to remove the selected User Interface file from the System that it is saved in. The program prompts you to confirm this action before the file is removed from the System. The file is not deleted from disk. Quick Load TPD/TP4 File This option allows you to access the File Transfer dialog, already configured to send the selected UI file to the Master associated with the active System. Opens the File Properties dialog, where you can view (and edit) properties for the selected UI file.
File Properties
Adding An Existing Ir File To A System To add an existing IR file to a selected System in the current Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the IR folder to access the IR File Folder context menu, and select Add Existing IR File. 3. In the Add Existing IR File dialog, locate and select the IR (.IRL or .IRV) file that you want to add to the selected System.
66
4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.
5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. The file should now appear in the IR folder under the selected System. IREDIT IREdit is a separate application that works in conjunction with NetLinx Studio v2.0 (or later). The IREdit software application allows you to view and edit IR files. Once IREdit is installed, you can double-click on any IR file in the Workspace tab of the Workspace Window or the Find IR Files tab of the Output Display Window to open the selected IR file for viewing and editing in IREdit.
For instructions on using IREdit to view and edit IR files, refer to the IREdit on-line help.
Working With IREdit Database (*.IRN) Files NetLinx Studio supports IR Database (*.IRN) files generated in the IREdit application. IRN Database files contain many individual IR files, organized by Manufacturer, Device Category, Device Model #, and Hand Control Model #. To launch the IREdit program double-click on an IR file in the Workspace tab of the Workspace Window or double-click on an IR file in the Find IR Files tab of the Output Display Window (results of a search). For detailed instructions on using IREdit, refer to the IREdit online help file. The options in the Select IR From a Database dialog allow you to locate and select IR file(s) from within either the (read-only) AMX IR Database, or a user-defined IR database (*IRN file). Adding An IR File From the AMX IR Database If you have installed the IREdit application, the Add From AMX IR Database option is available in the Project menu, the IR File Folder context menu and the Project Toolbar.
To add an IR file from the AMX IR Database to your Project: 1. Select Project > Add From AMX IR Database to open the Select IR From a Database dialog, with the AMX IR Database displayed.
67
2. In the IR Database Navigator Window (on the left side of this dialog), start by picking the Manufacturer of the device associated with the desired IR file, and drill down through the subfolders (Product Category, Product Model Number and Hand Control Model Number) to locate and select the desired IR file (FIG. 10).
3. Double-click on the file (or select the file and click the Add To List button) to add the file to the Selected IR List. 4. Repeat steps 2 and 3 as often as necessary to populate the Selected IR List, and click OK to close the Select IR From a Database dialog. 5. The selected IR files are add to the selected System (in the IR system file folder).
The file(s) will be added to the selected (highlighted) System in the Workspace tab, which is not necessarily the active system.
Adding An IR File From an IREDIT User Database (*IRN) File Use the options in the Select IR From a Database dialog to access individual IR files from within an existing IREdit IR Database (*IRN) file: 1. Select Add From User IR Database from the Project menu, the IR File Folder context menu, or click the toolbar button to open the Select IRN User Database dialog. 2. Locate and select the *IRN file that contains the IR file(s) that you want to add to the selected System. 3. Click Open to open the selected IRN file in the Select IR From a Database dialog. 4. In the Select IR From a Database dialog, select the Manufacturer, Product Category, Model #, Hand Control Model # and then select the IR file to add to the System. 5. With the desired IR file selected, click Add to add the file to the Selected IR File(s) list. 6. Repeat steps 4 and 5 as many times as is necessary to add the desired files to the Selected IR File(s) list. To remove a file from the Selected IR File(s) list, select a file and click Remove. 7. Click OK to close the Select IRN User Database dialog and open the File Properties dialog, where you can change the selected file's name (Identifier) and Description if necessary. You can assign multiple different identifiers, file names and descriptions to the same file for use in different Projects and Systems, as needed. 8. Click OK to add the file to the selected System (which is not necessarily the active system). The file appears in the IR System File Folder (in the Workspace tab of the Workspace Window).
68
IR File Folder Context Menu Right-click on any IR folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add Existing IR File Opens the Add Existing IR File dialog, which allows you to locate and select an IR file (*.IRL, *.IRV) to add to the System.
Add From AMX IR Database Opens the Select IR From a Database dialog, which allows you to locate and select a hand control record from within the 'AMX IR' database. Add From User IR Database Opens the Select IRN User Database dialog, which allows you to locate and select an IREdit Database file (*.IRN). Docking View Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.
Hide
IR File Context Menu Right-click on any IR file in the Workspace tab of the Workspace Window to access the IR File context menu:
Device Mapping Export to IRL File Opens the Device Mapping dialog to map the selected IR file to a specific device on the bus. This option is only available if the IR file you selected was extracted from an IR Database (*.IRN) file. IR Database files come from the IREdit application, and represent either the AMX IR Database (included with the IREdit application), or a user-defined IR Database file. Once you have added an IR file from an IR Database file (via the Add From AMX IR Database or Add From User IR Database options in the Project menu, IR File Folder context menu, or Project toolbar), you can use this option to export the file as an IRL file that can then be treated as a stand-alone IR entity (independent of the IR Database file that originally contained it). Remove File From System Click to remove the selected IR file from the System that it is saved in. The program prompts you to confirm this action before the file is removed from the Project. The file is not deleted from the disk. File Properties On IRL files, this option opens the standard File Properties dialog, where you can view (and edit) properties for the selected file. For IR Database (*.IRN) files (from either the AMX IR database or a User IR Database file), this option opens the IRN File Properties dialog, which includes several fields and options that are specific to IR Database files.
69
Do not attempt to open .LIB or .SYC files for editing in the Source Code Editor. Doing so could cause program failure.
Creating a Text File To create a Standard Text (.TXT) file: 1. Select New from the File menu, or click the toolbar button to open the New dialog. 2. Select Standard Text and click OK. 3. An (empty) Standard Text file is created in a new Source Code Editor window. By default, this file is named TXT<x>.txt. 4. Develop the file as needed in the Source Code Editor window, and select File > Save (or click the toolbar button). 5. Specify a name and target location for the new file in the Save As dialog.
Existing Text files can be added to Systems via the Project > Add File To System command.
Adding an Existing "Other" File To a System To add an existing "Other" file to a specific System in the Workspace: 1. Click to select (highlight) a System (in the Workspace tab of the Workspace Window). 2. Right-click on the Other folder to access the Other File Folder context menu, and select Add Existing Other File. 3. In the Add Existing Other File dialog, locate and select the file that you want to add to the selected System. The Add Other dialog is set to look for .TXT files by default; change the Files of Type option to All Files (*.*) to look for other file types.
4. Click Open to access the File Properties dialog, where you can view/edit general file information for the selected file.
70
If you select multiple files to add to the System, the program will prompt you to edit the file properties for each file before adding them.
5. Edit the file information (if necessary). 6. Click OK to add the file to the selected System. 7. The file should now appear in the Other folder under the selected System. Other File Folder Context Menu Right-click on any Other folder (in the Workspace tab of the Workspace Window) to access the context menu described below:
Add Existing Other File Opens the Add Existing Other File dialog, where you can add an existing non-System type file to the System containing the selected Other folder. The new file will be added to the selected Other folder. Docking View Hide Changes the Workspace Window to a dockable window that can be resized and moved to anywhere within the NetLinx Studio work area. Hides the Workspace Window.
Other File Context Menu Right-click on any Other (non-System type) file (in the Workspace tab of the Workspace Window) to access the context file described below:
Remove File From System Click to remove the selected file from the System that it is saved in. The program prompts you to confirm this action before the file is removed from the System. The file is not deleted from disk. File Properties Opens the File Properties dialog, where you can view (and edit) properties for the selected file.
Search Operations
Using The Edit And Search Functions The Edit and Search functions are accessible via the Edit menu: The Edit > Cut, Copy and Paste options work the same in NetLinx Studio as they do in any other Windows program. The Edit > Find, Find Next and Replace options allow you to perform search and replace operations. You can search and search/replace within the active Source Code file, or search across multiple files. Searching Within the Active Source Code File Use the Find and Find Next options in the Edit menu to search within the active Source Code file: 1. Choose Edit > Find (or click the "Find" toolbar button) to open the Find dialog. 2. Enter a search string in the Find What text box.
71
3. Click one or more of the checkboxes to set any additional search criteria, as desired.
Match whole word only Searches for instances of the search string that exist as whole words only. For example, a search for "yell", only finds the word "yell", as opposed to any instance of the search string (i.e. "yellow"). Searches only for instances that match the case (UPPERCASE or lowercase) of the characters in the search string. Start the search at the cursor's position, and automatically loop the cursor to either the top or bottom of the file (depending on the Direction setting) to finish searching the entire file, to the cursor's position. Start the search at the top of the file (regardless of the cursor's position). Click the radio buttons to specify whether to search Up (backward) or Down (forward) relative to the cursor's current position in the file (default = Down).
4. Click the Direction radio buttons to specify the direction of the search (Up or Down). 5. Click Find Next to perform the search and close the Find dialog. The first instance of the search string is highlighted in the Source Code Editor window. 6. Choose Edit > Find Next (or click the "Find Next" toolbar button) to continue the search after the first instance of the search string is found. Search And Replace Within The Active Source Code File To perform a Search and Replace operation within the active Source code file: 1. Choose Edit > Replace to open the Replace dialog. 2. Enter a search string in the Find What box. 3. Enter the replace string in the Replace With box. 4. Click the checkboxes to set additional search options, as desired:
Match whole word only Searches for instances of the search string that exist as whole words only. For example, a search for "yell", only finds the word "yell", as opposed to any instance of the search string (i.e. "yellow"). Searches only for instances that match the case (UPPERCASE or lowercase) of the characters in the search string. Start the search at the cursor's position, and automatically loop the cursor to either the top or bottom of the file (depending on the Direction setting) to finish searching the entire file, to the cursor's position. Start the search at the top of the file (regardless of the cursor's position). Click the radio buttons to specify whether to search Up (backward) or Down (forward) relative to the cursor's current position in the file (default = Down).
5. Click Find Next to perform the search. The first instance of the search string is highlighted in the Source Code Editor window. 6. Click Replace to replace the highlighted instance of the search string with the replace string, or click Replace All to replace all instances of the search string.
72
The total number of replaced instances is indicated in the Status bar (on the left-hand side).
Searching Across Multiple Files To perform a Search operation across multiple files: 1. Choose Tools > Find In Files (or click the toolbar button) to open the Find In Files dialog. 2. Enter a search string (up to 255 characters) in the Find What text box.
If you select text in a Source Code Editor window before opening the Find In Files dialog, the selection appears in the Find What text box.
3. Click the In files/file types down arrow to open a list of file types to search. This selection limits the search to a specific file type. To search all files, select the *.* option from this list. You can also manually enter any three-character file extension to search for a specific type of file. 4. Specify a folder to search in the In Folder text box: a. Click the down arrow to open a list of recently searched folders. b. Click the browse button to open the Browse For Folder dialog. Use this dialog to navigate to the desired folder and click OK to return to the Find In Files dialog. 5. Select the checkboxes to enable other search options, as desired (Match whole word only, Match case, Regular Expression, Look in subfolders, and Include Hidden and System Files). 6. Click Find to perform the search. The first instance of the search string is highlighted in the Find In Files tab of the Output Display window.
To cancel a Find in Files search, click Stop Find In Files (in the Tools menu).
7. The results of the Find In Files operation are displayed in the Find In Files tab of the Output Display window, along with the total number of instances of the search string that were found in the specified directory. 8. Double-click on any file listed in the Find In Files tab to open it in a Source Code Editor window, with the cursor positioned at the beginning of the line containing the search string. Searching For Ir Library (IRL/IRV) Files Use the Find IRL/IRV Files option in the Tools menu to search for an IR file in a specific directory, based on certain search criteria: 1. Choose Tools > Find IRL/IRV Files (or click the toolbar button) to access the Find IR Files dialog. 2. Fill in the search criteria fields:
Manufacturer Enter the name manufacturer of the IR device associated with the file you are searching for.
73
Hand Control Model # Enter the model number for the hand-held IR remote associated with the file you are searching for. Device Model # Where To Search Enter the manufacturer's model number for the IR device associated with the file you are searching for. Use the radio buttons to select one of three ways to specify where to search for IR files: IR Files in Folder - Use this option to specify a target directory to search. Click the Browse button to select the directory to search in the Browse For Folder dialog. The first time you search within any given directory, NetLinx Studio generates an index file of all IR files in that directory. The status of this operation is indicated in the Status dialog. This only happens the first time a directory is searched. AMX IRN Database - Use this option to search the AMX IRN Database. User's IRN Database - Use this option to search for IR files within an existing User IR Database (*.IRN) file. IRN files are generated in the IREdit utility program.
Once you have entered one or more items in the search criteria fields, you can use the down arrows to the right of these fields to open and select from a list of previously entered items. For example, once you have typed "Sony" in the Manufacturer field, the next time you need to search for Sony devices, just select "Sony" from the dropdown list.
3. Click OK to begin the search, based on the specified criteria. 4. The results of the Find IRL/IRV search operation are listed in the Find IRL Files tab of the Output Display Window. The information in this tab includes the search criteria entered in the Find IR Files dialog. Double-click any item in the Find IR Files tab to open the selected IR file in the IREdit application. Right-click in the Find IR Files tab to open the Output Display window context menu.
Printing Files
You can print the active file in the Source Code Editor using the Print option in the File menu. 1. Choose File > Print Preview to open the Print Preview window, to preview the file, as it will be printed (if necessary). 2. Choose File > Print Setup to open the Print Setup dialog, to choose and configure your printer (if necessary). 3. Choose File > Print (or click the toolbar button) to print the file. Print Preview Window This option displays a preview of the file or code block in a separate window, as it will appear when printed. If a block of text (in a Source Code Editor window) is selected, the highlighted block of text will appear in the Print Preview window. Otherwise, the active file will appear for preview.
74
One Page/Two Page Toggles the page view to one or two pages. This option is enabled only if the active file is longer than one page. Zoom In Zoom Out Close Zooms in on the page view Zooms out from the page view Closes the Print Preview window
If you don't have a printer installed on your PC, the Print and Print Preview options invoke a message alerting you to install a printer.
Print Dialog Select Print from the File menu (or click the toolbar button) to access the Print dialog. Use the options in this dialog to set preferences for your printer, and send the file in the currently active Source code Editor window to a specified printer.
Name Properties Click the down arrow to display a list of available printers. Select the target printer from this list. Click to open the Printer Setup dialog to set options specific to the selected printer. All - Click to print the entire file Pages - Click to enable the from: and to: fields where you can specify the pages that you want to print. Selection - Click to print only the currently selected (highlighted) text in the file. This option is only available if a block of text is selected in the active Source Code Editor window. Copies - Click the up and down arrow buttons to specify the number of copies to print.
Print Range Use the radio buttons to specify the range of the active file to be printed:
75
76
Programming
Programming
Overview
Use Source Code Editor windows (FIG. 11) to display, view and edit Axcess and NetLinx source code files. You can have multiple files open at any time. Each code file is opened in a separate Source Code Editor window.
Refer to the Source Code Editor Window - Features section on page 15 for a list of supported features.
Source Code Editor Context Menu Right-click inside any Source Code Editor window to open the Source Code Editor context menu. The options in this menu include:
Build Active System Compiles all Source Code files (and any associated Include and Module files) in the active System. Compile <active Source Code File> Compile as NetLinx Compile as Axcess Compiles the active file, using the compile type associated with the file (the compile type can be changed via the File Properties dialog). Click to compile the active file using the NetLinx compiler, regardless of it's Compile As property. Click to compile the active file using the Axcess compiler, regardless of it's Compile As property.
77
Programming
Undo and Redo the last text editing action. Cut the selected text to the clipboard, Copy the selected text to the clipboard, and Paste the contents of the clipboard to the active file, at the cursor position. Deletes the selected (highlighted) text in the active Source Code Editor window. Selects all of the code in the active file. Click to open the Goto Section sub-menu, which contains a listing of code sections in a Source Code File. Select a section from this list to jump to the beginning of that section in the active file. If a section that does not exist within the active code file is chosen, nothing happens. Opens the Goto Line dialog, where you can specify the line of code to which you want to move the cursor in the active file. If a line number is entered that is beyond the max number of lines in the file, the cursor is moved to the last line in the file. Inserts a bookmark at the line containing the cursor in the active file. Bookmarks are indicated by a blue box in the left margin of the Source Code Editor window. You can have as many bookmarks as number of lines in the source code. Places a breakpoint in the active file, at the cursor position (NetLinx files only). Once a breakpoint has been inserted in the file, place the cursor in the line with the breakpoint and select Toggle Breakpoint again to remove the breakpoint. Removes all NetLinx breakpoints. Select to open the Enter Text... dialog, which allows you to insert unicode characters in your code, at the cursor position in the editor.
Goto Line
Bookmark
Toggle Breakpoint
78
Programming
Creating Events With the Code Wizard 1. In the first Code Wizard dialog, select the appropriate radio button for the type of event you want to create (BUTTON_EVENTs, CHANNEL_EVENTs, LEVEL_EVENTs or DATA_EVENTs). 2. Click Next to proceed to the next Wizard dialog. The options in the Wizard dialogs are different for each event type. The Next button is enabled in each dialog as the required information is supplied. 3. Specify the Device for which you want to create this event, and enter a comment to include in the generated code (optional). 4. Click Finish to exit the Code Wizard. The new event is placed in the active Source Code file, in the DEFINE_EVENT section. The Code Wizard also automatically updates the DEFINE_PROGRAM section, and any other parts of the source code that are affected by the addition of the new code segment. Creating Send_Commands With the Code Wizard 1. In the first Code Wizard dialog, select the I want to generate a SEND_COMMAND radio button. 2. Click Next to proceed to the next Wizard dialog, where you can specify the type of SEND_COMMAND to create (select either to Make a New Page (PAGE) or to Make a New Popup Page (@PPN)), and specify the name of the new page or popup page. This dialog also contains the option to change the text on a specified button on a touch panel, in which case you must specify the Variable Text Channel, and the replacement Text for that button. Click Next to proceed. 3. Specify the Device for which you want to create this event, and enter a comment to include in the generated code (optional). 4. Click Finish to exit the Wizard. The new SEND_COMMAND is placed in the active Source Code file, at the current cursor location. Generating Constants From an IR File With the Code Wizard 1. In the first Code Wizard dialog, select the I want to generate constants from an IR file radio button. 2. Click Next to proceed to the next Wizard dialog, where you can specify the IR file to generate constants from (use the Browse button to locate and select the file via the Open IR File dialog). Specify a comment to add to the generated code segment containing the IR constants (optional), and specify a prefix to be added to each IR constant generated (also optional). 3. Click Finish to exit the Wizard. The new IR constants from the specified file are placed in the active Source Code file, in the DEFINE_CONSTANT section.
79
Programming
Code Wizard - Advanced Users The Code Wizard can be toggled to show the individual dialogs (containing detailed options) for all the above functionality that can be used by advanced users. To view the advanced options in every dialog, de-select the Wizard Style checkbox (on by default). When the Wizard generates a new code segment, it is inserted in the active Source Code file, in the appropriate section of the code. Code Wizard Dialog - Button Tab Select Tools > Code Wizard to launch the NetLinx Studio Code Wizard. De-select the Use Wizard Style checkbox to access the individual tabs containing detailed options for each code type. In NetLinx, button events are always created using the BUTTON_EVENT handler in the DEFINE_EVENT section. In Axcess, PUSHes, RELEASEs and feedback assignments are generated in the DEFINE_PROGRAM section. The items in the Button tab are described below:
Push Release Hold Feedback No Arrays Generate PUSH statements Generate RELEASE Statements Generate HOLD statement. Not supported in Axcess. Generate feedback assignments. Button Range will be generated without using arrays, i.e. multiple BUTTON_EVENTs, PUSHes or RELEASEs will be generated. This is the default option is generating code for Axcess. Button ranges will be placed in a DEVCHAN array named Array Name using the Device and button range defined as From through To in the DEFINE_VARIABLE section. A single BUTTON_EVENT statement referencing Array Name will be generated. Note that when Use DEVCHAN is selected, GET_LAST() is selected and grayed out. This option is not available if generating code for Axcess. Button ranges will be placed in an INTEGER array named Array Name using the button range defined as From through To in the DEFINE_VARIABLE section. A single BUTTON_EVENT statement referencing Device and Array Name will be generated. This option is not available if generating code for Axcess.
Use DEVCHAN
Use INTEGER
Button Index/GET_LAST() This option will include a calculation for the button index using a mathematical calculation, BUTTON.INPUT.CHANNEL - From, for non-array button ranges and a function call to GET_LAST(), GET_LAST(Array Name), for array button ranges. The button index calculation is used if generating code for Axcess. SWITCH/CASE This option will include a SWITCH/CASE construct under the PUSH and/or RELEASE statements. The SWITCH will be based on the Button Index. Note that when SWITCH/CASE is selected, the Button Index option is selected, and grayed out. When generating Axcess code, a SELECT/ACTIVE construct will be generated instead of a SWITCH/CASE. This option will cause each button in the Array Name definition to be generated on its own line with an empty comment at the end of the line. If this option is not selected, eight channels will be generated on each line with an empty comment above the line. This option will include the REPEAT keyword in the HOLD event handler. This option is not available when generating Axcess code.
Stacked
Hold Repeat
80
Programming
Device
The device name used during code generation. This name may appear in a DEVCHAN definition, BUTTON_EVENT, PUSH, RELEASE or feedback assignment statements depending on the platform and options selected. The button range used during code generation. The range is 1 1000. You may change any of these values; the others will adjust automatically. A value of 0 (zero) in the From field will generate an "all button" handler. In this case, code generation cannot support arrays or feedback. The array name used for generating DEVCHAN or INTEGER array for button ranges. This value is used when generating the HOLD statement. This value is used on the lines before the array definition, BUTTON_EVENT, PUSH, and RELEASE and feedback statements as determined by the options. Comments in NetLinx are always linestyle comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.
Insert
Code Wizard Dialog - Channel Tab The items in the Channel tab are described below:
On Off No Arrays Use DEVCHAN Generate ON statements Generate OFF Statements Channel ranges will be generated without using arrays, i.e. multiple CHANNEL_EVENTs will be generated. Channel ranges will be placed in a DEVCHAN array named Array Name using the Device and channel range defined as From through To in the DEFINE_VARIABLE section. A single CHANNEL_EVENT statement referencing Array Name will be generated. Note that when Use DEVCHAN is selected, GET_LAST() is selected and grayed out. This option is not available if generating code for Axcess. Channel ranges will be placed in an INTEGER array named Array Name using the channel range defined as From through To in the DEFINE_VARIABLE section. A single CHANNEL_EVENT statement referencing Device and Array Name will be generated.
Use INTEGER
Channel Index/GET_LAST() This option will include a calculation for the channel index using a mathematical calculation, CHANNEL.CHANNEL - From, for nonarray channel ranges and a function call to GET_LAST(), GET_LAST(Array Name), for array channel ranges. The channel index calculation is used if generating code for Axcess. SWITCH/CASE This option will include a SWITCH/CASE construct under the ON and/or OFF statements. The SWITCH will be based on the Channel Index. Note that when SWITCH/CASE is selected, the Channel Index option is selected, and grayed out. This option will cause each channel in the Array Name definition to be generated on its own line with an empty comment at the end of the line. If this option is not selected, eight channels will be generated on each line with an empty comment above the line. The device name used during code generation. This name may appear in a DEVCHAN definition or CHANNEL_EVENT statement depending on the platform and options selected.
Stacked
Device
81
Programming
The channel range used during code generation. The range is 1 1000. You may change any of these values; the others will adjust automatically. A value of 0 (zero) in the From field will generate an "all channel" handler. In this case, code generation cannot support arrays. The array name used for generating DEVCHAN or INTEGER array for channel ranges. This value is used on the lines before the array definition, CHANNEL_EVENT statements as determined by the options. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.
Insert
Code Wizard Dialog - Level Tab The advanced options available for Level_Events (in the Level tab of the Code Wizard dialog) are described below:
Event Create Send Generate LEVEL_EVENT statements. Generate CREATE_LEVEL statements. Generate SEND_LEVEL statements. Note: You cannot generate EVENT_LEVEL statements and CREATE_LEVEL or SEND_LEVEL statements at the same time. No Arrays Use DEVLEV Level ranges will be generated without using array, i.e. multiple LEVEL_EVENTs will be generated. Level ranges will be placed in a DEVLEV array named Array Name using the Device and button range defined as From through To in the DEFINE_VARIABLE section. A single LEVEL_EVENT statement referencing Array Name will be generated. If CREATE_LEVEL and/or SEND_LEVEL statements will be generated, each construct will reference this array for the level number for NetLinx only. Note that when Use DEVCHAN is selected, GET_LAST() is selected and grayed out. This option is not available if generating code for Axcess. Level ranges will be placed in an INTEGER array named Array Name using the button range defined as From through To in the DEFINE_VARIABLE section. A single LEVEL_EVENT statement referencing Device and Array Name will be generated. If CREATE_LEVEL and/or SEND_LEVEL statements will be generated, each construct will reference this array for the level number for NetLinx only.
Use INTEGER
Level Index/GET_LAST() This option will include a calculation for the level index using a mathematical calculation, LEVEL.INPUT.LEVEL- From, for non-array level ranges and a function call to GET_LAST(), GET_LAST(Array Name), for array level ranges. The option is only used for LEVEL_EVENTs. SWITCH/CASE This option will include a SWITCH/CASE construct under the LEVEL_EVENT statement. The SWITCH will be based on the Level Index. Note that when SWITCH/CASE is selected, the Level Index option is selected, and grayed out. This option will cause each level in the Array Name definition to be generated on it's own line with an empty comment at the end of the line. If this option is not selected, eight levels will be generated on each line with an empty comment above the line The device name used during code generation. This name may appear in a DEVLEV definition, LEVEL_EVENT, CREATE_LEVEL or SEND_LEVEL statements depending on the platform and options selected.
Stacked
Device
82
Programming
The level range used during code generation. The range is 1 - 1000. You may change any of these values; the others will adjust automatically. A value of 0 (zero) in the From field will generate an "all level" LEVEL_EVENT handler. In this case, code generation cannot support arrays. Note: The range setting (1-1000) affects the load placed on the CPU at compile time. Higher range settings may result in slower compile operations.
The array name used for generating DEVLEV or INTEGER array for level ranges. The array name or value used for generating CREATE_LEVEL or SEND_LEVEL statements. If generating code for a level range on NetLinx, this variable will be created as an array. If generating code for a level range on Axcess, this variable will be created as a series or variable starting with this name, i.e. Variable Name 1, Variable Name 2, etc This value is used on the lines before the array definition, LEVEL_EVENT, CREATE_LEVEL, and SEND_LEVEL statements as determined by the options. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.
Comment
Insert
Code Wizard Dialog - Data Tab The advanced options available for Data_Events (in the Data tab of the Code Wizard dialog) are described below:
Online Offline OnError String Command Create Buffer Generate ONLINE statements. In Axcess, a construct for detecting device online status is generated. Generate OFFLINE statements. In Axcess, a construct for detecting device offline status is generated. Generate ONERROR Statements (not supported in Axcess). Generate STRING statements (not supported in Axcess). Generate COMMAND Statements (not supported in Axcess). Define a buffer and connect it to a device using CREATE_BUFFER, in the DEFINE_START section.
Process Buffer Generate a construct for detecting incoming strings. If generating code for NetLinx, this code is placed in the STRING section of the DATA_EVENT. If generating code for Axcess, this code is placed in the DEFINE_PROGRAM section. Device The device name used during code generation. This name may appear in a variable declaration, ONLINE/OFFLINE construct, DATA_EVENT or CREATE_BUFFER statements depending on the platform and options selected. This value is used on the lines before the variable declaration, ONLINE/ OFFLINE construct, DATA_EVENT or CREATE_BUFFER statements as determined by the options. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.
Comment
Insert
83
Programming
Code Wizard Dialog - Send Command Tab The advanced options available for Send_Commands (in the Send Command tab of the Code Wizard dialog) are described below:
Page @T @BMF @PPN @PPF @PPK @PPX Custom Device Generate PAGE- page flip send command for touch panels. Generate @T variable text send command for touch panels. Generate @BMF variable text send command for touch panels. Generate @PPN- popup on send command for touch panels. Generate @PPF- popup off send command for touch panels. Generate @PPK- popup kill send command for touch panels. Generate @PPX- kill all popups send command for touch panels. Generate a custom send command. The device name used during code generation. This name will appear in the SEND_COMMAND statement.
Sub Command The command parameter used in the SEND_COMMAND. Depending on options, this may be the Page Name, Text to Send, @BMF sub-command, popup page name or custom command. Comment Insert This value is used on the line before the SEND_COMMAND statement. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.
Code Wizard Dialog - IR Constant Tab Constants are generated from IR files. One constant is generated for every IR function and are placed in the DEFINE_CONSTANT section. The advanced options available for IR Constants (in the IR Constant tab of the Code Wizard dialog) are described below:
Device IR File The device name used during code generation. This name is used to generate the Constant Prefix field. The IR file for which you would like to generate constants.
Constant Prefix The prefix to precede all constant declaration. By default, this will be <Device>_. Comment Insert This value is used on the line before the constant declarations. Comments in NetLinx are always line-style comments (i.e. //). Once you have made the relevant selections on this tab, click this command button to insert the specified code into the file.
84
Programming
Syntax Highlighting When a source file is loaded in the editor, it is read line by line. Each line is broken up into its constituent words. Technically the line is broken into tokens, but the concept of a word is more familiar to most people. Different words and groups of words are handled differently. Here is a breakdown of the mechanism used:
Comments Any portion of the line that initiates or falls within a comment is considered to be one comment (essentially it's treated as one big word). The comment is then syntax highlighted using the color specified in Preferences > Editor > Comment. When NetLinx Studio is started it loads two files: NetLinx.rw and Axcess.rw. These are the "reserved word" files. These files contain all of the words that NetLinx Studio will consider to be "Language Reserved Words". Language Reserved Words are syntax highlighted using the color specified in Preferences > Editor > Language Reserved Word. If a partial word that is typed is recognized as a reserved word, the editor will suggest its closest match. Operator All of the following operators
String
Default Syntax Highlighting Colors The text in the Source Code Editor windows is syntax highlighted with color codes for increased readability with a default set of colors that can be customized via the options in the Editor tab of the Preferences dialog. Syntax Highlighting assigns different colors to different types of data in your Source Code file.
85
Programming
Use chroma-coding to make your code easier to read and manage. For example, you could chromacode all comments to yellow, all identifiers to red and strings to blue to make them more easily identifiable in your code file. The text elements that can be chroma-coded, and their default color assignments are listed below:
Comments Default Text Floating Point Number green red dark green
Language Reserved Word blue Number Operator teal red Note: All of the following color as operators: =, <, >, +, -, *, /, %, <=, >=, <>, AND, OR, XOR, NOT, BAND, BOR, BXOR, BNOT, &&, ||, ^^, !, &, |, ^, ~ String maroon
AutoComplete and AutoSuggest You may enable or disable this feature by toggling the Enable AutoComplete/AutoSuggest checkbox in the Editor tab of the Preferences dialog. With this option enabled, the Editor can automatically complete typing many common and standard programming terms for you. When you begin typing in the editor, a drop-down list of probable matches for the term you started typing is displayed. Auto-Suggest will suggest a single word if that word matches something that has already been typed. Auto-Suggest will drop the rest of the word that has been typed (to the right of the cursor) when a suggestion is selected. Use the scroll bar to scroll through the list (if necessary) and click to select the desired term or phrase that you want to insert at the cursor's position. Double-click or press the Tab key (or Enter on your keyboard) to insert the selection. In the example below (FIG. 12), the user has typed the character "D", and is selecting to insert the phrase "DEFINE_EVENT" into the code. The selection always replaces the character(s) typed before the AutoComplete/AutoSuggest drop-down was invoked.
Note that AutoComplete/AutoSuggest is case-sensitive. Typically section headings are capitalized, and commands are not. Use the Edit > Rescan Current Source File option to rescan the active file, in order to rebuild the symbol information utilized by the AutoComplete/AutoSuggest feature.
86
Programming
With AutoComplete/AutoSuggest enabled, as you type in a variable name, device name or a reserved identifier, the program will suggest a name that has been previously defined within the source code. When the editor makes a suggestion, you may choose to accept the suggestion by hitting the TAB key (or a different keystroke as defined in the Keyboard tab of the Preferences dialog). However, if the suggestion is not what you intended, you may choose to have the editor display it's next suggestion. You can cycle through all of the suggestions by using the keystroke defined in the Keyboard tab of the Preferences dialog (the Next Suggestion item in the Advanced Editor category). There is no default keystroke assignment for Next Suggestion (to avoid conflicting with pre-existing custom keystrokes). You must set your own keystroke to take effect. Use the Edit > Rescan Current Source File option to rescan the active file to rebuild the symbol information used by the AutoComplete and AutoSuggest features. Stack Variables/Parameters only auto-suggest when they are within the scope of the CALL, FUNCTION or EVENT that they were declared in. Call Tips Call tips are similar to the AutoComplete and AutoSuggest functions, except that Call Tips assist you with adding declared functions by displaying a list of parameters that are valid for the particular function you are adding. Call Tips are shown for declared functions when: A function name is followed by an open parenthesis. A single-quoted call name is followed by an open parenthesis. A single-quoted system call name is followed by an open parenthesis. The application displays a list of calls when the word "CALL" is followed by a single quote. It displays a list of System Calls when the word "SYSTEM_CALL" is followed by a single quote as shown in FIG. 13:
The list of calls is in alphabetical order (with the very first item highlighted by default) - type the first letter of the desired call to jump to that point in the list. Use the scroll bar to scroll through the list of calls and click to select the item that you want to insert at the cursor's position. Double-click, or press the Tab key (or Enter on your keyboard) to insert the selection. In the example below, the user entered SYSTEM_CALL, then selected 'LDP1F', and added a space and an open single-quote to receive the following Call Tip:
87
Programming
The Call Tip displays a list of parameters that are valid for the particular function you are adding (separated by commas), with the current parameter being entered in bold (DEV DECK in the example above).
You may enable or disable this feature by toggling the Enable Call Tips checkbox in the Editor tab of the Preferences dialog.
Code Folding Fold levels can be used to simplify the view in the Source Code Editor windows by allowing you to "fold" each major section of the code (DEFINE_DEVICE, DEFINE_CONSTANT, DEFINE_TYPE, etc.) so that only the header row is visible. This way, you only see the section(s) that you are actually working in. Fold levels can be collapsed and expanded, in much the same way as the tree structures that occur in the Workspace window. Fold levels that are collapsed are indicated by a blue plus sign (+) to the left of the line containing that section's header row. Fold levels that are expanded are indicated by a red minus sign (-) to the left of the line containing that section's header row. In FIG. 15, all fold levels are collapsed except DEFINE_CONSTANT (in this example there are no data type definitions).
In order to use fold levels, you must first enable the option in the Editor tab of the Preferences dialog (by default, this option is disabled). Once the Enable Code Folding option is enabled, use the Expand All Fold Levels and Collapse All Fold Levels options (via either the Edit menu or the Edit toolbar) to control the fold levels (FIG. 16):
Expand All Fold Levels -Select this option to automatically expand all fold levels in the active file. Collapse All Fold Levels - Select this option to automatically collapse all fold levels in the active file. FIG. 16 Code Folding options
88
Programming
If the Enable Code Folding option has not been enabled, these two options are unavailable. Also note that the application will remember your last code folding settings when the file is closed, so they will still be in place the next you open the file (v2.4 or later). Unicode Characters To insert unicode characters into the active Source Code file, at the cursor's position: 1. Select Unicode Edit from the Edit Menu or the Source Code Editor Context Menu to access the Enter Text... dialog. 2. Type one or more characters in the upper text field to display the characters' unicode send command value in the lower (read-only) window. 3. Press OK to insert the unicode send command value in the code, at the cursor's position. UTF-8 Encoding In the Save As dialog, select UTF-8 from the Encoding menu to enable UTF-8 support for new files, to help NetLinx Studio files to work better with other editors. You can also select the Enable UTF-8 Encoding option in the Editor tab of the Preferences dialog.
You may also encode files created with a previous version of NetLinx Studio by choosing "Save-As" and selecting the UTF-8 encoding.
Insert Section The Insert Section option allows you to insert a particular section heading in your code, at the cursor's position. This option is available via the Edit menu, the Source Code Editor context menu, or the Edit toolbar.
This command only works on the open Source Code Editor window.
1. Select Edit > Insert Section to access the Insert Section sub-menu. 2. Position the cursor at the beginning of the line that you want to add the section heading to. 3. Select the section heading that you want to add from the sub-menu. The available options are:
NetLinx: DEFINE_DEVICE DEFINE_CONSTANT DEFINE_TYPE DEFINE_VARIABLE DEFINE_LATCHING DEFINE_TOGGLING DEFINE_VARIABLE DEFINE_LATCHING DEFINE_TOGGLING Axcess: DEFINE_DEVICE DEFINE_CONSTANT
89
Programming
4. The section heading is added at the cursor's position. Goto Section The Goto Section option allows you to jump to a particular section in your code. This option is available via the Edit Menu, the Source Code Editor context menu or the Edit toolbar. 1. Select Edit > Goto Section to access the Goto Section sub-menu. 2. Select the section that you want to jump to from the sub-menu.
The Insert Section and Goto Section sub-menus may include sections that are not defined in the Source Code file being edited. The valid commands for the System type will be available whether they are actually in the file or not.
3. The cursor jumps to the top of the selected section in the open Source Code Editor window. Goto Line Select Goto Line from the Edit menu, the Source Code Editor context menu (or click the toolbar button) to jump to a particular line number in your code.
To display line numbers in the Source Code Editor windows, select the Show Line Numbers option in the Editor Options tab of the Preferences dialog.
1. Right-click inside a Source Code Editor window to access the Source Code Editor context menu, and select Goto Line to access the Goto Line dialog. 2. Enter the line number in the Enter Line Number field and click OK to jump to the specified line number in the open Source Code Editor window. Goto Function Or Subroutine The Goto Function or Subroutine toolbar command allows you to jump to a particular section in your code, in the active Source Code Editor window. 1. Click the Goto Function or Subroutine toolbar button to access a list of functions contained within the active Source Code file. 2. Select the function or subroutine that you want to jump to from the list. 3. The cursor jumps to the top of the selected section in the Source Code Editor window. Block Comment - Uncomment Select Edit > Block Comment - Uncomment (or click the toolbar button) to toggle one or more selected lines of code to and from being a comment (by inserting two forward slashes at the beginning of the line containing the cursor).
Since the Block Comment-Uncomment command is a toggle function, in order to "uncomment" a block the first character set must be a double forward slash (//). Without the double forward slash, the selected block will be commented (rather than "uncommented).
90
Programming
Case Inversion Use the case inversion tools in the Edit menu (or the Edit toolbar) to quickly switch selected characters in the Source Code Editor window: Make Selection Uppercase - Changes all selected characters in the file to uppercase. Make Selection Lowercase - Changes all selected characters in the file to lowercase. Invert Case - With text selected in the Source Code Editor window, click this option to invert the case of the selected text. All uppercase characters become lowercase, and viceversa. Clipboard Text Buffer Select Edit > Clipboard Buffers (or click the toolbar button) to access a listing of the contents of the clipboard text buffer. Use this feature to reuse multiple text blocks that have been copied in the Source Code Editors. To retrieve text from the Clipboard Buffer and insert it into the active code file: 1. Copy (or cut) a selection from a code file (in a Source Code Editor window). 2. Position the cursor in the file at the point that you want to insert the copied text.
You can copy and paste across files, so you don't have to paste it into the same file it was copied from.
3. Select Edit >Clipboard Buffers (or click the toolbar button). This displays a list of all items currently stored in clipboard memory. Any text that has been cut or copied to clipboard memory is shown in the list, starting with the most recent entry. 4. Click on the item in the list that you want to insert into the active code file. The selected clipboard item is inserted into the active file at the cursor's position. Using The Clipboard Text Buffer The Clipboard Text Buffer allows you to copy multiple selections from the Source to clipboard memory as separate items that you can selectively paste from the clipboard. You can have up to 30 clip-board buffer items. The maximum display width is 80 characters. Clipboard items are not saved when the application terminates. To use the Clipboard Text Buffer: 1. Highlight a selection of code in a Source Code Editor window. 2. Press Ctrl+C to copy the selection to the clipboard. 3. Highlight another selection of code in a Source Code Editor window. 4. Press Ctrl+C to copy this selection to the clipboard as well. 5. Place the cursor in the location that you want to paste one of the copied items (in a Source Code Editor window).
91
Programming
6. Click the Clipboard Text Buffer toolbar button to access a list of items in the Clipboard Text Buffer. 7. Click an item in the list to paste it into the active Source Code Editor window, at the cursor location. Find Matching Brace Select Edit > Find Matching Brace (or click the toolbar button) to quickly locate the second (matching) brace in a set. With the cursor on one brace in a Source Code Editor window, click Find Matching Brace to move the cursor to the other (matching) brace in the set. Sequentially Renumber Selection Click Edit > Sequentially Renumber Selection (or click the toolbar) to re-arrange the selected text in the Source Code Editor window to make all numbers in the code (i.e. device numbers, channel numbers, etc) fall into ascending sequential order. Show Whitespace Select Edit > Show Whitespaces (or click the toolbar button) to place dots in the Source Code Editor window to indicate "whitespaces" (spaces and tabs) in the code. By default, this option is disabled. Show End Of Line Select Edit >Show End Of Line (or click the toolbar button) to toggle the display of the end of each line of code (indicated by "CRLF") as black text on a red background, as opposed to the default view which indicates the end of each line with a red bar. By default, this option is disabled. Rescan Current Source File Select Edit > Rescan Current Source File (or click the toolbar button) to rescan the active Source Code (*.AXS) file, in order to rebuild the symbol information utilized by the Auto-Complete/AutoSuggest feature. Advanced Editor Commands The following commands/keyboard movements are supported by the Source Code Editor:
Action Select None Delete Selection Delete All Select Word Select Word Left Description removes any selection. deletes whatever is selected. Equivalent to hitting the delete key when you have a selection. deletes everything. Clears the document. selects the nearest word to the cursor. selects from the cursor to the start of the word.
Select Word Right selects from the cursor to the end of the word Select Line Select Line Left Select Line Right selects the current line at the cursor selects from the cursor to the beginning of the line selects from the cursor to the end of the line
92
Programming
deletes the current word at the cursor deletes from the cursor to the start of the word
Delete Word Right deletes from the cursor to the end of the word Delete Line Delete Line Left Delete Line Right deletes the current line at the cursor deletes from the cursor to the beginning of the line deletes from the cursor to the end of the line
None of these commands have default keyboard hotkeys assigned. To assign hotkeys, use the Keyboard tab of the Preferences dialog (select Advanced Editor from the Category drop-down list).
Supported Regular Expression Special Characters The following regular expression special characters are supported for Regular Expression search operations:
Special Character Description
. \( \) \n
Matches on any character. This marks the start of a region for tagging a match. This marks the end of a tagged region. Where n is 1 through 9 refers to the first through ninth tagged region when replacing. For example: if the search string was Fred\([1-9]\)XXX and the replace string was Sam\1YYY, when applied to Fred2XXX this would generate Sam2YYY. This matches the start of a word. This matches the end of a word. This allows you to use a character x that would otherwise have a special meaning. For example: \[ would be interpreted as [ and not as the start of a character set. This indicates a set of characters. For example: [abc] means any of the characters a, b or c. You can also use ranges. For example: [a-z] for any lower case character. The complement of the characters in the set. For example: [^A-Za-z] means any character except an alphabetic character. This matches the start of a line (unless used inside a set, see above). This matches the end of a line. This matches 0 or more times. For example: Sa*m matches Sm, Sam, Saam, Saaam and so on. This matches 1 or more times. For example: Sa+m matches Sam, Saam, Saaam and so on.
Cut, Copy And Paste NetLinx Studio supports Cut, Copy and Paste functionality in the Source Code Editor: Select Edit > Cut (or click the toolbar button) to cut the selected text to the clipboard. Select Edit > Copy (or click the toolbar button) to copy the selected text to the clipboard. Select Edit > Paste (or click the toolbar button) to Paste the contents of the clipboard to the active file, at the cursor position.
93
Programming
Undo/redo NetLinx Studio supports Undo and Redo functionality in the Source Code Editor: Click Edit > Undo (or click the toolbar button) to undo the last action. Click Edit > Redo (or click the toolbar button) to redo (repeat) the last action.
Debugging
Debugging Source Code Files NetLinx Studio contains several useful options for debugging your Master Controller and Source Code files.
The Debugging feature allows you to view variables declared within the scope of a Function and or Call procedure. However, stack and parameter values are not editable. If you attempt to edit either the stack or parameter values, a warning message is displayed.
In order to begin debugging, your computer must be connected to a Master Controller, and you must have a compiled Source Code file active. To use debugging, the Build With Source option must be selected in the Axcess Compiler and/or NetLinx Compiler tabs of the Preferences dialog, before the file is compiled. For NetLinx code, select You cannot compile, send/receive files, or change port settings while the program is in debug mode. Avoid declaring variables as volatile whenever possible, since volatile variables will not display their contents during the debug session. NetLinx character strings by default are displayed in current length mode, while all other strings (including Integer strings) are displayed in total length mode.
94
Programming
To enter debug mode: 1. Open and compile a Source Code file (that contains at least one variable), if you have not already done so. The file must be successfully compiled before you can enter debug mode. 2. Choose Build > Debug (or click the toolbar button) to open the Watch window. If this option is disabled, make sure your Master Communications Port settings are set to connect to your Master Controller. 3. Right-click inside the Watch window to open the Watch Window context menu. 4. Click Add to insert a new variable in the Watch window. A box appears in the window, with a cursor blinking in the Name column. 5. Type the syntax of the variable exactly as it is defined in the code and press the Enter key. The value of the specified variable appears next to the variable (in the Value column). 6. You can select different view formats for the Value by right-clicking on the line containing the variable/value, and clicking on Display in the Watch window context menu. This opens the Display sub-menu, containing the following view options:
ASCII Display Decimal Display displays the value of the watched variable in ASCII format. displays the value of the watched variable in decimal format.
Hexadecimal Display displays the value of the watched variable in hexadecimal format. Octal Display Binary Display displays the value of the watched variable in octal format. displays the value of the watched variable in binary format.
To exit Debug mode, close the Watch window. Using Single-step Mode In Single-step mode, program execution is suspended between each pass through mainline, allowing you to test programs one line at a time. Single-step mode works differently in NetLinx than it does in Axcess: In NetLinx systems it executes a single instruction in the source file In Axcess systems it executes a single line of code in the Mainline To use Single-step mode: 1. Right-click on a watched variable and choose Debug > Single Step (or click the toolbar button) to put the Master into single-step mode. 2. With the watched variable selected, select Debug > Single Step (or click the toolbar button). This command executes mainline one time and breaks.
In NetLinx, you can use breakpoints with single-step mode. When the breakpoint is encountered (and the program is suspended), you can single-step without a watched variable reference.
95
Programming
Master Controller Debug Options The Watch window is displayed when Start Debugging is selected from the Debug menu (or the Debug Watch toolbar). The Watch window is a dockable window that allows you to view and edit the contents of variables within a compiled Axcess or NetLinx program. Also, you can control the execution through each pass of the mainline of a compiled Axcess or NetLinx program. Once Start Debugging has been selected, the other options in the Debug menu become available:
Start/Stop Debugging Ability to toggle the debug state of the application. There is no limitation on then number of NetLinx variables that can be watched in the Debug Watch windows. A maximum of 10 watch variables are allowed when debugging an Axcess master controller. Step Mode Enable/Disable Step mode causes the Interpreter to break after each execution of the mainline. Watch variables are always updated after each pass through mainline. To continue program execution while in Step mode, you must invoke the "Step" command again. Execute one line of a source code file at a time for a NetLinx master controller or execute one pass through the mainline code for an Axcess controller.
Single Step
The following options are only needed for debugging code located on a NetLinx master controller:
Run Run To Cursor Break Edit Breakpoints To continue execution after a Single Step operation or from a toggled break point. Execute the program and break on the line of code where the cursor is residing on the screen. Stop execution of the program and highlight the line of code on the screen. A dialog box appears listing all the break points within the code.
Toggle Break Point Toggle a break point on the screen where the cursor is residing. A red diamond appears next to the line of code to signify a break point. Clear Break Points Clears all the break points within the source code file.
Changing The Value Of A Watched Variable Once you have entered Debug mode, you can change the name and/or value of any watched variable, via the Value column in the Watch window: 1. Select a watched variable in the Watch window. 2. To change the variable's value, double-click on the desired variable's value to change the value to an edit field, which you can modify as desired. Debug Mode Error Messages The most common warnings that you may get when entering Debug Mode (Debug > Start Debugging) are: 1. No Debug Symbols: The source code file was not compiled with debug symbols - this can usually be ignored if you're only watching variables, but if you're getting weird behavior, recompile with "Compile with Debug Info" enabled (in the NetLinx Compiler tab of the Preference dialog). You will always need debug symbols for breakpoint debugging.
96
Programming
If you've made any changes to the source file, including a re-save, you'll get a message similar to the one above. It can often be safely ignored, but select No if you've done any significant editing. 3. Missing files
Breakpoints
Using Breakpoints (NetLinx Only) While Single Step Mode allows you to execute a single line of code in the Mainline in Axcess systems, NetLinx systems allow you to use Breakpoints to execute a single instruction in the source file. You can set a breakpoint on any line of code (other than a comment) that is within the DEFINE_PROGRAM section. The following is an example of a SEND_LEVEL breakpoint:
PUSH[dvLocalTP3,1] PUSH[dvLocalTP3,2] { fTestLevel=fTestLevel + 1; SEND_LEVEL dvLocalTP3,1,fTestLevel; }
Note that semicolons are used in the example to terminate each line in a breakpoint. The only time that the semicolon is absolutely necessary is when a breakpoint is set at the last line of code. To keep things simple, consider terminating each breakpoint with a semicolon. Setting A Breakpoint 1. Place the cursor on a line of code in the DEFINE_PROGRAM section (other than a comment). 2. To insert the breakpoint at the cursor position, right-click to open the Source Code Editor context menu, and select Toggle Breakpoint, or use the Toggle Breakpoint toolbar button. 3. A red arrow appears in the Source Code Editor window, to the left of the cursor position. A green bar highlighting the line of code, and the execution arrow (a little green arrow) indicate the current execution point.
97
Programming
To execute the next line of code, right-click and choose Step Into. You'll see the execution pointer advance one line. If you no longer need to single step, right-click and choose Run.
If you are not currently debugging, you won't see execution break until you start debugging (Debug > Start Debugging).
Clearing Breakpoints You clear an individual breakpoint, or clear all breakpoints in a file: To clear an individual breakpoint - Place the cursor on a line of code containing a set breakpoint, and choose Debug > Toggle Breakpoint, or use the Toggle Breakpoint toolbar button to unset the breakpoint on that line. To clear all breakpoints in a file - Choose Debug > Clear All Breakpoints, or use the Clear All Breakpoints toolbar button. Editing Breakpoints Select Debug > Edit Breakpoints (or click the toolbar button) to access the Breakpoints dialog. Use the options in this dialog to toggle any breakpoints set in the active (NetLinx) Source Code file.
PUSH Messages
Select Diagnostics > Enable Push Message Status Bar Display (or click the toolbar button) to display Push message status (Enabled/Disabled):
By default, Push Messages are disabled, as indicated in the Status Bar. Push Messages are enabled via the Diagnostics menu or the Diagnostics toolbar. Once the Push Message Status Bar display is enabled, you can send Push messages to the Master, via the Emulate a Device dialog. The Push Message Status Bar display then shows the D:P:S and Channel information for the most recently received Push
Left- click within the Push Message Status Bar display to view a list of recently received Push messages: FIG. 19 PUSH Messages
Insert Push Message Dialog Select Insert Push Message from the Edit menu to open the Insert Push Message dialog. This dialog displays a list of recent Push messages that were sent to the Master. Click to select a Push from the list, and click OK to insert the code for that Push message at the cursor's position in the active code file.
98
Programming
Find Push Message Dialog Select Find Push Message from the Edit menu to open the Find Push Message dialog. This dialog displays a list of recent Push messages that were sent to the Master. Select a Push from the list, and click OK to locate the selected Push message code in the active file.
99
Programming
Defining a Unicode String Literal To enter Unicode characters into your program, enclose the characters in single quotes, like you would any other string, and wrap the string literal in the Unicode macro _WC. Example:
_WC('Your string goes here') 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. To define a WIDECHAR constant or variable and initialize it using a Unicode string literal, use the following syntax:
WIDECHAR wcMyString[] = _WC('My String') The "wc" prefix is Hungarian notation for widechar. This is simply a programming convention and is completely optional. Hungarian notation helps you better identify your variables while you are programming and is a general recommended standard. For more information, see Wikipedia's Hungarian Notation page.
Working With Widechar Arrays and Unicode Strings Working with WIDECHAR arrays and Unicode strings is very similar to working with CHAR arrays and ASCII strings. Most operation that can be performed on a CHAR array can be performed on a WIDECHAR array. For instance, to assign a string to a variable use this syntax:
wcMyString = _WC('My String')
The string functions defined for CHAR arrays have been defined for WIDECHAR array for use in Unicode programming. These functions allow you to operate on strings similar to the way you would with CHAR array. For instance, to remove the first 3 characters from a WIDECHAR array and return those characters as a WIDECHAR array, use WC_GET_BUFFER_STRING:
wcRemoved = WC_GET_BUFFER_STRING(wcMyString,3)
You will find that most other function work exactly as their CHAR counterpart do except they work on and return WIDECHAR arrays. The list of Unicode compatible functions is:
WC_COMPARE_STRING WC_GET_BUFFER_CHAR WC_GET_BUFFER_STRING WC_LEFT_STRING WC_FIND_STRING WC_LENGTH_STRING WC_LOWER_STRING WC_MAX_LENGTH_STRING WC_MID_STRING WC_REMOVE_STRING WC_RIGHT_STRING WC_SET_LENGTH_STRING WC_UPPER_STRING
100
Programming
Unicode - 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.
For more information on Unicode character conversion, see the Unicode.org character conversion FAQ.
Unicode - Concatenating String Unicode strings and WIDECHAR array cannot be concatenated using the same syntax that ASCII strings use. In NetLinx, string expressions are enclosed in double quotes and can only contain 8-bit strings. To concatenate Unicode strings and WIDECHAR arrays, you must use the WC_CONCAT_STRING function:
wcMyString = WC_CONCAT_STRING(_WC('First name'),_WC(' SurName'))
If you attempt to concatenate Unicode strings or WIDECHAR arrays using NetLinx string expressions, expect data loss. Unicode - Converting Between WIDECHAR and CHAR On occasion, you may need to convert a CHAR array to a WIDECHAR array or a WIDECHAR array to a CHAR array. The CH_TO_WC and WC_TO_CH functions can be used to accomplish these conversions. For example:
wcMyString = CH_TO_WC('Any ASCII string') wcMyString = CH_TO_WC(cMyString) cMyString = WC_TO_CH(_WC('Any Unicode string')) cMyString = WC_TO_CH (wcMyString)
When converting from WIDECHAR to CHAR, Unicode characters are converted to '?'. Any ASCII or extended ASCII characters, i.e. 8-bit characters, contained in the WIDECHAR array will appear in the CHAR array. Converting from CHAR to WIDECHAR never results in loss of data. Unicode - Using FORMAT The NetLinx Unicode library does not include a Unicode compatible FORMAT function. In NetLinx, the format function is used to convert numbers to text. To use FORMAT with Unicode string, use FORMAT to convert the number to a CHAR array and then use CH_TO_WC and WC_CONCAT_STRING to combine the result with an existing WIDECHAR array. The following two syntaxes are functionality equivalent:
101
Programming
fTemperature = 98.652 cMyString = FORMAT('The current temperature is %3.2f',fTemperature) -----------------------------------------------------------------------fTemperature = 98.652 cTempString = FORMAT('%3.2f',fTemperature) wcMyString = _WC('The current temperature is ') wcMyString = WC_CONCAT_STRING(wcMyString,CH_TO_WC(cTempString))
Unicode - 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. The WC_FILE_OPEN returns a special file handle so it is important to only use the file handle returned by WC_FILE_OPEN with other WC_FILE functions and the file handle used with WC_FILE functions must have been obtained by calling WC_FILE_OPEN. The NetLinx Unicode library supports three different file formats for compatibility with files created on a computer. Windows Notepad supports the same three file formats so files created in Notepad can be read using the WC_FILE routines and files created using the WC_FILE routines can be read with Notepad. When reading or appending to file, the file format is automatically determined when the file is opened. You can pass in a variable to WC_FILE_OPEN and the function will set the variable to the file format that was detected. When writing files, the file format parameter will determine how data is written to the file. The following constants can be used for specifying or checking the file format: WC_FORMAT_UNICODE, WC_FORMAT_UNICODE_BE, WC_FORMAT_UTF8. The Unicode file format, specified by the constant WC_FORMAT_UNICODE, is the fastest to encode and decode. You should use this format unless you have a particular application that requires either UTF-8 or Unicode BE encoding. The WC_FILE_READ/WRITE functions take the number of characters that will be read or written to the file. However, the functions return the number of bytes read or written to the file, not the number of characters. For Unicode and Unicode BE encoding, there are 2 bytes for every character. For UTF-8 encoding, the number of bytes for every character varies depending on the character. Unicode filenames are not supported. The parameter for the file name is a CHAR array. Always use a non-Unicode name for the file. The following file functions support WIDECHAR arrays:
WC_FILE_OPEN WC_FILE_CLOSE WC_FILE_READ WC_FILE_READ_LINE WC_FILE_WRITE WC_FILE_WRITE_LINE
Unicode - Send Strings To A User Interface Sending a WIDECHAR array to a user interface is accomplished using WC_TP_ENCODE. WC_TP_ENCODE takes a WIDECHAR array and returns a CHAR array formatted for a user interface UNI or BAU command.
cMyString = WC_TP_ENCODE(wcMyString) SEND_COMMAND dvTP,"'^UNI-1,0,',cMyString "
102
Programming
Right-to-Left Unicode Strings Right-to-Left Unicode languages are stored in memory the same way left-to-right language are. The first memory position of an array contains the first logical character. You can access the rightmost character of a Right-to-Left Unicode string using this notation:
wchChar = wcString[1]
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. WC_LEFT_STRING returns the number of characters request from the front of the string and WC_RIGHT_STRING return the number of characters requested from the end of the string, regardless of the language's orientation. Unicode - Compiler Errors The most common type of compiler errors you will encounter while programming for Unicode are caused by not wrapping Unicode string literals in _WC, passing a WIDECHAR to a function that take a CHAR array or passing a CHAR array to a function that takes a WIDECHAR array. If you forget to wrap a Unicode string in _WC, expect to see the following compiler error: On the line where the string is defined:
C10571: Converting type [string] to [WIDECHAR]
If you try to pass a CHAR array to a function that expects a WIDECHAR array, expect to see the following compiler error: On the line where the function call is made:
C10585: Dimension mismatch: [1] vs. [0] and Type mismatch in call for parameter [WCDATA]
If you try to pass a WIDECHAR array to a function that expects a CHAR array, expect to see the following compiler error: On the line where the function call is made:
C10585: Dimension mismatch: [1] vs. [0] and Type mismatch in call for parameter [A]
103
Programming
104
Programming
105
Programming
106
Compile Operations
Compile Operations
Overview
The options in the Build menu allow you to compile source code into executable code that the Axcess or NetLinx control system can understand. NetLinx Studio v2 has the ability to compile and link all the source code (.AXS and .AXI) files at the Workspace, Project, System or File level, plus the ability to compile a single file as either an Axcess or NetLinx type source code file. To send the compiled code to the Master Controller, use the File Transfers option in the Tools menu.
107
Compile Operations
3. The status and results of the build are displayed in the Status tab of the Output Display Window.
To compile the Active System: 1. Select Build Active System from the Build menu, or click the toolbar button. Any errors detected by the program before the build operation starts are listed in the PreBuild Errors dialog. Assuming that a Master Source Code file has been defined for the System, this dialog gives you the option of ignoring the errors and continuing with the build. 2. The status and results of the build are displayed in the Status tab of the Output Display Window. Designating the System's Master Source Code File Each System must have a Master Source Code file, and only one Source Code file in the System can be designated as the Master Source. There are two possible ways to designate the Master Source Code file for a System: You can designate a Source Code file as the Master Source at the time that it is added to the System, via the Master File option in the File Properties dialog.
108
Compile Operations
Alternatively, you can designate any Source Code file in the System as the Master Source by right-clicking on a Source Code file (in the Workspace tab of the Workspace Window), and selecting Set As Master from the Source Code File context menu.
3. The status and results of the build are displayed in the Status tab of the Output Display Window.
109
Compile Operations
Compiler Errors
When the compiler finds an error during the compilation process, it informs the programmer. 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 program can be executed. Compilation errors are described below:
A "<symbol>" was expected Active keyword expected The compiler is expecting a certain symbol at this particular place. An ACTIVE keyword is not present after a SELECT keyword.
Allowed only in DEFINE_START A keyword that is only allowed to appear in the DEFINE_START section of the program was encountered elsewhere. Attempted CALL to undefined subroutine Comment never ends, EOF encountered Conditional compile nesting too deep Constant type not allowed A CALL statement refers to a subroutine that has not been defined with a DEFINE_CALL statement. A comment begins but never ends. Place a close comment, * ) at the end of the unfinished comment. There are too many nested #IF_DEFINED or #IF_NOT_DEFINED conditional compilation statements. The limit is 20 nested conditional compilation statements. A constant value was declared as latching, toggling, or mutually exclusive, as shown below: DEFINE_CONSTANT PLAY = 1 DEFINE_LATCHING PLAY (* Error: PLAY is a constant *) DEFINE_CALL must have a name DEFINE_CALL name already used DEFINE_CALL must have a name after it. For example, DEFINE_CALL 'VHS'. The name of the DEFINE_CALL has already been used. This name cannot be the same as an already declared identifier of any type.
110
Compile Operations
Device values must be equal Duplicate symbol Evaluation stack overflow Evaluation stack underflow Identifier expected
In a range specification, the devices (or their defined identifiers) must be equal. For example, ([1,1]..[1,5]) is valid; ([1,1]..[2,5]) is not. Duplicate definitions of variables or constants are found. All variables and constants must have unique identifiers. The expression is too complicated. Try breaking it up into smaller pieces. The compiler is expecting an identifier after a #DEFINE statement or after an integer declaration in the DEFINE_VARIABLE section. A non-array variable was treated as an array. An INCLUDE statement was encountered, but the specified Include file could not be found. A string literal enclosed in single quotes must follow the INCLUDE keyword. The library file containing the specified SYSTEM_CALL could not be found. String literals are limited in length to 132 characters, including spaces. An array type variable was expected in CREATE_BUFFER, CREATE_MULTI_BUFFER, or CLEAR_BUFFER. The identifier in question must be an integer. This error occurs when the third parameter of CREATE_LEVEL is an array or array element. This error means that the compiler cannot find the line number to even check what type of error has occurred, so it gives no details on the cause. If you get this non-descriptive error when compiling and the code contains modules, check to make sure the module parameters are the right type. If you're trying to pass in a onedimension array where the module requires a two-dimension array, or a CHAR instead of an INTEGER, etc., this error will occur.
Identifier is not an array type Include file not found Invalid Include file name Library file not found Maximum string length exceeded Must be char array reference Must be integer reference
Out of memory
The compiler has run out of memory. Free up memory either by removing any pop-up programs or drivers, by using extended memory, or by breaking your program into one or more Include files. A value or variable passed to a CALL as a parameter is of the wrong type as defined by the DEFINE_CALL statement. Move the PROGRAM_NAME= statement to the first line of the program. A PUSH or RELEASE statement was found within a block of code headed by a PUSH or RELEASE statement. These keywords are not allowed in a section of code which will be executed due to a WAIT keyword.
Parameter mismatch in CALL PROGRAM_NAME must be on line 1 PUSH/RELEASE not allowed within PUSH/RELEASE PUSH/RELEASE not allowed within WAIT PUSH_CHANNEL not allowed within WAIT RELEASE_CHANNEL not allowed within WAIT PUSH_DEVICE not allowed within WAIT RELEASE_DEVICE not allowed within WAIT
111
Compile Operations
A string is required for the particular operation. This error occurs if a string literal enclosed in single quotes does not follow the PROGRAM_NAME keyword. A string literal is started but never ends. Add a closing single quotation mark (') to the end of the string. A string is required for the particular operation. This error would occur if a string literal enclosed in single quotes does not follow the #WARN keyword. A subroutine cannot call itself. It can, however, call a different subroutine. A syntax error is found in an expression. In most cases, this error means that a character is out of place or something is misspelled. This error occurs when a library file is compiled and the name of the subroutine in the library file does not match the PROGRAM_NAME string on the first line of the file. This error occurs when an attempt is made to use an array variable with DEFINE_LATCHING, DEFINE_TOGGLING, or DEFINE_MUTUALLY_EXCLUSIVE.
SYSTEM_CALL name not same as PROGRAM_NAME in <file> This variable type not allowed
These errors occur if the TO keyword is found in an erroneous location. The TO keyword can only be associated directly with To not allowed within MAINLINE a PUSH statement. To not allowed within RELEASE To not allowed within WAIT Too few parameters in CALL Too many Include files Too many parameters in CALL Type mismatch in function CALL Undefined identifier Unmatched #END_IF Unrecognized character in input file Use SYSTEM_CALL [INSTANCE] 'NAME' Variable assignment not allowed here WAIT not found There are not enough parameters being passed to the subroutine. A program may only contain up to 20 Include files. There are too many parameters being passed to the subroutine. A function was called with a parameter of the wrong type. For instance, attempting to use ITOA with an array as a parameter will result in an error. An attempt was made to reference an identifier that has not been defined previously in the program. An #END_IF keyword was found, but no #IF_DEFINED or #IF_NOT_DEFINED was previously compiled. An invalid character was found during compilation. This error occurs if a SYSTEM_CALL statement is written incorrectly as SYSTEM_CALL 'NAME' [INSTANCE NUMBER]. Variables may not be assigned a value when they are defined in the DEFINE_VARIABLE section. A statement references a WAIT by a name that does not exist. For example, CANCEL_WAIT 'CASS' will produce this error if there is no WAIT named CASS.
112
Compile Operations
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. Some types of warnings can be disabled in the Compiler Options tab of the Preference dialog. Common compiler warnings are described below:
(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. Here are some examples: Assigning a string literal, string expression, or array to a non-array variable Assigning a non-array variable to an entire array Assigning an integer array to a non-integer array Assigning a two-dimensional array to a one-dimensional array, or vice versa Assigning the result of a function that returns an array type to a non-array variable or to a two-dimensional array variable (for example, X = ITOA(12), where X is a non-array variable or two-dimensional array variable) Assigning the result of a function that returns a non-array type to a one- or two-dimensional array variable (for example, X = ATOI('AMX'), where X is a one- or two-dimensional array variable) This message is a warning and not an error, because X = ITOA(12) works correctly when X is a simple variable, since the result is a single value between and 65,535. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog. (w) Define_Call is not used This warning occurs at the end of program compilation for each DEFINE_CALL subroutine that was declared but never used. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog This warning appears when the keyword INTEGER is applied to a non-array type of variable. Doing this is not an error, because non-array variables are already integers, but it is redundant. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog. This warning occurs if the compiler finds a LONG_WHILE or MEDIUM_WHILE inside a block of code following a WHILE keyword. This warning exists because the WHILE command has a 1/2 second timeout period, and the LONG_WHILE and MEDIUM_WHILE keywords do not. This could create a hard-to-find logic error. The solution is to change the WHILE to a LONG_WHILE to fix this problem. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog.
(w) Possibly too This warning appears if there is a large amount of nesting in the program. many nested levels This can happen with a long chain of IF...ELSE IF statements. The solution is to use the SELECT...ACTIVE set of statements. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog. (w) Variable is not used This warning occurs at the end of compilation for each variable that was declared but never used. The generation of this warning can be turned on or off in the Compiler Options tab of the Preference dialog.
113
Compile Operations
Compiler Error Warnings Report Dialog This dialog is invoked via the Compiler Errors/Warning Report option in the Output Display Window Context Menu. Use the options in this dialog to specify what you want to include in the report (Errors, Warnings or both). By default, both Errors and Warning are included. Note that Warnings will not automatically preclude a successful compile operation. By contrast, Errors must be corrected before your program can be compiled. Disabling Compiler Warnings In Netlinx Code In the AXCESS Compiler tab of the Preferences dialog, there are a number of Axcess compiler warnings that can be enabled / disabled, but there are no corresponding options in the NetLinx Compiler tab for enabling / disabling NetLinx compiler warnings. Disabling NetLinx compiler warnings can be done in code by adding a #DISABLE_WARNING statement with a warning number generated by the compiler. For example, if you are getting a warning you want to disable, such as:
WARNING: U:\My Documents\Studio\Test\DISABLE_WARNINGtest.axs(12): C10571: Converting type [SINTEGER] to [INTEGER]
The warning number is 10571. Add the line to the beginning of the code file:
#DISABLE_WARNING 10571
The code will now compile without generating the specified warning.
Run-Time Errors
In many cases, a program is compiled and sent to the Master Controller error-free, but the System does not act in the way it should. If the program code is correct, you should check for run-time errors. These errors occur in the Master Controller, usually when it could not perform a particular operation in the program. Run-Time errors are errors that occur during program execution, and are described below:
Bad assign 2dim... These errors occur if an attempt is made to assign a two-dimensional array to a different type (such as a variable or one-dimensional array), and vice versa. These errors occur if the Master Controller cannot assign a parameter in a CALL statement to the parameter in the corresponding DEFINE_CALL statement. 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. Bad re-assign Call... These errors occur when the Master Controller attempts to reassign the parameter variables in a DEFINE_CALL to the parameters in the corresponding CALL statement, and the assignment cannot be made. This error occurs when the Master Controller does not understand a piece of data in the program it is executing. These errors occur if the SET_LENGTH_STRING keyword tries to set the length value of an array to a value greater than the array's storage capacity. This error occurs whenever a WHILE loop terminates due to the half-second timeout imposed on WHILE loops.
Bad While
114
115
Enter your Gateway. This value determines a path to computers not on your network. If you did not receive a value for this, enter your IP address. Do not leave this blank. Enter your Domain Suffix. If you did not receive a value for this, leave it blank. Enter up to 3 DNS IP. This values help your master find other network resources. If you did not receive a value for these, leave them blank. Press Set IP Info, followed by Set DNS Info and then press Reboot. When the master restarts, it will use the new network settings. You are now finished with your NetLinx Network Setup.
116
The online devices are organized according to the System they belong to. Double-click any System folder to display a list of System devices (and their firmware version) that are currently online. Double-click any online device in the list to display the ports and sub-devices associated with the device.
Sub-devices are hardware components contained within a parent device, which may require their own firmware. For example, and NXI Master Controller contains three components, each of which require firmware.
Click the Display command button (or right-click anywhere within the Online Tree tab) to access the Online Tree Context Menu. Device Tree Elements The main elements of the online device tree are described below: System: The highest-level element in the device tree is the System element. This element indicates the System Number, followed by the Master Controllers IP address and MAC address (FIG. 21):
Master Controller: The next element down from the System is the Master Controller element. This element indicates the Master Controllers device number, device name and indicates the Master firmware version currently loaded (FIG. 22):
Click the plus sign to expand the view to show sub-devices and ports on the Master. Sub-devices are indicated with red icons, and give a description and firmware version info (in parenthesis) for each. Below the sub-devices is a listing of Ports on the Master. To check the status on any port, right-click on a port and select Check Port Status from the context menu. The
117
results of this status check are indicated in the Status tab of the Output Window (see FIG. 24 on page 120). Devices: The elements below the Master Controller in the device tree represent devices in the system. These elements indicate the device number, device name and the device firmware version currently loaded (FIG. 23):
Click the plus sign to expand the view to show sub-devices and ports on the Master. Sub-devices are indicated with red icons, and give a description and firmware version info (in parenthesis) for each. Below the sub-devices is a listing of Ports on the Master. To check the status on any port, right-click on a port and select Check Port Status from the context menu. The results of this status check are indicated in the Status tab of the Output Window (FIG. 24). Device States There are several possible "states" for devices listed in the online device tree:
Unbound Device: An Unbound (or "Orphan") device is one that has not been bound to a NetLinx Master. It may or may not have been assigned a Device Number. A device will live in this state until it is explicitly bound to a master. A device is "Searching" if it has been bound to a NetLinx Master in the past, but is not currently communicating with the Master. After 10 minutes with no communication with the NetLinx Master, a "Searching" device is moved into the "Lost" state. Lost: A device is "Lost" if it has been bound to a NetLinx Master in the past, but it has not communicated with the Master for over 10 minutes.
Searching:
118
Found:
A device is "Found" if the device has been bound to a NetLinx Master and is communicating with that NetLinx Master. Found devices inherit the System Number of the NetLinx Master it is "Found" by. If the device has been configured with a valid Device Number, it will communicate with the NetLinx Master as that Device Number. If it has not been configured with a valid Device Number, it will request a Dynamic Device Number from the NetLinx Master and use the Dynamic Device Number to communicate with the NetLinx Master.
Device Tree Context Menu Right-click on any device or folder, or click the Display command button (in the Online Tree tab of the Workspace Window) to open the Device Tree context menu. This context menu contains various commands and options relating to online devices, including:
Refresh System: Click to refresh the Online Device Tree for the local system (the system containing the Master Controller that your PC is connected to). For NetLinx systems, it is the Master Controller identified in the Network field of the Communication Settings dialog. The Connection Status to the Master Controller dialog may appear, if communication to the master has not already been established. Refresh Network: Device Addressing: Check Port Status: Click to refresh the entire online tree (all Systems). Click to access the Device Addressing dialog, where you can view/edit the Device/System addressing information for the selected device. This item is enabled only if a Port element is selected in the Online Device Tree. The status of the selected port is displayed in the Status tab of the Output Display window. This item only appears if you have selected a device from the Unbound Devices folder (see FIG. 20). If the device is unbound, this option binds the device to a specific Master Controller (via the Bind/Unbind Device dialog - see the Binding/Unbinding Devices section on page 120). Click to expand all of the folders in the Online Device Tree to show all devices, ports and components.
Bind/Unbind Device:
Expand Tree:
Expand to Device Level: Click to expand the Online Device Tree to show all devices in the System. Collapse Tree: Click to collapse the Online Device Tree to the top-level System Devices folder.
Checking Port Status 1. Click the plus-sign (+) next to any device in the Device Tree to expand the view to show all of the ports for that device (as shown in FIG. 20 on page 116). 2. Right-click on any Port in the list to access the Device Tree context menu. 3. Select Check Port Status. 4. The results of the status check are displayed in the Status tab of the Output window. An example is shown in FIG. 24:
119
FIG. 24 Example result of Check Port Status (displayed in the Status tab of the Output window)
Binding/Unbinding Devices The Unbound Devices folder in the device tree (FIG. 20) indicates all devices in the system that are not currently bound to a Master. These are "orphan" devices, until they are assigned to communicate to a specific Master. An Unbound (or "Orphan") device is an NDP-capable device which has not yet been assigned (bound) to communicate with a specific Master. Unbound devices can be associated (bound) to a Master for communications via the Bind/Unbind Device option in the Device Tree context menu. A Bound device is one which has established communication with a specific Master. To Bind an Unbound Device: 1. Right-click on a device contained in the Unbound Devices folder of the Device Tree to access the Device Tree context menu. 2. Select Bind Device to open the Bind/Unbind Device dialog (FIG. 25).
Selected Unbound Device (click down-arrow to select a different unbound device) The information here indicates: [device number], device name and firmware info Check the Master that you want to bind the device to The information here indicates: [device number], device name and firmware info
120
3. By default, the selected device is displayed in the Device to Bind/Unbind window at the top of the dialog. If there is more than one Unbound device in the system, click the down arrow to select which device you want to bind. 4. Check the checkbox next to the Master that you want to bind the device to. If there is more than one Master in the system, check the specific Master that you want to bind the device to. 5. Select Refresh System (in the Device Tree context menu). The device should now appear in the device list (indicated with a green device icon). To Unbind a Bound Device: 1. Right-click on the device that you want to unbind in the Device Tree. 2. Select Unbind Device to open the Bind/Unbind Device dialog (FIG. 25). 3. De-select the checkbox next to the Master that the device is currently bound to. 4. Select Refresh System (in the Device Tree context menu). The device should now appear in the Unbound Devices folder (indicated with a green device icon).
4. Check each notification type that you want to enable for that device.
121
To set the selected set of notifications as the default notifications for this device, click the Set As Defaults button. Once you set the default notifications, you can use the Use Defaults button to recall the default set. 5. Click OK to close the NetLinx Notification Properties (Add) dialog and return to the NetLinx Device Notifications Options dialog. The new target device specified has its own line in the notifications list. The Device:Port:System values (for example, 1:0:0) identify the device in the Device column. The selected notification option(s) are labeled as ON in the associated column(s). 6. Repeat steps 2-5 to configure NetLinx Notifications for as many additional devices as is necessary.
A very large amount of data may be generated if all options are enabled for every device in a large System.
Select Enable Asynchronous Notifications to enable/disable NetLinx asynchronous notification messages being sent by the master controller. These are low-level strings of raw data, used primarily for troubleshooting the NetLinx master. This option is intended for use in conjunction with AMX Technical Support. 7. Click Done to save the changes and exit the NetLinx Device Notifications Options dialog. Editing Device Notification Settings In order to edit, add or remove devices from the list you must be connected to a NetLinx master controller. 1. Select Diagnostics > NetLinx Device Notification Options to open the NetLinx Device Notifications dialog. 2. Select a device in the Device list and click the Edit button to open the NetLinx Notification Properties - (Edit) dialog. Alternatively, you can double-click on a device in the Device list to access this dialog. 3. Check or un-check the notification types as desired. Note that the target device's Device, Port and System settings are read-only. This option allows you change the selected device's notification options only.
A very large amount of data may be generated if all options are enabled for every device in a large System.
4. Click OK to save your changes and return to the NetLinx Device Notifications Options dialog. The new notification options are indicated (as ON) in the notifications list. Select Enable Asynchronous Notifications to enable/disable NetLinx asynchronous notification messages being sent by the master controller. These are low-level strings of raw data, used primarily for troubleshooting the NetLinx master. This option is intended for use in conjunction with AMX Technical Support.
122
Removing Devices From The Notifications List In order to edit, add or remove devices from the list you must be connected to a NetLinx master controller. 1. Select Diagnostics > NetLinx Device Notification Options to open the NetLinx Device Notifications dialog. 2. Select a Device from the list and click the Remove command button.
The program will not allow you to remove the All Devices (0:0:0) listing.
Debugging NetLinx Programs with Terminal or Telnet messages This is often referred to as using "SEND_STRING 0's" in your code. Strings sent to device 0 (the master), port 1 or port 0, system 0 (the local system) will show up in a terminal or Telnet session once the programmer has typed in 'MSG ON'<enter> at the prompt. For example, if this line is in your code:
SEND_STRING 0,'some message'
when the code executes. The 13 characters to the left of the message are called the "time stamp" or "tic time". Also, by default, the master will append a carriage return and line feed to the end of each string. If the master is v2.10.81 or higher, there are additional MSG ON modes: 1. All messages with tic time. This is the same as 'MSG ON' with no type. 2. SEND_STRING 0 only (no tic time in front of string and no CR and LF appended). 3. SEND_STRING 0 with tic time pre-pended to string. Example:
MSG ON 2<enter> sets the message mode to 2.
123
The SEND_STRING 0 message is obviously completely customizable - whatever is typed in will be what you are going to get. This can be used as a way to see the value of variables at specific points in the code, by sending that information from that point, instead of stopping execution with a breakpoint. This is especially useful if programmers have to watch non-printable data bytes that only show as blank boxes in Windows programs, the SEND_STRING 0 code can reformat the data as a string of printable ASCII characters. The 'debug.axi' file (attached to Technote #461) contains 16 subroutines useful for this type of debugging and other purposes, e.g. DPS_TO_STRING and STRING_TO_DEV are useful for passing DEV information between masters via a virtual device in a master-to-master scenario. Theses subroutines were created as an AXI so programmers could use a single #INCLUDE at the top of the program rather than having to dig through the old programs and find the appropriate code to cut and paste. 1. FUNCTION CHAR[17] DEV_TO_STRING (DEV dvDEV) Formatting NetLinx device structures as strings take a little more than the simple ITOA(<device>) that was done in Axcess. This function takes a DEV and returns a string in the '<number>:<port>:<system>' format. 2. FUNCTION CHAR[25] DEVCHAN_TO_STRING (DEVCHAN dcDC) This function returns a DEVCHAN as a string with brackets in the format '[<number>:<port>:<system>,<chan>]'. 3. FUNCTION CHAR[25] DEV_CHAN_TO_STRING (DEV dvDEV, INTEGER nChannel) Same as DEVCHAN_TO_STRING but takes a separate DEV and INTEGER as parameters. Returns '[<number>:<port>:<system>,<chan>]'. 4. FUNCTION CHAR[25] DEVLEV_TO_STRING (DEVLEV dlDL) This function returns a DEVLEV as a string in the format '<number>:<port>:<system>,<lev>'. 5. FUNCTION CHAR[25] DEV_LEV_TO_STRING (DEV dvDEV, INTEGER nLevel) Same as DEVLEV_TO_STRING but takes a separate DEV and INTEGER as parameters. Returns '<number>:<port>:<system>,<lev>'. 6. FUNCTION CHAR[17] DPS_TO_STRING (DEV dvDEV) This function takes a DEV and returns a string in the '<number>:<port>:<system>' format. Same as DEV_TO_STRING except it always returns the actual system number, not system 0, if the device is so defined. 7. CALL 'SEND 131 BYTE PACKETS TO MASTER' (sSTRING[]) Strings sent to the master will be truncated if they are longer than 131 bytes. This call breaks the strings up if they are longer than 131 bytes. Otherwise, it does not modify the string. Use with master v2.10.81 or higher "MSG ON 2" mode to see only the data in the sSTRING. 8. CALL 'SEND 7BIT ASCII TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode) This call is similar to 'SEND ASCII TO MASTER' but with a little more flexibility: dvDEBUG is the destination device for the string. It could be the local master, a virtual device on the local system (see TN435), an IP device, serial device, etc.
124
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes < $20 (ASCII control codes) and > $7E (~) are formatted as hex
and separated by commas. As of v2.01, a space ($20) is no longer added between STR1 and STR2.
nLine is the line length. This may need to be changed if a terminal with a line length
other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for
the defaults. 9. CALL 'SEND ASCII TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode) This call is similar to 'SEND ASCII TO MASTER' but with a little more flexibility: dvDEBUG is the destination device for the string. It could be the local master, a virtual device on the local system (see TN435), an IP device, serial device, etc.
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes < $20 (ASCII control codes) and $7F (DEL) are formatted as
hex and separated by commas. As of v2.01, a space ($20) is no longer added between STR1 and STR2.
nLine is the line length. This may need to be changed if a terminal with a line length
other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for
mode 1(default) and mode 3 prepend 13 characters to the string, each line fills the typical 80 character line (67 + 183 = 80).
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes < $20 (ASCII control codes) and $7F (DEL) are formatted as
hex and separated by commas. As of v2.01, a space ($20) is no longer added between STR1 and STR2. 11. CALL 'SEND DECIMAL TO DEBUG' (dvDEBUG,STR1[],STR2[],nLine,nMode)
dvDEBUG is the destination device for the string. It could be the local master, a virtual device
125
nLine is the line length. This may need to be changed if a terminal with a line length
other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for
device on the local system (see TN435), an IP device, serial device, etc.
dvDEV is the device from which to get the info.
device on the local system (see TN435), an IP device, serial device, etc.
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. All data bytes are formatted as 3 digit decimal and separated by commas.
other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for
device on the local system (see TN435), an IP device, serial device, etc.
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. Data bytes are not formatted.
other than the typical 80 characters is being used. If not, just leave it as 0 for the defaults. If nMode is 2, nLine defaults to 80, else nLine defaults to 67 to allow 13 characters for the tic time.
nMode is the mode, if "MSG ON 2" mode is being used to set it to 2; otherwise, use 0 for
mode 81(default) and mode 3 prepends 13 characters to the string, each line fills the typical 80 character line (67 + 13 = 80).
126
STR1 is a header sent with each line - this is a good place to use DEV_TO_STRING. STR2 is data. All data bytes are formatted as hex and separated by commas.
As of v2.01, a space ($20) is no longer added between STR1 and STR2. 16. CALL 'STRING TO DEV' (Txt[], dvDEV) Takes ASCII string Txt[] of the form '<dev>' or '<dev>:<port>:<sys>' and stores this as a DEV. The dev data in Txt[] can be embedded in other non-numeric characters. If Txt[] does not contain any numerals, dvDEV will default to 0:1:0 (the local master). In order to use these subroutines, debug.axi must be in the compile path. It is suggested that an "AXIs" folder in the My Documents folder be created, save debug.axi there, then add that path to Netlinx Studio "Edit/Preferences/Netlinx Compiler Options/Include Files". Then add the line:
#INCLUDE 'debug.axi'
to the source code. "Debug.axi" and example code are attached to Tech Note #461. To access AMX Tech Notes, go to www.amx.com, log in as a dealer and go to Tech Center > Tech Notes. Buffering of the Notification and Diagnostic Tabs The Notification and Diagnostic tabs are capable of handling a large number of messages without adversely affecting the system. There is a buffer file for each view and you can define the combined size of the two buffer files that are used to handle the large number of messages being sent from the master controller. As the buffer files are filling with messages from the master controller, the program will read in a message and display it into the appropriate list view every quarter of a second. This will allow you to view the messages at a reasonable rate versus what is being loading into the buffer files.
The buffer files that are used by the Notification and Diagnostic tabs can become full. When this happens, the program will disable the appropriate option. You will need to clear the appropriate list before you can start the option again. You may copy the text from the list view or save the content of the list view to a file.
127
3. To emulate a channel (push/release), enter a valid Channel number to emulate Channel messages (i.e., Push/Release, CHON, and CHOFF) for the specified <D:P:S> in the Channel text box. The Channel number range is 0-65535. Select the Push button to emulate a push/release on the channel specified. You may click and hold down the Push button to see how the master controller responds to the push message. Select the On or Off buttons to emulate Channel ON (CHON) and Channel OFF (CHOFF) messages for the specified <D:P:S>. 4. To emulate a level, enter the desired Level (number), Value and data Type (BYTE, CHAR, WIDECHAR, INTEGER, SINTEGER, ULONG, LONG, FLOAT, or DOUBLE), and click Send to emulate the specified level and value. The Level number range is 0-65535. The list below indicates the valid level data types and their ranges:
Data Type CHAR INTEGER Min Value 0 0 Max Value 255 65535 32767 429497295 2147483647
-3.402823466e+38 3.402823466e+38
5. To emulate sending a String or Command, type a String or Command in the Message(s) To Send text box. Use the Return key within the text box to enter a new line for the next message. When entering a send command (in the context of this dialog) do not include the "send c" or "send_command" in the statement - only type what would normally occur within the quotes, but don't include the quotes either. For example to send the "CALIBRATE" send command, simply type CALIBRATE (no quotes) rather than SEND_COMMAND <dev> "CALIBRATE".
Hold down the Shift key to select a specific range of lines to send to the controller instead of all the lines within the edit control.
a. Click the Message Type radio buttons (String or Command) to specify the type of message you are sending. b. Click Send To Master to send the messages in the Message(s) to Send text box to the master. If none of the messages are selected (highlighted), all messages are sent. If you have selected a line or a range of lines, only the selected messages will be sent. 6. Check the Messaging Options checkboxes to Enable Asynchronous Notifications and/or Enable Internal Diagnostic Messages.
128
It is recommended that you enable NetLinx Notifications to view the results in the Notifications tab of the Output Display window. For example, in order to view a string sent to a device (via the Emulate Device dialog), you must first enable the Strings to Device notification (in the NetLinx Device Notifications Options dialog). Additionally, to view any strings returned from the device, you must enable the Strings From Device notification.
-3.402823466e+38 3.402823466e+38
129
5. To emulate sending a String or Command, type a String or Command in the Message(s) To Send text box. Use the Return key within the text box to enter a new line for the next message. When entering a send command (in the context of this dialog) do not include the "send c" or "send_command" in the statement - only type what would normally occur within the quotes, but don't include the quotes either. For example to send the "CALIBRATE" send command, simply type CALIBRATE (no quotes) rather than SEND_COMMAND <dev> "CALIBRATE".
Hold down the Shift key to select a specific range of lines to send to the controller instead of all the lines within the edit control.
a. Click the Message Type radio buttons (String or Command) to specify the type of message you are sending. b. Click Send To Master to send the messages in the Message(s) to Send text box to the master. If none of the messages are selected (highlighted), all messages are sent. If you have selected a line or a range of lines, only the selected messages will be sent. 6. Check the Messaging Options checkboxes to Enable Asynchronous Notifications and/or Enable Internal Diagnostic Messages.
It is recommended that you enable NetLinx Notifications to view the results in the Notifications tab of the Output Display window. For example, in order to view a string sent to a device (via the Emulate Device dialog), you must first enable the Strings to Device notification (in the NetLinx Device Notifications Options dialog). Additionally, to view any strings returned from the device, you must enable the Strings From Device notification.
Viewing Push Results The PUSH keyword is used to find out if a channel has had an input change from off to on, such as when a button is pressed. If the channel has been turned on, the corresponding Push statement is activated. The operation or operations following this Push statement are only executed once after the channel is turned on. To view Push results, select Diagnostics > Enable Push Message Status Bar Display. NetLinx Studio displays the most recently received Push, or Push status (Push Enabled/ Disabled) in the Status Bar. Left-mouse click on the push message displayed to view a history of push messages. Then, right-mouse click within the list box to view the available options.
130
Changing The Device/System Address On A Netlinx Device Select Device Addressing from the Diagnostics menu, the Online Device context menu, or click the toolbar button to access the Device Addressing dialog, which allows you to change the Device and/or System Address for a NetLinx system device: 1. Enter the target device's current Device number in the (Device to Change) Device text box. 2. Click the Change Device checkbox and enter the new Device number in the New Device text box. 3. Enter the target device's current System number in the (System to Change) System text box. 4. Click the Change System checkbox and enter the new System number in the New System text box. 5. Click the Change Device/System Number command button to set the new address information for the specified device. 6. The master must be rebooted to accept the new System number assignment. To reboot the master, select Reboot Master from the Tools menu.
Alternatively, you can use the ID (Identification) Mode options on the right side of this tab to change the address assignment for a specified NetLinx device. Use ID Mode when you don't know the current address assignments. The Start Identify Mode button places the entire NetLinx system (specified in the Destination System text box) in ID Mode.
131
Restoring The Default Device and System Numbers On A Netlinx Device Use the Device Addressing dialog to restore the default Device and System numbers on a NetLinx device:
If the target Master has security applied, NetLinx Studio will prompt you for a User Name and Password in order to change these settings.
1. Select the target device/system in the Online Device Tree. 2. Right-click to access the Online Tree context menu. 3. Select Set Device/System to Factory Default. Using ID Mode To Change The Device Address On a NetLinx Device The ID Mode section of the Device Addressing dialog allows you to place the program in ID (Identity) mode. This is useful when the current address assignments are unknown. ID Mode means that the entire system is put on hold while it waits for an event from any NetLinx device in the named system (for example, a button push on a NetLinx Touch Panel). The device that generates the first event is the device that gets "identified". Once a device has been identified, it will be set (or changed to) the Device/System Address specified. Use the ID Mode options in the Device Addressing dialog to set or change the Device Address (Device and System ID numbers) for a NetLinx device.
If the target Master has security applied, NetLinx Studio will prompt you for a User Name and Password in order to change these settings.
1. Enter the Device and System numbers that you want to assign to the device in the (Change to Device) Device and System text boxes.
The Destination System number must be a System that is defined in the URL List dialog.
2. Enter the Device and System numbers that you want to assign to the device in the (Change to Device) Device and System text boxes. 3. Click the Start Identify Mode button to place the named System in ID Mode. The text box below this button displays a WaitingPress Cancel to Quit message. The Start Identify Mode button changes to Cancel Identify Mode (click to cancel ID Mode). 4. Generate an event from the device that you want to assign the new Device and System numbers to: For NetLinx control panels, press any button to generate a Push. For NetLinx Masters, press the ID button on the rear panel. 5. The device that generated an event is assigned the new Device and System numbers. The Online Device Tree will refresh to represent the new device address.
132
Creating a URL List 1. Select Diagnostics > URL Listing (or click the toolbar button) to access the URL Listing dialog. 2. Enter the System and Device numbers for the Master that you are connected to in the appropriate text boxes. The range is 0-65535. 3. To add a device to the URL List, click Add. This opens the Add URL dialog. 4. Enter the web address (URL or IP Address) of the device in the URL text box and click OK to return to the URL List dialog.
If you enter a valid URL for a device, the program generates the device's IP Address.
5. Initially the connection status reads Looking up URL. Once found, the new device appears in the URL List with its IP Port assignment = 1319.
Do not change the IP Port number! An IP Address is assigned to this URL and is displayed in the IP Address column.
6. Click Get URL List to refresh the URL List after adding a device. 7. Repeat steps 1-5 for as many additional devices as are required. To retrieve a list of all URL's in the list, click Get IRL List. The URL List is populated with all previously set URL's. To remove a URL from the list, select the URL and click Remove. To clear all URL's from the list, click Remove All.
133
Changing the System Number On a Netlinx Master Use the System field in the Network Addresses dialog to change the System number for the connected Master: 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, specify a new System number in the System text box. 3. Click the Reboot Master button to reboot the master and accept the new changes. Allow 20-30 seconds for the master to reboot. Changing the IP Address On a NetLinx Device Using DHCP Use the IP Address options in the Network Addresses dialog to change the IP Address for a specified NetLinx Device (using DHCP): 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, enter the specified device's System and Device numbers in the text boxes. The range is 0-65535. 3. Click the Get IP Information button to populate the IP Address fields with the current Host Name and Gateway assignments. 4. Click the Use DHCP radio button, and enter a new Host Name in the text box, if necessary. 5. Click the Set IP Information button to set the new Host Name assignment. 6. Click the Reboot Master button to reboot the master and accept the new changes. Allow 2030 seconds for the master to reboot.
When you change the IP Address of a master (if connected via IP), you must also change the communication settings to match the new IP Address in the Master Communications Settings dialog.
Setting the DNS Address For a Netlinx Master 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. Enter the specified device's System and Device values in the text boxes at the top of the dialog (ranges = 0-65535).
134
3. Click Get DNS Information to populate the DNS Address fields with the current Domain Suffix, DNS IP Address #1, DNS IP Address #2 and DNS IP Address #3 assignments (as applicable). 4. Edit the DNS Address assignments and/or add new DNS address information as needed. 5. Click Set DNS Information to set the new DNS address assignments. Setting the IP Address For a NetLinx Master 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, enter the specified device's System and Device numbers in the text boxes (range = 0-65535). 3. Click Get IP Information to populate the IP Address fields with the current Host Name, IP Address, Subnet Mask and Gateway assignments. 4. Click the Specify IP Address radio button, and enter the new IP Address, Subnet Mask and Gateway assignments in the text boxes, as necessary. 5. Click Set IP Information to set the new IP Address assignment. 6. Click Reboot Master... to reboot the master and accept the new changes. Allow 20-30 seconds for the master to reboot. Changing the IP Address On a Netlinx Master (Use DHCP) Use the options in the Network Addresses dialog to change the IP Address for a specified NetLinx device (using DHCP): 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. At the top of the dialog, enter the specified device's System and Device numbers in the text boxes. The range is 0-65535. 3. Click the Get IP Information button to populate the IP Address fields with the current Host Name and Gateway assignments. 4. Click the Use DHCP radio button, and enter the new Host Name in the text box, if necessary. 5. Click the Set IP Information button to set the new Host Name assignment. A message will be displayed indicating that the Master has accepted the new settings. 6. Click the Reboot Master... button to reboot the Master and accept the new changes. Allow 20-30 seconds for the Master to reboot.
If you change the IP Address of a Master (if connected via IP), you must also change the communication settings to match the new IP Address (in the Communication Setting dialog).
135
Changing the IP Address On a Netlinx Master (Specify IP Address) 1. Select Diagnostics > Network Addresses (or click the toolbar button) to access the Network Addresses dialog. 2. Enter the specified master's System number in the System text box at the top of the dialog. The range is 0-65535. 3. Click the Get IP Information button to populate the IP Address fields with the current Host Name, IP Address, Subnet Mask and Gateway assignments. 4. Click the Specify IP Address radio button, and enter the new IP Address, Subnet Mask and Gateway assignments in the text boxes, as necessary. 5. Click the Set IP Information button to set the new IP Address assignment. A message will be displayed indicating that the Master has accepted the new settings. 6. Click the Reboot Master... button to reboot the Master and accept the new changes. Allow 20-30 seconds for the Master to reboot.
136
Axcess/NetLinx Debugging
Debugging Source Code Files NetLinx Studio contains several useful options for debugging your Master Controller and Source Code files.
The Debugging feature allows you to view variables declared within the scope of a Function and or Call procedure. However, stack and parameter values are not editable. If you attempt to edit either the stack or parameter values, a warning message is displayed.
In order to begin debugging, your computer must be connected to a Master Controller, and you must have a compiled Source Code file active. To use debugging, the Build With Source option must be selected in the Axcess Compiler and/or NetLinx Compiler tabs of the Preferences dialog, before the file is compiled. For NetLinx code, select You cannot compile, send/receive files, or change port settings while the program is in debug mode. Avoid declaring variables as volatile whenever possible, since volatile variables will not display their contents during the debug session. NetLinx character strings by default are displayed in current length mode, while all other strings (including Integer strings) are displayed in total length mode. To enter debug mode: 1. Open and compile a Source Code file (that contains at least one variable), if you have not already done so. The file must be successfully compiled before you can enter debug mode. 2. Choose Build > Debug (or click the toolbar button) to open the Watch window. If this option is disabled, make sure your Master Communications Port settings are set to connect to your Master Controller.
137
3. Right-click inside the Watch window to open the Watch Window context menu. 4. Click Add to insert a new variable in the Watch window. A box appears in the window, with a cursor blinking in the Name column. 5. Type the syntax of the variable exactly as it is defined in the code and press the Enter key. The value of the specified variable appears next to the variable (in the Value column). 6. You can select different view formats for the Value by right-clicking on the line containing the variable/value, and clicking on Display in the Watch window context menu. This opens the Display sub-menu, containing the following view options:
ASCII Display Decimal Display displays the value of the watched variable in ASCII format. displays the value of the watched variable in decimal format.
Hexadecimal Display displays the value of the watched variable in hexadecimal format. Octal Display Binary Display displays the value of the watched variable in octal format. displays the value of the watched variable in binary format.
To exit Debug mode, close the Watch window. Notes on Using Current Length (when the Total Length option is disabled): The way you initialize variables in your source code affects the use of Current Length. For example, if you have a variable declared as:
CHAR cat[3]
in debug, Total Length = 3 and Current Length = 0. If you modified the code as:
CHAR cat[3] = 'CAT'
in debug Total Length = 3 and Current Length = 3. If you modified the code like this:
CHAR cat[3]
in debug Total Length = 3 and Current Length = 0, because setting values using array indexing does not set the current length. Master Controller Debug Options The Watch window is displayed when Start Debugging is selected from the Debug menu (or the Debug Watch toolbar). The Watch window is a dockable window that allows you to view and edit the contents of variables within a compiled Axcess or NetLinx program. Also, you can control the execution through each pass of the mainline of a compiled Axcess or NetLinx program. Once Start Debugging has been selected, the other options in the Debug menu become available:
Start/Stop Debugging Ability to toggle the debug state of the application. There is no limitation on then number of NetLinx variables that can be watched in the Debug Watch windows. A maximum of 10 watch variables are allowed when debugging an Axcess master controller.
138
Step Mode
Enable/Disable Step mode causes the Interpreter to break after each execution of the mainline. Watch variables are always updated after each pass through mainline. To continue program execution while in Step mode, you must invoke the "Step" command again. Execute one line of a source code file at a time for a NetLinx master controller or execute one pass through the mainline code for an Axcess controller.
Single Step
The following options are only needed for debugging code on a NetLinx master: Run Run To Cursor Break Edit Breakpoints Toggle Break Point Clear Break Points To continue execution after a Single Step operation or from a toggled break point. Execute the program and break on the line of code where the cursor is residing on the screen. Stop execution of the program and highlight the line of code on the screen. A dialog box appears listing all the break points within the code. Toggle a break point on the screen where the cursor is residing. A red diamond appears next to the line of code to signify a break point. Clears all the break points within the source code file.
Changing The Value Of a Watched Variable Once you have entered Debug mode, you can change the name and/or value of any watched variable, via the Value column in the Watch window: 1. Select a watched variable in the Watch window. 2. To change the variable's value, double-click on the desired variable's value to change the value to an edit field, which you can modify as desired.
139
140
6. Click Edit Settings to specify the communication settings for the selected connection option: For TCP/IP connections: Set the TCP/IP address (TCP/IP Settings dialog). For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). For Virtual NetLinx Master connections: Specify the System number for the Virtual Master (Virtual NetLinx Master Settings dialog; default = 1). The default settings for Serial and Modem ports are:
Com Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1
Some combinations of settings may result in truncation in the Settings display text field (indicated by an ellipsis). If this is the case, simply hover the mouse cursor over the Settings display text field to view the full description.
7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog.
141
Alternatively, you can access these option via the Set Default Communication Settings with the IP option in the Network Addresses dialog.
3. Click the Communication Settings button to access the Communication Settings dialog. 4. Select the default Platform (NetLinx or Axcess). 5. Select a Transport Connection Option (TCP/IP, Serial, Modem or Virtual NetLinx Master).
The TCP/IP and Virtual NetLinx Master options are only available if NetLinx is selected as the platform.
6. Click Edit Settings to specify the communication settings for the selected connection option: For TCP/IP connections: Set the TCP/IP address (TCP/IP Settings dialog). For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). For Virtual NetLinx Master connections: Specify the System number for the Virtual Master (Virtual NetLinx Master Settings dialog; default = 1). The default settings for Serial and Modem ports are:
Com Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1
142
Some combinations of settings may result in truncation in the Settings display text field (indicated by an ellipsis). If this is the case, simply hover the mouse cursor over the Settings display text field to view the full description.
7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. Alternatively, you can also access these System-level communications settings options via the System Properties dialog: 1. Select (highlight) a System in the Workspace tab of the Workspace Window, and select System Properties from either the Project menu or the System Folder context menu (or click the toolbar button) to open the System Properties dialog. 2. In the Communication Settings area (at the bottom of the dialog), click Communication Settings to open the Communication Settings dialog. 3. Follow steps 4 through 8 (above) to specify communication settings for the selected System.
3. Click the Communication Settings button to access the Communication Settings dialog. 4. Select the default Platform (NetLinx or Axcess). 5. Select a Transport Connection Option (Serial or Modem). 6. Click Edit Settings to specify the communication settings for the selected connection option: For Serial connections: Specify the COM port, and set baud rate, data bits, parity, stop bits and flow control (Serial Settings dialog). For Modem (serial-modem) connections: Specify the COM port, and set baud rate, data bits, parity, stop bits, flow control and target phone number (Modem Settings dialog). 7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog.
143
144
the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.
5. Click OK to return to the Communication Settings dialog. 6. Click OK to save the new VNM communication settings with the selected file. Connecting To a Netlinx Master Via TCP/IP To connect to a NetLinx master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the TCP/IP address. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select NetLinx Master as the Platform Selection. 4. Select TCP/IP as the Transport Connection Option. 5. Click Edit Settings to open the TCP/IP Settings dialog. 6. Enter the TCP/IP Address of the master.
The Port should always be set to 1319 (default setting). Do not change the Port assignment.
7. Click OK to return to the Communication Settings dialog. 8. Select Authentication Required to enable NetLinx Master Security for this connection. This enables the User Name and Password button. Click it to enter the user name and password assigned to the Master (case-sensitive). 9. Click OK to return to the Master Communication Settings dialog. 10. Click OK to close the Master Communications dialog. 11. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display.
12. Double-click the System icon to expand the tree to show the NetLinx master.
145
Connecting To a NetLinx Master Via Serial Port To connect to a NetLinx master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the serial port settings. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select NetLinx Master as the Platform Selection. 4. Select Serial as the Transport Connection Option. 5. Click Edit Settings to open the Serial Settings dialog. 6. Select a COM port and specify the communication settings for serial port communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits COM1 38400 8 None 1
7. Click OK to return to the Communication Settings dialog. 8. Select Authentication Required to enable NetLinx Master Security for this connection. This enables the User Name and Password button. Click it to enter the user name and password assigned to the Master (case-sensitive). 9. Click OK to return to the Master Communication Settings dialog. 10. Click OK to close the Master Communications dialog. 11. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 12. Double-click the System icon to expand the tree to show the NetLinx master. Connecting To A NetLinx Master Via Modem To connect to a NetLinx master, use the options in the Master Communication Settings and Communication Settings dialogs to specify the modem settings. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select NetLinx Master as the Platform Selection. 4. Select Modem as the Transport Connection Option. 5. Click Edit Settings to open the Modem Port Settings dialog.
146
6. Select a COM port and specify the communication settings for modem communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits Flow Control COM1 38400 8 None 1 None
7. Click OK to return to the Communication Settings dialog. 8. Select Authentication Required to enable NetLinx Master Security for this connection. This enables the User Name and Password button. Click it to enter the user name and password assigned to the Master (case-sensitive). 9. Click OK to return to the Master Communication Settings dialog. 10. Click OK to close the Master Communications dialog. 11. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 12. Double-click the System icon to expand the tree to show the NetLinx master. Connecting To A Secured Netlinx Master When connecting to a NetLinx Master that has security enabled, you will be required to enter a User Name and Password before you can connect. To establish a connection to a secured master, 1. Select Settings > Communication Settings to open the Communication Settings dialog and select NetLinx as the platform and select a Transport Type. 2. Click Edit Settings to configure the selected transport type. 3. Click OK to save the TCP/IP, Serial or Modem settings (depending on the transport type selected). 4. Click the Authentication Required checkbox. This enables the User Name and Password button. 5. Click on User Name and Password to enter the User Name and Password that are set for this NetLinx Master (in the Master Controller User Name and Password dialog). These are case sensitive. 6. Click OK to close the Master Controller User Name and Password dialog. 7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. At this point you should be able to connect to the Master.
147
If you don't connect: Verify that the master is set for ICSP Connectivity, with Require Encryption enabled (via the Master's built-in interface). Refer to the Master's documentation for details on enabling/disabling security.
7. Click OK to return to the Communication Settings dialog. 8. Click OK to return to the Master Communication Settings dialog. 9. Click OK to close the Master Communications dialog. 10. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 11. Double-click the System icon to expand the tree to show the Axcess master. Connecting To An Axcess Master Via Modem To connect to an AXCESS master, use the options in the Master Communication Settings and Communication Settings dialogs to specify serial port or modem settings, depending on the
148
transport connection type specified. These instructions in these topics assume that the physical link between the PC running NetLinx Studio and the NetLinx master is established. 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Click Communication Settings to access the Communication Settings dialog. 3. Select Axcess Master as the Platform Selection. 4. Select Modem as the Transport Connection Option. 5. Click Edit Settings to open the Modem Settings dialog. 6. Select a COM port and specify the communication settings for modem communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits Flow Control COM1 38400 8 None 1 None
7. Click OK to return to the Communication Settings dialog. 8. Click OK to return to the Master Communication Settings dialog. 9. Click OK to close the Master Communications dialog. 10. In the online tree (displayed in the Online Tree tab of the Workspace window), click Display to open the Online Tree sub-menu, and select Refresh Network to refresh the online tree display. 11. Double-click the System icon to expand the tree to show the Axcess master.
149
IR library files (.IRL/.IRV) are sent to IR-controlled devices on the bus, or directly to a System device (i.e. Touch Panels). The Virtual NetLinx Master option allows you to transfer files directly to G4 devices, without the need for an intermediate NetLinx Master. The File Transfer dialog (Tools > File Transfer) provides an easy to understand approach to file transfer while still providing a high level of flexibility. File Transfers Edit Sub-Menu With a file selected in the Files To Send table (of the File Transfer dialog), click the Edit command button to open the File Transfers Edit sub-menu, containing the following options: Options - This option is only available if you have selected a TPD or TP4 touch panel UI file. If you have selected a TPD (TPdesign3) file, this option opens the TPD Transfer Options dialog, where you can select which parts of the TPD file to include when the file is sent (the options are Bitmaps, Fonts and Icons - by default they are all selected). If you have selected a TP4 (TPDesign4) file, this option opens the TP4 Transfer Options dialog, where you can select to enable Smart Transfer. Smart Transfer automatically optimizes the transfer by identifying the various components (fonts, bitmaps, sound files, even pages and popup pages) of the selected panel file, and comparing them to the elements already present on the target panel. Any shared components are not sent, resulting in a much faster transfer (assuming that there are shared components).
When sending a TP4 file to a G4 panel, verify that the NetLinx Master Firmware is build 85 or later. Verify the TPDesign4 program being used is Version 1.01 or higher. Earlier versions of the firmware and TPD4 software are incompatible with G4 panels.
Communication Settings - Opens the Communication Settings dialog, where you can edit the Platform, Transport Connection type and Communication Settings for the selected file.
Alternatively, you can double-click in the Connection column to access the Communication Settings dialog.
Device Mapping - Opens the Enter DPS dialog, where you can view/edit the D:P:S assignment of the target device for the selected file.
In Axcess, Master Source Code files are always mapped to the Master Controller (device = 0). Master Source Code files cannot be mapped to any other device. NetLinx Master Source Code files are mapped according to the System settings when the Project was created. The only way to modify these settings is via the System Properties dialog. Also, when sending TPD files directly to a Touch Panel (i.e. via serial cable connection), the device = 0.
150
File Transfer Status Information Once you have started a file transfer operation, the following types of status information are displayed in the File Transfer Status tab of the Output Display window:
Type Status Connection Mapping The type of transfer (sending or receiving). The current state of the transfer (Pending, Transferring, Complete or Failed). The communications settings used to establish communication with the target device. The number(s) used to identify the target device on the bus or the message "Direct to Device (No Master)" if the target device does not reside behind a master. The name and extension of the file being transferred. The full path of the file being transferred.
File Path
Bytes Transferred The number of bytes transferred, and the total number of bytes left to transfer. Error Last Transfer An error message if an error has occurred. The time and date of the last transfer.
Canceling Transfers A file transfer may be cancelled by right-clicking on the item in the Output Display Window - File Transfer Status tab and selecting Cancel Transfer from the context menu. Canceling an item that is not currently transferring removes it from the transfer queue.
Canceling during a file transfer may leave the target device in an unstable state.
Transfer Errors And Definitions The following table describe the most common error messages that might be displayed in the Error column of the Transfer Status Window.
Error String Failure Success File does not exist Failed to create temporary file Invalid file type Unknown Error File: <filename> does not exist and cannot be transferred! File: <filename> is currently opened by another application and cannot be transferred! Nothing to transfer! [Project Identifier invalid?] [System Identifier invalid?] Meaning Generic/unclassified failure. Generic success. The file supplied on the cmdline doesn't exist. Couldn't create a required temporary file. The file supplied on the cmdline is an unknown file type. Generic/unknown error. File does not exist at location specified. This can happen if another application has an exclusive lock on a file. After processing all supplied parameters and options, there was nothing to transfer. That is, no files could be found or nothing was specified for transfer. Additionally, if you specified a project identifier and/or a system identifier, you may have inadvertently requested an empty or nonexistent set of files. Failed to open workspace! AXW file does not contain an APW.
151
There are several possible ways to access the Quick Load dialog: Click the Quick Load command button. If there is not already a Workspace file open, then the Quick Load dialog will indicate that no (zero) projects are open (no Project file/file path indicated in the top text field, and "New Workspace: 0 Project(s)" indicated in the main window. You should first open a Workspace file, then use the options in the Quick Start dialog to select the files within that Workspace file to add to Files To Send queue. Without having a workspace file open, you cannot select files for transfer via the Quick Start dialog. By default, FileTransfer2 opens the Quick Load dialog when a Workspace file is opened (via the Load Workspace button, or the File > Open Workspace/AXW/FTL File menu option. With at least one Workspace file open, the options in the Quick Load dialog allow you to specify which of the files contained in the Workspace file(s) to add to the Files To Send queue:
You can disable the Quick Load dialog from automatically opening by de-selecting the After opening a Workspace file. Visit the Quick Load dialog option in the Preferences dialog.
1. Selection Options menu - Click the down arrow to access the following load options: Active System - Loads only the files from the active System. Entire Workspace - Loads all files from the Workspace. Select System - Select an individual System from the Workspace to load. 2. File type checkboxes - The checkbox options in this dialog allow you to simplify the transfer operation by only sending only specific file types (including TKN, TOK, SRC, IRL, KPD, TP4 and TPD files). Use the Select All and Deselect All command buttons to streamline the selection process. Note that there are additional options associated with TP4 and TPD files. If you select TP4 Files, you also have the option of enabling Smart Transfer for those files. Similarly, if you select TPD files, you have the additional options of including Bitmaps, Icons, and/or Fonts for those files. 3. Remove Duplicates When Loading - Enable this option to prevent having any duplicate entries in the Files To Send queue (default = enabled).
152
Adding Files To The Files To Send Queue There are several possible approaches to adding files to the Files To Send List (Send tab). Add some or all of the files contained in a Workspace file or a Workspace-To-Go file. Add individual systems (see Supported File Types list). Notes: The file types that are available for selection depend on the selected Platform (Axcess or NetLinx), Send/Receive selection and Communication settings. All files must mapped to devices before they can be selected for transfer. You can edit the file's mapping information via the Edit menu (Device Mapping option), but without any mapping information associated with the file, it cannot be selected. Source Code files cannot be sent until they have been successfully compiled. While Touch Panel UI files are sent to the panels themselves, KPD files are sent to the master and not directly to the keypad. Before sending a KPD (KPDesign) file to the target keypad(s), be sure that you have successfully compiled the Source Code file that contains the keypad module, and sent it to the Master. Adding All Files Contained In An APW Or AXW File In the Send tab: 1. Select File > Open Workspace/AXW/FTL File or click the Load Workspace command button to open the Open File dialog. 2. Select either NetLinx Studio Files (*.apw) or Export-To-Go Files (*axw) from the File of Type drop-down menu (depending on which type of file contains the system files that you want to transfer). This dialog contains two tabs: Existing and Recent. Use the Existing tab to locate and select the desired file, with the ability to navigate through all available local and network drives. The Recent tab contains a listing of the most recently used files (of all types). 3. Locate and select the Workspace file that you want to add, and click Open. This opens the Quick Load dialog. 4. In the Selection Options section, select Entire Workspace. 5. Click Select All to add every file type in the Workspace, and enable the Remove Duplicates when Loading option. 6. Click OK to close the Quick Load dialog and add the files to the File To Send queue. Adding Files From A Specific Project/system In the Send tab: 1. Select File > Load Workspace/AXW/FTL File or click the Load Workspace command button to open the Open File dialog. 2. Set the File of Type drop-down to NetLinx Studio Files (*.apw).
153
This dialog contains two tabs: Existing and Recent. Use the Existing tab to locate and select the desired file, with the ability to navigate through all available local and network drives. The Recent tab contains a listing of the most recently used files (of all types). 3. Locate and select the Workspace file that contains the Project/System with the file(s) you want to add, and click Open. This opens the Quick Load dialog. 4. In the Selection Options section: Select Active System to add files from the active System in the open Workspace. Select a Project-System to add files from a specific Project/System in the open Workspace. 5. Click in the checkboxes to specify which file types in the selected System to add. 6. Click OK to close the Quick Load dialog and add the files to the File To Send queue. Adding Individual System Files From The Open Workspace File With a Workspace (or Workspace To-Go) file open, use the Add command button (in the Send tab) to select individual System files to add to the Files To Send queue: 1. Click the Add command button to open the Select Files For File Transfer dialog. 2. Open the Current Workspace tab. This tab consists of a display of the (compiled) Source Code (.AXS), Token (.TKN), UserInterface (.TPD/.TP4) and IR (.IRL) files contained in the currently open Workspace. Use the options in the Current Workspace tab to locate and select file(s) for transfer to the Master or System devices on the bus. Use this tab if the file(s) you want to transfer are included in the open Workspace. 3. Click OK to add the selected file(s). Adding Orphan Files In the Send tab: 1. Click the Add command button to open the Select Files For File Transfer dialog. 2. Open the Other tab. Use this tab if the file(s) you want to transfer are not included in the open Workspace. This tab consists of a display of the different types of files that can be transferred to the Master or System devices on the bus: IR Codes (*.IRL/*.IRV) NetLinx Source Code (*.SRC) Compiled NetLinx Source Code (*.TKN) Compiled Axcess Source Code (*.TOK) Touch Panel Design File (*.TPD) TP4 Touch Panel (*.TP4) KPD Keypad Touch File (*.KPD)
154
3. Select the type of file that you want to add to the Transfer List. 4. Click the Add button. This invokes the Open dialog, with the Files of Type selection already set to the selected file type. 5. In the Open dialog, locate and select the file that you want to add. 6. Click Open to add the selected file to the Files To Send queue. Adding Files To The Files To Receive Queue
To add files to the Files To Receive queue: 1. Open the Receive tab. 2. Click the Add command button to open the Select Files For Transfer dialog. 3. Select the type of file you want to receive from the system device (IRL/IRV, TPD, SRC, AXS or TP4), and click Add (opens the Save As dialog).
The file types that are available for selection depend on the selected Platform (Axcess or NetLinx), Send/Receive selection and Communication settings.
4. In the Save As dialog, specify a name and target directory for the retrieved file. Click Save to close this dialog and open the Enter Device Mapping Information dialog. 5. Enter the Device, Port and System numbers for the source device, and click OK to close the dialog and add the to the File list at the bottom of the Select Files To Transfer dialog. 6. Click Settings in the Communication Settings section at the bottom of the dialog to open the Communication Settings dialog and specify the communication settings for the source device. Note that in the Select Files For File Transfer dialog, communication settings apply to every file in the File list (since in this case the communication settings are relating to a system device that is the source for files you are receiving, not to individual files that may be sent to any of several devices in the system). 7. Click OK to close the Select Files For File Transfer dialog. The files you added should now appear in the Files To Receive queue of the Receive tab. 8. Repeat steps 2 - 7 to add files to retrieve from different system devices to the Files To Receive queue.
155
c. Click Edit Settings to specify the communication settings for the selected connection option. 3. Click OK to close the Communication Settings dialog. Configuring TCP/IP Communication Settings (Netlinx Only) With a Transfer selected in the Transfer List: 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Select NetLinx Master as the Platform Selection. 3. Select TCP/IP as the Transport Connection Option. 4. Click Edit Settings to open the TCP/IP Settings dialog. 5. Enter the TCP/IP Address of the master: a. Click New to open the New TCP/IP Setting dialog. b. Enter the new TCP/IP Address and (optional) Description in the text fields provided.
156
c. By default, the program is set to automatically ping the master controller to ensure availability. De-select this option if desired.
The Port should always be set to 1319 (default setting). Do not change the Port assignment.
d. Click OK to return to the Communication Settings dialog. 6. Click OK to save the new TCP/IP communication settings with the selected file. Configuring Serial Communication Settings With a Transfer selected in the Transfer List: 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Specify the Platform Selection (NetLinx Master or Axcess Master). 3. Select Serial as the Transport Connection Option. 4. Click Edit Settings to open the Serial Settings dialog. 5. Select a COM port and specify the communication settings for serial port communications. The default settings are:
Comm Port Baud Rate Data Bits Parity Stop Bits Flow Control COM1 38400 8 None 1 None
6. Click OK to return to the Communication Settings dialog. 7. Click OK to save the new Serial communication settings with the selected file. Configuring Modem Communication Settings With a Transfer selected in the Transfer List: 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Specify the Platform Selection (NetLinx Master or Axcess Master). 3. Select Modem as the Transport Connection Option. 4. Click Edit Settings to open the Modem Settings dialog. 5. Select a COM port and specify the communication settings for modem communications. The default settings are:
Comm Port Baud Rate Data Bits Parity COM1 38400 8 None
157
1 None
6. Click OK to return to the Communication Settings dialog. 7. Click OK to save the new Modem communication settings with the selected file. Configuring Virtual Netlinx Master Communication Settings (Netlinx Only) 1. Click the Edit command button, and select Communication Settings to open the Communication Settings dialog. 2. Select NetLinx Master as the Platform Selection. 3. Select Virtual NetLinx Master as the Transport Connection Option. 4. Click Edit Settings to access the Virtual NetLinx Master Settings dialog, which displays the System number (and IP address) of the Virtual NetLinx Master (default = 1). Assuming that the actual NetLinx Master is set to 0 (via the System Properties dialog - System ID field), this default setting will work. However, if you have designated any other number as the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.
5. Click OK to return to the Communication Settings dialog. 6. Click OK to save the new VNM communication settings with the selected file. Configuring the Panel For Virtual Netlinx Master TCP/IP Transfers If it is not already powered up and connected, apply power to the G4 panel and verify that it is connected to the LAN via the TCP/IP connector on the rear (or side) of the panel. 1. Press and hold the grey Front Setup Access button (below the touch screen) for 3 seconds to access the Setup page. 2. Press the Protected Setup button to access the Protected Setup page. 3. Use the on-screen keyboard to enter the password (the default password is 1988). 4. Press the System Connection button to access the System Connection Setup page. 5. Select Ethernet as the Master Connection. 6. Set the System Number to 0 (zero). 7. Select the Master URL / IP input box and enter the IP address of your PC.
To get your PC's IP address, select Start > Run and type cmd to open a DOS window. Then, enter ipconfig to display the IP address of your PC.
8. Press the Back button to return to the Protected Setup page and press the Reboot button to reboot the panel.
158
9. After several seconds, the panel should appear in the online device tree, listed as Virtual NetLinx Master. Once you can see the device online, you may transfer panel files directly to and from the G4 device.
159
Receiving Files Directly From A System Device (Serial Connections Only) To receive files directly from a system device (Serial connections only): 1. In the Receive tab, click to select a file in the Files to Receive queue. 2. Click Edit to open the Edit menu and select Device Mapping. This opens the Enter DPS dialog. 3. Enter the Device:Port:System (D:P:S) information for the selected file. 4. Check the Connect directly to the device - No Master... option. 5. Click OK.
160
Configuring the Touch Panel for Virtual NetLinx Master USB Transfers Connect the Panel to Your PC Via USB: 1. Apply power to the panel by plugging in the power supply. 2. Wait for the splash screen to disappear, then use a (Type A) USB cable to connect the panel to an available USB port on your PC. Plug the USB cable into the panel first, then connect to the PC. Configure the Panel for USB Virtual NetLinx Master Transfers: 1. Press and hold the grey Front Setup Access button (below the touch screen) for 3 seconds to access the Setup page. 2. Press the Protected Setup button to access the Protected Setup page. 3. Use the on-screen keyboard to enter the password (the default password is 1988). 4. Press the System Connection button to access the System Connection Setup page. 5. Select USB as the Master Connection. 6. Press the Back button to return to the Protected Setup page and press the Reboot button to reboot the panel. After several seconds, the panel should appear in the online device tree, listed as Virtual NetLinx Master. Once you can see the device online, you may transfer panel files directly to and from the G4 device. AMX USB Driver Information For USB Enabled G4 Panels The AMX USB driver (required to connect to USB-enabled G4 panels via USB) is included with the NetLinx Studio (as well as TPDesign4) installation programs. Once you have installed the latest version of either NetLinx Studio (v2.4 or higher) or TPD4 (v2.4 or higher), you should have the required USB driver. After having installed NetLinx Studio 2 (or TPDesign4), follow the steps below to ensure a valid USB connection to the G4 panels: 1. Power up the Panel without the USB cable connected to the panel. 2. Plug in the USB cable into the G4 panel. 3. You should see an USB icon show up in the System Tray. 4. Double click on the icon to bring up the list of USB devices (you should see the "AMX USB LAN LINK"" device in the list). 5. If the "Install Driver" dialog doesn't appear automatically, select the "Properties" button and then the "Update Driver" button. 6. When the Install Driver dialog does appear, click on the Next buttons, accepting all the default prompts. 7. The OS will complain about the fact that the driver you are installing/updating does not have a digital signature. This is acceptable, so select to continue the installation. 8. After installation is complete, you are ready to connect to the USB port of the G4 panel. a. Select Settings > Master Communication Settings to open the Master Communications Settings dialog.
161
b. Click the Communication Settings button to access the Communication Settings dialog. c. Select Virtual NetLinx Master as the Transport Connection Option. d. Click OK to close this dialog. e. Click OK to close the Master Communication Settings dialog. Configuring NetLinx Studio for Virtual NetLinx Master Transfers 1. Select Settings > Master Communications to open the Master Communication Settings dialog. 2. Make a selection in the Available Systems list to specify the scope of this communication setting: Select <No Active System-Default Settings> to set Virtual NetLinx Master as the default communication setting. To set Virtual NetLinx Master as the communication setting for a particular system in the active project, select one of the Systems listed under NetLinx Project. 3. Click Communication Settings to access the Communication Settings dialog. 4. Verify that NetLinx Master is selected as the Platform Selection, and select Virtual NetLinx Master as the Transport Connection Option. 5. Click Edit Settings to access the Virtual NetLinx Master Settings dialog. 6. The System Number field is set to 1 by default. Assuming that the actual NetLinx Master is set to 0 (via the System Properties dialog - System ID field), this default setting will work. However, if you have designated any other number as the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.
To use Virtual NetLinx Master to transfer TPDesign4 panel (.TP4) files, NetLinx Firmware (.KIT) files or IR files directly to a MVP-7500, MVP-8400 or NXD/T-CV7 panel via USB: 1. Select Tools > File Transfer to open the File Transfer dialog (open to the Send tab). 2. Click the Add button to open the Select Files for File Transfer dialog. 3. Click the Other tab, and select the type of file you want to transfer (only IRL/IRV, TP4 or IRN files can be transferred via a Virtual NetLinx Master connection). 4. Click the Add button. This invokes the Open dialog, where you can locate and select the file you want to transfer.
162
5. Select the desired file and click OK to close this dialog and invoke the Enter Device Mapping Information dialog. 6. Review the mapping information, and click OK to return to the Select Files for File Transfer dialog. 7. Click OK to return to the File Transfer dialog, where the new file should appear in the Files to Send list. 8. Click inside the checkbox to the left of the file you just added. Keep in mind that any files with a checkmark will be included in this transfer. Note that the Connection column indicates that the file you just added is using Virtual NetLinx Master. 9. Click the Send button to begin the transfer. Virtual NetLinx Master TCP/IP Transfers TPDesign4 v2.2 (or higher) supports direct connection to G4 panels via TCP/IP (and USB), for situations where the target panel is not connected to a NetLinx Master. In this situation, you can use your PC's Ethernet connection to connect directly to the panel, using your PC as a Virtual NetLinx Master. There are three basic steps to Virtual NetLinx Master TCP/IP file transfers: Configuring the Touch Panel for Virtual NetLinx Master TCP/IP Transfers Configuring NetLinx Studio for Virtual NetLinx Master TCP/IP Transfers Transferring Files Using a Virtual NetLinx Master TCP/IP Connection Configuring The Touch Panel For Virtual Netlinx Master Tcp/ip Transfers If it is not already powered up and connected, apply power to the G4 panel and verify that it is connected to the LAN via the TCP/IP connector on the rear (or side) of the panel. 1. Press and hold the grey Front Setup Access button (below the touch screen) for 3 seconds to access the Setup page. 2. Press the Protected Setup button to access the Protected Setup page. 3. Use the on-screen keyboard to enter the password (the default password is 1988). 4. Press the System Connection button to access the System Connection Setup page. 5. Select Ethernet as the Master Connection. 6. Set the System Number to 0 (zero). 7. Select the Master URL / IP input box and enter the IP address of your PC.
To get your PC's IP address, select Start > Run and type cmd to open a DOS window. Then, enter ipconfig to display the IP address of your PC.
8. Press the Back button to return to the Protected Setup page and press the Reboot button to reboot the panel.
163
9. After several seconds, the panel should appear in the online device tree, listed as Virtual NetLinx Master. Once you can see the device online, you may transfer panel files directly to and from the G4 device. Configuring Netlinx Studio For Virtual Netlinx Master Tcp/ip Transfers 1. Select Settings > Master Communication Settings to open the Master Communication Settings dialog. 2. Select the System that you want to set communication settings for (from the Available System(s) list. 3. Click the Communication Settings button to open the Communication Settings dialog. 4. Select [Virtual NetLinx Master] as the Transport Connection Option. 5. Click the Edit Settings button to access the Virtual NetLinx Master Settings dialog, which displays the System number of the Virtual NetLinx Master (default = 1). Assuming that the actual NetLinx Master is set to 0 (via the System Properties dialog - System ID field), this default setting will work. However, if you have designated any other number as the System ID, be sure to set this System Number to a different number than the System ID, to avoid a conflict with the actual NetLinx Master (range = 1-65535).
As indicated in the Virtual NetLinx Master dialog, changes made to the system number field will not take effect until all communications are stopped and restarted.
6. Click OK to close the Virtual NetLinx Master Settings dialog. 7. Click OK to close the Communication Settings dialog. Transferring Files Using A Virtual Netlinx Master Tcp/ip Connection
Verify that Virtual NetLinx Master is selected as the Transport Connection Option in the Communication Settings dialog.
To use Virtual NetLinx Master to transfer TPDesign4 panel (.TP4) files, NetLinx Firmware (.KIT) files or IR files directly to a MVP-7500, MVP-8400 or NXD/T-CV7 panel via TCP/IP: 1. Select Tools > File Transfer to open the File Transfer dialog (open to the Send tab). 2. Click the Add button to open the Select Files for File Transfer dialog. 3. Click the Other tab, and select the type of file you want to transfer (only IRL/IRV, TP4 or IRN files can be transferred via a Virtual NetLinx Master connection). 4. Click the Add button. This invokes the Open dialog, where you can locate and select the file you want to transfer. 5. Select the desired file and click OK to close this dialog and invoke the Enter Device Mapping Information dialog. 6. Review the mapping information, and click OK to return to the Select Files for File Transfer dialog. 7. Click OK to return to the File Transfer dialog, where the new file should appear in the Files to Send list.
164
8. Click inside the checkbox to the left of the file you just added. Keep in mind that any files with a checkmark will be included in this transfer. Note that the Connection column indicates that the file you just added is using Virtual NetLinx Master. 9. Click the Send button to begin the transfer.
Firmware Transfers
NetLinx Studio provides the ability to transfer KIT and TSK firmware files to a NetLinx or Axcess master controller. To send firmware files, select Tools > Firmware Transfers, then select either Send to NetLinx Device, or Send to Axcess Device from the sub-menu. Sending Firmware To a NetLinx Device (Kit File) Use the Firmware Transfers options in the Tools menu to update the firmware in NetLinx Master Controllers or System devices. NXI Master Controllers use Kit files for firmware upgrades. A Kit file (.KIT) is a package of several files, all of which are required to upgrade the firmware, and are available online via www.amx.com. The Online Device Tree (Online Tree tab of the Workspace Window) displays information about each online device, including the current firmware version. Before attempting to upgrade the firmware, you must have the appropriate Kit file for your NetLinx Master.
If for any reason your Kit file transfer should fail, continue to retry the transfer until you are successful. DO NOT reboot the Master, or change connections until the transfer is complete. Failure to complete this operation successfully may result in a factory repair of the Master.
To update NetLinx firmware: 1. Choose Tools > Firmware Transfers > Send to NetLinx Device to open the Send To NetLinx Device dialog. 2. Click the Browse button to navigate to the target directory (in the Browse For Folder dialog). The selected directory path is displayed in the Location text box. Assuming that the specified target directory contains one or more Kit files, the Kit files in the selected directory are displayed in the Files list box (with the file's last modified date and time). 3. Select the appropriate .KIT file from the list. 4. Enter the Device and System ID numbers for the target NetLinx Device in the Device and System text boxes. If the Kit file is determined to be specifically for the target Master, the Device number is forced to zero. If the Kit file is for an unspecified device, you must enter the correct Device ID number. You can use the Online Device Tree to determine the device's assigned ID. 5. Review the File, Connection, Address, and Target Device information before you send. Check the Reboot option (if required by the target device - see note below).
165
Click the Send button to send the selected KIT file to the specified device. You can watch the progress of the transfer in the "Send to NetLinx Device" dialog. When the transfer is finished, and the reboot is complete, press the Close button.
If the device is a NetLinx Master or NXI, then the Reboot option is valid. Other NetLinx devices need to be given the command to reboot (if they support it). Allow 20-30 seconds for NetLinx Masters to reboot. When the Master has rebooted, the Status LED on the front panel blinks once a second to indicate that it is functioning properly. Once it has rebooted, click OK.
Sending Firmware To An Axcess Device (Tsk File) Use the Firmware Transfers options in the Tools menu to update the firmware in Axcess Masters. Axcess Master Controllers use .TSK files for firmware upgrades. To update Axcess firmware: 1. Choose Tools > Firmware Transfers > Send To Axcess Device to open the Send To Axcess Device dialog. 2. Click the Browse button to navigate to the target directory (in the Browse For Folder dialog). The selected directory path is displayed in the Location text box. Assuming that the specified target directory contains one or more TSK files, the TSK files in the selected directory are displayed in the Files list box (with the file's last modification date and time). 3. Select the desired TSK file from the list. 4. Click the Query command button to populate the Devices list with a list of all Axcess devices currently online and capable of receiving the firmware. 5. Select the target AXlink device from the list. 6. Review the File, Connection, and Target Device information before you send. Click the Send button to send the selected TSK file to the specified device. You can watch the progress of the transfer in the "Send to Axcess Device" dialog. Once the TSK file has been transferred, the program prompts you to reboot the Master. Click Yes to reboot, and the program initiates the reboot sequence. When the Master has rebooted, the Status LED on the front panel of the Master blinks once a second to indicate that it is functioning properly. Once it has rebooted, click OK.
166
Enabling Security On Netlinx Masters Before you can enable/disable security on a NetLinx Master through NetLinx Studio, you must: Have loaded firmware in the target Master that supports security. This means that the Master must have NetLinx Master Firmware version 304 or higher to support this functionality. If your master does not have firmware loaded that supports security, the Master will not be secured (although it might appear to be in NetLinx Studio). Have security enabled on the target Master (via options in the Security tab of the Master's built-in interface). Refer to the NetLinx Master's documentation for details on enabling/ disabling security. You must first establish communication with the NetLinx Master in order to apply security (see Connecting to a NetLinx Master). 1. Once you are connected to the Master that you want to apply security to, select Settings > Master Communication Settings to access the Master Communication Settings dialog.
You can apply a default User Name and Password to the No active System - Default Settings option, so that as you create new NetLinx systems they will always require that User Name/Password combination.
167
2. Verify that you have connected to the desired Master by checking the information in displayed in the Configuration window. 3. Click the Communication Settings command button to access the Communication Settings dialog. 4. Click to select the Authentication Required option. This enables the User Name and Password command button. 5. Click the User Name and Password button to access the Master Controller User Name and Password dialog. 6. Enter the User Name and Password that will be required to establish communication with this Master (as long as the Authentication Required option is selected). The User Name and Password must each be between 4 and 20 characters long. 7. Click OK to save your changes and return to the Communication Settings dialog. 8. Click OK to save your changes and return to the Master Communication Settings dialog. Now that security has been applied to the Master, note that the Master Security Status icon in the Status Bar changes to indicate that the Master is "locked" (FIG. 29).
= Master is secured = Master is unsecured FIG. 29 Master Security Status icons
Master Controller User Name and Password Dialog Click the User Name and Password command button (in the Communication Settings dialog) to access the Master Controller User Name and Password dialog. Use this dialog to specify a User Name and a Password for the secured NetLinx Master (this option is only enabled if the Authentication Required option is enabled). The User Name and Password must each be between 4 and 20 characters long. Once these have been applied, any user must provide both correctly in order to establish communication with the Master. If the User Name and Password are not entered correctly, the program will indicate failed authentication status in the Connection Status and Reboot the Master Controllers dialogs. Applying Security To Individual File Transfers In addition to the security for NetLinx Masters that can be enabled per system, NetLinx Studio (v2.3 or higher) also allows you to apply security to individual file transfers via options in the File Transfer dialog. With security enabled on a file transfer operation, users will be required to provide the correct User Name and Password in order to transfer the file to/from the Master.
168
When you apply security to an individual file transfer operation (as described below), the individual file's security settings will be overridden by the security set for the target Master. For example, if the target Master already has security enabled (via the Authentication Required option in the Communication Settings for that Master), the user will have to provide the correct User Name and Password set for that Master, even if the File also requires a User Name and Password to successfully transfer to/ from the Master.
Before you can enable/disable NetLinx security on a File Transfer operation, you must verify the following: The target Master has been loaded with firmware that supports security. This means that the Master must have Master Firmware version 304 (or higher) to support this functionality. If your master does not have firmware loaded that supports security, the Master will not be secured (although it might appear to be in NetLinx Studio). Security has been enabled on the target Master (via options in the Security tab of the Master's built-in interface). Refer to the Master's documentation for details on enabling/ disabling security. To Apply Security To an Individual File Transfer Operation: 1. Queue up one or more files in the File Transfer dialog. 2. In the File Transfer dialog, click to select a file transfer from the list of files in the queue. 3. Click the Edit button and select Communication Settings from the drop-down menu to open the Communication Settings dialog. The settings you specify here are applied only to the selected File Transfer operation. 4. Click to select the Authentication Required option. 5. Click the User Name and Password button to open the Master Controller User Name and Password dialog, and enter the User Name and Password combination that the program will require in order to start this file transfer. Once security is applied, if the correct User Name and Password are not entered when prompted, NetLinx Studio will display an "Authentication Failure" message in the Error column of the File Transfer Status window, and the transfer will not complete. Connecting To a Secured Netlinx Master When connecting to a NetLinx Master that has security enabled, you will be required to enter a User Name and Password before you can connect. To establish a connection to a secured master, 1. Select Settings > Communication Settings to open the Communication Settings dialog and select NetLinx as the platform, and select a Transport Connection type. 2. Click Edit Settings to configure the selected transport type. 3. Click OK to save the TCP/IP, Serial or Modem settings (depending on the transport type selected). 4. Click the Authentication Required checkbox. This enables the User Name and Password button.
169
5. Click on User Name and Password to enter the User Name and Password that are set for this NetLinx Master (in the Master Controller User Name and Password dialog). These are case sensitive. 6. Click OK to close the Master Controller User Name and Password dialog. 7. Click OK to close the Communication Settings dialog. 8. Click OK to close the Master Communication Settings dialog. At this point you should be able to connect to the Master. If you don't connect: Verify that the master is set for ICSP Connectivity, with Require Encryption enabled (via the Master's built-in interface). Refer to the Master's documentation for details on enabling/disabling security.
Note: Internal modes were tested only for calling capabilities. External Modems Manufacturer Boca Hayes Hayes MultiTech Model - External 14.4 V.32b #MV.34xx Accura 56k #03328-A Accura 144+Fax 144 #5300AM MultiModem 19.2k Data/Fax --- Windows Operating System --95 X ? X ? ? ? CA ? ? ? 98 X C X X C< CA CA ? ? CA ME X C X ? ? ? CA ? ? C NT X C C A ? CA CA CA ? CA 2000 X C X A X CA CA ? ? C XP X ? X ? ? ? ? ? ? ?
Practical Peripherals PM288MT II v.34 - 28K US Robotics US Robotics US Robotics US Robotics Zoom 56k Fax v.90 #USR5686D Sportster56k Fax #USR5686-03 Sportster 33.6 - #0413 Sportster 14.4 Fax CJE-0235 Fax 56kx Dualmode #2949L
C = Call - means that the FileTransfer program can get the modem to call another modem and establish communications. A = Answer - means that the FileTransfer program can get the modem to answer inbound calls and establish communications with the master controller. X = Not supported. < = Less 100% reliable.
170
Software History Application This option allows you to specify wether to automatically close the AMX Software History Application when you exit NetLinx Studio, or to leave it running (default = Close when NetLinx Studio Exits). Recent File List Size This field allows you to change the size of the recent file list, displayed at the bottom of the File menu (range = 1-9),
171
Assigning a two-dimensional array to a one-dimensional array, or vice versa. Assigning the result of a function that returns an array type to a non-array variable or to a two-dimensional array variable (for example, X = ITOA(12), where X is a nonarray variable or two-dimensional array variable). Assigning the result of a function that returns a non-array type to a one- or twodimensional array variable (for example, X = ATOI('AMX'), where X is a one- or twodimensional array variable).
This message is a warning and not an error, because X = ITOA(12) works correctly when X is a simple variable, since the result is a single value between and 65,535. Variable not used - This warning occurs at the end of compilation for each variable that was declared but never used. Define_Call not used - This warning occurs at the end of program compilation for each DEFINE_CALL subroutine that was declared but never used. Too many nested levels - This warning appears if there is a large amount of nesting in the program. This can happen with a long chain of IF...ELSE IF statements. The solution is to use the SELECT...ACTIVE set of statements. Long_While in While - This warning occurs if the compiler finds a LONG_WHILE or MEDIUM_WHILE inside a block of code following a WHILE keyword. This warning exists because the WHILE command has a 1/2 second timeout period, and the LONG_WHILE and MEDIUM_WHILE keywords do not. This could create a hard-to-find logic error. The solution is to change the WHILE to a LONG_WHILE to fix this problem. Separate Define Call list - Check to store all DEFINE_CALL subroutines in a separate section of the Master Controller memory than the DEFINE_PROGRAM section. This effectively allows the code size of a program to reach 128K (64K for the DEFINE_CALLS and 64K for the DEFINE_PROGRAM section). Source Options - Click these checkboxes to enable the following build (compile) options: Build with Source - Check to compile the source code with the executable code so that you may later retrieve the source code from the device you send the compiled code to. If Build with Source is disabled, only the executable code is sent when the file is transferred to the master. Build With Password Protection - Select this option to apply a password to the Source file. Once applied, you cannot retrieve the source code from the Master Controller unless you provide the correct password. Select the Change button to edit the password (via the Change Password dialog). A password must be at least 6 characters in length (maximum of 20 characters).
When building with source, only the files needed for the compilation process are compressed. Though the APW may contain many files, if the source file only uses one axi file, then only 2 files will be compressed.
Directories - Click to open the directories menu, where you select the directories to point the compiler to, by file type. Once a directory type is selected, the directory list is
172
populated with the directories of that type that have been mapped. There are a maximum of 100 directories that can be entered for each type. Select Include Files to select or create the directory that the compiler will look for Include files in. Select Library Files to select or create the directory that the compiler will look for (IR) Library files in.
Build With Password Protection - Select this option to apply a password to the Source file. Once applied, you cannot retrieve the source code from the Master Controller unless you provide the correct password. Select the Change button to edit the password (via the Change Password dialog). A password must be at least 6 characters in length (maximum of 20 characters).
173
Window Background String Margin Operator Number Float (Floating Point Number) Device Constant Variable Type Default Text Selected Text Caret Function Names Stack/Param Variables Code-Fold Margin Code-Fold Plus Code-Fold Minus Window Background Margin
174
Background Color - This is the background color setting for the selected Item. Click the down arrow to select a different color from a palette.
Click the More Colors button on the color palette to access the advanced color selection palette.
Apply to All - Use this option to apply the selected background color to all items in the Selections list. Text Color - This is the text color setting for the selected Item. Click the down arrow to select a different color from a palette.
Click the More Colors button on the color palette to access the advanced color selection palette.
Bold/Italic - Use these checkboxes to specify the text style setting for the selected Item. Font - The Selection button opens the Font dialog, where you can select the font, font style (regular, italic, bold) and font size to be displayed in the Source Code Editor window. Check Only Fixed Pitch Fonts to limit the font selection list to include only fixedpitch fonts (such as Courier or Terminal). Printer - These options let you control how to best print source files that use colorcoding: Print Black on White: Print all text as black on a white background. Print Color on White: Print all text using the same colors displayed in the Source Code Editor window, on a white background. Print Color on White but Invert Light Colors: This is the same as "Print Color on White", except that light colors are automatically be inverted for better readability on a white background. Display options - These options offer more display-oriented options for the Source Code Editor window: Show Line Numbers - This option displays line numbers along the left-hand edge of the Source Code Editor window (default = enabled). Enable AutoComplete/Suggest - With this option enabled, the application examines the first few characters in a variable name, device name or a reserved identifier, and automatically finishes typing it for you (default = enabled). In some cases, the program will suggest the rest of the word. With option enabled, the program will automatically finish typing many common terms for you, to save time and effort. Click here for more details.
175
Enable Indentation Guides - This option causes the program to draw vertical lines indicating the tab stops in the Source Code Editor window (default = enabled). Note that indentation guides only appear if there are tabs present in the code. Enable Call Tips - This option enables the Call Tips function. Call Tips assist you with adding declared functions by displaying a list of parameters that are valid for the particular function you are adding. Enable Code Folding - This option allows you to "fold-up" each section of code in the Source Code Editor (default = enabled). With this option enabled, a grey bar is displayed in the Editor window, between the Line Numbers (if that option is enabled) and the actual code. Contained within this grey bar are red minus symbols (-) next to the first line of each section of code. Click on the minus symbol to "fold" (collapse) that section. When a section is folded, the minus symbol is replaced by a blue plus symbol (+). Click the plus symbol to expand the section for viewing/ editing. Use the Code-Fold Margin, Code-Fold Plus and Code-Fold Minus options in the Syntax Highlighting section to customize the color settings for code-folding (select Axcess/NetLinx Source as the Document Type).
Additionally, you can expand or collapse all fold levels in the active file via the Expand All Folded Levels and Collapse All Folded Levels commands in the Edit menu.
Enable UTF-8 format to display Hebrew, Arabic, Cyrillic and Han characters - This option allows these special character sets to be displayed in the Source Code Editor windows. You must close and re-open all files in order for this option to take effect. Tabs and Indentation Preferences - This set of options allows you to specify the following indentation preferences: Set tab stops every X characters - Use this option to specify the size (in number of characters) of the tab stops in the Source Code Editor window (default = 4). Each line contains a number of tab stops placed at regular intervals (for example, every 8 characters). When you press the tab key, the cursor or insertion point jumps to the next tab stop. Changing this value changes the interval of the tab stops. Indent with X characters - This value sets the number of space characters to be inserted by auto-indentation (default = 10). Enable Auto-Indentation - This option causes the program to automatically indent lines that occur after an indented line. When indenting, text is prepended the amount of spacing specified in the Indent with X Characters field (see above). Clipboard Text Buffer - These options allow you to define the number of clipboard buffer entries and the maximum width to display (via the Clipboard Buffers option in the Edit menu): Max Items - You can have a maximum of 30 clip-board buffer items (default = 20). Max Display Width - You can set the maximum display width to up to 80 characters (default = 50). Clear Text Buffer History - Clears all the clipboard text items from the list.
176
Importing/Exporting Editor Preferences Use the Import Editor Preferences and Export Editor Preferences options in the Tools menu to import/export the current Source Code Editor preferences, as they are defined in the Editor tab of the Preferences dialog: To export the current Editor Preferences, as a *.EPX file: 1. Select Tools > Export Editor Preferences. 2. In the Save As dialog, specify a name and target directory for the resulting *.EPX file, and click OK. To import an existing *.EPX file: 1. Select Tools > Import Editor Preferences. 2. The program will prompt you to acknowledge that the imported settings will overwrite your current Editor preferences - click OK to proceed. 3. In the Open dialog, locate and select the desired *.EPX file, and click Open. The Editor tab of the Preferences dialog should now reflect the preferences specified in the imported *.EPX file.
177
Creating Custom Toolbars Use the options on the Commands tab of the Preferences dialog to create custom toolbars: 1. Select Settings > Preferences to open the Preferences dialog. 2. In the Toolbars tab, click New. 3. Enter a name in the Toolbar Name dialog, and click OK. 4. The new toolbar appears in the Toolbars list, and the new (empty) toolbar appears within the Toolbars list area of this tab. 5. Click and drag the new toolbar into the work area. 6. Populate the toolbar with command buttons as desired.
178
arrow button (to the right of the Arguments text box) to access a list of arguments supported by the specified application.
To use arguments, you need to be familiar with the capabilities of the application you are adding. Consult the program's manufacturer for details on argument support.
Initial Directory - This option allows you to specify the initial directory for the specified application to open by default when the program is launched. Adding/Removing Application Shortcuts In The Tools Menu Use the options on the Tools tab of the Preferences dialog to add/remove shortcuts to external applications in the Tools menu: 1. Select Settings > Preferences to open the Preferences dialog. 2. In the Tools tab, click the New button to create an empty text field in the Menu Contents list. 3. Enter a name for the application. 4. Click the browse button ( ) to locate and select the application's .EXE file. The directory path is displayed in the Command text box. 5. Specify any Arguments, if necessary. Click the right-arrow button to select from a list of all applicable arguments. 6. Specify an Initial Directory, if necessary. Click the right-arrow button to select an initial directory option, or select Browse to specify an initial directory via the Browse For Folder dialog. 7. Click Close to close the Preferences dialog. 8. The new shortcut should appear at the bottom of the Tools menu.
179
Assign - Click to assign the newly specified keyboard shortcut to the selected command. This button is only enabled if a command is selected, and new shortcut keys have been entered in the Press New Shortcut Key text box. Remove - With a command selected (in the Commands list), click Remove to remove the associated keyboard shortcut. Reset All - Click to reset all keyboard shortcuts to the defaults. Creating Custom Shortcut Keys Use the options on the Keyboard tab of the Preferences dialog to set custom keyboard accelerators (shortcut keys/key combinations) for often-used commands: 1. Select Settings > Preferences to open the Preferences dialog. 2. In the Keyboard tab, select the command Category that contains the command that you want to create a new shortcut key for. 3. In the Commands list, select the command that you want to create a shortcut key for. If a shortcut key is already associated with the selected command, it is indicated in the Current Keys text box. 4. Place the cursor in the Press New Shortcut Key text box, and enter the desired shortcut key or key combination. If the new shortcut key is already assigned to another command, it is indicated directly below the Press New Shortcut Key text box, and the Assign button will be disabled to prevent duplicate assignments. 5. Click Assign to assign the new shortcut key to the selected command.
180
Text View
Customizing The Menus Use the options on the Commands tab of the Preferences dialog to customize menus, and reset the menus to their original default state. To customize a menu: 1. Select Settings > Preferences to open the Preferences dialog. 2. Open the Commands tab. 3. Open a menu (in the main Menu bar). To add a command: Select a command category and a select the command you want to add to the menu. Click and drag the command out of the Commands list and into the desired position in the open menu. To remove a command: Select a command from the open menu, and click and drag it outside of the menu. 4. Click Close to close the Preferences dialog.
181
Diagnostics View - Use this set of options to set default display preferences for the Diagnostics tab of the Output Display Window. Display Line Numbers - Toggles the display of line numbers in system diagnostics displays (default = enabled). Display Time Stamp - Toggles the display of time stamps in system diagnostics displays in one-second increments (default = enabled). When enabled, the Display Milliseconds option causes diagnostics time stamps to be displayed in milliseconds (default = disabled). Display Control Codes as - Converts unprintable characters (i.e. Control Codes) into either Hexadecimal or Decimal values within the message (default = Hex Values).
The Line Number, Time Stamp and Control Code display options will only take affect after you stop and then start the asynchronous notifications/diagnostics message feeds.
Buffer File Options - Use the text box to specify the total size of the two files that are used by the program to buffer the asynchronous notification and system diagnostic messages. The number specified here will be divided evenly between the two files. The range is 2 - 500 MB (default = 10). If you have less than 500 MB free on your disk, then the upper range value will be adjusted according to the amount of free space on your
182
disk. Your TEMP or TMP environment variables are used to determined the drive used for the two buffer files. Available Disc Space on drive c - this read-only field indicates the current amount of free disc space available on your local hard disc (c:). Use this number as reference if you are increasing the buffer file size.
183
184
Troubleshooting
Troubleshooting
NetLinx Debugger Not Stopping On A Breakpoint
Symptoms A breakpoint is set on a line of code, but the code does not stop execution on this line. The line of code in question contains a SEND_COMMAND, SEND_STRING, or SEND_LEVEL. Cause The debugger will not stop on a line of code that sends a command, string, or level because of a device declared as an integer instead of a DEVICE:PORT:SYSTEM (D:P:S) structure. Example:
DEFINE_DEVICE VCR = 2 TP = 128 DEFINE_EVENT BUTTON_EVENT[TP,101] { PUSH: { SEND_COMMAND VCR," 'SP', 9" //The debugger will not stop if you put a breakpoint here } }
Resolution Declare devices using the full D:P:S structure. In fact, you should always do this in Netlinx. Example:
DEFINE_DEVICE VCR = 2:1:0 TP = 128:1:0 DEFINE_EVENT BUTTON_EVENT[TP,101] { PUSH: { SEND_COMMAND VCR," 'SP', 9" //The debugger will now stop if you put a breakpoint here } }
185
Troubleshooting
This error is cause by passing a parameter that is not of type DEV to the DEVICE_ID keyword. This usually occurs when converting AXCESS code to Netlinx. To fix this error, try the following: Look for all references to the DEVICE_ID function Make sure the value passed to the function is of type DEV. If this appears inside a DEFINE_CALL or DEFINE_FUNCTION and a parameter is passed to the DEVICE_ID function, make sure that parameter is of type DEV.
186
Index
187
033-004-2713 11/05 2005 AMX Corporation. All rights reserved. AMX, the AMX logo, the building icon, the home icon, and the light bulb icon are all trademarks of AMX Corporation. *In Canada doing business as Panja Inc.
AMX reserves the right to alter specifications without notice at any time.
ARGENTINA AUSTRALIA BELGIUM BRAZIL CANADA CHINA ENGLAND FRANCE GERMANY GREECE HONG KONG INDIA INDONESIA ITALY JAPAN LEBANON MALAYSIA MEXICO NETHERLANDS NEW ZEALAND PHILIPPINES PORTUGAL RUSSIA SINGAPORE SPAIN SWITZERLAND THAILAND TURKEY USA
ATLANTA BOSTON CHICAGO CLEVELAND DALLAS DENVER INDIANAPOLIS LOS ANGELES MINNEAPOLIS PHILADELPHIA PHOENIX PORTLAND SPOKANE TAMPA
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