com.wrq.vhi.script.api
Interface HostSession

All Known Subinterfaces:

RemoteHostSession, ScriptHostSession

public interface HostSession

Provides information about a host session and allows for the manipulation of the terminal at various levels (direct, model, table).

Field Summary

static int	ANY_COLUMN Specifies any column for those methods that allow it as a column value.
static int	ANY_ROW Specifies any row for those methods that allow it as a row value.
static int	CURRENT_COLUMN Specifies the current column for those methods that allow it as a column value.
static int	CURRENT_ROW Specifies the current row for those methods that allow it as a row value.
static int	DESIGN_TOOL_AND_SERVER context parameter for the defaultValue(java.lang.String, java.lang.String, int) method which specifies a value to be used only when using both the Design Tool and Server.
static int	DESIGN_TOOL_ONLY context parameter for the defaultValue(java.lang.String, java.lang.String, int) method which specifies a value to be used only when using the Design Tool.
static int	DONT_WAIT_FOR_ECHO echoType which means not to wait for the data written to the terminal to be echoed.
static int	LINEAR_REGION regionType parameter for the waitForUpdate(int, int, int, int, int, boolean, int) method which specifies a linear region.
static int	RECTANGULAR_REGION regionType parameter for the waitForUpdate(int, int, int, int, int, boolean, int) method which specifies a rectangular region.
static int	SCROLL_END movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's End operation.
static int	SCROLL_HOME movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Home operation.
static int	SCROLL_LINE_DOWN movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Line Down operation.
static int	SCROLL_LINE_UP movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Line Up operation.
static int	SCROLL_PAGE_DOWN movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Page Up operation.
static int	SCROLL_PAGE_UP movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Page Down operation.
static int	SYNC_TO_HOST index parameter for the setCurrentRecordIndex(int) method which specifies to set the current index to the current host record.
static int	WAIT_FOR_CURSOR_AUTOTAB echoType which means to wait until the cursor reaches the next tabstop.
static int	WAIT_FOR_CURSOR_MOVE echoType which means to wait after writing only until the cursor moves.
static int	WAIT_FOR_ECHO_BEHIND_CURSOR echoType which means to wait until the data written appears behind the cursor.
static int	WAIT_FOR_ECHO_SAME_NUMBER echoType which means to wait for the same number of characters which were written are echoed.
static int	WAIT_FOR_ECHO_TAB_OR_BEHIND_CURSOR echoType which means to wait for the same data to be echoed or for the cursor to appear at the next tabstop.

Method Summary

