{"id":1481,"date":"2019-09-18T11:05:04","date_gmt":"2019-09-18T18:05:04","guid":{"rendered":"https:\/\/portal.staylinked.com\/sl\/kb\/?post_type=ht_kb&p=1481"},"modified":"2025-04-07T11:43:45","modified_gmt":"2025-04-07T18:43:45","slug":"device-naming","status":"publish","type":"ht_kb","link":"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/","title":{"rendered":"Device Naming and Device-Specific Variables"},"content":{"rendered":"\n

Workstation names can have a wide range of uses. There are several options to name or provide a custom variable to each device.<\/p>\n\n\n\n

Assigning workstation names allows the value to appear in the Administrator as displayed here:<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Lookup XML<\/h2>\n\n\n\n

Originally created for use with IBM systems as virtual workstation names, the Device Group option for prefix and suffix naming was highly limited. This was expanded with the availability of the [deviceid] variable that was configurable on each device, but still only offered one device-specific defined variable to work with. With StayLinked Server v15.5 and newer, there is now support for a wide range of device-specific variables, but server-managed in traditional StayLinked fashion. This server-side feature is called Lookup which utilizes an XML configuration file on the server to add additional variable options to each device based on the Unique Identifier<\/a>.<\/p>\n\n\n\n

With the initial release in 15.5, this XML file must be manually created. The best ways to find device Unique Identifiers is within the Usage Tracking<\/a> feature, the StayLinkedManager Log as described in Session Persistence<\/a>, or by double-clicking a session in the connections list to review the connection details<\/a>.<\/p>\n\n\n\n

With the release of v16.1, this XML file can now utilize a third lookup option to select related variables. This new lookup entry is call \"name\". Used with a 'key' entry and a name variable.[lookup name,value]. Including a key= within individual entries in the table will bypass the general \"lookups key=\" in the table setup\/properties before the table contents as the global\/general lookup key. In short, a custom key can be specified on any line, and then variables can be used to return the desired value. More information is found below in the 'Nested Lookup Values' section.<\/p>\n\n\n\n

LOOKUP.XML Formatting<\/h3>\n\n\n\n

Within a lookups node, each 'lu' entry will refer to the MAC address or application ID as reported by the OS used by StayLinked for that device. The lookup can also use the [deviceid] as defined on the device, with the lookup value define in the third line below as lookups key= accepting either devid or mac.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Substituting Session Values<\/h3>\n\n\n\n

To perform the substitutions from this lookup table, you can use the new custom mnemonic [lookup %%%%%] where the %%%%% represents the variable name. The server will replace the [lookup %%%%%] mnemonic with the variable value if found. If the name-value pair is not found, the mnemonic will be replaced by \"\" (null).<\/p>\n\n\n\n

For example, if the device with UID 3833510EF881 <\/strong>connects to the server and a script or event triggers the [lookup user<\/strong>] variable, the value john <\/strong>would be returned.<\/p>\n\n\n\n

With the release of v16.1, the key can now be combined with a secondary value called 'name'. Supporting the enhanced lookup, when the substitution mnemonic [lookup key,name] is used, the key will be used for finding the \u2018name\u2019 and the result will be the \u2018value\u2019 for that lookup entry. This mnemonic could then be placed in any Administrator section to return the value specific to that lookup entry. This option allows for a secondary key to be under in the event that the first key is not enough to locate the entry.<\/p>\n\n\n\n

v16.1 Nested Lookup Examples<\/strong><\/p>\n\n\n\n

In the example 'lookup.xml' file shown below:<\/p>\n\n\n\n

  • When the client\u2019s Device ID is 'WH010099', the [lookup user] substitution mnemonic will return 'mark'.<\/li>
  • When the device\u2019s MAC Address is '2229AAF3F513', the [lookup [device_mac],MERLOT] substitution mnemonic will return '01234567'.<\/li>
  • When the client\u2019s Device Type is MC93, the [lookup [devicetype], manufacturer] substitution mnemonic will return 'Zebra'.<\/li>
  • When the client\u2019s Device ID is '2229AAF3F5', the [lookup [deviceid], TelnetPort] substitution mnemonic will return '28'.<\/li><\/ul>\n\n\n\n

    sample lookup.xml<\/strong>
    <?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
    <!–lookupv10 DTD–><\/em>
    <lookups key=\"devid\">
    <lu mac=\"\" devid=\"WH010099\" name=\"user\">mark<\/lu>
    <lu key=\"2229AAF3F513\" name=\"MERLOT\">01234567<\/lu>
    <lu key=\"MC93\" name=\"manufacturer\">Zebra<\/lu>
    <lu key=\"2229AAF3F5\" name=\"TelnetPort\">28<\/lu><\/lookups><\/p>\n\n\n\n

    Once created, this file must be placed in the Config subdirectory of the StayLinked Server.<\/strong> This is the same file location as all other configuration files and does not need to be placed in the StayLinked Administrator folder structure. the initial release of this feature does not <\/strong>include this file in configuration export or import.<\/p>\n\n\n\n

    When changes to this file are made, the server process must be restarted or the configuration must be reloaded. Reloading setting is accomplished by placing an empty file in the config folder of the server named reload.xml.<\/strong> This file will get automatically cleaned up when the next session is started on the server, reloading all configuration.<\/p>\n\n\n\n

    Assigning Workstation Names by Device<\/h2>\n\n\n\n

    Prior to server version 15.5, there were only two methods of naming devices, [deviceid] or by configuring a pre+suffix value to build a name using part of the IP address. Prefix+suffix should only be used in networks with static network addressing.<\/p>\n\n\n\n

    Using [deviceid]<\/h3>\n\n\n\n

    The first step is to assign each device the name it will use. This is accomplished in one of a few different ways. On many Windows-based devices or when using Android Client build 222 or higher, the Client can use the device or 'node' name entered into the operating system. Since this provides no control over persistence, StayLinked Clients also offer several methods of assigning the name within the Client configuration.<\/p>\n\n\n\n

    \"\"<\/figure><\/div>\n\n\n\n

    Option 1: On the device itself under the Host > Configure > Server is the \u2018Use Device ID\u2019 option. This enables the field to enter the custom name for this device. Devices configured for \u2018Max Connections\u2019 of more than one will display a table that allows for a name to be assigned to each session.<\/p>\n\n\n\n

    Notes<\/p>\n\n\n\n

    1. If the Host menu is not visible, Android devices can re-display the menu bar with a single long tap. Other device operating systems using \u2018full screen mode\u2019 will need to have this option disabled or use one of the other options listed below.<\/li>
    2. Host options are not available while in a session or attempting to connect to the server.<\/li>
    3. Some hosts are case sensitive, and we recommend using all upper-case characters for workstation names.<\/li>
    4. Entering the value OSNAME in this device ID value can pull the device's name in the Android OS on most Android versions.<\/li><\/ol>\n\n\n\n

      Option 2: The value can also be populated directly in the client configuration file called staylink.ini using a text editor or from the Administrator\u2019s connections list under; the right click menu > Commands > Edit Client INI. Add or set the entry for device_id= value to your desired workstation name.<\/p>\n\n\n\n

      \"\"<\/figure><\/div>\n\n\n\n

      Option 3: Using the Administrator section for Client Configuration > Client Settings you can add the setting for Server > Workstation ID and set the unique value based on the device MAC or IP address.<\/p>\n\n\n\n

      Option 4: This same setting is also available under the Administrator section for Client Configuration > Scan2Configure Profiles. This allows you to create barcodes that can be scanned into the client scan test in order to set the workstation name.<\/p>\n\n\n\n

      The next step to using a device-assigned name is by configuring the device group to gather the value from each connection. This is done in the Administrator section for Emulation Settings > Device Groups > double click your device group and type [deviceid] into the \u2018Device Name Prefix\u2019 as displayed here:<\/p>\n\n\n\n

      \"\"<\/figure>\n\n\n\n

      Once all configuration is in place, any new sessions falling into your device group will display the workstation name in the connections list of the Administrator. If you do not see your desired name, make sure the device is falling into the proper device group and that it has started a new session. Refreshing the connections list will show the session start time, which should be after you have saved your configuration changes.<\/p>\n\n\n\n

      Using [prompt_user]<\/h3>\n\n\n\n

      Setting devices with [prompt_user] will cause the client to present a prompt to users on first launch. This value is placed in the configuration and will not prompt the user again unless the value is reset. <\/p>\n\n\n\n

      \"\"<\/figure>\n\n\n\n

      Note that using this mnemonic allows for customization of the message, for example: [prompt_user Custom message here] would user 'Custom message here' as the prompt message.<\/p>\n\n\n\n

      \"\"<\/figure>\n\n\n\n
      \"\"<\/figure>\n\n\n\n

      Using Device Names in StayLinked Scripting<\/h2>\n\n\n\n

      Once the device name variable has been established for a connection, it can be used in various StayLinked scripts by using the mnemonic [deviceid] or [devicename]. This will work for all emulation types and is not limited to 5250 virtual devices. Connections can be easily identified in the Administrator\u2019s connections list by matching inventory tags or device labels to this value.<\/p>\n\n\n\n

      Automatically Constructing Device Names by IP<\/h2>\n\n\n\n

      Entering any value other than [deviceid] in the device name prefix will result in a name built dynamically using the prefix plus the end of the IP address as a suffix. Naming is configured by device group to identify groupings by device type, device model, or network segment. By example, devices connecting from an Atlanta location might be given an \u2018ATLXXX\u2019 style name. Vehicle mount units might be given a \u2018VMUXXX\u2019 style name. Whatever naming you choose for your environment, StayLinked will use the configuration options from the appropriate device group.<\/p>\n\n\n\n

      \"\"<\/figure><\/div>\n\n\n\n

      The \u2018Suffix Octets\u2019 option determines how many portions of the IP address will be added to your suffix.<\/p>\n\n\n\n

      \"\"<\/figure><\/div>\n\n\n\n

      Using a prefix of NULL will return a value of the suffix only, with no prefix. If you do not use the decimal suffix option, the suffix will return a hexadecimal value of two-digits per octet.<\/p>\n\n\n\n

      Leaving the Device Name Prefix blank will default to \u2018automatic\u2019 naming. For IBMi, this will use the server\u2019s options for QAUTOCFG to provide a QPADEVXXXX style workstation ID.<\/p>\n\n\n\n

      Starting in v15.2, suffix octets can now be configured for public and private IP address use. Please review the Administrator Guide section on Device Group Administration for details on these options if your devices are using a NAT'd network address.<\/p>\n\n\n\n

      Dynamic Device Naming and DHCP<\/h3>\n\n\n\n

      If your devices use a Dynamic Host Configuration Protocol (DHCP, or server assigned) address, they have the possibility of changing network address while sessions are still active. When using the IP address as part of the device name, devices can hold ownership of a name longer than they own the network address. This can often cause naming conflicts. The more devices you own, the more difficult it becomes to create static IP address reservations in a DHCP scope, or manually assign names for each individual device. Essentially, when using device names, you will need to manage either the network address, or the unique name on each device.<\/p>\n\n\n\n

      Our two recommendations when using DHCP with prefix + suffix naming include:<\/p>\n\n\n\n

      1. Keep your DHCP lease as long as possible, preferably at least 3 days. The faster your devices acquire network addresses, the more likely they are to change address.<\/li>
      2. Use a telnet inactivity timeout to terminate inactive sessions. This can be done as a host property in the StayLinked Telnet Host Entry if your application or telnet host does not provide this feature. Inactive sessions can hold on to names that might be needed by active devices.<\/li><\/ol>\n\n\n\n

        IBM i ~ Virtual Devices and Subsystems<\/h2>\n\n\n\n

        Originally developed for IBM i (aka. OS\/400, i5\/OS), StayLinked provides several options for creating virtual workstation IDs. For IBM i, this can be a critical method of getting devices to the desired application screens.<\/p>\n\n\n\n

        Using workstation names provided by an emulator, IBM i systems can provide different work environments for various connection types. This can be especially helpful when working with partial displays, or devices that have a small display that can\u2019t effectively display the entire emulation screen.<\/p>\n\n\n\n

        The system is based on adding workstation entries to the subsystem description. While the description will display workstation entries, it does not work as an interface to add and remove entries. Once an entry is added, it cannot be adjusted, but must be removed and then re-added with the desired values. Using a workstation allocation value of *SIGNON will allow use of this subsystem for qualified workstations, while a value of *ENTER will prevent qualified workstations.<\/p>\n\n\n\n

        Important ~ When directing workstations to a specific subsystem, it is important to include the parameters in the desired subsystem and<\/u><\/strong> exclude them from other subsystems. The operating system may sometimes attach a device to any interactive subsystem that does not contain an exclusion but will typically provide connections to preferred subsystems.<\/p>\n\n\n\n

        There are several useful commands when configuring IBM i for workstation connection parameters:<\/p>\n\n\n\n

        WRKSBSD<\/strong>: Work with Subsystem Description. This command allows you to review the various subsystem configuration options. Using option 5 to display, select option 4 \u2018Work station name entries\u2019 to display each workstation value specified for the selected subsystem.<\/p>\n\n\n\n

        WRKCFGSTS<\/strong>: Work Configuration Status. This command is critical for reviewing the active and available workstation entries. Devices that have been varied off for security reasons must be re-enabled before the workstation will become available on the server. When using the Vary On option, the device will be set to Vary On Pending until the workstation description is used again.<\/p>\n\n\n\n

        ADDWSE<\/strong>: Add Workstation Entry. Use this command to add entries for workstation descriptions to a target subsystem. Use a value of *SIGNON to allow connections, and *ENTER to disable connections.<\/p>\n\n\n\n

        RMVWSE<\/strong>: Remove Workstation Entry. This command will remove workstation entries from a subsystem description.<\/p>\n\n\n\n

        Avoiding Duplicate Workstation IDs<\/h3>\n\n\n\n
        \"\"<\/figure><\/div>\n\n\n\n

        StayLinked server build 142 and newer includes a setting to help avoid errors related to workstation names. This setting is on by default and can be disabled as an emulation property in the telnet host entry. The feature adds a character to the end of the requested name until an available name is found. This option is available to 5250 emulation hosts only and will not appear in the options for VT or 3270 hosts.<\/p>\n\n\n\n

        <\/p>\n\n\n\n

        <\/p>\n\n\n\n

        <\/p>\n\n\n\n

        Possible Error Messages<\/h3>\n\n\n\n

        During the use of StayLinked, your users may be presented with various error messages. These messages can provide information when the server OS is unable to provide the requested device name for your device. In each of these cases, IBM i has rejected the requested workstation name. These messages are only available for 5250 emulation.<\/p>\n\n\n\n

        AUTOCFG IS OFF<\/strong><\/p>\n\n\n\n

        This message is returned when the server is reporting that it is unable to dynamically create the requested virtual device name. This may be caused if the IBM system value QAUTOVRT has reached a limit on the maximum number of virtual terminals, or if it cannot create or use the requested WSID for this session.<\/p>\n\n\n\n

        WSID VARIED OFF<\/strong><\/p>\n\n\n\n

        The virtual device name already exists and is in a varied off status. This is typically caused by too many invalid sign-on attempts. StayLinked cannot automatically clear this status. See the WRKCFGSTS command in the next section.<\/p>\n\n\n\n

        WSID IS IN USE<\/strong><\/p>\n\n\n\n

        The virtual device name has already been allocated to another interactive session.<\/p>\n\n\n\n

        WSID TIMEOUT<\/strong><\/p>\n\n\n\n

        This is a general message that will be retuned for many different possible reasons. On servers older than build 138, the WSID timeout will be used for all of the reasons listed above.<\/p>\n\n\n\n

        The first step to resolving any of the messages above is to determine the virtual device name being requested for the session. This value appears in the device name column of the connections list, along with the error in the status column. Using the OS400 command:<\/p>\n\n\n\n

        WRKCFGSTS CFGTYPE(*DEV)<\/em>, you can find the device description to check the status.<\/p>\n\n\n\n

        \"\"<\/figure>\n","protected":false},"excerpt":{"rendered":"

        Workstation names can have a wide range of uses. There are several options to name or provide a custom variable to each device. Assigning workstation names allows the value to appear in the Administrator as displayed here: Lookup XML Originally created for use with IBM systems as virtual workstation names,…<\/p>\n","protected":false},"author":7,"comment_status":"open","ping_status":"closed","template":"","format":"standard","meta":[],"ht-kb-category":[57],"ht-kb-tag":[43],"yoast_head":"\nDevice Naming and Device-Specific Variables – StayLinked<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.staylinked.com\/knowledge-base\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Device Naming and Device-Specific Variables – StayLinked\" \/>\n<meta property=\"og:description\" content=\"Workstation names can have a wide range of uses. There are several options to name or provide a custom variable to each device. Assigning workstation names allows the value to appear in the Administrator as displayed here: Lookup XML Originally created for use with IBM systems as virtual workstation names,...\" \/>\n<meta property=\"og:url\" content=\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/\" \/>\n<meta property=\"og:site_name\" content=\"StayLinked\" \/>\n<meta property=\"article:modified_time\" content=\"2025-04-07T18:43:45+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/09\/Device-Naming-0.jpg\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"14 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebSite\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/#website\",\"url\":\"https:\/\/portal.staylinked.com\/sl\/kb\/\",\"name\":\"StayLinked Knowledge Base\",\"description\":\"Partner Portal Resources and Support\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":\"https:\/\/portal.staylinked.com\/sl\/kb\/?s={search_term_string}\",\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"ImageObject\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/#primaryimage\",\"inLanguage\":\"en-US\",\"url\":\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/09\/Device-Naming-0.jpg\",\"contentUrl\":\"https:\/\/portal.staylinked.com\/sl\/kb\/wp-content\/uploads\/2019\/09\/Device-Naming-0.jpg\",\"width\":910,\"height\":323},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/#webpage\",\"url\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/\",\"name\":\"Device Naming and Device-Specific Variables – StayLinked\",\"isPartOf\":{\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/#primaryimage\"},\"datePublished\":\"2019-09-18T18:05:04+00:00\",\"dateModified\":\"2025-04-07T18:43:45+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/device-naming\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/portal.staylinked.com\/sl\/kb\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Articles\",\"item\":\"https:\/\/portal.staylinked.com\/sl\/kb\/knowledge-base\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Device Naming and Device-Specific Variables\"}]}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","_links":{"self":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb\/1481"}],"collection":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb"}],"about":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/types\/ht_kb"}],"author":[{"embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/comments?post=1481"}],"version-history":[{"count":11,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb\/1481\/revisions"}],"predecessor-version":[{"id":5639,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb\/1481\/revisions\/5639"}],"wp:attachment":[{"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/media?parent=1481"}],"wp:term":[{"taxonomy":"ht_kb_category","embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb-category?post=1481"},{"taxonomy":"ht_kb_tag","embeddable":true,"href":"https:\/\/portal.staylinked.com\/sl\/kb\/wp-json\/wp\/v2\/ht-kb-tag?post=1481"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}