com.attachmate.cicsbridge
Interface BridgeAPI

public interface BridgeAPI

This is a modernized Verastream Bridge Integrator's BridgeAPI

This implementation support some basic Java logging.
SEVERE - major problems and exceptions
WARNING - unexpected exception that will be correctly thrown as part of the API
FINE - common documented exceptions that are about to be thrown as part of the API
FINER - arguments passed into the API
FINEST - return values from the API

Since:

1.0

Method Summary

void	changePassword(java.lang.String hostIP, int hostPort, java.lang.String userId, java.lang.String password, java.lang.String newPassword) Changes the password for a given userId.
void	connectBridge(java.lang.String hostIP, int hostPort, TerminalModelType terminalModel, java.lang.String userid, java.lang.String password, java.lang.String terminalPoolName) Obtains a session state context from the host data engine.
void	connectBridge(java.lang.String hostIP, int hostPort, TerminalModelType terminalModel, java.lang.String userid, java.lang.String password, java.lang.String terminalPoolName, java.lang.String networkName, java.lang.String terminalFacilityLike) Obtains a session state context from the host data engine.
void	disconnect() Disconnects the session, releasing the session state context from the host data engine.
Position	findString(java.lang.String stringToFind, Position position, java.util.EnumSet<FindFlag> flags) Attempts to locate a given string on the current screen, beginning at a specified row and column position.
java.lang.String	getCurrentScreenName() Returns the name of the current host screen.
Position	getCursorPosition() Retrieves the cursor position on the current host screen.
Attribute	getFieldAttribute(java.lang.String fieldName) Retrieves the attribute of a specified field on the current screen.
Dimension	getFieldCoordinates(java.lang.String fieldName) Retrieves the coordinates (row, column, and length) of a specified field on the current screen.
int	getFieldCount() Retrieves the number of fields on the screen.
java.lang.String	getFieldNameFromIndex(int fieldIndex) Retrieves the name for the field with the specified index on the current screen.
java.lang.String	getFieldValue(java.lang.String fieldName) Retrieves the value of the specified field on the current screen.
ScreenInformation	getScreenInformation() Gets all relevant information for a given session.
java.lang.String	getString(Position position, int length) Retrieves any text on the current screen at the specified row, column, and length.
java.lang.String	getTerminalID() Retrieves the checked out terminal ID for this session.
TerminalModelType	getTerminalModelType() Retrieves the Terminal Model Type.
TraceConfiguration	getTraceConfiguration() Retrieves the TraceConfiguration object to allow you to turn host tracing on or off.
boolean	isConnected() Returns the status of the host connection.
int	putString(java.lang.String text, Position position) Writes text to the session presentation space beginning at the row and column specified.
void	sendKeys(java.lang.String keys) Writes text to the session presentation space beginning at the current cursor position.
java.lang.String	sendKeysGetString(java.lang.String keys, Position position, int length) Sends a sequence of keystrokes and AID keys to the host and retrieves any text on the current screen at the specified row, column, and length.
void	setCursorPosition(Position position) Sets the cursor position on the current host screen.
void	setFieldValue(java.util.List<java.lang.String> fields, java.util.List<java.lang.String> values) Sets the value of an array of specified unprotected fields on the current screen with a single call.
void	setFieldValue(java.lang.String field, java.lang.String value) Sets the value of the specified unprotected field on the current screen.
ScreenInformation	x3270Screen(java.lang.String keys, java.util.List<java.lang.String> fieldNames, java.util.List<java.lang.String> fieldValues) Place String value into the specified 3270 field of the current screen buffer, execute an AID key sequence, and get all relevant 3270 information from the requested screen in a given session.
ScreenInformation	x3270Screen(java.lang.String keys, java.lang.String fieldName, java.lang.String fieldValue) Place String value into the specified 3270 field of the current screen buffer, execute an AID key sequence, and get all relevant 3270 information from the requested screen in a given session.

Method Detail

connectBridge

void connectBridge(java.lang.String hostIP,
                   int hostPort,
                   TerminalModelType terminalModel,
                   java.lang.String userid,
                   java.lang.String password,
                   java.lang.String terminalPoolName,
                   java.lang.String networkName,
                   java.lang.String terminalFacilityLike)
                   throws BridgeException

Obtains a session state context from the host data engine. If the destination CICS region requires a CESN sign-on and the connectBridge does not pass a valid UserId and Password, the 3270 session is presented with the CESN sign-on screen upon completing the connectBridge. If a valid UserId and Password are passed in on the connectBridge, the user is Authenticated without requiring a separate CESN logon. Upon completion of a successful connectBridge featuring a valid UserId and Password, the session is at a clear screen, ready for a transaction to be initiated by the user.

