Session Manager API

Functional Requirements

The Session Manager API document describes the Session Manager APIs provided by Z and I Emulator for Web (ZIEWeb) for embedding host sessions in Web pages using JavaScript.

Brief Description:

In addition to the Application Programming Interfaces (APIs) provided with the Host Access Toolkit, Z and I Emulator for Web (ZIEWeb) 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 Z and I Emulator for Web (ZIEWeb) Session Manager.

The APIs are divided into the following four sets:

• Session Manager APIs

• Presentation Space APIs

• Z and I Emulator for Web (ZIEWeb) Functions APIs

• Error Reporting APIs

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.

API Functionality and Documentation:

• function startSession (String session)

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.

Returns

• function getSessionID ()

The getSessionIDmethod 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 JSHostOnDemandapplet 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.

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 startSessionmethod.

• function getAllSessionNames ()

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 – B

Parameters: None.
Returns: A string of all active sessions' full session names; or null if no active session; or "-2" if exception error.

• function stopSession ()

The stopSession method stops the currently selected session.

Parameters: None.
Returns:

• function stopSession1 (String sessionName)

This signature of the stopSessionmethod stops the specified session.

Parameters:
sessionName: the full name of the session to be stopped.
Returns:

• function stopAllSessions ()

The stopAllSessionsmethod stops all active sessions.

Parameters: None.
Returns:

• function connectSession ()

The connectSessionmethod connects the currently selected session.

Parameters: None.
Returns

• function connectSession1 (String sessionName)

This signature of the connectSession method connects the specified session.

Parameters:
sessionName: the full name of the session to be connected.
Returns:

• function disconnectSession ()

ThedisconnectSessionmethod disconnects the currently selected session.

Parameters: None.
Returns:

• function disconnectSession1 (String sessionName)

This signature of the disconnectSessionmethod disconnects the specified session.

Parameters:
sessionName: the full name of the session to be disconnected.
Returns:

• function displaySession ()

ThedisplaySessionmethod displays the currently selected session.

Parameters: None.
Returns:

• function displaySession1 (String sessionName)

This signature of the displaySession method displays the currently selected session.

Parameters:
sessionName: full name of the session to be displayed.
Returns:

• function booleanisHODLoaded()

The isHODLoadedmethod checks whether or not the Z and I Emulator for Web (ZIEWeb) applet is loaded. The main purpose of this method is for Cached Client users to confirm that Z and I Emulator for Web (ZIEWeb) is loaded before any of the JavaScript API functions are called. If the Z and I Emulator for Web (ZIEWeb) applet is not loaded and one of the APIs is called, the browser will give aNullPointerExceptionto the JavaScript.

Parameters: None.
Returns:
Returns true if ZIEWeb-Client page is loaded, and false otherwise.

• function sendKeys1 (String text)

ThesendKeysmethod 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:

• function sendKeys2 (String sessionName, String text)

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:

• function sendKeys3 (String sessionName, String text, intpos)

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.
post: 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.

Returns:

• function sendKeys4 (String sessionName, String text, int row, int col)

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.
col: the starting column where keys should be sent.

Returns:

• function setString1 (String text)

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:

• function setString2 (String sessionName, String text)

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:

• function setString3 (String sessionName, String text, intpos)

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.

Returns:

• function setString4 (String sessionName, String text, int row, int col)

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:

• function getString ()

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 theJSHostOnDemand 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:

• function getString1 (String sessionName)

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:

• function getString3 (String sessionName, intpos, int length)

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:

• function getString4 (String sessionName, int row, int col, int length)

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:

• function getStringLength ()

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.

• function inputInhibited ()

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:

• function inputInhibited1 (String sessionName)

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:

• function reset ()

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:

• function reset1 (String sessionName)

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.

• public booleanisCommReady ()

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.

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.

• public boolean isCommReady1 (String sessionName)

This signature of theisCommReadymethod 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.

Parameters:
text: 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.

• function waitForStringInRect8 (String text, intsRow, intsCol, inteRow, inteCol, long timeout, booleanwaitForInput, booleancaseSensitive)

The waitForStringInRect 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 eRowand 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:

• function waitForStringInRect9 (String sessionName, String text, intsRow, intsCol, inteRow, inteCol, long timeout, booleanwaitForInput, booleancaseSensitive)

The waitForStringInRect 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:

• function waitWhileStringInRect8 (String text, intsRow, intsCol, inteRow, inteCol, long timeout, booleanwaitForInput, booleancaseSensitive)

The waitWhileStringInRect 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 can 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:

• function waitWhileStringInRect9 (String sessionName, String text, intsRow, intsCol, inteRow, inteCol, long timeout, booleanwaitForInput, booleancaseSensitive)

The waitWhileStringInRect 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 can enter keystrokes like 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:

• function startMacro1(String macroName)

This signature of 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:

• function startMacro2(String sessionName, String macroName)

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: full name of the session to be used to start the macro.
macroName: name of the macro to be started.

Returns:

• function getErrorMessage ()

The getErrorMessage method returns a saved error message from the last API call. If there was an exception thrown by Z and I Emulator for Web (ZIEWeb) or Java because of one of the above API calls, then this method returns the exception message.

All exceptions thrown by the Z and I Emulator for Web (ZIEWeb) 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.

How To Configure:

Configuration Steps-

1. Include Session Manager API JavaScript file in the <head> section of the application (webpage)
Code:
<script src="http://<IP_of_ZIEWeb_Server>:<port>/zieweb/js/sessionManagerAPI.js">

For Example:
<script src="http://localhost:9080/zieweb/js/sessionManagerAPI.js"> </script>

2. Create an object of the sessionManagerAPI. inside javascript <script> tags
Code: varhod_applet = new hod_session();

3. To start working with the API, first connection need to be established using the following API function call:
Code: hod_applet.createConnection(url);

**URL: should be the url of the ZIEWeb page
Example: http://localhost:9080/zieweb/abc_page.html

4. Once the connection is established and ZIEWeb-Client window is opened, make API calls using the javascript object.

Code:
varreturnValue=hodApplet.getSessionID(),
varreturnValue=hodApplet.connectSession()

5. The sample application page should be placed on the same server (WAS) where ZIEWeb-Client is installed.

Known Issue & Limitations:
1. Cross Browser Communication is not possible through Session Manager API.
2. callCustomerFunction is not supported.
3. WorkAround with iframe is not supported.
4. Text after host function pneumonic ([pf1]..[pf24],[enter]) will be ignored.
Example: [pf4]Some text