void	checkOperationConditions() Verifies that operation conditions, as defined in the model, are satisfied.
void	defaultValue(java.lang.String attribute, java.lang.String value, int context) Transmits a value to an attribute when unmodified.
void	executeCommandList(CommandList list) Executes the specified command list.
void	executeOperation(java.lang.String operation) Performs an operation on the current entity.
ProcedureRecordSet	executeSQLStatement(java.lang.String sqlStatement) Executes an SQL statement on a table defined in the model.
ProcedureRecordSet	executeTableProcedure(java.lang.String tableName, java.lang.String procedureName, java.util.Map dataInputValues, java.util.Map filterValues, boolean filterIsCaseSensitive, java.util.List outputColumnNames, int maxRows) Performs a procedure on a table defined in the model.
ModelRecordSet	fetchRecords(int maxRows, java.util.List fields, java.lang.String filterExpression) Fetches up to the maximum number of rows specified from the current recordset starting with the next record.
java.lang.String	getAttribute(java.lang.String attribute) Reads the specified attribute on the current entity and returns the value.
java.lang.String	getAttributeAtCursor() Gets the name of the attribute at the current cursor position.
AttributeMetaData	getAttributeMetaData(java.lang.String entity, java.lang.String attribute) Gets the metadata for the specified attribute.
TerminalRegion	getAttributeRegion(java.lang.String attribute) Gets the location and contents of the specified attribute.
java.util.Map	getAttributeRegions(java.util.List attributes) Gets the location and contents of the specified attributes.
java.util.Map	getAttributes() Reads all the attributes on the current entity and returns their values.
java.util.Map	getAttributes(java.util.List attributes) Reads the specified attributes on the current entity and returns their values.
ColumnMetaData	getColumnMetaData(java.lang.String table, java.lang.String column) Gets the metadata for the specified column in a table.
java.lang.String	getCurrentEntity() Gets the current entity (screen) of the legacy application.
ModelRecord	getCurrentRecord() Fetches the current record in the current recordset.
int	getCurrentRecordIndex() Gets the index of the current record in the current recordset.
java.lang.String	getCurrentRecordSet() Gets the name of the current recordset.
CursorPosition	getCursorPosition() Gets the current position of the cursor on the terminal screen.
java.util.List	getEntityAttributes(java.lang.String entity) Gets the names of all attributes on the specified entity.
java.lang.String	getEntityDescription(java.lang.String entity) Gets the description for an entity.
java.util.List	getEntityOperations(java.lang.String entity) Gets the names of all operations on the specified entity.
java.util.List	getEntityRecordSets(java.lang.String entity) Gets the names of all recordsets on the specified entity.
FieldMetaData	getFieldMetaData(java.lang.String entity, java.lang.String recordset, java.lang.String field) Gets the metadata for the specified recordset field.
TerminalRegion	getFieldRegion(java.lang.String field) Gets the location and contents of the specified field in the current record of the current recordset.
java.util.Map	getFieldRegions(java.util.List fields) Gets the location and contents of the specified fields in the current record of the current recordset.
java.lang.String	getHomeEntity() Gets the name of the home entity for the model.
LinearTerminalRegion	getLinearTerminalRegion(int offset, int length) Gets the contents of a linear region of the terminal screen.
java.util.List	getModelEntities() Gets the names of all entities in the model.
java.lang.String	getModelVariable(java.lang.String variable) Gets the value of a model variable.
java.util.List	getModelVariableNames() Gets the names of all variables in the model.
java.util.Map	getModelVariables() Gets the values of all model variables.
OperationMetaData	getOperationMetaData(java.lang.String entity, java.lang.String operation) Gets the metadata for the specified operation.
TerminalRegion	getPatternRegion(java.lang.String pattern) Gets the location and contents of the specified pattern.
java.util.Map	getPatternRegions(java.util.List patterns) Gets the location and contents of the specified patterns.
ProcedureMetaData	getProcedureMetaData(java.lang.String table, java.lang.String procedure) Gets the metadata for the specified procedure in a table.
TerminalRegion	getRecordRegion(java.lang.String recordset) Gets the location and contents of the current record in the specified recordset.
RecordSetMetaData	getRecordSetMetaData(java.lang.String entity, java.lang.String recordset) Gets the metadata for the specified recordset.
TerminalRegion	getRecordSetRegion(java.lang.String recordset) Gets the location and contents of the specified recordset.
RectangularTerminalRegion	getRectangularTerminalRegion(int topRow, int leftColumn, int numRows, int numColumns) Gets the contents of a rectangular region of the terminal screen.
java.lang.String	getStringAtCursor(int length) Gets a string from a linear region of the terminal screen starting at the current cursor position.
java.lang.String	getStringAtLocation(int topRow, int leftColumn, int numRows, int numColumns) Gets a string from a rectangular region of the terminal screen starting at the given row and column.
java.lang.String	getStringAtOffset(int offset, int length) Gets a string from a linear region of the terminal screen starting at the given offset.
java.util.List	getTableColumns(java.lang.String table) Gets the names of all columns in the specified table.
java.lang.String	getTableDescription(java.lang.String table) Gets the description for a table.
java.util.List	getTableNames() Gets the names of all tables in the model.
java.util.List	getTableProcedures(java.lang.String table) Gets the names of all procedures in the specified table.
RectangularTerminalRegion	getTerminalScreen() Gets the size and contents of the terminal screen.
ScreenSize	getTerminalScreenSize() Gets the size of the terminal screen without the contents.
VariableMetaData	getVariableMetaData(java.lang.String variable) Gets the metadata for the specified variable.
void	insertRecord(java.util.Map record) Inserts a record into the current recordset.
void	insertRecords(java.util.List records) Inserts multiple records into the current recordset.
void	moveCurrentRecordIndex(int movement) Moves the current record index to a new position in the current recordset.
void	moveCursor(int row, int column) Sets the position of the cursor using row-column coordinates.
void	navigate(java.lang.String entity) Equivalent to calling the setCurrentEntity(java.lang.String) method.
ModelRecord	nextRecord(java.lang.String filterExpression) Finds and return a record in the current recordset using a filter expression starting with the record following the current record.
void	readFromMappedAttribute(java.lang.String attribute) Reads an attribute on the current entity and stores its value into the variable mapped to that attribute.
void	readVariableFromAttribute(java.lang.String attribute, java.lang.String variable) Reads an attribute on the current entity and stores its contents in a variable.
void	readVariableFromField(java.lang.String recordset, java.lang.String field, java.lang.String variable) Reads a field from the current record and stores its contents in a variable.
void	readVariableFromLocation(java.lang.String variable, int row, int column, int length) Reads data directly from the terminal and stores it in a variable.
void	readVariableFromTerminal(java.lang.String variable, int length) Reads terminal data at the current cursor position and stores it in a variable.
void	resetRecordSet(java.lang.String recordset) Resets the state of a recordset on the current entity.
void	selectCurrentRecord() Performs the model-defined selection operation for the current recordset.
boolean	selectRecordByFilter(java.lang.String filterExpression) Finds a record in the current recordset using a filter expression and performs the model-defined selection operation.
boolean	selectRecordByIndex(int index) Sets the current record in the current recordset by index and then performs the model-defined selection operation.
void	setAttribute(java.lang.String attribute, java.lang.String value) Writes a value to the specified attribute on the current entity.
void	setAttributeDelayed(java.lang.String entity, java.lang.String attribute, java.lang.String value) Queues a value to be written to the specified attribute on the specified entity.
void	setAttributes(java.util.Map attributes) Writes values to the specified attributes on the current entity.
void	setAttributesDelayed(java.lang.String entity, java.util.Map attributes) Queues values to be written to the specified attributes on the specified entity.
void	setCurrentEntity(java.lang.String entity) Sets the current entity.
boolean	setCurrentRecordIndex(int index) Sets the current record in the current recordset by index.
void	setCurrentRecordSet(java.lang.String recordset) Sets the current recordset by name.
void	setModelVariable(java.lang.String variable, java.lang.String value) Sets the value of a variable.
void	setModelVariables(java.util.Map variables) Sets the values of one or more variables.
void	shiftCursor(int vertical, int horizontal) Moves the cursor relative to its current position.
void	transmit(java.lang.String string) Writes a string to the terminal at the current cursor position using DONT_WAIT_FOR_ECHO.
void	transmit(java.lang.String string, int echoType) Writes a string to the terminal at the current cursor position.
void	transmitTerminalKey(int key) Sends a non-alphanumeric terminal key (for example, a Program Function key or a 3270 AID key) to the host.
void	transmitToAttribute(java.lang.String attribute, java.lang.String value) Writes a string to an attribute on the current entity.
void	transmitToField(java.lang.String recordset, java.lang.String field, java.lang.String value) Writes a string to a field in the current record in the current recordset.
void	transmitToLocation(java.lang.String string, int row, int column) Transmits a string to the terminal at the specified screen location using DONT_WAIT_FOR_ECHO.
void	transmitToLocation(java.lang.String string, int row, int column, int echoType) Transmits a string to the terminal at the specified screen location.
void	transmitToOffset(java.lang.String string, int offset) Transmits a string to the terminal at the specified offset using DONT_WAIT_FOR_ECHO.
void	transmitToOffset(java.lang.String string, int offset, int echoType) Transmits a string to the terminal at the specified offset.
void	updateAttribute(java.lang.String attribute) Writes the current entity's cached attribute data for the specified attribute.
void	updateAttributes() Writes the current entity's cached attribute data for all attributes.
void	updateAttributes(java.util.Collection attributes) Writes the current entity's cached attribute data for the specified attributes.
void	updateCurrentRecord(java.util.Map record) Updates the field values of the current record in the current recordset.
boolean	updateRecordByFilter(java.util.Map record, java.lang.String filterExpression) Finds a record in the current recordset using a filter expression and updates its field values.
boolean	updateRecordByIndex(java.util.Map record, int index) Updates the field values of the record at the specified index.
int	updateRecords(java.util.Map record, java.lang.String filterExpression) Finds records in the current recordset using a filter expression and update their field values.
void	updateRecordSetField(java.lang.String recordset, java.lang.String field) Writes the cached field data for the specified field in the recordset.
void	updateRecordSetFields(java.lang.String recordset) Writes the cached field data for all fields in the recordset.
void	updateRecordSetFields(java.lang.String recordset, java.util.Collection fields) Writes the cached field data for the specified fields in the recordset.
void	wait(int duration) Waits for the specified number of seconds.
void	waitForCommString(java.lang.String string, int timeout) Waits until the given string is received from the host.
void	waitForCommString(java.lang.String string, int timeout, int count) Waits until the given string is received from the host a specific number of times.
void	waitForCondition(java.lang.String entity, java.lang.String condition, int timeout) Waits for an expression to become true for the specified entity.
void	waitForCursorAtAttribute(java.lang.String entity, java.lang.String attribute, int timeout) Waits until the cursor is positioned within an attribute.
void	waitForCursorAtLocation(int row, int column, int timeout) Waits until the cursor is at the specified location.
void	waitForCursorAtRecordSetField(java.lang.String entity, java.lang.String recordset, java.lang.String field, int timeout) Waits until the cursor is positioned within a recordset field.
void	waitForCursorAtTerminalField(int row, int column, int timeout) Waits until the cursor is within the terminal field at the specified location.
void	waitForCursorNotAtLocation(int row, int column, int timeout) Waits until the cursor is not at the specified location.
void	waitForCursorNotAtTerminalField(int row, int column, int timeout) Waits until the cursor is not within the terminal field at the specified location.
void	waitForDisplayString(java.lang.String string, int row, int column, boolean relative, int timeout) Waits for the presence of a string starting at a particular terminal screen row and column.
java.lang.String	waitForEntities(java.util.List entities, int timeout) Waits until one of the specified entities is recognized.
void	waitForEntity(java.lang.String entity, int timeout) Waits until specified entity is recognized.
void	waitForHostData(int timeout) Processes any pending data received from the host.
void	waitForHostSilence(int duration, int timeout) Waits until data communication with the host is silent for the specified duration.
void	waitForKeyboardEnabled(int duration, int timeout) Waits for the keyboard to be enabled for the specified duration of time.
void	waitForMultipleEvents(java.lang.String expression, int timeout) Waits until the specified sequence of event expressions are satisfied.
void	waitForNewHostScreen(int timeout) Processes any pending data from the host.
void	waitForUpdate(int topRow, int leftColumn, int bottomRow, int rightColumn, int regionType, boolean relative, int timeout) Waits for the host to update a specified region on the terminal screen.
void	waitMS(int duration) Waits for the specified number of milliseconds.
void	writeToMappedAttribute(java.lang.String attribute) Writes to an attribute from its mapped variable.
void	writeVariableToAttribute(java.lang.String attribute, java.lang.String variable) Writes the contents of a variable to an attribute.
void	writeVariableToField(java.lang.String recordset, java.lang.String field, java.lang.String variable) Writes the contents of a variable to a field in the current record of a recordset defined on the current entity.
void	writeVariableToLocation(java.lang.String variable, int row, int column, int maxLength, boolean erase, int echoType) Writes the contents of a variable to the terminal at a specified location.
void	writeVariableToTerminal(java.lang.String variable, int maxLength, boolean erase, int echoType) Writes the contents of a variable to the terminal at the current cursor position.

Field Detail

DONT_WAIT_FOR_ECHO

static final int DONT_WAIT_FOR_ECHO

echoType which means not to wait for the data written to the terminal to be echoed.

WAIT_FOR_CURSOR_MOVE

static final int WAIT_FOR_CURSOR_MOVE

echoType which means to wait after writing only until the cursor moves.

WAIT_FOR_CURSOR_AUTOTAB

static final int WAIT_FOR_CURSOR_AUTOTAB

echoType which means to wait until the cursor reaches the next tabstop.

WAIT_FOR_ECHO_BEHIND_CURSOR

static final int WAIT_FOR_ECHO_BEHIND_CURSOR