Parameters:

hostIP - IP address of the target host CICS region (for example, '234.164.88.1').

hostPort - Port corresponding to the target CICS region.

terminalModel - 3270 terminal model type (valid values: 2 for Model 2, 3 for Model 3, 4 for Model 4, 5 for Model 5).

userid - The user ID for the host data engine to use with the External Security Manager on behalf of this session. If no userid is desired, use a null.

password - The password for the host data engine to use with the External Security Manager on behalf of this session. If no userid is desired, use a null.

terminalPoolName - The terminal pool name from which to draw the desired 3270 connection. If no particular pool is desired, pass in null.

networkName - The one to eight character to be assigned to the pseudo LU for the new connection. To use default name for this connection, pass in null.

terminalFacilityLike - The optional text format IP address of the requesting client. To omit client IP address, pass in null.

Throws:

BridgeException

connectBridge

void connectBridge(java.lang.String hostIP,
                   int hostPort,
                   TerminalModelType terminalModel,
                   java.lang.String userid,
                   java.lang.String password,
                   java.lang.String terminalPoolName)
                   throws BridgeException

Obtains a session state context from the host data engine. If the destination CICS region requires a CESN sign-on and the connectBridge does not pass a valid UserId and Password, the 3270 session is presented with the CESN sign-on screen upon completing the connectBridge. If a valid UserId and Password are passed in on the connectBridge, the user is Authenticated without requiring a separate CESN logon. Upon completion of a successful connectBridge featuring a valid UserId and Password, the session is at a clear screen, ready for a transaction to be initiated by the user.

Parameters:

hostIP - IP address of the target host CICS region (for example, '234.164.88.1').

hostPort - Port corresponding to the target CICS region.

terminalModel - 3270 terminal model type (valid values: 2 for Model 2, 3 for Model 3, 4 for Model 4, 5 for Model 5).

userid - The user ID for the host data engine to use with the External Security Manager on behalf of this session. If no userid is desired, use a null.

password - The password for the host data engine to use with the External Security Manager on behalf of this session. If no userid is desired, use a null.

terminalPoolName - The terminal pool name from which to draw the desired 3270 connection. If no particular pool is desired, pass in null.

Throws:

BridgeException

disconnect

void disconnect()
                throws BridgeException

Disconnects the session, releasing the session state context from the host data engine.

Throws:

BridgeException

findString

Position findString(java.lang.String stringToFind,
                    Position position,
                    java.util.EnumSet<FindFlag> flags)
                    throws BridgeException

Attempts to locate a given string on the current screen, beginning at a specified row and column position.

Parameters:

stringToFind - The string to search for on the current screen.

position - The row, col position at which to start the search

flags - is the EnumSet of flags that will control the find behavior. A value of null will perform a screen-wide, case-sensitive, non-wrapping, forward search.

Returns:

Coordinates containing the row position and column position where the string was found.

Throws:

BridgeException

isConnected

boolean isConnected()
                    throws BridgeException

Returns the status of the host connection.

Returns:

The status of the host connection.

Throws:

BridgeException

getCurrentScreenName

java.lang.String getCurrentScreenName()
                                      throws BridgeException

Returns the name of the current host screen.

Returns:

The name of the current screen.

Throws:

BridgeException

getCursorPosition

Position getCursorPosition()
                           throws BridgeException

Retrieves the cursor position on the current host screen.

Returns:

The cursor row and column position

Throws:

BridgeException

getFieldAttribute

Attribute getFieldAttribute(java.lang.String fieldName)
                            throws BridgeException

Retrieves the attribute of a specified field on the current screen.

Parameters:

fieldName - The name of the field.

Returns:

Attribute for the specified field

Throws:

BridgeException

getFieldCoordinates

Dimension getFieldCoordinates(java.lang.String fieldName)
                              throws BridgeException

Retrieves the coordinates (row, column, and length) of a specified field on the current screen.

Parameters:

fieldName - The name of the field for which coordinates are desired.

Returns:

The row and column location and the length of the specified field

Throws:

BridgeException

getFieldCount

int getFieldCount()
                  throws BridgeException

Retrieves the number of fields on the screen.

Returns:

The number of fields for the given screen.

Throws:

BridgeException

getFieldNameFromIndex

java.lang.String getFieldNameFromIndex(int fieldIndex)
                                       throws BridgeException

