Verastreamę Bridge Integrator 3.1

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

Verastreamę Bridge Integrator 3.1