echoType which means to wait until the data written appears behind the cursor.

WAIT_FOR_ECHO_SAME_NUMBER

static final int WAIT_FOR_ECHO_SAME_NUMBER

echoType which means to wait for the same number of characters which were written are echoed. The characters need not be the same, which is useful for things like password fields.

WAIT_FOR_ECHO_TAB_OR_BEHIND_CURSOR

static final int WAIT_FOR_ECHO_TAB_OR_BEHIND_CURSOR

echoType which means to wait for the same data to be echoed or for the cursor to appear at the next tabstop.

LINEAR_REGION

static final int LINEAR_REGION

regionType parameter for the waitForUpdate(int, int, int, int, int, boolean, int) method which specifies a linear region.

RECTANGULAR_REGION

static final int RECTANGULAR_REGION

regionType parameter for the waitForUpdate(int, int, int, int, int, boolean, int) method which specifies a rectangular region.

DESIGN_TOOL_ONLY

static final int DESIGN_TOOL_ONLY

context parameter for the defaultValue(java.lang.String, java.lang.String, int) method which specifies a value to be used only when using the Design Tool.

DESIGN_TOOL_AND_SERVER

static final int DESIGN_TOOL_AND_SERVER

context parameter for the defaultValue(java.lang.String, java.lang.String, int) method which specifies a value to be used only when using both the Design Tool and Server.

SCROLL_HOME

static final int SCROLL_HOME

movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Home operation.

SCROLL_END

static final int SCROLL_END

movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's End operation.

SCROLL_LINE_UP

static final int SCROLL_LINE_UP

movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Line Up operation.

SCROLL_LINE_DOWN

static final int SCROLL_LINE_DOWN

movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Line Down operation.

SCROLL_PAGE_UP

static final int SCROLL_PAGE_UP

movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Page Down operation.

SCROLL_PAGE_DOWN

static final int SCROLL_PAGE_DOWN

movement parameter for the moveCurrentRecordIndex(int) method which specifies to execute the recordset's Page Up operation.

SYNC_TO_HOST

static final int SYNC_TO_HOST

index parameter for the setCurrentRecordIndex(int) method which specifies to set the current index to the current host record.

ANY_ROW

static final int ANY_ROW

Specifies any row for those methods that allow it as a row value.

ANY_COLUMN

static final int ANY_COLUMN

Specifies any column for those methods that allow it as a column value.

CURRENT_ROW

static final int CURRENT_ROW

Specifies the current row for those methods that allow it as a row value.

CURRENT_COLUMN

static final int CURRENT_COLUMN

Specifies the current column for those methods that allow it as a column value.

Method Detail

checkOperationConditions

void checkOperationConditions()
                              throws ApptrieveException

Verifies that operation conditions, as defined in the model, are satisfied. This method should only be called during an operation.

This method is identical to the CheckOperationConditions command.

Throws:

ApptrieveException

defaultValue

void defaultValue(java.lang.String attribute,
                  java.lang.String value,
                  int context)
                  throws ApptrieveException

Transmits a value to an attribute when unmodified. An attribute is considered modified if it has been written since arriving at the current entity. Direct updates to the terminal via methods such as transmit() do not trigger the modified flag. If the attribute has not been modified, this method will trigger the AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) event handler.

This method is identical to the DefaultValue command.

Parameters:

attribute - name of attribute to be modified

value - the value to be transmitted

context - selects when the command will be executed:

• DESIGN_TOOL_ONLY - perform only in the design tool
• DESIGN_TOOL_AND_SERVER - perform in both the design tool and server

Throws:

ApptrieveException

moveCursor

void moveCursor(int row,
                int column)
                throws ApptrieveException

Sets the position of the cursor using row-column coordinates.

This method is identical to the MoveCursor command.

Parameters:

row - one-based vertical position of the cursor (CURRENT_ROW means the current cursor row).

column - one-based horizontal position of the cursor (CURRENT_COLUMN means the current cursor column).

Throws:

ApptrieveException

navigate

void navigate(java.lang.String entity)
              throws ApptrieveException

Equivalent to calling the setCurrentEntity(java.lang.String) method.

This method is identical to the Navigate command.

Parameters:

entity - name of the entity

Throws:

ApptrieveException

readFromMappedAttribute

void readFromMappedAttribute(java.lang.String attribute)
                             throws ApptrieveException

Reads an attribute on the current entity and stores its value into the variable mapped to that attribute.

This method is identical to the ReadFromMappedAttr command.

Parameters:

attribute - name of mapped attribute (on current entity) to read

Throws:

ApptrieveException

readVariableFromAttribute

void readVariableFromAttribute(java.lang.String attribute,
                               java.lang.String variable)
                               throws ApptrieveException

Reads an attribute on the current entity and stores its contents in a variable.

This method is identical to the ReadVarFromAttr command.

Parameters:

attribute - name of attribute on current entity to be read

variable - name of variable to be updated

Throws:

ApptrieveException

readVariableFromField

void readVariableFromField(java.lang.String recordset,
                           java.lang.String field,
                           java.lang.String variable)
                           throws ApptrieveException

Reads a field from the current record and stores its contents in a variable.

This method is identical to the ReadVarFromRecordSetField command.

Parameters:

recordset - name of recordset on current entity containing field to be read

field - name of field to be read

variable - name of variable to be updated

Throws:

ApptrieveException

readVariableFromLocation

void readVariableFromLocation(java.lang.String variable,
                              int row,
                              int column,
                              int length)
                              throws ApptrieveException

Reads data directly from the terminal and stores it in a variable.

This method is identical to the ReadVarFromLocation command.

Parameters:

variable - name of variable to be updated

row - the one-based row of the location to be read

column - the one-based column of the location to be read

length - the number of characters to be read

Throws:

ApptrieveException

readVariableFromTerminal

void readVariableFromTerminal(java.lang.String variable,
                              int length)
                              throws ApptrieveException

Reads terminal data at the current cursor position and stores it in a variable.

This method is identical to the ReadVarFromTerminal command.

Parameters:

variable - name of variable to be updated

length - the number of characters to be read

Throws:

ApptrieveException

resetRecordSet

void resetRecordSet(java.lang.String recordset)
                    throws ApptrieveException

Resets the state of a recordset on the current entity. All cached information about the recordset will be discarded, including information about what page number is current.

This method is identical to the ResetRecordset command.

Parameters:

recordset - name of recordset to be reset

Throws:

ApptrieveException

shiftCursor

void shiftCursor(int vertical,
                 int horizontal)
                 throws ApptrieveException

Moves the cursor relative to its current position.

This method is identical to the ShiftCursor command.

Parameters:

vertical - offset of the cursor (CURRENT_ROW means the current cursor row).

horizontal - offset of the cursor (CURRENT_COLUMN means the current cursor column).

Throws:

ApptrieveException

transmit

void transmit(java.lang.String string)
              throws ApptrieveException

Writes a string to the terminal at the current cursor position using DONT_WAIT_FOR_ECHO.

This method is identical to the TransmitANSI command with the rcDontWaitForEcho parameter.

Parameters:

string - the string to transmit

Throws:

ApptrieveException

transmit

void transmit(java.lang.String string,
              int echoType)
              throws ApptrieveException

Writes a string to the terminal at the current cursor position. The echoType parameter describes whether or not to wait for characters to be echoed, and must be one of the following integer constants:

• DONT_WAIT_FOR_ECHO
• WAIT_FOR_CURSOR_MOVE
• WAIT_FOR_CURSOR_AUTOTAB
• WAIT_FOR_ECHO_BEHIND_CURSOR
• WAIT_FOR_ECHO_SAME_NUMBER
• WAIT_FOR_ECHO_TAB_OR_BEHIND_CURSOR

This method is identical to the TransmitANSI command.

Parameters:

string - the string to transmit

echoType - specifies if VHI should wait for the characters to be echoed before returning. This parameter only has an effect on character mode hosts.

Throws:

ApptrieveException

transmitTerminalKey

void transmitTerminalKey(int key)
                         throws ApptrieveException

Sends a non-alphanumeric terminal key (for example, a Program Function key or a 3270 AID key) to the host. The key is one of the terminal key constants defined in AppConnAidKey.

This method is identical to the TransmitTerminalKey command.

Parameters:

key - the AppConnAidKey constant for the terminal key

Throws:

ApptrieveException

transmitToAttribute

void transmitToAttribute(java.lang.String attribute,
                         java.lang.String value)
                         throws ApptrieveException

Writes a string to an attribute on the current entity. This method will trigger the AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) event handler.

This method is identical to the TransmitToAttr command.

Parameters:

attribute - the attribute to be written

value - the value to write

Throws:

ApptrieveException

transmitToField

void transmitToField(java.lang.String recordset,
                     java.lang.String field,
                     java.lang.String value)
                     throws ApptrieveException

Writes a string to a field in the current record in the current recordset. This method will trigger the FieldEventHandler.writeField(com.wrq.vhi.script.api.WriteFieldEvent) event handler assuming the model is not configured to cache field writes. This method will not, however, trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler.

This method is identical to the TransmitToField command.

Parameters:

recordset - the field's recordset

field - the field in the recordset to be written

value - the value to write

Throws:

ApptrieveException

transmitToLocation

void transmitToLocation(java.lang.String string,
                        int row,
                        int column)
                        throws ApptrieveException

Transmits a string to the terminal at the specified screen location using DONT_WAIT_FOR_ECHO.

This method is identical to the TransmitToLocation command with the rcDontWaitForEcho parameter.

Parameters:

string - the string to transmit

row - the row number of the starting location for insertion

column - the column number of the starting location for insertion

Throws:

ApptrieveException

transmitToLocation

void transmitToLocation(java.lang.String string,
                        int row,
                        int column,
                        int echoType)
                        throws ApptrieveException

Transmits a string to the terminal at the specified screen location.

This method is identical to the TransmitToLocation command.

Parameters:

string - the string to transmit

row - the row number of the starting location for insertion (CURRENT_ROW means the current cursor row).

column - the column number of the starting location for insertion (CURRENT_COLUMN means the current cursor column).

echoType - specifies if VHI should wait for the characters to be echoed before returning. This parameter only has an effect on character mode hosts. See transmit(java.lang.String) for the list of valid echo types.

Throws:

ApptrieveException

transmitToOffset

void transmitToOffset(java.lang.String string,
                      int offset)
                      throws ApptrieveException

Transmits a string to the terminal at the specified offset using DONT_WAIT_FOR_ECHO.

This method is identical to the TransmitToOffset command with the rcDontWaitForEcho parameter.

Parameters:

string - the string to transmit

offset - character from the start of the screen buffer

Throws:

ApptrieveException

transmitToOffset

void transmitToOffset(java.lang.String string,
                      int offset,
                      int echoType)
                      throws ApptrieveException

Transmits a string to the terminal at the specified offset.

This method is identical to the TransmitToOffset command.

Parameters:

string - the string to transmit

offset - character from the start of the screen buffer

echoType - specifies if VHI should wait for the characters to be echoed before returning. This parameter only has an effect on character mode hosts. See transmit(java.lang.String) for the list of valid echo types.

Throws:

ApptrieveException

updateAttribute

void updateAttribute(java.lang.String attribute)
                     throws ApptrieveException

Writes the current entity's cached attribute data for the specified attribute. If data is cached for the attribute, this method will trigger the AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handler. This method will not, however, trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) event handler.

This method is identical to the UpdateAttribute command.

Parameters:

attribute - name of the attribute to update

Throws:

ApptrieveException

updateAttributes

void updateAttributes(java.util.Collection attributes)
                      throws ApptrieveException

Writes the current entity's cached attribute data for the specified attributes. If data is cached for one or more of the attributes, this method will trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) event handler.

Parameters:

attributes - Collection of attribute names to update

Throws:

ApptrieveException

updateAttributes

void updateAttributes()
                      throws ApptrieveException

Writes the current entity's cached attribute data for all attributes. If data is cached for one or more of the attributes, this method will trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) event handler.

This method is identical to the UpdateAttributes command.

Throws:

ApptrieveException

updateRecordSetField

void updateRecordSetField(java.lang.String recordset,
                          java.lang.String field)
                          throws ApptrieveException

Writes the cached field data for the specified field in the recordset. If data is cached for the field, this method will trigger the FieldEventHandler.writeField(com.wrq.vhi.script.api.WriteFieldEvent) event handler. This method will not, however, trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler.

This method is identical to the UpdateRecordSetField command.

Parameters:

recordset - name of recordset on current entity

field - name of the field to update

Throws:

ApptrieveException

updateRecordSetFields

void updateRecordSetFields(java.lang.String recordset,
                           java.util.Collection fields)
                           throws ApptrieveException

Writes the cached field data for the specified fields in the recordset. If data is cached for one or more of the fields, this method will trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler.

Parameters:

recordset - name of recordset on current entity

fields - collection of attribute names to update

Throws:

ApptrieveException

updateRecordSetFields

void updateRecordSetFields(java.lang.String recordset)
                           throws ApptrieveException

Writes the cached field data for all fields in the recordset. If data is cached for one or more of the fields, this method will trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler.

This method is identical to the UpdateRecordSetFields command.

Parameters:

recordset - name of recordset on current entity

Throws:

ApptrieveException

wait

void wait(int duration)
          throws ApptrieveException

Waits for the specified number of seconds.

This method is identical to the Wait command.

Parameters:

duration - the amount of time to wait in seconds

Throws:

ApptrieveException

waitMS

void waitMS(int duration)
            throws ApptrieveException

Waits for the specified number of milliseconds.

This method is identical to the WaitMS command.

Parameters:

duration - the amount of time to wait in milliseconds

Throws:

ApptrieveException

waitForCommString

void waitForCommString(java.lang.String string,
                       int timeout)
                       throws ApptrieveException

Waits until the given string is received from the host.

This method is identical to the WaitForCommString command.

Parameters:

string - the string to wait for

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCommString

void waitForCommString(java.lang.String string,
                       int timeout,
                       int count)
                       throws ApptrieveException

Waits until the given string is received from the host a specific number of times.

This method is identical to the WaitForCommString command.

Parameters:

string - the string to wait for

timeout - the maximum time to wait in seconds

count - the number of times the string must be found

Throws:

ApptrieveException

waitForDisplayString

void waitForDisplayString(java.lang.String string,
                          int row,
                          int column,
                          boolean relative,
                          int timeout)
                          throws ApptrieveException

Waits for the presence of a string starting at a particular terminal screen row and column.

This method is identical to the WaitForDisplayString command.

Parameters:

string - the string to wait for

row - the one-based screen row (ANY_ROW matches any row)

column - the one-based screen column (ANY_COLUMN matches any column)

relative - looks for the string relative to the cursor if true

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCursorAtLocation

void waitForCursorAtLocation(int row,
                             int column,
                             int timeout)
                             throws ApptrieveException

Waits until the cursor is at the specified location. If the cursor is already at the specified location this method returns immediately

This method is identical to the WaitForCursorAtLocation command.

Parameters:

row - the one-based screen row (ANY_ROW matches any row)

column - the one-based screen column (ANY_COLUMN matches any column)

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCursorNotAtLocation

void waitForCursorNotAtLocation(int row,
                                int column,
                                int timeout)
                                throws ApptrieveException

Waits until the cursor is not at the specified location. If the cursor is already not at the specified location this method returns immediately.

This method is identical to the WaitForCursorNotAtLocation command.

Parameters:

row - the one-based screen row (ANY_ROW matches any row)

column - the one-based screen column (ANY_COLUMN matches any column)

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCursorAtTerminalField

void waitForCursorAtTerminalField(int row,
                                  int column,
                                  int timeout)
                                  throws ApptrieveException

Waits until the cursor is within the terminal field at the specified location. This method only applies to block mode host applications.

This method is identical to the WaitForCursorAtTerminalField command.

Parameters:

row - the one-based screen row (ANY_ROW matches any row)

column - the one-based screen column (ANY_COLUMN matches any column)

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCursorNotAtTerminalField

void waitForCursorNotAtTerminalField(int row,
                                     int column,
                                     int timeout)
                                     throws ApptrieveException

Waits until the cursor is not within the terminal field at the specified location. This method only applies to block mode host applications.

This method is identical to the WaitForCursorNotAtTerminalField command.

Parameters:

row - the one-based screen row (ANY_ROW matches any row)