Retrieves the name for the field with the specified index on the current screen. The index numbers start at zero and end at 1 less than the field count.

Parameters:

fieldIndex - The index number of the field on the screen. The index is zero-based. This number must be less than the number of fields returned in getFieldCount().

Returns:

The returned field name.

Throws:

BridgeException

getFieldValue

java.lang.String getFieldValue(java.lang.String fieldName)
                               throws BridgeException

Retrieves the value of the specified field on the current screen.

Parameters:

fieldName - The name of the field for which you are requesting a value.

Returns:

The returned value of the specified field.

Throws:

BridgeException

getScreenInformation

ScreenInformation getScreenInformation()
                                       throws BridgeException

Gets all relevant information for a given session.

Returns:

All the information about the current screen

Throws:

BridgeException

getTerminalModelType

TerminalModelType getTerminalModelType()
                                       throws BridgeException

Retrieves the Terminal Model Type.

Returns:

The number of rows and columns of the current screen

Throws:

BridgeException

getString

java.lang.String getString(Position position,
                           int length)
                           throws BridgeException

Retrieves any text on the current screen at the specified row, column, and length. If the length parameter is zero, getString retrieves text from the specified row and column to the end of the screen. The Row and Column parameters must always be greater than or equal to 1. The getString method returns the correct value even though it is contained in non-display fields. Therefore, be sure to check the field attribute prior to displaying text retrieved with this method.

Parameters:

position - The row, col position on the host screen at which to begin retrieving text.

length - The length of the text string to be retrieved. If this value is zero, the text is retrieved up to the end of the screen.

Returns:

The text that is retrieved.

Throws:

BridgeException

getTerminalID

java.lang.String getTerminalID()
                               throws BridgeException

Retrieves the checked out terminal ID for this session. If no terminal was checked out, retrieves spaces.

Returns:

The checked out terminal ID for this session, or spaces.

Throws:

BridgeException

putString

int putString(java.lang.String text,
              Position position)
              throws BridgeException

Writes text to the session presentation space beginning at the row and column specified. If a protected field is encountered while writing, characters from the text string are discarded, and writing continues with the next unprotected field.

Parameters:

text - The text string to write, beginning at the specified position.

position - The row, col position on the host screen at which to begin writing the text string.

Returns:

The returned number of characters that were actually written to the screen

Throws:

BridgeException

sendKeys

void sendKeys(java.lang.String keys)
              throws BridgeException

Writes text to the session presentation space beginning at the current cursor position. If a protected field is encountered while writing, characters from the text string are discarded, and writing continues with the next unprotected field. If the HLLAPI representation of an AID keystroke is encountered in the text string, sendKeys initiates transmission to the host of the Aid key followed by any modified fields in the session presentation space. Text and AID keystrokes can be combined multiple times in the input string in this implementation.

Parameters:

keys - The keys to send to the host. The HLLAPI representations for special keys that can be used follows: AID key : Key Sequence
"@A@F" : Erase Input
"@B" : Backtab
"@C" : Clear
"@E" : Enter
"@F" : Erase EOF
"@L" : Cursor left
"@N" : Newline
"@T" : Tab
"@U" : Cursor up
"@V" : Cursor down
"@Z" : Cursor right
"@<" : Backspace
"@0" : Home
"@1" : PF1
"@2" : PF2
"@3" : PF3
"@4" : PF4
"@5" : PF5
"@6" : PF6
"@7" : PF7
"@8" : PF8
"@9" : PF9
"@a" : PF10
"@b" : PF11
"@c" : PF12
"@d" : PF13
"@e" : PF14
"@f" : PF15
"@g" : PF16
"@h" : PF17
"@i" : PF18
"@j" : PF19
"@k" : PF20
"@l" : PF21
"@m" : PF22
"@n" : PF23
"@o" : PF24
"@x" : PA1
"@y" : PA2
"@z" : PA3

Throws:

BridgeException

sendKeysGetString

java.lang.String sendKeysGetString(java.lang.String keys,
                                   Position position,
                                   int length)
                                   throws BridgeException

Sends a sequence of keystrokes and AID keys to the host and retrieves any text on the current screen at the specified row, column, and length. If the length parameter is zero, getString retrieves text from the specified row and column to the end of the screen. The Row and Column parameters must always be greater than or equal to 1. The sendKeysGetString method returns the correct value even though it is contained in non-display fields. Therefore, be sure to check the field attribute prior to displaying text retrieved with this method.

Parameters:

keys - The HLLAPI style string of keys to send before collecting the requested string.

