Eighth Edition (March 2019)
This edition applies to Version 14.0 of IBM(R) IBM Host On-Demand (program number 5724-I20) and to all subsequent releases and modifications until otherwise indicated in new editions.
(C); Copyright International Business Machines Corporation 2004, 2019. All rights reserved.
The Session Manager API Reference describes the Session Manager APIs provided by Host On-Demand for embedding host sessions in Web pages using JavaScript. In addition, this document also discusses the Deployment Wizard, the Cached Client, and tracing functions, all of which support the JavaScript API environment. This document is written for application developers and administrators.
The Session Manager API Reference is also available on the Host On-Demand online Information Center at http://publib.boulder.ibm.com/infocenter/hodhelp/v12r0/index.jsp.
The MySupport feature enables you to personalize your support view and register to receive weekly e-mail notifications alerting you to new patches, downloads, and other timely technical support information for IBM products. To register for MySupport, follow the instructions in the Technote found at the following URL: http://www.ibm.com/support/docview.wss?rs=132&context=SS5RCF&uid=swg21168680&loc=en_US&cs=utf-8&lang=en+en
The following typographic conventions are used in the Session Manager API Reference:
| Convention | Meaning |
| Monospace | Indicates text you must enter at a command prompt and values you must use literally, such as commands, functions, and resource definition attributes and their values. Monospace also indicates screen text and code examples. |
| Italics | Indicates variable values you must provide (for example, you supply the name of a file for file_name). Italics also indicates emphasis and the titles of books. |
| Return | Refers to the key labeled with the word Return, the word Enter, or the left arrow. |
|
|
This graphic is used to highlight notes to the reader. |
In addition to the application programming interfaces (APIs) provided with the Host Access Toolkit, Host On-Demand also provides specialized public APIs, called Session Manager APIs, that provide support for embedding host sessions in Web pages using JavaScript. These JavaScript-based APIs help application developers manage host sessions and text-based interactions with host sessions. The APIs are available through the Host On-Demand Session Manager.
The APIs are divided into the following four sets:
Using Session Manager APIs, application developers can write JavaScript code that manipulates data from the data stream presentation space (such as 3270, 5250, and Virtual Terminal) without requiring any Java coding. The presentation space represents a virtual terminal screen that contains both data and selected associated attributes presented by host applications. These JavaScript Session Manager APIs have many functions, including starting, stopping, and displaying sessions, starting macros, opening a session to the host, waiting for incoming host data, getting specific strings from the imaginary screen, setting new string values, sending data stream function keys back to the host, and waiting for the next host response. After an interaction is complete, the JavaScript code can switch to other tasks or simply close the session. The entire operation can be performed without ever showing host screens.
In order for JavaScript code to work with host sessions, it must interact with the Host On-Demand applet com.ibm.eNetwork.HOD.JSHostOnDemand. An application developer can create JavaScript files for the required functions and incorporate them into a Web page. JavaScript files must be placed into the Host On-Demand publish directory.
The following diagram shows how the JSHostOnDemand applet encapsulates the HostOnDemand applet:
java.applet.Applet
|
+--com.ibm.eNetwork.HOD.BaseApplet
|
+--com.ibm.eNetwork.HOD.HostOnDemand
|
+--com.ibm.eNetwork.HOD.JSHostOnDemand
Session Manager APIs provide start, stop, connect, disconnect, and display session functions. In addition, get methods are provided to retrieve active session IDs. Session Manager APIs support the management of multiple instances of a session as well as multiple sessions.
The startSession method starts the specified session. It can start the first instance of a session as well as another instance of a session. The user must keep track of the Session ID that gets assigned to the session. Any subsequent call for this session must include the Session ID in the session name parameter. For example, when the first session is started and the session name is "3270 Display," the session name parameter on any subsequent call must be "3270 Display - A." This allows correct mapping of the full session name with the associated presentation space.
Parameters
session: the name of the session to be started.
The name of the session must be the same as the one specified in the Session Name parameter of the session configuration. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name -2 EXCEPTION_ERROR Exception error
The getSessionID method returns the session ID of the last session that was started using the startSession API. The user must concatenate this session ID to the session name to form an active session's full (name+ID) session name. This new session name should be used on all subsequent API calls. The JSHostOnDemand applet only saves one session ID, so if you want to save the full session name, this API should be used prior to issuing a second startSession method call.
For example:
var fullSessionName;
Function startHODSession(sessionName) {
var i = document.HODApplet.startSession(sessionName);
if (i == 0) {
fullSessionName = sessionName + document.HODApplet.getSessionID();
}
}If the session ID is not retrieved after a startSession call, it can be retrieved later by calling the getAllSessionNames method and parsing the returned string. See the getAllSessionNames method for more details.
Parameters
None.
Returns
The session ID of the last session that was started using the startSession API; or null if no session has been started using the startSession method.
The getAllSessionNames method returns a string of all active session names in the following format:
sessionName+sessionID;sessionName+sessionID
e.g. 3270 Display - A;5250 Display - BThe caller can tokenize the string with the ";" character and use the full session names on APIs such as sendKeys, sendString, and getString.
Parameters
None.
Returns
A string of all active sessions' full session names; or null if no active session; or "-2" if exception error.
The stopSession method stops the currently selected session.
Parameters
None.
Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the stopSession method stops the specified session.
Parameters
sessionName: the full name of the session to be stopped. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error
The stopAllSessions method stops all active sessions.
Parameters
None.
Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error -3 NO_ACTIVE_SESSION There is no active session
The connectSession method connects the currently selected session.
Parameters
None.
Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the connectSession method connects the specified session.
Parameters
sessionName: the full name of the session to be connected. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error
The disconnectSession method disconnects the currently selected session.
Parameters
None.
Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the disconnectSession method disconnects the specified session.
Parameters
sessionName: the full name of the session to be disconnected. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error
The displaySession method displays the currently selected session.
This method allows users to selectively display a host session in a JavaScript frame. If the tabs are hidden, then only the currently selected session is displayed in the frame. Otherwise, all active sessions and the Host On-Demand client tab panels are displayed.
Parameters
None.
Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active or session not embedded -2 EXCEPTION_ERROR Exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the displaySession method displays the currently selected session.
This method allows users to selectively display a host session in a JavaScript frame. If the tabs are hidden, then only the currently selected session is displayed in the frame. Otherwise, all active sessions and the Host On-Demand client tab panels are displayed.
Parameters
sessionName: the full name of the session to be displayed. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active or session not embedded -2 EXCEPTION_ERROR Exception error
The isHODLoaded method checks whether or not the Host On-Demand applet is loaded. The main purpose of this method is for Cached Client users to confirm that Host On-Demand is loaded before any of the JavaScript API functions are called. If the Host On-Demand applet is not loaded and one of the APIs is called, the browser will give a NullPointerException to the JavaScript.
Parameters
None.
Returns
Returns true if Host On-Demand applet is loaded. For the Download Client, it always returns true.
The callCustomerFunction method is not implemented by Host On-Demand. The purpose of this method is to extend JavaScript APIs for users who want to write custom applets using Programmable Host On-Demand, the Cached Client, and JavaScript APIs. Using this method, the caller can call any function in the custom applet and pass any parameters. The custom applet that implements this method should parse the strings to know what it should do, and the caller should parse the returned string to know what it should do.
Parameters
functionName: name of the function to be executed in the custom applet. parms: parameters to be passed to the above function. Returns
Customized string. The Host On-Demand applet always returns a blank (zero length) string.
The presentation space is a virtual screen that contains all the characters and attributes that would be seen on a traditional emulator screen. The presentation space is the primary object for text-based interactions with the host. Presentation space APIs provide access to a subset of the ECLPS APIs, which send keystrokes to the host, send strings to the host, retrieve text plane information, and allow screen recognition with or without operator information area (OIA) inhibited. Presentation space APIs support multiple instances of a session as well as multiple sessions.
The sendKeys method sends a string of keys to the presentation space. The string can be thought of as a sequence of keystrokes from the keyboard that can contain both text characters and special keystrokes, such as the Enter key, the Tab key, or the Page Up key. These special keys are represented by keywords that are delimited by square brackets and called mnemonics. For example, the mnemonic keyword for the Enter key is [enter].
The text string can contain any number or combination of characters and mnemonics. For example, the following string can be used to send a user's ID, to tab to the next field, to send the user's password, and to send the Enter key to log onto a host.
userID[tab]password[enter]
To send a left or right square bracket, the character must be doubled. To send a left square bracket, use '[['. To send a right square bracket, use ']]'.
This signature of sendKeys sends the given text string to the currently selected session at the current cursor position.
Parameters
text: the string of characters and aid-key mnemonics to be sent. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Mnemonic or exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the sendKeys method sends the given text string to the specified session at the current cursor position.
Parameters
sessionName: the full name of the session where the keys should be sent. text: the string of characters and aid-key mnemonics to be sent. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Mnemonic or exception error
This signature of the sendKeys method sends the given text string to the specified session at the specified cursor position. The cursor is moved to the given position before the keys are sent.
Parameters
sessionName: the full name of the session where the keys should be sent. text: the string of characters and aid-key mnemonics to be sent. pos: the linear position where the keys should be sent. The linear cursor position is determined by assuming the presentation space is mapped to a one-dimensional array. Two-dimensional array coordinates can be mapped to a one-dimensional array using the following formula: (y - 1) * numCol + x. For example, the linear position of a cursor at 10, 15 on a 24 x 80 presentation space would be 9*80+15=735.
The cursor positioning system is one-based rather than zero-based. The valid cursor positions for a 24 x 80 presentation space are between one and 1920 inclusive. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Mnemonic or exception error: or the position is not valid; or exception error
This signature of the sendKeys method sends the given text string to the specified session at the specified cursor position. The cursor is moved to the given coordinates before the keys are sent.
Parameters
sessionName: the full name of the session where the keys should be sent. text: the string of characters and aid-key mnemonics to be sent. row: the starting row where keys should be sent. column: the starting column where keys should be sent. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Mnemonic or exception error: or the row or column is not valid; or exception error
The setString method sends a string to the presentation space. It automatically duplicates double-byte character set (DBCS) characters before copying the string to the presentation space.
The modified string overlays only unprotected fields. Any parts of the string that fall over protected fields are discarded.
This signature of setString sends the given string to the currently selected session at the current cursor position.
Parameters
text: the string to be placed in the presentation space. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Null input string or exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the setString method sends the given string to the specified session at the current cursor position.
Parameters
sessionName: the full name of the session where the string should be sent. text: the string to be placed in the presentation space. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Null input string or exception error
This signature of the setString method sends the given string to the specified session at the specified cursor position. The cursor is moved to the given position before the string is written.
Parameters
sessionName: the full name of the session where the string should be sent. text: the string to be placed in the presentation space. pos: the linear position where the string should be written. The linear cursor position is determined by assuming the presentation space is mapped to a one-dimensional array. Two-dimensional array coordinates can be mapped to a one-dimensional array using the following formula: (y - 1) * numCol + x. Therefore, the linear position of a cursor at 10, 15 on a 24 x 80 presentation space would be 9*80+15=735.
The cursor positioning system is one-based rather than zero-based. The valid cursor positions for a 24 x 80 presentation space are between one and 1920 inclusive. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Null input string; or the position is not valid; or exception error
This signature of the setString method sends the given string to the specified session at the specified cursor position. The cursor is moved to the given coordinates before the string is written.
Parameters
sessionName: the full name of the session where the string should be sent. text: the string to be placed in the presentation space. row: the starting row where the string should be written. col: the starting column where the string should be written. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Null input string; or the row or column is not valid; or exception error
The getString method retrieves text plane information from the presentation space using the TEXT_PLANE parameter. It removes duplicate DBCS characters before the text plane data is returned.
The data is returned starting from the beginning of the presentation space and continuing until the JSHostOnDemand applet's buffer is full, or the entire text plane has been copied. Users can use the length variable of String object to get the number of characters copied to the returned string, or they can call the getStringLength method immediately after a getString call to get the number of characters copied to the returned string.
This signature of getString retrieves the data from the currently selected session at the beginning of the presentation space.
Parameters
None.
Returns
Value Constant Description If successful, returns a string of data from the beginning of the presentation space. -1 STR_INVALID_SESSION_NAME Invalid session name or session not active -2 STR_EXCEPTION_ERROR Exception error -3 STR_NO_ACTIVE_SESSION There is no active session
This signature of the getString method retrieves the data from the specified session at the beginning of the presentation space.
Parameters
sessionName: the full name of the session from where the data should be read. Returns
Value Constant Description If successful, returns a string of data from the beginning of the presentation space. -1 STR_INVALID_SESSION_NAME Invalid session name or session not active -2 STR_EXCEPTION_ERROR Exception error
This signature of the getString method retrieves the data from the specified session at the beginning of the specified position until the specified number of plane positions have been copied.
Parameters
sessionName: the full name of the session from where the data should be read. pos: the starting position. length: the number of plane positions to copy. Returns
Value Constant Description If successful, returns a string of data from the given position until the specified number of plane positions. -1 STR_INVALID_SESSION_NAME Invalid session name or session not active -2 STR_EXCEPTION_ERROR The position is out of range or exception error
This signature of the getString method retrieves the data from the specified session at the beginning of the specified coordinates until the specified number of plane positions have been copied.
Parameters
sessionName: the full name of the session from where the data should be read. row: the starting row. col: the starting column. length: the number of plane positions to copy. Returns
Value Constant Description If successful, returns a string of data from the given coordinates until the specified number of plane positions. -1 STR_INVALID_SESSION_NAME Invalid session name or session not active -2 STR_EXCEPTION_ERROR The coordinates are out of range or exception error
The getStringLength method returns the number of characters copied into the last getString call's returned String object.
Parameters
None.
Returns
Number of characteristics copied into the getString's returned object (String) or zero.
The inputInhibited method checks whether the currently selected session is ready for interaction, such as sending keystrokes or calling other API methods. The keyboard/screen can be locked as a result of a sendKeys API call when the cursor is on a write-protected area of the host screen, or when the host session is not active. Use the reset API to unlock the keyboard.
Parameters
None.
Returns
Value Inhibit Indicator OIA String 0 INHIBIT_NOTINHIBITED 1 INHIBIT_SYSTEMWAIT 'X SYSTEM' or 'X[]' 2 INHIBIT_COMMCHECK 'X COMMxxx' 3 INHIBIT_PROGCHECK 'X PROGxxx' 4 INHIBIT_MACHCHECK 'X MACHxxx' 5 INHIBIT_OTHERINHIBIT
Value Constant Description -1 INVALID_SESSION_NAME Invalid session name -2 EXCEPTION_ERROR Exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the inputInhibited method checks whether the specified session is ready for interaction, such as sending keystrokes or calling other API methods. The keyboard/screen can be locked as a result of a sendKeys API call when the cursor is on a write-protected area of the host screen, or when the host session is not active. Use the reset API to unlock the keyboard.
Parameters
sessionName: the full name of the session where the check should be performed. Returns
Value Inhibit Indicator OIA String 0 INHIBIT_NOTINHIBITED 1 INHIBIT_SYSTEMWAIT 'X SYSTEM' or 'X[]' 2 INHIBIT_COMMCHECK 'X COMMxxx' 3 INHIBIT_PROGCHECK 'X PROGxxx' 4 INHIBIT_MACHCHECK 'X MACHxxx' 5 INHIBIT_OTHERINHIBIT
Value Constant Description -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error
The reset method resets the currently selected session's locked keyboard. If the inputInhibited method returns a non-zero value, then the keyboard can be reset by calling this method. It issues '[reset]' mnemonics using the sendKeys method.
Parameters
None.
Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the reset method resets the specified session's locked keyboard. If the inputInhibited method returns a non-zero value, then the keyboard can be reset by calling this method. It issues '[reset]' mnemonics using sendKeys method.
Parameters
sessionName: the full name of the session whose keyboard is reset. Returns
Returns 0 if sendKeys is successful; otherwise, returns a negative number.
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Exception error
The isCommReady method checks whether the currently selected session is ready to communicate with the host. It returns the status of the communications state. This method provides a way to detect communications line failures or abnormal termination of a session. Use the connectSession API to re-establish a lost connection.
Parameters
None.
Returns
Returns true if the host is ready for communications; otherwise returns false if the host is not ready for communications; or there is no active session; or there is an exception error.
This signature of the isCommReady method checks whether the specified session is ready to communicate with the host. It returns the status of the communications state. This method provides a way to detect communications line failures or abnormal termination of a session. Use the connectSession API to re-establish a lost connection.
Parameters
sessionName: the full name of the session where the check should be performed. Returns
Returns true if the host is ready for communications; otherwise returns false if the host is not ready for communications; or the session name is invalid; or there is an exception error.
The waitForStringInRec method synchronously waits until the input text string appears at the given rectangle in the currently selected session. If the waitForInput parameter is true, then it also waits until OIA indicates that the session is ready for input. Thus, this method provides screen recognition and OIA-uninhibited (no data communication, and you are able to enter keystrokes; for example, keyboard unlocked) functions. This method should be used before sending any data to a screen to avoid host screen synchronization/timing/lock-up problems. If sRow and sCol parameters are set to 1, and eRow and eCol parameters are set to -1, then the entire presentation space is scanned for the input string. If a host screen containing the specified string is not presented in the specified amount of time, the wait is terminated.
Parameters
text: the string to wait for. sRow: the upper left rectangle corner row position. sCol: the upper left rectangle corner column position. eRow: the lower right rectangle corner row position. eCol: the lower right rectangle corner column position. timeout: the wait time in milliseconds. Specify -1 for indefinite wait. waitForInput: if true, will wait until OIA indicates session is ready for input. caseSensitive: if true, the text string wait will be case-sensitive. Returns
Value Constant Description 0 OK The specified string found at the given rectangle in the presentation space. -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Interrupted exception error -3 NO_ACTIVE_SESSION There is no active session -4 TIMER_EXPIRED The timer expired before a host screen containing the specified string arrived
The waitForStringInRec method synchronously waits until the input text string appears at the given rectangle in the specified session. If the waitForInput parameter is true, then it also waits until OIA indicates that the session is ready for input. Thus, this method provides screen recognition and OIA-uninhibited (no data communication, and you are able to enter keystrokes; for example, keyboard unlocked) functions. This method should be used before sending any data to a screen to avoid host screen synchronization/timing/lock-up problems. If sRow and sCol parameters are set to 1, and eRow and eCol parameters are set to -1, then the entire presentation space is scanned for the input string. If a host screen containing the specified string is not presented in the specified amount of time, the wait is terminated.
Parameters
sessionName: the full name of the session where string wait should be done. text: the string to wait for. sRow: the upper left rectangle corner row position. sCol: the upper left rectangle corner column position. eRow: the lower right rectangle corner row position. eCol: the lower right rectangle corner column position. timeout: the wait time in milliseconds. Specify -1 for indefinite wait. waitForInput: if true, will wait until OIA indicates session is ready for input. caseSensitive: if true, the text string wait will be case-sensitive. Returns
Value Constant Description 0 OK The specified string found at the given rectangle in the presentation space. -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Interrupted exception error -4 TIMER_EXPIRED The timer expired before a host screen containing the specified string arrived
The waitWhileStringInRec method synchronously waits until the input text string is no longer in the given rectangle in the currently selected session. If the waitForInput parameter is true, then it also waits until OIA indicates that the session is ready for input. Thus, this method provides screen recognition and OIA-uninhibited (no data communication, and you are able to enter keystrokes; for example, keyboard unlocked) functions. This method should be used before sending any data to a host screen to avoid host screen synchronization/timing/lock-up problems. This function is also useful on a slower communication line or a slower host where the screens are not processed in a timely manner. It provides an indication to the caller that the host screen is flushed. If sRow and sCol parameters are set to 1, and eRow and eCol parameters are set to -1, then the entire presentation space is used to scan for the input string. If a host screen containing the specified string is not flushed in the specified amount of time, the wait is terminated.
Parameters
sessionName: the full name of the session where string wait should be done. text: the string to wait for. sRow: the upper left rectangle corner row position. sCol: the upper left rectangle corner column position. eRow: the lower right rectangle corner row position. eCol: the lower right rectangle corner column position. timeout: the wait time in milliseconds. Specify -1 for indefinite wait. waitForInput: if true, will wait until OIA indicates session is ready for input. caseSensitive: if true, the text string wait will be case-sensitive. Returns
Value Constant Description 0 OK The specified string is no longer at the given location in the presentation space. -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Interrupted exception error -3 NO_ACTIVE_SESSION There is no active session -4 TIMER_EXPIRED The timer expired before a host screen containing the specified string arrived
The waitWhileStringInRec method synchronously waits until the input text string is no longer in the given rectangle in the specified session. If the waitForInput parameter is true, then it also waits until OIA indicates that the session is ready for input. Thus, this method provides screen recognition and OIA-uninhibited (no data communication, and you are able to enter keystrokes; for example, keyboard unlocked) functions. This method should be used before sending any data to a host screen to avoid host screen synchronization/timing/lock-up problems. This function is also useful on a slower communication line or a slower host where the screens are not processed in a timely manner. It provides an indication to the caller that the host screen is flushed. If sRow and sCol parameters are set to 1, and eRow and eCol parameters are set to -1, then the entire presentation space is used to scan for the input string. If a host screen containing the specified string is not flushed in the specified amount of time, the wait is terminated.
Parameters
sessionName: the full name of the session where string wait should be done. text: the string to wait for. sRow: the upper left rectangle corner row position. sCol: the upper left rectangle corner column position. eRow: the lower right rectangle corner row position. eCol: the lower right rectangle corner column position. timeout: the wait time in milliseconds. Specify -1 for indefinite wait. waitForInput: if true, will wait until OIA indicates session is ready for input. caseSensitive: if true, the text string wait will be case-sensitive. Returns
Value Constant Description 0 OK The specified string is no longer at the given location in the presentation space -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Interrupted exception error -4 TIMER_EXPIRED The timer expired before a host screen containing the specified string flushed
The Host On-Demand built-in Function APIs are limited to running a predefined host macro.
The startMacro method starts the specified macro in the currently selected session. This method allows users to start a macro. The macro must have been predefined in the currently selected session.
Parameters
macroName: the name of the macro to be started. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Invalid macro name or exception error -3 NO_ACTIVE_SESSION There is no active session
This signature of the startMacro method starts the specified macro in the specified session. This method allows users to start a macro. The macro must have been predefined in the specified session.
Parameters
sessionName: the full name of the session to be used to start the macro. macroName: the name of the macro to be started. Returns
Value Constant Description 0 OK Successful -1 INVALID_SESSION_NAME Invalid session name or session not active -2 EXCEPTION_ERROR Invalid macro name or exception error
The getErrorMessage method returns a saved error message from the last API call. If there was an exception thrown by Host On-Demand or Java as a result of one of the above API calls, then this method returns the exception message.
All exceptions thrown by the Host On-Demand or Java are caught and saved by the JSHostOnDemand applet. The exception message can be retrieved by the JavaScript code by calling this method after any of the above API calls. Parameters
None.
Returns
The error message string of the last exception if it was created with an error message string; or null if it was created without an error message; or invalid session name; and so on.
The Host On-Demand Cached Client, the Deployment Wizard, and tracing function support the JavaScript API environment.
All of the above APIs are also supported by the Host On-Demand Cached Client. The Cached Client's loader applet either loads the com.ibm.eNetwork.HOD.HostOnDemand applet or the com.ibm.eNetwork.HOD.JSHostOnDemand applet, and provides the mapping APIs.
The JavaScript APIs are supported on all configuration models. However, it is best to use the HTML-based configuration model for Web integration (the Host On-Demand desktop and sessions can be hidden). The JavaScript APIs do not provide Logon and Logoff functions. So if the configuration server model is used, the Host On-Demand "Logon" panel will pop up (unless the username and password are specified in the HTML), and the "Logoff" button on Host On-Demand desktop will have to be used to logoff. All of the host sessions must be configured to start in the client window (for example, run embedded). The bookmarking option must be disabled.
A JavaScript interface code skeleton is created in the HODJSAPI.js file. For example:
function sendKeys2 (sessionName, request) {
return document.HODApplet.sendKeys2 (sessionName, request);
}
Host On-Demand provides a HideHODDesktop parameter for hiding the Host On-Demand desktop as well as the tab of each session. You can configure this option on the Advanced Options > Appearance window of the Deployment Wizard GUI. The Web page interacts with a host session thru JavaScript APIs.
The "CachedClientSupportedApplet" parameter of the CachedAppletSupportApplet applet will either be set to com.ibm.eNetwork.HOD.HostOnDemand.class or to com.ibm.eNetwork.HOD.JSHostOnDemand.class. The Cached Client applet uses this parameter to load the Host On-Demand applet.
The applet's "Code" parameter and the inclusion of the HODJSAPI.js file is controlled by the "Enable Session Manager JavaScript API" check box in the Advanced Options > Other window of the Deployment Wizard.
The JSHostOnDemand applet provides entry and exit levels of tracing for all APIs. It also traces all exceptions. The presentation space API calls are also traced by the ECLPS component of the Host Access Class Library. The Session Manager and Host On-Demand Functions APIs are traced by the existing Host On-Demand components.
A HOD.JSSessionManager option_tag is provided for the Session Manager APIs tracing. A user can use this tag on the TraceOptions HTML parameter to start tracing without going through the Trace GUI. For example:
<PARAM NAME="TraceOptions" VALUE="SaveLocation=Local,
OutputFile=c:\HODTrace\trace.tlg, HOD.SessionManagerAPI=3">
The following examples show how JavaScript can be coded to work with the Session Manager applet.
var sBuffer = new String(document.HODApplet.getString());
alert("Buffer = "+sBuffer);
alert("Number of characters copied = "+sBuffer.length);
OR
var buf = document.HODApplet.getString();
alert("Buffer = "+buffer);
alert ("Number of characters copied = "+document.HODApplet.getStringLength());
var session = "My Session";
var sessionName;
var rc = document.HODApplet.startSession(session);
if (rc == 0) {
sessionName = sessionName+document.HODApplet.getSessionID();
rc = document.HODApplet.sendKeys4(sessionName, "Userid[tab]password[enter]", 40, 110);
// Invalid row and column
if (rc == -1) {
alert("Error = "+document.HODApplet.getErrorMessage());
}
}
rc = document.HODApplet.closeSession(sessionName);
The communication between JavaScript and the Java applet requires the applet to be loaded in the browser. If the Host On-Demand applet is not loaded and a JavaScript API call is made, a NullPointerException will occur. Be sure that your JavaScript code allows enough time for Host On-Demand to load.
You may want to add the following code to handle Java exceptions:
<script type="text/javascript">
<!-- Catch Java Exceptions
function handleError() {
return true; // Handle exceptions
}
window.onerror = handleError;
</script>
DemoPage.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META name="GENERATOR" content="IBM WebSphere Page Designer V3.5.1 for Windows">
<META http-equiv="Content-Style-Type" content="text/css">
<TITLE>HOD JavaScript Demo</TITLE>
</HEAD>
<FRAMESET rows="36%,64%" frameborder="NO" name = "fs">
<FRAME src="Navigation.html" name = "navigation">
<FRAME src="JSHODPage.html" name = "contentsHOD">
</FRAMESET>
</HTML>
Navigation.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><!-- Navigation HTML file -->
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder V6.0.0 Trial for Windows">
<META http-equiv="Content-Style-Type" content="text/css">
<title>JavaScript/HOD Demo </title>
<script language="JavaScript">
var hodframe;
function init() {
hodFrame = parent.contentsHOD.getHODFrame();
}
function sendRequest(text) {
parent.contentsHOD.getHODFrame().displaySession1("Session - A");
parent.contentsHOD.getHODFrame().sendKeys2("Session - A", text+" [enter]");
OR
parent.contentsHOD.getHODFrame().sendKeys1(text+" [enter]");
OR
hodFrame.sendKeys1(text+" [enter]");
}
function startSession(sessionName) {
hodFrame.startSession(sessionName);
}
This appendix contains the mnemonic keywords for the SendKeys method and the type of session or sessions in which the mnemonic is supported. Session support for a given mnemonic is denoted by an X, along with any special notes that apply to the function.
Mnemonic Keywords for the SendKeys Method
Bidirectional Mnemonic Keywords for the SendKeys Method
| Function | Mnemonic Keyword | 3270 | 5250 | VT | CICS |
| Attention | [attn] | X |
X |
|
X |
| Alternate View | [altview] |
|
|||
| Backspace | [backspace] | X |
X |
X |
|
| Backtab | [backtab] | X |
X |
|
X |
| Beginning of Field | [bof] | X |
X |
|
X |
| Clear | [clear] | X |
X |
X |
|
| Cursor Down | [down] | X |
X |
X |
|
| Cursor Left | [left] | X |
X |
X |
|
| Cursor Right | [right] | X |
X |
X |
|
| Cursor Select | [cursel] | X |
X |
X |
|
| Cursor Up | [up] | X |
X |
X |
|
| Delete Character | [delete] | X |
X |
X |
|
| Display SO/SI | [dspsosi] |
|
|||
| DUP Field | [dup] | X |
X |
|
X |
| Enter | [enter] | X |
X |
X |
X |
| End of Field | [eof] | X |
X |
X |
|
| Erase EOF | [eraseeof] | X |
X |
|
X |
| Erase Field | [erasefld] | X |
X |
|
X |
| Erase Input | [erinp] | X |
X |
|
X |
| Field Exit | [fldext] |
|
X |
|
|
| Field Mark | [fieldmark] | X |
X |
|
|
| Field Minus | [field-] |
|
X |
|
|
| Field Plus | [field+] |
|
X |
|
|
| F1 | [pf1] | X |
X |
X |
X |
| F2 | [pf2] | X |
X |
X |
X |
| F3 | [pf3] | X |
X |
X |
X |
| F4 | [pf4] | X |
X |
X |
X |
| F5 | [pf5] | X |
X |
X |
X |
| F6 | [pf6] | X |
X |
X |
X |
| F7 | [pf7] | X |
X |
X |
X |
| F8 | [pf8] | X |
X |
X |
X |
| F9 | [pf9] | X |
X |
X |
X |
| F10 | [pf10] | X |
X |
X |
X |
| F11 | [pf11] | X |
X |
X |
X |
| F12 | [pf12] | X |
X |
X |
X |
| F13 | [pf13] | X |
X |
X |
X |
| F14 | [pf14] | X |
X |
X |
X |
| F15 | [pf15] | X |
X |
X |
X |
| F16 | [pf16] | X |
X |
X |
X |
| F17 | [pf17] | X |
X |
X |
X |
| F18 | [pf18] | X |
X |
X |
X |
| F19 | [pf19] | X |
X |
X |
X |
| F20 | [pf20] | X |
X |
X |
X |
| F21 | [pf21] | X |
X |
|
X |
| F22 | [pf22] | X |
X |
|
X |
| F23 | [pf23] | X |
X |
|
X |
| F24 | [pf24] | X |
X |
|
X |
| Help | [help] |
|
X |
|
|
| Home | [home] | X |
X |
X |
|
| Insert | [insert] | X |
X |
X |
|
| Keypad 0 | [keypad0] |
|
|
X |
|
| Keypad 1 | [keypad1] |
|
|
X |
|
| Keypad 2 | [keypad2] |
|
|
X |
|
| Keypad 3 | [keypad3] |
|
|
X |
|
| Keypad 4 | [keypad4] |
|
|
X |
|
| Keypad 5 | [keypad5] |
|
|
X |
|
| Keypad 6 | [keypad6] |
|
|
X |
|
| Keypad 7 | [keypad7] |
|
|
X |
|
| Keypad 8 | [keypad8] |
|
|
X |
|
| Keypad 9 | [keypad9] |
|
|
X |
|
| Keypad Dot | [keypad.] |
|
|
X |
|
| Keypad Enter | [keypadenter] |
|
|
X |
|
| Keypad Comma | [keypad,] |
|
|
X |
|
| Keypad Minus | [keypad-] |
|
|
X |
|
| New Line | [newline] | X |
X |
|
X |
| PA1 | [pa1] | X |
X |
|
X |
| PA2 | [pa2] | X |
X |
|
X |
| PA3 | [pa3] | X |
X |
|
X |
| Page Up | [pageup] | X |
X |
X |
|
| Page Down | [pagedn] | X |
X |
X |
|
| Reset | [reset] | X |
X |
X |
X |
| System Request | [sysreq] | X |
X |
|
X |
| Tab Field | [tab] | X |
X |
X |
|
| Test Request | [test] |
|
X |
|
|
| Function | Mnemonic Keyword | 3270 | 5250 | VT | CICS |
| Auto Push | [autopush] | X |
|
|
X |
| Auto Reverse | [autorev] | X |
|
X |
|
| Base | [base] | X |
X |
|
|
| BIDI Layer | [bidilayer] |
|
|
|
|
| Close | [close] |
|
X |
|
|
| CSD | [csd] | X |
|
|
X |
| End Push | [endpush] | X |
|
|
X |
| Field Reverse | [fldrev] | X |
X |
|
X |
| Field Shape | [fieldshape] | X |
|
|
X |
| Final | [final] | X |
|
|
X |
| Initial | [initial] | X |
|
|
X |
| Isolated | [isolated] | X |
|
|
X |
| Latin Layer | [latinlayer] | X |
X |
|
|
| Middle | [middle] | X |
|
|
X |
| Push | [push] | X |
|
|
X |
| Screen Reverse | [screenrev] | X |
X |
|
X |
The text plane represents the visible characters of the presentation space. Non-display fields are shown in the text plane. The value of each element of the text plane corresponds to the Unicode value of the displayed character. The text plane does not contain binary zero (null) character values. Any null characters in the presentation space (such as null-padded input fields) are represented as Unicode blank (0x0020) characters.
When dealing with DBCS languages, the text plane has some unique characteristics. Because each double-byte character takes up two positions in the presentation space, the text plane actually contains two of the same Unicode DBCS characters at the positions corresponding to the two positions that the single character occupies in the presentation space. This characteristic is analogous to the two bytes required to represent a double-byte character in the ASCII and EBCDIC character sets. The DBCS plane can be used to determine whether a character is the first or second in these pairs of duplicate characters.
The DBCS plane contains DBCS attribute data for each character and field attribute in the presentation space. The position of the DBCS character attribute data corresponds directly to the respective character in the text plane. The position of the DBCS field attribute data corresponds directly to the respective field attribute in the field plane.