column - the one-based screen column (ANY_COLUMN matches any column)

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForKeyboardEnabled

void waitForKeyboardEnabled(int duration,
                            int timeout)
                            throws ApptrieveException

Waits for the keyboard to be enabled for the specified duration of time.

This method is identical to the WaitForKeyboardEnabled command.

Parameters:

duration - the duration in seconds that the keyboard must remain enabled before returning.

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForNewHostScreen

void waitForNewHostScreen(int timeout)
                          throws ApptrieveException

Processes any pending data from the host. If no data is currently pending, or the amount of data is not sufficient enough to have changed the contents of the screen, wait until the specified timeout for such data. For block mode hosts, any data received from the host is sufficient to consider the screen changed. For character mode hosts anything other than change the cursor position is considered sufficient.

This method is identical to the WaitForNewHostScreen command.

Parameters:

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

See Also:

waitForHostData(int)

waitForHostSilence

void waitForHostSilence(int duration,
                        int timeout)
                        throws ApptrieveException

Waits until data communication with the host is silent for the specified duration.

This method is identical to the WaitForHostSilence command.

Parameters:

duration - the duration in seconds that the communication must be silent before returning

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForMultipleEvents

void waitForMultipleEvents(java.lang.String expression,
                           int timeout)
                           throws ApptrieveException

Waits until the specified sequence of event expressions are satisfied. This method utilizes the host events defined in the model to create an expected sequence of host events for which to wait.

The expression is composed of a sequence of event statements separated by semi-colons. The syntax for the expression is as follows:

 expression:
     <event_sequence>

 event_sequence:
     <event_statement>
     <event_sequence> ; <event_statement>

 event_statement:
     <event_statement> OR <event_statement>
     <event_statement> AND <event_statement>
     NOT <event_statement>
     ( <event_statement> )
     <event>
 

VHI will wait for each event statement to be satisfied before moving on to the next event statement. This method returns once all event statements have been satisfied in the order specified. If all the event statements are not satisfied within the specified timeout, an ApptrieveException will be thrown.

This method is identical to the WaitForMultipleEvents command.

Parameters:

expression - the expression of events to wait for

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForUpdate

void waitForUpdate(int topRow,
                   int leftColumn,
                   int bottomRow,
                   int rightColumn,
                   int regionType,
                   boolean relative,
                   int timeout)
                   throws ApptrieveException

Waits for the host to update a specified region on the terminal screen.

This method is identical to the WaitForUpdate command.

Parameters:

topRow - the top row of the region to watch

leftColumn - the left column of the region to watch

bottomRow - the bottom row of the region to watch

rightColumn - the right column of the region to watch

regionType - the type of region to use: LINEAR_REGION or RECTANGULAR_REGION.

relative - true if the region is relative to the cursor position

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCondition

void waitForCondition(java.lang.String entity,
                      java.lang.String condition,
                      int timeout)
                      throws ApptrieveException

Waits for an expression to become true for the specified entity.

This method is identical to the WaitForCondition command.

Parameters:

entity - the name of the entity to use as the context for the expression.

condition - the expression to wait for

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCursorAtAttribute

void waitForCursorAtAttribute(java.lang.String entity,
                              java.lang.String attribute,
                              int timeout)
                              throws ApptrieveException

Waits until the cursor is positioned within an attribute.

This method is identical to the WaitForCursorAtAttribute command.

Parameters:

entity - the name of the entity on which the attribute is defined

attribute - the name of the attribute

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForCursorAtRecordSetField

void waitForCursorAtRecordSetField(java.lang.String entity,
                                   java.lang.String recordset,
                                   java.lang.String field,
                                   int timeout)
                                   throws ApptrieveException

Waits until the cursor is positioned within a recordset field.

This method is identical to the WaitForCursorAtRecordSetField command.

Parameters:

entity - the name of the entity on which the recordset is defined

recordset - the name of the recordset on which the field is defined

field - the name of the field that can terminate the wait

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

writeToMappedAttribute

void writeToMappedAttribute(java.lang.String attribute)
                            throws ApptrieveException

Writes to an attribute from its mapped variable. This method will trigger the AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) event handler.

This method is identical to the WriteToMappedAttr command.

Parameters:

attribute - name of mapped attribute to be written

Throws:

ApptrieveException

writeVariableToAttribute

void writeVariableToAttribute(java.lang.String attribute,
                              java.lang.String variable)
                              throws ApptrieveException

Writes the contents of a variable to an attribute. This method will trigger the AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) event handler.

This method is identical to the WriteVarToAttr command.

Parameters:

attribute - name of attribute to be written to

variable - name of variable containing value to be written

Throws:

ApptrieveException

writeVariableToField

void writeVariableToField(java.lang.String recordset,
                          java.lang.String field,
                          java.lang.String variable)
                          throws ApptrieveException

Writes the contents of a variable to a field in the current record of a recordset defined on the current entity. This method will trigger the FieldEventHandler.writeField(com.wrq.vhi.script.api.WriteFieldEvent) event handler assuming the model is not configured to cache field writes. This method will not, however, trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler.

This method is identical to the WriteVarToField command.

Parameters:

recordset - name of recordset on current entity containing the field to be written to

field - name of field to be written to

variable - name of variable containing value to be written

Throws:

ApptrieveException

writeVariableToTerminal

void writeVariableToTerminal(java.lang.String variable,
                             int maxLength,
                             boolean erase,
                             int echoType)
                             throws ApptrieveException

Writes the contents of a variable to the terminal at the current cursor position.

This method is identical to the WriteVarToTerminal command.

Parameters:

variable - name of variable to be read.

maxLength - the maximum number of characters to write

erase - if true and if the length of the string contained in variable is less than maxLength, pad the value written with spaces until maxLength characters have been written.

echoType - type of wait for echo to perform. See transmit(java.lang.String) for values.

Throws:

ApptrieveException

writeVariableToLocation

void writeVariableToLocation(java.lang.String variable,
                             int row,
                             int column,
                             int maxLength,
                             boolean erase,
                             int echoType)
                             throws ApptrieveException

Writes the contents of a variable to the terminal at a specified location.

This method is identical to the WriteVarToLocation command.

Parameters:

variable - name variable containing value to be written

row - the row of the location to be written to

column - the starting column of the location to be written to

maxLength - the maximum number of characters to write

erase - if true and if the length of the string contained in variable is less than maxLength, pad the value written with spaces until maxLength characters have been written.

echoType - type of wait for echo to perform. See transmit(java.lang.String) for values.

Throws:

ApptrieveException

executeCommandList

void executeCommandList(CommandList list)
                        throws ApptrieveException

Executes the specified command list. This is more efficient for executing multiple commands. Using command lists also allows for the execution of back-to-back data stream based wait commands such as WaitForCommString.

A command list can be constructed as follows: CommandList list = new CommandList(); list.add(new WaitForDisplayString("prompt> ", 5, 0, -8, true)); list.add(new Transmit("run"));

Parameters:

list - the command list to execute.

Throws:

ApptrieveException

getStringAtCursor

java.lang.String getStringAtCursor(int length)
                                   throws ApptrieveException

Gets a string from a linear region of the terminal screen starting at the current cursor position.

Parameters:

length - the length of the string

Returns:

the display string

Throws:

ApptrieveException

getStringAtOffset

java.lang.String getStringAtOffset(int offset,
                                   int length)
                                   throws ApptrieveException

Gets a string from a linear region of the terminal screen starting at the given offset.

Parameters:

offset - the offset from the start of the screen

length - the length of the string

Returns:

the display string

Throws:

ApptrieveException

getStringAtLocation

java.lang.String getStringAtLocation(int topRow,
                                     int leftColumn,
                                     int numRows,
                                     int numColumns)
                                     throws ApptrieveException

Gets a string from a rectangular region of the terminal screen starting at the given row and column.

Parameters:

topRow - the starting row on the screen

leftColumn - the starting column on the screen

numRows - the number of rows to get relative to the starting row

numColumns - the number of columns to get relative to the starting column

Returns:

the display string

Throws:

ApptrieveException

getCursorPosition

CursorPosition getCursorPosition()
                                 throws ApptrieveException

Gets the current position of the cursor on the terminal screen.

Returns:

the cursor position

Throws:

ApptrieveException