position - The row, col position on the host screen at which to begin retrieving text.

length - The length of the text string to be retrieved. If this value is zero, the text is retrieved up to the end of the screen.

Returns:

The text that is retrieved.

Throws:

BridgeException

setCursorPosition

void setCursorPosition(Position position)
                       throws BridgeException

Sets the cursor position on the current host screen.

Parameters:

position - The cursor row, col position. The first row and col is 1.

Throws:

BridgeException

setFieldValue

void setFieldValue(java.util.List<java.lang.String> fields,
                   java.util.List<java.lang.String> values)
                   throws BridgeException

Sets the value of an array of specified unprotected fields on the current screen with a single call. Use of this function will increase performance of applications when updating multiple fields.

Parameters:

fields - A List of type String, each occurrence of which describes the name of the field to have its value replaced.

values - A List of type String, each occurrence of which specifies the new value to be placed into the above named field.

Throws:

BridgeException

setFieldValue

void setFieldValue(java.lang.String field,
                   java.lang.String value)
                   throws BridgeException

Sets the value of the specified unprotected field on the current screen.

Parameters:

field - The field for which a value is to be set.

value - The value to set for the specified field.

Throws:

BridgeException

getTraceConfiguration

TraceConfiguration getTraceConfiguration()

Retrieves the TraceConfiguration object to allow you to turn host tracing on or off.

Returns:

TraceConfiguration

x3270Screen

ScreenInformation x3270Screen(java.lang.String keys,
                              java.lang.String fieldName,
                              java.lang.String fieldValue)
                              throws BridgeException

Place String value into the specified 3270 field of the current screen buffer, execute an AID key sequence, and get all relevant 3270 information from the requested screen in a given session.

Parameters:

keys - A string to be typed into the 3270 session including Verastream® Bridge Integrator mnemonics:
"@B" : BACKTAB
"@C" : CLEAR
"@E" : ENTER
"@F" : ERASE EOF
"@T" : TAB
"@1" : PF01
"@2" : PF02
"@3" : PF03
"@4" : PF04
"@5" : PF05
"@6" : PF06
"@7" : PF07
"@8" : PF08
"@9" : PF09
"@a" : PF10
"@b" : PF11
"@c" : PF12
"@d" : PF13
"@e" : PF14
"@f" : PF15
"@g" : PF16
"@h" : PF17
"@i" : PF18
"@j" : PF19
"@k" : PF20
"@l" : PF21
"@m" : PF22
"@n" : PF23
"@o" : PF24
"@x" : PA01
"@y" : PA02
"@z" : PA03
"@A@F" : ERASE INP
"@A@P" : Put information (setFieldValue) on screen at this place in the key sequence
"@A@G" : Get information (getScreenInformation) from screen at this place in the key sequence
"@A@X" : After control is returned to the caller, Disconnect this session

fieldName - String containing the name of the 3270 field into which the value should be placed

fieldValue - String containing the value to place into the field identified by fieldName

Returns:

ScreenInfo for the requested screen or the current screen

Throws:

BridgeException

x3270Screen

ScreenInformation x3270Screen(java.lang.String keys,
                              java.util.List<java.lang.String> fieldNames,
                              java.util.List<java.lang.String> fieldValues)
                              throws BridgeException

Place String value into the specified 3270 field of the current screen buffer, execute an AID key sequence, and get all relevant 3270 information from the requested screen in a given session.

Parameters:

keys - A string to be typed into the 3270 session including Verastream® Bridge Integrator mnemonics, see x3270Screen(String, String, String)

fieldNames - List of Strings with the names of the 3270 fields into which values should be placed

fieldValues - List of Strings containing the values to place into the fields identified by the correlated inFieldNames array

Returns:

ScreenInfo for the requested screen or the current screen

Throws:

BridgeException

changePassword

void changePassword(java.lang.String hostIP,
                    int hostPort,
                    java.lang.String userId,
                    java.lang.String password,
                    java.lang.String newPassword)
                    throws BridgeException

Changes the password for a given userId. The userId, encrypted password, and encrypted newPassword are sent to the host. If the password is correct for the userId then the new password is set as the valid password for this userId.

Parameters:

hostIP - IP address of target CICS region in the form of nnn.nnn.nnn.nnn.

hostPort - TCP port address of target CICS region.

userId - User identification one to eight characters in length.

password - Existing password one to eight characters in length for the given userId.

newPassword - Proposed new password one to eight characters in length to use for the given userId.

Throws:

BridgeException