This section provides a list of the supported functions, along with descriptions and programming details for each. Note that these screen-based APIs are not available for use with TESS/Tekterm or VT-SmartTE emulation types. In addition to the items listed here, extended API options are available within Screen Recognition features.
Retrieve Session Properties
Description: Use this function to retrieve information about the device and StayLinked session. Note: The return parameters begin with a tilde (~), end with a tilde, and are separated by a tilde. This API is enhanced in server v15.4 build 216 to also include the client public IP for NAT'd sessions.
API ID: ~API01 Conditions: Embedded API only
Parameters: None
Returns: Session ID (Pos 2–6, Len=5)
Device Type (Pos 8–17, Len=10)
Device Name (Pos 19–28, Len=10)
IP Address (Pos 30–44, Len=15, Format=’###.###.###.###’)
MAC Address (Pos 46–57, Len=12)
Session Started Date/Time (Pos 59–77, Len=19, Format=’mm-dd-yyyy hh:mm:ss’)
Last Activity Date/Time (Pos 79–97, Len=19, Format=’mm-dd-yyyy hh:mm:ss’)
Client Software Version (Pos 99–108, Len=10, Format=’##.##.####’)
Device Number of Rows (Pos 110–111, Len=2)
Device Number of Columns (Pos 113–114, Len=2)
User Name (Pos 116–135, Len=20)
Public IP Address (Pos 137–151, Len=15, Format='###.###.###.###') (v15.4 required)
Notes: The host application may use either the ‘tilde’ character or ‘fixed positions‘ to acquire the individual values from the return value.
Here is an example return value:
~516AE~ESPWIN32__~__________~192.168.110.185~0054DA6E45B6~10-05-2008_10:46:24~10-05-2008_10:46:43~09.00.0100~25~80~TODD________________~
Send File to Device
Description: Use this function to send a file to the device.
API ID: ~API02 Conditions: Embedded API only
Parameters: Path/File name to be sent (Maximum length = 255 characters)
Path/File name to use on the device (Maximum length = 255 characters)
Mnemonic for successful transmission (like [enter])
Mnemonic for failure (like [pf2] or [pf12])
Flag to indicate if the server should show transfer status on the device (Y or N)
Returns: Completion Success/Error Message (Len=256)
Notes: The path for the file being sent must exist on and is always relative to the computer where the StayLinked Server is running (not necessarily the computer running the application)
Retrieve File from Device
Description: Use this function to retrieve a file from the device.
API ID: ~API03 Conditions: Embedded API only
Parameters: Path/File Name to be retrieved from the device (Maximum length = 255 characters)
Path/File Name where the file will be saved (Maximum length = 255 characters)
Mnemonic for successful transmission (like [enter])
Mnemonic for failure (like [pf2] or [pf12])
Flag to indicate if the server should show transfer status on the device (Y or N)
Flag to indicate if the file on the device should be cleared after the transfer (Y or N)
Returns: Completion Success/Error Message (Len=256)
Notes: The path for the file destination is always relative to the computer where the StayLinked Server is running (not necessarily the computer running the application)
Send Message to Device
Description: Use this function to send a special StayLinked message to the device. The message will immediately appear on the device.
API ID: ~API04 Conditions: Screen Reco or Embedded API
Parameters: Message Text (Maximum length = 255 characters)
Returns: None
Notes: The user must press a key to answer this message after it is displayed on the device.
Restart the Client
Description: Use this function to send a directive to the device to re-start the StayLinked client program.
API ID: ~API05 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: The client will always automatically reconnect to the session after restarting.
Reboot the Device
Description: Use this function to send a directive to the device to perform a “warm” reboot.
API ID: ~API06 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: The client will always automatically restart and then reconnect to the session after reboot.
Disconnect the Device
Description: Use this function to send a directive to the device to disconnect from the session and return to the main screen. The session stays alive on the server waiting for the device to reconnect.
API ID: ~API07 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: This option will cause a device that is running in the ‘Always Auto-Connect’ mode to exit back to the main screen.
Terminate the Session
Description: Use this function to send a directive to the server to terminate this device’s StayLinked session.
API ID: ~API08 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: If the client is running in ‘Always Auto-Connect’ mode, then the client will automatically reconnect to a new session after the old session is terminated.
Initiate Radio Stats
Description: Use this function to send a directive to the device to initiate the radio statistics utility.
API ID: ~API09 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: The Radio Stats dialog will be displayed on the device and the user will be required to dismiss the Radio Stats dialog.
Initiate Echo Test
Description: Use this function to send a directive to the device to initiate the echo test utility.
API ID: ~API10 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: The Echo Test dialog will be displayed on the device and the user will be required to dismiss the Echo Test dialog.
Reload Device Configuration
Description: Use this function to send a directive to the device to reload the device configuration.
API ID: ~API11 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: This function is normally performed during startup and client program initialization.
Send Remote Command
Description: Use this function to send a DOS command or program to call to the device.
API ID: ~API12 Conditions: Screen Reco or Embedded API
Parameters: Command Text (Maximum length = 99 characters)
Show Prompt – Show 'press any key' after executing program (Y/N)
Clear Screen – Clear the screen before executing the program (Y/N)
Wait – Should the server wait for a response from the device before continuing (Y/N)
(Device Dependent – PPC/CE.Net devices always respond immediately)
Returns: None
Notes: The syntax used in the Command Text will vary from OS to OS.
For DOS devices, you can add square brackets [ ] around the Command Text to cause the client to first exit and then run the program/command using all available memory, with the client reloading a reconnecting after the program/command ends.
For PPC/CE devices, you may need to add double quotes around the Command Text in case the program path contains any spaces. You would use an API command like this:
~API12~”\Program Files\MyApp\myapp.exe”~N~N~N~
Scanner Control
Description: Use this function to enable or disable the scanner laser on the device, with optional beep.
API ID: ~API13 Conditions: Screen Reco or Embedded API
Parameters: ‘0’ to disable the scanner laser
‘1’ to enable the scanner laser
‘2’ to disable the scanner laser and sound a short beep
‘3’ to disable the scanner laser and sound a long beep
‘4’ to disable the scanner laser and sound a double beep
‘5’ to disable the scanner laser and vibrate
Returns: None
Notes: This feature will only operate with devices that support the ability to enable and disable the scanner laser. The user can manually re-enable the scanner laser (usually by pressing ESC) or you can re-enable the laser using this same Host API.
Beeper Control
Description: Use this function to send StayLinked Beeps to the device.
API ID: ~API14 Conditions: Screen Reco or Embedded API
Parameters: Type of Beep to emit where:
‘1’=Short Beep
'2'=Long Beep
'3' = Double Beep and
‘4’ = Vibrate
Returns: None
Notes: The ‘Vibrate’ option will only cause vibration for devices that support vibration hardware. Devices that do not support vibration hardware will perform a system beep instead.
Verify StayLinked
Description: Use this function to determine whether or not the session is a StayLinked Session.
API ID: ~API15 Conditions: Embedded API only
Parameters: Unusual mnemonic value or data used to identify an automatic response from the StayLinked Session. Ex: ‘[pf23]’ or ‘staylinked[enter]’, etc.
Returns: The specified mnemonic or data if running a StayLinked Session.
Notes: This application using this Host API should always wait for an input. If the user is not running a StayLinked session, then they will see this API screen. The screen should provide instructions for a non-StayLinked user to provide a specific response. This response should be different than the response specified in the API parameter. If the user is running a StayLinked session, then the StayLinked Server will automatically reply to the host application using the mnemonic that you specify as the parameter. If your application gets the expected response, then the session is most likely a StayLinked session. If your application gets a different response, then the user is likely not running a StayLinked session and you can prevent display of any further Host API screens.
Update StayLinked User Name
Description: Use this function to update the current ‘User Name’ value for this StayLinked Session.
API ID: ~API16 Conditions: Screen Reco or Embedded API
Parameters: The new ‘User Name’ value, up to 20 characters in length.
Returns: None
Notes: The ‘User Name’ is displayed in the StayLinked Administrator Connections List. This API can be used to dynamically update the ‘User Name’ at any time. The API overrides the ‘User Name’ that is collected at the start of the session when the ‘Device Identification’ server setting is enabled.
Scanner Soft-Trigger
Description: Use this function to cause the Scanner Laser Beam to be lit up.
API ID: ~API17 Conditions: Screen Reco or Embedded API
Parameters: None
Returns: None
Notes: This API will operate only on devices that have hardware supporting the scanner laser ‘soft-trigger’ function.
Text-to-Speech
Description: Use this function to send Text-to-Speech strings to the device for voice processing.
API ID: ~API18 Conditions: Screen Reco or Embedded API
Parameters: Text-to-Speech String (Maximum length = 450 characters)
Returns: None
Notes: This API will work only for devices that have either StayLinked SpeechDirect software or StayLinked Speech powered by ctgTALK software installed and have the TTS function enabled on the device using Client Settings – Voice Support Mode. Details about the syntax and contents of the Text-to-Speech String can be found in the “Nuance Communications RealSpeak V4.0.1 User’s Guide for American English” available from your CTG representative.
Speech Recognition Rules
Description: Use this function to send Speech Recognition Rules to the device for voice processing against the ‘Grammar’ file on the device.
API ID: ~API19 Conditions: Screen Reco or Embedded API
Parameters: Speech Recognition Rules String (Maximum length = 450 characters)
Returns: None
Notes: This API will work only for devices that have StayLinked Speech powered by ctgTALK software installed and have the ASR function enabled on the device using Client Settings – Voice Support Mode. Details about the syntax and contents of the associated ‘Grammar’ file that must be installed on the device can be found in the “Nuance VOCON Embedded Development System Development Formalisms” document available from your CTG representative.
Session Reconnect Script
Description: Use this function to set the script that will be run if the device reconnects to the existing session.
API ID: ~API20 Conditions: Screen Reco or Embedded API
Parameters: Reconnect Script String
Returns: None
Notes: This API will be valuable for devices running VoiceWedge sessions. You can use this API to notify a VoiceWedge-enabled host application when a session is reconnected so that the host application can trigger the appropriate VoiceWedge Host APIs.
Update StayLinked Device Name
Description: Use this function to update the current ‘Device Name’ value for this StayLinked Session.
API ID: ~API21 Conditions: Screen Reco or Embedded API
Parameters: New ‘Device Name’ value up to 10 characters in length.
Returns: None
Notes: The ‘Device Name’ is displayed in the StayLinked Administrator Connections List. This API can be used to dynamically update the ‘Device Name’ at any time. The API overrides the ‘Device Name’ that is calculated before the telnet session is started. For 5250 sessions, changing this value does not affect the ‘Device Description’ in use for the session on the AS/400.
Update User Variable Value
Description: Use this function to update one of the ten ‘User Variables’ that are available for the StayLinked Session.
API ID: ~API22 Conditions: Screen Reco or Embedded API
Parameters: Index Number – Determines which User Variable to update (1 through 10 are valid).
New Value – Defines the new string value for the User Variable (Up to 50 characters).
Returns: None
Notes: The ‘User Variables’ can be used in scripting and are also displayed in the Administrator on the ‘Connection Details’ panel on the ‘User Variables’ tab. You can use these variables for any purpose you can imagine. One example would be to help locate a user. In this case, every time the user scans a ‘location’ label, you can use this Host API to update one of the ten User Variables with a value like this: ‘Last Location is A125’. In the Administrator, if you view the ‘Connection Details’ for that device, you will be able to see the ‘Last Location is A125’ displayed on the ‘User Variables’ tab.
Set TTS Language
Description: Use this function to set the language to be spoken by the Text-To-Speech Engine.
API ID: ~API23 Conditions: Screen Reco or Embedded API
Parameters: Language String can be either ENGLISH or SPANISH.
Returns: None
Notes: This API will work only for devices that have StayLinked SpeechDirect software installed and have the TTS function enabled on the device using Client Settings – Voice Support Mode. This API is not supported for StayLinked Speech powered by ctgTALK.
Record Usage Tracking Activity
Description: Use this function to record Activity text into the Usage Tracking Activity database.
API ID: ~API24 Conditions: Screen Reco or Embedded API
Parameters: Activity String
Returns: None
Notes: This API requires that Usage Tracking is enabled and Activity Tracking is enabled. The activity text can be any textual data up to 512 characters in length. The activity text will be recorded into the Usage Tracking Activity database. Substitution mnemonics will be processed for this API.
SIP Control
Description: Use this function to control visibility of the soft input panel (on-screen keyboard) on the device.
API ID: ~API25 Conditions: Screen Reco or Embedded API
Parameters: ‘0’ to hide the SIP
‘1’ to show the SIP – QWERTY Style
‘2’ to show the SIP – NumberSymbol Style
‘3’ to show the SIP – Numpad Style
‘4’ to show the SIP – Function Style
‘5’ to show the SIP – Control Style
Returns: None
Notes: This API will only operate on devices that allow control of the on-screen keyboard and are running a StayLinked Client version that supports this API. QWERTY style is available on all clients that support this API. The additional styles are available only on SmartTE clients.
Clear StayLinked User Name
Description: Use this function to clear the current ‘User Name’ value for this StayLinked Session.
API ID: ~API26 Conditions: Screen Reco or Embedded API
Parameters: The ‘reason’ for clearing the user name, up to 50 characters in length.
Returns: None
Notes: The ‘User Name’ is displayed in the StayLinked Administrator Connections List. This API can be used to clear the currently assigned ‘User Name’. You can provide a ‘reason’ for clearing the user name, e.g., ‘User Logged Off’. This API will only function if there is a current StayLinked User Name assigned using one of the ‘Device Identification’ or ‘Update StayLinked User Name API’ features.
Graphical Image Preview
Description: Use this function to display an image to the device.
API ID: ~API27 Conditions: Screen Reco and SmartTE
Parameters: Image URL followed by a tilde delimiter and the window title.
Returns: None
Notes: This API presents the client user with an image within a popup window. Usable with screen recognition variables, this can be users to capture part or product numbers from the screen and then display a related image. This SmartTE API will only work on SmartTE clients that use operating systems that can display the image dialogue.
Show SmartMenu
Description: Use this function to automatically display the SmartMenu on the device.
API ID: ~API28 Conditions: Screen Reco and SmartTE
Parameters: None
Returns: None
Notes: This SmartTE API presents the user with the SmartMenu. SmartMenu takes SmartTE buttons that are currently displayed and opens them in an operating system controlled scrolling menu. This can make smaller buttons much easier to read and select. This option is only available for use with SmartTE clients.
Send iQ Message
Description: Use this API to send information and tracking events to a StayLinked iQ server.
API ID: ~API29 Conditions: Screen Reco and StayLinked iQ full release
Parameters: Awaiting product release.
Returns: None
Notes: This API requires that StayLinked iQ is installed, enabled, and recording the requisite events. More information on this API will be available at the official release of the StayLinked iQ product. While the API exists today as an option in StayLinked, it does not yet have confirmed data formats and variables. Watch for more information on StayLinked iQ.
Printing and Automation
Description: Use this API to send information to third-party programs and printing devices.
API ID: ~API30 Conditions: Screen Reco only
Parameters: String determined by the receiving application.
Returns: None
Notes: This API will send the desired string of information to the COM port configured in the Device Group. More information on device groups is available in the Administrator User’s Guide. Standard COM configuration parameters are allowed, but the data string is not parsed or processed by StayLinked. The receiving application or printing device must be able to receive and process the data. Communication failures are handled as failed printing jobs, prompting the user to retry the print or ignore and continue. This option has been added to provide better flexibility in printing options and send data strings to any third-party application that can receive the data via COM port, such as warning lights and conveyor systems.
SmartTiles Commands
Description: Use this API to automatically display or hide SmartTiles.
API ID: ~API31 Conditions: Screen Reco and SmartTE
Parameters: [tile_hide] hides the current SmartTile page.
[tile_show #,#] shows the collection and page specified.
[tile_toggle] hides a displayed page or shows a hidden page.
[tile_prev] displays the previous page in the collection.
[tile_next] displays the next page in the collection.
[tile_cycle] cycles to the next page, and hides all pages after the last page before cycling back to the first page.
Returns: None
Notes: This option requires SmartTE clients of at least version 14.4. Clients will default to no collection unless one is set as the default using this API or client settings. Once a default collection is set, the client will step through pages within that collection. This API can be used to change the default collection or automatically display pages with the relative content required by the current emulation screen. More information on SmartTiles can be found in the Administrator User’s Guide.
Parameters: New ‘Device Name’ value up to 10 characters in length.
Returns: None
Notes: The ‘Device Name’ is displayed in the StayLinked Administrator Connections List. This API can be used to dynamically update the ‘Device Name’ at any time. The API overrides the ‘Device Name’ that is calculated before the telnet session is started. For 5250 sessions, changing this value does not affect the ‘Device Description’ in use for the session on the AS/400.
Update User Variable Value
Description: Use this function to update one of the ten ‘User Variables’ that are available for the StayLinked Session.
API ID: ~API22 Conditions: Screen Reco or Embedded API
Parameters: Index Number – Determines which User Variable to update (1 through 10 are valid).
New Value – Defines the new string value for the User Variable (Up to 50 characters).
Returns: None
Notes: The ‘User Variables’ can be used in scripting and are also displayed in the Administrator on the ‘Connection Details’ panel on the ‘User Variables’ tab. You can use these variables for any purpose you can imagine. One example would be to help locate a user. In this case, every time the user scans a ‘location’ label, you can use this Host API to update one of the ten User Variables with a value like this: ‘Last Location is A125’. In the Administrator, if you view the ‘Connection Details’ for that device, you will be able to see the ‘Last Location is A125’ displayed on the ‘User Variables’ tab.
Set TTS Language
Description: Use this function to set the language to be spoken by the Text-To-Speech Engine.
API ID: ~API23 Conditions: Screen Reco or Embedded API
Parameters: Language String can be either ENGLISH or SPANISH.
Returns: None
Notes: This API will work only for devices that have StayLinked SpeechDirect software installed and have the TTS function enabled on the device using Client Settings – Voice Support Mode. This API is not supported for StayLinked Speech powered by ctgTALK.
Record Usage Tracking Activity
Description: Use this function to record Activity text into the Usage Tracking Activity database.
API ID: ~API24 Conditions: Screen Reco or Embedded API
Parameters: Activity String
Returns: None
Notes: This API requires that Usage Tracking is enabled and Activity Tracking is enabled. The activity text can be any textual data up to 512 characters in length. The activity text will be recorded into the Usage Tracking Activity database. Substitution mnemonics will be processed for this API.
SIP Control
Description: Use this function to control visibility of the soft input panel (on-screen keyboard) on the device.
API ID: ~API25 Conditions: Screen Reco or Embedded API
Parameters: ‘0’ to hide the SIP
‘1’ to show the SIP – QWERTY Style
‘2’ to show the SIP – NumberSymbol Style
‘3’ to show the SIP – Numpad Style
‘4’ to show the SIP – Function Style
‘5’ to show the SIP – Control Style
Returns: None
Notes: This API will only operate on devices that allow control of the on-screen keyboard and are running a StayLinked Client version that supports this API. QWERTY style is available on all clients that support this API. The additional styles are available only on SmartTE clients.
Clear StayLinked User Name
Description: Use this function to clear the current ‘User Name’ value for this StayLinked Session.
API ID: ~API26 Conditions: Screen Reco or Embedded API
Parameters: The ‘reason’ for clearing the user name, up to 50 characters in length.
Returns: None
Notes: The ‘User Name’ is displayed in the StayLinked Administrator Connections List. This API can be used to clear the currently assigned ‘User Name’. You can provide a ‘reason’ for clearing the user name, e.g., ‘User Logged Off’. This API will only function if there is a current StayLinked User Name assigned using one of the ‘Device Identification’ or ‘Update StayLinked User Name API’ features.
Send Host Input
Description: Use this function to send standard input to the telnet host. This allows the stack/string of APIs to also include host commands/input which was not previously available using the script parser in StayLinked.
API ID: ~N/A~ Conditions: Server version 15.5 and Screen Reco or Global API.
Parameters: The contents of input to be transmitted to the telnet host.
Returns: None
Notes: For example, this might be used to send an input to the host while changing the on-screen keyboard, smarttiles, or any other API. APIs were previously restricted to APIs only, so an API was added to allow these strings to include commands to the telnet host.
Share the post "Host API Detail Descriptions"