getLinearTerminalRegion

LinearTerminalRegion getLinearTerminalRegion(int offset,
                                             int length)
                                             throws ApptrieveException

Gets the contents of a linear region of the terminal screen. This method gets both the character and terminal attribute content of the region.

Parameters:

offset - the zero-based offset

length - the length

Returns:

the contents of the specified region

Throws:

ApptrieveException

getRectangularTerminalRegion

RectangularTerminalRegion getRectangularTerminalRegion(int topRow,
                                                       int leftColumn,
                                                       int numRows,
                                                       int numColumns)
                                                       throws ApptrieveException

Gets the contents of a rectangular region of the terminal screen. This method gets both the character and terminal attribute content of the region.

Parameters:

topRow - the one-based screen row

leftColumn - the one-based screen column

numRows - the number of rows to get relative to topRow

numColumns - the number of columns to get relative to leftColumn

Returns:

the contents of the specified region

Throws:

ApptrieveException

getTerminalScreenSize

ScreenSize getTerminalScreenSize()
                                 throws ApptrieveException

Gets the size of the terminal screen without the contents.

Returns:

the height and width of the terminal screen in characters

Throws:

ApptrieveException

getTerminalScreen

RectangularTerminalRegion getTerminalScreen()
                                            throws ApptrieveException

Gets the size and contents of the terminal screen. This method gets both the character and terminal attribute content of the screen.

Returns:

the contents of the entire terminal screen

Throws:

ApptrieveException

waitForHostData

void waitForHostData(int timeout)
                     throws ApptrieveException

Processes any pending data received from the host. If no data is currently pending, wait until the specified timeout for any data to arrive.

Parameters:

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException - if a Host Integrator server error occurs

See Also:

waitForNewHostScreen(int)

waitForEntity

void waitForEntity(java.lang.String entity,
                   int timeout)
                   throws ApptrieveException

Waits until specified entity is recognized.

Parameters:

entity - the name of the entity to wait for

timeout - the maximum time to wait in seconds

Throws:

ApptrieveException

waitForEntities

java.lang.String waitForEntities(java.util.List entities,
                                 int timeout)
                                 throws ApptrieveException

Waits until one of the specified entities is recognized.

Parameters:

entities - array of entity names for which to wait

timeout - the maximum time to wait in seconds

Returns:

the name of the entity recognized

Throws:

ApptrieveException - if a Host Integrator server error occurs

getHomeEntity

java.lang.String getHomeEntity()
                               throws ApptrieveException

Gets the name of the home entity for the model.

Returns:

the name of the home entity

Throws:

ApptrieveException

getModelEntities

java.util.List getModelEntities()
                                throws ApptrieveException

Gets the names of all entities in the model.

Returns:

a list of entity names

Throws:

ApptrieveException

getEntityDescription

java.lang.String getEntityDescription(java.lang.String entity)
                                      throws ApptrieveException

Gets the description for an entity.

Parameters:

entity - the name of the entity

Returns:

the description for the entity

Throws:

ApptrieveException

getCurrentEntity

java.lang.String getCurrentEntity()
                                  throws ApptrieveException

Gets the current entity (screen) of the legacy application.

Returns:

the name of the current entity or an empty string if none

Throws:

ApptrieveException

setCurrentEntity

void setCurrentEntity(java.lang.String entity)
                      throws ApptrieveException

Sets the current entity. VHI will determine the sequence of operations needed to arrive at the specified entity and execute them.

Parameters:

entity - name of the entity

Throws:

ApptrieveException

getPatternRegion

TerminalRegion getPatternRegion(java.lang.String pattern)
                                throws ApptrieveException

Gets the location and contents of the specified pattern. If the specified pattern does not match the contents of the current screen, this method will return null. Entity signature patterns will always match and thus will always return a non-null value.

Parameters:

pattern - a pattern on the current entity

Returns:

the location and contents of the pattern or null if the pattern does not match the current screen.

Throws:

ApptrieveException

getPatternRegions

java.util.Map getPatternRegions(java.util.List patterns)
                                throws ApptrieveException

Gets the location and contents of the specified patterns. If a pattern does not match the contents of the current screen, its value in the returned map will be null. Entity signature patterns will always match and thus will always have a non-null value.

Parameters:

patterns - a list of patterns on the current entity

Returns:

a map of pattern names to TerminalRegion objects containing the location and contents of the pattern. If a pattern cannot be located on the current screen, the value in the map will be null.

Throws:

ApptrieveException

getEntityAttributes

java.util.List getEntityAttributes(java.lang.String entity)
                                   throws ApptrieveException

Gets the names of all attributes on the specified entity.

Parameters:

entity - name of the entity

Returns:

a list of attribute names

Throws:

ApptrieveException

getAttributeMetaData

AttributeMetaData getAttributeMetaData(java.lang.String entity,
                                       java.lang.String attribute)
                                       throws ApptrieveException

Gets the metadata for the specified attribute.

Parameters:

entity - name of the entity

attribute - name of the attribute on the entity

Returns:

the metadata for the attribute

Throws:

ApptrieveException

getAttributeAtCursor

java.lang.String getAttributeAtCursor()
                                      throws ApptrieveException

Gets the name of the attribute at the current cursor position. Returns null if the cursor is not currently within one of the attributes on the current entity.

Returns:

the attribute name

Throws:

ApptrieveException

getAttributeRegion

TerminalRegion getAttributeRegion(java.lang.String attribute)
                                  throws ApptrieveException

Gets the location and contents of the specified attribute.

Parameters:

attribute - an attribute on the current entity

Returns:

the location and contents of the attribute or null if the attribute is relative to a pattern that cannot be located on the current screen.

Throws:

ApptrieveException

getAttributeRegions

java.util.Map getAttributeRegions(java.util.List attributes)
                                  throws ApptrieveException

Gets the location and contents of the specified attributes.

Parameters:

attributes - a list of attributes on the current entity

Returns:

a map of attribute names to TerminalRegion objects containing the location and contents of the attribute. If an attribute is relative to a pattern that cannot be located on the current screen, the value in the map will be null.

Throws:

ApptrieveException

getAttribute

java.lang.String getAttribute(java.lang.String attribute)
                              throws ApptrieveException

Reads the specified attribute on the current entity and returns the value. This method will trigger the AttributeEventHandler.readAttribute(com.wrq.vhi.script.api.ReadAttributeEvent) event handler if defined.

Parameters:

attribute - an attribute on the current entity

Returns:

the attribute value

Throws:

ApptrieveException

getAttributes

java.util.Map getAttributes()
                            throws ApptrieveException

Reads all the attributes on the current entity and returns their values. This method will trigger the AttributeEventHandler.readAttribute(com.wrq.vhi.script.api.ReadAttributeEvent) event handler for each attribute if defined.

Returns:

a map of attribute names to attribute values

Throws:

ApptrieveException

getAttributes

java.util.Map getAttributes(java.util.List attributes)
                            throws ApptrieveException

Reads the specified attributes on the current entity and returns their values. This method will trigger the AttributeEventHandler.readAttribute(com.wrq.vhi.script.api.ReadAttributeEvent) event handler for each attribute if defined.

Parameters:

attributes - a list of attributes on the current entity

Returns:

a map of attribute names to attribute values

Throws:

ApptrieveException

setAttribute

void setAttribute(java.lang.String attribute,
                  java.lang.String value)
                  throws ApptrieveException

Writes a value to the specified attribute on the current entity. This method will trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) and AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handlers if defined.

Parameters:

attribute - an attribute on the current entity

value - the value to write

Throws:

ApptrieveException

setAttributes

void setAttributes(java.util.Map attributes)
                   throws ApptrieveException

Writes values to the specified attributes on the current entity. This method will trigger the EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) and AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handlers if defined.

Parameters:

attributes - a map of attribute names to values

Throws:

ApptrieveException

setAttributeDelayed

void setAttributeDelayed(java.lang.String entity,
                         java.lang.String attribute,
                         java.lang.String value)
                         throws ApptrieveException

Queues a value to be written to the specified attribute on the specified entity. The next time VHI recognizes the specified entity, VHI will write the value to the attribute. The EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) and AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handlers will be triggered if defined.

Parameters:

entity - the entity name

attribute - an attribute on the specified entity

value - the value to write

Throws:

ApptrieveException

setAttributesDelayed

void setAttributesDelayed(java.lang.String entity,
                          java.util.Map attributes)
                          throws ApptrieveException

Queues values to be written to the specified attributes on the specified entity. The next time VHI recognizes the specified entity, VHI will write the values to the attributes. The EntityEventHandler.writeAttributes(com.wrq.vhi.script.api.WriteAttributesEvent) and AttributeEventHandler.writeAttribute(com.wrq.vhi.script.api.WriteAttributeEvent) event handlers will be triggered if defined.

Parameters:

entity - the entity name

attributes - a map of attribute names to values

Throws:

ApptrieveException

getEntityOperations

java.util.List getEntityOperations(java.lang.String entity)
                                   throws ApptrieveException

Gets the names of all operations on the specified entity.

Parameters:

entity - name of the entity

Returns:

a list of operation names

Throws:

ApptrieveException

getOperationMetaData

OperationMetaData getOperationMetaData(java.lang.String entity,
                                       java.lang.String operation)
                                       throws ApptrieveException

Gets the metadata for the specified operation.

Parameters:

entity - name of the entity

operation - name of the operation on the entity

Returns:

the metadata for the operation

Throws:

ApptrieveException

executeOperation

void executeOperation(java.lang.String operation)
                      throws ApptrieveException

Performs an operation on the current entity. This method will trigger the OperationEventHandler.executeOperation(com.wrq.vhi.script.api.ExecuteOperationEvent) event handler if defined.

Parameters:

operation - the operation name

Throws:

ApptrieveException

getEntityRecordSets

java.util.List getEntityRecordSets(java.lang.String entity)
                                   throws ApptrieveException

Gets the names of all recordsets on the specified entity.

Parameters:

entity - name of the entity

Returns:

a list of recordset names

Throws:

ApptrieveException

getRecordSetMetaData

RecordSetMetaData getRecordSetMetaData(java.lang.String entity,
                                       java.lang.String recordset)
                                       throws ApptrieveException

Gets the metadata for the specified recordset.

Parameters:

entity - name of the entity

recordset - name of the recordset on the entity

Returns:

the metadata for the recordset

Throws:

ApptrieveException

getFieldMetaData

FieldMetaData getFieldMetaData(java.lang.String entity,
                               java.lang.String recordset,
                               java.lang.String field)
                               throws ApptrieveException

Gets the metadata for the specified recordset field.

Parameters:

entity - name of the entity

recordset - name of the recordset on the entity

field - name of the field on the recordset

Returns:

the metadata for the recordset field

Throws:

ApptrieveException

getCurrentRecordSet

java.lang.String getCurrentRecordSet()
                                     throws ApptrieveException

Gets the name of the current recordset.

Returns:

the name of the current recordset or an empty string if none

Throws:

ApptrieveException

setCurrentRecordSet

void setCurrentRecordSet(java.lang.String recordset)
                         throws ApptrieveException

Sets the current recordset by name.

Parameters:

recordset - the name of the recordset to make current

Throws:

ApptrieveException

fetchRecords

ModelRecordSet fetchRecords(int maxRows,
                            java.util.List fields,
                            java.lang.String filterExpression)
                            throws ApptrieveException

Fetches up to the maximum number of rows specified from the current recordset starting with the next record. If the maximum number of rows to fetch is zero, all remaining records will be fetched. The last record fetched will be the current record unless the end of the recordset was reached.

Filter Expression Syntax:

 expression:
     <expression> OR <expression>
     <expression> AND <expression>
     NOT <expression>
     ( <expression> )
     <value_expression> = <value_expression>
     <value_expression> =* <value_expression>
     <value_expression> != <value_expression>
     <value_expression> < <value_expression>
     <value_expression> > <value_expression>
     <value_expression> <= <value_expression>
     <value_expression> >= <value_expression>

 value_expression:
     <value_expression> + <value_expression>
     <value_expression> - <value_expression>
     <value_expression> * <value_expression>
     <value_expression> / <value_expression>
     <variable_reference>
     <attribute_reference>
     <field_reference>
     <constant>

 variable_reference:
     Variables.<variable_name>

 field_reference:
     <recordset_name>.<field_name>

 attribute_reference:
     <attribute_name>

 constant:
     " <string> "
     <number>
 

Filter Expression Examples:

 patients.LastName <> "smith"
 All recordset fields in the patients recordset that are not "smith."

 NOT (patients.LastName = "smith")
 All recordset fields in the patients recordset that are not "smith."

 (SearchResults.LastName = "smith") and (SearchResults.FirstName = "Steven")
 All records in the SearchResults recordset with the last name "smith" and first name "Steven."

 AccountNumbers.Accounts >= 10000 and AccountNumbers.Accounts <= 20000
 All fields in the AccountNumbers recordset greater than or equal to 10000 and less than or equal to 20000.

 (AccountNumbers.AcctNum >= variables.MinAccount) and (AccountNumbers.AcctNum <= variables.MaxAccount)
 AcctNum field in the AccountNumbers recordset greater than or equal to variable
 MinAccount and less than or equal to variable MaxAccount
 

Parameters:

maxRows - the maximum number of rows to fetch

fields - list of the field names to fetch or null for all

filterExpression - an expression that qualifies the records to fetch

Returns:

the resulting records fetched. If no records are fetched the ModelRecordSet object returned will have no records.

Throws:

ApptrieveException

getCurrentRecordIndex

int getCurrentRecordIndex()
                          throws ApptrieveException

Gets the index of the current record in the current recordset.

Returns:

the index of the current record

Throws:

ApptrieveException

setCurrentRecordIndex

boolean setCurrentRecordIndex(int index)
                              throws ApptrieveException

Sets the current record in the current recordset by index.

Parameters:

index - the index of the record to make current or SYNC_TO_HOST to make the current host record current

Returns:

true if the current record was changed to the corresponding to index

Throws:

ApptrieveException

nextRecord

ModelRecord nextRecord(java.lang.String filterExpression)
                       throws ApptrieveException

Finds and return a record in the current recordset using a filter expression starting with the record following the current record. If the current record is before the first record in the recordset, searching starts with the first record.

See fetchRecords(int, java.util.List, java.lang.String) for filter expression syntax.

Parameters:

filterExpression - an expression that qualifies the record to find

Returns:

the first record that matches the filter expression. If no record matches the filter expression, the method returns null.

Throws:

ApptrieveException

moveCurrentRecordIndex

void moveCurrentRecordIndex(int movement)
                            throws ApptrieveException

Moves the current record index to a new position in the current recordset. The movement can be one of the following:

• SCROLL_HOME
• SCROLL_END
• SCROLL_LINE_UP
• SCROLL_LINE_DOWN
• SCROLL_PAGE_UP
• SCROLL_PAGE_DOWN

Parameters:

movement - the type of movement to perform

Throws:

ApptrieveException

getCurrentRecord

ModelRecord getCurrentRecord()
                             throws ApptrieveException

Fetches the current record in the current recordset.

Returns:

the current record or null if there is no current record

Throws:

ApptrieveException

selectCurrentRecord

void selectCurrentRecord()
                         throws ApptrieveException

Performs the model-defined selection operation for the current recordset.

Throws:

ApptrieveException

selectRecordByFilter

boolean selectRecordByFilter(java.lang.String filterExpression)
                             throws ApptrieveException

Finds a record in the current recordset using a filter expression and performs the model-defined selection operation. The search starts with the record following the current record. If the current record is before the first record in the recordset, searching starts with the first record.

See fetchRecords(int, java.util.List, java.lang.String) for filter expression syntax.

Parameters:

filterExpression - an expression that qualifies the record to select

Returns:

true if a matching record is found and the selection succeeds

Throws:

ApptrieveException

selectRecordByIndex

boolean selectRecordByIndex(int index)
                            throws ApptrieveException

Sets the current record in the current recordset by index and then performs the model-defined selection operation.

Parameters:

index - the index of the record to select

Returns:

true if the record is found and the selection succeeds

Throws:

ApptrieveException

insertRecord

void insertRecord(java.util.Map record)
                  throws ApptrieveException

Inserts a record into the current recordset. This method will trigger the RecordSetEventHandler.insertRecord(com.wrq.vhi.script.api.InsertRecordEvent) event handler if defined, otherwise the model-defined insertion method will be used.

Parameters:

record - a map of field names to values

Throws:

ApptrieveException

insertRecords

void insertRecords(java.util.List records)
                   throws ApptrieveException

Inserts multiple records into the current recordset. This method will trigger the RecordSetEventHandler.insertRecord(com.wrq.vhi.script.api.InsertRecordEvent) event handler for each record if defined, otherwise the model-defined insertion method will be used.

Parameters:

records - a list of java.util.Map objects, one for each record to insert into the entity. Each map should contain a set of field name and value pairs.

Throws:

ApptrieveException

updateCurrentRecord

void updateCurrentRecord(java.util.Map record)
                         throws ApptrieveException

Updates the field values of the current record in the current recordset. This method will trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler for each record if defined, otherwise the model-defined update method will be used.

Parameters:

record - a map of field names to values

Throws:

ApptrieveException

updateRecordByFilter

boolean updateRecordByFilter(java.util.Map record,
                             java.lang.String filterExpression)
                             throws ApptrieveException

Finds a record in the current recordset using a filter expression and updates its field values. The search starts with the record following the current record. If the current record is before the first record in the recordset, searching starts with the first record.

This method will trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler for the record found, otherwise the model-defined update method will be used.

See fetchRecords(int, java.util.List, java.lang.String) for filter expression syntax.

Parameters:

record - a map of field names to values

filterExpression - an expression that qualifies the record to update

Returns:

true if a matching record is found and the update succeeds

Throws:

ApptrieveException

updateRecordByIndex

boolean updateRecordByIndex(java.util.Map record,
                            int index)
                            throws ApptrieveException

Updates the field values of the record at the specified index. This method will trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler if defined, otherwise the model-defined update method will be used.

Parameters:

record - a map of field names to values

index - the index of the record to update

Returns:

true if the record is found and the update succeeds

Throws:

ApptrieveException

updateRecords

int updateRecords(java.util.Map record,
                  java.lang.String filterExpression)
                  throws ApptrieveException

Finds records in the current recordset using a filter expression and update their field values. The search starts with the record following the current record and proceeds until the end of the recordset. If the current record is before the first record in the recordset, searching starts with the first record. Any record found that matches the filter expression is updated with the specified values.

This method will trigger the RecordSetEventHandler.updateRecord(com.wrq.vhi.script.api.UpdateRecordEvent) event handler for the record found, otherwise the model-defined update method will be used.

See fetchRecords(int, java.util.List, java.lang.String) for filter expression syntax.

Parameters:

record - a map of field names to values

filterExpression - an expression that qualifies which records to update

Returns:

the number of records updated

Throws:

ApptrieveException

getRecordSetRegion

TerminalRegion getRecordSetRegion(java.lang.String recordset)
                                  throws ApptrieveException

Gets the location and contents of the specified recordset.

Parameters:

recordset - a recordset on the current entity

Returns:

the location and contents of the recordset or null if the recordset is relative to a pattern that cannot be located on the current screen.

Throws:

ApptrieveException

getRecordRegion

TerminalRegion getRecordRegion(java.lang.String recordset)
                               throws ApptrieveException

Gets the location and contents of the current record in the specified recordset.

Parameters:

recordset - recordset on the current entity

Returns:

the location and contents of the current record

Throws:

ApptrieveException

getFieldRegion

TerminalRegion getFieldRegion(java.lang.String field)
                              throws ApptrieveException

Gets the location and contents of the specified field in the current record of the current recordset.

Parameters:

field - field in the current recordset

Returns:

the location and contents of the field in the current record

Throws:

ApptrieveException

getFieldRegions

java.util.Map getFieldRegions(java.util.List fields)
                              throws ApptrieveException

Gets the location and contents of the specified fields in the current record of the current recordset.

Parameters:

fields - a list of fields in the current recordset

Returns:

a map of field names to TerminalRegion objects containing the location and contents of each field

Throws:

ApptrieveException

getModelVariableNames

java.util.List getModelVariableNames()
                                     throws ApptrieveException

Gets the names of all variables in the model.

Returns:

a list of variable names

Throws:

ApptrieveException

getVariableMetaData

VariableMetaData getVariableMetaData(java.lang.String variable)
                                     throws ApptrieveException

Gets the metadata for the specified variable.

Parameters:

variable - name of the variable

Returns:

the metadata for the variable

Throws:

ApptrieveException

getModelVariable

java.lang.String getModelVariable(java.lang.String variable)
                                  throws ApptrieveException

Gets the value of a model variable. If multiple values are needed it is more efficient to call getModelVariables().

Parameters:

variable - the model variable name

Returns:

the model variable value

Throws:

ApptrieveException

getModelVariables

java.util.Map getModelVariables()
                                throws ApptrieveException

Gets the values of all model variables.

Returns:

a map of variable names to values

Throws:

ApptrieveException

setModelVariable

void setModelVariable(java.lang.String variable,
                      java.lang.String value)
                      throws ApptrieveException

Sets the value of a variable.

Parameters:

variable - the model variable name

value - the model variable value

Throws:

ApptrieveException

setModelVariables

void setModelVariables(java.util.Map variables)
                       throws ApptrieveException

Sets the values of one or more variables.

Parameters:

variables - a map of variable names to values

Throws:

ApptrieveException

getTableNames

java.util.List getTableNames()
                             throws ApptrieveException

Gets the names of all tables in the model.

Returns:

a list of table names

Throws:

ApptrieveException

getTableDescription

java.lang.String getTableDescription(java.lang.String table)
                                     throws ApptrieveException

Gets the description for a table.

Parameters:

table - name of the table

Returns:

the description for the table

Throws:

ApptrieveException

getTableProcedures

java.util.List getTableProcedures(java.lang.String table)
                                  throws ApptrieveException

Gets the names of all procedures in the specified table.

Parameters:

table - name of the table

Returns:

a list of procedure names

Throws:

ApptrieveException

getProcedureMetaData

ProcedureMetaData getProcedureMetaData(java.lang.String table,
                                       java.lang.String procedure)
                                       throws ApptrieveException

Gets the metadata for the specified procedure in a table.

Parameters:

table - name of the table

procedure - name of the procedure in the table

Returns:

the metadata for the procedure

Throws:

ApptrieveException

getTableColumns

java.util.List getTableColumns(java.lang.String table)
                               throws ApptrieveException

Gets the names of all columns in the specified table.

Parameters:

table - name of the table

Returns:

a list of column names

Throws:

ApptrieveException

getColumnMetaData

ColumnMetaData getColumnMetaData(java.lang.String table,
                                 java.lang.String column)
                                 throws ApptrieveException

Gets the metadata for the specified column in a table.

Parameters:

table - name of the table

column - name of the column in the table

Returns:

the metadata for the column

Throws:

ApptrieveException

executeTableProcedure

ProcedureRecordSet executeTableProcedure(java.lang.String tableName,
                                         java.lang.String procedureName,
                                         java.util.Map dataInputValues,
                                         java.util.Map filterValues,
                                         boolean filterIsCaseSensitive,
                                         java.util.List outputColumnNames,
                                         int maxRows)
                                         throws ApptrieveException

Performs a procedure on a table defined in the model. This method will trigger the ProcedureEventHandler.executeProcedure(com.wrq.vhi.script.api.ExecuteProcedureEvent) event handler for the procedure if defined.

Parameters:

tableName - name of the table

procedureName - name of the procedure to perform

dataInputValues - set of data input column name-value pairs to use (not required for SELECT and DELETE procedures)

filterValues - set of filter column name-value pairs to use (not required for INSERT procedures)

filterIsCaseSensitive - true means that filter comparisons are case sensitive

outputColumnNames - list of the table's column names to return as output (not required for UPDATE, INSERT or DELETE procedures)

maxRows - the maximum number of rows to return

Returns:

the records retrieved for SELECT procedures, otherwise null

Throws:

ApptrieveException

executeSQLStatement

ProcedureRecordSet executeSQLStatement(java.lang.String sqlStatement)
                                       throws ApptrieveException

Executes an SQL statement on a table defined in the model. The SQL statement will be resolved into a set of one or more procedures.

Parameters:

sqlStatement - the SQL statement to execute

Returns:

the results of the query

Throws:

ApptrieveException